···214214215215You 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:
216216217217-- []{#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.
217217+- []{#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.
218218219219- []{#ssec-gnome-common-issues-unwrappable-package-gsettings} The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions
220220···222222223223 * `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.
224224225225- []{#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).
225225+ []{#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).
226226227227 []{#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.
228228
+32-29
doc/packages/build-support.md
···3030```
3131:::
32323333-## `pkgs.substituteAll` {#pkgs-substituteall}
3333+## `pkgs.replaceVars` {#pkgs-replacevars}
34343535-`pkgs.substituteAll` substitutes all instances of `@varName@` (`@`s included) in file `src` with the value of the corresponding environment variable.
3636-As this uses the [`substituteAll`] (#fun-substitute) function, its limitations regarding variable names that will or will not be replaced also apply here.
3535+`pkgs.replaceVars <src> <replacements>` replaces all instances of `@varName@` (`@`s included) in file `src` with the respective value in the attribute set `replacements`.
37363838-:::{.example #ex-pkgs-substituteAll}
3939-# Usage of `pkgs.substituteAll`
3737+:::{.example #ex-pkgs-replace-vars}
3838+# Usage of `pkgs.replaceVars`
40394140If `say-goodbye.sh` contains the following:
4241···51505251```nix
5352{
5454- substituteAll,
5353+ replaceVars,
5554 bash,
5655 hello,
5756}:
5858-substituteAll {
5959- src = ./say-goodbye.sh;
6060- env = {
6161- inherit bash hello;
6262- greeting = "goodbye";
6363- };
5757+replaceVars ./say-goodbye.sh {
5858+ inherit bash hello;
5959+ greeting = "goodbye";
6060+ unchanged = null;
6461}
6562```
6663···7269echo @unchanged@
7370/nix/store/566f5isbvw014h7knmzmxa5l6hshx43k-hello-2.12.1/bin/hello --greeting goodbye
7471```
7272+7373+Note that, in contrast to the old `substituteAll`, `unchanged = null` must explicitly be set.
7474+Any unreferenced `@...@` pattern in the source file will throw an error.
7575:::
76767777-## `pkgs.substituteAllFiles` {#pkgs-substituteallfiles}
7777+## `pkgs.replaceVarsWith` {#pkgs-replacevarswith}
78787979-`pkgs.substituteAllFiles` replaces `@varName@` with the value of the environment variable `varName`.
8080-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`.
7979+`pkgs.replaceVarsWith` works the same way as [pkgs.replaceVars](#pkgs-replacevars), but additionally allows more options.
8080+8181+:::{.example #ex-pkgs-replace-vars-with}
8282+# Usage of `pkgs.replaceVarsWith`
81838282-As it also uses the `substituteAll` function, it is subject to the same limitations on environment variables as discussed in [pkgs.substituteAll](#pkgs-substituteall).
8484+With the example file `say-goodbye.sh`, consider:
83858484-:::{.example #ex-pkgs-substitute-all-files}
8585-# Usage of `pkgs.substituteAllFiles`
8686+```nix
8787+{ replaceVarsWith }:
8888+replaceVarsWith {
8989+ src = ./say-goodbye.sh;
86908787-If the current directory contains `{foo,bar,baz}.txt` and the following `default.nix`
9191+ replacements = {
9292+ inherit bash hello;
9393+ greeting = "goodbye";
9494+ unchanged = null;
9595+ };
88968989-```nix
9090-{ substituteAllFiles }:
9191-substituteAllFiles {
9292- src = ./.;
9393- files = [
9494- "foo.txt"
9595- "bar.txt"
9696- ];
9797- hello = "there";
9797+ name = "say-goodbye";
9898+ dir = "bin";
9999+ isExecutable = true;
100100+ meta.mainProgram = "say-goodbye";
98101}
99102```
100103101101-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`.
104104+This will make the resulting file executable, put it in `bin/say-goodbye` and set `meta` attributes respectively.
102105:::
···115115116116- All support for 32‐bit Darwin systems has been dropped.
117117118118+- `substituteAll` and `substituteAllFiles` have been deprecated in favor of `replaceVars` and will be removed in the next release.
119119+118120- Default ICU version updated from 74 to 76
119121120122- Apache Kafka was updated to `>= 4.0.0`. Please note that this is the first release which operates
···2626 qt6,
2727 tbb_2021_11,
2828 tracy,
2929- substituteAll,
2929+ replaceVars,
3030 python3,
3131}:
3232let
···9494 patches = [
9595 # These are for Nix compatibility {{{
9696 ./patches/use-find-package.patch # Replace some vendored dependencies with Nix provided versions
9797- (substituteAll {
9797+ (replaceVars ./patches/skip-git-versioning.patch {
9898 # Skip tagging build with git version, and substitute it with the src revision (still uses current year timestamp)
9999- src = ./patches/skip-git-versioning.patch;
10099 rev = finalAttrs.src.rev;
101100 })
102101 # Prevents using some Qt scripts that seemed to break the install step. Fixes missing link to some targets.