path: root/0.4.0/doc/doc_configuration_files.doxygen
diff options
authorAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-07-07 22:28:41 +0000
committerAvatar Ciaran McCreesh <ciaran.mccreesh@googlemail.com> 2006-07-07 22:28:41 +0000
commit575e1fc23d74dd1c18b4b1ed6ee45255e6c455fc (patch)
tree74072b4a76c7a5438e59d55eb4590e76fb168748 /0.4.0/doc/doc_configuration_files.doxygen
parentf9222f00eab4283de4a01bc6eb36ac1fbd9fd92c (diff)
Tag release
Diffstat (limited to '0.4.0/doc/doc_configuration_files.doxygen')
1 files changed, 214 insertions, 0 deletions
diff --git a/0.4.0/doc/doc_configuration_files.doxygen b/0.4.0/doc/doc_configuration_files.doxygen
new file mode 100644
index 000000000..7031d4404
--- /dev/null
+++ b/0.4.0/doc/doc_configuration_files.doxygen
@@ -0,0 +1,214 @@
+/* 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>
+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.
+# 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, <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:
+# 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
+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 ConfigurationFilesLicensesConf The licenses.conf File
+Licence filtering can be controlled via <code>licenses.conf</code>. 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
+\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:
+* file:///mnt/nfs/distfiles
+gentoo http://gentoo.blueyonder.co.uk/distfiles
+\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.
+\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.berlios.de/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 = vdb</code>:
+- <code>location</code> (mandatory).
+- <code>sync</code> (default: empty), as per <code>format = portage</code>.
+- <code>sync_exclude</code> (default: empty), idem.