/etc/portage/patches

User patches provide a way for users to apply patches to ebuilds. This is useful for the rare cases of site-specific patches, but also for testing patches before sending them to upstream or to the Gentoo bug tracker. The feature is provided by many ebuilds prior to EAPI=6, either by calling  explicitly or by inheriting an eclass and relying on its default implementation of. Starting with EAPI=6,, the EAPI=6 replacement for  , is required in all   phases. Current Gentoo policy does not require ebuilds to use  in EAPIs before EAPI=6, its usage is at the package maintainer's discretion. But there is also a way to enable it for all ebuilds that don't explicitly allow user patching.

Enabling /etc/portage/patches for all ebuilds
If an ebuild does not call, but user patches are still needed to be applied, it is possible to use /etc/portage/bashrc and hooks provided by Portage. Candidates are,   or. The first two have the advantage of being run before  (or similar) and the last two have the advantage of being run in the right directory, so only   shares those advantages.

Normally only ebuilds inheriting  can access , so one would need to test for its presence and non-eutils ebuilds would not get patched at all. There is a trick of pulling in only the necessary bits from, running  and dropping them.

With  and the above trick, changing directories do not need to be played with, all ebuilds can be supported whether they import   or not, and the patches will applied as soon as possible in the chain. While it might still be better to have this feature as part of Portage, the following snippet should cover everyday needs pretty well.

Adding user patches
First choose the location for the patches, depending on the package name and the version(s) it is intended for. Use the following locations and optionally append  to any of them:



Examples:



The next example shows a very simple patch for of.

The package that needs a patch will be unpacked using the command:

Any for the user patch needs to refer to the just created directory, so cd into it:

Say were the file to be changed. So it should be copied to (or somwere else):

After having modified the copy, check the :

Of course, still the directory for the patch needs to be created:

Now the directory is ready drop in the patches. Only files with suffix are considered and they are applied in the order determined by their name.

Repeat the and create the patch file:

It is imporant that the first line of the file refers to the directory created by unpacking.

Note that  attempts to apply them repeatedly with a prefix stripped up to a different number of slashes.

Using a git directory as a source of patches
Instead of creating the directory, a symlink can be created to a git directory on the system.

Now, in the git directory, perform the usual work. After finishing remove all patches from the previous run and use git format-patch to create a patchset from the branch based on another known branch.

This solution relies on the fact that only files ending with are processed in the patch directory.

Adding support for user patches to ebuilds
It is up to the maintainer of the ebuild to decide when exactly  is called. It would typically be in  together with patches specified in the ebuild itself and the build system actions like. To best accommodate user patches that would later be suitable for submitting upstream, it should be the very first action. Note that without changing the ebuild, the user can only force it to be called earlier, not later.

As a maintainer, often  is provided for free by inheriting an eclass. Then it can either be forced to run earlier or the eclass can be relied upon to do the work. For example, calls   after applying other patches in its implementation of.

When the ebuild ends up calling  multiple times (e.g. because the maintainer called it explicitly but also used an eclass that calls it), the first call creates  and subsequent calls have no effect.

In EAPI=6, the default src_prepare calls, and all src_prepare phases written by a maintainer must call  , either directly, through calling  , or by inheriting and using the   phase of an EAPI=6 compatible eclass.

External resources

 * eutils.eclass: Disable epatch_user in EAPI 6. - EAPI 6 has eapply_user which should be used instead.
 * The Ultimate Guide to EAPI 6
 * Patching with epatch - Patching within ebuilds, from devmanual.gentoo.org