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

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. For a gentle introduction to the module system, in the context of NixOS, see Writing NixOS Modules in the NixOS manual. :::

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

modules

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

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.

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.

If applicable, the class should match the "prefix" of the attributes used in (experimental) flakes. Some examples are:

• nixos as in flake.nixosModules
• nixosTest: modules that constitute a NixOS VM test

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

The result is an attribute set with the following attributes:

options

The nested attribute set of all option declarations.

config

The nested attribute set of all option values.

type

A module system type. This type is an instance of types.submoduleWith containing the current modules.

The option definitions that are typed with this type will extend the current set of modules, like extendModules.

However, the value returned from the type is just the 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 as the module argument moduleType.

extendModules

A function similar to evalModules but building on top of the already passed 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

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

_type

A nominal type marker, always "configuration".

class

The class argument.