Keywording concepts and policy

Note: Terminology: The term 'package' refers to an entire directory, for example app-editors/vim — it does not refer to a specific version. The terms 'ebuild' or 'package version' are used when this meaning is intended. This distinction is important.

Most ebuilds specify a KEYWORDS variable. This variable is used to indicate the suitability and stability of both the package and the ebuild on each given arch (sparc, ppc, x64-macos, ...).

Note: The term 'arch' is used in this sense for historical reasons. As a result of GLEP 22 and the various non-Linux ports, this is no longer a particularly accurate term.

A sample KEYWORDS entry might look like:

KEYWORDS="-hppa ~mips ~ppc sparc x86 ~ppc-macos"

The different levels of keyword are:

arch (x86, ppc-macos) ("stable"): Both the package version and the ebuild are widely tested, known to work and not have any serious issues on the indicated platform.
~arch (~x86, ~ppc-macos) ("testing"): The package version and the ebuild are believed to work and do not have any known serious bugs, but more testing is required before the package version is considered suitable for arch.
No keyword ("unkeyworded"): If a package has no keyword for a given arch, it means it is not known whether the package will work, or that insufficient testing has occurred for ~arch.
-arch (-x86, -ppc-macos): The package version will not work on the arch. This could be caused by badly written code (for example, non-64-bit or endian clean code), relying upon particular hardware (for example, a BIOS querying tool would not work on non-BIOS architectures) or binary only packages.

The -* keyword is special. It is used to indicate package versions which are not worth trying to test on unlisted arches. For example, a binary-only package which is only supported upstream on ppc and x86 might use:

KEYWORDS="-* ppc x86"

This is different in implication from "ppc x86" — the former implies that it will not work on other arches, whereas the latter implies that it has not been tested.

Do not use the * or ~* special keywords in ebuilds.

Note: Usually, "live" ebuilds (see Version Control System (VCS) sources) do not specify a KEYWORDS variable.

Equal visibility requirement

An ebuild must not depend upon any package that is of a lower keyword level than itself. For example, if foo-1.2 depends upon bar-1.2, and bar-1.2 is ~x86, then foo-1.2 must not be marked stable on x86 unless bar-1.2 is also stabilized.

You may assume that if a user accepts ~arch for a given arch then they also accept arch.

For optional dependencies, all possible dependencies must satisfy the above. Note that certain USE flags can be forcibly disabled on a per-profile basis — talk to the arch teams if you require this. For either-or dependencies, at least one of the options must be of equal or better visibility than the package in question.

Hard masks

The package.mask file can be used to 'hard mask' individual or groups of ebuilds. This should be used for testing ebuilds or beta releases of software, and may also be used if a package has serious compatibility problems. Packages which are not hard masked must not have a dependency upon hard masked packages.

It is good practice to file a bug for ebuilds listed in package.mask to allow feedback to be gathered in one location and to reduce the chance of forgetting about it. Mention the bug number in the mask message.

The only time it is acceptable for a user to see the Possibly a DEPEND problem error message is if they have manually changed visibility levels for a package (for example, through /etc/portage/) and have missed a dependency. You should never commit a change which could cause this error to appear on a user system.