Gentoo maintenance

The focus of this tutorial is installing new software and updating existing software, in the most common and basic style. Rough understanding of portage is expected.

For complicated tinkering, see other pages in this wiki.

eix
To search packages, the utility "eix" in is recommended.

After you emerged eix, build the eix cache by running.

"eix" replaces emerge --search functionality (which is slow) and also emerge --sync. Run to achieve that.

emerge
To actually emerge a package, can be used. These command line flags have the following results:
 * -a, --ask:portage will list all packages that it is going to emerge and then asks for confirmation
 * -v, --verbose:mainly has the effect, that you'll see USE flags for all packages
 * t, --tree:shows the dependency tree for the given target by indenting dependencies. It is useful in case you want to know which package pulls which dependency

Per-package USE flag can be set in the file and add a line like this: Don't specify it like. You'll forget what you have done!

USE flag modifications can be done through.

Unmasking packages masked by keyword
To unmask, use like this:

or - even better - like this:

(Note: is replacing . If both files exist, package.accept_keywords takes precedence)

Originally you always had to specify what keywords you wanted to attach to the package along side it. Recent version of portage negate this by automatically adding the keyword for your arch to any line in

The second way is to be preferred, if you just need a specific version of a package. If you unmask all version of a package you might end up updating to an even buggier version during an system update, which you did not intend. By being very specific you minimize the impact on your system and staying very close to the standard set of stable packages is always a good idea in terms of stability and low-maintenance, in my opinion.

If you don't want to manage it manually, there's also the command line tool "autounmask"(on old systems, on new systems it is deprecated):

autounmask is deprecated, instead use emerge packagename --autounmask-write.

Unmasking cvs/svn/git... Ebuilds
If you want to try a svn/cvs version of a package (usually designated as a "9999" version release), you'll need to add the package name (with optional version) to both /etc/portage/package.unmask and /etc/portage/package.accept_keywords with additional asterisks for package.keywords:

These additional tokens are can easily be found using

equery
One more thing about USE flags: To get more information about what a certain USE flag does, you can use "equery" which comes with the gentoolkit. You'll want to have that anyway, as it contains many useful tools.

For example:

list USE flags and their descriptions:

autounmask
Perl script that will correctly handle unmasking for your package and its dependencies Usage:

dispatch-conf
dispatch-conf is a replacment for etc-update that can auto-merge trivial changes in configuration files (like spacing) and keeps a record of which configuration files you edited and auto-updates those that you haven't touched. After it has collected the necessary information it will most often only prompt you for intervention where it is really necessary. You might also want to look into using dispatch-conf with RCS. There is more information elsewhere on this wiki about dispatch-conf.

It comes with portage, you only have to configure it and start using it: Whenever you are prompted to run etc-update, you can run dispatch-conf instead.

Updating
Now to the actual system-wide update process: The first step is syncing your portage tree. This can be done with but if you are using eix, a more convenient way is to run eix-sync as this will have the same effect and also eix will update its cache afterwards.

For updating I run the command

which consists of these command line flags:


 * -u, --update: updates packages to the _best_ version available, which sometimes might involve a downgrade. Trust the gentoo developers, they know what is 'best'. Higher version number is not always better.
 * -D, --deep:instead of looking only at the packages that are recorded in your world file, portage will also check all their dependencies for updates. Basically a "catch all" flag and that's what you'll want for a system-wide update.
 * -N, --newuse:will also reemerge packages where USE flags have changed since their last compilation (like when you changed the system-wide USE flags).
 * -a, --ask:as above
 * -v, --verbose:as above

These seem to be the recommended command line flags to use for updating. The wiki entry Upgrading Packages has more details about it.

eselect
With eselect you can easily switch to a new profile, manually update/correct kernel symlinks, activate opengl support, manage different versions of binutils, mailwrapper profiles ...

Just run eselect to figure out what's available on your system.

For changing the kernel symlink do the following

The asterisk indicates your current symlink, eselect shows all available kernels, change to whatever kernel you like.

Use the same syntax for other eselect modules.

Security updates
You can use the utility glsa-check to perform security only updates. Running will emerge those packages affected by known security holes.

You can run first to see what it will do.

depclean
After portage has finished updating, you may want to remove packages that are no longer needed. However, this process is known to fail at times, thereby horribly breaking the system. If you watch the process carefully and make sensible decisions, it shouldn't be that risky. Basically the idea is that all packages are checked whether they appear in your world file or as a dependency of one of the packages in your world file. If that is not the case, the package is - in theory - no longer needed. This assumption might break in certain cases: Imagine you have packages A, X, Y and Z. A depends on X and Y, but at compile time it detected the presence of package Z and compiles (optional) support for it in. Now it sort of 'depends' on the presence of Z even though its portage dependencies don't reflect that. Removing Z will now break A. The solution is to recompile A after removing Z.

We'll come to that, but for now - if you are courageous - run. In my experience, you don't have to be that courageous. I run this command on a regular basis, and it has not caused much trouble. Make sure you check the list of packages that portage wants to remove before giving confirmation. The latter applies especially when you do a dependency clean for the first time (that is after your first world update and thus on a "fresh" system). Here, for example, it wanted to remove grub. If you find packages that you would prefer to keep on your system, you may use in order to add the given package to the world file (please check that this sentence conforms to the "Best practices" goal, and remove this notice).

fixing broken gcc linkage ("econf failed" error)
After updating your system, it happens that portage is still configured to use your old version of gcc, which can't be found on your system anymore. When you run or even try to, portage pulls this message out: revdep-rebuild OR emerge -v foo Check first that confirms the problem: emerge --info Then type the following command, where N is the complete gcc version number (ex.: 4.3.2),

if you don't know the version number (N), you can try gcc-config -l The value of N would be the entire version number, here 4.3.2

revdep-rebuild
Now, after depclean has finished, some packages might be left broken as mentioned above. This is when you should use. It will check all binaries for missing libraries, figure out which binary belongs to which ebuild, and reemerge those ebuilds. If you use, always do a afterwards.

eclean
Finally, you might want to run eclean distfiles (eclean is also part of the gentoolkit) which will figure out if any of the distfiles in are no longer needed and will free up some disk space in this way.

Congratulations! Your system is now up to date and cleaned from old cruft.

emaint
It is also a good idea to run

to check for problems in the world file and then

if it finds problems.

enotice
Regarding the emerge process in general you might also want to look into the utility enotice (http://www.fmp.com/enotice/). One of the things that have always baffled me about Gentoo is the fact that all of these important/helpful notes that ebuilds tend to display while emerging are buried in between compiler outputs. As if anyone would actually watch the screen all the time while emerging more than a few packages. Enotice logs all of these notes on a per-package basis and collects them for later reviewing.

Enotice won't be in portage, because it could do nasty things and the functionality has now been replaced by portage's elog feature. See also the forum discussion on enotice

Portage Elog
Add the following lines to your :

You can edit the CLASSES section to include only what you want. The logs are then placed in (  by default). Setting also saves the entire emerge output.

A good gui viewer to browse these logs is elogviewer.

For further help on the elog functionality, please see.

eix-test-obsolete
From the man page: eix-test-obsolete is a script which calls eix several times to display the output of eix -tTc in a more organized manner.

What it shows are non-matching entries, redundant entries, and uninstalled entries in, , , , and. Also the names of all installed packages (with all installed versions) are checked to be in the database. The output of the following command should point you to changes that you can do to keep your clean.

Python
Basic procedure: General upgrading procedure of python

For the full explanation of Python in Gentoo, see Python maintenance.

Portable Kernel modules
When you upgrade your kernel you need to also reinstall the kernel modules that you built from portage, for example nvidia-drivers, alsa-driver, and so on.

If you can't remember which kernel modules you built from portage or you just want a tool to manage them module-rebuild comes in handy. It's a simple tool with no man page or even --help just run it by itself to see which options and actions it offers.

First, you'll need to install the package:

Now you can run the command.

Then get the modules rebuilt to work with your new kernel:

make.conf
Some tips to organize


 * use comments
 * split bash variables like USE and FEATURES into multiple lines

A make.conf like the one above allows you to toggle features as necessary. For example this user might want to disable distcc occasionally. To do this they simply comment out the 2 lines under the distcc section.

Manifest problems / Filesize does not match recorded size
When emerging, this is an error that is produced when an ebuild's manifest is incorrect.


 * What is a manifest?:Manifests are a method of checksumming a file to ensure that the file you download is the same one that the developers built against.
 * Why manifest?:Manifests help to avoid a range of problems, including helping to ensure that the package will work as expected and that the file on the download server hasn't been tampered with.
 * Why does it fail?:Manifests can fail for a number of reasons. Frequently it indicates that the file on the server has changed since the developers added the package to portage (Sun packages, among others, are infamous for this). However, don't be so quick to dismiss the failure - it could also be a sign that someone has maliciously changed the file on the mirror (real world examples include inserting a trojan (malicious program) into the download file).
 * How to solve it?:Generally the problem is already known and the easiest thing to do is simply wait a few hours, run and try again. If that doesn't work, file a bug (after searching to check one doesn't already exist).