An Introduction to Portage

Updated 25 October 2019

Welcome to Portage

Portage is one of the best software management tools available in Linux, due to its high flexibility and extremely rich features. Portage is written on Python and Bash.

Most users will use the emerge command to interact with Portage. Please note, however, that this doc does not cover all of the emerge man page. All available options of the emerge command can be viewed here.

Portage tree

Ebuild files

When speaking of packages, we often refer to software available to Calculate users through the Portage tree. The Portage tree is a set of ebuild files containing all the information that Portage needs to manage the software (for installation, search, extraction, etc.) By default, the ebuilds are located in /usr/portage/ and /var/lib/layman/calculate/. The second path points to the Calculate overlay, which also contains ebuilds.

When dealing with a package, Portage refers to its ebuild file, to be found on the system. Therefore, it is essential to regularly update the ebuilds, so that Portage stays aware of new software, security updates, etc.

Updating the Portage tree

The Portage tree is updated with the git command and runs whenever cl-update is called. To update the Portage tree without actually installing packages, run the following:

Software maintenance

Search

To search software in the Portage tree by name, you can use the built-in features of the emerge command. By default, emerge --search outputs the packages that match (either completely or partially) the specified search criteria.

For example, if you want to find all the packages that have "pdf " in their name, run the following:

In addition, the --searchdesc (or -S) parameter can be used to search in the package description.

Tools exist that can help Portage run faster and make automatic routine tasks such as searching the Portage tree, listing installed packages that belong to a category, etc. Use eix to perform a quick package search. To learn more, please refer to the manual.

Install

Once you have found an application that suits your needs, you can easily install it with emerge. Here is an example for app-office/gnumeric:

Since many applications depend on each other, any attempt to install new software may involve installing additional packages. Keep calm and trust Portage. If you absolutely want to know what exactly Portage is going to install with the package you need, run the command with the -p (or --pretend) option. Such as in:

Once Portage has received the command to install the package, it downloads the necessary source code from the Internet (if necessary), and saves it by default in /var/calculate/remote/distfiles/. The package is then extracted, compiled and installed. If you only want Portage to download the source code without installing the package, use the -f (or --fetchonly) option with emerge:

Documentation

Many packages provide their own documentation. Sometimes, you can use the "doc" USE flag to define whether to install the package documentation. To check the status of this USE flag', run emerge -pv <name_package>.

Example:

Local copy of remote index is up-to-date and will be used.

These are the packages that would be merged, in order:

Calculating dependencies  ... done!
[binary   R    ] app-admin/eselect-1.4.13::gentoo  USE="-doc -emacs -vim-syntax" 86 KiB

Total: 1 package (1 reinstall, 1 binary), Size of downloads: 86 KiB

You can enable or disable the 'doc' USE flag either globally in /etc/portage/make.conf/custom or per package, by creating a file in /etc/portage/package.use/ and managing the USE flag inside. To learn more, see the USE flags section.

Documentation from the newly installed package can usually be found in the corresponding subdirectory of /usr/share/doc/.

Example:

итого 56
-rw-r--r-- 1 root root   309 фев 25 01:40 AUTHORS.bz2
-rw-r--r-- 1 root root 18961 фев 25 01:40 ChangeLog.bz2
-rw-r--r-- 1 root root  5373 фев 25 01:40 developer-guide.txt.bz2
-rw-r--r-- 1 root root  5062 фев 25 01:40 NEWS.bz2
-rw-r--r-- 1 root root   799 фев 25 01:40 README.bz2
-rw-r--r-- 1 root root   689 фев 25 01:40 release-guide.txt.bz2
-rw-r--r-- 1 root root   471 фев 25 01:40 TODO.bz2
-rw-r--r-- 1 root root  2088 фев 25 01:40 user-guide.txt.bz2

You can also list all the installed files with the equery command, as shown below.

Example:

/usr
/usr/bin
/usr/bin/eselect
/usr/bin/kernel-config
/usr/bin/profile-config
/usr/bin/rc-config
/usr/share
/usr/share/bash-completion
/usr/share/bash-completion/completions
/usr/share/bash-completion/completions/eselect
/usr/share/doc
/usr/share/doc/eselect-1.4.13
...

Remove

To remove a package from your system, use emerge -C (or --unmerge). This will remove all files installed by the package, except for the configuration files of the application that have been modified after installation. Saving configuration files allows you to smoothly return to the package if you ever decide to install it again.

Whenever you remove a package, its dependencies remain on the system. For Portage to detect all the packages you once needed that can now be removed, use the emerge -c (or --depclean) command. We shall get back to that later.

You can also delete a package by running emerge -cv (--depclean --verbose). In this case, the package manager will only delete the package if it has no dependencies. If any, those will be displayed. Example:

Calculating dependencies... done!
  www-client/firefox-67.0 pulled in by:
    www-plugins/firefox-ublock-1.19.3.11 requires www-client/firefox

>>> No packages selected for removal by depclean
Packages installed:   1189
Packages in world:    203
Packages in system:   43
Required packages:    1189
Number removed:       0

www-client/firefox was not removed, as it depends on the www-plugins/firefox-ublock package, still installed. Delete both of the packages, as shown below:

System update

To ensure that your system is well maintained (not to mention the latest security fixes), you need to update it regularly. Since Portage only sees the ebuild files in the local Portage tree and overlay, you need to update them first. Once the Portage tree has been updated, you can update the whole system by running emerge -u world. In the following example, we also use the -a (--ask) option, which tells Portage to display the list of packages before proceeding to update and ask the user if they want to continue:

Portage will look for newer versions of the installed applications. But it will only check up for applications that you installed, and not the dependencies of those. If you want each package to update, add the -D (--deep) option:

Since security-related updates also apply to packages that were installed as dependencies, it is recommended to run this command from time to time.

If you edited USE flags, you may also want to add the -N (--newuse) option later on. Then Portage will check if this modification requires installing new packages or recompiling existing ones:

Calculate Linux comes with the cl-update tool, specially designed for easier system update. The utility will update Portage, install the update, and finally remove unused dependencies. To update, run:

Meta-packages

Some packages in the Portage Tree do not have any content as such, as they are an alias used to install a set of other packages. For example, the 'kde' package installs the full KDE environment on your desktop, as a set of KDE packages depend on it.

If you ever want to remove such a package, running emerge --unmerge will not have the desired effect because the packages it depends on will remain in the system.

With Portage, it is possible to remove residual dependencies, but as dependencies change over time, the first thing you need to do is to update the entire system, including the modifications of USE flags. Now run emerge -c (or--depclean) to remove the remaining dependencies. Once this is completed, you will have to rebuild the applications that were dynamically linked to the remote packages they no longer need.

Only three commands are necessary to do this:

When Portage sends an error message

Slots, virtuals, branches, architectures and profiles

As already mentioned, Portage is an extremely powerful engine, supporting many features that other software management tools lack. So it becomes more clear, here are a few aspects of Portage, without going into details.

With Portage, multiple versions of a package can co-exist on a system. While other package management solutions name packages according to their version (e.g. freetype and freetype2), Portage uses slot (SLOT), or area concept. A package allocates a specific slot for its version. Multislot packages can co-exist on a system. For instance, media-libs/freetype has an ebuild both with SLOT="1" and SLOT="2".

There are also packages that do the same but differ in implementation. For instance, metalogd, sysklogd and syslog-ng are system logging services. Applications using the system log cannot depend on one particular software, e.g. metalogd, as other tools are as good. Portage features virtual packages: as each journaling service provides a virtual/syslog, applications can be virtual/syslog-dependent.

Software is found in different branches of the Portage tree. By default, only stable packages are allowed. Most of the new software is included in the test branch when added, thus underlining that additional testing is needed before the software can be considered as stable. Though ebuild files are shown for such applications, Portage will not update them before they have been marked as stable.

Some software is not available for all architectures. They either do not work on some architectures, or need more testing, or else the developer cannot check if the package works on different architectures.

Each Gentoo installation follows a specific profile, which includes (but is not limited to) a list of packages required to keep the system up and running.

Blocked packages

Here is an example of 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.

Ebuild files have fields to tell Portage about the dependencies. Two types of dependencies are possible: the build dependency declared in the DEPEND variable and the execution dependence declared in the RDEPEND variable. When one of these dependencies is obviously indicating that a package or virtual is incompatible, it blocks the package.

To unblock, either do not install the package at all or previously remove the conflicting package. In the example above, you can either choose to not install mail-mta/postfix after all, or remove mail-mta/ssmtp first.

Two packages to be installed may also be blocking each other. In this rare case, you should consider whether you really need to install both packages: in most cases, one does the job.

Masked packages

Here is an example of warning message (masked packages):

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

Here is an example of warning message (masked packages and reason for masking them):

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

Whenever you are trying to install a package that is not intended for your system, a masking error is reported. Try installing another application that is available for your system or wait for the package to become available. A package is always masked for a reason:

• ~arch key: the package has not been tested well enough to be moved to the stable branch. Wait a few days or weeks and try again.
• -arch+ or -* means that the package is broken for your architecture. If you think it works, please report the bug.
• No key means that the package has not yet been tested for your architecture. Ask the porting team to check the package, or test it for them and report your findings to Bugzilla.
• package.mask means that package failure, instability or worse was detected, so that the package was masked on purpose.
• profile means that the package is not intended for use with your profile. If installed, it may cause a system failure or is simply incompatible with the profile you are using.

Unavailable packages

Here is an example of absent package error message:

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 on your system. Please check for it on Bugzilla. If the bug has not been reported yet, do report it yourself. If you are not mixing branches, this is clearly an error.

Ambiguous package name

Here is an example of warning about the redundant ebuild names:

!!! 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 name of the application you are going to install matches more than one package. You also have to specify the category. Portage will come up with possible solutions.

Circular dependencies

Here is an example of a circular dependency error message:

!!! 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 are cross-dependent, and therefore cannot be installed. This is most likely an error in the Portage tree. Update the Portage tree later and try again. You can also check Bugzilla and report the bug if it has not been reported yet.

Unpacking error

Here is a example of extraction error message:

!!! Fetch failed for sys-libs/ncurses-5.4-r5, continuing...
(...)
!!! Some fetch errors were encountered.  Please see above for details.

Portage was unable to fetch the source code for this software and will attempt to resume the installation process (if any other packages are planned to be installed). This can happen if the mirror failed to synchronize or if the ebuild points to a wrong location. The server hosting the source code may also be down for some reason.

Retry an hour later.

System profile protection

Here is an example of warning about a profile-protected package:

!!! Trying to unmerge package(s) in system profile. 'sys-apps/portage'
!!! This could be damaging to your system.

You told Portage to remove the package that is part of your basic package set. It is marked as mandatory in your profile and may not be removed from your system.