nixpkgs/doc/packages/build-support.md

Build Support

pkgs.substitute

pkgs.substitute is a wrapper around the substitute Bash function in the standard environment. It replaces strings in src as specified by the substitutions argument.

:::{.example #ex-pkgs-substitute}

Usage of pkgs.substitute

In a build script, the line:

substitute $infile $outfile --replace-fail @foo@ ${foopkg}/bin/foo

is equivalent to:

{ substitute, foopkg }:
substitute {
  src = ./sourcefile.txt;
  substitutions = [
    "--replace"
    "@foo@"
    "${foopkg}/bin/foo"
  ];
}

:::

pkgs.replaceVars

pkgs.replaceVars <src> <replacements> replaces all instances of @varName@ (@s included) in file src with the respective value in the attribute set replacements.

:::{.example #ex-pkgs-replace-vars}

Usage of pkgs.replaceVars

If say-goodbye.sh contains the following:

#! @bash@/bin/bash

echo @unchanged@
@hello@/bin/hello --greeting @greeting@

the following derivation will make substitutions to @bash@, @hello@, and @greeting@:

{
  replaceVars,
  bash,
  hello,
}:
replaceVars ./say-goodbye.sh {
  inherit bash hello;
  greeting = "goodbye";
  unchanged = null;
}

such that $out will result in something like the following:

#! /nix/store/s30jrpgav677fpc9yvkqsib70xfmx7xi-bash-5.2p26/bin/bash

echo @unchanged@
/nix/store/566f5isbvw014h7knmzmxa5l6hshx43k-hello-2.12.1/bin/hello --greeting goodbye

Note that, in contrast to the old substituteAll, unchanged = null must explicitly be set. Any unreferenced @...@ pattern in the source file will throw an error. :::

pkgs.replaceVarsWith

pkgs.replaceVarsWith works the same way as pkgs.replaceVars, but additionally allows more options.

:::{.example #ex-pkgs-replace-vars-with}

Usage of pkgs.replaceVarsWith

With the example file say-goodbye.sh, consider:

{ replaceVarsWith }:
replaceVarsWith {
  src = ./say-goodbye.sh;

  replacements = {
    inherit bash hello;
    greeting = "goodbye";
    unchanged = null;
  };

  name = "say-goodbye";
  dir = "bin";
  isExecutable = true;
  meta.mainProgram = "say-goodbye";
}

This will make the resulting file executable, put it in bin/say-goodbye and set meta attributes respectively. :::