Package Atoms and Dependency Expressions

Package Atoms and Dependency Expressions are fundamental components in Gentoo's Portage package management system, used to specify packages and their versions precisely, as well as to define complex dependencies and constraints for package installation, updates, and removal.

A package atom is a string that uniquely identifies a package or a set of packages with optional version constraints, slot information, USE flags, and repository qualifiers. Package atoms serve as the basic building blocks for specifying which packages to operate on.

Dependency expressions extend package atoms by allowing logical operators and grouping to express complex conditions and relationships between packages. These expressions enable Portage to resolve dependencies accurately, considering multiple factors such as version ranges, use flags, and masking.

Package Atoms

Definition and Structure

A package atom typically consists of the following components:

• Category: The top-level grouping of the package (e.g., app-editors).
• Package name: The specific package within the category (e.g., vim).
• Version specifier (optional): A constraint on the package version, using comparison operators.
• Slot (optional): Defines a parallel installable version space for packages.
• USE flag constraints (optional): Conditions based on USE flags.
• Repository qualifier (optional): Specifies the repository to use.

The general syntax of a package atom is:

[<repository>/]<category>/<package>[-<version>][:[slot]][[ USE=<use-flag>][ ...]]

Version Specifiers

Version specifiers constrain package versions and use comparison operators:

• =: exact version (e.g., =app-editors/vim-8.2.3456)
• <, <=: less than, less or equal than a version
• >, >=: greater than, greater or equal than a version
• ~: approximately equal to a version (usually the latest stable in that version series)

Example atoms with versions:

• >=sys-libs/glibc-2.31
• =dev-lang/python-3.9.5

Slots

Slots allow multiple versions of a package to coexist if they use different slots. A slot is specified after a colon (:) following the version or package name.

Example:

• dev-libs/libxml2:2
• app-editors/vim:8

Slots are crucial when different packages depend on different incompatible versions of the same package.

USE Flag Constraints

USE flags control optional features in packages. Package atoms can specify USE flag constraints to ensure a package is selected or masked based on certain USE flags.

Syntax examples:

• app-editors/vim +gtk -perl: requires gtk USE flag enabled and perl disabled.
• dev-lang/python -tk: requires tk USE flag disabled.

This syntax helps tailor package builds to specific needs and dependencies.

Repository Qualifier

If multiple repositories are configured, a package atom can specify which repository the package should come from by prefixing the atom with <repository>/.

Example:

• gentoo/app-editors/vim
• local/app-editors/vim

Dependency Expressions

Logical Operators

Dependency expressions use logical operators to combine package atoms and create complex dependency rules:

• AND (&& or whitespace): Both conditions must be true.
• OR (||): At least one condition must be true.
• NOT (!): Negates a condition.

Expressions can also be grouped using parentheses for clarity and precedence.

Example:

sys-libs/glibc >=2.31 || sys-libs/glibc:0

Means the system must have glibc version 2.31 or higher, or any version in slot 0.

Grouping and Precedence

Parentheses () are used to group expressions and control evaluation order, similar to Boolean algebra.

Example:

(dev-libs/libxml2:2 || dev-libs/libxml2:3) && !app-editors/vim

This means either libxml2 slot 2 or slot 3 must be present, and vim must not be installed.

Use of Atoms in Dependency Expressions

Dependency expressions are often used in ebuild files to specify conditions for dependencies:

• DEPEND: Build-time dependencies.
• RDEPEND: Runtime dependencies.
• PDEPEND: Post-build dependencies.

Example in an ebuild:

DEPEND=">=sys-libs/glibc-2.31 || >=sys-libs/glibc-2.32"
RDEPEND="dev-libs/libxml2:2 || dev-libs/libxml2:3"

Practical Examples

Simple Package Atom

app-editors/vim

Matches the latest available version of vim in the app-editors category.

Package Atom with Exact Version and Slot

=dev-lang/python-3.9.5:3.9

Matches exactly version 3.9.5 of Python in slot 3.9.

Dependency Expression with Logical Operators

(dev-libs/libxml2:2 || dev-libs/libxml2:3) && !app-editors/vim

Requires either slot 2 or slot 3 of libxml2 and excludes vim.

USE Flag Constraints in Package Atom

app-editors/vim +gtk -perl

Matches vim with the gtk USE flag enabled and perl disabled.

Summary of Syntax Elements

This precise and flexible syntax of package atoms and dependency expressions allows Gentoo's Portage system to manage packages effectively, resolving complex dependency graphs and ensuring consistent system states according to user specifications.