diff options
Diffstat (limited to '0.8.0/doc/doc_configuration_files.doxygen')
| -rw-r--r-- | 0.8.0/doc/doc_configuration_files.doxygen | 262 |
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 000000000..465b5cdb4 --- /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>. + +*/ + + |