doc/hooks/installShellFiles.section.md

   1 # `installShellFiles` {#installshellfiles}
   2
   3 This hook adds helpers that install artifacts like executable files, manpages
   4 and shell completions.
   5
   6 It exposes the following functions that can be used from your `postInstall`
   7 hook:
   8
   9 ## `installBin` {#installshellfiles-installbin}
  10
  11 The `installBin` function takes one or more paths to files to install as
  12 executable files.
  13
  14 This 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
  33 The `installManPage` function takes one or more paths to manpages to install.
  34
  35 The 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
  57 The `installShellCompletion` function takes one or more paths to shell
  58 completion files.
  59
  60 By default it will autodetect the shell type from the completion file extension,
  61 but 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
  63 shell flag is given). Each path may also have a custom installation name
  64 provided by providing a flag `--name NAME` before the path. If this flag is not
  65 provided, zsh completions will be renamed automatically such that `foobar.zsh`
  66 becomes `_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
  69 zsh).
  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
  87 The path may also be a fifo or named fd (such as produced by `<(cmd)`), in which
  88 case the shell and name must be provided (see below).
  89
  90 If the destination shell completion file is not actually present or consists of
  91 zero bytes after calling `installShellCompletion` this is treated as a build
  92 failure. In particular, if completion files are not vendored but are generated
  93 by running an executable, this is likely to fail in cross compilation
  94 scenarios. The result will be a zero byte completion file and hence a build
  95 failure. 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 ```