Get Gentoo!
gentoo.org sites
gentoo.org Wiki Bugs Forums Packages
Planet Archives Sources
Infra Status

Gentoo Archives: gentoo-commits

From: "Ulrich Müller" <ulm@g.o>
To: gentoo-commits@l.g.o
Subject: [gentoo-commits] proj/devmanual:master commit in: function-reference/, ebuild-writing/functions/src_configure/configuring/, ...
Date: Tue, 11 Feb 2020 13:15:49
Message-Id: 1581421080.3b8fa72d91bbdd08aa08f7e7bf0ca66833095186.ulm@gentoo
1 commit: 3b8fa72d91bbdd08aa08f7e7bf0ca66833095186
2 Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
3 AuthorDate: Sat Feb 8 19:43:23 2020 +0000
4 Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
5 CommitDate: Tue Feb 11 11:38:00 2020 +0000
6 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=3b8fa72d
7
8 ebuild-writing/eapi: Move EAPI=4 information to other sections.
9
10 - Utilities die, nonfatal: New section in ebuild-writing/error-handling,
11 new chapter function-reference/error-functions
12 - dodoc -r: Already in function-reference/install-functions,
13 add additional example to ebuild-writing/functions/src_install
14 - doins symlink support:
15 Incorporated into function-reference/install-functions
16 - dosed, dohard banned: Not mentioned anywhere else
17 - econf --disable-dependency-tracking: New section about econf options
18 in ebuild-writing/functions/src_configure/configuring
19 - Controllable compression and docompress:
20 New chapter ebuild-writing/functions/src_install/docompress
21
22 - USE dependency defaults: Incorporated into general-concepts/dependencies
23
24 - pkg_pretend: Already in ebuild-writing/functions/pkg_pretend
25 - default src_install: Already in ebuild-writing/functions/src_install
26 - pkg_info: Incorporated into ebuild-writing/functions/pkg_info
27
28 - REQUIRED_USE: Already in ebuild-writing/variables
29 - MERGE_TYPE, REPLACING_VERSIONS, REPLACED_BY_VERSION:
30 Moved to ebuild-writing/variables
31 - DOCS: Incorporated into ebuild-writing/variables
32 - AA, KV removed: Not mentioned anywhere else
33 - RDEPEND=DEPEND: Already handled in commit 5a946b4
34
35 Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
36
37 ebuild-writing/eapi/text.xml | 333 +--------------------
38 ebuild-writing/error-handling/text.xml | 32 +-
39 ebuild-writing/functions/pkg_info/text.xml | 16 +-
40 ebuild-writing/functions/pkg_pretend/text.xml | 2 +-
41 .../functions/src_configure/configuring/text.xml | 51 ++++
42 .../functions/src_install/docompress/text.xml | 51 ++++
43 ebuild-writing/functions/src_install/text.xml | 25 +-
44 ebuild-writing/functions/text.xml | 2 +-
45 ebuild-writing/variables/text.xml | 44 ++-
46 function-reference/build-functions/text.xml | 5 +-
47 function-reference/error-functions/text.xml | 50 ++++
48 function-reference/install-functions/text.xml | 14 +-
49 function-reference/text.xml | 1 +
50 general-concepts/dependencies/text.xml | 20 +-
51 general-concepts/use-flags/text.xml | 8 +-
52 general-concepts/virtuals/text.xml | 2 +-
53 16 files changed, 291 insertions(+), 365 deletions(-)
54
55 diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
56 index 2a47617..57c899e 100644
57 --- a/ebuild-writing/eapi/text.xml
58 +++ b/ebuild-writing/eapi/text.xml
59 @@ -65,346 +65,17 @@ is the best. Using the features of the latest EAPI is encouraged.
60 </section>
61
62 <section>
63 -<title>EAPIs 0 to 3</title>
64 +<title>EAPIs 0 to 4</title>
65 <body>
66
67 <p>
68 -EAPIs 0 to 3 are obsolete and must no longer be used. Refer to the Package
69 +EAPIs 0 to 4 are obsolete and must no longer be used. Refer to the Package
70 Manager Specification for details about them.
71 </p>
72
73 </body>
74 </section>
75
76 -<section>
77 -<title>EAPI=4</title>
78 -<body>
79 -
80 -<todo>
81 -Split up and move each feature to the section that is relevant for it.
82 -</todo>
83 -
84 -</body>
85 -
86 -<subsection>
87 -<title>EAPI 4 Helpers</title>
88 -<body>
89 -<ul>
90 - <li>
91 - <p><b>utilities die on their own, unless the nonfatal command is used</b></p>
92 - <p>
93 - <!-- TODO link auf fuunction-reference -->
94 - Ebuild functions all die on their own in EAPI=4. In case that this
95 - non-zero exit status is expected, you may call <c>nonfatal function
96 - [arg,...]</c>.
97 - </p>
98 - <p>Example:</p>
99 -<codesample lang="ebuild">
100 -EAPI=2
101 -...
102 -src_test() {
103 - if ! emake check ; then
104 - local a
105 - eerror "Tests failed. Looking for files for you to add to your bug report..."
106 - while IFS='' read -r -d $'\0' a ; do
107 - eerror " ${a}"
108 - done &lt; &lt;(find "${S}" -type f '(' -name '*.epicfail' -o -name '*.log' ')' -print0)
109 - die "Make check failed"
110 - fi
111 -}
112 -</codesample>
113 -<codesample lang="ebuild">
114 -EAPI=4
115 -...
116 -src_test() {
117 - if ! nonfatal emake check ; then
118 - local a
119 - eerror "Tests failed. Looking for files for you to add to your bug report..."
120 - while IFS='' read -r -d $'\0' a ; do
121 - eerror " ${a}"
122 - done &lt; &lt;(find "${S}" -type f '(' -name '*.epicfail' -o -name '*.log' ')' -print0)
123 - die "Make check failed"
124 - fi
125 -}
126 -</codesample>
127 - </li>
128 - <li>
129 - <p><b>recursive dodoc</b></p>
130 - <p>
131 - <c>dodoc</c> supports <c>-r</c> as the first argument, which leads
132 - <c>dodoc</c> to install the specified documentation directory
133 - recursively into the docdir.
134 - </p>
135 - <p>Example:</p>
136 -<codesample lang="ebuild">
137 -src_install() {
138 - default
139 - dodoc ChangeLog
140 - dodoc -r doc/
141 -}
142 -</codesample>
143 - </li>
144 - <li>
145 - <p><b>doins symlink supports</b></p>
146 - <p>
147 - Within EAPI=4, <c>doins</c> supports installing symlinks as symlinks
148 - when installing recursively. For older EAPIs, the symlink behaviour
149 - is undefined.
150 - </p>
151 - </li>
152 - <li>
153 - <p><b>dosed and dohard are banned</b></p>
154 - <p>
155 - The <c>dosed</c> and <c>dohard</c> commands are banned in this EAPI.
156 - </p>
157 - </li>
158 - <li>
159 - <p><b>econf adds --disable-dependency-tracking</b></p>
160 - <p>
161 - Within EAPI=4, <c>econf</c> adds
162 - <c>--disable-dependency-tracking</c> to the default configure
163 - options.
164 - </p>
165 - </li>
166 - <li>
167 - <p><b>controllable compression via docompress</b></p>
168 - <p>
169 - To compress files in the destination-folder <c>${D}</c>, the
170 - <c>docompress</c> command may be used in <c>src_install</c>.
171 - To control which items should be compressed and which shouldn't
172 - be compressed, you may include or exclude directories or plain
173 - files. The default inclusion list contains:
174 - </p>
175 - <ul>
176 - <li><c>/usr/share/doc</c></li>
177 - <li><c>/usr/share/info</c></li>
178 - <li><c>/usr/share/man</c></li>
179 - </ul>
180 - <p>
181 - The default exclusion list contains:
182 - </p>
183 - <ul>
184 - <li><c>/usr/share/doc/${PF}/html</c></li>
185 - </ul>
186 - <p>
187 - When a directory is in- or excluded, all files and directories in
188 - the given directories shall be added to the corresponding list.
189 - If a file is in- or excluded, the file shall be added to the
190 - corresponding list (exclusion is stronger than inclusion <d/>
191 - if a file is in both lists, the inclusion will be ignored).
192 - </p>
193 - <p>
194 - If the first argument of <c>docompress</c> is <c>-x</c>, the items
195 - specified will be added to the exclusion list, otherwise they will
196 - be added to the inclusion list.
197 - </p>
198 - <note>
199 - When <c>docompress</c> is called, it is <e>not</e> required that
200 - the paths specified as its arguments are pointing to existing files
201 - or directories. However, if a file still doesn't exist when
202 - <c>src_install</c> has completed, it will be ignored with a
203 - warning.
204 - </note>
205 - </li>
206 -</ul>
207 -</body>
208 -</subsection>
209 -
210 -<subsection>
211 -<title>EAPI 4 Metadata</title>
212 -<body>
213 -<ul>
214 - <li>
215 - <p><b>use dependencies default</b></p>
216 - <p>
217 - In addition to the use-deps specified in EAPI=2, a <c>(+)</c> or
218 - <c>(-)</c> may be added to the use-dep to define a default-value in
219 - case the use-flag does not exist in the given package. The
220 - <c>(+)</c> means that this use-flag is assumed to be enabled,
221 - <c>(-)</c> the opposite.
222 - </p>
223 - <p>Example:</p>
224 -<codesample lang="ebuild">
225 -DEPEND="
226 - >=dev-libs/boost-1.32[boost(+)]
227 - sys-devel/gcc[openmp(-)]"
228 -</codesample>
229 - </li>
230 -</ul>
231 -</body>
232 -</subsection>
233 -
234 -<subsection>
235 -<title>EAPI 4 Phases</title>
236 -<body>
237 -<ul>
238 - <li>
239 - <p><b>new pkg_pretend phase</b></p>
240 - <p>
241 - The new <c>pkg_pretend</c> phase can be used to do sanity checks
242 - before the main phase function sequence is run (meaning this phase is
243 - executed after the package manager has calculated the dependencies
244 - and before installing them).
245 - This phase typically checks for a kernel configuration and may
246 - <c>eerror</c> and <c>die</c> when needed.
247 - </p>
248 - <important>
249 - There is no guarantee that the ebuild's dependencies are installed
250 - when this phase is called.
251 - </important>
252 - <important>
253 - As <c>pkg_pretend</c> is not called in the main phase function
254 - sequence, environment saving is not guaranteed.
255 - </important>
256 - <p>Example:</p>
257 -<codesample lang="ebuild">
258 -# Copyright 1999-2020 Gentoo Authors
259 -# Distributed under the terms of the GNU General Public License v2
260 -
261 -EAPI=4
262 -inherit linux-info
263 -...
264 -
265 -CONFIG_CHECK="FUSE_FS"
266 -ERROR_FUSE_FS="this is an unrealistic testcase..."
267 -
268 -pkg_pretend() {
269 - if use kernel_linux ; then
270 - if [[ -e "${ROOT}"/usr/src/linux/.config ]] ; then
271 - if kernel_is lt 2 6 30 ; then
272 - check_extra_config
273 - fi
274 - fi
275 - fi
276 -}
277 -</codesample>
278 - </li>
279 - <li>
280 - <p><b>default src_install is no longer a no-op</b></p>
281 - <p>
282 - The default <c>src_install</c> function in EAPI=4:
283 - </p>
284 -<codesample lang="ebuild">
285 -src_install() {
286 - if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then
287 - emake DESTDIR="${D}" install
288 - fi
289 -
290 - if ! declare -p DOCS >/dev/null 2>&amp;1 ; then
291 - local d
292 - for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \
293 - FAQ CREDITS CHANGELOG ; do
294 - [[ -s "${d}" ]] &amp;&amp; dodoc "${d}"
295 - done
296 - elif declare -p DOCS | grep -q "^declare -a " ; then
297 - dodoc "${DOCS[@]}"
298 - else
299 - dodoc ${DOCS}
300 - fi
301 -}
302 -</codesample>
303 - </li>
304 - <li>
305 - <p><b>pkg_info for non-installed packages</b></p>
306 - <p>
307 - The <c>pkg_info</c> function may also be called by the
308 - package manager for non-installed packages.
309 - Ebuild writers should note that dependencies may not be
310 - available.
311 - </p>
312 - </li>
313 -</ul>
314 -</body>
315 -</subsection>
316 -
317 -<subsection>
318 -<title>EAPI 4 Variables</title>
319 -<body>
320 -<ul>
321 - <li>
322 - <p><b>REQUIRED_USE</b></p>
323 - <p>
324 - The <c>REQUIRED_USE</c> variable contains a list of assertions that
325 - must be met by the configuration of USE flags to be valid for this
326 - ebuild. In order to be matched, a USE flag in a terminal element
327 - must be enabled (or disabled if it has an exclamation mark prefix).
328 - </p>
329 - <p>
330 - See <uri link="::ebuild-writing/variables#REQUIRED_USE"/>
331 - </p>
332 - </li>
333 - <li>
334 - <p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p>
335 - <p>
336 - The <c>REPLACING_VERSIONS</c> variable contains a
337 - whitespace-separated list of all versions (<c>PVR</c>) of this
338 - package that are being replaced (uninstalled or overwritten) as a
339 - result of this install. It is a list, not a single optional value,
340 - to handle pathological cases such as installing <c>foo-2:2</c> to
341 - replace <c>foo-2:1</c> and <c>foo-3:2</c>.
342 - </p>
343 - <p>
344 - <c>REPLACING_VERSIONS</c> is valid in <c>pkg_preinst</c> and
345 - <c>pkg_postinst</c>. In addition, it may be available in
346 - <c>pkg_pretend</c> and <c>pkg_setup</c>, although you should take
347 - care to handle binary package creation and installation correctly
348 - when using it in these phases.
349 - </p>
350 - <p>
351 - The <c>REPLACED_BY_VERSION</c> variable contains the single version
352 - (<c>PVR</c>) of this package that is replacing us, if we are being
353 - uninstalled as part of an install, or an empty string otherwise.
354 - It is valid in <c>pkg_prerm</c> and <c>pkg_postrm</c>.
355 - </p>
356 - </li>
357 - <li>
358 - <p><b>MERGE_TYPE</b></p>
359 - <p>
360 - The <c>MERGE_TYPE</c> variable contains the type of package that
361 - is being merged. Possible values are:
362 - </p>
363 - <dl>
364 - <dt><c>source</c></dt>
365 - <dd>
366 - if building and installing a package from source,
367 - </dd>
368 - <dt><c>binary</c></dt>
369 - <dd>
370 - if installing a binary package,
371 - </dd>
372 - <dt><c>buildonly</c></dt>
373 - <dd>
374 - if building a binary package without installing it.
375 - </dd>
376 - </dl>
377 - </li>
378 - <li>
379 - <p><b>DOCS</b></p>
380 - <p>
381 - The <c>DOCS</c> variable is an array or whitespace-separated list
382 - of documentation files for the default <c>src_install</c> function
383 - to install using <c>dodoc</c>. If undefined, a reasonable default
384 - list is used. See the default <c>src_install</c> function above.
385 - </p>
386 - </li>
387 - <li>
388 - <p><b>AA and KV variables are gone</b></p>
389 - <p>
390 - The <c>AA</c> and <c>KV</c> variables are no longer set in EAPI=4.
391 - </p>
392 - </li>
393 - <li>
394 - <p><b>no more RDEPEND="${DEPEND}"</b></p>
395 - <p>
396 - When <c>RDEPEND</c> is unset, there will no longer be an automatic
397 - assignment of <c>RDEPEND="${DEPEND}"</c>.
398 - </p>
399 - </li>
400 -</ul>
401 -</body>
402 -</subsection>
403 -</section>
404 -
405 <section>
406 <title>EAPI=5</title>
407
408
409 diff --git a/ebuild-writing/error-handling/text.xml b/ebuild-writing/error-handling/text.xml
410 index 35c7419..f74f6d8 100644
411 --- a/ebuild-writing/error-handling/text.xml
412 +++ b/ebuild-writing/error-handling/text.xml
413 @@ -47,10 +47,9 @@ function can die in multiple places.
414 </p>
415
416 <p>
417 -Ebuild helpers from EAPI 4 and onwards automatically die on
418 -failure. Some eclass-provided functions will automatically die upon
419 -failure, others will not. Developers should check the
420 -<uri link="::eclass-reference/">eclass reference</uri> when in doubt.
421 +Ebuild helpers automatically die on failure. Some eclass-provided functions
422 +will automatically die upon failure, others will not. Developers should check
423 +the <uri link="::eclass-reference/">eclass reference</uri> when in doubt.
424 </p>
425
426 <p>
427 @@ -135,5 +134,30 @@ time, <c>assert</c> is enough.
428 </body>
429 </section>
430
431 +<section>
432 +<title>The <c>nonfatal</c> Command</title>
433 +<body>
434 +
435 +<p>
436 +If a non-zero exit status from an ebuild helper function is expected, you may
437 +call it under the <c>nonfatal</c> function. Instead of dying on failure,
438 +the command will then return non-zero exit status, as in the following example:
439 +</p>
440 +
441 +<codesample lang="ebuild">
442 +src_test() {
443 + if ! nonfatal emake check ; then
444 + local a
445 + eerror "Tests failed. Looking for files to add to your bug report..."
446 + while IFS='' read -r -d $'\0' a ; do
447 + eerror " ${a}"
448 + done &lt; &lt;(find "${S}" -type f -name '*.log' -print0)
449 + die "Make check failed"
450 + fi
451 +}
452 +</codesample>
453 +
454 +</body>
455 +</section>
456 </chapter>
457 </guide>
458
459 diff --git a/ebuild-writing/functions/pkg_info/text.xml b/ebuild-writing/functions/pkg_info/text.xml
460 index 8cb3dbb..c6e0432 100644
461 --- a/ebuild-writing/functions/pkg_info/text.xml
462 +++ b/ebuild-writing/functions/pkg_info/text.xml
463 @@ -54,15 +54,19 @@ pkg_info() {
464 <section>
465 <title>Notes on <c>pkg_info</c></title>
466 <body>
467 +
468 +<p>
469 +This phase will be called when a package manager displays information about
470 +a package.
471 +</p>
472 +
473 <p>
474 -this phase will be called when a package manager displays
475 -information about a package.
476 -within EAPI=4, this phase can also be called for non-installed
477 -packages.
478 +The <c>pkg_info</c> function may also be called by the package manager for
479 +non-installed packages. Ebuild writers should note that dependencies may not be
480 +available.
481 </p>
482 +
483 </body>
484 </section>
485 -
486 </chapter>
487 </guide>
488 -
489
490 diff --git a/ebuild-writing/functions/pkg_pretend/text.xml b/ebuild-writing/functions/pkg_pretend/text.xml
491 index e21a1c2..89eb269 100644
492 --- a/ebuild-writing/functions/pkg_pretend/text.xml
493 +++ b/ebuild-writing/functions/pkg_pretend/text.xml
494 @@ -67,7 +67,7 @@ pkg_pretend() {
495 <title>Notes on <c>pkg_pretend</c></title>
496 <body>
497 <p>
498 -the <c>pkg_pretend</c> phase can be used to do sanity checks
499 +The <c>pkg_pretend</c> phase can be used to do sanity checks
500 before the main phase function sequence is run (meaning this phase is
501 executed after the package manager has calculated the dependencies
502 and before installing them).
503
504 diff --git a/ebuild-writing/functions/src_configure/configuring/text.xml b/ebuild-writing/functions/src_configure/configuring/text.xml
505 index a31dc4e..86657bc 100644
506 --- a/ebuild-writing/functions/src_configure/configuring/text.xml
507 +++ b/ebuild-writing/functions/src_configure/configuring/text.xml
508 @@ -74,5 +74,56 @@ form can be used.
509 </p>
510 </body>
511
512 +<section>
513 +<title><c>econf</c> Options</title>
514 +<body>
515 +
516 +<p>
517 +<c>econf</c> is designed to work with configure scripts generated by
518 +GNU Autoconf. It first passes the default options listed below to the configure
519 +script, followed by any additional parameters passed to <c>econf</c>.
520 +</p>
521 +
522 +<ul>
523 + <li><c>--prefix="${EPREFIX}"/usr</c></li>
524 + <li><c>--mandir="${EPREFIX}"/usr/share/man</c></li>
525 + <li><c>--infodir="${EPREFIX}"/usr/share/info</c></li>
526 + <li><c>--datadir="${EPREFIX}"/usr/share</c></li>
527 + <li><c>--sysconfdir="${EPREFIX}"/etc</c></li>
528 + <li><c>--localstatedir="${EPREFIX}"/var/lib</c></li>
529 + <li>
530 + <c>--build="${CBUILD}"</c> (only passed if <c>CBUILD</c> is non-empty)
531 + </li>
532 + <li><c>--host="${CHOST}"</c></li>
533 + <li>
534 + <c>--target="${CTARGET}"</c> (only passed if <c>CTARGET</c> is non-empty)
535 + </li>
536 + <li>
537 + <c>--libdir</c> is set from the value of the <c>LIBDIR_${ABI}</c> variable
538 + in profiles.
539 + </li>
540 + <li><c>--disable-dependency-tracking</c></li>
541 + <li><c>--disable-silent-rules</c></li>
542 +</ul>
543 +
544 +<p>
545 +In EAPI 6 and later, the following options are passed in addition:
546 +</p>
547 +
548 +<ul>
549 + <li><c>--docdir="${EPREFIX}"/usr/share/doc/${PF}</c></li>
550 + <li><c>--htmldir="${EPREFIX}"/usr/share/doc/${PF}/html</c></li>
551 +</ul>
552 +
553 +<p>
554 +In EAPI 7 and later, the following option is passed in addition:
555 +</p>
556 +
557 +<ul>
558 + <li><c>--with-sysroot="${ESYSROOT:-/}"</c></li>
559 +</ul>
560 +
561 +</body>
562 +</section>
563 </chapter>
564 </guide>
565
566 diff --git a/ebuild-writing/functions/src_install/docompress/text.xml b/ebuild-writing/functions/src_install/docompress/text.xml
567 new file mode 100644
568 index 0000000..93478b4
569 --- /dev/null
570 +++ b/ebuild-writing/functions/src_install/docompress/text.xml
571 @@ -0,0 +1,51 @@
572 +<?xml version="1.0"?>
573 +<guide self="ebuild-writing/functions/src_install/docompress/">
574 +<chapter>
575 +<title>Controllable Compression</title>
576 +<body>
577 +
578 +<p>
579 +You can call the <c>docompress</c> function in <c>src_install</c> to control
580 +which items in the destination folder <c>${D}</c> should be compressed and
581 +which shouldn't be compressed. You can include or exclude directories or plain
582 +files. The default inclusion list contains:
583 +</p>
584 +
585 +<ul>
586 + <li><c>/usr/share/doc</c></li>
587 + <li><c>/usr/share/info</c></li>
588 + <li><c>/usr/share/man</c></li>
589 +</ul>
590 +
591 +<p>
592 +The default exclusion list contains:
593 +</p>
594 +
595 +<ul>
596 + <li><c>/usr/share/doc/${PF}/html</c></li>
597 +</ul>
598 +
599 +<p>
600 +When a directory is in- or excluded, all files and directories in the given
601 +directories shall be added to the corresponding list. If a file is in- or
602 +excluded, the file shall be added to the corresponding list (exclusion is
603 +stronger than inclusion <d/> if a file is in both lists, the inclusion will
604 +be ignored).
605 +</p>
606 +
607 +<p>
608 +If the first argument of <c>docompress</c> is <c>-x</c>, the items specified
609 +will be added to the exclusion list, otherwise they will be added to the
610 +inclusion list.
611 +</p>
612 +
613 +<note>
614 +When <c>docompress</c> is called, it is <e>not</e> required that the paths
615 +specified as its arguments are pointing to existing files or directories.
616 +However, if a file still doesn't exist when <c>src_install</c> has completed,
617 +it will be ignored with a warning.
618 +</note>
619 +
620 +</body>
621 +</chapter>
622 +</guide>
623
624 diff --git a/ebuild-writing/functions/src_install/text.xml b/ebuild-writing/functions/src_install/text.xml
625 index 02981ff..010638b 100644
626 --- a/ebuild-writing/functions/src_install/text.xml
627 +++ b/ebuild-writing/functions/src_install/text.xml
628 @@ -109,10 +109,16 @@ Usually the package's build system will not install the <c>README</c>,
629 </p>
630
631 <codesample lang="ebuild">
632 - emake DESTDIR="${D}" install
633 - dodoc README CHANGES
634 + emake DESTDIR="${D}" install
635 + dodoc README CHANGES
636 + dodoc -r doc
637 </codesample>
638
639 +<p>
640 +<c>dodoc</c> supports <c>-r</c> as the first argument, which allows directories
641 +to be installed recursively.
642 +</p>
643 +
644 <note>
645 There is no need to <c>dodoc</c> <c>COPYING</c>! The license belongs
646 to <c>${PORTDIR}/licenses</c>. Sometimes though, you might want to
647 @@ -215,5 +221,20 @@ upstream explaining the situation to them.
648 </body>
649 </section>
650
651 +<section>
652 +<title><c>src_install</c> Processes</title>
653 +<body>
654 +
655 +<p>
656 +The following subsections cover different topics which often occur when writing
657 +<c>src_install</c> functions.
658 +</p>
659 +
660 +<contentsTree/>
661 +
662 +</body>
663 +</section>
664 </chapter>
665 +
666 +<include href="docompress/"/>
667 </guide>
668
669 diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml
670 index e2167e6..3899aca 100644
671 --- a/ebuild-writing/functions/text.xml
672 +++ b/ebuild-writing/functions/text.xml
673 @@ -6,7 +6,7 @@
674 <body>
675 <p>
676 When installing packages from source, the function call order is
677 -<c>pkg_pretend</c> (for EAPI=4 and later), <c>pkg_setup</c>,
678 +<c>pkg_pretend</c>, <c>pkg_setup</c>,
679 <c>src_unpack</c>, <c>src_prepare</c>, <c>src_configure</c>, <c>src_compile</c>,
680 <c>src_test</c> (optional, <c>FEATURES="test"</c>),
681 <c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing packages
682
683 diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
684 index 81d4c44..b0c15d9 100644
685 --- a/ebuild-writing/variables/text.xml
686 +++ b/ebuild-writing/variables/text.xml
687 @@ -153,6 +153,35 @@ for these variables when writing ebuilds.
688 satisfied by <c>BDEPEND</c>, typically executable build tools.
689 </ti>
690 </tr>
691 + <tr>
692 + <ti><c>MERGE_TYPE</c></ti>
693 + <ti>
694 + The type of package that is being merged. Possible values are:
695 + <c>source</c> if building and installing a package from source,
696 + <c>binary</c> if installing a binary package previously built from
697 + the ebuild, <c>buildonly</c> if building a binary package without
698 + installing it.
699 + </ti>
700 + </tr>
701 + <tr>
702 + <ti><c>REPLACING_VERSIONS</c></ti>
703 + <ti>
704 + A whitespace-separated list of all versions (<c>PVR</c>) of this package
705 + that are being replaced (uninstalled or overwritten) as a result of this
706 + install. It is a list, not a single optional value, to handle pathological
707 + cases such as installing <c>foo-2:2</c> to replace <c>foo-2:1</c> and
708 + <c>foo-3:2</c>. Available in <c>pkg_preinst</c> and <c>pkg_postinst</c>.
709 + </ti>
710 + </tr>
711 + <tr>
712 + <ti><c>REPLACED_BY_VERSION</c></ti>
713 + <ti>
714 + The single version (<c>PVR</c>) of this package that is replacing the
715 + version provided by this ebuild, if it is being uninstalled as part of
716 + an install. An empty string otherwise, i.e., if it is being uninstalled
717 + without replacement. Available in <c>pkg_prerm</c> and <c>pkg_postrm</c>.
718 + </ti>
719 + </tr>
720 </table>
721
722 </body>
723 @@ -238,9 +267,9 @@ The following variables may or must be defined by every ebuild.
724 <tr>
725 <ti><c>REQUIRED_USE</c></ti>
726 <ti>
727 - A list of assertions that must be met by the configuration of
728 - <c>USE</c> flags to be valid for this ebuild. (Requires EAPI>=4.)
729 - See <uri link="::ebuild-writing/variables#REQUIRED_USE"/>.
730 + A list of assertions that must be met by the configuration of <c>USE</c>
731 + flags to be valid for this ebuild.
732 + See <uri link="::ebuild-writing/variables/#REQUIRED_USE"/>.
733 </ti>
734 </tr>
735 <tr>
736 @@ -300,10 +329,11 @@ The following variables may or must be defined by every ebuild.
737 <tr>
738 <ti><c>DOCS</c></ti>
739 <ti>
740 - An array or space-delimited list of documentation files for
741 - the default src_install function to install using dodoc. If
742 - undefined, a reasonable default list is used. (Requires
743 - <uri link="::ebuild-writing/eapi/#EAPI=4">EAPI&gt;=4</uri>.)
744 + An array or whitespace-separated list of documentation files for
745 + the default <c>src_install</c> function to install using <c>dodoc</c>.
746 + If undefined, a reasonable default list is used. See the
747 + <uri link="::ebuild-writing/functions/src_install/#Default src_install">
748 + default <c>src_install</c> function</uri>.
749 </ti>
750 </tr>
751 <tr>
752
753 diff --git a/function-reference/build-functions/text.xml b/function-reference/build-functions/text.xml
754 index 798e4ab..646c75e 100644
755 --- a/function-reference/build-functions/text.xml
756 +++ b/function-reference/build-functions/text.xml
757 @@ -32,7 +32,10 @@ during the unpack and compile stages.
758 <c>econf args</c>
759 </ti>
760 <ti>
761 - Wrapper for <c>./configure</c>. Passes on all <c>args</c>. Will abort (via <c>die</c>) should <c>configure</c> fail.
762 + Wrapper for <c>./configure</c>. Passes on all <c>args</c>. Will abort
763 + (via <c>die</c>) should <c>configure</c> fail.
764 + See <uri link="::ebuild-writing/functions/src_configure/configuring/#econf Options"/>
765 + for details.
766 </ti>
767 </tr>
768 <tr>
769
770 diff --git a/function-reference/error-functions/text.xml b/function-reference/error-functions/text.xml
771 new file mode 100644
772 index 0000000..70153eb
773 --- /dev/null
774 +++ b/function-reference/error-functions/text.xml
775 @@ -0,0 +1,50 @@
776 +<?xml version="1.0"?>
777 +<guide self="function-reference/error-functions/">
778 +<chapter>
779 +<title>Error Functions Reference</title>
780 +<body>
781 +
782 +<p>
783 +The following functions are provided by the package manager for error handling.
784 +</p>
785 +
786 +<table>
787 + <tr>
788 + <th>Function</th>
789 + <th>Details</th>
790 + </tr>
791 + <tr>
792 + <ti><c>die</c></ti>
793 + <ti>
794 + <p>
795 + Displays an error message provided in its argument, and aborts the build
796 + process.
797 + </p>
798 + <p>
799 + In EAPI 6 and later, <c>die</c> can be called under the <c>nonfatal</c>
800 + command and with the <c>-n</c> option, in which case it will not abort
801 + the build process, but return with non-zero status.
802 + </p>
803 + </ti>
804 + </tr>
805 + <tr>
806 + <ti><c>assert</c></ti>
807 + <ti>
808 + Checks the value of the <c>PIPESTATUS</c> array, and calls <c>die</c>
809 + if any of its component is non-zero (which indicates failure of the
810 + preceding command pipeline).
811 + </ti>
812 + </tr>
813 + <tr>
814 + <ti><c>nonfatal</c></ti>
815 + <ti>
816 + Takes another command as its argument and executes it. If the command
817 + fails and would normally die, it returns with non-zero status instead
818 + when called under <c>nonfatal</c>.
819 + </ti>
820 + </tr>
821 +</table>
822 +
823 +</body>
824 +</chapter>
825 +</guide>
826
827 diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml
828 index a042480..7e0b540 100644
829 --- a/function-reference/install-functions/text.xml
830 +++ b/function-reference/install-functions/text.xml
831 @@ -128,8 +128,7 @@ the first is the source name, the second the name to use when installing.
832 </ti>
833 <ti>
834 Install a documentation file into <c>/usr/share/doc/${PF}</c>.
835 - For EAPI 4 and above, the <c>-r</c> option allows directories to
836 - be installed recursively.
837 + The <c>-r</c> option allows directories to be installed recursively.
838 </ti>
839 </tr>
840 <tr>
841 @@ -205,6 +204,8 @@ the first is the source name, the second the name to use when installing.
842 <ti>
843 Install a miscellaneous file.
844 The <c>-r</c> option allows directories to be installed recursively.
845 + Any symlinks encountered are installed as symlinks, when installing
846 + recursively.
847 </ti>
848 </tr>
849 <tr>
850 @@ -407,6 +408,15 @@ the first is the source name, the second the name to use when installing.
851 Install an <c>sbin</c> file using the second argument as the name
852 </ti>
853 </tr>
854 + <tr>
855 + <ti>
856 + <c>docompress</c>
857 + </ti>
858 + <ti>
859 + Controls compression of files. Normally executed to exclude from
860 + compression, e.g., <c>docompress -x /usr/share/doc/${PF}/examples</c>.
861 + </ti>
862 + </tr>
863 <tr>
864 <ti>
865 <c>dostrip</c>
866
867 diff --git a/function-reference/text.xml b/function-reference/text.xml
868 index 336321d..2b90dfc 100644
869 --- a/function-reference/text.xml
870 +++ b/function-reference/text.xml
871 @@ -18,6 +18,7 @@ The following functions are available for use in ebuilds:
872 </chapter>
873
874 <include href="build-functions/"/>
875 +<include href="error-functions/"/>
876 <include href="install-functions/"/>
877 <include href="message-functions/"/>
878 <include href="query-functions/"/>
879
880 diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml
881 index 2aca289..ff198fb 100644
882 --- a/general-concepts/dependencies/text.xml
883 +++ b/general-concepts/dependencies/text.xml
884 @@ -572,15 +572,25 @@ There are also shortcuts for conditional situations:
885 <body>
886
887 <p>
888 -If a dependency is introducing or removing a <c>USE</c> flag in new versions, a use
889 -dependency default may be used. Appending a <c>(+)</c> or <c>(-)</c> suffix will indicate
890 -whether the absence of the flag from a particular version should indicate its
891 -presence or absence.
892 +If a dependency is introducing or removing a <c>USE</c> flag in a new package
893 +version, a <c>(+)</c> or <c>(-)</c> may be added to the use-dependency
894 +specification to define a default value in case the flag does not exist in the
895 +target package. The <c>(+)</c> indicates that the missing flag is assumed to be
896 +enabled, <c>(-)</c> the opposite.
897 </p>
898 +
899 <p>
900 -<c>>=dev-libs/boost-1.48[threads(+)]</c> will treat all versions without <c>threads</c> as having it set.
901 +For example, the following will treat all <c>boost</c> versions without the
902 +<c>threads</c> flag as having it enabled, and all <c>gcc</c> versions without
903 +the <c>openmp</c> as having it disabled:
904 </p>
905
906 +<codesample lang="ebuild">
907 +DEPEND="
908 + &gt;=dev-libs/boost-1.48[threads(+)]
909 + sys-devel/gcc[openmp(-)]"
910 +</codesample>
911 +
912 </body>
913 </subsection>
914 </section>
915
916 diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml
917 index 30b19f7..295bb8f 100644
918 --- a/general-concepts/use-flags/text.xml
919 +++ b/general-concepts/use-flags/text.xml
920 @@ -316,10 +316,10 @@ src_compile() {
921 </codesample>
922
923 <p>
924 -In some exceptional cases, above policy would break reverse USE
925 -dependencies. To avoid this, the ebuild can specify allowed USE flag
926 -combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section
927 -<uri link="::ebuild-writing/eapi/#EAPI=4"/> for a description
928 +In some exceptional cases, above policy would break reverse USE dependencies.
929 +To avoid this, the ebuild can specify allowed USE flag combinations with
930 +<c>REQUIRED_USE</c>. See section
931 +<uri link="::ebuild-writing/variables/#REQUIRED_USE"/> for a description
932 of its syntax.
933 </p>
934
935
936 diff --git a/general-concepts/virtuals/text.xml b/general-concepts/virtuals/text.xml
937 index 4f8b96d..bcea98d 100644
938 --- a/general-concepts/virtuals/text.xml
939 +++ b/general-concepts/virtuals/text.xml
940 @@ -24,7 +24,7 @@ An example of a virtual:
941 </p>
942
943 <codesample lang="ebuild">
944 -EAPI=4
945 +EAPI=7
946
947 DESCRIPTION="Virtual for C++ tr1 &lt;type_traits&gt;"
948 SLOT="0"
Report Message
Find on MARC Find on Google Groups