1 files changed, 136 insertions, 0 deletions
diff --git a/ebuild-writing/functions/src_prepare/eapply/text.xml b/ebuild-writing/functions/src_prepare/eapply/text.xml
new file mode 100644
index 0000000..97f4445
--- /dev/null
+++ b/ebuild-writing/functions/src_prepare/eapply/text.xml
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<guide self="ebuild-writing/functions/src_prepare/eapply/">
+<chapter>
+<title>Patching with eapply</title>
+<body>
+
+<p>
+The canonical way of applying patches in ebuilds is to use the package
+manager's <c>eapply</c> command, either by calling it explicitly, or by
+assigning the <c>PATCHES</c> variable supported by the default
+<c>src_prepare</c> implementation.
+</p>
+
+<important>
+Applying patches to the sources from the upstream tarball is <e>strongly</e>
+preferred to distributing your own modified tarball.
+</important>
+
+<p>
+The <c>eapply</c> command takes one or more regular file or directory paths as
+its arguments. Optionally, these can be preceded by GNU <c>patch</c> options.
+</p>
+
+<note>
+The <c>--</c> delimiter indicates the end of options. This is useful if a
+filename begins with a hyphen.
+</note>
+
+<ul>
+  <li>
+    If an argument is a regular file, it will be applied in the working
+    directory by calling GNU <c>patch</c> with patch level <c>-p1</c>.
+    Specifying an explicit <c>-p<e>N</e></c> option will override the default
+    patch level.
+  </li>
+  <li>
+    For a directory, <c>eapply</c> applies all patch files with names ending
+    in <c>.diff</c> or <c>.patch</c> in that directory, in POSIXbetical order
+    of their names. Any other files in the directory are ignored.
+    Again, <c>-p<e>N</e></c> can be used to override the default <c>-p1</c>
+    patch level. Note that <c>eapply</c> will not recurse into subdirectories.
+  </li>
+</ul>
+
+<p>
+<c>eapply</c> was added in EAPI 6. It differs from the previously available
+<c>epatch</c> in several ways:
+</p>
+
+<ul>
+  <li>
+    <c>eapply</c> will not unpack patches for you.
+  </li>
+  <li>
+    The patch level is no longer detected automatically. Patch levels other
+    than <c>-p1</c> must be specified manually.
+  </li>
+  <li>
+    When specifying a directory, at least one file with a name ending in
+    <c>.diff</c> or <c>.patch</c> must exist or the command fails.
+  </li>
+</ul>
+</body>
+
+<section>
+<title>Basic <c>eapply</c></title>
+<body>
+
+<p>
+In its simplest form, <c>eapply</c> takes a single filename and applies that
+patch. It will automatically <c>die</c> if the apply fails. The following is
+taken from <c>sys-libs/gpm</c>:
+</p>
+
+<codesample lang="ebuild">
+	eapply "${FILESDIR}"/${P}-musl.patch
+</codesample>
+
+<p>
+In the following simplified example taken from <c>www-client/firefox</c>,
+a patchset is added to <c>SRC_URI</c> in order to fetch and unpack it.
+<c>eapply</c> is then called with a directory argument. It applies all patches
+found in that directory:
+</p>
+
+<codesample lang="ebuild">
+SRC_URI+="https://dev.gentoo.org/~larry/patchsets/${P}-patches-01.tar.xz"
+
+src_prepare() {
+	eapply "${WORKDIR}/firefox-patches"
+	eapply_user
+}
+</codesample>
+
+<p>
+The <uri link="::ebuild-writing/misc-files/patches/"/> chapter gives some
+guidelines about where patches should be hosted and about their formatting.
+</p>
+
+<p>
+The default <c><uri link="::ebuild-writing/functions/src_prepare"/></c>
+function will look for a global PATCHES array to apply a list of patches
+for you.
+</p>
+
+<codesample lang="ebuild">
+PATCHES=(
+	# Fix install location
+	"${FILESDIR}/${P}-destdir.patch"
+	# Respect MAKEOPTS #876543
+	"${FILESDIR}/${P}-parallel_build.patch"
+)
+</codesample>
+</body>
+</section>
+
+<section>
+<title>Advanced <c>eapply</c></title>
+<body>
+
+<p>
+This example shows how different patch levels can be applied:
+</p>
+
+<codesample lang="ebuild">
+src_prepare() {
+	eapply -p2 "${WORKDIR}/${P}-suse-update.patch"
+	eapply -p0 "${FILESDIR}/${PV}-no-TIOCGDEV.patch"
+	eapply "${FILESDIR}/${PV}-gcc-6.patch"
+	eapply_user
+}
+</codesample>
+</body>
+</section>
+</chapter>
+</guide>