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
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
|
<?xml version="1.0"?>
<guide self="ebuild-writing/variables/">
<chapter>
<title>Variables</title>
<body>
<p>
There are a number of special variables which must be set in ebuilds, and many
more which can optionally be specified. There are also some predefined variables
which are of use throughout the ebuild.
</p>
</body>
<section>
<title>Predefined Read-Only Variables</title>
<body>
<p>
The following variables are defined for you. You must not attempt to set
them.
</p>
<table>
<tr>
<th>Variable</th>
<th>Purpose</th>
</tr>
<tr>
<ti><c>P</c></ti>
<ti>Package name and version (excluding revision, if any), for example <c>vim-6.3</c>.</ti>
</tr>
<tr>
<ti><c>PN</c></ti>
<ti>Package name, for example <c>vim</c>.</ti>
</tr>
<tr>
<ti><c>PV</c></ti>
<ti>Package version (excluding revision, if any), for example <c>6.3</c>.</ti>
</tr>
<tr>
<ti><c>PR</c></ti>
<ti>Package revision, or <c>r0</c> if no revision exists.</ti>
</tr>
<tr>
<ti><c>PVR</c></ti>
<ti>Package version and revision, for example <c>6.3-r0</c>, <c>6.3-r1</c>.</ti>
</tr>
<tr>
<ti><c>PF</c></ti>
<ti>Package name, version and revision, for example <c>vim-6.3-r1</c>.</ti>
</tr>
<tr>
<ti><c>A</c></ti>
<ti>
All the source files for the package (excluding those
which are not available because of <c>USE</c> flags).
</ti>
</tr>
<tr>
<ti><c>CATEGORY</c></ti>
<ti>Package's category, for example <c>app-editors</c>.</ti>
</tr>
<tr>
<ti><c>FILESDIR</c></ti>
<ti>
Path to the ebuild's <c>files/</c> directory, commonly used
for small patches and files. Value:
<c>"${PORTDIR}/${CATEGORY}/${PN}/files"</c>.
</ti>
</tr>
<tr>
<ti><c>WORKDIR</c></ti>
<ti>
Path to the ebuild's root build directory. Value:
<c>"${PORTAGE_TMPDIR}/portage/${PF}/work"</c>.
</ti>
</tr>
<tr>
<ti><c>T</c></ti>
<ti>
Path to a temporary directory which may be used by the
ebuild. Value: <c>"${PORTAGE_TMPDIR}/portage/${PF}/temp"</c>.
</ti>
</tr>
<tr>
<ti><c>D</c></ti>
<ti>
Path to the temporary install directory. Value:
<c>"${PORTAGE_TMPDIR}/portage/${PF}/image"</c>.
</ti>
</tr>
<tr>
<ti><c>ROOT</c></ti>
<ti>
Path to the root directory. When not using <c>${D}</c>,
always prepend <c>${ROOT}</c> to the path.
</ti>
</tr>
<tr>
<ti><c>DISTDIR</c></ti>
<ti>
Contains the path to the directory where all the files
fetched for the package are stored.
</ti>
</tr>
</table>
</body>
</section>
<section>
<title>Required Variables</title>
<body>
<p>
The following variables must be defined by every ebuild.
</p>
<table>
<tr>
<th>Variable</th>
<th>Purpose</th>
</tr>
<tr>
<ti><c>DESCRIPTION</c></ti>
<ti>
A short (less than 80 characters) description of the
package's purpose.
</ti>
</tr>
<tr>
<ti><c>SRC_URI</c></ti>
<ti>
A list of source URIs for the package. Can contain
<c>USE</c>-conditional parts, see
<uri link="::ebuild-writing/variables#SRC_URI"/>.
</ti>
</tr>
<tr>
<ti><c>HOMEPAGE</c></ti>
<ti>
Package's homepage. If you are unable to locate an official one, try
to provide a link to <uri link="http://freshmeat.net">freshmeat.net</uri>
or a similar package tracking site. Never refer to a variable name in
the string; include only raw text.
</ti>
</tr>
<tr>
<ti><c>KEYWORDS</c></ti>
<ti>
See <uri link="::ebuild-writing/variables#KEYWORDS"/> and
<uri link="::keywording/"/>.
</ti>
</tr>
<tr>
<ti><c>SLOT</c></ti>
<ti>
The package's <c>SLOT</c>. See
<uri link="::ebuild-writing/variables#SLOT"/>.
</ti>
</tr>
<tr>
<ti><c>LICENSE</c></ti>
<ti>
The package's license, corresponding exactly (including
case) to a file in <c>licenses/</c>. See
<uri link="::ebuild-writing/variables#LICENSE"/>.
</ti>
</tr>
<tr>
<ti><c>IUSE</c></ti>
<ti>
A list of all <c>USE</c> flags (excluding arch flags, but
including <c>USE_EXPAND</c> flags) used within the ebuild. See
<uri link="::ebuild-writing/variables#IUSE"/>.
</ti>
</tr>
</table>
</body>
</section>
<section>
<title>Optional Variables</title>
<body>
<p>
Specifying the following variables is optional:
</p>
<table>
<tr>
<th>Variable</th>
<th>Purpose</th>
</tr>
<tr>
<ti><c>S</c></ti>
<ti>
Path to the temporary build directory, used by
<c>src_compile</c> and <c>src_install</c>. Default:
<c>"${WORKDIR}/${P}"</c>. Ebuilds should <b>not</b> provide a
value for this variable if it is the same as the default value.
</ti>
</tr>
<tr>
<ti><c>DEPEND</c></ti>
<ti>
A list of the package's build dependencies. See
<uri link="::general-concepts/dependencies"/>.
</ti>
</tr>
<tr>
<ti><c>RDEPEND</c></ti>
<ti>
A list of the package's runtime dependencies. See
<uri link="::general-concepts/dependencies"/>.
</ti>
</tr>
<tr>
<ti><c>PDEPEND</c></ti>
<ti>
A list of packages to be installed after the package
is merged. Should only be used where <c>RDEPEND</c> is not
possible. See <uri link="::general-concepts/dependencies"/>.
</ti>
</tr>
<tr>
<ti><c>RESTRICT</c></ti>
<ti>
A space-delimited list of portage features to restrict.
Valid values are <c>fetch</c>, <c>mirror</c>, <c>strip</c>, <c>test</c> and
<c>userpriv</c>. See <c>man 5 ebuild</c> for details.
</ti>
</tr>
<tr>
<ti><c>PROVIDE</c></ti>
<ti>
Any virtuals provided by this package, for example
<c>"virtual/editor virtual/emacs"</c>.
</ti>
</tr>
</table>
</body>
</section>
<section>
<title>SLOT</title>
<body>
<p>
When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use <c>SLOT=""</c>, as
this will disable slotting for this package.
</p>
</body>
</section>
<section>
<title>KEYWORDS</title>
<body>
<p>
The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do
<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>.
</p>
<p>
See <uri link="::keywording/"/> for how to handle this variable.
</p>
</body>
</section>
<section>
<title>SRC_URI</title>
<subsection>
<title>Conditional Sources</title>
<body>
<p>
Conditional source files based upon USE flags are allowed using the usual
<c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary
packages <d/> downloading sparc binaries on ppc would be a waste of bandwidth.
</p>
<codesample lang="ebuild">
SRC_URI="http://example.com/files/${P}-core.tar.bz2
x86? ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 )
ppc? ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 )
sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 )
doc? ( http://example.com/files/${P}/${P}-docs.tar.bz2 )"
</codesample>
<p>
When creating digests it may be necessary to have <e>all</e> SRC_URI components
downloaded. If you have <c>FEATURES="cvs"</c> set, portage should get this right,
although you may end up downloading more than necessary.
</p>
<p>
If a <c>USE_EXPAND</c> variable is used to control whether certain optional
components are installed, the correct thing to do if the variable is unset is
generally to install <e>all</e> available components.
</p>
<codesample lang="ebuild">
SRC_URI="http://example.com/files/${P}-core.tar.bz2
examplecards_foo? ( http://example.com/files/${P}-foo.tar.bz2 )
examplecards_bar? ( http://example.com/files/${P}-bar.tar.bz2 )
examplecards_baz? ( http://example.com/files/${P}-baz.tar.bz2 )
!examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? (
http://example.com/files/${P}-foo.tar.bz2
http://example.com/files/${P}-bar.tar.bz2
http://example.com/files/${P}-baz.tar.bz2 ) ) )"
</codesample>
</body>
</subsection>
</section>
<section>
<title>IUSE</title>
<body>
<p>
Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify
USE flags used only within inherited eclasses within the ebuild's IUSE. Also
note that it's really really broken in portage versions before 2.0.51.
</p>
<p>
Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x86-fbsd</c> and so on) should not be
listed.
</p>
</body>
</section>
<section>
<title>LICENSE</title>
<body>
<p>
It is possible to specify multiple <c>LICENSE</c> entries, and entries which only
apply if a particular <c>USE</c> flag is set. The format is the same as for
<c>DEPEND</c>. See <uri link="http://www.gentoo.org/proj/en/glep/glep-0023.html">
GLEP 23</uri> for details.
</p>
</body>
</section>
<section>
<title>Version Formatting Issues</title>
<body>
<p>
Often upstream's tarball versioning format doesn't quite follow Gentoo
conventions. Differences in how underscores and hyphens are used are
particularly common. For example, what Gentoo calls <c>foo-1.2.3b</c> may be
expecting a tarball named <c>foo-1.2-3b.tar.bz2</c>. Rather than hard coding version
numbers, it is preferable to make a <c>MY_PV</c> variable and use that. The easy
way to do this, which should be used unless you are sure you know what you are
doing, is to use the <c>versionator</c> eclass:
</p>
<codesample lang="ebuild">
inherit versionator
MY_PV=$(replace_version_separator 2 '-')
</codesample>
<p>
This code has the advantage that it will carry on working even if upstream
switches to a format like <c>foo-1.3-4.5.tar.bz2</c> (yes, this really happens).
</p>
<p>
It is also possible to use bash substitution to achieve the same effect (this is
how versionator works internally), but this is complicated, error prone and hard
to read.
</p>
<p>
Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. This
must <e>not</e> be done for any new code, and should be fixed to use either
versionator or bash substitution where possible. Global scope non-bash code is
highly discouraged.
</p>
<p>
The <c>versionator</c> eclass can also be used to extract particular components
from a version string. See <c>man versionator.eclass</c> and the eclass source code
for further documentation and examples. A brief summary of the functions
follows.
</p>
<table>
<tr>
<th>Function</th>
<th>Purpose</th>
</tr>
<tr>
<ti><c>get_all_version_components</c></ti>
<ti>Split up a version string into its component parts.</ti>
</tr>
<tr>
<ti><c>get_version_components</c></ti>
<ti>Get important version components, excluding '.', '-' and '_'.</ti>
</tr>
<tr>
<ti><c>get_major_version</c></ti>
<ti>Get the major version.</ti>
</tr>
<tr>
<ti><c>get_version_component_range</c></ti>
<ti>Extract a range of subparts from a version string.</ti>
</tr>
<tr>
<ti><c>get_after_major_version</c></ti>
<ti>Get everything after the major version.</ti>
</tr>
<tr>
<ti><c>replace_version_separator</c></ti>
<ti>Replace a particular version separator.</ti>
</tr>
<tr>
<ti><c>replace_all_version_separators</c></ti>
<ti>Replace all version separators.</ti>
</tr>
<tr>
<ti><c>delete_version_separator</c></ti>
<ti>Delete a version separator.</ti>
</tr>
<tr>
<ti><c>delete_all_version_separators</c></ti>
<ti>Delete all version separators.</ti>
</tr>
</table>
</body>
</section>
</chapter>
</guide>
|
GitWeb