Table of Contents
ca.desrt.dconf or dconf.service? Table of Contents
ca.desrt.dconf or dconf.service? This manual will eventually describe how to install, use, and extend Home Manager.
If you encounter problems then please reach out on the IRC channel #home-manager @@ -235,7 +235,7 @@ the option. You can find the complete option documentation in
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 home-manager switch
-command performs a combined build and activation.
Table of Contents
A fresh install of Home Manager will generate a minimal +command performs a combined build and activation.
A fresh install of Home Manager will generate a minimal
~/.config/home-manager/home.nix file containing something like
{ config, pkgs, ... }:
{
@@ -370,6 +370,59 @@ like{
# …
}
in your Home Manager configuration.
+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 NixGL, which +can be integrated into Home Manager.
To enable the integration, import NixGL into your home configuration, either as
+a channel, or as a flake input passed via extraSpecialArgs. Then, set the
+nixGL.packages option to the package set provided by NixGL.
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 nix shell). In either case, there
+are several wrappers available. They can be broadly categorized
by vendor: as Mesa (for Free drivers of all vendors) and Nvidia (for +Nvidia-specific proprietary drivers).
by GPU selection: as primary and secondary (offloading).
For example, the mesa wrapper provides support for running programs on the
+primary GPU for Intel, AMD and Nouveau drivers, while the mesaPrime wrapper
+does the same for the secondary GPU.
Note: when using Nvidia wrappers together with flakes, your home
+configuration will not be pure and needs to be built using home-manager switch --impure. Otherwise, the build will fail, complaining about missing attribute
+currentTime.
Wrapper functions are available under config.lib.nixGL.wrappers. However, it
+can be more convenient to use the config.lib.nixGL.wrap 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 config.lib.nixGL.wrapOffload alias for
+two-GPU systems.
Another convenience is that all wrapper functions are always available. However,
+when nixGL.packages 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 prime-offload script which ignores nixGL.packages and is installed
+into the environment whenever nixGL.prime.installScript 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.
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 mpv 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.
{ config, lib, pkgs, nixgl, ... }:
+{
+ nixGL.packages = nixgl.packages;
+ nixGL.defaultWrapper = "mesa";
+ nixGL.offloadWrapper = "nvidiaPrime";
+ nixGL.installScripts = [ "mesa" "nvidiaPrime" ];
+
+ 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)
+ ];
+}
+The above example assumes a flake-based setup where nixgl was passed from the
+flake. When using channels, the example would instead begin with
{ config, lib, pkgs, ... }:
+{
+ nixGL.packages = import <nixgl> { inherit pkgs; };
+ # The rest is the same as above
+ ...
+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.
$ nix-channel --update
diff --git a/options.xhtml b/options.xhtml
index 448ae2069..45608a8f5 100644
--- a/options.xhtml
+++ b/options.xhtml
@@ -11540,6 +11540,245 @@ attribute set of (Nix config atom (null, bool, int, float, str, path or package)
+
+
+ nixGL.packages
+
+
+
+
+The nixGL package set containing GPU library wrappers. This can be used
+to provide OpenGL and Vulkan access to applications on non-NixOS systems
+by using (config.lib.nixGL.wrap <package>) for the default wrapper, or
+(config.lib.nixGL.wrappers.<wrapper> <package>) for any available
+wrapper.
The wrapper functions are always available. If this option is empty (the
+default), they are a no-op. This is useful on NixOS where the wrappers
+are unnecessary.
Note that using any Nvidia wrapper requires building the configuration
+with the --impure option.
+
+Type:
+null or (attribute set)
+
+Default:
+null
+
+Example:
+inputs.nixGL.packages
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
+
+
+ nixGL.defaultWrapper
+
+
+
+
+The package wrapper function available for use as (config.lib.nixGL.wrap <package>). Intended to start programs on the main GPU.
Wrapper functions can be found under config.lib.nixGL.wrappers. They
+can be used directly, however, setting this option provides a convenient
+shorthand.
The following wrappers are available:
mesa
mesaPrime
nvidia
nvidiaPrime
+
+Type:
+one of “mesa”, “mesaPrime”, “nvidia”, “nvidiaPrime”
+
+Default:
+"mesa"
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
+
+
+ nixGL.installScripts
+
+
+
+
+For each wrapper wrp named in the provided list, a wrapper script
+named nixGLWrp is installed into the environment. These scripts are
+useful for running programs not installed via Home Manager.
The following wrappers are available:
mesa
mesaPrime
nvidia
nvidiaPrime
+
+Type:
+null or (list of (one of “mesa”, “mesaPrime”, “nvidia”, “nvidiaPrime”))
+
+Default:
+null
+
+Example:
[
+ "mesa"
+ "mesaPrime"
+]
+
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
+
+
+ nixGL.offloadWrapper
+
+
+
+
+The package wrapper function available for use as
+(config.lib.nixGL.wrapOffload <package>). Intended to start programs
+on the secondary GPU.
Wrapper functions can be found under config.lib.nixGL.wrappers. They
+can be used directly, however, setting this option provides a convenient
+shorthand.
The following wrappers are available:
mesa
mesaPrime
nvidia
nvidiaPrime
+
+Type:
+one of “mesa”, “mesaPrime”, “nvidia”, “nvidiaPrime”
+
+Default:
+"mesaPrime"
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
+
+
+ nixGL.prime.card
+
+
+
+
+Selects the non-default graphics card used for PRIME render offloading.
+The value can be:
a number, selecting the n-th non-default GPU;
a PCI bus id in the form pci-XXX_YY_ZZ_U;
a PCI id in the form vendor_id:device_id
For more information, consult the Mesa documentation on the DRI_PRIME
+environment variable.
+
+Type:
+string
+
+Default:
+"1"
+
+Example:
+"pci-0000_06_00_0"
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
+
+
+ nixGL.prime.installScript
+
+
+
+
+If this option is set, the wrapper script prime-offload is installed
+into the environment. It allows starting programs on the secondary GPU
+selected by the nixGL.prime.card option. This makes sense when the
+program is not already using one of nixGL PRIME wrappers, or for
+programs not installed from Nixpkgs.
This option can be set to either “mesa” or “nvidia”, making the script
+use one or the other graphics library.
+
+Type:
+null or one of “mesa”, “nvidia”
+
+Default:
+null
+
+Example:
+"mesa"
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
+
+
+ nixGL.prime.nvidiaProvider
+
+
+
+
+If this option is set, it overrides the offload provider for Nvidia
+PRIME offloading. Consult the proprietary Nvidia driver documentation
+on the __NV_PRIME_RENDER_OFFLOAD_PROVIDER environment variable.
+
+Type:
+null or string
+
+Default:
+null
+
+Example:
+"NVIDIA-G0"
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
+
+
+ nixGL.vulkan.enable
+
+
+
+
+Whether to enable Vulkan in nixGL wrappers.
This is disabled by default bacause Vulkan brings in several libraries
+that can cause symbol version conflicts in wrapped programs. Your
+mileage may vary.
+
+Type:
+boolean
+
+Default:
+false
+
+Example:
+true
+
+Declared by:
+
+
+
+<home-manager/modules/misc/nixgl.nix>
+
+
+
nixpkgs.config