When you are installing Gentoo (or any other distribution, or even operating
system for that matter) you make choices depending on the environment you are
working with. A setup for a server differs from a setup for a workstation.
A gaming workstation differs from a 3D rendering workstation.

This is not only true for choosing what packages you want to install, but also
what features a certain package should support. If you don't need OpenGL, why
would you bother installing OpenGL and build OpenGL support in most of your
packages? If you don't want to use KDE, why would you bother compiling packages
with KDE-support if those packages work flawlessly without?

To help users in deciding what to install/activate and what not, we wanted the
user to specify his environment in an easy way. This forces the user into
deciding what he really wants and eases the process for Portage, our package
managment system, to make useful decisions.

Definition of a USE-flag

Enter the USE-flags. Such a flag is a keyword that embodies support and
dependency-information for a certain concept. If you define a certain USE-flag,
Portage will know that you want support for the chosen keyword. Of course
this also alters the dependency information for a package.

Let us take a look at a specific example: the kde keyword. If you do not
have this keyword in your USE variable, all packages that have
optional KDE support will be compiled without KDE support. All
packages that have an optional KDE dependency will be installed
without installing the KDE libraries (as dependency). If you have defined
the kde keyword, then those packages will be compiled with KDE
support, and the KDE libraries will be installed as dependency.

By correctly defining the keywords you will receive a system tailored
specifically to your needs.

What USE-flags exist?

There are two types of USE-flags: global and local USE-flags.

A global USE-flag is used by several packages, system-wide. This is
what most people see as USE-flags.

A local USE-fag is used by a single package to make package-specific
decisions.

A list of available global USE-flags can be found online or locally in
/usr/portage/profiles/use.desc. A short (very incomplete)
snippet:

gtk - Adds support for x11-libs/gtk+ (The GIMP Toolkit)
gtk2 - Use gtk+-2.0.0 over gtk+-1.2 in cases where a program supports both.
gtkhtml - Adds support for gnome-extra/gtkhtml
guile - Adds support for dev-util/guile (interpreter for Scheme)
icc - Use the Intel C++ Compiler if the package supports it
icc-pgo - Enable PGO data generation or use when use icc.
imap - Adds support for IMAP

Using USE-flagsDeclare permanent USE-flags

In the hope you are convinced of the importance of USE-flags we will now inform
you how to declare USE-flags.

As previously mentioned, all USE-flags are declared inside the USE
variable. To make it easy for users to search and pick USE-flags, we already
provide a default USE setting. This setting is a collection of USE-flags
we think are commonly used by the Gentoo users. This default setting is declared
in the /etc/make.profile/make.defaults file. Let us take a look at
this default setting:

As you can see, this variable already contains quite a lot of keywords. Do
not alter the /etc/make.profile/make.defaults file to tailor
the USE variable to your needs: changes in this file will be undone when
you update Portage!

To change this default setting, you need to add or remove keywords to the
USE variable. This is done globally by defining the USE variable
in /etc/make.conf. In this variable you add the extra USE-flags you
require, or remove the USE-flags you don't want. This latter is done by
prefixing the keyword with the minus-sign ("-").

For instance, to remove support for KDE and QT but add support for ldap, the
following USE can be defined in /etc/make.conf:

USE="-kde -qt ldap"

Declare temporary USE-flags

Sometimes you want to set a certain USE-setting only once. Instead of editing
/etc/make.conf twice (to do and undo the USE-changes) you can just
declare the USE-variable as environment variable.

As an example we will temporarily remove java from the USE-setting
during the installation of mozilla.

The emerge command will be discussed more thoroughly in Portage and Software.

# USE="-java" emerge mozilla

Inheriting USE-flags

Some packages don't only listen to USE-flags, but also provide USE-flags. When
you install such a package, the USE-flag they provide is added to your USE
setting. To view the list of packages that provide a USE-flag, check
/etc/make.profile/use.defaults:

Of course there is a certain precendence on what setting has priority over the
USE setting. You don't want to declare USE="-java" only to see that
java is declared anyway. The precedence for the USE setting is, ordered
by priority (first has lowest priority):

Default USE setting declared in /etc/make.profile/make.defaults

Inherited USE setting if a package from
/etc/make.profile/use.defaults is installed

User-defined USE setting in /etc/make.conf

User-defined USE setting as environment variable

To view the final USE setting as seen by Portage, run emerge info.
This will list all relevant variables (including the USE variable) with
the content used by Portage.

# emerge info

Package specific USE-flagsViewing available USE-flags

In the next chapter on Portage and Software
we will explain how to manage your installed software and how to work with
emerge. However, we will give you a primer on emerge by showing
you how to view what USE-flags a package uses.

Let us take the example of mozilla: what USE-flags does it listen to? To
find out, we use emerge with the --pretend (don't really do
anything) and --verbose (give more output) options: