lib/eval-config: document NIXOS_EXTRA_MODULE_PATH

This adds some documentation about importing modules external to
Nixpkgs, which provides context for documenting
NIXOS_EXTRA_MODULE_PATH.

Closes #30376

2 files changed, 60 insertions, 0 deletions

diff --git a/nixos/doc/manual/development/importing-modules.xml b/nixos/doc/manual/development/importing-modules.xml
new file mode 100644
index 00000000000..ec1da09b950
--- /dev/null
+++ b/nixos/doc/manual/development/importing-modules.xml
@@ -0,0 +1,59 @@
+<section xmlns="http://docbook.org/ns/docbook"
+         xmlns:xlink="http://www.w3.org/1999/xlink"
+         xmlns:xi="http://www.w3.org/2001/XInclude"
+         version="5.0"
+         xml:id="sec-importing-modules">
+
+<title>Importing Modules</title>
+
+<para>
+  Sometimes NixOS modules need to be used in configuration but exist
+  outside of Nixpkgs. These modules can be imported:
+</para>
+
+<programlisting>
+{ config, lib, pkgs, ... }:
+
+{
+  imports =
+    [ # Use a locally-available module definition in
+      # ./example-module/default.nix
+        ./example-module
+    ];
+
+  services.exampleModule.enable = true;
+}
+</programlisting>
+
+<para>
+  The environment variable <literal>NIXOS_EXTRA_MODULE_PATH</literal> is
+  an absolute path to a NixOS module that is included alongside the
+  Nixpkgs NixOS modules. Like any NixOS module, this module can import
+  additional modules:
+</para>
+
+<programlisting>
+# ./module-list/default.nix
+[
+  ./example-module1
+  ./example-module2
+]
+</programlisting>
+
+<programlisting>
+# ./extra-module/default.nix
+{ imports = import ./module-list.nix; }
+</programlisting>
+
+<programlisting>
+# NIXOS_EXTRA_MODULE_PATH=/absolute/path/to/extra-module
+{ config, lib, pkgs, ... }:
+
+{
+  # No `imports` needed
+
+  services.exampleModule1.enable = true;
+}
+</programlisting>
+
+</section>
diff --git a/nixos/doc/manual/development/writing-modules.xml b/nixos/doc/manual/development/writing-modules.xml
index cb363b45675..a49f99cb266 100644
--- a/nixos/doc/manual/development/writing-modules.xml
+++ b/nixos/doc/manual/development/writing-modules.xml
@@ -180,6 +180,7 @@ in {
 <xi:include href="option-def.xml" />
 <xi:include href="assertions.xml" />
 <xi:include href="meta-attributes.xml" />
+<xi:include href="importing-modules.xml" />
 <xi:include href="replace-modules.xml" />
 
 </chapter>