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
147 utils = import ./nix;
148
149 luaPath = "${./.}";
150
151 extra_pkg_config = {
152
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
167
168 dependencyOverlays = (import ./overlays inputs) ++ [
169
170
171
172
173 (utils.standardPluginOverlay inputs)
174
175 inputs.neorg-overlay.overlays.default
176 inputs.lz-n.overlays.default
177
178 inputs.codeium.overlays.${system}.default
179 ];
180
181
182
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
204
205
206
207
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)
218
219 (import ./overlays inputs)
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
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
448 { plugin = derivation; config.lua = ""; config.vim = "";}
449 { plugin = derivation; config = ""; type = "<viml or lua>"; }
450 { plugin = derivation; config = ""; }
451 { plugin = derivation; }
452
453
454 derivation
455
456
457
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
492 aliases = [ "viCat" ];
493 };
494 categories = {
495 custom = true;
496 gitPlugins = true;
497 general = true;
498 neonixdev = true;
499
500
501
502 lspDebugMode = false;
503
504
505
506 theBestCat = "says meow!!!";
507
508
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
528
529
530 aliases = null;
531 viAlias = false;
532 vimAlias = false;
533
534
535 extraName = "";
536
537 withRuby = true;
538 withPython3 = true;
539 withNodeJs = false;
540 withPerl = false;
541
542
543
544
545
546
547
548 wrapRc = true;
549
550
551
552
553
554
555
556 configDirName = "nvim";
557
558
559
560
561
562
563 unwrappedCfgPath = null;
564
565
566
567
568
569 neovim-unwrapped = null;
570
571
572 nvimSRC = null;
573
574
575
576
577 suffix-path = false;
578
579
580 suffix-LD = false;
581
582
583
584
585
586
587 disablePythonSafePath = false;
588
589
590
591
592
593
594
595 gem_path = null;
596
597
598
599
600
601
602
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
666 utils.eachSystem nixpkgs.lib.platforms.all (system: let
667
668 inherit (utils) baseBuilder;
669 nixCatsBuilder = baseBuilder luaPath {
670 inherit nixpkgs system dependencyOverlays extra_pkg_config;
671 } categoryDefinitions packageDefinitions;
672
673
674 defaultPackage = nixCatsBuilder defaultPackageName;
675
676
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
685 luaPath:
686
687 {
688
689 , nixpkgs
690 , system
691
692
693 , dependencyOverlays ? null
694
695
696 , extra_pkg_config ? {}
697
698
699 , nixCats_passthru ? {}
700 }:
701
702
703
704
705 categoryDefinitions:
706
707
708
709 packageDefinitions:
710
711
712
713
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
731
732 utils.eachSystem nixpkgs.lib.platforms.all (system: let
733
734 nixCatsBuilder = utils.baseBuilder luaPath {
735 inherit nixpkgs system dependencyOverlays extra_pkg_config;
736 } categoryDefinitions packageDefinitions;
737
738
739
740 defaultPackage = nixCatsBuilder defaultPackageName;
741
742
743
744
745 pkgs = import nixpkgs { inherit system; };
746
747
748
749
750
751 in
752 {
753
754
755
756
757 packages = utils.mkAllWithDefault defaultPackage;
758
759
760
761 devShells = {
762 default = pkgs.mkShell {
763 name = defaultPackageName;
764 packages = [ defaultPackage ];
765 inputsFrom = [ ];
766 shellHook = ''
767 '';
768 };
769 };
770
771 }) // {
772
773
774
775
776
777
778
779
780
781
782 overlays = utils.makeOverlays luaPath {
783
784 inherit nixpkgs dependencyOverlays extra_pkg_config;
785
786 } categoryDefinitions packageDefinitions defaultPackageName;
787
788
789
790 nixosModules.default = utils.mkNixosModules {
791 inherit dependencyOverlays luaPath defaultPackageName
792 categoryDefinitions packageDefinitions nixpkgs;
793 };
794
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: