Gentoo Forums
Gentoo Forums
Gentoo Forums
Quick Search: in
GUIDE: proper ~arch (un)masking
View unanswered posts
View posts from last 24 hours

Reply to topic    Gentoo Forums Forum Index Duplicate Threads
View previous topic :: View next topic  
Author Message

Joined: 18 Sep 2003
Posts: 506
Location: Beacon, NY

PostPosted: Sun Jul 18, 2004 4:40 pm    Post subject: GUIDE: proper ~arch (un)masking Reply with quote

Ok, in #gentoo on freenode there are people coming in and out every 5 minutes with problems of masked packages. To solve the problem of helping every single person individually I am writing this small HOWTO so I can just answer these people with a nice easy link.

1 - What architecture means

Every computer system has a cpu. Every cpu has an architecture. Pentiums and Athlons have the x86 architecture. Macs have the ppc architecture. Opterons have the amd64 architecture, and so on. When you compile a programs source code what you are really doing is converting the text of the programming language i.e: C or C++ into assembly instructions for the particular processor i.e: x86 machine code. The machine code is executable and ready to use. Because Linux is awesome and open source you can take the source code and build it for any architecture you want. This is how come linux can run on all kinds of different processors.

2 - Portage and Architectures

In portage, the gentoo package manager, every package has keywords. There are two keywords for each architecture. Some packages only work on particular architectures. And most packages need modification to work on different architectures. So every package has a set of keywords. For example go here. You will notice that wine as a + under x86 and a - under everythign else. This is because wine can only be run on x86 architecture. So you don't want to merge it if you have a ppc.

3 - Keywords

I said there were two keywords for each architecture. They are "arch" and "~arch". So for x86 you have "x86" and "~x86". "~arch" implies that the package is currently in testing. "arch" means that it is stable and ready to roll. So for a package like KDE you have multiple versions and it is under development all the time. So gentoo developers are really cool and they make ebuilds for versions of KDE as they come out. Sometimes even before they come out. If you go into /usr/portage/kde-base/kde you will see more than one ebuild. Right now I see ebuilds for versions 3.1.5 through 3.2.3. At the present time 3.2.2 is the stable "arch" ebuild and 3.2.3 is the testing "~x86" ebuild.


Assuming you have a working and good gentoo installation, portage (emerge) has a variable in it called ACCEPT_KEYWORDS. By default ACCEPT_KEYWORDS is set to "arch". This means that whenever you emerge a package it will emerge the stable version. This is good, especially if you don't want to have to mess around with broken ebuilds and things that don't work right. From my experience, depending on your hardware and what you do with it, using only arch packages and no ~arch packages reduces problems and frustration to almost nil.

5 - Why unmask

However, sometimes you need to use an ~arch package. This is especially true for desktop boxen. Maybe the newer version of a program has a new feature you can't wait to use. Maybe there is a new program released you want to try, but it isn't done testing yet. Maybe you use a 2.6 kernel and you have to use the testing version of the nvidia drivers. Never fear, gentoo accounts for this. It is possible, and good, to use mostly "arch" packages, but to still use a few packages as "~arch" on your system.

6 - What NOT to do

Here is how NOT to unmask a ~arch package. It used to be done back in the day, but it is now wrong. I Repeat, DO NOT DO THIS.
ACCEPT_KEYWORDS="~x86" emerge packagename

Why is this wrong you ask? It seems to work if you try it, but it is very bad. The first and major reason is this. Let's say you really want to try the new mplayer. But it is ~. So you do exactly what I just told you not to do. mplayer is dependent on a great many other packages depending on your USE flags. If you do this, then all of those dependencies will also be merged as ~x86. You don't want that! You only want to emerge the testing version of mplayer, you don't also want the testing version of arts or svgalib or lame or any other mplayer dependencies. You just want the testing version of mplayer. Secondly, if you do it this way portage will not "remember" that you want to use the ~ version of this package. So if it ever comes up for emerging it will try to downgrade you. Accidentally downgrading something like nvidia-kernel if you use a 2.6 kernel with 4k stacks could be disastrous.

7 - What TO do

Here is what you've been waiting for. How to unmask a package. This is what to do if you want to run a stable system, but want to use the testing version of a select few packages. I have used x86 as the example arch here. If you use a different arch just replace x86 with ppc or amd64 or whatever.

First, become root
prompt $ su

Next, make the file /etc/portage/package.keywords
prompt $ mkdir /etc/portage
prompt $ touch /etc/portage/package.keywords

Edit the file
prompt $ nano -w /etc/portage/package.keywords

For each package you want to unmask put one line in the file. Here is an example file.
media-video/mplayer ~x86
media-video/nvidia-glx ~x86
media-video/nvidia-kernel ~x86
net-www/mozilla-firefox ~x86

What this does is it tells portage to use the testing versions of mplayer, nvidia-kernel, nvidia-glx and firefox. Portage will continue to use the stable versions of all other packages. For every package you want to run unstable add another line to this file. After you add the line to the file just emerge it like normal and it will emerge the testing version. I must warn you though, that it is very difficult to go backwards. As soon as you set something to use testing it might be impossible to revert to stable. Only use testing packages if absolutely necessary.

8 - If you live dangerously

On my computer at work and on my servers I do exactly what I have described above. Those computers are important and I can't afford to fiddle with them. However, on my desktop machine I walk on the wild side. Every single package on my desktop box is ~x86. How do I do this? It is simple. In the file make.conf add a single line.

However, unless you plan to fiddle around with broken ebuilds, file bug reports and all that other garbage, don't do this. I guarantee you will come across problems that may be difficult to fix. Often the only fix is waiting for someone else to update the ebuilds in portage and to re-sync.

9 - Hard masking

When I said there were only two keywords I kind of lied, but not really. Some packages are not arch or ~arch, they are what is known as hard masked. I'm not going to tell you how to merge packages which are hard masked. The reason is that you should never emerge packages that are hard masked. Most often hard masking means that the package is in direct conflict with something else you have already emerged. The only way to fix it is to unmerge the conflicting package. The second most often reason is because the package is known to be completely broken. I am not going to advocate stupidity by telling people how they can emerge completely broken software on their system.

10 - Conclusion

I wrote this guide once through with barely any proof reading. I can guarantee that there are errors of all sorts throughout this post. I don't think any of them are major though. Because this is a good forum I have the power to edit this post many times. Please inform me of errors and I will fix them. If you come across anyone who needs help unmasking packages please point them at this post to save yourself a great deal of typing. Thank you and good day.
Back to top
View user's profile Send private message
Retired Dev
Retired Dev

Joined: 27 May 2003
Posts: 2634
Location: Jesus College, Oxford

PostPosted: Sun Jul 18, 2004 9:12 pm    Post subject: Reply with quote

I haven't got time to read all of that, but just in case I know something you don't, have a read of the first link in my sig, which may or may not teach you something (depends how good you are :P ).
Reality is for those who can't face Science Fiction.

emerge -U will kill your Gentoo
ecatmur, Lord of Portage Bash Scripts
Back to top
View user's profile Send private message

Joined: 04 May 2003
Posts: 2072
Location: /usa/utah

PostPosted: Fri Aug 06, 2004 6:10 pm    Post subject: Reply with quote

If we put ~x86 for packages in package.keywords -- then what is the point of package.unmask and package.mask? I'm lost.

I tried putting "=package-cat/package-name-version" in /etc/portage/package.unmask and it still has it masked. Is it to unmask things only that are hard masked?
If it ain't broke, tweak it. dvds | blurays | blog | wiki
Back to top
View user's profile Send private message

Joined: 27 Feb 2003
Posts: 1493
Location: Germany, Hamburg

PostPosted: Fri Aug 06, 2004 6:29 pm    Post subject: Reply with quote

sdibb wrote:
If we put ~x86 for packages in package.keywords -- then what is the point of package.unmask and package.mask? I'm lost.

Have a look at #9 above.

There are multiple ways a package can be masked:
~arch, -arch, -*: That's what you "fix" with package.keywords
package.mask: That's what package.keywords is for
profile: There is a way to unmask profile-masked ebuilds, but I forgot how to. But, anyway, you REALLY shouldn't do that.
Back to top
View user's profile Send private message

Joined: 17 Jul 2003
Posts: 618

PostPosted: Fri Aug 06, 2004 10:01 pm    Post subject: Reply with quote

Thanks for the nice post.

is there a way to add all the dependency of one package in the package.keywords file ? Because, I often come across this issue, if ~x86 of package A depends on ~x86 of package B and so on, then it's often a iterative process to add all such packages to the package.keywords .. is there a way of saying "A and all unstable packages it depends on, be added to package.keywords" ?
Back to top
View user's profile Send private message

Joined: 27 Jun 2003
Posts: 4975
Location: Gothenburg, Sweden

PostPosted: Sat Aug 07, 2004 12:25 am    Post subject: Reply with quote

Moved from Portage & Programming. As so many times before, someone has already thought of this great idea: How to use portage correctly. In fact, there is also an FAQ: GF5: Masked Packages

nsahoo: :arrow:
Please read our FAQ Forum, it answers many of your questions.
irc: #gentoo-forums on
Back to top
View user's profile Send private message
Display posts from previous:   
Reply to topic    Gentoo Forums Forum Index Duplicate Threads All times are GMT
Page 1 of 1

Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum