319 lines
13 KiB
HTML
319 lines
13 KiB
HTML
<!-- 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>Next, proceed to <a href="#testing">Testing a configuration</a>.</p>
|
|
|
|
<h2 id="automatic">Automatically migrating</h2>
|
|
|
|
<p>The <a
|
|
href="http://git.exherbo.org/paludis/paludis-scripts.git/plain/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 = ${root}/var/db/paludis/repositories/installed/world</pre>
|
|
|
|
<h3>keywords.conf / platforms.conf</h3>
|
|
|
|
<p>You will need to make <code>/etc/paludis/keywords.conf</code> (Gentoo) or <code>/etc/paludis/platforms.conf</code> (Exherbo):</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 / options.conf</h3>
|
|
|
|
<p>You will also need <code>/etc/paludis/use.conf</code> (Gentoo) or <code>/etc/paludis/options.conf</code> (Exherbo), 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>
|
|
|
|
<h3>licenses.conf / licences.conf</h3>
|
|
|
|
<p>And you will need <code>/etc/paludis/licenses.conf</code> (Gentoo) or <code>/etc/paludis/licences.conf</code> (Exherbo), 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>cave
|
|
fix-cache</code>. 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)
|
|
</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>cave
|
|
fix-cache</code>.</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://github.com/ciaranm/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 a list of <code>sync</code> formats, use <code>cave print-sync-protocols</code>. The protocol options can be obtained
|
|
using <code>cave sync-protocol-options</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 cave <em>[ add '--environment portage' if appropriate ]</em> sync
|
|
cave <em>[ add '--environment portage' if appropriate ]</em> resolve --complete 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>
|
|
|