diff options
Diffstat (limited to 'doc/module-system')
-rw-r--r-- | doc/module-system/module-system.chapter.md | 46 |
1 files changed, 30 insertions, 16 deletions
diff --git a/doc/module-system/module-system.chapter.md b/doc/module-system/module-system.chapter.md index 34214a85148ac..2f19096577fd8 100644 --- a/doc/module-system/module-system.chapter.md +++ b/doc/module-system/module-system.chapter.md @@ -6,34 +6,39 @@ The module system is a language for handling configuration, implemented as a Nix Compared to plain Nix, it adds documentation, type checking and composition or extensibility. -NOTE: 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. +::: {.note} +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. +::: + ## `lib.evalModules` {#module-system-lib-evalModules} -Evaluate a set of modules. The result is a set with the attributes: +Evaluate a set of modules. This function is typically only used once per application (e.g. once in NixOS, once in Home Manager, ...). ### Parameters {#module-system-lib-evalModules-parameters} #### `modules` {#module-system-lib-evalModules-param-modules} -A list of modules. These are merged together using various methods to form the final configuration. +A list of modules. These are merged together to form the final configuration. +<!-- TODO link to section about merging, TBD --> #### `specialArgs` {#module-system-lib-evalModules-param-specialArgs} An attribute set of module arguments that can be used in `imports`. -This is in contrast to `config._module.args`, which is only available within the module fixpoint, which does not exist before all imports are resolved. +This is in contrast to `config._module.args`, which is only available after all `imports` have been resolved. #### `specialArgs.class` {#module-system-lib-evalModules-param-specialArgs-class} -If the `class` attribute is set in `specialArgs`, the module system will rejected modules with a different `class`. +If the `class` attribute is set in `specialArgs`, the module system will reject modules with a different `class`. -This improves the error message that users will encounter when they import an incompatible module that was designed for a different class of configurations. +The `class` value should be in lower [camel case](https://en.wikipedia.org/wiki/Camel_case). -The `class` value should be in camelcase, and, if applicable, it should match the prefix of the attributes used in (experimental) flakes. Some examples are: +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: - - `nixos`: NixOS modules + - `nixos` as in `flake.nixosModules` - `nixosTest`: modules that constitute a [NixOS VM test](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests) +<!-- We've only just started with `class`. You're invited to add a few more. --> #### `prefix` {#module-system-lib-evalModules-param-prefix} @@ -41,29 +46,38 @@ A list of strings representing the location at or below which all options are ev ### Return value {#module-system-lib-evalModules-return-value} +The result is an attribute set with the following attributes: + #### `options` {#module-system-lib-evalModules-return-value-options} -The nested set of all option declarations. +The nested attribute set of all option declarations. #### `config` {#module-system-lib-evalModules-return-value-config} -The nested set of all option values. +The nested attribute set of all option values. #### `type` {#module-system-lib-evalModules-return-value-type} -A module system type representing the module set as a submodule, to be extended by configuration from the containing module set. +A module system type. This type is an instance of `types.submoduleWith` containing the current [`modules`](#module-system-lib-evalModules-param-modules). + +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). -This is also available as the module argument `moduleType`. +However, the value returned from the type is just the [`config`](#module-system-lib-evalModules-return-value-config), like any submodule. + +This type is also available to the [`modules`](#module-system-lib-evalModules-param-modules) as the module argument `moduleType`. #### `extendModules` {#module-system-lib-evalModules-return-value-extendModules} -A function similar to `evalModules` but building on top of the module set. Its arguments, `modules` and `specialArgs` are added to the existing values. +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. + +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. -Using `extendModules` a few times has no performance impact as long as you only reference the final `options` and `config`. -If you do reference multiple `config` (or `options`) from before and after `extendModules`, performance is the same as with multiple `evalModules` invocations, because the new modules' ability to override existing configuration fundamentally requires a new fixpoint to be constructed. +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. -This is also available as a module argument. +This functionality is also available to modules as the `extendModules` module argument. #### `_module` {#module-system-lib-evalModules-return-value-_module} A portion of the configuration tree which is elided from `config`. It contains some values that are mostly internal to the module system implementation. + +<!-- TODO: when markdown migration is complete, make _module docs visible again and reference _module docs. Maybe move those docs into this chapter? --> |