9 files changed, 214 insertions, 7 deletions
diff --git a/nixpkgs/doc/builders/fetchers.chapter.md b/nixpkgs/doc/builders/fetchers.chapter.md
index 4d4f3f427cd4..ba105764904c 100644
--- a/nixpkgs/doc/builders/fetchers.chapter.md
+++ b/nixpkgs/doc/builders/fetchers.chapter.md
@@ -82,6 +82,53 @@ Note that because the checksum is computed after applying these effects, using o
 
 Most other fetchers return a directory rather than a single file.
 
+
+## `fetchDebianPatch` {#fetchdebianpatch}
+
+A wrapper around `fetchpatch`, which takes:
+- `patch` and `hash`: the patch's filename without the `.patch` suffix,
+  and its hash after normalization by `fetchpatch` ;
+- `pname`: the Debian source package's name ;
+- `version`: the upstream version number ;
+- `debianRevision`: the [Debian revision number] if applicable ;
+- the `area` of the Debian archive: `main` (default), `contrib`, or `non-free`.
+
+Here is an example of `fetchDebianPatch` in action:
+
+```nix
+{ lib
+, fetchDebianPatch
+, buildPythonPackage
+}:
+
+buildPythonPackage rec {
+  pname = "pysimplesoap";
+  version = "1.16.2";
+  src = ...;
+
+  patches = [
+    (fetchDebianPatch {
+      inherit pname version;
+      debianRevision = "5";
+      name = "Add-quotes-to-SOAPAction-header-in-SoapClient";
+      hash = "sha256-xA8Wnrpr31H8wy3zHSNfezFNjUJt1HbSXn3qUMzeKc0=";
+    })
+  ];
+
+  ...
+}
+```
+
+Patches are fetched from `sources.debian.org`, and so must come from a
+package version that was uploaded to the Debian archive.  Packages may
+be removed from there once that specific version isn't in any suite
+anymore (stable, testing, unstable, etc.), so maintainers should use
+`copy-tarballs.pl` to archive the patch if it needs to be available
+longer-term.
+
+[Debian revision number]: https://www.debian.org/doc/debian-policy/ch-controlfields.html#version
+
+
 ## `fetchsvn` {#fetchsvn}
 
 Used with Subversion. Expects `url` to a Subversion directory, `rev`, and `hash`.
diff --git a/nixpkgs/doc/builders/packages/emacs.section.md b/nixpkgs/doc/builders/packages/emacs.section.md
index d46f890858f4..c50c7815537d 100644
--- a/nixpkgs/doc/builders/packages/emacs.section.md
+++ b/nixpkgs/doc/builders/packages/emacs.section.md
@@ -26,10 +26,6 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t
 {
   packageOverrides = pkgs: with pkgs; rec {
     myEmacsConfig = writeText "default.el" ''
-      ;; initialize package
-
-      (require 'package)
-      (package-initialize 'noactivate)
       (eval-when-compile
         (require 'use-package))
 
@@ -103,7 +99,7 @@ You can install it like any other packages via `nix-env -iA myEmacs`. However, t
 
 This provides a fairly full Emacs start file. It will load in addition to the user's personal config. You can always disable it by passing `-q` to the Emacs command.
 
-Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to Melpa Unstable, and the highest for packages manually defined in `pkgs/top-level/emacs-packages.nix`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`.
+Sometimes `emacs.pkgs.withPackages` is not enough, as this package set has some priorities imposed on packages (with the lowest priority assigned to GNU-devel ELPA, and the highest for packages manually defined in `pkgs/applications/editors/emacs/elisp-packages/manual-packages`). But you can't control these priorities when some package is installed as a dependency. You can override it on a per-package-basis, providing all the required dependencies manually, but it's tedious and there is always a possibility that an unwanted dependency will sneak in through some other package. To completely override such a package, you can use `overrideScope`.
 
 ```nix
 overrides = self: super: rec {
diff --git a/nixpkgs/doc/default.nix b/nixpkgs/doc/default.nix
index f4270ae856d5..58b945c692fc 100644
--- a/nixpkgs/doc/default.nix
+++ b/nixpkgs/doc/default.nix
@@ -21,6 +21,7 @@ let
       { name = "filesystem"; description = "filesystem functions"; }
       { name = "sources"; description = "source filtering functions"; }
       { name = "cli"; description = "command-line serialization functions"; }
+      { name = "gvariant"; description = "GVariant formatted string serialization functions"; }
     ];
   };
 
diff --git a/nixpkgs/doc/hooks/index.md b/nixpkgs/doc/hooks/index.md
index 602febaf9d9b..8100e91c8b48 100644
--- a/nixpkgs/doc/hooks/index.md
+++ b/nixpkgs/doc/hooks/index.md
@@ -17,6 +17,7 @@ installShellFiles.section.md
 libiconv.section.md
 libxml2.section.md
 meson.section.md
+mpi-check-hook.section.md
 ninja.section.md
 patch-rc-path-hooks.section.md
 perl.section.md
diff --git a/nixpkgs/doc/hooks/mpi-check-hook.section.md b/nixpkgs/doc/hooks/mpi-check-hook.section.md
new file mode 100644
index 000000000000..e3fb5c40dada
--- /dev/null
+++ b/nixpkgs/doc/hooks/mpi-check-hook.section.md
@@ -0,0 +1,24 @@
+#  mpiCheckPhaseHook {#setup-hook-mpi-check}
+
+
+This hook can be used to setup a check phase that
+requires running a MPI application. It detects the
+used present MPI implementaion type and exports
+the neceesary environment variables to use
+`mpirun` and `mpiexec` in a Nix sandbox.
+
+
+Example:
+
+```nix
+  { mpiCheckPhaseHook, mpi, ... }:
+
+  ...
+
+  nativeCheckInputs = [
+    openssh
+    mpiCheckPhaseHook
+  ];
+```
+
+
diff --git a/nixpkgs/doc/hooks/waf.section.md b/nixpkgs/doc/hooks/waf.section.md
index ee1bccff1d0a..8cacb30ea85f 100644
--- a/nixpkgs/doc/hooks/waf.section.md
+++ b/nixpkgs/doc/hooks/waf.section.md
@@ -1,3 +1,50 @@
 # wafHook {#wafhook}
 
-Overrides the configure, build, and install phases. This will run the “waf” script used by many projects. If `wafPath` (default `./waf`) doesn’t exist, it will copy the version of waf available in Nixpkgs. `wafFlags` can be used to pass flags to the waf script.
+[Waf](https://waf.io) is a Python-based software building system.
+
+In Nixpkgs, `wafHook` overrides the default configure, build, and install phases.
+
+## Variables controlling wafHook {#variablesControllingWafHook}
+
+### `wafPath` {#wafPath}
+
+Location of the `waf` tool. It defaults to `./waf`, to honor software projects that include it directly inside their source trees.
+
+If `wafPath` doesn't exist, then `wafHook` will copy the `waf` provided from Nixpkgs to it.
+
+### `wafConfigureFlags` {#wafConfigureFlags}
+
+Controls the flags passed to waf tool during configure phase.
+
+### `wafFlags` {#wafFlags}
+
+Controls the flags passed to waf tool during build and install phases.
+
+### `dontAddWafCrossFlags` {#dontAddWafCrossFlags}
+
+When set to `true`, don't add cross compilation flags during configure phase.
+
+### `dontUseWafConfigure` {#dontUseWafConfigure}
+
+When set to true, don't use the predefined `wafConfigurePhase`.
+
+### `dontUseWafBuild` {#dontUseWafBuild}
+
+When set to true, don't use the predefined `wafBuildPhase`.
+
+### `dontUseWafInstall` {#dontUseWafInstall}
+
+When set to true, don't use the predefined `wafInstallPhase`.
+
+### Variables honored by wafHook {#variablesHonoredByWafHook}
+
+The following variables commonly used by `stdenv.mkDerivation` are also honored by `wafHook`.
+
+- `prefixKey`
+- `configureTargets`
+- `enableParallelBuilding`
+- `enableParallelInstalling`
+- `buildFlags`
+- `buildTargets`
+- `installFlags`
+- `installTargets`
diff --git a/nixpkgs/doc/languages-frameworks/chicken.section.md b/nixpkgs/doc/languages-frameworks/chicken.section.md
index d329943dc3c2..72c2642a6478 100644
--- a/nixpkgs/doc/languages-frameworks/chicken.section.md
+++ b/nixpkgs/doc/languages-frameworks/chicken.section.md
@@ -47,3 +47,32 @@ To include more eggs, edit `pkgs/development/compilers/chicken/5/eggs.scm`.
 The first section of this file lists eggs which are required by `egg2nix`
 itself; all other eggs go into the second section. After editing, follow the
 procedure for updating eggs.
+
+## Override Scope {#sec-chicken-override-scope}
+
+The chicken package and its eggs, respectively, reside in a scope. This means,
+the scope can be overridden to effect other packages in it.
+
+This example shows how to use a local copy of `srfi-180` and have it affect
+all the other eggs:
+
+```nix
+let
+  myChickenPackages = pkgs.chickenPackages.overrideScope' (self: super: {
+      # The chicken package itself can be overridden to effect the whole ecosystem.
+      # chicken = super.chicken.overrideAttrs {
+      #   src = ...
+      # };
+
+      chickenEggs = super.chickenEggs.overrideScope' (eggself: eggsuper: {
+        srfi-180 = eggsuper.srfi-180.overrideAttrs {
+          # path to a local copy of srfi-180
+          src = ...
+        };
+      });
+  });
+in
+# Here, `myChickenPackages.chickenEggs.json-rpc`, which depends on `srfi-180` will use
+# the local copy of `srfi-180`.
+# ...
+```
diff --git a/nixpkgs/doc/languages-frameworks/cuda.section.md b/nixpkgs/doc/languages-frameworks/cuda.section.md
index 2d680ea6b3b6..01a4f20da982 100644
--- a/nixpkgs/doc/languages-frameworks/cuda.section.md
+++ b/nixpkgs/doc/languages-frameworks/cuda.section.md
@@ -54,3 +54,65 @@ for your specific card(s).
 
 Library maintainers should consult [NVCC Docs](https://docs.nvidia.com/cuda/cuda-compiler-driver-nvcc/)
 and release notes for their software package.
+
+## Adding a new CUDA release {#adding-a-new-cuda-release}
+
+> **WARNING**
+>
+> This section of the docs is still very much in progress. Feedback is welcome in GitHub Issues tagging @NixOS/cuda-maintainers or on [Matrix](https://matrix.to/#/#cuda:nixos.org).
+
+The CUDA Toolkit is a suite of CUDA libraries and software meant to provide a development environment for CUDA-accelerated applications. Until the release of CUDA 11.4, NVIDIA had only made the CUDA Toolkit available as a multi-gigabyte runfile installer, which we provide through the [`cudaPackages.cudatoolkit`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.cudatoolkit) attribute. From CUDA 11.4 and onwards, NVIDIA has also provided CUDA redistributables (“CUDA-redist”): individually packaged CUDA Toolkit components meant to facilitate redistribution and inclusion in downstream projects. These packages are available in the [`cudaPackages`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages) package set.
+
+All new projects should use the CUDA redistributables available in [`cudaPackages`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages) in place of [`cudaPackages.cudatoolkit`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.cudatoolkit), as they are much easier to maintain and update.
+
+### Updating CUDA redistributables {#updating-cuda-redistributables}
+
+1. Go to NVIDIA's index of CUDA redistributables: <https://developer.download.nvidia.com/compute/cuda/redist/>
+2. Copy the `redistrib_*.json` corresponding to the release to `pkgs/development/compilers/cudatoolkit/redist/manifests`.
+3. Generate the `redistrib_features_*.json` file by running:
+
+    ```bash
+    nix run github:ConnorBaker/cuda-redist-find-features -- <path to manifest>
+    ```
+
+    That command will generate the `redistrib_features_*.json` file in the same directory as the manifest.
+
+4. Include the path to the new manifest in `pkgs/development/compilers/cudatoolkit/redist/extension.nix`.
+
+### Updating the CUDA Toolkit runfile installer {#updating-the-cuda-toolkit}
+
+> **WARNING**
+>
+> While the CUDA Toolkit runfile installer is still available in Nixpkgs as the [`cudaPackages.cudatoolkit`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.cudatoolkit) attribute, its use is not recommended and should it be considered deprecated. Please migrate to the CUDA redistributables provided by the [`cudaPackages`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages) package set.
+>
+> To ensure packages relying on the CUDA Toolkit runfile installer continue to build, it will continue to be updated until a migration path is available.
+
+1. Go to NVIDIA's CUDA Toolkit runfile installer download page: <https://developer.nvidia.com/cuda-downloads>
+2. Select the appropriate OS, architecture, distribution, and version, and installer type.
+
+   - For example: Linux, x86_64, Ubuntu, 22.04, runfile (local)
+   - NOTE: Typically, we use the Ubuntu runfile. It is unclear if the runfile for other distributions will work.
+
+3. Take the link provided by the installer instructions on the webpage after selecting the installer type and get its hash by running:
+
+   ```bash
+   nix store prefetch-file --hash-type sha256 <link>
+   ```
+
+4. Update `pkgs/development/compilers/cudatoolkit/versions.toml` to include the release.
+
+### Updating the CUDA package set {#updating-the-cuda-package-set}
+
+1. Include a new `cudaPackages_<major>_<minor>` package set in `pkgs/top-level/all-packages.nix`.
+
+   - NOTE: Changing the default CUDA package set should occur in a separate PR, allowing time for additional testing.
+
+2. Successfully build the closure of the new package set, updating `pkgs/development/compilers/cudatoolkit/redist/overrides.nix` as needed. Below are some common failures:
+
+| Unable to ... | During ... | Reason | Solution | Note |
+| --- | --- | --- | --- | --- |
+| Find headers | `configurePhase` or `buildPhase` | Missing dependency on a `dev` output | Add the missing dependency | The `dev` output typically contain the headers |
+| Find libraries | `configurePhase` | Missing dependency on a `dev` output | Add the missing dependency | The `dev` output typically contain CMake configuration files |
+| Find libraries | `buildPhase` or `patchelf` | Missing dependency on a `lib` or `static` output | Add the missing dependency | The `lib` or `static` output typically contain the libraries |
+
+In the scenario you are unable to run the resulting binary: this is arguably the most complicated as it could be any combination of the previous reasons. This type of failure typically occurs when a library attempts to load or open a library it depends on that it does not declare in its `DT_NEEDED` section. As a first step, ensure that dependencies are patched with [`cudaPackages.autoAddOpenGLRunpath`](https://search.nixos.org/packages?channel=unstable&type=packages&query=cudaPackages.autoAddOpenGLRunpath). Failing that, try running the application with [`nixGL`](https://github.com/guibou/nixGL) or a similar wrapper tool. If that works, it likely means that the application is attempting to load a library that is not in the `RPATH` or `RUNPATH` of the binary.
diff --git a/nixpkgs/doc/stdenv/stdenv.chapter.md b/nixpkgs/doc/stdenv/stdenv.chapter.md
index 56843467fa4a..fe0f5daf7a07 100644
--- a/nixpkgs/doc/stdenv/stdenv.chapter.md
+++ b/nixpkgs/doc/stdenv/stdenv.chapter.md
@@ -1179,7 +1179,7 @@ someVar=$(stripHash $name)
 
 ### `wrapProgram` \<executable\> \<makeWrapperArgs\> {#fun-wrapProgram}
 
-Convenience function for `makeWrapper` that replaces `<\executable\>` with a wrapper that executes the original program. It takes all the same arguments as `makeWrapper`, except for `--inherit-argv0` (used by the `makeBinaryWrapper` implementation) and `--argv0` (used by both `makeWrapper` and `makeBinaryWrapper` wrapper implementations).
+Convenience function for `makeWrapper` that replaces `<executable>` with a wrapper that executes the original program. It takes all the same arguments as `makeWrapper`, except for `--inherit-argv0` (used by the `makeBinaryWrapper` implementation) and `--argv0` (used by both `makeWrapper` and `makeBinaryWrapper` wrapper implementations).
 
 If you will apply it multiple times, it will overwrite the wrapper file and you will end up with double wrapping, which should be avoided.