Welcome to nixCats!

If you are new to nixCats, check out the installation documentation!

The nixCats.utils set is the entire interface of nixCats.

It requires no dependencies, or arguments to access this set.

Most importantly it exports the main builder function, utils.baseBuilder.

The flake and expression based templates show how to call this function directly, and use some of the other functions in this set to construct various flake outputs.

The modules use the main builder function internally and install the result.

It also contains the functions for creating modules, along with various other utilities for working with the nix side of Neovim or nixCats that you may want to use.

nixCats.utils set documentation

nixCats.utils.baseBuilder

utils.baseBuilder is the main builder function of nixCats.

Arguments

luaPath (path or stringWithContext)

STORE PATH to your ~/.config/nvim replacement.

pkgsParams (AttrSet)

set of items for building the pkgs that builds your neovim.

accepted attributes are:

categoryDefinitions (functionTo AttrSet)

type: function that returns set of sets of categories of dependencies. Called with the contents of the current package definition as arguments

{ pkgs, settings, categories, extra, name, mkNvimPlugin, ... }@packageDef: {
  lspsAndRuntimeDeps = {
    general = with pkgs; [ ];
  };
  startupPlugins = {
    general = with pkgs.vimPlugins; [ ];
    some_other_name = [];
  };
  # ...
}

see :h nixCats.flake.outputs.categories

packageDefinitions (AttrsOf functionTo AttrSet)

set of functions that each represent the settings and included categories for a package.

Among other info, things declared in settings, categories, and extra will be available in lua.

{
  nvim = { pkgs, mkNvimPlugin, ... }: {
    settings = {};
    categories = {
      general = true;
      some_other_name = true;
    };
    extra = {};
  };
}

see :h nixCats.flake.outputs.packageDefinitions

see :h nixCats.flake.outputs.settings

name (string)

name of the package to build from packageDefinitions

Note:

When using override, all values shown above will be top level attributes of prev, none will be nested.

i.e. finalPackage.override (prev: { inherit (prev) dependencyOverlays; })

NOT prev.pkgsParams.dependencyOverlays or something like that

nixCats.utils.templates

a set of templates to get you started. See the template list.

nixCats.utils.standardPluginOverlay

standardPluginOverlay is called with flake inputs or a set of fetched derivations.

It will extract all items named in the form plugins-foobar

and return an overlay containing those items transformed into neovim plugins.

After adding the overlay returned, you can access them using pkgs.neovimPlugins.foobar

Example

if you had in your flake inputs

inputs = {
  plugins-foobar = {
    url = "github:exampleuser/foobar.nvim";
    flake = false;
  };
};

you can put the following in your dependencyOverlays

dependencyOverlays = [ (standardPluginOverlay inputs) ];

and then

pkgs.neovimPlugins.foobar

nixCats.utils.sanitizedPluginOverlay

same as standardPluginOverlay except if you give it plugins-foo.bar you can pkgs.neovimPlugins.foo-bar and still packadd foo.bar

Example

dependencyOverlays = [ (sanitizedPluginOverlay inputs) ];

nixCats.utils.fixSystemizedOverlay

if your dependencyOverlays is a list rather than a system-wrapped set, to deal with when other people (incorrectly) output an overlay wrapped in a system variable you may call this function on it.

Example

(utils.fixSystemizedOverlay inputs.codeium.overlays
  (system: inputs.codeium.overlays.${system}.default)
)

nixCats.utils.mkNixosModules

takes all the arguments of the main builder function but as a single set

Instead of name it needs defaultPackageName

This will control the namespace of the generated modules as well as the default package name to be enabled if only enable = true is present.

Unlike in the baseBuilder, all other arguments are optional

But if you want the module to actually contain configured packages, they are not optional.

The module will be able to combine any definitions passed in with new ones defined in the module correctly.

Arguments

defaultPackageName (string)
the only truly required argument
by default controls the namespace of the generated module and the default package installed
moduleNamespace (listOf string)
can be used to override the namespace of the module options
[ "programs" "nixCats" ] would mean options like programs.nixCats.enable = true
dependencyOverlays (listOf overlays or attrsOf (listOf overlays) or null)
default = null
luaPath (path or stringWithContext)
default = “”
store path to your ~/.config/nvim replacement within your nix config.
keepLuaBuilder (function)
default = null
baseBuilder with luaPath argument applied, can be used instead of luaPath
extra_pkg_config (attrs)
default = {}
the attrset passed to import nixpkgs { config = extra_pkg_config; inherit system; }
nixpkgs (path or attrs)
default = null
nixpkgs flake input, channel path, or pkgs variable
categoryDefinitions (functionTo AttrSet)
default = (_:{})
same as for the baseBuilder
packageDefinitions (AttrsOf functionTo AttrSet)
default = {}
same as for the baseBuilder

nixCats.utils.mkHomeModules

takes all the arguments of the main builder function but as a single set

Instead of name it needs defaultPackageName

This will control the namespace of the generated modules as well as the default package name to be enabled if only enable = true is present.

Unlike in the baseBuilder, all other arguments are optional

But if you want the module to actually contain configured packages, they are not optional.

The module will be able to combine any definitions passed in with new ones defined in the module correctly.

The generated home manager module is the same as the nixos module

Except there are no per-user arguments, because the module installs for the home manager user

Arguments

defaultPackageName (string)
the only truly required argument
by default controls the namespace of the generated module and the default package installed
moduleNamespace (listOf string)
can be used to override the namespace of the module options
[ "programs" "nixCats" ] would mean options like programs.nixCats.enable = true
dependencyOverlays (listOf overlays or attrsOf (listOf overlays) or null)
default = null
luaPath (path or stringWithContext)
default = “”
store path to your ~/.config/nvim replacement within your nix config.
keepLuaBuilder (function)
default = null
baseBuilder with luaPath argument applied, can be used instead of luaPath
extra_pkg_config (attrs)
default = {}
the attrset passed to import nixpkgs { config = extra_pkg_config; inherit system; }
nixpkgs (path or attrs)
default = null
nixpkgs flake input, channel path, or pkgs variable
categoryDefinitions (functionTo AttrSet)
default = (_:{})
same as for the baseBuilder
packageDefinitions (AttrsOf functionTo AttrSet)
default = {}
same as for the baseBuilder

nixCats.utils.n2l

see :h nixCats.flake.outputs.utils.n2l

you can use this to make values in the tables generated for the nixCats plugin using lua literals.

cache_location = utils.n2l.types.inline-safe.mk "vim.fn.stdpath('cache')",

nixCats.utils.mkLuaInline

see h: nixCats.flake.outputs.utils.n2l

This is an alias for utils.n2l.types.inline-safe.mk

nixCats.utils.eachSystem

flake-utils.lib.eachSystem but without the flake input

Builds a map from <attr> = value to <attr>.<system> = value for each system

Arguments

systems (listOf strings)

f (functionTo AttrSet)

nixCats.utils.bySystems

in case someone didn’t know that genAttrs is great for dealing with the system variable, this is literally just nixpkgs.lib.genAttrs

Arguments

systems (listOf strings)

f (function)

nixCats.utils.mergeDefs

Returns a merged definition from a list of definitions.

Works with both categoryDefinitions and individual packageDefinitions

If “replace” is chosen, it updates anything it finds that isn’t another set (with head being “older” and tail being “newer”)

If “merge” is chosen, if it encounters a list in both functions, (usually representing a category) it will merge them together rather than replacing the old one with the new one.

This means it works slightly differently for environment variables because each one will be updated individually rather than at a category level.

Arguments

type (enumOf "replace" | "merge")
controls the way individual categories are merged between definitions
definitions (listOf functionTo AttrSet)
accepts a list of categoryDefinitions or a list of individual packageDefinition

nixCats.utils.mergeCatDefs

alias for utils.mergeDefs "replace" [ oldCats newCats ] Works with both categoryDefinitions and individual packageDefinitions

Arguments

oldCats (functionTo AttrSet)
accepts categoryDefinitions or a single packageDefinition
newCats (functionTo AttrSet)
accepts categoryDefinitions or a single packageDefinition

nixCats.utils.deepmergeCats

alias for utils.mergeDefs "merge" [ oldCats newCats ] Works with both categoryDefinitions and individual packageDefinitions

Arguments

oldCats (functionTo AttrSet)
accepts categoryDefinitions or a single packageDefinition
newCats (functionTo AttrSet)
accepts categoryDefinitions or a single packageDefinition

nixCats.utils.mergeOverlays

recursiveUpdate each overlay output to avoid issues where two overlays output a set of the same name when importing from other nixCats. Merges everything into 1 overlay

If you have 2 overlays both outputting a set like pkgs.neovimPlugins, The second will replace the first.

This will merge the results instead.

Returns a SINGLE overlay

Arguments

overlist (listOf overlays)

nixCats.utils.mergeOverlayLists

equivalent to utils.mergeOverlays (oldOverlist ++ newOverlist)

returns a SINGLE overlay

Arguments

oldOverlist (listOf overlays)

newOverlist (listOf overlays)

nixCats.utils.safeOversList

Simple helper function for mergeOverlayLists

If you know the prior dependencyOverlays is a list, you dont need this.

If dependencyOverlays is an attrset, system string is required. If dependencyOverlays is a list, system string is ignored. if invalid type or system, returns an empty list

If you passed in dependencyOverlays as a list to your builder function, it will remain a list.

Arguments

system (string or null)
Technically optional if you know dependencyOverlays is a list
But the whole function isnt required at that point so, this is effectively required

dependencyOverlays (AttrsOfSystemsOf listOf overlays | listOf overlays)

Example

dependencyOverlays = nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all (system: [
  (utils.mergeOverlayLists # <-- merging 2 lists requires both to be a list
    # safeOversList checks if dependencyOverlays is a list or a set
    (utils.safeOversList { inherit system; inherit (prev) dependencyOverlays; })
    [ # <- and then we add our new list
      (utils.standardPluginOverlay inputs)
      # any other flake overlays here.
    ]
  )
]);

nixCats.utils.mkPackages

makes a default package and then one for each name in packageDefinitions

for constructing flake outputs.

Arguments

finalBuilder (function)
this is baseBuilder with all arguments except name applied.
packageDefinitions (AttrSet)
the set of packageDefinitions passed to the builder, passed in again.
defaultName (string)
the name of the package to be output as default in the resulting set of packages.

nixCats.utils.mkExtraPackages

mkPackages but without adding a default package, or the final defaultName argument

Arguments

finalBuilder (function)
this is baseBuilder with all arguments except name applied.
packageDefinitions (AttrSet)
the set of packageDefinitions passed to the builder, passed in again.

nixCats.utils.mkAllWithDefault

like mkPackages but easier.

Pass it a package and it will make that the default, and build all the packages in the packageDefinitions that package was built with.

Arguments

package (NixCats nvim derivation)

nixCats.utils.mkAllPackages

like mkExtraPackages but easier.

Pass it a package and it will build all the packages in the packageDefinitions that package was built with.

Arguments

package (NixCats nvim derivation)

nixCats.utils.makeOverlays

makes a set of overlays from your definitions for exporting from a flake.

defaultName is the package name for the default overlay

Arguments

luaPath (function or stringWithContext)

pkgsParams (AttrSet)
exactly the same as the pkgsParams in baseBuilder
except without system
categoryDefinitions (FunctionTo AttrSet)
exactly the same as categoryDefinitions in baseBuilder
packageDefinitions (AttrSet functionTo AttrSet)
exactly the same as packageDefinitions in baseBuilder

defaultName (string)

nixCats.utils.makeOverlaysWithMultiDefault

makes a set of overlays from your definitions for exporting from a flake.

Differs from makeOverlays in that the default overlay is a set of all the packages

default overlay yeilds pkgs.${defaultName}.${packageName} with all the packages

Arguments

luaPath (function or stringWithContext)

pkgsParams (AttrSet)
exactly the same as the pkgsParams in baseBuilder
except without system
categoryDefinitions (FunctionTo AttrSet)
exactly the same as categoryDefinitions in baseBuilder
packageDefinitions (AttrSet functionTo AttrSet)
exactly the same as packageDefinitions in baseBuilder

defaultName (string)

nixCats.utils.makeMultiOverlay

makes a set of overlays from your definitions for exporting from a flake.

overlay yeilds pkgs.${importName}.${packageName}

contains all the packages named in namesIncList (the last argument)

Arguments

luaPath (function or stringWithContext)

pkgsParams (AttrSet)
exactly the same as the pkgsParams in baseBuilder
except without system
categoryDefinitions (FunctionTo AttrSet)
exactly the same as categoryDefinitions in baseBuilder
packageDefinitions (AttrSet functionTo AttrSet)
exactly the same as packageDefinitions in baseBuilder
importName (string)
when applied, overlay yeilds pkgs.${importName}.${packageName}
namesIncList (listOf string)
the names of packages to include in the set yeilded by the overlay

nixCats.utils.easyMultiOverlayNamespaced

makeMultiOverlay except it takes only 2 arguments.

Arguments

package (NixCats nvim derivation)
will include all packages in the packageDefinitions the package was built with
importName (string)
overlay will yield pkgs.${importName}.${packageName}

Example

easyMultiOverlayNamespaced self.packages.x86_64-linux.${packageName} packageName
# The `system` chosen DOES NOT MATTER.
# The overlay utilizes override to change it to match `prev.system`

nixCats.utils.easyMultiOverlay

makes a single overlay with all the packages in packageDefinitions from the package as pkgs.${packageName}

Arguments

package (NixCats nvim derivation)
will include all packages in the packageDefinitions the package was built with

Example

easyMultiOverlay self.packages.x86_64-linux.${packageName}
# The `system` chosen DOES NOT MATTER.
# The overlay utilizes override to change it to match `prev.system`

nixCats.utils.easyNamedOvers

makes a separate overlay for each of the packages in packageDefinitions from the package as pkgs.${packageName}

Arguments

package (NixCats nvim derivation)
will include all packages in the packageDefinitions the package was built with

Example

easyMultiOverlay self.packages.x86_64-linux.${packageName}
# The `system` chosen DOES NOT MATTER.
# The overlay utilizes override to change it to match `prev.system`