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

<h1>use.conf / options.conf</h1>

###PALUDISENVIRONMENTONLY###

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

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

<p>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:</p>

<ul>
    <li>The special specification <code>*/*</code>, which matches all packages. Nearly all users will have at least one
    line using this specification.</li>
    <li>A simple <code>category/package</code> name.</li>
    <li>A simple <code>set</code> name.</li>
    <li>A complex dependency specification.</li>
</ul>

<p>Any token may be quoted using either single or double quotes.</p>

<p>A use flag or label can be:</p>

<ul>
    <li><code>flag</code>, which enables that flag.</li>
    <li><code>flag=value</code>, which enables that flag and sets its parameter value. Most flags do not
    use parameters, and so any parameter value specified is ignored. See the <code>BUILD_OPTIONS: jobs</code>
    flag below for an example of one that does.</li>
    <li><code>-flag</code>, which disables that flag.</li>
    <li><code>label:</code>, which marks any subsequent flags on that line as applying to a particular use expand
    (Gentoo) or suboption (Exherbo) label. Common examples of use expand labels are <code>VIDEO_CARDS</code>,
    <code>LINGUAS</code> and <code>INPUT_DEVICES</code>, as well as the special <code>BUILD_OPTIONS</code> label
    described below. Labels are <em>not</em> case sensitive.</li>
    <li><code>-*</code>, which disables all flags for the current label, or all flags that are not a label if there is
    no current label.</li>
</ul>

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

<h2>Special Flags</h2>

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

<dl>
    <dt>split</dt>
    <dd>If enabled, Paludis will split debugging information into <code>/usr/lib/debug</code> before merging
    binaries and libraries.</dd>

    <dt>strip</dt>
    <dd>If enabled, Paludis will strip debugging information before merging binaries and libraries.</dd>

    <dt>recommended_tests</dt>
    <dd>If set, Paludis will run any 'recommended' tests provided by a package.</dd>

    <dt>optional_tests</dt>
    <dd>If set, Paludis will run any 'optional' tests provided by a package.</dd>

    <dt>expensive_tests</dt>
    <dd>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.</dd>

    <dt>jobs</dt>
    <dd>If set to an unsigned integer, specifies the number of jobs to run in parallel when build systems
    support this (e.g. <code>BUILD_OPTIONS: jobs=4</code> would imply <code>make -j4</code>).</dd>
</dl>

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

<h2>Example</h2>

<pre>
# 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 -split strip

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

# 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
</pre>