From c855cdde20f3d00c421aeae59546d22430ba86ae Mon Sep 17 00:00:00 2001 From: Robert Helgesson Date: Sun, 14 Nov 2021 23:55:18 +0100 Subject: [PATCH] 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. --- README.md | 106 ++++++++--------------------------------- docs/installation.adoc | 72 ++++++++++++++++++++++++---- 2 files changed, 82 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 019eec5b..f5f010d5 100644 --- a/README.md +++ b/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 '' -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 '' -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 diff --git a/docs/installation.adoc b/docs/installation.adoc index 8a61b958..3bbdb4b7 100644 --- a/docs/installation.adoc +++ b/docs/installation.adoc @@ -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 <> 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 <> option to specify the absolute path to the repository. +Once installed you can see <> 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 +<> 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 <> 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 +<> 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 <> for a more detailed +description of Home Manager and how to use it.