commit: 9e1a56d2ff7389708c55423037cb96570e4d52ed Author: Ulrich Müller <ulm <AT> gentoo <DOT> org> AuthorDate: Mon Jan 20 16:32:43 2020 +0000 Commit: Ulrich Müller <ulm <AT> gentoo <DOT> org> CommitDate: Thu Jan 23 00:01:01 2020 +0000 URL: https://gitweb.gentoo.org/proj/devmanual.git/commit/?id=9e1a56d2
ebuild-writing/eapi: Move EAPI=2 information to other sections. - doman language support: incorporated into function-reference/install-functions - Blockers incorporated into general-concepts/dependencies (also say "weak" and "strong" blockers instead of "soft" and "hard", in order to agree with the terms used in PMS) - USE dependencies: already in general-concepts/dependencies - SRC_URI arrows: incorporated into ebuild-writing/variables - src_prepare: already in ebuild-writing/functions/src_prepare - src_configure: already in ebuild-writing/functions/src_configure - Execution order: already in ebuild-writing/functions - Default phase functions moved to ebuild-writing/functions Signed-off-by: Ulrich Müller <ulm <AT> gentoo.org> ebuild-writing/eapi/text.xml | 184 --------------------- ebuild-writing/functions/src_compile/text.xml | 53 ++---- .../functions/src_prepare/epatch/text.xml | 23 +-- ebuild-writing/functions/src_prepare/text.xml | 16 +- ebuild-writing/functions/src_unpack/text.xml | 17 +- ebuild-writing/functions/text.xml | 37 +++++ ebuild-writing/variables/text.xml | 5 +- function-reference/install-functions/text.xml | 12 +- general-concepts/autotools/text.xml | 20 +-- general-concepts/dependencies/text.xml | 40 +++-- 10 files changed, 113 insertions(+), 294 deletions(-) diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml index f7427fd..048284f 100644 --- a/ebuild-writing/eapi/text.xml +++ b/ebuild-writing/eapi/text.xml @@ -62,190 +62,6 @@ is the best. Using the features of the latest EAPI is encouraged. </body> </section> -<section> -<title>EAPI=2</title> - -<subsection> -<title>EAPI 2 Helpers</title> -<body> -<ul> - <li> - <p><b>doman Language Support</b></p> - <p> - <c>doman</c> automatically detects language codes and puts it in the - appropriate directory. - </p> -<codesample lang="ebuild"> -doman foo.1 -# will go into /usr/share/man/man1/foo.1 -doman foo.lang.1 -# will go into /usr/share/man/lang/man1/foo.1 with EAPI=2 -</codesample> - </li> -</ul> -</body> -</subsection> - -<subsection> -<title>EAPI 2 Metadata</title> -<body> -<ul> - <li> - <p><b>Blockers</b></p> - <ul> - <li> - <p><b>New Meaning for Old Syntax</b></p> - <p> - Blockers which use the previously existing <c>!</c> syntax - now have a slightly different meaning. These so-called - <e>weak blocks</e> indicate that conflicting packages may - be temporarily installed simultaneously. When temporary - simultaneous installation of conflicting packages occurs, the - installation of a newer package may overwrite any colliding - files that belong to an older package which is explicitly - blocked. When such file collisions occur, the colliding files - cease to belong to the older package, and they remain installed - after the older package is eventually uninstalled. The older - package is uninstalled only after any newer blocking packages - have been merged on top of it. - </p> - </li> - <li> - <p><b>New <c>!!</c> Operator</b></p> - <p> - A new <c>!!</c> operator for <e>strong blocks</e> is now - supported, for use in special cases for which temporary - simultaneous installation of conflicting packages should not be - allowed. If both weak and strong blocks match a given package, - the strong block takes precedence. - </p> - </li> - </ul> - </li> - <li> - <p><b>USE Dependencies</b></p> - <p> - It is possible to depend on USE-flags of packages. - </p> - <p>Examples:</p> - <ul> - <li><c>foo[bar]</c> means that package foo must have USE-flag bar - enabled</li> - <li><c>foo[bar,baz]</c> means that the package foo must have both - the bar and baz USE-flags enabled - </li> - <li><c>foo[-bar,baz]</c> means that the package foo must have the - bar USE-flag disabled and baz USE-flag enabled</li> - <li><c>foo[bar?]</c> means <c>bar? ( foo[bar] ) !bar? ( foo )</c></li> - <li><c>foo[!bar?]</c> means <c>bar? ( foo ) !bar? ( foo[-bar] )</c></li> - <li><c>foo[bar=]</c> means <c>bar? ( foo[bar] ) !bar? ( foo[-bar] )</c></li> - <li><c>foo[!bar=]</c> means <c>bar? ( foo[-bar] ) !bar? ( foo[bar] )</c></li> - </ul> - </li> - <li> - <p><b>Customization of Output File Names in SRC_URI</b></p> - <p> - A new syntax is supported which allows customization of the output - file name for a given URI. In order to customize the output file - name, a given URI should be followed by a "<c>-></c>" operator which, in - turn, should be followed by the desired output file name. As - usual, all tokens, including the operator and output file name, - should be separated by whitespace. - </p> - <p>Example:</p> -<codesample lang="ebuild"> -SRC_URI="https://dl.google.com/earth/client/GE4/release_4_3/GoogleEarthLinux.bin - -> GoogleEarthLinux-${PV}.bin" -</codesample> - </li> -</ul> -</body> -</subsection> - -<subsection> -<title>EAPI 2 Phases</title> -<body> -<ul> - <li> - <p><b>New <c>src_prepare</c> Phase Function</b></p> - <p> - A new src_prepare function is called after the <c>src_unpack</c> - function, with cwd initially set to <c>$S</c>. - </p> - </li> - <li> - <p><b>New <c>src_configure</c> Phase Function</b></p> - <p> - The configure portion of the <c>src_compile</c> function has been split - into a separate function which is named <c>src_configure</c>. The - <c>src_configure</c> function is called in-between the <c>src_prepare</c> and - <c>src_compile</c> functions. - </p> - <p>The default <c>src_configure</c> and <c>src_compile</c> - functions in EAPI=2:</p> -<codesample lang="ebuild"> -src_configure() { - if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then - econf - fi -} - -src_compile() { - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then - emake || die "emake failed" - fi -} -</codesample> - </li> - <li> - <p><b>Execution Order of Phase Functions</b></p> - <ul> - <li><c>pkg_setup</c></li> - <li><c>src_unpack</c></li> - <li><c>src_prepare</c></li> - <li><c>src_configure</c></li> - <li><c>src_compile</c></li> - <li><c>src_test</c></li> - <li><c>src_install</c></li> - <li><c>pkg_preinst</c></li> - <li><c>pkg_postinst</c></li> - <li><c>pkg_prerm</c></li> - <li><c>pkg_postrm</c></li> - </ul> - </li> - <li> - <p><b>Default Phase Functions</b></p> - <p> - The default <c>pkg_nofetch</c> and <c>src_*</c> phase functions are now - accessible via a function having a name that begins with <c>default_</c> - and ends with the respective phase function name. For example, a - call to a function with the name <c>default_src_compile</c> is equivalent - to a call to the default <c>src_compile</c> implementation. - </p> - <p>The default phase functions are:</p> - <ul> - <li><c>default_pkg_nofetch</c></li> - <li><c>default_src_unpack</c></li> - <li><c>default_src_prepare</c></li> - <li><c>default_src_configure</c></li> - <li><c>default_src_compile</c></li> - <li><c>default_src_test</c></li> - </ul> - </li> - <li> - <p><b>Default Phase Function Alias</b></p> - <p> - A function named "<c>default</c>" is redefined for each phase so that it - will call the <c>default_*</c> function corresponding to the current - phase. For example, a call to the function named "<c>default</c>" during - the <c>src_compile</c> phase is equivalent to a call to the function - named <c>default_src_compile</c>. - </p> - </li> -</ul> -</body> -</subsection> -</section> <section> <title>EAPI=3</title> <body> diff --git a/ebuild-writing/functions/src_compile/text.xml b/ebuild-writing/functions/src_compile/text.xml index 1cd5050..35f6285 100644 --- a/ebuild-writing/functions/src_compile/text.xml +++ b/ebuild-writing/functions/src_compile/text.xml @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Configure and build the package.<important>the configure parts of <c>src_compile</c> have been splitted out in EAPI=2 to <c>src_configure</c>. see <uri link="::ebuild-writing/functions/src_configure"/></important></ti> + <ti>Build the package.</ti> </tr> <tr> <th>Sandbox</th> @@ -33,22 +33,7 @@ <body> <ul> -<li> -<p>with EAPI=0,1</p> -<codesample lang="ebuild"> -src_compile() { - if [ -x ./configure ]; then - econf - fi - if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then - emake || die "emake failed" - fi -} -</codesample> -</li> - -<li> -<p>with EAPI=2</p> + <li> <codesample lang="ebuild"> src_compile() { if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ]; then @@ -56,44 +41,33 @@ src_compile() { fi } </codesample> -</li> + </li> </ul> </body> </section> <section> <title>Sample <c>src_compile</c></title> - <body> + <ul> -<li> -<p>with EAPI=0</p> + <li> <codesample lang="ebuild"> src_compile() { use sparc && filter-flags -fomit-frame-pointer append-ldflags -Wl,-z,now - econf \ - $(use_enable ssl ) \ - $(use_enable perl perlinterp ) - - emake || die "Make failed!" + emake } </codesample> -<note> -You also need to inherit the <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> eclass in order to use the <c>append-ldflags</c> function. -</note> -</li> - -<li> -<p>with EAPI=2</p> -<p> -Porting the above example to EAPI=2, you won't need to define an extra -<c>src_compile</c>, as it only calls <c>emake</c> (which is the default -<c>src_compile</c> function). -</p> -</li> + <note> + You also need to inherit the + <uri link="::eclass-reference/flag-o-matic.eclass/">flag-o-matic</uri> + eclass in order to use the <c>append-ldflags</c> function. + </note> + </li> </ul> + </body> </section> @@ -112,7 +86,6 @@ The following subsections cover different topics which often occur when writing </chapter> <include href="build-environment/"/> -<!--<include href="configuring/"/>--> <include href="building/"/> <include href="no-build-system/"/> </guide> diff --git a/ebuild-writing/functions/src_prepare/epatch/text.xml b/ebuild-writing/functions/src_prepare/epatch/text.xml index ad05830..d1def03 100644 --- a/ebuild-writing/functions/src_prepare/epatch/text.xml +++ b/ebuild-writing/functions/src_prepare/epatch/text.xml @@ -11,12 +11,6 @@ to inherit!) inside <c>src_prepare</c>. This function automatically handles <c>-p</c> levels, <c>gunzip</c> and so on as necessary. </p> -<p> -Also note that old ebuilds may still use src_unpack to apply patches. -This is because those ebuilds are based in EAPI=1. -You are advised to use the latest and apply your patches in src_prepare function instead. -</p> - <p> Starting with EAPI=7, this function is banned and <c>eapply</c> must be used. </p> @@ -90,9 +84,7 @@ fails. The following is taken from <c>app-misc/detox</c>: </p> <codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" +src_prepare() { epatch "${FILESDIR}/${P}-destdir.patch" epatch "${FILESDIR}/${P}-parallel_build.patch" } @@ -109,15 +101,6 @@ usually best to compress the patch in question with <c>xz</c> or be compressed). For example, from <c>app-admin/showconsole</c>: </p> -<codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" - epatch "${WORKDIR}/${P}-suse-update.patch.bz2" - epatch "${FILESDIR}/${PV}-no-TIOCGDEV.patch" -} -</codesample> -<p>As stated before, if you are using EAPI >=2, you should apply the patches in the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function</p> <codesample lang="ebuild"> src_prepare() { epatch "${WORKDIR}/${P}-suse-update.patch.bz2" @@ -146,9 +129,7 @@ A simple example: </p> <codesample lang="ebuild"> -src_unpack() { - unpack ${A} - cd "${S}" +src_prepare() { EPATCH_SOURCE="${WORKDIR}/patches" EPATCH_SUFFIX="patch" \ EPATCH_FORCE="yes" epatch } diff --git a/ebuild-writing/functions/src_prepare/text.xml b/ebuild-writing/functions/src_prepare/text.xml index 7ab3aa9..5cbfcf1 100644 --- a/ebuild-writing/functions/src_prepare/text.xml +++ b/ebuild-writing/functions/src_prepare/text.xml @@ -31,18 +31,22 @@ <section> <title>Default <c>src_prepare</c></title> <body> + <p> -Starting from EAPI=2, the src_prepare function is the appropriate area to perform -any kind of patching and source code manipulation, instead of src_unpack. +Before EAPI 6, the default implementation did nothing: </p> + <codesample lang="ebuild"> src_prepare() { - true; + true } </codesample> + <p> -Beginning with EAPI=6, the src_prepare function gained a new default implementation: +Beginning with EAPI 6, the src_prepare function gained a new default +implementation: </p> + <codesample lang="ebuild"> src_prepare() { if declare -p PATCHES | grep -q "^declare -a "; then @@ -53,10 +57,12 @@ src_prepare() { eapply_user } </codesample> + <note> -With EAPI=6, you must call <c>eapply_user</c> or <c>default</c> if you define +With EAPI 6, you must call <c>eapply_user</c> or <c>default</c> if you define <c>src_prepare</c>! </note> + </body> </section> diff --git a/ebuild-writing/functions/src_unpack/text.xml b/ebuild-writing/functions/src_unpack/text.xml index 76b5f35..aad45f6 100644 --- a/ebuild-writing/functions/src_unpack/text.xml +++ b/ebuild-writing/functions/src_unpack/text.xml @@ -11,7 +11,7 @@ </tr> <tr> <th>Purpose</th> - <ti>Extract source packages and do any necessary patching or fixes.</ti> + <ti>Extract source packages.</ti> </tr> <tr> <th>Sandbox</th> @@ -33,7 +33,7 @@ <body> <codesample lang="ebuild"> src_unpack() { - if [ "${A}" != "" ]; then + if [[ -n ${A} ]]; then unpack ${A} fi } @@ -44,20 +44,13 @@ src_unpack() { <section> <title>Sample <c>src_unpack</c></title> <body> + <codesample lang="ebuild"> src_unpack() { - unpack ${A} - cd "${S}" - - epatch "${FILESDIR}/${PV}/${P}-fix-bogosity.patch" - use pam && epatch "${FILESDIR}/${PV}/${P}-pam.patch" - - sed -i -e 's/"ispell"/"aspell"/' src/defaults.h || die "Sed failed!" + unpack ${P}.tar.xz + use foo && unpack ${P}-foo-extension.tar.xz } </codesample> -<note> -When using EAPI >=2, you should use the <uri link="::ebuild-writing/functions/src_prepare">src_prepare</uri> function to apply patches or alter any of the source files, instead of the src_unpack. -</note> </body> </section> diff --git a/ebuild-writing/functions/text.xml b/ebuild-writing/functions/text.xml index a6deb0a..e2167e6 100644 --- a/ebuild-writing/functions/text.xml +++ b/ebuild-writing/functions/text.xml @@ -62,6 +62,43 @@ Avoid network access in any phase by using local files, extending </p> </body> +<section> +<title>Default phase functions</title> +<body> + +<p> +The default <c>pkg_nofetch</c> and <c>src_*</c> phase functions are accessible +via a function having a name that begins with <c>default_</c> and ends with the +respective phase function name. For example, a call to a function with the name +<c>default_src_compile</c> is equivalent to a call to the default +<c>src_compile</c> implementation. +</p> + +<p> +The default phase functions are: +</p> + +<ul> + <li><c>default_pkg_nofetch</c></li> + <li><c>default_src_unpack</c></li> + <li><c>default_src_prepare</c></li> + <li><c>default_src_configure</c></li> + <li><c>default_src_compile</c></li> + <li><c>default_src_test</c></li> + <li><c>default_src_install</c></li> +</ul> + +<p> +A function named <c>default</c> is redefined for each of the above phases, +so that it will call the <c>default_*</c> function corresponding to +the current phase. For example, a call to the <c>default</c> function +during the <c>src_compile</c> phase is equivalent to a call to the +<c>default_src_compile</c> function. +</p> + +</body> +</section> + <section> <title>Contents</title> <body> diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml index b9310a1..66a9822 100644 --- a/ebuild-writing/variables/text.xml +++ b/ebuild-writing/variables/text.xml @@ -388,11 +388,12 @@ and in the local distdir. <p> Here we download a file from upstream which has a plain name like <c>1.0.tar.gz</c> and save/mirror it with a better name like -<c>thepackage-1.0.tar.gz</c>. +<c>thepackage-1.0.tar.gz</c>. As usual, all tokens, including the operator +and the output file name, must be separated by whitespace. </p> <codesample lang="ebuild"> -SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz" +SRC_URI="https://example.com/files/${PV}.tar.gz -> ${P}.tar.gz" </codesample> </body> diff --git a/function-reference/install-functions/text.xml b/function-reference/install-functions/text.xml index cdc7b48..a042480 100644 --- a/function-reference/install-functions/text.xml +++ b/function-reference/install-functions/text.xml @@ -237,7 +237,17 @@ the first is the source name, the second the name to use when installing. <c>doman</c> </ti> <ti> - Install a man page + <p> + Install a man page into the appropriate section of <c>/usr/share/man</c>. + e.g., <c>foo.1</c> will be installed in <c>/usr/share/man/man1/foo.1</c>. + </p> + <p> + If the man page is named <c>foo.<lang>.1</c> then it will be + installed in <c>/usr/share/man/<lang>/man1/foo.1</c>, where + <c><lang></c> is a language code. Option <c>-i18n=<lang></c> + can be used to explicitly specify a subdirectory (or to suppress it, if + empty). + </p> </ti> </tr> <tr> diff --git a/general-concepts/autotools/text.xml b/general-concepts/autotools/text.xml index 026e0e3..c6a9aa8 100644 --- a/general-concepts/autotools/text.xml +++ b/general-concepts/autotools/text.xml @@ -76,20 +76,12 @@ and have the same format <d/> the only difference is the name. </note> <p> - You may see autotools being used in a variety of phase - functions. Prior to EAPI2, the QA team preferred that the source - code be manipulated in <c>src_unpack</c> <d/> the rationale being that - <c>src_unpack</c> handles "getting the package ready to be - compiled." -</p> - -<p> - EAPI2, however, introduced a new phase function: <uri - link="::ebuild-writing/functions/src_prepare" />. This is now the - appropriate place to manipulate the source code prior to - configuration and compilation. In particular, <c>src_prepare</c> is - called before <uri link="::ebuild-writing/functions/src_configure" - />, which usually expects the <c>configure</c> script to exist. +You may see autotools being used in a variety of phase functions. +The <uri link="::ebuild-writing/functions/src_prepare/"/> function is the most +appropriate place to manipulate the source code prior to configuration +and compilation. In particular, <c>src_prepare</c> is called before +<uri link="::ebuild-writing/functions/src_configure/"/>, which usually expects +the <c>configure</c> script to exist. </p> <p> diff --git a/general-concepts/dependencies/text.xml b/general-concepts/dependencies/text.xml index 4e3a84e..7992571 100644 --- a/general-concepts/dependencies/text.xml +++ b/general-concepts/dependencies/text.xml @@ -218,39 +218,48 @@ to the package manager. </p> <p> -The following description applies to all EAPIs starting with EAPI 2. +There are two kinds of blockers: <e>weak blockers</e> and <e>strong +blockers</e>. </p> <p> -There are two kinds of blockers: soft blockers and hard blockers. +A weak blocker is defined using the following syntax: </p> -<p>A soft blocker is defined using the following syntax:</p> - <codesample lang="ebuild"> RDEPEND="!app-misc/foo" </codesample> <p> The package manager will try to resolve this conflict automatically. -The package blocked by a soft blocker can be uninstalled <e>after</e> +The package blocked by a weak blocker can be uninstalled <e>after</e> installing the package blocking it. However, it exempts the common -files from file collision checks. Soft blockers are usually used +files from file collision checks. Weak blockers are usually used to solve file collisions between packages and are meaningful only in <c>RDEPEND</c>. </p> +<p> +More specifically, installation of the newer package may overwrite any +colliding files that belong to the older package that is explicitly blocked. +When such file collisions occur, the colliding files cease to belong to the +older package, and they remain installed after the older package is eventually +uninstalled. The older package is uninstalled only after any newer blocking +packages have been merged on top of it. +</p> + <warning> -Soft blockers that are pure <c>DEPEND</c> <e>do not work correctly</e>. +Weak blockers that are pure <c>DEPEND</c> <e>do not work correctly</e>. While Portage seemingly queues the package for removal, it <e>does not</e> exempt their contents from file collision checks. Always include your -soft blockers in <c>RDEPEND</c>! +weak blockers in <c>RDEPEND</c>! </warning> <p> If it is strictly necessary to resolve the blocker before the package -is built (installed), a hard blocker must be used instead. Hard blockers -are expressed using the following syntax: +is built (installed), a strong blocker must be used instead. In this case, +temporary simultaneous installation of the conflicting packages is not allowed. +Strong blockers are expressed using the following syntax: </p> <codesample lang="ebuild"> @@ -258,7 +267,7 @@ RDEPEND="!!app-misc/foo" </codesample> <p> -Hard blockers apply accordingly to the dependency type defining them. +Strong blockers apply accordingly to the dependency type defining them. Blockers defined in <c>RDEPEND</c> are enforced as long as the package is installed (but do not prevent building binary packages). Blockers defined purely in <c>DEPEND</c> are enforced only for building @@ -266,6 +275,11 @@ the package from source, and may not apply once the package is installed or when it is installed from a binary package. </p> +<note> +If both weak and strong blockers match a given package, the strong blocker +takes precedence. +</note> + <p> Specific versions can also be blocked: </p> @@ -463,10 +477,6 @@ flag is not necessary if and only if all of the following hold: <title>Built with USE Dependencies</title> <body> -<p> -In order to use built with use dependencies you must specify <c>EAPI=2</c>. -</p> - <p> Available specifiers are: </p>
