[ << ] [ < ] [ Home ] [ > ] [ >> ]

4. Controlling Portage Behaviour

• Configuration File Protection
• Networking Options
• Directory Locations
• Other Portage Options
• Resources

4.a. Configuration File Protection

Protecting?

Portage knows the concept of "protected files". This means that, when you update software, it will not immediately overwrite certain files with newer versions, but inform you that a newer version exists. This is of course very usefull for configuration files (the files that reside in /etc).

Instead of overwriting such files, it will create a new file called ._cfg0000_<name> with <name> being the original file name. It is then up to the user to merge the necessary differences in the existing file. He/she can use the etc-update command to ease this operation. We will talk about etc-update later.

Declaring CONFIG_PROTECT

Portage cannot protect on a file per file basis. Instead it protects entire directories. The CONFIG_PROTECT variable lists all protected directories. All subdirectories of the listed directories are protected too. The CONFIG_PROTECT variable is defined in /etc/make.globals, but if you want to change it, you should declare it in /etc/make.conf (to keep things consistent /etc/make.conf is used for all Portage configuration).

CONFIG_PROTECT="/etc /usr/share/config /usr/kde/3.1/share/config"

If you want a certain directory protected, but not all of its subdirectories, you can "unprotect" these directories by listing them in the CONFIG_PROTECT_MASK variable, which also has a default value defined in /etc/make.globals but should be altered by declaring it in /etc/make.conf:

CONFIG_PROTECT_MASK="/etc/init.d"

More information about the Configuration File Protection can be found in emerge's online help:

# emerge --help config

etc-update

etc-update is a tool that aids in merging the ._cfg0000_<name> files. It provides an interactive merging setup and can also auto-merge trivial changes.

Running etc-update is pretty straight-forward:

# etc-update

After merging the trivial changes, you will be prompted with a list of protected files that have an update waiting. At the bottom you are greeted by the possible options:

Please select a file to edit by entering the corresponding number.
              (-1 to exit) (-3 to auto merge all remaining files)
                           (-5 to auto-merge AND not use 'mv -i'): 

If you enter -1, etc-update will exit without performing any changes. If you enter -3 or -5, all listed configuration files will be overwritten with the newer versions. It is therefore very important to first select the configuration files that should not be automatically updated. This is as easy as entering the number listed to the left of that configuration file.

As an example, we select the configuration file /etc/pear.conf:

Beginning of differences between /etc/pear.conf and /etc/._cfg0000_pear.conf
[...]
End of differences between /etc/pear.conf and /etc/._cfg0000_pear.conf
1) Replace original with update
2) Delete update, keeping original as is
3) Interactively merge original with update
4) Show differences again

You can now see the differences between the two files. If you believe that the updated configuration file can be used without problems, enter 1. If you believe that the updated configuration file isn't necessary, or doesn't provide any new or usefull information, enter 2. If you want to interactively update your current configuration file, enter 3.

It is not usefull to elaborate about the interactive merging here. For completeness sake, we will list the possible commands you can use while you are interactively merging the two files. You are greeted with two lines (the original one, and the proposed new one) and a prompt at which you can enter one of the following commands:

ed:     Edit then use both versions, each decorated with a header.
eb:     Edit then use both versions.
el:     Edit then use the left version.
er:     Edit then use the right version.
e:      Edit a new version.
l:      Use the left version.
r:      Use the right version.
s:      Silently include common lines.
v:      Verbosely include common lines.
q:      Quit.

When you have finished updating the important configuration files, you can now automatically update all the other configuration files. etc-update will exit if it doesn't find any more updateable configuration files.

4.b. Networking Options

Mirrors

As Gentoo is becoming increasingly popular, the use of mirrors is greatly appreciated. Portage uses three variables for the mirrors: one for the rsync mirrors (which is used to synchronise your Portage Tree with), one for the distfiles (which is used to download the source code) and one for the prebuilt packages.

All possible distfiles mirrors are listed on our Gentoo mirrors page. You can also use mirrorselect which will ease the setup of mirrors for your system. But let us first check out the individual variables...

The SYNC variable contains the rsync-mirror you wish to use. For instance, to use rsync://rsync.namerica.gentoo.org/gentoo-portage, you would define this in /etc/make.conf:

SYNC="rsync://rsync.namerica.gentoo.org/gentoo-portage"

The GENTOO_MIRRORS variable contains a list of distfiles mirrors you wish to use. For instance, to use ftp://ibiblio.org/pub/Linux/distributions/gentoo as first choice, and http://www.gtlib.cc.gatech.edu/pub/gentoo as second, you would define this in /etc/make.conf:

GENTOO_MIRRORS="ftp://ibiblio.org/pub/Linux/distributions/gentoo
                http://www.gtlib.cc.gatech.edu/pub/gentoo"

The PORTAGE_BINHOST variable contains a list of prebuilt package mirrors you wish to use. For instance, to use ftp://login:pass@grp.mirror.site/pub/grp/i686/athlon-xp, you would define this in /etc/make.conf:

PORTAGE_BINHOST="ftp://login:pass@grp.mirror.site/pub/grp/i686/athlon-xp"

Mirrorselect

If you want to use mirrorselect, first install it (if you haven't done so already).

# emerge mirrorselect

You can now opt to have mirrorselect automatically select the best mirrors for you, or select the mirrors manually from a list. For more information on how to use mirrorselect, just run mirrorselect from the command line - it will give you a quick overview on mirrorselect.

# mirrorselect

Fetching

The program which Portage uses to download archive files can be specified by setting the FETCHCOMMAND and RESUMECOMMAND settings. Several examples are shown in /etc/make.conf and /etc/make.globals. Portage uses wget by default:

FETCHCOMMAND="/usr/bin/wget -t 5 --passive-ftp -P \${DISTDIR} \${URI}"
RESUMECOMMAND="/usr/bin/wget -c -t 5 --passive-ftp -P \${DISTDIR} \${URI}"

The ${DISTDIR} variable is substituted with the location where downloaded files are saved (/usr/portage/distfiles), while the ${URI} variable is substituted with the file that Portage needs to download.

As Portage uses wget by default, you can configure it to use proxies by defining http_proxy and ftp_proxy (note the small caps). Although you can do this in /etc/make.conf too, you are advised to use a more general approach as the http_proxy and ftp_proxy variables are used by other tools too (/etc/make.conf is used by Portage only). Please read the chapter on Environment Variables on how to declare system-wide environment variables.

Configuring rsync

rsync is used by emerge sync to update your Portage tree. Three variables used by Portage to change rsync's behaviour are RSYNC_EXCLUDEFROM, RSYNC_RETRIES and RSYNC_TIMEOUT.

A way to "protect" ebuilds from being updated or removed by emerge sync is to use the RSYNC_EXCLUDEFROM variable. It should be set to a file that is used by rsync to exclude certain files and defaults to /etc/portage/rsync_excludes. It is not adviseable to use this method as it can break dependencies if you are not careful. We will talk about PORTDIR_OVERLAY later on, which is the recommended method. For more information, please read the rsync manpage.

RSYNC_EXCLUDEFROM="/etc/portage/rsync_excludes"

When rsync fails, it will retry a number of times before switching to the next available rsync server. The number of retries is defined in RSYNC_RETRIES and defaults to 3:

RSYNC_RETRIES="3"

If you are using a (very) slow rsync server, rsync can time-out if no traffic is received anymore. The amount of seconds to wait before time-out is defined in the RSYNC_TIMEOUT variable and defaults to 180:

RSYNC_TIMEOUT="180"

4.c. Directory Locations

Introduction

Everything about Portage is configurable, including the directories used for the various tasks and files needed by Portage. To change the default locations (as defined in /etc/make.globals) you need to define the correct variables in - where else :) - /etc/make.conf.

Portage Tree

The location of the Portage tree is defined in the PORTDIR variable. It defaults to /usr/portage:

PORTDIR="/usr/portage"

If you want to keep a local Portage tree next to the "official" one, you need to define the PORTDIR_OVERLAY variable. The directory location(s) listed in this value are unaffected by emerge sync actions: ebuilds in those locations will not get updated or removed, but are part of your Portage tree.

PORTDIR_OVERLAY="/usr/local/portage"

Distfiles

The location of the downloaded source code (so called distfiles) is defined in the DISTDIR variable. It defaults to ${PORTDIR}/distfiles:

DISTDIR="${PORTDIR}/distfiles"

Packages and RPMs

The location of the prebuilt packages is defined in the PKGDIR variable. It defaults to ${PORTDIR}/packages:

PKGDIR="${PORTDIR}/packages"

The location of the RPMs (yes, some packages are available as RPMs) is defined in the RPMDIR variable. It defaults to ${PORTDIR}/rpm:

RPMDIR="${PORTDIR}/rpm"

Temporary Portage Files

Portage uses a temporary location to build its ebuilds in. This location is defined in the PORTAGE_TMPDIR variable. It defaults to /var/tmp:

PORTAGE_TMPDIR="/var/tmp"

Per default, Portage will create a portage directory inside PORTAGE_TMPDIR. This is declared in the BUILD_PREFIX variable:

BUILD_PREFIX="${PORTAGE_TMPDIR}/portage"

If you intend to change the location, make sure this temporary directory is on a partition with a sufficient amount of free space: when compiling big software packages, the directory can grow to 2 Gb and beyond!

Logging

The PORT_LOGDIR is a special variable and unset by default. When you define it, Portage will create per-ebuild logs in the given directory:

PORT_LOGDIR="/var/log/portage"

4.d. Other Portage Options

Nice Value

Portage supports building with a different nice-value (a priority-like value). If you want to have Portage build packages with a higher nice-value (resulting in a more responsive system during the building process, but which also increases the build time) you can define the PORTAGE_NICENESS variable with a positive number:

PORTAGE_NICENESS="3"

SLOT'ed Packages and Automatic Cleaning

In several situations you want multiple different versions of a package (including libraries) to be available on your system. Portage supports this by defining the SLOT variable in the ebuilds. As a user, you don't have to know how SLOT'ing works, but it is important you know it is supported.

If you are installing a newer version of a package, Portage will check if the SLOT variable is declared for that package. If that is the case, and the SLOT variable is different for both packages (new and old), Portage will not touch the older package.

However, if the SLOT variable is the same (as is usually the case), the older package will be removed by default. In order for the user to interrupt this removal, Portage will count down a certain amount of seconds. This amount is defined in the CLEAN_DELAY variable and defaults to 5 seconds:

CLEAN_DELAY="5"

If you don't want Portage to automatically remove the older versions (called "cleaning") you can set the AUTOCLEAN variable to no:

AUTOCLEAN="no"

Build Related Variables

We have already encountered quite a lot of variables, but we are not done yet. People who have installed Gentoo will know about the CHOST, CFLAGS and CXXFLAGS variables, used by the compiler to compile and optimize the packages.

More information about these variables can be found in the gcc info pages, or online in the GCC Online Manuals.

# info gcc
(Select "Invoking gcc")
(Select "Optimize options")

If the DEBUGBUILD is defined, Portage will not strip the binaries and libraries to make debugging more easy. This slows down your system and increases the filesizes.

# Do not set this to "false"; instead remove the line. Portage does not
# check the value, it just checks if the variable is defined.
DEBUGBUILD="true"

The MAKEOPTS variable is used by make, a tool used to ease the compilation of a package. It is usually defined to tell make to run several compilations simultaneously (especially if you have a multi-CPU system, or are using distcc as described previously).

To have make run three compilations simultaneously, set the MAKEOPTS variable to -j3:

MAKEOPTS="-j3"

The ROOT variable shouldn't be set in /etc/make.conf, but rather as environment variable. Portage will check this variable to see where a package needs to be installed. Of course, this defaults to /. As an example we show you how to install gnumeric in /mnt/gentoo instead of in your running system:

# ROOT="/mnt/gentoo" emerge gnumeric

Output Formatting

By default, Portage colors its output to improve readability. If you do not want this, set the NOCOLOR variable to true:

NOCOLOR="true"

4.e. Resources

Man Pages

If you need a quick reference on all listed variables, please consult the make.conf man page:

# man make.conf

Commented Examples

The /etc/make.conf file contains lots of comments, including examples you might find interesting. However, most people don't update their /etc/make.conf interactively and therefore miss updates to the files. You can find the latest /etc/make.conf file in our Online ViewCVS Repository.

[ << ] [ < ] [ Home ] [ > ] [ >> ]