Paludis, the Other Package Mangler


This document describes some of the more commonly encountered problems, issues and things that aren't bugs but might look like they are. Pestering anyone about these is liable to get you hurt.

This document also describes some things that are not bugs or missing functionality. Pestering anyone about these is liable to get you hurt a lot.


General Paludis Questions

I have an Unanswered Question

If you've checked the documentation, and your question really isn't answered, you should ask it in one of these places:

You are encouraged to submit an entry for this document once your question has been answered.

Why not fix Portage?

The Portage codebase is too broken to be fixed. It is a huge mess of spaghetti procedural code with no underlying design. It relies upon weird quirks in its own behaviour all over the place, so any change is liable to cause huge breakage in seemingly unrelated areas. It is almost entirely undocumented, and the internal names are perverse and often do not reflect what the code now does.

Why C++?

Because we don't have the time or the manpower to write it in C.


Contributions to Paludis are welcome:

How do I...

Use ccache

To enable ccache, simply set the relevant variables in your configuration bashrc:


Use distcc

To enable distcc, simply set the relevant variables in your configuration bashrc:

DISTCC_HOSTS="localhost another_host"

Specify default options

Often users want to specify certain options by default. Common choices include:

You can either use a shell alias, or export PALUDIS_OPTIONS="--options" (in your environment, not in the configuration bashrc).

Remove unneeded packages

Paludis has three ways of removing unused packages. You should always use --pretend and check the output before proceeding:


For the purposes of --uninstall-unused, an installed package is used if any of these conditions are true:

This action will therefore flag any packages that are no longer in use, for example because they were only pulled in by a package that is no longer installed, or because they were required by an old version of a package but no longer are.

--uninstall --with-unused-dependencies

This action will uninstall a package, along with any of its dependencies that will no longer be used once the target package is removed.

This action is recursive, so if foo depends upon bar and bar depends upon baz, and if neither bar nor baz are otherwise required, uninstalling foo will also uninstall bar then baz.

--uninstall --with-dependencies

This action will uninstall a package, along with any other package that requires this package as a dependency. Again, this action is recursive.

Some important notes:

Unmask a Package

First, you need to determine how a package is masked. The easiest way to do this is to use paludis --query. Then, if you're sure you really want to unmask a package, and bearing in mind that doing so might break your system, you need to override the mask. How to do this depends upon the mask reasons:

You need to add an entry to your keywords.conf accepting one of the ebuild's keywords. The special -* keyword cannot be accepted this way; if an ebuild only has this in its keywords, report it to Gentoo bug 160519 and work around it by using *.
user mask
Either remove your package_mask.conf entry or override it with package_unmask.conf.
profile mask
Override with package_unmask.conf.
repository mask
Override with package_unmask.conf.
You cannot override this mask. It indicates either a broken ebuild (if EAPI=unknown or an ebuild not supported by your current version of Paludis.
Accept the appropriate licences in licenses.conf.
by association
Unmask the associated package. This mask reason is currently only used for old style virtuals.

Sync from CVS

Syncing from CVS requires use of either the cvs+pserver or the cvs+ssh protocol. The syntax for the configuration file line is sync = cvs+ssh://username@host:/path/to/cvsroot:modulename. As an example, for syncing with the gentoo repository via CVS, you would use sync = cvs+ssh://username@cvs.gentoo.org:/var/cvsroot:gentoo-x86.

Sync from a Gentoo tree snapshot

Syncing from a tarball requires the tar+http or tar+ftp protocol. You must also specify sync_options = --strip-components=1, as the Gentoo snapshots place everything under a subdirectory named portage. For example:

# Replace this with your favourite Gentoo mirror
sync = tar+ftp://my.favourite.mirror/gentoo/snapshots/portage-latest.tar.bz2
sync_options = --strip-components=1

General Operation

Paludis does not update DEPENDs of already installed packages

Paludis ignores DEPENDs of already installed packages by default. If you need a different behaviour, use the --dl-installed-deps-pre option.

Paludis is Stricter than Portage

Merging Weird Stuff

Paludis will refuse to merge various things:

Packages Failing src_test

Various packages will fail src_test.

You can set SKIP_FUNCTIONS="test" to skip tests. This is best done on a per-package basis via bashrc:

case "${PN}" in

    # Don't use src_test for these broken packages


Unfortunately not all package maintainers care about making their package's test suite work. This is a nuisance, a) because it makes things much harder for arch teams and b) because it makes it harder for users to catch bugs.

At this stage, you should not consider filing a bug about packages whose test phases fail. This is something that is being handled by the Gentoo QA team and various arch teams.

Sandbox Violations when ROOT is Set

Various packages will give sandbox violations when installing to somewhere other than /.

Paludis enforces ROOT via Sandbox. However, some packages don't honour ROOT. To temporarily disable sandbox for these packages, set SANDBOX_PREDICT=/ or SANDBOX_WRITE=/ as appropriate.

Repository Blacklists

Paludis will sometimes blacklist certain repositories. When using a blacklisted repository, you will receive a warning when Paludis starts up. This is not a fatal error, but you should realise that use of the repository in question will likely lead to breakages.

Repositories are only blacklisted under extreme circumstances, such as:

Paludis wants to downgrade Qt or KDE

Unlike Portage, Paludis enforces the dependencies of installed packages, rather than those of the corresponding package in the tree. Unfortunately, to work around Portage limitations, the Qt and KDE eclasses are set up to depend specifically on those versions that are in the tree at the time of installation. The result is that after upgrading to a newer version, dependant packages that were installed before the new version became available will try to force a downgrade back to the old version.

To solve this problem, run your Paludis update command with the --dl-downgrade warning option, and check the backtrace for the package that depends on the older library. Reinstalling this package will fix the dependency. Repeat if there is more than one package with the problem.

Undesirable Misfunctionality

wget Resume Support

Non-Problem: With Portage, wget -c is used to attempt to resume downloads of partial files. With Paludis, this is not done by default.

Rationale: This leads to corruption and wasted bandwidth far too frequently. In particular, if an error page that isn't recognised as a 404 is fetched from one server (this is common for mirror://sourceforge/), resume support means wget would then download all but the first few hundred bytes of the file from somewhere else, leading to a corrupt distfile notice only after lots of bandwidth has been wasted.

Paludis provides a --safe-resume option. When enabled, the download logic is as follows:

Note that you must always specify this option, not just after a download has already been interrupted. See the discussion on default options for how to do this easily.

This logic is handled by the default fetcher for http://, https:// and ftp://. This can be overridden by a custom fetcher if finer grained control is required.

Build Resume / Skip First Support

Non-Problem: Paludis doesn't have an equivalent to --resume --skipfirst in Portage.

Rationale: Too unreliable, too flaky and far too widely abused; however, if an ebuild exits with an error, Paludis will echo a resume command (paludis -i10 =sys-apps/foo-1.23-r1 =app-misc/fnord-2 ...) that can be used to resume the build.

No Automatic Niceness Support

Non-Problem: There's no PORTAGE_NICENESS equivalent.

Rationale: Learn how to use nice. There's no GCC_NICENESS or VIM_NICENESS either.

No Ask Support

Non-Problem: There's nothing like emerge --ask.

Rationale: the paludis client is non-interactive. If someone is making an interactive client, there are much better ways of doing it than the limited functionality that emerge --ask provides.

No Digest Generation

Non-Problem: Paludis doesn't do digest or Manifest creation.

Rationale: In its current form, digest / Manifest is worthless. We will be implementing Manifest2 when it gets properly worked out.

Restoring XTerm Titles

Non-Problem: Paludis doesn't restore the xterm title on exit.

Rationale: Neither does anything else. Some programs do set it to a guessed value based upon a default prompt for certain distributions, but they don't restore it. You should be using PROMPT_COMMAND to do that yourself -- see the bash documentation.

Paludis Does Things Differently

No --tree Equivalent

Paludis does not have something identical to emerge --tree. It does, however, have --show-reasons, which we find to be considerably more informative, useful and correct.

No FEATURES Equivalent

Paludis doesn't use the FEATURES variable. We find this to be a rather ugly way of handling things. We do have equivalents to most values:

See Use ccache.
There are various third party hooks that implement this. We might start shipping one as a demo hook at some point.
See Use distcc.
keepwork, keeptemp, noclean
The builtin_tidyup phase does cleaning up. You can turn this phase off using SKIP_FUNCTIONS="tidyup".
nodoc, noinfo, noman
You could write a hook that removes the relevant directories from $D.
Again, it's a function, so use SKIP_FUNCTIONS="strip".
Always on.
Use --debug-build split.
Always on. See Packages failing src_test.

No --emptytree Equivalent or No --newuse Equivalent

The option --dl-reinstall handles both these cases.

ELOG Equivalent

Paludis ships with a demo hook showing how to get a summary of messages after all packages have been installed. It can be found in SHAREDIR/paludis/hooks/demos/elog.bash. See the hooks documentation for more information about hooks.

No Automatic Directory Creation

Portage usually automatically creates directories for things. Paludis will usually refuse to create directories, except as a subdirectory of an existing Paludis-owned directory. This is for security reasons -- Paludis does not know what permissions are correct for you for the directory, and unlike Portage it does not grant back-door root access to all users in a particular group.

Incidentally, if you want to let multiple users do Paludis cache writes and the like, you should look into what chmod +s does to directories.

Revdep-rebuild Equivalent

Gentoolkit provides a script for rebuilding broken binaries and shared libraries using portage, Paludis provides a ruby script, check_linkage.rb. Install Paludis with the ruby USE flag enabled, and run ruby /usr/share/paludis/ruby/demos/check_linkage.rb.

Repository Questions

Profiles vs Profiles

Don't confuse the profiles/ directory with the profiles = setting for ebuild format repositories. The special files immediately under profiles/, such as profiles/thirdpartymirrors, profiles/use.desc and profiles/package.mask, are specific to that particular profile and no other; the profiles = key has no effect upon them.

Repository names

Because of a requirement forced into GLEP 42 by the peanut gallery, repositories are required to be uniquely identifiable. The identifier must remain consistent even if a repository is moved, either locally or remotely, and thus must be independent of user configuration.

For ebuild format repositories, this is controlled by the profiles/repo_name file. It should contain a single string with no whitespace or funny characters. For many repositories, this has already been created for you; for some overlays, probably including your local overlay if you have one, the file is not yet there so you will have to create it.