From 5cbeddfde486ca5524baeaf3da6e8944075cf463 Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <contact@infinisil.com>
Date: Wed, 8 Dec 2021 19:02:29 +0100
Subject: [PATCH 1/2] lib.types: Introduce `types.optionType`

This type correctly merges multiple option types together while also
annotating them with file information. In a future commit this will be
used for `_module.freeformType`
---
 lib/tests/modules.sh                          |  7 +++++
 lib/tests/modules/optionTypeFile.nix          | 28 +++++++++++++++++
 lib/tests/modules/optionTypeMerging.nix       | 27 ++++++++++++++++
 lib/types.nix                                 | 31 ++++++++++++++++++-
 .../development/option-types.section.md       |  7 +++++
 .../development/option-types.section.xml      | 14 +++++++++
 6 files changed, 113 insertions(+), 1 deletion(-)
 create mode 100644 lib/tests/modules/optionTypeFile.nix
 create mode 100644 lib/tests/modules/optionTypeMerging.nix

diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index a1c592cf4ef0..d11f32e59964 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -299,6 +299,13 @@ checkConfigOutput "10" config.processedToplevel ./raw.nix
 checkConfigError "The option .multiple. is defined multiple times" config.multiple ./raw.nix
 checkConfigOutput "bar" config.priorities ./raw.nix
 
+# Test that types.optionType merges types correctly
+checkConfigOutput '^10$' config.theOption.int ./optionTypeMerging.nix
+checkConfigOutput '^"hello"$' config.theOption.str ./optionTypeMerging.nix
+
+# Test that types.optionType correctly annotates option locations
+checkConfigError 'The option .theOption.nested. in .other.nix. is already declared in .optionTypeFile.nix.' config.theOption.nested ./optionTypeFile.nix
+
 cat <<EOF
 ====== module tests ======
 $pass Pass
diff --git a/lib/tests/modules/optionTypeFile.nix b/lib/tests/modules/optionTypeFile.nix
new file mode 100644
index 000000000000..6015d59a72c9
--- /dev/null
+++ b/lib/tests/modules/optionTypeFile.nix
@@ -0,0 +1,28 @@
+{ config, lib, ... }: {
+
+  _file = "optionTypeFile.nix";
+
+  options.theType = lib.mkOption {
+    type = lib.types.optionType;
+  };
+
+  options.theOption = lib.mkOption {
+    type = config.theType;
+    default = {};
+  };
+
+  config.theType = lib.mkMerge [
+    (lib.types.submodule {
+      options.nested = lib.mkOption {
+        type = lib.types.int;
+      };
+    })
+    (lib.types.submodule {
+      _file = "other.nix";
+      options.nested = lib.mkOption {
+        type = lib.types.str;
+      };
+    })
+  ];
+
+}
diff --git a/lib/tests/modules/optionTypeMerging.nix b/lib/tests/modules/optionTypeMerging.nix
new file mode 100644
index 000000000000..74a620c4620c
--- /dev/null
+++ b/lib/tests/modules/optionTypeMerging.nix
@@ -0,0 +1,27 @@
+{ config, lib, ... }: {
+
+  options.theType = lib.mkOption {
+    type = lib.types.optionType;
+  };
+
+  options.theOption = lib.mkOption {
+    type = config.theType;
+  };
+
+  config.theType = lib.mkMerge [
+    (lib.types.submodule {
+      options.int = lib.mkOption {
+        type = lib.types.int;
+        default = 10;
+      };
+    })
+    (lib.types.submodule {
+      options.str = lib.mkOption {
+        type = lib.types.str;
+      };
+    })
+  ];
+
+  config.theOption.str = "hello";
+
+}
diff --git a/lib/types.nix b/lib/types.nix
index c47a35cd0d67..acc7eac104ee 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -61,7 +61,11 @@ let
     boolToString
     ;
 
-  inherit (lib.modules) mergeDefinitions;
+  inherit (lib.modules)
+    mergeDefinitions
+    fixupOptionType
+    mergeOptionDecls
+    ;
   outer_types =
 rec {
   isType = type: x: (x._type or "") == type;
@@ -525,6 +529,31 @@ rec {
       modules = toList modules;
     };
 
+    # The type of a type!
+    optionType = mkOptionType {
+      name = "optionType";
+      description = "optionType";
+      check = value: value._type or null == "option-type";
+      merge = loc: defs:
+        let
+          # Prepares the type definitions for mergeOptionDecls, which
+          # annotates submodules types with file locations
+          optionModules = map ({ value, file }:
+            {
+              _file = file;
+              # There's no way to merge types directly from the module system,
+              # but we can cheat a bit by just declaring an option with the type
+              options = lib.mkOption {
+                type = value;
+              };
+            }
+          ) defs;
+          # Merges all the types into a single one, including submodule merging.
+          # This also propagates file information to all submodules
+          mergedOption = fixupOptionType loc (mergeOptionDecls loc optionModules);
+        in mergedOption.type;
+    };
+
     submoduleWith =
       { modules
       , specialArgs ? {}
diff --git a/nixos/doc/manual/development/option-types.section.md b/nixos/doc/manual/development/option-types.section.md
index 78ace62e8f17..071e7751eb67 100644
--- a/nixos/doc/manual/development/option-types.section.md
+++ b/nixos/doc/manual/development/option-types.section.md
@@ -74,6 +74,13 @@ merging is handled.
     should only be used when checking, merging and nested evaluation are not
     desirable.
 
+`types.optionType`
+
+:   The type of an option's type. Its merging operation ensures that nested
+    options have the correct file location annotated, and that if possible,
+    multiple option definitions are correctly merged together. The main use
+    case is as the type of the `_module.freeformType` option.
+
 `types.attrs`
 
 :   A free-form attribute set.
diff --git a/nixos/doc/manual/from_md/development/option-types.section.xml b/nixos/doc/manual/from_md/development/option-types.section.xml
index 90ef05a24e77..50a3da0ef5bb 100644
--- a/nixos/doc/manual/from_md/development/option-types.section.xml
+++ b/nixos/doc/manual/from_md/development/option-types.section.xml
@@ -111,6 +111,20 @@
           </para>
         </listitem>
       </varlistentry>
+      <varlistentry>
+        <term>
+          <literal>types.optionType</literal>
+        </term>
+        <listitem>
+          <para>
+            The type of an option’s type. Its merging operation ensures
+            that nested options have the correct file location
+            annotated, and that if possible, multiple option definitions
+            are correctly merged together. The main use case is as the
+            type of the <literal>_module.freeformType</literal> option.
+          </para>
+        </listitem>
+      </varlistentry>
       <varlistentry>
         <term>
           <literal>types.attrs</literal>

From 023fa7b9239e645f7dfcbbe3ee82ab0093f9978d Mon Sep 17 00:00:00 2001
From: Silvan Mosberger <contact@infinisil.com>
Date: Wed, 8 Dec 2021 19:13:14 +0100
Subject: [PATCH 2/2] lib.modules: Use types.optionType for
 _module.freeformType

This ensures that the module file locations are propagated to the
freeform type, which makes it so that submodules in freeform types now
have their declaration location shown in the manual, fixing
https://github.com/NixOS/nixpkgs/issues/132085.

In addition, this also newly allows freeformTypes to be declared
multiple times and all declarations being merged together according to
normal option merging.

This also removes some awkwardness regarding the type of `freeformType`
---
 lib/modules.nix                           |  3 +--
 lib/tests/modules.sh                      |  5 +++++
 lib/tests/modules/freeform-submodules.nix | 22 ++++++++++++++++++++++
 3 files changed, 28 insertions(+), 2 deletions(-)
 create mode 100644 lib/tests/modules/freeform-submodules.nix

diff --git a/lib/modules.nix b/lib/modules.nix
index e9fc1007fc20..79d54e4a5387 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -151,8 +151,7 @@ rec {
           };
 
           _module.freeformType = mkOption {
-            # Disallow merging for now, but could be implemented nicely with a `types.optionType`
-            type = types.nullOr (types.uniq types.attrs);
+            type = types.nullOr types.optionType;
             internal = true;
             default = null;
             description = ''
diff --git a/lib/tests/modules.sh b/lib/tests/modules.sh
index d11f32e59964..e4bb7ad21900 100755
--- a/lib/tests/modules.sh
+++ b/lib/tests/modules.sh
@@ -240,6 +240,11 @@ checkConfigOutput '^"24"$' config.foo ./freeform-attrsOf.nix ./freeform-str-dep-
 checkConfigError 'infinite recursion encountered' config.foo ./freeform-attrsOf.nix ./freeform-unstr-dep-str.nix
 checkConfigError 'The option .* is used but not defined' config.foo ./freeform-lazyAttrsOf.nix ./freeform-unstr-dep-str.nix
 checkConfigOutput '^"24"$' config.foo ./freeform-lazyAttrsOf.nix ./freeform-unstr-dep-str.nix ./define-value-string.nix
+# submodules in freeformTypes should have their locations annotated
+checkConfigOutput '/freeform-submodules.nix"$' config.fooDeclarations.0 ./freeform-submodules.nix
+# freeformTypes can get merged using `types.type`, including submodules
+checkConfigOutput '^10$' config.free.xxx.foo ./freeform-submodules.nix
+checkConfigOutput '^10$' config.free.yyy.bar ./freeform-submodules.nix
 
 ## types.anything
 # Check that attribute sets are merged recursively
diff --git a/lib/tests/modules/freeform-submodules.nix b/lib/tests/modules/freeform-submodules.nix
new file mode 100644
index 000000000000..3910435a7b5c
--- /dev/null
+++ b/lib/tests/modules/freeform-submodules.nix
@@ -0,0 +1,22 @@
+{ lib, options, ... }: with lib.types; {
+
+  options.fooDeclarations = lib.mkOption {
+    default = (options.free.type.getSubOptions [])._freeformOptions.foo.declarations;
+  };
+
+  options.free = lib.mkOption {
+    type = submodule {
+      config._module.freeformType = lib.mkMerge [
+        (attrsOf (submodule {
+          options.foo = lib.mkOption {};
+        }))
+        (attrsOf (submodule {
+          options.bar = lib.mkOption {};
+        }))
+      ];
+    };
+  };
+
+  config.free.xxx.foo = 10;
+  config.free.yyy.bar = 10;
+}