This handbook has been replaced by a newer version and is not maintained anymore.
[ << ]
[ < ]
[ Home ]
[ > ]
[ >> ]
1. A Portage Introduction
1.a. Welcome to Portage
Portage is probably Gentoo's most notable innovation in software management.
With its high flexibility and enormous amount of features it is frequently seen
as the best software management tool available for Linux.
Portage is completely written in Python
and Bash and therefore fully
visible to the users as both are scripting languages.
Most users will work with Portage through the emerge tool. This chapter
is not meant to duplicate the information available from the emerge man page.
For a complete rundown of emerge's options, please consult the man page:
Code Listing 1.1: Reading the emerge man page
$ man emerge
1.b. The Portage Tree
When we talk about packages, we often mean software titles that are available to
the Gentoo users through the Portage tree. The Portage tree is a collection of
ebuilds, files that contain all information Portage needs to maintain
software (install, search, query, ...). These ebuilds reside in
/usr/portage by default.
Whenever you ask Portage to perform some action regarding software titles, it
will use the ebuilds on your system as a base. It is therefore important that
you regularly update the ebuilds on your system so Portage knows about new
software, security updates, etc.
Updating the Portage Tree
The Portage tree is usually updated with rsync, a fast incremental file transfer
utility. Updating is fairly simple as the emerge command provides a
front-end for rsync:
Code Listing 2.1: Updating the Portage tree
# emerge --sync
If you are unable to rsync due to firewall restrictions you can still update
your Portage tree by using our daily generated Portage tree snapshots. The
emerge-webrsync tool automatically fetches and installs the latest
snapshot on your system:
Code Listing 2.2: Running emerge-webrsync
1.c. Maintaining Software
Searching for Software
To search through the Portage tree after software titles, you can use
emerge built-in search capabilities. By default, emerge search
returns the names of packages whose title matches (either fully or partially)
the given search term.
For instance, to search for all packages who have "pdf" in their name:
Code Listing 3.1: Searching for pdf-named packages
$ emerge search pdf
If you want to search through the descriptions as well you can use the
--searchdesc (or -S) switch:
Code Listing 3.2: Searching for pdf-related packages
$ emerge --searchdesc pdf
When you take a look at the output, you'll notice that it gives you a lot of
information. The fields are clearly labelled so we won't go further into their
Code Listing 3.3: Example emerge search output
Latest version available: 1.5.2
Latest version installed: [ Not Installed ]
Size of downloaded files: 15 kB
Description: Provides a virtual printer for CUPS to produce PDF files.
Once you've found a software title to your liking, you can easily install it
with emerge: just add the package name. For instance, to install
Code Listing 3.4: Installing gnumeric
# emerge gnumeric
Since many applications depend on each other, any attempt to install a certain
software package might result in the installation of several dependencies as
well. Don't worry, Portage handles dependencies well. If you want to find out
what Portage would install when you ask it to install a certain package,
add the --pretend switch. For instance:
Code Listing 3.5: Pretend to install gnumeric
# emerge --pretend gnumeric
When you ask Portage to install a package, it will download the necessary source
code from the internet (if necessary) and store it by default in
/usr/portage/distfiles. After this it will unpack, compile and
install the package. If you want Portage to only download the sources without
installing them, add the --fetchonly option to the emerge command:
Code Listing 3.6: Download the sourcecode for gnumeric
# emerge --fetchonly gnumeric
When you want to remove a software package from your system, use emerge
unmerge. This will tell Portage to remove all files installed by that
package from your system except the configuration files of that
application if you have altered those after the installation. Leaving the
configuration files allows you to continue working with the package if you ever
decide to install it again.
However, a big warning applies: Portage will not check if
the package you want to remove is required by another package. It will however
warn you when you want to remove an important package that breaks your system
if you unmerge it.
Code Listing 3.7: Removing gnumeric from the system
# emerge unmerge gnumeric
When you remove a package from your system, the dependencies of that package
that were installed automatically when you installed the software are left. To
have Portage locate all dependencies that can now be removed, use
emerge's depclean functionality. We will talk about this later on.
Updating your System
To keep your system in perfect shape (and not to mention install the latest
security updates) you need to update your system regularly. Since Portage only
checks the ebuilds in your Portage tree you first have to update your Portage
tree. When your Portage tree is updated, you can update your system with
emerge --update world:
Code Listing 3.8: Updating your system
# emerge --update world
Portage will then search for newer version of the applications you have
installed. However, it will only verify the versions for the applications you
have explicitly installed - not the dependencies. If you want to update every
single package on your system, add the --deep argument:
Code Listing 3.9: Updating your entire system
# emerge --update --deep world
If you have altered any of your USE flags
lately you might want to add --newuse as well. Portage will then verify
if the change requires the installation of new packages or recompilation of
Code Listing 3.10: Performing a full update
# emerge --update --deep --newuse world
Some packages in the Portage tree don't have any real content but are used to
install a collection of packages. For instance, the kde package will
install a complete KDE environment on your system by pulling in various
KDE-related packages as dependencies.
If you ever want to remove such a package from your system, running emerge
unmerge on the package won't have much effect as the dependencies remain on
Portage has the functionality to remove orphaned dependencies as well, but since
the availability of software is dynamically dependent you first need to update
your entire system fully, including the new changes you applied when changing
USE flags. After this you can run emerge depclean to remove the orphaned
dependencies. When this is done, you need to rebuild the applications that were
dynamically linked to the now-removed software titles but don't require them
All this is handled with the following three commands:
Code Listing 3.11: Removing orphaned dependencies
# emerge --update --deep --newuse world
# emerge depclean
revdep-rebuild is provided by the gentoolkit package; don't forget
to emerge it first:
Code Listing 3.12: Installing the gentoolkit package
# emerge gentoolkit
1.d. When Portage is Complaining...
About SLOTs, Virtuals, Branches, Architectures and Profiles
As we stated before, Portage is extremely powerful and supports many features
that other software management tools lack. To understand this, we explain a few
aspects of Portage without going in too much detail.
With Portage different versions of a single package can coexist on a system.
While other distributions tend to name their package to those versions (like
freetype and freetype2) Portage uses a technology called
SLOTs. An ebuild declares a certain SLOT for its version. Ebuilds with
different SLOTs can coexist on the same system. For instance, the
freetype package has ebuilds with SLOT="1" and SLOT="2".
There are also packages that provide the same functionality but are implemented
differently. For instance, metalogd, sysklogd and syslog-ng
are all system loggers. Applications that rely on the availability of "a system
logger" cannot depend on, for instance, metalogd, as the other system
loggers are as good a choice as any. Portage allows for virtuals: each
system logger provides virtual/syslog so that applications can depend on
Software in the Portage tree can reside in different branches. By default your
system only accepts packages that Gentoo deems stable. Most new software titles,
when committed, are added to the testing branch, meaning more testing needs to
be done before it is marked as stable. Although you will see the ebuilds for
those software in the Portage tree, Portage will not update them before they are
placed in the stable branch.
Some software is only available for a few architectures. Or the software doesn't
work on the other architectures, or it needs more testing, or the developer that
committed the software to the Portage tree is unable to verify if the package
works on different architectures.
Each Gentoo installation adheres to a certain profile which contains,
amongst other information, the list of packages that are required for a system
to function normally.
Code Listing 4.1: Portage warning about blocked packages (with --pretend)
[blocks B ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0)
Code Listing 4.2: Portage warning about blocked packages (without --pretend)
!!! Error: the gnome-base/bonobo-activation package conflicts with another package.
!!! both can't be installed on the same system together.
!!! Please use 'emerge --pretend' to determine blockers.
Ebuilds contain specific fields that inform Portage about its dependencies.
There are two possible dependencies: build dependencies, declared in
DEPEND and run-time dependencies, declared in RDEPEND. When one of
these dependencies explicitly marks a package or virtual as being not
compatible, it triggers a blockage.
To fix a blockage, you can choose to not install the package or unmerge the
conflicting package first. In the given example, you can opt not to install
libbonobo or to remove bonobo-activation first.
Code Listing 4.3: Portage warning about masked packages
!!! all ebuilds that could satisfy "bootsplash" have been masked.
Code Listing 4.4: Portage warning about masked packages - reason
!!! possible candidates are:
- gnome-base/gnome-2.8.0_pre1 (masked by: ~x86 keyword)
- lm-sensors/lm-sensors-2.8.7 (masked by: -sparc keyword)
- sys-libs/glibc-18.104.22.16840808 (masked by: -* keyword)
- dev-util/cvsd-1.0.2 (masked by: missing keyword)
- media-video/ati-gatos-4.3.0 (masked by: package.mask)
- sys-libs/glibc-2.3.2-r11 (masked by: profile)
When you want to install a package that isn't available for your system, you
will receive this masking error. You should try installing a different
application that is available for your system or wait until the package is put
available. There is always a reason why a package is masked:
~arch keyword means that the application is not tested sufficiently
to be put in the stable branch. Wait a few days or weeks and try again.
-arch keyword or -* keyword means that the application does
not work on your architecture. If you believe the package does work file
a bug at our bugzilla website.
missing keyword means that the application has not been tested on
your architecture yet. Ask the architecture porting team to test the package
or test it for them and report your findings on our bugzilla website.
package.mask means that the package has been found corrupt, unstable
or worse and has been deliberately marked as do-not-use.
profile means that the package has been found not suitable for your
profile. The application might break your system if you installed it or is
just not compatible with the profile you use.
Code Listing 4.5: Portage warning about missing dependency
emerge: there are no ebuilds to satisfy ">=sys-devel/gcc-4.2-r4".
!!! Problem with ebuild sys-devel/gcc-3.4.2-r2
!!! Possibly a DEPEND/*DEPEND problem.
The application you are trying to install depends on another package that is not
available for your system. Please check bugzilla if the issue is known and if not,
please report it. Unless you are mixing branches this should not occur and is
therefore a bug.
Ambiguous Ebuild Name
Code Listing 4.6: Portage warning about ambiguous ebuild names
!!! The short ebuild name "aterm" is ambiguous. Please specify
!!! one of the following fully-qualified ebuild names instead:
The application you want to install has a name that corresponds with more than
one package. You need to supply the category name as well. Portage will inform
you of possible matches to choose from.
Code Listing 4.7: Portage warning about circular dependencies
!!! Error: circular dependencies:
ebuild / net-print/cups-1.1.15-r2 depends on ebuild / app-text/ghostscript-7.05.3-r1
ebuild / app-text/ghostscript-7.05.3-r1 depends on ebuild / net-print/cups-1.1.15-r2
Two (or more) packages you want to install depend on each other and can
therefore not be installed. This is most likely a bug in the Portage tree.
Please resync after a while and try again. You can also check bugzilla if the issue is known and if not,
Code Listing 4.8: Portage warning about fetch failed
!!! Fetch failed for sys-libs/ncurses-5.4-r5, continuing...
!!! Some fetch errors were encountered. Please see above for details.
Portage was unable to download the sources for the given application and will
try to continue installing the other applications (if applicable). This failure
can be due to a mirror that has not synchronised correctly or because the ebuild
points to an incorrect location. The server where the sources reside can also be
down for some reason.
Retry after one hour to see if the issue still persists.
System Profile Protection
Code Listing 4.9: Portage warning about profile-protected package
!!! Trying to unmerge package(s) in system profile. 'sys-apps/portage'
!!! This could be damaging to your system.
You have asked to remove a package that is part of your system's core packages.
It is listed in your profile as required and should therefore not be removed
from the system.
[ << ]
[ < ]
[ 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.