commit 216315c6c47cd94070e02e57e53931864ffe05ea · pyrox.dev/nixpkgs

+4 -1

doc/doc-support/default.nix

···

       45
       45
        
         # NB: This file describes the Nixpkgs manual, which happens to use module

     

       46
       46
        
         #     docs infra originally developed for NixOS.

     

       47
       47
        
         optionsDoc = pkgs.nixosOptionsDoc {

     

       48
       48
       -
           inherit (pkgs.lib.evalModules { modules = [ ../../pkgs/top-level/config.nix ]; }) options;

     

       48
       48
       +
           inherit (pkgs.lib.evalModules {

     

       49
       49
       +
             modules = [ ../../pkgs/top-level/config.nix ];

     

       50
       50
       +
             class = "nixpkgsConfig";

     

       51
       51
       +
           }) options;

     

       49
       52
        
           documentType = "none";

     

       50
       53
        
           transformOptions = opt:

     

       51
       54
        
             opt // {

doc/manual.xml

···

       12
       12
        
         <xi:include href="using/configuration.chapter.xml" />

     

       13
       13
        
         <xi:include href="using/overlays.chapter.xml" />

     

       14
       14
        
         <xi:include href="using/overrides.chapter.xml" />

     

       15
       15
       +
        </part>

     

       16
       16
       +
        <part>

     

       17
       17
       +
         <title>Nixpkgs <code>lib</code></title>

     

       15
       18
        
         <xi:include href="functions.xml" />

     

       19
       19
       +
         <xi:include href="module-system/module-system.chapter.xml" />

     

       16
       20
        
        </part>

     

       17
       21
        
        <part xml:id="part-stdenv">

     

       18
       22
        
         <title>Standard environment</title>

+105

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

···

       1
       1
       +
       # Module System {#module-system}

     

       2
       2
       +
       

     

       3
       3
       +
       ## Introduction {#module-system-introduction}

     

       4
       4
       +
       

     

       5
       5
       +
       The module system is a language for handling configuration, implemented as a Nix library.

     

       6
       6
       +
       

     

       7
       7
       +
       Compared to plain Nix, it adds documentation, type checking and composition or extensibility.

     

       8
       8
       +
       

     

       9
       9
       +
       ::: {.note}

     

       10
       10
       +
       This chapter is new and not complete yet. For a gentle introduction to the module system, in the context of NixOS, see [Writing NixOS Modules](https://nixos.org/manual/nixos/unstable/index.html#sec-writing-modules) in the NixOS manual.

     

       11
       11
       +
       :::

     

       12
       12
       +
       

     

       13
       13
       +
       

     

       14
       14
       +
       ## `lib.evalModules` {#module-system-lib-evalModules}

     

       15
       15
       +
       

     

       16
       16
       +
       Evaluate a set of modules. This function is typically only used once per application (e.g. once in NixOS, once in Home Manager, ...).

     

       17
       17
       +
       

     

       18
       18
       +
       ### Parameters {#module-system-lib-evalModules-parameters}

     

       19
       19
       +
       

     

       20
       20
       +
       #### `modules` {#module-system-lib-evalModules-param-modules}

     

       21
       21
       +
       

     

       22
       22
       +
       A list of modules. These are merged together to form the final configuration.

     

       23
       23
       +
       <!-- TODO link to section about merging, TBD -->

     

       24
       24
       +
       

     

       25
       25
       +
       #### `specialArgs` {#module-system-lib-evalModules-param-specialArgs}

     

       26
       26
       +
       

     

       27
       27
       +
       An attribute set of module arguments that can be used in `imports`.

     

       28
       28
       +
       

     

       29
       29
       +
       This is in contrast to `config._module.args`, which is only available after all `imports` have been resolved.

     

       30
       30
       +
       

     

       31
       31
       +
       #### `class` {#module-system-lib-evalModules-param-class}

     

       32
       32
       +
       

     

       33
       33
       +
       If the `class` attribute is set and non-`null`, the module system will reject `imports` with a different `_class` declaration.

     

       34
       34
       +
       

     

       35
       35
       +
       The `class` value should be a string in lower [camel case](https://en.wikipedia.org/wiki/Camel_case).

     

       36
       36
       +
       

     

       37
       37
       +
       If applicable, the `class` should match the "prefix" of the attributes used in (experimental) [flakes](https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#description). Some examples are:

     

       38
       38
       +
       

     

       39
       39
       +
        - `nixos` as in `flake.nixosModules`

     

       40
       40
       +
        - `nixosTest`: modules that constitute a [NixOS VM test](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests)

     

       41
       41
       +
       <!-- We've only just started with `class`. You're invited to add a few more. -->

     

       42
       42
       +
       

     

       43
       43
       +
       #### `prefix` {#module-system-lib-evalModules-param-prefix}

     

       44
       44
       +
       

     

       45
       45
       +
       A list of strings representing the location at or below which all options are evaluated. This is used by `types.submodule` to improve error reporting and find the implicit `name` module argument.

     

       46
       46
       +
       

     

       47
       47
       +
       ### Return value {#module-system-lib-evalModules-return-value}

     

       48
       48
       +
       

     

       49
       49
       +
       The result is an attribute set with the following attributes:

     

       50
       50
       +
       

     

       51
       51
       +
       #### `options` {#module-system-lib-evalModules-return-value-options}

     

       52
       52
       +
       

     

       53
       53
       +
       The nested attribute set of all option declarations.

     

       54
       54
       +
       

     

       55
       55
       +
       #### `config` {#module-system-lib-evalModules-return-value-config}

     

       56
       56
       +
       

     

       57
       57
       +
       The nested attribute set of all option values.

     

       58
       58
       +
       

     

       59
       59
       +
       #### `type` {#module-system-lib-evalModules-return-value-type}

     

       60
       60
       +
       

     

       61
       61
       +
       A module system type. This type is an instance of `types.submoduleWith` containing the current [`modules`](#module-system-lib-evalModules-param-modules).

     

       62
       62
       +
       

     

       63
       63
       +
       The option definitions that are typed with this type will extend the current set of modules, like [`extendModules`](#module-system-lib-evalModules-return-value-extendModules).

     

       64
       64
       +
       

     

       65
       65
       +
       However, the value returned from the type is just the [`config`](#module-system-lib-evalModules-return-value-config), like any submodule.

     

       66
       66
       +
       

     

       67
       67
       +
       If you're familiar with prototype inheritance, you can think of this `evalModules` invocation as the prototype, and usages of this type as the instances.

     

       68
       68
       +
       

     

       69
       69
       +
       This type is also available to the [`modules`](#module-system-lib-evalModules-param-modules) as the module argument `moduleType`.

     

       70
       70
       +
       <!-- TODO: document the module arguments. Using moduleType is like saying: suppose this configuration was extended. -->

     

       71
       71
       +
       

     

       72
       72
       +
       #### `extendModules` {#module-system-lib-evalModules-return-value-extendModules}

     

       73
       73
       +
       

     

       74
       74
       +
       A function similar to `evalModules` but building on top of the already passed [`modules`](#module-system-lib-evalModules-param-modules). Its arguments, `modules` and `specialArgs` are added to the existing values.

     

       75
       75
       +
       

     

       76
       76
       +
       If you're familiar with prototype inheritance, you can think of the current, actual `evalModules` invocation as the prototype, and the return value of `extendModules` as the instance.

     

       77
       77
       +
       

     

       78
       78
       +
       This functionality is also available to modules as the `extendModules` module argument.

     

       79
       79
       +
       

     

       80
       80
       +
       ::: {.note}

     

       81
       81
       +
       

     

       82
       82
       +
       **Evaluation Performance**

     

       83
       83
       +
       

     

       84
       84
       +
       `extendModules` returns a configuration that shares very little with the original `evalModules` invocation, because the module arguments may be different.

     

       85
       85
       +
       

     

       86
       86
       +
       So if you have a configuration that has been (or will be) largely evaluated, almost none of the computation is shared with the configuration returned by `extendModules`.

     

       87
       87
       +
       

     

       88
       88
       +
       The real work of module evaluation happens while computing the values in `config` and `options`, so multiple invocations of `extendModules` have a particularly small cost, as long as only the final `config` and `options` are evaluated.

     

       89
       89
       +
       

     

       90
       90
       +
       If you do reference multiple `config` (or `options`) from before and after `extendModules`, evaluation performance is the same as with multiple `evalModules` invocations, because the new modules' ability to override existing configuration fundamentally requires constructing a new `config` and `options` fixpoint.

     

       91
       91
       +
       :::

     

       92
       92
       +
       

     

       93
       93
       +
       #### `_module` {#module-system-lib-evalModules-return-value-_module}

     

       94
       94
       +
       

     

       95
       95
       +
       A portion of the configuration tree which is elided from `config`.

     

       96
       96
       +
       

     

       97
       97
       +
       <!-- TODO: when markdown migration is complete, make _module docs visible again and reference _module docs. Maybe move those docs into this chapter? -->

     

       98
       98
       +
       

     

       99
       99
       +
       #### `_type` {#module-system-lib-evalModules-return-value-_type}

     

       100
       100
       +
       

     

       101
       101
       +
       A nominal type marker, always `"configuration"`.

     

       102
       102
       +
       

     

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

     

       104
       104
       +
       

     

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

+113 -47

lib/modules.nix

···

       63
       63
        
                 decls

     

       64
       64
        
             ));

     

       65
       65
        
       

     

       66
       66
       -
       in

     

       67
       67
       -
       

     

       68
       68
       -
       rec {

     

       69
       69
       -
       

     

       70
       70
       -
         /*

     

       71
       71
       -
           Evaluate a set of modules.  The result is a set with the attributes:

     

       72
       72
       -
       

     

       73
       73
       -
             ‘options’: The nested set of all option declarations,

     

       74
       74
       -
       

     

       75
       75
       -
             ‘config’: The nested set of all option values.

     

       76
       76
       -
       

     

       77
       77
       -
             ‘type’: A module system type representing the module set as a submodule,

     

       78
       78
       -
                   to be extended by configuration from the containing module set.

     

       79
       79
       -
       

     

       80
       80
       -
                   This is also available as the module argument ‘moduleType’.

     

       81
       81
       -
       

     

       82
       82
       -
             ‘extendModules’: A function similar to ‘evalModules’ but building on top

     

       83
       83
       -
                   of the module set. Its arguments, ‘modules’ and ‘specialArgs’ are

     

       84
       84
       -
                   added to the existing values.

     

       85
       85
       -
       

     

       86
       86
       -
                   Using ‘extendModules’ a few times has no performance impact as long

     

       87
       87
       -
                   as you only reference the final ‘options’ and ‘config’.

     

       88
       88
       -
                   If you do reference multiple ‘config’ (or ‘options’) from before and

     

       89
       89
       -
                   after ‘extendModules’, performance is the same as with multiple

     

       90
       90
       -
                   ‘evalModules’ invocations, because the new modules' ability to

     

       91
       91
       -
                   override existing configuration fundamentally requires a new

     

       92
       92
       -
                   fixpoint to be constructed.

     

       93
       93
       -
       

     

       94
       94
       -
                   This is also available as a module argument.

     

       95
       95
       -
       

     

       96
       96
       -
             ‘_module’: A portion of the configuration tree which is elided from

     

       97
       97
       -
                   ‘config’. It contains some values that are mostly internal to the

     

       98
       98
       -
                   module system implementation.

     

       66
       66
       +
         /* See https://nixos.org/manual/nixpkgs/unstable/#module-system-lib-evalModules

     

       67
       67
       +
            or file://./../doc/module-system/module-system.chapter.md

     

       99
       68
        
       

     

       100
       69
        
            !!! Please think twice before adding to this argument list! The more

     

       101
       70
        
            that is specified here instead of in the modules themselves the harder

     
···

       110
       79
        
                         # there's _module.args. If specialArgs.modulesPath is defined it will be

     

       111
       80
        
                         # used as the base path for disabledModules.

     

       112
       81
        
                         specialArgs ? {}

     

       113
       113
       -
                       , # This would be remove in the future, Prefer _module.args option instead.

     

       114
       114
       -
                         args ? {}

     

       82
       82
       +
                       , # `class`:

     

       83
       83
       +
                         # A nominal type for modules. When set and non-null, this adds a check to

     

       84
       84
       +
                         # make sure that only compatible modules are imported.

     

       85
       85
       +
                         # This would be remove in the future, Prefer _module.args option instead.

     

       86
       86
       +
                         class ? null

     

       87
       87
       +
                       , args ? {}

     

       115
       88
        
                       , # This would be remove in the future, Prefer _module.check option instead.

     

       116
       89
        
                         check ? true

     

       117
       90
        
                       }:

     
···

       260
       233
        
       

     

       261
       234
        
             merged =

     

       262
       235
        
               let collected = collectModules

     

       236
       236
       +
                 class

     

       263
       237
        
                 (specialArgs.modulesPath or "")

     

       264
       238
        
                 (regularModules ++ [ internalModule ])

     

       265
       239
        
                 ({ inherit lib options config specialArgs; } // specialArgs);

     
···

       336
       310
        
               prefix ? [],

     

       337
       311
        
               }:

     

       338
       312
        
                 evalModules (evalModulesArgs // {

     

       313
       313
       +
                   inherit class;

     

       339
       314
        
                   modules = regularModules ++ modules;

     

       340
       315
        
                   specialArgs = evalModulesArgs.specialArgs or {} // specialArgs;

     

       341
       316
        
                   prefix = extendArgs.prefix or evalModulesArgs.prefix or [];

     

       342
       317
        
                 });

     

       343
       318
        
       

     

       344
       319
        
             type = lib.types.submoduleWith {

     

       345
       345
       -
               inherit modules specialArgs;

     

       320
       320
       +
               inherit modules specialArgs class;

     

       346
       321
        
             };

     

       347
       322
        
       

     

       348
       323
        
             result = withWarnings {

     

       324
       324
       +
               _type = "configuration";

     

       349
       325
        
               options = checked options;

     

       350
       326
        
               config = checked (removeAttrs config [ "_module" ]);

     

       351
       327
        
               _module = checked (config._module);

     

       352
       328
        
               inherit extendModules type;

     

       329
       329
       +
               class = class;

     

       353
       330
        
             };

     

       354
       331
        
           in result;

     

       355
       332
        
       

     

       356
       356
       -
         # collectModules :: (modulesPath: String) -> (modules: [ Module ]) -> (args: Attrs) -> [ Module ]

     

       333
       333
       +
         # collectModules :: (class: String) -> (modulesPath: String) -> (modules: [ Module ]) -> (args: Attrs) -> [ Module ]

     

       357
       334
        
         #

     

       358
       335
        
         # Collects all modules recursively through `import` statements, filtering out

     

       359
       336
        
         # all modules in disabledModules.

     

       360
       360
       -
         collectModules = let

     

       337
       337
       +
         collectModules = class: let

     

       361
       338
        
       

     

       362
       339
        
             # Like unifyModuleSyntax, but also imports paths and calls functions if necessary

     

       363
       340
        
             loadModule = args: fallbackFile: fallbackKey: m:

     

       364
       364
       -
               if isFunction m || isAttrs m then

     

       365
       365
       -
                 unifyModuleSyntax fallbackFile fallbackKey (applyModuleArgsIfFunction fallbackKey m args)

     

       341
       341
       +
               if isFunction m then

     

       342
       342
       +
                 unifyModuleSyntax fallbackFile fallbackKey (applyModuleArgs fallbackKey m args)

     

       343
       343
       +
               else if isAttrs m then

     

       344
       344
       +
                 if m._type or "module" == "module" then

     

       345
       345
       +
                   unifyModuleSyntax fallbackFile fallbackKey m

     

       346
       346
       +
                 else if m._type == "if" || m._type == "override" then

     

       347
       347
       +
                   loadModule args fallbackFile fallbackKey { config = m; }

     

       348
       348
       +
                 else

     

       349
       349
       +
                   throw (

     

       350
       350
       +
                     "Could not load a value as a module, because it is of type ${lib.strings.escapeNixString m._type}"

     

       351
       351
       +
                     + lib.optionalString (fallbackFile != unknownModule) ", in file ${toString fallbackFile}."

     

       352
       352
       +
                     + lib.optionalString (m._type == "configuration") " If you do intend to import this configuration, please only import the modules that make up the configuration. You may have to create a `let` binding, file or attribute to give yourself access to the relevant modules.\nWhile loading a configuration into the module system is a very sensible idea, it can not be done cleanly in practice."

     

       353
       353
       +
                      # Extended explanation: That's because a finalized configuration is more than just a set of modules. For instance, it has its own `specialArgs` that, by the nature of `specialArgs` can't be loaded through `imports` or the the `modules` argument. So instead, we have to ask you to extract the relevant modules and use those instead. This way, we keep the module system comparatively simple, and hopefully avoid a bad surprise down the line.

     

       354
       354
       +
                   )

     

       366
       355
        
               else if isList m then

     

       367
       356
        
                 let defs = [{ file = fallbackFile; value = m; }]; in

     

       368
       357
        
                 throw "Module imports can't be nested lists. Perhaps you meant to remove one level of lists? Definitions: ${showDefs defs}"

     

       369
       358
        
               else unifyModuleSyntax (toString m) (toString m) (applyModuleArgsIfFunction (toString m) (import m) args);

     

       370
       359
        
       

     

       360
       360
       +
             checkModule =

     

       361
       361
       +
               if class != null

     

       362
       362
       +
               then

     

       363
       363
       +
                 m:

     

       364
       364
       +
                   if m._class != null -> m._class == class

     

       365
       365
       +
                   then m

     

       366
       366
       +
                   else

     

       367
       367
       +
                     throw "The module ${m._file or m.key} was imported into ${class} instead of ${m._class}."

     

       368
       368
       +
               else

     

       369
       369
       +
                 m: m;

     

       370
       370
       +
       

     

       371
       371
        
             /*

     

       372
       372
        
             Collects all modules recursively into the form

     

       373
       373
        
       

     
···

       401
       401
        
                 };

     

       402
       402
        
               in parentFile: parentKey: initialModules: args: collectResults (imap1 (n: x:

     

       403
       403
        
                 let

     

       404
       404
       -
                   module = loadModule args parentFile "${parentKey}:anon-${toString n}" x;

     

       404
       404
       +
                   module = checkModule (loadModule args parentFile "${parentKey}:anon-${toString n}" x);

     

       405
       405
        
                   collectedImports = collectStructuredModules module._file module.key module.imports args;

     

       406
       406
        
                 in {

     

       407
       407
        
                   key = module.key;

     
···

       465
       465
        
               else config;

     

       466
       466
        
           in

     

       467
       467
        
           if m ? config || m ? options then

     

       468
       468
       -
             let badAttrs = removeAttrs m ["_file" "key" "disabledModules" "imports" "options" "config" "meta" "freeformType"]; in

     

       468
       468
       +
             let badAttrs = removeAttrs m ["_class" "_file" "key" "disabledModules" "imports" "options" "config" "meta" "freeformType"]; in

     

       469
       469
        
             if badAttrs != {} then

     

       470
       470
        
               throw "Module `${key}' has an unsupported attribute `${head (attrNames badAttrs)}'. This is caused by introducing a top-level `config' or `options' attribute. Add configuration attributes immediately on the top level instead, or move all of them (namely: ${toString (attrNames badAttrs)}) into the explicit `config' attribute."

     

       471
       471
        
             else

     

       472
       472
        
               { _file = toString m._file or file;

     

       473
       473
       +
                 _class = m._class or null;

     

       473
       474
        
                 key = toString m.key or key;

     

       474
       475
        
                 disabledModules = m.disabledModules or [];

     

       475
       476
        
                 imports = m.imports or [];

     
···

       480
       481
        
             # shorthand syntax

     

       481
       482
        
             lib.throwIfNot (isAttrs m) "module ${file} (${key}) does not look like a module."

     

       482
       483
        
             { _file = toString m._file or file;

     

       484
       484
       +
               _class = m._class or null;

     

       483
       485
        
               key = toString m.key or key;

     

       484
       486
        
               disabledModules = m.disabledModules or [];

     

       485
       487
        
               imports = m.require or [] ++ m.imports or [];

     

       486
       488
        
               options = {};

     

       487
       487
       -
               config = addFreeformType (removeAttrs m ["_file" "key" "disabledModules" "require" "imports" "freeformType"]);

     

       489
       489
       +
               config = addFreeformType (removeAttrs m ["_class" "_file" "key" "disabledModules" "require" "imports" "freeformType"]);

     

       488
       490
        
             };

     

       489
       491
        
       

     

       490
       490
       -
         applyModuleArgsIfFunction = key: f: args@{ config, options, lib, ... }: if isFunction f then

     

       492
       492
       +
         applyModuleArgsIfFunction = key: f: args@{ config, options, lib, ... }:

     

       493
       493
       +
           if isFunction f then applyModuleArgs key f args else f;

     

       494
       494
       +
       

     

       495
       495
       +
         applyModuleArgs = key: f: args@{ config, options, lib, ... }:

     

       491
       496
        
           let

     

       492
       497
        
             # Module arguments are resolved in a strict manner when attribute set

     

       493
       498
        
             # deconstruction is used.  As the arguments are now defined with the

     
···

       511
       516
        
             # context on the explicit arguments of "args" too. This update

     

       512
       517
        
             # operator is used to make the "args@{ ... }: with args.lib;" notation

     

       513
       518
        
             # works.

     

       514
       514
       -
           in f (args // extraArgs)

     

       515
       515
       -
         else

     

       516
       516
       -
           f;

     

       519
       519
       +
           in f (args // extraArgs);

     

       517
       520
        
       

     

       518
       521
        
         /* Merge a list of modules.  This will recurse over the option

     

       519
       522
        
            declarations in all modules, combining them into a single set.

     
···

       1218
       1221
        
           _file = file;

     

       1219
       1222
        
           config = lib.importTOML file;

     

       1220
       1223
        
         };

     

       1224
       1224
       +
       

     

       1225
       1225
       +
         private = lib.mapAttrs

     

       1226
       1226
       +
           (k: lib.warn "External use of `lib.modules.${k}` is deprecated. If your use case isn't covered by non-deprecated functions, we'd like to know more and perhaps support your use case well, instead of providing access to these low level functions. In this case please open an issue in https://github.com/nixos/nixpkgs/issues/.")

     

       1227
       1227
       +
           {

     

       1228
       1228
       +
             inherit

     

       1229
       1229
       +
               applyModuleArgsIfFunction

     

       1230
       1230
       +
               dischargeProperties

     

       1231
       1231
       +
               evalOptionValue

     

       1232
       1232
       +
               mergeModules

     

       1233
       1233
       +
               mergeModules'

     

       1234
       1234
       +
               pushDownProperties

     

       1235
       1235
       +
               unifyModuleSyntax

     

       1236
       1236
       +
               ;

     

       1237
       1237
       +
             collectModules = collectModules null;

     

       1238
       1238
       +
           };

     

       1239
       1239
       +
       

     

       1240
       1240
       +
       in

     

       1241
       1241
       +
       private //

     

       1242
       1242
       +
       {

     

       1243
       1243
       +
         # NOTE: not all of these functions are necessarily public interfaces; some

     

       1244
       1244
       +
         #       are just needed by types.nix, but are not meant to be consumed

     

       1245
       1245
       +
         #       externally.

     

       1246
       1246
       +
         inherit

     

       1247
       1247
       +
           defaultOrderPriority

     

       1248
       1248
       +
           defaultOverridePriority

     

       1249
       1249
       +
           defaultPriority

     

       1250
       1250
       +
           doRename

     

       1251
       1251
       +
           evalModules

     

       1252
       1252
       +
           filterOverrides

     

       1253
       1253
       +
           filterOverrides'

     

       1254
       1254
       +
           fixMergeModules

     

       1255
       1255
       +
           fixupOptionType  # should be private?

     

       1256
       1256
       +
           importJSON

     

       1257
       1257
       +
           importTOML

     

       1258
       1258
       +
           mergeDefinitions

     

       1259
       1259
       +
           mergeOptionDecls  # should be private?

     

       1260
       1260
       +
           mkAfter

     

       1261
       1261
       +
           mkAliasAndWrapDefinitions

     

       1262
       1262
       +
           mkAliasAndWrapDefsWithPriority

     

       1263
       1263
       +
           mkAliasDefinitions

     

       1264
       1264
       +
           mkAliasIfDef

     

       1265
       1265
       +
           mkAliasOptionModule

     

       1266
       1266
       +
           mkAliasOptionModuleMD

     

       1267
       1267
       +
           mkAssert

     

       1268
       1268
       +
           mkBefore

     

       1269
       1269
       +
           mkChangedOptionModule

     

       1270
       1270
       +
           mkDefault

     

       1271
       1271
       +
           mkDerivedConfig

     

       1272
       1272
       +
           mkFixStrictness

     

       1273
       1273
       +
           mkForce

     

       1274
       1274
       +
           mkIf

     

       1275
       1275
       +
           mkImageMediaOverride

     

       1276
       1276
       +
           mkMerge

     

       1277
       1277
       +
           mkMergedOptionModule

     

       1278
       1278
       +
           mkOptionDefault

     

       1279
       1279
       +
           mkOrder

     

       1280
       1280
       +
           mkOverride

     

       1281
       1281
       +
           mkRemovedOptionModule

     

       1282
       1282
       +
           mkRenamedOptionModule

     

       1283
       1283
       +
           mkRenamedOptionModuleWith

     

       1284
       1284
       +
           mkVMOverride

     

       1285
       1285
       +
           setDefaultModuleLocation

     

       1286
       1286
       +
           sortProperties;

     

       1221
       1287
        
       }

+21

lib/tests/modules.sh

···

       166
       166
        
       checkConfigOutput '^true$' "$@" ./define-module-check.nix

     

       167
       167
        
       

     

       168
       168
        
       # Check coerced value.

     

       169
       169
       +
       set --

     

       169
       170
        
       checkConfigOutput '^"42"$' config.value ./declare-coerced-value.nix

     

       170
       171
        
       checkConfigOutput '^"24"$' config.value ./declare-coerced-value.nix ./define-value-string.nix

     

       171
       172
        
       checkConfigError 'A definition for option .* is not.*string or signed integer convertible to it.*. Definition values:\n\s*- In .*: \[ \]' config.value ./declare-coerced-value.nix ./define-value-list.nix

     
···

       254
       255
        
       ## Freeform modules

     

       255
       256
        
       # Assigning without a declared option should work

     

       256
       257
        
       checkConfigOutput '^"24"$' config.value ./freeform-attrsOf.nix ./define-value-string.nix

     

       258
       258
       +
       # Shorthand modules interpret `meta` and `class` as config items

     

       259
       259
       +
       checkConfigOutput '^true$' options._module.args.value.result ./freeform-attrsOf.nix ./define-freeform-keywords-shorthand.nix

     

       257
       260
        
       # No freeform assignments shouldn't make it error

     

       258
       261
        
       checkConfigOutput '^{ }$' config ./freeform-attrsOf.nix

     

       259
       262
        
       # but only if the type matches

     
···

       358
       361
        
       # Anonymous submodules don't get nixed by import resolution/deduplication

     

       359
       362
        
       # because of an `extendModules` bug, issue 168767.

     

       360
       363
        
       checkConfigOutput '^1$' config.sub.specialisation.value ./extendModules-168767-imports.nix

     

       364
       364
       +
       

     

       365
       365
       +
       # Class checks, evalModules

     

       366
       366
       +
       checkConfigOutput '^{ }$' config.ok.config ./class-check.nix

     

       367
       367
       +
       checkConfigOutput '"nixos"' config.ok.class ./class-check.nix

     

       368
       368
       +
       checkConfigError 'The module .*/module-class-is-darwin.nix was imported into nixos instead of darwin.' config.fail.config ./class-check.nix

     

       369
       369
       +
       checkConfigError 'The module foo.nix#darwinModules.default was imported into nixos instead of darwin.' config.fail-anon.config ./class-check.nix

     

       370
       370
       +
       

     

       371
       371
       +
       # Class checks, submoduleWith

     

       372
       372
       +
       checkConfigOutput '^{ }$' config.sub.nixosOk ./class-check.nix

     

       373
       373
       +
       checkConfigError 'The module .*/module-class-is-darwin.nix was imported into nixos instead of darwin.' config.sub.nixosFail.config ./class-check.nix

     

       374
       374
       +
       

     

       375
       375
       +
       # submoduleWith type merge with different class

     

       376
       376
       +
       checkConfigError 'error: A submoduleWith option is declared multiple times with conflicting class values "darwin" and "nixos".' config.sub.mergeFail.config ./class-check.nix

     

       377
       377
       +
       

     

       378
       378
       +
       # _type check

     

       379
       379
       +
       checkConfigError 'Could not load a value as a module, because it is of type "flake", in file .*/module-imports-_type-check.nix' config.ok.config ./module-imports-_type-check.nix

     

       380
       380
       +
       checkConfigOutput '^true$' "$@" config.enable ./declare-enable.nix ./define-enable-with-top-level-mkIf.nix

     

       381
       381
       +
       checkConfigError 'Could not load a value as a module, because it is of type "configuration", in file .*/import-configuration.nix.*please only import the modules that make up the configuration.*' config ./import-configuration.nix

     

       361
       382
        
       

     

       362
       383
        
       # doRename works when `warnings` does not exist.

     

       363
       384
        
       checkConfigOutput '^1234$' config.c.d.e ./doRename-basic.nix

+76

lib/tests/modules/class-check.nix

···

       1
       1
       +
       { lib, ... }: {

     

       2
       2
       +
         options = {

     

       3
       3
       +
           sub = {

     

       4
       4
       +
             nixosOk = lib.mkOption {

     

       5
       5
       +
               type = lib.types.submoduleWith {

     

       6
       6
       +
                 class = "nixos";

     

       7
       7
       +
                 modules = [ ];

     

       8
       8
       +
               };

     

       9
       9
       +
             };

     

       10
       10
       +
             # Same but will have bad definition

     

       11
       11
       +
             nixosFail = lib.mkOption {

     

       12
       12
       +
               type = lib.types.submoduleWith {

     

       13
       13
       +
                 class = "nixos";

     

       14
       14
       +
                 modules = [ ];

     

       15
       15
       +
               };

     

       16
       16
       +
             };

     

       17
       17
       +
       

     

       18
       18
       +
             mergeFail = lib.mkOption {

     

       19
       19
       +
               type = lib.types.submoduleWith {

     

       20
       20
       +
                 class = "nixos";

     

       21
       21
       +
                 modules = [ ];

     

       22
       22
       +
               };

     

       23
       23
       +
               default = { };

     

       24
       24
       +
             };

     

       25
       25
       +
           };

     

       26
       26
       +
         };

     

       27
       27
       +
         imports = [

     

       28
       28
       +
           {

     

       29
       29
       +
             options = {

     

       30
       30
       +
               sub = {

     

       31
       31
       +
                 mergeFail = lib.mkOption {

     

       32
       32
       +
                   type = lib.types.submoduleWith {

     

       33
       33
       +
                     class = "darwin";

     

       34
       34
       +
                     modules = [ ];

     

       35
       35
       +
                   };

     

       36
       36
       +
                 };

     

       37
       37
       +
               };

     

       38
       38
       +
             };

     

       39
       39
       +
           }

     

       40
       40
       +
         ];

     

       41
       41
       +
         config = {

     

       42
       42
       +
           _module.freeformType = lib.types.anything;

     

       43
       43
       +
           ok =

     

       44
       44
       +
             lib.evalModules {

     

       45
       45
       +
               class = "nixos";

     

       46
       46
       +
               modules = [

     

       47
       47
       +
                 ./module-class-is-nixos.nix

     

       48
       48
       +
               ];

     

       49
       49
       +
             };

     

       50
       50
       +
       

     

       51
       51
       +
           fail =

     

       52
       52
       +
             lib.evalModules {

     

       53
       53
       +
               class = "nixos";

     

       54
       54
       +
               modules = [

     

       55
       55
       +
                 ./module-class-is-nixos.nix

     

       56
       56
       +
                 ./module-class-is-darwin.nix

     

       57
       57
       +
               ];

     

       58
       58
       +
             };

     

       59
       59
       +
       

     

       60
       60
       +
           fail-anon =

     

       61
       61
       +
             lib.evalModules {

     

       62
       62
       +
               class = "nixos";

     

       63
       63
       +
               modules = [

     

       64
       64
       +
                 ./module-class-is-nixos.nix

     

       65
       65
       +
                 { _file = "foo.nix#darwinModules.default";

     

       66
       66
       +
                   _class = "darwin";

     

       67
       67
       +
                   config = {};

     

       68
       68
       +
                   imports = [];

     

       69
       69
       +
                 }

     

       70
       70
       +
               ];

     

       71
       71
       +
             };

     

       72
       72
       +
       

     

       73
       73
       +
           sub.nixosOk = { _class = "nixos"; };

     

       74
       74
       +
           sub.nixosFail = { imports = [ ./module-class-is-darwin.nix ]; };

     

       75
       75
       +
         };

     

       76
       76
       +
       }

lib/tests/modules/define-enable-with-top-level-mkIf.nix

···

       1
       1
       +
       { lib, ... }:

     

       2
       2
       +
       # I think this might occur more realistically in a submodule

     

       3
       3
       +
       {

     

       4
       4
       +
         imports = [ (lib.mkIf true { enable = true; }) ];

     

       5
       5
       +
       }

+15

lib/tests/modules/define-freeform-keywords-shorthand.nix

···

       1
       1
       +
       { config, ... }: {

     

       2
       2
       +
         class = { "just" = "data"; };

     

       3
       3
       +
         a = "one";

     

       4
       4
       +
         b = "two";

     

       5
       5
       +
         meta = "meta";

     

       6
       6
       +
       

     

       7
       7
       +
         _module.args.result =

     

       8
       8
       +
           let r = builtins.removeAttrs config [ "_module" ];

     

       9
       9
       +
           in builtins.trace (builtins.deepSeq r r) (r == {

     

       10
       10
       +
             a = "one";

     

       11
       11
       +
             b = "two";

     

       12
       12
       +
             class = { "just" = "data"; };

     

       13
       13
       +
             meta = "meta";

     

       14
       14
       +
           });

     

       15
       15
       +
       }

+12

lib/tests/modules/import-configuration.nix

···

       1
       1
       +
       { lib, ... }:

     

       2
       2
       +
       let

     

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

     

       4
       4
       +
       in

     

       5
       5
       +
       {

     

       6
       6
       +
         imports = [

     

       7
       7
       +
           # We can't do this. A configuration is not equal to its set of a modules.

     

       8
       8
       +
           # Equating those would lead to a mess, as specialArgs, anonymous modules

     

       9
       9
       +
           # that can't be deduplicated, and possibly more come into play.

     

       10
       10
       +
           myconf

     

       11
       11
       +
         ];

     

       12
       12
       +
       }

lib/tests/modules/module-class-is-darwin.nix

···

       1
       1
       +
       {

     

       2
       2
       +
         _class = "darwin";

     

       3
       3
       +
         config = {};

     

       4
       4
       +
       }

lib/tests/modules/module-class-is-nixos.nix

···

       1
       1
       +
       {

     

       2
       2
       +
         _class = "nixos";

     

       3
       3
       +
         config = {};

     

       4
       4
       +
       }

lib/tests/modules/module-imports-_type-check.nix

···

       1
       1
       +
       {

     

       2
       2
       +
         imports = [ { _type = "flake"; } ];

     

       3
       3
       +
       }

+8 -2

lib/types.nix

···

       696
       696
        
             , specialArgs ? {}

     

       697
       697
        
             , shorthandOnlyDefinesConfig ? false

     

       698
       698
        
             , description ? null

     

       699
       699
       +
             , class ? null

     

       699
       700
        
             }@attrs:

     

       700
       701
        
             let

     

       701
       702
        
               inherit (lib.modules) evalModules;

     
···

       707
       708
        
               ) defs;

     

       708
       709
        
       

     

       709
       710
        
               base = evalModules {

     

       710
       710
       -
                 inherit specialArgs;

     

       711
       711
       +
                 inherit class specialArgs;

     

       711
       712
        
                 modules = [{

     

       712
       713
        
                   # This is a work-around for the fact that some sub-modules,

     

       713
       714
        
                   # such as the one included in an attribute set, expects an "args"

     
···

       762
       763
        
               functor = defaultFunctor name // {

     

       763
       764
        
                 type = types.submoduleWith;

     

       764
       765
        
                 payload = {

     

       765
       765
       -
                   inherit modules specialArgs shorthandOnlyDefinesConfig description;

     

       766
       766
       +
                   inherit modules class specialArgs shorthandOnlyDefinesConfig description;

     

       766
       767
        
                 };

     

       767
       768
        
                 binOp = lhs: rhs: {

     

       769
       769
       +
                   class =

     

       770
       770
       +
                     if lhs.class == null then rhs.class

     

       771
       771
       +
                     else if rhs.class == null then lhs.class

     

       772
       772
       +
                     else if lhs.class == rhs.class then lhs.class

     

       773
       773
       +
                     else throw "A submoduleWith option is declared multiple times with conflicting class values \"${toString lhs.class}\" and \"${toString rhs.class}\".";

     

       768
       774
        
                   modules = lhs.modules ++ rhs.modules;

     

       769
       775
        
                   specialArgs =

     

       770
       776
        
                     let intersecting = builtins.intersectAttrs lhs.specialArgs rhs.specialArgs;

nixos/lib/eval-cacheable-options.nix

···

       33
       33
        
           ];

     

       34
       34
        
           specialArgs = {

     

       35
       35
        
             inherit config pkgs utils;

     

       36
       36
       +
             class = "nixos";

     

       36
       37
        
           };

     

       37
       38
        
         };

     

       38
       39
        
         docs = import "${nixosPath}/doc/manual" {

nixos/lib/eval-config-minimal.nix

···

       38
       38
        
         #       is experimental.

     

       39
       39
        
         lib.evalModules {

     

       40
       40
        
           inherit prefix modules;

     

       41
       41
       +
           class = "nixos";

     

       41
       42
        
           specialArgs = {

     

       42
       43
        
             modulesPath = builtins.toString ../modules;

     

       43
       44
        
           } // specialArgs;

+4 -1

nixos/lib/testing/default.nix

···

       1
       1
        
       { lib }:

     

       2
       2
        
       let

     

       3
       3
        
       

     

       4
       4
       -
         evalTest = module: lib.evalModules { modules = testModules ++ [ module ]; };

     

       4
       4
       +
         evalTest = module: lib.evalModules {

     

       5
       5
       +
           modules = testModules ++ [ module ];

     

       6
       6
       +
           class = "nixosTest";

     

       7
       7
       +
         };

     

       5
       8
        
         runTest = module: (evalTest ({ config, ... }: { imports = [ module ]; result = config.test; })).config.result;

     

       6
       9
        
       

     

       7
       10
        
         testModules = [

nixos/modules/misc/documentation.nix

···

       38
       38
        
                 modules = [ {

     

       39
       39
        
                   _module.check = false;

     

       40
       40
        
                 } ] ++ docModules.eager;

     

       41
       41
       +
                 class = "nixos";

     

       41
       42
        
                 specialArgs = specialArgs // {

     

       42
       43
        
                   pkgs = scrubDerivations "pkgs" pkgs;

     

       43
       44
        
                   # allow access to arbitrary options for eager modules, eg for getting

pkgs/top-level/default.nix

···

       82
       82
        
               config = config1;

     

       83
       83
        
             })

     

       84
       84
        
           ];

     

       85
       85
       +
           class = "nixpkgsConfig";

     

       85
       86
        
         };

     

       86
       87
        
       

     

       87
       88
        
         # take all the rest as-is