Paludis Logo Introduction Hooks general.conf bashrc
Bugs, Requests, Support Syncers keywords.conf / platforms.conf suggestions.conf
Overview Fetchers use.conf / options.conf sets/
FAQ Env Vars licenses.conf / licences.conf repositories/
Clients File Formats mirrors.conf  
Configuration Dep Specs output.conf  
API specpath.conf package_mask.conf  

use.conf / options.conf

This document applies only to clients using PaludisEnvironment. Any standard client that supports a --environment command line option uses PaludisEnvironment unless overridden, either by explicitly selecting another environment (e.g. --environment portage) or, on distributions also supporting Portage, by lack of a Paludis configuration and presence of a Portage configuration.

On Gentoo and derived distributions, the use.conf file controls which use flags are and are not enabled. It is a standard configuration file which may be a bash file (use.bash) and which may use the use.conf.d/ directory.

On Exherbo, the options.conf file controls which options are and are not enabled. It is a standard configuration file which may be a bash file (options.bash) and which may use the options.conf.d/ directory.

Each line in the file consists of a specification followed by one or more use or option flags and labels. A specification may be any of:

Any token may be quoted using either single or double quotes.

A use flag or label can be:

Flag settings are cumulative. This applies to expanded flags too, so if you do not wish to inherit, say, default VIDEO_CARDS from your profile, you will need to use */* VIDEO_CARDS: -* radeon.

Special Flags

Paludis automatically adds special flags controlling how packages are built. These flags are all in the BUILD_OPTIONS group. Packages may have any of the following special flags:

recommended_tests
If set, Paludis will run any 'recommended' tests provided by a package.
optional_tests
If set, Paludis will run any 'optional' tests provided by a package.
expensive_tests
If set, Paludis will run any 'expensive' tests provided by a package. This option should generally only be set by package maintainers, since tests marked as expensive are probably too painful in terms of CPU time or disk space requirements to run on user systems.
trace
If set, Paludis will ask bash to display extremely verbose information about what an ebuild or exheres is doing (using set -x). Not generally a good idea, but can be handy to track down why an ebuild is misbehaving.
work
Controls whether Paludis deletes temporary working directories used during the build. If set to preserve, the working directory is always kept (and a non-destructive merge is performed). If set to tidyup, the working directory is removed after a successful build. If set to remove, the working directory is always removed, even after a failed build.
jobs
If set to an unsigned integer, specifies the number of jobs to run in parallel when build systems support this (e.g. BUILD_OPTIONS: jobs=4 would imply make -j4).
symbols
Controls how debug symbols in executables and libraries are handled. If unset or set to preserve, no stripping is done. If set to strip, debug symbols are stripped. If set to split, debug symbols are split out into files in /usr/lib/debug/. If set to compress, symbols are also split out, and debug sections are compressed. Note that compress will only work with binutils >=2.21.51.0.4, and may cause problems with older versions of gdb.
dwarf_compress
Compress the DWARF sections in executables and libraries. If set, duplicated DIEs are combined into a global DIE section and DW_TAG_partial_unit is used to reference the moved DIEs. Certain DW_FORM_refs may be rewritten if they result in a more compact representation. This option requires the dwz tool to be present and in the default PATH.

Note that these special flags are not use flags from an ebuild perspective. They are used only by Paludis internals, and are not exported to ebuilds.

Example

# Accept some basic defaults for all packages, inheriting defaults from profiles
*/* -doc -nls -apache2 bash-completion -gnome -kde mpd flac aac cdparanoia \
  mmx mmxext rtc sse -arts -qt3 -cups real dvd threads dvdnav mp3 quicktime \
  pnm real vidix a52 3dnow 3dnowext amr bidi bl cddb dts srt unicode xvmc

# And set some USE_EXPAND defaults for all packages, explicitly overriding defaults
# from profiles
*/* LINGUAS:           -* en_GB en
*/* VIDEO_CARDS:       -* nv nvidia
*/* ALSA_CARDS:        -* emu10k1

# Some per package settings
app-editors/vim        -perl -python
app-crypt/gnupg        -X
media-sound/lame       -gtk

# And some wildcarding
dev-cpp/*              doc

# We like tests, and don't want debug symbols
*/*                    BUILD_OPTIONS: optional_tests symbols=strip

# But we do want split debug symbols for a few packages
dev-cpp/*              BUILD_OPTIONS: symbols=split

# We want to run four jobs in parallel if possible (Exheres format packages
# only; Gentoo EAPIs use the MAKEOPTS environment variable instead)
*/*                    BUILD_OPTIONS: jobs=4