Paludis Logo Introduction Features
Bugs, Requests, Support Getting Started
Overview Pbins
FAQ Contact
Clients  
Configuration  
API  

Getting Started

There are three ways to configure Paludis:

Once you have configured Paludis, you should test your configuration.

Using an existing Portage configuration

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

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 --environment portage (or --environment portage:/other/root to use configuration files in another filesystem root).

Next, proceed to Testing a configuration.

Automatically migrating

The portage2paludis script can be used to generate a Paludis configuration from an existing Portage configuration. 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. Some notes:

You may also wish to set up an unavailable repository for tracking repositories in layman. See the unavailable repository documentation for a sample repository config.

Next, proceed to Testing a configuration.

Manually configuring Paludis

First, create some configuration files. For full details on how to do this, see the configuration documentation. For a brief overview:

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

mkdir -p /etc/paludis/repositories

general.conf

The file /etc/paludis/general.conf 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:

world = /var/db/pkg/world

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

On Exherbo systems, we instead use:

world = ${root}/var/db/paludis/repositories/installed/world

keywords.conf / platforms.conf

You will need to make /etc/paludis/keywords.conf (Gentoo) or /etc/paludis/platforms.conf (Exherbo):

*/*                      x86
app-misc/blah            x86 ~x86

Or if you use mostly unstable:

*/*                      x86 ~x86
app-misc/blah            -* x86

Note that:

use.conf / options.conf

You will also need /etc/paludis/use.conf (Gentoo) or /etc/paludis/options.conf (Exherbo), which is also cumulative. Note the prefix syntax for things that would be handled by USE_EXPAND by Portage, and the explicit -*.

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

licenses.conf / licences.conf

And you will need /etc/paludis/licenses.conf (Gentoo) or /etc/paludis/licences.conf (Exherbo), which for most people would look like:

*/* *

mirrors.conf

You might find an /etc/paludis/mirrors.conf useful:

gentoo http://gentoo.blueyonder.co.uk/distfiles/
gnu http://gnu.blueyonder.co.uk/
debian http://debian.blueyonder.co.uk/

bashrc

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

If you need per-package settings, you can use standard variables like $CATEGORY, $PN and $PV.

You must not output anything to stdout, or very strange things will happen.

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

repositories/

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

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

Repositories for Gentoo

Gentoo users will need at least the following two repositories:

repositories/gentoo.conf

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

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)

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

The names_cache = option, if set to (for example) /var/cache/paludis/names, can be used to make resolving pkg to cat/pkg 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 cave fix-cache. You will also need to force a cache regeneration if you manually (as opposed to via --sync) modify a repository.

To disable the names cache, use /var/empty as the value.

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

repositories/installed.conf

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

location = /var/db/pkg/
format = vdb
names_cache = (see below)

The names_cache = option, if set to (for example) /var/cache/paludis/names, can be used to make resolving pkg to cat/pkg 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 cave fix-cache.

To disable either cache, use /var/empty as the value.

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

repositories/paludis-overlay.conf

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':

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

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

For a list of sync formats, use cave print-sync-protocols. The protocol options can be obtained using cave sync-protocol-options. The listed options can be used via sync_options = .

repositories/layman.conf and repositories/repository.conf

You may also wish to set up an unavailable repository for tracking repositories in layman. See the unavailable repository documentation for a sample repository config. This may be combined with a repository repository for automatic configuration of repositories. See the repository repository documentation for details.

Next, proceed to Testing a configuration.

Repositories for Exherbo

Exherbo users will need at least the following three repositories:

repositories/arbor.conf

The main Exherbo repository is 'arbor':

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

You also need a repository that holds your installed packages.

location = /var/db/paludis/repositories/installed
format = exndbam
repositories/unavailable.conf

You should usually set up an unavailable repository for tracking repositories that you do not have configured. See the unavailable repository documentation for a sample repository config.

Next, proceed to Testing a configuration.

Testing a configuration

To see if a configuration can be used successfully, try:

sudo cave [ add '--environment portage' if appropriate ] sync
cave [ add '--environment portage' if appropriate ] resolve --complete world

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.

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.