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: ebuild-writing/eapi/, appendices/contributors/
Date: Wed, 14 Jul 2021 12:27:27
Message-Id: 1626114504.9236a4c31054fb03cf86bfcdfc1e3ddff6cc5396.ulm@gentoo
1 commit: 9236a4c31054fb03cf86bfcdfc1e3ddff6cc5396
2 Author: Ulrich Müller <ulm <AT> gentoo <DOT> org>
3 AuthorDate: Fri Jul 2 19:09:18 2021 +0000
4 Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org>
5 CommitDate: Mon Jul 12 18:28:24 2021 +0000
6 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9236a4c3
7
8 ebuild-writing/eapi: Add EAPI 8 guide
9
10 Main part taken from "The ultimate guide to EAPI 8" by Michał Górny:
11 https://mgorny.pl/articles/the-ultimate-guide-to-eapi-8.html
12
13 Converted to DevBook XML and heavily edited to make it fit into the
14 framework of the devmanual.
15
16 Original-Author: Michał Górny <mgorny <AT> gentoo.org>
17 Original-License: CC-BY-3.0
18 Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org>
19
20 appendices/contributors/text.xml | 6 +-
21 ebuild-writing/eapi/text.xml | 766 +++++++++++++++++++++++++++++++++++++++
22 2 files changed, 769 insertions(+), 3 deletions(-)
23
24 diff --git a/appendices/contributors/text.xml b/appendices/contributors/text.xml
25 index b1e9bd9..55a4cc2 100644
26 --- a/appendices/contributors/text.xml
27 +++ b/appendices/contributors/text.xml
28 @@ -109,9 +109,9 @@ Misc
29 </author>
30 <author name="Michał Górny" email="mgorny@g.o">
31 <uri link="::general-concepts/"/>,
32 - <uri link="::ebuild-writing/users-and-groups/"/>,
33 - <uri link="::ebuild-writing/variables/"/>,
34 - <uri link="::ebuild-writing/functions/src_test/"/>,
35 + <uri link="::ebuild-writing/"/>,
36 + <!-- The following is 700+ lines, so keep is as a separate entry -->
37 + <uri link="::ebuild-writing/eapi/#EAPI 8"/>,
38 <uri link="::ebuild-maintenance/"/>
39 </author>
40 <author name="Brian Evans" email="grknight@g.o">
41
42 diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
43 index b738640..e85a3ec 100644
44 --- a/ebuild-writing/eapi/text.xml
45 +++ b/ebuild-writing/eapi/text.xml
46 @@ -616,6 +616,772 @@ installation targets.
47 </dd>
48 </dl>
49
50 +</body>
51 +</subsection>
52 +</section>
53 +
54 +<section>
55 +<title>EAPI 8</title>
56 +<body>
57 +
58 +<note>
59 +This section is based on
60 +<uri link="https://mgorny.pl/articles/the-ultimate-guide-to-eapi-8.html">
61 +The ultimate guide to EAPI 8</uri> by Michał Górny.
62 +</note>
63 +
64 +</body>
65 +
66 +<subsection>
67 +<title>EAPI 8 tree layout</title>
68 +<body>
69 +
70 +<dl>
71 + <dt>Less strict naming rules for updates directory</dt>
72 + <dd>
73 + <p>
74 + Up to EAPI 7, the files in the <c>profiles/updates</c> directory had to
75 + follow strict naming by quarters like <c>2Q-2021</c>, indicating the
76 + quarter and the year when they were added. Such a choice of name had the
77 + side effect that lexical sorting of filenames was unsuitable.
78 + </p>
79 +
80 + <p>
81 + In EAPI 8, the naming requirement is removed. Eventually, this will allow
82 + switching to a more convenient scheme sorted by year. Different lengths
83 + of time periods will also be possible.
84 + </p>
85 +
86 + <p>
87 + Note that this change actually requires changing the repository EAPI
88 + (found in <c>profiles/eapi</c>), so it will not affect Gentoo for at least
89 + the next two years.
90 + </p>
91 + </dd>
92 +</dl>
93 +
94 +</body>
95 +</subsection>
96 +<subsection>
97 +<title>EAPI 8 ebuild format</title>
98 +<body>
99 +
100 +<dl>
101 + <dt>Bash version is now 5.0</dt>
102 + <dd>
103 + <p>
104 + The Bash version used for ebuilds is changed from 4.2 to 5.0. This means
105 + not only that ebuilds are now permitted to use features provided by the new
106 + Bash version but also the <c>BASH_COMPAT</c> value used for the ebuild
107 + environment is updated, switching the shell behaviour.
108 + </p>
109 +
110 + <p>
111 + The only really relevant difference in behaviour is:
112 + </p>
113 +
114 + <ul>
115 + <li>
116 + <p>
117 + Quotes are now removed from the RHS argument of a
118 + <c>"${var/.../"..."}"</c> substitution:
119 + </p>
120 +
121 +<pre>
122 +var=foo
123 +echo "${var/foo/"bar"}"
124 +</pre>
125 +
126 + <p>
127 + The above snippet yields <c>"bar"</c> in Bash 4.2 but just <c>bar</c>
128 + in 4.3+.
129 + </p>
130 + </li>
131 + </ul>
132 +
133 + <p>
134 + Potentially interesting new features include:
135 + </p>
136 +
137 + <ul>
138 + <li>
139 + <p>
140 + Negative subscripts can now be used to set and unset array elements
141 + (Bash 4.3+):
142 + </p>
143 +
144 +<pre>
145 +$ foo=( 1 2 3 )
146 +$ foo[-1]=4
147 +$ unset 'foo[-2]'
148 +$ declare -p foo
149 +declare -a foo=([0]="1" [2]="4")
150 +</pre>
151 +
152 + </li>
153 + <li>
154 + <p>
155 + Nameref variables are introduced that work as references to other
156 + variables (4.3+):
157 + </p>
158 +
159 +<pre>
160 +$ foo=( 1 2 3 )
161 +$ declare -n bar=foo
162 +$ echo "${bar[@]}"
163 +1 2 3
164 +$ bar[0]=4
165 +$ echo "${foo[@]}"
166 +4 2 3
167 +$ declare -n baz=foo[1]
168 +$ echo "${baz}"
169 +2
170 +$ baz=100
171 +$ echo "${bar[@]}"
172 +4 100 3
173 +</pre>
174 +
175 + </li>
176 + <li>
177 + <p>
178 + The <c>[[ -v ... ]]</c> test operator can be used with array indices
179 + to test for array elements being set (4.3+). The two following lines
180 + are now equivalent:
181 + </p>
182 +
183 +<pre>
184 +[[ -n ${foo[3]+1} ]]
185 +[[ -v foo[3] ]]
186 +</pre>
187 + </li>
188 + <li>
189 + <p>
190 + <c>mapfile</c> (AKA <c>readarray</c>) now accepts a delimiter via
191 + <c>-d</c>, with a <c>-t</c> option to strip it from read data
192 + (Bash 4.4+). The two following solutions to grab output from
193 + <c>find(1)</c> are now equivalent:
194 + </p>
195 +
196 +<pre>
197 +# old solution
198 +local x files=()
199 +while read -d '' -r x; do
200 + files+=( "${x}" )
201 +done &lt; &lt;(find -print0)
202 +
203 +# new solution
204 +local files=()
205 +mapfile -d '' -t files &lt; &lt;(find -print0)
206 +</pre>
207 +
208 + </li>
209 + <li>
210 + <p>
211 + A new set of transformations is available via <c>${foo@...}</c>
212 + parameter expansion (4.4+), e.g. to print a value with necessary
213 + quoting:
214 + </p>
215 +
216 +<pre>
217 +$ var="foo 'bar' baz"
218 +$ echo "${var@Q}"
219 +'foo '\''bar'\'' baz'
220 +</pre>
221 +
222 + <p>
223 + For more details, see: <c>info bash</c> or the
224 + <uri link="https://www.gnu.org/software/bash/manual/html_node/Shell-Parameter-Expansion.html">
225 + Bash reference manual</uri>.
226 + </p>
227 + </li>
228 + <li>
229 + <p>
230 + <c>local -</c> can be used to limit single-letter (mangled via
231 + <c>set</c>) shell option changes to the scope of the function, and
232 + restore them upon returning from it (4.4+). The following two functions
233 + are now equivalent:
234 + </p>
235 +
236 +<pre>
237 +# old solution
238 +func() {
239 + local prev_shopt=$(shopt -p -o noglob)
240 + set -o noglob
241 + ${prev_shopt}
242 +}
243 +
244 +# new solution
245 +func() {
246 + local -
247 + set -o noglob
248 +}
249 +</pre>
250 +
251 + <p>
252 + The complete information on all changes and new features can be found
253 + in the
254 + <uri link="https://git.savannah.gnu.org/cgit/bash.git/tree/NEWS?h=bash-5.0">
255 + Bash 5.0 (and earlier) release notes</uri>.
256 + </p>
257 + </li>
258 + </ul>
259 + </dd>
260 +</dl>
261 +
262 +</body>
263 +</subsection>
264 +<subsection>
265 +<title>EAPI 8 variables</title>
266 +<body>
267 +
268 +<dl>
269 + <dt>Selective fetch/mirror restriction</dt>
270 + <dd>
271 + <p>
272 + Before EAPI 8, fetch and mirror restrictions applied globally. That is,
273 + if you needed to apply the respective restriction to at least one distfile,
274 + you had to apply it to them all. However, sometimes packages used a
275 + combination of proprietary and free distfiles, the latter including e.g.
276 + third party patches, artwork. Until now, they had to be mirror-restricted
277 + completely.
278 + </p>
279 +
280 + <p>
281 + EAPI 8 allows undoing fetch and mirror restriction for individual files.
282 + To use this, set <c>RESTRICT</c> as before, then use the special
283 + <c>fetch+</c> prefix to specify URLs that can be fetched from, or the
284 + <c>mirror+</c> prefix to reenable mirroring of individual files.
285 + </p>
286 +
287 + <p>
288 + Similarly to how the <c>fetch</c> restriction implies a <c>mirror</c>
289 + restriction, the <c>mirror</c> override implies a <c>fetch</c> override.
290 + </p>
291 +
292 +<codesample lang="ebuild">
293 +EAPI=8
294 +
295 +SRC_URI="
296 + ${P}.tgz
297 + fetch+https://example.com/${P}-patch-1.tgz
298 + mirror+https://example.com/${P}-fanstuff.tgz"
299 +
300 +RESTRICT="fetch"
301 +</codesample>
302 +
303 + <p>
304 + The following table summarises the new behaviour:
305 + </p>
306 +
307 + <table>
308 + <tr>
309 + <th><c>RESTRICT</c></th>
310 + <th>URI prefix</th>
311 + <th>Fetching</th>
312 + <th>Mirroring</th>
313 + </tr>
314 + <tr>
315 + <ti>(none)</ti>
316 + <ti>(any)</ti>
317 + <ti>allowed</ti>
318 + <ti>allowed</ti>
319 + </tr>
320 + <tr>
321 + <ti rowspan="2">mirror</ti>
322 + <ti>(none) / fetch+</ti>
323 + <ti>allowed</ti>
324 + <ti>prohibited</ti>
325 + </tr>
326 + <tr>
327 + <ti>mirror+</ti>
328 + <ti>allowed</ti>
329 + <ti>allowed</ti>
330 + </tr>
331 + <tr>
332 + <ti rowspan="3">fetch</ti>
333 + <ti>(none)</ti>
334 + <ti>prohibited</ti>
335 + <ti>prohibited</ti>
336 + </tr>
337 + <tr>
338 + <ti>fetch+</ti>
339 + <ti>allowed</ti>
340 + <ti>prohibited</ti>
341 + </tr>
342 + <tr>
343 + <ti>mirror+</ti>
344 + <ti>allowed</ti>
345 + <ti>allowed</ti>
346 + </tr>
347 + </table>
348 + </dd>
349 +
350 + <dt>Install-time dependencies (<c>IDEPEND</c>)</dt>
351 + <dd>
352 + <p>
353 + The primary use for install-time dependencies is to specify dependencies
354 + that are needed during the <c>pkg_postinst</c> phase and that can be
355 + unmerged afterwards. That's pretty much the same as <c>RDEPEND</c>, except
356 + for the unmerging part <d/> and uninstalling a few tools did not seem a
357 + goal justifying another dependency type.
358 + </p>
359 +
360 + <p>
361 + With cross-compilation support in EAPI 7, a new dependency type focused
362 + on the build host (<c>CBUILD</c>) tools was added <d/> <c>BDEPEND</c>.
363 + Unfortunately, this had missed the important use case of running
364 + executables installed to the target system when cross-compiling.
365 + <c>RDEPEND</c> was no longer a suitable method of pulling in tools for
366 + <c>pkg_postinst</c>; and since <c>BDEPEND</c> is not used when installing
367 + from a binary package, something new was needed.
368 + </p>
369 +
370 + <p>
371 + This is where <c>IDEPEND</c> comes in. It is roughly to <c>RDEPEND</c> what
372 + <c>BDEPEND</c> is to <c>DEPEND</c>. Similarly to <c>BDEPEND</c>,
373 + it specifies packages that must be built for the <c>CBUILD</c> triplet
374 + and installed into <c>BROOT</c> (and therefore queried using
375 + <c>has_version -b</c>). However, similarly to <c>RDEPEND</c>, it is used
376 + when the package is being merged rather than built from source.
377 + It is guaranteed to be satisfied throughout <c>pkg_preinst</c> and
378 + <c>pkg_postinst</c>, and it can be uninstalled afterwards.
379 + </p>
380 +
381 +<codesample lang="ebuild">
382 +EAPI=8
383 +
384 +inherit xdg-utils
385 +
386 +IDEPEND="dev-util/desktop-file-utils"
387 +
388 +pkg_postinst() {
389 + xdg_desktop_database_update
390 +}
391 +
392 +pkg_postrm() {
393 + xdg_desktop_database_update
394 +}
395 +</codesample>
396 +
397 + <p>
398 + In the example provided above, the ebuild needs to be update the icon cache
399 + upon being installed or uninstalled. By placing the respective tool in
400 + <c>IDEPEND</c>, the ebuild requests it to be available at the time of
401 + <c>pkg_postinst</c>. When cross-compiling, the tool will be built for
402 + <c>CBUILD</c> and therefore directly executable by the ebuild.
403 + </p>
404 +
405 + <p>
406 + The dependency types table for EAPI 8 is presented below.
407 + </p>
408 +
409 + <table>
410 + <tr>
411 + <th>Dependency type</th>
412 + <th>BDEPEND</th>
413 + <th>IDEPEND</th>
414 + <th>DEPEND</th>
415 + <th>RDEPEND</th>
416 + <th>PDEPEND</th>
417 + </tr>
418 + <tr>
419 + <th>Present at</th>
420 + <ti>build</ti>
421 + <ti>install</ti>
422 + <ti>build</ti>
423 + <ti>install</ti>
424 + <ti>n/a</ti>
425 + </tr>
426 + <tr>
427 + <th>Binary compatible with</th>
428 + <ti colspan="2">CBUILD</ti>
429 + <ti colspan="3">CHOST</ti>
430 + </tr>
431 + <tr>
432 + <th>Base unprefixed path</th>
433 + <ti colspan="2"><c>/</c></ti>
434 + <ti>SYSROOT</ti>
435 + <ti colspan="2">ROOT</ti>
436 + </tr>
437 + <tr>
438 + <th>Relevant offset-prefix</th>
439 + <ti colspan="2">BROOT</ti>
440 + <ti>EPREFIX (unless SYSROOT != ROOT)</ti>
441 + <ti colspan="2">EPREFIX</ti>
442 + </tr>
443 + <tr>
444 + <th>Path combined with prefix</th>
445 + <ti colspan="2">BROOT</ti>
446 + <ti>ESYSROOT</ti>
447 + <ti colspan="2">EROOT</ti>
448 + </tr>
449 + <tr>
450 + <th>PM query command option</th>
451 + <ti colspan="2"><c>-b</c></ti>
452 + <ti><c>-d</c></ti>
453 + <ti colspan="2"><c>-r</c></ti>
454 + </tr>
455 + </table>
456 + </dd>
457 +
458 + <dt>
459 + <c>PROPERTIES</c> and <c>RESTRICT</c> are now accumulated across eclasses
460 + </dt>
461 + <dd>
462 + <p>
463 + Up to EAPI 7, <c>PROPERTIES</c> and <c>RESTRICT</c> were treated like
464 + regular Bash variables when sourcing eclasses. This meant that if an eclass
465 + or an ebuild wanted to modify them, they had to explicitly append to them,
466 + e.g. via <c>+=</c>. This was inconsistent with how some other variables
467 + (but not all) were handled, and confusing to developers. For example,
468 + consider the following snippet:
469 + </p>
470 +
471 +<codesample lang="ebuild">
472 +EAPI=7
473 +
474 +inherit git-r3
475 +
476 +PROPERTIES+=" interactive"
477 +</codesample>
478 +
479 + <p>
480 + Note how you needed to append to <c>PROPERTIES</c> set by git-r3 eclass,
481 + otherwise the ebuild would have overwritten it. In EAPI 8, you can finally
482 + do the following instead:
483 + </p>
484 +
485 +<codesample lang="ebuild">
486 +EAPI=8
487 +
488 +inherit git-r3
489 +
490 +PROPERTIES="interactive"
491 +</codesample>
492 +
493 + <p>
494 + Now the complete list of metadata variables accumulated across eclasses
495 + and ebuilds includes: <c>IUSE</c>, <c>REQUIRED_USE</c>, <c>*DEPEND</c>,
496 + <c>PROPERTIES</c>, <c>RESTRICT</c>. Variables that are not treated this way
497 + are: <c>EAPI</c>, <c>HOMEPAGE</c>, <c>SRC_URI</c>, <c>LICENSE</c>,
498 + <c>KEYWORDS</c>. <c>EAPI</c> and <c>KEYWORDS</c> are not supposed to be set
499 + in eclasses; as for the others, there appears to be a valid use case for
500 + eclasses providing default values and the ebuilds being able to override
501 + them.
502 + </p>
503 + </dd>
504 +</dl>
505 +
506 +</body>
507 +</subsection>
508 +<subsection>
509 +<title>EAPI 8 phase functions</title>
510 +<body>
511 +
512 +<dl>
513 + <dt><c>pkg_*</c> phases now run in a dedicated empty directory</dt>
514 + <dd>
515 + <p>
516 + Before EAPI 8, the initial working directory was specified for <c>src_*</c>
517 + phases only. For other phases (i.e. <c>pkg_*</c> phases), ebuilds were not
518 + supposed to assume any particular directory. In EAPI 8, these phases are
519 + guaranteed to be started in a dedicated empty directory.
520 + </p>
521 +
522 + <p>
523 + The idea of using an empty directory is pretty simple <d/> if there are no
524 + files in it, the risk of unexpected and hard to predict interactions of
525 + tools with their current working directory is minimized.
526 + </p>
527 + </dd>
528 +
529 + <dt>
530 + <c>PATCHES</c> no longer permits options
531 + </dt>
532 + <dd>
533 + <p>
534 + The <c>eapply</c> invocation in the default <c>src_prepare</c>
535 + implementation has been changed to:
536 + </p>
537 +
538 +<codesample lang="ebuild">
539 +eapply -- "${PATCHES[@]}"
540 +</codesample>
541 +
542 + <p>
543 + This ensures that all items in the <c>PATCHES</c> variable are treated
544 + as path names. As a side effect, it is no longer possible to specify
545 + <c>patch</c> options via the <c>PATCHES</c> variable. Such hacks were never
546 + used in the Gentoo repository but they have been spotted in
547 + user-contributed ebuilds. The following will no longer work:
548 + </p>
549 +
550 +<codesample lang="ebuild">
551 +PATCHES=( -p0 "${FILESDIR}"/${P}-foo.patch )
552 +</codesample>
553 +
554 + <p>
555 + Instead, you will need to invoke <c>eapply</c> explicitly, see the example
556 + below. Alternatively, rebase the patch level.
557 + </p>
558 +
559 +<codesample lang="ebuild">
560 +src_prepare() {
561 + eapply -p0 "${FILESDIR}"/${P}-foo.patch
562 + eapply_user
563 +}
564 +</codesample>
565 +
566 + </dd>
567 +</dl>
568 +
569 +</body>
570 +</subsection>
571 +<subsection>
572 +<title>EAPI 8 commands</title>
573 +<body>
574 +
575 +<dl>
576 + <dt>New econf-passed options</dt>
577 + <dd>
578 + <p>
579 + The <c>econf</c> helper has been modified to pass two more options to
580 + the configure script if the <c>--help</c> text indicates that they are
581 + supported. These are:
582 + </p>
583 +
584 + <ul>
585 + <li><c>--datarootdir="${EPREFIX}"/usr/share</c></li>
586 + <li><c>--disable-static</c></li>
587 + </ul>
588 +
589 + <p>
590 + The former option defines the base directory that is used to determine
591 + locations for system/desktop-specific data files, e.g. .desktop files and
592 + various kinds of documentation. This is necessary for ebuilds that override
593 + <c>--prefix</c>, as the default path is relative to it.
594 + </p>
595 +
596 + <p>
597 + The latter option disables building static libraries by default. This is
598 + part of the ongoing effort to disable unconditional install of static
599 + libraries
600 + (<uri link="https://projects.gentoo.org/qa/policy-guide/installed-files.html#pg0302">
601 + Gentoo Policy Guide, Installation of static libraries</uri>).
602 + </p>
603 + </dd>
604 +
605 + <dt><c>dosym -r</c> to create relative symlinks</dt>
606 + <dd>
607 + <p>
608 + Relative symlink targets tend to be more reliable. Consider the two
609 + following examples:
610 + </p>
611 +
612 +<codesample lang="ebuild">
613 +dosym "${EPREFIX}"/usr/lib/frobnicate/frobnicate /usr/bin/frobnicate
614 +dosym ../lib/frobnicate/frobnicate /usr/bin/frobnicate
615 +</codesample>
616 +
617 + <p>
618 + The first line creates a symlink using an absolute path. The problem with
619 + that is if you mount your Gentoo system in a subdirectory of your root
620 + filesystem (e.g. for recovery), the symlink will point at the wrong
621 + location. Using relative symlinks (as demonstrated on the second line)
622 + guarantees that the symlink will work independently of where the filesystem
623 + is mounted.
624 + </p>
625 +
626 + <p>
627 + There is also fact that you need to explicitly prepend <c>${EPREFIX}</c>
628 + to the absolute paths passed as the first argument of <c>dosym</c>. Using
629 + a relative target avoids the problem altogether and makes it less likely to
630 + forget about the prefix.
631 + </p>
632 +
633 + <p>
634 + However, in some instances, determining the relative path could be hard or
635 + inconvenient. This is especially the case if one (or both) of the paths
636 + comes from an external tool. To make it easier, EAPI 8 adds a new <c>-r</c>
637 + option that makes <c>dosym</c> create a relative symlink to the specified
638 + path (similarly to <c>ln -r</c>):
639 + </p>
640 +
641 +<codesample lang="ebuild">
642 +dosym -r /usr/lib/frobnicate/frobnicate /usr/bin/frobnicate
643 +</codesample>
644 +
645 + <p>
646 + Note that in this case, you do not pass <c>${EPREFIX}</c>. The helper
647 + determines the <e>logical</e> relative path to the first argument and
648 + creates the appropriate relative symlink. It is very important here to
649 + understand that this function does not handle physical paths, i.e. it will
650 + work only if there are no directory symlinks along the way that would
651 + result in <c>..</c> resolving to a different path. For example, the
652 + following will not work:
653 + </p>
654 +
655 +<codesample lang="ebuild">
656 +dosym bar/foo /usr/lib/foo
657 +dosym -r /usr/lib/zomg /usr/lib/foo/zomg
658 +</codesample>
659 +
660 + <p>
661 + The logical path from <c>/usr/lib/foo/zomg</c> to <c>/usr/lib/zomg</c> is
662 + <c>../zomg</c>. However, since <c>/usr/lib/foo</c> is actually a symlink to
663 + <c>/usr/lib/bar/foo</c>, <c>/usr/lib/foo/..</c> resolves to
664 + <c>/usr/lib/bar</c>. If you need to account for such directory symlinks,
665 + you need to specify the correct path explicitly:
666 + </p>
667 +
668 +<codesample lang="ebuild">
669 +dosym bar/foo /usr/lib/foo
670 +dosym ../../zomg /usr/lib/foo/zomg
671 +</codesample>
672 +
673 + </dd>
674 +
675 + <dt>
676 + <c>insopts</c> and <c>exeopts</c> now apply to <c>doins</c>
677 + and <c>doexe</c> only
678 + </dt>
679 + <dd>
680 + <p>
681 + In previous EAPIs, there was an inconsistency in how <c>insopts</c> and
682 + <c>exeopts</c> applied to various helpers. In particular, the majority of
683 + helpers (e.g. <c>dobin</c>, <c>dodoc</c> and so on) ignored the options
684 + specified via these helpers but a few did not.
685 + </p>
686 +
687 + <p>
688 + EAPI 8 changes the behaviour of the following helpers that used to respect
689 + <c>insopts</c> or <c>exeopts</c>:
690 + </p>
691 +
692 + <ul>
693 + <li><c>doconfd</c></li>
694 + <li><c>doenvd</c></li>
695 + <li><c>doheader</c></li>
696 + <li><c>doinitd</c></li>
697 + </ul>
698 +
699 + <p>
700 + In EAPI 8, they always use the default options. As a result, <c>insopts</c>
701 + now only affects <c>doins</c>/<c>newins</c>, and <c>exeopts</c> only
702 + affects <c>doexe</c>/<c>newexe</c>. Furthermore, <c>diropts</c> does not
703 + affect the directories implicitly created by these helpers.
704 + </p>
705 + </dd>
706 +
707 + <dt><c>usev</c> now accepts a second argument</dt>
708 + <dd>
709 + <p>
710 + The <c>usev</c> helper was introduced to provide the historical Portage
711 + behaviour of outputting the USE flag name on match. In EAPI 8, it has been
712 + extended, in order to provide an alternative to three-argument <c>usex</c>
713 + with an empty third argument (the two-argument <c>usex</c> variant uses a
714 + default of <c>no</c> for the false branch).
715 + </p>
716 +
717 + <p>
718 + In other words, the following two calls are now equivalent:
719 + </p>
720 +
721 +<codesample lang="ebuild">
722 +$(usex foo --enable-foo '')
723 +$(usev foo --enable-foo)
724 +</codesample>
725 +
726 + <p>
727 + This is particularly useful with custom build systems that accept
728 + individual <c>--enable</c> or <c>--disable</c> options but not their
729 + counterparts.
730 + </p>
731 +
732 + <p>
733 + As a result, <c>usev</c> and <c>usex</c> can now be used to achieve all the
734 + common (and less common) output needs as summarized in the following table.
735 + </p>
736 +
737 + <table>
738 + <tr>
739 + <th>Variant</th>
740 + <th>True</th>
741 + <th>False</th>
742 + </tr>
743 + <tr>
744 + <ti>usev <e>flag</e></ti>
745 + <ti><e>flag</e></ti>
746 + <ti></ti>
747 + </tr>
748 + <tr>
749 + <ti>usev <e>flag</e> <e>true</e></ti>
750 + <ti><e>true</e></ti>
751 + <ti></ti>
752 + </tr>
753 + <tr>
754 + <ti>usex <e>flag</e></ti>
755 + <ti><c>yes</c></ti>
756 + <ti><c>no</c></ti>
757 + </tr>
758 + <tr>
759 + <ti>usex <e>flag</e> <e>true</e></ti>
760 + <ti><e>true</e></ti>
761 + <ti><c>no</c></ti>
762 + </tr>
763 + <tr>
764 + <ti>usex <e>flag</e> <e>true</e> <e>false</e></ti>
765 + <ti><e>true</e></ti>
766 + <ti><e>false</e></ti>
767 + </tr>
768 + </table>
769 + </dd>
770 +
771 + <dt><c>hasq</c>, <c>hasv</c> and <c>useq</c> functions have been banned</dt>
772 + <dd>
773 + <p>
774 + In its early days, the <c>use</c> helper would print the USE flag name
775 + if it matched, in addition to its boolean exit status. Later, a quiet
776 + <c>useq</c> and a verbose <c>usev</c> helper were added, and <c>use</c> was
777 + made quiet by default. The same changes were applied to <c>has</c>.
778 + </p>
779 +
780 + <p>
781 + Fast forward to EAPI 7, there are still three variants of <c>use</c>
782 + and three variants of <c>has</c>. The base variant that is quiet, the
783 + <c>useq</c>/<c>hasq</c> variant that is equivalent to the base variant,
784 + and the verbose <c>usev</c>/<c>hasv</c> variant.
785 + </p>
786 +
787 + <p>
788 + Obviously, adding a second argument to <c>hasv</c> was not possible, so its
789 + behaviour would have become inconsistent with <c>usev</c> in EAPI 8. Since
790 + <c>hasv</c> was not used in the Gentoo repository, it has been removed,
791 + along with <c>hasq</c> and <c>useq</c> which were considered deprecated
792 + since 2011.
793 + </p>
794 + </dd>
795 +
796 + <dt>unpack removes support for 7-Zip, LHA and RAR formats</dt>
797 + <dd>
798 + <p>
799 + Support for the least commonly used archive formats from <c>unpack</c> has
800 + been removed:
801 + </p>
802 +
803 + <ul>
804 + <li>7-Zip (.7z)</li>
805 + <li>LHA (.lha, .lzh)</li>
806 + <li>RAR (.rar)</li>
807 + </ul>
808 +
809 + <p>
810 + Packages using these format for distfiles must now unpack them manually.
811 + Using <c>unpacker.eclass</c> is recommended for this.
812 + </p>
813 + </dd>
814 +</dl>
815 +
816 </body>
817 </subsection>
818 </section>
Report Message
Find on MARC Find on Google Groups