epatch_user: add documentation by Martin von Gagern

diff --git a/eclass/eutils.eclass b/eclass/eutils.eclass
index 466a09fa75192f1f031c4cf20413ae0b61c664b3..d3a24ed8cad2cda8257da00e49e5e30f6a813412 100644 (file)
--- 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
 }