diff options
Diffstat (limited to 'home-manager/doc/installation.xml')
| -rw-r--r-- | home-manager/doc/installation.xml | 310 |
1 files changed, 310 insertions, 0 deletions
diff --git a/home-manager/doc/installation.xml b/home-manager/doc/installation.xml new file mode 100644 index 00000000000..52119886800 --- /dev/null +++ b/home-manager/doc/installation.xml @@ -0,0 +1,310 @@ +<chapter xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:xi="http://www.w3.org/2001/XInclude" + version="5.0" + xml:id="ch-installation"> + <title>Installing Home Manager</title> + <para> + Home Manager can be used in three primary ways: + <orderedlist> + <listitem> + <para> + Using the standalone <command>home-manager</command> 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 + <xref linkend="sec-install-standalone"/> for instructions on how to + perform this installation. + </para> + </listitem> + <listitem> + <para> + As a module within a NixOS system configuration. This allows the user + profiles to be built together with the system when running + <command>nixos-rebuild</command>. See + <xref linkend="sec-install-nixos-module"/> for a description of this + setup. + </para> + </listitem> + <listitem> + <para> + As a module within a + <link xlink:href="https://github.com/LnL7/nix-darwin/">nix-darwin</link> + system configuration. This allows the user profiles to be built together + with the system when running <command>darwin-rebuild</command>. See + <xref linkend="sec-install-nix-darwin-module"/> for a description of this + setup. + </para> + </listitem> + </orderedlist> + </para> + <section xml:id="sec-install-standalone"> + <title>Standalone installation</title> + + <orderedlist> + <listitem> + <para> + Make sure you have a working Nix installation. If you are not using NixOS + then it may be necessary to run + </para> +<screen> +<prompt>$</prompt> <userinput>mkdir -m 0755 -p /nix/var/nix/{profiles,gcroots}/per-user/$USER</userinput> +</screen> + <para> + since Home Manager uses these directories to manage your profile + generations. On NixOS these should already be available. + </para> + <para> + Also 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 + <literal>nix-instantiate '<nixpkgs>' -A hello</literal> 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 + <link xlink:href="https://nixos.org/nix/manual/#conf-allowed-users"><literal>allowed-users</literal></link> + Nix option. On NixOS you can control this option using the + <link xlink:href="https://nixos.org/nixos/manual/options.html#opt-nix.allowedUsers"><literal>nix.allowedUsers</literal></link> + system option. + </para> + </listitem> + <listitem> + <para> + Add the Home Manager channel that you wish to follow. This is done by + running + </para> +<screen> +<prompt>$</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager</userinput> +<prompt>$</prompt> <userinput>nix-channel --update</userinput> +</screen> + <para> + if you are following Nixpkgs master or an unstable channel and + </para> +<screen> +<prompt>$</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/release-19.09.tar.gz home-manager</userinput> +<prompt>$</prompt> <userinput>nix-channel --update</userinput> +</screen> + <para> + if you follow a Nixpkgs version 19.09 channel. + </para> + <para> + 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 +<programlisting language="bash"> +export NIX_PATH=$HOME/.nix-defexpr/channels${NIX_PATH:+:}$NIX_PATH +</programlisting> + to your shell (see + <link xlink:href="https://github.com/NixOS/nix/issues/2033">nix#2033</link>). + </para> + </listitem> + <listitem> + <para> + Run the Home Manager installation command and create the first Home + Manager generation: + </para> +<screen> +<prompt>$</prompt> <userinput>nix-shell '<home-manager>' -A install</userinput> +</screen> + <para> + Once finished, Home Manager should be active and available in your user + environment. + </para> + </listitem> + <listitem> + <para> + If you do not plan on having Home Manager manage your shell configuration + then you must source the + </para> +<programlisting language="bash"> +$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh +</programlisting> + <para> + file in your shell configuration. Unfortunately, we currently only support + POSIX.2-like shells such as + <link xlink:href="https://www.gnu.org/software/bash/">Bash</link> or + <link xlink:href="http://zsh.sourceforge.net/">Z shell</link>. + </para> + <para> + For example, if you use Bash then add + </para> +<programlisting language="bash"> +. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" +</programlisting> + <para> + to your <literal>~/.profile</literal> file. + </para> + </listitem> + </orderedlist> + + <para> + If instead of using channels you want to run Home Manager from a Git + checkout of the repository then you can use the + <literal>programs.home-manager.path</literal> option to specify the absolute + path to the repository. + </para> + </section> + <section xml:id="sec-install-nixos-module"> + <title>NixOS module</title> + + <para> + 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 <command>home-manager</command> tool. It also + opens up additional possibilities, for example, to automatically configure + user environments in NixOS declarative containers or on systems deployed + through NixOps. + </para> + + <para> + To make the NixOS module available for use you must <option>import</option> + it into your system configuration. This is most conveniently done by adding + a Home Manager channel, for example + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you are following Nixpkgs master or an unstable channel and + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/release-19.09.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you follow a Nixpkgs version 19.09 channel. + </para> + + <para> + It is then possible to add + </para> + +<programlisting language="nix"> +imports = [ <home-manager/nixos> ]; +</programlisting> + + <para> + to your system <filename>configuration.nix</filename> file, which will + introduce a new NixOS option called <option>home-manager.users</option> + whose type is an attribute set that maps user names to Home Manager + configurations. + </para> + + <para> + For example, a NixOS configuration may include the lines + </para> + +<programlisting language="nix"> +users.users.eve.isNormalUser = true; +home-manager.users.eve = { pkgs, ... }: { + home.packages = [ pkgs.atool pkgs.httpie ]; + programs.bash.enable = true; +}; +</programlisting> + + <para> + and after a <command>nixos-rebuild switch</command> the user eve's + environment should include a basic Bash configuration and the packages atool + and httpie. + </para> + + <note> + <para> + By default packages will be installed to + <filename>$HOME/.nix-profile</filename> but they can be installed to + <filename>/etc/profiles</filename> if + </para> +<programlisting language="nix"> +home-manager.useUserPackages = true; +</programlisting> + <para> + is added to the system configuration. This is necessary if, for example, + you wish to use <command>nixos-rebuild build-vm</command>. This option may + become the default value in the future. + </para> + </note> + </section> + <section xml:id="sec-install-nix-darwin-module"> + <title>nix-darwin module</title> + + <para> + 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 <command>home-manager</command> tool. + </para> + + <para> + To make the NixOS module available for use you must <option>import</option> + it into your system configuration. This is most conveniently done by adding + a Home Manager channel, for example + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you are following Nixpkgs master or an unstable channel and + </para> + +<screen> +<prompt>#</prompt> <userinput>nix-channel --add https://github.com/rycee/home-manager/archive/release-19.09.tar.gz home-manager</userinput> +<prompt>#</prompt> <userinput>nix-channel --update</userinput> +</screen> + + <para> + if you follow a Nixpkgs version 19.09 channel. + </para> + + <para> + It is then possible to add + </para> + +<programlisting language="nix"> +imports = [ <home-manager/nix-darwin> ]; +</programlisting> + + <para> + to your nix-darwin <filename>configuration.nix</filename> file, which will + introduce a new NixOS option called <option>home-manager</option> whose type + is an attribute set that maps user names to Home Manager configurations. + </para> + + <para> + For example, a nix-darwin configuration may include the lines + </para> + +<programlisting language="nix"> +home-manager.users.eve = { pkgs, ... }: { + home.packages = [ pkgs.atool pkgs.httpie ]; + programs.bash.enable = true; +}; +</programlisting> + + <para> + and after a <command>darwin-rebuild --switch</command> the user eve's + environment should include a basic Bash configuration and the packages atool + and httpie. + </para> + + <note> + <para> + By default user packages will not be ignored in favor of + <option>environment.systemPackages</option>, but they will be intalled to + <option>/etc/profiles/per-user/$USERNAME</option> if + </para> + +<programlisting language="nix"> +home-manager.useUserPackages = true; +</programlisting> + + <para> + is added to the nix-darwin configuration. This option may become the default + value in the future. + </para> + </note> + </section> +</chapter> |