Hello, developers. Here are a few short notes on how to properly install bash-completions so that they will work fine with autoloading support that will be enabled in bash-completion-2.1-r100.
I will also place the following instructions on the wiki once I figure out where. Suggestions are welcome :). 1. Completion files are to be installed to the directory specified by $(get_bashcompdir) from bash-completion-r1 (dobashcomp and newbashcomp respect that). 1a. Allowed exception: if the build system has hardcoded /usr/share/bash-completion/completions path, it is acceptable to leave it as-is and not use the eclass. 1b. Allowed exception: if the build system uses pkg-config to determine completionsdir and doesn't allow override, it is acceptable to leave it as-is. However, you need to DEPEND on app-shells/ebash-completion then -- so it's better to actually make the path configurable. 2. Completion files must be named after *all* commands they're completing. For example, completion for pulseaudio has to be named 'pulseaudio' and not 'pulseaudio-bash-completion.sh'. 2a. If a completion file provides completions for multiple commands, it should be installed for one of the commands, and symlinked for the others. For example, 'pacat', 'paplay', 'parecord' etc. should be all symlinked to 'pulseaudio'. Extra aliases can be created using 'bashcomp_alias' function from the eclass (note: patch currently in review). 3. The 'have' function that has been often used in completion files has been deprecated and will not work with autoloaded completions. 3a. When 'have' was used to conditionally load completions, it should be removed and completions can be loaded unconditionally. This is because the completion file won't be sourced before the command is typed anyway, and who types commands for non-installed programs? :) 3b. When 'have' was used *inside* the completion function for some reason, it may be replaced with '_have'. However, it should be noted that the latter does not set 'have' variable like 'have' did. Also, a reminder of the few generic rules: 4. USE=bash-completion should be used scarcely. Completions follow the rules for small text files with no side effects on the main program, and therefore should be installed unconditionally. 4a. The use of the USE flag is justified when it pulls in additional dependencies (but see app-shells/bash-completion dependency below). 4b. USE flag can also be used to control installing compatdir (/etc/bash_completion.d) files. However, use of that directory is strongly discouraged. 5. Run-time dependencies on app-shells/bash-completion are really unnecessary. If you don't have bash-completion, completions won't be loaded and there will be no issue. 5a. To enforce a particular version of bash-completion, it is better to use reversed blocker atom. For example, >=app-shells/bash-completion-1.9 should be replaced with !!<app-shells/bash-completion-1.9. This way, it is possible to enforce meeting the version requirements when bash-completion is installed, and not force installing it when it is not. 5b. If the build system uses pkg-config to find bash-completion and refuses to install the completions if it is not installed, it is acceptable to add a build-time dependency on app-shells/bash-completion. However, it is recommended to fix the build system instead. Thanks for the help. Any questions shall arise, please do not hesitate to reply to this mail or contact me directly. -- Best regards, Michał Górny
signature.asc
Description: PGP signature
