{"id":1002,"date":"2019-11-06T08:57:52","date_gmt":"2019-11-06T07:57:52","guid":{"rendered":"https:\/\/blogs.gentoo.org\/mgorny\/?p=1002"},"modified":"2019-11-10T18:31:43","modified_gmt":"2019-11-10T17:31:43","slug":"gentoo-eclass-design-pitfalls","status":"publish","type":"post","link":"https:\/\/blogs.gentoo.org\/mgorny\/2019\/11\/06\/gentoo-eclass-design-pitfalls\/","title":{"rendered":"Gentoo eclass design pitfalls"},"content":{"rendered":"

I have written my share of eclasses, and I have made my share of mistakes. Designing good eclasses is a non-trivial problem, and there are many pitfalls you should be watching for. In this post, I would like to highlight three of them.<\/p>\n

Not all metadata variables are combined<\/h2>\n

PMS provides a convenient feature for eclass writers: cumulative handling of metadata variables. Quoting the relevant passage:<\/p>\n

The IUSE<\/kbd>, REQUIRED_USE<\/kbd>, DEPEND<\/kbd>, BDEPEND<\/kbd>, RDEPEND<\/kbd> and PDEPEND<\/kbd> variables are handled specially when set by an eclass. They must be accumulated across eclasses, appending the value set by each eclass to the resulting value after the previous one is loaded. Then the eclass-defined value is appended to that defined by the ebuild. [\u2026]<\/p>\n

Package Manager Specification (30th April 2018), 10.2 Eclass-defined Metadata Keys<\/a><\/cite><\/p><\/blockquote>\n

That’s really handy! However, the important thing that’s not obvious from this description is that not all metadata variables<\/em> work this way. The following multi-value variables don’t: HOMEPAGE<\/kbd>, SRC_URI<\/kbd>, LICENSE<\/kbd>, KEYWORDS<\/kbd>, PROPERTIES<\/kbd> and RESTRICT<\/kbd>. Surely, some of them are not supposed to be set in eclasses but e.g. the last two are confusing.<\/p>\n

This means that technically you need to append when defining them, e.g.:<\/p>\n

# my.eclass\nRESTRICT+=\" !test? ( test )\"<\/code><\/pre>\n
However, that’s not the biggest problem.  The real issue is that those variables are normally set in ebuilds after inherit<\/em>, so you actually need to make sure that all ebuilds append to them.  For example, the ebuild needs to do:<\/p>\n
# my-1.ebuild\ninherit my\nRESTRICT+=\" bindist\"<\/code><\/pre>\n
Therefore, this design is prone to mistakes at ebuild level.  I’m going to discuss an alternative solution below.<\/p>\n
Declarative vs functional<\/h2>\n
It is common to use declarative style in eclasses \u2014 create a bunch of variables that ebuilds can use to control the eclass behavior.  However, this style has two significant disadvantages.<\/p>\n
Firstly, it is prone to typos.  If someone recalls the variable name wrong, and its effects are not explicitly visible, it is very easy to commit an ebuild with a silly bug.  If the effects are visible, it can still give you some quality debugging headache.<\/p>\n
Secondly, in order to affect global scope, the variables need to be set before inherit<\/kbd>.  This is not trivially enforced, and it is easy to miss that the variable doesn’t work (or partially misbehaves) when set too late.<\/p>\n
The alternative is to use functional style, especially for affecting global scope variables.  Instead of immediately editing variables in global scope and expecting ebuilds to control the behavior via variables, give them a function to do it:<\/p>\n
# my.eclass\nmy_enable_pytest() {\n  IUSE+=\" test\"\n  RESTRICT+=\" !test? ( test )\"\n  BDEPEND+=\" test? ( dev-python\/pytest[${PYTHON_USEDEP}] )\"\n  python_test() {\n    pytest -vv || die\n  }\n}<\/code><\/pre>\n
Note that this function is evaluated in ebuild context, so all variables need appending.  Its main advantage is that it works independently of where in ebuild it’s called (but if you call it early, remember to append!), and in case of typo you get an explicit error.  Example use in ebuild:<\/p>\n
# my-1.ebuild\ninherit my\nIUSE=\"randomstuff\"\nRDEPEND=\"randomstuff? ( dev-libs\/random )\"\nmy_enable_pytest<\/code><\/pre>\n
Think what phases to export<\/h2>\n
Exporting phase functions is often a matter of convenience.  However, doing it poorly can cause ebuild writers more pain than if they weren’t exported in the first place.  An example of this is vala.eclass<\/a> as of today.  It wrongly exports dysfunctional src_prepare()<\/kbd>, and all ebuilds have to redefine it anyway.<\/p>\n
It is often a good idea to consider how your eclass is going to be used.  If there are both use cases for having the phases exported and for providing utility functions without any phases, it is probably a good idea to split the eclass in two: into -utils<\/kbd> eclass that just provides the functions, and main eclass that combines them with phase functions.  A good examples today are xdg<\/kbd> and xdg-utils<\/kbd> eclasses.<\/p>\n
When you do need to export phases, it is wortwhile to consider how different eclasses are going to be combined.  Generally, a few eclass types could be listed:<\/p>\n