HOME TOC REPO
1   ---------------------------------------------------------------------------------------
2   INSTALLATION:                                                   nixCats.installation_options
3   
4   
5     nix shell github:BirdeeHub/nixCats-nvim?dir=templates/example
6     # then launch with
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    # Choose one of the following:
16    # flake template:
17    nix flake init -t github:BirdeeHub/nixCats-nvim
18    # the outputs function of the flake template but as its own file
19    # callable with import ./the/dir { inherit inputs; }
20    # to recieve all normal flake outputs
21    nix flake init -t github:BirdeeHub/nixCats-nvim#nixExpressionFlakeOutputs
22  
23    # for utilities for functionality without nix
24    # added at lua/nixCatsUtils also run:
25    nix flake init -t github:BirdeeHub/nixCats-nvim#luaUtils
26    # contains things like "is this nix?" "do this if not nix, else do that"
27    # needs to be in your config at lua/nixCatsUtils,
28    # because if you dont use nix to load neovim,
29    # nixCats (obviously) can't provide you with anything from nix!
30  
31    # If using zsh with extra regexing, be sure to escape the #
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       # etc ...
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     # see :help nixCats.flake.outputs.packageDefinitions
132     packageDefinitions = {
133       myCoolNeovimPackage = { pkgs, ... }@misc: {
134         settings = {
135           aliases = [ "vi" ];
136         };
137         categories = {
138           # setting the value to true will include it!
139           general = true;
140           # yes you can nest them
141         };
142       };
143       # You can return as many packages as you want
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         contains an example home manager module and an example nixos module in
226         separate files.
227       '';
228     };
229     nixExpressionFlakeOutputs = {
230       path = ./nixExpressionFlakeOutputs;
231       description = ''
232         how to import as just the outputs section of the flake, so that you can export
233         its outputs with your system outputs
234 
235         It is best practice to avoid using the system pkgs and its overlays in this method
236         as then you could not output packages for systems not defined in your system flake.
237         It creates a new one instead to use, just like the flake template does.
238 
239         Call it from your system flake and call it with inputs as arguments.
240       '';
241     };
242     overwrite = {
243       path = ./overwrite;
244       description = ''
245         How to CONFIGURE nixCats FROM SCRATCH,
246         given only an existing nixCats package,
247         achieved via the OVERRIDE function.
248 
249         Equivalent to the default flake template
250         or nixExpressionFlakeOutputs except
251         for using overrides
252 
253         every nixCats package is a full nixCats-nvim
254       '';
255     };
256     luaUtils = {
257       path = ./luaUtils;
258       description = ''
259         A template that includes lua utils for using neovim package managers
260         when your config file is not loaded via nix.
261       '';
262     };
263     kickstart-nvim = {
264       path = ./kickstart-nvim;
265       description = ''
266         The entirety of kickstart.nvim implemented as a nixCats flake.
267         With additional nix lsps for editing the nix part.
268         This is to serve as the tutorial for using the nixCats lazy wrapper.
269       '';
270     };
271     overriding = {
272       path = ./overriding;
273       description = ''
274         How to RECONFIGURE nixCats WITHOUT DUPLICATION,
275         given only an existing nixCats package,
276         achieved via the OVERRIDE function.
277 
278         In addition, it is also a demonstration of how to export a nixCats configuration
279         as an AppImage.
280 
281         It is a 2 for 1 example of 2 SEPARATE things one could do.
282       '';
283     };
284     overlayHub = {
285       path = ./overlayHub;
286       description = ''
287         A template for overlays/default.nix
288         :help nixCats.flake.nixperts.overlays
289       '';
290     };
291     overlayFile = {
292       path = ./overlayfile;
293       description = ''
294         A template for an empty overlay file defined as described in
295         :help nixCats.flake.nixperts.overlays
296       '';
297     };
298   }
299 
300 ---------------------------------------------------------------------------------------
301 vim:tw=78:ts=8:ft=help:norl: