Home-manager + flakes documentation missing

Help
1

Hi guys,
I am currently trying to configure home-manager using flakes. However, I am failing to configure it because I can’t find any documentation that tells me what parameters there are, nor which ones are needed.

I don’t mean in the home.nix, there is a very detailed documentation here: https://home-manager-options.extranix.com/

It fails because of what belongs in the flake.nix. I just can’t find anything about it.
For example, how are you supposed to know that “home-manager.lib.homeManagerConfiguration” exists and which parameters can or must be set in it?

thanks for help :smiley:

2

The home-manager manual has a section dedicated to flake installs. Make sure you select the right subsection based on whether you want a standalone install or as a nixos/nix-darwin module.

Also, the possible arguments to the home-manager.lib.homeManagerConfiguration function can be found in the code here:

3

Okay, that’s the whole documentary?
I was thinking of something similar to Java.

check ? true → seems to be an optional parameter of type bool.
modules ? → an optional list, but what belongs in there?
extraSpecialArgs ? { } → also optional, but what are the parameters it expects?

Is there no documentation here like:
check?: bool
modules?: string
extraSpecialArgs?: { para1: string, … }

and a short explanation of what the parameter does?

4

If you’re looking for an ecosystem with every interface well documented… You’re in the wrong ecosystem. When it comes to things like all the arguments you can pass in an attrset to a function like homeManagerConfiguration, you can read the code if you’re curious and have a sufficient understanding of the nix language, and that’s about it. But you don’t need to know what every argument does. Just how to use it normally. And the manual tells you that.

I can give you a little explanation, though:

  • pkgs: Bit of a weird convention, but this should be an instantiated copy of nixpkgs, which home-manager will then re-instantiate from pkgs.path.
  • modules: What modules to load and merge for the configuration. Same as imports inside any of those modules.
  • extraSpecialArgs: Attrset of arguments you want to be passed to every module without being set via an option. This is useful to get around infinite recursion issues that come with the otherwise preferred method for this, the _module.args option.
  • lib: The instance of nixpkgs’ lib that should be used by home manager. The default is to get it from pkgs, which should almost always be the right idea.
  • check: configures something internal to the module system. Just leave it as the default.
2 Likes
5

There should be docs like this, but there aren’t. Probably because flakes functionality was added on later and the docs weren’t updated to reflect, for some reason.

For now the only thing available is the code, which at least indicates the list of args and their default values:

6

@waffle8946
That is a great pity.
Are there perhaps already any approaches that pursue such a goal in order to provide a kind of typing for flakes?

@tejing
Thanks for the explanation of the parameters, if you take a closer look at flakes, you can recognize the logic behind them relatively quickly and the inputs are “relatively” clear.

Nevertheless, a general typing would help a lot here and make it easier to get started.

7

Problem is nix is not statically typed so getting “typing” information without docstrings is impossible. And that function is not commented, so generating docs wouldn’t be possible atm.

I would suggest asking the HM project to document that function via comments as well as generated docs.