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