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      luaPath = "${./.}";
11      inherit nixpkgs dependencyOverlays
12        categoryDefinitions packageDefinitions extra_pkg_config;
13  };
14  
15  <mkHomeModules> {
16      defaultPackageName = "nixCats";
17      luaPath = "${./.}";
18      inherit nixpkgs dependencyOverlays
19        categoryDefinitions packageDefinitions extra_pkg_config;
20  };
21  
22  where dependencyOverlays is a set of system names
23  with lists of overlays in each item. Such that
24  the lists would be accessed via dependencyOverlays.${system}
25  
26  If you do not have a luaPath, you may pass it a keepLua builder.
27  utils.mkNixosModules exports a nixos module with the following options,
28  and utils.mkHomeModules exports a home-manager module with the SAME EXACT options
29  as the nixos module has for system, but for the user managed by home-manager.
30  
31  IMPORTANT
32  By default, the module inherits pkgs.config from the system's pkgs object,
33  and its overlays AND the flake's overlays and nixCats config,
34  as well as the flake's nixpkgs source (by default).
35  It will inherit things from your system,
36  but your system will not inherit things from nixCats,
37  other than the packages themselves in config.${defaultPackageName}.out
38  
39  
40    options = with nixpkgs.lib; {
41  
42      # Set these with ${defaultPackageName} in your configuration.nix
43      ${defaultPackageName} = {
44  
45        nixpkgs_version = mkOption {
46          default = null;
47          type = types.nullOr (types.anything);
48          description = ''
49            a different nixpkgs import to use. By default will use the one from the flake.
50          '';
51          example = ''
52            nixpkgs_version = inputs.nixpkgs
53          '';
54        };
55  
56        addOverlays = mkOption {
57          default = [];
58          type = (types.listOf types.anything);
59          description = ''
60            A list of overlays to make available to nixCats but not to your system.
61            Will have access to system overlays regardless of this setting.
62          '';
63          example = (lib.literalExpression ''
64            addOverlays = [ (self: super: { vimPlugins = { pluginDerivationName = pluginDerivation; }; }) ]
65          '');
66        };
67  
68        # the above 2 are the only ones not also available at
69        # a per-user level in the nixos system module.
70  
71        enable = mkOption {
72          default = false;
73          type = types.bool;
74          description = "Enable ${defaultPackageName}";
75        };
76  
77        luaPath = mkOption {
78          default = luaPath;
79          type = types.str;
80          description = (lib.literalExpression ''
81            The path to your nvim config directory in the store.
82            In the base nixCats flake, this is "${./.}".
83          '');
84          example = (lib.literalExpression "${./.}/userLuaConfig");
85        };
86  
87        packageNames = mkOption {
88          default = [ "${defaultPackageName}" ];
89          type = (types.listOf types.str);
90          description = ''A list of packages from packageDefinitions to include'';
91          example = ''
92            packageNames = [ "nixCats" ]
93          '';
94        };
95  
96        categoryDefinitions = {
97          replace = mkOption {
98            default = null;
99            type = types.nullOr (types.functionTo (types.attrsOf types.anything));
100           description = (lib.literalExpression ''
101             Takes a function that receives the package definition set of this package
102             and returns a set of categoryDefinitions,
103             just like :help nixCats.flake.outputs.categories
104             you should use ${pkgs.system} provided in the packageDef set
105             to access system specific items.
106             Will replace the categoryDefinitions of the flake with this value.
107           '');
108           example = ''
109             # see :help nixCats.flake.outputs.categories
110             categoryDefinitions.replace = { pkgs, settings, categories, name, ... }@packageDef: { }
111           '';
112         };
113         merge = mkOption {
114           default = null;
115           type = types.nullOr (types.functionTo (types.attrsOf types.anything));
116           description = ''
117             Takes a function that receives the package definition set of this package
118             and returns a set of categoryDefinitions,
119             just like :help nixCats.flake.outputs.categories
120             Will merge the categoryDefinitions of the flake with this value,
121             recursively updating all non-attrset values,
122             such as replacing old category lists with ones defined here.
123           '';
124           example = ''
125             # see :help nixCats.flake.outputs.categories
126             categoryDefinitions.merge = { pkgs, settings, categories, name, ... }@packageDef: { }
127           '';
128         };
129       };
130 
131       packages = mkOption {
132         default = null;
133         description = ''
134           VERY IMPORTANT when setting aliases for each package,
135           they must not be the same as ANY other neovim package for that user.
136           It will cause a build conflict.
137 
138           You can have as many nixCats installed per user as you want,
139           as long as you obey that rule.
140 
141           for information on the values you may return,
142           see :help nixCats.flake.outputs.settings
143           and :help nixCats.flake.outputs.categories
144           https://github.com/BirdeeHub/nixCats-nvim/blob/main/nix/nixCatsHelp/nixCatsFlake.txt
145         '';
146         type = with types; nullOr (attrsOf (functionTo (attrsOf anything)));
147         example = ''
148           nixCats.packages = { 
149             nixCats = { pkgs, ... }: {
150               settings = {
151                 wrapRc = true;
152                 configDirName = "nixCats-nvim";
153                 # nvimSRC = inputs.neovim;
154                 aliases = [ "vim" "nixCats" ];
155               };
156               categories = {
157                 generalBuildInputs = true;
158                 markdown = true;
159                 gitPlugins = true;
160                 general = true;
161                 custom = true;
162                 neonixdev = true;
163                 debug = false;
164                 test = true;
165                 lspDebugMode = false;
166                 themer = true;
167                 colorscheme = "onedark";
168               };
169             };
170           }
171         '';
172       };
173 
174       users = mkOption {
175         default = {};
176         description = ''
177           same as system config but per user instead
178           and without addOverlays or nixpkgs_version
179         '';
180         type = with types; attrsOf (submodule {
181           options = {
182             enable = mkOption {
183               default = false;
184               type = types.bool;
185               description = "Enable ${defaultPackageName}";
186             };
187             # the same options but per user....
188             # Not shown here because its the same.
189           };
190         });
191       };
192     };
193 
194   };
195 
196 
197 I have condensed it here, but notice at the end it outputs
198 all the same options for each user when in a nixosModule as well?
199 
200 in addition, there are some config values that can be used to reference the
201 configs made in the module
202 
203   config.${defaultPackageName}.out.packages.<PACKAGE_NAME>
204 
205 
206 and if using the nixos module there is ALSO
207 
208   config.${defaultPackageName}.out.users.<USER_NAME>.packages.<PACKAGE_NAME>
209 
210 ---------------------------------------------------------------------------------------
211 vim:tw=78:ts=8:ft=help:norl: