From 4746f6d03e4f8dc6e7399f45aaba0ca3aac32761 Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Thu, 10 Mar 2022 22:45:41 +0100 Subject: [PATCH] lib.types: Add deferredModule --- lib/tests/modules.sh | 3 ++ lib/tests/modules/deferred-module.nix | 54 +++++++++++++++++++ lib/types.nix | 8 +++ .../development/option-types.section.md | 19 +++++++ .../development/option-types.section.xml | 34 ++++++++++++ 5 files changed, 118 insertions(+) create mode 100644 lib/tests/modules/deferred-module.nix diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh index 36af32ca89da..9b1348f58c9c 100755 --- a/lib/tests/modules.sh +++ b/lib/tests/modules.sh @@ -194,6 +194,9 @@ checkConfigOutput '^"submodule"$' options.submodule.type.description ./declare-s ## Paths should be allowed as values and work as expected checkConfigOutput '^true$' config.submodule.enable ./declare-submoduleWith-path.nix +## Deferred module +checkConfigOutput '"beta"' config.nodes.foo.settingsDict.c ./deferred-module.nix + # Check the file location information is propagated into submodules checkConfigOutput the-file.nix config.submodule.internalFiles.0 ./submoduleFiles.nix diff --git a/lib/tests/modules/deferred-module.nix b/lib/tests/modules/deferred-module.nix new file mode 100644 index 000000000000..faf459a991fa --- /dev/null +++ b/lib/tests/modules/deferred-module.nix @@ -0,0 +1,54 @@ +{ lib, ... }: +let + inherit (lib) types mkOption setDefaultModuleLocation; + inherit (types) deferredModule lazyAttrsOf submodule str raw; +in +{ + imports = [ + # generic module, declaring submodules: + # - nodes. + # - default + # where all nodes include the default + ({ config, ... }: { + _file = "generic.nix"; + options.nodes = mkOption { + type = lazyAttrsOf (submodule { imports = config.default; }); + default = {}; + }; + options.default = mkOption { + type = deferredModule; + default = { }; + description = '' + Module that is included in all nodes. + ''; + }; + }) + + { + _file = "default-1.nix"; + default = { config, ... }: { + options.settingsDict = lib.mkOption { type = lazyAttrsOf str; default = {}; }; + }; + } + + { + _file = "default-a-is-b.nix"; + default = { config, ... }: { + settingsDict.a = config.settingsDict.b; + }; + } + + { + _file = "nodes-foo.nix"; + nodes.foo.settingsDict.b = "beta"; + } + + { + _file = "nodes-foo-c-is-a.nix"; + nodes.foo = { config, ... }: { + settingsDict.c = config.settingsDict.a; + }; + } + + ]; +} diff --git a/lib/types.nix b/lib/types.nix index caaa6dccc6d4..22a329264457 100644 --- a/lib/types.nix +++ b/lib/types.nix @@ -539,6 +539,14 @@ rec { modules = toList modules; }; + # A module to be imported in some other part of the configuration. + deferredModule = mkOptionType { + name = "deferredModule"; + description = "module"; + check = t: isAttrs t || isFunction t; + merge = loc: defs: map (def: lib.setDefaultModuleLocation "${showOption loc} from ${def.file}" def.value) defs; + }; + # The type of a type! optionType = mkOptionType { name = "optionType"; diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md index d32d4fc50ad7..0241aae1dc89 100644 --- a/nixos/doc/manual/development/option-types.section.md +++ b/nixos/doc/manual/development/option-types.section.md @@ -220,6 +220,25 @@ Value types are types that take a value parameter. requires using a function: `the-submodule = { ... }: { options = { ... }; }`. +`types.deferredModule` + +: Whereas `submodule` represents an option tree, `deferredModule` represents + a module value, such as a module file or a configuration. + + It can be set multiple times. + + Module authors can use its value, which is always a list of module values, + in `imports` or in `submoduleWith`'s `modules` parameter. + Note that `imports` must be evaluated before the module fixpoint. Because + of this, deferred modules can only be imported into "other" fixpoints, such + as submodules. + + One use case for this type is the type of a "default" module that allow the + user to affect all submodules in an `attrsOf submodule` at once. This is + more convenient and discoverable than expecting the module user to + type-merge with the `attrsOf submodule` option. NixOps uses this type in + `network.defaults`. + ## Composed Types {#sec-option-types-composed} Composed types are types that take a type as parameter. `listOf diff --git a/nixos/doc/manual/from_md/development/option-types.section.xml b/nixos/doc/manual/from_md/development/option-types.section.xml index c67e183581c2..820646be671f 100644 --- a/nixos/doc/manual/from_md/development/option-types.section.xml +++ b/nixos/doc/manual/from_md/development/option-types.section.xml @@ -427,6 +427,40 @@ + + + types.deferredModule + + + + Whereas submodule represents an option + tree, deferredModule represents a module + value, such as a module file or a configuration. + + + It can be set multiple times. + + + Module authors can use its value, which is always a list of + module values, in imports or in + submoduleWith’s + modules parameter. Note that + imports must be evaluated before the + module fixpoint. Because of this, deferred modules can only + be imported into other fixpoints, such as + submodules. + + + One use case for this type is the type of a + default module that allow the user to affect + all submodules in an attrsOf submodule at + once. This is more convenient and discoverable than + expecting the module user to type-merge with the + attrsOf submodule option. NixOps uses + this type in network.defaults. + + +