diff --git a/doc/installation.adoc b/doc/installation.adoc new file mode 100644 index 000000000..ef97b96b2 --- /dev/null +++ b/doc/installation.adoc @@ -0,0 +1,260 @@ +[[ch-installation]] +== Installing Home Manager + +:nix-darwin: https://github.com/LnL7/nix-darwin/ + +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 +<> 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 <> for a description of +this setup. + +3. As a module within a {nix-darwin}[nix-darwin] system configuration. +This allows the user profiles to be built together with the system +when running `darwin-rebuild`. See <> +for a description of this setup. + +[[sec-install-standalone]] +=== Standalone installation + +:nix-allowed-users: https://nixos.org/nix/manual/#conf-allowed-users +:nixos-allowed-users: https://nixos.org/nixos/manual/options.html#opt-nix.allowedUsers + +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 {nix-allowed-users}[`allowed-users`] Nix +option. On NixOS you can control this option using the +{nixos-allowed-users}[`nix.allowedUsers`] system option. + +2. Add the Home Manager channel that you wish to follow. This is done +by running ++ +[source,console] +---- +$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager +$ nix-channel --update +---- ++ +if you are following Nixpkgs master or an unstable channel and ++ +[source,console] +---- +$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager +$ nix-channel --update +---- ++ +if you follow a Nixpkgs version 20.09 channel. ++ +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 ++ +[source,bash] +export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH ++ +to your shell (see +https://github.com/NixOS/nix/issues/2033[nix#2033]). + +3. Run the Home Manager installation command and create the first Home +Manager generation: ++ +[source,console] +$ nix-shell '' -A install ++ +Once finished, Home Manager should be active and available in your +user environment. + +4. If you do not plan on having Home Manager manage your shell +configuration then you must source the ++ +[source,bash] +$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh ++ +file in your shell configuration. Unfortunately, we currently only +support POSIX.2-like shells such as +https://www.gnu.org/software/bash/[Bash] or +http://zsh.sourceforge.net/[Z shell]. ++ +For example, if you use Bash then add ++ +[source,bash] +---- +. "$HOME/.nix-profile/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 +<> option to specify the absolute path +to the repository. + +[[sec-install-nixos-module]] +=== NixOS module + +Home Manager provides a NixOS module that allows you to prepare user +environments directly from the system configuration file, which often +is more convenient than using the `home-manager` tool. It also opens +up additional possibilities, for example, to automatically configure +user environments in NixOS declarative containers or on systems +deployed through NixOps. + +To make the NixOS module available for use you must `import` it into +your system configuration. This is most conveniently done by adding a +Home Manager channel, for example + +[source,console] +---- +# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager +# nix-channel --update +---- + +if you are following Nixpkgs master or an unstable channel and + +[source,console] +---- +# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager +# nix-channel --update +---- + +if you follow a Nixpkgs version 20.09 channel. + +It is then possible to add + +[source,nix] +imports = [ ]; + +to your system `configuration.nix` file, which will introduce a new +NixOS option called `home-manager.users` whose type is an attribute +set that maps user names to Home Manager configurations. + +For example, a NixOS configuration may include the lines + +[source,nix] +---- +users.users.eve.isNormalUser = true; +home-manager.users.eve = { pkgs, ... }: { + home.packages = [ pkgs.atool pkgs.httpie ]; + programs.bash.enable = true; +}; +---- + +and after a `nixos-rebuild switch` the user eve's environment should +include a basic Bash configuration and the packages atool and httpie. + +[NOTE] +==== +By default packages will be installed to `$HOME/.nix-profile` but they +can be installed to `/etc/profiles` if + +[source,nix] +home-manager.useUserPackages = true; + +is added to the system configuration. This is necessary if, for +example, you wish to use `nixos-rebuild build-vm`. This option may +become the default value in the future. +==== + +[NOTE] +==== +By default, Home Manager uses a private `pkgs` instance that is +configured via the `home-manager.users..nixpkgs` options. To +instead use the global `pkgs` that is configured via the system level +`nixpkgs` options, set + +[source,nix] +home-manager.useGlobalPkgs = true; + +This saves an extra Nixpkgs evaluation, adds consistency, and removes +the dependency on `NIX_PATH`, which is otherwise used for importing +Nixpkgs. +==== + +[[sec-install-nix-darwin-module]] +=== nix-darwin module + +Home Manager provides a module that allows you to prepare user +environments directly from the {nix-darwin}[nix-darwin] configuration +file, which often is more convenient than using the `home-manager` +tool. + +To make the NixOS module available for use you must `import` it into +your system configuration. This is most conveniently done by adding a +Home Manager channel, for example + +[source,console] +---- +# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager +# nix-channel --update +---- + +if you are following Nixpkgs master or an unstable channel and + +[source,console] +---- +# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager +# nix-channel --update +---- + +if you follow a Nixpkgs version 20.09 channel. + +It is then possible to add + +[source,nix] +imports = [ ]; + +to your nix-darwin `configuration.nix` file, which will introduce a +new NixOS option called `home-manager` whose type is an attribute set +that maps user names to Home Manager configurations. + +For example, a nix-darwin configuration may include the lines + +[source,nix] +---- +home-manager.users.eve = { pkgs, ... }: { + home.packages = [ pkgs.atool pkgs.httpie ]; + programs.bash.enable = true; +}; +---- + +and after a `darwin-rebuild --switch` the user eve's environment +should include a basic Bash configuration and the packages atool and +httpie. + +[NOTE] +==== +By default user packages will not be ignored in favor of +`environment.systemPackages`, but they will be intalled to +`/etc/profiles/per-user/$USERNAME` if + +[source,nix] +home-manager.useUserPackages = true; + +is added to the nix-darwin configuration. This option may become the +default value in the future. +==== + +[NOTE] +==== +By default, Home Manager uses a private `pkgs` instance that is +configured via the `home-manager.users..nixpkgs` options. To +instead use the global `pkgs` that is configured via the system level +`nixpkgs` options, set + +[source,nix] +home-manager.useGlobalPkgs = true; + +This saves an extra Nixpkgs evaluation, adds consistency, and removes +the dependency on `NIX_PATH`, which is otherwise used for importing +Nixpkgs. +==== diff --git a/doc/installation.xml b/doc/installation.xml deleted file mode 100644 index aff05a638..000000000 --- a/doc/installation.xml +++ /dev/null @@ -1,334 +0,0 @@ - - Installing Home Manager - - Home Manager can be used in three primary ways: - - - - 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 - for instructions on how to - perform this installation. - - - - - 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 - for a description of this - setup. - - - - - 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 - for a description of this - setup. - - - - -
- Standalone installation - - - - - 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 - Nix option. On NixOS you can control this option using the - nix.allowedUsers - system option. - - - - - Add the Home Manager channel that you wish to follow. This is done by - running - - -$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager -$ nix-channel --update - - - if you are following Nixpkgs master or an unstable channel and - - -$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager -$ nix-channel --update - - - if you follow a Nixpkgs version 20.09 channel. - - - 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 - -export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH - - to your shell (see - nix#2033). - - - - - Run the Home Manager installation command and create the first Home - Manager generation: - - -$ nix-shell '<home-manager>' -A install - - - Once finished, Home Manager should be active and available in your user - environment. - - - - - If you do not plan on having Home Manager manage your shell configuration - then you must source the - - -$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh - - - file in your shell configuration. Unfortunately, we currently only support - POSIX.2-like shells such as - Bash or - Z shell. - - - For example, if you use Bash then add - - -. "$HOME/.nix-profile/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. - -
-
- NixOS module - - - Home Manager provides a NixOS module that allows you to prepare user - environments directly from the system configuration file, which often is - more convenient than using the home-manager tool. It also - opens up additional possibilities, for example, to automatically configure - user environments in NixOS declarative containers or on systems deployed - through NixOps. - - - - To make the NixOS module available for use you must - it into your system configuration. This is most conveniently done by adding - a Home Manager channel, for example - - - -# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager -# nix-channel --update - - - - if you are following Nixpkgs master or an unstable channel and - - - -# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager -# nix-channel --update - - - - if you follow a Nixpkgs version 20.09 channel. - - - - It is then possible to add - - - -imports = [ <home-manager/nixos> ]; - - - - to your system configuration.nix file, which will - introduce a new NixOS option called - whose type is an attribute set that maps user names to Home Manager - configurations. - - - - For example, a NixOS configuration may include the lines - - - -users.users.eve.isNormalUser = true; -home-manager.users.eve = { pkgs, ... }: { - home.packages = [ pkgs.atool pkgs.httpie ]; - programs.bash.enable = true; -}; - - - - and after a nixos-rebuild switch the user eve's - environment should include a basic Bash configuration and the packages atool - and httpie. - - - - - By default packages will be installed to - $HOME/.nix-profile but they can be installed to - /etc/profiles if - - -home-manager.useUserPackages = true; - - - is added to the system configuration. This is necessary if, for example, - you wish to use nixos-rebuild build-vm. This option may - become the default value in the future. - - - - - - By default, Home Manager uses a private pkgs instance - that is configured via the options. - To instead use the global pkgs that is configured via - the system level options, set - - -home-manager.useGlobalPkgs = true; - - - This saves an extra Nixpkgs evaluation, adds consistency, and removes the - dependency on NIX_PATH, which is otherwise used for - importing Nixpkgs. - - -
-
- nix-darwin module - - - Home Manager provides a module that allows you to prepare user - environments directly from the nix-darwin configuration file, which often is - more convenient than using the home-manager tool. - - - - To make the NixOS module available for use you must - it into your system configuration. This is most conveniently done by adding - a Home Manager channel, for example - - - -# nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager -# nix-channel --update - - - - if you are following Nixpkgs master or an unstable channel and - - - -# nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager -# nix-channel --update - - - - if you follow a Nixpkgs version 20.09 channel. - - - - It is then possible to add - - - -imports = [ <home-manager/nix-darwin> ]; - - - - to your nix-darwin configuration.nix file, which will - introduce a new NixOS option called whose type - is an attribute set that maps user names to Home Manager configurations. - - - - For example, a nix-darwin configuration may include the lines - - - -home-manager.users.eve = { pkgs, ... }: { - home.packages = [ pkgs.atool pkgs.httpie ]; - programs.bash.enable = true; -}; - - - - and after a darwin-rebuild --switch the user eve's - environment should include a basic Bash configuration and the packages atool - and httpie. - - - - - By default user packages will not be ignored in favor of - , but they will be intalled to - if - - - -home-manager.useUserPackages = true; - - - - is added to the nix-darwin configuration. This option may become the default - value in the future. - - - - - - By default, Home Manager uses a private pkgs instance - that is configured via the options. - To instead use the global pkgs that is configured via - the system level options, set - - -home-manager.useGlobalPkgs = true; - - - This saves an extra Nixpkgs evaluation, adds consistency, and removes the - dependency on NIX_PATH, which is otherwise used for - importing Nixpkgs. - - -
-