From 33daa3f4b9104b55d11740277d0182cb23fcde07 Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Tue, 18 Mar 2025 15:02:12 +0000
Subject: [PATCH] lib.modules: init test for lib.mkDefinition

---
 lib/modules.nix                               |  2 -
 lib/tests/modules.sh                          |  8 +++
 lib/tests/modules/mkDefinition.nix            | 71 +++++++++++++++++++
 .../manual/development/option-def.section.md  | 20 +++++-
 4 files changed, 98 insertions(+), 3 deletions(-)
 create mode 100644 lib/tests/modules/mkDefinition.nix

diff --git a/lib/modules.nix b/lib/modules.nix
index 3d57c3dd062d..7716e855ebb2 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -1177,8 +1177,6 @@ let
       map (mapAttrs (n: v: mkIf cfg.condition v)) (pushDownProperties cfg.content)
     else if cfg._type or "" == "override" then
       map (mapAttrs (n: v: mkOverride cfg.priority v)) (pushDownProperties cfg.content)
-    # else if cfg._type or "" == "definition" then
-    #   map (mapAttrs (n: v: mkDefinition v)) (pushDownProperties cfg.content)
     # FIXME: handle mkOrder?
     else
       [ cfg ];
diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index e623c0fb55b8..9df6e61797b7 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -673,6 +673,14 @@ checkConfigError 'The option .conflictingPathOptionType. in .*/pathWith.nix. is
 # types.pathWith { inStore = true; absolute = false; }
 checkConfigError 'In pathWith, inStore means the path must be absolute' config.impossiblePathOptionType ./pathWith.nix
 
+# mkDefinition
+# check that mkDefinition 'file' is printed in the error message
+checkConfigError 'Cannot merge definitions.*\n\s*- In .file.*\n\s*- In .other.*' config.conflict ./mkDefinition.nix
+checkConfigError 'A definition for option .viaOptionDefault. is not of type .boolean.*' config.viaOptionDefault ./mkDefinition.nix
+checkConfigOutput '^true$' config.viaConfig ./mkDefinition.nix
+checkConfigOutput '^true$' config.mkMerge ./mkDefinition.nix
+checkConfigOutput '^true$' config.mkForce ./mkDefinition.nix
+
 cat <<EOF
 ====== module tests ======
 $pass Pass
diff --git a/lib/tests/modules/mkDefinition.nix b/lib/tests/modules/mkDefinition.nix
new file mode 100644
index 000000000000..0a807090fa28
--- /dev/null
+++ b/lib/tests/modules/mkDefinition.nix
@@ -0,0 +1,71 @@
+{ lib, ... }:
+let
+  inherit (lib)
+    mkOption
+    mkDefinition
+    mkOptionDefault
+    ;
+in
+{
+  imports = [
+    {
+      _file = "file";
+      options.conflict = mkOption {
+        default = 1;
+      };
+      config.conflict = mkDefinition {
+        file = "other";
+        value = mkOptionDefault 42;
+      };
+    }
+    {
+      # Check that mkDefinition works within 'config'
+      options.viaConfig = mkOption { };
+      config.viaConfig = mkDefinition {
+        file = "other";
+        value = true;
+      };
+    }
+    {
+      # Check mkMerge can wrap mkDefinitions
+      # Not the other way around
+      options.mkMerge = mkOption {
+        type = lib.types.bool;
+      };
+      config.mkMerge = lib.mkMerge [
+        (mkDefinition {
+          file = "a.nix";
+          value = true;
+        })
+        (mkDefinition {
+          file = "b.nix";
+          value = true;
+        })
+      ];
+    }
+    {
+      # Check mkDefinition can use mkForce on the value
+      # Not the other way around
+      options.mkForce = mkOption {
+        type = lib.types.bool;
+        default = false;
+      };
+      config.mkForce = mkDefinition {
+        file = "other";
+        value = lib.mkForce true;
+      };
+    }
+    {
+      # Currently expects an error
+      # mkDefinition doesn't work on option default
+      # This is a limitation and might be resolved in the future
+      options.viaOptionDefault = mkOption {
+        type = lib.types.bool;
+        default = mkDefinition {
+          file = "other";
+          value = true;
+        };
+      };
+    }
+  ];
+}
diff --git a/nixos/doc/manual/development/option-def.section.md b/nixos/doc/manual/development/option-def.section.md
index 6ab5b7dc96de..fddcfef393ae 100644
--- a/nixos/doc/manual/development/option-def.section.md
+++ b/nixos/doc/manual/development/option-def.section.md
@@ -139,7 +139,25 @@ A free-floating definition is created with `mkDefinition { file = ...; value = .
 
 Preserving the file location creates better error messages, for example when copying definitions from one option to another.
 
-Other properties like `mkOverride` `mkMerge` `mkAfter` can be used in the `value` attribute but not the other way around.
+Other properties like `mkOverride` `mkMerge` `mkAfter` can be used in the `value` attribute but not on the entire definition.
+
+This is what would work
+
+```nix
+mkDefinition {
+   value = mkForce 42;
+   file = "somefile.nix";
+}
+```
+
+While this would NOT work.
+
+```nix
+mkForce (mkDefinition {
+   value = 42;
+   file = "somefile.nix";
+})
+```
 
 The following shows an example configuration that yields an error with the custom position information: