Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Module Options Reference

This reference documents the caisson framework’s module options. All descriptions are sourced from the Nix-native description fields in the module code.

For lib.caisson functions, see Library Reference.

The options are declared by caisson’s core module, which is imported into an evaluation of an integrated class. In an evaluation whose library is not a caisson composition, such as a home-manager configuration that home-manager’s NixOS module embeds, the core module declares nothing.

Options

caisson.manifest

  • Type: caisson.flake-parts.types.manifest (read-only)
  • Default: the composed library’s caisson-core.evalManifest, or its caisson-core.libManifest in an evaluation that carries none
  • Source: modules/generic/core/caisson/manifest.nix

The manifest of this evaluation: its type, name, parent and children, and the registries and declared facts of the composition it is declared under, which are sources, defaultEcosystemSrc, systems and projects as given to mkLib, plus the registered libOverlays and modules dictionaries (project entries under <project>/<name>, locals winning). Structural, flake-parts and NixOS configurations carry a manifest. Reading it type-checks the manifest; the flake.modules and flake.libOverlays projections are drawn from it, and flake-parts’ systems defaults to the manifest’s systems, the empty list when the composition declares none, so such a flake has no per-system outputs (modules/flake/core/caisson/systems.nix).

caisson.<integration>.configurations

  • Type: lazy attribute set of configurations, read back as manifests
  • Default: { }
  • Source: lib.caisson.<integration>.configurationsModule, generated by mkIntegration in lib-overlays/integrations/default.nix

The configurations of an integration declared beneath this configuration, by name. The option is declared by the module of the integration, lib.caisson.<integration>.configurationsModule. For the integrations of caisson, the core module of caisson declares it instead, through one module for all of them (lib.caisson.integrations.configurationsModuleFor). An entry takes what that integration’s mkConfiguration returns, a function of { name, parent }, and reads back as the finished manifest:

{ config, lib, ... }:
{
  caisson.structural.configurations.inner = lib.caisson.structural.mkConfiguration { };
}

Each entry is finalized when it is read, with the attribute it is declared under as its name and the childless manifest of this evaluation as its parent. An entry of an integration that evaluates a configuration per system (nixos) reads back as its evaluations by system, config.caisson.nixos.configurations.laptop.x86_64-linux, a manifest for every system in force. The names are known without finalizing anything, so builtins.attrNames config.caisson.structural.configurations evaluates no configuration.

A configuration declared inside this configuration sees its childless evaluation, which leaves out the configurations declared inside it. In the childless evaluation an entry’s result is not readable, and reading it fails with a message saying so. A definition that reads an entry is therefore written under !lib.caisson.evalManifest.childless:

# an option of this configuration, defined from a configuration beneath it
innerGreeting =
  if lib.caisson.evalManifest.childless then
    null
  else
    config.caisson.structural.configurations.inner.value.config.greeting;

A module that only declares configurations needs no such test. What the configurations beneath export is passed up without that test, through caisson.<integration>.exported below.

An entry that is not a configuration, or is a configuration of another integration, is refused. Structural, flake-parts and nixos configurations can be declared. A configuration of an integration that evaluates a class another integration owns is a configuration of the owner in the tree: lib.caisson.nixos-minimal.mkConfiguration returns a nixos configuration, declared under caisson.nixos.configurations and published with the others. The constructors of the remaining integrations return an evaluated value. A configuration holds configurations of any integration beneath it.

caisson.<integration>.exported

  • Type: function from the configurations declared to an attribute set of them
  • Default: configurations: configurations, every configuration declared
  • Source: lib.caisson.<integration>.configurationsModule, generated by mkIntegration in lib-overlays/integrations/default.nix

Function that selects which of the configurations declared under caisson.<integration>.configurations this configuration passes up. What each selected configuration exports (its outputs.exports: lib, libOverlays, modules, pkgOverlays) is merged into this configuration’s caisson.exports, beside what the registry selectors here choose. A configuration beneath passes up what lies beneath it in turn, so the exports of a tree of structural configurations reach its top with nothing written:

{ lib, ... }:
{
  caisson.structural.configurations.impl = lib.caisson.structural.mkConfiguration { };
}

The configurations themselves are passed up as well, each with its path, and the top publishes them under the output attribute set their integration declares, named from the paths:

{ lib, ... }:
{
  caisson.nixos.configurations.laptop = lib.caisson.nixos.mkConfiguration { };
}

publishes nixosConfigurations.laptop from a flake-parts or structural top. A name that is alone stays bare. Names that collide gain the segments that tell them apart, from the segment nearest the top: host-1 declared in the structural configurations a and b is published as a/host-1 and b/host-1, and a configuration evaluated for several systems as x86_64-linux/laptop and aarch64-linux/laptop. Configurations that still share a name are refused, with their paths. An integration may give its configurations a different name first: a home-manager configuration declared as chris inside the NixOS configuration laptop is published as homeConfigurations."chris@laptop".

caisson.structural.exported = _: { }; passes up none, and a selector returning a subset passes up those. The merge is made in the evaluation that holds the configurations: it is absent from the childless view, and from an evaluation that carries no manifest.

The top records what it published in the export record, exportRecord of the manifest it publishes as caisson.manifest, keyed as the outputs are. The entry for a name holds the path to the configuration by the names declared, the sentences that say how the name came about, and the positions of the code that made it, among them the file that defines this selector when it is not left at its default.

caisson.<integration>.exportNote

  • Type: null or string
  • Default: null
  • Source: lib.caisson.<integration>.configurationsModule, generated by mkIntegration in lib-overlays/integrations/default.nix

A sentence saying what caisson.<integration>.exported does to the configurations it passes up, for a selector that does more than pass every configuration up unchanged. The top adds it to the notes of the export record entry of each name published from those configurations, after the notes of the levels beneath:

{ lib, ... }:
{
  caisson.nixos.configurations = {
    nas-1 = lib.caisson.nixos.mkConfiguration { };
    lab-3 = lib.caisson.nixos.mkConfiguration { };
  };
  caisson.nixos.exported =
    configurations:
    lib.mapAttrs' (name: lib.nameValuePair "office-${name}") (
      lib.filterAttrs (name: _: !lib.hasPrefix "lab-" name) configurations
    );
  caisson.nixos.exportNote = "office machines carry the site prefix; lab machines stay unpublished";
}

publishes nixosConfigurations.office-nas-1, and its entry in the export record holds the note.

caisson.home-manager.activation.usersDeclaredElsewhere

  • Type: listOf str
  • Default: [ ]
  • Source: modules/nixos/home-manager-activation/
  • Declared in: a NixOS configuration that imports caisson/home-manager-activation, which caisson/default for the nixos class does

The users that have an account on this machine although users.users does not declare it.

A NixOS configuration activates the home-manager configurations declared inside it. It expects the account of the user of each home-manager configuration in users.users, and it refuses a home-manager configuration whose user has no account there. Such a home-manager configuration is usually a mistake: a misspelled user name, or a home-manager configuration declared on the wrong machine.

An account that systemd-homed manages is not in users.users. systemd-homed keeps the record of the account, and the machine must not declare it a second time. List the user here:

{ lib, ... }:
{
  services.homed.enable = true;

  caisson.home-manager.activation.usersDeclaredElsewhere = [ "chris" ];

  caisson.home-manager.configurations.chris = lib.caisson.home-manager.mkConfiguration {
    configModule = {
      home.homeDirectory = "/home/chris";
    };
  };
}

The home-manager configuration of a listed user is not refused. It is activated by a user unit that runs when the user logs in, which is when systemd-homed mounts the home directory. The home-manager configuration sets its home directory itself, because the machine has no account to read it from.

A user that is listed here and also declared in users.users is refused, because the two statements contradict each other.

See modules.nixos."caisson/home-manager-activation" for the units.

caisson.drift.warn

  • Type: bool
  • Default: true
  • Source: modules/homeManager/activation-drift/, modules/nvf/default/
  • Declared in: a home-manager configuration that imports caisson/activation-drift, which the home-manager default module imports; an nvf or nixvim configuration that imports the default module of its class

Whether the activation of this home-manager configuration, or activate of this nvf or nixvim configuration, prints a warning when it was built for a version of the configuration it is declared inside, such as its machine or its home-manager configuration, that differs from the version that is applied.

The configuration above records what it applied in a marker file, /etc/caisson/marker.json on a machine. The activation of the home-manager configuration compares the marker with the configuration above as it is in the source the home-manager configuration was built from.

The comparison leaves out the configurations declared inside the configuration above. A change to a home-manager configuration does not cause a warning. The warning does not stop the activation.

{ ... }:
{
  caisson.drift.warn = false;
}

Here the home-manager configuration is activated with no comparison.

See drift detection for what the marker holds and what is compared.

caisson.profiles.selected

  • Type: attrsOf str
  • Default: { }
  • Source: modules/*/profile-activation/
  • Declared in: a NixOS, darwin or system-manager machine, a home-manager configuration or a hjem configuration that imports caisson/profile-activation, which the default module of each of these classes imports

By the variable that chooses among them, the profile a shell runs when it sets no other, as <kind>/<name>. nvf/editor is the nvf configuration declared as editor.

A configuration installs a program for each program of the profiles declared inside it, such as nvim, which runs the profile the variable names, and the default profile when the variable is unset. With one profile for a variable, that profile is the default. With several, this option names it, and the evaluation fails until it does.

{ ... }:
{
  caisson.profiles.selected.CAISSON_NVIM_PROFILE = "nvf/editor";
}

Here a shell that sets no CAISSON_NVIM_PROFILE runs the Neovim of the nvf configuration editor.

See profiles.

caisson.forChildren.extraDefaultModuleImports

  • Type: attrsOf (functionTo (listOf module)), by class
  • Default: { }
  • Source: modules/generic/core/caisson/forChildren.nix

Additions to the default selection of a class for the configurations beneath this configuration: a function of the lib of such a configuration returning registered modules. A module listed here is registered in the composition, on mkLib or by a project.

{ ... }:
{
  caisson.forChildren.extraDefaultModuleImports.nixos = lib: [ lib.caisson.modules.nixos.gaming ];
}

A configuration that passes no moduleImports gets every entry named default followed by these, those of the levels above it first. A configuration that passes moduleImports gets what it selects in place of that default, and one that passes extraModuleImports gets what that selects in addition. Definitions from several modules are concatenated.

The name says that the option adds to what is in force, as extraModuleImports does. The options defaultPkgs and systems below replace what is in force.

A configuration with a configuration beneath it is evaluated in both views, since what it gives is read from the childless view.

caisson.forChildren.defaultPkgs

  • Type: nullOr (functionTo pkgs)
  • Default: null
  • Source: modules/generic/core/caisson/forChildren.nix

The package set the configurations beneath this configuration get by default: a function that receives the package sets available to such a configuration, as an attribute set by package config name, and returns the set to run on.

{ ... }:
{
  caisson.forChildren.defaultPkgs = pkgSets: pkgSets.stable;
}

Here the default beneath this configuration is the set of the package config named stable. A configuration beneath runs on it unless that configuration, or a configuration between the two, is constructed with defaultPkgs or sets this option. This configuration runs on the set it was constructed with. When the option is null, the default beneath is the selection in force at this configuration.

caisson.forChildren.systems

  • Type: nullOr (listOf str)
  • Default: null
  • Source: modules/generic/core/caisson/forChildren.nix

The systems the configurations declared inside this configuration are evaluated for. It applies to configurations that are evaluated per system, such as a NixOS configuration or a home-manager configuration: each gets one evaluation per system listed.

{ ... }:
{
  caisson.forChildren.systems = [ "aarch64-linux" ];
}

Set on a NixOS configuration for x86_64-linux, this evaluates the configurations declared inside it for aarch64-linux. A machine that builds an image for an aarch64-linux device is an example. Set on a structural or flake level, it limits the systems the configurations inside that level are evaluated for. The systems have to be among those allowed where this configuration is declared, and a system that is not among them is refused.

When the option is null, a configuration that is itself evaluated per system has its children evaluated for its system only, so a home-manager configuration inside a NixOS configuration for x86_64-linux is evaluated for x86_64-linux. Any other configuration passes on the list it was given.

caisson.modules

  • Source: modules/generic/core/caisson/modules.nix

Export settings for each module class of the composition. caisson declares these options for each class:

  • export.enabled (bool, default true)
  • exported (function -> attrsOf deferredModule, default: the modules of the class that the composition registers itself)

The classes of the composition are the classes that the integrations declare and the classes that have a registered module. A setting for another class is refused as an option that does not exist, and so is a setting other than export.enabled and exported. A misspelled class name or setting name is therefore an error.

The selected modules are the exported modules. They are in the manifest, and mkLib reads them from there for each entry of projects.

The exported modules are also published under flake.modules.<class>, and caisson.flakeOutputs.modules selects which of them. For the "flake" class, the published modules are also mirrored to flake.flakeModules.

caisson.modules.<class>.export.enabled

  • Type: bool
  • Default: true
  • Source: modules/generic/core/caisson/modules.nix

Whether to export modules for a given class.

caisson.modules.<class>.exported

  • Type: a function from the registered modules to the modules to export
  • Default: the modules of the class that the composition registers itself
  • Source: modules/generic/core/caisson/modules.nix

Function that selects which registered modules of a class to export. Receives the modules registered for the class and returns the modules to export, which are exported as the function returns them. A module that came from an entry of projects, registered as <project>/<name>, is exported only when the function names it.

The two settings of every class are held in one option, caisson.modules, an attribute set by class of lazyAttrsOf raw values, so a class that no module sets costs nothing to evaluate. Each setting is a plain value: a priority such as mkDefault on exported takes effect, and two definitions of exported for one class conflict rather than merge. A class with no registered module, or a key other than export and exported, is refused when the exports are read.

caisson.flakeOutputs.modules

  • Type: function -> attrsOf (attrsOf deferredModule)
  • Default: modules: modules
  • Source: modules/flake/core/caisson/exports.nix

Function that selects which exported modules are also published in the modules output. It receives the exported modules, as an attribute set of classes that each hold modules by name, and returns the modules to publish in the same shape. The option exists in a flake-parts configuration.

The exported modules are the modules that the caisson.modules.<class>.exported selectors chose. They are in the manifest, and mkLib reads them from there for each entry of projects. mkLib reads every exported module, whatever this function returns.

The modules output serves an import by hand, as inputs.<input>.modules.<class>.<name>. Leave a module out of the output when it only works inside an evaluation that caisson makes, because it reads the options under caisson or the library under lib.caisson.

caisson.flakeOutputs.modules =
  modules: modules // { nixos = removeAttrs modules.nixos [ "needs-caisson" ]; };

caisson sets the option to _: { }. Each module that caisson exports works only inside an evaluation that caisson makes. The modules output of caisson holds the empty default entry of the flake class and nothing else.

caisson.libOverlays.export.enabled

  • Type: bool
  • Default: true
  • Source: modules/generic/core/caisson/libOverlays.nix

Whether to enable lib overlay export. When enabled, the lib overlays selected by caisson.libOverlays.exported are exported. They are in the manifest. mkLib reads them from there for each entry of projects, and registers each as <project>/<name>. A lib overlay is an entry in the shape caisson registers, so there is no libOverlays output.

caisson.libOverlays.exported

  • Type: function -> libOverlays, an attribute set of lib overlays merged as one attribute set, each entry checked when it is read
  • Default: the lib overlays that the composition registers itself
  • Source: modules/generic/core/caisson/libOverlays.nix

Function that selects which registered library overlays to export. Receives the set of overlays registered via mkLib and returns the overlays to export. A lib overlay that came from an entry of projects, registered as <project>/<name>, is exported only when the function names it.