diff --git a/lib/modules.nix b/lib/modules.nix index d8ae497fb2d8..1e48f5440798 100644 --- a/lib/modules.nix +++ b/lib/modules.nix @@ -462,6 +462,7 @@ rec { config = addFreeformType (addMeta (m.config or {})); } else + lib.throwIfNot (isAttrs m) "module ${file} (${key}) does not look like a module." { _file = toString m._file or file; key = toString m.key or key; disabledModules = m.disabledModules or []; diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh index 36af32ca89da..c92cc62023b5 100755 --- a/lib/tests/modules.sh +++ b/lib/tests/modules.sh @@ -194,6 +194,13 @@ 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 +## deferredModule +# default module is merged into nodes.foo +checkConfigOutput '"beta"' config.nodes.foo.settingsDict.c ./deferred-module.nix +# errors from the default module are reported with accurate location +checkConfigError 'In `the-file-that-contains-the-bad-config.nix, via option default'\'': "bogus"' config.nodes.foo.bottom ./deferred-module.nix +checkConfigError '.*lib/tests/modules/deferred-module-error.nix, via option deferred [(]:anon-1:anon-1:anon-1[)] does not look like a module.' config.result ./deferred-module-error.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-error.nix b/lib/tests/modules/deferred-module-error.nix new file mode 100644 index 000000000000..d48ae092e8fe --- /dev/null +++ b/lib/tests/modules/deferred-module-error.nix @@ -0,0 +1,20 @@ +{ config, lib, ... }: +let + inherit (lib) types mkOption setDefaultModuleLocation evalModules; + inherit (types) deferredModule lazyAttrsOf submodule str raw enum; +in +{ + options = { + deferred = mkOption { + type = deferredModule; + }; + result = mkOption { + default = (evalModules { modules = [ config.deferred ]; }).config.result; + }; + }; + config = { + deferred = { ... }: + # this should be an attrset, so this fails + true; + }; +} diff --git a/lib/tests/modules/deferred-module.nix b/lib/tests/modules/deferred-module.nix new file mode 100644 index 000000000000..d03c60b029bf --- /dev/null +++ b/lib/tests/modules/deferred-module.nix @@ -0,0 +1,58 @@ +{ lib, ... }: +let + inherit (lib) types mkOption setDefaultModuleLocation; + inherit (types) deferredModule lazyAttrsOf submodule str raw enum; +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 = {}; }; + options.bottom = lib.mkOption { type = enum []; }; + }; + } + + { + _file = "default-a-is-b.nix"; + default = ./define-settingsDict-a-is-b.nix; + } + + { + _file = "nodes-foo.nix"; + nodes.foo.settingsDict.b = "beta"; + } + + { + _file = "the-file-that-contains-the-bad-config.nix"; + default.bottom = "bogus"; + } + + { + _file = "nodes-foo-c-is-a.nix"; + nodes.foo = { config, ... }: { + settingsDict.c = config.settingsDict.a; + }; + } + + ]; +} diff --git a/lib/tests/modules/define-settingsDict-a-is-b.nix b/lib/tests/modules/define-settingsDict-a-is-b.nix new file mode 100644 index 000000000000..42363f45f78d --- /dev/null +++ b/lib/tests/modules/define-settingsDict-a-is-b.nix @@ -0,0 +1,3 @@ +{ config, ... }: { + settingsDict.a = config.settingsDict.b; +} diff --git a/lib/types.nix b/lib/types.nix index caaa6dccc6d4..354714b28733 100644 --- a/lib/types.nix +++ b/lib/types.nix @@ -539,6 +539,36 @@ rec { modules = toList modules; }; + # A module to be imported in some other part of the configuration. + deferredModule = deferredModuleWith { }; + + # A module to be imported in some other part of the configuration. + # `staticModules`' options will be added to the documentation, unlike + # options declared via `config`. + deferredModuleWith = attrs@{ staticModules ? [] }: mkOptionType { + name = "deferredModule"; + description = "module"; + check = x: isAttrs x || isFunction x || path.check x; + merge = loc: defs: { + imports = staticModules ++ map (def: lib.setDefaultModuleLocation "${def.file}, via option ${showOption loc}" def.value) defs; + }; + inherit (submoduleWith { modules = staticModules; }) + getSubOptions + getSubModules; + substSubModules = m: deferredModuleWith (attrs // { + staticModules = m; + }); + functor = defaultFunctor "deferredModuleWith" // { + type = types.deferredModuleWith; + payload = { + inherit staticModules; + }; + binOp = lhs: rhs: { + staticModules = lhs.staticModules ++ rhs.staticModules; + }; + }; + }; + # 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..9b35e6630144 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 in `imports`, in `submoduleWith`'s `modules` + or in `evalModules`' `modules` parameter, among other places. + + 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. + ## 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..929d5302ed41 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,43 @@ + + + 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 in + imports, in + submoduleWiths + modules or in + evalModules + modules parameter, among other places. + + + 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. + + +