Handbook:MIPS/Portage/Files
Portage files
Configuration directives
Portage comes with a default configuration stored in /usr/share/portage/config/make.globals. All Portage configuration is handled through variables. Portage's variables Portage and what they mean are described later.
Since many configuration directives differ between architectures, Portage also has default configuration files which are part of the system profile. This profile is pointed to by the /etc/portage/make.profile symlink; Portage's configurations are set in the make.defaults files of the profile and all parent profiles. We'll explain more about profiles and the /etc/portage/make.profile directory later on.
When changing a configuration variable, do not alter /usr/share/portage/config/make.globals or make.defaults. Instead use /etc/portage/make.conf which has precedence over the previous files. For more information, read the /usr/share/portage/config/make.conf.example file. As the name implies, this is merely an example file - Portage does not read it.
It is also possible to define a Portage configuration variable as an environment variable, but we don't recommend this.
Profile-specific information
We've already encountered the /etc/portage/make.profile directory. This is actually a symbolic link to a profile - by default, one inside /var/db/repos/gentoo/profiles/, although one can create profiles elsewhere and point to them. The profile this symlink points to is the profile to which the system adheres.
A profile contains architecture-specific information for Portage, such as a list of packages that belong to the system corresponding with that profile, a list of packages that don't work (or are masked-out) for that profile, etc.
User-specific configuration
When Portage's behavior needs to be changed, certain files inside /etc/portage/ will need to be modified. Using files within /etc/portage/ is highly recommended; overriding Portage's behavior through environment variables is highly discouraged.
Within /etc/portage/ users can create the following files:
- package.mask which lists the packages that Portage should never try to install
- package.unmask which lists the packages Portage should be able to install even though the Gentoo developers highly discourage users from emerging them
- package.accept_keywords which lists the packages Portage should be able to install even though the package hasn't been found suitable for the system or architecture (yet)
- package.use which lists the USE flags to use for certain packages without having the entire system use those USE flags
These don't have to be files; they can also be directories that contain one or more file(s) with the relevant settings. More information about the /etc/portage/ directory, together with a full list of files that can be created, can be found in the Portage man page:
user $man portageChanging Portage file and directory locations
The previously mentioned configuration files cannot be stored elsewhere - Portage will always look for those configuration files at those exact locations. However, Portage uses many other locations, for various purposes: package builds, source code storage, repository locations, and so on. All of these have default locations, but can be altered to personal taste through /etc/portage/make.conf.
All these purposes have well-known default locations but can be altered to personal taste through /etc/portage/make.conf. The rest of this chapter explains what special-purpose locations Portage uses and how to alter their placement on the filesystem.
This Handbook isn't meant to be used as a reference though - for details, please refer to the portage and make.conf man pages:
user $man portage
user $man make.conf
Storing files
Gentoo ebuild repository
The default location of the Gentoo ebuild repository is /var/db/repos/gentoo. /var/db/repos/gentoo. This is defined by the default repos.conf file found at /usr/share/portage/config/repos.conf. To modify the default, copy this file to /etc/portage/repos.conf/gentoo.conf and change the location setting. When storing the Gentoo ebuild repository elsewhere (by altering this variable), don't forget to change the /etc/portage/make.profile symbolic link accordingly.
After changing the location setting in /etc/portage/repos.conf/gentoo.conf, it is recommended to also alter the following variables in /etc/portage/make.conf, since - due to how Portage handle variables - they will not notice the location change: PKGDIR, DISTDIR, and RPMDIR.
Pre-built binaries
Even though Portage doesn't use pre-built binaries by default, it has extensive support for them. When asking Portage to work with pre-built packages, it will look for them in /var/cache/binpkgs. This location is defined by the PKGDIR variable.
Source code
Application source code is stored in /var/cache/distfiles by default. This location is defined by the DISTDIR variable.
Portage database
Portage stores the state of the system (what packages are installed, what files belong to which package, ...) in /var/db/pkg.
Do not alter the system state files manually! It might break Portage's knowledge of the system.
Portage cache
The Portage cache (with modification times, virtuals, dependency tree information, ...) is stored in /var/cache/edb. This location really is a cache: users can clean it if they are not running any Portage-related application at that moment.
Building software
Temporary Portage files
Portage's temporary files are stored in /var/tmp/ by default. This is defined by the PORTAGE_TMPDIR variable.
Building directory
Portage creates specific build directories for each package it emerges inside /var/tmp/portage/. This location is defined by the PORTAGE_TMPDIR variable with portage/ appended.
Live filesystem location
By default Portage installs all files on the current filesystem (/), but this can be changed by setting the ROOT environment variable. This is useful when creating new build images.
Logging features
Ebuild logging
Portage can create per-ebuild log files, but only when the PORT_LOGDIR variable is set to a location that is writable by Portage (through the Portage user). By default this variable is unset. If PORT_LOGDIR is not set, then there will not be any build logs with the current logging system, though users may receive some logs from the new elog support.
If PORT_LOGDIR is not set, there will be no build logs stored in the enabled logging system (although users may receive some logs from the new elog support.
Portage offers fine-grained control over logging through the use of elog:
- PORTAGE_ELOG_CLASSES: This is where users can define the kinds of messages to be logged. The variable's value can be any space-separated combination of
info,warn,error,log, andqa.info: Logs "einfo" messages printed by an ebuildwarn: Logs "ewarn" messages printed by an ebuilderror: Logs "eerror" messages printed by an ebuildlog: Logs the "elog" messages found in some ebuildsqa: Logs the "QA Notice" messages printed by an ebuild
- PORTAGE_ELOG_SYSTEM: This selects the module(s) to process the log messages. If left empty, logging is disabled. Anny space-separated combination of
save,custom,syslog,mail,save_summary, andmail_summarycan be used. At least one module must be used in order to use elog.save: This saves one log per package in $PORT_LOGDIR/elog, or /var/log/portage/elog if $PORT_LOGDIR is not defined.custom: Passes all messages to a user-defined command in $PORTAGE_ELOG_COMMAND; this will be discussed later.syslog: Sends all messages to the installed system logger.mail: Passes all messages to a user-defined mailserver in $PORTAGE_ELOG_MAILURI; this will be discussed later. The mail features of elog require >=portage-2.1.1.save_summary: Similar to save, but it merges all messages in $PORT_LOGDIR/elog/summary.log, or /var/log/portage/elog/summary.log if $PORT_LOGDIR is not defined.mail_summary: Similar to mail, but it sends all messages in a single mail when emerge exits.
- PORTAGE_ELOG_COMMAND: This is only used when the
custommodule is enabled. Users can specify a command to process log messages. Note that the command can make use of two variables: ${PACKAGE} is the package name and version, while ${LOGFILE} is the absolute path to the logfile. For instance:
PORTAGE_ELOG_COMMAND="/path/to/logger -p '\${PACKAGE}' -f '\${LOGFILE}'"
- PORTAGE_ELOG_MAILURI: This contains settings for the mail module, such as address, user, password, mail server, and port number. The default setting is "root@localhost localhost". The following is an example for an SMTP server that requires username and password-based authentication on a particular port (the default is port 25):
PORTAGE_ELOG_MAILURI="user@some.domain username:password@smtp.some.domain:995"
- PORTAGE_ELOG_MAILFROM: Allows the user to set the "from" address of log mails; defaults to "Portage" if unset.
- PORTAGE_ELOG_MAILSUBJECT: Allows the user to create a subject line for log mails. Note that it can make use of two variables: ${PACKAGE} will display the package name and version, while ${HOST} is the fully qualified domain name of the host Portage is running on. For instance:
PORTAGE_ELOG_MAILSUBJECT="package \${PACKAGE} was merged on \${HOST} with some messages"
Users who used enotice with Portage-2.0.* must completely remove enotice, as it is incompatible with elog.