====== Portage ======
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 ''/etc/make.conf'' :
ACCEPT_KEYWORDS="amd64" # stable (replace amd64 by your arch)
ACCEPT_KEYWORDS="amd64 ~amd64" # unstable
Emerge main options :
^ Long option ^ Short option ^ Description ^
| ''--update'' | -u | merge only if a more recent package is available |
| ''--pretend'' | -p | just print what would be merged |
| ''--tree'' | -t | shows dependencies as a tree |
| ''--deep'' | -D | search updates of all the dependencies |
| ''--newuse'' | -N | force to take into account changes in USE flags |
| ''--unmerge'' | -C | remove a package |
| ''--ask'' | -a | ask confirmation before to do something |
| ''--clean'' | -c | clean outdated packages (do not remove functionalities) |
| ''--verbose'' | -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
===== USE flags =====
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 :
=== /etc/make.profile/make.defaults ===
Don't touch it, it will be undone when you emerge Portage. (least priority)
USE="nptl alsa -java"
=== /etc/make.conf ===
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 ...
=== /etc/portage/package.use ===
Here you can set flags for each package separately (overwrite make.conf if conflicts).
www-client/mozilla-firefox java
www-client/links -X
=== Environment variable ===
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
===== Masking flags =====
=== /etc/make.conf ===
ACCEPT_KEYWORDS="amd64 ~amd64" # ~amd64 for unstable
=== /etc/portage/package.mask ===
''='' or ''<='' or ''>='' if you precise the version number.
=www-client/mozilla-firefox-1.5.0.7
>=www-client/mozilla-firefox-1.5.0.7
=== /etc/portage/package.unmask ===
app-cdr/cdrecord-prodvd
=media-video/ldvd-1.9.4
=== /usr/portage/profiles/package.mask ===
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
* 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 fluxbox
===== 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'' :
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/local/portage'', or ''/usr/portage2''. Then add this directory in the ''PORTDIR_OVERLAY'' variable in ''make.conf'' :
PORTDIR_OVERLAY="/usr/portage2"
==== 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 :\\
http://www.zugaina.org/gentoo/media-sound.html.en
===== Manage public overlays =====
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
# 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
===== Save an installed package =====
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
===== 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 :
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.
===== 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 ''/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 :
^ package ^ space needed ^ tested myself ^ time AMD64 1800MHz ^ Remarks ^
| GCC (gtk,nls/-O2) | 500MB | no | 0h25 | |
| GCC (fortran,gcj,gtk,nls/-O2) | 1400MB | yes | 1h45 | |
| firefox (java/-Os) | 550MB | yes | 0h30 | |
| thunderbird (crypt,ldap/-Os) | 620MB | yes | 0h35 | |
| kde | 350MB | no | | |
| wxGTK (X,opengl,unicode/-Os) | 2400MB | yes | 0h30 | |
\\
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.
===== Niceness =====
''PORTAGE_NICENESS="15"''
===== 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]]
===== Tools =====
==== eix ====
''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 ; search text in package titles, ex ^gcc$
eix -S ; 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).
==== equery ====
To find the package that a file came from.
equery belongs
==== genlop ====
To parse portage logs and get some stats.
genlop ; lists dates and version of every install of the package
genlop -t ; also prints merge time of every install of the package
genlop -c ; information about current merge