diff options
author | Silvan Mosberger <contact@infinisil.com> | 2022-03-24 02:44:43 +0100 |
---|---|---|
committer | Silvan Mosberger <contact@infinisil.com> | 2022-04-05 18:26:40 +0200 |
commit | 25de2935efce46fe51ac0e169fe13709166c788f (patch) | |
tree | eb600f53ed421041a5b3af60e9f76f898ef14694 /lib | |
parent | ec87404e71af342c65f9b3516e07b0eeb9a44610 (diff) |
lib/modules: Document _module.args
Documents the _module.args option, motivated by many usages in Flakes, especially with the deprecation of extraArgs (https://github.com/NixOS/nixpkgs/commit/78ada833615d241ed76463aa5a024b614150eb4d) The documentation rendering for this option had to be handled a bit specially, since it's not declared in nixos/modules like all the other NixOS options. Co-Authored-By: pennae <github@quasiparticle.net> Co-Authored-By: Robert Hensing <robert@roberthensing.nl>
Diffstat (limited to 'lib')
-rw-r--r-- | lib/modules.nix | 90 | ||||
-rw-r--r-- | lib/tests/misc.nix | 2 |
2 files changed, 88 insertions, 4 deletions
diff --git a/lib/modules.nix b/lib/modules.nix index 9bb8bfbbdf144..011ebb7111f82 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 2711190313956..d283c253f45f8 100644 --- a/lib/tests/misc.nix +++ b/lib/tests/misc.nix @@ -691,7 +691,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 = { |