From 1de329f5e181b4e46607934ef323f4931803e42b Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Tue, 15 Apr 2025 13:20:40 +0200
Subject: [PATCH] doc: Module arguments

---
 doc/module-system/module-system.chapter.md | 45 ++++++++++++++++++++++
 doc/redirects.json                         | 18 +++++++++
 2 files changed, 63 insertions(+)

diff --git a/doc/module-system/module-system.chapter.md b/doc/module-system/module-system.chapter.md
index 0c91012eebb4..eaeda870def6 100644
--- a/doc/module-system/module-system.chapter.md
+++ b/doc/module-system/module-system.chapter.md
@@ -115,3 +115,48 @@ A nominal type marker, always `"configuration"`.
 #### `class` {#module-system-lib-evalModules-return-value-_configurationClass}
 
 The [`class` argument](#module-system-lib-evalModules-param-class).
+
+## Module arguments {#module-system-module-arguments}
+
+Module arguments are the attribute values passed to modules when they are evaluated.
+
+They originate from these sources:
+1. Built-in arguments
+  - `lib`,
+  - `config`,
+  - `options`,
+  - `_class`,
+  - `_prefix`,
+2. Attributes from the [`specialArgs`] which were passed to [`evalModules`] or `submoduleWith`. These are application-specific.
+3. Attributes from the `_module.args` option value. These are application-specific and can be provided by any module.
+
+The prior two categories are available while evaluating the `imports`, whereas
+the last category is only available after the `imports` have been resolved.
+
+### `lib` {#module-system-module-argument-lib}
+
+A reference to the Nixpkgs library.
+
+### `config` {#module-system-module-argument-config}
+
+All option values.
+Unlike the `evalModules` [`config` return attribute](#module-system-lib-evalModules-return-value-config), this includes `_module`.
+
+### `options` {#module-system-module-argument-options}
+
+All evaluated option declarations.
+
+### `_class` {#module-system-module-argument-_class}
+
+The [expected class](#module-system-lib-evalModules-param-class) of the loaded modules.
+
+### `_prefix` {#module-system-module-argument-_prefix}
+
+The location under which the module is evaluated. This is used to improve error reporting and find the implicit `name` module argument in submodules.
+
+It is a good practice not to rely on `_prefix`. A module should not make assumptions about its location in the configuration tree.
+For example, the root of a NixOS configuration may have a non-empty prefix, for example when it is a specialisation, or when it is part of a larger, multi-host configuration such as a [NixOS test](https://nixos.org/manual/nixos/unstable/#sec-nixos-tests).
+Any dependencies on `_prefix` should be replaced with explicit options, whose default definitions can be provided by the module that imports them.
+
+[`evalModules`]: #module-system-lib-evalModules
+[`specialArgs`]: #module-system-lib-evalModules-param-specialArgs
diff --git a/doc/redirects.json b/doc/redirects.json
index 2a8069a490bb..714e4a691753 100644
--- a/doc/redirects.json
+++ b/doc/redirects.json
@@ -4363,5 +4363,23 @@
   ],
   "sec-interop.cylonedx-fod": [
     "index.html#sec-interop.cylonedx-fod"
+  ],
+  "module-system-module-argument-_prefix": [
+    "index.html#module-system-module-argument-_prefix"
+  ],
+  "module-system-module-argument-lib": [
+    "index.html#module-system-module-argument-lib"
+  ],
+  "module-system-module-argument-config": [
+    "index.html#module-system-module-argument-config"
+  ],
+  "module-system-module-arguments": [
+    "index.html#module-system-module-arguments"
+  ],
+  "module-system-module-argument-_class": [
+    "index.html#module-system-module-argument-_class"
+  ],
+  "module-system-module-argument-options": [
+    "index.html#module-system-module-argument-options"
   ]
 }