nix/2.home-manager
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 4

docs: describe embedded module integration

Browse source 
Document the extra module arguments, shared modules hook, and NixOS activation modes so embedded Home Manager setup matches the current integration code.
This commit is contained in:
Austin Horstman 2026-06-19 16:30:44 -05:00
parent e731ff60ec
commit db97e414d5
4 changed files with 49 additions and 10 deletions
Download patch file Download diff file Expand all files Collapse all files

19
docs/manual/installation/nix-darwin.md
View file

@ -52,6 +52,9 @@ home-manager.users.eve = { pkgs, ... }: {
and after a `darwin-rebuild switch` the user eve's environment should
include a basic Bash configuration and the packages atool and httpie.
Home Manager activation runs as part of nix-darwin activation for each
configured user.
If you do not plan on having Home Manager manage your shell
configuration then you must add either
@ -103,12 +106,22 @@ Nixpkgs.
:::
:::{.note}
Home Manager will pass `osConfig` as a module argument to any modules
you create. This contains the system's nix-darwin configuration.
Home Manager passes extra module arguments to each
`home-manager.users.<name>` module:
``` nix
{ lib, pkgs, osConfig, ... }:
{ lib, pkgs, osConfig, darwinConfig, osClass, modulesPath, ... }:
```
Here `osConfig` contains the system's nix-darwin configuration and
`darwinConfig` is a Darwin-specific alias for the same value. The `lib`
argument is Home Manager's extended library. You can pass additional module
arguments with `home-manager.extraSpecialArgs`.
:::
:::{.note}
Use `home-manager.sharedModules` to add Home Manager modules to every user
declared under `home-manager.users`.
:::
Once installed you can see [Using Home Manager](#ch-usage) for a more detailed

29
docs/manual/installation/nixos.md
View file

@ -85,12 +85,21 @@ httpie.
:::{.note}
If `nixos-rebuild switch` does not result in the environment you expect,
you can take a look at the output of the Home Manager activation script
output using
then the service to inspect depends on the activation mode.
By default, Home Manager activates each configured user during boot and
system rebuilds through a NixOS system service:
``` shell
$ systemctl status "home-manager-$USER.service"
```
If `home-manager.startAsUserService = true` is set, Home Manager instead
activates through the user's systemd service:
``` shell
$ systemctl --user status home-manager.service
```
:::
If you do not plan on having Home Manager manage your shell
@ -144,12 +153,22 @@ Nixpkgs.
:::
:::{.note}
Home Manager will pass `osConfig` as a module argument to any modules
you create. This contains the system's NixOS configuration.
Home Manager passes extra module arguments to each
`home-manager.users.<name>` module:
``` nix
{ lib, pkgs, osConfig, ... }:
{ lib, pkgs, osConfig, nixosConfig, osClass, modulesPath, ... }:
```
Here `osConfig` contains the system's NixOS configuration and `nixosConfig`
is a NixOS-specific alias for the same value. The `lib` argument is Home
Manager's extended library. You can pass additional module arguments with
`home-manager.extraSpecialArgs`.
:::
:::{.note}
Use `home-manager.sharedModules` to add Home Manager modules to every user
declared under `home-manager.users`.
:::
Once installed you can see [Using Home Manager](#ch-usage) for a more detailed

8
docs/manual/nix-flakes/nix-darwin.md
View file

@ -45,8 +45,12 @@ module argument from within the module graph itself. For values that originate
outside the module graph, such as flake inputs, prefer
`home-manager.extraSpecialArgs`.
and it is also rebuilt with the nix-darwin generations. The rebuild
command here may be `darwin-rebuild switch --flake ~/.config/darwin`.
Use `home-manager.sharedModules` for Home Manager modules or settings that
should be imported by every user declared in `home-manager.users`.
The Home Manager configuration is also rebuilt with the nix-darwin
generations. The rebuild command here may be
`darwin-rebuild switch --flake ~/.config/darwin`.
You can use the above `flake.nix` as a template in `~/.config/darwin` by

3
docs/manual/nix-flakes/nixos.md
View file

@ -43,6 +43,9 @@ module argument from within the module graph itself. For values that originate
outside the module graph, such as flake inputs, prefer
`home-manager.extraSpecialArgs`.
Use `home-manager.sharedModules` for Home Manager modules or settings that
should be imported by every user declared in `home-manager.users`.
The Home Manager configuration is then part of the NixOS configuration
and is automatically rebuilt with the system when using the appropriate
command for the system, such as