<e>Terminology</e>: The term 'package' refers to an entire directory, for example
<c>app-editors/vim</c> <d /> it does <e>not</e> refer to a specific version. The terms
'ebuild' or 'package version' are used when this meaning is intended. This
distinction is important.
Every ebuild must specify a <c>KEYWORDS</c> variable. This variable is used to
indicate the suitability and stability of both the package and the ebuild on
each given arch (<c>sparc</c>, <c>ppc</c>, <c>x86-obsd</c>, ...).
The term 'arch' is used in this sense for historical reasons. As a result
of <uri link="https://wiki.gentoo.org/wiki/GLEP:22">GLEP 22</uri>
and the various non-Linux ports, this is no longer a particularly
A sample <c>KEYWORDS</c> entry might look like:
KEYWORDS="x86 sparc ~mips ~ppc ~ppc-macos -ia64"
The different levels of keyword are:
<c>arch</c> (<c>x86</c>, <c>ppc-macos</c>)
Both the package version <e>and</e> the ebuild are widely tested, known to work
and not have any serious issues on the indicated platform.
<c>~arch</c> (<c>~x86</c>, <c>~ppc-macos</c>)
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 <c>arch</c>.
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
<c>-arch</c> (<c>-x86</c>, <c>-ppc-macos</c>)
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 <c>-*</c> keyword is special. It is used to indicate package versions which are
not worth trying to test on unlisted archs. For example, a binary-only package
which is only supported upstream on <c>x86</c> and <c>ppc</c> might use:
KEYWORDS="-* x86 ppc"
This is different in implication from <c>"x86 ppc"</c> <d /> the former implies that
it will not work on other archs, whereas the latter implies that it has not been
Do <b>not</b> use the <c>*</c> or <c>~*</c> special keywords in ebuilds.
<title>Equal Visibility Requirement</title>
An ebuild <b>must not</b> depend upon any package that is of a lower keyword level
than itself. For example, if <c>foo-1.2</c> depends upon <c>bar-1.2</c>, and
<c>bar-1.2</c> is <c>~x86</c>, then <c>foo-1.2</c> must <b>not</b> be marked stable on
<c>x86</c> unless <c>bar-1.2</c> is also stabilised.
You may assume that if a user accepts <c>~arch</c> for a given arch then they also
For optional dependencies, all <e>possible</e> dependencies must satisfy the above.
Note that certain <c>USE</c> flags can be forcibly disabled on a per-profile basis
<d /> talk to the arch teams if you require this. For either-or dependencies, <e>at
least one</e> of the options must be of equal or better visibility than the
package in question.
The <c>package.mask</c> 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 <b>not</b> have a dependency upon hard masked
The only time it is acceptable for a user to see the <c>Possibly a DEPEND
problem</c> error message is if they have manually changed visibility levels for a
package (for example, through <c>/etc/portage/</c>) and have missed a dependency.
<b>You should never commit a change which could cause this error to appear on a
<title>Keywording New Packages</title>
New packages should be marked as <c>~arch</c> only upon
architectures for which the committing developer has tested.
Do <b>not</b> assume that your package works on all architectures. Do <b>not</b>
assume that user submitted ebuilds will have correct <c>KEYWORDS</c> <d /> chances are
they just copied from somewhere else. Do <b>not</b> assume that upstream's
'supported architectures' list is correct. Do <b>not</b> assume that because your
code is written in Perl / Python / Java / whatever that it will run on other
archs (there is at least one case of a <c>vim</c> script which only worked on
Note that most (non-x86) archs expect you to be on the arch team and bugzilla
alias if you are committing packages with keywords for that arch, and may have
additional requirements of which you should be aware (on <c>mips</c>, for example,
there are multiple ABIs and byte orders to consider <d /> a package working on your
<c>o32</c> box may not work on <c>o64</c> or <c>n32</c>). Contact the individual arch
teams for details.
It's important to note that alternative arches (like alpha, ia64, s390,
sh, sparc, hppa, ppc*) are mainly undermanned arches, some of them are
slow, they have more basic problems and have a small userbase. Just file
bugs for these architectures when a package is going to be a dependency of a
package already keyworded.
Do <b>not</b> commit straight to <c>arch</c>.
<title>Keywording on Upgrades</title>
When upgrading, drop all existing keywords from <c>arch</c> to <c>~arch</c>, and leave
any existing <c>~arch</c> keywords intact. This must be done even if you <e>think</e>
you're just making a trivial fix <d /> there have been several examples of the
stable tree getting broken this way.
Sometimes you may need to remove a keyword because of new unresolved
dependencies. If you do this, you <b>must</b> file a bug notifying the relevant
This also applies to revision bumps, not just to upstream version changes.
<title>Moving from <c>~arch</c> to <c>arch</c></title>
Moving a package from <c>~arch</c> to <c>arch</c> is done only by the relevant arch teams.
If you have access to non-x86 hardware but are not on the arch teams, you may wish
to make individual arrangements <d /> the arch teams are happy for help, so long as
they know what is going on. Please note that <c>x86</c> is now no longer an exception
and stabilisation must be done through the <c>x86</c> arch team unless you have
individual arrangements <d /> see
<uri link="https://wiki.gentoo.org/wiki/GLEP:40">GLEP 40</uri>
for further details.
For a package to move to stable, the following guidelines must be met:
The package has spent a reasonable amount of time in <c>~arch</c> first. Thirty
days is the usual figure, although this is clearly only a guideline. For
critical packages, a much longer duration is expected. For small packages
which have only minor changes between versions, a shorter period is sometimes
The package must not have any non-<c>arch</c> dependencies.
The package must not have any severe outstanding bugs or issues.
The package must be widely tested.
If the package is a library, it should be known not to break any package which
depends upon it.
For security fixes, the "reasonable amount of time" guideline may be relaxed.
See the <uri link="http://www.gentoo.org/security/en/vulnerability-policy.xml">
Vulnerability Treatment Policy</uri>
<title>Removing Package Versions</title>
When removing ebuild, ensure that you do not remove the most recent version at
any given keyword level on any profile. The aim here is:
Never to force a downgrade. (Exception: occasionally you really do want to
force a downgrade, for example if the newly committed <c>foo-1.3</c> turns out
to be badly broken and that making everyone downgrade to <c>foo-1.2</c> is the
better option. This is rare.)
Do not break any existing dependencies.
If you would like a particular package version moved to stable on certain archs
so that you can tidy up, file a bug.