Gentoo Archives: gentoo-portage-dev

From: Dennis Schridde <devurandom@×××.net>
To: gentoo-portage-dev@l.g.o
Cc: Dennis Schridde <devurandom@×××.net>
Subject: [gentoo-portage-dev] [PATCH 1/6] Reorder and cleanup of ebuild(5)
Date: Mon, 24 Sep 2012 00:06:32
Message-Id: 1348439533-28481-2-git-send-email-devurandom@gmx.net
In Reply to: [gentoo-portage-dev] Please review: manpage-cleanup by Dennis Schridde
1 ---
2 man/ebuild.5 | 1137 ++++++++++++++++++++++++++++++----------------------------
3 1 file changed, 579 insertions(+), 558 deletions(-)
4
5 diff --git a/man/ebuild.5 b/man/ebuild.5
6 index 22e6468..f4a53be 100644
7 --- a/man/ebuild.5
8 +++ b/man/ebuild.5
9 @@ -1,311 +1,46 @@
10 .TH "EBUILD" "5" "Sep 2012" "Portage VERSION" "Portage"
11 +
12 .SH "NAME"
13 ebuild \- the internal format, variables, and functions in an ebuild script
14 +
15 .SH "DESCRIPTION"
16 -The
17 -.BR ebuild (1)
18 -program accepts a single ebuild script as an argument. This script
19 +The \fBebuild\fR(1) program accepts a single ebuild script as an argument. This script
20 contains variables and commands that specify how to download, unpack,
21 patch, compile, install and merge a particular software package from
22 its original sources. In addition to all of this, the ebuild script
23 can also contain pre/post install/remove commands, as required. All
24 ebuild scripts are written in bash.
25 -.SH "EXAMPLES"
26 -Here's a simple example ebuild:
27 -
28 -.DS
29 -.nf
30 -# Copyright 1999\-2009 Gentoo Foundation
31 -# Distributed under the terms of the GNU General Public License v2
32 -# $Header: $
33 -
34 -EAPI="5"
35 -
36 -inherit some_eclass another_eclass
37 -
38 -DESCRIPTION="Super\-useful stream editor (sed)"
39 -HOMEPAGE="http://www.gnu.org/software/sed/sed.html"
40 -SRC_URI="ftp://alpha.gnu.org/pub/gnu/${PN}/${P}.tar.gz"
41 -
42 -LICENSE="GPL\-2"
43 -SLOT="0"
44 -KEYWORDS="~x86"
45 -IUSE=""
46 -
47 -RDEPEND=""
48 -DEPEND="nls? ( sys-devel/gettext )"
49 -
50 -src_configure() {
51 - econf \\
52 - \-\-bindir="${EPREFIX}"/bin
53 -}
54
55 -src_install() {
56 - emake DESTDIR="${D}" install
57 - dodoc NEWS README* THANKS AUTHORS BUGS ChangeLog
58 -}
59 -.fi
60 -.SH "VARIABLES"
61 -.TP
62 -.B MISC USAGE NOTES
63 -\- All variables defined in \fBmake.conf\fR(5) are available for use in
64 -ebuilds (such as the PORTAGE* and PORTDIR* variables)
65 -.br
66 -\- When assigning values to variables in ebuilds, you \fBcannot have a
67 -space\fR between the variable name and the equal sign.
68 -.br
69 -\- Variable values should only contain characters that are members of the
70 -\fBascii\fR(7) character set. This requirement is mandated by \fBGLEP 31\fR.
71 -.TP
72 -.B P
73 -This variable contains the package name without the ebuild revision.
74 -This variable must NEVER be modified.
75 -.br
76 -\fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$P\fR=='\fIxfree\-4.2.1\fR'
77 -.TP
78 -.B PN
79 -Contains the name of the script without the version number.
80 -.br
81 -\fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PN\fR=='\fIxfree\fR'
82 -.TP
83 -.B PV
84 -Contains the version number without the revision.
85 -.br
86 -\fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PV\fR=='\fI4.2.1\fR'
87 -.TP
88 -.B PR
89 -Contains the revision number or 'r0' if no revision number exists.
90 -.br
91 -\fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PR\fR=='\fIr2\fR'
92 -.TP
93 -.B PVR
94 -Contains the version number with the revision.
95 -.br
96 -\fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PVR\fR=='\fI4.2.1\-r2\fR'
97 -.TP
98 -.B PF
99 -Contains the full package name \fI[PN]\-[PVR]\fR
100 -.br
101 -\fBxfree\-4.2.1\-r2.ebuild\fR \-\-> \fB$PF\fR=='\fIxfree\-4.2.1\-r2\fR'
102 -.TP
103 -.B CATEGORY
104 -Contains the package category name.
105 -.TP
106 -.B A
107 -Contains all source files required for the package. This variable must
108 -not be defined. It is autogenerated from the \fISRC_URI\fR variable.
109 -.TP
110 -\fBWORKDIR\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/work"\fR
111 -Contains the path to the package build root. Do not modify this variable.
112 -.TP
113 -\fBFILESDIR\fR = \fI"${PORTDIR}/${CATEGORY}/${PN}/files"\fR
114 -Contains the path to the 'files' sub folder in the package specific
115 -location in the portage tree. Do not modify this variable.
116 -.TP
117 -.B EBUILD_PHASE
118 -Contains the abreviated name of the phase function that is
119 -currently executing, such as "setup", "unpack", "compile", or
120 -"preinst".
121 -.TP
122 -.B EBUILD_PHASE_FUNC
123 -Beginning with \fBEAPI 5\fR, contains the full name of the phase
124 -function that is currently executing, such as "pkg_setup",
125 -"src_unpack", "src_compile", or "pkg_preinst".
126 -.TP
127 -.B EPREFIX
128 -Beginning with \fBEAPI 3\fR, contains the offset
129 -that this Portage was configured for during
130 -installation. The offset is sometimes necessary in an ebuild or eclass,
131 -and is available in such cases as ${EPREFIX}. EPREFIX does not contain
132 -a trailing slash, therefore an absent offset is represented by the empty
133 -string. Do not modify this variable.
134 -.TP
135 -\fBS\fR = \fI"${WORKDIR}/${P}"\fR
136 -Contains the path to the temporary \fIbuild directory\fR. This variable
137 -is used by the functions \fIsrc_compile\fR and \fIsrc_install\fR. Both
138 -are executed with \fIS\fR as the current directory. This variable may
139 -be modified to match the extraction directory of a tarball for the package.
140 -.TP
141 -\fBT\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/temp"\fR
142 -Contains the path to a \fItemporary directory\fR. You may use this for
143 -whatever you like.
144 -.TP
145 -\fBD\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/image/"\fR
146 -Contains the path to the temporary \fIinstall directory\fR. Every write
147 -operation that does not involve the helper tools and functions (found below)
148 -should be prefixed with ${D}.
149 -Beginning with \fBEAPI 3\fR, the offset prefix often needs
150 -to be taken into account here, for which the variable
151 -${ED} is provided (see below).
152 -Do not modify this variable.
153 -.TP
154 -\fBED\fT = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/image/${EPREFIX}/"\fR
155 -Beginning with \fBEAPI 3\fR, contains the path
156 -"${D%/}${EPREFIX}/" for convenience purposes.
157 -For \fBEAPI\fR values prior to \fBEAPI 3\fR which do
158 -not support \fB${ED}\fR, helpers use \fB${D}\fR where
159 -they would otherwise use \fB${ED}\fR.
160 -Do not modify this variable.
161 -.TP
162 -.B MERGE_TYPE
163 -Beginning with \fBEAPI 4\fR, the MERGE_TYPE variable can be used to
164 -query the current merge type. This variable will contain one of the
165 -following possible values:
166 -
167 -.RS
168 -.TS
169 -l l
170 -__
171 -l l.
172 -Value Meaning
173 -
174 -binary previously\-built which is scheduled for merge
175 -buildonly source\-build which is not scheduled for merge
176 -source source\-build which is scheduled for merge
177 -.TE
178 -.RE
179 -.TP
180 -.B PORTAGE_LOG_FILE
181 -Contains the path of the build log. If \fBPORT_LOGDIR\fR variable is unset then
182 -\fBPORTAGE_LOG_FILE\fR=\fB"${T}/build.log"\fR.
183 -.TP
184 -.B REPLACED_BY_VERSION
185 -Beginning with \fBEAPI 4\fR, the REPLACED_BY_VERSION variable can be
186 -used in pkg_prerm and pkg_postrm to query the package version that
187 -is replacing the current package. If there is no replacement package,
188 -the variable will be empty, otherwise it will contain a single version
189 -number.
190 -.TP
191 -.B REPLACING_VERSIONS
192 -Beginning with \fBEAPI 4\fR, the REPLACING_VERSIONS variable can be
193 -used in pkg_pretend, pkg_setup, pkg_preinst and pkg_postinst to query
194 -the package version(s) that the current package is replacing. If there
195 -are no packages to replace, the variable will be empty, otherwise it
196 -will contain a space\-separated list of version numbers corresponding
197 -to the package version(s) being replaced. Typically, this variable will
198 -not contain more than one version, but according to PMS it can contain
199 -more.
200 -.TP
201 -\fBROOT\fR = \fI"/"\fR
202 -Contains the path that portage should use as the root of the live filesystem.
203 -When packages wish to make changes to the live filesystem, they should do so in
204 -the tree prefixed by ${ROOT}. Often the offset prefix needs to be taken
205 -into account here, for which the variable ${EROOT} is provided (see
206 -below). Do not modify this variable.
207 -.TP
208 -\fBEROOT\fR = \fI"${ROOT%/}${EPREFIX}/"\fR
209 -Beginning with \fBEAPI 3\fR, contains
210 -"${ROOT%/}${EPREFIX}/" for convenience
211 -purposes. Do not modify this variable.
212 -.TP
213 -\fBDESCRIPTION\fR = \fI"A happy little package"\fR
214 -Should contain a short description of the package.
215 -.TP
216 -\fBEAPI\fR = \fI"0"\fR
217 -Defines the ebuild API version to which this package conforms. If not
218 -defined then it defaults to "0". If portage does not recognize the
219 -EAPI value then it will mask the package and refuse to perform any
220 -operations with it since this means that a newer version of portage
221 -needs to be installed first. For maximum backward compatiblity, a
222 -package should conform to the lowest possible EAPI. Note that anyone
223 -who uses the \fBebuild\fR(1) and \fBrepoman\fR(1) commands with this
224 -package will be required to have a version of portage that recognizes
225 -the EAPI to which this package conforms.
226 -.TP
227 -\fBSRC_URI\fR = \fI"http://example.com/path/${P}.tar.gz"\fR
228 -Contains a list of URIs for the required source files. It can contain
229 -multiple URIs for a single source file. The list is processed in order
230 -if the file was not found on any of the \fIGENTOO_MIRRORS\fR.
231 -Beginning with \fBEAPI 2\fR, the output file name of a given URI may be
232 -customized with a "->" operator on the right hand side, followed by the
233 -desired output file name. All tokens, including the operator and output
234 -file name, should be separated by whitespace.
235 -.TP
236 -\fBHOMEPAGE\fR = \fI"http://example.com/"\fR
237 -Should contain a list of URIs for the sources main sites and other further
238 -package dependent information.
239 -.TP
240 -\fBKEYWORDS\fR = \fI[\-~][x86,ppc,sparc,mips,alpha,arm,hppa]\fR
241 -Should contain appropriate list of arches that the ebuild is know to
242 -work/not work. By default if you do not know if an ebuild runs under
243 -a particular arch simply omit that KEYWORD. If the ebuild will not
244 -work on that arch include it as \-ppc for example. If the ebuild is
245 -being submitted for inclusion, it must have ~arch set for architectures
246 -where it has been PROVEN TO WORK. (Packages KEYWORDed this way may be
247 -unmasked for testing by setting ACCEPT_KEYWORDS="~arch" on the command
248 -line, or in \fBmake.conf\fR(5)) For an authoritative list please review
249 -/usr/portage/profiles/arch.list. Please keep this list in alphabetical order.
250 -.TP
251 -\fBSLOT\fR
252 -This sets the SLOT for packages that may need to have multiple versions
253 -co\-exist. By default you should set \fBSLOT\fR="0". If you are unsure, then
254 -do not fiddle with this until you seek some guidance from some guru. This
255 -value should \fINEVER\fR be left undefined.
256 -
257 -Beginning with \fBEAPI 5\fR, the SLOT variable may contain
258 -an optional sub\-slot part that follows the regular slot and
259 -is delimited by a / character. The sub\-slot must be a valid
260 -slot name. The sub\-slot is used to represent cases in which
261 -an upgrade to a new version of a package with a different
262 -sub\-slot may require dependent packages to be rebuilt. When
263 -the sub\-slot part is omitted from the SLOT definition, the
264 -package is considered to have an implicit sub\-slot which is
265 -equal to the regular slot. Refer to the \fBAtom Slot
266 -Operators\fR section for more information about sub\-slot
267 -usage.
268 -.TP
269 -\fBLICENSE\fR
270 -This should be a space delimited list of licenses that the package falls
271 -under. This \fB_must_\fR be set to a matching license in
272 -/usr/portage/licenses/. If the license does not exist in portage yet, you
273 -must add it first.
274 -.TP
275 -\fBIUSE\fR
276 -This should be a list of any and all USE flags that are leveraged within
277 -your build script. The only USE flags that should not be listed here are
278 -arch related flags (see \fBKEYWORDS\fR). Beginning with \fBEAPI 1\fR, it
279 -is possible to prefix flags with + or - in order to create default settings
280 -that respectively enable or disable the corresponding \fBUSE\fR flags. For
281 -details about \fBUSE\fR flag stacking order, refer to the \fBUSE_ORDER\fR
282 -variable in \fBmake.conf\fR(5). Given the default \fBUSE_ORDER\fR setting,
283 -negative IUSE default settings are effective only for negation of
284 -repo\-level USE settings, since profile and user configuration settings
285 -override them.
286 -.TP
287 -\fBDEPEND\fR
288 -This should contain a list of all packages that are required for the
289 -program to compile.
290 -.RS
291 -.TP
292 -.B DEPEND Atoms
293 -A depend atom is simply a dependency that is used by portage when calculating
294 +.SS "Dependencies"
295 +A \fIdepend atom\fR is simply a dependency that is used by portage when calculating
296 relationships between packages. Please note that if the atom has not already
297 been emerged, then the latest version available is matched.
298 -.RS
299 .TP
300 .B Atom Bases
301 -The base atom is just a full category/packagename. Hence, these are base atoms:
302 +The base atom is just a full category/packagename.
303
304 +Examples:
305 .nf
306 -.I sys\-apps/sed
307 -.I sys\-libs/zlib
308 -.I net\-misc/dhcp
309 +.I sys\-apps/sed
310 +.I sys\-libs/zlib
311 +.I net\-misc/dhcp
312 .fi
313 .TP
314 .B Atom Versions
315 It is nice to be more specific and say that only certain versions of atoms are
316 acceptable. Note that versions must be combined with a prefix (see below).
317 -Hence you may add a version number as a postfix to the base:
318 +Hence you may add a version number as a postfix to the base.
319
320 +Examples:
321 .nf
322 -sys\-apps/sed\fI\-4.0.5\fR
323 -sys\-libs/zlib\fI\-1.1.4\-r1\fR
324 -net\-misc/dhcp\fI\-3.0_p2\fR
325 + sys\-apps/sed\fI\-4.0.5\fR
326 + sys\-libs/zlib\fI\-1.1.4\-r1\fR
327 + net\-misc/dhcp\fI\-3.0_p2\fR
328 .fi
329
330 Versions are normally made up of two or three numbers separated by periods, such
331 as 1.2 or 4.5.2. This string may be followed by a character such as 1.2a or
332 -4.5.2z. Note that this letter is \fBnot\fR meant to indicate alpha, beta,
333 +4.5.2z. Note that this letter is \fInot\fR meant to indicate alpha, beta,
334 etc... status. For that, use the optional suffix; either _alpha, _beta, _pre
335 (pre\-release), _rc (release candidate), or _p (patch). This means for the
336 3rd pre\-release of a package, you would use something like 1.2_pre3. The
337 @@ -315,36 +50,52 @@ suffixes here can be arbitrarily chained without limitation.
338 Sometimes you want to be able to depend on general versions rather than specifying
339 exact versions all the time. Hence we provide standard boolean operators:
340
341 +Examples:
342 .nf
343 -\fI>\fRmedia\-libs/libgd\-1.6
344 -\fI>=\fRmedia\-libs/libgd\-1.6
345 -\fI=\fRmedia\-libs/libgd\-1.6
346 -\fI<=\fRmedia\-libs/libgd\-1.6
347 -\fI<\fRmedia\-libs/libgd\-1.6
348 + \fI>\fRmedia\-libs/libgd\-1.6
349 + \fI>=\fRmedia\-libs/libgd\-1.6
350 + \fI=\fRmedia\-libs/libgd\-1.6
351 + \fI<=\fRmedia\-libs/libgd\-1.6
352 + \fI<\fRmedia\-libs/libgd\-1.6
353 .fi
354 .TP
355 .B Extended Atom Prefixes [!~] and Postfixes [*]
356 Now to get even fancier, we provide the ability to define blocking packages and
357 version range matching. Also note that these extended prefixes/postfixes may
358 -be combined in any way with the atom classes defined above. Here are some common
359 -examples you may find in the portage tree:
360 +be combined in any way with the atom classes defined above.
361 +.RS
362 +.TP
363 +.I ~
364 +means match any revision of the base version specified. So in the
365 +example below, we would match versions '1.0.2a', '1.0.2a\-r1', '1.0.2a\-r2',
366 +etc...
367
368 +Example:
369 .nf
370 -\fI!\fRapp\-text/dos2unix
371 -=dev\-libs/glib\-2\fI*\fR
372 -\fI!\fR=net\-fs/samba\-2\fI*\fR
373 -\fI~\fRnet\-libs/libnet\-1.0.2a
374 -\fI!!\fR<sys\-apps/portage\-2.1.4_rc1\fI\fR
375 + \fI~\fRnet\-libs/libnet\-1.0.2a
376 .fi
377 +.TP
378 +.I !
379 +means block packages from being installed at the same time.
380
381 -\fI!\fR means block packages from being installed at the same time.
382 -.br
383 -\fI!!\fR means block packages from being installed at the same time
384 +Example:
385 +.nf
386 + \fI!\fRapp\-text/dos2unix
387 +.fi
388 +.TP
389 +.I !!
390 +means block packages from being installed at the same time
391 and explicitly disallow them from being temporarily installed
392 simultaneously during a series of upgrades. This syntax is supported
393 beginning with \fBEAPI 2\fR.
394 -.br
395 -\fI*\fR means match any version of the package so long
396 +
397 +Example:
398 +.nf
399 + \fI!!\fR<sys\-apps/portage\-2.1.4_rc1
400 +.fi
401 +.TP
402 +.I *
403 +means match any version of the package so long
404 as the specified string prefix is matched. So with a
405 version of '2*', we can match '2.1', '2.2', '2.2.1',
406 etc... and not match version '1.0', '3.0', '4.1', etc...
407 @@ -353,36 +104,39 @@ will also be matched by '2*'. The version part
408 that comes before the '*' must be a valid version in the absence of the '*'.
409 For example, '2' is a valid version and '2.' is not. Therefore, '2*' is
410 allowed and '2.*' is not.
411 -.br
412 -\fI~\fR means match any revision of the base version specified. So in the
413 -above example, we would match versions '1.0.2a', '1.0.2a\-r1', '1.0.2a\-r2',
414 -etc...
415 +
416 +Examples:
417 +.nf
418 + =dev\-libs/glib\-2\fI*\fR
419 + \fI!\fR=net\-fs/samba\-2\fI*\fR
420 +.fi
421 +.RE
422 .TP
423 .B Atom Slots
424 Beginning with \fBEAPI 1\fR, any atom can be constrained to match a specific
425 \fBSLOT\fR. This is accomplished by appending a colon followed by a
426 \fBSLOT\fR:
427
428 +Examples:
429 .nf
430 -x11\-libs/qt:3
431 -\fI~\fRx11\-libs/qt-3.3.8:3
432 -\fI>=\fRx11\-libs/qt-3.3.8:3
433 -\fI=\fRx11\-libs/qt-3.3*:3
434 + x11\-libs/qt:3
435 + \fI~\fRx11\-libs/qt-3.3.8:3
436 + \fI>=\fRx11\-libs/qt-3.3.8:3
437 + \fI=\fRx11\-libs/qt-3.3*:3
438 .fi
439 -
440 +.TP
441 +.B Sub Slots
442 Beginning with \fBEAPI 5\fR, a slot dependency may contain an
443 optional sub\-slot part that follows the regular slot and is
444 -delimited by a \fB/\fR character.
445 -
446 -.I Examples:
447 +delimited by a \fI/\fR character.
448
449 +Examples:
450 .nf
451 -dev\-libs/icu:0/0
452 -dev\-libs/icu:0/49
453 -dev\-lang/perl:0/5.12
454 -dev\-libs/glib:2/2.30
455 + dev\-libs/icu:0/0
456 + dev\-libs/icu:0/49
457 + dev\-lang/perl:0/5.12
458 + dev\-libs/glib:2/2.30
459 .fi
460 -
461 .TP
462 .B Atom Slot Operators
463 Beginning with \fBEAPI 5\fR, slot operator dependency consists
464 @@ -395,12 +149,11 @@ for runtime dependencies, indicates that the package will not
465 break if the matched package is uninstalled and replaced by
466 a different matching package in a different slot.
467
468 -.I Examples:
469 -
470 +Examples:
471 .nf
472 -dev\-libs/icu:*
473 -dev\-lang/perl:*
474 -dev-libs/glib:*
475 + dev\-libs/icu:*
476 + dev\-lang/perl:*
477 + dev-libs/glib:*
478 .fi
479 .TP
480 .I =
481 @@ -410,24 +163,22 @@ break unless a matching package with slot and sub\-slot equal
482 to the slot and sub\-slot of the best installed version at the
483 time the package was installed is available.
484
485 -.I Examples:
486 -
487 +Examples:
488 .nf
489 -dev\-libs/icu:=
490 -dev\-lang/perl:=
491 -dev-libs/glib:=
492 + dev\-libs/icu:=
493 + dev\-lang/perl:=
494 + dev-libs/glib:=
495 .fi
496 .TP
497 .I slot=
498 Indicates that only a specific slot value is acceptable, and
499 otherwise behaves identically to the plain equals slot operator.
500
501 -.I Examples:
502 -
503 +Examples:
504 .nf
505 -dev\-libs/icu:0=
506 -dev\-lang/perl:0=
507 -dev-libs/glib:2=
508 + dev\-libs/icu:0=
509 + dev\-lang/perl:0=
510 + dev-libs/glib:2=
511 .fi
512 .PP
513 To implement the equals slot operator, the package manager
514 @@ -441,13 +192,12 @@ dependencies. The sub\-slot part must not be omitted here
515 is considered to have an implicit sub\-slot which is equal to
516 the regular slot).
517
518 -.I Examples:
519 -
520 +Examples:
521 .nf
522 -dev\-libs/icu:0/0=
523 -dev\-libs/icu:0/49=
524 -dev\-lang/perl:0/5.12=
525 -dev-libs/glib:2/2.30=
526 + dev\-libs/icu:0/0=
527 + dev\-libs/icu:0/49=
528 + dev\-lang/perl:0/5.12=
529 + dev-libs/glib:2/2.30=
530 .fi
531 .RE
532 .TP
533 @@ -456,7 +206,6 @@ Beginning with \fBEAPI 2\fR, any atom can be constrained to match specific
534 \fBUSE\fR flag settings. When used together with \fBSLOT\fR dependencies,
535 \fBUSE\fR dependencies appear on the right hand side of \fBSLOT\fR
536 dependencies.
537 -
538 .RS
539 .TP
540 .B Unconditional USE Dependencies
541 @@ -465,125 +214,353 @@ l l
542 __
543 l l.
544 Example Meaning
545 -
546 foo[bar] foo must have bar enabled
547 foo[bar,baz] foo must have both bar and baz enabled
548 foo[\-bar,baz] foo must have bar disabled and baz enabled
549 .TE
550 +.TP
551 +.B Conditional USE Dependencies
552 +.TS
553 +l l
554 +__
555 +l l.
556 +Compact Form Equivalent Expanded Form
557 +foo[bar?] bar? ( foo[bar] ) !bar? ( foo )
558 +foo[!bar?] bar? ( foo ) !bar? ( foo[\-bar] )
559 +foo[bar=] bar? ( foo[bar] ) !bar? ( foo[\-bar] )
560 +foo[!bar=] bar? ( foo[\-bar] ) !bar? ( foo[bar] )
561 +.TE
562 +.RE
563 +.TP
564 +.B Atom USE defaults
565 +Beginning with \fBEAPI 4\fR, \fBUSE\fR dependencies may specify default
566 +assumptions about values for flags that may or may not be missing from
567 +the \fBIUSE\fR of the matched package. Such defaults are specified by
568 +immediately following a flag with either \fI(+)\fR or \fI(\-)\fR. Use
569 +\fI(+)\fR to behave as if a missing flag is present and enabled, or
570 +\fI(\-)\fR to behave as if it is present and disabled:
571
572 +Examples:
573 +.nf
574 + media\-video/ffmpeg[threads(+)]
575 + media\-video/ffmpeg[-threads(\-)]
576 +.fi
577 +.TP
578 +.B Dynamic Dependencies
579 +Sometimes programs may depend on different things depending on the USE
580 +variable. Portage offers a few options to handle this. Note that when
581 +using the following syntaxes, each case is considered as 1 Atom in the
582 +scope it appears. That means that each Atom both conditionally include
583 +multiple Atoms and be nested to an infinite depth.
584 +.RS
585 +.TP
586 +.B usevar? ( Atom )
587 +To include the jpeg library when the user has jpeg in \fBUSE\fR, simply use the
588 +following syntax:
589 +
590 +jpeg? ( media\-libs/jpeg )
591 +.TP
592 +.B !usevar? ( Atom )
593 +If you want to include a package only if the user does not have a certain option
594 +in their \fBUSE\fR variable, then use the following syntax:
595 +
596 +!nophysfs? ( dev\-games/physfs )
597 +
598 +This is often useful for those times when you want to want to add optional support
599 +for a feature and have it enabled by default.
600 +.TP
601 +.B usevar? ( Atom if true ) !usevar? ( Atom if false )
602 +For functionality like the tertiary operator found in C you must use
603 +two statements, one normal and one inverted. If a package uses
604 +GTK2 or GTK1, but not both, then you can handle that like this:
605 +
606 +gtk2? ( =x11\-libs/gtk+\-2* ) !gtk2? ( =x11\-libs/gtk+\-1* )
607 +
608 +That way the default is the superior GTK2 library.
609 +.TP
610 +.B || ( Atom Atom ... )
611 +When a package can work with a few different packages but a virtual is not
612 +appropriate, this syntax can easily be used.
613 +
614 +Example:
615 +.nf
616 +|| (
617 + app\-games/unreal\-tournament
618 + app\-games/unreal\-tournament\-goty
619 +)
620 +.fi
621 +
622 +Here we see that unreal\-tournament has a normal version and it has a goty
623 +version. Since they provide the same base set of files, another package can
624 +use either. Adding a virtual is inappropriate due to the small scope of it.
625 +
626 +Another good example is when a package can be built with multiple video
627 +interfaces, but it can only ever have just one.
628 +
629 +Example:
630 +.nf
631 +|| (
632 + sdl? ( media\-libs/libsdl )
633 + svga? ( media\-libs/svgalib )
634 + opengl? ( virtual/opengl )
635 + ggi? ( media\-libs/libggi )
636 + virtual/x11
637 +)
638 +.fi
639 +
640 +Here only one of the packages will be chosen, and the order of preference is
641 +determined by the order in which they appear. So sdl has the best chance of
642 +being chosen, followed by svga, then opengl, then ggi, with a default of X if
643 +the user does not specify any of the previous choices.
644 +
645 +Note that if any of the packages listed are already merged, the package manager
646 +will use that to consider the dependency satisfied.
647 +
648 +.SH "VARIABLES"
649 +.TP
650 +.B Usage Notes
651 +\- All variables defined in \fBmake.conf\fR(5) are available for use in
652 +ebuilds (such as the PORTAGE* and PORTDIR* variables)
653 +.br
654 +\- When assigning values to variables in ebuilds, you \fIcannot have a
655 +space\fR between the variable name and the equal sign.
656 +.br
657 +\- Variable values should only contain characters that are members of the
658 +\fBascii\fR(7) character set. This requirement is mandated by \fBGLEP 31\fR.
659 +.TP
660 +.B P
661 +This variable contains the package name without the ebuild revision.
662 +This variable must NEVER be modified.
663 +
664 +xfree\-4.2.1\-r2.ebuild \-\-> $P=='xfree\-4.2.1'
665 +.TP
666 +.B PN
667 +Contains the name of the script without the version number.
668 +
669 +xfree\-4.2.1\-r2.ebuild \-\-> $PN=='xfree'
670 +.TP
671 +.B PV
672 +Contains the version number without the revision.
673 +
674 +xfree\-4.2.1\-r2.ebuild \-\-> $PV=='4.2.1'
675 +.TP
676 +.B PR
677 +Contains the revision number or 'r0' if no revision number exists.
678 +
679 +xfree\-4.2.1\-r2.ebuild \-\-> $PR=='r2'
680 +.TP
681 +.B PVR
682 +Contains the version number with the revision.
683 +
684 +xfree\-4.2.1\-r2.ebuild \-\-> $PVR=='4.2.1\-r2'
685 +.TP
686 +.B PF
687 +Contains the full package name \fBPN\fR\-\fBPVR\fR
688 +
689 +xfree\-4.2.1\-r2.ebuild \-\-> $PF=='xfree\-4.2.1\-r2'
690 +.TP
691 +.B CATEGORY
692 +Contains the package category name.
693 +.TP
694 +.B A
695 +Contains all source files required for the package. This variable must
696 +not be defined. It is autogenerated from the \fBSRC_URI\fR variable.
697 +.TP
698 +.B WORKDIR\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/work"
699 +Contains the path to the package build root. Do not modify this variable.
700 +.TP
701 +.B FILESDIR\fR = \fI"${PORTDIR}/${CATEGORY}/${PN}/files"
702 +Contains the path to the 'files' sub folder in the package specific
703 +location in the portage tree. Do not modify this variable.
704 +.TP
705 +.B EBUILD_PHASE
706 +Contains the abreviated name of the phase function that is
707 +currently executing, such as "setup", "unpack", "compile", or
708 +"preinst".
709 +.TP
710 +.B EBUILD_PHASE_FUNC
711 +Beginning with \fBEAPI 5\fR, contains the full name of the phase
712 +function that is currently executing, such as "pkg_setup",
713 +"src_unpack", "src_compile", or "pkg_preinst".
714 +.TP
715 +.B EPREFIX
716 +Beginning with \fBEAPI 3\fR, contains the offset
717 +that this Portage was configured for during
718 +installation. The offset is sometimes necessary in an ebuild or eclass,
719 +and is available in such cases as ${EPREFIX}. EPREFIX does not contain
720 +a trailing slash, therefore an absent offset is represented by the empty
721 +string. Do not modify this variable.
722 +.TP
723 +.B S\fR = \fI"${WORKDIR}/${P}"
724 +Contains the path to the temporary \fIbuild directory\fR. This variable
725 +is used by the functions \fIsrc_compile\fR and \fIsrc_install\fR. Both
726 +are executed with \fIS\fR as the current directory. This variable may
727 +be modified to match the extraction directory of a tarball for the package.
728 +.TP
729 +.B T\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/temp"
730 +Contains the path to a \fItemporary directory\fR. You may use this for
731 +whatever you like.
732 +.TP
733 +.B D\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/image/"
734 +Contains the path to the temporary \fIinstall directory\fR. Every write
735 +operation that does not involve the helper tools and functions (found below)
736 +should be prefixed with ${D}.
737 +Beginning with \fBEAPI 3\fR, the offset prefix often needs
738 +to be taken into account here, for which the variable
739 +${ED} is provided (see below).
740 +Do not modify this variable.
741 +.TP
742 +.B ED\fR = \fI"${PORTAGE_TMPDIR}/portage/${CATEGORY}/${PF}/image/${EPREFIX}/"
743 +Beginning with \fBEAPI 3\fR, contains the path
744 +"${D%/}${EPREFIX}/" for convenience purposes.
745 +For EAPI values prior to \fBEAPI 3\fR which do
746 +not support ED, helpers use \fBD\fR where
747 +they would otherwise use ED.
748 +Do not modify this variable.
749 .TP
750 -.B Conditional USE Dependencies
751 +.B MERGE_TYPE
752 +Beginning with \fBEAPI 4\fR, the MERGE_TYPE variable can be used to
753 +query the current merge type. This variable will contain one of the
754 +following possible values:
755 +
756 +.RS
757 .TS
758 l l
759 __
760 l l.
761 -Compact Form Equivalent Expanded Form
762 -
763 -foo[bar?] bar? ( foo[bar] ) !bar? ( foo )
764 -foo[!bar?] bar? ( foo ) !bar? ( foo[\-bar] )
765 -foo[bar=] bar? ( foo[bar] ) !bar? ( foo[\-bar] )
766 -foo[!bar=] bar? ( foo[\-bar] ) !bar? ( foo[bar] )
767 +Value Meaning
768 +binary previously\-built which is scheduled for merge
769 +buildonly source\-build which is not scheduled for merge
770 +source source\-build which is scheduled for merge
771 .TE
772 .RE
773 .TP
774 -.B Atom USE defaults
775 -Beginning with \fBEAPI 4\fR, \fBUSE\fR dependencies may specify default
776 -assumptions about values for flags that may or may not be missing from
777 -the \fBIUSE\fR of the matched package. Such defaults are specified by
778 -immediately following a flag with either \fB(+)\fR or \fB(\-)\fR. Use
779 -\fB(+)\fR to behave as if a missing flag is present and enabled, or
780 -\fB(\-)\fR to behave as if it is present and disabled:
781 -
782 -.RS
783 -.nf
784 -media\-video/ffmpeg[threads(+)]
785 -media\-video/ffmpeg[-threads(\-)]
786 -.fi
787 -.RE
788 -.RE
789 +.B PORTAGE_LOG_FILE
790 +Contains the path of the build log. If \fBPORT_LOGDIR\fR variable is unset then
791 +PORTAGE_LOG_FILE=\fI"${T}/build.log"\fR.
792 .TP
793 -.B Dynamic DEPENDs
794 -Sometimes programs may depend on different things depending on the USE
795 -variable. Portage offers a few options to handle this. Note that when
796 -using the following syntaxes, each case is considered as 1 Atom in the
797 -scope it appears. That means that each Atom both conditionally include
798 -multiple Atoms and be nested to an infinite depth.
799 -.RS
800 +.B REPLACED_BY_VERSION
801 +Beginning with \fBEAPI 4\fR, the REPLACED_BY_VERSION variable can be
802 +used in pkg_prerm and pkg_postrm to query the package version that
803 +is replacing the current package. If there is no replacement package,
804 +the variable will be empty, otherwise it will contain a single version
805 +number.
806 .TP
807 -.B usevar? ( DEPEND Atom )
808 -To include the jpeg library when the user has jpeg in \fBUSE\fR, simply use the
809 -following syntax:
810 -.br
811 -.B jpeg? ( media\-libs/jpeg )
812 +.B REPLACING_VERSIONS
813 +Beginning with \fBEAPI 4\fR, the REPLACING_VERSIONS variable can be
814 +used in pkg_pretend, pkg_setup, pkg_preinst and pkg_postinst to query
815 +the package version(s) that the current package is replacing. If there
816 +are no packages to replace, the variable will be empty, otherwise it
817 +will contain a space\-separated list of version numbers corresponding
818 +to the package version(s) being replaced. Typically, this variable will
819 +not contain more than one version, but according to PMS it can contain
820 +more.
821 .TP
822 -.B !usevar? ( Atom )
823 -If you want to include a package only if the user does not have a certain option
824 -in their \fBUSE\fR variable, then use the following syntax:
825 -.br
826 -.B !nophysfs? ( dev\-games/physfs )
827 -.br
828 -This is often useful for those times when you want to want to add optional support
829 -for a feature and have it enabled by default.
830 +.B ROOT\fR = \fI"/"
831 +Contains the path that portage should use as the root of the live filesystem.
832 +When packages wish to make changes to the live filesystem, they should do so in
833 +the tree prefixed by ${ROOT}. Often the offset prefix needs to be taken
834 +into account here, for which the variable ${EROOT} is provided (see
835 +below). Do not modify this variable.
836 .TP
837 -.B usevar? ( Atom if true ) !usevar? ( Atom if false )
838 -For functionality like the tertiary operator found in C you must use
839 -two statements, one normal and one inverted. If a package uses
840 -GTK2 or GTK1, but not both, then you can handle that like this:
841 -.br
842 -.B gtk2? ( =x11\-libs/gtk+\-2* ) !gtk2? ( =x11\-libs/gtk+\-1* )
843 -.br
844 -That way the default is the superior GTK2 library.
845 +.B EROOT\fR = \fI"${ROOT%/}${EPREFIX}/"
846 +Beginning with \fBEAPI 3\fR, contains
847 +"${ROOT%/}${EPREFIX}/" for convenience
848 +purposes. Do not modify this variable.
849 .TP
850 -.B || ( Atom Atom ... )
851 -When a package can work with a few different packages but a virtual is not
852 -appropriate, this syntax can easily be used.
853 -.nf
854 -.B || (
855 -.B app\-games/unreal\-tournament
856 -.B app\-games/unreal\-tournament\-goty
857 -.B )
858 -.fi
859 -Here we see that unreal\-tournament has a normal version and it has a goty
860 -version. Since they provide the same base set of files, another package can
861 -use either. Adding a virtual is inappropriate due to the small scope of it.
862 -.br
863 -Another good example is when a package can be built with multiple video
864 -interfaces, but it can only ever have just one.
865 -.nf
866 -.B || (
867 -.B sdl? ( media\-libs/libsdl )
868 -.B svga? ( media\-libs/svgalib )
869 -.B opengl? ( virtual/opengl )
870 -.B ggi? ( media\-libs/libggi )
871 -.B virtual/x11
872 -.B )
873 -.fi
874 -Here only one of the packages will be chosen, and the order of preference is
875 -determined by the order in which they appear. So sdl has the best chance of
876 -being chosen, followed by svga, then opengl, then ggi, with a default of X if
877 -the user does not specify any of the previous choices.
878 -.br
879 -Note that if any of the packages listed are already merged, the package manager
880 -will use that to consider the dependency satisfied.
881 -.RE
882 +.B DESCRIPTION\fR = \fI"A happy little package"
883 +Should contain a short description of the package.
884 +.TP
885 +.B EAPI\fR = \fI"0"
886 +Defines the ebuild API version to which this package conforms. If not
887 +defined then it defaults to "0". If portage does not recognize the
888 +EAPI value then it will mask the package and refuse to perform any
889 +operations with it since this means that a newer version of portage
890 +needs to be installed first. For maximum backward compatiblity, a
891 +package should conform to the lowest possible EAPI. Note that anyone
892 +who uses the \fBebuild\fR(1) and \fBrepoman\fR(1) commands with this
893 +package will be required to have a version of portage that recognizes
894 +the EAPI to which this package conforms.
895 +.TP
896 +.B SRC_URI\fR = \fI"http://example.com/path/${P}.tar.gz"
897 +Contains a list of URIs for the required source files. It can contain
898 +multiple URIs for a single source file. The list is processed in order
899 +if the file was not found on any of the \fIGENTOO_MIRRORS\fR.
900 +Beginning with \fBEAPI 2\fR, the output file name of a given URI may be
901 +customized with a "->" operator on the right hand side, followed by the
902 +desired output file name. All tokens, including the operator and output
903 +file name, should be separated by whitespace.
904 +.TP
905 +.B HOMEPAGE\fR = \fI"http://example.com/"
906 +Should contain a list of URIs for the sources main sites and other further
907 +package dependent information.
908 +.TP
909 +.B KEYWORDS\fR = \fI[\-~][x86,ppc,sparc,mips,alpha,arm,hppa]
910 +Should contain appropriate list of arches that the ebuild is know to
911 +work/not work. By default if you do not know if an ebuild runs under
912 +a particular arch simply omit that KEYWORD. If the ebuild will not
913 +work on that arch include it as \-ppc for example. If the ebuild is
914 +being submitted for inclusion, it must have ~arch set for architectures
915 +where it has been PROVEN TO WORK. (Packages KEYWORDed this way may be
916 +unmasked for testing by setting ACCEPT_KEYWORDS="~arch" on the command
917 +line, or in \fBmake.conf\fR(5)) For an authoritative list please review
918 +/usr/portage/profiles/arch.list. Please keep this list in alphabetical order.
919 +.TP
920 +.B SLOT
921 +This sets the SLOT for packages that may need to have multiple versions
922 +co\-exist. By default you should set \fBSLOT\fR="0". If you are unsure, then
923 +do not fiddle with this until you seek some guidance from some guru. This
924 +value should \fINEVER\fR be left undefined.
925
926 -.RE
927 +Beginning with \fBEAPI 5\fR, the SLOT variable may contain
928 +an optional sub\-slot part that follows the regular slot and
929 +is delimited by a / character. The sub\-slot must be a valid
930 +slot name. The sub\-slot is used to represent cases in which
931 +an upgrade to a new version of a package with a different
932 +sub\-slot may require dependent packages to be rebuilt. When
933 +the sub\-slot part is omitted from the SLOT definition, the
934 +package is considered to have an implicit sub\-slot which is
935 +equal to the regular slot. Refer to the \fBAtom Slot
936 +Operators\fR section for more information about sub\-slot
937 +usage.
938 +.TP
939 +.B LICENSE
940 +This should be a space delimited list of licenses that the package falls
941 +under. This \fB_must_\fR be set to a matching license in
942 +/usr/portage/licenses/. If the license does not exist in portage yet, you
943 +must add it first.
944 +.TP
945 +.B IUSE
946 +This should be a list of any and all USE flags that are leveraged within
947 +your build script. The only USE flags that should not be listed here are
948 +arch related flags (see \fBKEYWORDS\fR). Beginning with \fBEAPI 1\fR, it
949 +is possible to prefix flags with + or - in order to create default settings
950 +that respectively enable or disable the corresponding \fBUSE\fR flags. For
951 +details about \fBUSE\fR flag stacking order, refer to the \fBUSE_ORDER\fR
952 +variable in \fBmake.conf\fR(5). Given the default \fBUSE_ORDER\fR setting,
953 +negative IUSE default settings are effective only for negation of
954 +repo\-level USE settings, since profile and user configuration settings
955 +override them.
956 +.TP
957 +.B DEPEND
958 +This should contain a list of all packages that are required for the
959 +program to compile as described in \fBDEPENDENCIES\fR.
960 .TP
961 -\fBRDEPEND\fR
962 +.B RDEPEND
963 This should contain a list of all packages that are required for this
964 program to run (aka runtime depend). If this is not set in \fBEAPI 3\fR
965 or earlier, then it defaults to the value of \fBDEPEND\fR. In
966 \fBEAPI 4\fR or later, \fBRDEPEND\fR will never be implicitly set.
967 -.br
968 -You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR.
969 +
970 +You may use the same syntax to vary dependencies as seen above in \fBDEPENDENCIES\fR.
971 .TP
972 -\fBPDEPEND\fR
973 +.B PDEPEND
974 This should contain a list of all packages that should be merged after this one,
975 but may be merged before if need be.
976 -.br
977 -You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR.
978 +
979 +You may use the same syntax to vary dependencies as seen above in \fBDEPENDENCIES\fR.
980 .TP
981 -\fBREQUIRED_USE\fR
982 +.B REQUIRED_USE
983 Beginning with \fBEAPI 4\fR, the \fBREQUIRED_USE\fR variable can be
984 used to specify combinations of \fBUSE\fR flags that are allowed
985 or not allowed. Elements can be nested when necessary.
986 @@ -592,7 +569,6 @@ l l
987 __
988 l l.
989 Behavior Expression
990 -
991 If flag1 enabled then flag2 disabled flag1? ( !flag2 )
992 If flag1 enabled then flag2 enabled flag1? ( flag2 )
993 If flag1 disabled then flag2 enabled !flag1? ( flag2 )
994 @@ -602,7 +578,7 @@ Must enable exactly one but not more (exclusive or) ^^ ( flag1 flag2 flag3 )
995 May enable at most one (EAPI 5 or later) ?? ( flag1 flag2 flag3 )
996 .TE
997 .TP
998 -\fBRESTRICT\fR = \fI[strip,mirror,fetch,userpriv]\fR
999 +.B RESTRICT\fR = \fI[strip,mirror,fetch,userpriv]
1000 This should be a space delimited list of portage features to restrict.
1001 You may use conditional syntax to vary restrictions as seen above in DEPEND.
1002 .PD 0
1003 @@ -642,7 +618,7 @@ Disables userpriv for specific packages.
1004 .RE
1005 .PD 1
1006 .TP
1007 -\fBPROPERTIES\fR = \fI[interactive]\fR
1008 +.B PROPERTIES\fR = \fI[interactive]
1009 A space delimited list of properties, with conditional syntax support.
1010 .PD 0
1011 .RS
1012 @@ -652,30 +628,31 @@ One or more ebuild phases will produce a prompt that requires user interaction.
1013 .RE
1014 .PD 1
1015 .TP
1016 -\fBPROVIDE\fR = \fI"virtual/TARGET"\fR
1017 +.B PROVIDE\fR = \fI"virtual/TARGET"
1018 This variable should only be used when a package provides a virtual target.
1019 For example, blackdown\-jdk and sun\-jdk provide \fIvirtual/jdk\fR. This
1020 allows for packages to depend on \fIvirtual/jdk\fR rather than on blackdown
1021 or sun specifically.
1022 .TP
1023 -\fBDOCS\fR
1024 +.B DOCS
1025 Beginning with \fBEAPI 4\fR, an array or space\-delimited list of documentation
1026 files for the default src_install function to install using dodoc. If
1027 undefined, a reasonable default list is used. See the documentation for
1028 src_install below.
1029 -.SH "QA CONTROL VARIABLES"
1030 +
1031 +.SS "QA Control Variables:"
1032 .TP
1033 -.B USAGE NOTES
1034 +.B Usage Notes
1035 Several QA variables are provided which allow an ebuild to manipulate some
1036 of the QA checks performed by portage. Use of these variables in ebuilds
1037 should be kept to an absolute minimum otherwise they defeat the purpose
1038 of the QA checks, and their use is subject to agreement of the QA team.
1039 They are primarily intended for use by ebuilds that install closed\-source
1040 binary objects that cannot be altered.
1041 -.br
1042 +
1043 Note that objects that violate these rules may fail on some architectures.
1044 .TP
1045 -\fBQA_PREBUILT\fR
1046 +.B QA_PREBUILT
1047 This should contain a list of file paths, relative to the image
1048 directory, of files that are pre\-built binaries. Paths
1049 listed here will be appended to each of the QA_* variables
1050 @@ -685,70 +662,70 @@ the QA_* variables that support regular expressions instead
1051 of fnmatch patterns. The translation mechanism simply replaces
1052 "*" with ".*".
1053 .TP
1054 -\fBQA_TEXTRELS\fR
1055 +.B QA_TEXTRELS
1056 This variable can be set to a list of file paths, relative to the image
1057 directory, of files that contain text relocations that cannot be eliminated.
1058 The paths may contain fnmatch patterns.
1059 -.br
1060 +
1061 This variable is intended to be used on closed\-source binary objects that
1062 cannot be altered.
1063 .TP
1064 -\fBQA_EXECSTACK\fR
1065 +.B QA_EXECSTACK
1066 This should contain a list of file paths, relative to the image directory, of
1067 objects that require executable stack in order to run.
1068 The paths may contain fnmatch patterns.
1069 -.br
1070 +
1071 This variable is intended to be used on objects that truly need executable
1072 stack (i.e. not those marked to need it which in fact do not).
1073 .TP
1074 -\fBQA_WX_LOAD\fR
1075 +.B QA_WX_LOAD
1076 This should contain a list of file paths, relative to the image directory, of
1077 files that contain writable and executable segments. These are rare.
1078 The paths may contain fnmatch patterns.
1079 .TP
1080 -\fBQA_FLAGS_IGNORED\fR
1081 +.B QA_FLAGS_IGNORED
1082 This should contain a list of file paths, relative to the image directory, of
1083 files that do not contain .GCC.command.line sections or contain .hash sections.
1084 The paths may contain regular expressions with escape\-quoted special characters.
1085 -.br
1086 +
1087 This variable is intended to be used on files of binary packages which ignore
1088 CFLAGS, CXXFLAGS, FFLAGS, FCFLAGS, and LDFLAGS variables.
1089 .TP
1090 -.TP
1091 -\fBQA_DT_HASH\fR
1092 +.B QA_DT_HASH
1093 This should contain a list of file paths, relative to the image directory, of
1094 files that contain .hash sections. The paths may contain regular expressions
1095 with escape\-quoted special characters. This variable is deprecated. Use
1096 \fBQA_FLAGS_IGNORED\fR instead.
1097 -.br
1098 +
1099 This variable is intended to be used on files of binary packages which ignore
1100 LDFLAGS variable.
1101 .TP
1102 -\fBQA_PRESTRIPPED\fR
1103 +.B QA_PRESTRIPPED
1104 This should contain a list of file paths, relative to the image directory, of
1105 files that contain pre-stripped binaries. The paths may contain regular
1106 expressions with escape\-quoted special characters.
1107 .TP
1108 -\fBQA_SONAME\fR
1109 +.B QA_SONAME
1110 This should contain a list of file paths, relative to the image directory, of
1111 shared libraries that lack SONAMEs. The paths may contain regular expressions
1112 with escape\-quoted special characters.
1113 .TP
1114 -\fBQA_SONAME_NO_SYMLINK\fR
1115 +.B QA_SONAME_NO_SYMLINK
1116 This should contain a list of file paths, relative to the image directory, of
1117 shared libraries that have SONAMEs but should not have a corresponding SONAME
1118 symlink in the same directory. The paths may contain regular expressions
1119 with escape\-quoted special characters.
1120 .TP
1121 -\fBQA_DT_NEEDED\fR
1122 +.B QA_DT_NEEDED
1123 This should contain a list of file paths, relative to the image directory, of
1124 shared libraries that lack NEEDED entries. The paths may contain regular
1125 expressions with escape\-quoted special characters.
1126 .TP
1127 -\fBQA_DESKTOP_FILE\fR
1128 +.B QA_DESKTOP_FILE
1129 This should contain a list of file paths, relative to the image directory, of
1130 desktop files which should not be validated. The paths may contain regular
1131 expressions with escape\-quoted special characters.
1132 +
1133 .SH "PORTAGE DECLARATIONS"
1134 .TP
1135 .B inherit
1136 @@ -761,6 +738,7 @@ ebuild. Specification of the eclasses contains only their name and not the
1137 \fI.eclass\fR extension. Also note that the inherit statement must come
1138 before other variable declarations unless these variables are used in global
1139 scope of eclasses.
1140 +
1141 .SH "PHASE FUNCTIONS"
1142 .TP
1143 .B pkg_pretend
1144 @@ -784,33 +762,33 @@ end the function with a call to \fBdie\fR.
1145 This function can be used if the package needs specific setup actions or
1146 checks to be preformed before anything else.
1147 .br
1148 -Initial working directory of ${PORTAGE_TMPDIR}.
1149 +Initial working directory: $PORTAGE_TMPDIR
1150 .TP
1151 .B src_unpack
1152 This function is used to unpack all the sources in \fIA\fR to \fIWORKDIR\fR.
1153 If not defined in the \fIebuild script\fR it calls \fIunpack ${A}\fR. Any
1154 patches and other pre configure/compile modifications should be done here.
1155 .br
1156 -Initial working directory of $WORKDIR.
1157 +Initial working directory: $WORKDIR
1158 .TP
1159 .B src_prepare
1160 All preparation of source code, such as application of patches, should be done
1161 here. This function is supported beginning with \fBEAPI 2\fR.
1162 .br
1163 -Initial working directory of $S.
1164 +Initial working directory: $S
1165 .TP
1166 .B src_configure
1167 All necessary steps for configuration should be done here. This function is
1168 supported beginning with \fBEAPI 2\fR.
1169 .br
1170 -Initial working directory of $S.
1171 +Initial working directory: $S
1172 .TP
1173 .B src_compile
1174 With less than \fBEAPI 2\fR, all necessary steps for both configuration and
1175 compilation should be done here. Beginning with \fBEAPI 2\fR, only compilation
1176 steps should be done here.
1177 .br
1178 -Initial working directory of $S.
1179 +Initial working directory: $S
1180 .TP
1181 .B src_test
1182 Run all package specific test cases. The default is to run
1183 @@ -819,13 +797,13 @@ the default src_test implementation will automatically pass the
1184 \-j1 option as the last argument to emake, and beginning with
1185 \fBEAPI 5\fR it will allow the tests to run in parallel.
1186 .br
1187 -Initial working directory of $S.
1188 +Initial working directory: $S
1189 .TP
1190 .B src_install
1191 Should contain everything required to install the package in the temporary
1192 \fIinstall directory\fR.
1193 .br
1194 -Initial working directory of $S.
1195 +Initial working directory: $S
1196
1197 Beginning with \fBEAPI 4\fR, if src_install is undefined then the
1198 following default implementation is used:
1199 @@ -855,18 +833,20 @@ All modifications required on the live\-filesystem before and after the
1200 package is merged should be placed here. Also commentary for the user
1201 should be listed here as it will be displayed last.
1202 .br
1203 -Initial working directory of $PWD.
1204 +Initial working directory: $PWD
1205 .TP
1206 .B pkg_prerm pkg_postrm
1207 Like the pkg_*inst functions but for unmerge.
1208 .br
1209 -Initial working directory of $PWD.
1210 +Initial working directory: $PWD
1211 .TP
1212 .B pkg_config
1213 This function should contain optional basic configuration steps.
1214 .br
1215 -Initial working directory of $PWD.
1216 -.SH "HELPER FUNCTIONS: PHASES"
1217 +Initial working directory: $PWD
1218 +
1219 +.SH "HELPER FUNCTIONS"
1220 +.SS "Phases:"
1221 .TP
1222 .B default
1223 Calls the default phase function implementation for the currently executing
1224 @@ -885,7 +865,6 @@ l
1225 _
1226 l.
1227 Default Phase Functions
1228 -
1229 default_pkg_nofetch
1230 default_src_unpack
1231 default_src_prepare
1232 @@ -894,9 +873,10 @@ default_src_compile
1233 default_src_test
1234 .TE
1235 .RE
1236 -.SH "HELPER FUNCTIONS: GENERAL"
1237 +
1238 +.SS "General:"
1239 .TP
1240 -\fBdie\fR \fI[reason]\fR
1241 +.B die\fR \fI[reason]
1242 Causes the current emerge process to be aborted. The final display will
1243 include \fIreason\fR.
1244
1245 @@ -904,11 +884,11 @@ Beginning with \fBEAPI 4\fR, all helpers automatically call \fBdie\fR
1246 whenever some sort of error occurs. Helper calls may be prefixed with
1247 the \fBnonfatal\fR helper in order to prevent errors from being fatal.
1248 .TP
1249 -\fBnonfatal\fR \fI<helper>\fR
1250 +.B nonfatal\fR \fI<helper>
1251 Execute \fIhelper\fR and \fIdo not\fR call die if it fails.
1252 The \fBnonfatal\fR helper is available beginning with \fBEAPI 4\fR.
1253 .TP
1254 -\fBuse\fR \fI<USE item>\fR
1255 +.B use\fR \fI<USE item>
1256 If \fIUSE item\fR is in the \fBUSE\fR variable, the function will silently
1257 return 0 (aka shell true). If \fIUSE item\fR is not in the \fBUSE\fR
1258 variable, the function will silently return 1 (aka shell false). \fBusev\fR
1259 @@ -930,12 +910,12 @@ fi
1260 .fi
1261 .RE
1262 .TP
1263 -\fBusex\fR \fI<USE flag>\fR \fI[true output]\fR \fI[false output]\fR \fI[true suffix]\fR \fI[false suffix]\fR
1264 +.B usex\fR \fI<USE flag>\fR \fI[true output]\fR \fI[false output]\fR \fI[true suffix]\fR \fI[false suffix]
1265 If USE flag is set, echo [true output][true suffix] (defaults to
1266 "yes"), otherwise echo [false output][false suffix] (defaults to
1267 "no"). The usex helper is available beginning with \fBEAPI 5\fR.
1268 .TP
1269 -\fBuse_with\fR \fI<USE item>\fR \fI[configure name]\fR \fI[configure opt]\fR
1270 +.B use_with\fR \fI<USE item>\fR \fI[configure name]\fR \fI[configure opt]
1271 Useful for creating custom options to pass to a configure script. If \fIUSE
1272 item\fR is in the \fBUSE\fR variable and a \fIconfigure opt\fR is specified,
1273 then the string \fI\-\-with\-[configure name]=[configure opt]\fR will be echoed.
1274 @@ -968,14 +948,14 @@ myconf=$(use_with sdl SDL all\-plugins)
1275 .fi
1276 .RE
1277 .TP
1278 -\fBuse_enable\fR \fI<USE item>\fR \fI[configure name]\fR \fI[configure opt]\fR
1279 +.B use_enable\fR \fI<USE item>\fR \fI[configure name]\fR \fI[configure opt]
1280 Same as \fBuse_with\fR above, except that the configure options are
1281 \fI\-\-enable\-\fR instead of \fI\-\-with\-\fR and \fI\-\-disable\-\fR instead of
1282 \fI\-\-without\-\fR. Beginning with \fBEAPI 4\fR, an empty \fIconfigure opt\fR
1283 argument is recognized. In \fBEAPI 3\fR and earlier, an empty
1284 \fIconfigure opt\fR argument is treated as if it weren't provided.
1285 .TP
1286 -\fBhasv\fR \fI<item>\fR \fI<item list>\fR
1287 +.B hasv\fR \fI<item>\fR \fI<item list>
1288 If \fIitem\fR is in \fIitem list\fR, then \fIitem\fR is echoed and \fBhasv\fR
1289 returns 0. Otherwise, nothing is echoed and 1 is returned. As indicated with
1290 use, there is a non\-echoing version \fBhas\fR. Please use \fBhas\fR in all
1291 @@ -984,7 +964,7 @@ places where output is to be disregarded. Never use the output for calculation.
1292 The \fIitem list\fR is delimited by the \fIIFS\fR variable. This variable
1293 has a default value of ' ', or a space. It is a \fBbash\fR(1) setting.
1294 .TP
1295 -\fBhas_version\fR \fI[\-\-host\-root]\fR \fI<category/package\-version>\fR
1296 +.B has_version\fR \fI[\-\-host\-root]\fR \fI<category/package\-version>
1297 Check to see if \fIcategory/package\-version\fR is installed on the system.
1298 The parameter accepts all values that are acceptable in the \fBDEPEND\fR
1299 variable. The function returns 0 if \fIcategory/package\-version\fR is
1300 @@ -992,68 +972,69 @@ installed, 1 otherwise. Beginning with \fBEAPI 5\fR, the
1301 \-\-host\-root option may be used in order to cause the query
1302 to apply to the host root instead of ${ROOT}.
1303 .TP
1304 -\fBbest_version\fR \fI[\-\-host\-root]\fR \fI<package name>\fR
1305 +.B best_version\fR \fI[\-\-host\-root]\fR \fI<package name>
1306 This function will look up \fIpackage name\fR in the database of currently
1307 installed programs and echo the "best version" of the package that is
1308 currently installed. Beginning with \fBEAPI 5\fR, the
1309 \-\-host\-root option may be used in order to cause the query
1310 to apply to the host root instead of ${ROOT}.
1311 -.RS
1312 -.TP
1313 -.I Example:
1314 -VERINS="$(best_version net\-ftp/glftpd)"
1315 -.br
1316 -(VERINS now has the value "net\-ftp/glftpd\-1.27" if glftpd\-1.27 is installed)
1317 -.RE
1318 -.SH "HELPER FUNCTIONS: HOOKS"
1319 +
1320 +Example:
1321 +.nf
1322 + VERINS="$(best_version net\-ftp/glftpd)"
1323 + (VERINS now has the value "net\-ftp/glftpd\-1.27" if glftpd\-1.27 is installed)
1324 +.fi
1325 +
1326 +.SS "Hooks:"
1327 .TP
1328 -\fBregister_die_hook\fR \fI[list of function names]\fR
1329 +.B register_die_hook\fR \fI[list of function names]
1330 Register one or more functions to call when the ebuild fails for any reason,
1331 including file collisions with other packages.
1332 .TP
1333 -\fBregister_success_hook\fR \fI[list of function names]\fR
1334 +.B register_success_hook\fR \fI[list of function names]
1335 Register one or more functions to call when the ebuild builds and/or installs
1336 successfully.
1337 +
1338 +.SS "Output:"
1339 .TP
1340 -.RE
1341 -.SH "HELPER FUNCTIONS: OUTPUT"
1342 -.TP
1343 -\fBeinfo\fR \fI"disposable message"\fR
1344 +.B einfo\fR \fI"disposable message"
1345 Same as \fBelog\fR, but should be used when the message isn't important to the
1346 user (like progress or status messages during the build process).
1347 .TP
1348 -\fBelog\fR \fI"informative message"\fR
1349 +.B elog\fR \fI"informative message"
1350 If you need to display a message that you wish the user to read and take
1351 notice of, then use \fBelog\fR. It works just like \fBecho\fR(1), but
1352 adds a little more to the output so as to catch the user's eye. The message
1353 will also be logged by portage for later review.
1354 .TP
1355 -\fBewarn\fR \fI"warning message"\fR
1356 +.B ewarn\fR \fI"warning message"
1357 Same as \fBeinfo\fR, but should be used when showing a warning to the user.
1358 .TP
1359 -\fBeqawarn\fR \fI"QA warning message"\fR
1360 +.B eqawarn\fR \fI"QA warning message"
1361 Same as \fBeinfo\fR, but should be used when showing a QA warning to the user.
1362 .TP
1363 -\fBeerror\fR \fI"error message"\fR
1364 +.B eerror\fR \fI"error message"
1365 Same as \fBeinfo\fR, but should be used when showing an error to the user.
1366 .TP
1367 -\fBebegin\fR \fI"helpful message"\fR
1368 +.B ebegin\fR \fI"helpful message"
1369 Like \fBeinfo\fR, we output a \fIhelpful message\fR and then hint that the
1370 following operation may take some time to complete. Once the task is
1371 finished, you need to call \fBeend\fR.
1372 .TP
1373 -\fBeend\fR \fI<status>\fR \fI["error message"]\fR
1374 +.B eend\fR \fI<status>\fR \fI["error message"]
1375 Followup the \fBebegin\fR message with an appropriate "OK" or "!!" (for
1376 errors) marker. If \fIstatus\fR is non\-zero, then the additional \fIerror
1377 message\fR is displayed.
1378 -.SH "HELPER FUNCTIONS: UNPACK"
1379 +
1380 +.SS "Unpack:"
1381 .TP
1382 -\fBunpack\fR \fI<source>\fR \fI[list of more sources]\fR
1383 +.B unpack\fR \fI<source>\fR \fI[list of more sources]
1384 This function uncompresses and/or untars a list of sources into the current
1385 directory. The function will append \fIsource\fR to the \fBDISTDIR\fR variable.
1386 -.SH "HELPER FUNCTIONS: COMPILE"
1387 +
1388 +.SS "Compile:"
1389 .TP
1390 -\fBeconf\fR \fI[configure options]\fR
1391 +.B econf\fR \fI[configure options]
1392 This is used as a replacement for configure. Performs:
1393 .nf
1394 ${\fIECONF_SOURCE\fR:-.}/configure \\
1395 @@ -1085,20 +1066,21 @@ Beginning with \fBEAPI 5\fR, \fBeconf\fR adds
1396 string \fIdisable\-silent\-rules\fR occurs in the output
1397 of \fIconfigure \-\-help\fR.
1398 .TP
1399 -\fBemake\fR \fI[make options]\fR
1400 +.B emake\fR \fI[make options]
1401 This is used as a replacement for make. Performs 'make ${MAKEOPTS}
1402 \fImake options\fR' (as set in make.globals), default is MAKEOPTS="\-j2".
1403
1404 -\fB***warning***\fR
1405 +.B ***WARNING***
1406 .br
1407 if you are going to use \fBemake\fR, make sure your build is happy with
1408 parallel makes (make \-j2). It should be tested thoroughly as parallel
1409 makes are notorious for failing _sometimes_ but not always. If you determine
1410 that your package fails to build in parallel, and you are unable to resolve
1411 the issue, then you should run '\fBemake\fR \-j1' instead of 'make'.
1412 -.SH "HELPER FUNCTIONS: INSTALL"
1413 +
1414 +.SS "Install:"
1415 .TP
1416 -\fBeinstall\fR \fI[make options]\fR
1417 +.B einstall\fR \fI[make options]
1418 This is used as a replacement for make install. Performs:
1419 .nf
1420 make \\
1421 @@ -1155,11 +1137,11 @@ Strips all executable files of debugging symboles. This includes libraries.
1422 .RE
1423
1424 .TP
1425 -\fBprepinfo\fR \fI[dir]\fR
1426 +.B prepinfo\fR \fI[dir]
1427 .TP
1428 -\fBprepman\fR \fI[dir]\fR
1429 +.B prepman\fR \fI[dir]
1430 .TP
1431 -\fBprepstrip\fR \fI[dir]\fR
1432 +.B prepstrip\fR \fI[dir]
1433 .PD 1
1434 Similar to the \fBprepall\fR functions, these are subtle in their differences.
1435 .RS
1436 @@ -1181,7 +1163,7 @@ multiple directories.
1437 .RE
1438 .PD 1
1439 .TP
1440 -\fBdocompress\fR \fI[\-x] <path> [list of more paths]\fR
1441 +.B docompress\fR \fI[\-x] <path> [list of more paths]
1442 .RS
1443 Beginning with \fBEAPI 4\fR, the \fBdocompress\fR helper is used to
1444 manage lists of files to be included or excluded from optional compression.
1445 @@ -1220,7 +1202,7 @@ If the item does not exist, it is ignored.
1446 .RE
1447 .RE
1448 .TP
1449 -\fBdosed\fR \fI"s:orig:change:g" <filename>\fR
1450 +.B dosed\fR \fI"s:orig:change:g" <filename>
1451 Beginning with \fBEAPI 4\fR, the \fBdosed\fR helper no longer exists. Ebuilds
1452 should call \fBsed(1)\fR directly (and assume that it is GNU sed).
1453
1454 @@ -1231,66 +1213,66 @@ that this expression does \fBNOT\fR use the offset prefix.
1455 .BR 'dosed\ "s:/usr/local:/usr:g"\ /usr/bin/some\-script'
1456 runs sed on ${ED}/usr/bin/some\-script
1457 .TP
1458 -\fBdodir\fR \fI<path> [more paths]\fR
1459 +.B dodir\fR \fI<path> [more paths]
1460 Creates directories inside of ${ED}.
1461 .br
1462 .BR 'dodir\ /usr/lib/apache'
1463 creates ${ED}/usr/lib/apache. Note that the do* functions will run
1464 \fBdodir\fR for you.
1465 .TP
1466 -\fBdiropts\fR \fI[options for install(1)]\fR
1467 +.B diropts\fR \fI[options for install(1)]
1468 Can be used to define options for the install function used in
1469 \fBdodir\fR. The default is \fI\-m0755\fR.
1470 .TP
1471 -\fBinto\fR \fI<path>\fR
1472 +.B into\fR \fI<path>
1473 Sets the root (\fIDESTTREE\fR) for other functions like \fBdobin\fR,
1474 \fBdosbin\fR, \fBdoman\fR, \fBdoinfo\fR, \fBdolib\fR.
1475 .br
1476 The default root is /usr.
1477 .TP
1478 -\fBkeepdir\fR \fI<path> [more paths]\fR
1479 +.B keepdir\fR \fI<path> [more paths]
1480 Tells portage to leave directories behind even if they're empty. Functions
1481 the same as \fBdodir\fR.
1482 .TP
1483 -\fBdobin\fR \fI<binary> [list of more binaries]\fR
1484 +.B dobin\fR \fI<binary> [list of more binaries]
1485 Installs a \fIbinary\fR or a list of binaries into \fIDESTTREE\fR/bin.
1486 Creates all necessary dirs.
1487 .TP
1488 -\fBdosbin\fR \fI<binary> [list of more binaries]\fR
1489 +.B dosbin\fR \fI<binary> [list of more binaries]
1490 Installs a \fIbinary\fR or a list of binaries into \fIDESTTREE\fR/sbin.
1491 Creates all necessary dirs.
1492 .TP
1493 -\fBdoinitd\fR \fI<init.d script> [list of more init.d scripts]\fR
1494 +.B doinitd\fR \fI<init.d script> [list of more init.d scripts]
1495 Install Gentoo \fIinit.d scripts\fR. They will be installed into the
1496 correct location for Gentoo init.d scripts (/etc/init.d/). Creates all
1497 necessary dirs.
1498 .TP
1499 -\fBdoconfd\fR \fI<conf.d file> [list of more conf.d file]\fR
1500 +.B doconfd\fR \fI<conf.d file> [list of more conf.d file]
1501 Install Gentoo \fIconf.d files\fR. They will be installed into the
1502 correct location for Gentoo conf.d files (/etc/conf.d/). Creates all
1503 necessary dirs.
1504 .TP
1505 -\fBdoenvd\fR \fI<env.d entry> [list of more env.d entries]\fR
1506 +.B doenvd\fR \fI<env.d entry> [list of more env.d entries]
1507 Install Gentoo \fIenv.d entries\fR. They will be installed into the
1508 correct location for Gentoo env.d entries (/etc/env.d/). Creates all
1509 necessary dirs.
1510
1511 .PD 0
1512 .TP
1513 -\fBdolib\fR \fI<library>\fR \fI[list of more libraries]\fR
1514 +.B dolib\fR \fI<library>\fR \fI[list of more libraries]
1515 .TP
1516 -\fBdolib.a\fR \fI<library>\fR \fI[list of more libraries]\fR
1517 +.B dolib.a\fR \fI<library>\fR \fI[list of more libraries]
1518 .TP
1519 -\fBdolib.so\fR \fI<library>\fR \fI[list of more libraries]\fR
1520 +.B dolib.so\fR \fI<library>\fR \fI[list of more libraries]
1521 .PD 1
1522 Installs a library or a list of libraries into \fIDESTTREE\fR/lib.
1523 Creates all necessary dirs.
1524 .TP
1525 -\fBlibopts\fR \fI[options for install(1)]\fR
1526 +.B libopts\fR \fI[options for install(1)]
1527 Can be used to define options for the install function used in
1528 the \fBdolib\fR functions. The default is \fI\-m0644\fR.
1529 .TP
1530 -\fBdoman\fR \fI[\-i18n=<locale>]\fR \fI<man\-page> [list of more man\-pages]\fR
1531 +.B doman\fR \fI[\-i18n=<locale>]\fR \fI<man\-page> [list of more man\-pages]
1532 Installs manual\-pages into /usr/share/man/man[0\-9n] depending on the
1533 manual file ending. The files are compressed if they are not already. You
1534 can specify locale\-specific manpages with the \fI\-i18n\fR option. Then the
1535 @@ -1305,79 +1287,79 @@ the \fI\-i18n\fR option takes precedence over the locale suffix of the
1536 file name.
1537 .PD 0
1538 .TP
1539 -\fBdohard\fR \fI<filename> <linkname>\fR
1540 +.B dohard\fR \fI<filename> <linkname>
1541 Beginning with \fBEAPI 4\fR, the \fBdohard\fR helper no longer exists. Ebuilds
1542 should call \fBln(1)\fR directly.
1543 .TP
1544 -\fBdosym\fR \fI<filename> <linkname>\fR
1545 +.B dosym\fR \fI<filename> <linkname>
1546 .PD 1
1547 Performs the ln command to create a symlink.
1548 .TP
1549 -\fBdoheader\fR \fI[\-r] <file> [list of more files]\fR
1550 +.B doheader\fR \fI[\-r] <file> [list of more files]
1551 Installs the given header files into /usr/include/, by default
1552 with file mode \fI0644\fR (this can be overridden with the
1553 \fBinsopts\fR function). Setting \-r sets recursive. The
1554 \fBdoheader\fR helper is available beginning with \fBEAPI 5\fR.
1555 .TP
1556 -\fBdohtml\fR \fI [\-a filetypes] [\-r] [\-x list\-of\-dirs\-to\-ignore] [list\-of\-files\-and\-dirs]\fR
1557 +.B dohtml\fR \fI [\-a filetypes] [\-r] [\-x list\-of\-dirs\-to\-ignore] [list\-of\-files\-and\-dirs]
1558 Installs the files in the list of files (space\-separated list) into
1559 /usr/share/doc/${PF}/html provided the file ends in .htm, .html, .css, .js, .gif, .jpeg, .jpg, or .png.
1560 Setting \fI\-a\fR limits what types of files will be included,
1561 \fI\-A\fR appends to the default list, setting \fI\-x\fR sets which dirs to
1562 exclude (CVS excluded by default), \fI\-p\fR sets a document prefix, \fI\-r\fR sets recursive.
1563 .TP
1564 -\fBdoinfo\fR \fI<info\-file> [list of more info\-files]\fR
1565 +.B doinfo\fR \fI<info\-file> [list of more info\-files]
1566 Installs info\-pages into \fIDESTDIR\fR/info. Files are automatically
1567 gzipped. Creates all necessary dirs.
1568 .TP
1569 -\fBdomo\fR \fI<locale\-file> [list of more locale\-files] \fR
1570 +.B domo\fR \fI<locale\-file> [list of more locale\-files]
1571 Installs locale\-files into \fIDESTDIR\fR/usr/share/locale/[LANG]
1572 depending on local\-file's ending. Creates all necessary dirs.
1573
1574 .PD 0
1575 .TP
1576 -\fBfowners\fR \fI<permissions> <file> [files]\fR
1577 +.B fowners\fR \fI<permissions> <file> [files]
1578 .TP
1579 -\fBfperms\fR \fI<permissions> <file> [files]\fR
1580 +.B fperms\fR \fI<permissions> <file> [files]
1581 .PD 1
1582 Performs chown (\fBfowners\fR) or chmod (\fBfperms\fR), applying
1583 \fIpermissions\fR to \fIfiles\fR.
1584 .TP
1585 -\fBinsinto\fR \fI[path]\fR
1586 +.B insinto\fR \fI[path]
1587 Sets the destination path for the \fBdoins\fR function.
1588 .br
1589 The default path is /.
1590 .TP
1591 -\fBinsopts\fR \fI[options for install(1)]\fR
1592 +.B insopts\fR \fI[options for install(1)]
1593 Can be used to define options for the install function used in
1594 \fBdoins\fR. The default is \fI\-m0644\fR.
1595 .TP
1596 -\fBdoins\fR \fI[\-r] <file> [list of more files]\fR
1597 +.B doins\fR \fI[\-r] <file> [list of more files]
1598 Installs files into the path controlled by \fBinsinto\fR. This function
1599 uses \fBinstall\fR(1). Creates all necessary dirs.
1600 Setting \-r sets recursive. Beginning with \fBEAPI 4\fR, both
1601 \fBdoins\fR and \fBnewins\fR preserve symlinks. In \fBEAPI 3\fR and
1602 earlier, symlinks are dereferenced rather than preserved.
1603 .TP
1604 -\fBexeinto\fR \fI[path]\fR
1605 +.B exeinto\fR \fI[path]
1606 Sets the destination path for the \fBdoexe\fR function.
1607 .br
1608 The default path is /.
1609 .TP
1610 -\fBexeopts\fR \fI[options for install(1)]\fR
1611 +.B exeopts\fR \fI[options for install(1)]
1612 Can be used to define options for the install function used in \fBdoexe\fR.
1613 The default is \fI\-m0755\fR.
1614 .TP
1615 -\fBdoexe\fR \fI<executable> [list of more executables]\fR
1616 +.B doexe\fR \fI<executable> [list of more executables]
1617 Installs executables into the path controlled by \fBexeinto\fR. This function
1618 uses \fBinstall\fR(1). Creates all necessary dirs.
1619 .TP
1620 -\fBdocinto\fR \fI[path]\fR
1621 +.B docinto\fR \fI[path]
1622 Sets the subdir used by \fBdodoc\fR and \fBdohtml\fR
1623 when installing into the document tree
1624 (based in /usr/share/doc/${PF}/). Default is no subdir, or just "".
1625 .TP
1626 -\fBdodoc\fR \fI[-r] <document> [list of more documents]\fR
1627 +.B dodoc\fR \fI[-r] <document> [list of more documents]
1628 Installs a document or a list of documents into /usr/share/doc/${PF}/\fI<docinto path>\fR.
1629 Documents are marked for compression. Creates all necessary dirs.
1630 Beginning with \fBEAPI 4\fR, there is support for recursion, enabled by the
1631 @@ -1385,45 +1367,70 @@ new \fI\-r\fR option.
1632
1633 .PD 0
1634 .TP
1635 -\fBnewbin\fR \fI<old file> <new filename>\fR
1636 +.B newbin\fR \fI<old file> <new filename>
1637 .TP
1638 -\fBnewsbin\fR \fI<old file> <new filename>\fR
1639 +.B newsbin\fR \fI<old file> <new filename>
1640 .TP
1641 -\fBnewinitd\fR \fI<old file> <new filename>\fR
1642 +.B newinitd\fR \fI<old file> <new filename>
1643 .TP
1644 -\fBnewconfd\fR \fI<old file> <new filename>\fR
1645 +.B newconfd\fR \fI<old file> <new filename>
1646 .TP
1647 -\fBnewenvd\fR \fI<old file> <new filename>\fR
1648 +.B newenvd\fR \fI<old file> <new filename>
1649 .TP
1650 -\fBnewlib.so\fR \fI<old file> <new filename>\fR
1651 +.B newlib.so\fR \fI<old file> <new filename>
1652 .TP
1653 -\fBnewlib.a\fR \fI<old file> <new filename>\fR
1654 +.B newlib.a\fR \fI<old file> <new filename>
1655 .TP
1656 -\fBnewman\fR \fI<old file> <new filename>\fR
1657 +.B newman\fR \fI<old file> <new filename>
1658 .TP
1659 -\fBnewinfo\fR \fI<old file> <new filename>\fR
1660 +.B newinfo\fR \fI<old file> <new filename>
1661 .TP
1662 -\fBnewins\fR \fI<old file> <new filename>\fR
1663 +.B newins\fR \fI<old file> <new filename>
1664 .TP
1665 -\fBnewexe\fR \fI<old file> <new filename>\fR
1666 +.B newexe\fR \fI<old file> <new filename>
1667 .TP
1668 -\fBnewdoc\fR \fI<old file> <new filename>\fR
1669 +.B newdoc\fR \fI<old file> <new filename>
1670 .PD 1
1671 All these functions act like the do* functions, but they only work with one
1672 file and the file is installed as \fI[new filename]\fR.
1673 Beginning with \fBEAPI 5\fR, standard input is read when the
1674 first parameter is \- (a hyphen).
1675 -.SH "REPORTING BUGS"
1676 -Please report bugs via http://bugs.gentoo.org/
1677 -.SH "AUTHORS"
1678 +
1679 +.SH "EXAMPLES"
1680 +.DS
1681 .nf
1682 -Achim Gottinger <achim@g.o>
1683 -Mark Guertin <gerk@g.o>
1684 -Nicholas Jones <carpaski@g.o>
1685 -Mike Frysinger <vapier@g.o>
1686 -Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA@×××××.com>
1687 -Fabian Groffen <grobian@g.o>
1688 +# Copyright 1999\-2009 Gentoo Foundation
1689 +# Distributed under the terms of the GNU General Public License v2
1690 +# $Header: $
1691 +
1692 +EAPI="5"
1693 +
1694 +inherit some_eclass another_eclass
1695 +
1696 +DESCRIPTION="Super\-useful stream editor (sed)"
1697 +HOMEPAGE="http://www.gnu.org/software/sed/sed.html"
1698 +SRC_URI="ftp://alpha.gnu.org/pub/gnu/${PN}/${P}.tar.gz"
1699 +
1700 +LICENSE="GPL\-2"
1701 +SLOT="0"
1702 +KEYWORDS="~x86"
1703 +IUSE=""
1704 +
1705 +RDEPEND=""
1706 +DEPEND="nls? ( sys-devel/gettext )"
1707 +
1708 +src_configure() {
1709 + econf \\
1710 + \-\-bindir="${EPREFIX}"/bin
1711 +}
1712 +
1713 +src_install() {
1714 + emake DESTDIR="${D}" install
1715 + dodoc NEWS README* THANKS AUTHORS BUGS ChangeLog
1716 +}
1717 .fi
1718 +.DE
1719 +
1720 .SH "FILES"
1721 .TP
1722 The \fI/usr/sbin/ebuild.sh\fR script.
1723 @@ -1439,7 +1446,21 @@ Contains the default variables for the build\-process, you should edit
1724 .TP
1725 .B /etc/portage/color.map
1726 Contains variables customizing colors.
1727 +
1728 .SH "SEE ALSO"
1729 .BR ebuild (1),
1730 .BR make.conf (5),
1731 .BR color.map (5)
1732 +
1733 +.SH "REPORTING BUGS"
1734 +Please report bugs via http://bugs.gentoo.org/
1735 +
1736 +.SH "AUTHORS"
1737 +.nf
1738 +Achim Gottinger <achim@g.o>
1739 +Mark Guertin <gerk@g.o>
1740 +Nicholas Jones <carpaski@g.o>
1741 +Mike Frysinger <vapier@g.o>
1742 +Arfrever Frehtes Taifersar Arahesis <Arfrever.FTA@×××××.com>
1743 +Fabian Groffen <grobian@g.o>
1744 +.fi
1745 --
1746 1.7.12