2024-07-11 14:47:04 -06:00
# Build Support {#sec-build-support}
## `pkgs.substitute` {#pkgs-substitute}
`pkgs.substitute` is a wrapper around [the `substitute` Bash function ](#fun-substitute ) 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:
```bash
substitute $infile $outfile --replace-fail @foo @ ${foopkg}/bin/foo
```
is equivalent to:
```nix
{ substitute, foopkg }:
substitute {
src = ./sourcefile.txt;
substitutions = [
"--replace"
"@foo @"
"${foopkg}/bin/foo"
];
}
```
:::
2025-04-05 15:22:01 +02:00
## `pkgs.replaceVars` {#pkgs-replacevars}
2024-07-11 14:47:04 -06:00
2025-04-05 15:22:01 +02:00
`pkgs.replaceVars <src> <replacements>` replaces all instances of `@varName@` (`@` s included) in file `src` with the respective value in the attribute set `replacements` .
2024-07-11 14:47:04 -06:00
2025-04-05 15:22:01 +02:00
:::{.example #ex -pkgs-replace-vars}
# Usage of `pkgs.replaceVars`
2024-07-11 14:47:04 -06:00
If `say-goodbye.sh` contains the following:
```bash
#! @bash@/bin/bash
echo @unchanged @
@hello@/bin/hello --greeting @greeting @
```
the following derivation will make substitutions to `@bash@` , `@hello@` , and `@greeting@` :
```nix
{
2025-04-05 15:22:01 +02:00
replaceVars,
2024-07-11 14:47:04 -06:00
bash,
hello,
}:
2025-04-05 15:22:01 +02:00
replaceVars ./say-goodbye.sh {
inherit bash hello;
greeting = "goodbye";
unchanged = null;
2024-07-11 14:47:04 -06:00
}
```
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
```
2025-04-05 15:22:01 +02:00
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.
:::
2024-07-11 14:47:04 -06:00
2025-04-05 15:22:01 +02:00
## `pkgs.replaceVarsWith` {#pkgs-replacevarswith}
2024-07-11 14:47:04 -06:00
2025-04-05 15:22:01 +02:00
`pkgs.replaceVarsWith` works the same way as [pkgs.replaceVars ](#pkgs-replacevars ), but additionally allows more options.
2024-07-11 14:47:04 -06:00
2025-04-05 15:22:01 +02:00
:::{.example #ex -pkgs-replace-vars-with}
# Usage of `pkgs.replaceVarsWith`
2024-07-11 14:47:04 -06:00
2025-04-05 15:22:01 +02:00
With the example file `say-goodbye.sh` , consider:
2024-07-11 14:47:04 -06:00
```nix
2025-04-05 15:22:01 +02:00
{ 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";
2024-07-11 14:47:04 -06:00
}
```
2025-04-05 15:22:01 +02:00
This will make the resulting file executable, put it in `bin/say-goodbye` and set `meta` attributes respectively.
2024-07-11 14:47:04 -06:00
:::