diff options
author | Robert Helgesson <robert@rycee.net> | 2018-09-15 13:27:21 +0200 |
---|---|---|
committer | Robert Helgesson <robert@rycee.net> | 2018-12-06 00:57:49 +0100 |
commit | 6e67bb7ae611ee37bd94638f90a3f001467a7ba3 (patch) | |
tree | 2b49d0f63c1fcf23f5bcc35c05938bad19bf41a7 /doc | |
parent | d67835260dbdbc0fc3fc735871ec26a2421ac1b2 (diff) |
doc: add installation instructions to manual
Also minor cleanups in README.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/installation.xml | 149 | ||||
-rw-r--r-- | doc/manual.xml | 1 |
2 files changed, 150 insertions, 0 deletions
diff --git a/doc/installation.xml b/doc/installation.xml new file mode 100644 index 00000000000..532947554b0 --- /dev/null +++ b/doc/installation.xml @@ -0,0 +1,149 @@ +<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> +<programlisting> +$ mkdir -m 0755 -p /nix/var/nix/{profiles,gcroots}/per-user/$USER +</programlisting> + <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> +<programlisting> +$ nix-channel --add https://github.com/rycee/home-manager/archive/master.tar.gz home-manager +$ nix-channel --update +</programlisting> + <para> + if you are following Nixpkgs master or an unstable channel and + </para> +<programlisting> +$ nix-channel --add https://github.com/rycee/home-manager/archive/release-18.09.tar.gz home-manager +$ nix-channel --update +</programlisting> + <para> + if you follow a Nixpkgs version 18.09 channel. + </para> + </listitem> + <listitem> + <para> + Run the Home Manager installation command and create the first Home + Manager generation: + </para> +<programlisting> +$ nix-shell '<home-manager>' -A install +</programlisting> + <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> +$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> + To be done. + </para> + </section> + <section xml:id="sec-install-nix-darwin-module"> + <title>nix-darwin module</title> + + <para> + To be done. + </para> + </section> +</chapter> diff --git a/doc/manual.xml b/doc/manual.xml index f076f833886..f0431092b2a 100644 --- a/doc/manual.xml +++ b/doc/manual.xml @@ -24,6 +24,7 @@ </para> </note> </preface> + <xi:include href="installation.xml" /> <appendix xml:id="ch-options"> <title>Configuration Options</title> <xi:include href="./generated/options-db.xml" xpointer="configuration-variable-list" /> |