stdenv: add applyPatches and support patch directories

doc/build-helpers/trivial-build-helpers.chapter.md

@@ -156,6 +156,44 @@ runCommandWith {
 ```
 :::
 
+## `applyPatches` {#trivial-builder-applyPatches}
+
+Applies a list of patches to a source directory like [`patchPhase`](#ssec-patch-phase).
+
+`src :: Path | Derivation`
+:   The path to the source directory to patch.
+
+`name :: String` (optional)
+:   The name that Nix will append to the store path in the same way that
+    `stdenv.mkDerivation` uses its `name` attribute. If not set, default is
+    computed from the [basename](https://nixos.org/manual/nix/stable/language/builtins.html#builtins-baseNameOf)
+    of the `src` if it is a path or `src.name` if `src` has `name` attribute.
+
+`patches :: [Path | Derivation]`
+:   The list of patches to apply like [`patches`](#var-stdenv-patches) argument
+    of `stdenv.mkDerivation`.
+
+`prePatch :: String` (optional)
+:   Shell commands to run before applying patches.
+
+`postPatch :: String` (optional)
+:   Shell commands to run after applying patches.
+
+::: {.example #ex-applypatches-nixpkgs}
+# Patching Nixpkgs with `applyPatches`
+
+```nix
+applyPatches {
+  src = pkgs.path;
+  patches = [
+    (pkgs.fetchpatch {
+      url = "https://github.com/NixOS/nixpkgs/commit/1f770d20550a413e508e081ddc08464e9d08ba3d.patch";
+      hash = "sha256-uXrn1hWfI72QQ8oSTOUps9UZwqF2QwzmkiMPH07on9o=";
+    })
+  ];
+}
+```
+:::
 
 ## Writing text files {#trivial-builder-text-writing}
 

doc/stdenv/stdenv.chapter.md

@@ -610,7 +610,7 @@ The unpack phase evaluates the string `$unpackCmd` for any unrecognised file. Th
 
 ### The patch phase {#ssec-patch-phase}
 
-The patch phase applies the list of patches defined in the `patches` variable.
+The patch phase applies the list of patches defined in the `patches` variable using the [`applyPatches`](#fun-applyPatches) function.
 
 #### Variables controlling the patch phase {#variables-controlling-the-patch-phase}
 
@@ -620,7 +620,7 @@ Set to true to skip the patch phase.
 
 ##### `patches` {#var-stdenv-patches}
 
-The list of patches. They must be in the format accepted by the `patch` command, and may optionally be compressed using `gzip` (`.gz`), `bzip2` (`.bz2`) or `xz` (`.xz`).
+The list of patches. They must be in the format accepted by the `patch` command, and may optionally be compressed using `gzip` (`.gz`), `bzip2` (`.bz2`) or `xz` (`.xz`, `.lzma`).
 
 ##### `patchFlags` {#var-stdenv-patchFlags}
 
@@ -1136,6 +1136,29 @@ Example removing all references to the compiler in the output:
 }
 ```
 
+### `applyPatches` [ `-p` \<patch-set\> ... ] [--] [ \<additional-arguments\> ... ] {#fun-applyPatches}
+
+Applies a set of patches to the current directory. Patch files are automatically
+decompressed using `gzip` (`.gz`), `bzip2` (`.bz2`) or `xz` (`.xz`, `.lzma`)
+based on the file name extension. Additional arguments are passed directly to
+the `patch` command.
+
+A patch set is either a path to an individual patch file or a directory containing
+multiple patch files. If a directory contains a `series` file, it is treated as
+a list of patch files to apply. The `series` file lists patch file paths, one
+per line, relative to the patch set directory. Empty lines and comments (lines
+starting with `#`) are ignored. It is an error if a line starts with either `-`
+or `+`.
+
+When processing a directory without a `series` file, only files with standard
+patch extensions `.patch` and `.diff` will be considered for application,
+optionally with compressed file name extension (e.g. `.patch.gz`).
+
+Example:
+```shell
+applyPatches -p patches -- -p1
+```
+
 ### `substitute` \<infile\> \<outfile\> \<subs\> {#fun-substitute}
 
 Performs string substitution on the contents of \<infile\>, writing the result to \<outfile\>. The substitutions in \<subs\> are of the following form:

pkgs/build-support/trivial-builders/default.nix

@@ -828,24 +828,8 @@ rec {
   */
   copyPathsToStore = builtins.map copyPathToStore;
 
-  # TODO: move applyPatches docs to the Nixpkgs manual
-  /* Applies a list of patches to a source directory.
-
-    Example:
-
-    # Patching nixpkgs:
-
-    applyPatches {
-      src = pkgs.path;
-      patches = [
-        (pkgs.fetchpatch {
-          url = "https://github.com/NixOS/nixpkgs/commit/1f770d20550a413e508e081ddc08464e9d08ba3d.patch";
-          sha256 = "1nlzx171y3r3jbk0qhvnl711kmdk57jlq4na8f8bs8wz2pbffymr";
-        })
-      ];
-    }
-
-   */
+  # Docs in doc/build-helpers/trivial-build-helpers.chapter.md
+  # See https://nixos.org/manual/nixpkgs/unstable/#trivial-builder-applyPatches
   applyPatches =
     { src
     , name ? (if builtins.typeOf src == "path"