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";
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
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 ([
87 (utils.standardPluginOverlay inputs)
88
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 ([
107 (utils.standardPluginOverlay inputs)
108
109 inputs.neorg-overlay.overlays.default
110 inputs.lz-n.overlays.default
111
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, ... }@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 = ''
144
145 require('lz.n').load({
146
147 "neorg",
148 ft = "norg",
149 after = function(_)
150 require("neorg").setup({
151
152 })
153 end
154 })
155 '';
156 }
157
158
159
160 ];
161 };
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
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
211 name = "newvim";
212 packageDefinitions = prev.packageDefinitions // {
213
214
215
216 newvim = utils.mergeCatDefs prev.packageDefinitions.nixCats ({ pkgs, ... }: {
217 settings = {
218
219 aliases = [ "nvi" ];
220
221 };
222 categories = {
223
224 newcat = true;
225
226
227
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: