tjh.dev
1# `installShellFiles` {#installshellfiles}
2
3This hook adds helpers that install artifacts like executable files, manpages
4and shell completions.
5
6It exposes the following functions that can be used from your `postInstall`
7hook:
8
9## `installBin` {#installshellfiles-installbin}
10
11The `installBin` function takes one or more paths to files to install as
12executable files.
13
14This function will place them into [`outputBin`](#outputbin).
15
16### Example Usage {#installshellfiles-installbin-exampleusage}
17
18```nix
19{
20 nativeBuildInputs = [ installShellFiles ];
21
22 # Sometimes the file has an undesirable name. It should be renamed before
23 # being installed via installBin
24 postInstall = ''
25 mv a.out delmar
26 installBin foobar delmar
27 '';
28}
29```
30
31## `installManPage` {#installshellfiles-installmanpage}
32
33The `installManPage` function takes one or more paths to manpages to install.
34
35The manpages must have a section suffix, and may optionally be compressed (with
36`.gz` suffix). This function will place them into the correct
37`share/man/man<section>/` directory in [`outputMan`](#outputman).
38
39### Example Usage {#installshellfiles-installmanpage-exampleusage}
40
41```nix
42{
43 nativeBuildInputs = [ installShellFiles ];
44
45 # Sometimes the manpage file has an undersirable name; e.g., it conflicts with
46 # another software with an equal name. To install it with a different name,
47 # the installed name must be provided before the path to the file.
48 #
49 # Below install a manpage "foobar.1" from the source file "./foobar.1", and
50 # also installs the manpage "fromsea.3" from the source file "./delmar.3".
51 postInstall = ''
52 installManPage \
53 foobar.1 \
54 --name fromsea.3 delmar.3
55 '';
56}
57```
58
59The manpage may be the result of a piped input (e.g. `<(cmd)`), in which
60case the name must be provided before the pipe with the `--name` flag.
61
62```nix
63{
64 nativeBuildInputs = [ installShellFiles ];
65
66 postInstall = ''
67 installManPage --name foobar.1 <($out/bin/foobar --manpage)
68 '';
69}
70```
71
72If no parsing of arguments is desired, pass `--` to opt-out of all subsequent
73arguments.
74
75```nix
76{
77 nativeBuildInputs = [ installShellFiles ];
78
79 # Installs a manpage from a file called "--name"
80 postInstall = ''
81 installManPage -- --name
82 '';
83}
84```
85
86## `installShellCompletion` {#installshellfiles-installshellcompletion}
87
88The `installShellCompletion` function takes one or more paths to shell
89completion files.
90
91By default it will autodetect the shell type from the completion file extension,
92but you may also specify it by passing one of `--bash`, `--fish`, `--zsh`, or
93`--nushell`. These flags apply to all paths listed after them (up until another
94shell flag is given). Each path may also have a custom installation name
95provided by providing a flag `--name NAME` before the path. If this flag is not
96provided, zsh completions will be renamed automatically such that `foobar.zsh`
97becomes `_foobar`. A root name may be provided for all paths using the flag
98`--cmd NAME`; this synthesizes the appropriate name depending on the shell
99(e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for
100zsh).
101
102### Example Usage {#installshellfiles-installshellcompletion-exampleusage}
103
104```nix
105{
106 nativeBuildInputs = [ installShellFiles ];
107 postInstall = ''
108 # explicit behavior
109 installShellCompletion --bash --name foobar.bash share/completions.bash
110 installShellCompletion --fish --name foobar.fish share/completions.fish
111 installShellCompletion --nushell --name foobar share/completions.nu
112 installShellCompletion --zsh --name _foobar share/completions.zsh
113 # implicit behavior
114 installShellCompletion share/completions/foobar.{bash,fish,zsh,nu}
115 '';
116}
117```
118
119The path may also be the result of process substitution (e.g. `<(cmd)`), in which
120case the shell and name must be provided (see below).
121
122If the destination shell completion file is not actually present or consists of
123zero bytes after calling `installShellCompletion` this is treated as a build
124failure. In particular, if completion files are not vendored but are generated
125by running an executable, this is likely to fail in cross compilation
126scenarios. The result will be a zero byte completion file and hence a build
127failure. To prevent this, guard the completion generation commands.
128
129### Example Usage {#installshellfiles-installshellcompletion-exampleusage-guarded}
130
131```nix
132{
133 nativeBuildInputs = [ installShellFiles ];
134 postInstall = lib.optionalString (stdenv.buildPlatform.canExecute stdenv.hostPlatform) ''
135 # using process substitution
136 installShellCompletion --cmd foobar \
137 --bash <($out/bin/foobar --bash-completion) \
138 --fish <($out/bin/foobar --fish-completion) \
139 --nushell <($out/bin/foobar --nushell-completion) \
140 --zsh <($out/bin/foobar --zsh-completion)
141 '';
142}
143```