docs: convert installation chapter to AsciiDoc

This commit is contained in:
Robert Helgesson 2020-11-05 22:52:20 +01:00
parent ef72617c4a
commit faca77d77d
No known key found for this signature in database
GPG key ID: 36BDAA14C2797E89
2 changed files with 260 additions and 334 deletions

260
doc/installation.adoc Normal file
View file

@ -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
<<sec-install-standalone>> 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 <<sec-install-nixos-module>> 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 <<sec-install-nix-darwin-module>>
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 '<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 {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 '<home-manager>' -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
<<opt-programs.home-manager.path>> 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 = [ <home-manager/nixos> ];
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.<name>.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 = [ <home-manager/nix-darwin> ];
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.<name>.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.
====

View file

@ -1,334 +0,0 @@
<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. 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 <literal>nix-instantiate '&lt;nixpkgs&gt;' -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/nix-community/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/nix-community/home-manager/archive/release-20.09.tar.gz home-manager</userinput>
<prompt>$</prompt> <userinput>nix-channel --update</userinput>
</screen>
<para>
if you follow a Nixpkgs version 20.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 '&lt;home-manager&gt;' -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">
. &quot;$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh&quot;
</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 language="console">
<prompt>#</prompt> <userinput>nix-channel --add https://github.com/nix-community/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 language="console">
<prompt>#</prompt> <userinput>nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager</userinput>
<prompt>#</prompt> <userinput>nix-channel --update</userinput>
</screen>
<para>
if you follow a Nixpkgs version 20.09 channel.
</para>
<para>
It is then possible to add
</para>
<programlisting language="nix">
imports = [ &lt;home-manager/nixos&gt; ];
</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>
<note>
<para>
By default, Home Manager uses a private <literal>pkgs</literal> instance
that is configured via the <option>home-manager.users.&lt;name&gt;.nixpkgs</option> options.
To instead use the global <literal>pkgs</literal> that is configured via
the system level <option>nixpkgs</option> options, set
</para>
<programlisting language="nix">
home-manager.useGlobalPkgs = true;
</programlisting>
<para>
This saves an extra Nixpkgs evaluation, adds consistency, and removes the
dependency on <envar>NIX_PATH</envar>, which is otherwise used for
importing Nixpkgs.
</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 language="console">
<prompt>#</prompt> <userinput>nix-channel --add https://github.com/nix-community/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 language="console">
<prompt>#</prompt> <userinput>nix-channel --add https://github.com/nix-community/home-manager/archive/release-20.09.tar.gz home-manager</userinput>
<prompt>#</prompt> <userinput>nix-channel --update</userinput>
</screen>
<para>
if you follow a Nixpkgs version 20.09 channel.
</para>
<para>
It is then possible to add
</para>
<programlisting language="nix">
imports = [ &lt;home-manager/nix-darwin&gt; ];
</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>
<note>
<para>
By default, Home Manager uses a private <literal>pkgs</literal> instance
that is configured via the <option>home-manager.users.&lt;name&gt;.nixpkgs</option> options.
To instead use the global <literal>pkgs</literal> that is configured via
the system level <option>nixpkgs</option> options, set
</para>
<programlisting language="nix">
home-manager.useGlobalPkgs = true;
</programlisting>
<para>
This saves an extra Nixpkgs evaluation, adds consistency, and removes the
dependency on <envar>NIX_PATH</envar>, which is otherwise used for
importing Nixpkgs.
</para>
</note>
</section>
</chapter>