HOME TOC REPO

1   =======================================================================================
2   Flake Help                                                      nixCats.flake
3   
4   A Lua-natic's neovim flake, with extra cats! nixCats!
5   
6   This is the documentation for the flake itself.
7   This flake uses nix for importing plugins, lsps, dependencies, and more,
8   in place of usual nvim package managers such as packer, lazy or mason.
9   
10  Everything else is done in a regular lua config style.
11  Download in flake.nix and then, simply pretend the root of the flake 
12  is the root of your Lua config. 
13  
14  *******************************************************
15  AN IMPORTANT NOTE:
16  
17  <1> When editing the files within the flake directory,
18  nix will not package a new file if it isn't staged in git.
19  run git add before rebuilding it whenever adding a new file.
20  Using wrapRc = true would mean this also applies to lua files.
21  Only tracked files will recieve their updates when
22  rebuilt without git add being ran first. New files need to be added.
23  *******************************************************
24  
25  Related:
26  For detecting what was included by 
27  the flake in your Lua, see:
28  :help nixCats
29  
30  stdpath('config') will still point to ~/.config/<configDirName>.
31  But your lua config will be in the store.
32  This is ok, because most of the reason for a plugin to use
33  it would be to write to it, and we cant write to store paths anyway. 
34  You could use require('nixCats').configDir,
35  or nixCats('nixCats_config_location')
36  to get current config directory for your uses, if ever necessary.
37  It will be present and correct regardless of settings.
38  
39  However if you did not use nix at all and did not run the setup
40  function, of course the nixCats plugin wont be there to ask.
41  
42  The setup function from require('nixCatsUtils').setup
43  will provide a mock nixCats plugin with SOME values
44  and empty tables to prevent accidental indexing errors.
45  You could instead do require('nixCatsUtils').isNixCats to default to
46  vim.fn.stdpath('config') if all you wanted was this path though.
47  
48  Keep in mind they will be read-only if in the store!
49  
50  =======================================================================================
51  Flake Inputs:                                            nixCats.flake.inputs
52  
53  If a plugin does not have an extra build step, and are not on nixpkgs,
54  you may use this format to import them, replacing the fields marked with <>
55  
56      "plugins-<pluginName>" = {
57        url = "github:<userName>/<repositoryName>";
58        flake = false;
59      };
60  
61  More info on flake url syntax at:
62  https://nixos.org/manual/nix/stable/command-ref/new-cli/nix3-flake.html#examples
63  You may also use this syntax to pin the version of a plugin regardless of if
64  you ran nix flake update or not.
65  You may choose the directory, branch, commit, tag, or even directory
66  imported.
67  
68  All inputs named in the plugins-<pluginName> format will be added to pkgs
69  at pkgs.neovimPlugins.<pluginName> for you to add to your configuration.
70  
71  If the plugin has a dot . character in it's name, you should name it something else.
72  Because . is not a valid character in an identifier in nix.
73  
74  The name here only affects the filename of the overall plugin, and should
75  only affect things like vim.cmd("packadd <filename>") that refer to
76  the actual filename of the plugin. Usually I would replace it with -
77  You will then add it to categoryDefinitions later with the NEW name.
78  
79  If you use this method to import a plugin, and really dont
80  want to change the filename of the plugin when they have a
81  dot in their name, you may
82  swap the call to (utils.standardPluginOverlay inputs)
83  with (utils.sanitizedPluginOverlay inputs)
84  and then plugins-plugin.name would become pkgs.neovimPlugins.plugin-name
85  but neovim would see it as vim.cmd("packadd plugin.name") still
86  
87  If they have a build step or are not a plugin, 
88  i.e. an lsp, or if they are a plugin from a flake,
89  dont name them in that format.
90  If they are a plugin from a flake, they can be added directly,
91  or they may be added as an overlay if offered.
92  If they are anything else they arent a plugin at all and obviously
93  should thus not be added as a plugin via plugins-<pluginName>
94  
95  If they are on nixpkgs, you dont need to put them in inputs,
96  because you will be able to access them through pkgs.vimPlugins variable.
97  Most plugins will not require you to use the inputs section due to being on nixpkgs.
98  But you may still use it to pin the plugin to a specific version.
99  
100 If you decided not to use utils.sanitizedPluginOverlay
101 and wanted to do it with utils.standardPluginOverlay:
102 If in your inputs you had:
103 
104   "plugins-<plugin-name>" = {
105     url = "github:<userName>/<repository.name>";
106     flake = false;
107   };
108 
109 Where you put plugins in your categoryDefinitions, instead of:
110 
111   pkgs.neovimPlugins.<plugin-name>
112 
113 You would put this:
114 
115   (pkgs.neovimPlugins.<plugin-name>.overrideAttrs { pname = "<plugin.name>"; })
116 
117 overrideAttrs can be used for a lot more than just fixing the name of the
118 imported plugin. See:
119 https://ryantm.github.io/nixpkgs/using/overrides/
120 
121 If they have a build step and are not on nixpkgs,
122 you will deal with them in overlays/customBuildsOverlay.nix
123 then import them into a category of the builder. 
124 Alternatively you may use overrideAttrs as mentioned above instead of an
125 overlay for these sorts of packages, but this would possibly get messy if the
126 build step were complex.
127 
128 =======================================================================================
129 Flake Outputs Introduction                              nixCats.flake.outputs
130 
131 With our inputs to our flake taken care of:
132 First, we take care of importing our utils set from nixCats.
133 The reason we are doing this now, is so that it can be defined outside of
134 the utils.eachSystem function, and thus we can export it
135 without having to include a system variable when we import it somewhere else.
136 
137 We also define our luaPath, which is the path to be loaded into the store as
138 your new neovim config directory. (see :help 'rtp' for the directories
139 available for you to use!)
140 
141 We also define our extra_pkg_config, which is used when initializing the
142 nixpkgs instance that will build your neovim! Its the same one from
143 pkgs = import nixpkgs { inherit system; overlays = []; config = {}; }
144 
145   outputs = { self, nixpkgs, ... }@inputs: let
146     # In the templates, this is inherit (inputs.nixCats) utils;
147     utils = import ./nix;
148     # path the the store path to be loaded as neovim config directory
149     luaPath = "${./.}";
150     # used when initializing the nixpkgs instance
151     extra_pkg_config = {
152       # allowUnfree = true;
153     };
154 
155                                            nixCats.flake.outputs.getOverlays
156 We call flake utils to get system variable for all default systems.
157 It simply calls the function with each system value, and maps the resulting
158 set from { mySet = {}; } to { mySet.${system} = {}; }
159 Many overlays require being accessed via ${system} variable in this manner,
160 and thus there is a method for handling it in nixCats.
161 
162 No overlays SHOULD be exported requiring the ${system} variable to access.
163 However, some are (such as codeium, a free ai plugin) and thus, we will wrap this anyway.
164 
165   inherit (utils.eachSystem nixpkgs.lib.platforms.all (system: let
166                   /* utils.eachSystem is just flake-utils.lib.eachSystem */
167          /* list of overlays from ./overlays is added to the rest of the list */
168     dependencyOverlays = (import ./overlays inputs) ++ [
169       # This overlay grabs all the inputs named in the format
170       # `plugins-<pluginName>`
171       # Once we add this overlay to our nixpkgs, we are able to
172       # use `pkgs.neovimPlugins`, which is a set of our plugins.
173       (utils.standardPluginOverlay inputs)
174       # add any flake overlays here.
175       inputs.neorg-overlay.overlays.default
176       inputs.lz-n.overlays.default
177       # stuff like this is why this part is done this way.
178       inputs.codeium.overlays.${system}.default
179     ];
180     # these overlays will be wrapped with ${system}
181     # and we will call the same utils.eachSystem function
182     # later on to access them.
183   in { inherit dependencyOverlays; })) dependencyOverlays;
184 
185 This will allow us to pass system independent overlays to our module options,
186 even when importing overlays from improperly formed flakes.
187 
188 Managing the system variable in combination with overlays
189 can be one of the hardest parts of flake usage.
190 This flake resolves our pkgs instance for neovim itself to help with this,
191 and takes care of passing the correct pkgs instance
192 to the categoryDefinitions for use in defining your plugins.
193 
194 ALTERNATIVELY
195 
196 They could also just be a list of overlays!
197 
198   dependencyOverlays = (import ./overlays inputs) ++ [
199     (utils.standardPluginOverlay inputs)
200     inputs.neorg-overlay.overlays.default
201     inputs.lz-n.overlays.default
202 
203     # when other people mess up their overlays by wrapping them,
204     # you may instead call this function on their overlay.
205     # it will check if it has the system in it.
206     # if so, it will call the function with the system
207     # and return the desired overlay
208     (utils.fixSystemizedOverlay inputs.codeium.overlays
209       (system: inputs.codeium.overlays.${system}.default)
210     )
211   ];
212 
213 
214                                                nixCats.flake.outputs.overlays
215 The two major things of note in this overlays section.
216 Regardless of which above method you choose. 
217   (utils.standardPluginOverlay inputs) # return type: a single overlay
218   # and
219   (import ./overlays inputs) # type: List of Overlays
220 
221 <1>
222 -- The first to explain is utils.standardPluginOverlay:
223 You do not need to edit it to use it.
224 Usage of this overlay is described in:
225 :h nixCats.flake.inputs
226 along with its friend, utils.sanitizedPluginOverlay
227 
228 It takes all the inputs named in the format
229 plugins-somepluginname and makes them into plugins. 
230 If the plugin doesn't have a build step,
231 and it wasnt on nixpkgs, then use this method.
232 Access them to add them to a category of the builder function 
233 with pkgs.neovimPlugins.somepluginname
234 
235 <2>
236 -- The second is overlays/customBuildsOverlay.nix:
237 
238 It is imported via overlays/default.nix above
239 
240 If you need to interact with one of these overlays, it will be this one.
241 You should not need to do it much.
242 overlays/default.nix imports this overlay and any others like it.
243 see :help nixCats.flake.nixperts.overlays
244 
245 It is used for defining plugins with build steps that 
246 were not well handled by nixpkgs.
247 It is passed flake inputs, and super is pkgs.
248 Define the things within the file. 
249 Then, access plugins defined there later 
250 with 'pkgs.nixCatsBuilds.somepluginname'
251 
252 If you decide you wish to split your customBuildsOverlay up, 
253 see :help nixCats.flake.nixperts.overlays
254 or look at the overlays/default.nix file.
255 
256 <IMPORTANT> When defining your overlays, they will be
257 defined in a SEPARATE LIST named <dependencyOverlays>.
258 You will need <dependencyOverlays> later.
259 
260 ---------------------------------------------------------------------------------------
261                                             nixCats.flake.outputs.categories
262 Then we define what is in our categories!
263 This section is a function that takes the package definition for this
264 particular package as an argument.
265 The builder will call it with that argument, you may use it.
266 This allows categoryDefinitions to access their packages categories and settings,
267 which allows categoryDefinitions to be much more dynamic.
268 
269 These are the things you can return:
270 
271   categoryDefinitions = { pkgs, settings, categories, name, ... }@packageDef: {
272 
273 <propagatedBuildInputs> 
274   a flexible set of categories, each containing internal
275   BUILD TIME dependencies. Will also be available to the devShell.
276 
277 <lspsAndRuntimeDeps>
278   a flexible set of categories, each containing LSP's or 
279   other internal runtime dependencies such as ctags or debuggers
280   these are available to the PATH while within the neovim program.
281   this includes the neovim terminal.
282 
283 <startupPlugins>
284   a flexible set of categories, each containing startup plugins.
285   Startup plugins are loaded and can be required. 
286 
287 <optionalPlugins>
288   a flexible set of categories, each containing optional plugins.
289   Optional plugins need to be added with packadd before being required.
290   Use :NixCats pawsible to see the names to use for packadd
291 
292 <sharedLibraries>
293   a flexible set of categories, each containing a derivation for
294   a runtime shared library. Will be prepended to the LD_LIBRARY_PATH variable.
295 
296 <environmentVariables>
297   a flexible set of categories, each containing an ATTRIBUTE SET of 
298   EnvironmentVariableName = "EnvironmentVariableValue";
299 
300 <extraWrapperArgs>
301   a flexible set of categories, each containing extra wrapper arguments.
302   If you don't know what that is, see here:
303 github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/setup-hooks/make-wrapper.sh
304 
305 <extraLuaPackages>
306   a flexible set of categories, each containing FUNCTIONS 
307   that return lists of extra Lua packages.
308   These functions are the same thing that you would pass to lua.withPackages.
309   Is used to populate $LUA_PATH and $LUA_CPATH
310 
311 <extraPython3Packages> 
312   a flexible set of categories, each containing FUNCTIONS
313   that return lists of python packages.
314   These functions are the same thing that you would pass to python.withPackages.
315   You may get the path to this python environment in your lua config via
316   vim.g.python3_host_prog
317   or run from nvim terminal via :!<packagename>-python3
318 
319 <extraPython3wrapperArgs>
320   the same as extraWrapperArgs but for bundled python3 executable
321 
322 <optionalLuaPreInit>
323   a flexible set of categories, each containing a lua string
324   that will be ran before sourcing your init.lua
325   Yes it can access nixCats.
326   It is not the recommended way to create lua for this flake, 
327   but it may be useful in editing flake imports 
328   of other already configured setups following the nixCats format.
329 <optionalLuaAdditions>
330   a flexible set of categories, each containing a lua string
331   that will be ran after sourcing your init.lua
332   Yes it can access nixCats.
333   It is not the recommended way to create lua for this flake, 
334   but it may be useful in editing flake imports 
335   of other already configured setups following the nixCats format.
336 <bashBeforeWrapper>
337   a flexible set of categories, each containing arbitrary bash code
338   to run before the wrapper starts within the wrapper's bash environment.
339   CAUTION: only use this if you know what you are doing and why you need
340   to do it. Whenever possible, use extraWrapperArgs instead.
341 }
342 
343 In essence, the contents of each set listed here are filtered
344 based on the packageDefinitions set you provide, 
345 where by including categoryname = true; you enable that category.
346 :help nixCats.flake.outputs.packageDefinitions
347 
348 It will remove duplicate items, so feel free to include the same thing in
349 multiple categories if it suits your purposes.
350 
351 It does this recursively. (explained below)
352                             nixCats.flake.outputs.categoryDefinitions.scheme
353 
354 If, inside one of these main sets, you had another set,
355 it would consider that a subcategory, and you could enable it
356 just like you do with a normal category, by setting a value with the
357 corresponding attribute path to true in the category
358 set of nixCats.flake.outputs.packageDefinitions.
359 You can nest them as much as you like, or just have a category that is a
360 single derivation.
361 
362 There is a behavior to keep in mind.
363 
364 If in your categoryDefinitions you had the following:
365 
366     environmentVariables = {
367       test = {
368         subtest1 = {
369           CATTESTVAR = "It worked!";
370         };
371         subtest2 = {
372           CATTESTVAR3 = "It didn't work!";
373         };
374       };
375     };
376     extraWrapperArgs = {
377       test = [
378         '' --set CATTESTVAR2 "It worked again!"''
379       ];
380     };
381 
382 And in your packageDefinitions set, under categories, you had the following:
383 
384     test = {
385       subtest1 = true;
386     };
387 
388 you could echo $CATTESTVAR and $CATTESTVAR2 in your terminal to see them.
389 However you could not echo $CATTESTVAR3.
390 
391 All items that are not attributes of the parent set will be included
392 when you enable a subcategory. This includes lists, strings, functions, etc...
393 
394 However, attributes will not and you must explicitly enable all attributes of
395 a subcategory if you set even 1 explicitly.
396 
397 Thus to include CATTESTVAR3, you would have to enable it like so: 
398     test = {
399       subtest1 = true;
400       subtest2 = true;
401     };
402  However, those are all the items in the test category.
403 So instead we can do this to enable all the subcategories in test. 
404     test = true;
405 
406 This applies in many situations. Take this one for example.
407 
408     lspsAndRuntimeDeps = {
409       neonixdev = {
410         inherit (pkgs)
411           nix-doc nil lua-language-server nixd; 
412       };
413     };
414     startupPlugins = {
415       neonixdev = with pkgs.vimPlugins; [
416         neodev-nvim
417         neoconf-nvim
418       ];
419     };
420 
421  If you were to put the following in your packageDefinitions: 
422     neonixdev.nix-doc = true;
423 
424  neodev-nvim and neoconf-nvim would still be included.
425  However, nil, lua-language-server, and nixd would not be!
426  You would need to pick which of those you wanted separately.
427  Sometimes this is the desired behavior.
428  Sometimes it is not and a list of packages would be better suited.
429 
430  You may also use the packageDef variable within categoryDefinitions
431  to get access to the set of categories and settings that are being
432  used to define the current package being built!
433 
434     themer = with pkgs.vimPlugins;
435       (builtins.getAttr packageDef.categories.colorscheme {
436           # Theme switcher without creating a new category
437           "onedark" = onedark-vim;
438           "catppuccin" = catppuccin-nvim;
439         }
440       );
441 
442   In addition to all this, if a plugin is defined within a list, it may
443   instead be defined within an attribute set that also contains config
444   to be ran after sourcing init.lua and optionalLuaAdditions
445   to do this, you may use the following syntax in opt or start sections: 
446     [
447       # you may add a plugin to a category list in any of these ways
448       { plugin = derivation; config.lua = ""; config.vim = "";}
449       { plugin = derivation; config = ""; type = "<viml or lua>"; }
450       { plugin = derivation; config = ""; } # defaults to viml
451       { plugin = derivation; }
452       # all the above options can accept an optional = bool;
453       # to override its presence in either startupPlugins or optionalPlugins
454       derivation
455       # plain derivation does not need to be in a list, but it should be
456       # anyway. It could be on its own though and would act as its own
457       # category.
458     ]
459 
460 ---------------------------------------------------------------------------------------
461 Package Generation:                           nixCats.flake.outputs.packageDefinitions
462 
463 generate packages by calling that builder function we just created.
464 Place them in the packageDefinitions set.
465 
466 First, pick the set of settings you wish to include.
467 
468 Then, pass it a set of named boolean values like this:
469 { categoryname1 = true; categoryname2 = false; etc... }
470 False may be omitted. True may not.
471 Only true matters for what plugins will be added.
472 
473 These categories are defined in the Builder function above 
474 by placing named lists of plugins in the flexible sets provided.
475 The category names are the names of those lists. 
476 Add a new list, then enable the category here.
477 
478 If you have categories with the same name in 
479 multiple different sets outlined above in the builder,
480 all plugins in those categories will be
481 included when you set "thatname = true;" here.
482 hence, general = true; will include the general lspsAndDeps category,
483 as well as the general startupPlugins category.
484 
485 an example package definition:
486 
487   packageDefinitions = {
488     nixCats = { pkgs, ... }: {
489       setting = {
490         wrapRc = true;
491         # nvimSRC = inputs.neovim;
492         aliases = [ "viCat" ];
493       };
494       categories = {
495         custom = true;
496         gitPlugins = true;
497         general = true;
498         neonixdev = true;
499 
500         # this does not have an associated category of plugins, 
501         # but lua can still check for it
502         lspDebugMode = false;
503 
504         # you could also pass something else and it calls 
505         # builtins.toString on it and passes it in as a string
506         theBestCat = "says meow!!!";
507         # maybe you need to pass a port or path in or something idk.
508         # you could :lua print(require('nixCats').theBestCat)
509       };
510     };
511   };
512 
513 You can use the nixCats plugin for the set you define here in your lua
514 It returns a lua table of the same format.
515 
516 see :help nixCats
517 
518 For more nuances on enabling categories and subcategories, see above at
519 :help nixCats.flake.outputs.categoryDefinitions.scheme
520 
521 ----------------------------------------------------------------------------------------
522 Settings                                       nixCats.flake.outputs.settings
523 
524 These are the defaults:
525 
526     default_settings = {
527       # YOU ARE IN CHARGE OF MAKING SURE THESE ALIASES DO NOT COLLIDE WITH
528       # ANYTHING ELSE
529       # [ "takes" "a" "list" "of" "strings" "and" "makes" "an" "alias" "for" "each" ];
530       aliases = null;
531       viAlias = false;
532       vimAlias = false;
533 
534       # so that you can see it in the store
535       extraName = "";
536 
537       withRuby = true;
538       withPython3 = true;
539       withNodeJs = false;
540       withPerl = false;
541 
542       # do you want to package the lua from this flake in the store?
543       # or would you rather it just read it in your .config/<configDirName>?
544       # nixCats and this help will work either way.
545       # packages with wrapRc = false are for quick changes to lua.
546       # it is not for being ran from anywhere via nix run, because the config
547       # was not wrapped with the program.
548       wrapRc = true;
549 
550       # What should the name of the folder within standard directories
551       # i.e. .config, .local/share, .local/state, .cache, etc... be?
552       # This option is very useful when you want 
553       # to clone an unwrapped config straight to the .config dir.
554       # It is also helpful to prevent other nvim packages sharing data folders.
555       # see :help `$NVIM_APPNAME`
556       configDirName = "nvim";
557 
558       # Only active when wrapRc = false, this option allows you to specify
559       # an absolute path to the unwrapped config directory.
560       # This is not a nix path. This is the unwrapped config directory.
561       # This means you are going to need to make
562       # sure that it points the right place on the current machine.
563       unwrappedCfgPath = null;
564       # Will not change anything other than config directory, configDirName
565       # is still needed for .local/share or .cache and the like
566 
567       # use this to pin a specific neovim version.
568       # This one will specify the base neovim derivation to use.
569       neovim-unwrapped = null;
570       # This one will just override the src value of the neovim in nixpkgs
571       # import it in flake inputs with flake = false,
572       nvimSRC = null;
573 
574       # These 2 options are useful for when you want to allow your dev shells
575       # to override things such as lsps and shared libraries that you have
576       # already in your configuration.
577       suffix-path = false;
578       # causes lspsAndDeps to be added to the END of
579       # PATH instead of the start
580       suffix-LD = false;
581       # causes sharedLibraries to be added to the END of
582       # LD_LIBRARY_PATH instead of the start
583 
584       # unsets PYTHONSAFEPATH variable.
585       # Can cause issues with reproducibility,
586       # can fix some stuff
587       disablePythonSafePath = false;
588 
589       # optional, specify custom store path gemdir
590       # must contain a gemset.nix like one generated by bundix
591       # must contain the neovim gem
592       # for further info, see
593       # https://github.com/NixOS/nixpkgs/tree/74ad6cb1d2b14edb4ad1fffc0791e94910c61453/pkgs/applications/editors/neovim/ruby_provider
594       # https://github.com/BirdeeHub/neovim_ruby_updater
595       gem_path = null;
596       # If you are using neovim-unwrapped from nixpkgs itself,
597       # there is a good chance your neovim
598       # will not be able to find it regardless of settings.
599       # thus withRuby and gem_path options may not work
600       # It works great using https://github.com/nix-community/neovim-nightly-overlay
601       # so this seems to be an upstream issue, as all the expected variables
602       # are still being set correctly.
603     };
604 
605 
606 QUICK TIP: wrapRc
607 
608 The wrapRc option is very useful for testing lua changes.
609 It removes the need to stage and rebuild to see your lua changes reflected.
610 You will still need to rebuild when making changes to nix regardless of the
611 value of wrapRc
612 
613 However it also means that the lua isn't going run if it isn't in the right
614 folder, i.e. when installed and ran from github with nix run
615 
616 If the lua is not in vim.fn.stdpath('config'), wrapRc = false will not work.
617 By default this is ~/.config/nvim on linux systems, although we can
618 change nvim to whatever we wish via the configDirName setting.
619 
620 Alternatively, you can set the unwrappedCfgPath option to allow the
621 configuration to be set to an absolute path. You still may want to set
622 the configDirName option anyway to change the data directories,
623 or explicitly keep it the same on both so that they share stuff like auths.
624 
625 The most convenient way to use this is the following:
626 Make a second identical packageDefinition, but with wrapRc disabled.
627 Then install both the wrapped one and unwrapped one with different aliases.
628 When you want to hack in lua, use unwrapped! When you're done, just rebuild
629 and go back to the wrapped one.
630 
631 The nixCats main flake.nix file has an example of this with nixCats
632 and regularCats.
633 
634 Then, when testing lua changes, you run the other package and have a vanilla
635 neovim experience, only rebuilding when you install new packages.
636 
637 When you are satisfied, simply rebuild and go back to using the main package,
638 as it was the same except for the single option!
639 
640 --------------------------------------------------------------------------------------
641 Neovim Builder Creation:                        nixCats.flake.outputs.builder
642 
643 Now we define our builder function.
644 We inherit utils.baseBuilder which is
645 a function that takes 5 arguments. It is defined in ./nix/builder
646 Right now we are going to call it with just the first 4 of them. This will
647 leave us with a function that takes 1 argument.
648 That argument is the name of the neovim package to be packaged.
649 
650 1. The path to the lua to include (in the flake, we use the self variable to get
651      this path and wrap the lua when wrapRc = true)
652 
653 2. A set containing:
654   The dependencyOverlays set or list,
655   extra_pkg_config, nixpkgs, nixCats_passthru, and system so it can
656   resolve pkgs and pass it where it needs to go.
657 
658 3. our function that takes an individual package definition
659      and returns a set of categoryDefinitions.
660 
661 4. our set of packageDefinitions see: nixCats.flake.outputs.packageDefinitions
662 
663 It is now a function that takes a name, and returns your chosen neovim package.
664 
665   # It requires the system variable to build a package.
666   utils.eachSystem nixpkgs.lib.platforms.all (system: let
667     # create our builder for our exports
668     inherit (utils) baseBuilder;
669     nixCatsBuilder = baseBuilder luaPath {
670       inherit nixpkgs system dependencyOverlays extra_pkg_config;
671     } categoryDefinitions packageDefinitions;
672     # it can take a name of a package in packageDefinitions
673     # and return the package!
674     defaultPackage = nixCatsBuilder defaultPackageName;
675     # ... rest of the outputs section explained
676     # below in :h nixCats.flake.outputs.exports ...
677 
678 If you use it wrong, you will most likely get this error message:
679 
680   The following arguments are accepted:
681 
682   # -------------------------------------------------------- #
683 
684   # the path to your ~/.config/nvim replacement within your nix config.
685   luaPath: # <-- must be a store path
686 
687   { # set of items for building the pkgs that builds your neovim
688 
689     , nixpkgs # <-- required
690     , system # <-- required
691 
692     # type: (attrsOf listOf overlays) or (listOf overlays) or null
693     , dependencyOverlays ? null 
694 
695     # import nixpkgs { config = extra_pkg_config; inherit system; }
696     , extra_pkg_config ? {} # type: attrs
697 
698     # any extra stuff for finalPackage.passthru
699     , nixCats_passthru ? {} # type: attrs
700   }:
701 
702   # type: function with args { pkgs, settings, categories, name, ... }:
703   # returns: set of sets of categories
704   # see :h nixCats.flake.outputs.categories
705   categoryDefinitions: 
706 
707   # type: function with args { pkgs, ... }:
708   # returns: { settings = {}; categories = {}; }
709   packageDefinitions: 
710   # see :h nixCats.flake.outputs.packageDefinitions
711   # see :h nixCats.flake.outputs.settings
712 
713   # name of the package to built from packageDefinitions
714   name: 
715 
716   # -------------------------------------------------------- #
717 
718   # Note:
719   When using override, all values shown above will
720   be top level attributes of prev, none will be nested.
721   i.e. 
722   finalPackage.override (prev: { inherit (prev) dependencyOverlays; })
723       NOT prev.pkgsargs.dependencyOverlays or something like that
724 
725 ---------------------------------------------------------------------------------------
726 Flake Exports and Export options               nixCats.flake.outputs.exports
727 
728 They look something like this:
729 
730   # this first section is the outputs we
731   # want to wrap with the ${system} variable
732   utils.eachSystem nixpkgs.lib.platforms.all (system: let
733     # this is the builder (see :h nixCats.flake.outputs.builder above):
734     nixCatsBuilder = utils.baseBuilder luaPath {
735       inherit nixpkgs system dependencyOverlays extra_pkg_config;
736     } categoryDefinitions packageDefinitions;
737     # then it takes our categoryDefinitions and packageDefinitions
738 
739     # then we build a package to serve as the default one by providing its name.
740     defaultPackage = nixCatsBuilder defaultPackageName;
741 
742     # this is just for using utils in the following section such as pkgs.mkShell
743     # The one used to build neovim is resolved inside the builder
744     # and is passed to our categoryDefinitions and packageDefinitions
745     pkgs = import nixpkgs { inherit system; };
746     # as you can see, "resolve pkgs" does not mean anything fancy.
747     # however, with overlays and system variable,
748     # sometimes you can get yourself in a loop when
749     # doing more advanced things. So this flake takes care of that for you.
750     # it will make sure pkgs is passed to the categoryDefinitions and packageDefinitions
751   in
752   {
753     # these outputs will be wrapped with ${system} by utils.eachSystem
754 
755     # this will make a package out of each of the packageDefinitions defined above
756     # and set the default package to the one passed in here.
757     packages = utils.mkAllWithDefault defaultPackage;
758 
759     # choose your package for devShell
760     # and add whatever else you want in it.
761     devShells = {
762       default = pkgs.mkShell {
763         name = defaultPackageName;
764         packages = [ defaultPackage ];
765         inputsFrom = [ ];
766         shellHook = ''
767         '';
768       };
769     };
770 
771   }) // {
772 
773     # these outputs will be NOT wrapped with ${system}
774 
775     # now we can export some things that can be imported in other
776     # flakes, WITHOUT needing to use a system variable to do it.
777     # and update them into the rest of the outputs returned by the
778     # eachSystem function.
779 
780     # this will make an overlay out of each of the packageDefinitions defined
781     # and set the default overlay to the one named here.
782     overlays = utils.makeOverlays luaPath {
783       # we pass in the things to make a pkgs variable to build nvim with later
784       inherit nixpkgs dependencyOverlays extra_pkg_config;
785       # and also our categoryDefinitions
786     } categoryDefinitions packageDefinitions defaultPackageName;
787 
788     # we export a nixos module to allow configuration from configuration.nix
789     # allows you to either inherit values from your main flake, or start fresh
790     nixosModules.default = utils.mkNixosModules {
791       inherit dependencyOverlays luaPath defaultPackageName
792         categoryDefinitions packageDefinitions nixpkgs;
793     };
794     # and the same for home manager
795     homeModule = utils.mkHomeModules {
796       inherit dependencyOverlays luaPath defaultPackageName
797         categoryDefinitions packageDefinitions nixpkgs;
798     };
799     inherit utils;
800     inherit (utils) templates;
801   };
802 
803 
804 We also export the <utils> set so we can get it easier later,
805 along with <templates> which are inside it.
806 The <utils> is also exported by the passthru of all packages based on nixCats
807 but exporting it separately makes it easier to get again later.
808 
809 It also contains all the other functions used in creating the format in the
810 templates, including the main builder!
811 (see :h nixCats.flake.outputs.builder for builder explanation)
812 
813 In addition to the templates and the builder function, the utils set contains:
814 
815 <standardPluginOverlay> inputs:
816 allows for inputs named plugins-something to be
817 turned into an overlay containing them as plugins automatically
818 
819 <sanitizedPluginOverlay> inputs:
820 optional replacement for utils.standardPluginOverlay.
821 If you give it an input named plugins-foo.bar
822 you can get it at pkgs.neovimPlugins.foo-bar
823 and still packadd foo.bar because it keeps the folder name the same.
824 To use, in your overlays section:
825 Replace (utils.standardPluginOverlay inputs)
826 with (utils.sanitizedPluginOverlay inputs)
827 
828 <fixSystemizedOverlay> overlaysSet: outfunc:
829 takes 2 arguments.
830 a set of system-wrapped overlays,
831 and a function (system: overlays.${system}.<desired_overlay>)
832 returns the desired overlay, with the system resolved.
833 
834 <mergeCatDefs> oldCats: newCats:
835 for merging categoryDefinitions and individual packages in packageDefinitions,
836 will recursively update up to the first thing not an attrset.
837 For our purposes, we do not consider derivations to be attrsets.
838 It takes 2 functions that return sets and returns
839 a function which calls them both and merges the result as desired above.
840 
841 <mergeOverlayLists> oldOverlist: newOverlist: self: super:
842 for merging lists of overlays together properly
843 to avoid naming conflict issues.
844 Takes 2 lists of overlays, returns a single merged overlay.
845 Merging logic is the same as mergeCatDefs
846 
847 <safeOversList> { dependencyOverlays, system ? null }:
848 Simple helper function for mergeOverlayLists
849 Pass it the inherited dependencyOverlays, always recieve a list back.
850 Then feed it to mergeOverlayLists.
851 If dependencyOverlays is an attrset, system string is required.
852 If dependencyOverlays is a list, system string is ignored
853 If invalid type or system, returns an empty list
854 
855 <mkNixosModules> {
856     defaultPackageName = "nixCats";
857     luaPath = "${./.}";
858     inherit nixpkgs dependencyOverlays
859       categoryDefinitions packageDefinitions extra_pkg_config;
860 };
861 Will create a nixos module that you can import in configuration.nix
862 If you do not have a luaPath, you may pass it a keepLua builder
863 See :help nixCats.flake.outputs.exports.mkNixosModules
864 The packages also export a module with defaultPackageName
865 set to THEIR package name via their passthru variable using this function.
866 
867 <mkHomeModules>
868 The same as mkNixosModules above, but for home manager.
869 
870 <mkAllWithDefault> package:
871 makes each package in the packageDefinitions this package was made from
872 and also a default one out of the one passed in.
873 
874 <mkAllPackages> package:
875 makes each package in the packageDefinitions this package was made from
876 
877 <mkPackages> finalBuilder: packageDefinitions: defaultName:
878 makes each package in packageDefinitions and also a default one
879 where finalBuilder is the builder function with all but the name applied
880 
881 <mkExtraPackages> finalBuilder: packageDefinitions:
882 mkPackages just calls this and adds a default one.
883 where finalBuilder is the builder function with all but the name applied
884 
885 <makeOverlays> luaPath: {
886         nixpkgs
887         , extra_pkg_config ? {}
888         , dependencyOverlays ? null
889         , nixCats_passthru ? {}
890         , ...
891       }@pkgsParams: categoryDefFunction: packageDefinitions:
892       defaultName:
893 makes an overlay for each package and also a default one
894 These are basically the same as the arguments to utils.baseBuilder
895 dependencyOverlays may be dependencyOverlays.${system} = [ list of overlays ];
896 or simply dependencyOverlays = [ list of overlays ];
897 
898 <makeMultiOverlay> <same args as makeOverlays BUT with the following 2 args INSTEAD of defaultName>:
899             importName: namesIncList:
900 Instead of taking a defaultName, it takes an importName and a list of names.
901 It will output them in an overlay where they will be accessible by pkgs.${importName}.${name}
902 
903 <makeOverlaysWithMultiDefault> utils.makeOverlays but the default overlay
904 uses makeMultiOverlay. So that after adding it, all your packages from packageDefinitions will
905 be accessible at pkgs.${defaultPackageName}.${packageName}
906 Can be swapped out 1 for 1 with utils.makeOverlays if preferred
907 
908 <easyMultiOverlay> package:
909 i.e. if you had a package named nvim1 and a package named nvim2,
910 would output an overlay containing both pkgs.nvim1 and pkgs.nvim2
911 
912 Takes as its argument only a finished nixCats package.
913 Utilizes override to avoid wrapping the overlay with ${system} variable.
914 
915 Slightly different from makeMultiOverlay in that
916 makeMultiOverlay would output at pkgs.${importName}.nvim1
917 instead of pkgs.nvim1 like this one does.
918 
919 <easyMultiOverlayNamespaced> package: importName:
920 If you had a package named nvim1 and a package named nvim2,
921 would output an overlay containing
922 both pkgs.${importName}.nvim1 and pkgs.${importName}.nvim2
923 
924 Takes as its argument only a finished nixCats package.
925 Utilizes override to avoid wrapping the overlay with ${system} variable.
926 
927 identical output to makeMultiOverlay
928 
929 <easyNamedOvers> package:
930 Same output as makeOverlays except without a default package.
931 i.e. if you had a package named nvim1 and a package named nvim2,
932 would make an overlay named nvim1 and an overlay named nvim2
933 
934 Takes as its argument only a finished nixCats package.
935 Utilizes override to avoid wrapping the overlay with ${system} variable
936 
937 <eachSystem> systems: f:
938 just flake-utils.lib.eachSystem copied here to remove the final input outside
939 of nixpkgs itself.
940 
941 <bySystem> systems: f:
942 similar to flake-utils.lib.eachSystem but for only 1 variable. If used for the
943 whole outputs section instead of eachSystem, it would add the
944 ${system} to the start like ${system}.packages.default and not
945 packages.${system}.default so instead it is used for only a single output like:
946 { packages = utils.bySystem nixpkgs.lib.platforms.all (system: { default = ...; }) }
947 
948 It is the same thing as nixpkgs.lib.genAttrs, renamed so that people know
949 how to use it.
950 
951 <mkLuaInline> luaCode:
952 This helper can be used in the packageDefinitions set in order to write
953 unescaped lua code into the nixCats plugin.
954 
955 For example, if settings.wrapRc = false; and settings.unwrappedCfgPath
956 is NOT set, nixCats uses this function to make
957 your config path default to the value of:
958 nixCats_config_location = utils.mkLuaInline "vim.fn.stdpath('config')"
959 
960 
961 ---------------------------------------------------------------------------------------
962 Nix OS Module                     nixCats.flake.outputs.exports.mkNixosModules
963                                   nixCats.flake.outputs.exports.mkHomeModules
964 
965 We create the module by exporting the following in our flake outputs.
966 More information on the modules can be found at :h nixCats.module
967 
968 <mkNixosModules> {
969     defaultPackageName = "nixCats";
970     luaPath = "${./.}";
971     inherit nixpkgs dependencyOverlays
972       categoryDefinitions packageDefinitions extra_pkg_config;
973 };
974 
975 <mkHomeModules> {
976     defaultPackageName = "nixCats";
977     luaPath = "${./.}";
978     inherit nixpkgs dependencyOverlays
979       categoryDefinitions packageDefinitions extra_pkg_config;
980 };
981 
982 dependencyOverlays may be dependencyOverlays.${system} = [ list of overlays ];
983 or simply dependencyOverlays = [ list of overlays ];
984 
985 IMPORTANT
986 By default, the module inherits your flake or nixExpressionFlakeOutputs nixpkgs object,
987 and its overlays, and everything else.
988 It will still inherit your system overlays and config set and system value,
989 but your system will not inherit overlays added to the nixCats module option.
990 
991 More information on the modules can be found at :h nixCats.module
992 
993 ---------------------------------------------------------------------------------------
994 vim:tw=78:ts=8:ft=help:norl: