What does it mean when a package is masked?

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.