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 nixCats offers an extra override method to prevent shadowing of .override
25 variable via things like callPackage being called above it.
26
27 package.override and package.overrideNixCats are equivalent in all ways
28 other than having different names to prevent shadowing.
29
30 For the sake of brevity, we will mostly use .override in this documentation.
31
32 ---------------------------------------------------------------------------------
33 nixCats.overriding.setupVariables
34 Here are some various settings you may recognize that you can override if you
35 wish by setting their values here.
36 You COULD overide them, but we did not here.
37 we chose to inherit them from the main example config.
38 If you wanted to build for a different system for example,
39 you could change that here.
40
41 pkgWithNewSetupVars = OGpackage.overrideNixCats (prev: {
42 inherit (prev) luaPath;
43 inherit (prev) nixpkgs;
44 inherit (prev) system;
45 inherit (prev) extra_pkg_config;
46 inherit (prev) extra_pkg_params;
47 inherit (prev) nixCats_passthru;
48 pkgs = prev.pkgs or null;
49 };
50
51
52 The things you may override are any of the arguments to the main builder
53 function, grouped into a single set
54
55 ---------------------------------------------------------------------------------
56 nixCats.overriding.name
57 Overriding just the name of a nixCats package is highly effective.
58 Overriding the name will cause it to build the name of the package from
59 packageDefinitions with that name
60
61 regularCats = OGpackage.override {
62
63 name = "regularCats";
64 };
65
66 if we wanted regularCats but with a different system, we could override
67 it in the same set, or chain overrides like so:
68
69 pkgWithNewSetupVars2 = OGpackage.override (prev: {
70 system = "aarch64-linux";
71 })
72 regularCats = pkgWithNewSetupVars2.overrideNixCats {
73 name = "regularCats";
74 };
75
76 ---------------------------------------------------------------------------------
77 nixCats.overriding.dependencyOverlays
78
79 And now we are going to make another package with more overlays!
80 We will override it again in the next section.
81 You could do all of these in the same override call of course,
82 but this fits within documentation better.
83
84 pkgWithNewOverlays = OGpackage.override (prev: {
85 dependencyOverlays = prev.dependencyOverlays ++ [
86 (utils.standardPluginOverlay inputs)
87
88 inputs.neorg-overlay.overlays.default
89 inputs.lz-n.overlays.default
90 (utils.fixSystemizedOverlay inputs.codeium.overlays
91 (system: inputs.codeium.overlays.${system}.default)
92 )
93 ];
94 });
95
96 ---------------------------------------------------------------------------------
97 nixCats.overriding.categoryDefinitions
98 In our categoryDefinitions, we most likely also want our new overlays.
99 So lets chain it with pkgWithNewOverlays
100 We can use utils.mergeCatDefs to merge in the previous categoryDefinitions
101 It will update prev.categoryDefinitions with the new values recursively,
102 replacing whenever it reaches 2 conflicting items that
103 are not a set or a derivation and adding any new values.
104
105 pkgWithExtraCats = pkgWithNewOverlays.override (prev: {
106 categoryDefinitions = utils.mergeCatDefs prev.categoryDefinitions ({ pkgs, settings, categories, name, extra, mkPlugin, ... }@packageDef: {
107 startupPlugins = with pkgs.vimPlugins; {
108 newcat = [
109 lze
110 ];
111 };
112 optionalPlugins = with pkgs.vimPlugins; {
113 newcat = [
114 { plugin = neorg;
115 type = "lua";
116 config = ''
117
118 require('lze').load({
119
120 "neorg",
121 ft = "norg",
122 after = function(_)
123 require("neorg").setup({
124
125 })
126 end
127 })
128 '';
129 }
130
131
132
133 ];
134 };
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157 });
158 });
159
160 Okay, so we have a new category. But it isn't enabled!
161
162 We need to make a package with the newcat category enabled!
163
164 ---------------------------------------------------------------------------------
165 nixCats.overriding.packageDefinitions
166 To make the package with the newcat category enabled,
167 lets add a new package definition to our packageDefinitions set.
168
169 We will call our package newvim which will be the default launch name.
170 And the name we must set as the name we override with, in order to build it.
171
172 It will merge in the packageDefinitions from the example nixCats config
173 so it will have most of the same settings and categories. We do this using
174 utils.mergeCatDefs once again, but for the individual package definition
175 items, rather than the entire packageDefinitions section.
176
177 We have changed the aliases to nvi here.
178
179 And we included our newcat category alongside the old ones!
180
181 withExtraPkgDefs = withExtraCats.override (prev: {
182
183 name = "newvim";
184 packageDefinitions = prev.packageDefinitions // {
185
186
187
188 newvim = utils.mergeCatDefs prev.packageDefinitions.nixCats ({ pkgs, name, ... }: {
189 settings = {
190
191 aliases = [ "nvi" ];
192
193 };
194 categories = {
195
196 newcat = true;
197
198
199
200 };
201 });
202 };
203 });
204
205
206 ---------------------------------------------------------------------------------
207 nixCats.overriding.wrap-up
208 All of the overriding you see above can be done ANYWHERE you have an existing
209 nixCats package. This means within your ./configuration.nix or ./home.nix or
210 within a flake, or a devShell or anywhere else.
211
212 You could have a base configuration, with a bunch of categories disabled by
213 default, and enable only the ones you need in project shells if you wanted.
214
215 You can have a package based on any of your other packages,
216 but with wrapRc = false for testing Lua without rebuild.
217
218 The packages themselves also output modules via passthru.
219 You can still output modules and overlays from a package built for only a
220 single any system, because system is resolved later
221 via override or via getting it from the system pkgs object in those cases
222
223 This means you could output the following from a flake
224 homeModules = nixCats.packages.x86_64-linux.default.passthru.homeModule
225
226 and it would not matter which system you chose to use there.
227 The module's options would be at config.${packageName}
228
229 If you wanted to start over from scratch with just override,
230 even easier. Just dont merge anything from prev.
231
232 As you can see, overriding provides a very powerful way to customize your
233 packages upon import somewhere else, and works very effectively with the
234 nixCats category scheme. Overriding just the packageDefinitions set
235 alone can produce wildly different Neovim packages, and the more attention
236 paid to how you categorize, the better those options become.
237
238 Have fun!
239
240 =================================================================================
241 vim:tw=78:ts=8:ft=help:norl: