doc/packages/build-support.md

   1 # Build Support {#sec-build-support}
   2
   3 ## `pkgs.substitute` {#pkgs-substitute}
   4
   5 `pkgs.substitute` is a wrapper around [the `substitute` Bash function](#fun-substitute) in the standard environment.
   6 It replaces strings in `src` as specified by the `substitutions` argument.
   7
   8
   9 :::{.example #ex-pkgs-substitute}
  10 # Usage of `pkgs.substitute`
  11
  12 In a build script, the line:
  13
  14 ```bash
  15 substitute $infile $outfile --replace-fail @foo@ ${foopkg}/bin/foo
  16 ```
  17
  18 is equivalent to:
  19
  20 ```nix
  21 { substitute, foopkg }:
  22 substitute {
  23   src = ./sourcefile.txt;
  24   substitutions = [
  25     "--replace"
  26     "@foo@"
  27     "${foopkg}/bin/foo"
  28   ];
  29 }
  30 ```
  31 :::
  32
  33 ## `pkgs.substituteAll` {#pkgs-substituteall}
  34
  35 `pkgs.substituteAll` substitutes all instances of `@varName@` (`@`s included) in file `src` with the value of the corresponding environment variable.
  36 As this uses the [`substituteAll`] (#fun-substitute) function, its limitations regarding variable names that will or will not be replaced also apply here.
  37
  38 :::{.example #ex-pkgs-substituteAll}
  39 # Usage of `pkgs.substituteAll`
  40
  41 If `say-goodbye.sh` contains the following:
  42
  43 ```bash
  44 #! @bash@/bin/bash
  45
  46 echo @unchanged@
  47 @hello@/bin/hello --greeting @greeting@
  48 ```
  49
  50 the following derivation will make substitutions to `@bash@`, `@hello@`, and `@greeting@`:
  51
  52 ```nix
  53 {
  54   substituteAll,
  55   bash,
  56   hello,
  57 }:
  58 substituteAll {
  59   src = ./say-goodbye.sh;
  60   env = {
  61     inherit bash hello;
  62     greeting = "goodbye";
  63   };
  64 }
  65 ```
  66
  67 such that `$out` will result in something like the following:
  68
  69 ```
  70 #! /nix/store/s30jrpgav677fpc9yvkqsib70xfmx7xi-bash-5.2p26/bin/bash
  71
  72 echo @unchanged@
  73 /nix/store/566f5isbvw014h7knmzmxa5l6hshx43k-hello-2.12.1/bin/hello --greeting goodbye
  74 ```
  75 :::
  76
  77 ## `pkgs.substituteAllFiles` {#pkgs-substituteallfiles}
  78
  79 `pkgs.substituteAllFiles` replaces `@varName@` with the value of the environment variable `varName`.
  80 It expects `src` to be a directory and requires a `files` argument that specifies which files will be subject to replacements; only these files will be placed in `$out`.
  81
  82 As it also uses the `substituteAll` function, it is subject to the same limitations on environment variables as discussed in [pkgs.substituteAll](#pkgs-substituteall).
  83
  84 :::{.example #ex-pkgs-substitute-all-files}
  85 # Usage of `pkgs.substituteAllFiles`
  86
  87 If the current directory contains `{foo,bar,baz}.txt` and the following `default.nix`
  88
  89 ```nix
  90 { substituteAllFiles }:
  91 substituteAllFiles {
  92   src = ./.;
  93   files = [
  94     "foo.txt"
  95     "bar.txt"
  96   ];
  97   hello = "there";
  98 }
  99 ```
 100
 101 in the resulting derivation, every instance of `@hello@` will be replaced with `there` in `$out/foo.txt` and` `$out/bar.txt`; `baz.txt` will not be processed nor will it appear in `$out`.
 102 :::