for the Lua-natic’s Neovim config on Nix
This repository is in maintenance mode.
Please see this project instead
The core nix code of nixCats that makes this project run will continue to work.
The actual wrapping of neovim works in a very similar way and I can mirror maintenance changes here, and I anticipate very few.
However, if a template becomes too much to maintain, I may simply delete it instead! You may have noticed I already did this with one of them.
I made something better enough to warrant that.
Bring this level of control to every program, with the module system!
docs page for the neovim wrapper
Instead of using categories for your neovim:
The neovim module takes flexible specs that you can add type-safe options to with the module system
They can be used in a similar fashion to the categories here, but also in a lot of new ways!
tips and tricks section at the end
The neovim wrapper there can do everything this one can!
It still allows for configuration with the same philosophy of “install with nix, configure with lua”.
But it opens up a lot of new possibilities as well, while reducing initial complexity of the interface.
The lua tips and tricks used in the templates here are all applicable there.
It has an info plugin with a lot of the same information.
Just like nixCats, it allows you to split things up into groups and
inform your lua of that, and it is still possible to install multiple
neovim executables at once should that be desired.
However, the ability to override your configuration later is much improved.
You can make your own module options, and then you override it later the same way you configured it in the first place. Simply provide another module!
nixCats theoretically has a lot of capabilities.
You will find them all there as well, and will likely have an easier time actually making use of them.
Hope to see you there!
lazy.nvim in the new wrapper:If someone wants to adapt the nixCatsUtils/lazyCat.lua
file to work with the new wrapper, it would be a simple task.
It simply sets some lazy.nvim options to treat the nix
provided plugins as dev dependencies, and the info plugin in the new one
contains the plugin paths just like it does here.
If you do this, feel free to post about it in discussions on the new repository.
But this repository only ever contained such a file because it
predates both lze and lz.n.
They work well with both the built-in neovim plugin manager, and with nix-provided plugins.
They have been around long enough to prove that they actually are a better alternative, at least for this use-case if not others.
Should you decide to not heed this warning and choose
lazy.nvim anyway, the settings you are looking for are:
dev.path: which can receive a function that receives
the spec, and should return the path to the plugin
dev.patterns: set it to { "" } or fetch
the names you downloaded from nix from the info plugin
dev.fallback = true: lets it still fall back to
downloading via lazy.nvim in case you did
dev.patterns = { "" } and still wanted to be able to do
that
performance.rtp.reset = false
performance.reset_packpath = false
You also will have to make sure all names detected by
lazy.nvim agree with their nix counterpart via that spec’s
name field, or make sure the name from nix agrees with the one from
lazy.nvim by setting pname for that
plugin.
Again, using lazy.nvim is not the best way to do lazy
loading with any nix wrapper scheme, despite the above workarounds.
And now, most of the readme as it was before nixCats
became “the old way to do things”.
The goal of nixCats is to make it as easy as possible to
interact with the normal configuration scheme, while using Nix to
install things and add useful meta-features. This is the opposite
approach to projects like nixvim or nvf, which aim to “nixify” Neovim as much as
possible.
The end result ends up being very comparable to — if not better than — using a regular Neovim package manager + Mason. And it is much more portable.
It also avoids falling into the trap of trying to make a module for every plugin somebody might want to use. The Neovim plugin ecosystem is very large, and updates are often. This leads to a lot of time spent doing and maintaining simple translations of Lua options into Nix. Or worse, lagging behind on new features due to having to reapply them for each plugin.
Instead, nixCats aims for a higher quality experience
interacting with the plugin ecosystem as it is, and it only needs a
single Nix file to effectively manage your Neovim installation. In
addition, you can still make use of the nice features and Lua
autocompletion usual for a Neovim configuration.
But what if you want to pass information from Nix to the rest of your Neovim configuration?
This is where Home Manager and pkgs.wrapNeovim start to
fall short. It is not uncommon to see a mess of global variables written
in Nix strings, and a bunch of files called via dofile that
are not properly detected by Neovim tooling with these methods. To pass
info from Nix to Lua, you must
''${interpolate a string}'';. So you need to write some Lua
in strings in Nix. Right?
Not anymore!
The Nix Category scheme is simple:
Make a new list in the correct section of categoryDefinitions.
For example, make a list in the startupPlugins set for
plugins that load on startup.
Enable that category for the desired Neovim package in packageDefinitions.
Check for it in your Neovim Lua configuration with nixCats('attr.path.to.yourList').
Your package definitions are not only how you enable categories per package, but they also allow you to pass arbitrary information to Neovim, and grab it just as easily.
Simply put your Nix data into the set in your package definitions, and access it in Lua as a Lua data structure.
You can pass anything that is not an uncalled Nix function. Lua interpreters can’t run Nix code.
No more wondering how you are going to get info into Lua without ruining your normal Neovim directory by writing Lua in nix strings!
If you like the normal Neovim configuration scheme, but want your
config to be runnable via nix run and have an easier time
dealing with dependency issues, this repo is for you.
Even if you don’t use it for downloading plugins at all, preferring to use lazy and Mason and deal with issues as they arise, this scheme will have useful things for you.
So many templates!
How do I know which of them to pick? How do I install the thing I get from that?
The installation guide is here to help!
The first thing it will guide you through is how to decide on a template.
Don’t worry, the modules and the flake templates have very similar structure. So if you pick one that doesn’t fit you, it will be easy to swap to one that does.
It will then walk you through a 100 line overview
detailing each of the parts of nixCats you will interact
with most.
All config folders like ftplugin/, pack/
and after/ work as designed (see :h rtp).
If you want lazy loading put it in optionalPlugins in
your categoryDefinitions
and call vim.cmd('packadd <pluginName>') from an
autocommand or keybind when you want it.
For lazy loading in your configuration, I strongly recommend using lze or lz.n.
The main example configuration here
uses lze. They are not package managers, and work within
the normal Neovim plugin system, just like nixCats does.
This makes them much more suitable for managing lazy loading when using
Nix.
lazy.nvim is
known for not playing well in conjunction with other package managers,
so using it will require a little bit of extra setup compared to the 2
above options.
However nixCats provides a simple to use lazy.nvim wrapper
wrapper that can be used if desired.
It is demonstrated to good effect in the kickstart-nvim template.
Keep in mind, lazy.nvim will prevent Nix from loading
any plugins unless you also add it to a lazy.nvim plugin
spec
You may launch your Neovim built via nixCats with any
name you would like to choose. The default launch name is given by
package name in packageDefinitions.
In particular, the desktop file follows the package name, so programs
like git will only know where to look if you set that as your
$EDITOR variable.
You may then make any other aliases that you please as long as they
do not conflict. If you try to install conflicting aliases to your path
via home.packages or
environment.systemPackages, you will get a collision
error.
Neovim does not know about the wrapper script. It is still at
<store_path>/bin/nvim and is aware of that. Therefore
this should not cause any issues beyond how Neovim is normally wrapped
in nixpkgs.
Remember to change your $EDITOR variable if you
named your package something other than nvim!
Make sure you run git add . first as anything not staged
will not be added to the store and thus not be findable by either Nix or
Neovim.
See Nix documentation on how to use the command line commands further at: the Nix command reference manual
Zsh users may occasionally run into globbing issues running nix flake commands. See this note for more info
Also, familiarize yourself with the flake schema
This knowledge will be useful when installing flake based nixCats configurations into your main configuration.
Mason does not readily work on NixOS (although it does on other OS options).
Luckily you also don’t need it.
All Mason does is download it to your path, and call lspconfig
on the result.
You can install them via the lspsAndRuntimeDeps field in
your categoryDefinitions.
Then call lspconfig
yourself in your Lua.
The example config and :h nixCats.LSPs show examples of this, and the examples still run Mason when Nix wasn’t used to load the config!
You could force it to work. NixCats has the ability to bundle any type of dependency it might need.
Sometimes it can be hard to tell what dependency the error is even asking for though.
Many thanks to Quoteme for a great repo to teach me the basics of Nix!!! I borrowed some code from it as well because I couldn’t have written it better.
Definitely the simplest example I have seen thus far.
As someone with no prior exposure to functional programming, such a simple example was absolutely fantastic.
utils.standardPluginOverlay is copy-pasted from a section of Quoteme’s repo.
Thank you!!! I literally did not even know what an overlay was yet and you taught me!
I also borrowed code from nixpkgs and made modifications and improvements to better fit nixCats.