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
|
<?xml version="1.0"?>
<guide self="keywording/">
<chapter>
<title>Keywording</title>
<body>
<note>
<e>Terminology</e>: The term 'package' refers to an entire directory, for example
<c>app-editors/vim</c> <d /> it does <e>not</e> refer to a specific version. The terms
'ebuild' or 'package version' are used when this meaning is intended. This
distinction is important.
</note>
<p>
Every ebuild must specify a <c>KEYWORDS</c> variable. This variable is used to
indicate the suitability and stability of both the package and the ebuild on
each given arch (<c>sparc</c>, <c>ppc</c>, <c>x86-obsd</c>, ...).
</p>
<note>
The term 'arch' is used in this sense for historical reasons. As a result
of <uri link="https://wiki.gentoo.org/wiki/GLEP:22">GLEP 22</uri>
and the various non-Linux ports, this is no longer a particularly
accurate term.
</note>
<p>
A sample <c>KEYWORDS</c> entry might look like:
</p>
<codesample lang="ebuild">
KEYWORDS="x86 sparc ~mips ~ppc ~ppc-macos -ia64"
</codesample>
<p>
The different levels of keyword are:
</p>
<dl>
<dt>
<c>arch</c> (<c>x86</c>, <c>ppc-macos</c>)
</dt>
<dd>
<p>
Both the package version <e>and</e> the ebuild are widely tested, known to work
and not have any serious issues on the indicated platform.
</p>
</dd>
<dt>
<c>~arch</c> (<c>~x86</c>, <c>~ppc-macos</c>)
</dt>
<dd>
<p>
The package version and the ebuild are believed to work and do not have any
known serious bugs, but more testing is required before the package version
is considered suitable for <c>arch</c>.
</p>
</dd>
<dt>
No keyword
</dt>
<dd>
<p>
If a package has no keyword for a given arch, it means it is not known
whether the package will work, or that insufficient testing has occurred for
<c>~arch</c>.
</p>
</dd>
<dt>
<c>-arch</c> (<c>-x86</c>, <c>-ppc-macos</c>)
</dt>
<dd>
<p>
The package version will not work on the arch. This could be caused by badly
written code (for example, non-64-bit or endian clean code), relying upon
particular hardware (for example, a BIOS querying tool would not work on
non-BIOS architectures) or binary only packages.
</p>
</dd>
</dl>
<p>
The <c>-*</c> keyword is special. It is used to indicate package versions which are
not worth trying to test on unlisted archs. For example, a binary-only package
which is only supported upstream on <c>x86</c> and <c>ppc</c> might use:
</p>
<codesample lang="ebuild">
KEYWORDS="-* x86 ppc"
</codesample>
<p>
This is different in implication from <c>"x86 ppc"</c> <d /> the former implies that
it will not work on other archs, whereas the latter implies that it has not been
tested.
</p>
<p>
Do <b>not</b> use the <c>*</c> or <c>~*</c> special keywords in ebuilds.
</p>
<section>
<title>Equal Visibility Requirement</title>
<body>
<p>
An ebuild <b>must not</b> depend upon any package that is of a lower keyword level
than itself. For example, if <c>foo-1.2</c> depends upon <c>bar-1.2</c>, and
<c>bar-1.2</c> is <c>~x86</c>, then <c>foo-1.2</c> must <b>not</b> be marked stable on
<c>x86</c> unless <c>bar-1.2</c> is also stabilised.
</p>
<p>
You may assume that if a user accepts <c>~arch</c> for a given arch then they also
accept <c>arch</c>.
</p>
<p>
For optional dependencies, all <e>possible</e> dependencies must satisfy the above.
Note that certain <c>USE</c> flags can be forcibly disabled on a per-profile basis
<d /> talk to the arch teams if you require this. For either-or dependencies, <e>at
least one</e> of the options must be of equal or better visibility than the
package in question.
</p>
</body>
</section>
<section>
<title>Hard Masks</title>
<body>
<p>
The <c>package.mask</c> file can be used to 'hard mask' individual or groups of
ebuilds. This should be used for testing ebuilds or beta releases of software,
and may also be used if a package has serious compatibility problems. Packages
which are not hard masked must <b>not</b> have a dependency upon hard masked
packages.
</p>
<p>
The only time it is acceptable for a user to see the <c>Possibly a DEPEND
problem</c> error message is if they have manually changed visibility levels for a
package (for example, through <c>/etc/portage/</c>) and have missed a dependency.
<b>You should never commit a change which could cause this error to appear on a
user system</b>.
</p>
</body>
</section>
<section>
<title>Keywording New Packages</title>
<body>
<important>
New packages should be marked as <c>~arch</c> only upon
architectures for which the committing developer has tested.
</important>
<p>
Do <b>not</b> assume that your package works on all architectures. Do <b>not</b>
assume that user submitted ebuilds will have correct <c>KEYWORDS</c> <d /> chances are
they just copied from somewhere else. Do <b>not</b> assume that upstream's
'supported architectures' list is correct. Do <b>not</b> assume that because your
code is written in Perl / Python / Java / whatever that it will run on other
archs (there is at least one case of a <c>vim</c> script which only worked on
<c>x86</c>).
</p>
<p>
Note that most (non-x86) archs expect you to be on the arch team and bugzilla
alias if you are committing packages with keywords for that arch, and may have
additional requirements of which you should be aware (on <c>mips</c>, for example,
there are multiple ABIs and byte orders to consider <d /> a package working on your
<c>o32</c> box may not work on <c>o64</c> or <c>n32</c>). Contact the individual arch
teams for details.
</p>
<p>
It's important to note that alternative arches (like alpha, ia64, s390,
sh, sparc, hppa, ppc*) are mainly undermanned arches, some of them are
slow, they have more basic problems and have a small userbase. Just file
bugs for these architectures when a package is going to be a dependency of a
package already keyworded.
</p>
<p>
Do <b>not</b> commit straight to <c>arch</c>.
</p>
</body>
</section>
<section>
<title>Keywording on Upgrades</title>
<body>
<p>
When upgrading, drop all existing keywords from <c>arch</c> to <c>~arch</c>, and leave
any existing <c>~arch</c> keywords intact. This must be done even if you <e>think</e>
you're just making a trivial fix <d /> there have been several examples of the
stable tree getting broken this way.
</p>
<p>
Sometimes you may need to remove a keyword because of new unresolved
dependencies. If you do this, you <b>must</b> file a bug notifying the relevant
arch teams.
</p>
<p>
This also applies to revision bumps, not just to upstream version changes.
</p>
</body>
</section>
<section>
<title>Moving from <c>~arch</c> to <c>arch</c></title>
<body>
<p>
Moving a package from <c>~arch</c> to <c>arch</c> is done only by the relevant arch teams.
If you have access to non-x86 hardware but are not on the arch teams, you may wish
to make individual arrangements <d /> the arch teams are happy for help, so long as
they know what is going on. Please note that <c>x86</c> is now no longer an exception
and stabilisation must be done through the <c>x86</c> arch team unless you have
individual arrangements <d /> see
<uri link="https://wiki.gentoo.org/wiki/GLEP:40">GLEP 40</uri>
for further details.
</p>
<p>
For a package to move to stable, the following guidelines must be met:
</p>
<ul>
<li>
The package has spent a reasonable amount of time in <c>~arch</c> first. Thirty
days is the usual figure, although this is clearly only a guideline. For
critical packages, a much longer duration is expected. For small packages
which have only minor changes between versions, a shorter period is sometimes
appropriate.
</li>
<li>
The package must not have any non-<c>arch</c> dependencies.
</li>
<li>
The package must not have any severe outstanding bugs or issues.
</li>
<li>
The package must be widely tested.
</li>
<li>
If the package is a library, it should be known not to break any package which
depends upon it.
</li>
</ul>
<p>
For security fixes, the "reasonable amount of time" guideline may be relaxed.
See the <uri link="http://www.gentoo.org/security/en/vulnerability-policy.xml">
Vulnerability Treatment Policy</uri>
</p>
</body>
</section>
<subsection>
<title>
Simultaneous stabilization on all architectures
</title>
<body>
<p>
If you maintain an architecture-independent package (data files,
icons, pure Perl,...) then you may request that your
package be stabilized on all arches at once. To do this<d />when
you are filing the stabilization bug<d />please add the keyword
<c>ALLARCHES</c> in addition to <c>STABLEREQ</c> and CC the
arches that you would like to stabilize.
</p>
<p>
The arch teams, when encountering the <c>ALLARCHES</c> keyword,
should perform their usual set of tests on a single convenient
architecture. Then, if everything works, stabilize not only the
arch that was used during testing, but also all of the other
arches in CC on the bug. Afterwards, the CC field can be cleared
and the bug closed if appropriate.
</p>
</body>
</subsection>
<section>
<title>Removing Package Versions</title>
<body>
<p>
When removing ebuild, ensure that you do not remove the most recent version at
any given keyword level on any profile. The aim here is:
</p>
<ul>
<li>
Never to force a downgrade. (Exception: occasionally you really do want to
force a downgrade, for example if the newly committed <c>foo-1.3</c> turns out
to be badly broken and that making everyone downgrade to <c>foo-1.2</c> is the
better option. This is rare.)
</li>
<li>
Do not break any existing dependencies.
</li>
</ul>
<p>
If you would like a particular package version moved to stable on certain archs
so that you can tidy up, file a bug.
</p>
</body>
</section>
</body>
</chapter>
</guide>
|
GitWeb