HOME TOC REPO
1   ---------------------------------------------------------------------------------------
2   INSTALLATION:                                                   nixCats.installation_options
3   
4   
5     nix shell github:BirdeeHub/nixCats-nvim
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  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       # etc ...
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     # see :help nixCats.flake.outputs.packageDefinitions
130     packageDefinitions = {
131       myCoolNeovimPackage = { pkgs, ... }@misc: {
132         settings = {
133           aliases = [ "vi" ];
134         };
135         categories = {
136           # setting the value to true will include it!
137           general = true;
138           # yes you can nest them
139         };
140       };
141       # You can return as many packages as you want
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: