This rewrites the multilib-minimal.eclass in-source documentation,
providing considerably more hand-holding for end-users, exploring
some pitfalls that users may encounter, and clarifying some
less-than lucid language.
It also reverses an existing in-source comment about inheritance
ordering, which, I presume, was a thinko, and provides some
background about why it matters.
--- 002-MULTILIB_INSECURE_INSTALL/multilib-minimal.eclass 2013-12-03 02:23:06.888008751 -0800
+++ 003-in-source-doc/multilib-minimal.eclass 2013-12-03 02:45:19.428664959 -0800
@@ -7,23 +7,102 @@
# Julian Ospald <hasuf...@gentoo.org>
# @BLURB: wrapper for multilib builds providing convenient multilib_src_* functions
# @DESCRIPTION:
+# multilib-minimal implements src_configure, src_compile, src_test
+# and src_install, and invokes callbacks which may be used by multi-abi
+# ebuilds and eclasses to cleanly separate per-ABI and global logic
+# within their implementations. It also provides logic to ensure that
+# ABI's do not scribble over each other's header files during installation.
#
-# src_configure, src_compile, src_test and src_install are exported.
+# To use multilib-minimal.eclass, inherit from it normally and implement
+# functions named multilib_<phase> (i.e.: multilib_src_install) containing
+# code which must run once for each ABI. multilib-minimal will invoke your
+# callback repeatedly and automatically, once for each active ABI,
+# with essential abi-specific settings for variables such as CFLAGS
+# automatically exported.
#
-# Use multilib_src_* instead of src_* which runs this phase for
-# all enabled ABIs.
+# Be advised that, for now at least, some features of
+# toolchain-funcs.eclass, specifically, those that
+# retrieve those same variables, will not work as expected, as this
+# eclass knows nothing about multilib-minimal and will return values
+# suitable only for the native ABI.
#
-# multilib-minimal should _always_ go last in inherit order!
+# A simple workaround for this limitation is to check if a variable is
+# already defined before querying toolchain-funcs. For example:
+#
+# @CODE@
+# local CC=${CC:-$(tc-getCC)}
+# @CODE
+#
+# It is also important to make sure that your ebuild or eclass's dependencies
+# correctly reflect build- and run-time dependencies of each active ABI.
+# This can be simplified by using the ${MULTILIB_USEDEP} variable during
+# construction of *DEPEND variables. Note that not all dependencies
+# will require this; a judgement call will need to be made for each
+# dependency when porting existing ebuilds. See:
+# @CODE@
+# http://devmanual.gentoo.org/eclass-reference/multilib-build.eclass/index.html
+# @CODE@
+# for more information.
+#
+# Another snag you may encounter is that, in many circumstances, it is possible
+# for variables to flow between multilib_<phase> functions. This is because
+# no subshell is utilized.
+# Extreme care must sometimes be taken to ensure that different ABI's don't
+# trample each other's variables.
+#
+# A reasonable precaution against this type of problem would be to localize
+# certian variables to the multilib_<phase> function, for example:
+#
+# @CODE@
+# multilib_src_configure() {
+# local CFLAGS="${CFLAGS}" CXXFLAGS="${CXXFLAGS}"
+# local FFLAGS="${FFLAGS}" FCFLAGS="${FCFLAGS}"
+# if [[ ${CHOST} == *x86_64* ]] ; then
+# append-flags -foo_flag -bar_flag
+# fi
+# @CODE@
+#
+# However, this approach can create subtly confusing behavior. When porting
+# traditional phase-function-based code to multilib minimal, keep an eye out
+# for code that assumes variables defined in a prior phase function will persist
+# in subsequent phases. Depending on a number of factors, this may not
+# be the case -- it certainly will not, if you have localized variables as above.
+#
+# Eventually, a feature allowing reliable automatic variable persistence across
+# multilib_<phase> functions may be added, so, for the moment, it is best to
+# avoid any assumption about variable persistence, for example, by isolating
+# variable setup code in a convenience function which is invoked at the outset
+# of each multilib_<phase> function, or, where possible, by refactoring code
+# to avoid the use of persistent variables entirely.
#
# If you want to use in-source builds, then you must run
-# multilib_copy_sources at the end of src_prepare!
-# Also make sure to set correct variables such as
+# multilib_copy_sources at the end of src_prepare.
+# Also make sure to correctly set ECONF_SOURCE, i.e.,
+#
+# @CODE@
# ECONF_SOURCE=${S}
+# @CODE@
#
-# If you need generic install rules, use multilib_src_install_all function.
-
+# as out-of-tree builds will not be building in the same directory as
+# the configure script.
+#
+# EAPI >= 4 is required by multilib minimial, as without it,
+# the ${MULTILIB_USEDEP} variable cannot be correctly implemented.
+#
+# Note: inheritance order matters when inheriting from multiple
+# eclasses. In particular, it is important to understand that the
+# first inherited eclass on the list is the one whose phase
+# functions get wired up to the defaults; if it does not provide
+# an implementation, then the next (in a depthwise-recursive manner) is
+# afforded the opportunity, and so-forth, down the line. Therefore,
+# if you inherit both from a framework eclass and multilib-minimal,
+# and multilib-minimal comes after the framework eclass on the
+# inheritance list, you will get the framework eclass phase-function
+# implementations, if present, possibly making your inheritance
+# from multilib-minimal, and any implementations of the
+# multilib_<phase> callbacks, into a noop. For this reason,
+# it is often best to put multilib-minimal first on the inherits list.
-# EAPI=4 is required for meaningful MULTILIB_USEDEP.
case ${EAPI:-0} in
4|5) ;;
*) die "EAPI=${EAPI} is not supported" ;;
