Gentoo Logo

Disclaimer : This handbook has been replaced by a newer version and is not maintained anymore.


[ << ] [ < ] [ Home ] [ > ] [ >> ]


2. USE flags

Content:

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 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-flag 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:

Code Listing 1.1: A short snippet of available USE-flags

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

A list of available local USE-flags can be found locally in /usr/portage/profiles/use.local.desc.

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 /etc/make.profile/make.defaults file. Let us take a look at this default setting:

Code Listing 2.1: /etc/make.profile/make.defaults USE variable on an x86 system

USE="x86 oss apm arts avi berkdb crypt cups encode foomaticdb gdbm gif gpm
     gtk gtk2 imlib jpeg kde gnome libg++ libwww mad mikmod motif mpeg ncurses
     nls oggvorbis opengl pam pdflib png python qt quicktime readline sdl
     slang spell ssl svga tcpd truetype X xml2 xmms xv zlib"

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:

Code Listing 2.2: An example USE setting in /etc/make.conf

USE="-kde -qt 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.

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

dev-db/mysql berkdb

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

dev-php/php -java

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

Code Listing 2.5: Using USE as environment variable

# 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:

Code Listing 2.6: A snippet from /etc/make.profile/use.defaults

gnome           gnome-base/gnome
gtk             x11-libs/gtk+
qt              x11-libs/qt
kde             kde-base/kdebase
motif           x11-libs/openmotif

Precedence

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 declared anyway. The precedence for the USE setting is, ordered by priority (first has lowest priority):

  1. Default USE setting declared in /etc/make.profile/make.defaults
  2. Inherited USE setting if a package from /etc/make.profile/use.defaults is installed
  3. User-defined USE setting in /etc/make.conf
  4. User-defined USE setting in /etc/portage/package.use
  5. 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.7: 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.8: 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 flags.

Warning: 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.9: 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.10: Running revdep-rebuild

# 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 mozilla: what USE-flags does it listen to? To find out, we use emerge with the --pretend and --verbose options:

Code Listing 3.1: Viewing the used USE-flags

# emerge --pretend --verbose mozilla
These are the packages that I would merge, in order:

Calculating dependencies ...done!
[ebuild  N    ] net-www/mozilla-1.5-r1 +java +crypt -ipv6 -gtk2 +ssl +ldap 
+gnome -debug +mozcalendar -mozaccess -mozxmlterm -moznoirc -moznomail
-moznocompose -moznoxft 

emerge isn't the only tool for this job. In fact, we have a tool dedicated to package information called etcat which resides in the gentoolkit package. First, install gentoolkit:

Code Listing 3.2: Installing gentoolkit

# emerge gentoolkit

Now run etcat with the uses argument to view the USE-flags of a certain package. For instance, for the gnumeric package:

Code Listing 3.3: Using etcat to view used USE-flags

# etcat uses gnumeric
[ Colour Code : set unset ]
[ Legend      : (U) Col 1 - Current USE flags        ]
[             : (I) Col 2 - Installed With USE flags ]

 U I [ Found these USE variables in : app-office/gnumeric-1.2.0 ]
 - - libgda  : Adds GNU Data Access (CORBA wrapper) support for gnumeric
 - - gnomedb : unknown
 + + python  : Adds support/bindings for the Python language
 + + bonobo  : Adds support for gnome-base/bonobo (Gnome CORBA interfaces)

[ << ] [ < ] [ Home ] [ > ] [ >> ]


Print

View all

Page updated October 21, 2004

Summary: USE-flags are a very important aspect of Gentoo. In this chapter, you learn to work with USE-flags and understand how USE-flags interact with your system.

Sven Vermeulen
Author

Daniel Robbins
Author

Chris Houser
Author

Jerry Alexandratos
Author

Seemant Kulleen
Gentoo x86 Developer

Tavis Ormandy
Gentoo Alpha Developer

Jason Huebel
Gentoo AMD64 Developer

Guy Martin
Gentoo HPPA developer

Pieter Van den Abeele
Gentoo PPC developer

Joe Kallar
Gentoo SPARC developer

John P. Davis
Editor

Pierre-Henri Jondot
Editor

Eric Stockbridge
Editor

Rajiv Manglani
Editor

Jungmin Seo
Editor

Stoyan Zhekov
Editor

Jared Hudson
Editor

Colin Morey
Editor

Jorge Paulo
Editor

Carl Anderson
Editor

Jon Portnoy
Editor

Zack Gilburd
Editor

Jack Morgan
Editor

Benny Chuang
Editor

Erwin
Editor

Joshua Kinard
Editor

Tobias Scherbaum
Editor

Grant Goodyear
Reviewer

Gerald J. Normandin Jr.
Reviewer

Donnie Berkholz
Reviewer

Ken Nowack
Reviewer

Lars Weiler
Contributor

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.