EAPI 8

+EAPI 8 + + + +This section is based on + +The ultimate guide to EAPI 8 by Michał Górny. + + + + + +EAPI 8 tree layout + + +

Less strict naming rules for updates directory

+ Up to EAPI 7, the files in the profiles/updates directory had to + follow strict naming by quarters like 2Q-2021, indicating the + quarter and the year when they were added. Such a choice of name had the + side effect that lexical sorting of filenames was unsuitable. +

+ +

+ In EAPI 8, the naming requirement is removed. Eventually, this will allow + switching to a more convenient scheme sorted by year. Different lengths + of time periods will also be possible. +

+ +

+ Note that this change actually requires changing the repository EAPI + (found in profiles/eapi), so it will not affect Gentoo for at least + the next two years. +

+ + + + +EAPI 8 ebuild format + + +

Bash version is now 5.0

+ The Bash version used for ebuilds is changed from 4.2 to 5.0. This means + not only that ebuilds are now permitted to use features provided by the new + Bash version but also the BASH_COMPAT value used for the ebuild + environment is updated, switching the shell behaviour. +

+ +

+ The only really relevant difference in behaviour is: +

+ +

+
+ Quotes are now removed from the RHS argument of a + "${var/.../"..."}" substitution: +
+ +
```
+var=foo
+echo "${var/foo/"bar"}"
+
```
+ +
+ The above snippet yields "bar" in Bash 4.2 but just bar + in 4.3+. +
+

+ +

+ Potentially interesting new features include: +

+ +

+
+ Negative subscripts can now be used to set and unset array elements + (Bash 4.3+): +
+ +
```
+$ foo=( 1 2 3 )
+$ foo[-1]=4
+$ unset 'foo[-2]'
+$ declare -p foo
+declare -a foo=([0]="1" [2]="4")
+
```
+ +

+ Nameref variables are introduced that work as references to other + variables (4.3+): +

+ +

+$ foo=( 1 2 3 )
+$ declare -n bar=foo
+$ echo "${bar[@]}"
+1 2 3
+$ bar[0]=4
+$ echo "${foo[@]}"
+4 2 3
+$ declare -n baz=foo[1]
+$ echo "${baz}"
+2
+$ baz=100
+$ echo "${bar[@]}"
+4 100 3
+

+ +

+
+ The [[ -v ... ]] test operator can be used with array indices + to test for array elements being set (4.3+). The two following lines + are now equivalent: +
+ +
```
+[[ -n ${foo[3]+1} ]]
+[[ -v foo[3] ]]
+
```
+
+
+ mapfile (AKA readarray) now accepts a delimiter via + -d, with a -t option to strip it from read data + (Bash 4.4+). The two following solutions to grab output from + find(1) are now equivalent: +
+ +
```
+# old solution
+local x files=()
+while read -d '' -r x; do
+	files+=( "${x}" )
+done < <(find -print0)
+
+# new solution
+local files=()
+mapfile -d '' -t files < <(find -print0)
+
```
+ +
+
+ A new set of transformations is available via ${foo@...} + parameter expansion (4.4+), e.g. to print a value with necessary + quoting: +
+ +
```
+$ var="foo 'bar' baz"
+$ echo "${var@Q}"
+'foo '\''bar'\'' baz'
+
```
+ +
+ For more details, see: info bash or the + + Bash reference manual. +
+
+
+ local - can be used to limit single-letter (mangled via + set) shell option changes to the scope of the function, and + restore them upon returning from it (4.4+). The following two functions + are now equivalent: +
+ +
```
+# old solution
+func() {
+	local prev_shopt=$(shopt -p -o noglob)
+	set -o noglob
+	${prev_shopt}
+}
+
+# new solution
+func() {
+	local -
+	set -o noglob
+}
+
```
+ +
+ The complete information on all changes and new features can be found + in the + + Bash 5.0 (and earlier) release notes. +
+

+ + + + +EAPI 8 variables + + +

Selective fetch/mirror restriction

+ Before EAPI 8, fetch and mirror restrictions applied globally. That is, + if you needed to apply the respective restriction to at least one distfile, + you had to apply it to them all. However, sometimes packages used a + combination of proprietary and free distfiles, the latter including e.g. + third party patches, artwork. Until now, they had to be mirror-restricted + completely. +

+ +

+ EAPI 8 allows undoing fetch and mirror restriction for individual files. + To use this, set RESTRICT as before, then use the special + fetch+ prefix to specify URLs that can be fetched from, or the + mirror+ prefix to reenable mirroring of individual files. +

+ +

+ Similarly to how the fetch restriction implies a mirror + restriction, the mirror override implies a fetch override. +

+ + +EAPI=8 + +SRC_URI=" + ${P}.tgz + fetch+https://example.com/${P}-patch-1.tgz + mirror+https://example.com/${P}-fanstuff.tgz" + +RESTRICT="fetch" + + +

+ The following table summarises the new behaviour: +

+ + + + + + + + + + (none) + (any) + allowed + allowed + + + mirror + (none) / fetch+ + allowed + prohibited + + + mirror+ + allowed + allowed + + + fetch + (none) + prohibited + prohibited + + + fetch+ + allowed + prohibited + + + mirror+ + allowed + allowed + +

RESTRICT	URI prefix	Fetching	Mirroring

Install-time dependencies (IDEPEND)

+ The primary use for install-time dependencies is to specify dependencies + that are needed during the pkg_postinst phase and that can be + unmerged afterwards. That's pretty much the same as RDEPEND, except + for the unmerging part and uninstalling a few tools did not seem a + goal justifying another dependency type. +

+ +

+ With cross-compilation support in EAPI 7, a new dependency type focused + on the build host (CBUILD) tools was added BDEPEND. + Unfortunately, this had missed the important use case of running + executables installed to the target system when cross-compiling. + RDEPEND was no longer a suitable method of pulling in tools for + pkg_postinst; and since BDEPEND is not used when installing + from a binary package, something new was needed. +

+ +

+ This is where IDEPEND comes in. It is roughly to RDEPEND what + BDEPEND is to DEPEND. Similarly to BDEPEND, + it specifies packages that must be built for the CBUILD triplet + and installed into BROOT (and therefore queried using + has_version -b). However, similarly to RDEPEND, it is used + when the package is being merged rather than built from source. + It is guaranteed to be satisfied throughout pkg_preinst and + pkg_postinst, and it can be uninstalled afterwards. +

+ + +EAPI=8 + +inherit xdg-utils + +IDEPEND="dev-util/desktop-file-utils" + +pkg_postinst() { + xdg_desktop_database_update +} + +pkg_postrm() { + xdg_desktop_database_update +} + + +

+ In the example provided above, the ebuild needs to be update the icon cache + upon being installed or uninstalled. By placing the respective tool in + IDEPEND, the ebuild requests it to be available at the time of + pkg_postinst. When cross-compiling, the tool will be built for + CBUILD and therefore directly executable by the ebuild. +

+ +

+ The dependency types table for EAPI 8 is presented below. +

+ + + + + + + + + + + + + build + install + build + install + n/a + + + + CBUILD + CHOST + + + + / + SYSROOT + ROOT + + + + BROOT + EPREFIX (unless SYSROOT != ROOT) + EPREFIX + + + + BROOT + ESYSROOT + EROOT + + + + -b + -d + -r + +

Dependency type	BDEPEND	IDEPEND	DEPEND	RDEPEND	PDEPEND
Present at
Binary compatible with
Base unprefixed path
Relevant offset-prefix
Path combined with prefix
PM query command option

+ PROPERTIES and RESTRICT are now accumulated across eclasses +

+ Up to EAPI 7, PROPERTIES and RESTRICT were treated like + regular Bash variables when sourcing eclasses. This meant that if an eclass + or an ebuild wanted to modify them, they had to explicitly append to them, + e.g. via +=. This was inconsistent with how some other variables + (but not all) were handled, and confusing to developers. For example, + consider the following snippet: +

+ + +EAPI=7 + +inherit git-r3 + +PROPERTIES+=" interactive" + + +

+ Note how you needed to append to PROPERTIES set by git-r3 eclass, + otherwise the ebuild would have overwritten it. In EAPI 8, you can finally + do the following instead: +

+ + +EAPI=8 + +inherit git-r3 + +PROPERTIES="interactive" + + +

+ Now the complete list of metadata variables accumulated across eclasses + and ebuilds includes: IUSE, REQUIRED_USE, *DEPEND, + PROPERTIES, RESTRICT. Variables that are not treated this way + are: EAPI, HOMEPAGE, SRC_URI, LICENSE, + KEYWORDS. EAPI and KEYWORDS are not supposed to be set + in eclasses; as for the others, there appears to be a valid use case for + eclasses providing default values and the ebuilds being able to override + them. +

+ + + + +EAPI 8 phase functions + + +

pkg_* phases now run in a dedicated empty directory

+ Before EAPI 8, the initial working directory was specified for src_* + phases only. For other phases (i.e. pkg_* phases), ebuilds were not + supposed to assume any particular directory. In EAPI 8, these phases are + guaranteed to be started in a dedicated empty directory. +

+ +

+ The idea of using an empty directory is pretty simple if there are no + files in it, the risk of unexpected and hard to predict interactions of + tools with their current working directory is minimized. +

+ PATCHES no longer permits options +

+ The eapply invocation in the default src_prepare + implementation has been changed to: +

+ + +eapply -- "${PATCHES[@]}" + + +

+ This ensures that all items in the PATCHES variable are treated + as path names. As a side effect, it is no longer possible to specify + patch options via the PATCHES variable. Such hacks were never + used in the Gentoo repository but they have been spotted in + user-contributed ebuilds. The following will no longer work: +

+ + +PATCHES=( -p0 "${FILESDIR}"/${P}-foo.patch ) + + +

+ Instead, you will need to invoke eapply explicitly, see the example + below. Alternatively, rebase the patch level. +

+ + +src_prepare() { + eapply -p0 "${FILESDIR}"/${P}-foo.patch + eapply_user +} + + +

+ + + + +EAPI 8 commands + + +

New econf-passed options

+ The econf helper has been modified to pass two more options to + the configure script if the --help text indicates that they are + supported. These are: +

+ +

--datarootdir="${EPREFIX}"/usr/share
--disable-static

+ +

+ The former option defines the base directory that is used to determine + locations for system/desktop-specific data files, e.g. .desktop files and + various kinds of documentation. This is necessary for ebuilds that override + --prefix, as the default path is relative to it. +

+ +

+ The latter option disables building static libraries by default. This is + part of the ongoing effort to disable unconditional install of static + libraries + ( + Gentoo Policy Guide, Installation of static libraries). +

dosym -r to create relative symlinks

+ Relative symlink targets tend to be more reliable. Consider the two + following examples: +

+ + +dosym "${EPREFIX}"/usr/lib/frobnicate/frobnicate /usr/bin/frobnicate +dosym ../lib/frobnicate/frobnicate /usr/bin/frobnicate + + +

+ The first line creates a symlink using an absolute path. The problem with + that is if you mount your Gentoo system in a subdirectory of your root + filesystem (e.g. for recovery), the symlink will point at the wrong + location. Using relative symlinks (as demonstrated on the second line) + guarantees that the symlink will work independently of where the filesystem + is mounted. +

+ +

+ There is also fact that you need to explicitly prepend ${EPREFIX} + to the absolute paths passed as the first argument of dosym. Using + a relative target avoids the problem altogether and makes it less likely to + forget about the prefix. +

+ +

+ However, in some instances, determining the relative path could be hard or + inconvenient. This is especially the case if one (or both) of the paths + comes from an external tool. To make it easier, EAPI 8 adds a new -r + option that makes dosym create a relative symlink to the specified + path (similarly to ln -r): +

+ + +dosym -r /usr/lib/frobnicate/frobnicate /usr/bin/frobnicate + + +

+ Note that in this case, you do not pass ${EPREFIX}. The helper + determines the logical relative path to the first argument and + creates the appropriate relative symlink. It is very important here to + understand that this function does not handle physical paths, i.e. it will + work only if there are no directory symlinks along the way that would + result in .. resolving to a different path. For example, the + following will not work: +

+ + +dosym bar/foo /usr/lib/foo +dosym -r /usr/lib/zomg /usr/lib/foo/zomg + + +

+ The logical path from /usr/lib/foo/zomg to /usr/lib/zomg is + ../zomg. However, since /usr/lib/foo is actually a symlink to + /usr/lib/bar/foo, /usr/lib/foo/.. resolves to + /usr/lib/bar. If you need to account for such directory symlinks, + you need to specify the correct path explicitly: +

+ + +dosym bar/foo /usr/lib/foo +dosym ../../zomg /usr/lib/foo/zomg + + +

+ insopts and exeopts now apply to doins + and doexe only +

+ In previous EAPIs, there was an inconsistency in how insopts and + exeopts applied to various helpers. In particular, the majority of + helpers (e.g. dobin, dodoc and so on) ignored the options + specified via these helpers but a few did not. +

+ +

+ EAPI 8 changes the behaviour of the following helpers that used to respect + insopts or exeopts: +

+ +

doconfd
doenvd
doheader
doinitd

+ +

+ In EAPI 8, they always use the default options. As a result, insopts + now only affects doins/newins, and exeopts only + affects doexe/newexe. Furthermore, diropts does not + affect the directories implicitly created by these helpers. +

usev now accepts a second argument

+ The usev helper was introduced to provide the historical Portage + behaviour of outputting the USE flag name on match. In EAPI 8, it has been + extended, in order to provide an alternative to three-argument usex + with an empty third argument (the two-argument usex variant uses a + default of no for the false branch). +

+ +

+ In other words, the following two calls are now equivalent: +

+ + +$(usex foo --enable-foo '') +$(usev foo --enable-foo) + + +

+ This is particularly useful with custom build systems that accept + individual --enable or --disable options but not their + counterparts. +

+ +

+ As a result, usev and usex can now be used to achieve all the + common (and less common) output needs as summarized in the following table. +

+ + + + + + + + + usev flag + flag + + + + usev flag true + true + + + + usex flag + yes + no + + + usex flag true + true + no + + + usex flag true false + true + false + +

Variant	True	False

hasq, hasv and useq functions have been banned

+ In its early days, the use helper would print the USE flag name + if it matched, in addition to its boolean exit status. Later, a quiet + useq and a verbose usev helper were added, and use was + made quiet by default. The same changes were applied to has. +

+ +

+ Fast forward to EAPI 7, there are still three variants of use + and three variants of has. The base variant that is quiet, the + useq/hasq variant that is equivalent to the base variant, + and the verbose usev/hasv variant. +

+ +

+ Obviously, adding a second argument to hasv was not possible, so its + behaviour would have become inconsistent with usev in EAPI 8. Since + hasv was not used in the Gentoo repository, it has been removed, + along with hasq and useq which were considered deprecated + since 2011. +

unpack removes support for 7-Zip, LHA and RAR formats

+ Support for the least commonly used archive formats from unpack has + been removed: +

+ +

7-Zip (.7z)
LHA (.lha, .lzh)
RAR (.rar)

+ +

+ Packages using these format for distfiles must now unpack them manually. + Using unpacker.eclass is recommended for this. +