kookie
/
nomicon
1
0
Fork 0
Code Issues Projects Releases 1 Activity

docs: make README refer to installation chapter

Browse Source 
This gives a single source of truth of installation instructions and
we can also point to instructions for the NixOS and nix-darwin
modules.
main
Robert Helgesson 3 years ago
parent e785e67977
commit c855cdde20
No known key found for this signature in database
GPG Key ID: 36BDAA14C2797E89
2 changed files with 85 additions and 99 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 112
      README.md
  2. 72
      docs/installation.adoc

112
README.md
Unescape View File

@ -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:
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.
Note that Nix 2.4 is not yet fully supported. Most significantly,
Home Manager is incompatible with the new `nix profile` command.
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.
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 independently of the system as a whole. See
[Standalone installation][manual standalone install] in the manual
for instructions on how to perform this installation.
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.
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

72
docs/installation.adoc
Unescape View File

@ -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.

Write Preview
Loading…
Cancel
Save