From f5f24cdb5883bb4e672477a52bf2e9130c708c52 Mon Sep 17 00:00:00 2001
From: Nathan Henrie <nate@n8henrie.com>
Date: Thu, 11 Jul 2024 14:47:04 -0600
Subject: [PATCH] doc: add documentation for
 `pkgs.{substitute,substituteAll,substituteAllFiles}`

Fixes https://github.com/NixOS/nixpkgs/issues/65252
---
 doc/packages/build-support.md | 102 ++++++++++++++++++++++++++++++++++
 doc/packages/index.md         |   1 +
 2 files changed, 103 insertions(+)
 create mode 100644 doc/packages/build-support.md

diff --git a/doc/packages/build-support.md b/doc/packages/build-support.md
new file mode 100644
index 000000000000..cf6a13384753
--- /dev/null
+++ b/doc/packages/build-support.md
@@ -0,0 +1,102 @@
+# 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"
+  ];
+}
+```
+:::
+
+## `pkgs.substituteAll` {#pkgs-substituteall}
+
+`pkgs.substituteAll` substitutes all instances of `@varName@` (`@`s included) in file `src` with the value of the corresponding environment variable.
+As this uses the [`substituteAll`] (#fun-substitute) function, its limitations regarding variable names that will or will not be replaced also apply here.
+
+:::{.example #ex-pkgs-substituteAll}
+# Usage of `pkgs.substituteAll`
+
+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
+{
+  substituteAll,
+  bash,
+  hello,
+}:
+substituteAll {
+  src = ./say-goodbye.sh;
+  env = {
+    inherit bash hello;
+    greeting = "goodbye";
+  };
+}
+```
+
+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
+```
+:::
+
+## `pkgs.substituteAllFiles` {#pkgs-substituteallfiles}
+
+`pkgs.substituteAllFiles` replaces `@varName@` with the value of the environment variable `varName`.
+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`.
+
+As it also uses the `substituteAll` function, it is subject to the same limitations on environment variables as discussed in [pkgs.substituteAll](#pkgs-substituteall).
+
+:::{.example #ex-pkgs-substitute-all-files}
+# Usage of `pkgs.substituteAllFiles`
+
+If the current directory contains `{foo,bar,baz}.txt` and the following `default.nix`
+
+```nix
+{ substituteAllFiles }:
+substituteAllFiles {
+  src = ./.;
+  files = [
+    "foo.txt"
+    "bar.txt"
+  ];
+  hello = "there";
+}
+```
+
+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`.
+:::
diff --git a/doc/packages/index.md b/doc/packages/index.md
index 69dd8c3b3bff..c5aa7dbfa0ee 100644
--- a/doc/packages/index.md
+++ b/doc/packages/index.md
@@ -27,4 +27,5 @@ urxvt.section.md
 vcpkg.section.md
 weechat.section.md
 xorg.section.md
+build-support.md
 ```