USE Flags
Contents |
[edit] What is a USE flag?
In Gentoo, USE flags are a mechanism for fine-tuning the options and capabilities with which portage installs software. By enabling or disabling these options, users can cut down on dependencies, compile time, and package size to make for a leaner, faster system while retaining important functionality. Flags can be defined on a global or a per-package basis.
For example, mail-client/mutt has twenty USE flags. Some flags such as pop, imap and nntp enable or disable compile-time options. The mutt source file contains all the code for these options; the flag merely determines whether or not that code will be used when building the package. Without the pop and imap flags enabled, mutt can only read mail stored in local files.
Some flags enable features which require certain commands or libraries; gdbm, berkdb, ssl and sasl all enable features that require additional userspace libraries such as Sleepycat DBM or OpenSSL. If these flags are enabled, portage will pull in additional packages to satisfy the dependencies, which may in turn, depend on other software packages as well.
Some flags are specific to just fix bugs. These are usually localized and temporary. Their descriptions usually hint that they are the case. For example, the buffysize flag description reads, "Enables buffysize workaround, see bug #72422."
[edit] Choosing global USE flags for your system
Choosing the right USE flags is crucial, but it's also pretty simple. First, consider the purpose of the system you're setting up and the capabilities it is likely to need. Will it be a server? A workstation? Web client? Media box? Router?
Then consult the list of USE flags available locally at /usr/portage/profiles/use.desc or online at the Gentoo-Portage USE Flag Listing. The description of each use flag should help you decide which to choose. If you are not sure leave it out; there are some default USE flags set for you already..
[edit] Viewing USE flag descriptions
Using grep, you can easily find out what a USE flag means (Don't forget to substitute the flag you're searching for):
If that does not return any results, you can search package-specific USE flags as well:
If you have app-portage/gentoolkit installed, you could use the euse command instead:
Try your best to anticipate the needs of your system but don't sweat mistakes or omissions. You can always modify USE flags later, but all relevant packages will need to be rebuilt.
[edit] Viewing a package's current USE flags
To view what USE flags would be used to install a package with your current settings:
or if you have eix installed:
Eix is a utility that can speed up portage searches. More info can be found in the Eix article.
[edit] Viewing all packages with a specific USE flag
To view what packages that can use some USE flag:
equery is a part of app-portage/gentoolkit.
[edit] Setting your USE flags
Once you've chosen your flags, add them to the appropriate portage configuration files with your favorite editor. Global USE definitions go in /etc/make.conf like so:
... CHOST="i686-pc-linux-gnu" MAKEOPTS="-j3" USE="java cups samba alsa vorbis pdf sdl dbus udev opengl exchange -kde" ...
To enable a flag simply add it to the USE: line. Do not prefix the flagname with a plus sign, e.g. use kde, but not +kde. To disable, add it with a minus sign as a prefix: -kde.
Per-package flags can be defined in /etc/portage/package.use. These override global settings in /etc/make.conf
net-irc/xchat -perl -python net-p2p/bittornado -gtk www-client/mozilla-firefox java mozdevelop net-p2p/mldonkey gnutella -fasttrack
In the above example:
- X-Chat will be installed without built-in Perl and Python interpreters,
- BitTornado will be installed without a Python-GTK GUI interface, and
- Mozilla Firefox will be built with Java support and the Venkman web developers' features.
- MLdonkey will include support for the Gnutella network but not the FastTrack network.
If you prefer, there are a number of utilities for managing USE flags.
[edit] euse
euse - Part of the app-portage/gentoolkit package
euse is a good way to handle USE Flags. Read the euse MAN page.
[edit] ufed
ufed - Use Flag Editor
app-portage/ufed will show you which flags have been specified by default and a description for each USE flag. Within the program, you can edit which USE flags will be used. But without a detailed description per USE flag, ufed is still weak.
[edit] Profuse
A good replacement for ufed is profuse (app-portage/profuse). This program has a GUI, relatively good descriptions for USE flags and does not make such big mistakes in writing the make.conf as ufed. But, as always when changing config-files, it is recommended to make a backup of the /etc/make.conf before using ufed or profuse.
[edit] flagedit
Flagedit (app-portage/flagedit) is an easy to use command line USE flag, and keyword, editor. It can set USE flags both on a per-package basis, and globally. It can also be used to edit keywords, again on a per-package basis as well as globally.
See flagedit --help for examples and details after installing it.
[edit] Paludis users
If you're using paludis, set your use flags in /etc/paludis/use.conf. Its syntax is similar, but it also accepts wildcards (*).
[edit] Default USE flags
Some use flags are automatically included in your build based on your selected system profile. This is defined by the symlink at /etc/make.profile which points to one of the available profiles in /usr/portage/profiles
The current default USE flags for an x86 Linux system:
...
USE="berkdb crypt ipv6 ncurses nls pam perl python readline ssl tcpd zlib"
USE="${USE} fortran mudflap openmp"
USE="${USE} cli pcre session"
USE="${USE} dri"
USE="${USE} pppd"
USE="${USE} xorg"
USE="${USE} iconv"
USE="${USE} modules"
...While the server subprofile isn't officially supported at the current time, it defines a much leaner set of USE flags than the standard profile. This keeps server users from having to manually disable large numbers of flags not needed by servers such as X or Gnome or KDE.
[edit] USE flag definitions
Any USE flag's exact effect may be a mystery without looking at the ebuild but here some general descriptions for most use flags:
- Descriptions of known global USE flags
- Gentoo-Portagehas definitions for some local USE flags; select a package and click the link to the USE flags for that package to see the descriptions. For a list of all known USE flags, Gentoo-Portage has compiled a comprehensive list.
