diff --git a/index.html b/index.html index 2098e3ab4..f81a7bc20 100644 --- a/index.html +++ b/index.html @@ -1,5 +1,5 @@ -
ca.desrt.dconf
or dconf.service
?ca.desrt.dconf
or dconf.service
?This manual will eventually describe how to install, use, and extend Home Manager. @@ -578,7 +578,14 @@ If you refer to an option then write its full attribute path. That is, instead o
The option 'foo' has been deprecated, please use 'bar' instead.
it should read
The option 'services.myservice.foo' has been deprecated, please use 'services.myservice.bar' instead.
A new module, say foo.nix
, should always include a news entry that has a message along the lines of
-
A new module is available: 'services.foo'.
If the module is platform specific, e.g., a service module using systemd, then a condition like
condition = hostPlatform.isLinux;
should be added. If you contribute a module then you don’t need to add this entry, the merger will create an entry for you.
Home Manager includes a basic test suite and it is highly recommended to include at least one test when adding a module. Tests are typically in the form of "golden tests" where, for example, a generated configuration file is compared to a known correct file.
It is relatively easy to create tests by modeling the existing tests, found in the tests
project directory.
The full Home Manager test suite can be run by executing
$ nix-shell --pure tests -A run.all
in the project root. List all test cases through
$ nix-shell --pure tests -A list
and run an individual test, for example alacritty-empty-settings
, through
$ nix-shell --pure tests -A run.alacritty-empty-settings
However, those invocations will impurely source the system’s nixpkgs, and may cause failures. To run against the nixpkgs from the flake.lock, use instead e.g.
$ nix develop --ignore-environment .#tests.all
Home Manager currently installs packages into the user environment, precisely as if the packages were installed through nix-env --install
. This means that you will get a collision error if your Home Manager configuration attempts to install a package that you already have installed manually, that is, packages that shows up when you run nix-env --query
.
For example, imagine you have the hello
package installed in your environment
$ nix-env --query +A new module is available: 'services.foo'.If the module is platform specific, e.g., a service module using systemd, then a condition like
condition = hostPlatform.isLinux;should be added. If you contribute a module then you don’t need to add this entry, the merger will create an entry for you.
Home Manager includes a basic test suite and it is highly recommended to include at least one test when adding a module. Tests are typically in the form of "golden tests" where, for example, a generated configuration file is compared to a known correct file.
It is relatively easy to create tests by modeling the existing tests, found in the tests
project directory.
The full Home Manager test suite can be run by executing
$ nix-shell --pure tests -A run.all
in the project root. List all test cases through
$ nix-shell --pure tests -A list
and run an individual test, for example alacritty-empty-settings
, through
$ nix-shell --pure tests -A run.alacritty-empty-settings
However, those invocations will impurely source the system’s nixpkgs, and may cause failures. To run against the nixpkgs from the flake.lock, use instead e.g.
$ nix develop --ignore-environment .#tests.all
Here is a collection of tools and extensions that relate to Home +Manager. Note, these are maintained outside the regular Home Manager +flow so quality and support may vary wildly. If you encounter problems +then please raise them in the corresponding project, not as issues in +the Home Manager tracker.
If you have made something interesting related to Home Manager then +you are encouraged to create a PR that expands this chapter.
+xhmm — extra Home Manager modules +
A collection of modules maintained by Anselm Schüler.
Home Manager currently installs packages into the user environment, precisely as if the packages were installed through nix-env --install
. This means that you will get a collision error if your Home Manager configuration attempts to install a package that you already have installed manually, that is, packages that shows up when you run nix-env --query
.
For example, imagine you have the hello
package installed in your environment
$ nix-env --query hello-2.10
and your Home Manager configuration contains
home.packages = [ pkgs.hello ];
Then attempting to switch to this configuration will result in an error similar to
$ home-manager switch these derivations will be built: /nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv @@ -590,7 +597,7 @@ building path(s) ‘/nix/store/b5c0asjz9f06l52l9812w6k39ifr49jj-user-environment Wide character in die at /nix/store/64jc9gd2rkbgdb4yjx3nrgc91bpjj5ky-buildenv.pl line 79. collision between ‘/nix/store/fmwa4axzghz11cnln5absh31nbhs9lq1-home-manager-path/bin/hello’ and ‘/nix/store/c2wyl8b9p4afivpcz8jplc9kis8rj36d-hello-2.10/bin/hello’; use ‘nix-env --set-flag priority NUMBER PKGNAME’ to change the priority of one of the conflicting packages builder for ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed with exit code 2 -error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed
The solution is typically to uninstall the package from the environment using nix-env --uninstall
and reattempt the Home Manager generation switch.
You could also opt to unistall all of the packages from your profile with nix-env --uninstall '*'
.
Home Manager is only able to set session variables automatically if it manages your Bash, Z shell, or fish shell configuration. To enable such management you use programs.bash.enable
, programs.zsh.enable
, or programs.fish.enable
.
If you don’t want to let Home Manager manage your shell then you will have to manually source the ~/.nix-profile/etc/profile.d/hm-session-vars.sh
file in an appropriate way. In Bash and Z shell this can be done by adding
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
to your .profile
and .zshrc
files, respectively. The hm-session-vars.sh
file should work in most Bourne-like shells. For fish shell, it is possible to source it using the foreign-env plugin
fenv source "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" > /dev/null
A typical way to prepare a repository of configurations for multiple logins and machines is to prepare one "top-level" file for each unique combination.
For example, if you have two machines, called "kronos" and "rhea" on which you want to configure your user "jane" then you could create the files
The solution is typically to uninstall the package from the environment using nix-env --uninstall
and reattempt the Home Manager generation switch.
You could also opt to unistall all of the packages from your profile with nix-env --uninstall '*'
.
Home Manager is only able to set session variables automatically if it manages your Bash, Z shell, or fish shell configuration. To enable such management you use programs.bash.enable
, programs.zsh.enable
, or programs.fish.enable
.
If you don’t want to let Home Manager manage your shell then you will have to manually source the ~/.nix-profile/etc/profile.d/hm-session-vars.sh
file in an appropriate way. In Bash and Z shell this can be done by adding
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
to your .profile
and .zshrc
files, respectively. The hm-session-vars.sh
file should work in most Bourne-like shells. For fish shell, it is possible to source it using the foreign-env plugin
fenv source "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" > /dev/null
A typical way to prepare a repository of configurations for multiple logins and machines is to prepare one "top-level" file for each unique combination.
For example, if you have two machines, called "kronos" and "rhea" on which you want to configure your user "jane" then you could create the files
kronos-jane.nix
,
rhea-jane.nix
, and
@@ -602,9 +609,9 @@ error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.
imports = [ ./common.nix ];
# Various options that are specific for this machine/user.
-}while the common.nix
file contains configuration shared across the two logins. Of course, instead of just a single common.nix
file you can have multiple ones, even one per program or service.
You can get some inspiration from the Post your home-manager home.nix file! Reddit thread.
You are most likely trying to configure something that uses dconf +}
while the common.nix
file contains configuration shared across the two logins. Of course, instead of just a single common.nix
file you can have multiple ones, even one per program or service.
You can get some inspiration from the Post your home-manager home.nix file! Reddit thread.
You are most likely trying to configure something that uses dconf but the DBus session is not aware of the dconf service. -The full error you might get is
error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files
or
error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.
The solution on NixOS is to add
programs.dconf.enable = true;
to your system configuration.
If you are using a stable version of Nixpkgs but would like to install some particular packages from Nixpkgs unstable – or some other channel – then you can import the unstable Nixpkgs and refer to its packages within your configuration. Something like
{ pkgs, config, ... }: +The full error you might get iserror: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service filesor
error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.The solution on NixOS is to add
programs.dconf.enable = true;to your system configuration.
If you are using a stable version of Nixpkgs but would like to install some particular packages from Nixpkgs unstable – or some other channel – then you can import the unstable Nixpkgs and refer to its packages within your configuration. Something like
{ pkgs, config, ... }: let @@ -619,7 +626,7 @@ in # … }
should work provided you have a Nix channel called nixpkgs-unstable
.
You can add the nixpkgs-unstable
channel by running
$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs-unstable -$ nix-channel --update
Note, the package will not be affected by any package overrides, overlays, etc.
By default Home Manager will install the package provided by your chosen nixpkgs
channel but occasionally you might end up needing to change this package. This can typically be done in two ways.
+$ nix-channel --update
Note, the package will not be affected by any package overrides, overlays, etc.
By default Home Manager will install the package provided by your chosen nixpkgs
channel but occasionally you might end up needing to change this package. This can typically be done in two ways.
If the module provides a package
option, such as programs.beets.package
, then this is the recommended way to perform the override. For example,
programs.beets.package = pkgs.beets.override { enableCheck = true; };
If no package
option is available then you can typically override the relevant package using an overlay.
diff --git a/tools.html b/tools.html
index 23a656745..dc5c2155e 100644
--- a/tools.html
+++ b/tools.html
@@ -1,6 +1,6 @@
-
home-manager +
home-manager — reconfigure a user environment
home-manager
{
build
|
@@ -92,7 +92,7 @@
|
--verbose
}
- ]
This command updates the user environment so that it corresponds to the
configuration specified in ~/.config/nixpkgs/home.nix
or ~/.config/nixpkgs/flake.nix
.
@@ -161,7 +161,7 @@ available for immediate garbage collection.
-
The tool accepts the options
-A attrPath
@@ -284,15 +284,15 @@
--verbose
Activates verbose output. -