docs: make README refer to installation chapter
This gives a single source of truth of installation instructions and we can also point to instructions for the NixOS and nix-darwin modules.
This commit is contained in:
Robert Helgesson
parent
e785e67977
commit
c855cdde20
106
README.md
106
README.md
|
|
@ -53,87 +53,25 @@ You can chat with us on IRC in the channel [#home-manager][] on
|
|||
Installation
|
||||
------------
|
||||
|
||||
Currently the easiest way to install Home Manager is as follows:
|
||||
Home Manager can be used in three primary ways:
|
||||
|
||||
1. Make sure you have a working Nix installation. Specifically, make
|
||||
sure that your user is able to build and install Nix packages. For
|
||||
example, you should be able to successfully run a command like
|
||||
`nix-instantiate '<nixpkgs>' -A hello` without having to switch to
|
||||
the root user. For a multi-user install of Nix this means that
|
||||
your user must be covered by the
|
||||
[`allowed-users`][nixAllowedUsers] Nix option. On NixOS you can
|
||||
control this option using the
|
||||
[`nix.allowedUsers`][nixosAllowedUsers] system option.
|
||||
1. Using the standalone `home-manager` tool. For platforms other than
|
||||
NixOS and Darwin, this is the only available choice. It is also
|
||||
recommended for people on NixOS or Darwin that want to manage their
|
||||
home directory independently of the system as a whole. See
|
||||
[Standalone installation][manual standalone install] in the manual
|
||||
for instructions on how to perform this installation.
|
||||
|
||||
Note that Nix 2.4 is not yet fully supported. Most significantly,
|
||||
Home Manager is incompatible with the new `nix profile` command.
|
||||
2. As a module within a NixOS system configuration. This allows the
|
||||
user profiles to be built together with the system when running
|
||||
`nixos-rebuild`. See [NixOS module installation][manual nixos
|
||||
install] in the manual for a description of this setup.
|
||||
|
||||
2. Add the appropriate Home Manager channel. If you are following
|
||||
Nixpkgs master or an unstable channel you can run
|
||||
|
||||
```shell
|
||||
nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
|
||||
nix-channel --update
|
||||
```
|
||||
|
||||
and if you follow a Nixpkgs version 21.05 channel you can run
|
||||
|
||||
```shell
|
||||
nix-channel --add https://github.com/nix-community/home-manager/archive/release-21.05.tar.gz home-manager
|
||||
nix-channel --update
|
||||
```
|
||||
|
||||
On NixOS you may need to log out and back in for the channel to
|
||||
become available. On non-NixOS you may have to add
|
||||
|
||||
```shell
|
||||
export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH
|
||||
```
|
||||
|
||||
to your shell (see [nix#2033](https://github.com/NixOS/nix/issues/2033)).
|
||||
|
||||
3. Install Home Manager and create the first Home Manager generation:
|
||||
|
||||
```shell
|
||||
nix-shell '<home-manager>' -A install
|
||||
```
|
||||
|
||||
Once finished, Home Manager should be active and available in your
|
||||
user environment.
|
||||
|
||||
3. If you do not plan on having Home Manager manage your shell
|
||||
configuration then you must source the
|
||||
|
||||
```shell
|
||||
$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh
|
||||
```
|
||||
|
||||
file in your shell configuration. This file can be sourced
|
||||
directly by POSIX.2-like shells such as [Bash][] or [Z shell][].
|
||||
[Fish][] users can use utilities such as [foreign-env][] or
|
||||
[babelfish][].
|
||||
|
||||
For example, if you use Bash then add
|
||||
|
||||
```bash
|
||||
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||||
```
|
||||
|
||||
or this when managing home configuration together with system
|
||||
configuration
|
||||
|
||||
```bash
|
||||
. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
|
||||
```
|
||||
|
||||
to your `~/.profile` file.
|
||||
|
||||
If instead of using channels you want to run Home Manager from a Git
|
||||
checkout of the repository then you can use the
|
||||
`programs.home-manager.path` option to specify the absolute path to
|
||||
the repository.
|
||||
|
||||
Once installed you can now read the [usage section][manual usage] of the manual.
|
||||
3. As a module within a [nix-darwin][] system configuration. This
|
||||
allows the user profiles to be built together with the system when
|
||||
running `darwin-rebuild`. See [nix-darwin module
|
||||
installation][manual nix-darwin install] in the manual for a
|
||||
description of this setup.
|
||||
|
||||
Nix Flakes
|
||||
----------
|
||||
|
|
@ -223,21 +161,17 @@ License
|
|||
|
||||
This project is licensed under the terms of the [MIT license](LICENSE).
|
||||
|
||||
[Bash]: https://www.gnu.org/software/bash/
|
||||
[Nix]: https://nixos.org/nix/
|
||||
[NixOS]: https://nixos.org/
|
||||
[Nixpkgs]: https://nixos.org/nixpkgs/
|
||||
[nixAllowedUsers]: https://nixos.org/nix/manual/#conf-allowed-users
|
||||
[nixosAllowedUsers]: https://nixos.org/nixos/manual/options.html#opt-nix.allowedUsers
|
||||
[Z shell]: http://zsh.sourceforge.net/
|
||||
[manual]: https://nix-community.github.io/home-manager/
|
||||
[manual usage]: https://nix-community.github.io/home-manager/#ch-usage
|
||||
[configuration options]: https://nix-community.github.io/home-manager/options.html
|
||||
[#home-manager]: https://webchat.oftc.net/?channels=home-manager
|
||||
[OFTC]: https://oftc.net/
|
||||
[samueldr]: https://github.com/samueldr/
|
||||
[Nix Pills]: https://nixos.org/nixos/nix-pills/
|
||||
[Nix Flakes]: https://nixos.wiki/wiki/Flakes
|
||||
[Fish]: https://fishshell.com
|
||||
[foreign-env]: https://github.com/oh-my-fish/plugin-foreign-env
|
||||
[babelfish]: https://github.com/bouk/babelfish
|
||||
[nix-darwin]: https://github.com/LnL7/nix-darwin/
|
||||
[manual standalone install]: https://nix-community.github.io/home-manager/index.html#sec-install-standalone
|
||||
[manual nixos install]: https://nix-community.github.io/home-manager/index.html#sec-install-nixos-module
|
||||
[manual nix-darwin install]: https://nix-community.github.io/home-manager/index.html#sec-install-nix-darwin-module
|
||||
|
|
|
|||
|
|
@ -8,7 +8,7 @@ Home Manager can be used in three primary ways:
|
|||
1. Using the standalone `home-manager` tool. For platforms other than
|
||||
NixOS and Darwin, this is the only available choice. It is also
|
||||
recommended for people on NixOS or Darwin that want to manage their
|
||||
home directory independent of the system as a whole. See
|
||||
home directory independently of the system as a whole. See
|
||||
<<sec-install-standalone>> for instructions on how to perform this
|
||||
installation.
|
||||
|
||||
|
|
@ -27,6 +27,11 @@ for a description of this setup.
|
|||
|
||||
:nix-allowed-users: https://nixos.org/nix/manual/#conf-allowed-users
|
||||
:nixos-allowed-users: https://nixos.org/nixos/manual/options.html#opt-nix.allowedUsers
|
||||
:bash: https://www.gnu.org/software/bash/
|
||||
:zsh: http://zsh.sourceforge.net/
|
||||
:fish: https://fishshell.com
|
||||
:plugin-foreign-env: https://github.com/oh-my-fish/plugin-foreign-env
|
||||
:babelfish: https://github.com/bouk/babelfish
|
||||
|
||||
1. Make sure you have a working Nix installation. Specifically, make
|
||||
sure that your user is able to build and install Nix packages. For
|
||||
|
|
@ -40,9 +45,8 @@ option. On NixOS you can control this option using the
|
|||
Note that Nix 2.4 is not yet fully supported. Most significantly, Home
|
||||
Manager is incompatible with the new `nix profile`.
|
||||
|
||||
2. Add the Home Manager channel that you wish to follow. If you are
|
||||
following Nixpkgs master or an unstable channel then this is done by
|
||||
running
|
||||
2. Add the appropriate Home Manager channel. If you are following
|
||||
Nixpkgs master or an unstable channel you can run
|
||||
+
|
||||
[source,console]
|
||||
----
|
||||
|
|
@ -50,7 +54,7 @@ $ nix-channel --add https://github.com/nix-community/home-manager/archive/master
|
|||
$ nix-channel --update
|
||||
----
|
||||
+
|
||||
and if you follow a Nixpkgs version 21.05 channel, you can run
|
||||
and if you follow a Nixpkgs version 21.05 channel you can run
|
||||
+
|
||||
[source,console]
|
||||
----
|
||||
|
|
@ -90,11 +94,8 @@ file in your shell configuration. Alternatively source
|
|||
when managing home configuration together with system configuration.
|
||||
+
|
||||
This file can be sourced directly by POSIX.2-like shells such as
|
||||
https://www.gnu.org/software/bash/[Bash] or
|
||||
http://zsh.sourceforge.net/[Z shell]. https://fishshell.com[Fish]
|
||||
users can use utilities such as
|
||||
https://github.com/oh-my-fish/plugin-foreign-env[foreign-env] or
|
||||
https://github.com/bouk/babelfish[babelfish].
|
||||
{bash}[Bash] or {zsh}[Z shell]. {fish}[Fish] users can use utilities
|
||||
such as {plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
|
||||
+
|
||||
For example, if you use Bash then add
|
||||
+
|
||||
|
|
@ -110,6 +111,9 @@ checkout of the repository then you can use the
|
|||
<<opt-programs.home-manager.path>> option to specify the absolute path
|
||||
to the repository.
|
||||
|
||||
Once installed you can see <<ch-usage>> for a more detailed
|
||||
description of Home Manager and how to use it.
|
||||
|
||||
[[sec-install-nixos-module]]
|
||||
=== NixOS module
|
||||
|
||||
|
|
@ -162,6 +166,27 @@ home-manager.users.eve = { pkgs, ... }: {
|
|||
and after a `nixos-rebuild switch` the user eve's environment should
|
||||
include a basic Bash configuration and the packages atool and httpie.
|
||||
|
||||
If you do not plan on having Home Manager manage your shell
|
||||
configuration then you must add either
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||||
----
|
||||
|
||||
or
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
|
||||
----
|
||||
|
||||
to your shell configuration, depending on whether
|
||||
<<nixos-opt-home-manager.useUserPackages>> is enabled. This file can
|
||||
be sourced directly by POSIX.2-like shells such as {bash}[Bash] or
|
||||
{zsh}[Z shell]. {fish}[Fish] users can use utilities such as
|
||||
{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
By default packages will be installed to `$HOME/.nix-profile` but they
|
||||
|
|
@ -190,6 +215,9 @@ the dependency on `NIX_PATH`, which is otherwise used for importing
|
|||
Nixpkgs.
|
||||
====
|
||||
|
||||
Once installed you can see <<ch-usage>> for a more detailed
|
||||
description of Home Manager and how to use it.
|
||||
|
||||
[[sec-install-nix-darwin-module]]
|
||||
=== nix-darwin module
|
||||
|
||||
|
|
@ -244,6 +272,27 @@ and after a `darwin-rebuild switch` the user eve's environment
|
|||
should include a basic Bash configuration and the packages atool and
|
||||
httpie.
|
||||
|
||||
If you do not plan on having Home Manager manage your shell
|
||||
configuration then you must add either
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||||
----
|
||||
|
||||
or
|
||||
|
||||
[source,bash]
|
||||
----
|
||||
. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
|
||||
----
|
||||
|
||||
to your shell configuration, depending on whether
|
||||
<<nix-darwin-opt-home-manager.useUserPackages>> is enabled. This file
|
||||
can be sourced directly by POSIX.2-like shells such as {bash}[Bash] or
|
||||
{zsh}[Z shell]. {fish}[Fish] users can use utilities such as
|
||||
{plugin-foreign-env}[foreign-env] or {babelfish}[babelfish].
|
||||
|
||||
[NOTE]
|
||||
====
|
||||
By default user packages will not be ignored in favor of
|
||||
|
|
@ -271,3 +320,6 @@ This saves an extra Nixpkgs evaluation, adds consistency, and removes
|
|||
the dependency on `NIX_PATH`, which is otherwise used for importing
|
||||
Nixpkgs.
|
||||
====
|
||||
|
||||
Once installed you can see <<ch-usage>> for a more detailed
|
||||
description of Home Manager and how to use it.
|
||||
|
|
|
|||
Loading…
Reference in a new issue