1 ---------------------------------------------------------------------------------------
2 INSTALLATION: nixCats.installation_options
3
4 Try it out! Run the example config with the following:
5
6 nix shell github:BirdeeHub/nixCats-nvim?dir=templates/example
7
8 nixCats
9
10 Now that you have access to the help and a Nix LSP, to get started,
11 first exit Neovim. (but not the Nix shell!)
12
13 In a terminal, navigate to your nvim directory and
14 run your choice of the following commands (don't worry! It doesnt overwrite):
15
16
17
18 nix flake init -t github:BirdeeHub/nixCats-nvim
19
20 The flake template will be easiest to run from anywhere via nix run,
21 and most self explanatory for new users.
22
23 nixCats also offers modules to be used with NixOS, Home-Manager, and nix-darwin.
24
25 If you wish to export the packages constructed
26 by the module from your system flake as a package to be
27 ran via nix run, you will need to grab them from the config variable of
28 your finished system configuration.
29 Instructions for doing this are at :h nixCats.module
30
31
32 nix flake init -t github:BirdeeHub/nixCats-nvim#home-manager
33
34 nix flake init -t github:BirdeeHub/nixCats-nvim#nixos
35
36
37
38
39
40 And this method, called the nixExpressionFlakeOutputs is somewhere in between.
41 It is the outputs function of the flake template, but as its own file.
42 Thus, it is an expression that returns the outputs of the flake. Hence the
43 name. You call it like a function with your inputs, and recieve all normal flake outputs.
44
45 This makes it as easier to export for running via nix run,
46 but is slightly more difficult to install than using the module is for first time users.
47
48
49
50
51 nix flake init -t github:BirdeeHub/nixCats-nvim#nixExpressionFlakeOutputs
52
53 Initializing a template will create a skeleton flake.nix or default.nix for you to fill in.
54
55 All the above templates use the same builder function eventually. Either
56 directly in the flake templates, or behind the scenes in the module one.
57
58 So swapping between them is easy if you picked one you dont like for any
59 reason.
60
61 If you are unfamiliar with Neovim and want a ready-made starter config,
62 you should instead use the following template:
63
64 nix flake init -t github:BirdeeHub/nixCats-nvim#example
65
66
67 If you want the lazy.nvim wrapper and various utilities for functionality without Nix
68 added at lua/nixCatsUtils also run:
69
70 nix flake init -t github:BirdeeHub/nixCats-nvim#luaUtils
71
72
73
74
75
76 Re-enter the nixCats Neovim version by typing nixCats . and take a look!
77 Reference the :help nixCats docs and nixCats-nvim itself as a guide for importing your setup.
78
79 You add plugins to the nix file, call whatever lua setup function is required by the plugins,
80 and use lspconfig to set up LSPs. You may optionally choose to set up a plugin
81 only when that particular category is enabled in the current package
82
83 It is a similar process to migrating to a new Neovim plugin manager.
84
85 Use a template, and migrate your plugins into the nix file provided.
86
87 Then configure in Lua with the configuration options provided by the plugin.
88
89 It is suggested to start with the default flake template
90 or one of the example configurations so that you
91 can mess around with it in a separate repository/directory,
92 and easily use nix repl to see what it exports.
93 Just use nix repl in the directory, :lf . and type outputs. and
94 autocomplete to see the exported items!
95 You can use nix build --show-trace . to build to a result directory
96 to test your setup in isolation.
97 See nix documentation on how to use these commands further at:
98 [the nix command reference manual]
99 (https://nixos.org/manual/nix/stable/command-ref/new-cli/nix)
100
101 To install that flake in your system flake, you simply add it to your system flake's inputs,
102 and then grab inputs.yourflake.packages.${system}.<packagename>
103 and place it in your environment.systemPackages list (or equivalent)
104
105 If you then wish to integrate the directory into your main system flake,
106 it is suggested to then move to the nixExpressionFlakeOutputs template.
107
108 This is because the nixExpressionFlakeOutputs template
109 is simply the outputs function of the default template.
110 So it will be most familiar.
111
112 However the modules are also great options, and instructions for still
113 exporting the package from your system flake are at :h nixCats.module
114
115 Use the help and the example configs in nixCats-nvim as an example.
116 The help will still be accessible in your version of the editor.
117
118 Make sure you run git add . before building as anything not staged will not
119 be added to the store and thus not be findable by either nix or neovim.
120
121 ---------------------------------------------------------------------------------------
122 nixCats.templates
123 You may initialize templates into the current directory via
124 nix flake init -t github:BirdeeHub/nixCats-nvim#$TEMPLATE_NAME
125
126 The main starter templates have already been mentioned above,
127 but you may view the full list of templates at
128 https://nixcats.org/nixCats_templates.html
129
130 In particular, the example configurations that demonstrate the lazy.nvim might
131 be interesting for those who wish to use it!
132
133 ---------------------------------------------------------------------------------------
134 How it works in 100 lines: nixCats.overview
135
136 <tip> For the following 100 lines, it is most effective to cross reference with a template!
137
138 First choose a path for luaPath as your new Neovim directory to be loaded into
139 the store.
140
141 Then in categoryDefinitions:
142 You have a SET to add LISTS of plugins to the packpath (one for both
143 pack/*/start and pack/*/opt), a SET to add LISTS of things to add to the path,
144 a set to add lists of shared libraries,
145 a set of lists to add... pretty much anything.
146 Full list of these sets is at :h nixCats.flake.outputs.categories.
147
148 Those lists are in sets, and thus have names.
149
150 You do this in categoryDefintions, which is a function provided a pkgs set.
151 It also recieves the values from packageDefintions of the package it is being called with.
152 It returns those sets of things mentioned above.
153
154 packageDefintions is a set, containing functions that also are provided a
155 pkgs set. They return a set of categories you wish to include.
156 If, from your categoryDefintions, you returned:
157
158 startupPlugins = {
159 general = [
160 pkgs.vimPlugins.lz-n
161 pkgs.vimPlugins.nvim-treesitter.withAllGrammars
162 pkgs.vimPlugins.telescope
163
164 ];
165 };
166
167 In your packageDefintions, if you wanted to include it in a package named
168 myCoolNeovimPackage, launched with either myCoolNeovimPackage or vi,
169 you could have:
170
171
172 packageDefinitions = {
173 myCoolNeovimPackage = { pkgs, ... }@misc: {
174 settings = {
175 aliases = [ "vi" ];
176 };
177 categories = {
178
179 general = true;
180
181 };
182 };
183
184 };
185 defaultPackageName = "myCoolNeovimPackage";
186
187 They also return a set of settings, for the full list see :h nixCats.flake.outputs.settings.
188
189 Then, a package is exported and built based on that using the nixCats builder
190 function, and various flake exports such as modules based on your config
191 are made using utility functions provided.
192 The templates take care of that part for you: just add stuff to lists.
193
194 But the cool part. That set of settings and categories is translated verbatim
195 from a Nix set to a Lua table, and put into a plugin that returns it.
196 It also passes the full set of plugins included via Nix and their store paths
197 in the same manner. This gives full transparency to your Neovim of everything
198 in Nix. Passing extra info is rarely necessary outside of including categories
199 and setting settings, but it can be useful, and anything other than Nix
200 functions may be passed. You then have access to the contents of these tables
201 anywhere in your Neovim, because they are literally a set hardcoded into a
202 Lua file on your runtimepath.
203
204 You may use the :NixCats user command to view these
205 tables for your debugging. There is a global function defined that
206 makes checking subcategories easier. Simply call nixCats('the.category')!
207 It will return the nearest parent category value, but nil if it was a table,
208 because that would mean a different sub category was enabled, but this one was
209 not. It is simply a getter function for the table require('nixCats').cats
210 see :h nixCats for more info.
211
212 That is what enables full transparency of your Nix configuration
213 to your Neovim! Everything you could have needed to know from Nix
214 is now easily passed, or already available, through the nixCats plugin!
215
216 It has a shorthand for importing plugins that arent on nixpkgs, covered in
217 :h nixCats.flake.inputs and the templates set up the outputs for you.
218 Info about those outputs is detailed in nixCats.flake.outputs.exports.
219 You can also add overlays accessible to the pkgs object above, and set config
220 values for it, how to do that is at the top of the templates, and covered in
221 help at :h nixCats.flake.outputs.overlays and :h nixCats.flake.outputs.overlays.
222
223 It also has a template containing some Lua functions that can allow you
224 to adapt your configuration to work without Nix. For more info see :h
225 nixCats.luaUtils It contains useful functions,
226 such as "did Nix load Neovim" and "if not Nix do this, else do that"
227 It also contains a simple wrapper for lazy.nvim that does the rtp reset
228 properly, and then can be used to tell lazy not
229 to download stuff in an easy to use fashion.
230
231 The goal of the starter templates is so that the usage at the start can be as simple
232 as adding plugins to lists and calling require('theplugin').setup().
233 Most further complexity is optional, and very complex things can be achieved
234 with only minor changes in Nix, and some nixCats('something') calls.
235 You can then import the finished package, and reconfigure it again
236 without duplication using the override function! see :h nixCats.overriding.
237
238 ---------------------------------------------------------------------------------------
239 vim:tw=78:ts=8:ft=help:norl: