pyrox.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 undersirable 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. It should be renamed before being
47 # installed via installManPage
48 postInstall = ''
49 mv fromsea.3 delmar.3
50 installManPage foobar.1 delmar.3
51 '';
52}
53```
54
55## `installShellCompletion` {#installshellfiles-installshellcompletion}
56
57The `installShellCompletion` function takes one or more paths to shell
58completion files.
59
60By default it will autodetect the shell type from the completion file extension,
61but you may also specify it by passing one of `--bash`, `--fish`, or
62`--zsh`. These flags apply to all paths listed after them (up until another
63shell flag is given). Each path may also have a custom installation name
64provided by providing a flag `--name NAME` before the path. If this flag is not
65provided, zsh completions will be renamed automatically such that `foobar.zsh`
66becomes `_foobar`. A root name may be provided for all paths using the flag
67`--cmd NAME`; this synthesizes the appropriate name depending on the shell
68(e.g. `--cmd foo` will synthesize the name `foo.bash` for bash and `_foo` for
69zsh).
70
71### Example Usage {#installshellfiles-installshellcompletion-exampleusage}
72
73```nix
74{
75 nativeBuildInputs = [ installShellFiles ];
76 postInstall = ''
77 # explicit behavior
78 installShellCompletion --bash --name foobar.bash share/completions.bash
79 installShellCompletion --fish --name foobar.fish share/completions.fish
80 installShellCompletion --zsh --name _foobar share/completions.zsh
81 # implicit behavior
82 installShellCompletion share/completions/foobar.{bash,fish,zsh}
83 '';
84}
85```
86
87The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which
88case the shell and name must be provided (see below).
89
90If the destination shell completion file is not actually present or consists of
91zero bytes after calling `installShellCompletion` this is treated as a build
92failure. In particular, if completion files are not vendored but are generated
93by running an executable, this is likely to fail in cross compilation
94scenarios. The result will be a zero byte completion file and hence a build
95failure. To prevent this, guard the completion generation commands.
96
97### Example Usage {#installshellfiles-installshellcompletion-exampleusage-guarded}
98
99```nix
100{
101 nativeBuildInputs = [ installShellFiles ];
102 postInstall = lib.optionalString (stdenv.buildPlatform.canExecute stdenv.hostPlatform) ''
103 # using named fd
104 installShellCompletion --cmd foobar \
105 --bash <($out/bin/foobar --bash-completion) \
106 --fish <($out/bin/foobar --fish-completion) \
107 --zsh <($out/bin/foobar --zsh-completion)
108 '';
109}
110```