mirror of
https://github.com/nix-community/home-manager
synced 2024-11-27 13:39:46 +01:00
docs: convert installation chapter to AsciiDoc
This commit is contained in:
Robert Helgesson
parent
ef72617c4a
commit
faca77d77d
2 changed files with 260 additions and 334 deletions
260
doc/installation.adoc
Normal file
260
doc/installation.adoc
Normal 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.
|
||||||
|
====
|
||||||
|
|
@ -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 '<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/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 '<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 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 = [ <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>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
By default, Home Manager uses a private <literal>pkgs</literal> instance
|
|
||||||
that is configured via the <option>home-manager.users.<name>.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 = [ <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>
|
|
||||||
|
|
||||||
<note>
|
|
||||||
<para>
|
|
||||||
By default, Home Manager uses a private <literal>pkgs</literal> instance
|
|
||||||
that is configured via the <option>home-manager.users.<name>.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>
|
|
||||||
Loading…
Reference in a new issue