USE Flags

USE flags are to control optional dependencies and settings which the user may reasonably want to select. For example, app-editors/vim can optionally build with support for the ruby interpreter, and it needs dev-lang/ruby installed to do this — we use the ruby USE flag to provide this option. On the other hand, app-text/glark requires ruby no matter what, so no USE flag is used there.

No combination of USE flags should cause a package to fail to build because users can set any combination of flags.

Packages should not configure and link based upon what is available at compile time — any autodetection must be overridden. This is commonly referred to as the dependency being "automagic" - This is bad because the dependency is not detected by the package manager tools and can easily break, among other issues.

The usage of a USE flag should not control runtime dependencies when the package does not link to it. Doing so will create extra configuration for the package and re-compilation for no underlying file change on disk. This should be avoided and instead can be conveyed to the user via post install messages if needed.

Note: The status of USE flags is saved in the VDB, and their value in pkg_prerm and pkg_postrm is taken from there. This means that setting or unsetting a USE flag between merge and unmerge has no effect.

`noblah` USE Flags

Avoid noblah style USE flags. These break use.mask and cause all sorts of complications for arch developers. Here's why:

Consider a hypothetical package named 'vplayer', which plays videos. This package has optional support, via USE flags, for various sound and video output methods, various video codecs and so on.

One of vplayer's optional features is support for the 'fakemedia' codec, which is unfortunately only available as a dodgy x86 binary. We could handle this by doing something like:

RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )"

Except this is pretty nasty — what happens when an AMD64 binary is made as well? Also, users on other archs will see fakemedia listed in emerge -pv output, even though it is not actually available.

Similarly, say vplayer supports output via the ALSA codec as one option. However, ALSA isn't (or wasn't when this example was written) available on SPARC or Alpha. So we could do:

DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )"

Again, it's messy, and ALSA still shows up in the emerge -p output. Also, once ALSA starts working on SPARC, every ebuild that does this would have to be manually edited.

The solution is use.mask, which is documented in Profiles use.mask File. Each profile can have a use.mask file which can be used to forcibly disable certain USE flags on a given arch (or subarch, or subprofile). So, if the fakemedia USE flag was use.masked on every non-x86 profile, the following would be totally legal and wouldn't break anything:

RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"

Users of non-x86 would see the following when doing emerge -pv vplayer:

	[ebuild   R   ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz

To get a flag added to use.mask, ask the relevant arch team.

Local and Global USE Flags

USE flags are categorised as either local or global. A global USE flag must satisfy several criteria:

It is used by many different packages, at least 5 seems to be agreed upon.
It has a general non-specific purpose.

The second point is important. If the effect of the USE flag upon pkg-one is substantially different from the effect it has upon pkg-two, then the flag is not a suitable candidate for being made a global flag. In particular, note that if client and server USE flags are ever introduced, they can not be global USE flags for this reason.

Before introducing a new global USE flag, it must be discussed on the gentoo-dev mailing list.

USE Flag Descriptions

All USE flags must be described in either use.desc in the profiles/ directory or metadata.xml in the package's directory. See man portage or the comments in these files for an explanation of the format. Remember to keep these files sorted. The file use.local.desc is automatically generated from entries in the package's metadata.xml and may be used by tools that parse the tree. Since use.local.desc is automatically generated it must never be manually editted in the tree. See GLEP 56 for more info.

The exceptions to this are USE_EXPAND flags, which must be documented in the profiles/desc/ directory. One file per USE_EXPAND variable is required, which must contain descriptions of the possible values this variable can take. See the comments in these files for the format, and remember to keep them sorted.

Conflicting USE Flags

Occasionally, ebuilds will have conflicting USE flags for functionality. Checking for them and returning an error is not a viable solution. Instead, you must pick one of the USE flags in conflict to favour and should alert the user that a particular flag is being used instead.

One example comes from the mail-mta/msmtp ebuilds. The package can use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because GnuTLS is more featureful than OpenSSL, it is favoured:

src_compile() {
    local myconf

    if use ssl && use gnutls ; then
        myconf="${myconf} --enable-ssl --with-ssl=gnutls"
    elif use ssl && ! use gnutls ; then
        myconf="${myconf} --enable-ssl --with-ssl=openssl"
    else
        myconf="${myconf} --disable-ssl"
    fi

    econf \
        # Other stuff
        ${myconf}

    emake || die "make failed"
}

In some exceptional cases, above policy would break reverse USE dependencies. To avoid this, the ebuild can specify allowed USE flag combinations with REQUIRED_USE (available in EAPI 4). See section eapi=4 for a description of its syntax.

For example, if a package dev-libs/foo can be built with either USE="a" or USE="b" but not with both, then preferring one of the flags would break packages that depend on either dev-libs/foo[a] or dev-libs/foo[b]. Therefore, the ebuild should specify REQUIRED_USE="a? ( !b )" in this case.

Note: In order to avoid forcing users to micro-manage flags too much, REQUIRED_USE should be used sparingly. Follow the normal policy whenever it is possible to do a build that will presumably suit the user's needs.

USE_EXPAND and ARCH USE Flags

The VIDEO_CARDS, INPUT_DEVICES and LINGUAS variables are automatically expanded into USE flags. These are known as USE_EXPAND variables. If the user has LINGUAS="en fr" in make.conf, for example, then USE="linguas_en linguas_fr" will automatically be set by Portage.

The USE_EXPAND list is set in profiles/base/make.defaults as of Portage 2.0.51.20. This must not be modified without discussion on the gentoo-dev list, and it must not be modified in any subprofile.

The current architecture (e.g. x86, sparc, ppc-macos) will automatically be set as a USE flag as well. See profiles/arch.list for a full list of valid architecture keywords, and GLEP 22 for an explanation of the format.

Warning: It is a common misconception that the architecture variable is somehow related to ACCEPT_KEYWORDS. It isn't. Accepting x86 keywords on sparc, for example, won't set USE="x86". Similarly, there are no ~arch USE flags, so don't try if use ~x86.