diff options
| author |   Thomas Bracht Laumann Jespersen <t@laumann.xyz> | 2022-03-27 22:17:34 +0200 |
|---|---|---|
| committer |   Ulrich Müller <ulm@gentoo.org> | 2022-04-06 20:40:39 +0200 |
| commit | dcb57d688530aa1af4193aaec350d6d7f571c6cf (patch) | |
| tree | 5f023940cc8309cf330f0eb036b41a1d1a051d07 /ebuild-writing | |
| parent | ebuild-writing/user-submitted: Add cross-reference to copyright policy (diff) | |
| download | devmanual-dcb57d688530aa1af4193aaec350d6d7f571c6cf.tar.gz devmanual-dcb57d688530aa1af4193aaec350d6d7f571c6cf.tar.bz2 devmanual-dcb57d688530aa1af4193aaec350d6d7f571c6cf.zip | |
ebuild-writing/patches: Add "Conditional patching" section
The added section under "Patches" tries to describe what patches are
intended for and why conditional patching should be avoided.
It was pointed out in a PR review that conditional patching in general
should be avoided as it introduces more variance and can make it harder
to debug breakage if a patch is only applied under certain conditions
(USE flags being the primary example).
Signed-off-by: Thomas Bracht Laumann Jespersen <t@laumann.xyz>
Signed-off-by: Ulrich Müller <ulm@gentoo.org>
Diffstat (limited to 'ebuild-writing')
| -rw-r--r-- | ebuild-writing/misc-files/patches/text.xml | 59 |
1 files changed, 59 insertions, 0 deletions
diff --git a/ebuild-writing/misc-files/patches/text.xml b/ebuild-writing/misc-files/patches/text.xml index 05052e6..87b4a7e 100644 --- a/ebuild-writing/misc-files/patches/text.xml +++ b/ebuild-writing/misc-files/patches/text.xml @@ -113,6 +113,65 @@ from the <c>vim</c> patch tarball: </section> <section> +<title>Conditional patching</title> +<body> + +<p> +Patching is ideally only done to make the package in question build properly, +and should not be done to modify the runtime behaviour of the package. This is +what USE flags and features of the package are for. As such, it is preferable to +apply patches unconditionally and avoid conditional patching. +</p> + +<p> +There are a number of reasons to avoid conditional patching: +</p> + +<ul> + <li> + It may go unnoticed that a patch fails to apply, if a package is not being + tested with a given flag + </li> + <li> + More variance is introduced and problems with a package can become much more + difficult to debug + </li> + <li> + Patches should preferably be upstreamed, but conditional patches cannot + </li> +</ul> + +<p> +Consider the following example <c>src_prepare()</c> implementation: +</p> + +<codesample lang="ebuild"> +src_prepare() { + if use threads; then + PATCHES+=( "${FILESDIR}"/${P}-mt.patch ) + fi + default +} +</codesample> + +<p> +As this patch is only applied when <c>USE="threads"</c> is set, any developer +creating new versions of this package might not detect whether the patch applies +successfully if they don't test with the same flag. +</p> + +<p> +Although conditional patching is discouraged it can be unavoidable and as such, +it is not considered a banned practice, but, to the extent possible, patches +should be written such that they affect behaviour correctly based on e.g. build +time definitions and configuration options rather than USE flags directly. This +allows them to be applied unconditionally. +</p> + +</body> +</section> + +<section> <title>Clean Patch Howto</title> <body> |