Portage (software)

Portage

Portage in action
Original author(s)	Daniel Robbins
Developer(s)	Gentoo developers (Funtoo users for Funtoo fork)
Stable release	3.0.64  / 28 April 2024 (28 April 2024)
Repository	gitweb.gentoo.org/proj/portage.git
Written in	Python, shell script, C
Operating system	Gentoo Linux and Gentoo/FreeBSD, ChromiumOS, ChromeOS, Sabayon, Funtoo Linux, Calculate Linux
Platform	POSIX-compatible/Python-capable
Type	package manager, free software
License	GNU General Public License
Website	wiki.gentoo.org/wiki/Project:Portage

Portage is a package management system originally created for and used by Gentoo Linux and also by ChromeOS, Calculate, and Funtoo Linux among others. Portage is based on the concept of ports collections. Gentoo is sometimes referred to as a meta-distribution due to the extreme flexibility of Portage, which makes it operating-system-independent. The Gentoo/Alt project was concerned with using Portage to manage other operating systems, such as BSDs, macOS and Solaris. The most notable of these implementations is the Gentoo/FreeBSD project.

There is an ongoing effort called the Package Manager Specification project (PMS), which aims to standardise and document the behaviour of Portage, allowing the ebuild tree and Gentoo system packages to be used with alternative package managers such as Paludis and pkgcore. Its goal is to specify the exact set of features and behaviour of package managers and ebuilds, serving as an authoritative reference for Portage.

Overview

Accessing Portage

Porthole graphical frontend.

Portage is similar to the BSD-style package management known as ports, and was originally designed with FreeBSD's ports in mind. Portage is written in the Python programming language, and is the main utility that defines Gentoo. Although the system itself is known as Portage, it consists of two main parts, the ebuild system and emerge. The ebuild system takes care of the actual work of building and installing packages, while emerge provides an interface to ebuild: managing an ebuild repository, resolving dependencies and similar issues. (These two therefore have roughly the same relation as rpm has with yum, or dpkg has with APT.)

A GTK+-based GUI, Porthole, is available for working with Portage. There is also the Himerge GUI, which stands for "Haskell Interface for eMerge".

Functions provided

Portage is characterized by its main function: compiling from source code the packages the user wishes to install. In doing so it allows customization of compiler and target-application options to fit the system's specifications and the user's own wishes. Functionalities related to system management include: allowing parallel package-version installation, tracking cross-package dependencies, managing a database of installed packages, providing a local ebuild repository, and synchronizing of the local Portage tree with remote repositories. Functionalities related to individual package installation include: specifying compilation settings for the target machine and choosing package components.

Portage distinguishes between three levels of stability in ebuilds: stable (e.g., the software works as intended with no known security issues at time of release), keyword masked (mainly for packages that have not been sufficiently tested on the target system architecture to be considered stable) and hard masked (broken or very insecure) packages.

Features

Emerge

Unmerge of SpaceFM file manager

The emerge command-line tool is the heart of Portage. The command is customizable with many options and modifiers. The emerge tool is the most important utility for accessing the features of Portage from the command line.

The program calculates and manages dependencies, executes ebuilds and maintains the local Portage tree and database of installed packages. The compilation settings used by ebuilds can be changed through the CFLAGS environment variable, based on the specifications of the individual computer and on the user's desire for optimization. The emerge utility executes ebuilds in a sandbox environment. This way the system is protected from software executed by the ebuild and resulting binaries are only merged after a successful build and sandboxed install.

What emerge installs as dependencies is affected by the USE flag-settings. They decide which optional features will be included when installing or upgrading an application. The emerge command can also be used to download and install precompiled binary files.

USE flags

Portage during system update

The Portage system offers the use of "USE flags", which allows users to indicate which software features they would like to include (and exclude) while building packages. For example, there is a USE flag to include DVD support, where available, in packages compiled with the flag enabled. The USE flags affect which dependencies are required, generally affecting which optional features will be built into a given program when it is compiled. For example, in packages which use a configure script, the USE flag feature would translate to ./configure --with-feature.

The specification of USE flags is the usual way to configure programs on Gentoo. USE flags may be set manually, or via user-friendly tools such as 'ufed' (USE flag editor), which lists flags along with their description. A list of available USE flags is available at the Gentoo website's USE Flag Index.

ebuild

Gentoo does not, by default, use binary packages as other package management systems do (like pacman or apt), employing instead a format known as the ebuild. Whereas RPM binaries are precompiled binaries, ebuilds are shell scripts with variables and functions which contain a description of the software, and instructions on how to obtain, configure, compile, and install it, more closely akin to (but more powerful than) the .spec files distributed in SRPMs. The official repository provides over 19,600 ebuilds, the majority of which are distributed by the Gentoo mirrors. New and updated ebuilds can be obtained by synchronizing the local ebuild repositories with the mirrors. This is done by executing the command emaint sync -a. Historically, Gentoo has provided pre-compiled binary packages for many common programs, especially those which are lengthy to compile, such as Mozilla Firefox and OpenOffice.org. These are still installed with emerge, just by appending a "-bin" to the package name to instead install the binary version.

Example of ebuild for GNOME Terminator:

# Copyright 1999-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

EAPI=7

PYTHON_COMPAT=( python3_{6,7,8} )
DISTUTILS_USE_SETUPTOOLS="no"
inherit distutils-r1 virtualx xdg-utils

DESCRIPTION="Multiple GNOME terminals in one window"
HOMEPAGE="https://github.com/gnome-terminator/terminator"
SRC_URI="https://github.com/gnome-terminator/terminator/releases/download/v${PV}/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="amd64 ~ppc x86"
IUSE="dbus +libnotify"

RDEPEND="
	>=dev-libs/glib-2.32:2
	dev-libs/keybinder:3[introspection]
	dev-python/configobj[${PYTHON_USEDEP}]
	dev-python/psutil[${PYTHON_USEDEP}]
	dev-python/pycairo[${PYTHON_USEDEP}]
	dev-python/pygobject:3[${PYTHON_USEDEP}]
	>=x11-libs/gtk+-3.16:3
	x11-libs/vte:2.91[introspection]
	dbus? ( dev-python/dbus-python[${PYTHON_USEDEP}] )
	libnotify? ( x11-libs/libnotify[introspection] )
"
BDEPEND="
	dev-util/intltool
"
distutils_enable_tests setup.py

PATCHES=(
	"${FILESDIR}"/terminator-1.91-without-icon-cache.patch
	"${FILESDIR}"/terminator-1.91-desktop.patch
	"${FILESDIR}"/terminator-1.92-make-tests-fail.patch
	"${FILESDIR}"/terminator-1.92-metainfo.patch
)

src_prepare() {
	xdg_environment_reset
	distutils-r1_src_prepare
}

src_test() {
	virtx distutils-r1_src_test
}

pkg_postinst() {
	xdg_desktop_database_update
	xdg_icon_cache_update
}

pkg_postrm() {
	xdg_desktop_database_update
	xdg_icon_cache_update
}

Binary packages

Gentoo does have a binary packaging format, which is a .tbz2 file (tar with bzip2 compression) with additional metadata. This feature enables the building of binary packages on one system (using Portage's buildpkg or quickpkg) followed by quick installation on compatible systems (with Portage's getbinpkg or emerge -K). See Portage Features in the Gentoo Linux Handbook for more information.

Masking

Masking is how Gentoo determines which packages are suitable for a system. Ebuilds designed for different architectures or experimental software are usually masked in a manner which prevents a stable system from installing them without user intervention.

Packages that generally just require some testing but will often work fine are said to be keyword masked (i.e. they are available for systems with an ACCEPT_KEYWORDS make.conf entry starting with the character ~, such as ~x86, ~amd64, ~ppc). An individual keyword masked package can be unmasked by adding a line with the full package name and keyword to some file within the /etc/portage/package.accept_keywords/ directory. Users can make subdirectories here as well, allowing for custom organization. For example, if a masked package had multiple masked dependencies, the user could make a directory with the name of the original masked package, and put all the mask files for the package and its dependencies in that directory. This scheme replaces the older scheme of having /etc/portage/package.accept_keywords as one text file.

Packages with known problems or not considered mature enough to be candidates for stable are hard masked by one of the various package.mask files in /usr/portage/profiles, and such entries are generally accompanied by a comment from developers explaining the reason for the mask.

Gentoo/Alt

Gentoo/Alt is a project created to manage porting the portage framework and other features to other operating systems, such as Mac OS X and the free BSDs. Gentoo/Alt was set up by Pieter Van den Abeele and Daniel Robbins after Pieter Van den Abeele founded Gentoo for Mac OS X.

Mac OS X

Gentoo for Mac OS X was the first non-Linux project of Gentoo and focused on making the Gentoo experience available on Apple's operating system by introducing the Portage system as a separate entity. This was roughly similar to Fink and MacPorts, but it used Portage instead of a Debian-like or Ports-like system. Later on, Gentoo for Mac OS X was made a subproject of Gentoo/Alt. The project is no longer active, because its prime assumption of using and not modifying the host OS appeared not to be realistic and eventually broke most packages or made them hardly maintainable. Gentoo for Mac OS X has been superseded by Gentoo Prefix, which is currently what Gentoo offers to Mac OS X users.

The Prefix project on Mac OS X is tested and supported on Mac OS X Tiger, Leopard and Snow Leopard on PowerPC, IA-32, and x86-64 architectures.

FreeBSD

Gentoo/FreeBSD

OS family	Unix-like (BSD)
Working state	Discontinued
Source model	Open source
Repository	gitweb.gentoo.org/proj/portage.git
Package manager	Portage
Kernel type	Monolithic (kFreeBSD)
Userland	FreeBSD
License	Various
Official website	Gentoo/FreeBSD

Gentoo/FreeBSD brings the Gentoo Linux design, structure, and tools such as Portage and the Gentoo Linux base layout to the FreeBSD operating system. Gentoo's GNU toolchain is used instead of the original FreeBSD one.

Although the project is no longer maintained by any active Gentoo developers, there are instructions that allow installation of a full Gentoo/FreeBSD system. FreeBSD system ebuilds are integrated into the main portage tree, but this port is far from being complete due to the amount of packages needing to be ported and the lack of a proper Live CD (FreeSBIE's Live CD or FreeBSD setup CD is used during installation).

The current (semi) official logo for Gentoo/FreeBSD is a daemonized "g", derived from original Gentoo Linux logo and inspired by the BSD Daemon. It was designed by Marius Morawski, responding to an unofficial contest launched by Diego Elio Pettenò on his blog.

NetBSD

Gentoo/NetBSD is a project to provide a GNU userland managed by Portage with a NetBSD kernel. The project was started by Damian Florczyk. Only the x86 architecture is targeted and the system as a whole is in an incomplete state.

OpenBSD

Gentoo/OpenBSD

OS family	Unix-like (BSD)
Source model	Open source
Latest release	Gentoo Prefix on OpenBSD / April 4, 2011 (2011-04-04)
Repository	gitweb.gentoo.org/proj/portage.git
Package manager	Portage
Kernel type	Monolithic (kOpenBSD)
Userland	OpenBSD
License	Various
Official website	Gentoo/OpenBSD

Gentoo/OpenBSD was a Gentoo/*BSD subproject to port Gentoo features such as Portage to the OpenBSD operating system. It was originally started by Grant Goodyear and is deprecated. An install guide is provided on the project page but is also marked as deprecated.

DragonFlyBSD

Gentoo/DragonFlyBSD is a currently unofficial port to the DragonFlyBSD kernel. The project is developed by Robert Sebastian Gerus.

GNU Hurd

An unofficial port to GNU Hurd was also being developed, but was abandoned in late 2006.

Android

Led by Benda Xu, "Gentoo RAP for Android Devices" installs a variant of Gentoo called Gentoo RAP in a directory prefix alongside Android. The Linux kernel is used by both Android and Gentoo RAP.

Interix

Gentoo/Interix (eprefix) is a port of Gentoo that runs atop the Interix Subsystem for Windows which is also known as Microsoft Windows Services for UNIX (SFU) or Subsystem for Unix-based Applications (SUA). A result of the Gentoo/Interix project is the ability to install and use the Portage system to emerge native Windows applications (requires Visual Studio, 2008 Express Edition will do too). However, this feature does not support the wide variety of packages supported by other platforms (including Interix).

Portaris

An unofficial port to the Solaris operating system, "Portaris", was announced around 2006, but never got into a public state. It was superseded by the Gentoo Prefix project.

Plan 9

Started in 2011 as a Google Summer of Code project, Plan 9 For Gentoo takes the Gentoo base and overlays a userspace inspired by Plan 9. The stated objectives of the project are to have better hardware support, better software support and to create a "culture shock" for people that have previously used Linux systems. The project is maintained by Robert Seaton.

See also

• pkgsrc
• List of Linux package management systems

External links

Official documentation

• Funtoo Portage Documentation
• Gentoo Portage Features
• Gentoo Portage Introduction
• Working with Portage
• Gentoo Packages, information about currently available ebuilds

Unofficial documentation

• Gentoo-Portage, alternative presentation of current ebuild information
• Using Portage
• Installing portage on other Linux distros

Similar software

• Emerde, portage-like project for Slackware
• Pkgcore, bsd re-implementation of portage
• Paludis Archived 2020-09-23 at the Wayback Machine, a package manager which can be used with ebuilds and other formats
• Arch Build System a ports-like system for Arch Linux