epatch_user: add documentation by Martin von Gagern

1 files changed, 34 insertions, 1 deletions

diff --git a/eclass/eutils.eclass b/eclass/eutils.eclass
index 466a09fa7519..d3a24ed8cad2 100644
--- a/eclass/eutils.eclass
+++ b/eclass/eutils.eclass
@@ -1,6 +1,6 @@
 # Copyright 1999-2011 Gentoo Foundation
 # Distributed under the terms of the GNU General Public License v2
-# $Header: /var/cvsroot/gentoo-x86/eclass/eutils.eclass,v 1.360 2011/08/07 23:35:28 vapier Exp $
+# $Header: /var/cvsroot/gentoo-x86/eclass/eutils.eclass,v 1.361 2011/08/08 02:01:40 vapier Exp $
 
 # @ECLASS: eutils.eclass
 # @MAINTAINER:
@@ -441,9 +441,40 @@ epatch() {
 	[[ ${SINGLE_PATCH} == "no" ]] && einfo "Done with patching"
 	: # everything worked
 }
+
+# @FUNCTION: epatch_user
+# @USAGE:
+# @DESCRIPTION:
+# Applies user-provided patches to the source tree. The patches are
+# taken from /etc/portage/patches/<CATEGORY>/<PF|P|PN>/, where the first
+# of these three directories to exist will be the one to use, ignoring
+# any more general directories which might exist as well.
+#
+# User patches are intended for quick testing of patches without ebuild
+# modifications, as well as for permanent customizations a user might
+# desire. Obviously, there can be no official support for arbitrarily
+# patched ebuilds. So whenever a build log in a bug report mentions that
+# user patches were applied, the user should be asked to reproduce the
+# problem without these.
+#
+# Not all ebuilds do call this function, so placing patches in the
+# stated directory might or might not work, depending on the package and
+# the eclasses it inherits and uses. It is safe to call the function
+# repeatedly, so it is always possible to add a call at the ebuild
+# level. The first call is the time when the patches will be
+# applied.
+#
+# Ideally, this function should be called after gentoo-specific patches
+# have been applied, so that their code can be modified as well, but
+# before calls to e.g. eautoreconf, as the user patches might affect
+# autotool input files as well.
 epatch_user() {
 	[[ $# -ne 0 ]] && die "epatch_user takes no options"
 
+	# Allow multiple calls to this function; ignore all but the first
+	local applied="${T}/epach_user.applied"
+	[[ -e ${applied} ]] && return 2
+
 	# don't clobber any EPATCH vars that the parent might want
 	local EPATCH_SOURCE check base=${PORTAGE_CONFIGROOT%/}/etc/portage/patches
 	for check in {${CATEGORY}/${PF},${CATEGORY}/${P},${CATEGORY}/${PN}}; do
@@ -456,9 +487,11 @@ epatch_user() {
 			EPATCH_FORCE="yes" \
 			EPATCH_MULTI_MSG="Applying user patches from ${EPATCH_SOURCE} ..." \
 			epatch
+			echo "${EPATCH_SOURCE}" > "${applied}"
 			return 0
 		fi
 	done
+	echo "none" > "${applied}"
 	return 1
 }