aboutsummaryrefslogtreecommitdiff
path: root/doc/configuration.html.skel
blob: 36adbc25b09b62ab5b9ae1408395710b9e7746a8 (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
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html lang="en" xml:lang="en">
<head>
<title>Paludis, the Other Package Mangler</title>
<link rel="stylesheet" href="paludis.css" type="text/css" />
</head>
<body>
@HEADER@

<h1>Paludis, the Other Package Mangler</h1>

<h2>Configuration Files</h2>

<h3>Overview</h3>

<p>This document explains where Paludis looks for user configuration files, and
describes the format of these files.</p>

<h3>General File Format</h3>

<p>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.</p>

<p>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>.</p>

<h3>Locations</h3>

<p>Paludis tries the following locations for its configuration directory:</p>

<ul>
  <li><code>${PALUDIS_HOME}/.paludis/</code>, if the <code>PALUDIS_HOME</code>
  environment variable is set, or <code>${HOME}/.paludis/</code> otherwise.</li>
  <li><code>SYSCONFDIR/paludis/</code>, where <code>SYSCONFDIR</code> is
  <code>/etc</code> on most systems.</li>
</ul>

<p>If the <code>--config-suffix</code> commandline argument is supplied, Paludis
will use <code>.paludis-thesuffix</code> or <code>paludis-thesuffix</code>
instead.</p>

<p>If a file named <code>specpath.conf</code> exists in this directory, Paludis uses
this file to determine the real configuration directory. The <code>specpath.conf</code>
file is a standard key / value configuration file (see above). The keys that
are used are:</p>

<ul>
    <li><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.conf</code> rather than the real configuration directory so
    that chrooting into an image can work with no configuration changes.</li>

    <li><code>config-suffix</code>, which specifies a new configuration suffix. By
    default, no configuration suffix is used under root.</li>
</ul>

<p>If no <code>specpath.conf</code> file is present, the original directory is
used.</p>

<h3>The environment.conf File</h3>

<p>The <code>environment.conf</code> file controls various options related to
general operation. Recognised keys are:</p>

<dl>
    <dt><code>reduced_username</code></dt>
    <dd>The username to use when dropping priviledges. Defaults to
    <code>paludisbuild</code>. This user's default group (which is also called
    <code>paludisbuild</code> if you installed using ebuilds) must have read,
    write and execute access to distfiles and build directories.</dd>

    <dt><code>portage_compatible</code></dt>
    <dd>If set to a non-empty string, Paludis will mask any ebuild that is known
    to break Portage. Currently this means any version containing <code>-scm</code>
    or <code>-try</code> and any <code>EAPI</code> containing the string <code>paludis</code>.</dd>
</dl>

<p>If <code>environment.conf</code> does not exist and <code>environment.bash</code>
does, Paludis executes the latter and pretends that its stdout is the content of the former.</p>

<h3>The use.conf File</h3>

<p>User <code>USE</code> preferences are controlled by the <code>use.conf</code>
file. The basic format of a line is <code>spec use use use ...</code>, where
<code>spec</code> is a package dependency specification or <a href="sets.html">package set</a>
and <code>use use use ...</code> is one or more USE flag names, prefixed by
a minus if they are to be disabled.</p>

<p>For <code>USE_EXPAND</code> variables such as <code>LINGUAS</code> and
<code>VIDEO_CARDS</code>, <code>spec VARIABLE: value value ...</code> should be
used. To avoid inheriting values from your profile, include <code>-*</code>.</p>

<pre>
# 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
&gt;=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
</pre>

<p>Note that if a package matches multiple lines, <em>all</em> of these lines will
be considered, not just the best or last match.</p>

<p>If <code>use.bash</code> exists, it is executed and its stdout is used as if
it were appended to the main file. If a <code>use.conf.d</code> directory
exists, any file named <code>*.conf</code> in this directory is treated as if it
were appended to the main file, and any file named <code>*.bash</code> is
executed and has its stdout used as if it were appended to the main file.</p>

<h3>The keywords.conf File</h3>

<p>Which <code>ARCH KEYWORDS</code> to accept is controlled by the
<code>keywords.conf</code> file. The format of a line is
<code>spec keyword1 keywords2 ...</code>, where <code>spec</code> is a package
dependency specification or <a href="sets.html">set name</a> and
<code>keyword1 keyword2 ...</code> is one or more arch keywords. As with Portage,
accepting <code>~arch</code> does <em>not</em> 
implicitly accept <code>arch</code>, however, if a package matches multiple lines,
<em>all</em> of these lines will be considered, not just the best or last match.
For example:</p>

<pre>
# We want a mostly stable system:
*/* x86

# But some ~arch packages:
app-editors/vim ~x86
app-editors/vim-core ~x86
</pre>

<p>If <code>*/*</code> is not used, then every package that is to be installed will require
an entry in <code>keywords.conf</code>. It is also generally assumed within the gentoo
tree that if <code>~ARCH</code> is accepted for a package, then so is
<code>ARCH</code>; not doing so may result in all versions or the latest version of a
package being masked, as the package is stabilised.</p>

<p>The <code>-*</code> special keyword can be used to remove previously accepted
keywords from a less specific match. The <code>*</code> special keyword can be
used to accept anything.</p>

<p>If <code>keywords.bash</code> exists, it is executed and its stdout is used as if
it were appended to the main file. If a <code>keywords.conf.d</code> directory
exists, any file named <code>*.conf</code> in this directory is treated as if it
were appended to the main file, and any file named <code>*.bash</code> is
executed and has its stdout used as if it were appended to the main file.</p>

<h3>The package_mask.conf File</h3>

<p>Packages can be masked through the use of the <code>package_mask.conf</code>
file. The format of the file is one <code>spec</code> or <a href="sets.html">set name</a>
per line. For example:</p>

<pre>
# Hide vim 7
&gt;=app-editors/vim-core-7
&gt;=app-editors/vim-7

# Hide gvim
app-editors/gvim
</pre>

<p>If <code>package_mask.bash</code> exists, it is executed and its stdout is used as if
it were appended to the main file. If a <code>package_mask.conf.d</code> directory
exists, any file named <code>*.conf</code> in this directory is treated as if it
were appended to the main file, and any file named <code>*.bash</code> is
executed and has its stdout used as if it were appended to the main file.</p>

<h3>The package_unmask.conf File</h3>

<p>Packages can be unmasked through the use of the
<code>package_unmask.conf</code> file. The format of the file is one
<code>spec</code> or <a href="sets.html">set name</a> per line. For example:</p>

<pre>
# I need banshee 0.11.0
=media-sound/banshee-0.11.0
</pre>

<p>If <code>package_unmask.bash</code> exists, it is executed and its stdout is used as if
it were appended to the main file. If a <code>package_unmask.conf.d</code> directory
exists, any file named <code>*.conf</code> in this directory is treated as if it
were appended to the main file, and any file named <code>*.bash</code> is
executed and has its stdout used as if it were appended to the main file.</p>

<h3>The licenses.conf File</h3>

<p>Licence filtering can be controlled via <code>licenses.conf</code>. If no
filtering is desired, use:</p>

<pre>
*/* *
</pre>

<p>For filtering, the format is similar to the keywords and use files:</p>

<pre>
*/* GPL-2 BSD
app-editors/vim-core vim
</pre>

<p>If <code>licenses.bash</code> exists, it is executed and its stdout is used as if
it were appended to the main file. If a <code>licenses.conf.d</code> directory
exists, any file named <code>*.conf</code> in this directory is treated as if it
were appended to the main file, and any file named <code>*.bash</code> is
executed and has its stdout used as if it were appended to the main file.</p>

<h3>The mirrors.conf File</h3>

<p>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:</p>

<pre>
* file:///mnt/nfs/distfiles
gentoo http://gentoo.blueyonder.co.uk/distfiles
</pre>

<p>If <code>mirrors.bash</code> exists, it is executed and its stdout is used as if
it were appended to the main file. If a <code>mirrors.conf.d</code> directory
exists, any file named <code>*.conf</code> in this directory is treated as if it
were appended to the main file, and any file named <code>*.bash</code> is
executed and has its stdout used as if it were appended to the main file.</p>

<h3>The bashrc File</h3>

<p>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>.</p>

<h3>The repositories/ Files</h3>

<p>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.conf</code>. All
files must define a <code>format =</code> key; depending upon the value used, other
optional and mandatory keys are available.</p>

<p>Files named <code>*.bash</code> in the <code>repositories/</code> subdirectory
are executed by Paludis and their stdout is used as if it were a normal repository
<code>.conf</code> file.</p>

<p>Each repository can have a key named <code>importance</code>. This is used when
two different repositories contain an identically named and versioned package (e.g. foo/bar-1.0).
The repository with the higher importance will always be chosen first. If not
provided, the default is 0.</p>

<p>To avoid duplication across configuration files, a file named
<code>repository_defaults.conf</code> can be used to specify defaults (this file
does <strong>not</strong> live in the <code>repositories/</code> subdirectory).
Keys in this file are overridden by identically named keys in individual
configuration files.</p>

<p>If <code>repository_defaults.conf</code> does not exist and <code>repository_defaults.bash</code>
does, Paludis executes the latter and pretends that its stdout is the content of the former.</p>

<h4>ebuild Format Repositories</h4>

<p>The following keys are available for <code>format = ebuild</code>:</p>

<ul>
    <li><code>location</code> (mandatory), which points to the location of the
    tree.</li>

    <li><code>master_repository</code> (default: not used), which specifies the
    name of another ebuild format repository that is used as a 'master' for
    this repository. The master repository's location is used for the <code>PORTDIR</code>
    variable, its <code>profiles/</code> directory (not to be confused with its
    profiles) is used in addition to the repository's own and the default values
    for some of the keys below are affected.</li>

    <li><code>profiles</code> (mandatory), which should be a space separated list of
    directories used for profile data. Later directories have priority. Inherited from
    <code>master_repository</code> if unset.</li>
    <li><code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
    the temporary directory used by Paludis for compiling software.</li>
    <li><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.</li>
  <li><code>write_cache</code>, which can be set to a directory that will be used
  to write generated cache files.</li>
  <li><code>names_cache</code>, which should be either <code>/var/empty</code> or
  <code>${location}/.cache/names</code>. See <a href="cachefiles.html">the cache
      documentation</a>.</li>
  <li><code>distdir</code> (default: <code>${location}/distfiles</code>), which
  controls where downloaded files are saved. Inherited from
  <code>master_repository</code> if unset.</li>
  <li><code>eclassdirs</code> (default: any <code>master_repository</code> values,
  plus <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.</li>
  <li><code>newsdir</code> (default: <code>${location}/metadata/news</code>), which
  controls where GLEP 42 news items are located.</li>
  <li><code>securitydir</code> (default: <code>${location}/metadata/security</code>),
  which controls where security advisories are located.</li>
  <li><code>setsdir</code> (default: <code>${location}/sets</code>), which controls
  where package set files are located.</li>
  <li><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.  This
  can be a space-separated list, in which case each will be tried in order
  until one succeeds.</li>
  <li><code>sync_options</code> (default: empty), which specifies
  additional options to pass to the syncing script.  The valid options
  for each protocol are listed by <code>paludis
  --list-sync-protocols</code>.  Note that options are not
  automatically passed through to the underlying sync program
  (<code>rsync</code>, <code>svn</code> etc.), you must use
  <code>--<em>program</em>-option=OPTION</code> or
  <code>--<em>program</em>-<em>action</em>-option=OPTION</code> for
  each option.  If a pass-through option takes an argument, you must
  specify <code>--<em>program</em>-option=</code> for both the option
  itself and the argument.  For example:
<pre>
# For an rsync repository, to exclude files matching patterns listed in
# /etc/sync.exclude, and to log the transfer to the file /var/log/sync.log
sync_options = --exclude-from=/etc/sync.exclude --rsync-option=--log-file --rsync-option=/var/log/sync.log
# For a CVS repository, to use maximum compression for the network
# traffic, and to disable keyword expansion
sync_options = --cvs-option=-z9 --cvs-checkout-option=-ko
</pre></li>
  <li><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>.  This key is deprecated, use
  <code>sync_options = --exclude-from=FILE</code> instead.</li>
  </ul>

<h4>vdb Format Repositories</h4>

<p>You should have exactly one VDB format repository. It holds packages that have
been installed from a <code>ebuild</code> format repository.</p>

<p>The following keys are available for <code>format = vdb</code>:</p>

<ul>
    <li><code>location</code> (mandatory), which <strong>must</strong> be set to
    <code>${ROOT}/var/db/pkg</code>.</li>
    <li><code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which is
    used as a temporary directory when carrying out uninstall operations,</li>
    <li><code>provides_cache</code>, which should be either <code>/var/empty</code> or
    <code>${location}/.cache/provides</code>. See <a href="cachefiles.html">the
        cache documentation</a>.</li>
    <li><code>world</code> (default: <code>${location}/world</code>), which is used
    for the world file.</li>
</ul>

<h4>CRAN Format Repositories</h4>

<p>The following keys are available for <code>format = cran</code>:</p>

<ul>
    <li><code>buildroot</code> (default: <code>/var/tmp/paludis</code>), which controls
    the temporary directory used by Paludis for compiling software.</li>
    <li><code>distdir</code> (default: <code>${location}/distfiles</code>), which
    controls where downloaded files are saved.</li>
    <li><code>library</code> (mandatory), which should be set to <code>${ROOT}/usr/${libdir}/R/library</code>, unless
    you know what you're doing.</li>
    <li><code>location</code> (mandatory), which points to the location of the
    CRAN tree.</li>
    <li><code>sync</code> (default: empty), as per <code>format =
        ebuild</code>.</li>
</ul>

<h4>CRAN Installed Format Repositories</h4>

<p>The following keys are available for <code>format =
    cran_installed</code>:</p>

<ul>
    <li><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>.</li>
</ul>

@FOOTER@
</body>
</html>