diff options
| author |   Ulrich Müller <ulm@gentoo.org> | 2020-02-08 20:43:23 +0100 |
|---|---|---|
| committer | Ulrich Müller <ulm@gentoo.org> | 2020-02-11 12:38:00 +0100 |
| commit | 3b8fa72d91bbdd08aa08f7e7bf0ca66833095186 (patch) | |
| tree | ac5d3a0407786a7c860d006d1f50d934647ec504 | |
| parent | Makefile: Remove quirks necessary for installing in-place. (diff) | |
| download | devmanual-3b8fa72d.tar.gz devmanual-3b8fa72d.tar.bz2 devmanual-3b8fa72d.zip | |
ebuild-writing/eapi: Move EAPI=4 information to other sections.
- Utilities die, nonfatal: New section in ebuild-writing/error-handling,
new chapter function-reference/error-functions
- dodoc -r: Already in function-reference/install-functions,
add additional example to ebuild-writing/functions/src_install
- doins symlink support:
Incorporated into function-reference/install-functions
- dosed, dohard banned: Not mentioned anywhere else
- econf --disable-dependency-tracking: New section about econf options
in ebuild-writing/functions/src_configure/configuring
- Controllable compression and docompress:
New chapter ebuild-writing/functions/src_install/docompress
- USE dependency defaults: Incorporated into general-concepts/dependencies
- pkg_pretend: Already in ebuild-writing/functions/pkg_pretend
- default src_install: Already in ebuild-writing/functions/src_install
- pkg_info: Incorporated into ebuild-writing/functions/pkg_info
- REQUIRED_USE: Already in ebuild-writing/variables
- MERGE_TYPE, REPLACING_VERSIONS, REPLACED_BY_VERSION:
Moved to ebuild-writing/variables
- DOCS: Incorporated into ebuild-writing/variables
- AA, KV removed: Not mentioned anywhere else
- RDEPEND=DEPEND: Already handled in commit 5a946b4
Signed-off-by: Ulrich Müller <ulm@gentoo.org>
| -rw-r--r-- | ebuild-writing/eapi/text.xml | 333 | ||||
| -rw-r--r-- | ebuild-writing/error-handling/text.xml | 32 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_info/text.xml | 16 | ||||
| -rw-r--r-- | ebuild-writing/functions/pkg_pretend/text.xml | 2 | ||||
| -rw-r--r-- | ebuild-writing/functions/src_configure/configuring/text.xml | 51 | ||||
| -rw-r--r-- | ebuild-writing/functions/src_install/docompress/text.xml | 51 | ||||
| -rw-r--r-- | ebuild-writing/functions/src_install/text.xml | 25 | ||||
| -rw-r--r-- | ebuild-writing/functions/text.xml | 2 | ||||
| -rw-r--r-- | ebuild-writing/variables/text.xml | 44 | ||||
| -rw-r--r-- | function-reference/build-functions/text.xml | 5 | ||||
| -rw-r--r-- | function-reference/error-functions/text.xml | 50 | ||||
| -rw-r--r-- | function-reference/install-functions/text.xml | 14 | ||||
| -rw-r--r-- | function-reference/text.xml | 1 | ||||
| -rw-r--r-- | general-concepts/dependencies/text.xml | 20 | ||||
| -rw-r--r-- | general-concepts/use-flags/text.xml | 8 | ||||
| -rw-r--r-- | general-concepts/virtuals/text.xml | 2 |
16 files changed, 291 insertions, 365 deletions
diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml index 2a47617..57c899e 100644 --- a/ebuild-writing/eapi/text.xml +++ b/ebuild-writing/eapi/text.xml @@ -65,11 +65,11 @@ is the best. Using the features of the latest EAPI is encouraged. </section> <section> -<title>EAPIs 0 to 3</title> +<title>EAPIs 0 to 4</title> <body> <p> -EAPIs 0 to 3 are obsolete and must no longer be used. Refer to the Package +EAPIs 0 to 4 are obsolete and must no longer be used. Refer to the Package Manager Specification for details about them. </p> @@ -77,335 +77,6 @@ Manager Specification for details about them. </section> <section> -<title>EAPI=4</title> -<body> - -<todo> -Split up and move each feature to the section that is relevant for it. -</todo> - -</body> - -<subsection> -<title>EAPI 4 Helpers</title> -<body> -<ul> - <li> - <p><b>utilities die on their own, unless the nonfatal command is used</b></p> - <p> - <!-- TODO link auf fuunction-reference --> - Ebuild functions all die on their own in EAPI=4. In case that this - non-zero exit status is expected, you may call <c>nonfatal function - [arg,...]</c>. - </p> - <p>Example:</p> -<codesample lang="ebuild"> -EAPI=2 -... -src_test() { - if ! emake check ; then - local a - eerror "Tests failed. Looking for files for you to add to your bug report..." - while IFS='' read -r -d $'\0' a ; do - eerror " ${a}" - done < <(find "${S}" -type f '(' -name '*.epicfail' -o -name '*.log' ')' -print0) - die "Make check failed" - fi -} -</codesample> -<codesample lang="ebuild"> -EAPI=4 -... -src_test() { - if ! nonfatal emake check ; then - local a - eerror "Tests failed. Looking for files for you to add to your bug report..." - while IFS='' read -r -d $'\0' a ; do - eerror " ${a}" - done < <(find "${S}" -type f '(' -name '*.epicfail' -o -name '*.log' ')' -print0) - die "Make check failed" - fi -} -</codesample> - </li> - <li> - <p><b>recursive dodoc</b></p> - <p> - <c>dodoc</c> supports <c>-r</c> as the first argument, which leads - <c>dodoc</c> to install the specified documentation directory - recursively into the docdir. - </p> - <p>Example:</p> -<codesample lang="ebuild"> -src_install() { - default - dodoc ChangeLog - dodoc -r doc/ -} -</codesample> - </li> - <li> - <p><b>doins symlink supports</b></p> - <p> - Within EAPI=4, <c>doins</c> supports installing symlinks as symlinks - when installing recursively. For older EAPIs, the symlink behaviour - is undefined. - </p> - </li> - <li> - <p><b>dosed and dohard are banned</b></p> - <p> - The <c>dosed</c> and <c>dohard</c> commands are banned in this EAPI. - </p> - </li> - <li> - <p><b>econf adds --disable-dependency-tracking</b></p> - <p> - Within EAPI=4, <c>econf</c> adds - <c>--disable-dependency-tracking</c> to the default configure - options. - </p> - </li> - <li> - <p><b>controllable compression via docompress</b></p> - <p> - To compress files in the destination-folder <c>${D}</c>, the - <c>docompress</c> command may be used in <c>src_install</c>. - To control which items should be compressed and which shouldn't - be compressed, you may include or exclude directories or plain - files. The default inclusion list contains: - </p> - <ul> - <li><c>/usr/share/doc</c></li> - <li><c>/usr/share/info</c></li> - <li><c>/usr/share/man</c></li> - </ul> - <p> - The default exclusion list contains: - </p> - <ul> - <li><c>/usr/share/doc/${PF}/html</c></li> - </ul> - <p> - When a directory is in- or excluded, all files and directories in - the given directories shall be added to the corresponding list. - If a file is in- or excluded, the file shall be added to the - corresponding list (exclusion is stronger than inclusion <d/> - if a file is in both lists, the inclusion will be ignored). - </p> - <p> - If the first argument of <c>docompress</c> is <c>-x</c>, the items - specified will be added to the exclusion list, otherwise they will - be added to the inclusion list. - </p> - <note> - When <c>docompress</c> is called, it is <e>not</e> required that - the paths specified as its arguments are pointing to existing files - or directories. However, if a file still doesn't exist when - <c>src_install</c> has completed, it will be ignored with a - warning. - </note> - </li> -</ul> -</body> -</subsection> - -<subsection> -<title>EAPI 4 Metadata</title> -<body> -<ul> - <li> - <p><b>use dependencies default</b></p> - <p> - In addition to the use-deps specified in EAPI=2, a <c>(+)</c> or - <c>(-)</c> may be added to the use-dep to define a default-value in - case the use-flag does not exist in the given package. The - <c>(+)</c> means that this use-flag is assumed to be enabled, - <c>(-)</c> the opposite. - </p> - <p>Example:</p> -<codesample lang="ebuild"> -DEPEND=" - >=dev-libs/boost-1.32[boost(+)] - sys-devel/gcc[openmp(-)]" -</codesample> - </li> -</ul> -</body> -</subsection> - -<subsection> -<title>EAPI 4 Phases</title> -<body> -<ul> - <li> - <p><b>new pkg_pretend phase</b></p> - <p> - The new <c>pkg_pretend</c> phase can be used to do sanity checks - before the main phase function sequence is run (meaning this phase is - executed after the package manager has calculated the dependencies - and before installing them). - This phase typically checks for a kernel configuration and may - <c>eerror</c> and <c>die</c> when needed. - </p> - <important> - There is no guarantee that the ebuild's dependencies are installed - when this phase is called. - </important> - <important> - As <c>pkg_pretend</c> is not called in the main phase function - sequence, environment saving is not guaranteed. - </important> - <p>Example:</p> -<codesample lang="ebuild"> -# Copyright 1999-2020 Gentoo Authors -# Distributed under the terms of the GNU General Public License v2 - -EAPI=4 -inherit linux-info -... - -CONFIG_CHECK="FUSE_FS" -ERROR_FUSE_FS="this is an unrealistic testcase..." - -pkg_pretend() { - if use kernel_linux ; then - if [[ -e "${ROOT}"/usr/src/linux/.config ]] ; then - if kernel_is lt 2 6 30 ; then - check_extra_config - fi - fi - fi -} -</codesample> - </li> - <li> - <p><b>default src_install is no longer a no-op</b></p> - <p> - The default <c>src_install</c> function in EAPI=4: - </p> -<codesample lang="ebuild"> -src_install() { - if [[ -f Makefile ]] || [[ -f GNUmakefile]] || [[ -f makefile ]] ; then - emake DESTDIR="${D}" install - fi - - if ! declare -p DOCS >/dev/null 2>&1 ; then - local d - for d in README* ChangeLog AUTHORS NEWS TODO CHANGES THANKS BUGS \ - FAQ CREDITS CHANGELOG ; do - [[ -s "${d}" ]] && dodoc "${d}" - done - elif declare -p DOCS | grep -q "^declare -a " ; then - dodoc "${DOCS[@]}" - else - dodoc ${DOCS} - fi -} -</codesample> - </li> - <li> - <p><b>pkg_info for non-installed packages</b></p> - <p> - The <c>pkg_info</c> function may also be called by the - package manager for non-installed packages. - Ebuild writers should note that dependencies may not be - available. - </p> - </li> -</ul> -</body> -</subsection> - -<subsection> -<title>EAPI 4 Variables</title> -<body> -<ul> - <li> - <p><b>REQUIRED_USE</b></p> - <p> - The <c>REQUIRED_USE</c> variable contains a list of assertions that - must be met by the configuration of USE flags to be valid for this - ebuild. In order to be matched, a USE flag in a terminal element - must be enabled (or disabled if it has an exclamation mark prefix). - </p> - <p> - See <uri link="::ebuild-writing/variables#REQUIRED_USE"/> - </p> - </li> - <li> - <p><b>REPLACING_VERSIONS and REPLACED_BY_VERSION</b></p> - <p> - The <c>REPLACING_VERSIONS</c> variable contains a - whitespace-separated list of all versions (<c>PVR</c>) of this - package that are being replaced (uninstalled or overwritten) as a - result of this install. It is a list, not a single optional value, - to handle pathological cases such as installing <c>foo-2:2</c> to - replace <c>foo-2:1</c> and <c>foo-3:2</c>. - </p> - <p> - <c>REPLACING_VERSIONS</c> is valid in <c>pkg_preinst</c> and - <c>pkg_postinst</c>. In addition, it may be available in - <c>pkg_pretend</c> and <c>pkg_setup</c>, although you should take - care to handle binary package creation and installation correctly - when using it in these phases. - </p> - <p> - The <c>REPLACED_BY_VERSION</c> variable contains the single version - (<c>PVR</c>) of this package that is replacing us, if we are being - uninstalled as part of an install, or an empty string otherwise. - It is valid in <c>pkg_prerm</c> and <c>pkg_postrm</c>. - </p> - </li> - <li> - <p><b>MERGE_TYPE</b></p> - <p> - The <c>MERGE_TYPE</c> variable contains the type of package that - is being merged. Possible values are: - </p> - <dl> - <dt><c>source</c></dt> - <dd> - if building and installing a package from source, - </dd> - <dt><c>binary</c></dt> - <dd> - if installing a binary package, - </dd> - <dt><c>buildonly</c></dt> - <dd> - if building a binary package without installing it. - </dd> - </dl> - </li> - <li> - <p><b>DOCS</b></p> - <p> - The <c>DOCS</c> variable is an array or whitespace-separated list - of documentation files for the default <c>src_install</c> function - to install using <c>dodoc</c>. If undefined, a reasonable default - list is used. See the default <c>src_install</c> function above. - </p> - </li> - <li> - <p><b>AA and KV variables are gone</b></p> - <p> - The <c>AA</c> and <c>KV</c> variables are no longer set in EAPI=4. - </p> - </li> - <li> - <p><b>no more RDEPEND="${DEPEND}"</b></p> - <p> - When <c>RDEPEND</c> is unset, there will no longer be an automatic - assignment of <c>RDEPEND="${DEPEND}"</c>. - </p> - </li> -</ul> -</body> -</subsection> -</section> - -<section> <title>EAPI=5</title> <subsection> diff --git a/ebuild-writing/error-handling/text.xml b/ebuild-writing/error-handling/text.xml index 35c7419..f74f6d8 100644 --- a/ebuild-writing/error-handling/text.xml +++ b/ebuild-writing/error-handling/text.xml @@ -47,10 +47,9 @@ function can die in multiple places. </p> <p> -Ebuild helpers from EAPI 4 and onwards automatically die on -failure. Some eclass-provided functions will automatically die upon -failure, others will not. Developers should check the -<uri link="::eclass-reference/">eclass reference</uri> when in doubt. +Ebuild helpers automatically die on failure. Some eclass-provided functions +will automatically die upon failure, others will not. Developers should check +the <uri link="::eclass-reference/">eclass reference</uri> when in doubt. </p> <p> @@ -135,5 +134,30 @@ time, <c>assert</c> is enough. </body> </section> +<section> +<title>The <c>nonfatal</c> Command</title> +<body> + +<p> +If a non-zero exit status from an ebuild helper function is expected, you may +call it under the <c>nonfatal</c> function. Instead of dying on failure, +the command will then return non-zero exit status, as in the following example: +</p> + +<codesample lang="ebuild"> +src_test() { + if ! nonfatal emake check ; then + local a + eerror "Tests failed. Looking for files to add to your bug report..." + while IFS='' read -r -d $'\0' a ; do + eerror " ${a}" + done < <(find "${S}" -type f -name '*.log' -print0) + die "Make check failed" + fi +} +</codesample> + +</body> +</section> </chapter> </guide> diff --git a/ebuild-writing/functions/pkg_info/text.xml b/ebuild-writing/functions/pkg_info/text.xml index 8cb3dbb..c6e0432 100644 --- a/ebuild-writing/functions/pkg_info/text.xml +++ b/ebuild-writing/functions/pkg_info/text.xml @@ -54,15 +54,19 @@ pkg_info() { <section> <title>Notes on <c>pkg_info</c></title> <body> + +<p> +This phase will be called when a package manager displays information about +a package. +</p> + <p> -this phase will be called when a package manager displays -information about a package. -within EAPI=4, this phase can also be called for non-installed -packages. +The <c>pkg_info</c> function may also be called by the package manager for +non-installed packages. Ebuild writers should note that dependencies may not be +available. </p> + </body> </section> - </chapter> </guide> - diff --git a/ebuild-writing/functions/pkg_pretend/text.xml b/ebuild-writing/functions/pkg_pretend/text.xml index e21a1c2..89eb269 100644 --- a/ebuild-writing/functions/pkg_pretend/text.xml +++ b/ebuild-writing/functions/pkg_pretend/text.xml @@ -67,7 +67,7 @@ pkg_pretend() { <title>Notes on <c>pkg_pretend</c></title> <body> <p> -the <c>pkg_pretend</c> phase can be used to do sanity checks +The <c>pkg_pretend</c> phase can be used to do sanity checks before the main phase function sequence is run (meaning this phase is executed after the package manager has calculated the dependencies and before installing them). diff --git a/ebuild-writing/functions/src_configure/configuring/text.xml b/ebuild-writing/functions/src_configure/configuring/text.xml index a31dc4e..86657bc 100644 --- a/ebuild-writing/functions/src_configure/configuring/text.xml +++ b/ebuild-writing/functions/src_configure/configuring/text.xml @@ -74,5 +74,56 @@ form can be used. </p> </body> +<section> +<title><c>econf</c> Options</title> +<body> + +<p> +<c>econf</c> is designed to work with configure scripts generated by +GNU Autoconf. It first passes the default options listed below to the configure +script, followed by any additional parameters passed to <c>econf</c>. +</p> + +<ul> + <li><c>--prefix="${EPREFIX}"/usr</c></li> + <li><c>--mandir="${EPREFIX}"/usr/share/man</c></li> + <li><c>--infodir="${EPREFIX}"/usr/share/info</c></li> + <li><c>--datadir="${EPREFIX}"/usr/share</c></li> + <li><c>--sysconfdir="${EPREFIX}"/etc</c></li> + <li><c>--localstatedir="${EPREFIX}"/var/lib</c></li> + <li> + <c>--build="${CBUILD}"</c> (only passed if <c>CBUILD</c> is non-empty) + </li> + <li><c>--host="${CHOST}"</c></li> + <li> + <c>--target="${CTARGET}"</c> (only passed if <c>CTARGET</c> is non-empty) + </li> + <li> + <c>--libdir</c> is set from the value of the <c>LIBDIR_${ABI}</c> variable + in profiles. + </li> + <li><c>--disable-dependency-tracking</c></li> + <li><c>--disable-silent-rules</c></li> +</ul> + +<p> +In EAPI 6 and later, the following options are passed in addition: +</p> + +<ul> + <li><c>--docdir="${EPREFIX}"/usr/share/doc/${PF}</c></li> + <li><c>--htmldir="${EPREFIX}"/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +In EAPI 7 and later, the following option is passed in addition: +</p> + +<ul> + <li><c>--with-sysroot="${ESYSROOT:-/}"</c></li> +</ul> + +</body> +</section> </chapter> </guide> diff --git a/ebuild-writing/functions/src_install/docompress/text.xml b/ebuild-writing/functions/src_install/docompress/text.xml new file mode 100644 index 0000000..93478b4 --- /dev/null +++ b/ebuild-writing/functions/src_install/docompress/text.xml @@ -0,0 +1,51 @@ +<?xml version="1.0"?> +<guide self="ebuild-writing/functions/src_install/docompress/"> +<chapter> +<title>Controllable Compression</title> +<body> + +<p> +You can call the <c>docompress</c> function in <c>src_install</c> to control +which items in the destination folder <c>${D}</c> should be compressed and +which shouldn't be compressed. You can include or exclude directories or plain +files. The default inclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc</c></li> + <li><c>/usr/share/info</c></li> + <li><c>/usr/share/man</c></li> +</ul> + +<p> +The default exclusion list contains: +</p> + +<ul> + <li><c>/usr/share/doc/${PF}/html</c></li> +</ul> + +<p> +When a directory is in- or excluded, all files and directories in the given +directories shall be added to the corresponding list. If a file is in- or +excluded, the file shall be added to the corresponding list (exclusion is +stronger than inclusion <d/> if a file is in both lists, the inclusion will +be ignored). +</p> + +<p> +If the first argument of <c>docompress</c> is <c>-x</c>, the items specified +will be added to the exclusion list, otherwise they will be added to the +inclusion list. +</p> + +<note> +When <c>docompress</c> is called, it is <e>not</e> required that the paths +specified as its arguments are pointing to existing files or directories. +However, if a file still doesn't exist when <c>src_install</c> has completed, +it will be ignored with a warning. +</note> + +</body> +</chapter> +</guide> diff --git a/ebuild-writing/functions/src_install/text.xml b/ebuild-writing/functions/src_install/text.xml index 02981ff..010638b 100644 --- a/ebuild-writing/functions/src_install/text.xml +++ b/ebuild-writing/functions/src_install/text.xml @@ -109,10 +109,16 @@ Usually the package's build system will not install the <c>README</c>, </p> <codesample lang="ebuild"> - emake DESTDIR="${D}" install - dodoc README CHANGES + emake DESTDIR="${D}" install + dodoc README CHANGES + dodoc -r doc </codesample> +<p> +<c>dodoc</c> supports <c>-r</c> as the first argument, which allows directories +to be installed recursively. +</p> + <note> There is no need to <c>dodoc</c> <c>COPYING</c>! The license belongs to <c>${PORTDIR}/licenses</c>. Sometimes though, you might want to @@ -215,5 +221,20 @@ upstream explaining the situation to them. </body> </section> +<section> +<title><c>src_install</c> Processes</title> +<body> + +<p> +The following subsections cover different topics which often occur when writing +<c>src_install</c> functions. +</p> + +<contentsTree/> + +</body> +</section> </chapter> + +<include href="docompress/"/> </guide> diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml index e2167e6..3899aca 100644 --- a/ebuild-writing/functions/text.xml +++ b/ebuild-writing/functions/text.xml @@ -6,7 +6,7 @@ <body> <p> When installing packages from source, the function call order is -<c>pkg_pretend</c> (for EAPI=4 and later), <c>pkg_setup</c>, +<c>pkg_pretend</c>, <c>pkg_setup</c>, <c>src_unpack</c>, <c>src_prepare</c>, <c>src_configure</c>, <c>src_compile</c>, <c>src_test</c> (optional, <c>FEATURES="test"</c>), <c>src_install</c>, <c>pkg_preinst</c>, <c>pkg_postinst</c>. When installing packages diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index 81d4c44..b0c15d9 100644 --- a/ebuild-writing/variables/text.xml +++ b/ebuild-writing/variables/text.xml @@ -153,6 +153,35 @@ for these variables when writing ebuilds. satisfied by <c>BDEPEND</c>, typically executable build tools. </ti> </tr> + <tr> + <ti><c>MERGE_TYPE</c></ti> + <ti> + The type of package that is being merged. Possible values are: + <c>source</c> if building and installing a package from source, + <c>binary</c> if installing a binary package previously built from + the ebuild, <c>buildonly</c> if building a binary package without + installing it. + </ti> + </tr> + <tr> + <ti><c>REPLACING_VERSIONS</c></ti> + <ti> + A whitespace-separated list of all versions (<c>PVR</c>) of this package + that are being replaced (uninstalled or overwritten) as a result of this + install. It is a list, not a single optional value, to handle pathological + cases such as installing <c>foo-2:2</c> to replace <c>foo-2:1</c> and + <c>foo-3:2</c>. Available in <c>pkg_preinst</c> and <c>pkg_postinst</c>. + </ti> + </tr> + <tr> + <ti><c>REPLACED_BY_VERSION</c></ti> + <ti> + The single version (<c>PVR</c>) of this package that is replacing the + version provided by this ebuild, if it is being uninstalled as part of + an install. An empty string otherwise, i.e., if it is being uninstalled + without replacement. Available in <c>pkg_prerm</c> and <c>pkg_postrm</c>. + </ti> + </tr> </table> </body> @@ -238,9 +267,9 @@ The following variables may or must be defined by every ebuild. <tr> <ti><c>REQUIRED_USE</c></ti> <ti> - A list of assertions that must be met by the configuration of - <c>USE</c> flags to be valid for this ebuild. (Requires EAPI>=4.) - See <uri link="::ebuild-writing/variables#REQUIRED_USE"/>. + A list of assertions that must be met by the configuration of <c>USE</c> + flags to be valid for this ebuild. + See <uri link="::ebuild-writing/variables/#REQUIRED_USE"/>. </ti> </tr> <tr> @@ -300,10 +329,11 @@ The following variables may or must be defined by every ebuild. <tr> <ti><c>DOCS</c></ti> <ti> - An array or space-delimited list of documentation files for - the default src_install function to install using dodoc. If - undefined, a reasonable default list is used. (Requires - <uri link="::ebuild-writing/eapi/#EAPI=4">EAPI>=4</uri>.) + An array or whitespace-separated list of documentation files for + the default <c>src_install</c> function to install using <c>dodoc</c>. + If undefined, a reasonable default list is used. See the + <uri link="::ebuild-writing/functions/src_install/#Default src_install"> + default <c>src_install</c> function</uri>. </ti> </tr> <tr> diff --git a/function-reference/build-functions/text.xml b/function-reference/build-functions/text.xml index 798e4ab..646c75e 100644 --- a/function-reference/build-functions/text.xml +++ b/function-reference/build-functions/text.xml @@ -32,7 +32,10 @@ during the unpack and compile stages. <c>econf args</c> </ti> <ti> - Wrapper for <c>./configure</c>. Passes on all <c>args</c>. Will abort (via <c>die</c>) should <c>configure</c> fail. + Wrapper for <c>./configure</c>. Passes on all <c>args</c>. Will abort + (via <c>die</c>) should <c>configure</c> fail. + See <uri link="::ebuild-writing/functions/src_configure/configuring/#econf Options"/> + for details. </ti> </tr> <tr> diff --git a/function-reference/error-functions/text.xml b/function-reference/error-functions/text.xml new file mode 100644 index 0000000..70153eb --- /dev/null +++ b/function-reference/error-functions/text.xml @@ -0,0 +1,50 @@ +<?xml version="1.0"?> +<guide self="function-reference/error-functions/"> +<chapter> +<title>Error Functions Reference</title> +<body> + +<p> +The following functions are provided by the package manager for error handling. +</p> + +<table> + <tr> + <th>Function</th> + <th>Details</th> + </tr> + <tr> + <ti><c>die</c></ti> + <ti> + <p> + Displays an error message provided in its argument, and aborts the build + process. + </p> + <p> + In EAPI 6 and later, <c>die</c> can be called under the <c>nonfatal</c> + command and with the <c>-n</c> option, in which case it will not abort + the build process, but return with non-zero status. + </p> + </ti> + </tr> + <tr> + <ti><c>assert</c></ti> + <ti> + Checks the value of the <c>PIPESTATUS</c> array, and calls <c>die</c> + if any of its component is non-zero (which indicates failure of the + preceding command pipeline). + </ti> + </tr> + <tr> + <ti><c>nonfatal</c></ti> + <ti> + Takes another command as its argument and executes it. If the command + fails and would normally die, it returns with non-zero status instead + when called under <c>nonfatal</c>. + </ti> + </tr> +</table> + +</body> +</chapter> +</guide> diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml index a042480..7e0b540 100644 --- a/function-reference/install-functions/text.xml +++ b/function-reference/install-functions/text.xml @@ -128,8 +128,7 @@ the first is the source name, the second the name to use when installing. </ti> <ti> Install a documentation file into <c>/usr/share/doc/${PF}</c>. - For EAPI 4 and above, the <c>-r</c> option allows directories to - be installed recursively. + The <c>-r</c> option allows directories to be installed recursively. </ti> </tr> <tr> @@ -205,6 +204,8 @@ the first is the source name, the second the name to use when installing. <ti> Install a miscellaneous file. The <c>-r</c> option allows directories to be installed recursively. + Any symlinks encountered are installed as symlinks, when installing + recursively. </ti> </tr> <tr> @@ -409,6 +410,15 @@ the first is the source name, the second the name to use when installing. </tr> <tr> <ti> + <c>docompress</c> + </ti> + <ti> + Controls compression of files. Normally executed to exclude from + compression, e.g., <c>docompress -x /usr/share/doc/${PF}/examples</c>. + </ti> + </tr> + <tr> + <ti> <c>dostrip</c> </ti> <ti> diff --git a/function-reference/text.xml b/function-reference/text.xml index 336321d..2b90dfc 100644 --- a/function-reference/text.xml +++ b/function-reference/text.xml @@ -18,6 +18,7 @@ The following functions are available for use in ebuilds: </chapter> <include href="build-functions/"/> +<include href="error-functions/"/> <include href="install-functions/"/> <include href="message-functions/"/> <include href="query-functions/"/> diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml index 2aca289..ff198fb 100644 --- a/general-concepts/dependencies/text.xml +++ b/general-concepts/dependencies/text.xml @@ -572,15 +572,25 @@ There are also shortcuts for conditional situations: <body> <p> -If a dependency is introducing or removing a <c>USE</c> flag in new versions, a use -dependency default may be used. Appending a <c>(+)</c> or <c>(-)</c> suffix will indicate -whether the absence of the flag from a particular version should indicate its -presence or absence. +If a dependency is introducing or removing a <c>USE</c> flag in a new package +version, a <c>(+)</c> or <c>(-)</c> may be added to the use-dependency +specification to define a default value in case the flag does not exist in the +target package. The <c>(+)</c> indicates that the missing flag is assumed to be +enabled, <c>(-)</c> the opposite. </p> + <p> -<c>>=dev-libs/boost-1.48[threads(+)]</c> will treat all versions without <c>threads</c> as having it set. +For example, the following will treat all <c>boost</c> versions without the +<c>threads</c> flag as having it enabled, and all <c>gcc</c> versions without +the <c>openmp</c> as having it disabled: </p> +<codesample lang="ebuild"> +DEPEND=" + >=dev-libs/boost-1.48[threads(+)] + sys-devel/gcc[openmp(-)]" +</codesample> + </body> </subsection> </section> diff --git a/general-concepts/use-flags/text.xml b/general-concepts/use-flags/text.xml index 30b19f7..295bb8f 100644 --- a/general-concepts/use-flags/text.xml +++ b/general-concepts/use-flags/text.xml @@ -316,10 +316,10 @@ src_compile() { </codesample> <p> -In some exceptional cases, above policy would break reverse USE -dependencies. To avoid this, the ebuild can specify allowed USE flag -combinations with <c>REQUIRED_USE</c> (available in EAPI 4). See section -<uri link="::ebuild-writing/eapi/#EAPI=4"/> for a description +In some exceptional cases, above policy would break reverse USE dependencies. +To avoid this, the ebuild can specify allowed USE flag combinations with +<c>REQUIRED_USE</c>. See section +<uri link="::ebuild-writing/variables/#REQUIRED_USE"/> for a description of its syntax. </p> diff --git a/general-concepts/virtuals/text.xml b/general-concepts/virtuals/text.xml index 4f8b96d..bcea98d 100644 --- a/general-concepts/virtuals/text.xml +++ b/general-concepts/virtuals/text.xml @@ -24,7 +24,7 @@ An example of a virtual: </p> <codesample lang="ebuild"> -EAPI=4 +EAPI=7 DESCRIPTION="Virtual for C++ tr1 <type_traits>" SLOT="0" |