Patching with epatch and eapply

-Patching with epatch and eapply - +Patching with eapply -

-The canonical way of applying patches in ebuilds is to -use epatch (from epatch.eclass, which you must make sure -to inherit!) inside src_prepare. This function automatically -handles -p levels, gunzip and so on as necessary. -

-Starting with EAPI=7, this function is banned and eapply must be used. +The canonical way of applying patches in ebuilds is to use the package +manager's eapply command, either by calling it explicitly, or by +assigning the PATCHES variable supported by the default +src_prepare implementation.

+ +Applying patches to the sources from the upstream tarball is strongly +preferred to distributing your own modified tarball. + +

-Beginning with EAPI=6, a new function eapply was added to apply patches -without the need for an eclass. -This function differs from epatch in several ways: +The eapply command takes one or more regular file or directory paths as +its arguments. Optionally, these can be preceded by GNU patch options.

+ +The -- delimiter indicates the end of options. This is useful if a +filename begins with a hyphen. + +

eapply will not unpack patches for you.
-The default patch level is -p1. -Other patch levels must be specified manually or the command will fail. -
-When specifying a directory, at least one file with a name ending in .patch or .diff -must exist or the command fails. Other files are ignored. -
+ If an argument is a regular file, it will be applied it in the working + directory by calling GNU patch with patch level -p1. + Specifying an explicit -pN option will override the default + patch level. +
+ For a directory, patch -p1 applies all patch files with names ending + in .diff or .patch in that directory, in POSIXbetical order + of their names. Any other files in the directory are ignored. + Again, -pN can be used to override the default patch level. + Note that eapply will not recurse into subdirectories. +

-Note that distributing modified tarballs rather than a vanilla tarball -and patches is highly discouraged. +eapply was added in EAPI 6. It differs from the previously available +epatch in several ways:

+ +

+ eapply will not unpack patches for you. +
+ The patch level is no longer detected automatically. Patch levels other + than -p1 must be specified manually. +
+ When specifying a directory, at least one file with a name ending in + .diff or .patch must exist or the command fails. +

Basic <c>eapply</c> +

-The default src_prepare function will look for a global PATCHES array to apply -a list of patches for you. +In its simplest form, eapply takes a single filename and applies that +patch. It will automatically die if the apply fails. The following is +taken from sys-libs/gpm:

+ -PATCHES=( - "${FILESDIR}/${P}-destdir.patch" - "${FILESDIR}/${P}-parallel_build.patch" -) + eapply "${FILESDIR}"/${P}-musl.patch - -

-Advanced <c>eapply</c> -

-This example shows how different patch levels can be applied: +In the following simplified example taken from www-client/firefox, +a patchset is added to SRC_URI in order to fetch and unpack it. +eapply is then called with a directory argument. It applies all patches +found in that directory:

+SRC_URI+="https://dev.gentoo.org/~larry/patchsets/${P}-patches-01.tar.xz" + src_prepare() { - eapply -p2 "${WORKDIR}/${P}-suse-update.patch" - eapply -p0 "${FILESDIR}/${PV}-no-TIOCGDEV.patch" - eapply "${FILESDIR}/${PV}-gcc-6.patch" + eapply "${WORKDIR}/firefox-patches" eapply_user } - -

- -

-Basic <c>epatch</c> -

-In its simplest form, epatch takes a single filename and -applies that patch. It will automatically die if the apply -fails. The following is taken from app-misc/detox: +The chapter gives some +guidelines about where patches should be hosted and about their formatting.

- -src_prepare() { - epatch "${FILESDIR}/${P}-destdir.patch" - epatch "${FILESDIR}/${P}-parallel_build.patch" -} - -

-For larger patches, using - -your devspace rather than - -${FILESDIR} is more appropriate. In these situations, it is -usually best to compress the patch in question with xz or -bzip2 (as opposed to ${FILESDIR} patches, which must not -be compressed). For example, from app-admin/showconsole: +The default +function will look for a global PATCHES array to apply a list of patches +for you.

-src_prepare() { - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} +PATCHES=( + # Fix install location + "${FILESDIR}/${P}-destdir.patch" + # Respect MAKEOPTS #876543 + "${FILESDIR}/${P}-parallel_build.patch" +) - -

-Remember to add the patch to SRC_URI. -

-Multiple Patches with <c>epatch</c> +Advanced <c>eapply</c>

-epatch can also apply multiple patches (which can be selectively based -upon arch) from a single directory. This can be useful if upstream -have releases that need more patches. -

- -

-A simple example: +This example shows how different patch levels can be applied:

src_prepare() { - EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ - EPATCH_FORCE="yes" epatch + eapply -p2 "${WORKDIR}/${P}-suse-update.patch" + eapply -p0 "${FILESDIR}/${PV}-no-TIOCGDEV.patch" + eapply "${FILESDIR}/${PV}-gcc-6.patch" + eapply_user } - -

-Here, one of the SRC_URI components is a tarball containing -many patches with file extension .patch. -

- -

-Variables which may be defined include: -

- - - - - - - - EPATCH_SOURCE - Specifies the directory in which epatch looks for patches. - - - EPATCH_SUFFIX - File extension for patches. - - - EPATCH_OPTS - Default options to patch. - - - EPATCH_EXCLUDE - List of patches to exclude. - - - EPATCH_FORCE - - Force epatch to apply patches even if they do not follow the - canonical naming form (set to yes). - - -

Variable	Purpose

- -

-Bulk patches should be named in the form -??_${ARCH}_foo.${EPATCH_SUFFIX}. If they are -not, EPATCH_FORCE="yes" must be set. To apply a patch on all -archs, use all for the ${ARCH} part. -