commit d3842f26e8c6c9a8ba92fa406a7005f604662c49 · pyrox.dev/nixpkgs

+2 -2

doc/languages-frameworks/gnome.section.md

···

       214
       214
        
       

     

       215
       215
        
       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:

     

       216
       216
        
       

     

       217
       217
       -
       - []{#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.

     

       217
       217
       +
       - []{#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.

     

       218
       218
        
       

     

       219
       219
        
       - []{#ssec-gnome-common-issues-unwrappable-package-gsettings} The following examples are hardcoding GSettings schema paths. To get the schema paths we use the functions

     

       220
       220
        
       

     
···

       222
       222
        
       

     

       223
       223
        
         * `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.

     

       224
       224
        
       

     

       225
       225
       -
         []{#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).

     

       225
       225
       +
         []{#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).

     

       226
       226
        
       

     

       227
       227
        
         []{#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.

     

       228
       228

+32 -29

doc/packages/build-support.md

···

       30
       30
        
       ```

     

       31
       31
        
       :::

     

       32
       32
        
       

     

       33
       33
       -
       ## `pkgs.substituteAll` {#pkgs-substituteall}

     

       33
       33
       +
       ## `pkgs.replaceVars` {#pkgs-replacevars}

     

       34
       34
        
       

     

       35
       35
       -
       `pkgs.substituteAll` substitutes all instances of `@varName@` (`@`s included) in file `src` with the value of the corresponding environment variable.

     

       36
       36
       -
       As this uses the [`substituteAll`] (#fun-substitute) function, its limitations regarding variable names that will or will not be replaced also apply here.

     

       35
       35
       +
       `pkgs.replaceVars <src> <replacements>` replaces all instances of `@varName@` (`@`s included) in file `src` with the respective value in the attribute set `replacements`.

     

       37
       36
        
       

     

       38
       38
       -
       :::{.example #ex-pkgs-substituteAll}

     

       39
       39
       -
       # Usage of `pkgs.substituteAll`

     

       37
       37
       +
       :::{.example #ex-pkgs-replace-vars}

     

       38
       38
       +
       # Usage of `pkgs.replaceVars`

     

       40
       39
        
       

     

       41
       40
        
       If `say-goodbye.sh` contains the following:

     

       42
       41
        
       

     
···

       51
       50
        
       

     

       52
       51
        
       ```nix

     

       53
       52
        
       {

     

       54
       54
       -
         substituteAll,

     

       53
       53
       +
         replaceVars,

     

       55
       54
        
         bash,

     

       56
       55
        
         hello,

     

       57
       56
        
       }:

     

       58
       58
       -
       substituteAll {

     

       59
       59
       -
         src = ./say-goodbye.sh;

     

       60
       60
       -
         env = {

     

       61
       61
       -
           inherit bash hello;

     

       62
       62
       -
           greeting = "goodbye";

     

       63
       63
       -
         };

     

       57
       57
       +
       replaceVars ./say-goodbye.sh {

     

       58
       58
       +
         inherit bash hello;

     

       59
       59
       +
         greeting = "goodbye";

     

       60
       60
       +
         unchanged = null;

     

       64
       61
        
       }

     

       65
       62
        
       ```

     

       66
       63
        
       

     
···

       72
       69
        
       echo @unchanged@

     

       73
       70
        
       /nix/store/566f5isbvw014h7knmzmxa5l6hshx43k-hello-2.12.1/bin/hello --greeting goodbye

     

       74
       71
        
       ```

     

       72
       72
       +
       

     

       73
       73
       +
       Note that, in contrast to the old `substituteAll`, `unchanged = null` must explicitly be set.

     

       74
       74
       +
       Any unreferenced `@...@` pattern in the source file will throw an error.

     

       75
       75
        
       :::

     

       76
       76
        
       

     

       77
       77
       -
       ## `pkgs.substituteAllFiles` {#pkgs-substituteallfiles}

     

       77
       77
       +
       ## `pkgs.replaceVarsWith` {#pkgs-replacevarswith}

     

       78
       78
        
       

     

       79
       79
       -
       `pkgs.substituteAllFiles` replaces `@varName@` with the value of the environment variable `varName`.

     

       80
       80
       -
       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`.

     

       79
       79
       +
       `pkgs.replaceVarsWith` works the same way as [pkgs.replaceVars](#pkgs-replacevars), but additionally allows more options.

     

       80
       80
       +
       

     

       81
       81
       +
       :::{.example #ex-pkgs-replace-vars-with}

     

       82
       82
       +
       # Usage of `pkgs.replaceVarsWith`

     

       81
       83
        
       

     

       82
       82
       -
       As it also uses the `substituteAll` function, it is subject to the same limitations on environment variables as discussed in [pkgs.substituteAll](#pkgs-substituteall).

     

       84
       84
       +
       With the example file `say-goodbye.sh`, consider:

     

       83
       85
        
       

     

       84
       84
       -
       :::{.example #ex-pkgs-substitute-all-files}

     

       85
       85
       -
       # Usage of `pkgs.substituteAllFiles`

     

       86
       86
       +
       ```nix

     

       87
       87
       +
       { replaceVarsWith }:

     

       88
       88
       +
       replaceVarsWith {

     

       89
       89
       +
         src = ./say-goodbye.sh;

     

       86
       90
        
       

     

       87
       87
       -
       If the current directory contains `{foo,bar,baz}.txt` and the following `default.nix`

     

       91
       91
       +
         replacements = {

     

       92
       92
       +
           inherit bash hello;

     

       93
       93
       +
           greeting = "goodbye";

     

       94
       94
       +
           unchanged = null;

     

       95
       95
       +
         };

     

       88
       96
        
       

     

       89
       89
       -
       ```nix

     

       90
       90
       -
       { substituteAllFiles }:

     

       91
       91
       -
       substituteAllFiles {

     

       92
       92
       -
         src = ./.;

     

       93
       93
       -
         files = [

     

       94
       94
       -
           "foo.txt"

     

       95
       95
       -
           "bar.txt"

     

       96
       96
       -
         ];

     

       97
       97
       -
         hello = "there";

     

       97
       97
       +
         name = "say-goodbye";

     

       98
       98
       +
         dir = "bin";

     

       99
       99
       +
         isExecutable = true;

     

       100
       100
       +
         meta.mainProgram = "say-goodbye";

     

       98
       101
        
       }

     

       99
       102
        
       ```

     

       100
       103
        
       

     

       101
       101
       -
       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`.

     

       104
       104
       +
       This will make the resulting file executable, put it in `bin/say-goodbye` and set `meta` attributes respectively.

     

       102
       105
        
       :::

+16 -12

doc/redirects.json

···

       8
       8
        
         "ex-build-helpers-extendMkDerivation": [

     

       9
       9
        
           "index.html#ex-build-helpers-extendMkDerivation"

     

       10
       10
        
         ],

     

       11
       11
       +
         "ex-pkgs-replace-vars": [

     

       12
       12
       +
           "index.html#ex-pkgs-replace-vars",

     

       13
       13
       +
           "index.html#ex-pkgs-substituteAll",

     

       14
       14
       +
           "index.html#ex-pkgs-substitute-all-files"

     

       15
       15
       +
         ],

     

       16
       16
       +
         "ex-pkgs-replace-vars-with": [

     

       17
       17
       +
           "index.html#ex-pkgs-replace-vars-with"

     

       18
       18
       +
         ],

     

       11
       19
        
         "ex-shfmt": [

     

       12
       20
        
           "index.html#ex-shfmt"

     

       13
       21
        
         ],

     
···

       34
       42
        
         ],

     

       35
       43
        
         "no-broken-symlinks.sh": [

     

       36
       44
        
           "index.html#no-broken-symlinks.sh"

     

       45
       45
       +
         ],

     

       46
       46
       +
         "pkgs-replacevars": [

     

       47
       47
       +
           "index.html#pkgs-replacevars",

     

       48
       48
       +
           "index.html#pkgs-substituteall",

     

       49
       49
       +
           "index.html#pkgs-substituteallfiles"

     

       50
       50
       +
         ],

     

       51
       51
       +
         "pkgs-replacevarswith": [

     

       52
       52
       +
           "index.html#pkgs-replacevarswith"

     

       37
       53
        
         ],

     

       38
       54
        
         "preface": [

     

       39
       55
        
           "index.html#preface"

     
···

       4192
       4208
        
         ],

     

       4193
       4209
        
         "ex-pkgs-substitute": [

     

       4194
       4210
        
           "index.html#ex-pkgs-substitute"

     

       4195
       4195
       -
         ],

     

       4196
       4196
       -
         "pkgs-substituteall": [

     

       4197
       4197
       -
           "index.html#pkgs-substituteall"

     

       4198
       4198
       -
         ],

     

       4199
       4199
       -
         "ex-pkgs-substituteAll": [

     

       4200
       4200
       -
           "index.html#ex-pkgs-substituteAll"

     

       4201
       4201
       -
         ],

     

       4202
       4202
       -
         "pkgs-substituteallfiles": [

     

       4203
       4203
       -
           "index.html#pkgs-substituteallfiles"

     

       4204
       4204
       -
         ],

     

       4205
       4205
       -
         "ex-pkgs-substitute-all-files": [

     

       4206
       4206
       -
           "index.html#ex-pkgs-substitute-all-files"

     

       4207
       4211
        
         ],

     

       4208
       4212
        
         "part-development": [

     

       4209
       4213
        
           "index.html#part-development"