HOME TOC REPO

1   =================================================================================
2   OVERRIDING:                                                 nixCats.overriding
3   ---------------------------------------------------------------------------------
4   
5   When you have already created at least 1 nixCats package, you gain a new
6   ability. Overriding. Say we imported the example config from the nixCats repo.
7   
8     inputs = {
9       nixpkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable";
10      nixCats.url = "github:BirdeeHub/nixCats-nvim?dir=templates/example";
11      nixCats.inputs.nixpkgs.follows = "nixpkgs";
12    };
13    outputs = { self, nixpkgs, nixCats, ... }@inputs: let
14      OGpackage = nixCats.packages.x86_64-linux.default;
15      inherit (OGpackage.passthru) utils;
16  
17  Great. we have a package. It has a config with it, and all the arguments it
18  was passed before. We also grabbed the utils set from it.
19  
20  In the following help, we will override many times. We could combine them all
21  together into 1 big override, but it is better to show them separately for
22  documentation purposes.
23  
24  ---------------------------------------------------------------------------------
25                                             nixCats.overriding.setupVariables
26  Here are some various settings you may recognize that you can override if you
27  wish by setting their values here.
28  You COULD overide them, but we did not here.
29  we chose to inherit them from the main example config.
30  If you wanted to build for a different system for example,
31  you could change that here.
32  
33    pkgWithNewSetupVars = OGpackage.override (prev: {
34      inherit (prev) luaPath;
35      inherit (prev) nixpkgs;
36      inherit (prev) system;
37      inherit (prev) extra_pkg_config;
38      inherit (prev) nixCats_passthru;
39    };
40  
41  This is the full list of attributes you may override:
42  
43  luaPath categoryDefinitions packageDefinitions name
44  nixpkgs system extra_pkg_config dependencyOverlays nixCats_passthru;
45  
46  ---------------------------------------------------------------------------------
47                                                       nixCats.overriding.name
48  Overriding just the name of a nixCats package is highly effective.
49  Overriding the name will cause it to build the name of the package from
50  packageDefinitions with that name
51  
52    regularCats = OGpackage.override {
53      # this one was present in the packageDefinitions of the example config
54      name = "regularCats";
55    };
56  
57  if we wanted regularCats but with a different system, we could override
58  it in the same set, or chain overrides like so:
59  
60    pkgWithNewSetupVars2 = OGpackage.override (prev: {
61      system = "aarch64-linux";
62    })
63    regularCats = pkgWithNewSetupVars2.override {
64      name = "regularCats";
65    };
66  
67  ---------------------------------------------------------------------------------
68                                         nixCats.overriding.dependencyOverlays
69  Now we will address the overlays. Overlays can be a list or a set,
70  so they are slightly tricky.
71  In practice, this is mostly just boilerplate you would get from a template so
72  it is not too big of a pain.
73  
74  This is the same as both of the starter templates,
75  we are just using a different function to iterate over systems
76  to show more possibilities. It outputs to:
77  
78    dependencyOverlays.${system} = somelistofoverlays;
79  
80  and looks like:
81  
82    pkgWithNewOverlays = OGpackage.override (prev: {
83      dependencyOverlays = nixpkgs.lib.genAttrs nixpkgs.lib.platforms.all (system: [
84        (utils.mergeOverlayLists
85          (utils.safeOversList { inherit system; inherit (prev) dependencyOverlays; })
86          (/* (import ./overlays inputs) ++ */[
87            (utils.standardPluginOverlay inputs)
88            # any other flake overlays here.
89            inputs.neorg-overlay.overlays.default
90            inputs.lz-n.overlays.default
91            inputs.codeium.overlays.${system}.default
92          ])
93        )
94      ]);
95    });
96  
97  utils.safeOversList just checks if dependencyOverlays is a list or a set of lists,
98  and always returns a list
99  
100 OR
101 as just a list, fixing improper overlays via helper function:
102 
103   pkgWithNewOverlays = OGpackage.override (prev: {
104     dependencyOverlays = [ (utils.mergeOverlayLists
105       (utils.safeOversList { inherit (prev) system dependencyOverlays; })
106       (/* (import ./overlays inputs) ++ */[
107         (utils.standardPluginOverlay inputs)
108         # any other flake overlays here.
109         inputs.neorg-overlay.overlays.default
110         inputs.lz-n.overlays.default
111         # to fix systematized overlay sets
112         (utils.fixSystemizedOverlay inputs.codeium.overlays
113           (system: inputs.codeium.overlays.${system}.default)
114         )
115       ])
116     ) ];
117   });
118 
119  If you always choose the list option, it will always be
120 a list from then on and thus no need for utils.safeOversList,
121 but you still will need utils.mergeOverlayLists to merge overlays.
122 
123 ---------------------------------------------------------------------------------
124                                       nixCats.overriding.categoryDefinitions
125 In our categoryDefinitions, we most likely also want our new overlays.
126 So lets chain it with pkgWithNewOverlays
127 We can use utils.mergeCatDefs to merge in the previous categoryDefinitions
128 It will update prev.categoryDefinitions with the new values recursively,
129 replacing whenever it reaches 2 conflicting items that
130 are not a set or a derivation and adding any new values.
131 
132   pkgWithExtraCats = pkgWithNewOverlays.override (prev: {
133     categoryDefinitions = utils.mergeCatDefs prev.categoryDefinitions ({ pkgs, settings, categories, name, extra, mkNvimPlugin, ... }@packageDef: {
134       startupPlugins = with pkgs.vimPlugins; {
135         newcat = [
136           lz-n
137         ];
138       };
139       optionalPlugins = with pkgs.vimPlugins; {
140         newcat = [
141           { plugin = neorg;
142             type = "lua";
143             config = /*lua*/''
144               -- use our new lz.n to lazy load it!
145               require('lz.n').load({
146                 -- use :NixCats pawsible to see the final name for packadd
147                 "neorg",
148                 ft = "norg",
149                 after = function(_)
150                   require("neorg").setup({
151                     -- your settings here
152                   })
153                 end
154               })
155             '';
156           }
157           # the home manager syntax for plugins is supported by nixCats
158           # which is useful for one-off cases like this.
159           # here we use it to lazy load neorg on neorg filetype
160         ];
161       };
162       # in addiion to the home-manager syntax,
163       # you could also source the current directory ON TOP of the one in luaPath.
164       # if you want to make it also respect wrapRc, you can access the value
165       # of wrapRc in the settings set provided to the function.
166       # optionalLuaAdditions = {
167       #   newcat = let
168       #     newDir = if settings.wrapRc then
169       #       "${./.}" else
170       #       "/path/to/here";
171       #   in /*lua*/''
172       #     local newCfgDir = [[${newDir}]]
173       #     vim.opt.packpath:prepend(newCfgDir)
174       #     vim.opt.runtimepath:prepend(newCfgDir)
175       #     vim.opt.runtimepath:append(newCfgDir .. "/after")
176       #     if vim.fn.filereadable(newCfgDir .. "/init.vim") == 1 then
177       #       vim.cmd.source(newCfgDir .. "/init.vim")
178       #     end
179       #     if vim.fn.filereadable(newCfgDir .. "/init.lua") == 1 then
180       #       dofile(newCfgDir .. "/init.lua")
181       #     end
182       #   '';
183       # };
184       # see :h nixCats.flake.outputs.categories for the available sets in categoryDefinitions
185     });
186   });
187 
188 Ok so we have a new category. But it isnt enabled!
189 
190 We need to make a package with the newcat category enabled!
191 
192 ---------------------------------------------------------------------------------
193                                        nixCats.overriding.packageDefinitions
194 To make the package with the newcat category enabled,
195 lets add a new package definition to our packageDefinitions set.
196 
197 We will call our package newvim which will be the default launch name.
198 And the name we must set as the name we override with, in order to build it.
199 
200 It will merge in the packageDefinitions from the example nixCats config
201 so it will have most of the same settings and categories. We do this using
202 utils.mergeCatDefs once again, but for the individual package definition
203 items, rather than the entire packageDefinitions section.
204 
205 We have changed the aliases to nvi here.
206 
207 And we included our newcat category alongside the old ones!
208 
209   withExtraPkgDefs = withExtraCats.override (prev: {
210     # we could set the name here, or in a separate override
211     name = "newvim";
212     packageDefinitions = prev.packageDefinitions // {
213       # we merge the new definitions into
214       # the prev.packageDefinitions.nixCats package 
215       # which was in the original packageDefinitions set.
216       newvim = utils.mergeCatDefs prev.packageDefinitions.nixCats ({ pkgs, ... }: {
217         settings = {
218           # these ones override the old ones
219           aliases = [ "nvi" ];
220           # for available settings, see :h nixCats.flake.outputs.settings
221         };
222         categories = {
223           # enable our new category
224           newcat = true;
225           # remember, the others are still here!
226           # We merged, rather than overwriting them.
227           # You can see all of them with `:NixCats cats` in your editor!
228         };
229       });
230     };
231   });
232 
233 
234 ---------------------------------------------------------------------------------
235                                                   nixCats.overriding.wrap-up
236 All of the overriding you see above can be done ANYWHERE you have an existing
237 nixCats package. This means within your ./configuration.nix or ./home.nix or
238 within a flake, or a devShell or anywhere else.
239 
240 You could have a base configuration, with a bunch of categories disabled by
241 default, and enable only the ones you need in project shells if you wanted.
242 
243 You can have a package based on any of your other packages but with wrapRc =
244 false for testing lua without rebuild.
245 
246 The packages themselves also output modules via passthru.
247 You can still output modules and overlays from a package built for only a
248 single any system, because system is resolved later
249 via override or via getting it from the system pkgs object in those cases
250 
251 This means you could output the following from a flake 
252   homeModules = nixCats.packages.x86_64-linux.default.passthru.homeModule
253 
254 and it would not matter which system you chose to use there.
255 The module's options would be at config.${packageName}
256 
257 If you wanted to start over from scratch with just override,
258 even easier. Just dont merge anything from prev.
259 
260 As you can see, overriding provides a very powerful way to customize your
261 packages upon import somewhere else, and works very effectively with the
262 nixCats category scheme. Overriding just the packageDefinitions set
263 alone can produce wildly different neovim packages, and the more attention
264 paid to how you categorize, the better those options become.
265 
266 Have fun!
267 
268 =================================================================================
269 vim:tw=78:ts=8:ft=help:norl: