modules/nixpkgs: initial pkgs option; drop defaultPkgs specialArg

docs/default.nix

@@ -34,11 +34,11 @@ let
     };
 
   evaledModules = helpers.modules.evalNixvim {
-    extraSpecialArgs = {
-      defaultPkgs = pkgs;
-    };
     modules = [
-      { isDocs = true; }
+      {
+        isDocs = true;
+        nixpkgs.pkgs = pkgs;
+      }
     ];
   };
 

flake-modules/legacy-packages.nix

@@ -3,6 +3,7 @@
   perSystem =
     {
       pkgs,
+      lib,
       makeNixvimWithModule,
       ...
     }:
@@ -12,9 +13,12 @@
         makeNixvim = module: makeNixvimWithModule { inherit module; };
 
         nixvimConfiguration = helpers.modules.evalNixvim {
-          extraSpecialArgs = {
-            defaultPkgs = pkgs;
-          };
+          modules = [
+            {
+              _file = ./legacy-packages.nix;
+              nixpkgs.pkgs = lib.mkDefault pkgs;
+            }
+          ];
         };
       };
     };

lib/default.nix

@@ -38,24 +38,12 @@ lib.fix (
     extendedLib = call ./extend-lib.nix { inherit lib; };
     keymaps = call ./keymap-helpers.nix { };
     lua = call ./to-lua.nix { };
+    modules = call ./modules.nix { };
     neovim-plugin = call ./neovim-plugin.nix { };
     options = call ./options.nix { };
     utils = call ./utils.nix { inherit _nixvimTests; };
     vim-plugin = call ./vim-plugin.nix { };
 
-    # Handle modules, which currently requires a `defaultPkgs` specialArg
-    # FIXME: our minimal specialArgs should not need `pkgs`
-    modules = call ./modules.nix { } // {
-      # Minimal specialArgs required to evaluate nixvim modules
-      specialArgs = self.modules.specialArgsWith {
-        defaultPkgs =
-          if pkgs == null then
-            throw "`modules.specialArgs` cannot currently be used when nixvim's lib is built without a `pkgs` instance. This will be resolved in the future."
-          else
-            pkgs;
-      };
-    };
-
     # Handle builders, which has some deprecated stuff that depends on `pkgs`
     builders = builders // deprecatedBuilders;
     inherit (self.builders)

lib/modules.nix

@@ -2,19 +2,16 @@
   lib,
   self,
 }:
-rec {
-  # Build specialArgs for evaluating nixvim modules
-  specialArgsWith =
-    # TODO: switch defaultPkgs -> pkgsPath (i.e. pkgs.path or inputs.nixvim)
-    # FIXME: Ideally, we should not require callers to pass in _anything_ specific
-    { defaultPkgs, ... }@extraSpecialArgs:
-    {
-      inherit lib defaultPkgs;
-      # TODO: deprecate `helpers`
-      helpers = self;
-    }
-    // extraSpecialArgs;
-
+let
+  removed = {
+    # Removed 2024-09-24
+    getAssertionMessages = "";
+    # Removed 2024-09-27
+    specialArgs = "It has been integrated into `evalNixvim`";
+    specialArgsWith = "It has been integrated into `evalNixvim`";
+  };
+in
+{
   # Evaluate nixvim modules, checking warnings and assertions
   evalNixvim =
     {
@@ -28,9 +25,14 @@ rec {
       "`evalNixvim`: passing `check` is no longer supported. Checks are now done when evaluating `config.build.package` and can be avoided by using `config.build.packageUnchecked` instead.";
     lib.evalModules {
       modules = [ ../modules/top-level ] ++ modules;
-      specialArgs = specialArgsWith extraSpecialArgs;
+      specialArgs = {
+        inherit lib;
+        # TODO: deprecate `helpers`
+        helpers = self;
+      } // extraSpecialArgs;
     };
-
-  # TODO: Removed 2024-09-24
-  getAssertionMessages = throw "`modules.getAssertionMessages` has been removed.";
 }
+// lib.mapAttrs (
+  name: msg:
+  throw ("`modules.${name}` has been removed." + lib.optionalString (msg != "") (" " + msg))
+) removed

lib/tests.nix

@@ -62,10 +62,11 @@ let
               { config.test.runNvim = !dontRun; }
           ))
           { wrapRc = true; }
+          # TODO: Only do this when `args?pkgs`
+          # Consider deprecating the `pkgs` arg too...
+          { nixpkgs.pkgs = lib.mkDefault pkgs; }
         ];
-        extraSpecialArgs = {
-          defaultPkgs = pkgs;
-        } // extraSpecialArgs;
+        inherit extraSpecialArgs;
       };
     in
     result.config.build.test;

modules/misc/default.nix

@@ -3,7 +3,6 @@
     ./assertions.nix
     ./context.nix
     ./meta.nix
-    ./nixpkgs.nix
     ./nixvim-info.nix
   ];
 }

modules/top-level/default.nix

@@ -7,6 +7,7 @@
   imports = [
     ../.
     ./files
+    ./nixpkgs.nix
     ./output.nix
     ./readonly-renames.nix
     ./test.nix

modules/top-level/files/default.nix

@@ -15,6 +15,15 @@ let
     modules = lib.optionals (!config.isDocs) [
       ../../.
       ./submodule.nix
+      # Pass module args through to the submodule (except `name`)
+      # Wrap each arg with the correct priority
+      {
+        _module.args = lib.pipe options._module.args [
+          lib.modules.mergeAttrDefinitionsWithPrio
+          (lib.flip builtins.removeAttrs [ "name" ])
+          (lib.mapAttrs (_: { highestPrio, value }: lib.mkOverride highestPrio value))
+        ];
+      }
     ];
     description = "Nixvim configuration";
   };

modules/top-level/nixpkgs.nix

@@ -0,0 +1,85 @@
+{
+  config,
+  options,
+  lib,
+  ...
+}:
+let
+  cfg = config.nixpkgs;
+  opt = options.nixpkgs;
+in
+{
+  options.nixpkgs = {
+    pkgs = lib.mkOption {
+      # TODO:
+      # defaultText = lib.literalExpression ''
+      #   import "''${nixos}/.." {
+      #     inherit (cfg) config overlays localSystem crossSystem;
+      #   }
+      # '';
+      defaultText = lib.literalMD ''
+        The `pkgs` inherited from your host config (i.e. NixOS, home-manager, or nix-darwin),
+        or the `pkgs` supplied to `makeNixvimWithModule` when building a standalone nixvim.
+
+        > [!CAUTION]
+        > This default will be removed in a future version of nixvim
+      '';
+      type = lib.types.pkgs // {
+        description = "An evaluation of Nixpkgs; the top level attribute set of packages";
+      };
+      example = lib.literalExpression "import <nixpkgs> { }";
+      description = ''
+        If set, the `pkgs` argument to all Nixvim modules is the value of this option.
+
+        <!-- TODO: remove -->
+        If unset, an assertion will trigger. In the future a `pkgs` instance will be constructed.
+
+        <!--
+          TODO:
+          If unset, the pkgs argument is determined as shown in the default value for this option.
+
+          TODO:
+          The default value imports the Nixpkgs input specified in Nixvim's `flake.lock`.
+          The `config`, `overlays`, `localSystem`, and `crossSystem` come from this option's siblings.
+        -->
+
+        This option can be used by external applications to increase the performance of evaluation,
+        or to create packages that depend on a container that should be built with the exact same
+        evaluation of Nixpkgs, for example.
+        Applications like this should set their default value using `lib.mkDefault`,
+        so user-provided configuration can override it without using `lib`.
+        E.g. Nixvim's home-manager module can re-use the `pkgs` instance from the "host" modules.
+
+        > [!NOTE]
+        > Using a distinct version of Nixpkgs with Nixvim may be an unexpected source of problems.
+        > Use this option with care.
+      '';
+    };
+  };
+
+  config = {
+    # For now we only set this when `nixpkgs.pkgs` is defined
+    # TODO: construct a default pkgs instance from pkgsPath and cfg options
+    # https://github.com/nix-community/nixvim/issues/1784
+    _module.args = lib.optionalAttrs opt.pkgs.isDefined {
+      # We explicitly set the default override priority, so that we do not need
+      # to evaluate finalPkgs in case an override is placed on `_module.args.pkgs`.
+      # After all, to determine a definition priority, we need to evaluate `._type`,
+      # which is somewhat costly for Nixpkgs. With an explicit priority, we only
+      # evaluate the wrapper to find out that the priority is lower, and then we
+      # don't need to evaluate `finalPkgs`.
+      pkgs = lib.mkOverride lib.modules.defaultOverridePriority cfg.pkgs.__splicedPackages;
+    };
+
+    assertions = [
+      {
+        # TODO: Remove or rephrase once pkgs can be constructed internally
+        assertion = config._module.args ? pkgs;
+        message = ''
+          `nixpkgs.pkgs` is not defined. In the future, this option will be optional.
+          Currently a pkgs instance must be evaluated externally and assigned to `nixpkgs.pkgs` option.
+        '';
+      }
+    ];
+  };
+}

wrappers/_shared.nix

@@ -55,6 +55,10 @@ in
       _module.args.nixvimLib = lib.mkDefault config.lib.nixvim.extendedLib;
     }
 
+    # Use global packages by default in nixvim's submodule
+    # TODO: `useGlobalPackages` option and/or deprecate using host packages?
+    { programs.nixvim.nixpkgs.pkgs = lib.mkDefault pkgs; }
+
     # Propagate nixvim's assertions to the host modules
     (lib.mkIf cfg.enable { inherit (cfg) warnings assertions; })
 

wrappers/darwin.nix

@@ -18,7 +18,6 @@ let
   cfg = config.programs.nixvim;
   nixvimConfig = config.lib.nixvim.modules.evalNixvim {
     extraSpecialArgs = {
-      defaultPkgs = pkgs;
       darwinConfig = config;
     };
     modules = [

wrappers/hm.nix

@@ -17,7 +17,6 @@ let
   cfg = config.programs.nixvim;
   nixvimConfig = config.lib.nixvim.modules.evalNixvim {
     extraSpecialArgs = {
-      defaultPkgs = pkgs;
       hmConfig = config;
     };
     modules = [

wrappers/nixos.nix

@@ -18,7 +18,6 @@ let
   cfg = config.programs.nixvim;
   nixvimConfig = config.lib.nixvim.modules.evalNixvim {
     extraSpecialArgs = {
-      defaultPkgs = pkgs;
       nixosConfig = config;
     };
     modules = [

wrappers/standalone.nix

@@ -1,5 +1,6 @@
 default_pkgs: self:
 {
+  # TODO: Deprecate this arg in favour of using module options
   pkgs ? default_pkgs,
   lib ? pkgs.lib,
   extraSpecialArgs ? { },
@@ -18,10 +19,13 @@ let
       nixvimConfig = evalNixvim {
         modules = [
           mod
+          # TODO: only include this when `args?pkgs`:
+          {
+            _file = ./standalone.nix;
+            nixpkgs.pkgs = lib.mkDefault pkgs;
+          }
         ];
-        extraSpecialArgs = {
-          defaultPkgs = pkgs;
-        } // extraSpecialArgs;
+        inherit extraSpecialArgs;
       };
       inherit (nixvimConfig.config) enableMan build;
     in