modules/nixpkgs: add useGlobalPackages option

wrappers/_shared.nix

@@ -23,30 +23,33 @@ let
     map
     mkIf
     mkMerge
-    mkOption
     optionalAttrs
     setAttrByPath
     ;
   cfg = config.programs.nixvim;
+
+  # FIXME: buildPlatform can't use mkOptionDefault because it already defaults to hostPlatform
+  buildPlatformPrio = (lib.mkOptionDefault null).priority - 1;
+
+  nixpkgsModule =
+    { config, ... }:
+    {
+      _file = ./_shared.nix;
+      nixpkgs = {
+        # Use global packages in nixvim's submodule
+        pkgs = lib.mkIf config.nixpkgs.useGlobalPackages (lib.mkDefault pkgs);
+
+        # Inherit platform spec
+        hostPlatform = lib.mkOptionDefault pkgs.stdenv.hostPlatform;
+        buildPlatform = lib.mkOverride buildPlatformPrio pkgs.stdenv.buildPlatform;
+      };
+    };
+
   nixvimConfiguration = config.lib.nixvim.modules.evalNixvim (
     evalArgs
     // {
       modules = evalArgs.modules or [ ] ++ [
-        {
-          _file = ./_shared.nix;
-
-          nixpkgs = {
-            # Use global packages by default in nixvim's submodule
-            # TODO: `useGlobalPackages` option and/or deprecate using host packages?
-            pkgs = lib.mkDefault pkgs;
-
-            # Inherit platform spec
-            # FIXME: buildPlatform can't use option-default because it already has a default
-            #        (it defaults to hostPlatform)...
-            hostPlatform = lib.mkOptionDefault pkgs.stdenv.hostPlatform;
-            buildPlatform = lib.mkDefault pkgs.stdenv.buildPlatform;
-          };
-        }
+        nixpkgsModule
       ];
     }
   );

wrappers/modules/nixpkgs.nix

@@ -0,0 +1,83 @@
+{
+  lib,
+  config,
+  options,
+  ...
+}:
+let
+  cfg = config.nixpkgs;
+  opts = options.nixpkgs;
+  argOpts = lib.modules.mergeAttrDefinitionsWithPrio options._module.args;
+
+  normalPrio = lib.modules.defaultOverridePriority;
+  defaultPrio = (lib.mkDefault null).priority;
+  optionDefaultPrio = (lib.mkOptionDefault null).priority;
+  # FIXME: buildPlatform can't use mkOptionDefault because it already defaults to hostPlatform
+  buildPlatformPrio = optionDefaultPrio - 1;
+
+  mkGlobalPackagesAssertion =
+    {
+      assertion,
+      option ? null,
+      loc ? option.loc,
+      issue ? "is overridden",
+    }:
+    {
+      assertion = cfg.useGlobalPackages -> assertion;
+      message =
+        "`${lib.showOption opts.useGlobalPackages.loc}' is enabled, "
+        + "but `${lib.showOption loc}' ${issue}. "
+        + lib.optionalString (
+          option != null
+        ) "Definition values:${lib.options.showDefs option.definitionsWithLocations}";
+    };
+in
+{
+  options = {
+    nixpkgs.useGlobalPackages = lib.mkOption {
+      type = lib.types.bool;
+      default = true; # TODO: Added 2025-01-15; switch to false one release after adding a deprecation warning
+      defaultText = lib.literalMD ''`true`, but will change to `false` in a future version.'';
+      description = ''
+        Whether Nixvim should use the ${config.meta.wrapper.name} configuration's `pkgs`,
+        instead of constructing its own instance.
+      '';
+    };
+  };
+
+  config = {
+    assertions = map mkGlobalPackagesAssertion [
+      {
+        assertion = opts.pkgs.highestPrio == defaultPrio;
+        option = opts.pkgs;
+        issue = "is overridden";
+      }
+      {
+        assertion = argOpts.pkgs.highestPrio == normalPrio;
+        # FIXME: can't showDefs for an attrOf an option
+        loc = options._module.args.loc ++ [ "pkgs" ];
+        issue = "is overridden";
+      }
+      {
+        assertion = opts.hostPlatform.highestPrio == optionDefaultPrio;
+        option = opts.hostPlatform;
+        issue = "is overridden";
+      }
+      {
+        assertion = opts.buildPlatform.highestPrio == buildPlatformPrio;
+        option = opts.buildPlatform;
+        issue = "is overridden";
+      }
+      {
+        assertion = cfg.config == { };
+        option = opts.config;
+        issue = "is not empty";
+      }
+      {
+        assertion = cfg.overlays == [ ];
+        option = opts.overlays;
+        issue = "is not empty";
+      }
+    ];
+  };
+}

wrappers/modules/shared.nix

@@ -11,4 +11,8 @@
       };
     };
   };
+
+  imports = [
+    ./nixpkgs.nix
+  ];
 }