Chapter 9. Software Management

Table of Contents

Gentoo Portage
Introduction
Package Management: Portage
Package Structure: Ebuilds
USE Flags
Maintaining your Software Stack
Obtaining the Latest Portage Tree
Getting Gentoo News
Querying for Software
Enabling Installation Logs
Installing New Software
Updating your System
Uninstalling Software
Advanced Software Management
Package States
Unmasking Packages
Switching System Profiles
Using Third Party Software Repositories
When Things Go Wrong
Portage Refuses To Install A Package
Resolving Build Failures
Changing Configuration Files
Configuration File Updates
dispatch-conf
Modifying Build Decisions
Languages
Video Cards
Compiler Directives
Portage Behaviour
Specific software choices
Fixing Postinstall Problems
Dynamic Linking Inconsistency
Exercises

Gentoo Portage

In this section, we describe how to install software on Gentoo and what Gentoo's Portage and Portage tree are. This chapter is very Gentoo-specific - in fact, if you're not using Gentoo or a Gentoo-derived Linux distribution, you'll find most of this chapter entertaining yet not usable. If you are in this scenario, please do check the documentation of your distribution: software management is a part of a distributions' responsibilities which isn't standard(ised) in the free software community yet (because there are so many different ways, policies, politics and functionalities).

I'm also not saying standardisation here is needed right now - the functionalities offered by the various distributions are too different to make standardisation possible at this point.

Introduction

Gentoo is primarily a source-code based Linux distribution. This means that, unlike most operating systems (including other Linux distributions), Gentoo does not just place compiled files on your file system but actually fetches the source code for the software you need from the Internet, configures the compilation environment and builds the software before it finally moves the resulting build onto the file system.

Of course, Gentoo does support binary package installations, and this on two levels:

  1. Software titles that would take a very long time to build on a users' system (such as the popular LibreOffice.org office suite) are available as binary packages. In this case, Gentoo downloads the binary files and installs those on the file system.

  2. Prebuilt packages are supported as well: software built on a different Gentoo system, stored in a binary format file and made available to other Gentoo systems with the same settings (otherwise the binary packages might not be compatible with the system).

The second level is a more advanced approach as Gentoo doesn't provide binary packages itself - you'll need to create and maintain a build environment yourself or use a third-party repository. As such, I am going to focus on source-code installations and the first binary package level (which is automatically supported).

Package Management: Portage

The software that is responsible for managing installed software is called a package manager. It is the interface to the user to install and uninstall software, upgrade the system, search through the available software and help with the configuration of the various software titles.

For Gentoo, the default package manager is called Portage. I say "default" because there are other package managers available for Gentoo as well (like Paludis and pkgcore). These other package managers generally have the same features, but behave a bit differently. They are all compatible though, thanks to a standard approach to the packaging structure Gentoo uses.

The package manager manages a local package repository called the Portage tree. This package repository is a set of package metadata (so no source code or binary package) about software that can be installed on Gentoo.

You can find the Portage tree at /usr/portage.

Package Structure: Ebuilds

The package metadata files are called ebuilds. Ebuilds contain information about the package:

  • the name of the package, the internet site where you can find information about the software and the version of the software package

  • the dependencies of the package (what other software is needed in order to successfully build or run this software)

  • the location where the software source code (or binary files in case of binary packages - first level) can be downloaded from

  • the build instructions for the software (remember, Gentoo is primarily a source code based distribution)

  • the license the software uses

  • the USE flags the package supports (USE flags are described later)

  • the configuration instructions needed to finalize the installation after building and installing the software

  • ...

Because all this information is simple, the ebuild file is a text file. This allows users to easily read what an ebuild actually does (although this does require knowledge about scripting and the ebuild format itself which isn't in the scope of this chapter).

These packages are the main source for software installation and management. In order to keep track of new software releases, you will need to update the collection of ebuilds (Portage tree).

USE Flags

A USE flag is one of Gentoo's main strengths. USE flags are simple terms (such as "dvd", "X", "mysql" ...) and are used by ebuilds to detect what options you want enabled (or disabled) while building software.

Most applications have optional support for one or more tools and libraries. For instance, at the time of writing, the Mozilla Firefox application in Gentoo supports the following use flags (I dropped the various linguas flags which enable/disable support for certain language locales in the output to make it more readable):

$ equery uses firefox
[ Legend : U - final flag setting for installation]
[        : I - package is installed with flag     ]
[ Colors : set, unset                             ]
 * Found these USE flags for www-client/firefox-45.6.0:
 U I
 + + bindist              : Disable official Firefox branding (icons, name) which are not binary-redistributable according to upstream.
 - - custom-cflags        : Build with user-specified CFLAGS (unsupported)
 - - custom-optimization  : Build with user-specified compiler optimizations (-Os, -O0, -O1, -O2, -O3) from CFLAGS (unsupported)
 - - dbus                 : Enable dbus support for anything that needs it (gpsd, gnomemeeting, etc)
 - - debug                : Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
                            https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
 - - ffmpeg               : Enable ffmpeg/libav-based audio/video codec support
 - - gmp-autoupdate       : Allow Gecko Media Plugins (binary blobs) to be automatically downloaded and kept up-to-date in user profiles
 + - gstreamer            : Add support for media-libs/gstreamer (Streaming media)
 - - gstreamer-0          : Use gstreamer:0.10 instead of gstreamer:1 for media support
 + + hardened             : Activate default security enhancements for toolchain (gcc, glibc, binutils)
 + - hwaccel              : Use hardware-accelerated rendering
 + - jemalloc3            : Enable or disable jemalloc3 (forced-on when supported prior to 38.0)
 - - jit                  : Enable just-in-time compilation for improved performance. May prevent use of some PaX memory protection features in
                            Gentoo Hardened.
...

Other distributions choose what support they want enabled and what not when building the software. Because with Gentoo, you build the software yourself, you have the opportunity to enable or disable these features based on your USE flags.

You can set your global USE flags inside /etc/portage/make.conf. To disable a USE flag, prepend it with the minus sign.

# nano -w /etc/portage/make.conf
(...)
USE="acpi apm pmu sasl howl -cdr -dvdread ..."

Because of the vast amount of USE flags that Gentoo supports, it is not your job to know and understand every single one of them. Gentoo is shipped with a sane default for your USE variable. To find out what your current USE flags are (based on Gentoo's default USE flags plus the USE flags you enabled or disabled in /etc/portage/make.conf), use emerge --info, filtering on the USE term:

$ emerge --info | grep USE
USE="X acl acpi alsa apache2 apm arts berkdb bitmap-fonts cairo cdr
cli cracklib crypt cscope css cups dbus dri dvd dvdr dvdread eds
emboss encode esd evo fam firefox fortran gdbm gif gnome gpm
gstreamer gtk hal howl iconv imap innodb ipv6 isdnlog java jpeg kde
kerberos ldap libwww mad maildir midi mikmod mp3 mpeg mudflap mysql
ncurses nls nptl nptlonly nsplugin odbc ogg opengl openmp oss pam
pcre pdf perl pmu png pppd python qt3 qt3support qt4 quicktime readline
reflection sasl sdl session spell spl ssl svg tcpd tetex tiff truetype
truetype-fonts type1-fonts unicode vcd vhosts vorbis win32codecs x86
xml xorg xv zlib" ALSA_CARDS="ali5451 als4000 atiixp atiixp-modem
bt87x ca0106 cmipci emu10k1 emu10k1x ens1370 ens1371 es1938 es1968
fm801 hda-intel intel8x0 intel8x0m maestro3 trident usb-audio via82xx
via82xx-modem ymfpci" ALSA_PCM_PLUGINS="adpcm alaw asym copy dmix
dshare dsnoop empty extplug file hooks iec958 ioplug ladspa lfloat
linear meter mulaw multi null plug rate route share shm softvol" 
APACHE2_MODULES="actions alias auth_basic authn_alias authn_anon 
authn_dbm authn_default authn_file authz_dbm authz_default
authz_groupfile authz_host authz_owner authz_user autoindex
cache dav dav_fs dav_lock deflate dir disk_cache env expires
ext_filter file_cache filter headers include info log_config logio
mem_cache mime mime_magic negotiation rewrite setenvif speling
status unique_id userdir usertrack vhost_alias" ELIBC="glibc" 
INPUT_DEVICES="keyboard mouse" KERNEL="linux" LCD_DEVICES="bayrad
cfontz cfontz633 glk hd44780 lb216 lcdm001 mtxorb ncurses text"
LINGUAS="en nl fr de" USERLAND="GNU" VIDEO_CARDS="i810 i915 vesa"

To obtain some information on a USE flag, you can use the euse command:

$ euse --info mp3
global use flags (searching: mp3)
************************************************************
[+  D ] mp3 - Add support for reading mp3 files

local use flags (searching: mp3)
************************************************************
no matching entries found

If you want to manage USE flags on a per-package level (say you want to include MP3 support in mplayer but not in vlc) you can set per-package USE flags in /etc/portage/package.use. This location can either be a simple text file, but you can also make it a directory which contains many text files. This latter feature is very interesting if you want to manage the USE definitions more easily (say by aggregating media-related USE flag settings). Gentoo's Portage will read all files inside this directory.

# mkdir /etc/portage/package.use
# nano -w /etc/portage/package.use/media-flags
media-video/vlc mp3

Maintaining your Software Stack

With software stack maintenance, I mean installing and deinstalling software, updating your system and keeping track of the security patches for your system.

Obtaining the Latest Portage Tree

As stated before, the Portage tree is the collection of ebuilds (which we will call "packages" from now onwards) that you can install on your system. Whether you want to update your system, install new software or obtain the latest security fixes, you will first need to update your Portage tree.

The command to update the Portage tree is emerge --sync. The sync comes from synchronisation and gives you an idea on what emerge (Portage' main tool for software management) will do: it will synchronise your local Portage tree with the Portage tree available on one of Gentoo's mirrors.

# emerge --sync

You can easily configure what mirror emerge should use. For this, open up /etc/portage/repos.conf or /etc/portage/repos.conf/gentoo.org and locate the sync-type and sync-uri settings:

# nano -w /etc/portage/repos.conf/gentoo.conf
(...)
sync-type = uri
sync-uri = rsync://rsync.us.gentoo.org/gentoo-portage

The sync-uri setting is set to a public Portage mirror. In the example, sync-uri is set to a round-robin address which covers all mirrors in the United States of America. You can substitute the "us" country code with your country ("be" for Belgium, for instance) to use the round-robin address for the mirrors in your country.

You notice that the setting references the rsync protocol. Indeed, rsync is used to synchronise your local Portage tree. The tool (and protocol) has been selected because it only transfers the differences between two files rather than downloading the entire new tree.

If you cannot use rsync (for instance because of a firewall setting) you can use emerge-webrsync (without any options). This tool will fetch an archive which contains the entire Portage tree using the HTTP or FTP protocol and synchronise this archive locally. Of course, this will take more network traffic as an entire tree is downloaded.

Also, Gentoo rsync mirrors update their Portage tree hourly. The snapshots retrieved using emerge-webrsync are updated daily.

Getting Gentoo News

With an up to date Portage tree, you will also receive Gentoo's latest announcements for its users. Gentoo's news system allows Gentoo to inform its users about changes that the end user should read before blindly starting with an upgrade. This is also why I mention it before we start doing anything with software.

When a news item is added, you will be notified of this at the end of a Portage update session:

* IMPORTANT: 21news items need reading for repository 'gentoo'.
* Use eselect news to read news items.

When you find such a notice at the end of your update, you can use Gentoo's eselect tool to find out more:

# eselect news list
News items:
  [1]      2009-04-18  Generation 1 Java Setup Deprecated
  [2]      2009-07-02  (2009-07-02-kdeprefix+monolithics - removed?)
  [3]      2010-03-25  Python 3.1
  [4]      2010-08-01  (2010-08-01-as-needed-default - removed?)
  [5]      2010-10-22  Perl 5.12 upgrade procedure
  [6]      2011-04-27  Upgrade to GLIB 2.28
  [7]      2011-05-01  Baselayout update
  [8]      2011-05-22  (2011-05-22-kdeprefix - removed?)
  [9]      2011-08-28  Mesa r600 driver now defaults to gallium
  [10]     2011-10-15  Upgrade to libpng15
  [11]     2012-03-16  (2012-03-16-udev-181-unmasking - removed?)
  [12]     2012-04-24  The default JPEG implementation
  [13]     2012-05-21  Portage config-protect-if-modified default
  [14]     2012-09-09  make.conf and make.profile move
  [15]     2012-09-09  Catalyst updates
  [16]     2012-11-06  PYTHON_TARGETS deployment
  [17]     2013-01-23  (2013-01-23-udev-upgrade - removed?)
  [18]  N  2013-03-29  Upgrading udev to version >=200

You can then read the news items one by one (eselect news read <number>) but I prefer to just tell eselect to display the content of the unread news items:

# eselect news read new

Querying for Software

With tens of thousands of software titles at your fingertips, how do you know what software is available (or what software you currently have installed)? Or what about querying information about software itself (like installed or installable files, dependencies ...), even when that software is or is not installed on your system? There are quite a few tools that help you with this...

Searching for Software Using emerge

With emerge, you can query for software using --search or --searchdesc.

With emerge --search, you can look for software whose title (or part of) matches the selection you passed:

$ emerge --search acroread
Searching...  
[ Results for search key : acroread ]
[ Applications found : 2 ]
 
*  app-text/acroread
      Latest version available: 9.4.2
      Latest version installed: [ Not Installed ]
      Size of files: 121,848 kB
      Homepage:      http://www.adobe.com/products/acrobat/
      Description:   Adobe's PDF reader
      License:       Adobe

*  media-fonts/acroread-asianfonts
      Latest version available: 9.1
      Latest version installed: [ Not Installed ]
      Size of files: 5,767 kB
      Homepage:      http://www.adobe.com/products/acrobat/acrrasianfontpack.html
      Description:   Asian font packs for Adobe Acrobat Reader
      License:       Adobe

In the resulting output, you can find the (in this case two) packages that match the given selection, together with

  • the latest, installable version

  • the currently installed version (if applicable)

  • the size of the files that the installation needs to download

  • the homepage of the application (where you can usually find more information about the tool)

  • the description of the software

  • the software license

If you use --searchdesc, the search also tries to match the description fields:

$ emerge --searchdesc acrobat
Searching...  
[ Results for search key : acrobat ]
[ Applications found : 3 ]
 
*  app-admin/watchfolder
      Latest version available: 0.3.3
      Latest version installed: [ Not Installed ]
      Size of files: 93 kB
      Homepage:      http://freshmeat.net/projects/watchd/
      Description:   Watches directories and processes files, similar to the watchfolder option of Acrobat Distiller.
      License:       GPL-2

*  app-text/fdftk
      Latest version available: 6.0-r1
      Latest version installed: [ Not Installed ]
      Size of files: 5,591 kB
      Homepage:      http://www.adobe.com/devnet/acrobat/fdftoolkit.html
      Description:   Acrobat FDF Toolkit
      License:       Adobe

Running --searchdesc takes quite some time. I advise you to use an indexing tool to speed up searches...

Searching for Software Using eix

The eix tool (not available by default, you will need to install it: emerge --ask eix) indexes the searchable application information to allow you to quickly search through the portage tree.

Once installed, you will need to run eix-update (which will index all the information) after every emerge --sync (as this pulls in new packages which you want to index). You can also use eix-sync which will synchronise portage first and then update its indexing tables immediately afterwards.

Once the index is built, you can quickly search through the Portage tree using eix. I frequently use -HAS (--homepage --category-name --description) as this also matches the homepage URI next to the application name and description:

$ eix -HAS acrobat

Searching Installed Software Based on File(s)

The qfile tool (part of app-portage/portage-utils) allows you to find out which package has delivered a certain file. That can be interesting if someone is asking you which package provided that particular file at your system.

$ qfile /usr/bin/qfile
app-portage/portage-utils (/usr/bin/qfile)

Searching Software (Installed or Not) Based on File(s)

A Gentoo community project, called PortageFileList, is attempting to store information about files provided by all packages. This isn't as simple as it sounds, since the files in a package depend heavily on the user his system: USE flags, other installed packages etc. The project asks users to run one of their tools to upload the local file information (file + package + USE flags) to the server. Other users can then use the tool e-file (part of app-portage/pfl) to query for packages.

The command supports SQL-like wildcards. For instance, %bin/xdm matches /usr/sbin/xdm and /bin/xdm.

$ e-file '%bin/xdm'
 * x11-apps/xdm
      Available versions: 1.1.8 1.1.9-r0
      Description:        X.Org xdm application
      Matched files:      /usr/bin/xdm;

Okay, this one was an easy guess as well ;-)

Listing Installed Files

To list which files are provided by a package, you can use qlist (also part of app-portage/portage-utils):

$ qlist portage-utils
/usr/bin/q
/usr/bin/qatom
...
/usr/share/doc/portage-utils-0.2.1/qsync

Enabling Installation Logs

When a Gentoo developer wants to inform a package user about certain changes or things to look out for, he often puts informational messages in the package itself which are displayed the moment you've finished the installation of the package. However, for lengthy updates or installations, you often overlook these messages. For this purpose, Gentoo Portage allows you to store these messages in separate log files. By default, Portage only sets up a summary log for the installation. You can stick with those defaults, or set up a more verbose logging:

# nano /etc/portage/make.conf

PORT_LOGDIR="/var/log/portage"
PORTAGE_ELOG_SYSTEM="save"
PORTAGE_ELOG_CLASSES="info warn error log"

With this defined, you'll find per-package logs in /var/log/portage/elog. You can then read those log files with your favorite text reader (like less or view) or using elog-specific tools like elogv (console) or elogviewer (graphical).

Installing New Software

You've seen already that emerge is Gentoo's main tool to work with Portage and that it can be used to search for software. The same tool is used to install or remove software. To help users install software, it has a few options that allow you to make better informed decisions on which software to install (and what the effects will be). For instance, the --pretend option lets emerge show you what it would do, without actually modifying anything. You can even add the --verbose flag so that emerge tells you what additional settings the package supports. It also supports the --ask option which first behaves like --pretend, and then asks for confirmation to continue or not.

For instance, to install Adobe's Acrobat Reader on your system:

# emerge --ask --verbose acroread
These are the packages that would be merged, in order:

Calculating dependencies   ... done!
[ebuild  N    ] app-text/acroread-8.1.2  USE="cups ldap nsplugin" 
  LINGUAS="de en fr nl -da -es -fi -it -ja -ko -nb -pt -sv -zh_CN -zh_TW" 

Would you like to merge these packages? [Yes/No] 

Note

Sometimes it might be necessary to use the category/package-name syntax (in this case, emerge --ask --verbose app-text/acroread). This could happen when two packages share the same name but are part of different categories.

In this example, emerge tells you that it will install Adobe Acrobat Reader version 8.1.2 and that it doesn't need any other dependencies (otherwise you'll have more lines in the same line as the one you see). Emerge also tells you that the acroread package supports three USE flags:

  • cups (support for the Common Unix Printing System),

  • ldap (support for the Lightweight Directory Access Protocol) and

  • nsplugin (creating Acrobat Reader plugins for the Mozilla-based browsers)

All three flags are in this case enabled on this system.

Also, the acroread package supports various languages: de (German), en (English), fr (French), nl (Dutch), da (Danish), es (Spanish), fi (Finnish), it (Italian), ja (Japanese), ko (Korean), nb (Norwegian Bokmal), pt (Portugese), sv (Swedish), zh_CN (Simplified Chinese) and zn_TW (Taiwanese Mandarin). Of all these languages, Portage will only include support for German, English, French and Dutch (the languages I want supported on my system).

To install the software, accept the merge. This will, for every package:

  1. download the source code from the Internet,

  2. verify the source code with the checksum stored in the Portage tree (to ensure that the downloaded file isn't corrupt),

  3. extract the source code to a temporary location on the system (/var/tmp/portage),

  4. patch the source code with Gentoo-specific patches,

  5. configure the source code based on the USE flags you use,

  6. build the source code into a temporary location,

  7. register the files it has created in this location, and finally

  8. move the files to the system (making the application available to the end user)

This installation process will take some time (compared to distributions who use prebuilt packages), mainly because of the build step. There are tools that show the user how long the emerge phase of a package took in average, but these are only for informational purposes and give no guarantee whatsoever about future emerge phase durations (as this depends on USE flags, source code size, CPU speed, system resource availability ...).

qlop (part of the portage-utils package) is such a tool. In the next example, it shows the build duration averaged over 27 merges:

$ qlop --time --human firefox
firefox: 18 minutes, 24 seconds for 23 merges

Updating your System

When you are booted inside a Gentoo Linux system, many packages will already be installed. It is wise to regularly update your system by pulling in the latest updates, bugfixes and security fixes.

Updating All Installed Packages

If you want to update all installed packages to their latest, stable version, first update your Portage tree as mentioned before. Then, run the following command to see what packages will be updated, installed or removed:

# emerge --update --deep --newuse @world --pretend

The options you pass on to emerge are:

  • --update (or -u), asking emerge to update software,

  • --deep (or -D), asking emerge to select not only the software selected, but also all of its dependencies,

  • --newuse (or -N), asking emerge to update software when new dynamic switches are used (USE flags),

  • @world, asking emerge to select all software that the user has installed, and

  • --pretend (or -p), asking emerge to display what it would install, update or remove

To really perform the update, use the same command without --pretend. The next example does this using the single letter arguments:

# emerge -uDN @world

Now, if you're tired of continuously running a command with --pretend only to remove the --pretend after verifying the output, use --ask instead as we discussed before.

From now onwards, I will be using the --ask argument where appropriate.

You might have noticed that the world argument is prefixed with the at sign (@). This is not mandatory - in the past it was without - but a while ago, Portage started supporting what we call "sets" of packages. The world target is one of such sets, and sets are prefixed with an at sign to distinguish them from regular packages.

Updating All User-Installed Packages

If you don't want to upgrade every single package on your system, but only the packages you've selected to install previously, don't use the --deep argument. User installed packages are the packages you've asked to install excluding the dependencies that were pulled in to satisfy the application requirements. The end result is that only a small amount of updates is installed. However, this doesn't mean that you will quickly have outdated dependencies - every time an update is pulled in, this update might instruct Portage that it can only work with a higher version of a particular dependency, causing Portage to update that dependency as well.

# emerge --update --newuse --ask @world

Do not Stop Installing after Build Failures

By default, Gentoo Portage stops the installation / upgrade process when one package fails to build properly. Although this definitely needs some attention, you can ask Gentoo Portage to resume building the other packages first. At the end of the final build process, you will be greeted with a small report informing you which packages have failed and why.

To ask Portage to keep going after failure, use --keep-going:

# emerge -uDN --keep-going @world

Pulling Security Fixes

Gentoo also supports building the software affected by security issues alone. In this case, none of your unaffected software is upgraded (unless required as a dependency of a security upgrade). Gentoo provides GLSA (Gentoo Linux Security Advisory) documents to inform its users about possible security issues (except kernel issues). These GLSA documents are parsed by the glsa-check command which can apply the necessary fixes.

To verify if your system is affected by one or more security advisories, first update your Portage tree and then run glsa-check --test all:

# glsa-check --test all
This system is affected by the following GLSAs:
200711-10

In the example, one security advisory matches my system. I can obtain more information about the advisory using glsa-check --dump 200711-10. To fix the system, I can run glsa-check's --fix:

# glsa-check --fix all
(This will iterate over all GLSAs, including the matching one(s))

Switching between software versions

Gentoo supports having multiple versions of the same software on the system. Notable examples are gcc, python and java but many more exist. Administrators are able to switch between these installed versions using eselect. We have seen this tool already previously for switching between profiles.

For instance, to display the installed Python versions:

# eselect python list
Available Python interpreters:
  [1] python2.7
  [2] python3.1 *

In the above example, Python 3.1 is the system default. You can switch the system to 2.7 then using eselect python set 1.

To get an overview of the supported modules in eselect, run eselect help.

Uninstalling Software

Now suppose you've found some software installed on your system that you want to remove. With emerge --unmerge (-C in short) you can remove installed software from your system.

# emerge --unmerge acroread --ask

However, if this software is a dependency of an installed software title, your next system update will pull the software back in. Even worse, software that depends on it that is still being used / running might even stop functioning properly or crash. A safer way of pursuing the de-installation of a package is by asking Portage to delete the package but only if no other dependencies point to it. To do so, use emerge --depclean (or in short, emerge -c):

# emerge --depclean acroread

With this command, Portage will remove the package if it is no longer in use otherwise. In other words, if no other package depends upon acroread, it will remove acroread. However, if some package still depends upon acroread, Portage will let acroread remain on your system and inform you of the dependencies towards it.

Advanced Software Management

Of course, Gentoo allows for much more advanced software management aspects than described before. If you search the available documentation, you'll quickly notice that Gentoo Portage supports the notion of stable versus "unstable" packages (the so-called ~arch states), supports third-party repositories and more.

Package States

Gentoo packages, which are called ebuilds, are always in a certain state. Although this state is never explicitly defined in the package, it is a result of a set of rules set forth by developers to keep track of a package's stability, security, license rules, ...

When you install packages, those rules are checked to make sure you are not installing a package that shouldn't be installed on your system. These various rules can trigger installation errors, most of the time described as being a package mask.

Whenever an installation is triggered, Gentoo Portage tries to install the highest version of a package which matches all possible validity rules. Only when no such version exists, or when you explicitly asked to install a certain version, Gentoo aborts the installation with a failure message.

The following sections describe the various states / rules that are checked when an installation is triggered. If you want to work around such a rule, see the section on "Unmasking Packages".

Architecture Availability

Gentoo is a multi-architecture operating system. Packages available within Gentoo can be installed on several architectures, ranging from the popular x86/amd64 onto sparc, mips, powerpc, ... But of course, most packages can't be installed on any platform. Some tools are only supported on the Intel-like platforms (x86, amd64) or on a specific platform (like the silo boot loader, which is explicitly made for the sparc platform).

Packages are marked as being available for a particular platform using their KEYWORDS variable. An example, taken from sys-apps/iproute2 version 2.6.29-r1:

KEYWORDS="alpha amd64 arm hppa ia64 m68k ~mips ppc ppc64 s390 sh sparc x86"

When you install a package, its platform keywords are checked against the keywords that your system accepts. These keywords are defined in the ACCEPT_KEYWORDS variable, which you can query with emerge --info:

$ emerge --info | grep ACCEPT_KEYWORDS
ACCEPT_KEYWORDS="amd64"

Whenever a mismatch occurs (the package doesn't have the keyword that you have defined in ACCEPT_KEYWORDS) you get an error message like so:

!!! All ebuilds that could satisfy "sys-boot/silo" have been masked.
!!! One of the following masked packages is required to complete your request:
- sys-boot/silo-1.4.14 (masked by: missing keyword)

Having an error due to an unsupported architecture, it is not advisable to try and work around this (forcing the package to be installable). It will most likely not work anyhow.

Other related error messages that you might receive are:

- lm-sensors/lm-sensors-2.8.7 (masked by: -sparc keyword)
- sys-libs/glibc-2.3.4.20040808 (masked by: -* keyword)

These error messages are similar to the one above (missing keyword). The differences are:

  • "missing keyword" means that the architecture isn't set in the KEYWORDS variable.

    The architecture might be supported by the package, but no developer has tried to install it on this platform yet.

  • "-sparc keyword" (or other architecture) means that that particular architecture is explicitly denied in the KEYWORDS variable.

    In this case, the developer has either tried to install it, but it destroyed its system, or the package itself is known not to work on the mentioned platform.

  • "-* keyword" means that all architectures are explicitly denied in the KEYWORDS variable except a few.

    This case is mostly used for packages that are meant to be available on a single platform only. The developer marks the package as unavailable for any other architecture, hence the "-*".

Stabilization of Gentoo Packages

When a developer creates or edits a Gentoo package, the software isn't immediately available for the general public. First, it is put through a sort of staging period. During this time, testers try out the package, finding possible package definition bugs (like wrong dependencies) and helping the further development until the package is deemed stable.

There is an unwritten rule that says that packages should "linger" in the staging period for 30 bug-free days (no additional bugs found by the architecture testers) before it is released to the general public.

Within Gentoo, this staging period is described by prepending the tilde (~) sign in front of the architecture in the KEYWORDS variable. In the KEYWORDS example above (of the iproute2 package) you notice that this is done for the mips architecture. In other words, the package most likely is supported on the MIPS architecture, but it is currently under review (in staging period). It is well possible that within a month, the package is made available for the general MIPS public as well.

Whenever you try to install a package that is in the staging period, you get an error message as follows:

!!! All ebuilds that could satisfy ">=sys-apps/portage-2.1.8" have been masked.
!!! One of the following masked packages is required to complete your request:
- sys-apps/portage-2.2_rc62 (masked by: ~amd64 keyword)

If you get such an error message, I recommend to wait until the package is generally available (and let the architecture testers bring out most of the bugs for you).

Critical Bugs or Security Issues

Whenever a package has a critical bug (critical = breaks your system severely), a security issue (like having an exploitable vulnerability that might grant malicious users access to your system) or just isn't maintained any more, the Gentoo developer might mask the package explicitly.

Explicit masks do not only disallow the installation of the software, they usually also contain a comment as to why the installation is prohibited. These explicit masks (and their comments) are stored in a file called package.mask. By default, this file is available in /usr/portage/profiles.

An example would be:

!!! All ebuilds that could satisfy "games-roguelike/slashem" have been masked.
!!! One of the following masked packages is required to complete your request:
- games-roguelike/slashem-0.0.772 (masked by: package.mask)
/usr/portage/profiles/package.mask:
# Tavis Ormandy <taviso@gentoo.org> (21 Mar 2006)
# masked pending unresolved security issues #127167

In this example, you find out who masked the package, when the mask occurs, and why (including a bug number which can be checked at https://bugs.gentoo.org).

License Approval

Gentoo packages always keep track of the license under which the software is distributed / allowed to be used. Like the architecture available cases, this is done through a variable called LICENSE. For instance, for the net-im/skype package:

LICENSE="skype-eula"

And, just like the KEYWORDS case, your system has a variable called ACCEPT_LICENSE in which you set which software licenses you want on your system. The default setting on Gentoo systems is quite liberal, but you can set it to your liking. For instance, you can accept only FSF approved licenses:

$ emerge --info | grep ACCEPT_LICENSE
ACCEPT_LICENSE="-* @FSF-APPROVED"

The use of the @-sign allows Gentoo to group similar licenses together. The list of license groups can be obtained from /usr/portage/profiles/license_groups.

If you ever want to install a software which doesn't match the license(s) you allow, you will get an error like so:

!!! All ebuilds that could satisfy "net-im/skype" have been masked.
!!! One of the following masked packages is required to complete your request:
- net-im/skype-2.0.0.72 (masked by: skype-eula license)

In this example, the package I want to install uses the "skype-eula" license which doesn't match the licenses I allow (which are only the FSF-APPROVED ones).

Profile Supported Software

Gentoo supports several profiles. A profile should be seen as a collection of predefined settings for your Gentoo Linux environment. These settings include default USE flags, default license acceptance, default package choices, etc. Such profiles can also have masks against certain packages because they don't fit in the spirit of the profile.

An example is the selinux/v2refpolicy/x86/hardened profile, which masks out glibc-2.4 as it doesn't match the security measures that the profile wants to enforce.

Whenever you try to install a package that isn't allowed due to your profile, you get a message like so:

!!! All ebuilds that could satisfy "=sys-libs/glibc-2.4*" have been masked.
!!! One of the following masked packages is required to complete your request:
- sys-libs/glibc-2.4-r2 (masked by: profile)

Unmasking Packages

When you get an installation failure because the package you want to install is considered masked, you can opt to install it anyway. I recommend that you consider this step carefully - masking of packages is done with a reason.

  • If it is because of a critical bug or security issue, I seriously discourage you to install it (for obvious reasons).

  • If the package is masked due to the stabilization track, I urge you to wait until it is generally available.

  • If the package is masked due to architecture unavailability, I suggest that you investigate if the package supports your architecture. If it doesn't, there's no point in trying to install it anyway. If it does, you might want to ask the architecture testing team of Gentoo to investigate the package.

  • If the package is masked due to profile mismatch, you're either running the wrong profile or have made a mistake in trying to install the package and will now continue with your life as it is.

  • If the package is masked due to license mismatch, then your license setting is incorrect.

Now, the last reason (license settings) is (in my opinion) the only one that warrants a change in the configuration, but the way on dealing with these blocks is similar.

System-wide or Package Specific?

Whenever you want to resolve a masking issue, you need to ask yourself if you want to resolve this for this particular package only (or a set of packages) or if you want to alter the settings for the entire system. In the majority of cases (except for licenses) it is for a particular package (or set of packages).

Portage has a specific configuration directory (/etc/portage) in which deviation settings can be stored. Each type of deviation has its own file or directory:

  • /etc/portage/package.license allows you to set license-deviations (approve or deny a license on a per-package basis)

  • /etc/portage/package.mask allows you to mask packages (deny packages on a per-package basis)

  • /etc/portage/package.unmask allows you to unmask packages (allow packages that are disapproved due to critical bugs, security issues or profile mismatches, on a per-package basis)

  • /etc/portage/package.accept_keywords allows you to set keyword deviations (inform Portage that for this package, other keywords are accepted as well)

Note

Previous versions of Portage use package.keywords instead of package.accept_keywords. Recent Portage versions still support this old location, but it is recommended to rename them to package.accept_keywords to remain functional in the future.

Now, I did say "file or directory" in the previous paragraph. That's right: Portage allows you to either put the information in files that are called as mentioned above, or in files that reside in a directory called as mentioned above.

The most proper way, in my opinion, is to create directories. Within each directory, you can then group deviations based on the reason.

If you want to make a system-wide deviation, you need to edit the /etc/portage/make.conf file.

Example: Allow the Skype-EULA License for the net-im/skype package

As an example, let's allow the skype EULA license for the skype package (and only for the skype package).

  1. Create a directory called package.license within /etc/portage.

    # mkdir -p /etc/portage/package.license
  2. Create a file called "skype" inside this directory, and enter "net-im/skype skype-eula".

    # nano -w /etc/portage/package.license/skype
    net-im/skype skype-eula

That's it. If you now would launch the installation of the skype package, it will not abort saying that the license is masked because you explicitly allowed the license on this package. However, if for some reason another package uses the same license, it will still fail installing because that particular package isn't mentioned as a valid deviation.

Example: Allow the Skype-EULA License System-wide

The other way is to allow the skype EULA system-wide.

  1. Find out what your current license acceptance rule is.

    $ emerge --info | grep ACCEPT_LICENSE
    ACCEPT_LICENSE="-* @FSF-APPROVED"
  2. Open /etc/portage/make.conf in your favourite text editor:

    # nano -w /etc/portage/make.conf
  3. Navigate to the place where ACCEPT_LICENSE is defined or, if it isn't defined, create a new line and make it so that it looks like the current setting as obtained from the first step:

    ACCEPT_LICENSE="-* @FSF-APPROVED"
  4. Now add the skype-eula license:

    ACCEPT_LICENSE="-* @FSF-APPROVED skype-eula"
  5. Save the file and exit.

If you now install the skype package, it will not fail due to the license, as you now state that you accept this license. If any other package also works with the skype EULA license, it will also be installable now.

Example: Allow bonnie++ Version 1.96 (Staging State) to be Installable

If you want to install app-benchmarks/bonnie++-1.96 but find out that the package is masked (say ~x86 keyword mask), you can inform Portage to allow the installation of this particular package regardless of it being in the staging state or not:

  1. Create the /etc/portage/package.accept_keywords directory

    # mkdir -p /etc/portage/package.accept_keywords
  2. Create a file (say benchmarks) and add "app-benchmarks/bonnie++" to it:

    # nano -w /etc/portage/package.accept_keywords/benchmarks
    app-benchmarks/bonnie++

With this setting in place, Portage will allow you to install bonnie++ (any version) regardless if it is still in the staging state or not.

If you only want to allow this for the 1.96 version, use the following line instead:

=app-benchmarks/bonnie++-1.96

Example: Allow All Staging State Packages to be Installable

Warning

Setting this is greatly discouraged. You do not get support from Gentoo developers if you do this!

Oh, and if you do it, your next system update will pull in a lot of packages, and chances are slim that you can safely downgrade (so this step is difficult to undo).

To allow the staging packages to be installable on your system (any package in the staging state), edit /etc/portage/make.conf accordingly:

  1. Find out your current ACCEPT_KEYWORDS value.

    $ emerge --info | grep ACCEPT_KEYWORDS
    ACCEPT_KEYWORDS="x86"
  2. Open /etc/portage/make.conf in your favourite editor

    # nano -w /etc/portage/make.conf
  3. Navigate to the ACCEPT_KEYWORDS variable or, if it doesn't exist, create it with the value obtained in the first step:

    ACCEPT_KEYWORDS="x86"
  4. Now add the staging sign to it:

    ACCEPT_KEYWORDS="~x86"
  5. Save the file and exit.

From this point onwards, Portage will install the highest available version of a package regardless of it being in the staging state or not.

Other Examples...

From the previous examples, you should get a grip on how to handle masked packages:

  • either create a file in a /etc/portage subdirectory, or

  • edit the make.conf file to make things globally

You can find more information on the syntax used within the /etc/portage subdirectories through the portage manpage:

$ man portage
(...)
(Type in "/" followed by the file name you want to know more about)
/package.mask
(Type "n" (next) until you get the section information)

package.mask
  A list of package atoms to mask. Useful if specific ver-
  sions of packages do not work well for you. For example,
  if you swear ...

Automatically unmasking packages

More than often, a staging-state masked package has dependencies upon other masked packages, who have dependencies upon other masked packages, etc. To manually enter these dependencies in /etc/portage/package.accept_keywords and, more importantly, finding out about these packages, you would need to retry installing over and over again until you have met and resolved all errors.

A more automated way of dealing with this is to use emerge --autounmask-write. This option allows you to select the main package you want, and it will automatically create a file inside /etc/portage/package.accept_keywords that unmasks all depending packages as well.

# emerge --autounmask-write x11-misc/googleearth

Switching System Profiles

Gentoo Linux uses profiles to define defaults for your system environment. You should have gotten a first glance at profiles while installing Gentoo (if you didn't, that's okay). As a quick recap: profiles are a set of predefined default values made by the Gentoo project to distinguish between particular uses of the distribution. Whereas other distributions ask you to select a particular type of deployment (say desktop or server) in the beginning of, or during the initial installation, Gentoo allows you to switch profiles whenever you like.

The profile a system uses is defined by the /etc/make.profile symbolic link:

# ls -l /etc/make.profile
lrwxrwxrwx 1 root root 57 Dec 2007 make.profile -> 
  /usr/portage/profiles/default-linux/x86/20O7.0/desktop

A Gentoo profile defines, amongst other things:

  • what USE flags are activated by default

  • what applications get installed by default when you select a virtual[2]

  • what packages are not available for the profile (for instance, a uclibc profile doesn't support glibc) or should have a certain version (for instance, glibc higher than or equal to 2.4).

Users can easily switch between profiles. A useful tool for this is eselect:

# eselect profile list
Available profile symlink targets:
  [1]   default/linux/amd64/13.0
  [2]   default/linux/amd64/13.0/selinux
  [3]   default/linux/amd64/13.0/desktop
  [4]   default/linux/amd64/13.0/desktop/gnome
  [5]   default/linux/amd64/13.0/desktop/gnome/systemd
  [6]   default/linux/amd64/13.0/desktop/kde
  [7]   default/linux/amd64/13.0/desktop/kde/systemd
  [8]   default/linux/amd64/13.0/desktop/plasma
  [9]   default/linux/amd64/13.0/desktop/plasma/systemd
  [10]  default/linux/amd64/13.0/developer
  [11]  default/linux/amd64/13.0/no-multilib
  [12]  default/linux/amd64/13.0/systemd
  [13]  default/linux/amd64/13.0/x32
  [14]  hardened/linux/amd64
  [15]  hardened/linux/amd64/selinux *
  [16]  hardened/linux/amd64/no-multilib
  [17]  hardened/linux/amd64/no-multilib/selinux
  [18]  hardened/linux/amd64/x32
  [19]  hardened/linux/musl/amd64
  [20]  hardened/linux/musl/amd64/x32
  [21]  default/linux/uclibc/amd64
  [22]  hardened/linux/uclibc/amd64

# eselect profile set 17

As you can see from the profile names, one profile can be a child of another; if this is the case (for instance, profile number 4 from the above list has profile number 3 as parent), the profile inherits the settings from its parent and may extend or override particular settings itself.

Using Third Party Software Repositories

Next to Gentoo's main Portage tree, you can also select third party software repositories. Those are trees of developers, users and organisations that offer ebuilds for you to use which aren't available in Gentoo's Portage tree (yet).

A great tool for managing third party software repositories is layman. Install layman and then see what repositories layman supports:

# layman -L
(...)
xen          [Subversion] (source: http://overlays....)

The output of this layman command shows you what third party repositories are configured for use with layman. If you want to select one, add it to your system:

# layman -a xen

Likewise, to stop using a repository, remove it with layman -d. If you want to see what repositories you are currently using, use layman -l.

When Things Go Wrong

Of course, both Gentoo and the upstream projects that Gentoo relies on are still ran and developed by humans, and humans are programmed to make occasional mistakes, so things can go wrong. If you have installation or build failures, the following sections might help you troubleshoot it.

Portage Refuses To Install A Package

During package installation analysis, a few issues can occur which need intervention. Those are:

  • Blocked packages (a package that needs to be installed is blocked by an already installed package or another package on the installation list)

  • Masked packages (a package is not available for your profile or environment)

  • Download failures (one or more files needed to install the software aren't available or might be corrupt)

  • Kernel configuration mismatch (the package requires particular kernel configuration directives to be set)

  • Other issues (catch-all)

Blocked Packages

Sometimes a package offers a functionality that another package also offers and where the two packages cannot coexist with each other. When this occurs, you get the following two error:

[blocks B     ] mail-mta/ssmtp (is blocking mail-mta/postfix-2.2.2-r1)

In this example, the postfix package is on the installation list, but cannot coexist with ssmtp (which is already installed). As a result, the installation fails.

To resolve this, the easiest approach is to unmerge (remove) the ssmtp package from the system and retry.

Masked Packages

A package can fail to install if it is masked. A mask on a package means that the package is in a state that it shouldn't be installed on your system. Package states are described earlier in this chapter. Package masks are one of the more common causes of installation failures. There can be plenty of reasons why a package mask is interfering with an installation cycle:

  • the end user was instructed through a document or another user to unmask one package, causing a possible failure on the dependency integrity

  • a developer wrongfully made a package available which has dependencies on packages that aren't available in this particular state

  • the package just doesn't fit the profile that the users system requires

  • the end user was instructed to install a particular package which isn't available for general consumption yet

If you have a masked package, read "Package States" carefully and, if necessary, "Unmasking Packages" earlier in this chapter.

Verification of download results in failure

When Gentoo Portage attempts to install software, it will verify the downloaded files with the checksums and file sizes that the Gentoo developer has recorded when he added the software package to the Portage tree. When the downloaded file and the checksum/file size doesn't match, an error is shown:

('Filesize does not match recorded size', 97003L, 952)
!!! Fetched file: genpatches-2.6.33-1.base.tar.bz2 VERIFY FAILED!
!!! Reason: Filesize does not match recorded size
!!! Got: 97003
!!! Expected: 952
...
>>> Failed to emerge sys-kernel/gentoo-sources-2.6.33, Log file:

>>> '/var/tmp/portage/sys-kernel/gentoo-sources-2.6.33/temp/build.log'

In the above example, the file size as recorded by the developer (952 bytes) is different from the file size of the downloaded file (97003 bytes). As a result, Gentoo Portage refuses to install the software as it might be corrupted, contain malicious code, etc.

Most of the time this occurs when the developer has made a honest mistake (he uploaded a file, found an issue, resolved it in Portage but forgot to upload the modified file). In this case, the problem will most likely be reported to https://bugs.gentoo.org and quickly resolved. Try synchronising the Portage tree after a few hours and retry.

If it isn't, check if the problem has been reported or not. You can also try synchronising the Portage tree from a different Gentoo mirror (change the value of the sync-uri variable in /etc/portage/repos.conf/gentoo.org) as it might be possible that the rsync server you are synchronising with is corrupt.

Another occurring problem can be that a particular file is missing:

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

If your network connection is up and running, it is possible that the mirror where Portage wants to download the source code from is temporarily down. You can try again later or search for a different mirror (see the Gentoo Handbook for more information). If the file is really missing (i.e. other mirrors are also not hosting it), check https://bugs.gentoo.org to see if this is a known issue.

Kernel configuration mismatch

Some packages require certain kernel configurations. To ensure you don't install the packages without running a kernel with the right configurations, these packages verify your kernel configuration settings. If they find a mismatch, they will report it and abort the installation:

>>> Emerging (1 of 1) net-wireless/broadcom-sta-5.60.48.36
...
 * Determining the location of the kernel source code
 * Found kernel source directory:
 *     /usr/src/linux
 * Found kernel object directory:
 *     /lib/modules/2.6.33-rc8/build
 * Found sources for kernel version:
 *     2.6.33-rc8
 * Checking for suitable kernel configuration options...
 *   CONFIG_WIRELESS_EXT:    is not set when it should be.
 *   CONFIG_WEXT_PRIV:    is not set when it should be.
 * Please check to make sure these options are set correctly.:
 *   Incorrect kernel configuration options

When such an error occurs, you will need to reconfigure your kernel to contain the appropriate configuration parameters (quick hint: during the kernel configuration process, search for the settings using the / help search system).

Multiple packages within a single package slot

When software is being installed, Portage verifies if all requirements are met. This includes USE requirements that some packages have on others. For instance, kdelibs requires dbus, built with the USE="X" setting. If for some other reason dbus is being pulled in without X (an ebuild requires dbus without X, or you changed your USE flags to disallow X in USE), you might get the following error message:

!!! Multiple package instances within a single package slot have been pulled
!!! into the dependency graph, resulting in a slot conflict:

sys-apps/dbus:0

  ('ebuild', '/', 'sys-apps/dbus-1.2.24', 'merge') pulled in by
    >=sys-apps/dbus-1.0.2 required by ('installed', '/', 'x11-libs/qt-dbus-4.6.2', 'nomerge')
    sys-apps/dbus required by ('installed', '/', 'app-misc/strigi-0.7.1', 'nomerge')
    >=sys-apps/dbus-1.1 required by ('installed', '/', 'dev-libs/dbus-glib-0.86', 'nomerge')

  ('installed', '/', 'sys-apps/dbus-1.2.24', 'nomerge') pulled in by
    sys-apps/dbus[X] required by ('installed', '/', 'kde-base/kdelibs-4.4.5', 'nomerge')
    (and 3 more)

  Explanation:

    New USE for 'sys-apps/dbus:0' are incorrectly set. In order to solve
    this, adjust USE to satisfy 'sys-apps/dbus[X]'.

If this is due to a change in USE flags, undo the change (in the above case, setting USE to "-X" generally was a bad idea). If you need a particular USE setting, you can use /etc/portage/package.use to change the USE settings of one or more packages without affecting the entire system.

If this due to packages with conflicting dependencies, you'll either need to drop one of the packages, or file a bug at https://bugs.gentoo.org and ask for a proper solution.

Dependency required with different USE flags

When a package has a dependency on another package, but requires this dependency to be build with some USE flags which you currently have not set, Portage will give you an appropriate error:

emerge: there are no ebuilds built with USE flags to 
satisfy ">=x11-libs/qt-sql-4.5.0:4[mysql]".

!!! One of the following packages is required to complete your request:
- x11-libs/qt-sql-4.5.2 (Change USE: +mysql)

(dependency required by "app-office/akonadi-server-1.2.1" [ebuild])

In the above case, the package akonadi-server requires qt-sql (as a dependency) to be built with USE="mysql".

The solution: either add the requested USE flag to your global USE flags (in /etc/portage/make.conf) or set the USE flag specifically for the selected package (in /etc/portage/package.use).

Other Issues

A few other issues can come up:

  • When a package depends on another package which isn't available, you will get a warning "there are no ebuilds to satisfy <dependency>". This shouldn't occur as this means an ebuild has a missing dependency or dependency which isn't available for you. If it does occur, please file a bug at https://bugs.gentoo.org.

  • When two packages exist with the same name (but different category), you will get a warning that the name is ambiguous. In this case, Portage will ask you to specify the full name (category + packagename) and give you a list of candidates.

Resolving Build Failures

One of the most troublesome issue is when a package fails to build properly. There can be a plethora on issues that is causing this, so this section is definitely going to be updated frequently. In any case, chances that you're the only one having the issue is very small, so a build failure now can be resolved if you sync and retry (say) a day later...

Catch-all solution: revdep-rebuild

Before you start investigating possible build failures, run revdep-rebuild first. This tool will check and see if all library dependencies are still correct on your system. Really, this is a time-saver in case of most build errors. This tool is described more in-depth at Dynamic Linking Inconsistency.

# revdep-rebuild

Compiler errors

Compiler errors are almost always due to a bug in the package itself, not your system. An example would be:

/var/tmp/portage/app-misc/lirc-0.8.6-r2/work/lirc-0.8.6/drivers/lirc_i2c/lirc_i2c.c:402:
error: unknown field 'id' specified in initializer
/var/tmp/portage/app-misc/lirc-0.8.6-r2/work/lirc-0.8.6/drivers/lirc_i2c/lirc_i2c.c:402:
warning: initialization makes pointer from integer without a cast
make[5]: ***
[/var/tmp/portage/app-misc/lirc-0.8.6-r2/work/lirc-0.8.6/drivers/lirc_i2c/lirc_i2c.o]
Error 1
make[4]: ***
[_module_/var/tmp/portage/app-misc/lirc-0.8.6-r2/work/lirc-0.8.6/drivers/lirc_i2c]
Error 2

The important part here is the error statement prefixed by the file name (usually ending in .c or .cpp) and a number (which is the line number in the file where the compiler found an error). Whenever you get such error messages, chances are that the package itself is broken. You should check Gentoo's Bugzilla to see if it is a known error (usually is) and if a fix is already available (or a workaround).

Changing Configuration Files

When Portage installs or upgrades software which provides configuration files, the files themselves aren't automatically updated. This is to prevent Portage from overwriting changes you made to the configuration files. However, package upgrades might require configuration file upgrades as well.

Note

The setting that defines which locations are "protected" from automated updates and which aren't is the CONFIG_PROTECT (list of directories or files that are not automatically updated) and CONFIG_PROTECT_MASK (list of directories or files, inside those defined by CONFIG_PROTECT, which are automatically updated).

Both variables are defined by the profile used by your system and expanded by the environment files offered by various applications and, optionally, the setting you gave inside /etc/portage/make.conf.

To be able to identify possible configuration file upgrades, Portage warns you when configuration file updates are available. There are a few tools available that help you "merge" these updates with your existing configuration files. It is important to understand their limitations though.

Configuration File Updates

Whenever a configuration file update is available, the file itself is stored on the file system next to the current configuration file. These files (whose file name starts with .cfg_) can then be compared with the current configuration file.

There are no tools available that do this automatically for you. Most functionality that the tools provide is a view on the differences and the possibility to merge these changes automatically. In this book I describe the dispatch-conf tool. Another tool is etc-update.

dispatch-conf

The dispatch-conf tool allows you to view the differences between a configuration file and its update and merge updates automatically if the only differences are comments.

To view the list of updates, launch dispatch-conf. It will first perform the automated updates and then show you the differences between the rest of the available updates:

--- /etc/conf.d/bootmisc           2007-12-26 14:41:35.000000000 +0100
+++ /etc/conf.d/._cfg0000_bootmisc 2008-02-29 18:40:02.000000000 +0100
@@ -9,4 +9,4 @@
# Should we completely wipe out /tmp or just selectively remove known
# locks / files / etc... ?
   
-WIPE_TMP="no"
+WIPE_TMP="yes"

>> (1 of 4) -- /etc/conf.d/bootmisc
>> q quit, h help, n next, e edit-new, z zap-new, u use-new
   m merge, t toggle-merge, l look-merge:

In this example, the /etc/conf.d/bootmisc file has an update where the WIPE_TMP variable is set to "yes". If you want to keep the "no" setting, press z (zap-new) to keep the current configuration file. If you want to use the "yes" value, press "u" (use-new) to use the new configuration file.

Modifying Build Decisions

I have already covered the use of USE flags to help Portage decide which features you want (or don't want) in a package. However, there are more items that Portage needs to decide upon and you can offer your choice inside /etc/portage/make.conf, Portage' main configuration file.

Languages

Some packages support several languages. Portage can help you select what languages you want supported on your system through the LINGUAS variable. You set the LINGUAS variable in /etc/portage/make.conf with the languages of your choice. In the next example, I select the English (en), Dutch (nl), French (fr) and German (de) languages.

~# nano -w /etc/portage/make.conf
LINGUAS="en nl fr de"

For instance, when enabled, LibreOffice.org's ebuild will pull in the language packs for those languages.

Underlyingly, Gentoo's package manager will expand this into USE flags. For instance, "linguas_en".

Video Cards

Some packages might need video card information. Examples are the X11 server but also some games or rendering engines. In these cases, you should set the VIDEO_CARDS variable to your video card architecture. You might want to include several in case your architecture is quite new (you can then select the earlier architectures as well).

VIDEO_CARDS="i915 i810 intel vesa"

Compiler Directives

When building packages, Portage offers optimization directives to the compiler, telling the compiler for which architecture it should build and what optimizations the compiler can try to run. These optimization flags are set in the CFLAGS (C-code) and CXXFLAGS (C++-code) variables, again inside /etc/portage/make.conf.

I'll start off with my example CFLAGS (CXXFLAGS is the same):

CFLAGS="-O2 -march=native -pipe"
CXXFLAGS="${CFLAGS}"

Let's start off with the architecture selection: march. With -march=native, the compiler is asked to optimize code for the architecture of the current system (say a pentium 3 architecture). Also, because I select -march=, it will only run on this architecture (or architectures that are backwards compatible with mine). If you want to optimize code for a specific architecture but want to be able to run the code on any x86 architecture, use -mcpu= instead. You can also select a particular architecture, like "core2" or "nocona". A full list of supported architectures for the current GCC (make sure you are using the current one) is available online.

With -O2 (Optimizations, not zero) I ask GCC to use a list of optimization flags (-O2 is shorthand for a whole set of optimizations) which are documented in the GCC info manual (info gcc, select Invoking GCC, Optimize Options).

I also ask the compiler to pass on information between various stages of compilation using pipes (-pipe) rather than temporary files.

Portage Behaviour

Portage itself also has a lot of features it supports. You can set them through the FEATURES variable.

FEATURES="sign buildpkg"

You can find all possible features in the make.conf manual page (man make.conf). A small selection of supported features is given next.

  • buildpkg creates binary packages of every succesful build. These binary packages can be reused, even on other systems (as long as they have the same build decision parameters).

  • collision-protect ensures that a package doesn't overwrite files during its installation that it doesn't own. You might want to use protect-owned instead (this is the default) as it allows overwriting files if they aren't currently owned by any package.

  • nodoc to tell Portage not to install doc files (/usr/share/doc), with noinfo and noman having similar functions

  • parallel-fetch will have Portage download files in the background while it is building

Specific software choices

Some software items (mainly scripting languages) can have multiple versions installed side by side. In Gentoo, users can not only define what versions they want installed, but also for which versions other software should build. For instance, applications that provide Python bindings can be configured to provide Python bindings for Python version 2.7 and 3.2 (if supported by the application of course).

These software choices are provided by their respective variables:

PYTHON_TARGETS="python2_7 python3_2"
RUBY_TARGETS="ruby18 ruby19"

Underlyingly, Gentoo's package manager will expand these variables into USE flags (like "python_targets_python2_7" or "ruby_targets_ruby18").

Fixing Postinstall Problems

Even when software installation has finished successfully, you can still get into trouble.

Dynamic Linking Inconsistency

When Portage (prior to 2.2) upgrades a library, it removes the old shared libraries from the system. As a result, some applications who rely on these libraries might fail with a message like the following:

error while loading shared libraries: libcom_err.so.2: cannot
  open object file: no such file or directory

If this is the case, you will need to run revdep-rebuild to fix this. revdep-rebuild is a tool that scans your system for applications that rely on (removed) libraries and will rebuild those packages so that they get linked with the new libraries.

Exercises

  1. Portage is not the only package manager that works on Gentoo. There are at least two others. Look up what these packages are and where they differ with Portage.

  2. USE flags can also be enabled as an environment variable during your emerge process itself, like so:

    ~# USE="-ssl" emerge irssi

    Try to find out where Portage reads all possible USE flags from (you know make.conf and environment variable now, but there are others) and in what order.

  3. Try to find information regarding Gentoo's architecture testing program.



[2] A virtual is a placeholder for an application. For instance, Gentoo offers several Java runtimes; they all implement the virtual/jre. A Gentoo profiles marks a specific package as default for such virtual.