commit 1849ee507e1824bf54bdd7c3113f4016ee345836 · pyrox.dev/nixpkgs

+43

doc/module-system/module-system.chapter.md

···

       115
       115
        
       #### `class` {#module-system-lib-evalModules-return-value-_configurationClass}

     

       116
       116
        
       

     

       117
       117
        
       The [`class` argument](#module-system-lib-evalModules-param-class).

     

       118
       118
       +
       

     

       119
       119
       +
       ## Module arguments {#module-system-module-arguments}

     

       120
       120
       +
       

     

       121
       121
       +
       Module arguments are the attribute values passed to modules when they are evaluated.

     

       122
       122
       +
       

     

       123
       123
       +
       They originate from these sources:

     

       124
       124
       +
       1. Built-in arguments

     

       125
       125
       +
           - `lib`,

     

       126
       126
       +
           - `config`,

     

       127
       127
       +
           - `options`,

     

       128
       128
       +
           - `_class`,

     

       129
       129
       +
           - `_prefix`,

     

       130
       130
       +
       2. Attributes from the [`specialArgs`] argument passed to [`evalModules`] or `submoduleWith`. These are application-specific.

     

       131
       131
       +
       3. Attributes from the `_module.args` option value. These are application-specific and can be provided by any module.

     

       132
       132
       +
       

     

       133
       133
       +
       The prior two categories are available while evaluating the `imports`, whereas

     

       134
       134
       +
       the last category is only available after the `imports` have been resolved.

     

       135
       135
       +
       

     

       136
       136
       +
       [`lib`]{#module-system-module-argument-lib} [🔗](#module-system-module-argument-lib)

     

       137
       137
       +
       : A reference to the Nixpkgs library.

     

       138
       138
       +
       

     

       139
       139
       +
       [`config`]{#module-system-module-argument-config} [🔗](#module-system-module-argument-config)

     

       140
       140
       +
       : All option values.

     

       141
       141
       +
         Unlike the `evalModules` [`config` return attribute](#module-system-lib-evalModules-return-value-config), this includes `_module`.

     

       142
       142
       +
       

     

       143
       143
       +
       [`options`]{#module-system-module-argument-options} [🔗](#module-system-module-argument-options)

     

       144
       144
       +
       : All evaluated option declarations.

     

       145
       145
       +
       

     

       146
       146
       +
       [`_class`]{#module-system-module-argument-_class} [🔗](#module-system-module-argument-_class)

     

       147
       147
       +
       : The [expected class](#module-system-lib-evalModules-param-class) of the loaded modules.

     

       148
       148
       +
       

     

       149
       149
       +
       [`_prefix`]{#module-system-module-argument-_prefix} [🔗](#module-system-module-argument-_prefix)

     

       150
       150
       +
       : The location under which the module is evaluated.

     

       151
       151
       +
         This is used to improve error reporting and to find the implicit `name` module argument in submodules.

     

       152
       152
       +
         It is exposed as a module argument due to how the module system is implemented, which cannot be avoided without breaking compatibility.

     

       153
       153
       +
       

     

       154
       154
       +
         It is a good practice not to rely on `_prefix`. A module should not make assumptions about its location in the configuration tree.

     

       155
       155
       +
         For example, the root of a NixOS configuration may have a non-empty prefix, for example when it is a specialisation, or when it is part of a larger, multi-host configuration such as a [NixOS test](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests).

     

       156
       156
       +
         Instead of depending on `_prefix` use explicit options, whose default definitions can be provided by the module that imports them.

     

       157
       157
       +
       

     

       158
       158
       +
       <!-- markdown link aliases -->

     

       159
       159
       +
       [`evalModules`]: #module-system-lib-evalModules

     

       160
       160
       +
       [`specialArgs`]: #module-system-lib-evalModules-param-specialArgs

+18

doc/redirects.json

···

       4515
       4515
        
         ],

     

       4516
       4516
        
         "sec-interop.cylonedx-fod": [

     

       4517
       4517
        
           "index.html#sec-interop.cylonedx-fod"

     

       4518
       4518
       +
         ],

     

       4519
       4519
       +
         "module-system-module-argument-_prefix": [

     

       4520
       4520
       +
           "index.html#module-system-module-argument-_prefix"

     

       4521
       4521
       +
         ],

     

       4522
       4522
       +
         "module-system-module-argument-lib": [

     

       4523
       4523
       +
           "index.html#module-system-module-argument-lib"

     

       4524
       4524
       +
         ],

     

       4525
       4525
       +
         "module-system-module-argument-config": [

     

       4526
       4526
       +
           "index.html#module-system-module-argument-config"

     

       4527
       4527
       +
         ],

     

       4528
       4528
       +
         "module-system-module-arguments": [

     

       4529
       4529
       +
           "index.html#module-system-module-arguments"

     

       4530
       4530
       +
         ],

     

       4531
       4531
       +
         "module-system-module-argument-_class": [

     

       4532
       4532
       +
           "index.html#module-system-module-argument-_class"

     

       4533
       4533
       +
         ],

     

       4534
       4534
       +
         "module-system-module-argument-options": [

     

       4535
       4535
       +
           "index.html#module-system-module-argument-options"

     

       4518
       4536
        
         ]

     

       4519
       4537
        
       }

+10 -3

lib/modules.nix

···

       258
       258
        
                           specialArgs

     

       259
       259
        
                           ;

     

       260
       260
        
                         _class = class;

     

       261
       261
       +
                         _prefix = prefix;

     

       261
       262
        
                       }

     

       262
       263
        
                       // specialArgs

     

       263
       264
        
                     );

     
···

       388
       389
        
                       value = m;

     

       389
       390
        
                       _type = m._type;

     

       390
       391
        
                       expectedClass = class;

     

       392
       392
       +
                       prefix = args._prefix;

     

       391
       393
        
                     }

     

       392
       394
        
                   )

     

       393
       395
        
               else if isList m then

     
···

       1976
       1978
        
                 file != null && file != unknownModule

     

       1977
       1979
        
               ) ", while trying to load a module into ${toString file}";

     

       1978
       1980
        
       

     

       1981
       1981
       +
             into_prefix_maybe =

     

       1982
       1982
       +
               prefix:

     

       1983
       1983
       +
               optionalString (prefix != [ ]) ", while trying to load a module into ${code (showOption prefix)}";

     

       1984
       1984
       +
       

     

       1979
       1985
        
             /**

     

       1980
       1986
        
               Format text with one line break between each list item.

     

       1981
       1987
        
             */

     
···

       2023
       2029
        
                 value,

     

       2024
       2030
        
                 _type,

     

       2025
       2031
        
                 expectedClass ? null,

     

       2032
       2032
       +
                 prefix,

     

       2026
       2033
        
               }:

     

       2027
       2034
        
               paragraphs (

     

       2028
       2035
        
                 [

     

       2029
       2036
        
                   ''

     

       2030
       2030
       -
                     Expected a module, but found a value of type ${warn (escapeNixString _type)}${into_fallback_file_maybe fallbackFile}.

     

       2031
       2031
       -
                     A module is typically loaded by adding it the ${code "imports = [ ... ];"} attribute of an existing module, or in the ${code "modules = [ ... ];"} argument of various functions.

     

       2037
       2037
       +
                     Expected a module, but found a value of type ${warn (escapeNixString _type)}${into_fallback_file_maybe fallbackFile}${into_prefix_maybe prefix}.

     

       2038
       2038
       +
                     A module is typically loaded by adding it to the ${code "imports = [ ... ];"} attribute of an existing module, or in the ${code "modules = [ ... ];"} argument of various functions.

     

       2032
       2039
        
                     Please make sure that each of the list items is a module, and not a different kind of value.

     

       2033
       2040
        
                   ''

     

       2034
       2041
        
                 ]

     
···

       2057
       2064
        
                       '')

     

       2058
       2065
        
                     ]

     

       2059
       2066
        
                     ++ optionalMatch {

     

       2060
       2060
       -
                       # We'll no more than 5 custom suggestions here.

     

       2067
       2067
       +
                       # We'll add no more than 5 custom suggestions here.

     

       2061
       2068
        
                       # Please switch to `.modules.${class}` in your Module System application.

     

       2062
       2069
        
                       "nixos" = trim ''

     

       2063
       2070
        
                         or

lib/tests/modules.sh

···

       364
       364
        
       ## Paths should be allowed as values and work as expected

     

       365
       365
        
       checkConfigOutput '^true$' config.submodule.enable ./declare-submoduleWith-path.nix

     

       366
       366
        
       

     

       367
       367
       +
       ## _prefix module argument is available at import time and contains the prefix

     

       368
       368
       +
       checkConfigOutput '^true$' config.foo.ok ./prefix-module-argument.nix

     

       369
       369
       +
       

     

       367
       370
        
       ## deferredModule

     

       368
       371
        
       # default module is merged into nodes.foo

     

       369
       372
        
       checkConfigOutput '"beta"' config.nodes.foo.settingsDict.c ./deferred-module.nix

     
···

       615
       618
        
       checkConfigOutput '^true$' config.enable ./declare-enable.nix ./define-enable-with-top-level-mkIf.nix

     

       616
       619
        
       checkConfigError 'Expected a module, but found a value of type .*"configuration".*, while trying to load a module into .*/import-configuration.nix.' config ./import-configuration.nix

     

       617
       620
        
       checkConfigError 'please only import the modules that make up the configuration' config ./import-configuration.nix

     

       621
       621
       +
       checkConfigError 'Expected a module, but found a value of type "configuration", while trying to load a module into .*/import-error-submodule.nix, while trying to load a module into .*foo.*\.' config.foo ./import-error-submodule.nix

     

       618
       622
        
       

     

       619
       623
        
       # doRename works when `warnings` does not exist.

     

       620
       624
        
       checkConfigOutput '^1234$' config.c.d.e ./doRename-basic.nix

+18

lib/tests/modules/import-error-submodule.nix

···

       1
       1
       +
       { lib, ... }:

     

       2
       2
       +
       let

     

       3
       3
       +
         myconf = lib.evalModules { modules = [ { } ]; };

     

       4
       4
       +
       in

     

       5
       5
       +
       {

     

       6
       6
       +
         options.foo = lib.mkOption {

     

       7
       7
       +
           type = lib.types.submodule { };

     

       8
       8
       +
           default = { };

     

       9
       9
       +
         };

     

       10
       10
       +
         config.foo =

     

       11
       11
       +
           { ... }:

     

       12
       12
       +
           {

     

       13
       13
       +
             imports = [

     

       14
       14
       +
               # error, like `import-configuration.nix`, but in a submodule this time

     

       15
       15
       +
               myconf

     

       16
       16
       +
             ];

     

       17
       17
       +
           };

     

       18
       18
       +
       }

+17

lib/tests/modules/prefix-module-argument.nix

···

       1
       1
       +
       { lib, ... }:

     

       2
       2
       +
       {

     

       3
       3
       +
         options.foo = lib.mkOption {

     

       4
       4
       +
           type = lib.types.submodule { };

     

       5
       5
       +
           default = { };

     

       6
       6
       +
         };

     

       7
       7
       +
       

     

       8
       8
       +
         config = {

     

       9
       9
       +
           foo =

     

       10
       10
       +
             { _prefix, ... }:

     

       11
       11
       +
             assert _prefix == [ "foo" ];

     

       12
       12
       +
             {

     

       13
       13
       +
               options.ok = lib.mkOption { };

     

       14
       14
       +
               config.ok = true;

     

       15
       15
       +
             };

     

       16
       16
       +
         };

     

       17
       17
       +
       }