Patching with epatch

The canonical way of applying patches in ebuilds is to use epatch (from eutils.eclass, which you must make sure to import!) inside src_prepare. This function automatically handles -p levels, gunzip and so on as necessary. Also note that olds ebuild may still use src_unpack to apply patches. This is because those ebuilds are based in EAPI="1". You are advised to use EAPI="2" and apply your patches in src_prepare function instead.

Note that distributing modified tarballs rather than a vanilla tarball and patches is highly discouraged.

Basic epatch

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:

src_unpack() {
    unpack ${A}
    cd "${S}"
    epatch "${FILESDIR}/${P}-destdir.patch"
    epatch "${FILESDIR}/${P}-parallel_build.patch"
}

For larger patches, using your devspace rather than files/ is more appropriate. In these situations, it is usually best to bzip2 the patch in question (as opposed to files/ patches, which must not be compressed). For example, from app-admin/showconsole:

src_unpack() {
    unpack ${A}
    cd "${S}"
    epatch "${WORKDIR}/${P}-suse-update.patch.bz2"
    epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch"
}

As stated before, if you are using EAPI >=2, you should apply the patches in the src_prepare function

src_prepare() {
	epatch "${WORKDIR}/${P}-suse-update.patch.bz2"
	epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch"
}

Remember to add the patch to SRC_URI.

CVS Keyword Lines and Patches

If your patch includes any changes to CVS $Id: $ (or $Header: $, or $Date: $) lines, it cannot be distributed under files/, since CVS will clobber the patch when you commit. In these situations, either remove this hunk of the patch manually, or mirror the file.

Multiple Patches with epatch

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:

src_unpack() {
    unpack ${A}
    cd "${S}"
    EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \
        EPATCH_FORCE="yes" epatch
}

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

Variables which may be defined include:

Variable Purpose
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).

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.