aboutsummaryrefslogtreecommitdiff
path: root/0.8.0/doc/doc_configuration_files.doxygen
diff options
context:
space:
mode:
Diffstat (limited to '0.8.0/doc/doc_configuration_files.doxygen')
-rw-r--r--0.8.0/doc/doc_configuration_files.doxygen262
1 files changed, 262 insertions, 0 deletions
diff --git a/0.8.0/doc/doc_configuration_files.doxygen b/0.8.0/doc/doc_configuration_files.doxygen
new file mode 100644
index 0000000..465b5cd
--- /dev/null
+++ b/0.8.0/doc/doc_configuration_files.doxygen
@@ -0,0 +1,262 @@
+/* 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 <code>${variable}</code>. To
+include a literal dollar, use <code>\$</code>.
+
+\section ConfigurationFilesLocations Locations
+
+Paludis tries the following locations for its configuration directory:
+
+- <code>${PALUDIS_HOME}/.paludis/</code>, if the <code>PALUDIS_HOME</code>
+ environment variable is set, or <code>${HOME}/.paludis/</code> otherwise.
+- <code>SYSCONFDIR/paludis/</code>, where <code>SYSCONFDIR</code> is
+ <code>/etc</code> on most systems.
+
+If the <code>--config-suffix</code> commandline argument is supplied, Paludis
+will use <code>.paludis-thesuffix</code> or <code>paludis-thesuffix</code>
+instead.
+
+If a file named <code>specpath</code> exists in this directory, Paludis uses
+this file to determine the real configuration directory. The <code>specpath</code>
+file is a standard key / value configuration file (see above). The keys that
+are used are:
+
+- <code>root</code>, which specifies the install root for packages and the
+ real configuration directory, which is <code>${root}/SYSCONFDIR/paludis/</code>
+ (note that the HOME values are <em>not</em> used here). This value is set in
+ <code>specpath</code> rather than the real configuration directory so
+ that chrooting into an image can work with no configuration changes.
+- <code>config-suffix</code>, which specifies a new configuration suffix. By
+ default, no configuration suffix is used under root.
+
+If no <code>specpath</code> file is present, the original directory is used.
+
+\section ConfigurationFilesUseConf The use.conf File
+
+User <code>USE</code> preferences are controlled by the <code>use.conf</code>
+file. The basic format of a line is <code>atom use use use ...</code>, where
+<code>atom</code> is a package depend atom or <code>*</code> for "all packages",
+and <code>use use use ...</code> is one or more USE flag names, prefixed by
+a minus if they are to be disabled.
+
+For <code>USE_EXPAND</code> variables such as <code>LINGUAS</code> and
+<code>VIDEO_CARDS</code>, <code>atom VARIABLE: value value ...</code> should be
+used. To avoid inheriting values from your profile, include <code>-*</code>.
+
+\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, <em>all</em> of these lines will
+be considered, not just the best or last match.
+
+\section ConfigurationFilesKeywordsConf The keywords.conf File
+
+Which <code>KEYWORDS</code> to accept is controlled through
+<code>keywords.conf</code>. The format of a line is
+<code>atom keyword ...</code>. As with Portage, accepting
+<code>~arch</code> does <em>not</em> implicitly accept <code>arch</code>.
+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, <em>all</em> 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 <code>package_mask.conf</code> file. The format of the file is one <code>atom</code> 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 <code>package_unmask.conf</code> file. The format of the file is one <code>atom</code> 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 <code>licenses.conf</code>. 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 <code>mirrors.conf</code>. Each
+line takes the form <code>mirrorname http://mirror/blah/ http://another.mirror/</code>.
+A special mirror named <code>*</code>, if present, will be consulted <em>before</em>
+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 <code>bashrc</code> when doing ebuild work. This file
+can be used to set environment variables (<code>CHOST</code>, <code>CFLAGS</code>
+and so on), but <em>cannot</em> be used to change metadata-affecting variables
+such as <code>USE</code> or <code>LINGUAS</code>.
+
+\section ConfigurationFilesRepositories The repositories/ Files
+
+Each file named <code>*.conf</code> in the <code>repositories/</code> subdirectory
+creates a repository for Paludis. This is a key = value format file, and the special
+variable <code>${ROOT}</code> is defined based upon <code>specpath</code>. All
+files must define a <code>format =</code> key; depending upon the value used, other
+optional and mandatory keys are available.
+
+Each repository can have a key named <code>importance</code>. 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 <code>portage</code> is used here to refer to repositories in the
+format used by the <code>gentoo-portage</code> (or <code>gentoo-x86</code>) tree.
+The name is far from ideal...
+
+The following keys are available for <code>format = portage</code>:
+
+- <code>location</code> (mandatory), which points to the location of the
+ tree.
+- <code>profiles</code> (mandatory), which should be a space separated list of
+ directories used for profile data. Later directories have priority.
+- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
+ the temporary directory used by Paludis for compiling software.
+- <code>cache</code> (default: <code>${location}/metadata/cache</code>), which
+ controls the location of the metadata cache for a repository. It should be set
+ to <code>/var/empty</code> if there is no metadata cache available.
+- <code>distdir</code> (default: <code>${location}/distfiles</code>), which
+ controls where downloaded files are saved.
+- <code>eclassdirs</code> (default: <code>${location}/eclass</code>), which
+ is a space separated list of locations of eclasses. The value of ECLASSDIR
+ is taken from the <em>first</em> entry, but eclasses from later entries are
+ favoured.
+- <code>newsdir</code> (default: <code>${location}/metadata/news</code>), which
+ controls where GLEP 42 news items are located.
+- <code>securitydir</code> (default: <code>${location}/metadata/security</code>),
+ which controls where security advisories are located.
+- <code>setsdir</code> (default: <code>${location}/sets</code>), which controls
+ where package set files are located.
+- <code>sync</code> (default: empty), which controls how the repository is
+ synced. Typically values are in the form <code>rsync://rsync.europe.gentoo.org/gentoo-portage</code>
+ or <code>svn://svn.pioto.org/paludis/overlay</code>. Use
+ <code>paludis --list-sync-protocols</code> to see supported protocols.
+- <code>sync_exclude</code> (default: empty), which can point to a file that
+ contains a list of directories to exclude when syncing via
+ <code>rsync://</code>.
+
+\subsection ConfigurationFilesRepositoriesVDB vdb Format Repositories
+
+You should have exactly one VDB format repository. It holds packages that have
+been installed from a <code>portage</code> format repository.
+
+The following keys are available for <code>format = vdb</code>:
+
+- <code>location</code> (mandatory), which <strong>must</strong> be set to
+ <code>${ROOT}/var/db/pkg</code>.
+- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which is
+ used as a temporary directory when carrying out uninstall operations,
+- <code>world</code> (default: <code>${location}/world</code>), which is used
+ for the world file.
+
+\subsection ConfigurationFilesRepositoriesNothing nothing Format Repositories
+
+Usually you won't have any <code>nothing</code> repositories. They are used as
+a convenience when certain locations have to be synced at <code>--sync</code>
+time; they do not contain any packages.
+
+The following keys are available for <code>format = nothing</code>:
+
+- <code>location</code> (mandatory).
+- <code>sync</code> (default: empty), as per <code>format = portage</code>.
+- <code>sync_exclude</code> (default: empty), idem.
+
+\subsection ConfigurationFilesRepositoriesCRAN CRAN Format Repositories
+
+The following keys are available for <code>format = cran</code>:
+
+- <code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
+ the temporary directory used by Paludis for compiling software.
+- <code>distdir</code> (default: <code>${location}/distfiles</code>), which
+ controls where downloaded files are saved.
+- <code>library</code> (mandatory), which should be set to <code>${ROOT}/usr/${libdir}/R/library</code>, unless
+you know what you're doing.
+- <code>location</code> (mandatory), which points to the location of the CRAN tree.
+- <code>sync</code> (default: empty), as per <code>format = portage</code>.
+
+\subsection ConfigurationFilesRepositoriesCRANInstalled CRAN Installed Format Repositories
+
+The following keys are available for <code>format = cran_installed</code>:
+
+- <code>location</code> (mandatory), which should be set to <code>${ROOT}/usr/${libdir}/R/library</code>, unless
+you know what you're doing. This must point to the same directory as <code>library</code> for <code>format = cran</code>.
+
+*/
+
+