modules/nixpkgs: allow creating a nixpkgs internally

modules/top-level/nixpkgs.nix

@@ -136,9 +136,52 @@ in
 
         Ignored when `nixpkgs.pkgs` is set.
       '';
+    };
+
+    hostPlatform = lib.mkOption {
+      type = with lib.types; either str attrs;
+      example = {
+        system = "aarch64-linux";
+      };
+      apply = lib.systems.elaborate;
+      defaultText = lib.literalMD ''
+        Inherited from the "host" configuration's `pkgs`.
+        Must be specified manually when building a standalone nixvim.
+      '';
+      description = ''
+        Specifies the platform where the Nixvim configuration will run.
 
-      # FIXME: This is a stub option for now
-      internal = true;
+        To cross-compile, also set `nixpkgs.buildPlatform`.
+
+        Ignored when `nixpkgs.pkgs` is set.
+      '';
+    };
+
+    buildPlatform = lib.mkOption {
+      type = with lib.types; either str attrs;
+      default = cfg.hostPlatform;
+      example = {
+        system = "x86_64-linux";
+      };
+      apply =
+        value:
+        let
+          elaborated = lib.systems.elaborate value;
+        in
+        # If equivalent to `hostPlatform`, make it actually identical so that `==` can be used
+        # See https://github.com/NixOS/nixpkgs/issues/278001
+        if lib.systems.equals elaborated cfg.hostPlatform then cfg.hostPlatform else elaborated;
+      defaultText = lib.literalMD ''
+        Inherited from the "host" configuration's `pkgs`.
+        Or `config.nixpkgs.hostPlatform` when building a standalone nixvim.
+      '';
+      description = ''
+        Specifies the platform on which Nixvim should be built.
+        By default, Nixvim is built on the system where it runs, but you can change where it's built.
+        Setting this option will cause Nixvim to be cross-compiled.
+
+        Ignored when `nixpkgs.pkgs` is set.
+      '';
     };
   };
 
@@ -165,10 +208,5 @@ in
       # evaluate the wrapper to find out that the priority is lower, and then we
       # don't need to evaluate `finalPkgs`.
       _module.args.pkgs = lib.mkOverride lib.modules.defaultOverridePriority finalPkgs.__splicedPackages;
-
-      # FIXME: This is a stub option for now
-      warnings = lib.optional (
-        opt.source.isDefined && opt.source.highestPrio < (lib.mkOptionDefault null).priority
-      ) "Defining the option `nixpkgs.source` currently has no effect";
     };
 }

wrappers/_shared.nix

@@ -28,16 +28,45 @@ let
     setAttrByPath
     ;
   cfg = config.programs.nixvim;
+
+  # TODO: Find a way to document the options declared here
+  nixpkgsModule =
+    { config, ... }:
+    {
+      _file = ./_shared.nix;
+
+      options.nixpkgs = {
+        useGlobalPackages = lib.mkOption {
+          type = lib.types.bool;
+          default = true; # TODO: Added 2024-10-20; switch to false one release after adding a deprecation warning
+          description = ''
+            Whether Nixvim should use the host configuration's `pkgs` instance.
+
+            The host configuration is usually home-manager, nixos, or nix-darwin.
+
+            When false, an instance of nixpkgs will be constructed by nixvim.
+          '';
+        };
+      };
+
+      config = {
+        nixpkgs = {
+          # Use global packages by default in nixvim's submodule
+          pkgs = lib.mkIf config.nixpkgs.useGlobalPackages (lib.mkForce 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;
+        };
+      };
+    };
   nixvimConfiguration = config.lib.nixvim.modules.evalNixvim (
     evalArgs
     // {
       modules = evalArgs.modules or [ ] ++ [
-        # Use global packages by default in nixvim's submodule
-        # TODO: `useGlobalPackages` option and/or deprecate using host packages?
-        {
-          _file = ./_shared.nix;
-          nixpkgs.pkgs = lib.mkDefault pkgs;
-        }
+        nixpkgsModule
       ];
     }
   );