From 5f197bf5d0eaee359dc5c3eb4deabf1654c81b72 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Fri, 18 Oct 2024 16:54:07 +0200
Subject: [PATCH] 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
---
 .../development/importing-modules.section.md  | 28 -------------------
 .../development/meta-attributes.section.md    |  2 +-
 nixos/lib/eval-config.nix                     | 25 +++++++++++++++--
 3 files changed, 24 insertions(+), 31 deletions(-)

diff --git a/nixos/doc/manual/development/importing-modules.section.md b/nixos/doc/manual/development/importing-modules.section.md
index 65d78959b8e0..32556b9bf192 100644
--- a/nixos/doc/manual/development/importing-modules.section.md
+++ b/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;
-}
-```
diff --git a/nixos/doc/manual/development/meta-attributes.section.md b/nixos/doc/manual/development/meta-attributes.section.md
index b2ad23e58b94..fc0f7ae268de 100644
--- a/nixos/doc/manual/development/meta-attributes.section.md
+++ b/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
diff --git a/nixos/lib/eval-config.nix b/nixos/lib/eval-config.nix
index 8bab3752073f..66ad9dba700a 100644
--- a/nixos/lib/eval-config.nix
+++ b/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";
-                 in lib.optional (e != "") (import e)
+, extraModules ?
+    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