noblah USE Flags

If at all possible, 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.
• It has a general non-specific purpose.

The second point is important. If the effect of the thing USE flag upon pkg-one is substantially different from the effect it has upon pkg-two, then thing 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 or use.local.desc in the profiles/ directory. See man portage or the comments in these files for an explanation of the format. Remember to keep these files sorted.

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.

One example comes from the 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} \
        || die "configure failed"

    emake || die "make failed"
}

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