/* vim: set ft=cpp tw=80 sw=4 et : */
/**
\page ConfigurationFiles Configuration Files
\section ConfigurationFilesOverview Overview
This document explains where Paludis looks for user configuration files, and
describes the format of these files.
\section ConfigurationFilesGeneralFormat 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 \$.
\section ConfigurationFilesLocations Locations
Paludis tries the following locations for its configuration directory:
- ${PALUDIS_HOME}/.paludis/, if the PALUDIS_HOME
environment variable is set, or ${HOME}/.paludis/ otherwise.
- SYSCONFDIR/paludis/, where SYSCONFDIR is
/etc on most systems.
If the --config-suffix commandline argument is supplied, Paludis
will use .paludis-thesuffix or paludis-thesuffix
instead.
If a file named specpath exists in this directory, Paludis uses
this file to determine the real configuration directory. The specpath
file is a standard key / value configuration file (see above). The keys that
are used are:
- root, which specifies the install root for packages and the
real configuration directory, which is ${root}/SYSCONFDIR/paludis/
(note that the HOME values are not used here). This value is set in
specpath rather than the real configuration directory so
that chrooting into an image can work with no configuration changes.
- config-suffix, which specifies a new configuration suffix. By
default, no configuration suffix is used under root.
If no specpath file is present, the original directory is used.
\section ConfigurationFilesUseConf The use.conf File
User USE preferences are controlled by the use.conf
file. The basic format of a line is atom use use use ..., where
atom is a package depend atom or * for "all packages",
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, atom VARIABLE: value value ... should be
used. To avoid inheriting values from your profile, include -*.
\verbatim
# 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
\endverbatim
Note that if a package matches multiple lines, all of these lines will
be considered, not just the best or last match.
\section ConfigurationFilesKeywordsConf The keywords.conf File
Which KEYWORDS to accept is controlled through
keywords.conf. The format of a line is
atom keyword .... As with Portage, accepting
~arch does not implicitly accept arch.
For example:
\verbatim
# We want a mostly stable system:
* x86
# But some ~arch packages:
dev-cpp/libebt x86 ~x86
sys-apps/paludis x86 ~x86
dev-util/subversion x86 ~x86
app-admin/eselect x86 ~x86
app-editors/vim x86 ~x86
app-editors/vim-core x86 ~x86
\endverbatim
Note that if a package matches multiple lines, all of these lines will
be considered, not just the best or last match.
\section ConfigurationFilesPackage_MaskConf 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 atom per line. For example:
\verbatim
# Hide vim 7
>=app-editors/vim-core-7
>=app-editors/vim-7
# Hide gvim
app-editors/gvim
\endverbatim
\section ConfigurationFilesPackage_UnmaskConf 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 atom per line. For example:
\verbatim
# I need banshee 0.11.0
media-sound/banshee
\endverbatim
\section ConfigurationFilesLicensesConf The licenses.conf File
Licence filtering can be controlled via licenses.conf. If no
filtering is desired, use:
\verbatim
* *
\endverbatim
For filtering, the format is similar to the keywords and use files:
\verbatim
* GPL-2 BSD
app-editors/vim-core vim
\endverbatim
\section ConfigurationFilesMirrorsConf 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:
\verbatim
* file:///mnt/nfs/distfiles
gentoo http://gentoo.blueyonder.co.uk/distfiles
\endverbatim
\section ConfigurationFilesBashrc 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.
\section ConfigurationFilesRepositories 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. All
files must define a format = key; depending upon the value used, other
optional and mandatory keys are available.
Each repository can have a key named importance. This is used when
two different repositories contain an identical package atom (e.g. foo/bar-1.0).
The repository with the higher importance will always be chosen first. If not
provided, the default is 0.
\subsection ConfigurationFilesRepositoriesPortage portage Format Repositories
\note The name portage is used here to refer to repositories in the
format used by the gentoo-portage (or gentoo-x86) tree.
The name is far from ideal...
The following keys are available for format = portage:
- location (mandatory), which points to the location of the
tree.
- profiles (mandatory), which should be a space separated list of
directories used for profile data. Later directories have priority.
- buildroot (default: /var/tmp/paludis), which controls
the temporary directory used by Paludis for compiling software.
- cache (default: ${location}/metadata/cache), which
controls the location of the metadata cache for a repository. It should be set
to /var/empty if there is no metadata cache available.
- distdir (default: ${location}/distfiles), which
controls where downloaded files are saved.
- eclassdirs (default: ${location}/eclass), which
is a space separated list of locations of eclasses. The value of ECLASSDIR
is taken from the first entry, but eclasses from later entries are
favoured.
- newsdir (default: ${location}/metadata/news), which
controls where GLEP 42 news items are located.
- securitydir (default: ${location}/metadata/security),
which controls where security advisories are located.
- setsdir (default: ${location}/sets), which controls
where package set files are located.
- sync (default: empty), which controls how the repository is
synced. Typically values are in the form rsync://rsync.europe.gentoo.org/gentoo-portage
or svn://svn.pioto.org/paludis/overlay. Use
paludis --list-sync-protocols to see supported protocols.
- sync_exclude (default: empty), which can point to a file that
contains a list of directories to exclude when syncing via
rsync://.
\subsection ConfigurationFilesRepositoriesVDB vdb Format Repositories
You should have exactly one VDB format repository. It holds packages that have
been installed from a portage format repository.
The following keys are available for format = vdb:
- location (mandatory), which must be set to
${ROOT}/var/db/pkg.
- buildroot (default: /var/tmp/paludis), which is
used as a temporary directory when carrying out uninstall operations,
- world (default: ${location}/world), which is used
for the world file.
\subsection ConfigurationFilesRepositoriesNothing nothing Format Repositories
Usually you won't have any nothing repositories. They are used as
a convenience when certain locations have to be synced at --sync
time; they do not contain any packages.
The following keys are available for format = nothing:
- location (mandatory).
- sync (default: empty), as per format = portage.
- sync_exclude (default: empty), idem.
\subsection ConfigurationFilesRepositoriesCRAN CRAN Format Repositories
The following keys are available for format = cran:
- buildroot (default: /var/tmp/paludis), which controls
the temporary directory used by Paludis for compiling software.
- distdir (default: ${location}/distfiles), which
controls where downloaded files are saved.
- library (mandatory), which should be set to ${ROOT}/usr/${libdir}/R/library, unless
you know what you're doing.
- location (mandatory), which points to the location of the CRAN tree.
- sync (default: empty), as per format = portage.
\subsection ConfigurationFilesRepositoriesCRANInstalled CRAN Installed Format Repositories
The following keys are available for format = cran_installed:
- location (mandatory), which should be set to ${ROOT}/usr/${libdir}/R/library, unless
you know what you're doing. This must point to the same directory as library for format = cran.
*/