aboutsummaryrefslogtreecommitdiff
path: root/doc/overview/gettingstarted.html.part
blob: b43ec080e9e5ae529e37e583cac32e800238185b (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
<!-- vim: set tw=120 ft=html sw=4 sts=4 et : -->

<h1>Getting Started</h1>

<p>There are three ways to configure Paludis:</p>

<ul>
    <li><p><a href="#portage">Using an existing Portage configuration</a>. This is the quickest way for many users who may
    not be ready to commit to using Paludis exclusively. However, it has drawbacks:</p>

    <ul>
        <li>Paludis will be significantly slower for certain operations (e.g. resolving <code>pkg</code> to
        <code>cat/pkg</code>) because various additional cache options are not available.</li>

        <li>The user is restricted to Portage's limited configuration format.</li>

        <li>The Portage 'environment' (this is the term used by paludis for the class that handles configuration files)
        is less widely used, and so may not support all Portage options perfectly.</li>

        <li>It is only available on Gentoo and Gentoo-derived distributions.</li>
    </ul>
    </li>

    <li><p><a href="#automatic">Automatically migrating</a> an existing Portage configuration to the Paludis configuration
    format using a script.</p></li>

    <li><p><a href="#manual">Manually configuring</a> Paludis.</li>
</ul>

<p>Once you have configured Paludis, you should <a href="#testing">test your configuration</a>.</p>

<h2 id="portage">Using an existing Portage configuration</h2>

<p>To use a Portage configuration, Paludis must be built with the Portage environment enabled. On Gentoo, this is
controlled by the <code>portage</code> use flag; when compiling manually,
<code>--with-environments=paludis,portage</code> enables it (and note that you should also ensure that
<code>sysconfdir=/etc</code>).</p>

<p>On Gentoo and Gentoo-derived distributions, if Paludis is built with Portage environment support enabled and no
Paludis configuration can be detected, Paludis will try to fall back to using the system Portage configuration.
All Paludis clients that use configuration can also be told explicitly to use Portage configuration by using
<code>--environment portage</code> (or <code>--environment portage:/other/root</code> to use configuration files in
another filesystem root).</p>

<p>By default, will be unable to use packages that use EAPIs that Portage does not support. The packages in the Paludis
overlay fall into this category.  You may override this by setting the <code>PALUDIS_IGNORE_BREAKS_PORTAGE</code>
in <code>make.conf</code>; the allowed values are the same as for the <code>accept_breaks_portage</code>
key in Paludis's <a href="../configuration/general.html"><code>general.conf</code></a>,
except that the default is an empty string.</p>

<p>Next, proceed to <a href="#testing">Testing a configuration</a>.</p>

<h2 id="automatic">Automatically migrating</h2>

<p>The <a
    href="http://git.pioto.org/?p=paludis-scripts.git;a=blob_plain;f=portage2paludis.bash">portage2paludis</a>
script can be used to generate a Paludis configuration from an existing Portage configuration. <strong>It is important
    that you check all the configuration files generated by this script by hand; you should not assume that it will
    always get everything perfectly correct.</strong> Some notes:</p>

<ul>
    <li>If using the default configuration directory of <code>/etc/paludis</code>, the script will need to be run as
    root.</li>
    <li>The target configuration directory must not already exist.</li>
    <li>The script will not attempt to migrate a Portage bashrc (note that most of the things that need to be done in a
    bashrc with Portage can be done more sensibly with Paludis).</li>
    <li>Paludis doesn't need an external tool to support syncing of overlays (for Paludis, an overlay is just a normal
    repository that has the <code>master_repository</code> configuration option set). Because Portage does, and because
    several external tools are available that do that, Paludis may not be able to work out a correct <code>sync =
    </code> option for some overlays.</li>
</ul>

<p>You may also wish to set up an unavailable repository for tracking repositories in layman. See <a
    href="../configuration/repositories/unavailable.html">the unavailable repository documentation</a> for a sample repository
config.</p>

<p>Next, proceed to <a href="#testing">Testing a configuration</a>.</p>

<h2 id="manual">Manually configuring Paludis</h2>

<p>First, create some configuration files. For full details on how to do this, see <a href="../configuration/">the
    configuration documentation</a>. For a brief overview:</p>

<p>By default, Paludis looks in <code>sysconfdir/paludis</code> for its configuration, where <code>sysconfdir</code>
should usually be <code>/etc</code>:</p>

<pre>
mkdir -p /etc/paludis/repositories
</pre>

<h3>general.conf</h3>

<p>The file <code>/etc/paludis/general.conf</code> must, at minimum, specify the location of the world file
(other options are described elsewhere in the documentation).  The usual location for Paludis on Gentoo and
Gentoo-derived systems is:</p>

<pre>world = /var/db/pkg/world</pre>

<p>The option <code>world = /var/lib/portage/world</code> can be set if Portage's world file is to be used.</p>

<p>On Exherbo systems, we instead use:</p>

<pre>world = /var/db/paludis/world</pre>

<h3>keywords.conf</h3>

<p>You will need to make <code>/etc/paludis/keywords.conf</code>:</p>

<pre>
*/*                      x86
app-misc/blah            x86 ~x86
</pre>

<p>Or if you use mostly unstable:</p>

<pre>
*/*                      x86 ~x86
app-misc/blah            -* x86
</pre>

<p>Note that:</p>

<ul>
    <li>Matches are cumulative. Use <code>-*</code> if you don't want this.</li>
    <li>Accepting <code>~arch</code> does not accept <code>arch</code> automatically.</li>
    <li>The magic keyword <code>*</code> can be used to accept anything, even empty keywords.</li>
</ul>

<h3>use.conf</h3>

<p>You will also need <code>/etc/paludis/use.conf</code>, which is also cumulative. Note the prefix syntax for things
that would be handled by <code>USE_EXPAND</code> by Portage, and the explicit <code>-*</code>.</p>

<pre>
*/* -doc nls -apache2
*/* LINGUAS: en
*/* INPUT_DEVICES: keyboard mouse
*/* VIDEO_CARDS: -* ati
app-editors/vim -nls
</pre>

<p>And you will need <code>/etc/paludis/licenses.conf</code>, which for most people would look like:</p>

<pre>
*/* *
</pre>

<h3>mirrors.conf</h3>

<p>You might find an <code>/etc/paludis/mirrors.conf</code> useful:</p>

<pre>
gentoo http://gentoo.blueyonder.co.uk/distfiles/
gnu http://gnu.blueyonder.co.uk/
debian http://debian.blueyonder.co.uk/
</pre>

<h3>bashrc</h3>

<p>Next, set up <code>/etc/paludis/bashrc</code>. This <strong>must not</strong> be used to change any value which
affects dependency resolution (<code>USE</code>, <code>LINGUAS</code> etc). It can be used to set <code>CFLAGS</code>
and the like. On some profiles, you <em>must</em> set <code>CHOST</code> as well.</p>

<p>If you need per-package settings, you can use standard variables like <code>$CATEGORY</code>, <code>$PN</code> and
<code>$PV</code>.</p>

<p>You must not output anything to <code>stdout</code>, or very strange things will happen.</p>

<pre>
CFLAGS="-O2 -march=pentium4 -fomit-frame-pointer"
CXXFLAGS="${CFLAGS}"
CHOST="i686-pc-linux-gnu"
MAKEOPTS="-j2"

if [[ "${CATEGORY}/${PN}" == "sys-apps/paludis" ]] ; then
    CXXFLAGS="${CXXFLAGS} -g -ggdb3"
fi
</pre>

<h3 id="repositories">repositories/</h3>

<p>Rather than a couple of simple variables containing directory names, Paludis uses a configuration file for every
repository. This allows substantially more flexibility.</p>

<p>Each file named <code>*.conf</code> in <code>/etc/paludis/repositories</code> defines a single repository. For sanity
reasons, it is strongly recommended that the filename used matches the name of the repository in question, although
<em>the filename you use here has no meaning to Paludis, and does not have to correspond to the repository's
    name</em>.</p>

<h4>Repositories for Gentoo</h4>

<p>Gentoo users will need at least the following two repositories:</p>

<h5>repositories/gentoo.conf</h5>

<p>The main Gentoo repository, sometimes annoyingly called 'the Portage tree' and sometimes historically called
'gentoo-x86', will typically look like:</p>

<pre>
location = /usr/portage
sync = rsync://rsync.europe.gentoo.org/gentoo-portage/
profiles = ${location}/profiles/default-linux/x86/2007.1
format = e
names_cache = (see below)
</pre>

<p>The <code>profiles = </code> option is used in place of Portage's <code>/etc/make.profile</code> symlink, which
Paludis ignores.</p>

<p>The <code>names_cache = </code> option, if set to (for example) <code>/var/cache/paludis/names</code>, can be used to
make resolving <code>pkg</code> to <code>cat/pkg</code> much faster (a lot less than a second, as opposed to tens of
seconds on typical hardware). Most users will benefit hugely from this option. However, Portage will not update or use
this cache, so if for any reason you use Portage for any operation, you must then run <code>paludis
    --regenerate-installable-cache</code> (and possibly <code>paludis --regenerate-installed-cache</code> if you also
use caches for VDB as described below). You will also need to force a cache regeneration if you manually (as opposed to
via <code>--sync</code>) modify a repository.</p>

<p>To disable the names cache, use <code>/var/empty</code> as the value.</p>

<p>You are responsible for ensuring that any cache directories you use exist and have appropriate permissions.</p>

<h5>repositories/installed.conf</h5>

<p>You also need a repository that holds your installed packages. <strong>You must not change the location of this
    repository</strong>; its location is hardcoded in various badly written ebuilds.</p>

<pre>
location = /var/db/pkg/
format = vdb
names_cache = (see below)
provides_cache = (see below)
</pre>

<p>The <code>names_cache = </code> option, if set to (for example) <code>/var/cache/paludis/names</code>, can be used to
make resolving <code>pkg</code> to <code>cat/pkg</code> much faster (a lot less than a second, as opposed to tens of
seconds on typical hardware). Most users will benefit hugely from this option. However, Portage will not update or use
this cache, so if for any reason you use Portage for any operation, you must then run <code>paludis
    --regenerate-installed-cache</code> (and possibly <code>paludis --regenerate-installable-cache</code> if you also
use caches for other repositories as described above).</p>

<p>The <code>provides_cache = </code> option, if set to (for example) <code>/var/cache/paludis/provides</code>, can be
used to make resolving an old style virtual to its providers much faster (a lot less of a second, as opposed to anywhere
up to a minute if many packages are installed). Because many common operations require a virtual resolution, using this
option can give huge speedups. Again, however, Portage will not use this cache, so you will need to regenerate it
manually if you install or uninstall any package using Portage.</p>

<p>To disable either cache, use <code>/var/empty</code> as the value.</p>

<p>You are responsible for ensuring that any cache directories you use exist and have appropriate permissions.</p>

<h5>repositories/paludis-overlay.conf</h5>

<p>You might find the Paludis overlay useful, if you need very up to date or live ebuilds. This also illustrates the
typical way to set up what Portage calls an 'overlay':</p>

<pre>
master_repository = gentoo
location = /var/paludis/repositories/paludis-overlay/
sync = git://git.pioto.org/paludis-overlay.git
names_cache = (as above)
write_cache = (see below)
format = e
</pre>

<p>If <code>write_cache =</code> is set to (for example) <code>/var/cache/paludis/metadata</code>, Paludis will write
generated metadata to this directory. This will avoid having to source every ebuild every time Paludis is run. Use
<code>/var/empty</code> if no cache is desired. (The Gentoo repository includes a pregenerated cache in
<code>${location}/metadata/cache</code>, so the <code>write_cache</code> option is of no use for it; most overlays,
however, do not provide this.)</p>

<p>For details on <code>sync</code> formats, use <code>paludis --list-sync-protocols</code>. The listed options can be
used via <code>sync_options = </code>.</p>

<h5>repositories/layman.conf and repositories/repository.conf</h5>

<p>You may also wish to set up an unavailable repository for tracking repositories in layman. See <a
    href="../configuration/repositories/unavailable.html">the unavailable repository documentation</a> for a sample repository
config. This may be combined with a repository repository for automatic configuration of repositories. See <a
    href="../configuration/repositories/repository.html">the repository repository documentation</a> for details.</p>

<p>Next, proceed to <a href="#testing">Testing a configuration</a>.</p>

<h4>Repositories for Exherbo</h4>

<p>Exherbo users will need at least the following three repositories:</p>

<h5>repositories/arbor.conf</h5>

<p>The main Exherbo repository is 'arbor':</p>

<pre>
location = /var/db/paludis/repositories/arbor
sync = git://git.exherbo.org/arbor.git
profiles = ${location}/profiles/default-linux/x86/2007.0
format = e
</pre>

<h5>repositories/installed.conf</h5>

<p>You also need a repository that holds your installed packages.</p>

<pre>
location = /var/db/paludis/repositories/installed
format = exndbam
</pre>

<h5>repositories/unavailable.conf</h5>


<p>You should usually set up an unavailable repository for tracking repositories that you do not have configured. See <a
    href="../configuration/repositories/unavailable.html">the unavailable repository documentation</a> for a sample repository
config.</p>

<p>Next, proceed to <a href="#testing">Testing a configuration</a>.</p>

<h2 id="testing">Testing a configuration</h2>

<p>To see if a configuration can be used successfully, try:</p>

<pre>
sudo paludis <em>[ add '--environment portage' if appropriate ]</em> --sync
paludis <em>[ add '--environment portage' if appropriate ]</em> --pretend --install world
</pre>

<p>You will probably find that Paludis picks up some updates that Portage doesn't. Paludis does complete dependency
resolution and enforces runtime dependencies by default.</p>

<p>You may encounter nasty error messages, especially if you are running an old install and have some packages that were
installed a long time ago with a broken Portage release. In most cases, reinstalling the package with a recent Portage
release will fix the problem.</p>