He's not dead, he's resting
EAPI 3: Profile Controlled IUSE Injection
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
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 in
VDB). It contains everything in
IUSE, along with profile-injected extra values.
- Any value in the profile
IUSE_IMPLICITvariable is treated as being in
IUSE_EFFECTIVE. This would let the much-abused
buildflag carry on working; it has not yet been decided whether any values will be set this way in the profile.
USE_EXPAND_UNPREFIXEDvariable whose name appears in the profile
USE_EXPAND_IMPLICITvariable is treated as having its values implicitly listed. This will probably contain
ARCHetc, but not
LINGUASet al. For any
FOO, the profile
USE_EXPAND_VALUES_FOOvariable lists its (unprefixed) implicitly injected values.
IUSE_EFFECTIVEis thus a fixed, well defined set rather than an infinite set as it is in older EAPIs. Any value that doesn’t end up in
IUSE_EFFECTIVEcannot be queried in any way, and is treated as ‘missing’ for use dependency defaults. Any value in
IUSE_EFFECTIVE, whether or not it is explicitly in
IUSE, 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
KERNEL flags and possibly things like