en/handbook/hb-working-portage.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE sections SYSTEM "/dtd/book.dtd">

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/1.0 -->

<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/handbook/hb-working-portage.xml,v 1.35 2004/08/29 10:56:31 swift Exp $ -->

<sections>
<section>
<title>Obtaining Package Information</title>
<subsection>
<title>The Lord of All Tools: emerge</title>
<body>

<p>
The main Portage tool that most users will use is <c>emerge</c>. 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 <c>emerge</c>
and teach you how to use <c>emerge</c> to fix all your software-related needs.
</p>

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

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

<pre caption="Retrieving help for emerge">
# <i>man emerge</i>
# <i>emerge --help</i>
</pre>

</body>
</subsection>
<subsection>
<title>The Portage Tree</title>
<body>

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

<pre caption="Viewing the Portage Tree">
# <i>cd /usr/portage; ls --classify</i>
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/
</pre>

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

<pre caption="Viewing a category">
# <i>cd app-office; ls --classify</i>
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/
</pre>

<p>
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 <c>openoffice</c>
package:
</p>

<pre caption="Viewing a package">
# <i>cd openoffice; ls --classify</i>
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
</pre>

<p>
In the example directory, four ebuilds are stored. An <e>ebuild</e> 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.
</p>

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

<p>
Inside the <path>files</path> 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.
</p>

<pre caption="Viewing the extra files">
# <i>cd files; ls --classify</i>
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
# <i>cd 1.1.0; ls --classify</i>
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
nptl.patch
</pre>

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

</body>
</subsection>
<subsection>
<title>Search for a Package</title>
<body>

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

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

<pre caption="Showing information about mozilla">
# <i>emerge search mozilla</i>
Searching...   
[ Results for search key : mozilla ]
[ Applications found : 5 ]
<comment>(Some output removed to improve readability)</comment>
*  net-www/mozilla
      Latest version available: 1.5-r1
      Latest version installed: 1.4-r3
      Size of downloaded files: 29,153 kB
      Homepage:    http://www.mozilla.org
      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
      Homepage:    http://www.mozilla.org/projects/firebird/
      Description: The Mozilla Firebird Web Browser
<comment>(...)</comment>
</pre>

<p>
If you want to include a search through the descriptions too, use the
<c>--searchdesc</c> argument:
</p>

<pre caption="Search through the descriptions too">
# <i>emerge --searchdesc mozilla</i>
Searching...   
[ Results for search key : mozilla ]
[ Applications found : 10 ]
<comment>(Some output removed to improve readability)</comment>
*  dev-libs/nss-3.8
      Latest version available: 3.8
      Latest version installed: 3.8
      Size of downloaded files:  2,782 kB
      Homepage:    http://www.mozilla.org/projects/security/pki/nss/
      Description: Mozilla's Netscape Security Services Library that implements PKI support
</pre>

<p>
As you can see, the output of <c>emerge</c> 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.
</p>

<p>
Do you see something else? Yes, <e>downloaded files</e>. 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
<path>/usr/portage/distfiles</path> to see if the necessary files are already
available. If not, it downloads the necessary files and places them in that
directory.
</p>

</body>
</subsection>
<subsection>
<title>Viewing the ChangeLog</title>
<body>

<p>
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 <c>emerge</c> too. Use the
<c>--pretend --changelog</c> (<c>-pl</c> in short) options. As an example we
will view the ChangeLog entries for <c>gnumeric</c>:
</p>

<pre caption="Viewing the ChangeLog entries for gnumeric">
# <i>emerge --pretend --changelog gnumeric</i>
<comment>(Some output removed to improve readability)</comment>
*gnumeric-1.2.2

  27 Nov 2003; foser &lt;foser@gentoo.org&gt; gnumeric-1.2.2.ebuild :
  New release, requested in #34492
  updated deps

  12 Nov 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.2.0.ebuild:
  Marked stable on sparc, fixes bug #32405.

  14 Oct 2003; Jason Wever &lt;weeve@gentoo.org&gt; gnumeric-1.0.8.ebuild:
  Added ~sparc keyword.  Fixes bug #31150.
</pre>

</body>
</subsection>
</section>
<section>
<title>Updating Portage</title>
<subsection>
<title>Introduction</title>
<body>

<p>
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.
</p>

<p>
There are several ways to update your Portage Tree. The most popular method is
by using one of our <uri link="/main/en/mirrors.xml">rsync mirrors</uri>.
Another one is by using a Portage snapshot (in case a firewall or unavailability
of a network prohibits the use of the rsync server).
</p>

</body>
</subsection>
<subsection>
<title>Selecting a Mirror for rsync</title>
<body>

<p>
It is advisable to first select a fast <uri
link="/main/en/mirrors.xml">mirror</uri> close to you. You can do this manually
(by setting the <c>SYNC</c> variable in <path>/etc/make.conf</path>) or use
<c>mirrorselect</c> to do this for you automatically. As the <c>SYNC</c>
variable will be discussed later on, we will focus on using <c>mirrorselect</c>.
First install <c>mirrorselect</c> by emerging it:
</p>

<pre caption="Installing mirrorselect">
# <i>emerge --usepkg mirrorselect</i>
</pre>

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

<pre caption="Running mirrorselect">
# <i>mirrorselect -a -s3</i>
</pre>

</body>
</subsection>
<subsection>
<title>Updating Portage</title>
<body>

<p>
To update Portage using rsync, simply run <c>emerge sync</c>:
</p>

<pre caption="Updating Portage using emerge sync">
# <i>emerge sync</i>
</pre>

<p>
If this fails (due to network problems, or a firewall), you can try using
<c>emerge-webrsync</c> which will download a Portage Tree snapshot using
<c>wget</c>. 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.
</p>

<pre caption="Updating Portage using emerge-webrsync">
# <i>emerge-webrsync</i>
</pre>

</body>
</subsection>
</section>
<section>
<title>Maintaining Software</title>
<subsection>
<title>Building or Prebuilt?</title>
<body>

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

<p>
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 <uri
link="http://www.kde.org">KDE</uri>, <uri
link="http://www.openoffice.org">OpenOffice.org</uri>, etc.). By building the
package, you can use the <c>USE</c> setting to tweak the package to your system.
Of course, you can also define high optimization options (in the <c>CFLAGS</c> 
and <c>CXXFLAGS</c> variables) to compile the package with.
</p>

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

<p>
As previously stated, prebuilt packages are stored in the
<path>/usr/portage/packages/All</path> directory, while the source code of the
packages is placed in <path>/usr/portage/distfiles</path>. 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).
</p>

</body>
</subsection>
<subsection>
<title>Installing Software from Sources</title>
<body>

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

<pre caption="Building gnumeric">
# <i>emerge gnumeric</i>
</pre>

<p>
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
<c>--pretend</c> option (<c>-p</c> in short):
</p>

<pre caption="Pretending to build gnumeric">
# <i>emerge --pretend gnumeric</i>
</pre>

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

<pre caption="Fetching sources for gnumeric">
# <i>emerge --fetchonly gnumeric</i>
</pre>

<p>
If you want to see where <c>emerge</c> downloads the sources from, combine the
<c>--fetchonly</c> and <c>--pretend</c> options:
</p>

<pre caption="Showing URLs of the sources for gnumeric">
# <i>emerge --fetchonly --pretend gnumeric</i>
</pre>

<p>
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:
</p>

<pre caption="Installing a specific gnumeric version">
# <i>emerge "&lt;gnumeric-1.2"</i>
</pre>

<p>
Other possibilities are of course "&gt;" (later version) and "=" (the exact
version).
</p>

</body>
</subsection>
<subsection>
<title>Installing Prebuilt Packages</title>
<body>

<p>
When you want to install a prebuilt package, you should use the <c>--usepkg</c>
option (<c>-k</c> in short). This will use the binary package available in
<path>/usr/portage/packages/All</path> <e>if</e> the package and the version of
the application you want to install match.
</p>

<pre caption="Installing a prebuilt package for gnumeric">
# <i>emerge --usepkg gnumeric</i>
</pre>

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

<pre caption="Installing the prebuilt package for gnumeric">
# <i>emerge --usepkgonly gnumeric</i>
</pre>

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

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

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

<pre caption="Downloading and installing a prebuilt package for gnumeric">
# <i>emerge --getbinpkg gnumeric</i>
</pre>

<p>
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 <c>--pretend</c> option 
(<c>-p</c> in short):
</p>

<pre caption="Pretending to download the prebuilt packages for gnumeric">
# <i>emerge --getbinpkg --pretend gnumeric</i>
</pre>

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

<pre caption="Installing a prebuilt package without using local information">
# <i>emerge --getbinpkgonly gnumeric</i>
</pre>

<p>
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:
</p>

<pre caption="Installing a specific gnumeric version">
# <i>emerge --usepkg "&lt;gnumeric-1.2"</i>
</pre>

<p>
Other possibilities are of course "&gt;" (later version) and "=" (the exact
version).
</p>


</body>
</subsection>
<subsection>
<title>Working with Dependencies</title>
<body>

<p>
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 <c>emerge</c>
and dependencies.
</p>

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

<pre caption="Show all dependencies of gnumeric">
# <i>emerge --emptytree --pretend gnumeric</i>
</pre>

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

<pre caption="Installing gnumeric without taking care of the dependencies">
# <i>emerge --nodeps gnumeric</i>
</pre>

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

<pre caption="Installing the dependencies of gnumeric">
# <i>emerge --onlydeps gnumeric</i>
</pre>

<p>
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 <c>emerge depclean</c>. 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.
</p>

<warn>
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!
</warn>

<pre caption="Listing and removing the orphaned dependencies">
# <i>emerge -p depclean</i>
<comment>(After seriously verifying the list, remove the orphaned dependencies)</comment>
# <i>emerge depclean</i>
</pre>

</body>
</subsection>
<subsection>
<title>Updating your System</title>
<body>

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

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

<p>
If you want to update the system packages, use the <c>--update</c> option
(<c>-u</c> in short):
</p>

<pre caption="Updating the system packages">
# <i>emerge --update system</i>
</pre>

<p>
An identical approach can be used for the world packages:
</p>

<pre caption="Updating your entire system">
# <i>emerge --update world</i>
</pre>

<p>
Again, if you want to see what <c>emerge</c> wants to update, use the
<c>--pretend</c> option together with the <c>--update</c> option:
</p>

<pre caption="Pretending to update your entire system">
# <i>emerge --pretend --update world</i>
<comment>(Some output removed to improve readability)</comment>
[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] 
</pre>

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

<ul>
  <li>
    <e>B</e> (blocks) The package listed to the left is blocking the emerge of
    the package listed to the right
  </li>
  <li>
    <e>N</e> (new) The package is new to your system and will be emerged for the
    first time
  </li>
  <li>
    <e>R</e> (replace) The package isn't new, but will be reemerged
  </li>
  <li>
    <e>F</e> (fetch) The package requires that you download the source code
    manually (for instance due to licencing issues)
  </li>
  <li>
    <e>U</e> (update) The package already exists on your system but will be
    upgraded
  </li>
  <li>
    <e>UD</e> (downgrade) The package already exists on your system but will be
    downgraded
  </li>
</ul>

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

<pre caption="Upgrading your entire system, including all dependencies">
# <i>emerge --update --deep world</i>
</pre>

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

</body>
</subsection>
<subsection>
<title>Removing Software</title>
<body>

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

<pre caption="Uninstalling software">
# <i>emerge unmerge gnumeric</i>
</pre>

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

<pre caption="Pretending to uninstall software">
# <i>emerge --pretend unmerge gnumeric</i>
</pre>

<warn>
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
<e>system</e>, i.e. a core application necessary for the correct functioning of
your system!
</warn>

<p>
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 <c>!mtime</c>, <c>!empty</c>, and <c>cfgpro</c>
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:
</p>

<ul>
  <li>
    <c>!mtime</c> : The listed file has been changed since it was installed,
    probably by you or some tool
  </li>
  <li>
    <c>!empty</c> : The listed directory is not empty
  </li>
  <li>
    <c>cfgpro</c> : This file is located inside a protected directory and will
    not be touched for safety
  </li>
</ul>

</body>
</subsection>
</section>
<section>
<title>Working with Masked Packages</title>
<subsection>
<title>ARCH or not?</title>
<body>

<p>
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 <c>KEYWORDS</c> 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.
</p>

<table>
<tr>
  <th>Flag</th>
  <th>Description</th>
</tr>
<tr>
  <ti>ARCH</ti>
  <ti>Known to work well on the given architecture</ti>
</tr>
<tr>
  <ti>~ARCH</ti>
  <ti>
    Probably works well but needs some further testing on the given
    architecture
  </ti>
</tr>
<tr>
  <ti>-ARCH</ti>
  <ti>Known not to work on the given architecture</ti>
</tr>
<tr>
  <ti>-*</ti>
  <ti>Known not to work or being extremely dangerous on any architecture</ti>
</tr>
</table>

<p>
Let's take a look at an example:
</p>

<pre caption="Example KEYWORDS setting">
KEYWORDS="x86 -sparc ~alpha ~ppc"
</pre>

<p>
This example can be read as follows:
</p>

<ul>
  <li>
    The ebuild works well on the x86 architecture
  </li>
  <li>
    The ebuild doesn't work on the sparc architecture
  </li>
  <li>
    The ebuild probably works on the alpha architecture but needs more testing
  </li>
  <li>
    The ebuild probably works on the ppc architecture but needs more testing
  </li>
  <li>
    The ebuild might work on the other architectures but hasn't been tried yet
  </li>
</ul>

<p>
Your system will use <e>ARCH</e> 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 <uri
link="http://bugs.gentoo.org">bugs.gentoo.org</uri>, then you can opt to use
<e>~ARCH</e> packages. To "move" your system to a <e>~ARCH</e>-using system,
edit the <c>ACCEPT_KEYWORDS</c> variable in <path>/etc/make.conf</path> so that
it reads <e>~ARCH</e> (again: for x86-based systems: <e>~x86</e>, etc.).
</p>

<p>
Note though that it is far from simple (or even impossible) to go back to
<e>ARCH</e> from <e>~ARCH</e>. 
</p>

<p>
If you want to update your system now, you will notice that <e>a lot</e> of
packages will be updated!
</p>

</body>
</subsection>
<subsection>
<title>Masked Packages</title>
<body>

<p>
When you want to install a package, you might come across the following message:
</p>

<pre caption="Message about masked packages">
Calculating dependencies   
!!! <comment>all ebuilds that could satisfy </comment>&lt;your package&gt;<comment> have been masked.</comment>
</pre>

<p>
A package can be masked due to several reasons: 
</p>

<ol>
  <li>The package is in <e>~ARCH</e> while you use <e>ARCH</e></li>
  <li>The package is hard-masked explicitly</li>
  <li>The package isn't available for your ARCH entirely</li>
  <li>The package is masked by your profile</li>
</ol>

<p>
Portage will inform you why a certain package cannot be installed:
</p>

<ul>
  <li>
    <b>~arch keyword</b>: 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
  </li>
  <li>
    <b>-arch keyword</b>: the package is known not to work on the given 
    architecture
  </li>
  <li>
    <b>-* keyword</b>: the package is known not to work on any architecture
  </li>
  <li>
    <b>package.mask</b>: the package is listed in the <path>package.mask</path>
    file, meaning that it breaks something, crashes your system, has severe
    security issues or worse
  </li>
  <li>
    <b>profile</b>: the package is not available for your profile
  </li>
</ul>

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

<pre caption="Accepting the ~ARCH version of a package">
<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
# <i>mkdir /etc/portage</i>

# <i>echo "app-office/gnumeric ~x86" &gt;&gt; /etc/portage/package.keywords</i>
# <i>emerge gnumeric</i>
</pre>

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

<pre caption="Accepting the -arch or -* version of a package">
<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
# <i>mkdir /etc/portage</i>

# <i>echo "app-office/gnumeric -x86" &gt;&gt; /etc/portage/package.keywords</i>
<comment>(or)</comment>
# <i>echo "app-office/gnumeric -*" &gt;&gt; /etc/portage/package.keywords</i>
# <i>emerge gnumeric</i>
</pre>

<p>
If you only want to allow the merging of such a package for a specific version
or version range, you can use the "&lt;, &lt;=, =, &gt;= or &gt;" operands:
</p>

<pre caption="Accepting a specific ~arch-marked version of a package">
# <i>echo "=app-office/gnumeric-2.0 ~x86" &gt;&gt; /etc/portage/package.keywords</i>
</pre>

<p>
A package is masked due to <b>package.mask</b> if it is listed in
<path>/usr/portage/profiles/package.mask</path>. 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
<path>/etc/portage/package.unmask</path> file and list the package in it (use
the same format as is used in <path>/usr/portage/profiles/package.mask</path>).
</p>

<pre caption="Unmasking a hard-masked application">
<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
# <i>mkdir /etc/portage</i>

# <i>echo "=app-office/gnumeric-1.2.12" &gt;&gt; /etc/portage/package.unmask</i>
</pre>

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

<p>
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.
</p>

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

<pre caption="Hard-masking a package">
<comment>(Create the /etc/portage directory if it doesn't exist yet)</comment>
# <i>mkdir /etc/portage</i>

# <i>echo "&gt;app-office/gnumeric-1.2.10" &gt;&gt; /etc/portage/package.mask</i>
</pre>

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

<p>
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
(<path>/etc/make.profile</path>).
</p>

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

<p>
You will find more information in our <uri
link="/proj/en/releng/docs/cascading-profiles.xml">Cascading Profiles
Document</uri>.
</p>

</body>
</subsection>
<subsection>
<title>Blocked Packages</title>
<body>

<p>
You have a situation when you receive the following error on your screen:
</p>

<pre caption="Blocking package">
[blocks B     ] gnome-base/bonobo-activation (from pkg gnome-base/libbonobo-2.4.0) 
</pre>

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

<pre caption="Resolving a blocking situation">
# <i>emerge unmerge bonobo-activation</i>
</pre>

</body>
</subsection>
</section>
</sections>