The main Portage tool that most users will use is emerge. We have already
used it during the Gentoo installation and in the previous chapter, but we just
briefly explained how to use it. This chapter will elaborate on emerge
and teach you how to use emerge to fix all your software-related needs.

emerge is the command used to install, remove, query and maintain
software packages. It is a front-end for ebuild; people interested in
becoming Gentoo professionals will learn how to use ebuild later on. For
now, we will focus on emerge as it has functionality that ebuild
lacks (such as resolving dependencies, searching the Portage tree, etc.).

Since emerge is the most important tool for Gentoo users, it has an
extensive manpage you can read by issuing man emerge. You can also view
the in-command help by running emerge --help.

# man emerge
# emerge --help

The Portage Tree

Before we continue describing emerge, let us first take a look at the
Portage Tree. Go to /usr/portage and do a listing of the available
directories. We use ls --classify to list the contents of a
directory as it will show directories with a trailing "/".

In the example directory, four ebuilds are stored. An ebuild is a script
which contains all the necessary information about a specific version of a
package. The naming for the ebuilds is almost identical; they only differ in
the version name.
You are free to view the contents of such an ebuild: they are plain scripts. We
will not discuss it right now as it isn't important to know if you plan on just
using Gentoo.

The other files are the ChangeLog (which contains a listing of all
the changes done to the ebuilds), Manifest (which contains the
checksums and filesizes of all the files in the directory) and
metadata.xml (which contains more information about the package,
such as the responsible development group -- called herd -- and a more
extensive description).

Inside the files directory, you will find extra files, needed by
Portage: digests (names, sizes and checksums of the files needed by a single
version of the package), patches, example configuration files, etc.

If you go back to the root of the Portage tree (/usr/portage) you
will notice that there are other, non-category directories, too. We will discuss
those later in this chapter.

Search for a Package

If you are new to Linux or Gentoo, you might not know what tool you need for
what job. To facilitate searching, emerge provides you with a way to
search through the available packages on your system. There are two ways you can
search through packages: by name, or by name and
description.

To search through the Portage tree by name, use emerge search. For
instance, to find out more about mozilla:

As you can see, the output of emerge informs you about the category and
name of the package, the available version, the currently installed version,
the size of the downloaded files, the homepage and the short description.

Do you see something else? Yes, downloaded files. When you tell Portage
to install a package, it of course needs to have the necessary sources (or
precompiled packages) available. It therefore checks the contents of
/usr/portage/distfiles to see if the necessary files are already
available. If not, it downloads the necessary files and places them in that
directory.

Viewing the ChangeLog

While browsing through the Portage Tree, you saw that there was a ChangeLog for
each package. You can view the ChangeLog entries between the available version
and the installed version with emerge too. Use the
--pretend --changelog (-pl in short) options. As an example we
will view the ChangeLog entries for gnumeric:

Searching through Portage is nice, but if you don't update your Portage Tree
regularly, you will be stuck with the packages and versions available on your
system. This means that your system will get outdated pretty soon and that
you will be missing bugfixes and remedies for possible security problems.

There are several ways to update your Portage Tree. The most popular method is
by using one of our rsync mirrors.
Another one is by using a Portage snapshot (in case a firewall or unavailability
of a network prohibits the use of the rsync server).

Selecting a Mirror for rsync

It is advisable to first select a fast mirror close to you. You can do this manually
(by setting the SYNC variable in /etc/make.conf) or use
mirrorselect to do this for you automatically. As the SYNC
variable will be discussed later on, we will focus on using mirrorselect.
First install mirrorselect by emerging it:

# emerge --usepkg mirrorselect

Now run mirrorselect to automatically select mirrors for you (it will
also setup Portage to use a mirror for the source code):

# mirrorselect -a -s3

Updating Portage

To update Portage using rsync, simply run emerge --sync:

# emerge --sync

If this fails (due to network problems, or a firewall), you can try using
emerge-webrsync which will download a Portage Tree snapshot using
wget. This also means that you can use proxies if you want. We discussed
how to setup your system to use proxies during the Gentoo installation.

# emerge-webrsync

Maintaining SoftwareBuilding or Prebuilt?

Gentoo provides ebuilds, the Gentoo packages if you like. But when you want to
install such an ebuild, you can choose between building the package and
using a prebuilt package. But what are the advantages/disadvantages of
both approaches, and can they be used alongside each other?

As you probably have guessed, building packages takes a lot of time (especially
if you have little resources or want to build big packages, such as KDE, OpenOffice.org, etc.). By building the
package, you can use the USE setting to tweak the package to your system.
Of course, you can also define high optimization options (in the CFLAGS
and CXXFLAGS variables) to compile the package with.

Using prebuilt packages improves the installation time (as no more compilation
is needed), but you will lose the advantages of the USE setting and the
CFLAGS & CXXFLAGS variables.

As previously stated, prebuilt packages are stored in the
/usr/portage/packages/All directory, while the source code of the
packages is placed in /usr/portage/distfiles. If you have finished
installing a package you can remove the package or source code from the
respective directory. However, you might want to keep the package/source code of
the latest version, just in case you want to reinstall the package (so you don't
have to redownload it).

Installing Software from Sources

Okay, enough talking, let's cut to the chase. To install a package, you will use
the emerge command. If you don't want to use any prebuilt packages, you
can just use emerge <package-name> or emerge
<category>/<package-name>. As an example we'll install
gnumeric:

# emerge gnumeric

This will download the source code for you and unpacks, compiles and installs
the package on your system. It will also do the same for all the dependencies.
If you want to see what dependencies will be installed with it, use the
--pretend option (-p in short):

# emerge --pretend gnumeric

If you want to download the source code of the package and its dependencies,
but don't want to build the package, use the --fetchonly option
(-f in short):

# emerge --fetchonly gnumeric

If you want to see where emerge downloads the sources from, combine the
--fetchonly and --pretend options:

# emerge --fetchonly --pretend gnumeric

You can also opt to install a specific version of a package.
For instance, if you want to install a gnumeric version older than 1.2 -- for
any reason whatsoever :) you would type:

# emerge "<gnumeric-1.2"

Other possibilities are of course ">" (later version), "=" (the exact
version) and the combinations "<=" and ">=".

Installing Prebuilt Packages

When you want to install a prebuilt package, you should use the --usepkg
option (-k in short). This will use the binary package available in
/usr/portage/packages/Allif the package and the version of
the application you want to install match.

# emerge --usepkg gnumeric

If you want to use the binary package, even if the versions don't match, use
--usepkgonly (-K in short).

# emerge --usepkgonly gnumeric

If you don't have the prebuilt package on your system yet, you can have
emerge download it from a mirror, defined in the PORTAGE_BINHOST
variable declared in /etc/make.conf.

Gentoo does not have any server or mirror containing such prebuilt packages.
Portage has been extended with this feature to fullfil the community request.

To download the binary package in case this package doesn't exist on
your system already, use --getbinpkg (-g in short):

# emerge --getbinpkg gnumeric

This will download the package and the package-related information for you and
install it on your system, together with the dependencies. If you want to see
what dependencies will be installed with it, use the --pretend option
(-p in short):

# emerge --getbinpkg --pretend gnumeric

You can also opt to download the prebuilt package (and the package-related
information) without checking the information on your local system and
without using the prebuilt package already on your system (if
applicable), use the --getbinpkgonly option (-G in short):

# emerge --getbinpkgonly gnumeric

You can also opt to install a specific version of a package.
For instance, if you want to install a gnumeric version older than 1.2 -- for
any reason whatsoever :) you would type:

# emerge --usepkg "<gnumeric-1.2"

Other possibilities are of course ">" (later version), "=" (the exact
version) and the combinations "<=" and ">=".

Working with Dependencies

Portage has extensive support for dependency handling. Although you usually
don't need to even think about this (as dependencies are automatically handled
by Portage) some users might want to know how you can work with emerge
and dependencies.

For instance, if you want Portage to pretend that none of the dependencies of a
package are installed, you can use --emptytree (-e in short). This
is useful with --pretend to display a complete tree of dependencies for
any particular package. Without --pretend, emerge will (re)compile
all listed packages.

# emerge --emptytree --pretend gnumeric

Another argument is --nodeps, which will ask Portage to try install the
given package without taking care of the dependencies. This can all too often
lead to failures.

# emerge --nodeps gnumeric

The opposite of --nodeps is --onlydeps, which will have Portage
install all dependencies of a given package, but not the package itself:

# emerge --onlydeps gnumeric

When you uninstall software Portage will not automatically unmerge the
dependencies that aren't needed anymore. If you want to "clean" your system from
those orphaned dependencies, you can use emerge depclean. This will
search for all installed software that you haven't installed explicitly and that
isn't a dependency of software that you have installed explicitly.

Using depclean can seriously impair your system. Use with caution and
double-check the list of dependencies that Portage wants to remove before you go
ahead!

Portage knows two special tags to denote a set of software packages:
system and world. You have already seen the former while
installing Gentoo if you didn't use a stage3 installation. To refresh
things: system is the collection of core packages, necessary to
have a working Gentoo system.

The world tag consists of all software you have installed yourself on
your system plus the system information. In other words, every time you
emerge a package using emerge <package-name>, the
<package-name> is registered in the world file
(/var/cache/edb/world). Dependencies are not part of the
world file, but we will get to that later.

If you want to update the system packages, use the --update option
(-u in short):

# emerge --update system

An identical approach can be used for the world packages:

# emerge --update world

Again, if you want to see what emerge wants to update, use the
--pretend option together with the --update option:

Right next to the word "ebuild" you will notice a letter (or combination of
letters) which gives you more information about the package:

B (blocks) The package listed to the left is blocking the emerge of
the package listed to the right

N (new) The package is new to your system and will be emerged for the
first time

R (replace) The package isn't new, but will be reemerged

F (fetch) The package requires that you download the source code
manually (for instance due to licencing issues)

U (update) The package already exists on your system but will be
upgraded

UD (downgrade) The package already exists on your system but will be
downgraded

We have mentioned that the world file doesn't contain dependencies. When
you run emerge --update world only the packages mentioned in the
world file and it's immediate dependencies are checked and, if necessary,
upgraded. If you want emerge to check all the dependencies
(including the dependencies of the dependencies), add the --deep flag:

# emerge --update --deep world

Of course, we are talking here about system and world, but you can
perform the same actions for individual software packages.

Removing Software

If you want to remove software from your system, you can use the unmerge
option (-C - capital C - in short):

# emerge unmerge gnumeric

If you want to test a removal (but not perform it), you can use --pretend
again:

# emerge --pretend unmerge gnumeric

Portage doesn't verify if a package is a dependency for another
installed package. It also doesn't warn you if the package is part of
system, i.e. a core application necessary for the correct functioning of
your system!

Once the unmerge begins you will see a long list of filenames belonging to the
package. Some of these filenames will have a flag displayed to the
left of the filename. The flags !mtime, !empty, and cfgpro
specify reasons why certain files are not being removed while the package is.
Files listed without any of these three flags are removed from the
filesystem successfully. The three flags specify the following reasons:

!mtime : The listed file has been changed since it was installed,
probably by you or some tool

!empty : The listed directory is not empty

cfgpro : This file is located inside a protected directory and will
not be touched for safety

Working with Masked PackagesARCH or not?

When a Gentoo developer puts an ebuild online it informs Portage how to treat
the package depending on the architecture and stability of the software title.
He does so by defining a variable called KEYWORDS inside the ebuild.
This variable contains one or more architectures and marks them with a special
flag. An explanation of the available flags is given in the next table.

Flag

Description

ARCHKnown to work well on the given architecture

~ARCH
Probably works well but needs some further testing on the given
architecture

-ARCHKnown not to work on the given architecture

-*Known not to work or being extremely dangerous on any architecture

Let's take a look at an example:

KEYWORDS="x86 -sparc ~alpha ~ppc"

This example can be read as follows:

The ebuild works well on the x86 architecture

The ebuild doesn't work on the sparc architecture

The ebuild probably works on the alpha architecture but needs more testing

The ebuild probably works on the ppc architecture but needs more testing

The ebuild might work on the other architectures but hasn't been tried yet

Your system will use ARCH packages per default. If you want to live on
the edge, don't mind having a broken package once in a while, know how to deal
with a broken system and you like submitting bugreports to bugs.gentoo.org, then you can opt to use
~ARCH packages. To "move" your system to a ~ARCH-using system,
edit the ACCEPT_KEYWORDS variable in /etc/make.conf so that
it reads ~ARCH (again: for x86-based systems: ~x86, etc.).

Note though that it is far from simple (or even impossible) to go back to
ARCH from ~ARCH.

If you want to update your system now, you will notice that a lot of
packages will be updated!

Masked Packages

When you want to install a package, you might come across the following message:

Calculating dependencies
!!! all ebuilds that could satisfy <your package> have been masked.

A package can be masked due to several reasons:

The package is in ~ARCH while you use ARCH

The package is hard-masked explicitly

The package isn't available for your ARCH entirely

The package is masked by your profile

Portage will inform you why a certain package cannot be installed:

~arch keyword: the package is known to work on the given architecture
but requires more testing while your system requires that a package is
known to work well

-arch keyword: the package is known not to work on the given
architecture

-* keyword: the package is known not to work on any architecture

package.mask: the package is listed in the package.mask
file, meaning that it breaks something, crashes your system, has severe
security issues or worse

profile: the package is not available for your profile

If the package is masked because of ~arch keyword, and you really
want to install it (knowing that there is a reason why it isn't
available in ARCH), you can accept the ~ARCH version of any
package by adding it to your /etc/portage/package.keywords file:

Similarly, if you want to install a package marked -arch keyword or -*
keyword regardless of all the warnings we might put in front of you, edit
/etc/portage/package.keywords and add the package with the required
keyword:

A package is masked due to package.mask if it is listed in
/usr/portage/profiles/package.mask. If you read this file, you
will also read the reason why the package is hardmasked (it is usually added as
a comment). If you want to install the package nevertheless (despite all the
possible warnings we could ever throw at your head about "breaking your system",
"breaks other packages", or "badly needs testing"), create the
/etc/portage/package.unmask file and list the package in it (use
the same format as is used in /usr/portage/profiles/package.mask).

Do not alter the /usr/portage/profiles/package.mask file as
all changes are undone the next time you update your Portage tree.

Sometimes you might want to hardmask a (collection of) package(s). This is the
case when newer versions of an application don't support something you require
or when these versions break something else in your environment.

To hard-mask a package, create /etc/portage/package.mask and list
the package in it (use the same format as mentioned above).

When Portage tells you that it cannot install a package due to profile it
means that you are working with a certain profile that doesn't allow the package
to be installed. But what is this "profile"?

A profile contains a list of package names and a set of default configuration
options to be used by Portage. Those files tell Portage which packages
and which specific versions of those packages to allow, disallow, or
treat as required. Users can switch profiles by changing a single symlink
(/etc/make.profile).

You cannot override a package that is blocked due to profile; if you
really want to use it, switch to the required profile.

You will find more information in our Cascading Profiles
Document.

Blocked Packages

You have a situation when you receive the following error on your screen: