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
|
<?xml version="1.0"?>
<guide self="general-concepts/use-flags/">
<chapter>
<title>USE Flags</title>
<body>
<p>
USE flags are to control optional dependencies and settings which the user may
reasonably want to select. For example, vim can optionally build with support for
the ruby interpreter, and it needs ruby installed to do this <d/> we use the ruby USE
flag to provide this option. On the other hand, glark requires ruby no matter what,
so no USE flag is used here.
</p>
<p>
No combination of USE flags should cause a package to fail to build.
</p>
<p>
Packages should not configure and link based upon what is available at compile time
-- any autodetection must be overridden.
</p>
</body>
<section>
<title><c>noblah</c> USE Flags</title>
<body>
<p>
If at all possible, avoid <c>noblah</c> style USE 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 USE 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 `Profiles use.mask File`_.
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>
<p>
So what's the problem with <c>noblah</c> flags?
</p>
<p>
There's no way to forcibly <e>enable</e> a given USE flag on a particular profile.
So, something like:
</p>
<codesample lang="ebuild">
RDEPEND="!noalsa? ( media-libs/alsa )"
</codesample>
<p>
will make your package unusable by archs without ALSA support, and there is no
way to fix it that doesn't involve adding in nasty <c>arch?</c> flags.
</p>
</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.</li>
<li>It has a general non-specific purpose.</li>
</ul>
<p>
The second point is important. If the effect of the <c>thing</c> USE flag upon
<c>pkg-one</c> is substantially different from the effect it has upon <c>pkg-two</c>,
then <c>thing</c> 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 (excluding <c>USE_EXPAND</c> flags) must be described in either
<c>use.desc</c> or <c>use.local.desc</c> in the <c>profiles/</c> directory. See
`portage-5`_ or the comments in these files for an explanation of the format.
Remember to keep these files 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.
</p>
<p>
One example comes from the <c>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} \
|| die "configure failed"
emake || die "make failed"
}
</codesample>
</body>
</section>
<section>
<title>USE_EXPAND and ARCH USE Flags</title>
<body>
<p>
The <c>VIDEO_CARDS</c>, <c>INPUT_DEVICES</c> and <c>LINGUAS</c> variables are
automatically expanded into USE flags. These are known as <c>USE_EXPAND</c>
variables. If the user has <c>LINGUAS="en fr"</c> in <c>make.conf</c>, for example,
then <c>USE="linguas_en linguas_fr"</c> will automatically be set by portage.
</p>
<p>
The <c>USE_EXPAND</c> list is set in <c>profiles/base/make.default</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 `GLEP 22`_ 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