mirror of
https://github.com/nix-community/home-manager
synced 2024-09-21 05:47:29 +02:00
977 lines
No EOL
100 KiB
HTML
977 lines
No EOL
100 KiB
HTML
<?xml version="1.0" encoding="utf-8" standalone="no"?>
|
||
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
||
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
||
<html xmlns="http://www.w3.org/1999/xhtml">
|
||
<head>
|
||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||
<title>Home Manager Manual</title>
|
||
<link rel="stylesheet" type="text/css" href="style.css" />
|
||
<script src="highlightjs/highlight.pack.js" type="text/javascript"></script><script src="highlightjs/loader.js" type="text/javascript"></script>
|
||
<meta name="generator" content="nixos-render-docs" />
|
||
<link rel="home" href="index.xhtml" title="Home Manager Manual" />
|
||
<link rel="next" href="options.xhtml" title="Appendix A. Home Manager Configuration Options" />
|
||
</head>
|
||
<body>
|
||
<div class="navheader">
|
||
<table width="100%" summary="Navigation header">
|
||
<tr>
|
||
<th colspan="3" align="center">Home Manager Manual</th>
|
||
</tr>
|
||
<tr>
|
||
<td width="20%" align="left"> </td>
|
||
<th width="60%" align="center"> </th>
|
||
<td width="20%" align="right"> <a accesskey="n" href="options.xhtml">Next</a></td>
|
||
</tr>
|
||
</table>
|
||
<hr />
|
||
</div>
|
||
<div class="book">
|
||
<div class="titlepage">
|
||
<div>
|
||
<div><h1 class="title"><a id="home-manager-manual"></a>Home Manager Manual</h1></div>
|
||
<div><h2 class="subtitle">Version 24.05 (unstable)</h2></div>
|
||
</div>
|
||
<hr />
|
||
</div>
|
||
<div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="preface"> <a href="index.xhtml#preface">Preface</a> </span></dt><dt> <span class="part"> <a href="index.xhtml#ch-installation">Installing Home Manager</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-install-standalone">Standalone installation</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-install-nixos-module">NixOS module</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-install-nix-darwin-module">nix-darwin module</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-usage">Using Home Manager</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-usage-configuration">Configuration Example</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-usage-rollbacks">Rollbacks</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-usage-dotfiles">Keeping your ~ safe from harm</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-usage-graphical">Graphical services</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-updating">Updating</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-nix-flakes">Nix Flakes</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-flakes-prerequisites">Prerequisites</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-flakes-standalone">Standalone setup</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-flakes-nixos-module">NixOS module</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-flakes-nix-darwin-module">nix-darwin module</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-writing-modules">Writing Home Manager Modules</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-option-types">Option Types</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-contributing">Contributing</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-contrib-getting-started">Getting started</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines">Guidelines</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-news">News</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-tests">Tests</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-3rd-party">Third-Party Tools and Extensions</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#sec-3rd-party-module-collections">Module Collections</a> </span></dt></dl></dd><dt> <span class="part"> <a href="index.xhtml#ch-faq">Frequently Asked Questions (FAQ)</a> </span></dt><dd><dl><dt> <span class="section"> <a href="index.xhtml#_why_is_there_a_collision_error_when_switching_generation">Why is there a collision error when switching generation?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_why_are_the_session_variables_not_set">Why are the session variables not set?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_how_to_set_up_a_configuration_for_multiple_users_machines">How to set up a configuration for multiple users/machines?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal">Why do I get an error message about <code class="literal">ca.desrt.dconf</code> or <code class="literal">dconf.service</code>?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_how_do_i_install_packages_from_nixpkgs_unstable">How do I install packages from Nixpkgs unstable?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_how_do_i_change_the_package_used_by_a_module">How do I change the package used by a module?</a> </span></dt></dl></dd><dt> <span class="appendix"> <a href="options.xhtml">A. Home Manager Configuration Options</a> </span></dt><dt> <span class="appendix"> <a href="nixos-options.xhtml">B. NixOS Configuration Options</a> </span></dt><dt> <span class="appendix"> <a href="nix-darwin-options.xhtml">C. nix-darwin Configuration Options</a> </span></dt><dt> <span class="appendix"> <a href="release-notes.xhtml">D. Release Notes</a> </span></dt> </dl></div>
|
||
<div class="preface"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="preface"></span>Preface </h1> </div> </div></div><p>This manual will eventually describe how to install, use, and extend Home
|
||
Manager.</p><p>If you encounter problems then please reach out on the IRC channel
|
||
<a class="link" href="https://webchat.oftc.net/?channels=home-manager" target="_top">#home-manager</a>
|
||
hosted by <a class="link" href="https://oftc.net/" target="_top">OFTC</a>.
|
||
There is also a <a class="link" href="https://matrix.to/#/%23hm:rycee.net" target="_top">Matrix room</a>,
|
||
which is bridged to the IRC channel.
|
||
If your problem is caused by a bug in Home Manager then it should
|
||
be reported on the
|
||
<a class="link" href="https://github.com/nix-community/home-manager/issues" target="_top">Home Manager issue tracker</a>.</p><div class="note"><h3 class="title">Note</h3><p>Commands prefixed with <code class="literal">$ sudo</code> have to be run as root, either
|
||
requiring to login as root user or temporarily switching to it using
|
||
<code class="literal">sudo</code> for example.</p></div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="ch-installation"></span>Installing Home Manager </h1> </div> </div></div><div class="partintro"><p>Home Manager can be used in three primary ways:</p><div class="orderedlist"><ol class="orderedlist " type="1"><li class="listitem"><p>Using the standalone <code class="literal">home-manager</code> 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 independently of the system as a whole. See
|
||
<a class="link" href="index.xhtml#sec-install-standalone" title="Standalone installation" >Standalone installation</a> for instructions
|
||
on how to perform this installation.</p></li><li class="listitem"><p>As a module within a NixOS system configuration. This allows the
|
||
user profiles to be built together with the system when running
|
||
<code class="literal">nixos-rebuild</code>. See <a class="link" href="index.xhtml#sec-install-nixos-module" title="NixOS module" >NixOS module</a> for a
|
||
description of this setup.</p></li><li class="listitem"><p>As a module within a
|
||
<a class="link" href="https://github.com/LnL7/nix-darwin/" target="_top">nix-darwin</a> system
|
||
configuration. This allows the user profiles to be built together
|
||
with the system when running <code class="literal">darwin-rebuild</code>. See <a class="link" href="index.xhtml#sec-install-nix-darwin-module" title="nix-darwin module" >nix-darwin
|
||
module</a> for a description of this
|
||
setup.</p></li></ol></div><div class="note"><h3 class="title">Note</h3><p>In this chapter we describe how to install Home Manager in the standard
|
||
way using channels. If you prefer to use <a class="link" href="https://nixos.wiki/wiki/Flakes" target="_top">Nix
|
||
Flakes</a> then please see the instructions
|
||
in <a class="link" href="index.xhtml#ch-nix-flakes" title="Nix Flakes" >nix flakes</a>.</p></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-install-standalone">Standalone installation</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-install-nixos-module">NixOS module</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-install-nix-darwin-module">nix-darwin module</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-install-standalone"></span>Standalone installation </h2> </div> </div></div><div class="orderedlist"><ol class="orderedlist " type="1"><li class="listitem"><p>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
|
||
<code class="literal">nix-instantiate '<nixpkgs>' -A hello</code> 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
|
||
<a class="link" href="https://nixos.org/nix/manual/#conf-allowed-users" target="_top"><code class="literal">allowed-users</code></a>
|
||
Nix option. On NixOS you can control this option using the
|
||
<a class="link" href="https://nixos.org/manual/nixos/stable/options.html#opt-nix.settings.allowed-users" target="_top"><code class="literal">nix.settings.allowed-users</code></a>
|
||
system option.</p></li><li class="listitem"><p>Add the appropriate Home Manager channel. If you are following
|
||
Nixpkgs master or an unstable channel you can run</p><pre><code class="programlisting shell">$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
|
||
$ nix-channel --update
|
||
</code></pre><p>and if you follow a Nixpkgs version 23.11 channel you can run</p><pre><code class="programlisting shell">$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
|
||
$ nix-channel --update
|
||
</code></pre></li><li class="listitem"><p>Run the Home Manager installation command and create the first Home
|
||
Manager generation:</p><pre><code class="programlisting shell">$ nix-shell '<home-manager>' -A install
|
||
</code></pre><p>Once finished, Home Manager should be active and available in your
|
||
user environment.</p></li><li class="listitem"><p>If you do not plan on having Home Manager manage your shell
|
||
configuration then you must source the</p><pre><code class="programlisting bash">$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh
|
||
</code></pre><p>file in your shell configuration. Alternatively source</p><pre><code class="programlisting bash">/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh
|
||
</code></pre><p>when managing home configuration together with system configuration.</p><p>This file can be sourced directly by POSIX.2-like shells such as
|
||
<a class="link" href="https://www.gnu.org/software/bash/" target="_top">Bash</a> or <a class="link" href="http://zsh.sourceforge.net/" target="_top">Z
|
||
shell</a>. <a class="link" href="https://fishshell.com" target="_top">Fish</a>
|
||
users can use utilities such as
|
||
<a class="link" href="https://github.com/oh-my-fish/plugin-foreign-env" target="_top">foreign-env</a> or
|
||
<a class="link" href="https://github.com/bouk/babelfish" target="_top">babelfish</a>.</p><p>For example, if you use Bash then add</p><pre><code class="programlisting bash">. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||
</code></pre><p>to your <code class="literal">~/.profile</code> file.</p></li></ol></div><p>If instead of using channels you want to run Home Manager from a Git
|
||
checkout of the repository then you can use the
|
||
<a class="link" href="options.xhtml#opt-programs.home-manager.path" >home-manager.path</a> option to specify the absolute
|
||
path to the repository.</p><p>Once installed you can see <a class="link" href="index.xhtml#ch-usage" title="Using Home Manager" >Using Home Manager</a> for a more detailed
|
||
description of Home Manager and how to use it.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-install-nixos-module"></span>NixOS module </h2> </div> </div></div><p>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 <code class="literal">home-manager</code> tool. It also opens up
|
||
additional possibilities, for example, to automatically configure user
|
||
environments in NixOS declarative containers or on systems deployed
|
||
through NixOps.</p><p>To make the NixOS module available for use you must <code class="literal">import</code> it into
|
||
your system configuration. This is most conveniently done by adding a
|
||
Home Manager channel to the root user. For example, if you are following
|
||
Nixpkgs master or an unstable channel, you can run</p><pre><code class="programlisting shell">$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
|
||
$ sudo nix-channel --update
|
||
</code></pre><p>and if you follow a Nixpkgs version 23.11 channel, you can run</p><pre><code class="programlisting shell">$ sudo nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
|
||
$ sudo nix-channel --update
|
||
</code></pre><p>It is then possible to add</p><pre><code class="programlisting nix">imports = [ <home-manager/nixos> ];
|
||
</code></pre><p>to your system <code class="literal">configuration.nix</code> file, which will introduce a new
|
||
NixOS option called <code class="literal">home-manager.users</code> whose type is an attribute set
|
||
that maps user names to Home Manager configurations.</p><p>For example, a NixOS configuration may include the lines</p><pre><code class="programlisting nix">users.users.eve.isNormalUser = true;
|
||
home-manager.users.eve = { pkgs, ... }: {
|
||
home.packages = [ pkgs.atool pkgs.httpie ];
|
||
programs.bash.enable = true;
|
||
|
||
# The state version is required and should stay at the version you
|
||
# originally installed.
|
||
home.stateVersion = "23.11";
|
||
};
|
||
</code></pre><p>and after a <code class="literal">sudo nixos-rebuild switch</code> the user eve’s environment
|
||
should include a basic Bash configuration and the packages atool and
|
||
httpie.</p><div class="note"><h3 class="title">Note</h3><p>If <code class="literal">nixos-rebuild switch</code> does not result in the environment you expect,
|
||
you can take a look at the output of the Home Manager activation script
|
||
output using</p><pre><code class="programlisting shell">$ systemctl status "home-manager-$USER.service"
|
||
</code></pre></div><p>If you do not plan on having Home Manager manage your shell
|
||
configuration then you must add either</p><pre><code class="programlisting bash">. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||
</code></pre><p>or</p><pre><code class="programlisting bash">. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
|
||
</code></pre><p>to your shell configuration, depending on whether
|
||
<a class="link" href="nixos-options.xhtml#nixos-opt-home-manager.useUserPackages" >home-manager.useUserPackages</a> is enabled. This file can
|
||
be sourced directly by POSIX.2-like shells such as
|
||
<a class="link" href="https://www.gnu.org/software/bash/" target="_top">Bash</a> or <a class="link" href="http://zsh.sourceforge.net/" target="_top">Z
|
||
shell</a>. <a class="link" href="https://fishshell.com" target="_top">Fish</a> users
|
||
can use utilities such as
|
||
<a class="link" href="https://github.com/oh-my-fish/plugin-foreign-env" target="_top">foreign-env</a> or
|
||
<a class="link" href="https://github.com/bouk/babelfish" target="_top">babelfish</a>.</p><div class="note"><h3 class="title">Note</h3><p>By default packages will be installed to <code class="literal">$HOME/.nix-profile</code> but they
|
||
can be installed to <code class="literal">/etc/profiles</code> if</p><pre><code class="programlisting nix">home-manager.useUserPackages = true;
|
||
</code></pre><p>is added to the system configuration. This is necessary if, for example,
|
||
you wish to use <code class="literal">nixos-rebuild build-vm</code>. This option may become the
|
||
default value in the future.</p></div><div class="note"><h3 class="title">Note</h3><p>By default, Home Manager uses a private <code class="literal">pkgs</code> instance that is
|
||
configured via the <code class="literal">home-manager.users.<name>.nixpkgs</code> options. To
|
||
instead use the global <code class="literal">pkgs</code> that is configured via the system level
|
||
<code class="literal">nixpkgs</code> options, set</p><pre><code class="programlisting nix">home-manager.useGlobalPkgs = true;
|
||
</code></pre><p>This saves an extra Nixpkgs evaluation, adds consistency, and removes
|
||
the dependency on <code class="literal">NIX_PATH</code>, which is otherwise used for importing
|
||
Nixpkgs.</p></div><div class="note"><h3 class="title">Note</h3><p>Home Manager will pass <code class="literal">osConfig</code> as a module argument to any modules
|
||
you create. This contains the system’s NixOS configuration.</p><pre><code class="programlisting nix">{ lib, pkgs, osConfig, ... }:
|
||
</code></pre></div><p>Once installed you can see <a class="link" href="index.xhtml#ch-usage" title="Using Home Manager" >Using Home Manager</a> for a more detailed
|
||
description of Home Manager and how to use it.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-install-nix-darwin-module"></span>nix-darwin module </h2> </div> </div></div><p>Home Manager provides a module that allows you to prepare user
|
||
environments directly from the
|
||
<a class="link" href="https://github.com/LnL7/nix-darwin/" target="_top">nix-darwin</a> configuration file,
|
||
which often is more convenient than using the <code class="literal">home-manager</code> tool.</p><p>To make the NixOS module available for use you must <code class="literal">import</code> it into
|
||
your system configuration. This is most conveniently done by adding a
|
||
Home Manager channel. For example, if you are following Nixpkgs master
|
||
or an unstable channel, you can run</p><pre><code class="programlisting shell">$ nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
|
||
$ nix-channel --update
|
||
</code></pre><p>and if you follow a Nixpkgs version 23.11 channel, you can run</p><pre><code class="programlisting shell">$ nix-channel --add https://github.com/nix-community/home-manager/archive/release-23.11.tar.gz home-manager
|
||
$ nix-channel --update
|
||
</code></pre><p>It is then possible to add</p><pre><code class="programlisting nix">imports = [ <home-manager/nix-darwin> ];
|
||
</code></pre><p>to your nix-darwin <code class="literal">configuration.nix</code> file, which will introduce a new
|
||
NixOS option called <code class="literal">home-manager</code> whose type is an attribute set that
|
||
maps user names to Home Manager configurations.</p><p>For example, a nix-darwin configuration may include the lines</p><pre><code class="programlisting nix">users.users.eve = {
|
||
name = "eve";
|
||
home = "/Users/eve";
|
||
};
|
||
home-manager.users.eve = { pkgs, ... }: {
|
||
home.packages = [ pkgs.atool pkgs.httpie ];
|
||
programs.bash.enable = true;
|
||
|
||
# The state version is required and should stay at the version you
|
||
# originally installed.
|
||
home.stateVersion = "23.11";
|
||
};
|
||
</code></pre><p>and after a <code class="literal">darwin-rebuild switch</code> the user eve’s environment should
|
||
include a basic Bash configuration and the packages atool and httpie.</p><p>If you do not plan on having Home Manager manage your shell
|
||
configuration then you must add either</p><pre><code class="programlisting bash">. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||
</code></pre><p>or</p><pre><code class="programlisting bash">. "/etc/profiles/per-user/$USER/etc/profile.d/hm-session-vars.sh"
|
||
</code></pre><p>to your shell configuration, depending on whether
|
||
<a class="link" href="nix-darwin-options.xhtml#nix-darwin-opt-home-manager.useUserPackages" >home-manager.useUserPackages</a> is enabled. This
|
||
file can be sourced directly by POSIX.2-like shells such as
|
||
<a class="link" href="https://www.gnu.org/software/bash/" target="_top">Bash</a> or <a class="link" href="http://zsh.sourceforge.net/" target="_top">Z
|
||
shell</a>. <a class="link" href="https://fishshell.com" target="_top">Fish</a> users
|
||
can use utilities such as
|
||
<a class="link" href="https://github.com/oh-my-fish/plugin-foreign-env" target="_top">foreign-env</a> or
|
||
<a class="link" href="https://github.com/bouk/babelfish" target="_top">babelfish</a>.</p><div class="note"><h3 class="title">Note</h3><p>By default user packages will not be ignored in favor of
|
||
<code class="literal">environment.systemPackages</code>, but they will be installed to
|
||
<code class="literal">/etc/profiles/per-user/$USERNAME</code> if</p><pre><code class="programlisting nix">home-manager.useUserPackages = true;
|
||
</code></pre><p>is added to the nix-darwin configuration. This option may become the
|
||
default value in the future.</p></div><div class="note"><h3 class="title">Note</h3><p>By default, Home Manager uses a private <code class="literal">pkgs</code> instance that is
|
||
configured via the <code class="literal">home-manager.users.<name>.nixpkgs</code> options. To
|
||
instead use the global <code class="literal">pkgs</code> that is configured via the system level
|
||
<code class="literal">nixpkgs</code> options, set</p><pre><code class="programlisting nix">home-manager.useGlobalPkgs = true;
|
||
</code></pre><p>This saves an extra Nixpkgs evaluation, adds consistency, and removes
|
||
the dependency on <code class="literal">NIX_PATH</code>, which is otherwise used for importing
|
||
Nixpkgs.</p></div><div class="note"><h3 class="title">Note</h3><p>Home Manager will pass <code class="literal">osConfig</code> as a module argument to any modules
|
||
you create. This contains the system’s nix-darwin configuration.</p><pre><code class="programlisting nix">{ lib, pkgs, osConfig, ... }:
|
||
</code></pre></div><p>Once installed you can see <a class="link" href="index.xhtml#ch-usage" title="Using Home Manager" >Using Home Manager</a> for a more detailed
|
||
description of Home Manager and how to use it.</p>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="ch-usage"></span>Using Home Manager </h1> </div> </div></div><div class="partintro"><p>Your use of Home Manager is centered around the configuration file,
|
||
which is typically found at <code class="literal">~/.config/home-manager/home.nix</code> in the
|
||
standard installation or <code class="literal">~/.config/home-manager/flake.nix</code> in a Nix
|
||
flake based installation.</p><div class="note"><h3 class="title">Note</h3><p>The default configuration used to be placed in <code class="literal">~/.config/nixpkgs</code>¸ so
|
||
you may see references to that elsewhere. The old directory still works
|
||
but Home Manager will print a warning message when used.</p></div><p>This configuration file can be <span class="emphasis"><em>built</em></span> and <span class="emphasis"><em>activated</em></span>.</p><p>Building a configuration produces a directory in the Nix store that
|
||
contains all files and programs that should be available in your home
|
||
directory and Nix user profile, respectively. The build step also checks
|
||
that the configuration is valid and it will fail with an error if you,
|
||
for example, assign a value to an option that does not exist or assign a
|
||
value of the wrong type. Some modules also have custom assertions that
|
||
perform more detailed, module specific, checks.</p><p>Concretely, if your configuration contains</p><pre><code class="programlisting nix">programs.emacs.enable = "yes";
|
||
</code></pre><p>then building it, for example using <code class="literal">home-manager build</code>, will result in
|
||
an error message saying something like</p><pre><code class="programlisting console">$ home-manager build
|
||
error: A definition for option `programs.emacs.enable' is not of type `boolean'. Definition values:
|
||
- In `/home/jdoe/.config/home-manager/home.nix': "yes"
|
||
(use '--show-trace' to show detailed location information)
|
||
</code></pre><p>The message indicates that you must provide a Boolean value for this
|
||
option, that is, either <code class="literal">true</code> or <code class="literal">false</code>. The documentation of each
|
||
option will state the expected type, for
|
||
<a class="link" href="options.xhtml#opt-programs.emacs.enable" >programs.emacs.enable</a> you will see “Type: boolean”. You
|
||
there also find information about the default value and a description of
|
||
the option. You can find the complete option documentation in
|
||
<a class="link" href="options.xhtml" title="Appendix A. Home Manager Configuration Options" >Home Manager Configuration Options</a> or directly in the terminal by running</p><pre><code class="programlisting shell">man home-configuration.nix
|
||
</code></pre><p>Once a configuration is successfully built, it can be activated. The
|
||
activation performs the steps necessary to make the files, programs, and
|
||
services available in your user environment. The <code class="literal">home-manager switch</code>
|
||
command performs a combined build and activation.</p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-usage-configuration">Configuration Example</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-usage-rollbacks">Rollbacks</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-usage-dotfiles">Keeping your ~ safe from harm</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-usage-graphical">Graphical services</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-updating">Updating</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-usage-configuration"></span>Configuration Example </h2> </div> </div></div><p>A fresh install of Home Manager will generate a minimal
|
||
<code class="literal">~/.config/home-manager/home.nix</code> file containing something like</p><pre><code class="programlisting nix">{ config, pkgs, ... }:
|
||
|
||
{
|
||
# Home Manager needs a bit of information about you and the
|
||
# paths it should manage.
|
||
home.username = "jdoe";
|
||
home.homeDirectory = "/home/jdoe";
|
||
|
||
# This value determines the Home Manager release that your
|
||
# configuration is compatible with. This helps avoid breakage
|
||
# when a new Home Manager release introduces backwards
|
||
# incompatible changes.
|
||
#
|
||
# You can update Home Manager without changing this value. See
|
||
# the Home Manager release notes for a list of state version
|
||
# changes in each release.
|
||
home.stateVersion = "23.11";
|
||
|
||
# Let Home Manager install and manage itself.
|
||
programs.home-manager.enable = true;
|
||
}
|
||
</code></pre><p>You can use this as a base for your further configurations.</p><div class="note"><h3 class="title">Note</h3><p>If you are not very familiar with the Nix language and NixOS modules
|
||
then it is encouraged to start with small and simple changes. As you
|
||
learn you can gradually grow the configuration with confidence.</p></div><p>As an example, let us expand the initial configuration file to also
|
||
install the htop and fortune packages, install Emacs with a few extra
|
||
packages available, and enable the user gpg-agent service.</p><p>To satisfy the above setup we should elaborate the <code class="literal">home.nix</code> file as
|
||
follows:</p><pre><code class="programlisting nix">{ config, pkgs, ... }:
|
||
|
||
{
|
||
# Home Manager needs a bit of information about you and the
|
||
# paths it should manage.
|
||
home.username = "jdoe";
|
||
home.homeDirectory = "/home/jdoe";
|
||
|
||
# Packages that should be installed to the user profile.
|
||
home.packages = [
|
||
pkgs.htop
|
||
pkgs.fortune
|
||
];
|
||
|
||
# This value determines the Home Manager release that your
|
||
# configuration is compatible with. This helps avoid breakage
|
||
# when a new Home Manager release introduces backwards
|
||
# incompatible changes.
|
||
#
|
||
# You can update Home Manager without changing this value. See
|
||
# the Home Manager release notes for a list of state version
|
||
# changes in each release.
|
||
home.stateVersion = "23.11";
|
||
|
||
# Let Home Manager install and manage itself.
|
||
programs.home-manager.enable = true;
|
||
|
||
programs.emacs = {
|
||
enable = true;
|
||
extraPackages = epkgs: [
|
||
epkgs.nix-mode
|
||
epkgs.magit
|
||
];
|
||
};
|
||
|
||
services.gpg-agent = {
|
||
enable = true;
|
||
defaultCacheTtl = 1800;
|
||
enableSshSupport = true;
|
||
};
|
||
}
|
||
</code></pre><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: disc;"><li class="listitem"><p>Nixpkgs packages can be installed to the user profile using
|
||
<a class="link" href="options.xhtml#opt-home.packages" >home.packages</a>.</p></li><li class="listitem"><p>The option names of a program module typically start with
|
||
<code class="literal">programs.<package name></code>.</p></li><li class="listitem"><p>Similarly, for a service module, the names start with
|
||
<code class="literal">services.<package name></code>. Note in some cases a package has both
|
||
programs <span class="emphasis"><em>and</em></span> service options – Emacs is such an example.</p></li></ul></div><p>To activate this configuration you can run</p><pre><code class="programlisting shell">home-manager switch
|
||
</code></pre><p>or if you are not feeling so lucky,</p><pre><code class="programlisting shell">home-manager build
|
||
</code></pre><p>which will create a <code class="literal">result</code> link to a directory containing an
|
||
activation script and the generated home directory files.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-usage-rollbacks"></span>Rollbacks </h2> </div> </div></div><p>While the <code class="literal">home-manager</code> tool does not explicitly support rollbacks at
|
||
the moment it is relatively easy to perform one manually. The steps to
|
||
do so are</p><div class="orderedlist"><ol class="orderedlist " type="1"><li class="listitem"><p>Run <code class="literal">home-manager generations</code> to determine which generation you
|
||
wish to rollback to:</p><pre><code class="programlisting shell">$ home-manager generations
|
||
2018-01-04 11:56 : id 765 -> /nix/store/kahm1rxk77mnvd2l8pfvd4jkkffk5ijk-home-manager-generation
|
||
2018-01-03 10:29 : id 764 -> /nix/store/2wsmsliqr5yynqkdyjzb1y57pr5q2lsj-home-manager-generation
|
||
2018-01-01 12:21 : id 763 -> /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
|
||
2017-12-29 21:03 : id 762 -> /nix/store/6c0k1r03fxckql4vgqcn9ccb616ynb94-home-manager-generation
|
||
2017-12-25 18:51 : id 761 -> /nix/store/czc5y6vi1rvnkfv83cs3rn84jarcgsgh-home-manager-generation
|
||
…
|
||
</code></pre></li><li class="listitem"><p>Copy the Nix store path of the generation you chose, e.g.,</p><pre><code class="programlisting">/nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation
|
||
</code></pre><p>for generation 763.</p></li><li class="listitem"><p>Run the <code class="literal">activate</code> script inside the copied store path:</p><pre><code class="programlisting shell">$ /nix/store/mv960kl9chn2lal5q8lnqdp1ygxngcd1-home-manager-generation/activate
|
||
Starting home manager activation
|
||
…
|
||
</code></pre></li></ol></div>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-usage-dotfiles"></span>Keeping your ~ safe from harm </h2> </div> </div></div><p>To configure programs and services Home Manager must write various
|
||
things to your home directory. To prevent overwriting any existing files
|
||
when switching to a new generation, Home Manager will attempt to detect
|
||
collisions between existing files and generated files. If any such
|
||
collision is detected the activation will terminate before changing
|
||
anything on your computer.</p><p>For example, suppose you have a wonderful, painstakingly created
|
||
<code class="literal">~/.config/git/config</code> and add</p><pre><code class="programlisting nix">{
|
||
# …
|
||
|
||
programs.git = {
|
||
enable = true;
|
||
userName = "Jane Doe";
|
||
userEmail = "jane.doe@example.org";
|
||
};
|
||
|
||
# …
|
||
}
|
||
</code></pre><p>to your configuration. Attempting to switch to the generation will then
|
||
result in</p><pre><code class="programlisting shell">$ home-manager switch
|
||
…
|
||
Activating checkLinkTargets
|
||
Existing file '/home/jdoe/.config/git/config' is in the way
|
||
Please move the above files and try again
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-usage-graphical"></span>Graphical services </h2> </div> </div></div><p>Home Manager includes a number of services intended to run in a
|
||
graphical session, for example <code class="literal">xscreensaver</code> and <code class="literal">dunst</code>.
|
||
Unfortunately, such services will not be started automatically unless
|
||
you let Home Manager start your X session. That is, you have something
|
||
like</p><pre><code class="programlisting nix">{
|
||
# …
|
||
|
||
services.xserver.enable = true;
|
||
|
||
# …
|
||
}
|
||
</code></pre><p>in your system configuration and</p><pre><code class="programlisting nix">{
|
||
# …
|
||
|
||
xsession.enable = true;
|
||
xsession.windowManager.command = "…";
|
||
|
||
# …
|
||
}
|
||
</code></pre><p>in your Home Manager configuration.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-updating"></span>Updating </h2> </div> </div></div><p>If you have installed Home Manager using the Nix channel method then
|
||
updating Home Manager is done by first updating the channel. You can
|
||
then switch to the updated Home Manager environment.</p><pre><code class="programlisting shell">$ nix-channel --update
|
||
…
|
||
unpacking channels...
|
||
$ home-manager switch
|
||
</code></pre>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="ch-nix-flakes"></span>Nix Flakes </h1> </div> </div></div><div class="partintro"><p>Home Manager is compatible with <a class="link" href="https://nixos.wiki/wiki/Flakes" target="_top">Nix
|
||
Flakes</a>. But please be aware that this
|
||
support is still experimental and may change in backwards
|
||
incompatible ways.</p><p>Just like in the standard installation you can use the Home Manager
|
||
flake in three ways:</p><div class="orderedlist"><ol class="orderedlist " type="1"><li class="listitem"><p>Using the standalone <code class="literal">home-manager</code> 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 independently of the system as a whole. See
|
||
<a class="link" href="index.xhtml#sec-flakes-standalone" title="Standalone setup" >Standalone setup</a> for instructions on how
|
||
to perform this installation.</p></li><li class="listitem"><p>As a module within a NixOS system configuration. This allows the
|
||
user profiles to be built together with the system when running
|
||
<code class="literal">nixos-rebuild</code>. See <a class="link" href="index.xhtml#sec-flakes-nixos-module" title="NixOS module" >NixOS module</a> for a
|
||
description of this setup.</p></li><li class="listitem"><p>This allows the user profiles to be built together with the system
|
||
when running <code class="literal">darwin-rebuild</code>. See <a class="link" href="index.xhtml#sec-flakes-nix-darwin-module" title="nix-darwin module" >nix-darwin
|
||
module</a> for a description of this
|
||
setup.</p></li></ol></div><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-flakes-prerequisites">Prerequisites</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-flakes-standalone">Standalone setup</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-flakes-nixos-module">NixOS module</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-flakes-nix-darwin-module">nix-darwin module</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-flakes-prerequisites"></span>Prerequisites </h2> </div> </div></div><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: disc;"><li class="listitem"><p>Install Nix 2.4 or later, or have it in <code class="literal">nix-shell</code>.</p></li><li class="listitem"><p>Enable experimental features <code class="literal">nix-command</code> and <code class="literal">flakes</code>.</p><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: circle;"><li class="listitem"><p>When using NixOS, add the following to your <code class="literal">configuration.nix</code>
|
||
and rebuild your system.</p><pre><code class="programlisting nix">nix = {
|
||
package = pkgs.nixFlakes;
|
||
extraOptions = ''
|
||
experimental-features = nix-command flakes
|
||
'';
|
||
};
|
||
</code></pre></li><li class="listitem"><p>If you are not using NixOS, add the following to <code class="literal">nix.conf</code>
|
||
(located at <code class="literal">~/.config/nix/</code> or <code class="literal">/etc/nix/nix.conf</code>).</p><pre><code class="programlisting bash">experimental-features = nix-command flakes
|
||
</code></pre><p>You may need to restart the Nix daemon with, for example,
|
||
<code class="literal">sudo systemctl restart nix-daemon.service</code>.</p></li><li class="listitem"><p>Alternatively, you can enable flakes on a per-command basis with
|
||
the following additional flags to <code class="literal">nix</code> and <code class="literal">home-manager</code>:</p><pre><code class="programlisting shell">$ nix --extra-experimental-features "nix-command flakes" <sub-commands>
|
||
$ home-manager --extra-experimental-features "nix-command flakes" <sub-commands>
|
||
</code></pre></li></ul></div></li><li class="listitem"><p>Prepare your Home Manager configuration (<code class="literal">home.nix</code>).</p><p>Unlike the channel-based setup, <code class="literal">home.nix</code> will be evaluated when
|
||
the flake is built, so it must be present before bootstrap of Home
|
||
Manager from the flake. See <a class="link" href="index.xhtml#sec-usage-configuration" title="Configuration Example" >Configuration Example</a> for
|
||
introduction about writing a Home Manager configuration.</p></li></ul></div>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-flakes-standalone"></span>Standalone setup </h2> </div> </div></div><p>To prepare an initial Home Manager configuration for your logged in
|
||
user, you can run the Home Manager <code class="literal">init</code> command directly from its
|
||
flake.</p><p>For example, if you are using the unstable version of Nixpkgs or NixOS,
|
||
then to generate and activate a basic configuration run the command</p><pre><code class="programlisting shell">$ nix run home-manager/master -- init --switch
|
||
</code></pre><p>For Nixpkgs or NixOS version 23.11 run</p><pre><code class="programlisting shell">$ nix run home-manager/release-23.11 -- init --switch
|
||
</code></pre><p>This will generate a <code class="literal">flake.nix</code> and a <code class="literal">home.nix</code> file in
|
||
<code class="literal">~/.config/home-manager</code>, creating the directory if it does not exist.</p><p>If you omit the <code class="literal">--switch</code> option then the activation will not happen.
|
||
This is useful if you want to inspect and edit the configuration before
|
||
activating it.</p><pre><code class="programlisting shell">$ nix run home-manager/$branch -- init
|
||
$ # Edit files in ~/.config/home-manager
|
||
$ nix run home-manager/$branch -- init --switch
|
||
</code></pre><p>Where <code class="literal">$branch</code> is one of <code class="literal">master</code> or <code class="literal">release-23.11</code>.</p><p>After the initial activation has completed successfully then building
|
||
and activating your flake-based configuration is as simple as</p><pre><code class="programlisting shell">$ home-manager switch
|
||
</code></pre><p>It is possible to override the default configuration directory, if you
|
||
want. For example,</p><pre><code class="programlisting shell">$ nix run home-manager/$branch -- init --switch ~/hmconf
|
||
$ # And after the initial activation.
|
||
$ home-manager switch --flake ~/hmconf
|
||
</code></pre><div class="note"><h3 class="title">Note</h3><p>The flake inputs are not automatically updated by Home Manager. You need
|
||
to use the standard <code class="literal">nix flake update</code> command for that.</p><p>If you only want to update a single flake input, then the command
|
||
<code class="literal">nix flake lock --update-input <input></code> can be used.</p><p>You can also pass flake-related options such as <code class="literal">--recreate-lock-file</code>
|
||
or <code class="literal">--update-input <input></code> to <code class="literal">home-manager</code> when building or
|
||
switching, and these options will be forwarded to <code class="literal">nix build</code>. See the
|
||
<a class="link" href="https://nixos.wiki/wiki/Flakes" target="_top">NixOS Wiki page</a> for details.</p></div>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-flakes-nixos-module"></span>NixOS module </h2> </div> </div></div><p>To use Home Manager as a NixOS module, a bare-minimum <code class="literal">flake.nix</code> would
|
||
be as follows:</p><pre><code class="programlisting nix">{
|
||
description = "NixOS configuration";
|
||
|
||
inputs = {
|
||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||
home-manager.url = "github:nix-community/home-manager";
|
||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||
};
|
||
|
||
outputs = inputs@{ nixpkgs, home-manager, ... }: {
|
||
nixosConfigurations = {
|
||
hostname = nixpkgs.lib.nixosSystem {
|
||
system = "x86_64-linux";
|
||
modules = [
|
||
./configuration.nix
|
||
home-manager.nixosModules.home-manager
|
||
{
|
||
home-manager.useGlobalPkgs = true;
|
||
home-manager.useUserPackages = true;
|
||
home-manager.users.jdoe = import ./home.nix;
|
||
|
||
# Optionally, use home-manager.extraSpecialArgs to pass
|
||
# arguments to home.nix
|
||
}
|
||
];
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>The Home Manager configuration is then part of the NixOS configuration
|
||
and is automatically rebuilt with the system when using the appropriate
|
||
command for the system, such as
|
||
<code class="literal">nixos-rebuild switch --flake <flake-uri></code>.</p><p>You can use the above <code class="literal">flake.nix</code> as a template in <code class="literal">/etc/nixos</code> by</p><pre><code class="programlisting shell">$ nix flake new /etc/nixos -t github:nix-community/home-manager#nixos
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-flakes-nix-darwin-module"></span>nix-darwin module </h2> </div> </div></div><p>The flake-based setup of the Home Manager nix-darwin module is similar
|
||
to that of NixOS. The <code class="literal">flake.nix</code> would be:</p><pre><code class="programlisting nix">{
|
||
description = "Darwin configuration";
|
||
|
||
inputs = {
|
||
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
|
||
darwin.url = "github:lnl7/nix-darwin";
|
||
darwin.inputs.nixpkgs.follows = "nixpkgs";
|
||
home-manager.url = "github:nix-community/home-manager";
|
||
home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||
};
|
||
|
||
outputs = inputs@{ nixpkgs, home-manager, darwin, ... }: {
|
||
darwinConfigurations = {
|
||
hostname = darwin.lib.darwinSystem {
|
||
system = "x86_64-darwin";
|
||
modules = [
|
||
./configuration.nix
|
||
home-manager.darwinModules.home-manager
|
||
{
|
||
home-manager.useGlobalPkgs = true;
|
||
home-manager.useUserPackages = true;
|
||
home-manager.users.jdoe = import ./home.nix;
|
||
|
||
# Optionally, use home-manager.extraSpecialArgs to pass
|
||
# arguments to home.nix
|
||
}
|
||
];
|
||
};
|
||
};
|
||
};
|
||
}
|
||
</code></pre><p>and it is also rebuilt with the nix-darwin generations. The rebuild
|
||
command here may be <code class="literal">darwin-rebuild switch --flake <flake-uri></code>.</p><p>You can use the above <code class="literal">flake.nix</code> as a template in <code class="literal">~/.config/darwin</code> by</p><pre><code class="programlisting shell">$ nix flake new ~/.config/darwin -t github:nix-community/home-manager#nix-darwin
|
||
</code></pre>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="ch-writing-modules"></span>Writing Home Manager Modules </h1> </div> </div></div><div class="partintro"><p>The module system in Home Manager is based entirely on the NixOS module
|
||
system so we will here only highlight aspects that are specific for Home
|
||
Manager. For information about the module system as such please refer to
|
||
the <a class="link" href="https://nixos.org/nixos/manual/index.html#sec-writing-modules" target="_top">Writing NixOS
|
||
Modules</a>
|
||
chapter of the NixOS manual.</p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-option-types">Option Types</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-option-types"></span>Option Types </h2> </div> </div></div><p>Overall the basic option types are the same in Home Manager as NixOS. A
|
||
few Home Manager options, however, make use of custom types that are
|
||
worth describing in more detail. These are the option types <code class="literal">dagOf</code> and
|
||
<code class="literal">gvariant</code> that are used, for example, by
|
||
<a class="link" href="options.xhtml#opt-programs.ssh.matchBlocks" >programs.ssh.matchBlocks</a> and <a class="link" href="options.xhtml#opt-dconf.settings" >dconf.settings</a>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span id="sec-option-types-dag"></span><code class="literal">hm.types.dagOf</code></span></dt><dd><p>Options of this type have attribute sets as values where each member
|
||
is a node in a <a class="link" href="https://en.wikipedia.org/w/index.php?title=Directed_acyclic_graph&oldid=939656095" target="_top">directed acyclic
|
||
graph</a>
|
||
(DAG). This allows the attribute set entries to express dependency
|
||
relations among themselves. This can, for example, be used to
|
||
control the order of match blocks in a OpenSSH client configuration
|
||
or the order of activation script blocks in
|
||
<a class="link" href="options.xhtml#opt-home.activation" >home.activation</a>.</p><p>A number of functions are provided to create DAG nodes. The
|
||
functions are shown below with examples using an option <code class="literal">foo.bar</code> of
|
||
type <code class="literal">hm.types.dagOf types.int</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span id="sec-option-types-dag-entryAnywhere"></span><code class="literal">hm.dag.entryAnywhere (value: T) : DagEntry<T></code></span></dt><dd><p>Indicates that <code class="literal">value</code> can be placed anywhere within the DAG.
|
||
This is also the default for plain attribute set entries, that
|
||
is</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = hm.dag.entryAnywhere 0;
|
||
}
|
||
</code></pre><p>and</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = 0;
|
||
}
|
||
</code></pre><p>are equivalent.</p></dd><dt><span class="term"><span id="sec-option-types-dag-entryAfter"></span><code class="literal">hm.dag.entryAfter (afters: list string) (value: T) : DagEntry<T></code></span></dt><dd><p>Indicates that <code class="literal">value</code> must be placed <span class="emphasis"><em>after</em></span> each of the
|
||
attribute names in the given list. For example</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = 0;
|
||
b = hm.dag.entryAfter [ "a" ] 1;
|
||
}
|
||
</code></pre><p>would place <code class="literal">b</code> after <code class="literal">a</code> in the graph.</p></dd><dt><span class="term"><span id="sec-option-types-dag-entryBefore"></span><code class="literal">hm.dag.entryBefore (befores: list string) (value: T) : DagEntry<T></code></span></dt><dd><p>Indicates that <code class="literal">value</code> must be placed <span class="emphasis"><em>before</em></span> each of the
|
||
attribute names in the given list. For example</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = hm.dag.entryBefore [ "a" ] 1;
|
||
a = 0;
|
||
}
|
||
</code></pre><p>would place <code class="literal">b</code> before <code class="literal">a</code> in the graph.</p></dd><dt><span class="term"><span id="sec-option-types-dag-entryBetween"></span><code class="literal">hm.dag.entryBetween (befores: list string) (afters: list string) (value: T) : DagEntry<T></code></span></dt><dd><p>Indicates that <code class="literal">value</code> must be placed <span class="emphasis"><em>before</em></span> the attribute
|
||
names in the first list and <span class="emphasis"><em>after</em></span> the attribute names in the
|
||
second list. For example</p><pre><code class="programlisting nix">foo.bar = {
|
||
a = 0;
|
||
c = hm.dag.entryBetween [ "b" ] [ "a" ] 2;
|
||
b = 1;
|
||
}
|
||
</code></pre><p>would place <code class="literal">c</code> before <code class="literal">b</code> and after <code class="literal">a</code> in the graph.</p></dd></dl></div><p>There are also a set of functions that generate a DAG from a list.
|
||
These are convenient when you just want to have a linear list of DAG
|
||
entries, without having to manually enter the relationship between
|
||
each entry. Each of these functions take a <code class="literal">tag</code> as argument and the
|
||
DAG entries will be named <code class="literal">${tag}-${index}</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span id="sec-option-types-dag-entriesAnywhere"></span><code class="literal">hm.dag.entriesAnywhere (tag: string) (values: [T]) : Dag<T></code></span></dt><dd><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. For example</p><pre><code class="programlisting nix">foo.bar = hm.dag.entriesAnywhere "a" [ 0 1 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
a-0 = 0;
|
||
a-1 = hm.dag.entryAfter [ "a-0" ] 1;
|
||
}
|
||
</code></pre></dd><dt><span class="term"><span id="sec-option-types-dag-entriesAfter"></span><code class="literal">hm.dag.entriesAfter (tag: string) (afters: list string) (values: [T]) : Dag<T></code></span></dt><dd><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. The list of values are placed are placed
|
||
<span class="emphasis"><em>after</em></span> each of the attribute names in <code class="literal">afters</code>. For example</p><pre><code class="programlisting nix">foo.bar =
|
||
{ b = 0; }
|
||
// hm.dag.entriesAfter "a" [ "b" ] [ 1 2 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = 0;
|
||
a-0 = hm.dag.entryAfter [ "b" ] 1;
|
||
a-1 = hm.dag.entryAfter [ "a-0" ] 2;
|
||
}
|
||
</code></pre></dd><dt><span class="term"><span id="sec-option-types-dag-entriesBefore"></span><code class="literal">hm.dag.entriesBefore (tag: string) (befores: list string) (values: [T]) : Dag<T></code></span></dt><dd><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. The list of values are placed <span class="emphasis"><em>before</em></span> each
|
||
of the attribute names in <code class="literal">befores</code>. For example</p><pre><code class="programlisting nix">foo.bar =
|
||
{ b = 0; }
|
||
// hm.dag.entriesBefore "a" [ "b" ] [ 1 2 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = 0;
|
||
a-0 = 1;
|
||
a-1 = hm.dag.entryBetween [ "b" ] [ "a-0" ] 2;
|
||
}
|
||
</code></pre></dd><dt><span class="term"><span id="sec-option-types-dag-entriesBetween"></span><code class="literal">hm.dag.entriesBetween (tag: string) (befores: list string) (afters: list string) (values: [T]) : Dag<T></code></span></dt><dd><p>Creates a DAG with the given values with each entry labeled
|
||
using the given tag. The list of values are placed <span class="emphasis"><em>before</em></span> each
|
||
of the attribute names in <code class="literal">befores</code> and <span class="emphasis"><em>after</em></span> each of the
|
||
attribute names in <code class="literal">afters</code>. For example</p><pre><code class="programlisting nix">foo.bar =
|
||
{ b = 0; c = 3; }
|
||
// hm.dag.entriesBetween "a" [ "b" ] [ "c" ] [ 1 2 ];
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = {
|
||
b = 0;
|
||
c = 3;
|
||
a-0 = hm.dag.entryAfter [ "c" ] 1;
|
||
a-1 = hm.dag.entryBetween [ "b" ] [ "a-0" ] 2;
|
||
}
|
||
</code></pre></dd></dl></div></dd><dt><span class="term"><span id="sec-option-types-gvariant"></span><code class="literal">hm.types.gvariant</code></span></dt><dd><p>This type is useful for options representing
|
||
<a class="link" href="https://docs.gtk.org/glib/struct.Variant.html#description" target="_top">GVariant</a>
|
||
values. The type accepts all primitive GVariant types as well as
|
||
arrays, tuples, “maybe” types, and dictionaries.</p><p>Some Nix values are automatically coerced to matching GVariant value
|
||
but the GVariant model is richer so you may need to use one of the
|
||
provided constructor functions. Examples assume an option <code class="literal">foo.bar</code>
|
||
of type <code class="literal">hm.types.gvariant</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span id="sec-option-types-gvariant-mkBoolean"></span><code class="literal">hm.gvariant.mkBoolean (v: bool)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">boolean</code> value (GVariant
|
||
format string <code class="literal">b</code>). Note, Nix booleans are automatically coerced
|
||
using this function. That is,</p><pre><code class="programlisting nix">foo.bar = hm.gvariant.mkBoolean true;
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = true;
|
||
</code></pre></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkString"></span><code class="literal">hm.gvariant.mkString (v: string)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">string</code> value (GVariant
|
||
format string <code class="literal">s</code>). Note, Nix strings are automatically coerced
|
||
using this function. That is,</p><pre><code class="programlisting nix">foo.bar = hm.gvariant.mkString "a string";
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = "a string";
|
||
</code></pre></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkObjectpath"></span><code class="literal">hm.gvariant.mkObjectpath (v: string)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">objectpath</code> value (GVariant
|
||
format string <code class="literal">o</code>).</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkUchar"></span><code class="literal">hm.gvariant.mkUchar (v: string)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">uchar</code> value (GVariant
|
||
format string <code class="literal">y</code>).</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkInt16"></span><code class="literal">hm.gvariant.mkInt16 (v: int)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">int16</code> value (GVariant
|
||
format string <code class="literal">n</code>).</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkUint16"></span><code class="literal">hm.gvariant.mkUint16 (v: int)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">uint16</code> value (GVariant
|
||
format string <code class="literal">q</code>).</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkInt32"></span><code class="literal">hm.gvariant.mkInt32 (v: int)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">int32</code> value (GVariant
|
||
format string <code class="literal">i</code>). Note, Nix integers are automatically coerced
|
||
using this function. That is,</p><pre><code class="programlisting nix">foo.bar = hm.gvariant.mkInt32 7;
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = 7;
|
||
</code></pre></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkUint32"></span><code class="literal">hm.gvariant.mkUint32 (v: int)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">uint32</code> value (GVariant
|
||
format string <code class="literal">u</code>).</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkInt64"></span><code class="literal">hm.gvariant.mkInt64 (v: int)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">int64</code> value (GVariant
|
||
format string <code class="literal">x</code>).</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkUint64"></span><code class="literal">hm.gvariant.mkUint64 (v: int)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">uint64</code> value (GVariant
|
||
format string <code class="literal">t</code>).</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkDouble"></span><code class="literal">hm.gvariant.mkDouble (v: double)</code></span></dt><dd><p>Takes a Nix value <code class="literal">v</code> to a GVariant <code class="literal">double</code> value (GVariant
|
||
format string <code class="literal">d</code>). Note, Nix floats are automatically coerced
|
||
using this function. That is,</p><pre><code class="programlisting nix">foo.bar = hm.gvariant.mkDouble 3.14;
|
||
</code></pre><p>is equivalent to</p><pre><code class="programlisting nix">foo.bar = 3.14;
|
||
</code></pre></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkArray"></span><code class="literal">hm.gvariant.mkArray type elements</code></span></dt><dd><p>Builds a GVariant array containing the given list of elements,
|
||
where each element is a GVariant value of the given type
|
||
(GVariant format string <code class="literal">a${type}</code>). The <code class="literal">type</code> value can be
|
||
constructed using</p><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: disc;"><li class="listitem"><p><code class="literal">hm.gvariant.type.string</code> (GVariant format string <code class="literal">s</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.boolean</code> (GVariant format string <code class="literal">b</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.uchar</code> (GVariant format string <code class="literal">y</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.int16</code> (GVariant format string <code class="literal">n</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.uint16</code> (GVariant format string <code class="literal">q</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.int32</code> (GVariant format string <code class="literal">i</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.uint32</code> (GVariant format string <code class="literal">u</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.int64</code> (GVariant format string <code class="literal">x</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.uint64</code> (GVariant format string <code class="literal">t</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.double</code> (GVariant format string <code class="literal">d</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.variant</code> (GVariant format string <code class="literal">v</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.arrayOf type</code> (GVariant format string
|
||
<code class="literal">a${type}</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.maybeOf type</code> (GVariant format string
|
||
<code class="literal">m${type}</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.tupleOf types</code> (GVariant format string
|
||
<code class="literal">(${lib.concatStrings types})</code>)</p></li><li class="listitem"><p><code class="literal">hm.gvariant.type.dictionaryEntryOf [keyType valueType]</code>
|
||
(GVariant format string <code class="literal">{${keyType}${valueType}}</code>)</p></li></ul></div><p>where <code class="literal">type</code> and <code class="literal">types</code> are themselves a type and list of
|
||
types, respectively.</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkEmptyArray"></span><code class="literal">hm.gvariant.mkEmptyArray type</code></span></dt><dd><p>An alias of
|
||
<a class="link" href="index.xhtml#sec-option-types-gvariant-mkArray" ><code class="literal">hm.gvariant.mkArray type []</code></a>.</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkNothing"></span><code class="literal">hm.gvariant.mkNothing type</code></span></dt><dd><p>Builds a GVariant maybe value (GVariant format string
|
||
<code class="literal">m${type}</code>) whose (non-existent) element is of the given type.
|
||
The <code class="literal">type</code> value is constructed as described for the
|
||
<a class="link" href="index.xhtml#sec-option-types-gvariant-mkArray" ><code class="literal">mkArray</code></a> function above.</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkJust"></span><code class="literal">hm.gvariant.mkJust element</code></span></dt><dd><p>Builds a GVariant maybe value (GVariant format string
|
||
<code class="literal">m${element.type}</code>) containing the given GVariant element.</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkTuple"></span><code class="literal">hm.gvariant.mkTuple elements</code></span></dt><dd><p>Builds a GVariant tuple containing the given list of elements,
|
||
where each element is a GVariant value.</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkVariant"></span><code class="literal">hm.gvariant.mkVariant element</code></span></dt><dd><p>Builds a GVariant variant (GVariant format string <code class="literal">v</code>) which
|
||
contains the value of a GVariant element.</p></dd><dt><span class="term"><span id="sec-option-types-gvariant-mkDictionaryEntry"></span><code class="literal">hm.gvariant.mkDictionaryEntry [key value]</code></span></dt><dd><p>Builds a GVariant dictionary entry containing the given list of
|
||
elements (GVariant format string <code class="literal">{${key.type}${value.type}}</code>),
|
||
where each element is a GVariant value.</p></dd></dl></div></dd></dl></div>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="ch-contributing"></span>Contributing </h1> </div> </div></div><div class="partintro"><p>Contributions to Home Manager are very welcome. To make the process as
|
||
smooth as possible for both you and the Home Manager maintainers we
|
||
provide some guidelines that we ask you to follow. See <a class="link" href="index.xhtml#sec-contrib-getting-started" title="Getting started" >Getting
|
||
started</a> for information on how to set up
|
||
a suitable development environment and <a class="link" href="index.xhtml#sec-guidelines" title="Guidelines" >Guidelines</a> for
|
||
the actual guidelines.</p><p>This text is mainly directed at those who would like to make code
|
||
contributions to Home Manager. If you just want to report a bug then
|
||
first look among the already <a class="link" href="https://github.com/nix-community/home-manager/issues" target="_top">open
|
||
issues</a>, if you
|
||
find one matching yours then feel free to comment on it to add any
|
||
additional information you may have. If no matching issue exists then go
|
||
to the <a class="link" href="https://github.com/nix-community/home-manager/issues/new" target="_top">new
|
||
issue</a> page
|
||
and write a description of your problem. Include as much information as
|
||
you can, ideally also include relevant excerpts from your Home Manager
|
||
configuration.</p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-contrib-getting-started">Getting started</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines">Guidelines</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-news">News</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-tests">Tests</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-contrib-getting-started"></span>Getting started </h2> </div> </div></div><p>If you have not previously forked Home Manager then you need to do that
|
||
first. Have a look at GitHub’s <a class="link" href="https://help.github.com/articles/fork-a-repo/" target="_top">Fork a
|
||
repo</a> for instructions on
|
||
how to do this.</p><p>Once you have a fork of Home Manager you should create a branch starting
|
||
at the most recent <code class="literal">master</code> branch. Give your branch a reasonably
|
||
descriptive name. Commit your changes to this branch and when you are
|
||
happy with the result and it fulfills <a class="link" href="index.xhtml#sec-guidelines" title="Guidelines" >Guidelines</a> then
|
||
push the branch to GitHub and <a class="link" href="https://help.github.com/articles/creating-a-pull-request/" target="_top">create a pull
|
||
request</a>.</p><p>Assuming your clone is at <code class="literal">$HOME/devel/home-manager</code> then you can make
|
||
the <code class="literal">home-manager</code> command use it by either</p><div class="orderedlist"><ol class="orderedlist " type="1"><li class="listitem"><p>overriding the default path by using the <code class="literal">-I</code> command line option:</p><pre><code class="programlisting shell">$ home-manager -I home-manager=$HOME/devel/home-manager
|
||
</code></pre><p>or, if using <a class="link" href="index.xhtml#sec-flakes-standalone" title="Standalone setup" >flakes</a>:</p><pre><code class="programlisting shell">$ home-manager --override-input home-manager ~/devel/home-manager
|
||
</code></pre><p>or</p></li><li class="listitem"><p>changing the default path by ensuring your configuration includes</p><pre><code class="programlisting nix">programs.home-manager.enable = true;
|
||
programs.home-manager.path = "$HOME/devel/home-manager";
|
||
</code></pre><p>and running <code class="literal">home-manager switch</code> to activate the change.
|
||
Afterwards, <code class="literal">home-manager build</code> and <code class="literal">home-manager switch</code> will use
|
||
your cloned repository.</p></li></ol></div><p>The first option is good if you only temporarily want to use your clone.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-guidelines"></span>Guidelines </h2> </div> </div></div><div class="toc"> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-guidelines-back-compat">Maintain backward compatibility</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-forward-compat">Keep forward compatibility in mind</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-valuable-options">Add only valuable options</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-add-tests">Add relevant tests</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-module-maintainer">Add relevant documentation</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_add_yourself_as_a_module_maintainer">Add yourself as a module maintainer</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-code-style">Format your code</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-commit-message-style">Format your commit messages</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-news-style">Format your news entries</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-conditional-modules">Use conditional modules and news</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-guidelines-licensing">Mind the license</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-commit-style">Commits</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#ex-commit-message">Example commit</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#sec-code-style">Code Style</a> </span></dt> </dl></div><p>If your contribution satisfy the following rules then there is a good
|
||
chance it will be merged without too much trouble. The rules are
|
||
enforced by the Home Manager maintainers and to a lesser extent the Home
|
||
Manager CI system.</p><p>If you are uncertain how these rules affect the change you would like to
|
||
make then feel free to start a discussion in the
|
||
<a class="link" href="https://webchat.oftc.net/?channels=home-manager" target="_top">#home-manager</a> IRC
|
||
channel, ideally before you start developing.</p><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-back-compat"></span>Maintain backward compatibility </h3> </div> </div></div><p>Your contribution should not cause another user’s existing configuration
|
||
to break unless there is a very good reason and the change should be
|
||
announced to the user through an
|
||
<a class="link" href="https://nixos.org/manual/nixos/stable/index.html#sec-assertions" target="_top">assertion</a>
|
||
or similar.</p><p>Remember that Home Manager is used in many different environments and
|
||
you should consider how your change may effect others. For example,</p><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: disc;"><li class="listitem"><p>Does your change work for people that do not use NixOS? Consider
|
||
other GNU/Linux distributions and macOS.</p></li><li class="listitem"><p>Does your change work for people whose configuration is built on one
|
||
system and deployed on another system?</p></li></ul></div>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-forward-compat"></span>Keep forward compatibility in mind </h3> </div> </div></div><p>The master branch of Home Manager tracks the unstable channel of
|
||
Nixpkgs, which may update package versions at any time. It is therefore
|
||
important to consider how a package update may affect your code and try
|
||
to reduce the risk of breakage.</p><p>The most effective way to reduce this risk is to follow the advice in
|
||
<a class="link" href="index.xhtml#sec-guidelines-valuable-options" title="Add only valuable options" >Add only valuable options</a>.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-valuable-options"></span>Add only valuable options </h3> </div> </div></div><p>When creating a new module it is tempting to include every option
|
||
supported by the software. This is <span class="emphasis"><em>strongly</em></span> discouraged. Providing
|
||
many options increases maintenance burden and risk of breakage
|
||
considerably. This is why only the most <a class="link" href="https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md#valuable-options" target="_top">important software
|
||
options</a>
|
||
should be modeled explicitly. Less important options should be
|
||
expressible through an <code class="literal">extraConfig</code> escape hatch.</p><p>A good rule of thumb for the first implementation of a module is to only
|
||
add explicit options for those settings that absolutely must be set for
|
||
the software to function correctly. It follows that a module for
|
||
software that provides sensible default values for all settings would
|
||
require no explicit options at all.</p><p>If the software uses a structured configuration format like a JSON,
|
||
YAML, INI, TOML, or even a plain list of key/value pairs then consider
|
||
using a <code class="literal">settings</code> option as described in <a class="link" href="https://github.com/NixOS/rfcs/blob/master/rfcs/0042-config-option.md" target="_top">Nix RFC
|
||
42</a>.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-add-tests"></span>Add relevant tests </h3> </div> </div></div><p>If at all possible, make sure to add new tests and expand existing tests
|
||
so that your change will keep working in the future. See
|
||
<a class="link" href="index.xhtml#sec-tests" title="Tests" >Tests</a> for more information about the Home Manager test
|
||
suite.</p><p>All contributed code <span class="emphasis"><em>must</em></span> pass the test suite.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-module-maintainer"></span>Add relevant documentation </h3> </div> </div></div><p>Many code changes require changing the documentation as well. The
|
||
documentation is written in
|
||
<a class="link" href="https://nixos.org/manual/nixpkgs/unstable/#sec-contributing-markup" target="_top">Nixpkgs-flavoured Markdown</a>.
|
||
All text is hosted in Home Manager’s Git repository.</p><p>The HTML version of the manual containing both the module option
|
||
descriptions and the documentation of Home Manager can be generated and
|
||
opened by typing the following in a shell within a clone of the Home
|
||
Manager Git repository:</p><pre><code class="programlisting shell">$ nix-build -A docs.html
|
||
$ xdg-open ./result/share/doc/home-manager/index.html
|
||
</code></pre><p>When you have made changes to a module, it is a good idea to check that
|
||
the man page version of the module options looks good:</p><pre><code class="programlisting shell">$ nix-build -A docs.manPages
|
||
$ man ./result/share/man/man5/home-configuration.nix.5.gz
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="_add_yourself_as_a_module_maintainer"></span>Add yourself as a module maintainer </h3> </div> </div></div><p>Every new module <span class="emphasis"><em>must</em></span> include a named maintainer using the
|
||
<code class="literal">meta.maintainers</code> attribute. If you are a user of a module that
|
||
currently lacks a maintainer then please consider adopting it.</p><p>If you are present in the nixpkgs maintainer list then you can use that
|
||
entry. If you are not then you can add yourself to
|
||
<code class="literal">modules/lib/maintainers.nix</code> in the Home Manager project.</p><p>As a maintainer you are expected to respond to issues and
|
||
pull-requests associated with your module.</p><p>Maintainers are encouraged to join the IRC or Matrix channel and
|
||
participate when they have opportunity.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-code-style"></span>Format your code </h3> </div> </div></div><p>Make sure your code is formatted as described in <a class="link" href="index.xhtml#sec-code-style" title="Code Style" >Code
|
||
Style</a>. To maintain consistency throughout the project
|
||
you are encouraged to browse through existing code and adopt its style
|
||
also in new code.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-commit-message-style"></span>Format your commit messages </h3> </div> </div></div><p>Similar to <a class="link" href="index.xhtml#sec-guidelines-code-style" title="Format your code" >Format your code</a> we encourage a
|
||
consistent commit message format as described in
|
||
<a class="link" href="index.xhtml#sec-commit-style" title="Commits" >Commits</a>.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-news-style"></span>Format your news entries </h3> </div> </div></div><p>If your contribution includes a change that should be communicated to
|
||
users of Home Manager then you can add a news entry. The entry must be
|
||
formatted as described in <a class="link" href="index.xhtml#sec-news" title="News" >News</a>.</p><p>When new modules are added a news entry should be included but you do
|
||
not need to create this entry manually. The merging maintainer will
|
||
create the entry for you. This is to reduce the risk of merge conflicts.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-conditional-modules"></span>Use conditional modules and news </h3> </div> </div></div><p>Home Manager includes a number of modules that are only usable on some
|
||
of the supported platforms. The most common example of platform specific
|
||
modules are those that define systemd user services, which only works on
|
||
Linux systems.</p><p>If you add a module that is platform specific then make sure to include
|
||
a condition in the <code class="literal">loadModule</code> function call. This will make the module
|
||
accessible only on systems where the condition evaluates to <code class="literal">true</code>.</p><p>Similarly, if you are adding a news entry then it should be shown only
|
||
to users that may find it relevant, see <a class="link" href="index.xhtml#sec-news" title="News" >News</a> for a
|
||
description of conditional news.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-guidelines-licensing"></span>Mind the license </h3> </div> </div></div><p>The Home Manager project is covered by the MIT license and we can only
|
||
accept contributions that fall under this license, or are licensed in a
|
||
compatible way. When you contribute self written code and documentation
|
||
it is assumed that you are doing so under the MIT license.</p><p>A potential gotcha with respect to licensing are option descriptions.
|
||
Often it is convenient to copy from the upstream software documentation.
|
||
When this is done it is important to verify that the license of the
|
||
upstream documentation allows redistribution under the terms of the MIT
|
||
license.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-commit-style"></span>Commits </h3> </div> </div></div><p>The commits in your pull request should be reasonably self-contained,
|
||
that is, each commit should make sense in isolation. In particular, you
|
||
will be asked to amend any commit that introduces syntax errors or
|
||
similar problems even if they are fixed in a later commit.</p><p>The commit messages should follow the <a class="link" href="https://chris.beams.io/posts/git-commit/#seven-rules" target="_top">seven
|
||
rules</a>, except for
|
||
"Capitalize the subject line". We also ask you to include the affected
|
||
code component or module in the first line. That is, a commit message
|
||
should follow the template</p><pre><code class="programlisting">{component}: {description}
|
||
|
||
{long description}
|
||
</code></pre><p>where <code class="literal">{component}</code> refers to the code component (or module) your change
|
||
affects, <code class="literal">{description}</code> is a very brief description of your change, and
|
||
<code class="literal">{long description}</code> is an optional clarifying description. As a rare
|
||
exception, if there is no clear component, or your change affects many
|
||
components, then the <code class="literal">{component}</code> part is optional. See
|
||
<a class="link" href="index.xhtml#ex-commit-message" title="Example commit" >example_title</a> for a commit message that fulfills
|
||
these requirements.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="ex-commit-message"></span>Example commit </h3> </div> </div></div><p>The commit
|
||
<a class="link" href="https://github.com/nix-community/home-manager/commit/69f8e47e9e74c8d3d060ca22e18246b7f7d988ef" target="_top">69f8e47e9e74c8d3d060ca22e18246b7f7d988ef</a>
|
||
contains the commit message</p><pre><code class="programlisting">
|
||
starship: allow running in Emacs if vterm is used
|
||
|
||
The vterm buffer is backed by libvterm and can handle Starship prompts
|
||
without issues.
|
||
</code></pre><p>which ticks all the boxes necessary to be accepted in Home Manager.</p><p>Finally, when adding a new module, say <code class="literal">programs/foo.nix</code>, we use the
|
||
fixed commit format <code class="literal">foo: add module</code>. You can, of course, still include
|
||
a long description if you wish.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h3 class="title" > <span id="sec-code-style"></span>Code Style </h3> </div> </div></div><p>The code in Home Manager is formatted by the
|
||
<a class="link" href="https://github.com/serokell/nixfmt/" target="_top">nixfmt</a> tool and the formatting is
|
||
checked in the pull request tests. Run the <code class="literal">format</code> tool inside the
|
||
project repository before submitting your pull request.</p><p>Keep lines at a reasonable width, ideally 80 characters or less. This
|
||
also applies to string literals.</p><p>We prefer <code class="literal">lowerCamelCase</code> for variable and attribute names with the
|
||
accepted exception of variables directly referencing packages in Nixpkgs
|
||
which use a hyphenated style. For example, the Home Manager option
|
||
<code class="literal">services.gpg-agent.enableSshSupport</code> references the <code class="literal">gpg-agent</code> package
|
||
in Nixpkgs.</p>
|
||
</div>
|
||
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-news"></span>News </h2> </div> </div></div><p>Home Manager includes a system for presenting news to the user. When
|
||
making a change you, therefore, have the option to also include an
|
||
associated news entry. In general, a news entry should only be added for
|
||
truly noteworthy news. For example, a bug fix or new option does
|
||
generally not need a news entry.</p><p>If you do have a change worthy of a news entry then please add one in
|
||
<a class="link" href="https://github.com/nix-community/home-manager/blob/master/modules/misc/news.nix" target="_top"><code class="literal">news.nix</code></a>
|
||
but you should follow some basic guidelines:</p><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: disc;"><li class="listitem"><p>The entry timestamp should be in ISO-8601 format having "+00:00"
|
||
as time zone. For example, "2017-09-13T17:10:14+00:00". A suitable
|
||
timestamp can be produced by the command</p><pre><code class="programlisting shell">$ date --iso-8601=second --universal
|
||
</code></pre></li><li class="listitem"><p>The entry condition should be as specific as possible. For example,
|
||
if you are changing or deprecating a specific option then you could
|
||
restrict the news to those users who actually use this option.</p></li><li class="listitem"><p>Wrap the news message so that it will fit in the typical terminal,
|
||
that is, at most 80 characters wide. Ideally a bit less.</p></li><li class="listitem"><p>Unlike commit messages, news will be read without any connection to
|
||
the Home Manager source code. It is therefore important to make the
|
||
message understandable in isolation and to those who do not have
|
||
knowledge of the Home Manager internals. To this end it should be
|
||
written in more descriptive, prose like way.</p></li><li class="listitem"><p>If you refer to an option then write its full attribute path. That
|
||
is, instead of writing</p><pre><code class="programlisting">The option 'foo' has been deprecated, please use 'bar' instead.
|
||
</code></pre><p>it should read</p><pre><code class="programlisting">The option 'services.myservice.foo' has been deprecated, please
|
||
use 'services.myservice.bar' instead.
|
||
</code></pre></li><li class="listitem"><p>A new module, say <code class="literal">foo.nix</code>, should always include a news entry that
|
||
has a message along the lines of</p><pre><code class="programlisting">A new module is available: 'services.foo'.
|
||
</code></pre><p>If the module is platform specific, e.g., a service module using
|
||
systemd, then a condition like</p><pre><code class="programlisting nix">condition = hostPlatform.isLinux;
|
||
</code></pre><p>should be added. If you contribute a module then you don’t need to
|
||
add this entry, the merger will create an entry for you.</p></li></ul></div>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-tests"></span>Tests </h2> </div> </div></div><p>Home Manager includes a basic test suite and it is highly recommended to
|
||
include at least one test when adding a module. Tests are typically in
|
||
the form of "golden tests" where, for example, a generated
|
||
configuration file is compared to a known correct file.</p><p>It is relatively easy to create tests by modeling the existing tests,
|
||
found in the <code class="literal">tests</code> project directory. For a full reference to the
|
||
functions available in test scripts, you can look at NMT’s
|
||
<a class="link" href="https://git.sr.ht/~rycee/nmt/tree/master/item/bash-lib" target="_top">bash-lib</a>.</p><p>The full Home Manager test suite can be run by executing</p><pre><code class="programlisting shell">$ nix-shell --pure tests -A run.all
|
||
</code></pre><p>in the project root. List all test cases through</p><pre><code class="programlisting shell">$ nix-shell --pure tests -A list
|
||
</code></pre><p>and run an individual test, for example <code class="literal">alacritty-empty-settings</code>,
|
||
through</p><pre><code class="programlisting shell">$ nix-shell --pure tests -A run.alacritty-empty-settings
|
||
</code></pre><p>However, those invocations will impurely source the system’s nixpkgs,
|
||
and may cause failures. To run against the nixpkgs from the flake.lock,
|
||
use instead e.g.</p><pre><code class="programlisting shell">$ nix develop --ignore-environment .#all
|
||
</code></pre>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="ch-3rd-party"></span>Third-Party Tools and Extensions </h1> </div> </div></div><div class="partintro"><p>Here is a collection of tools and extensions that relate to Home
|
||
Manager. Note, these are maintained outside the regular Home Manager
|
||
flow so quality and support may vary wildly. If you encounter problems
|
||
then please raise them in the corresponding project, not as issues in
|
||
the Home Manager tracker.</p><p>If you have made something interesting related to Home Manager then you
|
||
are encouraged to create a PR that expands this chapter.</p><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#sec-3rd-party-module-collections">Module Collections</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="sec-3rd-party-module-collections"></span>Module Collections </h2> </div> </div></div><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: disc;"><li class="listitem"><p><a class="link" href="https://github.com/schuelermine/xhmm" target="_top">xhmm — extra Home Manager
|
||
modules</a></p><p>A collection of modules maintained by Anselm Schüler.</p></li><li class="listitem"><p><a class="link" href="https://github.com/danth/stylix/" target="_top">Stylix — System-wide colorscheming and
|
||
typography</a></p><p>Configure your applications to get coherent color scheme and font.</p></li></ul></div>
|
||
</div>
|
||
</div><div class="part"> <div class="titlepage"> <div> <div> <h1 class="title" > <span id="ch-faq"></span>Frequently Asked Questions (FAQ) </h1> </div> </div></div><div class="partintro"><div class="toc"> <p><strong>Table of Contents</strong></p> <dl class="toc"> <dt> <span class="section"> <a href="index.xhtml#_why_is_there_a_collision_error_when_switching_generation">Why is there a collision error when switching generation?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_why_are_the_session_variables_not_set">Why are the session variables not set?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_how_to_set_up_a_configuration_for_multiple_users_machines">How to set up a configuration for multiple users/machines?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal">Why do I get an error message about <code class="literal">ca.desrt.dconf</code> or <code class="literal">dconf.service</code>?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_how_do_i_install_packages_from_nixpkgs_unstable">How do I install packages from Nixpkgs unstable?</a> </span></dt><dt> <span class="section"> <a href="index.xhtml#_how_do_i_change_the_package_used_by_a_module">How do I change the package used by a module?</a> </span></dt> </dl></div></div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="_why_is_there_a_collision_error_when_switching_generation"></span>Why is there a collision error when switching generation? </h2> </div> </div></div><p>Home Manager currently installs packages into the user environment,
|
||
precisely as if the packages were installed through <code class="literal">nix-env --install</code>.
|
||
This means that you will get a collision error if your Home Manager
|
||
configuration attempts to install a package that you already have
|
||
installed manually, that is, packages that shows up when you run
|
||
<code class="literal">nix-env --query</code>.</p><p>For example, imagine you have the <code class="literal">hello</code> package installed in your
|
||
environment</p><pre><code class="programlisting shell">$ nix-env --query
|
||
hello-2.10
|
||
</code></pre><p>and your Home Manager configuration contains</p><pre><code class="programlisting nix">home.packages = [ pkgs.hello ];
|
||
</code></pre><p>Then attempting to switch to this configuration will result in an error
|
||
similar to</p><pre><code class="programlisting shell">$ home-manager switch
|
||
these derivations will be built:
|
||
/nix/store/xg69wsnd1rp8xgs9qfsjal017nf0ldhm-home-manager-path.drv
|
||
[…]
|
||
Activating installPackages
|
||
replacing old ‘home-manager-path’
|
||
installing ‘home-manager-path’
|
||
building path(s) ‘/nix/store/b5c0asjz9f06l52l9812w6k39ifr49jj-user-environment’
|
||
Wide character in die at /nix/store/64jc9gd2rkbgdb4yjx3nrgc91bpjj5ky-buildenv.pl line 79.
|
||
collision between ‘/nix/store/fmwa4axzghz11cnln5absh31nbhs9lq1-home-manager-path/bin/hello’ and ‘/nix/store/c2wyl8b9p4afivpcz8jplc9kis8rj36d-hello-2.10/bin/hello’; use ‘nix-env --set-flag priority NUMBER PKGNAME’ to change the priority of one of the conflicting packages
|
||
builder for ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed with exit code 2
|
||
error: build of ‘/nix/store/b37x3s7pzxbasfqhaca5dqbf3pjjw0ip-user-environment.drv’ failed
|
||
</code></pre><p>The solution is typically to uninstall the package from the environment
|
||
using <code class="literal">nix-env --uninstall</code> and reattempt the Home Manager generation
|
||
switch.</p><p>You could also opt to unistall <span class="emphasis"><em>all</em></span> of the packages from your profile
|
||
with <code class="literal">nix-env --uninstall '*'</code>.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="_why_are_the_session_variables_not_set"></span>Why are the session variables not set? </h2> </div> </div></div><p>Home Manager is only able to set session variables automatically if it
|
||
manages your Bash, Z shell, or fish shell configuration. To enable such
|
||
management you use <a class="link" href="options.xhtml#opt-programs.bash.enable" >programs.bash.enable</a>,
|
||
<a class="link" href="options.xhtml#opt-programs.zsh.enable" >programs.zsh.enable</a>, or <a class="link" href="options.xhtml#opt-programs.fish.enable" >programs.fish.enable</a>.</p><p>If you don’t want to let Home Manager manage your shell then you will
|
||
have to manually source the
|
||
<code class="literal">~/.nix-profile/etc/profile.d/hm-session-vars.sh</code> file in an appropriate
|
||
way. In Bash and Z shell this can be done by adding</p><pre><code class="programlisting bash">. "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh"
|
||
</code></pre><p>to your <code class="literal">.profile</code> and <code class="literal">.zshrc</code> files, respectively. The
|
||
<code class="literal">hm-session-vars.sh</code> file should work in most Bourne-like shells. For
|
||
fish shell, it is possible to source it using <a class="link" href="https://github.com/oh-my-fish/plugin-foreign-env" target="_top">the foreign-env
|
||
plugin</a></p><pre><code class="programlisting bash">fenv source "$HOME/.nix-profile/etc/profile.d/hm-session-vars.sh" > /dev/null
|
||
</code></pre>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="_how_to_set_up_a_configuration_for_multiple_users_machines"></span>How to set up a configuration for multiple users/machines? </h2> </div> </div></div><p>A typical way to prepare a repository of configurations for multiple
|
||
logins and machines is to prepare one "top-level" file for each unique
|
||
combination.</p><p>For example, if you have two machines, called "kronos" and "rhea" on
|
||
which you want to configure your user "jane" then you could create the
|
||
files</p><div class="itemizedlist"><ul class="itemizedlist " style="list-style-type: disc;"><li class="listitem"><p><code class="literal">kronos-jane.nix</code>,</p></li><li class="listitem"><p><code class="literal">rhea-jane.nix</code>, and</p></li><li class="listitem"><p><code class="literal">common.nix</code></p></li></ul></div><p>in your repository. On the kronos and rhea machines you can then make
|
||
<code class="literal">~jane/.config/home-manager/home.nix</code> be a symbolic link to the
|
||
corresponding file in your configuration repository.</p><p>The <code class="literal">kronos-jane.nix</code> and <code class="literal">rhea-jane.nix</code> files follow the format</p><pre><code class="programlisting nix">{ ... }:
|
||
|
||
{
|
||
imports = [ ./common.nix ];
|
||
|
||
# Various options that are specific for this machine/user.
|
||
}
|
||
</code></pre><p>while the <code class="literal">common.nix</code> file contains configuration shared across the two
|
||
logins. Of course, instead of just a single <code class="literal">common.nix</code> file you can
|
||
have multiple ones, even one per program or service.</p><p>You can get some inspiration from the <a class="link" href="https://www.reddit.com/r/NixOS/comments/9bb9h9/post_your_homemanager_homenix_file/" target="_top">Post your home-manager home.nix
|
||
file!</a>
|
||
Reddit thread.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="_why_do_i_get_an_error_message_about_literal_ca_desrt_dconf_literal_or_literal_dconf_service_literal"></span>Why do I get an error message about <code class="literal">ca.desrt.dconf</code> or <code class="literal">dconf.service</code>? </h2> </div> </div></div><p>You are most likely trying to configure something that uses dconf but
|
||
the DBus session is not aware of the dconf service. The full error you
|
||
might get is</p><pre><code class="programlisting">error: GDBus.Error:org.freedesktop.DBus.Error.ServiceUnknown: The name ca.desrt.dconf was not provided by any .service files
|
||
</code></pre><p>or</p><pre><code class="programlisting">error: GDBus.Error:org.freedesktop.systemd1.NoSuchUnit: Unit dconf.service not found.
|
||
</code></pre><p>The solution on NixOS is to add</p><pre><code class="programlisting nix">programs.dconf.enable = true;
|
||
</code></pre><p>to your system configuration.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="_how_do_i_install_packages_from_nixpkgs_unstable"></span>How do I install packages from Nixpkgs unstable? </h2> </div> </div></div><p>If you are using a stable version of Nixpkgs but would like to install
|
||
some particular packages from Nixpkgs unstable – or some other channel
|
||
– then you can import the unstable Nixpkgs and refer to its packages
|
||
within your configuration. Something like</p><pre><code class="programlisting nix">{ pkgs, config, ... }:
|
||
|
||
let
|
||
|
||
pkgsUnstable = import <nixpkgs-unstable> {};
|
||
|
||
in
|
||
|
||
{
|
||
home.packages = [
|
||
pkgsUnstable.foo
|
||
];
|
||
|
||
# …
|
||
}
|
||
</code></pre><p>should work provided you have a Nix channel called <code class="literal">nixpkgs-unstable</code>.</p><p>You can add the <code class="literal">nixpkgs-unstable</code> channel by running</p><pre><code class="programlisting shell">$ nix-channel --add https://nixos.org/channels/nixpkgs-unstable nixpkgs-unstable
|
||
$ nix-channel --update
|
||
</code></pre><p>Note, the package will not be affected by any package overrides,
|
||
overlays, etc.</p>
|
||
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 class="title" style="clear: both"> <span id="_how_do_i_change_the_package_used_by_a_module"></span>How do I change the package used by a module? </h2> </div> </div></div><p>By default Home Manager will install the package provided by your chosen
|
||
<code class="literal">nixpkgs</code> channel but occasionally you might end up needing to change
|
||
this package. This can typically be done in two ways.</p><div class="orderedlist"><ol class="orderedlist " type="1"><li class="listitem"><p>If the module provides a <code class="literal">package</code> option, such as
|
||
<code class="literal">programs.beets.package</code>, then this is the recommended way to
|
||
perform the change. For example,</p><pre><code class="programlisting nix">programs.beets.package = pkgs.beets.override { pluginOverrides = { beatport.enable = false; }; };
|
||
</code></pre><p>See <a class="link" href="https://nixos.org/guides/nix-pills/nixpkgs-overriding-packages.html" target="_top">Nix pill 17</a>
|
||
for more information on package overrides. Alternatively, if you want
|
||
to use the <code class="literal">beets</code> package from Nixpkgs unstable, then a configuration like</p><pre><code class="programlisting nix">{ pkgs, config, ... }:
|
||
|
||
let
|
||
|
||
pkgsUnstable = import <nixpkgs-unstable> {};
|
||
|
||
in
|
||
|
||
{
|
||
programs.beets.package = pkgsUnstable.beets;
|
||
|
||
# …
|
||
}
|
||
</code></pre><p>should work OK.</p></li><li class="listitem"><p>If no <code class="literal">package</code> option is available then you can typically change
|
||
the relevant package using an
|
||
<a class="link" href="https://nixos.org/nixpkgs/manual/#chap-overlays" target="_top">overlay</a>.</p><p>For example, if you want to use the <code class="literal">programs.skim</code> module but use
|
||
the <code class="literal">skim</code> package from Nixpkgs unstable, then a configuration like</p><pre><code class="programlisting nix">{ pkgs, config, ... }:
|
||
|
||
let
|
||
|
||
pkgsUnstable = import <nixpkgs-unstable> {};
|
||
|
||
in
|
||
|
||
{
|
||
programs.skim.enable = true;
|
||
|
||
nixpkgs.overlays = [
|
||
(self: super: {
|
||
skim = pkgsUnstable.skim;
|
||
})
|
||
];
|
||
|
||
# …
|
||
}
|
||
</code></pre><p>should work OK.</p></li></ol></div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="navfooter">
|
||
<hr />
|
||
<table width="100%" summary="Navigation footer">
|
||
<tr>
|
||
<td width="40%" align="left"> </td>
|
||
<td width="20%" align="center"> </td>
|
||
<td width="40%" align="right"> <a accesskey="n" href="options.xhtml">Next</a></td>
|
||
</tr>
|
||
<tr>
|
||
<td width="40%" align="left" valign="top"> </td>
|
||
<td width="20%" align="center"> </td>
|
||
<td width="40%" align="right" valign="top"> Appendix A. Home Manager Configuration Options</td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</body>
|
||
</html> |