This handbook has been replaced by a newer version and is not maintained anymore.
[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
2. USE flags
2.a. What are USE flags?
The ideas behind USE flags
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/her environment in an easy way. This forces the user into
deciding what they really want and eases the process for Portage, our package
management 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 flag is used by a single package to make package-specific
A list of available global USE flags can be found online or locally in
A list of available local USE flags can be found locally in
2.b. Using USE flags
Declare 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 make.defaults files part of your profile.
The profile your system listens to is pointed to by the
/etc/portage/make.profile symlink. Each profile works on top of
another, larger profile, the end result is therefore the sum of all profiles.
The top profile is the base profile
Let us take a look at this default setting for the 13.0 profile:
Code Listing 2.1: Cumulative make.defaults USE variable for the 13.0 profile
USE="a52 aac acpi alsa branding cairo cdr dbus dts dvd dvdr emboss encode exif
fam firefox flac gif gpm gtk hal jpeg lcms ldap libnotify mad mikmod mng mp3
mp4 mpeg ogg opengl pango pdf png ppds qt3support qt4 sdl spell
startup-notification svg tiff truetype vorbis unicode usb X xcb x264 xml xv
As you can see, this variable already contains quite a lot of keywords. Do
not alter any 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/portage/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/portage/make.conf:
Code Listing 2.2: An example USE setting in /etc/portage/make.conf
USE="-kde -qt4 ldap"
Declaring USE flags for individual packages
Sometimes you want to declare a certain USE flag for one (or a couple) of
applications but not system-wide. To accomplish this, you will need to create
the /etc/portage directory (if it doesn't exist yet) and edit
/etc/portage/package.use. This is usually a single file, but can
also be a directory; see man portage for more information. The following
examples assume package.use is a single file.
For instance, if you don't want berkdb support globally but you do want
it for mysql, you would add:
Code Listing 2.3: /etc/portage/package.use example
You can of course also explicitly disable USE flags for a certain
application. For instance, if you don't want java support in PHP:
Code Listing 2.4: /etc/portage/package.use 2nd example
Declare temporary USE flags
Sometimes you want to set a certain USE setting only once. Instead of editing
/etc/portage/make.conf twice (to do and undo the USE changes) you
can just declare the USE variable as environment variable. Remember that, when
you re-emerge or update this application (either explicitly or as part of a
system update) your changes will be lost!
As an example we will temporarily remove java from the USE setting
during the installation of seamonkey.
Code Listing 2.5: Using USE as environment variable
# USE="-java" emerge seamonkey
Of course there is a certain precedence on what setting has priority over the
USE setting. You don't want to declare USE="-java" only to see that
java is still used due to a setting that has a higher priority.
The precedence for the USE setting is, ordered
by priority (first has lowest priority):
Default USE setting declared in the make.defaults files part of
User-defined USE setting in /etc/portage/make.conf
User-defined USE setting in /etc/portage/package.use
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.
Code Listing 2.6: Running emerge --info
# emerge --info
Adapting your Entire System to New USE Flags
If you have altered your USE flags and you wish to update your entire system to
use the new USE flags, use emerge's --newuse option:
Code Listing 2.7: Rebuilding your entire system
# emerge --update --deep --newuse world
Next, run Portage's depclean to remove the conditional dependencies that
were emerged on your "old" system but that have been obsoleted by the new USE
Running emerge --depclean is a dangerous operation and should be handled
with care. Double-check the provided list of "obsoleted" packages to make sure
it doesn't remove packages you need. In the following example we add the
-p switch to have depclean only list the packages without removing them.
Code Listing 2.8: Removing obsoleted packages
# emerge -p --depclean
When depclean has finished, run revdep-rebuild to rebuild the
applications that are dynamically linked against shared objects provided by
possibly removed packages. revdep-rebuild is part of the
gentoolkit package; don't forget to emerge it first.
Code Listing 2.9: Running revdep-rebuild
When all this is accomplished, your system is using the new USE flag settings.
2.c. Package specific USE flags
Viewing available USE flags
Let us take the example of seamonkey: what USE flags does it listen to? To
find out, we use emerge with the --pretend and --verbose
Code Listing 3.1: Viewing the used USE flags
# emerge --pretend --verbose seamonkey
These are the packages that I would merge, in order:
Calculating dependencies ...done!
[ebuild R ] www-client/seamonkey-1.0.7 USE="crypt gnome java -debug -ipv6
-ldap -mozcalendar -mozdevelop -moznocompose -moznoirc -moznomail -moznopango
-moznoroaming -postgres -xinerama -xprint" 0 kB
emerge isn't the only tool for this job. In fact, we have a tool
dedicated to package information called equery which resides in the
gentoolkit package. First, install gentoolkit:
Code Listing 3.2: Installing gentoolkit
# emerge gentoolkit
Now run equery with the uses argument to view the USE flags of a
certain package. For instance, for the gnumeric package:
Code Listing 3.3: Using equery to view used USE flags
# equery --nocolor uses =gnumeric-1.6.3 -a
[ Searching for packages matching =gnumeric-1.6.3... ]
[ Colour Code : set unset ]
[ Legend : Left column (U) - USE flags from make.conf ]
[ : Right column (I) - USE flags packages was installed with ]
[ Found these USE variables for app-office/gnumeric-1.6.3 ]
- - debug : Enable extra debug codepaths, like asserts and extra output.
If you want to get meaningful backtraces see
+ + gnome : Adds GNOME support
+ + python : Adds support/bindings for the Python language
- - static : !!do not set this during bootstrap!! Causes binaries to be
statically linked instead of dynamically
[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.