mirror of
https://github.com/nix-community/home-manager
synced 2024-11-30 06:59:45 +01:00
doc: move FAQ to manual
This converts the FAQ into AsciiDoc and includes it in the HTML manual.
This commit is contained in:
Robert Helgesson
parent
cba7b6ee6e
commit
1afa5e257b
5 changed files with 175 additions and 208 deletions
1
FAQ.adoc
Symbolic link
1
FAQ.adoc
Symbolic link
|
|
@ -0,0 +1 @@
|
||||||
|
doc/faq.adoc
|
||||||
206
FAQ.md
206
FAQ.md
|
|
@ -1,206 +0,0 @@
|
||||||
Frequently Asked Questions (FAQ)
|
|
||||||
================================
|
|
||||||
|
|
||||||
Why is there a collision error when switching generation?
|
|
||||||
---------------------------------------------------------
|
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ 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
|
|
||||||
|
|
||||||
```console
|
|
||||||
$ home-manager switch
|
|
||||||
these derivations will be built:
|
|
||||||
/nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv
|
|
||||||
[…]
|
|
||||||
Activating installPackages
|
|
||||||
replacing old ‘home-manager-path’
|
|
||||||
installing ‘home-manager-path’
|
|
||||||
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.
|
|
||||||
|
|
||||||
Why are the session variables not set?
|
|
||||||
--------------------------------------
|
|
||||||
|
|
||||||
Home Manager is only able to set session variables automatically if it
|
|
||||||
manages your Bash or Z shell configuration. 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
|
|
||||||
|
|
||||||
```sh
|
|
||||||
. "$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.
|
|
||||||
|
|
||||||
How do set up a configuration for multiple users/machines?
|
|
||||||
----------------------------------------------------------
|
|
||||||
|
|
||||||
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
|
|
||||||
- `common.nix`
|
|
||||||
|
|
||||||
in your repository. On the kronos and rhea machines you can then make
|
|
||||||
`~jane/.config/nixpkgs/home.nix` be a symbolic link to the
|
|
||||||
corresponding file in your configuration repository.
|
|
||||||
|
|
||||||
The `kronos-jane.nix` and `rhea-jane.nix` files follow the format
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ ... }:
|
|
||||||
|
|
||||||
{
|
|
||||||
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!][1] Reddit thread.
|
|
||||||
|
|
||||||
[1]: https://www.reddit.com/r/NixOS/comments/9bb9h9/post_your_homemanager_homenix_file/
|
|
||||||
|
|
||||||
Why do I get an error message about `ca.desrt.dconf`?
|
|
||||||
-----------------------------------------------------
|
|
||||||
|
|
||||||
You are most likely trying to configure the GTK or Gnome Terminal 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
|
|
||||||
|
|
||||||
The solution on NixOS is to add
|
|
||||||
|
|
||||||
services.dbus.packages = with pkgs; [ gnome3.dconf ];
|
|
||||||
|
|
||||||
to your system configuration.
|
|
||||||
|
|
||||||
How do I install packages from Nixpkgs unstable?
|
|
||||||
------------------------------------------------
|
|
||||||
|
|
||||||
If you are using a stable version of Nixpkgs but would like to install
|
|
||||||
some particular packages from Nixpkgs unstable then you can import the
|
|
||||||
unstable Nixpkgs and refer to its packages within your configuration.
|
|
||||||
Something like
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ pkgs, config, ... }:
|
|
||||||
|
|
||||||
let
|
|
||||||
|
|
||||||
pkgsUnstable = import <nixpkgs-unstable> {};
|
|
||||||
|
|
||||||
in
|
|
||||||
|
|
||||||
{
|
|
||||||
home.packages = [
|
|
||||||
pkgsUnstable.foo
|
|
||||||
];
|
|
||||||
|
|
||||||
# …
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
How do I override the package used by a module?
|
|
||||||
-----------------------------------------------
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
1. 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; };
|
|
||||||
```
|
|
||||||
|
|
||||||
2. If no `package` option is available, then you can typically
|
|
||||||
override the relevant package using an [overlay][nixpkgs-overlays].
|
|
||||||
|
|
||||||
For example, if you want to use the `programs.skim` module but use
|
|
||||||
the `skim` package from Nixpkgs unstable, then a configuration like
|
|
||||||
|
|
||||||
```nix
|
|
||||||
{ pkgs, config, ... }:
|
|
||||||
|
|
||||||
let
|
|
||||||
|
|
||||||
pkgsUnstable = import <nixpkgs-unstable> {};
|
|
||||||
|
|
||||||
in
|
|
||||||
|
|
||||||
{
|
|
||||||
programs.skim.enable = true;
|
|
||||||
|
|
||||||
nixpkgs.overlays = [
|
|
||||||
(self: super: {
|
|
||||||
skim = pkgsUnstable.skim;
|
|
||||||
})
|
|
||||||
];
|
|
||||||
|
|
||||||
# …
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
should work OK.
|
|
||||||
|
|
||||||
[nixpkgs-overlays]: https://nixos.org/nixpkgs/manual/#chap-overlays
|
|
||||||
|
|
@ -8,8 +8,8 @@ let
|
||||||
name = "nmd";
|
name = "nmd";
|
||||||
owner = "rycee";
|
owner = "rycee";
|
||||||
repo = "nmd";
|
repo = "nmd";
|
||||||
rev = "49567e3ff2824ac8ba457f439f384eafc1eb4547";
|
rev = "701d981f0ab979b79143e4f3b52e3b58836d4f6e";
|
||||||
sha256 = "0x2lwcryvmnr128r497bzrawi4x1yyxb4riicppdaib95iwn8jck";
|
sha256 = "0wwa5ivrvqy4izj2zwn9vzr44n54lz3kbbj4d6f0gjriab07dwd6";
|
||||||
};
|
};
|
||||||
|
|
||||||
nmd = import nmdSrc { inherit lib pkgs; };
|
nmd = import nmdSrc { inherit lib pkgs; };
|
||||||
|
|
|
||||||
171
doc/faq.adoc
Normal file
171
doc/faq.adoc
Normal file
|
|
@ -0,0 +1,171 @@
|
||||||
|
[[ch-faq]]
|
||||||
|
== Frequently Asked Questions (FAQ)
|
||||||
|
|
||||||
|
=== Why is there a collision error when switching generation?
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
----
|
||||||
|
$ nix-env --query
|
||||||
|
hello-2.10
|
||||||
|
----
|
||||||
|
|
||||||
|
and your Home Manager configuration contains
|
||||||
|
|
||||||
|
[source,nix]
|
||||||
|
----
|
||||||
|
home.packages = [ pkgs.hello ];
|
||||||
|
----
|
||||||
|
|
||||||
|
Then attempting to switch to this configuration will result in an error similar to
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
----
|
||||||
|
$ home-manager switch
|
||||||
|
these derivations will be built:
|
||||||
|
/nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv
|
||||||
|
[…]
|
||||||
|
Activating installPackages
|
||||||
|
replacing old ‘home-manager-path’
|
||||||
|
installing ‘home-manager-path’
|
||||||
|
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.
|
||||||
|
|
||||||
|
=== Why are the session variables not set?
|
||||||
|
|
||||||
|
Home Manager is only able to set session variables automatically if it manages your Bash or Z shell configuration. 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
|
||||||
|
|
||||||
|
[source,bash]
|
||||||
|
----
|
||||||
|
. "$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.
|
||||||
|
|
||||||
|
=== How do set up a configuration for multiple users/machines?
|
||||||
|
:post-your-homenix: https://www.reddit.com/r/NixOS/comments/9bb9h9/post_your_homemanager_homenix_file/
|
||||||
|
|
||||||
|
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
|
||||||
|
- `common.nix`
|
||||||
|
|
||||||
|
in your repository. On the kronos and rhea machines you can then make `~jane/.config/nixpkgs/home.nix` be a symbolic link to the corresponding file in your configuration repository.
|
||||||
|
|
||||||
|
The `kronos-jane.nix` and `rhea-jane.nix` files follow the format
|
||||||
|
|
||||||
|
[source,nix]
|
||||||
|
----
|
||||||
|
{ ... }:
|
||||||
|
|
||||||
|
{
|
||||||
|
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-homenix}[Post your home-manager home.nix file!] Reddit thread.
|
||||||
|
|
||||||
|
=== Why do I get an error message about `ca.desrt.dconf`?
|
||||||
|
|
||||||
|
You are most likely trying to configure the GTK or Gnome Terminal 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
|
||||||
|
----
|
||||||
|
|
||||||
|
The solution on NixOS is to add
|
||||||
|
|
||||||
|
[source,nix]
|
||||||
|
services.dbus.packages = with pkgs; [ gnome3.dconf ];
|
||||||
|
|
||||||
|
to your system configuration.
|
||||||
|
|
||||||
|
=== How do I install packages from Nixpkgs unstable?
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
[source,nix]
|
||||||
|
----
|
||||||
|
{ pkgs, config, ... }:
|
||||||
|
|
||||||
|
let
|
||||||
|
|
||||||
|
pkgsUnstable = import <nixpkgs-unstable> {};
|
||||||
|
|
||||||
|
in
|
||||||
|
|
||||||
|
{
|
||||||
|
home.packages = [
|
||||||
|
pkgsUnstable.foo
|
||||||
|
];
|
||||||
|
|
||||||
|
# …
|
||||||
|
}
|
||||||
|
----
|
||||||
|
|
||||||
|
should work provided you have a Nix channel called `nixpkgs-unstable`.
|
||||||
|
|
||||||
|
You can add the `nixpkgs-unstable` channel by running
|
||||||
|
|
||||||
|
[source,console]
|
||||||
|
----
|
||||||
|
# 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.
|
||||||
|
|
||||||
|
=== How do I override the package used by a module?
|
||||||
|
:nixpkgs-overlays: https://nixos.org/nixpkgs/manual/#chap-overlays
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
1. If the module provides a `package` option, such as `programs.beets.package`, then this is the recommended way to perform the override. For example,
|
||||||
|
+
|
||||||
|
[source,nix]
|
||||||
|
programs.beets.package = pkgs.beets.override { enableCheck = true; };
|
||||||
|
|
||||||
|
2. If no `package` option is available then you can typically override the relevant package using an {nixpkgs-overlays}[overlay].
|
||||||
|
+
|
||||||
|
For example, if you want to use the `programs.skim` module but use the `skim` package from Nixpkgs unstable, then a configuration like
|
||||||
|
+
|
||||||
|
[source,nix]
|
||||||
|
----
|
||||||
|
{ pkgs, config, ... }:
|
||||||
|
|
||||||
|
let
|
||||||
|
|
||||||
|
pkgsUnstable = import <nixpkgs-unstable> {};
|
||||||
|
|
||||||
|
in
|
||||||
|
|
||||||
|
{
|
||||||
|
programs.skim.enable = true;
|
||||||
|
|
||||||
|
nixpkgs.overlays = [
|
||||||
|
(self: super: {
|
||||||
|
skim = pkgsUnstable.skim;
|
||||||
|
})
|
||||||
|
];
|
||||||
|
|
||||||
|
# …
|
||||||
|
}
|
||||||
|
----
|
||||||
|
+
|
||||||
|
should work OK.
|
||||||
|
|
@ -27,6 +27,7 @@
|
||||||
</preface>
|
</preface>
|
||||||
<xi:include href="installation.xml" />
|
<xi:include href="installation.xml" />
|
||||||
<xi:include href="writing-modules.xml" />
|
<xi:include href="writing-modules.xml" />
|
||||||
|
<xi:include href="faq.xml" />
|
||||||
<appendix xml:id="ch-options">
|
<appendix xml:id="ch-options">
|
||||||
<title>Configuration Options</title>
|
<title>Configuration Options</title>
|
||||||
<xi:include href="./nmd-result/home-manager-options.xml" />
|
<xi:include href="./nmd-result/home-manager-options.xml" />
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue