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 (
KEYWORDS entry might look like:
KEYWORDS="-ia64 ~mips ~ppc sparc x86 ~ppc-macos"
The different levels of keyword are:
-* 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
x86 might use:
KEYWORDS="-* ppc x86"
This is different in implication from
"ppc x86" — the former implies that
it will not work on other archs, whereas the latter implies that it has not been
Do not use the
~* special keywords in ebuilds.
KEYWORDSvariable, or assign the empty string to it.
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
foo-1.2 must not be marked stable on
bar-1.2 is also stabilised.
You may assume that if a user accepts
~arch for a given arch then they also
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.
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
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
~archonly upon architectures for which the committing developer has tested.
Do not assume that your package works on all architectures. Do not
assume that user submitted ebuilds will have correct
KEYWORDS — chances are
they just copied from somewhere else. Do not assume that upstream's
'supported architectures' list is correct. Do not 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
vim 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
mips, for example,
there are multiple ABIs and byte orders to consider — a package working on your
o32 box may not work on
n32). 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 not commit straight to
When upgrading, drop all existing keywords from
~arch, and leave
~arch keywords intact. This must be done even if you think
you're just making a trivial fix — 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 must file a bug notifying the relevant arch teams.
This also applies to revision bumps, not just to upstream version changes.
Moving a package from
arch 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 — the arch teams are happy for help, so long as
they know what is going on. Please note that
x86 is now no longer an exception
and stabilisation must be done through the
x86 arch team unless you have
individual arrangements — see
for further details.
For a package to move to stable, the following guidelines must be met:
~archfirst. 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 appropriate.
For security fixes, the "reasonable amount of time" guideline may be relaxed. See the Vulnerability Treatment Policy
If you maintain an architecture-independent package (data files,
icons, pure Perl,...) then you may request that your
package be stabilized on all arches at once. To do this — when
you are filing the stabilization bug — please add the keyword
ALLARCHES in addition to
STABLEREQ and CC the
arches that you would like to stabilize.
The arch teams, when encountering the
should perform their usual set of tests on a single convenient
architecture. Then, if everything works, stabilize not only the
arch that was used during testing, but also all of the other
arches in CC on the bug. Afterwards, the CC field can be cleared
and the bug closed if appropriate.
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:
foo-1.3turns out to be badly broken and that making everyone downgrade to
foo-1.2is the better option. This is rare.)
If you would like a particular package version moved to stable on certain archs so that you can tidy up, file a bug.