User:AllenJB/Package Management

The purpose of this article is to introduce you to the basics of package management in Gentoo using the Portage package manager and associated utilities.

Basic Terminology
The following is some basic terminology used throughout this article. Further terms will be introduced later, but these are ones you'll need before you go further.

Keywords are basically used to specify the architecture and package tree branches available. Your system keywords are set using ACCEPT_KEYWORDS in /etc/make.conf. By default this will be the stable branch for your architecture (eg. "x86" or "amd64"). Any keyword prefixed with a ~ (tilde) refers to the testing branch (ie. "~x86" is the "x86" testing branch).

Note that the "amd64" keyword refers to the 64-bit x86 architecture shared by both AMD and most Intel 64-bit processors (anything that's not Itanium branded) - the reason for this being that AMD came up with this particular 64-bit implementation first, Intel licensed it and it's far too much hassle to change.

Slots allow more than one version of the given package to be installed at the same time. You may have one version of a package installed per slot. For example, you can have any version of kdelibs from the 3.5 slot and any version from the 4.2 slot installed at the same time. Slots must be enabled when the package is created by the developer - they are not something that users can create (because you have to ensure that different slots do not try to overwrite each others files).

A package atom is a descriptor of one or more packages. Package atoms are used by many utilities to search for or manipulate packages. The syntax for basic package atoms is: / - -
 * is the package tree category in which the package resides. In many cases it is permissable to omit this (along with the forward-slash seperator)
 * is the name of the package
 * is the version of the package. This changes when the upstream developers release a new version.
 * is the revision of the package. This changes when the Gentoo developers change something that may require the package to be reinstalled. The revision is generally considered part of the package version, so anywhere that a version is specified, you include the revision (if appropriate).

The basic package atoms available are as follows (note that not all tools will accept all package atoms):
 * @set - A package set (a collection of packages - explained in detail later)
 * packageName - A package name. If a version is needed by the tool, this usually refers to the latest version available on your configuration (this mainly depends on your keywords)
 * cat-egory/packageName - A specific package name in a specific category. This is sometimes needed as there can be more than one package with the same name in the package tree, as long as they are in different categories. Anywhere that accepts "packageName" also accepts "cat-egory/packageName".
 * =packageName-version - A specific version of the specified package.
 * packageName-version or >=packageName-version - A specific version range (less than or greater than the specified version)
 * ~packageName-version - Any revision of the specified package version.
 * packageName:slot - A specific slot of the specified package.

Package Information with eix
There are a number of tools for getting information about packages. The one you'll most commonly want to use is eix, provided by the package, which allows you to quickly search through all the available and installed packages on your system.

The most basic usage is: Where is any part of the package name you wish to search for.

Further details of eix usage will be shown throughout this article.

Package Sets (Basics)
A set is a collection of related packages. Set atoms are prefixed with an @ (at-sign). The two most basic sets that you should know about are @system and @world.

The @system set is a basic working linux system - toolchain, init system and basic utilities packages - and it is roughly the same as what is installed by a stage3 tarball. You can list the packages in the @system set with:

The @world set contains every package which you have specifically asked to be installed. Portage will then travel through the dependencies of these packages to work out the entire list of installed packages. By default, the @system set is included in the @world set. You can list all packages that are directly in the @world set (ie. excluding packages which are in a set, such as @system, which is included in the @world set) with:

Installing and Removing Packages
To install a package and all the dependencies required to use it, you use:

Whenever you install a package, it is automatically added to the world set. You can install a package without adding it to the world set using:

To uninstall a package, you run:

Whenever you uninstall a package, it is removed from the world set (if it is in the world set, otherwise it's just uninstalled). Additionally it should be noted that none of the dependencies will be removed.

Over time, you will end up with packages which were installed as dependencies, but are no longer needed. You can uninstall these packages using the following command:

When depclean wants to remove a package that you want to keep installed, you can ask emerge to add the package to world set and install it only if it's not installed using:

Use Flags
Many packages have optional features which the user can enable or disable. In Gentoo, these are managed through "use flags".

You can find out what use flags a given package has using:

Managing use flags is already well covered in the Gentoo Handbook section titled Working with Portage: Use Flags.

Updating Your Install
Before you update your packages, you'll first need to update the local copy of the package repository with:

When the package repository is sync'd, Portage will then tell you if there are any updates available for itself. If you see no message, then there are no updates available. If an update is available, install it with:

News Items
The package manager will sometimes alert you that there are news items available. These news items will give you important information about changes to packages.

You can check what news items are available using:

You can read all unread news items by running:

For further commands and help, run:

Updating Packages
The basic command for updating all packages in the world set and their dependencies is:

Often, when updating packages there is extra information that can be useful. This includes use flag changes and the dependency tree (showing which packages dependencies were pulled in by):

That's a bit of a mouthful, so you can shorten it to:

Reinstalling Everything
Very occasionally, you'll want to recompile everything, regardless of whether it really needs updating. There are several slightly different ways to do this:

To reinstall every installed package, run:

To reinstall every package in the world set and its dependencies, run:

Sometimes you'll just want to recompile your toolchain. You can do this by reinstalling the system set with: