Blag
He's not dead, he's resting
EAPI 3: Profile Controlled IUSE Injection
April 30, 2009
Posted by on This is part of a series on EAPI 3.
EAPI 3 makes some fairly substantial changes to how use flags are handled inside the package manager. For developers, this requires a certain amount of attention; for users, there’s probably not much visible difference.
Historically, core Portage didn’t really do much with USE
flags. They were used by conditional dependency specifications, but that was it — things like the use
function were just bits of shell script that looked at the USE
variable, which mostly just came directly from the user’s configuration. Similarly, IUSE
was originally only used for cosmetic purposes — Portage used it to decide which flags to display in output, but didn’t use it to restrict USE
in any way. Thus, packages could query use flags that weren’t listed in IUSE
and still expect things to work.
USE_EXPAND
gets even more complicated. Developers often didn’t bother even trying to list such flags in IUSE
, leading to much confusion and strange behaviour.
This is a bit of a nuisance. It makes later user-facing functionality like “has this USE flag changed?” queries much harder to define, and it severely cripples use dependency defaults (was a flag not present for a given version, and thus should the default be used, or was it present but just not listed?). EAPI 3 fixes this.
In EAPI 3, IUSE
is strictly enforced. If a flag isn’t listed in IUSE
(and isn’t covered by the exceptions detailed later), the package manager will filter it from USE
and any relevant USE_EXPAND
variable, and make the use
functions die if the flag is used in a query.
The problem is, Gentoo developers don’t tend to like the idea of having to explicitly list ARCH
flags like x86
or certain USE_EXPAND
flags like userland_GNU
in IUSE
. There are two reasons given for this:
- The flags shouldn’t be user visible.
- It’s lots of effort.
The first argument is mostly invalid; we already have USE_EXPAND_HIDDEN
, and EAPI 3 is tweaking the definition of USE_EXPAND
to let us treat ARCH
as a USE_EXPAND
value that isn’t prefixed with arch_
like it otherwise would be, allowing us to hide those too.
The second argument may or may not have merit; Gentoo’s gone for the “at least keep the possibility that we’ll avoid having to make people explicitly list things open” approach (at the expense of use dependency defaults not being usable on anything that’s treated that way), whilst Exherbo’s gone for “list everything”.
Here’s (roughly — see PMS for the gory details) how the compromise works:
- The package manager works out something we’ll call
IUSE_EFFECTIVE
(which may or may not be an ebuild-visible variable, is not an ebuild-modifiable variable and which will end up inVDB
). It contains everything inIUSE
, along with profile-injected extra values. - Any value in the profile
IUSE_IMPLICIT
variable is treated as being inIUSE_EFFECTIVE
. This would let the much-abusedbuild
flag carry on working; it has not yet been decided whether any values will be set this way in the profile. - Any
USE_EXPAND
orUSE_EXPAND_UNPREFIXED
variable whose name appears in the profileUSE_EXPAND_IMPLICIT
variable is treated as having its values implicitly listed. This will probably containUSERLAND
,KERNEL
,ARCH
etc, but notLINGUAS
et al. For anyUSE_EXPAND_IMPLICIT
variableFOO
, the profileUSE_EXPAND_VALUES_FOO
variable lists its (unprefixed) implicitly injected values. IUSE_EFFECTIVE
is thus a fixed, well defined set rather than an infinite set as it is in older EAPIs. Any value that doesn’t end up inIUSE_EFFECTIVE
cannot be queried in any way, and is treated as ‘missing’ for use dependency defaults. Any value inIUSE_EFFECTIVE
, whether or not it is explicitly inIUSE
, is ‘present’ for use dependency defaults.
For developers, all you really need to know is that you need to list things in IUSE
if you want to use them, except if they’re in a small group of special values that will likely contain ARCH
, USERLAND
and KERNEL
flags and possibly things like build
.
Can IUSE_IMPLICIT be used in base/ ? Will un-aware PMs just ignore the value?
IUSE_IMPLICIT has to be set in the same way that USE_EXPAND is — that is to say, it can only be set in the base profile (and only modified after extensive discussion), and it has to be the same for everyone. There aren’t any unaware package managers for this — anyone supporting EAPI 3 has to support it, and any older EAPI must not make use of it.
By un-aware, I meant older versions. They should just ignore IUSE_IMPLICIT I guess. thx for the clarification.
Correct. For older EAPIs it’s illegal to make use of anything that’s either in IUSE or an ARCH or USE_EXPAND value.
Pingback: What’s in EAPI 3? « Ciaran McCreesh’s Blag
a question, if i may. from the look of things, i feel that eapi3 should be incorporated as soon as possible.
still, the eapi revisions are coming up much faster than gentoo can handle them (well, from outsider’s point of view anyway – portage is a huge ebuild collection after all).
is there going to be a total transition to new eapi in whole portage tree, or will it be more of an incremental process? how are gentoo devs feeling about this?
Uhm. EAPIs are coming up as slowly as Gentoo can handle them. That’s the limiting factor. And two fairly minor EAPI changes per year really isn’t very fast.
EAPIs are a purely incremental process. That’s the point of them — they remove the need for mass migrations. People will use EAPI 3 in non-system packages when they have a need to do so, and anything that doesn’t need it will remain using older EAPIs.