[patch] Documentation in eclass (v1)

epatch_user-doc.patch (text/plain), 2.19 KB, created by Martin von Gagern on 2011-08-07 16:11:13 UTC

--- /usr/portage/eclass/eutils.eclass	2011-07-20 08:01:13.000000000 +0200
+++ eutils.eclass	2011-08-07 18:08:13.301740446 +0200
@@ -432,9 +432,40 @@
 	[[ ${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
@@ -447,9 +478,11 @@
 			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
 }