From d3842f26e8c6c9a8ba92fa406a7005f604662c49 Mon Sep 17 00:00:00 2001 From: Wolfgang Walther Date: Sat, 5 Apr 2025 15:22:01 +0200 Subject: [PATCH] doc/build-support: replace substituteAll with replaceVars --- doc/languages-frameworks/gnome.section.md | 4 +- doc/packages/build-support.md | 61 ++++++++++++----------- doc/redirects.json | 28 ++++++----- 3 files changed, 50 insertions(+), 43 deletions(-) diff --git a/doc/languages-frameworks/gnome.section.md b/doc/languages-frameworks/gnome.section.md index 03b030fb7be5..718c296bce80 100644 --- a/doc/languages-frameworks/gnome.section.md +++ b/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. diff --git a/doc/packages/build-support.md b/doc/packages/build-support.md index 80392f4d121e..1e4756d7f258 100644 --- a/doc/packages/build-support.md +++ b/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. -As this uses the [`substituteAll`] (#fun-substitute) function, its limitations regarding variable names that will or will not be replaced also apply here. +`pkgs.replaceVars ` replaces all instances of `@varName@` (`@`s included) in file `src` with the respective value in the attribute set `replacements`. -:::{.example #ex-pkgs-substituteAll} -# Usage of `pkgs.substituteAll` +:::{.example #ex-pkgs-replace-vars} +# 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 { - src = ./say-goodbye.sh; - env = { - inherit bash hello; - greeting = "goodbye"; - }; +replaceVars ./say-goodbye.sh { + inherit bash hello; + greeting = "goodbye"; + unchanged = null; } ``` @@ -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`. -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`. +`pkgs.replaceVarsWith` works the same way as [pkgs.replaceVars](#pkgs-replacevars), but additionally allows more options. -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} -# Usage of `pkgs.substituteAllFiles` - -If the current directory contains `{foo,bar,baz}.txt` and the following `default.nix` +With the example file `say-goodbye.sh`, consider: ```nix -{ substituteAllFiles }: -substituteAllFiles { - src = ./.; - files = [ - "foo.txt" - "bar.txt" - ]; - hello = "there"; +{ 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"; } ``` -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. ::: diff --git a/doc/redirects.json b/doc/redirects.json index 627b4137281d..15141bb96426 100644 --- a/doc/redirects.json +++ b/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" ],