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. e.g. ./.

pkgsParams (AttrSet)

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

accepted attributes are:

{ inherit nixpkgs system dependencyOverlays; }
{ inherit pkgs; }
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, mkPlugin, ... }@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, name, mkPlugin, luaPath, this, ... }: {
    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, except it cannot take system or pkgs, from pkgsParams, only nixpkgs.

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, arguments are optional, but if you want the module to be preloaded with configured packages, they are not.

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

Arguments

nixCats.utils.mkHomeModules

takes all the arguments of the main builder function but as a single set, except it cannot take system or pkgs, from pkgsParams, only nixpkgs.

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, arguments are optional, but if you want the module to be preloaded with configured packages, they are not.

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

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-unsafe.mk { body = "vim.fn.stdpath('cache')"; }

nixCats.utils.mkLuaInline

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

utils.mkLuaInline "[[I am a]] .. [[ lua ]] .. type([[value]])";

alias for

body: inline.types.inline-unsafe.mk { inherit body; };

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

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

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

nixCats.utils.mergeCatDefs

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

Arguments

nixCats.utils.deepmergeCats

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

Arguments

nixCats.utils.mkPackages

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

for constructing flake outputs.

Arguments

nixCats.utils.mkExtraPackages

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

Arguments

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

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

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

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

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

nixCats.utils.easyMultiOverlayNamespaced

makeMultiOverlay except it takes only 2 arguments.

Arguments

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

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

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`