lib/modules: Document `_module.args` #165540

infinisil · 2022-03-24T01:57:05Z

Description of changes

Documents the _module.args option, motivated by many usages in Flakes, especially with the deprecation of extraArgs

Click for screenshot of the documentation

Things done

Built the manual with nix-build nixos/release.nix -A manualHTML.x86_64-linux and checked the resulting result/share/doc/nixos/options.html

pennae

nice! would clarify how args works for submodules a little bit though and mention the name argument since it's really useful but apparently not documented anywhere either.

lib/modules.nix

roberth

We actually need to discourage use of module arguments :(

roberth · 2022-03-24T10:24:33Z

lib/modules.nix

+            description = ''
+              Additional arguments passed to each module in addition to ones
+              like <literal>lib</literal>, <literal>config</literal>,
+              <literal>pkgs</literal>, <literal>modulesPath</literal> for


These are NixOS-specific and don't belong in the generated documentation of other configuration systems.
They are better documented as freeform options.

Suggested change

<literal>pkgs</literal>, <literal>modulesPath</literal> for

These arguments are not evaluated by the module system.

What does this mean?

Technically the module system doesn't evaluate anything, as it is a library or embedded dsl.
Maybe "they aren't processed by the module system", but that's still vague. Probably best to remove this sentence.

These are NixOS-specific and don't belong in the generated documentation of other configuration systems. They are better documented as freeform options.

I should reword this sentence (there's a for nixpkgs afterwards, but it's very ambiguous). I think it's valid to mention pkgs and modulesPath in this documentation because there's no other place where these are documented currently, and NixOS modules are by far the most common use case. With a freeform type we should be able to make this documentation NixOS-specific in the future though.

I just dropped the for nixpkgs. This sentence specifically says "ones like ...", which indicates that it's just an example of some arguments the reader might be familiar with. I think this should be fine

lib/modules.nix

roberth · 2022-03-24T11:00:40Z

lib/modules.nix

+            example = literalExpression ''
+              {
+                unstable = import nixpkgs {};
+                myLib = { addOne = x: x + 1; };


This is actually an antipattern. It works for "split configuration" but is a bad idea for reusable modules.
It's better than lib.extend by virtue of being slightly more composable, but still vulnerable to name collisions.
The most robust method of using "libraries" is to import them directly into the lexical scope: let myLib = import ./myLlib; in ...... The root values in file imports are cached, so there's no loss of performance. Function invocations are not, so we need an alternative place to memoize those and internal options fit that purpose, without the risk of name collisions or organic accumulation of "utils" junk libraries.

Do you have suggestions for better examples? Or should we drop examples completely?

I honestly don't know of a good example. The ones in nixpkgs itself aren't actually good either. They're highly specific and/or workarounds.

unstable is the best example I know of, only slightly better than myLib. I'd call it pkgsUnstable though.

I think we need to clarify what are the "acceptable" use cases:

end user configurations that are not intended to be included into anything that isn't defined "locally". Here convenience wins over reusability, but it does mean turning configs into modules will be harder.

specific features of configuration systems, maybe?

for example NixOS defines noUserModules to solve quite a NixOS-specific problem (maybe I should have used an internal specialisations option instead? I guess that namespace was taken by an attrsOf. Is that sufficient reason?

is baseModules any better?

I'm really trying to like it, but not succeeding.

I removed the example altogether for now. We can still add one later if we have a good one.

nixos-discourse · 2022-04-01T11:29:20Z

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/tweag-nix-dev-update-27/18433/1

Documents the _module.args option, motivated by many usages in Flakes, especially with the deprecation of extraArgs (NixOS@78ada83) 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 <[email protected]> Co-Authored-By: Robert Hensing <[email protected]>

infinisil · 2022-04-05T16:27:21Z

@roberth Good to merge?

roberth

One final thing it seems.
Otherwise lgtm.

roberth · 2022-04-05T17:44:58Z

lib/modules.nix

+               </listitem>
+               <listitem>
+                <para>
+                 <varname>config</varname>: The results of all options after merging the values from all modules together.


Subtle but important.

Suggested change

<varname>config</varname>: The results of all options after merging the values from all modules together.

<varname>config</varname>: The results of all options after merging the values from all modules together. In the context of a submodule, "all modules" does not include the parent module that contains the submodule.

</para>

<para>

The module arguments of the parent can be accessed through the lexical scope instead.

It seems that something is missing from my terminology here. I can't find a word for what's like a level of modules, corresponding to an evalModules invocation, whether through lib or types.submodule. "Modules" is too vague "configuration" is a little more accurate but deemphasizes the options. "Configuration fixpoint" will send our readers studying for a day ;). Not sure what to do.

"modules are merged according to the longest common option path prefix"? that covers both configurations (prefix 𝜀) and submodules (nested or not)

While that is true, it does not indicate where config starts or equivalently: what is the result of "all options" and which options are "all".

I don't think this clarification is needed because it's fairly obvious, submodules have a completely separate option set. This would fit better into the full NixOS documentation, this here should only be a very short explanation, only in relation to _module.args.

fair enough 🚀

roberth · 2022-04-05T17:46:19Z

lib/modules.nix

+               </listitem>
+               <listitem>
+                <para>
+                 <varname>options</varname>: The options declared in all modules.


Suggested change

<varname>options</varname>: The options declared in all modules.

<varname>options</varname>: The options declared in all modules, where "all modules" is defined the same as in <varname>config</varname>.

roberth · 2022-04-07T21:44:42Z

Making this opt-out in #167776 so arion doesn't have to deal with docbook in its asciidoc.

infinisil added the 6.topic: module system About "NixOS" module system internals label Mar 24, 2022

infinisil requested review from edolstra and nbp as code owners March 24, 2022 01:57

infinisil changed the title ~~lib/modules: Document _module.args~~ lib/modules: Document _module.args Mar 24, 2022

github-actions bot added the 6.topic: nixos Issues or PRs affecting NixOS modules, or package usability issues specific to NixOS label Mar 24, 2022

infinisil mentioned this pull request Mar 24, 2022

Document NixOS module inputs #132419

Open

pennae reviewed Mar 24, 2022

View reviewed changes

lib/modules.nix Outdated Show resolved Hide resolved

roberth requested changes Mar 24, 2022

View reviewed changes

infinisil force-pushed the module-args-docs branch 3 times, most recently from ecdf336 to 2f218ed Compare March 24, 2022 14:38

infinisil force-pushed the module-args-docs branch from 2f218ed to 25de293 Compare April 5, 2022 16:26

ofborg bot added 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin 10.rebuild-linux: 1-10 labels Apr 5, 2022

roberth reviewed Apr 5, 2022

View reviewed changes

roberth approved these changes Apr 5, 2022

View reviewed changes

roberth merged commit c705953 into NixOS:master Apr 5, 2022

infinisil deleted the module-args-docs branch April 5, 2022 19:52

roberth mentioned this pull request Apr 7, 2022

lib.modules: Allow making _module.args internal #167776

Merged

13 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

lib/modules: Document `_module.args` #165540

lib/modules: Document `_module.args` #165540

infinisil commented Mar 24, 2022 •

edited

Loading

pennae left a comment

roberth left a comment •

edited

Loading

roberth Mar 24, 2022

roberth Mar 24, 2022

infinisil Mar 24, 2022

infinisil Mar 24, 2022

roberth Mar 24, 2022

infinisil Mar 24, 2022

roberth Mar 24, 2022

infinisil Apr 5, 2022

nixos-discourse commented Apr 1, 2022

infinisil commented Apr 5, 2022

roberth left a comment

roberth Apr 5, 2022

roberth Apr 5, 2022

pennae Apr 5, 2022

roberth Apr 5, 2022

infinisil Apr 5, 2022

roberth Apr 5, 2022

roberth Apr 5, 2022

roberth commented Apr 7, 2022

-                 <varname>config</varname>: The results of all options after merging the values from all modules together.
+                 <varname>config</varname>: The results of all options after merging the values from all modules together. In the context of a submodule, "all modules" does not include the parent module that contains the submodule.
+               </para>
+               <para>
+                 The module arguments of the parent can be accessed through the lexical scope instead.

	<varname>options</varname>: The options declared in all modules.
	<varname>options</varname>: The options declared in all modules, where "all modules" is defined the same as in <varname>config</varname>.

lib/modules: Document _module.args #165540

lib/modules: Document _module.args #165540

Conversation

infinisil commented Mar 24, 2022 • edited Loading

Description of changes

Things done

pennae left a comment

Choose a reason for hiding this comment

roberth left a comment • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nixos-discourse commented Apr 1, 2022

infinisil commented Apr 5, 2022

roberth left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

roberth commented Apr 7, 2022

lib/modules: Document `_module.args` #165540

lib/modules: Document `_module.args` #165540

infinisil commented Mar 24, 2022 •

edited

Loading

roberth left a comment •

edited

Loading