|
|
|
|
@ -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> |
Robert Helgesson
4 years ago