doc/build-support: replace substituteAll with replaceVars

doc/languages-frameworks/gnome.section.md

@@ -214,7 +214,7 @@ stdenv.mkDerivation {
 
 You can rely on applications depending on the library setting the necessary environment variables but that is often easy to miss. Instead we recommend to patch the paths in the source code whenever possible. Here are some examples:
 
-- []{#ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext} [Replacing a `GI_TYPELIB_PATH` in GNOME Shell extension](https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/gnome-3/core/gnome-shell-extensions/default.nix#L21-L24) – we are using `substituteAll` to include the path to a typelib into a patch.
+- []{#ssec-gnome-common-issues-unwrappable-package-gnome-shell-ext} [Replacing a `GI_TYPELIB_PATH` in GNOME Shell extension](https://github.com/NixOS/nixpkgs/blob/e981466fbb08e6231a1377539ff17fbba3270fda/pkgs/by-name/gn/gnome-shell-extensions/package.nix#L25-L32) – we are using `replaceVars` to include the path to a typelib into a patch.
 
 - []{#ssec-gnome-common-issues-unwrappable-package-gsettings} The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions
 
@@ -222,7 +222,7 @@ You can rely on applications depending on the library setting the necessary envi
 
   * `glib.makeSchemaPath` Takes a package output like `$out` and a derivation name. You should use this if the schemas you need to hardcode are in the same derivation.
 
-  []{#ssec-gnome-common-issues-unwrappable-package-gsettings-vala} [Hard-coding GSettings schema path in Vala plug-in (dynamically loaded library)](https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86) – here, `substituteAll` cannot be used since the schema comes from the same package preventing us from pass its path to the function, probably due to a [Nix bug](https://github.com/NixOS/nix/issues/1846).
+  []{#ssec-gnome-common-issues-unwrappable-package-gsettings-vala} [Hard-coding GSettings schema path in Vala plug-in (dynamically loaded library)](https://github.com/NixOS/nixpkgs/blob/7bb8f05f12ca3cff9da72b56caa2f7472d5732bc/pkgs/desktops/pantheon/apps/elementary-files/default.nix#L78-L86) – here, `replaceVars` cannot be used since the schema comes from the same package preventing us from pass its path to the function, probably due to a [Nix bug](https://github.com/NixOS/nix/issues/1846).
 
   []{#ssec-gnome-common-issues-unwrappable-package-gsettings-c} [Hard-coding GSettings schema path in C library](https://github.com/NixOS/nixpkgs/blob/29c120c065d03b000224872251bed93932d42412/pkgs/development/libraries/glib-networking/default.nix#L31-L34) – nothing special other than using [Coccinelle patch](https://github.com/NixOS/nixpkgs/pull/67957#issuecomment-527717467) to generate the patch itself.
 

doc/packages/build-support.md

@@ -30,13 +30,12 @@ substitute {
 ```
 :::
 
-## `pkgs.substituteAll` {#pkgs-substituteall}
+## `pkgs.replaceVars` {#pkgs-replacevars}
 
-`pkgs.substituteAll` substitutes all instances of `@varName@` (`@`s included) in file `src` with the value of the corresponding environment variable.
+`pkgs.replaceVars <src> <replacements>` replaces all instances of `@varName@` (`@`s included) in file `src` with the respective value in the attribute set `replacements`.
-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}
+:::{.example #ex-pkgs-replace-vars}
-# Usage of `pkgs.substituteAll`
+# Usage of `pkgs.replaceVars`
 
 If `say-goodbye.sh` contains the following:
 
@@ -51,16 +50,14 @@ the following derivation will make substitutions to `@bash@`, `@hello@`, and `@g
 
 ```nix
 {
-  substituteAll,
+  replaceVars,
   bash,
   hello,
 }:
-substituteAll {
+replaceVars ./say-goodbye.sh {
-  src = ./say-goodbye.sh;
+  inherit bash hello;
-  env = {
+  greeting = "goodbye";
-    inherit bash hello;
+  unchanged = null;
-    greeting = "goodbye";
-  };
 }
 ```
 
@@ -72,31 +69,37 @@ such that `$out` will result in something like the following:
 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.substituteAllFiles` {#pkgs-substituteallfiles}
+## `pkgs.replaceVarsWith` {#pkgs-replacevarswith}
 
-`pkgs.substituteAllFiles` replaces `@varName@` with the value of the environment variable `varName`.
+`pkgs.replaceVarsWith` works the same way as [pkgs.replaceVars](#pkgs-replacevars), but additionally allows more options.
-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-replace-vars-with}
+# Usage of `pkgs.replaceVarsWith`
 
-:::{.example #ex-pkgs-substitute-all-files}
+With the example file `say-goodbye.sh`, consider:
-# Usage of `pkgs.substituteAllFiles`
-
-If the current directory contains `{foo,bar,baz}.txt` and the following `default.nix`
 
 ```nix
-{ substituteAllFiles }:
+{ replaceVarsWith }:
-substituteAllFiles {
+replaceVarsWith {
-  src = ./.;
+  src = ./say-goodbye.sh;
-  files = [
+
-    "foo.txt"
+  replacements = {
-    "bar.txt"
+    inherit bash hello;
-  ];
+    greeting = "goodbye";
-  hello = "there";
+    unchanged = null;
+  };
+
+  name = "say-goodbye";
+  dir = "bin";
+  isExecutable = true;
+  meta.mainProgram = "say-goodbye";
 }
 ```
 
-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`.
+This will make the resulting file executable, put it in `bin/say-goodbye` and set `meta` attributes respectively.
 :::

doc/redirects.json

@@ -8,6 +8,14 @@
   "ex-build-helpers-extendMkDerivation": [
     "index.html#ex-build-helpers-extendMkDerivation"
   ],
+  "ex-pkgs-replace-vars": [
+    "index.html#ex-pkgs-replace-vars",
+    "index.html#ex-pkgs-substituteAll",
+    "index.html#ex-pkgs-substitute-all-files"
+  ],
+  "ex-pkgs-replace-vars-with": [
+    "index.html#ex-pkgs-replace-vars-with"
+  ],
   "ex-shfmt": [
     "index.html#ex-shfmt"
   ],
@@ -35,6 +43,14 @@
   "no-broken-symlinks.sh": [
     "index.html#no-broken-symlinks.sh"
   ],
+  "pkgs-replacevars": [
+    "index.html#pkgs-replacevars",
+    "index.html#pkgs-substituteall",
+    "index.html#pkgs-substituteallfiles"
+  ],
+  "pkgs-replacevarswith": [
+    "index.html#pkgs-replacevarswith"
+  ],
   "preface": [
     "index.html#preface"
   ],
@@ -4193,18 +4209,6 @@
   "ex-pkgs-substitute": [
     "index.html#ex-pkgs-substitute"
   ],
-  "pkgs-substituteall": [
-    "index.html#pkgs-substituteall"
-  ],
-  "ex-pkgs-substituteAll": [
-    "index.html#ex-pkgs-substituteAll"
-  ],
-  "pkgs-substituteallfiles": [
-    "index.html#pkgs-substituteallfiles"
-  ],
-  "ex-pkgs-substitute-all-files": [
-    "index.html#ex-pkgs-substitute-all-files"
-  ],
   "part-development": [
     "index.html#part-development"
   ],