diff options
Diffstat (limited to 'eclass-writing/text.xml')
| -rw-r--r-- | eclass-writing/text.xml | 749 |
1 files changed, 406 insertions, 343 deletions
diff --git a/eclass-writing/text.xml b/eclass-writing/text.xml index 352e026..8c4c910 100644 --- a/eclass-writing/text.xml +++ b/eclass-writing/text.xml @@ -1,20 +1,22 @@ -<?xml version="1.0"?> +<?xml version="1.0" encoding="UTF-8"?> <guide self="eclass-writing/"> <chapter> -<title>Eclass Writing Guide</title> - +<title>Eclass writing guide</title> <body> + <p> This section provides a brief introduction to eclass authoring. </p> <important> -You should reread the <uri link="::general-concepts/overlay#Overlay and Eclasses"/> -and <uri link="::general-concepts/portage-cache"/> sections before continuing. +You should reread the +<uri link="::general-concepts/overlay/#Overlay and eclasses"/> +and <uri link="::general-concepts/portage-cache/"/> sections before continuing. </important> +</body> <section> -<title>Purpose of Eclasses</title> +<title>Purpose of eclasses</title> <body> <p> @@ -26,15 +28,16 @@ Roughly speaking, there are three kinds of eclass: <ul> <li> Those which provide common functions which are used by many ebuilds (for - example, <c>eutils</c>, <c>eapi7-ver</c>, <c>cvs</c>, <c>bash-completion</c>) + example, <c>autotools</c>, <c>bash-completion-r1</c>, <c>flag-o-matic</c>, + <c>toolchain-funcs</c>) </li> <li> Those which provide a basic build system for many similar packages (for - example, <c>vim-plugin</c>, <c>kde</c>) + example, <c>perl-module</c>, <c>vim-plugin</c>) </li> <li> Those which handle one or a small number of packages with complex build - systems (for example, <c>vim</c>, <c>toolchain</c>, <c>kernel-2</c>) + systems (for example, <c>kernel-2</c>, <c>toolchain</c>) </li> </ul> @@ -42,60 +45,78 @@ Roughly speaking, there are three kinds of eclass: </section> <section> -<title>Adding and Updating Eclasses</title> +<title>Adding and updating eclasses</title> <body> <p> -Before committing a new eclass to the tree, it should be emailed to the -gentoo-dev mailing list with a justification and a proposed implementation. Do -not skip this step <d/> sometimes a better implementation or an alternative which +Before committing a new eclass to the tree, it must be emailed to the gentoo-dev +mailing list with a justification and a proposed implementation. Do not skip +this step <d/> sometimes a better implementation or an alternative which does not require a new eclass will be suggested. </p> <p> -Before updating <c>eutils</c> or a similar widely used eclass, it is best to email -the gentoo-dev list. It may be that your proposed change is broken in a way you -had not anticipated, or that there is an existing function which performs the -same purpose, or that your function may be better off in its own eclass. If you -don't email gentoo-dev first, and end up breaking something, expect to be in a -lot of trouble. +Before updating any eclass, email patches to the gentoo-dev list. It may be that +your proposed change is broken in a way you had not anticipated, or that there +is an existing function which performs the same purpose, or that your function +may be better off in its own eclass. If you don't email gentoo-dev first, +and end up breaking something, expect to be in a lot of trouble. </p> <p> -When removing a function or changing the API of an eclass, make -sure that it doesn't break any ebuilds in the tree, and post a -notice to gentoo-dev at least 30 days in advance, preferably with -a patch included. +Note that you should also, when sending your patch, CC any maintainers of the +eclass listed in the <c>@MAINTAINER</c> tag. You may want to contact them +ahead of time and get their opinions too. </p> <p> -If there is an existing maintainer for an eclass (this is usually the case), you -<b>must</b> talk to the maintainer before committing any changes. +The exceptions to this rule are updates to per-package eclasses. For example, +the <c>apache-2</c> eclass is only used by the <c>www-servers/apache</c> +package, and thus does not typically require changes to be emailed for review. </p> <p> -It is not usually necessary to email the gentoo-dev list before making changes -to a non-general eclass which you maintain. Use common sense here. +When removing a function or changing the API of an eclass, make sure that +it doesn't break any ebuilds in the Gentoo repository. Optionally, you may wish +to do a survey of some (official) overlays like <c>::guru</c>, <c>::musl</c>, or +<c>::science</c> in order to better understand how it is currently used and +<d/> where possible <d/> avoid breakage by pinging the maintainers directly. +</p> + +<p> +If there is an existing maintainer for an eclass (this is usually the case), you +<b>must</b> talk to the maintainer before committing any changes. </p> <warning> -Committing a broken eclass can kill huge numbers of packages. Since -<c>repoman</c> is not eclass-aware, be very sure you do proper testing. +Committing a broken eclass can kill huge numbers of packages. </warning> <p> A simple way to verify syntax is <c>bash -n foo.eclass</c>. </p> +<note> +Given that updating an eclass will invalidate the cache of all consumer ebuilds, +it is good etiquette to ping other developers in e.g. <c>#gentoo-dev</c> +on IRC or informally determine if there are other similar changes (mainly +documentation) which should be pushed at the same time in order to avoid +unnecessary cache regeneration within a few hours or days of each other. +The same applies to your own work <d/> please prepare all of your commits and +batch push them at once where possible. +</note> + </body> </section> <section> -<title>Removing Eclasses</title> +<title>Removing eclasses</title> <body> -<p>No longer used eclasses may be removed from the tree, but developers must -adhere to the following process:</p> +<p> +Eclasses that are no longer in use may be removed from the tree, but developers +must adhere to the following process: +</p> <ol> <li> @@ -116,12 +137,17 @@ adhere to the following process:</p> </li> </ol> +<note> +Before considering removal, please mark the eclass as <c># @DEPRECATED:</c> +to ensure consumers are warned if they are still using the eclass. Do this at +least 30 days before removing the eclass. +</note> </body> </section> <section> -<title>Documenting Eclasses</title> +<title>Documenting eclasses</title> <body> <p> @@ -132,16 +158,31 @@ each block documents an individual element of an eclass. <p> Documentation tags for various eclass elements are explained in their -respective sections below. Common to all the tags that accept -multiline freetext, the <c>@CODE</c> tag should be used when necessary -to create unformatted code chunks (such as example code) by placing -the tag at the beginning and the end. +respective sections below. Common to all the tags that accept multiline +freetext, the <c>@CODE</c> tag should be used when necessary to create +unformatted code chunks (such as example code) by placing the tag at the +beginning and the end. The <c>@SUBSECTION</c> tag inserts a subsection +heading; it is allowed only in the main <c>@DESCRIPTION</c>. </p> + +<p> +Note that <c>pkgcheck</c> can check for issues in eclass documentation. +You could run e.g. <c>pkgcheck scan -s eclass</c> to check for issues +in the tree or <c>pkgcheck scan --commits</c> to check for issues +in your staged git commits. +</p> + +<note> +In eclass documentation, two spaces should be used after the end of each +sentence (unless it is followed by a newline). This will help <c>groff</c> +to properly break lines when generating eclass manpages. +</note> + </body> </section> <section> -<title>Basic Eclass Format</title> +<title>Basic eclass format</title> <body> <p> @@ -162,133 +203,107 @@ summarizes the available documentation tags: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> - <ti> - <c>@ECLASS:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the eclass being documented. - </ti> + <ti><c>@ECLASS:</c></ti> + <ti>Yes</ti> + <ti>Name of the eclass being documented</ti> <ti> Documents various information about the eclass. Must appear as the first tag in the comment block. </ti> </tr> <tr> - <ti> - <c>@MAINTAINER:</c> - </ti> - <ti> - NO - </ti> - <ti> - One or more name and email pairs. - </ti> + <ti><c>@MAINTAINER:</c></ti> + <ti>Yes</ti> + <ti>One or more name and email pairs</ti> <ti> List of maintainers for the eclass to be contacted. One line per maintainer. Must start on a newline after the tag. </ti> </tr> <tr> - <ti> - <c>@AUTHOR:</c> - </ti> - <ti> - YES - </ti> - <ti> - One or more name and email pairs. - </ti> + <ti><c>@AUTHOR:</c></ti> + <ti>No</ti> + <ti>One or more name and email pairs</ti> <ti> List of authors for the eclass. One line per author. Must start on a newline after the tag. </ti> </tr> <tr> - <ti> - <c>@BUGREPORTS:</c> - </ti> - <ti> - YES - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Describes how bugs related to this eclass should be reported. - </ti> + <ti><c>@BUGREPORTS:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> + <ti>Describes how bugs related to this eclass should be reported</ti> </tr> <tr> - <ti> - <c>@VCSURL:</c> - </ti> - <ti> - YES - </ti> - <ti> - A URI string. - </ti> - <ti> - Points to the URL of the VCS that contains the eclass source. - </ti> + <ti><c>@VCSURL:</c></ti> + <ti>No</ti> + <ti>A URI string</ti> + <ti>Points to the URL of the VCS that contains the eclass source</ti> </tr> <tr> + <ti nowrap="nowrap"><c>@SUPPORTED_EAPIS:</c></ti> + <ti>No</ti> + <ti>Space-separated list of EAPIs</ti> + <ti>List of EAPIs supported by this eclass</ti> +</tr> +<tr> + <ti><c>@PROVIDES:</c></ti> + <ti>No</ti> + <ti>Space-separated list of eclass names</ti> <ti> - <c>@BLURB:</c> - </ti> - <ti> - NO - </ti> - <ti> - Single line freetext. + List of indirectly inherited eclasses whose functions and variables may be + used by an ebuild inheriting this eclass </ti> +</tr> +<tr> + <ti><c>@BLURB:</c></ti> + <ti>Yes</ti> + <ti>Single line freetext</ti> <ti> Contains a short description for the eclass. Must be on the same line with the tag. </ti> </tr> <tr> - <ti> - <c>@DESCRIPTION:</c> - </ti> - <ti> - YES - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Long description for the eclass. - </ti> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Replacement (or "none")</ti> + <ti>Declares that this eclass should no longer be used</ti> </tr> <tr> + <ti><c>@DEAD</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> - <c>@EXAMPLE:</c> - </ti> - <ti> - YES - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Examples that illustrate various uses of this eclass. + For an eclass that is slated for removal; prevents the eclass-manpages + package from documenting the eclass. </ti> </tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> + <ti>Long description for the eclass</ti> +</tr> +<tr> + <ti><c>@EXAMPLE:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> + <ti>Examples that illustrate various uses of this eclass</ti> +</tr> </table> </body> </section> <section> -<title>Eclass Variables</title> +<title>Eclass variables</title> <body> <p> @@ -306,20 +321,14 @@ variables are as follows: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> - <ti nowrap="nowrap"> - <c>@ECLASS-VARIABLE:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the eclass variable to which the documentation applies. - </ti> + <ti nowrap="nowrap"><c>@ECLASS_VARIABLE:</c></ti> + <ti>Yes</ti> + <ti>Name of the eclass variable to which the documentation applies</ti> <ti> This tag applies to eclass specific variables that affect the default behavior of the eclass. Read-only variables, which are @@ -328,61 +337,66 @@ variables are as follows: </ti> </tr> <tr> + <ti><c>@PRE_INHERIT</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> - <c>@DEFAULT_UNSET</c> + This tag describes whether the variable must be defined before + the eclass is inherited. This is important if any e.g. dependencies + are modified in global scope at the point of sourcing. </ti> +</tr> +<tr> + <ti><c>@USER_VARIABLE</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> - YES + This tag describes whether the variable is unsuitable for use in ebuilds, + i.e. if it is solely for user consumption via e.g. make.conf or a similar + mechanism </ti> +</tr> +<tr> + <ti><c>@OUTPUT_VARIABLE</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> - <d/> + This tag indicates that the variable's value (which will be set by the + eclass) should be read within an ebuild </ti> +</tr> +<tr> + <ti><c>@DEFAULT_UNSET</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> Indicates that this variable is unset by default if not set by the - developer. + developer </ti> </tr> <tr> - <ti> - <c>@INTERNAL</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that the variable is internal to the eclass. - </ti> + <ti><c>@INTERNAL</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that the variable is internal to the eclass</ti> </tr> <tr> - <ti> - <c>@REQUIRED</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that this variable must be set by the developer. - </ti> + <ti><c>@REQUIRED</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that this variable must be set by the developer</ti> </tr> <tr> - <ti> - <c>@DESCRIPTION:</c> - </ti> - <ti> - NO - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Long description for the eclass variable. - </ti> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Optionally, the name of any replacement variable</ti> + <ti>Declares that this variable should no longer be used in ebuilds</ti> +</tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti>Yes</ti> + <ti>Multiline freetext</ti> + <ti>Long description for the eclass variable</ti> </tr> </table> @@ -390,7 +404,7 @@ variables are as follows: </section> <section> -<title>Eclass Functions</title> +<title>Eclass functions</title> <body> <p> @@ -407,35 +421,23 @@ documentation are: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> - <ti> - <c>@FUNCTION:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the function to which the documentation block applies. - </ti> + <ti><c>@FUNCTION:</c></ti> + <ti>Yes</ti> + <ti>Name of the function to which the documentation block applies</ti> <ti> Documents information about an eclass function such as its calling - convention etc. Must appear as the first tag in the comment block. + convention etc. Must appear as the first tag in the comment block </ti> </tr> <tr> - <ti> - <c>@USAGE:</c> - </ti> - <ti> - NO - </ti> - <ti> - List of required and optional arguments to the function. - </ti> + <ti><c>@USAGE:</c></ti> + <ti>No</ti> + <ti>List of required and optional arguments to the function</ti> <ti> List of arguments that the eclass function accepts, specified in the following syntax: <c><</c>Required arguments<c>></c> @@ -443,63 +445,45 @@ documentation are: </ti> </tr> <tr> - <ti> - <c>@RETURN:</c> - </ti> - <ti> - <b>*</b> - </ti> - <ti> - Return value of the function. - </ti> + <ti><c>@RETURN:</c></ti> + <ti><b>*</b></ti> + <ti>Return value of the function</ti> <ti> <p>Description for the value returned by the function.</p> - <p><b>*</b>: Not optional for functions that return a value.</p> + <p><b>*</b>: Required for functions that return a value.</p> </ti> </tr> <tr> - <ti> - <c>@MAINTAINER:</c> - </ti> - <ti> - YES - </ti> - <ti> - Multiline freetext. - </ti> + <ti><c>@MAINTAINER:</c></ti> + <ti>No</ti> + <ti>Multiline freetext</ti> <ti> List of contacts for the eclass function. One line per maintainer. Must start on a newline after the tag. </ti> </tr> <tr> - <ti> - <c>@INTERNAL</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> + <ti><c>@INTERNAL</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> Indicates that the function is internal to the eclass and should - not be called from outside. + not be called from outside </ti> </tr> <tr> - <ti> - <c>@DESCRIPTION:</c> - </ti> - <ti> - <b>*</b> - </ti> - <ti> - Multiline freetext. - </ti> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Optionally, the name of a replacement function</ti> + <ti>Declares that this function should no longer be used in ebuilds</ti> +</tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti><b>*</b></ti> + <ti>Multiline freetext</ti> <ti> <p>Long description for the eclass function.</p> - <p><b>*:</b> Not optional if <c>RETURN:</c> is absent.</p> + <p><b>*:</b> Required if <c>RETURN:</c> is absent.</p> </ti> </tr> </table> @@ -507,7 +491,7 @@ documentation are: </body> </section> <section> -<title>Eclass Function Variables</title> +<title>Eclass function variables</title> <body> <p> @@ -519,19 +503,15 @@ using the following tags: <table> <tr> <th>tag</th> - <th>optional?</th> + <th>required?</th> <th>arguments</th> <th>description</th> </tr> <tr> + <ti><c>@VARIABLE:</c></ti> + <ti>Yes</ti> <ti> - <c>@VARIABLE:</c> - </ti> - <ti> - NO - </ti> - <ti> - Name of the function-specific variable to which the documentation applies. + Name of the function-specific variable to which the documentation applies </ti> <ti> This tag applies to variables consumed by specific functions of @@ -540,61 +520,47 @@ using the following tags: </ti> </tr> <tr> - <ti> - <c>@DEFAULT_UNSET</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> + <ti><c>@USER_VARIABLE</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti> + This tag describes whether the variable is unsuitable for use in ebuilds, + i.e. if it is solely for user consumption via e.g. make.conf or a similar + mechanism + </ti> +</tr> +<tr> + <ti><c>@DEFAULT_UNSET</c></ti> + <ti>No</ti> + <ti><d/></ti> <ti> Indicates that this variable is unset by default if not set by the - developer. + developer </ti> </tr> <tr> - <ti> - <c>@INTERNAL</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that the variable is internal to the eclass function. - </ti> + <ti><c>@INTERNAL</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that the variable is internal to the eclass function</ti> </tr> <tr> - <ti> - <c>@REQUIRED</c> - </ti> - <ti> - YES - </ti> - <ti> - <d/> - </ti> - <ti> - Indicates that this variable must be set by the developer. - </ti> + <ti><c>@REQUIRED</c></ti> + <ti>No</ti> + <ti><d/></ti> + <ti>Indicates that this variable must be set by the developer</ti> </tr> <tr> - <ti> - <c>@DESCRIPTION:</c> - </ti> - <ti> - NO - </ti> - <ti> - Multiline freetext. - </ti> - <ti> - Long description for the function variable. - </ti> + <ti><c>@DEPRECATED:</c></ti> + <ti>No</ti> + <ti>Optionally, the name of any replacement variable</ti> + <ti>Declares that this variable should no longer be used in ebuilds</ti> +</tr> +<tr> + <ti><c>@DESCRIPTION:</c></ti> + <ti>Yes</ti> + <ti>Multiline freetext</ti> + <ti>Long description for the function variable</ti> </tr> </table> @@ -602,7 +568,7 @@ using the following tags: </section> <section> -<title>Simple Common Functions Eclass Example</title> +<title>Simple common functions eclass example</title> <body> <p> @@ -612,7 +578,7 @@ a single function, <c>domacosapp</c>. </p> <codesample lang="ebuild"> -# Copyright 1999-2019 Gentoo Foundation +# Copyright 1999-2021 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 # @ECLASS: macosapp.eclass @@ -623,14 +589,14 @@ a single function, <c>domacosapp</c>. # @FUNCTION: domacosapp # @USAGE: <app-file> [new-file] # @DESCRIPTION: -# Install the given .app file into the appropriate location. If +# Install the given .app file into the appropriate location. If # [new-file] is given, it will be used as the new (installed) name of -# the file. Otherwise <app-file> is installed as-is. +# the file. Otherwise <app-file> is installed as-is. domacosapp() { [[ -z "${1}" ]] && die "usage: domacosapp <file> [new file]" if use ppc-macos ; then insinto /Applications - newins "$1" "${2:-${1}}" || die "Failed to install ${1}" + newins "$1" "${2:-${1}}" fi } </codesample> @@ -639,19 +605,19 @@ domacosapp() { </section> <section> -<title>Export Functions</title> +<title>Export functions</title> <body> <p> -An eclass may provide default implementations for any of the standard ebuild -functions (<c>src_unpack</c>, <c>pkg_postinst</c> etc). This can be done either as a +An eclass may provide default implementations for any of the ebuild phase +functions (<c>src_unpack</c>, <c>pkg_postinst</c>, etc). This can be done either as a simple function definition (which is not multiple eclass friendly) or using <c>EXPORT_FUNCTIONS</c>. Functions given to <c>EXPORT_FUNCTIONS</c> are implemented -as normal, but have their name prefixed with <c>${ECLASS}_</c>. +as normal, but have their name prefixed ("namespaced") with <c>${ECLASS}_</c>. </p> <important> -Only 'standard' functions should be specified in <c>EXPORT_FUNCTIONS</c>. +Only the ebuild phase functions may be specified in <c>EXPORT_FUNCTIONS</c>. </important> <note><c>EXPORT_FUNCTIONS</c> is a function, <e>not</e> a variable.</note> @@ -664,11 +630,11 @@ eclass-defined defaults <d/> for example, say we had <c>fnord.eclass</c>: </p> <codesample lang="ebuild"> -EXPORT_FUNCTIONS src_compile - fnord_src_compile() { do_stuff || die } + +EXPORT_FUNCTIONS src_compile </codesample> <p> @@ -676,7 +642,7 @@ Then an ebuild could do this: </p> <codesample lang="ebuild"> -inherit fnord.eclass +inherit fnord src_compile() { do_pre_stuff || die @@ -685,64 +651,84 @@ src_compile() { } </codesample> +<p> +Eclasses may inherit other eclasses to make use of their functionality, and +historically there have been instances of eclasses calling +<c>EXPORT_FUNCTIONS</c> and then inheriting another eclass. As inherited +eclasses may also execute <c>EXPORT_FUNCTIONS</c>, it was not fully defined +which defaults should take effect. The general recommendation is now that +eclasses should not inherit other eclasses <e>after</e> calling +<c>EXPORT_FUNCTIONS</c>. +</p> + </body> </section> <section> -<title>Simple Build System Eclass Example</title> +<title>Inherit guards</title> <body> <p> -A simple eclass which defines a number of functions and a default -<c>src_compile</c> for the (hypothetical) <c>jmake</c> build system might look -something like the following: +It is common practice to surround the main contents of an eclass with an +"inherit guard". Much like header guards known from C, inherit guards help +ensure that an eclass can be inherited multiple times and have its functions and +variables defined only once. An inherit guard is only needed for an eclass that +can be inherited more than once. +</p> + +<p> +A typical inherit guard looks as follows (for a hypothetical <c>foo.eclass</c>): </p> <codesample lang="ebuild"> -# Copyright 1999-2019 Gentoo Foundation -# Distributed under the terms of the GNU General Public License v2 +if [[ -z ${_FOO_ECLASS} ]]; then +_FOO_ECLASS=1 -# @ECLASS: jmake.eclass -# @MAINTAINER: -# Gentoo Devmanual Project <devmanual@gentoo.org> -# @AUTHOR: -# Ciaran McCreesh <ciaranm@gentoo.org> -# @BLURB: Demonstrate a simple build system eclass. -# @DESCRIPTION: -# Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the -# (hypothetical) jmake build system and a default src_compile. +# Variables and functions go here -EXPORT_FUNCTIONS src_compile +fi +</codesample> -DEPEND=">=sys-devel/jmake-2" +<p> +When it comes to <c>EXPORT_FUNCTIONS</c> and inherit guards, the call to +<c>EXPORT_FUNCTIONS</c> must be placed at the very end of the eclass +<e>outside</e> any inherit guards, like this: +</p> -# @FUNCTION: jmake-configure -# @USAGE: [additional-args] -# @DESCRIPTION: -# Passes all arguments through to the appropriate "jmake configure" -# command. -jmake-configure() { - jmake configure --prefix=/usr "$@" -} +<codesample lang="ebuild"> +if [[ -z ${_FOO_ECLASS} ]]; then +_FOO_ECLASS=1 -# @FUNCTION: jmake-build -# @USAGE: [additional-args] -# @DESCRIPTION: -# First builds all dependencies, and then passes through its arguments -# to the appropriate "jmake build" command. -jmake-build() { - jmake dep && jmake build "$@" +foo_src_compile() { + ... } +fi -# @FUNCTION: jmake-src_compile -# @DESCRIPTION: -# Calls jmake-configure() and jmake-build() to compile a jmake project. -jmake_src_compile() { - jmake-configure || die "configure failed" - jmake-build || die "build failed" -} +EXPORT_FUNCTIONS src_compile </codesample> +<p> +This helps to ensure that the last inherited eclass gets to define the default +phase functions. Consider two eclasses <c>foo.eclass</c> and <c>bar.eclass</c> +that define the same default phase function via <c>EXPORT_FUNCTIONS</c>. If an +ebuild inherits both as <c>inherit foo bar</c>, then the default phases are +defined by <c>bar.eclass</c>. If <c>foo.eclass</c> is then modified to inherit +<c>bar</c> as well, then the ebuild's default functions could suddenly become +those from <c>foo</c> if <c>EXPORT_FUNCTIONS</c> was placed inside the inherit +guard. +</p> + +<note> +The rule of thumb here is: put the call (if any) to <c>EXPORT_FUNCTIONS</c> in +the last line of an eclass, outside of any inherit guards. +</note> + +<warning> +Old eclasses may put <c>EXPORT_FUNCTIONS</c> in other places, even before +<c>inherit</c>. They should <e>not</e> blindly be updated to follow the +recommended pattern here, as it could result in significant breakage. +</warning> + </body> </section> @@ -752,31 +738,108 @@ jmake_src_compile() { <p> Sometimes an eclass is used incorrectly by an ebuild and the eclass -knows it is being used incorrectly- the common example is an +knows it is being used incorrectly <d/> the common example is an eclass that only works with a specific set of EAPIs, but is being -accessed inherited by an ebuild with a different EAPI. +accessed (inherited) by an ebuild with a different EAPI. In those cases, used sparingly as a last resort, it is allowed for an eclass to invoke die from the global scope. For example: </p> <codesample lang="ebuild"> -# Copyright 1999-2019 Gentoo Foundation +# Copyright 1999-2022 Gentoo Authors # Distributed under the terms of the GNU General Public License v2 # @ECLASS: eapi-die.eclass # @MAINTAINER: # Gentoo Devmanual Project <devmanual@gentoo.org> +# @SUPPORTED_EAPIS: 7 8 # @BLURB: Calls die when used with an invalid EAPI. -case ${EAPI:-0} in - 0) die "this eclass doesn't support EAPI 0" ;; - *) ;; +case ${EAPI} in + 7|8) ;; + *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;; esac </codesample> </body> </section> +<section> +<title>Simple build system eclass example</title> +<body> + +<p> +Here is an example of how a simple eclass for a hypothetical <c>jmake</c> build +system might look. The eclass defines a few functions, along with default +implementations for the <c>src_configure</c> and <c>src_compile</c> phase +functions. +</p> + +<codesample lang="ebuild"> +# Copyright 1999-2022 Gentoo Authors +# Distributed under the terms of the GNU General Public License v2 + +# @ECLASS: jmake.eclass +# @MAINTAINER: +# Gentoo Devmanual Project <devmanual@gentoo.org> +# @AUTHOR: +# Ciaran McCreesh <ciaranm@gentoo.org> +# @BLURB: Demonstrate a simple build system eclass. +# @DESCRIPTION: +# Demonstrates EXPORT_FUNCTIONS and defines simple wrappers for the +# (hypothetical) jmake build system along with default src_configure and +# src_compile phase functions. + +case ${EAPI} in + 7|8) ;; + *) die "${ECLASS}: EAPI ${EAPI:-0} not supported" ;; +esac + +if [[ -z ${_JMAKE_ECLASS} ]]; then +_JMAKE_ECLASS=1 + +BDEPEND=">=sys-devel/jmake-2" + +# @FUNCTION: jmake-configure +# @USAGE: [additional-args] +# @DESCRIPTION: +# Passes all arguments through to the appropriate "jmake configure" +# command. +jmake_configure() { + jmake configure --prefix=/usr "$@" +} + +# @FUNCTION: jmake_src_configure +# @USAGE: [additional-args] +# @DESCRIPTION: +# Calls jmake_configure() to configure a jmake project. Passes all +# arguments through to the appropriate "jmake configure" command. +jmake_src_configure() { + jmake_configure "$@" || die "configure failed" +} + +# @FUNCTION: jmake_build +# @USAGE: [additional-args] +# @DESCRIPTION: +# First builds all dependencies, and then passes through its arguments +# to the appropriate "jmake build" command. +jmake_build() { + jmake dep && jmake build "$@" +} + +# @FUNCTION: jmake_src_compile +# @DESCRIPTION: +# Calls jmake_build() to compile a jmake project. +jmake_src_compile() { + jmake_build || die "build failed" +} + +fi + +EXPORT_FUNCTIONS src_configure src_compile +</codesample> + </body> +</section> </chapter> </guide> |