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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
|
<?xml version="1.0"?>
<guide self="general-concepts/use-flags/">
<chapter>
<title>USE Flags</title>
<body>
<p>
<c>USE</c> flags are to control optional dependencies and settings which
the user may reasonably want to select. For example, <c>app-editors/vim</c>
can optionally build with support for the <c>ruby</c> interpreter, and it
needs <c>dev-lang/ruby</c> installed to do this <d/> we use the ruby
<c>USE</c> flag to provide this option. On the other hand,
<c>app-text/glark</c> requires <c>ruby</c> no matter what, so no <c>USE</c>
flag is used there.
</p>
<p>
No combination of <c>USE</c> flags should cause a package to fail to build
because users can set any combination of flags.
</p>
<p>
Packages should not configure and link based upon what is available at
compile time <d/> any autodetection must be overridden. This is commonly
referred to as the dependency being "automagic". This is bad because the
dependency is not detected by the package manager tools and can easily
break, among other issues.
</p>
<p>
Automagic dependencies are preferably fixed by preparing a build system patch
adding appropriate options to control the dependency in question, and submitting
this patch upstream for the benefit of all users. To avoid carrying additional
patches downstream, automagic dependencies can usually be worked around using
special build system options (e.g. cache variables in autotools) or through
depending on the relevant packages unconditionally (i.e. forcing the check
to always succeed).
</p>
<note>
The states of USE flags are saved in the VDB, and their values in
<c>pkg_prerm</c> and <c>pkg_postrm</c> are taken from there. This means that
setting or unsetting a USE flag between merge and unmerge has no effect.
</note>
</body>
<section>
<title>When not to use USE flags?</title>
<body>
<p>
While <c>USE</c> flags are generally considered beneficial to users, there
are valid use cases for avoiding them. When writing ebuilds, consider whether
to add flags for particular conditional features, or explore one
of the alternative solutions described below.
</p>
<p>
The usage of a <c>USE</c> flag should not control runtime dependencies when
the package does not link to it. Doing so will create extra
configuration for the package and re-compilation for no underlying file
change on disk. This should be avoided and instead can be conveyed to the
user via post install messages if needed.
</p>
<p>
<c>USE</c> flags must not be used to control installing files that are small,
non-intrusive, do not introduce additional build-time dependencies or cause
a significant increase in build time. Examples of such files are bash completion
files, init.d scripts, logrotate configuration files, systemd service files.
The rationale is the same as above. Instead, those files must be installed
unconditionally.
</p>
<p>
A similar case can be made for packages having multiple conditional programs
or modules. Whenever this results in a large number of <c>USE</c> flags that
would force the user to spend a lot of time choosing compatible flags
and possibly rebuilding after incomplete choices, consider reducing the use
of flags to those programs or modules that have external dependencies
and/or long build times. The rest of them should be built unconditionally
instead, or controlled by a flag such as <c>minimal</c>.
</p>
<p>
You should not introduce USE flags that merely manipulate <c>CFLAGS</c>,
<c>FEATURES</c> or similar variables configured directly by the user. Instead,
packages should avoid manipulating them at all, and let users set them directly.
Common mistakes include:
</p>
<ol>
<li>
Using <c>debug</c> USE flag to force <c>-O0 -g</c> and disable
stripping. The correct purpose of <c>debug</c> flag is to control additional
debug code paths. The use of correct flags and features to preserve
debugging information is user's responsibility.
</li>
<li>
Introducing <c>lto</c> flag to force <c>-flto</c>. This is something user
should set directly in flag varibles.
</li>
<li>
Using <c>CPU_FLAGS_*</c> to control <c>-m*</c> options. Those flags are
intended to control code paths explicitly requiring specific CPU extensions,
e.g. separate assembly. Compiler-generated assembly should respect user's
<c>-march</c> choice.
</li>
</ol>
<p>
There might be corner cases where these rules do not apply. For example, a few
upstreams require users to use specific <c>CFLAGS</c> and reject bug reports
against builds using other values. In this case, it is customary to strip flags
by default and provide <c>custom-cflags</c> flag to allow users to force their
preferred flags.
</p>
</body>
</section>
<section>
<title><c>noblah</c> USE Flags</title>
<body>
<p>
Avoid <c>noblah</c> style <c>USE</c> flags. These break <c>use.mask</c> and
cause all sorts of complications for arch developers. Here's why:
</p>
<p>
Consider a hypothetical package named 'vplayer', which plays videos. This
package has optional support, via <c>USE</c> flags, for various sound and
video output methods, various video codecs and so on.
</p>
<p>
One of vplayer's optional features is support for the 'fakemedia' codec,
which is unfortunately only available as a dodgy x86 binary. We <e>could</e>
handle this by doing something like:
</p>
<codesample lang="ebuild">
RDEPEND="x86? ( fakemedia? ( >=media-libs/fakemedia-1.1 ) )"
</codesample>
<p>
Except this is pretty nasty <d/> what happens when an AMD64 binary is made
as well? Also, users on other archs will see fakemedia listed in
<c>emerge -pv</c> output, even though it is not actually available.
</p>
<p>
Similarly, say vplayer supports output via the ALSA codec as one option.
However, ALSA isn't (or wasn't when this example was written) available on
SPARC or Alpha. So we could do:
</p>
<codesample lang="ebuild">
DEPEND="!sparc? ( !alpha? ( alsa? ( media-libs/alsa-lib ) ) )"
</codesample>
<p>
Again, it's messy, and ALSA still shows up in the <c>emerge -p</c> output.
Also, once ALSA starts working on SPARC, every ebuild that does this would
have to be manually edited.
</p>
<p>
The solution is <c>use.mask</c>, which is documented in
<uri link="::profiles/use.mask/"/>. Each profile can have a <c>use.mask</c>
file which can be used to forcibly disable certain USE flags on a given
arch (or subarch, or subprofile). So, if the <c>fakemedia</c> USE flag was
use.masked on every non-x86 profile, the following would be totally legal
and wouldn't break anything:
</p>
<codesample lang="ebuild">
RDEPEND="fakemedia? ( >=media-libs/fakemedia-1-1 )"
</codesample>
<p>
Users of non-x86 would see the following when doing
<c>emerge -pv vplayer</c>:
</p>
<pre>
[ebuild R ] media-video/vplayer-1.2 alsa -blah (-fakemedia) xyz
</pre>
<p>
To get a flag added to <c>use.mask</c>, ask the relevant arch team.
</p>
</body>
</section>
<section>
<title>IUSE defaults</title>
<body>
<p>
Add <c>+</c> or <c>-</c> before the name of the use flag in <c>IUSE</c> to turn
it on or off by default.
</p>
<important>
Adding <c>-</c> before a flag in <c>IUSE</c> is pretty much useless, as it will
neither override the user configuration (<c>make.conf</c>) nor the profile
default (<c>make.defaults</c> and <c>package.use</c>). See make.conf(5) for
details on USE-ordering in Portage.
</important>
<codesample lang="ebuild">
# Copyright 1999-2020 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=7
IUSE="foo +bar"
</codesample>
</body>
</section>
<section>
<title>Local and Global USE Flags</title>
<body>
<p>
USE flags are categorised as either local or global. A global USE flag must
satisfy several criteria:
</p>
<ul>
<li>It is used by many different packages, at least 5 seems to be agreed
upon.</li>
<li>It has a general non-specific purpose.</li>
</ul>
<p>
The second point is important. If the effect of the USE flag upon
<c>pkg-one</c> is substantially different from the effect it has upon
<c>pkg-two</c>, then the flag is not a suitable candidate for being made a
global flag. In particular, note that if <c>client</c> and <c>server</c>
USE flags are ever introduced, they can not be global USE flags for this
reason.
</p>
<p>
Before introducing a new global USE flag, it must be discussed on the
gentoo-dev mailing list.
</p>
</body>
</section>
<section>
<title>USE Flag Descriptions</title>
<body>
<p>
All USE flags must be described in either <c>use.desc</c> in the
<c>profiles/</c> directory or <c>metadata.xml</c> in the package's
directory. See <c>man portage</c> or the comments in these files for an
explanation of the format. Remember to keep these files sorted. The file
<c>use.local.desc</c> is automatically generated from entries in the
package's <c>metadata.xml</c> and may be used by tools that parse the tree.
Since <c>use.local.desc</c> is automatically generated it must never be
manually editted in the tree.
See <uri link="https://www.gentoo.org/glep/glep-0056.html">GLEP 56</uri>
for more info.
</p>
<p>
The exceptions to this are <c>USE_EXPAND</c> flags, which must be
documented in the <c>profiles/desc/</c> directory. One file per
<c>USE_EXPAND</c> variable is required, which must contain descriptions of
the possible values this variable can take. See the comments in these files
for the format, and remember to keep them sorted.
</p>
</body>
</section>
<section>
<title>Conflicting USE Flags</title>
<body>
<p>
Occasionally, ebuilds will have conflicting USE flags for functionality.
Checking for them and returning an error is <e>not</e> a viable solution.
Instead, you must pick one of the USE flags in conflict to favour and should
alert the user that a particular flag is being used instead.
</p>
<p>
One example comes from the <c>mail-mta/msmtp</c> ebuilds. The package can
use either SSL with GnuTLS, SSL with OpenSSL, or no SSL at all. Because
GnuTLS is more featureful than OpenSSL, it is favoured:
</p>
<codesample lang="ebuild">
src_compile() {
local myconf
if use ssl && use gnutls ; then
myconf="${myconf} --enable-ssl --with-ssl=gnutls"
elif use ssl && ! use gnutls ; then
myconf="${myconf} --enable-ssl --with-ssl=openssl"
else
myconf="${myconf} --disable-ssl"
fi
econf \
# Other stuff
${myconf}
emake
}
</codesample>
<p>
In some exceptional cases, above policy would break reverse USE
dependencies. To avoid this, the ebuild can specify allowed USE flag
combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section
<uri link="::ebuild-writing/eapi/#EAPI=4"/> for a description
of its syntax.
</p>
<p>
For example, if a package <c>dev-libs/foo</c> can be built with either
<c>USE="a"</c> or <c>USE="b"</c> but not with both, then preferring one of
the flags would break packages that depend on either <c>dev-libs/foo[a]</c>
or <c>dev-libs/foo[b]</c>. Therefore, the ebuild should specify
<c>REQUIRED_USE="a? ( !b )"</c> in this case.
</p>
<note>
In order to avoid forcing users to micro-manage flags too much,
<c>REQUIRED_USE</c> should be used sparingly. Follow the normal policy
whenever it is possible to do a build that will presumably suit the user's
needs.
</note>
</body>
</section>
<section>
<title>USE_EXPAND and ARCH USE Flags</title>
<body>
<p>
The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>L10N</c> variables
are automatically expanded into USE flags. These are known as
<c>USE_EXPAND</c> variables. If the user has <c>L10N="en fr"</c> in
<c>make.conf</c>, for example, then <c>USE="l10n_en l10n_fr"</c> will
automatically be set by Portage.
</p>
<p>
The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.defaults</c> as of
Portage 2.0.51.20. This must not be modified without discussion on the
gentoo-dev list, and it must not be modified in any subprofile.
</p>
<p>
The current architecture (e.g. <c>x86</c>, <c>sparc</c>, <c>ppc-macos</c>)
will automatically be set as a USE flag as well. See
<c>profiles/arch.list</c> for a full list of valid architecture keywords,
and <uri link="https://www.gentoo.org/glep/glep-0022.html">GLEP 22</uri>
for an explanation of the format.
</p>
<warning>
It is a common misconception that the architecture variable is somehow
related to <c>ACCEPT_KEYWORDS</c>. It isn't. Accepting <c>x86</c> keywords
on <c>sparc</c>, for example, won't set <c>USE="x86"</c>. Similarly, there
are no <c>~arch</c> USE flags, so don't try <c>if use ~x86</c>.
</warning>
</body>
</section>
</chapter>
</guide>
|
GitWeb