lib/modules: Document _module.args

[infinisil]

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

Ping @roberth

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.

[roberth]

We actually need to discourage use of module arguments :(

[roberth]

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

[roberth]

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.

[infinisil]

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.

[infinisil]

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

[roberth]

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.

[infinisil]

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

[roberth]

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.

[infinisil]

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

[nixos-discourse]

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

[infinisil]

@roberth Good to merge?

[roberth]

One final thing it seems.
Otherwise lgtm.

[roberth]

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.

[roberth]

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.

[pennae]

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

[roberth]

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".

[infinisil]

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.

[roberth]

fair enough 🚀

[roberth]

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]

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