Powerful Portage

Discover how to use Gentoo’s package management tools.

Many articles and books assume that Linux
users run the popular distributions, such as Red
Hat, Fedora, SuSE, Debian,
or Ubuntu.
A few Linux distributions, though, are perfectly capable of filling
the same roles as the more popular distributions, but provide
unusual features. Knowing about the smaller distributions and the
peculiarities can be useful as a point of comparison even if you
use another distribution, much like knowing French can help your
understanding of English, even if you’ve lived in the United
States your whole life.

For these reasons, this month’s column is devoted to
Portage, Gentoo’s package management

Red Hat originated the RPM Package
(RPM) and Debian uses its own, eponymous package
system. Rather than use either of these systems, though,
Gentoo’s designers created their own package management
system, Portage. Portage is similar to "i">FreeBSD’s Ports system; both enable you to easily
compile source code and install it on the computer in a way that
also makes it easy to track dependencies and uninstall the software
at a later date. Gentoo’s Portage helps define the
distribution’s strengths and weaknesses compared to other

A Portage Overview

Portage is designed to help you easily compile and install
source code without the tedious mucking about with "c">configure scripts, the make
utility, and so on. To some users, compiling everything locally is
a sort of spiritual purification. To others, though, it’s got
a real advantage over installing precompiled binaries, as both RPM
and Debian packages emphasize: Building software locally means you
can use the optimum compiler and other configuration settings for
your system.

In particular, Portage enables you to set compiler optimizations
for your CPU (so that your code is compiled for your AMD
Athlon rather than an Intel 80386, for
example) and to specify what libraries and other compile-time
options you want to support. In theory, these optimizations can
help improve system performance. In practice, this benefit is
likely to be slim if you aren’t intimately familiar with your
CPU and the common library options, including which libraries you
do and do not want to use. A little tweaking can help you gain some
benefits from Portage, though.

Compiling all your software locally has two significant
disadvantages and a host of more minor quirks. First, it takes a
long time, particularly for big packages. Upgrading mega-packages
like KDE or GNOME can
be an overnight affair. Second, compilation can sometimes fail
because of system-specific idiosyncrasies or the very compiler and
linking options you chose in the hopes of optimizing performance.
The worst quirk of Portage is that it tends to consume a lot of
disk space, so you’ve got to be careful to watch disk

Portage maintains information on multiple versions of most
packages. This enables you to select the version you prefer, if you
don’t want to run the latest version. Some packages are
masked, meaning that you must pass special
options to install them on your system. Masking is typically done
because a package hasn’t been thoroughly tested and so
isn’t considered perfectly reliable. A single package can be
masked on one platform but not another. In most cases, packages are
unmasked for x86 before they’re unmasked for "i">PowerPC, AMD64 (aka x86-64), or
other CPUs. Sometimes packages simply can’t be installed on
certain platforms if they include platform-specific code with no

In practice, Portage is a perfectly usable system, but to get
the most out of it, you must understand its main tools and the
compile options you can set. You may also want to investigate some
handy front-ends to Portage and delve into its directory tree so
that you can clean up after it when a compile goes bad or when it
chews up too much disk space.

The Main Portage Tools

Portage works on package files that it calls "i">ebuilds. An ebuild is simply a description of a package,
including what source code files it uses, what dependencies it has,
on what hardware platforms the ebuild should work, and so on. An
ebuild includes a description of where on the Internet the source
code can be found, including any patches the Gentoo maintainers
have incorporated or written themselves. Ebuild specifications are
stored in the /usr/portage directory tree in
files with names that end in .ebuild, as
described later.

The major interface to Portage is emerge.
This program is roughly equivalent to yum on
many RPM systems or apt-get on Debian-based
systems. Of course, emerge emphasizes
building programs from source code rather than installing
pre-compiled binaries, although emerge does
include an option to install binary packages. You’re likely
to use several emerge features:

*Sync your
emerge maintains a local
database of available packages, but you must periodically
synchronize your database to the one maintained by the Gentoo
developers. To do so, type emerge
. This process can take a while as
emerge downloads data and updates local

*Search for
You can use the "c">––search or –s
action to search for packages by name, as in emerge
––search office
to find any package whose name
includes the string “office” (such as "i">openoffice or koffice). You can
search through ebuild descriptions by using "c">–searchdesc in a similar way.

To install software, you provide no special action
name, just the package name. For instance, emerge
installs the "i">SpamAssassin utility. This process can take quite a
while, particularly with big packages. If your CPU is fast, small
packages install in little more time than it would take
yum or apt-get to do
their jobs on other distributions.

The ––unmerge
or –C action uninstalls the named
package. For instance, emerge ––unmerge
removes SpamAssassin. This process is usually
much faster than package installations.

*Update your
The ––update or
–u action updates a package to the
latest unmasked version. This action is frequently used with the
system or world
target. These names correspond to the most critical system software
and to all the software listed in "i">/var/lib/portage/world, respectively. The latter
normally includes all the packages you’ve explicitly

These actions may be modified by many options, including:

The ––ask
(–a) and "c">––pretend (–p)
options are particularly important: They cause "i">emerge to pause and ask you before proceeding with an
action after an initial report or to simply display a report of
what it would do, respectively. These options are particularly
handy when updating your system.

Ordinarily, emerge updates
only the package (or group of packages, as in the "c">system or world targets) you
specify. If you include the "c">––deep or –d
option, though, emerge updates its
dependencies, too.

*Install binary
The ––usepkg or
–k option tells "i">emerge to install a binary package from the directory
tree specified by the PKGDIR environment
variable, if one is available. The "c">––usepkgonly or "c">–K options do the same, but cause "i">emerge to fail if a binary package isn’t

This list of emerge actions and options
is incomplete. Consult the emerge man page
for the program for a more complete listing.

Many packages include configuration files. To compare these to
your existing configuration files, type "c">etc-update. This tool locates the updated configuration
files, which are initially installed as dot-files in their target
directories. etc-update then compares the
original and updated files using diff and
gives you the option of deleting the updated file, replacing the
original with the update, or taking a few other actions.

Setting Compile Options

Since Portage enables you to customize your compile-time
options, you should know how to do so. The main file for setting
default compile-time options is "i">/etc/make.conf. This file sets options in the form of
environment variables, as in "c">MAKEOPTS=”–j2”.

In practice, two environment variables are the ones you’re
most likely to modify: CFLAGS and

The CFLAGS environment variable specifies
what flags to pass to gcc when it compiles a
program. A couple of important options that you may be able to set
with minimal expertise are the optimization level (specified with
–O; no setting, numbered from
–O1 to "c">–O3 to optimize for performance, or "c">–Os to optimize for code size) and the
architecture type (set with –march=
, where "c">arch is an architecture type
code, such as i386 for an "i">80386, pentium4 for a
Pentium 4, or "c">athlon64 for an Athlon 64.

Generally speaking, increasing optimization levels improves
performance, but increases the risk of creating bugs. A level of
–O2 is usually a good compromise, but
you can experiment with this value if you like. You can also review
the gcc man page for information on
optimization levels as well as other optimization-specific

The general rule for the architecture code value is to set it to
the CPU you’re using. This enables gcc
to create code that’s optimized for your CPU. Setting the
value too low (say, to i386 if you’re
using a Pentium 4) generates code that will run a bit more slowly
than if you’d set the code optimally. Setting the code too
high, though, generates code that might not run at all. Code
generated with pentium4 optimizations is
unlikely to run on an Pentium 3, much less
an 80386.

The USE flags work in an entirely
different way: they tell Portage which libraries it should or
should not include, if the package provides options.

For instance, some programs offer a compile-time option to
support Kerberos authentication. In a
traditional binary package, whoever compiled the software made the
decision for you of whether or not to include that support. In
Gentoo, though, you can make that decision yourself, by including
kerberos or "c">–kerberos (to include or not include the support,
respectively) in the USE option line in
/etc/make.conf. Once you make this change,
it will affect all the packages you subsequently compile that
don’t hard-code a response. For instance, if you opt to omit
Kerberos support, that choice won’t affect your compilation
of Kerberos itself, if you decide to install a Kerberos

You might be wondering what sorts of USE
options are available. You can find a complete list of global
options in /usr/portage/profiles/use.desc.
Take some time to peruse this file. If you have any doubts about
the meaning of a particular USE flag, leave
it alone; however, if you’re certain you want to change your
system-wide default, do so. You might notice libraries that you
definitely do or definitely do not want to include. Adding support
for particular features makes your software more flexible, but can
increase complexity and reduce speed; deleting unnecessary support
can sometimes improve performance.

Options you set in the /etc/make.conf
file override system defaults, which are set in the "i">/etc/make.profile/make.defaults file. (The "i">/etc/make.profile directory is actually a symbolic link
to a directory that’s specific to your architecture and
Gentoo release version.) You shouldn’t attempt to edit this
file, but you can examine it to learn what your defaults are before
you attempt to override them.

Portage Front-Ends

The emerge utility and its configuration
files are powerful tools; however, you might not always like the
way they work. If you’re familiar with utilities on other
systems or if you prefer working with visual tools, various
front-ends to Portage can make it easier to use:

USE flags.
You can use tools such as
euse (part of the "i">gentoolkit package) or the GUI "i">profuse to set USE flags.

rpm workalike.
If you’ve
converted to Gentoo from an RPM-based distribution, you might want
to check out epm, which supports a subset of
rpm commands as front-ends to "i">emerge and other tools. The query and verification
options are particularly handy.

This utility, shown in Figure One, is a
Qt- based front-end to "i">emerge. It’s similar to tools such as "i">Yum Extender for systems that use Yum, or "i">Synaptic for systems that use "i">APT.

* "b">Porthole. If you prefer GTK+
applications to Qt programs, you might prefer "i">Porthole to Kuroo. The two packages are similar in
overall features but use different widget sets, and also vary in
several details.

These tools are particularly handy if you’re new to
Gentoo. Kuroo and Porthole can be useful even for experienced
Gentoo administrators because they can simplify package browsing,
determining which packages are and are not installed and making
changes in your package lineup.

Behind-the-Scenes Portage

Like many Linux programs, Portage relies on a variety of
configuration files and other behind-the-scenes files and
directories, such as /etc/make.conf. You may
need to keep an eye on or occasionally visit some of these files
and directories, though, in addition to "i">make.conf.

* "i">/usr/portage holds the Portage ebuilds, organized in
categories, each within its own subdirectory. You can search these
subdirectories for information on packages in particular
categories, which can be useful if you’re looking for
software of a particular type, such as office software
(/usr/portage/app-office) or mail servers

* "i">/usr/portage/distfiles stores source code and other
files it downloads from Internet archives in this directory. The
trouble is that this practice results in an accumulation of files
that may occasionally require cleaning.

* "i">/usr/portage/packages is the usual location for storing
binary packages, either that emerge builds
when given certain options or that you wish to install using

* "i">/var/tmp/portage is used to build packages. It should
normally be empty, but it will temporarily hold files while
packages are being built. If a compilation fails, the files are
left behind. If the partition in which the directory resides is too
small, large packages can fail to compile. If this happens, you may
need to clean out or resize the partition or use a symbolic link to
relocate the directory to a partition with more free space.

Appropriate use and maintenance of these directories and the
files in them keep your Gentoo system running smoothly.

Pay particular attention to the free space on the relevant
partitions on your system. Use df to
determine a partition’s free space and "i">du to sum up the space used in particular directory
trees. Keep track of the disk space that Portage consumes and take
corrective measures before a problem occurs.

Comments are closed.