How to properly use the home-manager / nixos modules

[DerRockWolf]

I probably don't really need it, as I don't need to merge lists, but I still want to understand it 🙂

What I already got (I hope):

The <defaultPackageName>.packageDefinitions.existing option is used to configure if and how the packageDefinitions, of the package from which the module was generated from, are inherited to the module.
E.g., if existing is set to discard, packageDefinitions from the original package are not inherited.

The difference between replace and merge seems to be how lists are handled, sets are merged the same regardless of the existing value.

---

Now the module exposes two options to change (or add new) packageDefinitions: packageDefinitions.replace & packageDefinitions.merge.
From what I could find, this is basically the same as the packageDefinitions.existing option but it affects how packageDefinitions are merged by the module (if specified in multiple locations).

What I didn't get was how, or more particular in what order, the packageDefinitions are being merged. From observation I think it's somehow related to the order the modules are "included" (the modules list from home-manager.lib.homeManagerConfiguration). Modules included first seem to have preference.

But I find it hard to debug the order of modules I'm importing to my actual config 😅 At least the order I expected didn't align with the outcome.

Do you have any tips on how one could debug module execution order?

I did this to test my hypothesis:

Details

    homeConfigurations = {
      "test" = home-manager.lib.homeManagerConfiguration {
        pkgs = nixpkgs.legacyPackages.x86_64-linux;
          modules = [
            {
              home.stateVersion = "23.11";
              home.username = "kai";
              home.homeDirectory = "/home/kai";

              nixCats.enable = true;
              nixCats.packageNames = ["lala"];
              nixCats.packageDefinitions.replace = {
                lala = _: { settings.aliases = ["a"]; };
              };
            }
            {
              nixCats.packageDefinitions.replace = {
                lala = _: { settings.aliases = ["b"]; };
              };
            }
            {
              nixCats.packageDefinitions.replace = {
                lala = _: { settings.aliases = ["c"]; };
              };
            }
          ] ++ [nixCatsModules.homeManagerModule];

Result has lala and only a as alias. Using packageDefinitions.merge at the first module changes nothing, as expected. Using merge for the second or third module results in a + b or c, also as expected.

[BirdeeHub]

You are spot on in your understanding.

One detail, all replace types happen first, all merges are merged into that after.

Edit: existing is before both of those, and the others update into it according to the strategy chosen

Unfortunately the order of the merges and replacements is not easily controllable, the way it works is by defining a custom type for the module option, which the module evaluator uses to merge options when it encounters the same one in multiple places.

The general rule is that the module that imports the other module will win (go last)

So, if you make several other modules, but then in your main module you import all of those, the ones in the main module will go last.

Unfortunately, I dont have that many tricks for you for determining module import order. (you could put in a builtins.trace?)

Rather than deal with it, I would suggest making a new category for your stuff in the new file so that you don't have to worry about it being overridden in other files in most cases.

[DerRockWolf]

Thanks for the quick and great reply!

Btw, if you ever accept sponsors, let us know ❤️ Thanks for building nixCats 😻

[BirdeeHub]

Honestly maybe I should? Its not the first time someone has asked about that. I need to fix the template readmes though at least XD Its honestly not something I have thought much about I just made nixCats because it was fun, I like the result, and it has been useful for me, and because it seems kinda like the logical conclusion of where most people using pkgs.wrapNeovimUnstable and want to factor stuff out end up but wrapped up nicer.

I did end up adding a sponsor thing to my github account today, it seemed easy enough to do. Not sure if Im going to put the button here or not though, feels possibly a little gauche? No idea. But its not like I have a bunch so, may as well have it somewhere so people who want to can.

Edit: Thank you, by the way :) I appreciate it a lot.

[BirdeeHub]

I also just learned

if you, for example, wanted to make sure one packageDefinitions in one file comes before another one

packageDefinitions.replace = lib.mkBefore { /* etc */ };

Will make it go before. I think theres also a lib.mkAfter