Initial descriptions of EAPIs, thanks to Markus Meier <maekke AT gentoo DOT org>; bug #208514

git-svn-id: svn+ssh://svn.gentoo.org/var/svnroot/devmanual/trunk@132 176d3534-300d-0410-8db8-84e73ed771c3
author: Mark Loeser <halcy0n@gentoo.org> 2008-10-04 21:05:05 +0000
committer: Mark Loeser <halcy0n@gentoo.org> 2008-10-04 21:05:05 +0000
commit: 5715346d8ec386b097579a0417806c5b78c094ff (patch)
tree: f81b133480e0140649ca946f786704c4e9bcba82
parent: Update documentation for LDFLAGS, thanks to Arfrever Frehtes Taifersar Arahes... (diff)
download: devmanual-5715346d8ec386b097579a0417806c5b78c094ff.tar.gz
devmanual-5715346d8ec386b097579a0417806c5b78c094ff.tar.bz2
devmanual-5715346d8ec386b097579a0417806c5b78c094ff.zip
2 files changed, 308 insertions, 0 deletions
diff --git a/ebuild-writing/eapi/text.xml b/ebuild-writing/eapi/text.xml
new file mode 100644
index 0000000..5fc0cb7
--- /dev/null
+++ b/ebuild-writing/eapi/text.xml
@@ -0,0 +1,307 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/eapi-description/">
+<chapter>
+<title>EAPI Usage and Description</title>
+
+<body>
+<p>
+This section provides usage and descriptions of the different EAPIs.
+</p>
+
+<section>
+<title>Usage of EAPIs</title>
+<body>
+<p>
+If EAPI is undefined in an ebuild, then EAPI="0" is selected. If you want to override
+the EAPI variable, you have to specify it at the top of the ebuild:
+</p>
+<codesample lang="ebuild">
+# Copyright 1999-2008 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+EAPI="1"
+
+inherit eutils
+
+</codesample>
+
+<important>
+EAPI must only be defined in ebuild files, not eclasses. (eclasses may have
+EAPI-conditional code)
+</important>
+
+</body>
+</section>
+
+<section>
+<title>EAPI="1"</title>
+<body>
+
+<ul>
+	<li>
+		<p><b>Default src_compile Phase Function</b></p>
+		<p>
+		Support for the <c>ECONF_SOURCE</c> variable, which is also supported by
+		<c>econf</c>, has been added to the default <c>src_compile</c> implementation.
+		</p>
+		<codesample lang="ebuild">
+src_compile() {
+	if [[ -x ${ECONF_SOURCE:-.}/configure ]] ; then
+		econf
+	fi
+	if [ -f Makefile ] || [ -f GNUmakefile ] || [ -f makefile ] ; then
+		emake || die "emake failed"
+	fi
+}
+		</codesample>
+	</li>
+	<li>
+		<p><b>SLOT dependencies</b></p>
+		<p>
+		Any valid atom can be constrained to match a specific SLOT. This
+		is accomplished by appending a colon to the atom, followed by a
+		SLOT value.
+		</p>
+		<p>
+		<b>SLOT dependency examples:</b>
+		<ul>
+			<li><c>x11-libs/qt:3</c></li>
+			<li><c>~x11-libs/qt-3.3.8:3</c></li>
+			<li><c>&gt;=x11-libs/qt-3.3.8:3</c></li>
+			<li><c>=x11-libs/qt-3.3*:3</c></li>
+		</ul>
+		</p>
+	</li>
+	<li>
+		<p><b>IUSE defaults</b></p>
+		<p>
+		Add + or - before the name of the use flag in IUSE to turn it on or off by
+		default.
+		</p>
+
+		<important>
+		The default USE-ordering is <c>USE_ORDER="env:pkg:conf:defaults:pkginternal:env.d"</c>
+		(see man make.conf)
+		</important>
+		<important>
+		Disabling default IUSE is pretty much useless as it does not
+		override the profile and user config (make.conf and package.use)
+		</important>
+
+		<codesample lang="ebuild">
+# Copyright 1999-2008 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+EAPI="1"
+
+IUSE="foo +bar"
+
+		</codesample>
+	</li>
+</ul>
+
+</body>
+</section>
+
+
+<section>
+<title>EAPI="2"</title>
+<body>
+
+<subsection>
+<title>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.
+		<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>
+		</p>
+	</li>
+</ul>
+</body>
+</subsection>
+
+<subsection>
+<title>Metadata</title>
+<body>
+<ul>
+	<li>
+		<p><b>Blocker Atoms</b></p>
+		<p>
+		<ul>
+			<li>
+				<p><b>New Meaning for Old Syntax</b></p>
+				<p>
+				Blocker atoms which use the previously existing !atom syntax now
+				have a slightly different meaning. These blocker atoms 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 !!atom Syntax</b></p>
+				<p>
+				A new !!atom syntax is now supported, for use in special cases for
+				which temporary simultaneous installation of conflicting packages
+				should not be allowed. If a given package happens to be blocked by
+				a mixture of atoms consisting of both the !atom and !!atom
+				syntaxes, the !!atom syntax takes precedence over the !atom
+				syntax.
+				</p>
+			</li>
+		</ul>
+		</p>
+	</li>
+	<li>
+		<p><b>USE Dependencies</b></p>
+		<p>
+		It is possible to depend on USE-flags of packages.
+		</p>
+		<p>Examples:
+		<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 packge 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>
+		</p>
+	</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>-&gt;</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="http://dl.google.com/earth/client/GE4/release_4_3/GoogleEarthLinux.bin
+                        -&gt; GoogleEarthLinux-${PV}.bin"
+		</codesample>
+	</li>
+</ul>
+</body>
+</subsection>
+
+<subsection>
+<title>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:
+		<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>
+		</p>
+	</li>
+	<li>
+		<p><b>Execution Order of Phase Functions</b></p>
+		<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>
+		</p>
+	</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:
+		<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>
+		</p>
+	</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>
+
+</body>
+</section>
+
+
+</body>
+</chapter>
+</guide>
diff --git a/ebuild-writing/text.xml b/ebuild-writing/text.xml
index c76336e..2f55b47 100644
--- a/ebuild-writing/text.xml
+++ b/ebuild-writing/text.xml
@@ -20,6 +20,7 @@ with some general notes and extended examples.
 </chapter>
 
 <include href="file-format/"/>
+<include href="eapi/"/>
 <include href="use-conditional-code/"/>
 <include href="error-handling/"/>
 <include href="users-and-groups/"/>
author	Mark Loeser <halcy0n@gentoo.org>	2008-10-04 21:05:05 +0000
committer	Mark Loeser <halcy0n@gentoo.org>	2008-10-04 21:05:05 +0000
commit	5715346d8ec386b097579a0417806c5b78c094ff (patch)
tree	f81b133480e0140649ca946f786704c4e9bcba82
parent	Update documentation for LDFLAGS, thanks to Arfrever Frehtes Taifersar Arahes... (diff)
download	devmanual-5715346d8ec386b097579a0417806c5b78c094ff.tar.gz devmanual-5715346d8ec386b097579a0417806c5b78c094ff.tar.bz2 devmanual-5715346d8ec386b097579a0417806c5b78c094ff.zip