Gentoo Archives: gentoo-dev

From: "Michał Górny" <mgorny@g.o>
To: gentoo-dev-announce@l.g.o
Cc: gentoo-dev@l.g.o
Subject: [gentoo-dev] Guidelines for forward bash-completion compatibility
Date: Fri, 29 Aug 2014 18:37:33
Message-Id: 20140829203709.642e5379@pomiot.lan
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

Attachments

File name MIME type
signature.asc application/pgp-signature