Portage

Portage is the package manager of Gentoo.

First you have to choose if you want to use stable or unstable version. In /etc/make.conf :

ACCEPT_KEYWORDS="amd64"         # stable (replace amd64 by your arch)
ACCEPT_KEYWORDS="amd64 ~amd64"  # unstable

Emerge main options :

They are mainly used with :

emerge -[D][N]tuav # to see dependencies as a tree
emerge -[D][N]uav  # to see what will be installed in which order, and you just have to type yes if you want to install, or no
emerge -Ca      # to remove a package
emerge --sync   # synchronize your portage tree

Description of USE flags : http://www.gentoo.org/dyn/use-index.xml

There are several places to modify them, which correspond to several levels of priority :

Don't touch it, it will be undone when you emerge Portage. (least priority)

USE="nptl alsa -java"

Global flags used for all packages (overwrite make.defaults if conflicts).

USE="dri gtk java -qt"

Don't forget also in make.conf :

INPUT_DEVICES="mouse keyboard" # kbd ...
VIDEO_CARDS="vesa" # nv, nvidia ...

Here you can set flags for each package separately (overwrite make.conf if conflicts).

www-client/mozilla-firefox java
www-client/links -X

You can set flags for one execution of emerge (overwrite all other flags if conflicts), but if you emerge again flags are not recorded (particularly if it is a dependency update). Thus you should only use it for testing flags.

USE="ldap" emerge mozilla-thunderbird

ACCEPT_KEYWORDS="amd64 ~amd64" # ~amd64 for unstable

= or ⇐ or >= if you precise the version number.

=www-client/mozilla-firefox-1.5.0.7
>=www-client/mozilla-firefox-1.5.0.7

app-cdr/cdrecord-prodvd
=media-video/ldvd-1.9.4

Contains hard masked packages by portage developpers. Do not modify it (use /etc/portage/package.unmask instead), but there are some explanations about why it has been masked.

A lot of problems during emerge come from dependencies. Portage developpers are not perfect and can make errors when defining dependencies.

If emerge fails you can try :

• if you see that the error message is related to something, try to install this package before (eg opengl). If you don't know to which package a file is related :

equery belongs <file-name>

• install manually some of the dependencies before, it changes the order and can work
• look at the USE flags for this package, and try to remove some of them, which seem explicitly related to the error, or that you they can be “error-provoking”
• downgrade to an older version, by masking it in the package.use file
• if nothing works, unmerge all packages related to what you want (eg x11), or remove them from /usr/portage to force portage to reinstall them, and reinstall everything (that's what I had to do to install modular xorg).

For example for fluxbox :

# in /usr/portage/x11-wm/fluxbox :
ebuild fluxbox-1.0.0.ebuild fetch   # to download the package
ebuild fluxbox-1.0.0.ebuild unpack  # to uncompress the sources
# NOW you can modify sources
# in /var/tmp/portage/x11-wm/fluxbox-1.0.0/work/fluxbox-1.0.0/src,
# or wherever specified in make.conf
ebuild fluxbox-1.0.0.ebuild compile # to compile
ebuild fluxbox-1.0.0.ebuild install # to install (in a temp folder)
ebuild fluxbox-1.0.0.ebuild qmerge  # to finish install
ebuild fluxbox-1.0.0.ebuild clean   # to clean temporary folders

Or more simply:

# in /usr/portage/x11-wm/fluxbox :
ebuild fluxbox-1.0.0.ebuild fetch unpack   # to download and unpack
# NOW modify sources in /var/tmp/portage/x11-wm/fluxbox-1.0.0/word/fluxbox-1.0.0/src
ebuild fluxbox-1.0.0.ebuild compile install qmerge clean # to compile, install, merge and clean

Then you can have to unmerge the previous version (check with eix described below).

This is exactly equivalent to :

emerge fluxbox

You can get somewhere an ebuild. But to use it you need a Manifest file. You can create it with ebuild :

ebuild name.ebuild manifest

Then you can do the emerge step by step with ebuild as explained in the previous section, or move the ebuild in the /usr/portage/ directory, and simply use emerge, or even better, create an overlay of the portage tree (so that it won't be overwritter during the next sync of portage).

Create another folder similar to /usr/portage, for example /usr/local/portage, or /usr/portage2. Then add this directory in the PORTDIR_OVERLAY variable in make.conf :

PORTDIR_OVERLAY="/usr/portage2"

For example to install xmms2 :

wget http://www.zugaina.org/gentoo/portage/media-sound/xmms2/xmms2-0.2.7.ebuild
mkdir /usr/portage2/media-sound
mkdir /usr/portage2/media-sound/xmms2
mv xmms2-0.2.7.ebuild /usr/portage2/media-sound/xmms2
ebuild /usr/portage2/media-sound/xmms2/xmms2-0.2.7.ebuild manifest

And finally, simply :

emerge -Duav xmms2

If you really want to use xmms2, you can test it with xmms2 play, but you'll need a client then (xmms2 is based on a server/client architecture), for example gxmms2 :

wget http://www.zugaina.org/gentoo/portage/media-sound/gxmms2/gxmms2-0.6.4.ebuild
mkdir /usr/portage/media-sound/gxmms2
mv gxmms2-0.6.4.ebuild /usr/portage/media-sound/gxmms2
ebuild /usr/portage/media-sound/xmms2/gxmms2-0.6.4.ebuild manifest
emerge -Duav gxmms2

You can find a list of clients for xmms2 here :
http://www.zugaina.org/gentoo/media-sound.html.en

There are some public overlays you can manage automatically. First install layman with emerge layman. Then :

# list available overlays
layman -L
# install an overlay
layman -a <overlay-name>
# sync overlays
layman --sync ALL

In order to use the main gentoo tree in priority over overlays, create the file /etc/portage/repos.conf with:

[gentoo]
priority = 1000

You can also refer to overlays in the /etc/package.* files with the syntax:

category/package-version:slot::overlay
category/package-version::overlay

To save your package as it is installed :

quickpkg xorg-x11

(you need to emerge portage-tools to use it)

To restore it (obliges emerge to use local binaries) :

emerge -K xorg-x11
#OR
emerge --usepkgonly -a xorg-x11-6.8.2-r8

After an emerge, there is often a warning telling you that some config files need to be updated. The tool called etc-update can help you to do this, by merging automatically what it can and asking your for the rest :

sudo etc-update

It is very important to make the effort to deal with config files updates, because you can lose all the changes you did in your configuration files if it is overwritten !

Thus for each configuration file :

• enter its number to show the diff file
• look at the diff file to see if there are some configurations that you did yourself
• ⇒ if you didn't modify the config file, overwrite it with the update
• ⇒ if you modified it and there is nothing new in the update, keep your original file
• ⇒ if there are some new things and some things you modified, choose interactive merging. It will show you each different blocks, and you can each time choose l if you want to keep the block of your original config file, or r if you want to take the updated block.

If you do anything about it, your portage folder will grow along time. This is due to the distfiles folder, where are stored all source tarballs of packages you have installed.

There is a portage tool called eclean which can remove all useless tarballs while keeping interesting ones :

eclean --destructive distfiles

You can add the -p option (pretend) if you just want to see what will be removed.

If you have enough memory, it can be faster (hum, a LOT faster) to compile directly in the memory instead of on the hard disk. For that, mount /var/tmp/portage in a ram disk, for example in /etc/fstab :

none   /var/tmp/portage   tmpfs   size=1000M,nr_inodes=1M   0 0

and then :

mount /var/tmp/portage

You can check with the df command that your ram disk is well mounted.

The amount of memory you mount depends on how much memory you have, and how much you need. If there is not enough mounted memory, emerge will fail and stop when there is no more memory available. But if you use more memory than available it will use the swap and as slow as before, and if you use more memory than ram+swap available, linux can have big problems.

300MB is enough for most of packages, but for some others you need more. Here is some examples of necessary space :

As ram is not used if the mounted ram is not used, there is no risk to always mount a great amount of memory. Even if it uses swap, it will prevent emerge from failing and won't be slower than not using mounted ram. Then you should mount the maximum of memory so that ram+swap will be enough for the normally used memory, and the mounted memory.

PORTAGE_NICENESS=“15”

Packages : http://gentoo-portage.com

Overlays packages : http://gpo.zugaina.org

Use flags : http://www.gentoo.org/dyn/use-index.xml

eix is a portage tool which can search faster in your portage tree, and show you all versions available with their masks and all versions already installed :

eix-sync # to do an emerge --sync and synchronize its database
eix <text|regexp> ; search text in package titles, ex ^gcc$
eix -S <text|regexp> ; search in package descriptions

Versions stable are in red, unstable are in yellow masked by (~), software masked in red with (m) (you masked it), hard masked in red with (M) (don't try to install them).

To find the package that a file came from.

equery belongs <filename>

To parse portage logs and get some stats.

genlop <package-name> ; lists dates and version of every install of the package
genlop -t <package-name> ; also prints merge time of every install of the package
genlop -c ; information about current merge