3 files changed, 51 insertions, 2 deletions
diff --git a/doc/languages-frameworks/cuda.section.md b/doc/languages-frameworks/cuda.section.md
new file mode 100644
index 0000000000000..fccf66bf79d2a
--- /dev/null
+++ b/doc/languages-frameworks/cuda.section.md
@@ -0,0 +1,34 @@
+# CUDA {#cuda}
+
+CUDA-only packages are stored in the `cudaPackages` packages set. This set
+includes the `cudatoolkit`, portions of the toolkit in separate derivations,
+`cudnn`, `cutensor` and `nccl`.
+
+A package set is available for each CUDA version, so for example
+`cudaPackages_11_6`. Within each set is a matching version of the above listed
+packages. Additionally, other versions of the packages that are packaged and
+compatible are available as well. For example, there can be a
+`cudaPackages.cudnn_8_3_2` package.
+
+To use one or more CUDA packages in an expression, give the expression a `cudaPackages` parameter, and in case CUDA is optional
+```nix
+cudaSupport ? false
+cudaPackages ? {}
+```
+
+When using `callPackage`, you can choose to pass in a different variant, e.g.
+when a different version of the toolkit suffices
+```nix
+mypkg = callPackage { cudaPackages = cudaPackages_11_5; }
+```
+
+If another version of say `cudnn` or `cutensor` is needed, you can override the
+package set to make it the default. This guarantees you get a consistent package
+set.
+```nix
+mypkg = let
+  cudaPackages = cudaPackages_11_5.overrideScope' (final: prev {
+    cudnn = prev.cudnn_8_3_2;
+  }});
+in callPackage { inherit cudaPackages; };
+```
diff --git a/doc/languages-frameworks/gnome.section.md b/doc/languages-frameworks/gnome.section.md
index 29cb2e0e464a2..d5996cce13cfd 100644
--- a/doc/languages-frameworks/gnome.section.md
+++ b/doc/languages-frameworks/gnome.section.md
@@ -42,7 +42,21 @@ Unlike other libraries mentioned in this section, GdkPixbuf only supports a sing
 
 ### Icons {#ssec-gnome-icons}
 
-When an application uses icons, an icon theme should be available in `XDG_DATA_DIRS` during runtime. The package for the default, icon-less [hicolor-icon-theme](https://www.freedesktop.org/wiki/Software/icon-theme/) (should be propagated by every icon theme) contains [a setup hook](#ssec-gnome-hooks-hicolor-icon-theme) that will pick up icon themes from `buildInputs` and pass it to our wrapper. Unfortunately, relying on that would mean every user has to download the theme included in the package expression no matter their preference. For that reason, we leave the installation of icon theme on the user. If you use one of the desktop environments, you probably already have an icon theme installed.
+When an application uses icons, an icon theme should be available in `XDG_DATA_DIRS` during runtime. The package for the default, icon-less [hicolor-icon-theme](https://www.freedesktop.org/wiki/Software/icon-theme/) (should be propagated by every icon theme) contains [a setup hook](#ssec-gnome-hooks-hicolor-icon-theme) that will pick up icon themes from `buildInputs` and add their datadirs to `XDG_ICON_DIRS` environment variable (this is Nixpkgs specific, not actually a XDG standard variable). Unfortunately, relying on that would mean every user has to download the theme included in the package expression no matter their preference. For that reason, we leave the installation of icon theme on the user. If you use one of the desktop environments, you probably already have an icon theme installed.
+
+In the rare case you need to use icons from dependencies (e.g. when an app forces an icon theme), you can use the following to pick them up:
+
+```nix
+  buildInputs = [
+    pantheon.elementary-icon-theme
+  ];
+  preFixup = ''
+    gappsWrapperArgs+=(
+      # The icon theme is hardcoded.
+      --prefix XDG_DATA_DIRS : "$XDG_ICON_DIRS"
+    )
+  '';
+```
 
 To avoid costly file system access when locating icons, GTK, [as well as Qt](https://woboq.com/blog/qicon-reads-gtk-icon-cache-in-qt57.html), can rely on `icon-theme.cache` files from the themes' top-level directories. These files are generated using `gtk-update-icon-cache`, which is expected to be run whenever an icon is added or removed to an icon theme (typically an application icon into `hicolor` theme) and some programs do indeed run this after icon installation. However, since packages are installed into their own prefix by Nix, this would lead to conflicts. For that reason, `gtk3` provides a [setup hook](#ssec-gnome-hooks-gtk-drop-icon-theme-cache) that will clean the file from installation. Since most applications only ship their own icon that will be loaded on start-up, it should not affect them too much. On the other hand, icon themes are much larger and more widely used so we need to cache them. Because we recommend installing icon themes globally, we will generate the cache files from all packages in a profile using a NixOS module. You can enable the cache generation using `gtk.iconCache.enable` option if your desktop environment does not already do that.
 
@@ -98,7 +112,7 @@ For convenience, it also adds `dconf.lib` for a GIO module implementing a GSetti
 
 - []{#ssec-gnome-hooks-dconf} `dconf.lib` is a dependency of `wrapGAppsHook`, which then also adds it to the `GIO_EXTRA_MODULES` variable.
 
-- []{#ssec-gnome-hooks-hicolor-icon-theme} `hicolor-icon-theme`’s setup hook will add icon themes to `XDG_ICON_DIRS` which is prepended to `XDG_DATA_DIRS` by `wrapGAppsHook`.
+- []{#ssec-gnome-hooks-hicolor-icon-theme} `hicolor-icon-theme`’s setup hook will add icon themes to `XDG_ICON_DIRS`.
 
 - []{#ssec-gnome-hooks-gobject-introspection} `gobject-introspection` setup hook populates `GI_TYPELIB_PATH` variable with `lib/girepository-1.0` directories of dependencies, which is then added to wrapper by `wrapGAppsHook`. It also adds `share` directories of dependencies to `XDG_DATA_DIRS`, which is intended to promote GIR files but it also [pollutes the closures](https://github.com/NixOS/nixpkgs/issues/32790) of packages using `wrapGAppsHook`.
 
diff --git a/doc/languages-frameworks/index.xml b/doc/languages-frameworks/index.xml
index 2c34a29d4863f..3d5b2f738976d 100644
--- a/doc/languages-frameworks/index.xml
+++ b/doc/languages-frameworks/index.xml
@@ -12,6 +12,7 @@
  <xi:include href="chicken.section.xml" />
  <xi:include href="coq.section.xml" />
  <xi:include href="crystal.section.xml" />
+ <xi:include href="cuda.section.xml" />
  <xi:include href="dhall.section.xml" />
  <xi:include href="dotnet.section.xml" />
  <xi:include href="emscripten.section.xml" />