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.

[edit] Installing new software

[edit] eix

To search packages, the utility "eix" in app-portage/eix is recommended.

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

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

[edit] emerge

To actually emerge a package, emerge -av <whatever> 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

app-editors/vim  cscope

Don't specify it like USE=cscope emerge vim. You'll forget what you have done!

USE flag modifications can be done through app-portage/ufed.

[edit] Unmasking packages masked by keyword

To unmask, use /etc/portage/package.accept_keywords like this:

or - even better - like this:

(Note:/etc/portage/package.accept_keywords is replacing /etc/portage/package.keywords. 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 ~arch keyword for your arch to any line in /etc/portage/package.accept_keywords

The second way is to be preferred, if you just need a specific version of a package. If you unmask all ~arch 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 depricated):

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

[edit] 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:

[edit] 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:

[edit] autounmask

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

[edit] Updating existing software

[edit] 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 (/etc/dispatch-conf.conf) and start using it: Whenever you are prompted to run etc-update, you can run dispatch-conf instead.

[edit] Updating

Now to the actual system-wide update process: The first step is syncing your portage tree. This can be done with emerge --sync 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.

[edit] 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

eselect kernel list
Available kernel symlink targets:
  [1]   linux-2.6.21-gentoo-r4 *
  [2]   linux-2.6.22-gentoo-r1

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.

[edit] Security updates

[edit] 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 emerge -av --depclean. 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 emerge --noreplace <atom> 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).

[edit] 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 revdep-rebuild or even try to emerge -v foo, portage pulls this message out:

configure: error: C compiler cannot create executables

...

*   The specific snippet of code:
*   			die "econf failed"
*   The die message:
*   econf failed

Check first that emerge --info confirms the problem:

!!! No gcc found. You probably need to 'source /etc/profile'
!!! to update the environment of this terminal and possibly
!!! other terminals also.

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

[1] x86_64-pc-linux-gnu-4.3.2

The value of N would be the entire version number, here 4.3.2

[edit] revdep-rebuild

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

[edit] 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 /usr/portage/distfiles 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.

[edit] emaint

It is also a good idea to run

to check for problems in the world file and then

if it finds problems.

[edit] 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

[edit] Portage Elog

Add the following lines to your /etc/make.conf:

PORTAGE_ELOG_CLASSES="info warn error log"
PORTAGE_ELOG_SYSTEM="save"

You can edit the CLASSES section to include only what you want. The logs are then placed in $PORT_LOGDIR/elog ( /var/log/portage/elog by default). Setting PORT_LOGDIR 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 /etc/make.conf.example.

[edit] 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 /etc/portage/package.keywords, package.mask, package.unmask, package.use, and package.cflags. 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 /etc/portage/* clean.

[edit] Python

Basic procedure:

# just emerge
$ emerge dev-lang/python

# or specify the version by slot (eg. 2.6, 2.7)
$ emerge python:2.x

# If the slot hasn't changed, that's all. Otherwise, you also need below.
$ eselect python set <new slot, e.g. python2.7>

$ python-updater   # See below for more.
# Now you can delete the old slot.

# After you delete the old slot, do also
$ revdep-rebuild   # Maybe better to pass "-- -va"

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

[edit] 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:

[edit] make.conf

Some tips to organize /etc/make.conf

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

USE="${USE} acpi"       #hardware

#nVidia TNT2
VIDEO_CARDS="nv nvidia"

ALSA_CARDS="via82xx"

USE="${USE} apache2"

# generic

USE="${USE} bash-completion"
USE="${USE} emacs"

INPUT_DEVICES="keyboard mouse"

# distcc
FEATURES="${FEATURES} distcc"
MAKEOPTS="-j5"

FEATURES="${FEATURES} ccache"
FEATURES="${FEATURES} parallel-fetch"

USE="${USE} pic"                
USE="${USE} cjk"        #UTF-8 support

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.

[edit] Dealing with common problems

[edit] 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 emerge --sync and try again. If that doesn't work, file a bug (after searching to check one doesn't already exist).

[edit] See also

• Speeding up portage with tmpfs

[edit] Authors

Edited by: Klandreth - 08.12.2008

Authors are people who have worked on this document and have made significant changes to its content. If you have edited this article and wish to add yourself to the authors list please read "Who are Authors".

To-do list for Gentoo maintenance:	edit · history · watch · refresh
remove info already available in other articles and link to them instead maybe split up article if only a handful of information does not exist elsewhere yet remove depricated information and mention some migration guides This is a good guide, may be making a step by step in the official doc would be nice plus a guide to these tools.