Keywords, Masks, and Package Acceptance

Keywords, Masks, and Package Acceptance define mechanisms in Gentoo's Portage package management system that control which package versions are considered stable or unstable, which ones are allowed to be installed, and how the system handles packages based on user preferences and system architecture. These concepts work together to enable precise control over the software that is installed, ensuring compatibility, stability, and user choice.

Keywords

Keywords are labels attached to packages indicating the stability and compatibility of a specific package version with certain architectures. They inform Portage about the maturity level of a package for a given CPU architecture, guiding whether a package should be treated as stable or unstable.

Keyword Types

• Stable Keywords: Represented by architecture names like amd64, x86, or arm, these indicate that a package version is considered stable and suitable for general use on that architecture.

• Unstable Keywords: Prefixed by an underscore (e.g., _amd64), these mark packages that are experimental or testing versions for the specified architecture.

• Masking Keywords: Keywords can be masked or unmasked to selectively allow or disallow certain package versions.

Usage in Portage

Portage uses the keywords to decide which package versions are eligible for installation by default. Stable keywords mean packages are considered production-ready, while unstable keywords indicate that packages are still being tested or developed and may not be fully reliable.

Users can override default keyword settings to accept unstable versions by specifying them in configuration files like /etc/portage/package.accept_keywords.

Masks

Masks are mechanisms to prevent certain packages or package versions from being installed, regardless of their keyword status. Masking can be done globally or on a per-package basis, typically used to block packages that are known to be broken, insecure, or incompatible with the user's system.

Mask Types

• Global Masks (package.mask): These masks apply system-wide and are usually set by Gentoo maintainers to prevent problematic packages from being installed.

• User Masks (package.unmask): Users can override global masks by explicitly unmasking packages they want to install despite the mask.

• Keyword Masks: Packages with unstable keywords are implicitly masked unless the user accepts the unstable keyword.

• Hard Masks (package.mask): Often used for packages that are considered unsafe or severely broken, requiring explicit user intervention to install.

Mask Syntax

Masks use versioned atoms to specify which package versions are blocked, for example:

>=dev-lang/python-3.12

This masks all Python versions starting from 3.12 upwards.

Package Acceptance

Package acceptance is the overall process by which Portage determines whether a package version is eligible for installation based on keywords, masks, and user configurations. It combines information about the package’s stability, the presence of masks, and explicit user preferences to decide if a package can be installed or upgraded.

Configuration Files Affecting Package Acceptance

• /etc/portage/package.accept_keywords: Allows users to accept unstable keywords for specific packages or globally, enabling the installation of testing or experimental versions.

• /etc/portage/package.mask: Allows users to mask certain packages or versions to prevent their installation.

• /etc/portage/package.unmask: Allows users to override global masks to force acceptance of a package.

• /etc/portage/package.use: While not directly related to keywords or masks, it influences package acceptance by enabling or disabling USE flags that can affect dependencies and package variants.

Acceptance Rules

1. Default Behavior: Only packages with stable keywords matching the system architecture are accepted.

2. Unstable Keywords: Packages marked with unstable keywords are rejected unless explicitly accepted by the user in package.accept_keywords.

3. Masks: Any package version that is masked in package.mask is rejected unless unmasked by the user.

4. Hard Masks and Keyword Masks: Hard masks take precedence over keywords; a hard-masked package will not be accepted even if the keyword is stable or accepted.

Practical Example

If a user wants to install an unstable version of a package (e.g., dev-lang/python with the keyword _amd64), they must add an entry in /etc/portage/package.accept_keywords:

dev-lang/python ~amd64

This explicitly tells Portage to accept the unstable build for the amd64 architecture.

Interaction Between Keywords, Masks, and Package Acceptance

The Portage system evaluates package eligibility by intersecting keyword states and mask rules, with user preferences overriding defaults where allowed. The decision flow is:

• Check if the package version is masked globally. If yes, reject unless unmasked.

• Check the keyword for the package version relative to the system architecture.

• If the keyword is stable, proceed.

• If the keyword is unstable, check if the user explicitly accepts it.

• If accepted, allow installation; otherwise, reject.

This layered control model ensures Gentoo users can maintain system stability while optionally testing newer or less stable software versions.

Summary of Relevant Files and Their Roles

Conclusion

Keywords, Masks, and Package Acceptance form a core part of Gentoo's package management system, enabling fine-grained control over package stability and availability. Keywords classify package versions by stability and architecture compatibility, masks prevent installation of undesirable packages, and package acceptance is the mechanism that combines these factors with user preferences to determine what software can be installed or upgraded on the system. Understanding these concepts is essential for managing a stable yet flexible Gentoo environment.