# How to use portage correctly

## GaMMa

How to use portage correctly

Revised: 7/10/04

The Spanish version of this guide is available at https://forums.gentoo.org/viewtopic.php?t=195629 and was translated by ArsDangor.

Introduction:

Gentoo's portage system is an excellent resource when used properly. Incorrect usage can lead to a bloated system with untraceable packages as well as a broken world file. Following this guide will allow the user to have a better system.

Emerging packages:

When emerging an unstable package it is recommended that one emerges the package 

```
emerge foo
```

DON'T use ACCEPT_KEYWORDS="~x86" for it'll emerge dependencies with ~x86 which may not be wanted. 

What is recommend is that one tries emerging the ebuild first, and if it complains the ebuild is unstable take the appropriate action below. Once that is resolved try emerging the package again and it may complain about a dependency. Take appropriate action for the dependency and try to emerge the package again. Keep doing this until the package is emerged. Yes it may seem like a pain, but at least you know what's getting put on your system as far as unstable packages.

WARNING: Directly emerging an ebuild (emerge foo.ebuild) has caused problems for some users and should NOT be used. In a few situations it refuses to add packages to the world file. Also using this method the user will not be notified of new unstable releases of this package, even if they contain essential security fixes.

Maintaining packages:

Sometimes when running 'emerge -u world' portage wants to downgrade packages. To unmask packages so portage doesn't try to downgrade them make the /etc/portage directory if it's not already there. 

```
mkdir /etc/portage
```

Inside of the file /etc/portage/package.keywords add the complete package name followed by ~x86. For example to have portage recognize we want to have Gaim unstable ebuilds on our system we input the line 

```
echo net-im/gaim ~x86 >> /etc/portage/package.keywords
```

Do this for all the unstable packages you don't want downgraded. 

We can also enable specific unstable versions of a certain package, so when the next unstable version comes out, the system won't auto upgrade that package. We do this by following this syntax:

```
echo =app-misc/foo-version ~x86>> /etc/portage/package.keywords
```

The line above will only allow that one specific version of the package to be emerged. However, revision bumps will still be ~arch masked. In order to allow revision bumps to be marked as stable in addition to the specific version we use the following code instead

```
echo ~app-misc/foo-version ~x86>> /etc/portage/package.keywords
```

Where version is the version without the -rX.

NOTE: It's a lot easier to keep track of packages if you keep this list alphabetized. 

WARNING: Using 'emerge -U world' may cause problems with the system and should NOT be used. Earthwings discusses why it's bad here https://forums.gentoo.org/viewtopic.php?t=167323

Sometimes, however, portage still wants to downgrade a package. Generally, there is a good reason behind it and it's best to downgrade it. There are exceptions though; for example linux-headers wanted to revert to 2.4.x when I have a 2.6.x kernel. Linux-headers is the only package that should use this method, others should use the previous method or be downgraded. In /etc/portage/package.keywords we add a line or do 

```
echo sys-kernel/linux-headers -* >> /etc/portage/package.keywords
```

Packages sometimes try to creep back onto the system when they aren't needed. Users of xorg-x11 may have noticed xfree trying to make its way back onto the system. To fix this, in /etc/portage/package.mask add a line or type 

```
echo x11-base/xfree >> /etc/portage/package.mask
```

Packages are also hard masked from time to time. One package I know that is for example is realone. It's hard masked due to the fact there is a security hole that could lead to a compromised system. If for some reason you want to use realone though, there's a package.unmask file. Make a /etc/portage/package.unmask and enter this command 

```
echo media-video/realone >> /etc/portage/package.unmask
```

Also if you don't want a package to include a particular USE flag, there's a package.use. Make a /etc/portage/package.use and enter a function similar to this into a terminal 

```
echo net-p2p/bittorrent -X >> /etc/portage/package.use
```

This would tell portage not to include X support when emerging bittorrent.

Maintaining the world file:

Sometimes packages aren't added to the world file for whatever reason. To [attempt to] fix your world file and add the packages type

```
regenworld
```

There's also another thread that provides information on how to fix your world file if regenworld doesn't work. https://forums.gentoo.org/viewtopic.php?t=136627

Conclusion:

Using this method you'll allow 'emerge -u world' to become a reality and you'll have a bleeding edge system.

```
emerge -uDav world
```

Is the best way to upgrade the world. u is for upgrade, D is for deep, a stands for ask and v is verbose, and tells the USE flags that will be used in each package.

I recommend trying ecatmur's cruft script to keep your install neat and clean!

https://forums.gentoo.org/viewtopic.php?t=152618

Any revisions/adds to this send me a PM. Yes it may seem like a dumb topic, but you'd be surprised at the people that use portage wrong.

Thanks to everyone who contributed to this guide and proved me wrong in the process  :Smile: . Your countless emails and PMs helped make this guide what it is now.

----------

## ozonator

 *GaMMa wrote:*   

> So there's an unstable package in the system, and emerge -u world wants to downgrade it.

 

Uhm, you could use 'emerge -U world' instead.  Yes, sometimes portage may still want to downgrade something, but that's typically because the ebuild for something that's installed is no longer in portage; assuming you're not running completely with ACCEPT_KEYWORDS="~arch", emerge will default to installing the latest stable version, which typically is older than the version installed (likely masked at the time it was emerged).

As for it never being advisable to emerge an ebuild directly, it's sometimes useful:  the Gentoo docs cover this, and give examples of when it might be appropriate.

----------

## GaMMa

Emerging an ebuild directly isn't a smart idea like I said because emerge --depclean sees them as unneeded dependencies. I'm sure there are other reasons besides that, but that alone should be something to consider.

Why emerge -U shouldn't be used:

 *Quote:*   

> 
> 
> Ok, here are two reasons why "-U" is drop dead ugly (bookmarking this now so in the future I can link to it rather then writing it again and again Wink )
> 
> Reason 1: Problems with SLOTs
> ...

 

https://forums.gentoo.org/viewtopic.php?t=167323

----------

## ozonator

Ahhh.  I stand corrected.  When first I read your response, it seemed that the examples (which include the 'missing ebuild' example I suggested) just showed a shortcoming in the way '-U' works.  Re-reading your first post, however, I see now you had mentioned '-U' as being problematic, even buggy (as the examples you cite suggest), so I shouldn't be surprised you had a good response ready.   :Smile:   Sorry to jump the gun there.  And indeed, another post in the thread you quoted from suggests even that '-U' may even be superfluous now.  Thanks for the correction, and your explanation of package.keywords et al.

----------

## GaMMa

Until I saw that thread yesterday I use to always emerge ebuilds directly. I think tried an emerge -e world and noticed none of my ebuilds were getting emerged. I think tried an emerge -p --depclean (a feature that removes packages that aren't needed) and noticed all my ebuilds I emerged directly were there along with their dependencies. I then concluded that seriously messes up portage, and shouldn't be used.

I then ran 'qpkg -d -I -v' and noticed I had a few installs of the same program on my system. So then I decided I had to make a guide to how to use portage.

Today I'm also fixing my system as well as running an emerge -e world. Now that I followed what I said in the guide I can run emerge -uD world without worries.

 *Quote:*   

> root:/home/gamma% emerge -puD world
> 
> These are the packages that I would merge, in order:
> 
> Calculating world dependencies ...done!
> ...

 

You have to love it  :Very Happy: . BTW I've had this install for over a year and yesterday doing that command would have returned 100 or so results because I love to use unstable packages.

----------

## ozonator

 *GaMMa wrote:*   

> Until I saw that thread yesterday I use to always emerge ebuilds directly. I think tried an emerge -e world and noticed none of my ebuilds were getting emerged. I think tried an emerge -p --depclean (a feature that removes packages that aren't needed) and noticed all my ebuilds I emerged directly were there along with their dependencies. I then concluded that seriously messes up portage, and shouldn't be used.

 

I'm not sure that's because they were emerged directly -- I just tried the same thing, and noticed a lot of things there that I'm sure I didn't emerge directly, but did with the usual "emerge foo" command.  The reason they seem to be picked up by depclean is that those packages aren't listed in /var/cache/edb/world -- i.e., for some reason, emerging them didn't put a corresponding entry in the world file.  Interestingly, if I check with 'emerge -ep world', those packages not in the world file are still listed among those that would be emerged, so portage somehow knows they're installed even though they're not in the world file.

I just tried running 'regenworld', which did seem to add some things to my 'world' file, but not all the non-essential things I want to have installed.  One example:  app-text/gv, for which I noticed a newer stable version available -- I emerged the new version, and voila, it put an entry in the 'world' file.  This has me wondering:  could it be that an older version of portage had a bug whereby it didn't always maintain the 'world' file properly?  Just a thought.  Otherwise, I don't have an explanation.

Glad to hear you've got your system clean and in shape!  If you can't tell, this thread has me thinking about that, too (I'm a few months shy of the second anniversary of the initial install on one of my machines, so it's about time!).  I've even started using package.keywords.   :Smile: 

----------

## GaMMa

Yea package.keywords is a great resource. People seriously need to read more into using portage. I know this guide isn't the best and people assume because it emerges everything is fine, but you can end up having packages on your system you can't account for or multiple slotted items you don't know about by not following the guide. Live and learn  :Very Happy: .

----------

## teedog

More about why emerge -U is a bad idea.  Always use package.keywords instead.

https://forums.gentoo.org/viewtopic.php?p=1060314#1060314

----------

## mike4148

```
ACCEPT_KEYWORDS="~x86 emerge foo"
```

should be

```
ACCEPT_KEYWORDS="~x86" emerge foo
```

----------

## teedog

 *mike4148 wrote:*   

> 
> 
> ```
> ACCEPT_KEYWORDS="~x86 emerge foo"
> ```
> ...

 

And you should emphasize that it is a bad idea.  The command

```
ACCEPT_KEYWORDS="~x86" emerge foo
```

will cause all the dependencies of foo to be merged with the ~x86 keyword, which is probably not what you want.  One should put the necessary ~x86 packages in /etc/portage/package.keywords.

Thanks for pointing out "regenworld".  Didn't know about that.

----------

## GaMMa

Fixed the mistake, I had everything in quotes then decided to make it look pretty, I guess I forgot one quotes and to remove the one on the end.

teedog: if people were to ACCEPT_KEYWORDS="~x86" wouldn't emerge -pu world pick up on it and ask that you downgrade? And if it's asking you downgrade, THEN you add it to packages.keywords.

The reason I see doing it this way is better is because say you have a package foo that only has foo-1.0.ebuild. The user adds the package to package.keywords and emerges the program. Little do they know they're really emerging a stable version. Later foo has another version, which is marked unstable. Now the user doesn't know it's unstable, yet he/she will be prompted to upgrade and they'll be going from stable to unstable packages without even realizing it. Plus it keeps the package.keywords less bloated.

Again I could be wrong, please tell me if I am.. I'll fix it  :Very Happy: .

----------

## Duty

And shouldn't

```
echo x11-base/xfree >> /etc/portage/package.keywords
```

be

```
echo x11-base/xfree >> /etc/portage/package.mask
```

 ?

----------

## teedog

 *GaMMa wrote:*   

> 
> 
> teedog: if people were to ACCEPT_KEYWORDS="~x86" wouldn't emerge -pu world pick up on it and ask that you downgrade? And if it's asking you downgrade, THEN you add it to packages.keywords.
> 
> 

 

Yes, if you do "ACCEPT_KEYWORDS=~x86 emerge gnome" when you do "emerge -up gnome" Portage will ask you to downgrade.  True, you can then add gnome to package.keywords.

 *GaMMa wrote:*   

> 
> 
> The reason I see doing it this way is better is because say you have a package foo that only has foo-1.0.ebuild. The user adds the package to package.keywords and emerges the program. Little do they know they're really emerging a stable version. Later foo has another version, which is marked unstable. Now the user doesn't know it's unstable, yet he/she will be prompted to upgrade and they'll be going from stable to unstable packages without even realizing it. Plus it keeps the package.keywords less bloated.
> 
> 

 

But why would a user add foo ~x86 to package.keywords unless he/she specifically wants to use the bleeding edge foo builds from now on?

To restate the reason for not doing "ACCEPT_KEYWORDS=~x86 emerge foo": If you do that, all dependencies of foo will be emerged with keyword ~x86.  That can create a major problem when you try to do "emerge -u world" as Portage will try to downgrade everything that is ~x86, and there might be a LOT of them.  If you place foo ~x86 in package.keywords, then only foo will be emerged with ~x86; all dependencies will be x86 unless otherwise specified in the ebuild.  If the foo.ebuild specifically asks for other ~x86 packages, you can place those in package.keywords too.

----------

## GaMMa

I guess it's a matter of opinion, but your way may be easier. The thing is if there's 50 dependencies that are masked, you do emerge foo.ebuild you add dep1, then run it again and add dep2, that could take a while. As opposed to doing a emerge -puD world and c/ping all the deps that want to be downgraded.

----------

## teglsbo

 *teedog wrote:*   

> 
> 
> But why would a user add foo ~x86 to package.keywords unless he/she specifically wants to use the bleeding edge foo builds from now on?
> 
> 

 

Example:

I wanted to have mosml. But there was only a masked package available at the time, so I installed the masked package.

When a stable package becomes available I want to use that, and not use any masked mosml packages after that.

Can that be done in an automatic way?Last edited by teglsbo on Fri May 21, 2004 12:08 am; edited 1 time in total

----------

## tomk

Nice guide   :Smile: 

For fixing your world file, there's a FAQ about it, which explains the use of regenworld and some other commands if regenworld doesn't work.

----------

## calhoun

 *GaMMa wrote:*   

> 
> 
> The reason I see doing it this way is better is because say you have a package foo that only has foo-1.0.ebuild. The user adds the package to package.keywords and emerges the program. Little do they know they're really emerging a stable version. Later foo has another version, which is marked unstable. Now the user doesn't know it's unstable, yet he/she will be prompted to upgrade and they'll be going from stable to unstable packages without even realizing it. Plus it keeps the package.keywords less bloated.
> 
> Again I could be wrong, please tell me if I am.. I'll fix it .

 

What if you just name the emerged ~x86 version in the keyword file without the "~x86".  Will this allow you to run the unstable version, while waiting for the next stable version?  This way portage won't assume that you want all future ~x86 versions, but still allow you to run "emerge uDp world" without downgrading the installed apps.  

With the package files below, I can run "emerge uDp world" and it won't try to downgrade my apps.  This is how I have mine setup, but can't confirm that the apps will update until these applications are upgraded.

```
package.keywords

::::::::::::::

=x11-misc/superkaramba-0.33-r1

=sys-apps/qtparted-0.4.4

=app-cdr/cdrtools-2.01_alpha27-r1

=media-gfx/gimp-2.0.0

::::::::::::::

package.mask

::::::::::::::

<media-gfx/gimp-2.0.0

```

----------

## gtaluvit

 *Quote:*   

> I guess it's a matter of opinion, but your way may be easier. The thing is if there's 50 dependencies that are masked, you do emerge foo.ebuild you add dep1, then run it again and add dep2, that could take a while. As opposed to doing a emerge -puD world and c/ping all the deps that want to be downgraded.

 

However, you don't know necessarily why they want to be downgraded.  They could have been removed from portage or you have a ~ dependency.  It is a pain (particularly with a Gnome 2.6 example) to have to put a seriously large list of ~x86 lines in your keywords file, but it solves any issues you have with doing a emerge -uDav world in the future.  Not only that, but if you decide to emerge something else from a stable branch, wouldn't you want it to use the most stable libraries available?  By only putting the hard dependencies that are actually required in keywords, you're only using unstable when necessary, not for an entire dependency tree.   Anyways, onto my suggestions: 

keywords can take versions, so if you only want a specific version installed, you can put a line such as: 

```
~media-sound/rhythmbox-0.8.1 ~x86
```

 which will allow me to emerge rhythmbox 0.8.1 but not any higher versions if they are masked.  The ~ before the line means that it will also allow installs of -r1, -r2, etc if there are updates.

kernel-headers DO NOT need to be version 2.6 for a 2.6 kernel.  2.4 works just fine.  You only need to go up to 2.6 if you want to use NPTL.  Search the forums but some people have had issues with the 2.6 headers with NPTL.  

In addition to package.mask and package.keywords, there is also package.unmask (for things that are hardmasked) and package.use.  I use package.use all the time for the bittorrent client.  I don't want X support so I have the line: 

```
net-psp/bittorrent -X
```

 which when emerging would be like 

```
USE=-X emerge bittorrent
```

Finally, you may want to mention 

```
emerge -uDav world
```

 as the line to update world.  u does the update, D for deep, v shows what the USE flags are going to be for the emerge, and a stands for ask.  a is better than using p for pause since you have to run emerge again without p to do the emerge while with a, you just type yes or no and you don't have to redetermine dependencies.

----------

## gtaluvit

Just for examples of these files:

```

::::::::::::::

package.keywords

::::::::::::::

~media-gfx/gimp-2.0.0 ~x86

~media-tv/xawtv-3.91 ~x86

~media-libs/xvid-0.9.2 ~x86

~media-gfx/icoutils-0.22.0 ~x86

~media-gfx/inkscape-0.38 ~x86

~dev-python/pyxdg-0.5 ~x86

~gnome-extra/gdesklets-core-0.26 ~x86

~media-sound/grip-3.2.0 ~x86

~media-libs/win32codecs-20031001 ~x86

~net-www/mplayerplug-in-2.60 ~x86

~x11-themes/redhat-artwork-0.95 ~x86

~media-sound/rhythmbox-0.8.1 ~x86

~app-emulation/wine-20040408 ~x86

~media-gfx/gnuplot-4.0 ~x86

#~media-video/mplayer-1.0_pre4 ~x86

# xorg

~x11-base/xorg-x11-6.7.0 ~x86

~x11-terms/xterm-184 ~x86

~sys-apps/utempter-0.5.3.2 ~x86

# Gnome 2.6 (Omitted)

::::::::::::::

package.mask

::::::::::::::

sys-fs/devfsd

dev-lang/tcl

dev-lang/tk

::::::::::::::

package.unmask

::::::::::::::

::::::::::::::

package.use

::::::::::::::

net-p2p/bittorrent -X

x11-themes/redhat-artwork -gtk

media-sound/lame -gtk

net-im/gaim -crypt

media-video/mplayer -gtk theora v4l2

media-libs/libquicktime -gtk

media-libs/libdv -gtk

media-libs/smpeg -gtk

media-tv/xawtv -quicktime

net-www/netscape-flash -gtk

net-mail/evolution -mozilla

x11-themes/lila-artwork -gtk

media-gfx/gnuplot gd

games-misc/fortune-mod offensive

```

----------

## NickDaFish

I'm trying to wrap my noodle around this.....

A few weeks ago I upgraded to rsync-2.6.2-r2, but there was a problem with the build so portage quickly reverted back to 2.6.0. The problem was with running an rsync server so I really don't care and I'm happy to leave it at 2.6.2-r2.... So I edited /etc/portage/package.keywords

And added:

```
net-misc/rsync
```

Portage now wants to downgrade me to 2.6.0-r1 rather than 2.6.0?!?!?

I'm very confused. I tryed serveral ways to un-keyword the specific version of rsync that I have installed as explained by gtaluvit (among others).... but I simply CANNOT get this to work. The above line is the only one that appears to have *ANY* effect on emerge (I have tryed ALOT of variations trying to add the version). This isn't urgent.... I'm just trying to figure out how all this is supposed to work..... if anyone can give me any tips/pointers/links ect on what I'm doing wrong I'd be most happy!

Many thanks.....

  Nick

----------

## gtaluvit

Rsync is now hardmasked over 2.6.2 according to /usr/portage/profiles/package.mask.  If you want an "emerge sync" to work properly, i'd STRONGLY recommend going back down to 2.6.0 unless there is something you need specifically in 2.6.2.  So, if that is the case, here is what you need to do.  

First, if you run

```
etcat -v rsync
```

 it probably looks like the following:

```

*  net-misc/rsync :

        [  I] 2.6.0 (0)

        [M~ ] 2.6.0-r1 (0)

        [M~ ] 2.6.2 (0)

        [M  ] 2.6.2-r1 (0)

        [M  ] 2.6.2-r2 (0)

        [M  ] 2.6.2-r3 (0)

```

Well, mine does, yours probably has the I next to 2.6.2-r2.  

Since the package is hard masked, you'll need to unmask it using /etc/portage/package.unmask.  If I add this to that file:

```
=net-misc/rsync-2.6.2-r2
```

that will unmask it.  Running the above etcat command again:

```
*  net-misc/rsync :

        [  I] 2.6.0 (0)

        [M~ ] 2.6.0-r1 (0)

        [M~ ] 2.6.2 (0)

        [M  ] 2.6.2-r1 (0)

        [   ] 2.6.2-r2 (0)

        [M  ] 2.6.2-r3 (0)

```

It looks like rsync would be perfectly happy now to update.  So, all you should need to do is modify your package.unmask file (create it if it doesn't exist) and add that line.  Your package.keywords file doesn't need an rsync entry. 

Also, if you don't have etcat, emerge app-portage/gentoolkit.  It has a lot of helpful utilities.

----------

## NickDaFish

 *gtaluvit wrote:*   

> Rsync is now hardmasked over 2.6.2 according to /usr/portage/profiles/package.mask.

 

 :Embarassed:  DOH!  :Embarassed: 

Yeah.... now that I see that it's masked this is all making sence now.

Thanks to all for the great thread BTW!

  Nick

----------

## GaMMa

Hey GaMMa again, forums.gentoo.org is supposed to notify me of updates to the thread, but never did. Luckily robmoss2k sent me a PM telling me my guide needed updating. I'm still here, the thread isn't dead and I just updated with the stuff people said. 

I'm currently fixing the part teedog and teglsbo noted, so give me a few minutes!

If you find any typos, or things I missed or need to add or aren't clear reply back. Thanks guys for helping with this thread.

UPDATE: All fixed; if I'm missing anything give me a yell!

----------

## amasidlover

 *GaMMa wrote:*   

> 
> 
> What is recommend is that one tries emerging the ebuild first, and if it complains the ebuild is unstable take the appropriate action below. Once that is resolved try emerging the package again and it may complain about a dependency. Take appropriate action for the dependency and try to emerge the package again. Keep doing this until the package is emerged. Yes it may seem like a pain, but at least you know what's getting put on your system as far as unstable packages.
> 
> 

 

I think I have created a couple of scripts which alleviate this. Firstly a script which will do the emerge -p process repeatedy, adding the masked dependencies (specific versions of) to package.keywords. Simply call the following with the package (with version number e.g. gnome-2.6.1_rc1):

```
#!/usr/bin/perl

my $package_keywords="/etc/portage/package.keywords";

my $unstable_package=$ARGV[0];

while(system("emerge -puD =$unstable_package 2>/dev/null >/dev/null") ) {

   $_ = `emerge -puD =$unstable_package 2>/dev/null`;

   if(/satisfy \"(.*)\"/i) {

      $package = $1;

      $package =~ s/>//g;

      print "Adding $package to $package_keywords\n";

      `echo "$package ~x86" >> $package_keywords`

   } else {

      print "Some other error occured...\n";

      exit;

   }

}

print `emerge -p =$unstable_package`;
```

Also, if you want to do a safe version of emerge -U world then the following script will do an emerge -pu world and add anything that portage tries to downgrade to package.keywords:

```
#!/usr/bin/perl

my $package_keywords="/etc/portage/package.keywords";

my $output = `emerge -puD world`;

my @lines = split(/\n/,$output);

my $ind;

foreach $ind (@lines) {

   $_ = $ind;

   if(/\[ebuild     UD\] (.*)-[0-9].*\[(.*)\]/i) {

      print "Adding package $1 version $2 to $package_keywords\n";

      `echo "=$1-$2 ~x86" >> $package_keywords`;

   }

}

print `emerge -puD world`;
```

I can't guarantee that these scripts will always work, or that they won't put rubbish in your package.keywords file. But they should be ok....

----------

## stonent

What would be the correct way to hard mask headers < 2.6 yet still leave the 2.6 headers masked as well? (Basically freezing the headers until they get unmasked by portage) 2.6.x headers are fine, but it is not necessary for me to have the latest every time they come out.

----------

## GaMMa

Would you do in package.mask:

<=sys-kernel/linux-headers-2.6.*

I haven't tried it; I just got back from vacation so I have 45 packages to emerge, so I'll try it out later.

----------

## Redeeman

my opinion is still that emerge -U is fine, and its great, i use it all time, nothing bad happend to me, so the quite robmoss2k said "emerge -U WILL kill your system" simply is wrong, ofcourse, in some odd cases his cases might be true, but its the same as buying a helmet because you think a meteor will hit your face.

true, that keeping track of keyworded packages is much easier with a package.keywords, but its not a must  :Smile: 

----------

## ArsDangor

Hi, GaMMa.

I've translated your how-to to Spanish. I've also included on my translation Earthwing's comments on emerge -U. My translation, of course, keeps links to the original posts (yours and Earthwing's), as well as your nicks as the authors for the guide (I've just translated, didn't add any new ideas).

I have not submitted it yet. I want to ask for your permission and the suggestions you may want to give me.

Thank you very much.

PS: My signature is the translation for this thread's title. It still links here. If you allow me to post my translation, it will link to it.

----------

## GaMMa

Yes you have my permission to use it. Reply back to this topic with the link to your Spanish translation, I'll add it to the link to the bottom of the guide.

----------

## yeags_1001

Thanks GaMMa, and to everyone on this thread ... this has been a big help getting my new system set up correctly and my gaining an understanding of portage/emerge.

I'm not sure if this is on topic or not but when I do an emerge info I get different USE flags than I defined in my make.conf, is this normal?

------------updated---------------

My bad, I should of RTFM before posting.  I now understand that USE flags are stacked from make.defaults and use.defaults, through make.conf and ENV.

------------updated---------------Last edited by yeags_1001 on Mon Jul 12, 2004 7:48 pm; edited 2 times in total

----------

## ArsDangor

Thank you for your permission.  :Smile: 

The translation is on https://forums.gentoo.org/viewtopic.php?t=195629&sid=7910287662fbafd02667062cf724a2c3

and is titled "Cómo usar Portage correctamente". My signature already links to it.

----------

## GaMMa

Looks good, I skimmed through it (mi Espanol es muy malo), but good work. If anyone else wants to translate to another language feel free to post here. A German or French version would be nice.

----------

## don quixada

How do you unmask a bunch of related ebuilds? For example, I have just installed gdesklets-core and now want to install the desklets themselves to try them out. To me, it would make sense to put 

```

x11-plugins/desklet-* ~x86

```

in my package.keywords file. However this doesn't work. Am I asking the impossible?

Thanks,

dq

----------

## GaMMa

That's what I would have done, I tried it and that didn't work either. I tried doing something similar to this way back and one of the #gentoo developers told me that portage isn't equipped to handle that. I'm going to ask around later tonight and I'll post what I get for answers.

Update: It's one ebuilds per line, I guess it's either a security feature or programmers not adding wildcards for multiple packages.

----------

## karnesky

Rather than doing it by hand, you can do:

```
cd /usr/portage

ls -d x11-plugins/desklet-* | sed 's/$/ ~x86/' >> /etc/portage/package.keywords
```

where ~x86 is the keyword(s) you wish to apply.Last edited by karnesky on Tue Jul 27, 2004 4:29 am; edited 1 time in total

----------

## don quixada

Ahhh, very clever I must say. Sometimes I forget the power of the command line and its tools; however, you forget that one must add '~xarch' to the end of each line. Which, I'm sure, one can use more command line magic to solve this problem, perhaps by using 'awk', 'sed' et al.-- but I'm not gonna figure it out... too tired.

dq

----------

## karnesky

Good catch--I fixed my post to show how to use sed to append ~x86 to the end of all lines.

----------

## GaMMa

Dumb question, but are forums ever cleaned up? I don't want this post to get deleted if I don't have it backed up  :Very Happy: .

----------

## psyqil

Nope, normally posts are never deleted. Nonetheless, back it up  :Very Happy: 

----------

## Polynomial-C

Hi,

while using this howto for a long time myself I realized how many german users still don't know how to use portage correctly. So I translated the howto into german. For getting it proof-read first I created an OOo-document with the translation. You can find the document here

If you think it's a good idea having this howto in the german forum let me know and I'll post it there.

Poly

----------

## psyqil

 *Polynomial-C wrote:*   

> You can find the document here

 

Nope:

```
howto_-_portage_richtig_benutzen.sxw 29-Oct-2004 13:18    0 
```

 :Sad: 

----------

## Polynomial-C

Hi,

that's strange... can you get the file with wget?

[edit1]

```
gamemaster@breakmygentoo:~ # wget http://polynomial-c.homelinux.net/pub/gentoo/documentation/howto_-_portage_richtig_benutzen.sxw

--19:59:11--  http://polynomial-c.homelinux.net/pub/gentoo/documentation/howto_-_portage_richtig_benutzen.sxw

           => `howto_-_portage_richtig_benutzen.sxw'

Resolving polynomial-c.homelinux.net...

Connecting to polynomial-c.homelinux.net:80... connected.

HTTP request sent, awaiting response... 200 OK

Length: 20,003 [text/plain]

100%[====================================>] 20,003         9.59K/s

19:59:14 (9.57 KB/s) - `howto_-_portage_richtig_benutzen.sxw' saved [20003/20003]
```

[/edit1]

[edit2]

This can happen due to missing or incorrect mime-type. Please right klick on the above link and choose "save as" to download the file.

[/edit2]

Poly

----------

## psyqil

I tried both and got that 0-byte file, but now I tried again and it's here!  :Very Happy:  Reading now...

----------

## GaMMa

There's a portage guide in Gentoo Documentation now, so this guide is kinda obsolete :/

----------

## Polynomial-C

Hi,

@GaMMa: It's done, I like it, and I won't take it off my webpage unless you ask me for  :Smile: 

And unfortunately still many people follow the link in my sig and later tell me, what a big mess they did with portage all the time before...

Poly

----------

## GaMMa

Yea I'm a fan of this guide too, it's simple and to the point. The other guide is alright. I'm also keeping this in my signature  :Very Happy: . You should have seen how many people were doing emerge -U world before this guide, and how many used portage incorrectly. Thanks again to those who helped  :Razz: .

----------

## kamina

So if I want to make sure that I don't get offered KDE or xorg updates unless there is a major update / ati updates their drivers I should add something like this:?

echo xorg-x11 >> /etc/portage/package.mask

echo kde* >> /etc/portage/package.mask

----------

## slycordinator

 *kamina wrote:*   

> So if I want to make sure that I don't get offered KDE or xorg updates unless there is a major update / ati updates their drivers I should add something like this:?
> 
> echo xorg-x11 >> /etc/portage/package.mask
> 
> echo kde* >> /etc/portage/package.mask

 

If you try to mask all versions of kde won't it try to uninstall kde if you've got it already?

----------

## kamina

So I should know what the newest version is, and allways change the mask to the direct versions name?

----------

## slycordinator

Or you can do "emerge --update --deep -pv" and it'll list what all will be updated.

It lists the newest version, the version it's updating from, the USE flags associated, and the size of downloads.

All you have to do then it decide which ones to emerge.  Manually emerge those.

----------

## nyda

Ah great, some portage gurus to bug...  :Smile: 

How would I make a package join the stable tree. What I mean is this:

When Gnome 2.8 was ~x86 I added all it's packages to packages.keywords. Now 2.8 has hit stable, but it seems portage already upgraded my local version to 2.8.1 which is not yet stable. I don't want to downgrade (because 2.8.1 will be the next stable in a few weeks anyways), but I don't want any further unstable upgrades either. How can I tell portage to keep the current version and only upgrade once there is a stable version available?

I didn't find any info how to do this without -U (which doesn't seem to work anymore), but surely portage supports something as important as this. Any ideas?

----------

## fearofcorners

I think the reason why I learned to use portage wrong is much of the docs I used when I originally started using gentoo suggested you emerge things with ACCEPT_KEYWORDS="~arch" instead of adding it to /etc/portage/package.keywords. I didn't realize my folly until I tried something like running emerge -e system.  

Furthermore, there seems to be some confusion in some docs about whether it is package or packages.keywords/unmask/etc. It would be nice if there was example files placed there when you intially set up your system, especially in stage 2/3 installs where the user is expected to know less. Is it not possible to have comments in those files?

----------

## eandry

 *fearofcorners wrote:*   

> I think the reason why I learned to use portage wrong is much of the docs I used when I originally started using gentoo suggested you emerge things with ACCEPT_KEYWORDS="~arch" instead of adding it to /etc/portage/package.keywords. I didn't realize my folly until I tried something like running emerge -e system.  
> 
> Furthermore, there seems to be some confusion in some docs about whether it is package or packages.keywords/unmask/etc. It would be nice if there was example files placed there when you intially set up your system, especially in stage 2/3 installs where the user is expected to know less. Is it not possible to have comments in those files?

 

I have the exact same complaint.  If those mentioned files had an example configuration just like most other files in /etc/ then I might have had less problems.  I too was foolish to have ACCEPT_KEYWORDS=~x86 in the beginning and have since removed it.  When I tried to downgrade to stable packages I had many problems with gcc and glibc.  And now, I get really strage errors when I try to emerge packages that I would think have no problems.  I'm now set on doing a stage 3 reinstall very soon.

----------

## fearofcorners

 *eandry wrote:*   

> 
> 
> I have the exact same complaint.  If those mentioned files had an example configuration just like most other files in /etc/ then I might have had less problems.  I too was foolish to have ACCEPT_KEYWORDS=~x86 in the beginning and have since removed it.  When I tried to downgrade to stable packages I had many problems with gcc and glibc.  And now, I get really strage errors when I try to emerge packages that I would think have no problems.  I'm now set on doing a stage 3 reinstall very soon.

 

Well the whole point of gentoo is flexibility, from hardened to bleeding edge. The second you start unmasking packages you're putting your system's stability in your own hands. 

My problem was after doing things like ACCEPT_KEYWORDS="~arch" USE="..." emerge whatever I couldn't do anything like emerge -e world to take advantage of gcc-3.4/cflags/etc without downgrading lots of packages and loosing things like dvd-rw support.

As it was, I wanted to start fresh as well. I found it is pretty quick to be up and running from a stage 2 or stage 3 if you've got your old config files for things like xorg, and as long as you set up your /etc/portage/package.* files you can safely update and recompile your whole system with one or two commands.

----------

## fearofcorners

Actually, a kde-esque GUI portage frontend with lots of tooltips and warnings would be a godsend to noobs everywhere. That plus widely available binary ebuilds would basically make gentoo the ultimate linux distro, for the newbie and the ub3r alike.

----------

## kimchi_sg

 *fearofcorners wrote:*   

> Actually, a kde-esque GUI portage frontend with lots of tooltips and warnings would be a godsend to noobs everywhere.

 

```
emerge guitoo
```

 *fearofcorners wrote:*   

> That plus widely available binary ebuilds would basically make gentoo the ultimate linux distro, for the newbie and the ub3r alike.

 

No it would not. Gentoo is only greay as long as it remains a primarily source-based distro. This my $0.02.

This not my $0.02: a good page explaining the near-total absence of binary packages and ebuilds in Portage, and why there may never ever be many more. His $0.02 though.

----------

## nexus780

 *fearofcorners wrote:*   

> Actually, a kde-esque GUI portage frontend with lots of tooltips and warnings would be a godsend to noobs everywhere. That plus widely available binary ebuilds would basically make gentoo the ultimate linux distro, for the newbie and the ub3r alike.

 

Disagreed. I agree with the example files in /etc/portage though, would surely be helpful for many people without harming them. However a GUI that will do everything for you is IMO not even desirable. Gentoo - and especially ~ Gentoo - is not for the uninterested noob. It is for the ready-and-willing-to-learn noob though, and usually even retarded mistakes get help, at least if it's visible that the noob tried, and having a complete GUI (if that's even possible..) would discourage trying. And I honestly can't see how Gentoo4Noobs could work, since Gentoo is made for people who want to decide themselves, whereas uninterested noobs want to put in a CD or press a button and then have the system ready to use. I think Gentoo should stick to its target audience (people who know, or people who are willing&able to learn). One size doesn't fit all, if one wants easy tell them to go for Mandrake, SuSE or Fedora  :Smile: 

My 2 eurocents  :Wink: 

----------

## eandry

 *nexus780 wrote:*   

> However a GUI that will do everything for you is IMO not even desirable. Gentoo - and especially ~ Gentoo - is not for the uninterested noob. It is for the ready-and-willing-to-learn noob though, and usually even retarded mistakes get help, at least if it's visible that the noob tried, and having a complete GUI (if that's even possible..) would discourage trying.

 

Agreed.  Otherwise they should use Ubuntu or something.  A n00b I am with Gentoo, but not with Linux and Unix.

I think I might try the route suggested in kimchi_sg's sig.

I am curious about what fearofcorners said...

 *fearofcorners wrote:*   

> As it was, I wanted to start fresh as well. I found it is pretty quick to be up and running from a stage 2 or stage 3 if you've got your old config files for things like xorg, and as long as you set up your /etc/portage/package.* files you can safely update and recompile your whole system with one or two commands.

 

Before my laptop's HD completely died a few months ago, I managed to backup most of what I considered important config files but neglected to get the portage config files.  You mean if I back those up, reinstall stage 2/3, restore the portage config files, and do an emerge -e world I'm set?

Or were you describing another method where I wouldn't have to completely restart from scratch?  Having a n00b mentality, I thought I needed to start over because my gcc/glib is so fsck'ed now I have a chicken-or-egg scenerio and doing any more compiles would break things even more.  And yes, I tried the gcc-config/fix_libtool_files.sh thing which helped for a while but not completely.

----------

## fearofcorners

Personally, I have no major interest in a portage gui, beyond the fact that a progress bar/eta on compiles would be nifty. I merely speak from the desire to see a linux distro that has the potential to hit mainstream use without becoming bloated, slow and oversimplified (suse anyone?).

 *eandry wrote:*   

> 
> 
> Before my laptop's HD completely died a few months ago, I managed to backup most of what I considered important config files but neglected to get the portage config files.  You mean if I back those up, reinstall stage 2/3, restore the portage config files, and do an emerge -e world I'm set?
> 
> Or were you describing another method where I wouldn't have to completely restart from scratch?  Having a n00b mentality, I thought I needed to start over because my gcc/glib is so fsck'ed now I have a chicken-or-egg scenerio and doing any more compiles would break things even more.  And yes, I tried the gcc-config/fix_libtool_files.sh thing which helped for a while but not completely.

 

Well I've done it 2 ways. The first time I deleted almost everything, started more or less from strach and just kept my old /etc folder for the most part. The other time I got to the point where my gcc/glibc were compiled with CFLAGS that made them break, among other things. I booted from a livecd, fixed my overly-agressive /etc/make.conf and /etc/portage/package.* files, chrooted, did an emerge -e system, emerge -e world. The only thing was I think it may have created some orphaned files, but I later I used one of the anti-cruft scripts available here to fix it up.

There is in my experience no situation where a gentoo install cannot be salvaged with a livecd, regardless of what silly thing you might have tried. I haven't tried reiser4 though  :Smile: 

----------

## infirit

How would one mark packages for a specific ~arch? When i try to emerge for example the gnome 2.10 from bmg all packages are marked ~x86 and not ~amd64.

```
!!! One of the following masked packages is required to complete your request:

- app-admin/system-tools-backends-1.1.91 (masked by: missing keyword)
```

Surely this is possible but i'm having problems getting this done. And I'm getting sick manually editing those ebuilds. 

Thanks!

edit: Found a way to do this with ekeyword, from within the bmg overlay:

```
find -name '*.ebuild' -exec ekeyword ~amd64 {} \;
```

----------

## Gherald

I don't know if this has been mentioned but the original post should be edited to reflect that "~x86" and similar are not required in /etc/portage/package.keywords

"app-category/packagename" is all an entry needs.

----------

## GaMMa

I'll change it. This should be depricated soon though, there's a guide in Gentoo docs now that's much more in depth. I did this back when people used portage in ways it shouldn't have been used, and it annoyed me. People seem to be following it today though  :Very Happy: .

UPDATE: Actually does adding ~x86 make portage whine? I know when things are masked you have to add another flag, which might unmask it, but wouldn't it still be marked unstable?

----------

## Gherald

Many forum posts already link to this thread.  You could add a link to relevant parts of Gentoo docs if you like.

----------

## GaMMa

Yea the Gentoo docs say include the ~x86 after the package name in the package.keywords file. 

http://www.gentoo.org/doc/en/handbook/handbook-x86.xml?part=3&chap=3

I'm going to leave it as it is  :Razz: .

----------

## thoffmeyer

I cant belive im reading this.. how to use portage correctly, if you dont know how to use it, then done use gentoo.

----------

## GaMMa

Actually back in the Gentoo 1.4 days when I first made this guide package.* was pretty new (or to me anyway). People used the --upgrade-only flag which was proven to be bad. Lots of people were messing up their systems because some newer packages depended on slotted older versions of other packages. So I thought hey what a great way to give back to Gentoo. So this was here to inform people. Today everyone pretty much knows about package.* because it's been documented so much, but before they didn't.

----------

## coffea_arabica

I have to defend ACCEPT_KEYWORDS now. There are actually situations in wich I think this is the easiest way to do what I want. An example: The last GLSA was about a security hole in the java JREs. I use blackdown, and the secure version is still masked as unstable. Now I am this sure version will move to stable very soon, so I just emerge the version with ACCEPT_KEYWORDS. (of course, I have a look on what portage wants to emerge as package dependencies in addition to the package itself, which in this case and often enough is nothing) I can have an eye on it when new updates come in. Plus, I don't update my system every three days, only securityupdates go in really fast, everything else has to wait until I have time to fix potentials breakups. So, it doesn't hurt and I have saved another line lor two in my package.keywords, which I probably would forget in there.

----------

## GaMMa

I'm not a huge fan of the ACCEPT_KEYWORDS because it's a pain to emerge -uD world when you have a bunch of packages like that (I upgrade a lot  :Razz: ). I find it generally better to have a short list of unstable packages added to the package.keywords file that way emerge -uD world passes over them. If you don't upgrade a lot (or on a cron job), or think a package will become stable when you update again then that is a solution (although I still don't recommend it).

----------

## leo.fontenelle

 *GaMMa wrote:*   

> NOTE: It's a lot easier to keep track of packages if you keep this list alphabetized.

 

One can accomplish that with

```
# sort /etc/portage/package.whatever -o /etc/portage/package.whatever
```

It is very useful if you're adding lines with "echo something >> file".

Don't use "sort file > file", you'll lose data!

----------

## kimchi_sg

 *telurion wrote:*   

> Don't use "sort file > file", you'll lose data!

 

I learnt that the hard way, with my world file.   :Sad: 

----------

## leo.fontenelle

I did it wrong, at first. But I had just sorted package.use to the console, so I was pretty lucky to be able to select it (thanks gpm!) and cat into package.use again. That's what (almost!) happens to people who don't RTFM and don't even make backups!  (me  :Laughing: )

----------

