diff options
author | Robert Hensing <roberth@users.noreply.github.com> | 2022-04-05 21:51:46 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2022-04-05 21:51:46 +0200 |
commit | c70595326763ac7427293cd7e005619fa762c37c (patch) | |
tree | 3a33a0692b4e4c771c0465c8bef907889dbdc155 | |
parent | fcbcab75c2f12f433129325f5644e124de29af1e (diff) | |
parent | 25de2935efce46fe51ac0e169fe13709166c788f (diff) |
Merge pull request #165540 from Infinisil/module-args-docs
lib/modules: Document `_module.args`
-rw-r--r-- | lib/modules.nix | 90 | ||||
-rw-r--r-- | lib/tests/misc.nix | 2 | ||||
-rw-r--r-- | nixos/lib/make-options-doc/mergeJSON.py | 4 |
3 files changed, 91 insertions, 5 deletions
diff --git a/lib/modules.nix b/lib/modules.nix index 894104cc57907..abcdd1a894cca 100644 --- a/lib/modules.nix +++ b/lib/modules.nix @@ -46,6 +46,7 @@ let showFiles showOption unknownModule + literalExpression ; showDeclPrefix = loc: decl: prefix: @@ -140,7 +141,7 @@ rec { # this module is used, to avoid conflicts and allow chaining of # extendModules. internalModule = rec { - _file = ./modules.nix; + _file = "lib/modules.nix"; key = _file; @@ -153,8 +154,91 @@ rec { # a `_module.args.pkgs = import (fetchTarball { ... }) {}` won't # start a download when `pkgs` wasn't evaluated. type = types.lazyAttrsOf types.raw; - internal = true; - description = "Arguments passed to each module."; + # Only render documentation once at the root of the option tree, + # not for all individual submodules. + internal = prefix != []; + # TODO: Change the type of this option to a submodule with a + # freeformType, so that individual arguments can be documented + # separately + description = '' + Additional arguments passed to each module in addition to ones + like <literal>lib</literal>, <literal>config</literal>, + and <literal>pkgs</literal>, <literal>modulesPath</literal>. + </para> + <para> + This option is also available to all submodules. Submodules do not + inherit args from their parent module, nor do they provide args to + their parent module or sibling submodules. The sole exception to + this is the argument <literal>name</literal> which is provided by + parent modules to a submodule and contains the attribute name + the submodule is bound to, or a unique generated name if it is + not bound to an attribute. + </para> + <para> + Some arguments are already passed by default, of which the + following <emphasis>cannot</emphasis> be changed with this option: + <itemizedlist> + <listitem> + <para> + <varname>lib</varname>: The nixpkgs library. + </para> + </listitem> + <listitem> + <para> + <varname>config</varname>: The results of all options after merging the values from all modules together. + </para> + </listitem> + <listitem> + <para> + <varname>options</varname>: The options declared in all modules. + </para> + </listitem> + <listitem> + <para> + <varname>specialArgs</varname>: The <literal>specialArgs</literal> argument passed to <literal>evalModules</literal>. + </para> + </listitem> + <listitem> + <para> + All attributes of <varname>specialArgs</varname> + </para> + <para> + Whereas option values can generally depend on other option values + thanks to laziness, this does not apply to <literal>imports</literal>, which + must be computed statically before anything else. + </para> + <para> + For this reason, callers of the module system can provide <literal>specialArgs</literal> + which are available during import resolution. + </para> + <para> + For NixOS, <literal>specialArgs</literal> includes + <varname>modulesPath</varname>, which allows you to import + extra modules from the nixpkgs package tree without having to + somehow make the module aware of the location of the + <literal>nixpkgs</literal> or NixOS directories. + <programlisting> + { modulesPath, ... }: { + imports = [ + (modulesPath + "/profiles/minimal.nix") + ]; + } + </programlisting> + </para> + </listitem> + </itemizedlist> + </para> + <para> + For NixOS, the default value for this option includes at least this argument: + <itemizedlist> + <listitem> + <para> + <varname>pkgs</varname>: The nixpkgs package set according to + the <option>nixpkgs.pkgs</option> option. + </para> + </listitem> + </itemizedlist> + ''; }; _module.check = mkOption { diff --git a/lib/tests/misc.nix b/lib/tests/misc.nix index c7cef2a9059f1..9012bba2b5675 100644 --- a/lib/tests/misc.nix +++ b/lib/tests/misc.nix @@ -696,7 +696,7 @@ runTests { locs = filter (o: ! o.internal) (optionAttrSetToDocList options); in map (o: o.loc) locs; - expected = [ [ "foo" ] [ "foo" "<name>" "bar" ] [ "foo" "bar" ] ]; + expected = [ [ "_module" "args" ] [ "foo" ] [ "foo" "<name>" "bar" ] [ "foo" "bar" ] ]; }; testCartesianProductOfEmptySet = { diff --git a/nixos/lib/make-options-doc/mergeJSON.py b/nixos/lib/make-options-doc/mergeJSON.py index 8e2ea322dc896..44a188a08c999 100644 --- a/nixos/lib/make-options-doc/mergeJSON.py +++ b/nixos/lib/make-options-doc/mergeJSON.py @@ -48,7 +48,9 @@ overrides = pivot(json.load(open(sys.argv[2 + optOffset], 'r'))) # fix up declaration paths in lazy options, since we don't eval them from a full nixpkgs dir for (k, v) in options.items(): - v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}', v.value['declarations'])) + # The _module options are not declared in nixos/modules + if v.value['loc'][0] != "_module": + v.value['declarations'] = list(map(lambda s: f'nixos/modules/{s}', v.value['declarations'])) # merge both descriptions for (k, v) in overrides.items(): |