1 |
Hello, developers. |
2 |
|
3 |
Here are a few short notes on how to properly install bash-completions |
4 |
so that they will work fine with autoloading support that will be |
5 |
enabled in bash-completion-2.1-r100. |
6 |
|
7 |
I will also place the following instructions on the wiki once I figure |
8 |
out where. Suggestions are welcome :). |
9 |
|
10 |
|
11 |
1. Completion files are to be installed to the directory specified by |
12 |
$(get_bashcompdir) from bash-completion-r1 (dobashcomp and newbashcomp |
13 |
respect that). |
14 |
|
15 |
1a. Allowed exception: if the build system has hardcoded |
16 |
/usr/share/bash-completion/completions path, it is acceptable to leave |
17 |
it as-is and not use the eclass. |
18 |
|
19 |
1b. Allowed exception: if the build system uses pkg-config to determine |
20 |
completionsdir and doesn't allow override, it is acceptable to leave |
21 |
it as-is. However, you need to DEPEND on app-shells/ebash-completion |
22 |
then -- so it's better to actually make the path configurable. |
23 |
|
24 |
2. Completion files must be named after *all* commands they're |
25 |
completing. For example, completion for pulseaudio has to be named |
26 |
'pulseaudio' and not 'pulseaudio-bash-completion.sh'. |
27 |
|
28 |
2a. If a completion file provides completions for multiple commands, |
29 |
it should be installed for one of the commands, and symlinked for |
30 |
the others. For example, 'pacat', 'paplay', 'parecord' etc. should be |
31 |
all symlinked to 'pulseaudio'. Extra aliases can be created using |
32 |
'bashcomp_alias' function from the eclass (note: patch currently |
33 |
in review). |
34 |
|
35 |
3. The 'have' function that has been often used in completion files has |
36 |
been deprecated and will not work with autoloaded completions. |
37 |
|
38 |
3a. When 'have' was used to conditionally load completions, it should |
39 |
be removed and completions can be loaded unconditionally. This is |
40 |
because the completion file won't be sourced before the command is |
41 |
typed anyway, and who types commands for non-installed programs? :) |
42 |
|
43 |
3b. When 'have' was used *inside* the completion function for some |
44 |
reason, it may be replaced with '_have'. However, it should be noted |
45 |
that the latter does not set 'have' variable like 'have' did. |
46 |
|
47 |
|
48 |
Also, a reminder of the few generic rules: |
49 |
|
50 |
4. USE=bash-completion should be used scarcely. Completions follow |
51 |
the rules for small text files with no side effects on the main |
52 |
program, and therefore should be installed unconditionally. |
53 |
|
54 |
4a. The use of the USE flag is justified when it pulls in additional |
55 |
dependencies (but see app-shells/bash-completion dependency below). |
56 |
|
57 |
4b. USE flag can also be used to control installing compatdir |
58 |
(/etc/bash_completion.d) files. However, use of that directory is |
59 |
strongly discouraged. |
60 |
|
61 |
5. Run-time dependencies on app-shells/bash-completion are really |
62 |
unnecessary. If you don't have bash-completion, completions won't be |
63 |
loaded and there will be no issue. |
64 |
|
65 |
5a. To enforce a particular version of bash-completion, it is better to |
66 |
use reversed blocker atom. For example, >=app-shells/bash-completion-1.9 |
67 |
should be replaced with !!<app-shells/bash-completion-1.9. This way, it |
68 |
is possible to enforce meeting the version requirements when |
69 |
bash-completion is installed, and not force installing it when it is |
70 |
not. |
71 |
|
72 |
5b. If the build system uses pkg-config to find bash-completion |
73 |
and refuses to install the completions if it is not installed, it is |
74 |
acceptable to add a build-time dependency on app-shells/bash-completion. |
75 |
However, it is recommended to fix the build system instead. |
76 |
|
77 |
|
78 |
Thanks for the help. Any questions shall arise, please do not hesitate |
79 |
to reply to this mail or contact me directly. |
80 |
|
81 |
-- |
82 |
Best regards, |
83 |
Michał Górny |