@HEADER@

Paludis, the Other Package Mangler

Configuration Files

Overview

This document explains where Paludis looks for user configuration files, and describes the format of these files.

General File Format

Except where otherwise noted, configuration files are plain text files where blank lines and lines starting with optional whitespace followed by a hash symbol are ignored.

Many files use a key = value format. Here, any whitespace around the outside of key and value is stripped. The value may be quoted using single or double quotes. Variable expansion on previously defined keys (and sometimes on predefined special values) may be done using ${variable}. To include a literal dollar, use \$.

Locations

Paludis tries the following locations for its configuration directory:

If the --config-suffix commandline argument is supplied, Paludis will use .paludis-thesuffix or paludis-thesuffix instead.

If a file named specpath.conf exists in this directory, Paludis uses this file to determine the real configuration directory. The specpath.conf file is a standard key / value configuration file (see above). The keys that are used are:

If no specpath.conf file is present, the original directory is used.

The environment.conf File

The environment.conf file controls various options related to general operation. Recognised keys are:

reduced_username
The username to use when dropping priviledges. Defaults to paludisbuild. This user's default group (which is also called paludisbuild if you installed using ebuilds) must have read, write and execute access to distfiles and build directories.
portage_compatible
If set to a non-empty string, Paludis will mask any ebuild that is known to break Portage. Currently this means any version containing -scm or -try and any EAPI containing the string paludis.

If environment.conf does not exist and environment.bash does, Paludis executes the latter and pretends that its stdout is the content of the former.

The use.conf File

User USE preferences are controlled by the use.conf file. The basic format of a line is spec use use use ..., where spec is a package dependency specification or package set and use use use ... is one or more USE flag names, prefixed by a minus if they are to be disabled.

For USE_EXPAND variables such as LINGUAS and VIDEO_CARDS, spec VARIABLE: value value ... should be used. To avoid inheriting values from your profile, include -*.

# By default, apply these to all packages
*/* -doc nls -apache2

# Turn off nls for vim
app-editors/vim -nls

# For gvim 7, turn on and off various interpreters
>=app-editors/gvim-7_alpha mzscheme perl -python ruby

# For gtk+ with SLOT=2, enable tiff support
x11-libs/gtk+:2 tiff

# We like English
*/* LINGUAS: -* en_GB en

Note that if a package matches multiple lines, all of these lines will be considered, not just the best or last match.

If use.bash exists, it is executed and its stdout is used as if it were appended to the main file. If a use.conf.d directory exists, any file named *.conf in this directory is treated as if it were appended to the main file, and any file named *.bash is executed and has its stdout used as if it were appended to the main file.

The keywords.conf File

Which ARCH KEYWORDS to accept is controlled by the keywords.conf file. The format of a line is spec keyword1 keywords2 ..., where spec is a package dependency specification or set name and keyword1 keyword2 ... is one or more arch keywords. As with Portage, accepting ~arch does not implicitly accept arch, however, if a package matches multiple lines, all of these lines will be considered, not just the best or last match. For example:

# We want a mostly stable system:
*/* x86

# But some ~arch packages:
app-editors/vim ~x86
app-editors/vim-core ~x86

If */* is not used, then every package that is to be installed will require an entry in keywords.conf. It is also generally assumed within the gentoo tree that if ~ARCH is accepted for a package, then so is ARCH; not doing so may result in all versions or the latest version of a package being masked, as the package is stabilised.

The -* special keyword can be used to remove previously accepted keywords from a less specific match. The * special keyword can be used to accept anything.

If keywords.bash exists, it is executed and its stdout is used as if it were appended to the main file. If a keywords.conf.d directory exists, any file named *.conf in this directory is treated as if it were appended to the main file, and any file named *.bash is executed and has its stdout used as if it were appended to the main file.

The package_mask.conf File

Packages can be masked through the use of the package_mask.conf file. The format of the file is one spec or set name per line. For example:

# Hide vim 7
>=app-editors/vim-core-7
>=app-editors/vim-7

# Hide gvim
app-editors/gvim

If package_mask.bash exists, it is executed and its stdout is used as if it were appended to the main file. If a package_mask.conf.d directory exists, any file named *.conf in this directory is treated as if it were appended to the main file, and any file named *.bash is executed and has its stdout used as if it were appended to the main file.

The package_unmask.conf File

Packages can be unmasked through the use of the package_unmask.conf file. The format of the file is one spec or set name per line. For example:

# I need banshee 0.11.0
=media-sound/banshee-0.11.0

If package_unmask.bash exists, it is executed and its stdout is used as if it were appended to the main file. If a package_unmask.conf.d directory exists, any file named *.conf in this directory is treated as if it were appended to the main file, and any file named *.bash is executed and has its stdout used as if it were appended to the main file.

The licenses.conf File

Licence filtering can be controlled via licenses.conf. If no filtering is desired, use:

*/* *

For filtering, the format is similar to the keywords and use files:

*/* GPL-2 BSD
app-editors/vim-core vim

If licenses.bash exists, it is executed and its stdout is used as if it were appended to the main file. If a licenses.conf.d directory exists, any file named *.conf in this directory is treated as if it were appended to the main file, and any file named *.bash is executed and has its stdout used as if it were appended to the main file.

The mirrors.conf File

Mirrors and downloading can be controlled via mirrors.conf. Each line takes the form mirrorname http://mirror/blah/ http://another.mirror/. A special mirror named *, if present, will be consulted before any other location for all files. For example:

* file:///mnt/nfs/distfiles
gentoo http://gentoo.blueyonder.co.uk/distfiles

If mirrors.bash exists, it is executed and its stdout is used as if it were appended to the main file. If a mirrors.conf.d directory exists, any file named *.conf in this directory is treated as if it were appended to the main file, and any file named *.bash is executed and has its stdout used as if it were appended to the main file.

The bashrc File

Paludis will source bashrc when doing ebuild work. This file can be used to set environment variables (CHOST, CFLAGS and so on), but cannot be used to change metadata-affecting variables such as USE or LINGUAS.

The repositories/ Files

Each file named *.conf in the repositories/ subdirectory creates a repository for Paludis. This is a key = value format file, and the special variable ${ROOT} is defined based upon specpath.conf. All files must define a format = key; depending upon the value used, other optional and mandatory keys are available.

Files named *.bash in the repositories/ subdirectory are executed by Paludis and their stdout is used as if it were a normal repository .conf file.

Each repository can have a key named importance. This is used when two different repositories contain an identically named and versioned package (e.g. foo/bar-1.0). The repository with the higher importance will always be chosen first. If not provided, the default is 0.

To avoid duplication across configuration files, a file named repository_defaults.conf can be used to specify defaults (this file does not live in the repositories/ subdirectory). Keys in this file are overridden by identically named keys in individual configuration files.

If repository_defaults.conf does not exist and repository_defaults.bash does, Paludis executes the latter and pretends that its stdout is the content of the former.

ebuild Format Repositories

The following keys are available for format = ebuild:

vdb Format Repositories

You should have exactly one VDB format repository. It holds packages that have been installed from a ebuild format repository.

The following keys are available for format = vdb:

CRAN Format Repositories

The following keys are available for format = cran:

CRAN Installed Format Repositories

The following keys are available for format = cran_installed:

@FOOTER@