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 <lspsAndRuntimeDeps>
274   a flexible set of categories, each containing LSP's or 
275   other internal runtime dependencies such as ctags or debuggers
276   these are available to the PATH while within the neovim program.
277   this includes the neovim terminal.
278 
279 <startupPlugins>
280   a flexible set of categories, each containing startup plugins.
281   Startup plugins are loaded and can be required. 
282 
283 <optionalPlugins>
284   a flexible set of categories, each containing optional plugins.
285   Optional plugins need to be added with packadd before being required.
286   Use :NixCats pawsible to see the names to use for packadd
287 
288 <sharedLibraries>
289   a flexible set of categories, each containing a derivation for
290   a runtime shared library. Will be prepended to the LD_LIBRARY_PATH variable.
291 
292 <environmentVariables>
293   a flexible set of categories, each containing an ATTRIBUTE SET of 
294   EnvironmentVariableName = "EnvironmentVariableValue";
295 
296 <extraWrapperArgs>
297   a flexible set of categories, each containing extra wrapper arguments.
298   If you don't know what that is, see here:
299 github.com/NixOS/nixpkgs/blob/master/pkgs/build-support/setup-hooks/make-wrapper.sh
300 
301 <extraLuaPackages>
302   a flexible set of categories, each containing FUNCTIONS 
303   that return lists of extra Lua packages.
304   These functions are the same thing that you would pass to lua.withPackages.
305   Is used to populate $LUA_PATH and $LUA_CPATH
306 
307 <extraPython3Packages> 
308   a flexible set of categories, each containing FUNCTIONS
309   that return lists of python packages.
310   These functions are the same thing that you would pass to python.withPackages.
311   You may get the path to this python environment in your lua config via
312   vim.g.python3_host_prog
313   or run from nvim terminal via :!<packagename>-python3
314 
315 <extraPython3wrapperArgs>
316   the same as extraWrapperArgs but for bundled python3 executable
317 
318 <propagatedBuildInputs> 
319   a flexible set of categories, each containing internal BUILD dependencies.
320   Will not be available to the PATH unless in a devShell.
321   USING THIS OPTION WILL CAUSE NVIM TO BUILD FROM SOURCE.
322 
323 <optionalLuaPreInit>
324   a flexible set of categories, each containing a lua string
325   that will be ran before sourcing your init.lua
326   Yes it can access nixCats.
327   It is not the recommended way to create lua for this flake, 
328   but it may be useful in editing flake imports 
329   of other already configured setups following the nixCats format.
330 <optionalLuaAdditions>
331   a flexible set of categories, each containing a lua string
332   that will be ran after sourcing your init.lua
333   Yes it can access nixCats.
334   It is not the recommended way to create lua for this flake, 
335   but it may be useful in editing flake imports 
336   of other already configured setups following the nixCats format.
337 <bashBeforeWrapper>
338   a flexible set of categories, each containing arbitrary bash code
339   to run before the wrapper starts within the wrapper's bash environment.
340   CAUTION: only use this if you know what you are doing and why you need
341   to do it. Whenever possible, use extraWrapperArgs instead.
342 }
343 
344 In essence, the contents of each set listed here are filtered
345 based on the packageDefinitions set you provide, 
346 where by including categoryname = true; you enable that category.
347 :help nixCats.flake.outputs.packageDefinitions
348 
349 It will remove duplicate items, so feel free to include the same thing in
350 multiple categories if it suits your purposes.
351 
352 It does this recursively. (explained below)
353                             nixCats.flake.outputs.categoryDefinitions.scheme
354 
355 If, inside one of these main sets, you had another set,
356 it would consider that a subcategory, and you could enable it
357 just like you do with a normal category, by setting a value with the
358 corresponding attribute path to true in the category
359 set of nixCats.flake.outputs.packageDefinitions.
360 You can nest them as much as you like, or just have a category that is a
361 single derivation.
362 
363 There is a behavior to keep in mind.
364 
365 If in your categoryDefinitions you had the following:
366 
367     environmentVariables = {
368       test = {
369         subtest1 = {
370           CATTESTVAR = "It worked!";
371         };
372         subtest2 = {
373           CATTESTVAR3 = "It didn't work!";
374         };
375       };
376     };
377     extraWrapperArgs = {
378       test = [
379         '' --set CATTESTVAR2 "It worked again!"''
380       ];
381     };
382 
383 And in your packageDefinitions set, under categories, you had the following:
384 
385     test = {
386       subtest1 = true;
387     };
388 
389 you could echo $CATTESTVAR and $CATTESTVAR2 in your terminal to see them.
390 However you could not echo $CATTESTVAR3.
391 
392 All items that are not attributes of the parent set will be included
393 when you enable a subcategory. This includes lists, strings, functions, etc...
394 
395 However, attributes will not and you must explicitly enable all attributes of
396 a subcategory if you set even 1 explicitly.
397 
398 Thus to include CATTESTVAR3, you would have to enable it like so: 
399     test = {
400       subtest1 = true;
401       subtest2 = true;
402     };
403  However, those are all the items in the test category.
404 So instead we can do this to enable all the subcategories in test. 
405     test = true;
406 
407 This applies in many situations. Take this one for example.
408 
409     lspsAndRuntimeDeps = {
410       neonixdev = {
411         inherit (pkgs)
412           nix-doc nil lua-language-server nixd; 
413       };
414     };
415     startupPlugins = {
416       neonixdev = with pkgs.vimPlugins; [
417         neodev-nvim
418         neoconf-nvim
419       ];
420     };
421 
422  If you were to put the following in your packageDefinitions: 
423     neonixdev.nix-doc = true;
424 
425  neodev-nvim and neoconf-nvim would still be included.
426  However, nil, lua-language-server, and nixd would not be!
427  You would need to pick which of those you wanted separately.
428  Sometimes this is the desired behavior.
429  Sometimes it is not and a list of packages would be better suited.
430 
431  You may also use the packageDef variable within categoryDefinitions
432  to get access to the set of categories and settings that are being
433  used to define the current package being built!
434 
435     themer = with pkgs.vimPlugins;
436       (builtins.getAttr packageDef.categories.colorscheme {
437           # Theme switcher without creating a new category
438           "onedark" = onedark-vim;
439           "catppuccin" = catppuccin-nvim;
440         }
441       );
442 
443   In addition to all this, if a plugin is defined within a list, it may
444   instead be defined within an attribute set that also contains config
445   to be ran after sourcing init.lua and optionalLuaAdditions
446   to do this, you may use the following syntax in opt or start sections: 
447     [
448       # you may add a plugin to a category list in any of these ways
449       { plugin = derivation; config.lua = ""; config.vim = "";}
450       { plugin = derivation; config = ""; type = "<viml or lua>"; }
451       { plugin = derivation; config = ""; } # defaults to viml
452       { plugin = derivation; }
453       # all the above options can accept an optional = bool;
454       # to override its presence in either startupPlugins or optionalPlugins
455       derivation
456       # plain derivation does not need to be in a list, but it should be
457       # anyway. It could be on its own though and would act as its own
458       # category.
459     ]
460 
461 ---------------------------------------------------------------------------------------
462 Package Generation:                           nixCats.flake.outputs.packageDefinitions
463 
464 generate packages by calling that builder function we just created.
465 Place them in the packageDefinitions set.
466 
467 First, pick the set of settings you wish to include.
468 
469 Then, pass it a set of named boolean values like this:
470 { categoryname1 = true; categoryname2 = false; etc... }
471 False may be omitted. True may not.
472 Only true matters for what plugins will be added.
473 
474 These categories are defined in the Builder function above 
475 by placing named lists of plugins in the flexible sets provided.
476 The category names are the names of those lists. 
477 Add a new list, then enable the category here.
478 
479 If you have categories with the same name in 
480 multiple different sets outlined above in the builder,
481 all plugins in those categories will be
482 included when you set "thatname = true;" here.
483 hence, general = true; will include the general lspsAndDeps category,
484 as well as the general startupPlugins category.
485 
486 an example package definition:
487 
488   packageDefinitions = {
489     nixCats = { pkgs, ... }: {
490       setting = {
491         wrapRc = true;
492         # nvimSRC = inputs.neovim;
493         aliases = [ "viCat" ];
494       };
495       categories = {
496         custom = true;
497         gitPlugins = true;
498         general = true;
499         neonixdev = true;
500 
501         # this does not have an associated category of plugins, 
502         # but lua can still check for it
503         lspDebugMode = false;
504 
505         # you could also pass something else and it calls 
506         # builtins.toString on it and passes it in as a string
507         theBestCat = "says meow!!!";
508         # maybe you need to pass a port or path in or something idk.
509         # you could :lua print(require('nixCats').theBestCat)
510       };
511     };
512   };
513 
514 You can use the nixCats plugin for the set you define here in your lua
515 It returns a lua table of the same format.
516 
517 see :help nixCats
518 
519 For more nuances on enabling categories and subcategories, see above at
520 :help nixCats.flake.outputs.categoryDefinitions.scheme
521 
522 ----------------------------------------------------------------------------------------
523 Settings                                       nixCats.flake.outputs.settings
524 
525 These are the defaults:
526 
527     default_settings = {
528       # YOU ARE IN CHARGE OF MAKING SURE THESE ALIASES DO NOT COLLIDE WITH
529       # ANYTHING ELSE
530       # [ "takes" "a" "list" "of" "strings" "and" "makes" "an" "alias" "for" "each" ];
531       aliases = null;
532       viAlias = false;
533       vimAlias = false;
534 
535       # so that you can see it in the store
536       extraName = "";
537 
538       withRuby = true;
539       withPython3 = true;
540       withNodeJs = false;
541       withPerl = false;
542 
543       # do you want to package the lua from this flake in the store?
544       # or would you rather it just read it in your .config/<configDirName>?
545       # nixCats and this help will work either way.
546       # packages with wrapRc = false are for quick changes to lua.
547       # it is not for being ran from anywhere via nix run, because the config
548       # was not wrapped with the program.
549       wrapRc = true;
550 
551       # What should the name of the folder within standard directories
552       # i.e. .config, .local/share, .local/state, .cache, etc... be?
553       # This option is very useful when you want 
554       # to clone an unwrapped config straight to the .config dir.
555       # It is also helpful to prevent other nvim packages sharing data folders.
556       # see :help `$NVIM_APPNAME`
557       configDirName = "nvim";
558 
559       # Only active when wrapRc = false, this option allows you to specify
560       # an absolute path to the unwrapped config directory.
561       # This is not a nix path. This is the unwrapped config directory.
562       # This means you are going to need to make
563       # sure that it points the right place on the current machine.
564       unwrappedCfgPath = null;
565       # Will not change anything other than config directory, configDirName
566       # is still needed for .local/share or .cache and the like
567 
568       # use this to pin a specific neovim version.
569       # This one will specify the base neovim derivation to use.
570       neovim-unwrapped = null;
571       # This one will just override the src value of the neovim in nixpkgs
572       # import it in flake inputs with flake = false,
573       # It will also obviously cause neovim to build from source.
574       nvimSRC = null;
575 
576       # These 2 options are useful for when you want to allow your dev shells
577       # to override things such as lsps and shared libraries that you have
578       # already in your configuration.
579       suffix-path = false;
580       # causes lspsAndDeps to be added to the END of
581       # PATH instead of the start
582       suffix-LD = false;
583       # causes sharedLibraries to be added to the END of
584       # LD_LIBRARY_PATH instead of the start
585 
586       # unsets PYTHONSAFEPATH variable.
587       # Can cause issues with reproducibility,
588       # can fix some stuff
589       disablePythonSafePath = false;
590 
591       # optional, specify custom store path gemdir
592       # must contain a gemset.nix like one generated by bundix
593       # must contain the neovim gem
594       # for further info, see
595       # https://github.com/NixOS/nixpkgs/tree/74ad6cb1d2b14edb4ad1fffc0791e94910c61453/pkgs/applications/editors/neovim/ruby_provider
596       # https://github.com/BirdeeHub/neovim_ruby_updater
597       gem_path = null;
598       # If you are using neovim-unwrapped from nixpkgs itself,
599       # there is a good chance your neovim
600       # will not be able to find it regardless of settings.
601       # thus withRuby and gem_path options may not work
602       # It works great using https://github.com/nix-community/neovim-nightly-overlay
603       # so this seems to be an upstream issue, as all the expected variables
604       # are still being set correctly.
605     };
606 
607 
608 QUICK TIP: wrapRc
609 
610 The wrapRc option is very useful for testing lua changes.
611 It removes the need to stage and rebuild to see your lua changes reflected.
612 You will still need to rebuild when making changes to nix regardless of the
613 value of wrapRc
614 
615 However it also means that the lua isn't going run if it isn't in the right
616 folder, i.e. when installed and ran from github with nix run
617 
618 If the lua is not in vim.fn.stdpath('config'), wrapRc = false will not work.
619 By default this is ~/.config/nvim on linux systems, although we can
620 change nvim to whatever we wish via the configDirName setting.
621 
622 Alternatively, you can set the unwrappedCfgPath option to allow the
623 configuration to be set to an absolute path. You still may want to set
624 the configDirName option anyway to change the data directories,
625 or explicitly keep it the same on both so that they share stuff like auths.
626 
627 The most convenient way to use this is the following:
628 Make a second identical packageDefinition, but with wrapRc disabled.
629 Then install both the wrapped one and unwrapped one with different aliases.
630 When you want to hack in lua, use unwrapped! When you're done, just rebuild
631 and go back to the wrapped one.
632 
633 The nixCats main flake.nix file has an example of this with nixCats
634 and regularCats.
635 
636 Then, when testing lua changes, you run the other package and have a vanilla
637 neovim experience, only rebuilding when you install new packages.
638 
639 When you are satisfied, simply rebuild and go back to using the main package,
640 as it was the same except for the single option!
641 
642 --------------------------------------------------------------------------------------
643 Neovim Builder Creation:                        nixCats.flake.outputs.builder
644 
645 Now we define our builder function.
646 We inherit utils.baseBuilder which is
647 a function that takes 5 arguments. It is defined in ./nix/builder
648 Right now we are going to call it with just the first 4 of them. This will
649 leave us with a function that takes 1 argument.
650 That argument is the name of the neovim package to be packaged.
651 
652 1. The path to the lua to include (in the flake, we use the self variable to get
653      this path and wrap the lua when wrapRc = true)
654 
655 2. A set containing:
656   The dependencyOverlays set or list,
657   extra_pkg_config, nixpkgs, nixCats_passthru, and system so it can
658   resolve pkgs and pass it where it needs to go.
659 
660 3. our function that takes an individual package definition
661      and returns a set of categoryDefinitions.
662 
663 4. our set of packageDefinitions see: nixCats.flake.outputs.packageDefinitions
664 
665 It is now a function that takes a name, and returns your chosen neovim package.
666 
667   # It requires the system variable to build a package.
668   utils.eachSystem nixpkgs.lib.platforms.all (system: let
669     # create our builder for our exports
670     inherit (utils) baseBuilder;
671     nixCatsBuilder = baseBuilder luaPath {
672       inherit nixpkgs system dependencyOverlays extra_pkg_config;
673     } categoryDefinitions packageDefinitions;
674     # it can take a name of a package in packageDefinitions
675     # and return the package!
676     defaultPackage = nixCatsBuilder defaultPackageName;
677     # ... rest of the outputs section explained
678     # below in :h nixCats.flake.outputs.exports ...
679 
680 If you use it wrong, you will most likely get this error message:
681 
682   The following arguments are accepted:
683 
684   # -------------------------------------------------------- #
685 
686   # the path to your ~/.config/nvim replacement within your nix config.
687   luaPath: # <-- must be a store path
688 
689   { # set of items for building the pkgs that builds your neovim
690 
691     , nixpkgs # <-- required
692     , system # <-- required
693 
694     # type: (attrsOf listOf overlays) or (listOf overlays) or null
695     , dependencyOverlays ? null 
696 
697     # import nixpkgs { config = extra_pkg_config; inherit system; }
698     , extra_pkg_config ? {} # type: attrs
699 
700     # any extra stuff for finalPackage.passthru
701     , nixCats_passthru ? {} # type: attrs
702   }:
703 
704   # type: function with args { pkgs, settings, categories, name, ... }:
705   # returns: set of sets of categories
706   # see :h nixCats.flake.outputs.categories
707   categoryDefinitions: 
708 
709   # type: function with args { pkgs, ... }:
710   # returns: { settings = {}; categories = {}; }
711   packageDefinitions: 
712   # see :h nixCats.flake.outputs.packageDefinitions
713   # see :h nixCats.flake.outputs.settings
714 
715   # name of the package to built from packageDefinitions
716   name: 
717 
718   # -------------------------------------------------------- #
719 
720   # Note:
721   When using override, all values shown above will
722   be top level attributes of prev, none will be nested.
723   i.e. 
724   finalPackage.override (prev: { inherit (prev) dependencyOverlays; })
725       NOT prev.pkgsargs.dependencyOverlays or something like that
726 
727 ---------------------------------------------------------------------------------------
728 Flake Exports and Export options               nixCats.flake.outputs.exports
729 
730 They look something like this:
731 
732   # this first section is the outputs we
733   # want to wrap with the ${system} variable
734   utils.eachSystem nixpkgs.lib.platforms.all (system: let
735     # this is the builder (see :h nixCats.flake.outputs.builder above):
736     nixCatsBuilder = utils.baseBuilder luaPath {
737       inherit nixpkgs system dependencyOverlays extra_pkg_config;
738     } categoryDefinitions packageDefinitions;
739     # then it takes our categoryDefinitions and packageDefinitions
740 
741     # then we build a package to serve as the default one by providing its name.
742     defaultPackage = nixCatsBuilder defaultPackageName;
743 
744     # this is just for using utils in the following section such as pkgs.mkShell
745     # The one used to build neovim is resolved inside the builder
746     # and is passed to our categoryDefinitions and packageDefinitions
747     pkgs = import nixpkgs { inherit system; };
748     # as you can see, "resolve pkgs" does not mean anything fancy.
749     # however, with overlays and system variable,
750     # sometimes you can get yourself in a loop when
751     # doing more advanced things. So this flake takes care of that for you.
752     # it will make sure pkgs is passed to the categoryDefinitions and packageDefinitions
753   in
754   {
755     # these outputs will be wrapped with ${system} by utils.eachSystem
756 
757     # this will make a package out of each of the packageDefinitions defined above
758     # and set the default package to the one passed in here.
759     packages = utils.mkAllWithDefault defaultPackage;
760 
761     # choose your package for devShell
762     # and add whatever else you want in it.
763     devShells = {
764       default = pkgs.mkShell {
765         name = defaultPackageName;
766         packages = [ defaultPackage ];
767         inputsFrom = [ ];
768         shellHook = ''
769         '';
770       };
771     };
772 
773   }) // {
774 
775     # these outputs will be NOT wrapped with ${system}
776 
777     # now we can export some things that can be imported in other
778     # flakes, WITHOUT needing to use a system variable to do it.
779     # and update them into the rest of the outputs returned by the
780     # eachSystem function.
781 
782     # this will make an overlay out of each of the packageDefinitions defined
783     # and set the default overlay to the one named here.
784     overlays = utils.makeOverlays luaPath {
785       # we pass in the things to make a pkgs variable to build nvim with later
786       inherit nixpkgs dependencyOverlays extra_pkg_config;
787       # and also our categoryDefinitions
788     } categoryDefinitions packageDefinitions defaultPackageName;
789 
790     # we export a nixos module to allow configuration from configuration.nix
791     # allows you to either inherit values from your main flake, or start fresh
792     nixosModules.default = utils.mkNixosModules {
793       inherit dependencyOverlays luaPath defaultPackageName
794         categoryDefinitions packageDefinitions nixpkgs;
795     };
796     # and the same for home manager
797     homeModule = utils.mkHomeModules {
798       inherit dependencyOverlays luaPath defaultPackageName
799         categoryDefinitions packageDefinitions nixpkgs;
800     };
801     inherit utils;
802     inherit (utils) templates;
803   };
804 
805 
806 We also export the <utils> set so we can get it easier later,
807 along with <templates> which are inside it.
808 The <utils> is also exported by the passthru of all packages based on nixCats
809 but exporting it separately makes it easier to get again later.
810 
811 It also contains all the other functions used in creating the format in the
812 templates, including the main builder!
813 (see :h nixCats.flake.outputs.builder for builder explanation)
814 
815 In addition to the templates and the builder function, the utils set contains:
816 
817 <standardPluginOverlay> inputs:
818 allows for inputs named plugins-something to be
819 turned into an overlay containing them as plugins automatically
820 
821 <sanitizedPluginOverlay> inputs:
822 optional replacement for utils.standardPluginOverlay.
823 If you give it an input named plugins-foo.bar
824 you can get it at pkgs.neovimPlugins.foo-bar
825 and still packadd foo.bar because it keeps the folder name the same.
826 To use, in your overlays section:
827 Replace (utils.standardPluginOverlay inputs)
828 with (utils.sanitizedPluginOverlay inputs)
829 
830 <fixSystemizedOverlay> overlaysSet: outfunc:
831 takes 2 arguments.
832 a set of system-wrapped overlays,
833 and a function (system: overlays.${system}.<desired_overlay>)
834 returns the desired overlay, with the system resolved.
835 
836 <mergeCatDefs> oldCats: newCats:
837 for merging categoryDefinitions and individual packages in packageDefinitions,
838 will recursively update up to the first thing not an attrset.
839 For our purposes, we do not consider derivations to be attrsets.
840 It takes 2 functions that return sets and returns
841 a function which calls them both and merges the result as desired above.
842 
843 <mergeOverlayLists> oldOverlist: newOverlist: self: super:
844 for merging lists of overlays together properly
845 to avoid naming conflict issues.
846 Takes 2 lists of overlays, returns a single merged overlay.
847 Merging logic is the same as mergeCatDefs
848 
849 <safeOversList> { dependencyOverlays, system ? null }:
850 Simple helper function for mergeOverlayLists
851 Pass it the inherited dependencyOverlays, always recieve a list back.
852 Then feed it to mergeOverlayLists.
853 If dependencyOverlays is an attrset, system string is required.
854 If dependencyOverlays is a list, system string is ignored
855 If invalid type or system, returns an empty list
856 
857 <mkNixosModules> {
858     defaultPackageName = "nixCats";
859     luaPath = "${./.}";
860     inherit nixpkgs dependencyOverlays
861       categoryDefinitions packageDefinitions extra_pkg_config;
862 };
863 Will create a nixos module that you can import in configuration.nix
864 If you do not have a luaPath, you may pass it a keepLua builder
865 See :help nixCats.flake.outputs.exports.mkNixosModules
866 The packages also export a module with defaultPackageName
867 set to THEIR package name via their passthru variable using this function.
868 
869 <mkHomeModules>
870 The same as mkNixosModules above, but for home manager.
871 
872 <mkAllWithDefault> package:
873 makes each package in the packageDefinitions this package was made from
874 and also a default one out of the one passed in.
875 
876 <mkAllPackages> package:
877 makes each package in the packageDefinitions this package was made from
878 
879 <mkPackages> finalBuilder: packageDefinitions: defaultName:
880 makes each package in packageDefinitions and also a default one
881 where finalBuilder is the builder function with all but the name applied
882 
883 <mkExtraPackages> finalBuilder: packageDefinitions:
884 mkPackages just calls this and adds a default one.
885 where finalBuilder is the builder function with all but the name applied
886 
887 <makeOverlays> luaPath: {
888         nixpkgs
889         , extra_pkg_config ? {}
890         , dependencyOverlays ? null
891         , nixCats_passthru ? {}
892         , ...
893       }@pkgsParams: categoryDefFunction: packageDefinitions:
894       defaultName:
895 makes an overlay for each package and also a default one
896 These are basically the same as the arguments to utils.baseBuilder
897 dependencyOverlays may be dependencyOverlays.${system} = [ list of overlays ];
898 or simply dependencyOverlays = [ list of overlays ];
899 
900 <makeMultiOverlay> <same args as makeOverlays BUT with the following 2 args INSTEAD of defaultName>:
901             importName: namesIncList:
902 Instead of taking a defaultName, it takes an importName and a list of names.
903 It will output them in an overlay where they will be accessible by pkgs.${importName}.${name}
904 
905 <makeOverlaysWithMultiDefault> utils.makeOverlays but the default overlay
906 uses makeMultiOverlay. So that after adding it, all your packages from packageDefinitions will
907 be accessible at pkgs.${defaultPackageName}.${packageName}
908 Can be swapped out 1 for 1 with utils.makeOverlays if preferred
909 
910 <easyMultiOverlay> package:
911 i.e. if you had a package named nvim1 and a package named nvim2,
912 would output an overlay containing both pkgs.nvim1 and pkgs.nvim2
913 
914 Takes as its argument only a finished nixCats package.
915 Utilizes override to avoid wrapping the overlay with ${system} variable.
916 
917 Slightly different from makeMultiOverlay in that
918 makeMultiOverlay would output at pkgs.${importName}.nvim1
919 instead of pkgs.nvim1 like this one does.
920 
921 <easyMultiOverlayNamespaced> package: importName:
922 If you had a package named nvim1 and a package named nvim2,
923 would output an overlay containing
924 both pkgs.${importName}.nvim1 and pkgs.${importName}.nvim2
925 
926 Takes as its argument only a finished nixCats package.
927 Utilizes override to avoid wrapping the overlay with ${system} variable.
928 
929 identical output to makeMultiOverlay
930 
931 <easyNamedOvers> package:
932 Same output as makeOverlays except without a default package.
933 i.e. if you had a package named nvim1 and a package named nvim2,
934 would make an overlay named nvim1 and an overlay named nvim2
935 
936 Takes as its argument only a finished nixCats package.
937 Utilizes override to avoid wrapping the overlay with ${system} variable
938 
939 <eachSystem> systems: f:
940 just flake-utils.lib.eachSystem copied here to remove the final input outside
941 of nixpkgs itself.
942 
943 <bySystem> systems: f:
944 similar to flake-utils.lib.eachSystem but for only 1 variable. If used for the
945 whole outputs section instead of eachSystem, it would add the
946 ${system} to the start like ${system}.packages.default and not
947 packages.${system}.default so instead it is used for only a single output like:
948 { packages = utils.bySystem nixpkgs.lib.platforms.all (system: { default = ...; }) }
949 
950 It is the same thing as nixpkgs.lib.genAttrs, renamed so that people know
951 how to use it.
952 
953 <mkLuaInline> luaCode:
954 This helper can be used in the packageDefinitions set in order to write
955 unescaped lua code into the nixCats plugin.
956 
957 For example, if settings.wrapRc = false; and settings.unwrappedCfgPath
958 is NOT set, nixCats uses this function to make
959 your config path default to the value of:
960 nixCats_config_location = utils.mkLuaInline "vim.fn.stdpath('config')"
961 
962 
963 ---------------------------------------------------------------------------------------
964 Nix OS Module                     nixCats.flake.outputs.exports.mkNixosModules
965                                   nixCats.flake.outputs.exports.mkHomeModules
966 
967 We create the module by exporting the following in our flake outputs.
968 More information on the modules can be found at :h nixCats.module
969 
970 <mkNixosModules> {
971     defaultPackageName = "nixCats";
972     luaPath = "${./.}";
973     inherit nixpkgs dependencyOverlays
974       categoryDefinitions packageDefinitions extra_pkg_config;
975 };
976 
977 <mkHomeModules> {
978     defaultPackageName = "nixCats";
979     luaPath = "${./.}";
980     inherit nixpkgs dependencyOverlays
981       categoryDefinitions packageDefinitions extra_pkg_config;
982 };
983 
984 dependencyOverlays may be dependencyOverlays.${system} = [ list of overlays ];
985 or simply dependencyOverlays = [ list of overlays ];
986 
987 IMPORTANT
988 By default, the module inherits your flake or nixExpressionFlakeOutputs nixpkgs object,
989 and its overlays, and everything else.
990 It will still inherit your system overlays and config set and system value,
991 but your system will not inherit overlays added to the nixCats module option.
992 
993 More information on the modules can be found at :h nixCats.module
994 
995 ---------------------------------------------------------------------------------------
996 vim:tw=78:ts=8:ft=help:norl: