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 # @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_ (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_ 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_ 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_ 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_ 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_ 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" ;;