3.1 A Portage introduction¶

Welcome to Portage¶

With its high flexibility and enormous amount of features Portage can be seen as the best software management tool available for Linux. Portage is written in Python and Bash.

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.

The Portage tree¶

Ebuilds¶

When we talk about packages, we often mean software titles that are available to Calculate 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 and /var/lib/layman/calculate by default. The second path leads to Calculate overlay, also containing ebuilds.

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. Updating is fairly simple as the emerge command provides a front-end for rsync:

emerge --sync

If you are unable to perform 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:

emerge-webrsync

While updating the Portage tree, don't forget do update the calculate overlay. Our overlay is stored on Git; you can launch its update with the layman tool:

layman -s calculate

One command is enough to update both the Portage tree and the overlay, as well as the eix database:

eix-sync

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:

emerge --search pdf

If you want to search through the descriptions as well you can use the --searchdesc (or -S) switch:

# emerge --searchdesc pdf
Searching...    
[ Results for search key : firefox ]
[ Applications found : 10 ]

*  www-client/firefox
      Latest version available: 3.6.13
      Latest version installed: [ Not Installed ]
      Size of files: 59,577 kB
      Homepage:      http://www.mozilla.com/firefox
      Description:   Firefox Web Browser
      License:       || ( MPL-1.1 GPL-2 LGPL-2.1 )
...

There are other tools designed to automate or to make faster standard tasks such as searching through the Portage tree, listing all installed package by category, etc. For a rapid search of a package, use eix. For example, to look for the firefox browser enter:

eix firefox

Or if you need to view all packages that contain browser in their description:

eix -S browser

Installing software¶

Once you've found a software title to your liking, you can easily install it with emerge. For instance, to install 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 will handle it. If you want to find out what Portage would install when you ask it to install a certain package, add the -p or the --pretend switch. Here is an example:

emerge -p 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 /var/calculate/remote/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 -f or the --fetchonly option to the emerge command:

emerge -f gnumeric

Finding package documentation¶

Many packages come with their own documentation. Sometimes, the doc USE flag determines whether the package documentation should be installed or not. You can check the existence of a doc USE flag with emerge -vp <package name>. For instance:

emerge -vp eselect
[ebuild   R    ] app-admin/eselect-1.2.11  USE="bash-completion -doc" 0 kB

You can enable or disable the doc USE flag either globally, in /etc/portage/make.conf/custom, or only for some packages, by creating a file in the /etc/portage/package.use directory and specifying the flag there. For more information, please refer to the USE flags section.

When you have installed a package, its documentation is generally found in a subdirectory named after the package under the /usr/share/doc directory. You can also list all installed files with the equery tool. Here are some examples:

# ls -l /usr/share/doc/eselect-1.2.11
total 48
-rw-r--r-- 1 root root   296 Jan 26 21:36 AUTHORS.bz2
-rw-r--r-- 1 root root 14202 Jan 26 21:36 ChangeLog.bz2
-rw-r--r-- 1 root root  5320 Jan 26 21:36 developer-guide.txt.bz2
-rw-r--r-- 1 root root  3837 Jan 26 21:36 NEWS.bz2
-rw-r--r-- 1 root root   541 Jan 26 21:36 README.bz2
-rw-r--r-- 1 root root   703 Jan 26 21:36 release-guide.txt.bz2
-rw-r--r-- 1 root root   471 Jan 26 21:36 TODO.bz2
-rw-r--r-- 1 root root  2067 Jan 26 21:36 user-guide.txt.bz2

# equery f eselect | less
/usr
/usr/bin
/usr/bin/bashcomp-config
/usr/bin/eselect
...

Removing a package¶

When you want to remove a software package from your system, use emerge -C (or 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.

Note that 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.

emerge -C 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 -c (or emerge --depclean). 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 and overlay you first have to update them. When your Portage tree is updated, you can update your system with emerge -u world. In the next example, we'll also use the -a or the --ask switch which will tell Portage to display the list of packages it wants to upgrade and ask you if you want to continue:

emerge -ua 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 (the applications listed in /var/lib/portage/world), but will not check their dependencies. If you want to update every single package on your system, add the -D (or --deep) argument:

emerge -uDa world

Since security updates also happen in packages that are pulled in as dependencies of other programs, it is recommended to run this command once in a while.

If you have altered any of your USE flags lately you might want to add -N (or --newuse) as well. Portage will then verify if the change requires the installation of new packages or recompilation of existing ones:

emerge -uDNa world

Metapackages¶

Some packages in the Portage tree do not have any real content but are used to install a collection of packages. For instance, the kde-meta 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 will not have much effect as the dependencies remain on the system.

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 -c (or 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 anymore.

All this is handled with the following three commands:

emerge -uDNa world
emerge -ca
revdep-rebuild

When Portage is complaining...¶

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 into 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 virtual/syslog.

Software in the Portage tree can reside in different branches. By default your system only accepts packages that are deemed 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.

Blocked packages¶

Here is an example of Portage warning about blocked packages (with --pretend):

[blocks B     ] mail-mta/ssmtp (is blocking mail-mta/postfix-2.2.2-r1)
...
!!! Error: the mail-mta/postfix 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 postfix or to remove ssmtp first.

It is also possible that two packages that are yet to be installed are blocking each other. In this rare case, you should find out why you need to install both. In most cases you can do with one of the packages alone.

Masked packages¶

Here is an example of masked packages warning:

!!! all ebuilds that could satisfy "bootsplash" have been masked.

Portage warning about masked packages and explaining the 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-2.3.4.20040808 (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 the 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 the bugzilla website.
package.mask means that the package has been found corrupt, unstable or worse and has been deliberately marked.
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.

Missing dependencies¶

If a dependency is missing, the warning you get will look like this:

emerge: there are no ebuilds to satisfy ">=sys-devel/gcc-3.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¶

In case of an ambiguous ebuild name, you will see something like this:

!!! The short ebuild name "aterm" is ambiguous.  Please specify
!!! one of the following fully-qualified ebuild names instead:

    dev-libs/aterm
    x11-terms/aterm

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.

Circular dependencies¶

This is how Portage informs 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 update the Portage tree after a while and try again. You can also check bugzilla if the issue is known and if not, report it.

Fetch failed¶

When Portage witnesses a fetch fail, you see something like that:

!!! 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¶

Here is an example of warning that Portage returns when a package has system profile protection:

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