[gentoo-dev] some multilib-minimal enhancements [3/6]: a shitload of in-source doc

[gentoo-dev] some multilib-minimal enhancements [3/6]: a shitload of in-source doc

[Greg Turner]

[-- Attachment #1: Type: text/plain, Size: 1 bytes --]



[-- Attachment #2: 003-in-source-doc.patch --]
[-- Type: text/x-patch, Size: 5891 bytes --]

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 <hasufell@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" ;;

Re: [gentoo-dev] some multilib-minimal enhancements [3/6]: a shitload of in-source doc

[hasufell]

On 12/11/2013 10:18 PM, Greg Turner wrote:
> 


I actually feel that some parts of this is not documentation, but rather
"wiki". So maybe that's exactly where to put it?

The doc in the eclass should only describe the behavior of the eclass
and the main points you need to know in order to get it going.

But it is not a strong feeling.

> +# it is often best to put multilib-minimal first on the inherits
> list.

first? You mean last or what?

Re: [gentoo-dev] some multilib-minimal enhancements [3/6]: a shitload of in-source doc

[Greg Turner]

On Wed, Dec 11, 2013 at 2:01 PM, hasufell <hasufell@gentoo.org> wrote:
> I actually feel that some parts of this is not documentation, but rather
> "wiki". So maybe that's exactly where to put it?
>
> The doc in the eclass should only describe the behavior of the eclass
> and the main points you need to know in order to get it going.
>
> But it is not a strong feeling.

I think you're probably right... I'll endeavor to re-factor this patch
and put the wiki stuff into the wiki.

>> +# it is often best to put multilib-minimal first on the inherits
>> list.
>
> first? You mean last or what?

I definitely meant first -- the existing in-source doc said "last" but
I thought that must surely be a thinko... unless my understanding of
how inherits works is backwards -- the first, not the last, inheritee
gets the default phase-function implementations wired up to it,
correct?  I suppose another assumption I have, that, if not shared,
might be leading us to opposite conclusions, is that a majority of
inheritors would want the default phase function implementations to be
wired up to multilib-minimal...?

btw, based on the same criteria you mention above, some of what I've
said about the matter probably better belongs in the wiki rather than
the in-source doc.

-gmt

[gentoo-dev] Re: some multilib-minimal enhancements [3/6]: a shitload of in-source doc

[Jonathan Callen]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA512

On 12/11/2013 07:54 PM, Greg Turner wrote:
> On Wed, Dec 11, 2013 at 2:01 PM, hasufell <hasufell@gentoo.org> wrote:
>> I actually feel that some parts of this is not documentation, but rather "wiki". So maybe
>> that's exactly where to put it?
>> 
>> The doc in the eclass should only describe the behavior of the eclass and the main points you
>> need to know in order to get it going.
>> 
>> But it is not a strong feeling.
> 
> I think you're probably right... I'll endeavor to re-factor this patch and put the wiki stuff
> into the wiki.
> 
>>> +# it is often best to put multilib-minimal first on the inherits list.
>> 
>> first? You mean last or what?
> 
> I definitely meant first -- the existing in-source doc said "last" but I thought that must
> surely be a thinko... unless my understanding of how inherits works is backwards -- the first,
> not the last, inheritee gets the default phase-function implementations wired up to it, 
> correct?  I suppose another assumption I have, that, if not shared, might be leading us to
> opposite conclusions, is that a majority of inheritors would want the default phase function
> implementations to be wired up to multilib-minimal...?
> 
> btw, based on the same criteria you mention above, some of what I've said about the matter
> probably better belongs in the wiki rather than the in-source doc.
> 
> -gmt
> 
> 

The *last* eclass inherited that exports a particular function (via EXPORT_FUNCTIONS) is the one
that prevails, not the *first*.  Therefore, if it is expected that multilib-minimal.eclass's
versions will be used, it should be nearer the end of the inherit line, not the beginning.

- -- 
Jonathan Callen
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.22 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/

iQIcBAEBCgAGBQJSqSBrAAoJELHSF2kinlg4JcgP/2KKiXTcRkBUQmT0A5X0NLJV
TqthtEKHlQhAuc9VjVtMj+h1UhAuDxsK4tasUBlXG6b3ab3o5drXVyD+rZWJHr8N
FaqWuwSsbnIxp461DNVbQk5vhHAHY9oxFxT1rV/wjgFIK0d6yZxSBBDWWtWLbOba
ev/FRw5LqnK8JkX/YaGCo6HYNSxaSGTRdeuSlndfF5dLYXRFO5JIR98S6YtsZWFY
jXjKNcYQNVX/HAeU42LCMffgODSiCmLQPE9D5vhP9hOD9tLlBe6WZLt8iKKaBOug
rBvRaQq9lL7obivYohMqR+7MCeCcvlDc6rMu1ZEdBMEfN39lzmTiAp9wXlYpbB7Q
pM1YI97bqXGwS8lpBL6AIkS5Uep/0q1UD8bDw67PMtOrCh5Oi/SniCY8pdZCqpms
bFYp+MgtYtvopI+vtn1P7/P4LBv9LspReQ7lVV4ukKSkuqx7L4B3Az3fiHcTV8ce
XCzbSkR4ZOwvAypXtMRhmfcpIchVegqLwUIZHVRkUH9Qwd+o4dvpmBIxkUVdqFJD
OINNplQ1/WqxJdonkFVzWUAO1jE67M91uf3zcimB63ioNKwSQGalVGQt3Rp1RfCd
eJgsgkmtvI8fqhnkZTO+i70Xl89+JXhz+R4tfMewTId4wch+w3EiX3PKJUbF9rWK
P6tuUW0eRNp6t7SU2ZdY
=WMyy
-----END PGP SIGNATURE-----

Re: [gentoo-dev] Re: some multilib-minimal enhancements [3/6]: a shitload of in-source doc

[Greg Turner]

On Wed, Dec 11, 2013 at 6:33 PM, Jonathan Callen <jcallen@gentoo.org> wrote:
> The *last* eclass inherited

Well I'll be ferschnookered!

Googling confirms this.  I'm quite shocked.  I have believed the
opposite, for a very long time, with perfect confidence.  No idea why
I thought so -- in retrospect, I'm pretty sure I was aware that they
were sourced in order -- so why would the phase function overrides act
in an entirely opposite pattern?  Some stupid aislexydic thinko, years
ago, no doubt.  Good catch, Julian!

I'll fix it when I rev this patch series.

-gmt