lib: segregate and deprecate functions that need pkgs

Splits everything that depends on a `pkgs` instance into an optional
attrs, allowing `helpers.nix` to be bootstrapped without `pkgs`.

This required some refactoring:
- `modules.specialArgs` is only available when `pkgs` is used
- `modules.specialArgsWith` now requires `defaultPkgs` be provided
- `builders.*` now have `*With` variants that take `pkgs` as an argument
  and a `withPkgs` function that returns the old interface
- Had to define the fixed part of `builders` outside the attrs for now,
  to avoid infinite recursion.
- The old `builders` are now deprecated, and print a warning when
  evaluated
- `withOptoinalFns` was introduced to merge the optional attrs into the
  final lib.

lib/builders.nix

@@ -1,21 +1,39 @@
-{ lib, pkgs }:
-rec {
+{ lib }:
+# NOTE: use local recursion instead of accessing `lib.nixvim.builders`.
+# The latter isn't a fixed shape since it may get the deprecated functions meregd in,
+# which would lead to infinite recursion.
+lib.fix (builders: {
+  # Curry a nixpkgs instance into the *With functions below, dropping the `With` suffix
+  withPkgs =
+    pkgs:
+    lib.concatMapAttrs (
+      name: fn:
+      let
+        match' = builtins.match "(.*)With" name;
+        name' = builtins.head match';
+      in
+      lib.optionalAttrs (match' != null) {
+        ${name'} = fn pkgs;
+      }
+    ) builders;
+
   /*
     Write a lua file to the nix store, formatted using stylua.
 
     # Type
 
     ```
-    writeLua :: String -> String -> Derivation
+    writeLuaWith :: pkgs -> String -> String -> Derivation
     ```
 
     # Arguments
 
+    - [pkgs] A nixpkgs instance
     - [name] The name of the derivation
     - [text] The content of the lua file
   */
-  writeLua =
-    name: text:
+  writeLuaWith =
+    pkgs: name: text:
     pkgs.runCommand name { inherit text; } ''
       echo -n "$text" > "$out"
 
@@ -33,16 +51,17 @@ rec {
     # Type
 
     ```
-    writeByteCompiledLua :: String -> String -> Derivation
+    writeByteCompiledLuaWith :: pkgs -> String -> String -> Derivation
     ```
 
     # Arguments
 
+    - [pkgs] A nixpkgs instance
     - [name] The name of the derivation
     - [text] The content of the lua file
   */
-  writeByteCompiledLua =
-    name: text:
+  writeByteCompiledLuaWith =
+    pkgs: name: text:
     pkgs.runCommandLocal name { inherit text; } ''
       echo -n "$text" > "$out"
 
@@ -56,54 +75,57 @@ rec {
     # Type
 
     ```
-    byteCompileLuaFile :: String -> String -> Derivation
+    byteCompileLuaFileWith :: pkgs -> String -> String -> Derivation
     ```
 
     # Arguments
 
+    - [pkgs] A nixpkgs instance
     - [name] The name of the derivation
     - [src] The path to the source lua file
   */
-  byteCompileLuaFile =
-    name: src:
+  byteCompileLuaFileWith =
+    pkgs: name: src:
     pkgs.runCommandLocal name { inherit src; } ''
       ${lib.getExe' pkgs.luajit "luajit"} -bd -- "$src" "$out"
     '';
 
   # Setup hook to byte compile all lua files in the output directory.
   # Invalid lua files are ignored.
-  byteCompileLuaHook = pkgs.makeSetupHook { name = "byte-compile-lua-hook"; } (
-    let
-      luajit = lib.getExe' pkgs.luajit "luajit";
-    in
-    pkgs.writeText "byte-compile-lua-hook.sh" # bash
-      ''
-        byteCompileLuaPostFixup() {
-            # Target is a single file
-            if [[ -f $out ]]; then
-                if [[ $out = *.lua ]]; then
-                    tmp=$(mktemp)
-                    ${luajit} -bd -- "$out" "$tmp"
-                    mv "$tmp" "$out"
-                fi
-                return
-            fi
+  byteCompileLuaHookWith =
+    pkgs:
+    pkgs.makeSetupHook { name = "byte-compile-lua-hook"; } (
+      let
+        luajit = lib.getExe' pkgs.luajit "luajit";
+      in
+      pkgs.writeText "byte-compile-lua-hook.sh" # bash
+        ''
+          byteCompileLuaPostFixup() {
+              # Target is a single file
+              if [[ -f $out ]]; then
+                  if [[ $out = *.lua ]]; then
+                      tmp=$(mktemp)
+                      ${luajit} -bd -- "$out" "$tmp"
+                      mv "$tmp" "$out"
+                  fi
+                  return
+              fi
 
-            # Target is a directory
-            while IFS= read -r -d "" file; do
-                tmp=$(mktemp -u "$file.XXXX")
-                # Ignore invalid lua files
-                if ${luajit} -bd -- "$file" "$tmp"; then
-                    mv "$tmp" "$file"
-                else
-                    echo "WARNING: Ignoring byte compiling error for '$file' lua file" >&2
-                fi
-            done < <(find "$out" -type f,l -name "*.lua" -print0)
-        }
+              # Target is a directory
+              while IFS= read -r -d "" file; do
+                  tmp=$(mktemp -u "$file.XXXX")
+                  # Ignore invalid lua files
+                  if ${luajit} -bd -- "$file" "$tmp"; then
+                      mv "$tmp" "$file"
+                  else
+                      echo "WARNING: Ignoring byte compiling error for '$file' lua file" >&2
+                  fi
+              done < <(find "$out" -type f,l -name "*.lua" -print0)
+          }
 
-        postFixupHooks+=(byteCompileLuaPostFixup)
-      ''
-  );
+          postFixupHooks+=(byteCompileLuaPostFixup)
+        ''
+    );
 
   /*
     Returns an overridden derivation with all lua files byte compiled.
@@ -111,19 +133,22 @@ rec {
     # Type
 
     ```
-    byteCompileLuaDrv :: Derivation -> Derivation
+    byteCompileLuaDrvWith :: pkgs -> Derivation -> Derivation
     ```
 
     # Arguments
 
+    - [pkgs] A nixpkgs instance
     - [drv] Input derivation
   */
-  byteCompileLuaDrv =
-    drv:
+  byteCompileLuaDrvWith =
+    pkgs: drv:
     drv.overrideAttrs (
       prev:
       {
-        nativeBuildInputs = prev.nativeBuildInputs or [ ] ++ [ byteCompileLuaHook ];
+        nativeBuildInputs = prev.nativeBuildInputs or [ ] ++ [
+          (lib.nixvim.builders.byteCompileLuaHookWith pkgs)
+        ];
       }
       // lib.optionalAttrs (prev ? buildCommand) {
         buildCommand = ''
@@ -132,4 +157,4 @@ rec {
         '';
       }
     );
-}
+})

lib/default.nix

@@ -1,5 +1,5 @@
 {
-  pkgs,
+  pkgs ? null,
   lib ? pkgs.lib,
   _nixvimTests ? false,
   ...
@@ -14,10 +14,48 @@ lib.fix (
       helpers = self; # TODO: stop using `helpers` in the subsections
       lib = self.extendedLib;
     };
-  in
-  {
-    autocmd = call ./autocmd-helpers.nix { };
+
+    # Define this outside of the attrs to avoid infinite recursion,
+    # since the final value will have been merged from two places
     builders = call ./builders.nix { };
+
+    # Merge in deprecated functions that require a nixpkgs instance
+    # Does shallow recursion, only one level deeper than normal
+    # Does nothing when `pkgs` is null
+    withOptionalFns =
+      if pkgs == null then
+        lib.id
+      else
+        lib.recursiveUpdateUntil
+          (
+            path: lhs: rhs:
+            builtins.length path > 1
+          )
+          {
+            # Minimal specialArgs required to evaluate nixvim modules
+            # FIXME: our minimal specialArgs should not need `pkgs`
+            modules.specialArgs = self.modules.specialArgsWith {
+              defaultPkgs = pkgs;
+            };
+
+            # We used to provide top-level access to the "builder" functions, with `pkgs` already baked in
+            # TODO: deprecated 2024-09-13; remove after 24.11
+            builders = lib.mapAttrs (
+              name:
+              lib.warn "`${name}` is deprecated. You should either use `${name}With` or access `${name}` via `builders.withPkgs`."
+            ) (builders.withPkgs pkgs);
+
+            inherit (self.builders)
+              writeLua
+              writeByteCompiledLua
+              byteCompileLuaFile
+              byteCompileLuaHook
+              byteCompileLuaDrv
+              ;
+          };
+  in
+  withOptionalFns {
+    autocmd = call ./autocmd-helpers.nix { };
     deprecation = call ./deprecation.nix { };
     extendedLib = call ./extend-lib.nix { inherit lib; };
     keymaps = call ./keymap-helpers.nix { };
@@ -27,18 +65,11 @@ lib.fix (
     options = call ./options.nix { };
     utils = call ./utils.nix { inherit _nixvimTests; };
     vim-plugin = call ./vim-plugin.nix { };
+    inherit builders;
 
     # Top-level helper aliases:
     # TODO: deprecate some aliases
 
-    inherit (self.builders)
-      writeLua
-      writeByteCompiledLua
-      byteCompileLuaFile
-      byteCompileLuaHook
-      byteCompileLuaDrv
-      ;
-
     inherit (self.deprecation)
       getOptionRecursive
       mkDeprecatedSubOptionModule

lib/modules.nix

@@ -1,19 +1,17 @@
 {
-  pkgs,
   lib,
-  helpers,
+  self,
 }:
 rec {
-  # Minimal specialArgs required to evaluate nixvim modules
-  specialArgs = specialArgsWith { };
-
   # Build specialArgs for evaluating nixvim modules
   specialArgsWith =
-    extraSpecialArgs:
+    # 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`
-      inherit lib helpers;
-      defaultPkgs = pkgs;
+      helpers = self;
     }
     // extraSpecialArgs;