nix-community/home-manager
1
0
Fork 0
mirror of https://github.com/nix-community/home-manager.git synced 2025-12-05 08:31:03 +01:00
Code Activity

deploy: 5feb9dba3c

Browse source
This commit is contained in:
rycee 2024-10-25 08:24:35 +00:00
parent 99c67113d3
commit e090f86894
2 changed files with 294 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

57
index.xhtml
View file

@ -33,7 +33,7 @@
</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-introduction">Introduction to Home Manager</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="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-introduction">Introduction to Home Manager</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-usage-gpu-non-nixos">GPU on non-NixOS systems</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 id="preface" class="title" >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>
@ -235,7 +235,7 @@ the option. You can find the complete option documentation in
</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 id="sec-usage-configuration" class="title" style="clear: both">Configuration Example </h2> </div> </div></div><p>A fresh install of Home Manager will generate a minimal
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-usage-gpu-non-nixos">GPU on non-NixOS systems</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 id="sec-usage-configuration" class="title" style="clear: both">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, ... }:
{
@ -370,6 +370,59 @@ like</p><pre><code class="programlisting nix">{
# …
}
</code></pre><p>in your Home Manager configuration.</p>
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-usage-gpu-non-nixos" class="title" style="clear: both">GPU on non-NixOS systems </h2> </div> </div></div><p>To access the GPU, programs need access to OpenGL and Vulkan libraries. While
this works transparently on NixOS, it does not on other Linux systems. A
solution is provided by <a class="link" href="https://github.com/nix-community/nixGL" target="_top">NixGL</a>, which
can be integrated into Home Manager.</p><p>To enable the integration, import NixGL into your home configuration, either as
a channel, or as a flake input passed via <code class="literal">extraSpecialArgs</code>. Then, set the
<code class="literal">nixGL.packages</code> option to the package set provided by NixGL.</p><p>Once integration is enabled, it can be used in two ways: as Nix functions for
wrapping programs installed via Home Manager, and as shell commands for running
programs installed by other means (such as <code class="literal">nix shell</code>). In either case, there
are several wrappers available. They can be broadly categorized</p><div class="itemizedlist"><ul class="itemizedlist compact" style="list-style-type: disc;"><li class="listitem"><p>by vendor: as Mesa (for Free drivers of all vendors) and Nvidia (for
Nvidia-specific proprietary drivers).</p></li><li class="listitem"><p>by GPU selection: as primary and secondary (offloading).</p></li></ul></div><p>For example, the <code class="literal">mesa</code> wrapper provides support for running programs on the
primary GPU for Intel, AMD and Nouveau drivers, while the <code class="literal">mesaPrime</code> wrapper
does the same for the secondary GPU.</p><p><span class="strong"><strong>Note:</strong></span> when using Nvidia wrappers together with flakes, your home
configuration will not be pure and needs to be built using <code class="literal">home-manager switch --impure</code>. Otherwise, the build will fail, complaining about missing attribute
<code class="literal">currentTime</code>.</p><p>Wrapper functions are available under <code class="literal">config.lib.nixGL.wrappers</code>. However, it
can be more convenient to use the <code class="literal">config.lib.nixGL.wrap</code> alias, which can be
configured to use any of the wrappers. It is intended to provide a customization
point when the same home configuration is used across several machines with
different hardware. There is also the <code class="literal">config.lib.nixGL.wrapOffload</code> alias for
two-GPU systems.</p><p>Another convenience is that all wrapper functions are always available. However,
when <code class="literal">nixGL.packages</code> option is unset, they are no-ops. This allows them to be
used even when the home configuration is used on NixOS machines. The exception
is the <code class="literal">prime-offload</code> script which ignores <code class="literal">nixGL.packages</code> and is installed
into the environment whenever <code class="literal">nixGL.prime.installScript</code> is set. This script,
which can be used to start a program on a secondary GPU, does not depend on
NixGL and is useful on NixOS systems as well.</p><p>Below is an abbreviated example for an Optimus laptop that makes use of both
Mesa and Nvidia wrappers, where the latter is used in dGPU offloading mode. It
demonstrates how to wrap <code class="literal">mpv</code> to run on the integrated Intel GPU, wrap FreeCAD
to run on the Nvidia dGPU, and how to install the wrapper scripts. It also wraps
Xonotic to run on the dGPU, but uses the wrapper function directly for
demonstration purposes.</p><pre><code class="programlisting nix">{ config, lib, pkgs, nixgl, ... }:
{
nixGL.packages = nixgl.packages;
nixGL.defaultWrapper = &quot;mesa&quot;;
nixGL.offloadWrapper = &quot;nvidiaPrime&quot;;
nixGL.installScripts = [ &quot;mesa&quot; &quot;nvidiaPrime&quot; ];
programs.mpv = {
enable = true;
package = config.lib.nixGL.wrap pkgs.mpv;
};
home.packages = [
(config.lib.nixGL.wrapOffload pkgs.freecad)
(config.lib.nixGL.wrappers.nvidiaPrime pkgs.xonotic)
];
}
</code></pre><p>The above example assumes a flake-based setup where <code class="literal">nixgl</code> was passed from the
flake. When using channels, the example would instead begin with</p><pre><code class="programlisting nix">{ config, lib, pkgs, ... }:
{
nixGL.packages = import &lt;nixgl&gt; { inherit pkgs; };
# The rest is the same as above
...
</code></pre>
</div><div class="section"> <div class="titlepage"> <div> <div> <h2 id="sec-updating" class="title" style="clear: both">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