diff --git a/lib/types.nix b/lib/types.nix
index ee6163229fd60..acad53d7f5cac 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -367,6 +367,7 @@ rec {
{ configDefault ? false
, modules ? []
, specialArgs ? {}
+ , hideSubOptions ? false
}@attrs:
let
inherit (lib.modules) evalModules;
@@ -390,7 +391,7 @@ rec {
args.name = last loc;
prefix = loc;
}).config;
- getSubOptions = prefix: (evalModules
+ getSubOptions = prefix: optionalAttrs (!hideSubOptions) (evalModules
{ inherit modules prefix specialArgs;
# This is a work-around due to the fact that some sub-modules,
# such as the one included in an attribute set, expects a "args"
diff --git a/nixos/doc/manual/development/option-types.xml b/nixos/doc/manual/development/option-types.xml
index 8fcbb627342b2..8ab7ea91ab76b 100644
--- a/nixos/doc/manual/development/option-types.xml
+++ b/nixos/doc/manual/development/option-types.xml
@@ -259,12 +259,39 @@
A set of sub options o.
o can be an attribute set or a function
returning an attribute set. Submodules are used in composed types to
- create modular options. Submodule are detailed in
+ create modular options. This is equivalent to types.fullSubmodule { configDefault = true; modules = toList o; }. Submodules are detailed in
.
+
+
+ types.fullSubmodule { modules ? [], specialArgs ? {}, configDefault ? false }
+
+
+
+ Like types.submodule, but more flexible and without as much magic. It has arguments
+
+
+ modules
+ A list of modules to use by default for this submodule type. This gets combined with all option definitions to build the final list of modules that will be included.
+
+
+ specialArgs
+ An attribute set of extra arguments that get passed to the module functions. For most arguments, the option _module.args should be used instead, since it allows overriding. specialArgs should only be used for arguments that can't go through the module fixed-point, because of infinite recursion or other problems. A good use-case example is overriding the lib argument that gets passed to all modules, because lib itself is used to define _module.args, which makes using _module.args impossible.
+
+
+ configDefault
+ Whether definitions of this type should default to the config section of a module (see ) if it is an attribute set. Enabling this only has a benefit when the submodule defines an option named config or options. In such a case it would allow the option to be set with the-submodule.config = "value" instead of requiring the-submodule.config.config = "value". This is because only when modules don't set the config or options keys, all keys are interpreted as option definitions in the config section. Enabling this option explicitly puts all definitions in the config section.
+
+
+ This option defaults to false because enabling it makes declaring non-config module sections difficult.
+
+
+
+
+