Document using out-of-tree modules with flakes

[berbiche]

Home Manager would benefit from having a section documenting how to use out-of-tree modules.

• Does nix-sops support using it as a module in home-manager configuration? Mic92/sops-nix#62
• https://github.com/vlaci/nix-doom-emacs
• https://github.com/nix-community/neovim-nightly-overlay
• etc.

CC users who recently opened flake related issues: @pinpox @terlar @roosemberth

I think this could be tackled in #1697 if @pinpox wants to.

[TLATER]

Maybe out of scope for this specific issue, but I think documenting some of the de-facto flake standards that are popping up might be a good idea (and also fix this issue).

Currently it seems to be hmModule, legacyPackages.hmActivationPackages and homeConfigurations (also formerly used by nixflk). It would be nice if those were standardized and eventually consumed by home-manager in a meaningful way, with suggested workarounds for the time being.

[Mic92]

I don't understand legacyPackages.hmActivationPackages. The others could be mentioned in the home-manager README attributes

[terlar]

Currently I use homeManagerModules and would suggest both:

• homeManagerModule
• homeManagerModules

to match the pattern used by the NixOS ones.

The activation packages and configurations are not modules, but final configurations and is a different thing. For that I would suggest homeManagerConfigurations again to match NixOS. I’ve also seen activation packages just being added as normal packages which I think is fine, they don’t need their own thing since it already can be accessed via the configuration output.

[Mic92]

Currently I use homeManagerModules and would suggest both:

* `homeManagerModule`

* `homeManagerModules`

to match the pattern used by the NixOS ones.

The activation packages and configurations are not modules, but final configurations and is a different thing. For that I would suggest homeManagerConfigurations again to match NixOS. I’ve also seen activation packages just being added as normal packages which I think is fine, they don’t need their own thing since it already can be accessed via the configuration output.

Let's get this quickly standardized before we see to many flakes with different attributes.

[NobbZ]

I currently do homeConfigurations.<host> though I am fine with any other proposal and would adjust my flakes.

Also as I am preparing to extract modules, I'm thinking about naming the related output attribute…

Currently I am tempted to use homeModule(s) to match my homeConfigurations, though writing it out as homeManagerModules as proposed earlier here does make sense at well.

---

Especially for the *Configurations key we should also think about if it would make sense to not only have a single nesting for the hostname, but perhaps another one for the username as well, this should be standardized and documented clearly then.

[Pacman99]

legacyPackages.hmActivationPackages was useful for debugging purposes. When you build the home-manager activation package with homeConfigurations and if there is an error, nix build won't tell you the error, it will then fallback and try to find homeConfigurations in packages/legacyPackages and tell you that it doesn't exist.

So by using legacyPackages you can distinguish between an error in the home-manager configuration or in the flakes configuration.

There might be a better workaround, but this was what we went with for nixflk. I'm not sure what nixos-rebuild --flake uses, since that works fine with nixosConfigurations. Just remembered, this was only an issue because of homeConfigurations being a nested attribute of hosts then users.

[ant-arctica]

This discussion is probably relevant to #1856, which ads a --flake option. It currently builds homeConfigurations.<name> (name defaults to username), but that can be changed if the community prefers something else.

[pinpox]

Hi, I'm the author of the PR #1697 where I was in the process of documenting flake usage with home-manager. PR #1856 seems relevant aswell as this one (#1783). Have been a bit busy lately, but would like to finish up the documentation on flakes now. How should we organize this? Should I continue working where I left of in #1697 or are the other PRs duplicates we should combine?

[ant-arctica]

I don't think #1697 and #1856 are duplicates, my pr only implements a --flake flag and I haven't added anything to the README of similar. But ideally the documentation would also mention how to do a standalone flake setup.
There's still disagreement on what attributes to use for home-manager modules and configurations, so that has to be cleared up before anything gets finalized.

[stale]

Thank you for your contribution! I marked this issue as stale due to inactivity. If this remains inactive for another 7 days, I will close this issue. Please read the relevant sections below before commenting.

If you are the original author of the issue

• If this is resolved, please consider closing it so that the maintainers know not to focus on this.
• If this might still be an issue, but you are not interested in promoting its resolution, please consider closing it while encouraging others to take over and reopen an issue if they care enough.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

If you are not the original author of the issue

• If you are also experiencing this issue, please add details of your situation to help with the debugging process.
• If you know how to solve the issue, please consider submitting a Pull Request that addresses this issue.

Memorandum on closing issues

If you have nothing of substance to add, please refrain from commenting and allow the bot close the issue. Also, don't be afraid to manually close an issue, even if it holds valuable information.

Closed issues stay in the system for people to search, read, cross-reference, or even reopen--nothing is lost! Closing obsolete issues is an important way to help maintainers focus their time and effort.

[Gerschtli]

Hey, I was just reading through all the related issues regarding flake output naming conventions, but it is really hard to gather the convention you decided on (if there even was made a decision yet). Is this somewhere documented or is there currently still ongoing effort? I searched around but didn't find anything.

If I just overlooked it, then please point me to the right direction :)

[TLATER]

homeConfigurations is what home-manager --flake accepts. A PR somewhere added it, but I can't find it at a glance either.

Edit: Ah, it's #1856, as I helpfully linked a while ago ;)

[ony]

As I understood homeConfigurations is for configuring home-manager when it is used as a module in system configuration or at least when it is whole configuration for some users.

I thought that this topic is about having re-usable home manager modules. I.e. incomplete home-manager configuration (e.g. without username set).

And I still not sure how to do that.

How do we "package" modules in flakes?

E.g. how do I package modules/misc/numlock.nix (just an example).
And it is also worth remember that beside name we should agree on value as well and what exactly flakes bring there.
Should it be like homeConfigurations in malob/nixpkgs that is suitable to be placed in imports?

{
  outputs = { self, ... }: {
    homeManagerModules = { numlock-module = import ./modules/misc/numlock.nix; };
  };
}

Or should it also have access to flake inputs like in hmModule in vlaci/nix-doom-emacs?

{
  # some inputs setup 
  outputs = { self, hm-utils, ... }@inputs: {
    homeManagerModules = {
      numlock-module = hm-utils.lib.importModule ./modules/misc/numlock.nix { inherit inputs; };
    };
  };
}

How to consume such flakes in home-manager (be it part of system config or be it standalone)?

This is even more mystery for me?
Before packaging in flake I do (in my home.nix):

{ ... }: {
  imports = [ ./modules/misc/numlock.nix ];
  home.username = "vagrant";
  home.homeDirectory = "/home/vagrant";
  home.stateVersion = "21.03";
}

But how do I start depending on flake-packaged module in standalone version?

{ ... }:
let
  inputs = {
    some-nix-modules = builtins.getFlake "github:some/nix-modules";
  };
in {
  imports = [
    some-nix-modules.homeManagerModules.numlock-module
    ./home-parts/xorg.nix
  ];
  _module.args.inputs = inputs;  # to allow access to other inputs?
  home.username = "vagrant";
  home.homeDirectory = "/home/vagrant";
  home.stateVersion = "21.03";
}

How do I model dependencies between modules?

E.g. having local module home-parts/xorg.nix imported from home.nix:

{ ... }: {
  require = [ ./modules/misc/numlock.nix ];
  xsession.numlock.enable = true;
}

Now that numlock.nix is behind flake... Should it be like?..

{ inputs, ... }: {
  require = [ inputs.some-nix-modules.homeManagerModules.numlock-module ];
  xsession.numlock.enable = true;
}

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/home-manager-shell-nix-shell-for-your-home-manager-config/24632/1

[shajra]

This thread is long enough that I've lost the thread. I think it's apparent that homeConfiguration is not sufficient for distributing Home Manager modules. From the manual, here's a snippet showing how homeConfiguration is used, which I can attest works as documented:

  outputs = { nixpkgs, home-manager, ... }:
    let
      system = "x86_64-linux";
      pkgs = nixpkgs.legacyPackages.${system};
    in {
      homeConfigurations.jdoe = home-manager.lib.homeManagerConfiguration {
        inherit pkgs;
        modules = [
          ./home.nix
        ];
      };
    };

Note that this isn't just a pointer to the entry point module(s). Rather it takes modules, and sets them up, most importantly with the appropriate Nixpkgs instance to get everything woven together. This weaving is the responsibility of the manager.lib.homeManagerConfiguration call. And this is how we get something that can work with the --flake option of the home-manager CLI tool.

However, some projects benefit from distributing modules, not whole configurations.

All I've tried to do above is sum up the state of things, which seem more confused in the thread than I'd expect.

So... I really think all that needs to be decided on is a name for the flake output attribute: to be used, so the community can do this consistently.

Here are options I saw in the thread:

• hmModules
• homeManagerModules
• homeModules

Personally, I like homeModules. It mirrors nicely homeConfigurations, and why stick the "manager" in one, but not the other? I'm also inclined to use a "default" name to mirror what flakes are already doing with packages and apps.

Anyway, that's my vote. Also, let me know if I read this thread too quickly, and if the issue is actually more than just picking a good name for the flake output attribute.

[nixos-discourse]

This issue has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/nix-flake-wrapping-a-nix-module-using-home-manager/39162/6