ebuild-writing/using-eclasses: mention sorting inherit arguments

[thesamesam]

Signed-off-by: Sam James sam@gentoo.org

[ulm]

Thinking about it, an ebuild shouldn't rely on inherit order.

Instead, in the (relatively rare?) case that there's more than one eclass exporting a phase function, the ebuild should define that phase function and call the eclass functions in a well-defined order.

[SoapGentoo]

are you going to rewrite all the multilib-minimal using ebuilds? I doubt it. Having the last eclass be the canonical one has been standard practice for a long time

[ulm]

How about something similar to the following instead?

Suggested change

	<p>
	When using <c>inherit</c>, it is best practice to sort the arguments (eclasses)
	alphabetically. An exception is where the phases exported by an eclass are
	affected by subsequent arguments. For example, <c>multilib-minimal.eclass</c>
	mentions in its
	<uri link="::eclass-reference/multilib-minimal.eclass/">documentation</uri>
	that it should be inherited last because it overrides most phases.
	</p>
	<p>
	When using <c>inherit</c>, it is best practice to sort the arguments (eclasses)
	alphabetically.
	</p>
	<important>
	Don't rely on inherit order. It can be different from what it appears to be
	because eclasses can indirectly inherit each other. If several eclasses export
	the same phase functions, the ebuild should therefore define that function
	and explicitly call the eclass functions in a well defined order.
	</important>

[SoapGentoo]

Again, disagree, noone is going to clutter multilib ebuilds like this.

[ulm]

"This eclass must always go last" is strange advice. What if more than one eclass says that?

[SoapGentoo]

The eclass won't say it, it's the use that implies where it does (even though anything overriding multilib-minimal would seem strange)

[ulm]

But it does:

# multilib-minimal should _always_ go last in inherit order!

[ulm]

For reference, the old Devrel Handbook had some wisdom about this:

Oh, and you can inherit several eclasses at the same time by saying:

inherit eclass1 eclass2 [...]

...but watch their order! Remember, eclasses can inherit one another and override each other's settings, so you should be careful when dealing with multiple eclasses that might influence one another.

[...]

Let's look at another problem for a moment. Suppose that foo.eclass and bar.eclass both define src_compile(). If you inherit both foo and bar you'll get a different src_compile() depending on the order in which you inherit them. That's ok; you're supposed to keep track of your inheritance order. But you may want to call either of the two src_compile()s explicitly.

This is still up to date, so maybe some of it could be reused?

(I also think that the last sentence from above is what I remembered as a policy, but looks like it was never an absolute requirement.)