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.

Automagic dependencies are preferably fixed by preparing a build system patch adding appropriate options to control the dependency in question, and submitting this patch upstream for the benefit of all users. To avoid carrying additional patches downstream, automagic dependencies can usually be worked around using special build system options (e.g. cache variables in autotools) or through depending on the relevant packages unconditionally (i.e. forcing the check to always succeed).

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

When not to use USE flags?

While USE flags are generally considered beneficial to users, there are valid use cases for avoiding them. When writing ebuilds, consider whether to add flags for particular conditional features, or explore one of the alternative solutions described below.

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.

USE flags must not be used to control installing files that are small, non-intrusive, do not introduce additional build-time dependencies or cause a significant increase in build time. Examples of such files are bash completion files, init.d scripts, logrotate configuration files, systemd service files. The rationale is the same as above. Instead, those files must be installed unconditionally.

A similar case can be made for packages having multiple conditional programs or modules. Whenever this results in a large number of USE flags that would force the user to spend a lot of time choosing compatible flags and possibly rebuilding after incomplete choices, consider reducing the use of flags to those programs or modules that have external dependencies and/or long build times. The rest of them should be built unconditionally instead, or controlled by a flag such as minimal.

You should not introduce USE flags that manipulate compiler flags or similar variables configured directly by the user (e.g. -O3, -flto). Instead, packages should avoid manipulating them at all, and let users set them directly. Common mistakes include:

Using debug USE flag to force -O0 -g and disable stripping. The correct purpose of debug flag is to control additional debug code paths. The use of correct flags and features to preserve debugging information is user's responsibility.
Introducing lto flag to force -flto. This is something the user should set directly in flag variables.
Using CPU_FLAGS_* to control -m* options. Those flags are intended to control code paths explicitly requiring specific CPU extensions, e.g. separate assembly. Compiler-generated assembly should respect user's -march choice.

There might be corner cases where these rules do not apply. For example, a few upstreams require users to use specific CFLAGS and reject bug reports against builds using other values. In this case, it is customary to strip flags by default and provide custom-cflags flag to allow users to force their preferred flags. Another exception are CFLAGS that enable/disable features at compile time (via pre-processor macros).

`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.

IUSE defaults

Add + or - before the name of the use flag in IUSE to turn it on or off by default.

IUSE defaults should be used sparingly. Reasons to exclude/default-disable a feature may include e.g. large build time for a dependency, or a configuration that the Gentoo maintainer is unable to test at runtime.

The IUSE defaults for a package should not leave a package in a non-functional state or lacking important, common functionality. Consulting upstream documentation may be useful for assessing this.

Important: Adding - before a flag in IUSE is pretty much useless, as it will neither override the user configuration (make.conf) nor the profile default (make.defaults and package.use). See make.conf(5) for details on USE-ordering in Portage.

# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

EAPI=7

IUSE="+bar foo"

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_configure() {
	local myconf

	if use ssl; then
		myconf+=" --enable-ssl --with-ssl=$(usex gnutls gnutls openssl)"
	else
		myconf+=" --disable-ssl"
	fi

	econf \
		# Other stuff
		${myconf}
}

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. See section REQUIRED_USE 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 L10N variables are automatically expanded into USE flags. These are known as USE_EXPAND variables. If the user has L10N="en fr" in make.conf, for example, then USE="l10n_en l10n_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.