pkgs/build-support/replace-vars/default.nix

   1 { lib, stdenvNoCC }:
   2
   3 /**
   4   `replaceVars` is a wrapper around the [bash function `substitute`](https://nixos.org/manual/nixpkgs/stable/#fun-substitute)
   5   in the stdenv. It allows for terse replacement of names in the specified path, while checking
   6   for common mistakes such as naming a replacement that does nothing or forgetting a variable which
   7   needs to be replaced.
   8
   9   As with the [`--subst-var-by`](https://nixos.org/manual/nixpkgs/stable/#fun-substitute-subst-var-by)
  10   flag, names are encoded as `@name@` in the provided file at the provided path.
  11
  12   Any unmatched variable names in the file at the provided path will cause a build failure.
  13
  14   Any remaining text that matches `@[A-Za-z_][0-9A-Za-z_'-]@` in the output after replacement
  15   has occurred will cause a build failure.
  16
  17   # Inputs
  18
  19   `path` ([Store Path](https://nixos.org/manual/nix/latest/store/store-path.html#store-path) String)
  20   : The file in which to replace variables.
  21
  22   `attrs` (AttrsOf String)
  23   : Each entry in this set corresponds to a `--subst-var-by` entry in [`substitute`](https://nixos.org/manual/nixpkgs/stable/#fun-substitute).
  24
  25   # Example
  26
  27   ```nix
  28   { replaceVars }:
  29
  30   replaceVars ./greeting.txt { world = "hello"; }
  31   ```
  32
  33   See `../../test/replace-vars/default.nix` for tests of this function.
  34 */
  35 path: attrs:
  36
  37 let
  38   # We use `--replace-fail` instead of `--subst-var-by` so that if the thing isn't there, we fail.
  39   subst-var-by = name: value: [
  40     "--replace-fail"
  41     (lib.escapeShellArg "@${name}@")
  42     (lib.escapeShellArg value)
  43   ];
  44
  45   replacements = lib.concatLists (lib.mapAttrsToList subst-var-by attrs);
  46 in
  47
  48 stdenvNoCC.mkDerivation {
  49   name = baseNameOf (toString path);
  50   src = path;
  51   doCheck = true;
  52   dontUnpack = true;
  53   preferLocalBuild = true;
  54   allowSubstitutes = false;
  55
  56   buildPhase = ''
  57     runHook preBuild
  58     substitute "$src" "$out" ${lib.concatStringsSep " " replacements}
  59     runHook postBuild
  60   '';
  61
  62   # Look for Nix identifiers surrounded by `@` that aren't substituted.
  63   checkPhase =
  64     let
  65       regex = lib.escapeShellArg "@[a-zA-Z_][0-9A-Za-z_'-]*@";
  66     in
  67     ''
  68       runHook preCheck
  69       if grep -qe ${regex} "$out"; then
  70         echo The following look like unsubstituted Nix identifiers that remain in "$out":
  71         grep -oe ${regex} "$out"
  72         echo Use the more precise '`substitute`' function if this check is in error.
  73         exit 1
  74       fi
  75       runHook postCheck
  76     '';
  77 }