pyrox.dev
1# Module System {#module-system}
2
3## Introduction {#module-system-introduction}
4
5The module system is a language for handling configuration, implemented as a Nix library.
6
7Compared to plain Nix, it adds documentation, type checking and composition or extensibility.
8
9::: {.note}
10This chapter is new and not complete yet.
11
12See also:
13- 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.
14- Generic guide to the module system on [nix.dev](https://nix.dev/tutorials/module-system/index.html).
15:::
16
17## `lib.evalModules` {#module-system-lib-evalModules}
18
19Evaluate a set of modules. This function is typically only used once per application (e.g. once in NixOS, once in Home Manager, ...).
20
21### Parameters {#module-system-lib-evalModules-parameters}
22
23#### `modules` {#module-system-lib-evalModules-param-modules}
24
25A list of modules. These are merged together to form the final configuration.
26<!-- TODO link to section about merging, TBD -->
27
28#### `specialArgs` {#module-system-lib-evalModules-param-specialArgs}
29
30An attribute set of module arguments that can be used in `imports`.
31
32This is in contrast to `config._module.args`, which is only available after all `imports` have been resolved.
33
34::: {.warning}
35You may be tempted to use `specialArgs.lib` to provide extra library functions. Doing so limits the interoperability of modules, as well as the interoperability of Module System applications.
36
37`lib` is reserved for the Nixpkgs library, and should not be used for custom functions.
38
39Instead, you may create a new attribute in `specialArgs` to provide custom functions.
40This clarifies their origin and avoids incompatibilities.
41:::
42
43#### `class` {#module-system-lib-evalModules-param-class}
44
45If the `class` attribute is set and non-`null`, the module system will reject `imports` with a different `_class` declaration.
46
47The `class` value should be a string in lower [camel case](https://en.wikipedia.org/wiki/Camel_case).
48
49If 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:
50
51 - `nixos` as in `flake.nixosModules`
52 - `nixosTest`: modules that constitute a [NixOS VM test](https://nixos.org/manual/nixos/stable/index.html#sec-nixos-tests)
53<!-- We've only just started with `class`. You're invited to add a few more. -->
54
55#### `prefix` {#module-system-lib-evalModules-param-prefix}
56
57A 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.
58
59### Return value {#module-system-lib-evalModules-return-value}
60
61The result is an attribute set with the following attributes:
62
63#### `options` {#module-system-lib-evalModules-return-value-options}
64
65The nested attribute set of all option declarations.
66
67#### `config` {#module-system-lib-evalModules-return-value-config}
68
69The nested attribute set of all option values.
70
71#### `type` {#module-system-lib-evalModules-return-value-type}
72
73A module system type. This type is an instance of `types.submoduleWith` containing the current [`modules`](#module-system-lib-evalModules-param-modules).
74
75The option definitions that are typed with this type will extend the current set of modules, like [`extendModules`](#module-system-lib-evalModules-return-value-extendModules).
76
77However, the value returned from the type is just the [`config`](#module-system-lib-evalModules-return-value-config), like any submodule.
78
79If you're familiar with prototype inheritance, you can think of this `evalModules` invocation as the prototype, and usages of this type as the instances.
80
81This type is also available to the [`modules`](#module-system-lib-evalModules-param-modules) as the module argument `moduleType`.
82<!-- TODO: document the module arguments. Using moduleType is like saying: suppose this configuration was extended. -->
83
84#### `extendModules` {#module-system-lib-evalModules-return-value-extendModules}
85
86A 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.
87
88If 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.
89
90This functionality is also available to modules as the `extendModules` module argument.
91
92::: {.note}
93
94**Evaluation Performance**
95
96`extendModules` returns a configuration that shares very little with the original `evalModules` invocation, because the module arguments may be different.
97
98So 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`.
99
100The 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.
101
102If 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.
103:::
104
105#### `_module` {#module-system-lib-evalModules-return-value-_module}
106
107A portion of the configuration tree which is elided from `config`.
108
109<!-- TODO: when markdown migration is complete, make _module docs visible again and reference _module docs. Maybe move those docs into this chapter? -->
110
111#### `_type` {#module-system-lib-evalModules-return-value-_type}
112
113A nominal type marker, always `"configuration"`.
114
115#### `class` {#module-system-lib-evalModules-return-value-_configurationClass}
116
117The [`class` argument](#module-system-lib-evalModules-param-class).
118
119#### `graph` {#module-system-lib-evalModules-return-value-graph}
120
121Represents all the modules that took part in the evaluation.
122It is a list of `ModuleGraph` where `ModuleGraph` is defined as an attribute set with the following attributes:
123
124- `key`: `string` for the purpose of module deduplication and `disabledModules`
125- `file`: `string` for the purpose of error messages and warnings
126- `imports`: `[ ModuleGraph ]`
127- `disabled`: `bool`
128
129## Module arguments {#module-system-module-arguments}
130
131Module arguments are the attribute values passed to modules when they are evaluated.
132
133They originate from these sources:
1341. Built-in arguments
135 - `lib`,
136 - `config`,
137 - `options`,
138 - `_class`,
139 - `_prefix`,
1402. Attributes from the [`specialArgs`] argument passed to [`evalModules`] or `submoduleWith`. These are application-specific.
1413. Attributes from the `_module.args` option value. These are application-specific and can be provided by any module.
142
143The prior two categories are available while evaluating the `imports`, whereas
144the last category is only available after the `imports` have been resolved.
145
146[`lib`]{#module-system-module-argument-lib} [🔗](#module-system-module-argument-lib)
147: A reference to the Nixpkgs library.
148
149[`config`]{#module-system-module-argument-config} [🔗](#module-system-module-argument-config)
150: All option values.
151 Unlike the `evalModules` [`config` return attribute](#module-system-lib-evalModules-return-value-config), this includes `_module`.
152
153[`options`]{#module-system-module-argument-options} [🔗](#module-system-module-argument-options)
154: All evaluated option declarations.
155
156[`_class`]{#module-system-module-argument-_class} [🔗](#module-system-module-argument-_class)
157: The [expected class](#module-system-lib-evalModules-param-class) of the loaded modules.
158
159[`_prefix`]{#module-system-module-argument-_prefix} [🔗](#module-system-module-argument-_prefix)
160: The location under which the module is evaluated.
161 This is used to improve error reporting and to find the implicit `name` module argument in submodules.
162 It is exposed as a module argument due to how the module system is implemented, which cannot be avoided without breaking compatibility.
163
164 It is a good practice not to rely on `_prefix`. A module should not make assumptions about its location in the configuration tree.
165 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).
166 Instead of depending on `_prefix` use explicit options, whose default definitions can be provided by the module that imports them.
167
168<!-- markdown link aliases -->
169[`evalModules`]: #module-system-lib-evalModules
170[`specialArgs`]: #module-system-lib-evalModules-param-specialArgs