aboutsummaryrefslogtreecommitdiff
path: root/0.4.0/doc/doc_configuration_files.doxygen
blob: 7031d4404e35b6de1f4ef637b9ce17feeb513a81 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
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>
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.

\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 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.

\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.
*/