Portage Advanced Usage

This article lists some neat things you can do with Portage/emerge.

File locations

/etc/portage directory

This directory contains important configuration directories and files for Portage. Each entry can either be a file or a directory; a directory is recommended and if used, will take into account all files present in the directory.

• package.accept_keywords/ lets you add keywords for individual packages. To allow unkeyworded packages to be installed, write for instance app-emulation/wine **. You do not need to write it in package.mask.

• package.use/ lets you add local USE flags for certain packages. To add/remove certain languages, you can use expanded USE flags:

USE="linguas_en -linguas_fr"

• Note that each line must contain only the package name and the options. Don't add any comment (comments must use a whole line) after the package name and options.

• You can use package.env and the env directory to have per package FEATURES. See this page for more information.

Portage world file

It is located in /var/lib/portage/world.

Portage cache

It is located in /var/cache/edb.

revdep-rebuild cache files

They are in /var/cache/revdep-rebuild (no longer in /root).

emerge options

• --newuse will recompile packages that had their USE flags changed.
• --depclean will attempt to remove packages that are no longer needed as dependencies.
• --fetchonly will only fetch the distribution files.
• -t will display a tree view. It can be very useful to know which package pulls in another one.
• -O will disable any dependency check (both on the dependencies of the emerged packages, and on already installed packages to see if an upgrade would not satisfy them). It can be a very useful options when there are bugs in the Gentoo tree and you really need to upgrade a package without checking dependencies.
• To emerge a particular version of a package: emerge =mypackage-0.6.3-r2

Variables

• CPU_FLAGS_X86 should be set in /etc/portage/make.conf. You can use cpuid2cpuflags package to get the correct value. Failing to do so leads for instance to segfaults with ffmpeg.
• CONFIG_PROTECT and CONFIG_PROTECT_MASK can be set in /etc/portage/make.conf and control the behavior of the configuration protection feature. Note that turn it off in /etc, you must set CONFIG_PROTECT_MASK="/etc", it is not enough to set CONFIG_PROTECT="".

Features

• Collision protection cannot apparently be disabled, even with -collision-protect and -protect-owned. The only way to partly disable it is to use the environment variable COLLISION_IGNORE with a list of directories (those are not recursively ignored).

Binary Packages

• Portage can build a binary package if a package was already emerged (installed) on a given system. This will just create an archive of all files and can be used to later install this binary package on another machine (without compiling as usual). This is very useful if you want to fix broken systems. For instance, let's say you have a broken system with a non-working gcc package, or missing critical shared libraries. You cannot reinstall gcc normally, but you could install a standard stage 3 tarball, chroot into it, create a gcc binary package (and other binary packages if needed), then take those binary packages and install them on main system to fix it.
• Creating the binary package is done via quickpkg:

quickpkg sys-devel/gcc

• Then the resulting package is (by default) installed in /var/cache/binpkgs. If needed, copy it to the target system. You can then install from a binary tarball with emerge -K:

emerge -K --oneshot sys-devel/gcc

Disabling test feature

• You can add a file in /etc/portage/env/dev-python/pygtk (for instance) with the following content:

FEATURES=${FEATURES/test/}

Repositories & Overlays

• If you remove an overlay, the following command can list all the packages currently installed that belonged to the overlay (and that should be removed):

qlist -IRC | grep overlay-name

• Note that emerge --depclean won't remove it if they are part of the world file, and emerge won't even complain that there are packages in the world file that are no longer present in the repositories.
• It may also happen that the old overlay installed packages that are also part of the main repository. In this case, re-emerging them is enough, or they can be removed and will be reinstalled after an emerge world upgrade.

Gentoolkit

• equery files ebuild_name will list all the files installed by the specified ebuild.
• qfile /path/to/file will display which package provides that particular file. It can sometimes be useful (it searches in all packages in repository, not only in installed ones).

Profiles

• Profiles contain default configuration values and settings.
• For a server machine, don't use the server profile. It is not yet production-ready. Use the generic profile, eg default/linux/x86/2008.0 (for a desktop box, use default/linux/x86/2008.0/desktop).

Updating operations

• If you update a major Python version (eg, 2.5 to 2.6), you must run python-updater to ensure a smooth transition. Be careful to run python-updater before emerge --depclean, as the remerge is much more difficult if the old python version is not there anymore.

Troubleshooting

• If an ebuild fails to emerge because of memory issues (not enough RAM), you should change MAKEOPTS="-j9" to MAKEOPTS="-j1" temporarily. This will allow only a single compiling thread to run, thus reducing overall memory usage and solving the issue.

Useful Links

• Portage Features
• Working with Portage
• An online list of USE flags