modules/nixpkgs: add overlays option

Based on the `nixpkgs.overlays` option available in NixOS, allows users
to further customize the `pkgs` instance used when evaluating nixvim.

The standard module tests are now provided a few extra module args to
enable a test where we instantiate a custom nixpkgs instance.

Author: MattSturgeon

modules/top-level/nixpkgs.nix

@@ -55,6 +55,47 @@ in
         > Use this option with care.
       '';
     };
+
+    overlays = lib.mkOption {
+      type =
+        let
+          overlayType = lib.mkOptionType {
+            name = "nixpkgs-overlay";
+            description = "nixpkgs overlay";
+            check = lib.isFunction;
+            merge = lib.mergeOneOption;
+          };
+        in
+        lib.types.listOf overlayType;
+      default = [ ];
+      # FIXME: use an example that is topical for vim
+      example = lib.literalExpression ''
+        [
+          (self: super: {
+            openssh = super.openssh.override {
+              hpnSupport = true;
+              kerberos = self.libkrb5;
+            };
+          })
+        ]
+      '';
+      description = ''
+        List of overlays to apply to Nixpkgs.
+        This option allows modifying the Nixpkgs package set accessed through the `pkgs` module argument.
+
+        For details, see the [Overlays chapter in the Nixpkgs manual](https://nixos.org/manual/nixpkgs/stable/#chap-overlays).
+
+        <!-- TODO: Remove -->
+        Overlays specified using the {option}`nixpkgs.overlays` option will be
+        applied after the overlays that were already included in `nixpkgs.pkgs`.
+
+        <!--
+          TODO:
+          If the {option}`nixpkgs.pkgs` option is set, overlays specified using `nixpkgs.overlays`
+          will be applied after the overlays that were already included in `nixpkgs.pkgs`.
+        -->
+      '';
+    };
   };
 
   config =
@@ -64,7 +105,7 @@ in
 
       finalPkgs =
         if opt.pkgs.isDefined then
-          cfg.pkgs
+          cfg.pkgs.appendOverlays cfg.overlays
         else
           # TODO: Remove once pkgs can be constructed internally
           throw ''

tests/default.nix

@@ -1,4 +1,6 @@
 {
+  self, # This flake
+  system,
   lib ? pkgs.lib,
   helpers,
   pkgs,
@@ -16,6 +18,11 @@ let
       module = {
         _file = file;
         imports = [ module ];
+        _module.args = {
+          # Give tests access to the flake
+          inherit self system;
+          inherit (self) inputs;
+        };
       };
       pkgs = pkgsUnfree;
     };

tests/test-sources/modules/nixpkgs.nix

@@ -0,0 +1,74 @@
+{
+  # TODO: expect not setting `nixpkgs.pkgs` to throw
+
+  overlays =
+    { pkgs, ... }:
+    {
+      test.runNvim = false;
+
+      nixpkgs.overlays = [
+        (final: prev: {
+          foobar = "foobar";
+        })
+      ];
+
+      assertions = [
+        {
+          assertion = pkgs.foobar or null == "foobar";
+          message = ''
+            Expected `pkgs.foobar` to be "foobar"
+          '';
+        }
+      ];
+    };
+
+  # Test that overlays from both `nixpkgs.pkgs` _and_ `nixpkgs.overlays` are applied
+  stacked_overlays =
+    {
+      inputs,
+      system,
+      pkgs,
+      ...
+    }:
+    {
+      test.runNvim = false;
+
+      nixpkgs.pkgs = import inputs.nixpkgs {
+        inherit system;
+        overlays = [
+          (final: prev: {
+            foobar = "foobar";
+            conflict = "a";
+          })
+        ];
+      };
+
+      nixpkgs.overlays = [
+        (final: prev: {
+          hello = "world";
+          conflict = "b";
+        })
+      ];
+
+      assertions = [
+        {
+          assertion = pkgs.foobar or null == "foobar";
+          message = ''
+            Expected `pkgs.foobar` to be "foobar"
+          '';
+        }
+        {
+          assertion = pkgs.hello or null == "world";
+          message = ''
+            Expected `pkgs.hello` to be "world"
+          '';
+        }
+        {
+          assertion = pkgs.conflict or null == "b";
+          message = ''
+            Expected `pkgs.conflict` to be "b"
+          '';
+        }
+      ];
+    };
+}