From 86f5136bafec4a6208ffe23e870f74c731f849de Mon Sep 17 00:00:00 2001 From: Robert Hensing Date: Fri, 29 Oct 2021 14:58:28 +0200 Subject: [PATCH] modules: Update evalModules doc --- lib/modules.nix | 29 ++++++++++++++++++++++++++--- 1 file changed, 26 insertions(+), 3 deletions(-) diff --git a/lib/modules.nix b/lib/modules.nix index 3a420451bf8e..d9b4000e56bd 100644 --- a/lib/modules.nix +++ b/lib/modules.nix @@ -52,9 +52,32 @@ in rec { - /* Evaluate a set of modules. The result is a set of two - attributes: ‘options’: the nested set of all option declarations, - and ‘config’: the nested set of all option values. + /* + Evaluate a set of modules. The result is a set with the attributes: + + ‘options’: The nested set of all option declarations, + + ‘config’: The nested set of all option values. + + ‘type’: A module system type representing the module set as a submodule, + to be extended by configuration from the containing module set. + + ‘extendModules’: A function similar to ‘evalModules’ but building on top + of the module set. Its arguments, ‘modules’ and ‘specialArgs’ are + added to the existing values. + + Using ‘extendModules’ a few times has no performance impact as long + as you only reference the final ‘options’ and ‘config’. + If you do reference multiple ‘config’ (or ‘options’) from before and + after ‘extendModules’, performance is the same as with multiple + ‘evalModules’ invocations, because the new modules' ability to + override existing configuration fundamentally requires a new + fixpoint to be constructed. + + ‘_module’: A portion of the configuration tree which is elided from + ‘config’. It contains some values that are mostly internal to the + module system implementation. + !!! Please think twice before adding to this argument list! The more that is specified here instead of in the modules themselves the harder it is to transparently move a set of modules to be a submodule of another