forked from mirrors/nixpkgs
lib/modules: Document _module.args
Documents the _module.args option, motivated by many usages in Flakes,
especially with the deprecation of extraArgs
(78ada83361)
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>
This commit is contained in:
Silvan Mosberger
parent
ec87404e71
commit
25de2935ef
|
|
@ -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 {
|
||||
|
|
|
|||
|
|
@ -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 = {
|
||||
|
|
|
|||
|
|
@ -48,6 +48,8 @@ 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():
|
||||
# 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
|
||||
|
|
|
|||
Loading…
Reference in a new issue