diff --git a/doc/builders/fetchers.chapter.md b/doc/builders/fetchers.chapter.md index 4d4f3f427cd4..d434806aa9b2 100644 --- a/doc/builders/fetchers.chapter.md +++ b/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: +- `name` 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 in +the very long-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`.