Gentoo Logo

Renuncia de responsabilidad: Este manual ha sido sustituido por una versión más reciente y no tendrá soporte de aquí en adelante.

[ << ] [ < ] [ Inicio ] [ > ] [ >> ]

1. Introducción al Sistema Portage


1.a. Obtaining Package Information

The Lord of All Tools: emerge

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.

Listado de Código 1.1: Retrieving help for emerge

# 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 "/".

Listado de Código 1.2: Viewing the Portage Tree

# cd /usr/portage; ls --classify
app-admin/       dev-ml/            gnome-libs/     net-print/
app-arch/        dev-perl/          gnome-office/   net-wireless/
app-benchmarks/  dev-php/           header.txt      net-www/
app-cdr/         dev-python/        incoming/       net-zope/
app-crypt/       dev-ruby/          jython/         packages/
app-dicts/       dev-tcltk/         kde-apps/       profiles/
app-doc/         dev-tex/           kde-base/       releases/
app-editors/     dev-util/          kde-i18n/       scripts/
app-emacs/       distfiles/         kde-libs/       sec-policy/
app-emulation/   eclass/            licenses/       skel.ChangeLog
app-games/       experimental/      media-fonts/    skel.ebuild
app-gnustep/     files/             media-gfx/      skel.metadata.xml
app-i18n/        fresco-base/       media-libs/     snapshots/
app-misc/        games-action/      media-plugins/  sys-apps/
app-office/      games-arcade/      media-radio/    sys-build/
app-pda/         games-board/       media-sound/    sys-cluster/
app-portage/     games-emulation/   media-tv/       sys-devel/
app-sci/         games-engines/     media-video/    sys-fs/
app-shells/      games-fps/         metadata/       sys-kernel/
app-text/        games-kids/        net-analyzer/   sys-kmods/
app-vim/         games-misc/        net-apache/     sys-libs/
app-xemacs/      games-mud/         net-dialup/     unix2tcp/
berlin-base/     games-puzzle/      net-dns/        x11-base/
dev-ada/         games-roguelike/   net-firewall/   x11-libs/
dev-cpp/         games-rpg/         net-fs/         x11-misc/
dev-db/          games-server/      net-ftp/        x11-plugins/
dev-dotnet/      games-simulation/  net-im/         x11-terms/
dev-embedded/    games-sports/      net-irc/        x11-themes/
dev-games/       games-strategy/    net-libs/       x11-wm/
dev-haskell/     games-util/        net-mail/       xfce-base/
dev-java/        glep/              net-misc/       xfce-extra/
dev-lang/        gnome-apps/        net-nds/
dev-libs/        gnome-base/        net-news/
dev-lisp/        gnome-extra/       net-p2p/

As you can see, the Portage tree has several subdirectories. Most of them are the categories in which the Gentoo packages, called ebuilds, reside. Take a look at, for instance, app-office:

Listado de Código 1.3: Viewing a category

# cd app-office; ls --classify
abiword/     gnotime/   kmymoney2/  ooodi/              plan/     timestamp.x
dia/         gnucash/   koffice/    oooqs/              qhacc/
dia2code/    gnumeric/  lxbank/     openoffice/         sc/
facturalux/  ical/      lyx/        openoffice-bin/     scribus/
gaby/        kbudget/   mdbtools/   openoffice-ximian/  siag/
gnofin/      khacc/     mrproject/  phprojekt/          texmacs/

Inside a category you will find the packages belonging to that category, with a separate directory for each package. Let us take a look at the openoffice package:

Listado de Código 1.4: Viewing a package

# cd openoffice; ls --classify
ChangeLog  files/        openoffice-1.0.3-r1.ebuild  openoffice-1.1.0-r2.ebuild
Manifest   metadata.xml  openoffice-1.1.0-r1.ebuild  openoffice-1.1.0.ebuild

Remember that we told you that a Gentoo package is called an ebuild? Well, in the example directory four of such ebuilds are stored. Their naming is almost identical: they only differ in the version name. You are free to view the contents of such a package: 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 (checksums and permissions of the files needed by a single version of the package), patches, example configuration files, etc.

Listado de Código 1.5: Viewing the extra files

# cd files; ls --classify
1.0.3/  digest-openoffice-1.0.3-r1  digest-openoffice-1.1.0-r1
1.1.0/  digest-openoffice-1.1.0     digest-openoffice-1.1.0-r2
# cd 1.1.0; ls --classify
fixed-gcc.patch      ooffice-wrapper-1.3
newstlportfix.patch  openoffice-1.1.0-linux-2.6-fix.patch
no-mozab.patch       openoffice-1.1.0-sparc64-fix.patch

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:

Listado de Código 1.6: Showing information about mozilla

# emerge search mozilla
[ Results for search key : mozilla ]
[ Applications found : 5 ]
(Some output removed to improve readability)
*  net-www/mozilla
      Latest version available: 1.5-r1
      Latest version installed: 1.4-r3
      Size of downloaded files: 29,153 kB
      Description: The Mozilla Web Browser

*  net-www/mozilla-firebird
      Latest version available: 0.7
      Latest version installed: [ Not Installed ]
      Size of downloaded files: 37,850 kB
      Description: The Mozilla Firebird Web Browser

If you want to include a search through the descriptions too, use the --searchdesc argument:

Listado de Código 1.7: Search through the descriptions too

# emerge --searchdesc mozilla
[ Results for search key : mozilla ]
[ Applications found : 10 ]
(Some output removed to improve readability)
*  dev-libs/nss-3.8
      Latest version available: 3.8
      Latest version installed: 3.8
      Size of downloaded files:  2,782 kB
      Description: Mozilla's Netscape Security Services Library that implements PKI support

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 small description.

You see something new? 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 (for source code) or /usr/portage/packages/All (for precompiled packages) to see if the necessary files are already available. If not, it downloads the necessary files and places them in those directories.

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:

Listado de Código 1.8: Viewing the ChangeLog entries for gnumeric

# emerge --pretend --changelog gnumeric
(Some output removed to improve readability)

  27 Nov 2003; foser <> gnumeric-1.2.2.ebuild :
  New release, requested in #34492
  updated deps

  12 Nov 2003; Jason Wever <> gnumeric-1.2.0.ebuild:
  Marked stable on sparc, fixes bug #32405.

  14 Oct 2003; Jason Wever <> gnumeric-1.0.8.ebuild:
  Added ~sparc keyword.  Fixes bug #31150.

1.b. Updating Portage


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

Listado de Código 2.1: Installing mirrorselect

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

Listado de Código 2.2: Running mirrorselect

# mirrorselect -a -s3

Updating Portage

To update Portage using rsync, simply run emerge sync:

Listado de Código 2.3: Updating Portage using 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.

Listado de Código 2.4: Updating Portage using emerge-webrsync

# emerge-webrsync

1.c. Maintaining Software

Building 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 next to 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,, 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:

Listado de Código 3.1: Building 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):

Listado de Código 3.2: Pretending to build gnumeric

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

Listado de Código 3.3: Fetching sources for gnumeric

# emerge --fetchonly gnumeric

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

Listado de Código 3.4: Showing URLs of the sources for gnumeric

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

Listado de Código 3.5: Installing a specific gnumeric version

# emerge "<gnumeric-1.2"

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

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/All if the package and the version of the application you want to install match.

Listado de Código 3.6: Installing a prebuilt package for gnumeric

# emerge --usepkg gnumeric

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

Listado de Código 3.7: Installing the prebuilt package for gnumeric

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

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

Listado de Código 3.8: Downloading and installing a prebuilt package for gnumeric

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

Listado de Código 3.9: Pretending to download the prebuilt packages for gnumeric

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

Listado de Código 3.10: Installing a prebuilt package without using local information

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

Listado de Código 3.11: Installing a specific gnumeric version

# emerge --usepkg "<gnumeric-1.2"

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

Working with Dependencies

Portage has an 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. However, glibc will not be listed as dependency for safety reasons.

Listado de Código 3.12: Show all dependencies of gnumeric

# emerge --emptytree --pretend gnumeric

Another argument is --nodeps, which will ask Portage to try install the given package without taking care of the dependencies. It is trivial that this can lead to failures.

Listado de Código 3.13: Installing gnumeric without taking care of the dependencies

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

Listado de Código 3.14: Installing the dependencies of gnumeric

# emerge --onlydeps gnumeric

Updating your System

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

Listado de Código 3.15: Updating the system packages

# emerge --update system

An identical approach can be used for the world packages:

Listado de Código 3.16: Updating your entire system

# emerge --update world

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

Listado de Código 3.17: Pretending to update your entire system

# emerge --pretend --update world
(Some output removed to improve readability)
[ebuild     U ] net-misc/wget-1.9-r1 [1.9] 
[ebuild     UD] media-video/dvdauthor-0.5.0 [0.5.3] 
[ebuild     U ] net-analyzer/ethereal-0.9.16 [0.9.14] 

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 (reemerge) The package isn't new, but needs to 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
  • U- (slot warning) The package you have installed on your system is listed as a package that can not coexist with a different version, but your update does. The update will be installed and the older version will be removed.

In certain cases, an update may mean a downgrade (i.e. install an older version instead of a newer version). If you don't want this to happen, use the --upgradeonly option (-U in short):

Listado de Código 3.18: Upgrading your entire system

# emerge --update --upgradeonly 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):

Listado de Código 3.19: Uninstalling software

# emerge unmerge gnumeric

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

Listado de Código 3.20: Pretending to uninstall software

# emerge --pretend unmerge gnumeric

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

1.d. Software Availability

ARCH or not?

Gentoo places its packages in two possible stadia called ARCH and ~ARCH. Don't take this literally: the stadia depend on the architecture you are using. In other words, for x86-based systems you have x86 and ~x86, for ppc-based systems you have ppc and ~ppc etc.

The ~ARCH stadium means that the package works for the developer in charge of the package, but that the package hasn't been tested thoroughly enough by the community to be placed in ARCH. ~ARCH packages usually go to ARCH after being bugfree for a sufficient amount of time.

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, 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 trivial (if 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:

Listado de Código 4.1: Message about masked packages

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

A package can be masked due to two reasons:

  1. The package is in ~ARCH while you use ARCH
  2. The package is hard-masked explicitly

If the package is masked because of the first reason, and you really want to install it (knowing that there is a reason why it isn't available in ARCH), you can temporarily accept ~ARCH packages:

Listado de Código 4.2: Temporarily accepting ~ARCH packages

# ACCEPT_KEYWORDS="~x86" emerge gnumeric

A package is hardmasked 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. If you want to hardmask a package create /etc/portage/package.mask and list the package in it (use the same format as mentioned above).

Blocked Packages

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

Listado de Código 4.3: Blocking package

[blocks B     ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0) 

In the above example, the package bonobo-activation is blocking the emerge of libbonobo. To resolve this issue, remove the bonobo-activation package and continue:

Listado de Código 4.4: Resolving a blocking situation

# emerge unmerge bonobo-activation

[ << ] [ < ] [ Inicio ] [ > ] [ >> ]


Ver completo

Página actualizada 21 de octubre, 2004

Esta traducción ha dejado de tener soporte

Sumario: Este capítulo explica los pasos "sencillos" que un usuario necesita saber definitivamente para mantener el software en su sistema.

Daniel Robbins

Sven Vermeulen

Chris Houser

Jerry Alexandratos

Seemant Kulleen
Desarrollador Gentoo x86

Tavis Ormandy
Desarrollador Gentoo Alpha

Jason Huebel
Desarrollador Gentoo AMD64

Guy Martin
Desarrollador Gentoo HPPA

Pieter Van den Abeele
Desarrollador Gentoo PPC

Joe Kallar
Desarrollador Gentoo SPARC

John P. Davis

Pierre-Henri Jondot

Eric Stockbridge

Rajiv Manglani

Jungmin Seo

Stoyan Zhekov

Jared Hudson

Colin Morey

Jorge Paulo

Carl Anderson

Jon Portnoy

Zack Gilburd

Jack Morgan

Benny Chuang


Joshua Kinard

Tobias Scherbaum

Grant Goodyear

Gerald J. Normandin Jr.

Donnie Berkholz

Ken Nowack

Lars Weiler

José Alberto Suárez López

John Christian Stoddart
Editor-Es Adjunto

Donate to support our development efforts.

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