0f9034d8b5
It creates interoperability issues that can not be reconciled by `lib` or maintainers of projects that use the Nixpkgs library. Occasionally, end users may be able to solve the problems they run into, but most are not prepared to deal with this set of problems, nor should they be. Typical conflict: - User wants to propagate their own lib, because it has some function they like to use throughout their projects - Project maintainer requires the project's lib to be used No sane language uses a single namespace for combining all the things. (Arguably not even C with its extensive use of prefixing) Meanwhile, in Nix, all symbols are first class variables. We don't even have the concept of a global top-level namespace to pour everything into. With `lib` you can try to approximate that, I get the appeal of its apparent simplicity, but since `lib` can't be global, we just don't even get that apparent simplicity. I apologize for not offering concrete solutions to this in the text. The manuals are limited to reference documentation. Alternatives - of which we have multiple - are best provided in task-oriented documentation, e.g. nix.dev.
118 lines
6.0 KiB
Markdown
118 lines
6.0 KiB
Markdown
# Module System {#module-system}
|
|
|
|
## Introduction {#module-system-introduction}
|
|
|
|
The module system is a language for handling configuration, implemented as a Nix library.
|
|
|
|
Compared to plain Nix, it adds documentation, type checking and composition or extensibility.
|
|
|
|
::: {.note}
|
|
This chapter is new and not complete yet.
|
|
|
|
See also:
|
|
- 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.
|
|
- Generic guide to the module system on [nix.dev](https://nix.dev/tutorials/module-system/index.html).
|
|
:::
|
|
|
|
## `lib.evalModules` {#module-system-lib-evalModules}
|
|
|
|
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 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 after all `imports` have been resolved.
|
|
|
|
::: {.warning}
|
|
You 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.
|
|
|
|
`lib` is reserved for the Nixpkgs library, and should not be used for custom functions.
|
|
|
|
Instead, you may create a new attribute in `specialArgs` to provide custom functions.
|
|
This clarifies their origin and avoids incompatibilities.
|
|
:::
|
|
|
|
#### `class` {#module-system-lib-evalModules-param-class}
|
|
|
|
If the `class` attribute is set and non-`null`, the module system will reject `imports` with a different `_class` declaration.
|
|
|
|
The `class` value should be a string in lower [camel case](https://en.wikipedia.org/wiki/Camel_case).
|
|
|
|
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` 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}
|
|
|
|
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.
|
|
|
|
### 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 attribute set of all option declarations.
|
|
|
|
#### `config` {#module-system-lib-evalModules-return-value-config}
|
|
|
|
The nested attribute set of all option values.
|
|
|
|
#### `type` {#module-system-lib-evalModules-return-value-type}
|
|
|
|
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).
|
|
|
|
However, the value returned from the type is just the [`config`](#module-system-lib-evalModules-return-value-config), like any submodule.
|
|
|
|
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.
|
|
|
|
This type is also available to the [`modules`](#module-system-lib-evalModules-param-modules) as the module argument `moduleType`.
|
|
<!-- TODO: document the module arguments. Using moduleType is like saying: suppose this configuration was extended. -->
|
|
|
|
#### `extendModules` {#module-system-lib-evalModules-return-value-extendModules}
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
This functionality is also available to modules as the `extendModules` module argument.
|
|
|
|
::: {.note}
|
|
|
|
**Evaluation Performance**
|
|
|
|
`extendModules` returns a configuration that shares very little with the original `evalModules` invocation, because the module arguments may be different.
|
|
|
|
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`.
|
|
|
|
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.
|
|
|
|
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.
|
|
:::
|
|
|
|
#### `_module` {#module-system-lib-evalModules-return-value-_module}
|
|
|
|
A portion of the configuration tree which is elided from `config`.
|
|
|
|
<!-- TODO: when markdown migration is complete, make _module docs visible again and reference _module docs. Maybe move those docs into this chapter? -->
|
|
|
|
#### `_type` {#module-system-lib-evalModules-return-value-_type}
|
|
|
|
A nominal type marker, always `"configuration"`.
|
|
|
|
#### `class` {#module-system-lib-evalModules-return-value-_configurationClass}
|
|
|
|
The [`class` argument](#module-system-lib-evalModules-param-class).
|