http://dev.gentoo.org/~dang/masked.txt
What does it mean when a package is masked?
There are several levels of masking, with a range of severity. First, a description of
keywording.
Keywords are a way of marking a package for a particular architectures. Each architecture has a
keyword named after it (x86 for x86-class CPUs, amd64 for x86_64 class CPUs, mips, sparc, and so
on). Each version of a package has a list of the keywords that apply to that package. There
are four levels of keywording:
arch (x86, amd64, mips, etc.):
This means that the version of the package is tested on that arch, and considered stable.
This is commonly called "stable"
~arch (~x86, ~amd64, ~mips, etc.):
This means that the version of the package has been tested at lest somewhat on the arch, and
is considered usable, but more tesing is needed before it is considered stable. This is
commonly called "testing".
No Keyword
This means that the version of the package has not been tested for the arch. It may or may
not work.
-arch (-x86, -ame64, -mips, etc.)
This means that the package is known to be broken on the arch. Most likely, it means that
it can never run on the arch; for example, and x86 binary-only package will be -mips,
because it can never run on mips.
Unless you specify otherwise, portage will only consider stable (arch keyworded) packages to
install for your arch, where your arch is determined by your profile. You can override this on
a per-package basis (more below) or globally by setting ACCEPT_KEYWORDS in /etc/make.conf. It
is generally considered a very bad idea to set ACCEPT_KEYWORDS to something other than your
arch, as things will likely break. However, it is common, for example, for developers to have a
development machine that runs a fully ~arch system (ACCEPT_KEYWORDS="amd64 ~amd64" on amd64).
The first type of masking, then, is keyword masking. A version of a package is keyword masked
if it has a keyword lower on the above list than your ACCEPT_KEYWORDS allows. Typically, this
means you're running a stable system and the version of the package is unkeyworded on your arch
or keyworded unstable on your arch. As you go down the list, the masking becomes more severe:
unmasking a ~arch version of a package is probably not a big deal; unmasking an unkeyworded
version of a package may be a problem, but may not; and unmasking a -arch version of a package
is a very bad idea, unless you are working on fixing it.
The second type of masking is called package masking, because the package (or version of the
package) has an entry in the package.mask file. The main package.mask file lives in
$PORTDIR/profiles/package.mask, and is maintained by the gentoo developers. Versions of
packages get entries in this file when the maintainer thinks that there is a good reason to have
it in the tree, but it should not be used by the general public yet. Examples of reasons for
this may be that a version of a package (either stable or unstable) has been discovered to have
a severe problem, and the developer is working on fixing it; an example of this may be that a
newly committed version of a library breaks existing programs. Another common case is that a
set of packages should be released together; for example, a new Gnome or KDE release. It's
common to add the new release the package.mask file, put the new versions in the tree, test for
a couple of days, and then unmask the whole set together. Another common reason is that the
version is considered alpha or beta by upstream, but the developer wants to share testing with
some users; this case is becoming less common, as developers move to using overlays. Regardless
of the reason, each entry in the package.mask file has a comment describing the reason that
version was masked. Read this before deciding if it's safe to unmask.
So, you ask, how to I unmask a version of a package? Well, that depens on how it's masked.
Package masked packages can by unmasked by placing the correct depend atom in
/etc/portage/package.unmask Depend atoms are described in the ebuild(5) man page, but for
unmasking packages they generally come in the form:
=category/package-1.2.3-r4
This will unmask the single version of the give package, which is generally what you want unless
you really know what you're doing.
Keyword masked packages can be unmasked by placing the correct depend atom followed by a keyword
in /etc/portage/package.keywords like so:
=category/package-1.2.3.4-r4 ~amd64
This will emerge that version of the package only if ~amd64 is in it's keywords. As a shortcut,
you can leave off the the keyword, which means "arch ~arch". You can put more than one keyword
on the line, and any that match apply.
Okay, practical example:
Suppose I want nikibot:
[14:59:53 athena] ~> emerge -av nikibot
These are the packages that would be merged, in order:
Calculating dependencies /
!!! All ebuilds that could satisfy "nikibot" have been masked.
!!! One of the following masked packages is required to complete your request:
- net-irc/nikibot-0.8 (masked by: package.mask, missing keyword)
# Matti Bickel <mabi@gentoo.org> (28 Feb 2007)
# Fails to compile against lua-5.1.1, no upstream release for 3 years
For more information, see MASKED PACKAGES section in the emerge man page or
refer to the Gentoo Handbook.
Uh oh, it's package masked, and Matti says it fails to compile against a recent lua. Still, I
want nikibot; maybe I'm planning on fixing it. So, I'll do this:
[15:01:45 athena] ~> echo "=net-irc/nikibot-0.8" >> /etc/portage/package.unmask
[15:01:54 athena] ~> emerge -av nikibot
These are the packages that would be merged, in order:
Calculating dependencies /
!!! All ebuilds that could satisfy "nikibot" have been masked.
!!! One of the following masked packages is required to complete your request:
- net-irc/nikibot-0.8 (masked by: ~amd64 keyword)
# Matti Bickel <mabi@gentoo.org> (28 Feb 2007)
# Fails to compile against lua-5.1.1, no upstream release for 3 years
For more information, see MASKED PACKAGES section in the emerge man page or
refer to the Gentoo Handbook.
Now, it's masked by a ~arch keyword (~amd64 for me). To unmask this, I need to run this:
[15:07:05 athena] ~> echo "=net-irc/nikibot-0.8 ~amd64" >> /etc/portage/package.keywords
[15:07:05 athena] ~> emerge -av nikibot
These are the packages that would be merged, in order:
Calculating dependencies... done!
[ebuild N ] dev-lang/lua-5.0.2 USE="readline" 186 kB
[ebuild N ] net-irc/nikibot-0.8 197 kB
Total: 2 packages (2 new), Size of downloads: 383 kB
Would you like to merge these packages? [Yes/No]
There you go, it's ready to emerge.
