Gentoo USE Flags: Design, Boundaries, and Operational Checks

The problem and the useful takeaway

When you install a package on Gentoo, Portage compiles it from source. That build may include optional features you do not need, such as Bluetooth support in a media player or documentation in a server. It may also omit features you require, such as encryption in a network tool. The useful takeaway is that USE flags are Portage's compile-time switches for these optional capabilities. Set defaults globally in /etc/portage/make.conf, override per package in /etc/portage/package.use, verify with emerge --info and equery uses, and preview changes with emerge --pretend before rebuilding.

Requirements

A workable USE flag design needs four things. First, a single place for system-wide default build options. Second, a way to exempt individual packages from that default without editing ebuilds. Third, visibility into the effective flag set before a build starts. Fourth, a trust boundary that stops unprivileged users from injecting build-time behavior into packages they do not own.

Smallest suitable design

The smallest design uses two configuration locations. The file /etc/portage/make.conf holds the global USE variable. The directory /etc/portage/package.use/ or a single file at /etc/portage/package.use holds per-package exceptions. Environment variables can override flags for one emerge invocation, but Portage's sandbox strips user-controlled environment during build phases.

Example configuration

# /etc/portage/make.conf
USE="ssl unicode zlib"

# /etc/portage/package.use/curl
net-misc/curl ssl -gnutls

The minus sign before gnutls disables that flag for curl only. The global ssl setting applies unless a more specific rule overrides it.

Trust and data boundaries

Only root can modify /etc/portage/make.conf and /etc/portage/package.use. Unprivileged users may set environment variables such as USE="..." before running emerge, but Portage removes those variables inside the sandboxed build. When emerge resolves dependencies, it adds the selected flags to the ebuild's IUSE list. IUSE is the metadata field that lists which optional features a package recognizes. Selected flags trigger conditional dependencies and adjust the src_configure, src_compile, and src_install phases of the build.

Operational checks

1. Run emerge --info | grep '^USE' as root or a regular user to display the effective USE flags.
2. Run emerge --pretend --verbose net-misc/curl as root to see what would be built. The output lists packages and the USE flags Portage will apply.
3. Install app-portage/gentoolkit, then run equery uses net-misc/curl to confirm which flags influence that package's dependencies.

Concrete diagnostic example

Suppose you want SSL support in net-misc/curl. Confirm ssl appears in the global USE variable, then run as root:

emerge --pretend --verbose net-misc/curl

Expected check: the output should list net-misc/curl with ssl in its effective USE flags, and it should pull in a provider such as dev-libs/openssl as a dependency. After installation, run equery uses net-misc/curl to verify ssl is recognized. If you also have -ssl or nossl in effect, Portage may report a use conflict or build curl without SSL.

Risk: changing a global flag can trigger rebuilds of many installed packages because dependencies shift. Always review the pretend output before removing the --pretend flag.

Failure modes

• Conflicting flags: enabling both X and noX, or ssl and -ssl in conflicting scopes, creates unresolved use conflicts.
• Missing dependencies: enabling a flag pulls in a library that is not installed. emerge attempts to install it, increasing build time and disk use.
• Sandbox violations: if a flag causes the build to access disallowed paths, Portage blocks the operation and the package fails.
• Silent feature loss: disabling ssl on a network tool removes runtime protection without an obvious build error.

Limitations and how to check the result

USE flags are compile-time. Changing a flag requires rebuilding the affected package and any reverse dependencies that depend on the changed capability. Binary packages fetched with --getbinpkg may have been built with different flags and can mismatch local expectations. Not every package defines every flag; equery uses shows only recognized flags.

Practical verification: before editing make.conf, run emerge --info | grep '^USE' and save the output. After editing, run the same command and compare. Then run emerge --pretend --verbose --update --deep --newuse @world to see which installed packages would be rebuilt. This command is read-only while --pretend is present.

Rollback

Editing make.conf or package.use changes system state. To roll back, restore the previous file from a backup, then run emerge --pretend --verbose --update --deep --newuse @world to confirm the package set returns to the previous expectation. If packages were already rebuilt with unwanted flags, rebuild them again after restoring the flags.

Conditions that would change the design

• Switching to Gentoo binary packages or another distribution removes compile-time USE control.
• Strict reproducibility requirements may disable optional compile-time features or pin flags globally.
• Moving to a package manager without conditional compilation means replacing USE with post-install configuration or container image variants.