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

   1 # Module System {#module-system}
   2
   3 ## Introduction {#module-system-introduction}
   4
   5 The module system is a language for handling configuration, implemented as a Nix library.
   6
   7 Compared to plain Nix, it adds documentation, type checking and composition or extensibility.
   8
   9 ::: {.note}
  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 :::
  12
  13
  14 ## `lib.evalModules` {#module-system-lib-evalModules}
  15
  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
  18 ### Parameters {#module-system-lib-evalModules-parameters}
  19
  20 #### `modules` {#module-system-lib-evalModules-param-modules}
  21
  22 A list of modules. These are merged together to form the final configuration.
  23 <!-- TODO link to section about merging, TBD -->
  24
  25 #### `specialArgs` {#module-system-lib-evalModules-param-specialArgs}
  26
  27 An attribute set of module arguments that can be used in `imports`.
  28
  29 This is in contrast to `config._module.args`, which is only available after all `imports` have been resolved.
  30
  31 #### `class` {#module-system-lib-evalModules-param-class}
  32
  33 If the `class` attribute is set and non-`null`, the module system will reject `imports` with a different `_class` declaration.
  34
  35 The `class` value should be a string in lower [camel case](https://en.wikipedia.org/wiki/Camel_case).
  36
  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
  39  - `nixos` as in `flake.nixosModules`
  40  - `nixosTest`: modules that constitute a [NixOS VM test](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests)
  41 <!-- We've only just started with `class`. You're invited to add a few more. -->
  42
  43 #### `prefix` {#module-system-lib-evalModules-param-prefix}
  44
  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
  47 ### Return value {#module-system-lib-evalModules-return-value}
  48
  49 The result is an attribute set with the following attributes:
  50
  51 #### `options` {#module-system-lib-evalModules-return-value-options}
  52
  53 The nested attribute set of all option declarations.
  54
  55 #### `config` {#module-system-lib-evalModules-return-value-config}
  56
  57 The nested attribute set of all option values.
  58
  59 #### `type` {#module-system-lib-evalModules-return-value-type}
  60
  61 A module system type. This type is an instance of `types.submoduleWith` containing the current [`modules`](#module-system-lib-evalModules-param-modules).
  62
  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
  65 However, the value returned from the type is just the [`config`](#module-system-lib-evalModules-return-value-config), like any submodule.
  66
  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
  69 This type is also available to the [`modules`](#module-system-lib-evalModules-param-modules) as the module argument `moduleType`.
  70 <!-- TODO: document the module arguments. Using moduleType is like saying: suppose this configuration was extended. -->
  71
  72 #### `extendModules` {#module-system-lib-evalModules-return-value-extendModules}
  73
  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
  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
  78 This functionality is also available to modules as the `extendModules` module argument.
  79
  80 ::: {.note}
  81
  82 **Evaluation Performance**
  83
  84 `extendModules` returns a configuration that shares very little with the original `evalModules` invocation, because the module arguments may be different.
  85
  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
  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
  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 :::
  92
  93 #### `_module` {#module-system-lib-evalModules-return-value-_module}
  94
  95 A portion of the configuration tree which is elided from `config`.
  96
  97 <!-- TODO: when markdown migration is complete, make _module docs visible again and reference _module docs. Maybe move those docs into this chapter? -->
  98
  99 #### `_type` {#module-system-lib-evalModules-return-value-_type}
 100
 101 A nominal type marker, always `"configuration"`.
 102
 103 #### `class` {#module-system-lib-evalModules-return-value-_configurationClass}
 104
 105 The [`class` argument](#module-system-lib-evalModules-param-class).