✦ For everyone, free.

Practical knowledge for real and everyday life

Home

Portage Configuration

Portage Configuration manages package installations and system updates in Gentoo Linux through a centralized configuration file.

Portage Configuration defines the set of files, directories, and settings that control the behavior of the Gentoo Linux Portage package management system. This configuration governs how packages are fetched, compiled, installed, and managed on a Gentoo system, allowing fine-tuned control over build options, package selection, system profiles, overlays, and environment settings. By customizing Portage Configuration, administrators can optimize performance, enforce policies, and ensure consistency across system updates and package installations.

Configuration File Locations

Portage Configuration is primarily stored in specific directories and files under /etc/portage and /usr/portage (or /var/db/repos/gentoo in newer setups).

/etc/portage

This directory contains the system-wide configuration files and user-customized settings that override default Portage behavior, including:

  • make.conf: The central configuration file that contains global build options, environment variables, and Portage settings.
  • package.accept_keywords: Controls acceptance of testing or unstable package versions.
  • package.use: Enables or disables specific USE flags on a per-package basis.
  • package.mask and package.unmask: Define packages or versions to exclude or allow respectively.
  • package.provided: Marks certain packages as already installed, preventing Portage from reinstalling them.
  • package.license: Specifies license restrictions for packages.
  • repos.conf: Defines repository locations and priorities.
  • env/: Directory for environment files used to set environment variables during builds.
  • profile/: Symbolic link to the selected system profile, which defines default USE flags, package masks, and system settings.

Repository Metadata

Portage reads ebuilds and metadata from the main Gentoo repository, typically located in /var/db/repos/gentoo or /usr/portage depending on the system's configuration. Overlays are additional repositories that can be added to extend or customize available packages.

Core Configuration Files

make.conf

make.conf is the primary configuration file for Portage. It sets global variables affecting compilation, package management, and system behavior. Key variables include:

  • USE: Global USE flags that enable or disable optional features across packages.
  • CFLAGS, CXXFLAGS: Compiler optimization flags.
  • MAKEOPTS: Parallel compilation options (e.g., -j4 for 4 simultaneous jobs).
  • GENTOO_MIRRORS: URLs for downloading source files.
  • PORTDIR: Location of the Portage tree (default is /usr/portage or /var/db/repos/gentoo).
  • DISTDIR: Directory where source tarballs are stored.
  • PKGDIR: Directory where binary packages are stored.
  • ACCEPT_LICENSE: Specifies which licenses to accept during package installation.

Example snippet from make.conf:

USE="X gtk -gnome -kde"
CFLAGS="-O2 -pipe"
MAKEOPTS="-j4"
GENTOO_MIRRORS="http://mirror.example.com/gentoo"
ACCEPT_LICENSE="* -@EULA"

package.use

This file allows setting or overriding USE flags on a per-package basis. It can be structured either as a flat file or as a directory with multiple files to organize flags clearly.

Example entries:

media-video/vlc qt5
net-misc/openssh -X

This configures vlc to build with Qt5 support, disables the X USE flag for openssh.

package.accept_keywords

Controls which packages or versions from testing or unstable branches are acceptable. It can selectively accept keywords like ~amd64 to allow testing versions.

Example:

app-editors/vim ~amd64

Profiles

Profiles are sets of default configuration settings that define the system's base environment. This includes default USE flags, package masks, and system metadata.

  • Profiles are located under /usr/portage/profiles or /var/db/repos/gentoo/profiles.
  • The active profile is selected via a symbolic link /etc/portage/make.profile.
  • Profiles tailor the system for different use cases, such as desktop, server, hardened, or embedded environments.
  • They provide a baseline configuration that users can customize further.

Overlays and Repositories

Portage supports multiple repositories, including the main Gentoo repository and additional overlays.

  • Overlays allow access to packages not in the main tree or to newer versions.
  • They are configured in /etc/portage/repos.conf or within /etc/portage/repos.conf/ directory.
  • Overlay management tools like layman or eselect repository simplify adding/removing overlays.
  • Each repository can have its own configuration, priority, and metadata.

Environment and Build Settings

env.d and Environment Files

Portage can load environment variables from files located in /etc/portage/env or /etc/portage/env.d. These allow setting custom environment variables for individual packages or sets of packages, which influence compilation or run-time behavior.

Example in /etc/portage/env/package.env:

CFLAGS="-O3 -march=native"

FEATURES

The FEATURES variable in make.conf controls Portage's behavior during package management, such as:

  • sandbox: Enables build sandboxing for security.
  • parallel-fetch: Allows multiple source downloads simultaneously.
  • buildpkg: Builds binary packages after compilation.
  • userfetch: Allows users to fetch sources manually.

Example:

FEATURES="sandbox parallel-fetch buildpkg"

Package Masking and Unmasking

Portage uses package masks to prevent installation of certain packages or versions.

  • package.mask: Blocks specified packages globally or on a per-architecture basis.
  • package.unmask: Overrides masks to allow installation.
  • These files accept versioned package specs and can be used to avoid unstable or deprecated packages.

Example to mask a problematic package version:

>=sys-kernel/linux-5.10.0

To unmask:

=sys-kernel/linux-5.10.0

License Management

Portage enforces license restrictions through:

  • package.license: Specifies which licenses are acceptable for individual packages.
  • ACCEPT_LICENSE in make.conf: Global license acceptance.

This system ensures compliance with user or organizational policies regarding software licensing.

Binary Package Management

Portage supports building and installing binary packages to speed up deployment.

  • PKGDIR sets the storage directory for binary packages.
  • buildpkg feature enables automatic binary package creation after compilation.
  • Binary packages are managed with emerge options such as --usepkg and --buildpkg.

Configuration Directories and Structure

A typical configuration layout looks like this:

/etc/portage/
├── make.conf
├── package.use/
│   ├── media
│   └── net
├── package.accept_keywords
├── package.mask
├── package.unmask
├── package.license
├── repos.conf
├── env/
│   └── custom.env
└── make.profile -> /usr/portage/profiles/default/linux/amd64/17.1

This modular structure allows administrators to maintain clear, organized, and scalable configurations.

Summary

Portage Configuration is the comprehensive set of files and settings that govern the behavior of Gentoo's Portage package manager. It allows system administrators to control package versions, USE flags, compilation options, repositories, licenses, and environment settings with fine granularity. By leveraging profiles, overlays, and modular configuration files, Portage Configuration provides a flexible and powerful mechanism to tailor Gentoo Linux systems to specific needs and use cases.

Related content