1 ---------------------------------------------------------------------------------------
2 INSTALLATION: nixCats.installation_options
3
4
5 nix shell github:BirdeeHub/nixCats-nvim?dir=templates/example
6
7 nixCats
8
9 Now that you have access to the help and a nix lsp, to get started,
10 first exit neovim. (but not the nix shell!)
11
12 In a terminal, navigate to your nvim directory and
13 run your choice of the following commands (don't worry! It doesnt overwrite):
14
15
16
17 nix flake init -t github:BirdeeHub/nixCats-nvim
18
19
20
21 nix flake init -t github:BirdeeHub/nixCats-nvim#nixExpressionFlakeOutputs
22
23
24
25 nix flake init -t github:BirdeeHub/nixCats-nvim#luaUtils
26
27
28
29
30
31
32
33 This will create an empty version of flake.nix (or default.nix) for you to fill in.
34
35 If you are unfamiliar with nvim and want a ready-made starter config,
36 you should instead use the following template:
37
38 nix flake init -t github:BirdeeHub/nixCats-nvim#example
39
40 If you added the luaUtils template, you should also have that at lua/nixCatsUtils
41
42 Re-enter the nixCats nvim version by typing nixCats . and take a look!
43 Reference the :help nixCats docs and nixCats-nvim itself as a guide for importing your setup.
44
45 You add plugins to the flake.nix, call whatever setup function is required by the plugin,
46 and use lspconfig to set up lsps. You may optionally choose to set up a plugin
47 only when that particular category is enabled in the current package
48
49 It is a similar process to migrating to a new neovim plugin manager.
50
51 Use a template, and migrate your plugins into the flake.nix file provided.
52
53 Then configure in lua with the configuration options provided by the plugin.
54
55 It is suggested to start with the default template so that you can mess around with it in
56 a separate repository/directory,
57 and easily use nix repl to see what it exports.
58 Just use nix repl in the directory, :lf . and type outputs. and
59 autocomplete to see the exported items!
60
61 Then move to the nixExpressionFlakeOutputs template to
62 integrate it with your main nix config when you are happy with it!
63
64 This is because the nixExpressionFlakeOutputs template
65 is simply the outputs function of the default template. You then move the
66 inputs to your main system inputs, and retrieve all the normal flake outputs
67 with yournvim = import ./the/dir/with/template { inherit inputs; };
68 You can then install them with yournvim.packages.${system}.nvimpackagename,
69 use the modules they export to modify them further before installing them,
70 install them via overlay, export them from your system flake so you can still
71 access them from anywhere via nix run, etc...
72
73 Use the help and the example config in nixCats-nvim itself that you just ran as an example.
74 The help will still be accessible in your version of the editor.
75
76 When you have your plugins added, you can build it using nix build and it
77 will build to a result directory, or nix profile install to install it to your
78 profile. Make sure you run git add . first as anything not staged will not
79 be added to the store and thus not be findable by either nix or neovim.
80 See nix documentation on how to use these commands further at:
81 [the nix command reference manual]
82 (https://nixos.org/manual/nix/stable/command-ref/new-cli/nix)
83
84 When you have a working version, you can begin to explore the many
85 options made available for importing your new nix neovim configuration
86 into a nix system or home manager configuration.
87 There are MANY, thanks to the virtues of the category scheme of this flake.
88
89 It is made to be customized into your own portable nix neovim distribution
90 with as many options as you wish, while requiring you to leave the normal
91 nvim configuration scheme as little as possible.
92
93 ---------------------------------------------------------------------------------------
94 How it works in 100 lines: nixCats.overview
95
96 <tip> For the following 100 lines, it is most effective to cross reference with a template!
97
98 First choose a path for luaPath as your new neovim directory to be loaded into
99 the store.
100
101 Then in categoryDefinitions:
102 You have a SET to add LISTS of plugins to the packpath (one for both
103 pack/*/start and pack/*/opt), a SET to add LISTS of things to add to the path,
104 a set to add lists of shared libraries,
105 a set of lists to add... pretty much anything.
106 Full list of these sets is at :h nixCats.flake.outputs.categories
107
108 Those lists are in sets, and thus have names.
109
110 You do this in categoryDefintions, which is a function provided a pkgs set.
111 It also recieves the values from packageDefintions of the package it is being called with.
112 It returns those sets of things mentioned above.
113
114 packageDefintions is a set, containing functions that also are provided a
115 pkgs set. They return a set of categories you wish to include.
116 If, from your categoryDefintions, you returned:
117
118 startupPlugins = {
119 general = [
120 pkgs.vimPlugins.lz-n
121 pkgs.vimPlugins.nvim-treesitter.withAllGrammars
122 pkgs.vimPlugins.telescope
123
124 ];
125 };
126
127 In your packageDefintions, if you wanted to include it in a package named
128 myCoolNeovimPackage, launched with either myCoolNeovimPackage or vi,
129 you could have:
130
131
132 packageDefinitions = {
133 myCoolNeovimPackage = { pkgs, ... }@misc: {
134 settings = {
135 aliases = [ "vi" ];
136 };
137 categories = {
138
139 general = true;
140
141 };
142 };
143
144 };
145 defaultPackageName = "myCoolNeovimPackage";
146
147 They also return a set of settings, for the full list see :h nixCats.flake.outputs.settings
148
149 Then, a package is exported and built based on that using the nixCats builder
150 function, and various flake exports such as modules based on your config
151 are made using utility functions provided.
152 The templates take care of that part for you, just add stuff to lists.
153
154 But the cool part. That set of settings and categories is translated verbatim
155 from a nix set to a lua table, and put into a plugin that returns it.
156 It also passes the full set of plugins included via nix and their store paths
157 in the same manner. This gives full transparency to your neovim of everything
158 in nix. Passing extra info is rarely necessary outside of including categories
159 and setting settings, but it can be useful, and anything other than nix
160 functions may be passed. You then have access to the contents of these tables
161 anywhere in your neovim, because they are literally a set hardcoded into a
162 lua file on your runtimpath.
163
164 You may use the :NixCats user command to view these
165 tables for your debugging. There is a global function defined that
166 makes checking subcategories easier. Simply call nixCats('the.category')!
167 It will return the nearest parent category value, but nil if it was a table,
168 because that would mean a different sub category was enabled, but this one was
169 not. It is simply a getter function for the table require('nixCats').cats
170 see :h nixCats for more info.
171
172 That is what enables full transparency of your nix configuration
173 to your neovim! Everything you could have needed to know from nix
174 is now easily passed, or already available, through the nixCats plugin!
175
176 It has a shorthand for importing plugins that arent on nixpkgs, covered in
177 :h nixCats.flake.inputs and the templates set up the outputs for you.
178 Info about those outputs is detailed in nixCats.flake.outputs.exports
179 You can also add overlays accessible to the pkgs object above, and set config
180 values for it, how to do that is at the top of the templates, and covered in
181 help at :h nixCats.flake.outputs.overlays and :h nixCats.flake.outputs.overlays
182
183 It also has a template containing some lua functions that can allow you
184 to adapt your configuration to work without nix. For more info see :h
185 nixCats.luaUtils It contains useful functions,
186 such as "did nix load neovim" and "if not nix do this, else do that"
187 It also contains a simple wrapper for lazy.nvim that does the rtp reset
188 properly, and then can be used to tell lazy not
189 to download stuff in an easy to use fashion.
190
191 The goal of the starter templates is so that the usage at the start can be as simple
192 as adding plugins to lists and calling require('theplugin').setup()
193 Most further complexity is optional, and very complex things can be achieved
194 with only minor changes in nix, and some nixCats('something') calls.
195 You can then import the finished package, and reconfigure it again
196 without duplication using the override function! see :h nixCats.overriding
197
198 ---------------------------------------------------------------------------------------
199 nixCats.templates
200 The templates may also be imported from the utils set
201 via inputs.nixCats.utils.templates
202 The following is the set where they are defined.
203
204 You may initialize them into the current directory via
205 nix flake init -t github:BirdeeHub/nixCats-nvim#$TEMPLATE_NAME
206
207 {
208 default = {
209 path = ./fresh;
210 description = "starting point template for making your neovim flake";
211 };
212 fresh = {
213 path = ./fresh;
214 description = "starting point template for making your neovim flake";
215 };
216 example = {
217 path = ./example;
218 description = "an idiomatic nixCats example configuration using lze for lazy loading and paq.nvim for backup when not using nix";
219 };
220 module = {
221 path = ./module;
222 description = ''
223 starting point for creating a nixCats module for your system and home-manager
224 '';
225 };
226 nixExpressionFlakeOutputs = {
227 path = ./nixExpressionFlakeOutputs;
228 description = ''
229 how to import as just the outputs section of the flake, so that you can export
230 its outputs with your system outputs
231
232 It is best practice to avoid using the system pkgs and its overlays in this method
233 as then you could not output packages for systems not defined in your system flake.
234 It creates a new one instead to use, just like the flake template does.
235
236 Call it from your system flake and call it with inputs as arguments.
237 '';
238 };
239 overwrite = {
240 path = ./overwrite;
241 description = ''
242 How to CONFIGURE nixCats FROM SCRATCH,
243 given only an existing nixCats package,
244 achieved via the OVERRIDE function.
245
246 Equivalent to the default flake template
247 or nixExpressionFlakeOutputs except
248 for using overrides
249
250 every nixCats package is a full nixCats-nvim
251 '';
252 };
253 luaUtils = {
254 path = ./luaUtils;
255 description = ''
256 A template that includes lua utils for using neovim package managers
257 when your config file is not loaded via nix.
258 '';
259 };
260 kickstart-nvim = {
261 path = ./kickstart-nvim;
262 description = ''
263 The entirety of kickstart.nvim implemented as a nixCats flake.
264 With additional nix lsps for editing the nix part.
265 This is to serve as the tutorial for using the nixCats lazy wrapper.
266 '';
267 };
268 overriding = {
269 path = ./overriding;
270 description = ''
271 How to RECONFIGURE nixCats WITHOUT DUPLICATION,
272 given only an existing nixCats package,
273 achieved via the OVERRIDE function.
274
275 In addition, it is also a demonstration of how to export a nixCats configuration
276 as an AppImage.
277
278 It is a 2 for 1 example of 2 SEPARATE things one could do.
279 '';
280 };
281 overlayHub = {
282 path = ./overlayHub;
283 description = ''
284 A template for overlays/default.nix
285 :help nixCats.flake.nixperts.overlays
286 '';
287 };
288 overlayFile = {
289 path = ./overlayfile;
290 description = ''
291 A template for an empty overlay file defined as described in
292 :help nixCats.flake.nixperts.overlays
293 '';
294 };
295 }
296
297 ---------------------------------------------------------------------------------------
298 vim:tw=78:ts=8:ft=help:norl: