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