Table of Contents
Portage is the package manager of Gentoo.
How to use emerge
First you have to choose if you want to use stable or unstable version. In
ACCEPT_KEYWORDS="amd64" # stable (replace amd64 by your arch) ACCEPT_KEYWORDS="amd64 ~amd64" # unstable
Emerge main options :
|Long option||Short option||Description|
| ||-u||merge only if a more recent package is available|
| ||-p||just print what would be merged|
| ||-t||shows dependencies as a tree|
| ||-D||search updates of all the dependencies|
| ||-N||force to take into account changes in USE flags|
| ||-C||remove a package|
| ||-a||ask confirmation before to do something|
| ||-c||clean outdated packages (do not remove functionalities)|
| ||-v||to show USE flags and versions installed & to install|
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
>= if you precise the version number.
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.
Dealing with most problems
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).
Emerge step-by-step for modifying source
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 a package not in the portage tree
You can get somewhere an ebuild. But to use it you need a Manifest file. You can create it with
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 the overlay
Create another folder similar to
/usr/portage, for example
/usr/portage2. Then add this directory in the
PORTDIR_OVERLAY variable in
Install the package in the overlay and install it
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
Finish installing xmms2 if you really want ;-)
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 :
Manage public overlays
There are some public overlays you can manage automatically. First install
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:
Save an installed package
To save your package as it is installed :
(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
Updating config files
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 :
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
lif you want to keep the block of your original config file, or
rif you want to take the updated block.
Clean your portage folder
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.
Compiling in RAM
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
none /var/tmp/portage tmpfs size=1000M,nr_inodes=1M 0 0
and then :
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 :
|package||space needed||tested myself||time AMD64 1800MHz||Remarks|
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.
List of gentoo packages
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