HOME TOC REPO
1   ===============================================================================
2   Nix OS Module                                    nixCats.module
3                                     nixCats.module.mkNixosModules
4                                      nixCats.module.mkHomeModules
5   
6   We create the module by exporting the following in our flake outputs.
7   
8   <mkNixosModules> {
9       defaultPackageName = "nixCats";
10      moduleNamespace = [ "nixCats" ];
11      luaPath = "${./.}";
12      inherit nixpkgs dependencyOverlays
13        categoryDefinitions packageDefinitions extra_pkg_config;
14  };
15  
16  <mkHomeModules> {
17      defaultPackageName = "nixCats";
18      moduleNamespace = [ "nixCats" ];
19      luaPath = "${./.}";
20      inherit nixpkgs dependencyOverlays
21        categoryDefinitions packageDefinitions extra_pkg_config;
22  };
23  
24  If moduleNamespace is omitted, it will default to [ defaultPackageName ]
25  
26  moduleNamespace controls the namespace for the module options.
27  
28  This means if moduleNamespace = [ "my_mods" "nixCats" ];
29  
30  Then you would my_mods.nixCats.enable = true;
31  and my_mods.nixCats.packageNames = [ "package" "names" "toinstall" ];
32  
33  If you do not have a luaPath, you may pass it a keepLua builder.
34  utils.mkNixosModules exports a nixos module with the following options,
35  and utils.mkHomeModules exports a home-manager module with the SAME EXACT options
36  as the nixos module has for system, but for the user managed by home-manager.
37  
38  IMPORTANT
39  By default, the module inherits pkgs.config from the system's pkgs object,
40  and its overlays AND the flake's overlays and nixCats config,
41  as well as the flake's nixpkgs source (by default).
42  It will inherit things from your system,
43  but your system will not inherit things from nixCats,
44  other than the packages themselves in config.${defaultPackageName}.out
45  
46  
47    options = with lib; {
48  
49      # Set these with ${defaultPackageName} in your configuration.nix
50      ${defaultPackageName} = {
51  
52        nixpkgs_version = mkOption {
53          default = null;
54          type = types.nullOr (types.anything);
55          description = ''
56            a different nixpkgs import to use. By default will use the one from the flake, or `pkgs.path`.
57          '';
58          example = ''
59            nixpkgs_version = inputs.nixpkgs
60          '';
61        };
62  
63        addOverlays = mkOption {
64          default = [];
65          type = (types.listOf types.anything);
66          description = ''
67            A list of overlays to make available to any nixCats package from this module but not to your system.
68            Will have access to system overlays regardless of this setting.
69          '';
70          example = (lib.literalExpression ''
71            addOverlays = [ (self: super: { nvimPlugins = { pluginDerivationName = pluginDerivation; }; }) ]
72          '');
73        };
74  
75        enable = mkOption {
76          default = false;
77          type = types.bool;
78          description = "Enable the ${defaultPackageName} module";
79        };
80  
81        dontInstall = mkOption {
82          default = false;
83          type = types.bool;
84          description = ''
85            If true, do not output to packages list,
86            output only to config.${defaultPackageName}.out
87          '';
88        };
89  
90        luaPath = mkOption {
91          default = luaPath;
92          type = types.oneOf [ types.str types.path ];
93          description = (literalExpression ''
94            The path to your nvim config directory in the store.
95            In the base nixCats flake, this is "${./.}".
96          '');
97          example = (literalExpression "${./.}/userLuaConfig");
98        };
99  
100       packageNames = mkOption {
101         default = if packageDefinitions ? defaultPackageName then [ "${defaultPackageName}" ] else [];
102         type = (types.listOf types.str);
103         description = ''A list of packages from packageDefinitions to include'';
104         example = ''
105           packageNames = [ "nixCats" ]
106         '';
107       };
108 
109       categoryDefinitions = {
110         existing = mkOption {
111           default = "replace";
112           type = types.enum [ "replace" "merge" "discard" ];
113           description = ''
114             the merge strategy to use for categoryDefinitions inherited from the package this module was based on
115             choose between "replace", "merge" or "discard"
116             replace uses utils.mergeCatDefs
117             merge uses utils.deepmergeCats
118             discard does not inherit
119             see :help nixCats.flake.outputs.exports for more info on the merge strategy options
120           '';
121         };
122         replace = mkOption {
123           default = null;
124           type = types.nullOr (catDef "replace");
125           description = (literalExpression ''
126             see :help nixCats.flake.outputs.categories
127             uses utils.mergeCatDefs to recursively update old categories with new values
128             see :help nixCats.flake.outputs.exports for more info on the merge strategy options
129           '');
130           example = ''
131             # see :help nixCats.flake.outputs.categories
132             categoryDefinitions.replace = { pkgs, settings, categories, name, ... }@packageDef: { }
133           '';
134         };
135         merge = mkOption {
136           default = null;
137           type = types.nullOr (catDef "merge");
138           description = ''
139             see :help nixCats.flake.outputs.categories
140             uses utils.deepmergeCats to recursively update and merge category lists if duplicates are defined
141             see :help nixCats.flake.outputs.exports for more info on the merge strategy options
142           '';
143           example = ''
144             # see :help nixCats.flake.outputs.categories
145             categoryDefinitions.merge = { pkgs, settings, categories, name, ... }@packageDef: { }
146           '';
147         };
148       };
149 
150       packageDefinitions = {
151         existing = mkOption {
152           default = "replace";
153           type = types.enum [ "replace" "merge" "discard" ];
154           description = ''
155             the merge strategy to use for packageDefinitions inherited from the package this module was based on
156             choose between "replace", "merge" or "discard"
157             replace uses utils.mergeCatDefs
158             merge uses utils.deepmergeCats
159             discard does not inherit
160             see :help nixCats.flake.outputs.exports for more info on the merge strategy options
161           '';
162         };
163         merge = mkOption {
164           default = null;
165           description = ''
166             VERY IMPORTANT when setting aliases for each package,
167             they must not be the same as ANY other neovim package for that user.
168             It will cause a build conflict.
169 
170             You can have as many nixCats installed per user as you want,
171             as long as you obey that rule.
172 
173             for information on the values you may return,
174             see :help nixCats.flake.outputs.settings
175             and :help nixCats.flake.outputs.categories
176           '';
177           type = with types; nullOr (attrsOf (catDef "merge"));
178           example = ''
179             nixCats.packages = { 
180               nixCats = { pkgs, ... }: {
181                 settings = {
182                   wrapRc = true;
183                   configDirName = "nixCats-nvim";
184                   # nvimSRC = inputs.neovim;
185                   aliases = [ "vim" "nixCats" ];
186                 };
187                 categories = {
188                   generalBuildInputs = true;
189                   markdown = true;
190                   gitPlugins = true;
191                   general = true;
192                   custom = true;
193                   neonixdev = true;
194                   debug = false;
195                   test = true;
196                   lspDebugMode = false;
197                   themer = true;
198                   colorscheme = "onedark";
199                 };
200               };
201             }
202           '';
203         };
204         replace = mkOption {
205           default = null;
206           description = ''
207             VERY IMPORTANT when setting aliases for each package,
208             they must not be the same as ANY other neovim package for that user.
209             It will cause a build conflict.
210 
211             You can have as many nixCats installed per user as you want,
212             as long as you obey that rule.
213 
214             for information on the values you may return,
215             see :help nixCats.flake.outputs.settings
216             and :help nixCats.flake.outputs.categories
217           '';
218           type = with types; nullOr (attrsOf (catDef "replace"));
219           example = ''
220             nixCats.packages = { 
221               nixCats = { pkgs, ... }: {
222                 settings = {
223                   wrapRc = true;
224                   configDirName = "nixCats-nvim";
225                   # nvimSRC = inputs.neovim;
226                   aliases = [ "vim" "nixCats" ];
227                 };
228                 categories = {
229                   generalBuildInputs = true;
230                   markdown = true;
231                   gitPlugins = true;
232                   general = true;
233                   custom = true;
234                   neonixdev = true;
235                   debug = false;
236                   test = true;
237                   lspDebugMode = false;
238                   themer = true;
239                   colorscheme = "onedark";
240                 };
241               };
242             }
243           '';
244         };
245       };
246 
247       # in addition, the nixos module also has per-user options if desired.
248 
249       users = mkOption {
250         default = {};
251         description = ''
252           same as system config but per user instead
253         '';
254         type = with types; attrsOf (submodule {
255           options = {
256             enable = mkOption {
257               default = false;
258               type = types.bool;
259               description = "Enable the ${defaultPackageName} module for a user";
260             };
261 
262             luaPath = mkOption {
263               default = luaPath;
264               type = types.str;
265               description = ''
266                 The path to your nvim config directory in the store.
267                 In the base nixCats flake, this is "''${./.}".
268               '';
269               example = ''"''${./.}/userLuaConfig"'';
270             };
271 
272             # the same options but per user....
273             # Not shown here because its the same.
274           };
275         });
276       };
277     };
278   };
279 
280 
281 I have condensed it here, but notice at the end it outputs
282 all the same options for each user when in a nixosModule as well?
283 
284 in addition, there are some config values that can be used to reference the
285 configs made in the module
286 
287   config.${defaultPackageName}.out.packages.<PACKAGE_NAME>
288 
289 
290 and if using the nixos module there is ALSO
291 
292   config.${defaultPackageName}.out.users.<USER_NAME>.packages.<PACKAGE_NAME>
293 
294 ---------------------------------------------------------------------------------------
295 vim:tw=78:ts=8:ft=help:norl: