nixos/eval-config: Deprecate NIXOS_EXTRA_MODULE_PATH

This gets rid of a potentially confusing behavior that doesn't need to
be in NixOS, and nobody ever bothered to add a test for it.
Let's keep things simple!
The suggested snippet is better than this feature ever was, and will be
in the user's face, where it belongs, kindly.

Tested with

    nix-instantiate nixos/lib/eval-config.nix --arg modules '[{fileSystems."/".device="x";boot.loader.grub.enable=false;}]' -A config.system.build.toplevel
    NIXOS_EXTRA_MODULE_PATH=$HOME/whatever.nix nix-instantiate nixos/lib/eval-config.nix --arg modules '[{fileSystems."/".device="x";boot.loader.grub.enable=false;}]' -A config.system.build.toplevel

nixos/doc/manual/development/importing-modules.section.md

@@ -16,31 +16,3 @@ outside of Nixpkgs. These modules can be imported:
   services.exampleModule.enable = true;
 }
 ```
-
-The environment variable `NIXOS_EXTRA_MODULE_PATH` 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:
-
-```nix
-# ./module-list/default.nix
-[
-  ./example-module1
-  ./example-module2
-]
-```
-
-```nix
-# ./extra-module/default.nix
-{ imports = import ./module-list.nix; }
-```
-
-```nix
-# NIXOS_EXTRA_MODULE_PATH=/absolute/path/to/extra-module
-{ config, lib, pkgs, ... }:
-
-{
-  # No `imports` needed
-
-  services.exampleModule1.enable = true;
-}
-```

nixos/doc/manual/development/meta-attributes.section.md

@@ -45,7 +45,7 @@ file.
 -  `buildDocsInSandbox` indicates whether the option documentation for the
    module can be built in a derivation sandbox. This option is currently only
    honored for modules shipped by nixpkgs. User modules and modules taken from
-   `NIXOS_EXTRA_MODULE_PATH` are always built outside of the sandbox, as has
+   `extraModules` are always built outside of the sandbox, as has
    been the case in previous releases.
 
    Building NixOS option documentation in a sandbox allows caching of the built

nixos/lib/eval-config.nix

@@ -30,8 +30,29 @@ evalConfigArgs@
   check ? true
 , prefix ? []
 , lib ? import ../../lib
-, extraModules ? let e = builtins.getEnv "NIXOS_EXTRA_MODULE_PATH";
+, extraModules ?
-                 in lib.optional (e != "") (import e)
+    let e = builtins.getEnv "NIXOS_EXTRA_MODULE_PATH";
+    in lib.optional (e != "") (
+      lib.warn
+        ''
+          The NIXOS_EXTRA_MODULE_PATH environment variable is deprecated and will be
+          removed in NixOS 25.05.
+          We recommend a workflow where you update the expression files instead, but
+          if you wish to continue to use this variable, you may do so with a module like:
+
+          {
+            imports = [
+              (builtins.getEnv "NIXOS_EXTRA_MODULE_PATH")
+            ];
+          }
+
+          This has the benefit that your configuration hints at the
+          non-standard workflow.
+        ''
+        # NOTE: this import call is unnecessary and it even removes the file name
+        #       from error messages.
+        import e
+    )
 }:
 
 let