diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml index 584ce67c..a643c6d5 100644 --- a/ebuild-writing/eapi/text.xml +++ b/ebuild-writing/eapi/text.xml @@ -1428,6 +1428,322 @@ $(usev foo --enable-foo) + + + + +
+EAPI 9 + + + +This section is based on the + +EAPI Cheat Sheet. + + + + +EAPI 9 profiles + + +
+
Default EAPI for profiles
+
+ Profile directories that don't contain an own eapi file no longer + default to EAPI 0, but to the EAPI specified in the top-level + profiles directory. +
+ +
use.stable and package.use.stable
+
+ Profile dirs may contain two new files use.stable and + package.use.stable. They can be used to override the USE flags + specified by make.defaults, but act only on packages that would be + merged due to a stable keyword. + + The format of the use.stable file is simple: Each line contains a + USE flag to enable; a minus sign before the flag indicates that the flag + should be disabled instead. + + The package.use.stable file has the same format as package.use + (see make.conf(5)). + + USE_EXPAND values may be enabled or disabled by using + expand_name_value. + + Flags listed in package.use.stable take precedence over these listed + in package.use, which in turn take precedence over use.stable. +
+
+ + + + + +EAPI 9 ebuild format + + +
+
Bash version is now 5.3
+
+

+ Ebuilds can use Bash version 5.3 (was 5.0 before). + Some notable new features are: +

+ +
    +
  • +

    + declare and local now have a -I option that + inherits the attributes and value from of any existing variable with + the same name at a surrounding scope. For example, an ebuild could do +

    + +local -Ix ROOT + +

    + to export the ROOT variable to the environment, from where an + external could get its value. +

    +
    • + +
  • +

    + There is a new form of command substitution: ${ command; } or + ${|command;} to capture the output of command without + forking a child process and using pipes. +

    +

    + ${ command; } executes command in the current execution + environment and captures its output. Any side effects of command + take effect immediately in the current execution environment and + persist after the command completes. This type of command substitution + superficially resembles executing an unnamed shell function: local + variables are created as when a shell function is executing, and the + return builtin forces command to complete; however, the + rest of the execution environment is shared with the caller. +

    +

    + The ${|command;} construct expands to the value of the + REPLY shell variable after command executes, without + removing any trailing newlines, and the standard output of + command remains the same as in the calling shell. Bash creates + REPLY as an initially-unset local variable when command + executes, and restores REPLY to its old value after + command completes, as with any local variable. +

    +

    + For example, this construct expands to 12345, and leaves the + shell variable X unchanged in the current execution environment: +

    + +${ local X=12345; echo $X; } + +

    + while the following construct does not require any output to expand to + 12345 and restores REPLY to the value it had before the + command substitution: +

    + +${| REPLY=12345; } + +
    • + +
  • +

    + Pattern substitution now duplicates a common sed idiom: + If the patsub_replacement shell option is enabled (which it is + by default), any unquoted & in the replacement string is + replaced with the portion of the string that matched the pattern. +

    +

    + For instance: +

    + +var="foobar" +echo "${var/foo/&123}" + +

    + will print foo123bar, i.e. the & in the replacement + string is replaced with the string foo that matched the pattern. +

    +

    + A backslash can be used to escape the & and insert a literal + & in the replacement string. +

    +
    • +
+
+
+ + + + + +EAPI 9 variables + + +
+
Variables are no longer exported
+
+

+ The package manager no longer exports its defined shell variables to the + environment but keeps them as unexported shell variables, namely: +

+
    +
  • + CATEGORY, P, PF, PN, PV, PR, + PVR +
    • +
  • A
    • +
  • + FILESDIR, DISTDIR, WORKDIR, S, ROOT, + EROOT, SYSROOT, ESYSROOT, BROOT, T, + EPREFIX, D, ED +
    • +
  • USE
    • +
  • EBUILD_PHASE, EBUILD_PHASE_FUNC
    • +
  • MERGE_TYPE
    • +
  • REPLACING_VERSIONS, REPLACED_BY_VERSION
    • +
  • ECLASS, INHERITED, DEFINED_PHASES
    • +
+ + Exceptions are TMPDIR and HOME which are always exported. + +

+ The same applies to variables set in make.defaults that have + specific meanings or special handling. These are no longer exported to the + environment of an EAPI 9 ebuild: +

+
    +
  • ARCH
    • +
  • CONFIG_PROTECT, CONFIG_PROTECT_MASK
    • +
  • + USE, USE_EXPAND, USE_EXPAND_UNPREFIXED, + USE_EXPAND_HIDDEN, USE_EXPAND_IMPLICIT, + IUSE_IMPLICIT +
    • +
  • ENV_UNSET
    • +
  • + All variables named in USE_EXPAND and + USE_EXPAND_UNPREFIXED +
    • +
  • + All USE_EXPAND_VALUES_${v} variables, where ${v} is a + value in USE_EXPAND_IMPLICIT +
    • +
+

+ All other variables set in make.defaults will still be exported to + the environment. +

+

+ As a consequence, external commands can no longer rely on the value of the + ROOT variable in the environment. For example, eselect must + be called with the --root option in EAPI 9: +

+ +pkg_postinst() { + eselect --root="${ROOT}" emacs update ifunset +} + +
+
+ + + + + +EAPI 9 commands + + +
+
assert has been banned
+
+ Our definition of assert deviated from the semantics of the command + in mainstream programming languages and was a source of confusion. + Therefore, use of the assert command in ebuilds is no longer + allowed. pipestatus (see below) should be used as replacement. +
+ +
domo has been banned
+
+ The operation of the domo command was unintuitive. It also hardcoded + ${PN} as the gettext domain, which is often not what is wanted. + Therefore, the domo command has been banned. insinto plus + newins should be used as replacement. +
+ +
pipestatus
+
+ Checks if all commands in the last executed pipeline have returned an exit + status of zero. When the -v option is specified, also prints the + shell's pipe status array. + +foo | bar | baz +pipestatus || die + +
+ +
ver_replacing op v2
+
+

+ Checks if the relation v1 op v2 is true for at least one element + v1 of REPLACING_VERSIONS. op can be any operator that + is accepted by ver_test. Returns shell true (0) if the specified + relation holds for at least one element, shell false (1) otherwise. + In particular, shell false is returned when REPLACING_VERSIONS + is empty. +

+

+ Obviously, ver_replacing is only meaningful in phases where + REPLACING_VERSIONS is defined, i.e. in pkg_preinst and + pkg_postinst. +

+ +pkg_postinst() { + if ver_replacing -lt 3; then + elog "This is a major upgrade and may break your existing setup!" + fi +} + +
+ +
edo
+
+ Outputs its entire argument list as an informational message, then executes + it as a simple shell command, with standard failure behaviour. +
+
+ + + + + +EAPI 9 merging and unmerging + + +
+
Merging of symlinks
+
+

+ When merging D to ROOT, absolute symlinks are now merged + as-is. The package manager will no longer strip a leading D from + their link targets. +

+

+ In previous EAPIs, any absolute symlink whose link target started with + ${D} was rewritten with the leading ${D} removed. + That behaviour was ill-defined because D is not guaranteed to have + the same value that it had in the src_* phases. For example, when + a binary package was merged on a target host with PORTAGE_TMPDIR + different from the build host's PORTAGE_TMPDIR, symlink rewriting + would have failed. +

+
+
+
diff --git a/xsl/lang.highlight.ebuild.xsl b/xsl/lang.highlight.ebuild.xsl index 222ba08e..cfb8b71b 100644 --- a/xsl/lang.highlight.ebuild.xsl +++ b/xsl/lang.highlight.ebuild.xsl @@ -18,11 +18,11 @@ - assert best_version debug-print debug-print-function debug-print-section die diropts dobin docinto doconfd dodir - dodoc doenvd doexe doinfo doinitd doins dolib.a dolib.so doman domo dosbin dosym ebegin econf eend eerror einfo - einfon elog emake ewarn exeinto exeopts EXPORT_FUNCTIONS fowners fperms has has_version inherit insinto insopts into - keepdir newbin newconfd newdoc newenvd newexe newinitd newins newlib.a newlib.so newman newsbin unpack use usev - use_enable use_with + best_version debug-print debug-print-function debug-print-section die diropts dobin docinto doconfd dodir dodoc + doenvd doexe doinfo doinitd doins dolib.a dolib.so doman dosbin dosym ebegin econf eend eerror einfo einfon elog + emake ewarn exeinto exeopts EXPORT_FUNCTIONS fowners fperms has has_version inherit insinto insopts into keepdir + newbin newconfd newdoc newenvd newexe newinitd newins newlib.a newlib.so newman newsbin unpack use usev use_enable + use_with docompress nonfatal @@ -32,6 +32,8 @@ dostrip eqawarn ver_cut ver_rs ver_test + + edo pipestatus ver_replacing adddeny addpredict addread addwrite @@ -113,11 +115,29 @@ - ${} - - - - + + + + ${ + + + + ${} + + + + + + + + Warning: No closing brace in + ${ + + + + + +