aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat (limited to 'ebuild-writing')
-rw-r--r--ebuild-writing/error-handling/text.xml134
-rw-r--r--ebuild-writing/file-format/text.xml150
-rw-r--r--ebuild-writing/messages/text.xml149
-rw-r--r--ebuild-writing/text.xml15
-rw-r--r--ebuild-writing/use-conditional-code/text.xml62
-rw-r--r--ebuild-writing/users-and-groups/text.xml90
-rw-r--r--ebuild-writing/using-eclasses/text.xml98
-rw-r--r--ebuild-writing/variables/text.xml424
8 files changed, 1122 insertions, 0 deletions
diff --git a/ebuild-writing/error-handling/text.xml b/ebuild-writing/error-handling/text.xml
new file mode 100644
index 0000000..7931311
--- /dev/null
+++ b/ebuild-writing/error-handling/text.xml
@@ -0,0 +1,134 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/error-handling/">
+<chapter>
+<title>Error Handling</title>
+
+<section>
+<title>Importance of Error Handling</title>
+<body>
+
+<p>
+Decent error handling is important because:
+</p>
+
+<ul>
+ <li>
+ Errors must be detected <e>before</e> portage tries to install a broken or
+ incomplete package onto the live filesystem. If build failures aren't caught,
+ a working package could be unmerged and replaced with nothing.
+ </li>
+ <li>
+ When receiving bug reports, it is a lot easier to figure out what went wrong
+ if you know exactly which call caused the error, rather than just knowing
+ that, say, something somewhere in <c>src_compile</c> broke.
+ </li>
+ <li>
+ Good error handling and notification can help cut down on the number of bug
+ reports received for a package.
+ </li>
+</ul>
+
+</body>
+</section>
+
+<section>
+<title>The <c>die</c> Function</title>
+<body>
+
+<p>
+The <c>die</c> function should be used to indicate a fatal error and abort the
+build. Its parameters should be the message to display.
+</p>
+
+<p>
+Although <c>die</c> will work with no parameters, a short message should always be
+provided to ease error identification. This is especially important when a
+function can die in multiple places.
+</p>
+
+<p>
+Some portage-provided functions will automatically die upon failure. Others will
+not. It is safe to omit the <c>|| die</c> after a call to <c>epatch</c>, but not
+<c>econf</c> or <c>emake</c>.
+</p>
+
+<p>
+Sometimes displaying additional error information beforehand can be useful. Use
+<c>eerror</c> to do this. See `Messages`_.
+</p>
+
+</body>
+</section>
+
+<section>
+<title><c>die</c> and Subshells</title>
+<body>
+
+<warning>
+<c>die</c> <b>will not work in a subshell</b>.
+</warning>
+
+<p>
+The following code will not work as expected, since the <c>die</c> is inside a
+subshell:
+</p>
+
+<codesample lang="ebuild">
+[[ -f foorc ]] &amp;&amp; ( update_foorc || die "Couldn't update foorc!" )
+</codesample>
+
+<p>
+The correct way to rewrite this is to use an <c>if</c> block:
+</p>
+
+<codesample lang="ebuild">
+if [[ -f foorc ]] ; then
+ update_foorc || die "Couldn't update foorc!"
+fi
+</codesample>
+
+<p>
+When using pipes, a subshell is introduced, so the following is unsafe:
+</p>
+
+<codesample lang="ebuild">
+cat list | while read file ; do epatch ${file} ; done
+</codesample>
+
+<p>
+Using input redirection (see `Abuse of cat`_) avoids this problem:
+</p>
+
+<codesample lang="ebuild">
+while read file ; do epatch ${file} ; done &lt; list
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>The <c>assert</c> Function and <c>$PIPESTATUS</c></title>
+<body>
+
+<p>
+When using pipes, simple conditionals and tests upon <c>$?</c> will not correctly
+detect errors occurring in anything except the final command in the chain. To get
+around this, <c>bash</c> provides the <c>$PIPESTATUS</c> variable, and portage
+provides the <c>assert</c> function to check this variable.
+</p>
+
+<codesample lang="ebuild">
+bunzip2 ${DISTDIR}/${VIM_RUNTIME_SNAP} | tar xf
+assert
+</codesample>
+
+<p>
+If you need the gory details of <c>$PIPESTATUS</c>, see the bash manpage. Most of the
+time, <c>assert</c> is enough.
+</p>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/file-format/text.xml b/ebuild-writing/file-format/text.xml
new file mode 100644
index 0000000..499a60c
--- /dev/null
+++ b/ebuild-writing/file-format/text.xml
@@ -0,0 +1,150 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/file-format/">
+<chapter>
+<title>Ebuild File Format</title>
+
+<body>
+<p>
+An ebuild is a <c>bash</c> script which is executed within a special environment.
+Files should be simple text files with a <c>.ebuild</c> extension.
+</p>
+</body>
+
+<section>
+<title>File Naming Rules</title>
+<body>
+
+<p>
+An ebuild should be named in the form <c>name-version.ebuild</c>.
+</p>
+
+<p>
+The name section should contain only lowercase non-accented letters, the digits
+0-9, hyphens, underscores and plus characters. Uppercase characters are strongly
+discouraged, but technically valid.
+</p>
+
+<note>
+This is the same as `IEEE1003.1-2004-3.276`_, with the addition of the plus
+character to keep GTK+ and friends happy.
+</note>
+
+<p>
+The version section is more complicated. It consists of one or more numbers
+separated by full stop (or period, or dot, or decimal point) characters (eg
+<c>1.2.3</c>, <c>20050108</c>). The final number may have a single letter following it
+(e.g. <c>1.2b</c>). This letter should not be used to indicate 'beta' status --
+portage treats <c>1.2b</c> as being a later version than <c>1.2</c> or <c>1.2a</c>.
+</p>
+
+<p>
+There can be a suffix to version indicating the kind of release. In the following table,
+what portage considers to be the 'lowest' version comes first.
+</p>
+
+<table>
+ <tr>
+ <th>Suffix</th>
+ <th>Meaning</th>
+ </tr>
+ <tr>
+ <ti><c>_alpha</c></ti>
+ <ti>Alpha release (earliest)</ti>
+ </tr>
+ <tr>
+ <ti><c>_beta</c></ti>
+ <ti>Beta release</ti>
+ </tr>
+ <tr>
+ <ti><c>_pre</c></ti>
+ <ti>Pre release</ti>
+ </tr>
+ <tr>
+ <ti><c>_rc</c></ti>
+ <ti>Release candidate</ti>
+ </tr>
+ <tr>
+ <ti>(no suffix)</ti>
+ <ti>Normal release</ti>
+ </tr>
+ <tr>
+ <ti>_p</ti>
+ <ti>Patch level</ti>
+ </tr>
+</table>
+
+<p>
+Any of these suffixes may be followed by a non-zero positive integer.
+</p>
+
+<p>
+Finally, version may have a Gentoo revision number in the form <c>-r1</c>. The initial
+Gentoo version should have no revision suffix, the first revision should be
+<c>-r1</c>, the second <c>-r2</c> and so on. See `Ebuild Revisions`_.
+</p>
+
+<p>
+Overall, this gives us a filename like <c>libfoo-1.2.5b_pre5-r2.ebuild</c>.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Ebuild Header</title>
+<body>
+
+<p>
+All ebuilds committed to the tree should have a three line header immediately at
+the start indicating copyright. This must be an exact copy of the contents of
+<c>$(portageq portdir)/header.txt</c>. Ensure that the <c>$Header: $</c> line is not
+modified manually -- CVS will handle this line specially.
+</p>
+
+<codesample lang="ebuild">
+# Copyright 1999-2006 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Indenting and Whitespace</title>
+<body>
+
+<p>
+Indenting in ebuilds must be done with tabs, one tab per indent
+level. Each tab represents four spaces. Tabs should only be used for
+indenting, never inside strings.
+</p>
+
+<p>
+Avoid trailing whitespace: repoman will warn you about this if your
+ebuild contains trailing or leading whitespace (whitespace instead of
+tabs for indentation) when you commit.
+</p>
+
+<p>
+Where possible, try to keep lines no wider than 80 positions. A
+'position' is generally the same as a character -- tabs are four
+positions wide, and multibyte characters are just one position wide.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Character Set</title>
+<body>
+<p>
+All ebuilds (and eclasses, metadata files and ChangeLogs) must use the
+UTF-8 character set. See `GLEP 31`_ for details, and `glep31check`_
+for an easy way of checking for validity.
+</p>
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/messages/text.xml b/ebuild-writing/messages/text.xml
new file mode 100644
index 0000000..bcb002e
--- /dev/null
+++ b/ebuild-writing/messages/text.xml
@@ -0,0 +1,149 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/users-and-groups/">
+<chapter>
+<title>Messages</title>
+
+<body>
+<p>
+Sometimes it is necessary to display messages for the user. This can be for
+errors, post-install help messages, pre-install warnings or simply to notify the
+user of what's going on. It is considered good form to display a message
+before any particularly long and silent task is carried out, for example (and it
+also helps cut down on bogus "compiling foo froze!" bugs).
+</p>
+
+<note>
+It is a policy violation to use any of these functions to display a line
+of characters (a banner header). The use of colours and special leading
+characters provided by these functions is sufficient to make a message stand
+out.
+</note>
+
+<p>
+In all cases, assume that the user's terminal is no wider than 79 columns, and
+that the <c>einfo</c>, <c>ewarn</c> and <c>eerror</c> functions will occupy 4 columns
+with their fancy leading markers.
+</p>
+
+</body>
+
+<section>
+<title>Information Messages</title>
+<body>
+
+<p>
+There are a number of functions available to assist here. The `echo` bash
+internal is the simplest -- it simply displays its parameters as a message.
+</p>
+
+<p>
+The <c>einfo</c> function can be used to display an informational message which is
+meant to 'stand out'. On a colour terminal, the message provided will be
+prefixed with a green asterisk.
+</p>
+
+<codesample lang="ebuild">
+pkg_postinst() {
+ einfo "You will need to set up your /etc/foo/foo.conf file before"
+ einfo "running foo for the first time. For details, please see the"
+ einfo "foo.conf(5) manual page."
+}
+</codesample>
+
+</body>
+</section>
+
+<section>
+<title>Warning Messages</title>
+<body>
+
+<p>
+The <c>ewarn</c> function is similar, but displays a yellow asterisk. This should be
+used for warning messages rather than information.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Error Messages</title>
+<body>
+
+<p>
+The <c>eerror</c> function displays a red star, and is used for displaying error
+messages. It should almost always be followed by a <c>die</c> call. This function
+is mainly used for displaying additional error details before bailing out.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Important Messages</title>
+<body>
+
+<p>
+For <e>really</e> important messages, <c>eutils.eclass</c> provides <c>ebeep</c> and
+<c>epause</c>. The former will beep a number of times, and the latter will pause
+for several seconds to allow the user to read any messages. Both can be disabled
+by the user -- you must <b>not</b> attempt to override the user's preference in
+this. <c>ebeep</c> takes an optional parameter specifying how many times to beep.
+<c>epause</c> takes an optional parameter (which <b>must</b> be an exact whole number)
+specifying for how long it should sleep.
+</p>
+
+<p>
+Do not abuse these functions -- better to save them for when things really are
+important.
+</p>
+
+<p>
+See `Message Functions Reference`_ for a full list of functions.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Good and Bad Messages</title>
+<body>
+
+<p>
+Here is an example of a bad message:
+</p>
+
+<codesample lang="ebuild">
+i=10
+while ((i--)) ; do
+ ewarn "PLEASE UPDATE TO YOUR PACKAGE TO USE linux-info.eclass"
+done
+</codesample>
+
+<ul>
+ <li>Displaying the same message repeatedly is excessive.</li>
+ <li>The uppercase is excessive.</li>
+ <li>The bad English looks unprofessional.</li>
+ <li>
+ The message will only confuse the end user and will not help them work out
+ whether they have a problem and how to solve it if they do.
+ </li>
+</ul>
+
+<p>
+It would be better written as:
+</p>
+
+<codesample lang="ebuild">
+ewarn "The 'frozbinate' function provided by eutils.eclass is deprecated"
+ewarn "in favour of frozbinate.eclass, but this package has not been"
+ewarn "updated yet. If this is a package from the main tree, please check"
+ewarn "http://bugs.gentoo.org/ and file a bug if there is not one already."
+ewarn "If this is your own package, please read the comments in the"
+ewarn "frozbinate eclass for instructions on how to convert."
+</codesample>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/text.xml b/ebuild-writing/text.xml
index 41bb84b..ace7fa2 100644
--- a/ebuild-writing/text.xml
+++ b/ebuild-writing/text.xml
@@ -9,6 +9,21 @@ This section covers some general concepts with which you should be familiar when
writing ebuilds or working with the portage tree.
</p>
</body>
+
+<section>
+<title>Contents</title>
+<body>
+<contentsTree/>
+</body>
+</section>
+
</chapter>
+<include href="file-format/"/>
+<include href="use-conditional-code/"/>
+<include href="error-handling/"/>
+<include href="users-and-groups/"/>
+<include href="messages/"/>
+<include href="variables/"/>
+<include href="using-eclasses/"/>
<include href="ebuild-functions/"/>
</guide>
diff --git a/ebuild-writing/use-conditional-code/text.xml b/ebuild-writing/use-conditional-code/text.xml
new file mode 100644
index 0000000..84fc490
--- /dev/null
+++ b/ebuild-writing/use-conditional-code/text.xml
@@ -0,0 +1,62 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/use-conditional-code/">
+<chapter>
+<title>USE Flag Conditional Code</title>
+
+<body>
+<p>
+Often a particular block of code must only be executed if a given USE flag is
+set (or unset). For large blocks, <c>if use foo</c> is best, or for inverse tests
+either <c>if ! use foo</c> or <c>if use !foo</c> can be used (the former is more
+common and is recommended for readability). For single-statement conditions, the
+<c>use foo &amp;&amp; blah</c> (or <c>use foo || blah</c> for negatives) form is often more
+readable.
+</p>
+
+<p>
+The <c>if [ "`use foo`" ]</c> and <c>if [ -n "`use foo`" ]</c> forms which are
+occasionally seen in older code must <b>not</b> be used.
+</p>
+
+<note>
+<c>die</c> will not work as expected within a subshell, so code in the
+form <c>use foo &amp;&amp; ( blah ; blah )</c> should be avoided in favour of a proper if
+statement. See `die and Subshells`_.
+</note>
+
+<codesample lang="ebuild">
+ # USE conditional blocks...
+ if use livecd ; then
+ # remove some extra files for a small livecd install
+ rm -fr ${vimfiles}/{compiler,doc,ftplugin,indent}
+ fi
+
+ # Inverse USE conditional blocks...
+ if ! use cscope ; then
+ # the --disable-cscope configure arg doesn't quite work properly,
+ # so sed it out of feature.h if we're not USEing cscope.
+ sed -i -e '/# define FEAT_CSCOPE/d' src/feature.h || die "couldn't disable cscope"
+ fi
+
+ # USE conditional statements...
+ use ssl &amp;&amp; epatch ${FILESDIR}/${P}-ssl.patch
+ use sparc &amp;&amp; filter-flags -fomit-frame-pointer
+
+ # Inverse USE conditional statements...
+ use ncurses || epatch ${FILESDIR}/${P}-no-ncurses.patch
+</codesample>
+
+<p>
+For echoing content based upon a USE flag, there is often a better helper
+function available.
+</p>
+
+<p>
+You must not rely upon <c>use</c> producing an output -- this no longer happens.
+If you really need output displayed, use the <c>usev</c> function. The
+<c>useq</c> function is available for explicitly requesting no output.
+</p>
+</body>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/users-and-groups/text.xml b/ebuild-writing/users-and-groups/text.xml
new file mode 100644
index 0000000..7dc774b
--- /dev/null
+++ b/ebuild-writing/users-and-groups/text.xml
@@ -0,0 +1,90 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/users-and-groups/">
+<chapter>
+<title>Users and Groups</title>
+
+<body>
+<p>
+If your ebuild requires a user or group to be added for a daemon, for example,
+this should be performed via the functions available in <c>eutils.eclass</c>.
+Regardless of whether you are adding a group or a user, this should be performed
+in the <c>pkg_setup</c> function and <b>not</b> somewhere else: pkg_setup is sandbox-safe,
+is called before the compile process so a build that requires the user to exist will
+have it, and is also called for both binary and source packages.
+</p>
+</body>
+
+<section>
+<title>Adding Groups</title>
+<body>
+
+<p>
+To add a group, use the <c>enewgroup</c> function:
+</p>
+
+<pre>
+enewgroup &lt;name&gt; [uid]
+</pre>
+
+<p>
+By default the next available group ID is selected. To set a specfic group ID,
+pass it an extra argument to <c>enewgroup</c>.
+</p>
+
+<note>
+Group IDs should rarely be hardcoded. If this is the case, you should
+probably check first on gentoo-dev.
+</note>
+
+</body>
+</section>
+
+<section>
+<title>Adding Users</title>
+<body>
+
+<p>
+To add a user, use the <c>enewuser</c> function:
+</p>
+
+<pre>
+enewuser &lt;user&gt; [uid] [shell] [homedir] [groups] [params]
+</pre>
+
+<p>
+By default, both <c>enewuser</c> and <c>enewgroup</c> allocate the next available user
+ID or group ID to the new user or group - if not, you explicitly have to specify
+one.
+</p>
+
+<p>
+Arguments for <c>enewuser</c> must be passed in the order as shown above: if you do
+not want to specify a fixed user ID however but do want to set a specific shell,
+for example, use <c>-1</c> for the <c>uid</c> parameter. The same applies for any other
+parameter where you want to keep the default setting.
+</p>
+
+<p>
+Groups for the <c>groups</c> argument should be separated by a comma (<c>,</c>) and
+wrapped correctly, for example:
+</p>
+
+<pre>
+enewuser frozd -1 -1 -1 "backup,frozd"
+</pre>
+
+<p>
+Finally, any data left over for the <c>params</c> argument is passed directly to
+useradd.
+</p>
+
+<note>
+User IDs should rarely be hardcoded. If this is the case, you should
+probably check first on gentoo-dev.
+</note>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/using-eclasses/text.xml b/ebuild-writing/using-eclasses/text.xml
new file mode 100644
index 0000000..171d967
--- /dev/null
+++ b/ebuild-writing/using-eclasses/text.xml
@@ -0,0 +1,98 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/using-eclasses/">
+<chapter>
+<title>Using Eclasses</title>
+
+<body>
+<p>
+An eclass is a collection (library) of functions or functionality that is shared
+between packages. See `Eclass Writing Guide`_ for the full story on what
+eclasses can do, how they work and how to write them, and `Eclass Reference`_
+for documentation on various commonly used eclasses. This section only explains
+how to use an eclass which has already been written.
+</p>
+</body>
+
+<section>
+<title>The <c>inherit</c> Function</title>
+<body>
+
+<p>
+To use an eclass, it must be 'inherited'. This is done via the <c>inherit</c>
+function, which is provided by <c>ebuild.sh</c>. The <c>inherit</c> statement must
+come at the top of the ebuild, *before* any functions. Conditional inherits are
+illegal (except where the inheritance criteria are cache-constant -- see `The
+Portage Cache`_).
+</p>
+
+<p>
+After inheriting an eclass, its provided functions can be used as normal. Here's
+<c>devtodo-0.1.18-r2.ebuild</c>, which uses three eclasses:
+</p>
+
+<codesample lang="ebuild">
+# Copyright 1999-2005 Gentoo Foundation
+# Distributed under the terms of the GNU General Public License v2
+# $Header: $
+
+inherit eutils bash-completion flag-o-matic
+
+DESCRIPTION="A nice command line todo list for developers"
+HOMEPAGE="http://swapoff.org/DevTodo"
+SRC_URI="http://swapoff.org/files/${PN}/${P}.tar.gz"
+
+LICENSE="GPL-2"
+SLOT="0"
+KEYWORDS="alpha amd64 arm hppa ia64 mips ppc s390 sparc x86 ppc64"
+IUSE=""
+
+RDEPEND=">=sys-libs/ncurses-5.2
+ >=sys-libs/readline-4.1"
+DEPEND="${RDEPEND}"
+
+src_unpack() {
+ unpack ${A}
+ cd ${S}
+ epatch ${FILESDIR}/${P}-gentoo.diff
+}
+
+src_compile() {
+ einfo "Running autoreconf"
+ autoreconf -f -i || die "autoreconf failed"
+ replace-flags -O? -O1
+ econf --sysconfdir=/etc/devtodo || die "econf failed"
+ emake || die "emake failed"
+}
+
+src_install() {
+ make DESTDIR=${D} install || die "make install failed"
+ dodoc AUTHORS ChangeLog QuickStart README TODO doc/scripts.sh \
+ doc/scripts.tcsh doc/todorc.example contrib/tdrec || die "dodoc failed"
+ dobashcompletion ${FILESDIR}/${PN}.bash-completion ${PN}
+}
+
+pkg_postinst() {
+ echo
+ einfo "Because of a conflict with app-misc/tdl, the tdl symbolic link"
+ einfo "and manual page have been removed."
+ bash-completion_pkg_postinst
+}
+</codesample>
+
+<p>
+Note the <c>inherit</c> immediately after the header.
+</p>
+
+<p>
+The <c>eutils</c> eclass (see `eutils.eclass Reference`_) is needed to get the
+<c>epatch</c> function. The <c>flag-o-matic</c> eclass (see `flag-o-matic.eclass
+Reference`_) is needed for <c>replace-flags</c>, and the <c>bash-completion</c> eclass
+(`bash-completion.eclass Reference`_) is used to handle the bash completion file
+via <c>dobashcompletion</c> and <c>bash-completion_pkg_postinst</c>.
+</p>
+
+</body>
+</section>
+
+</chapter>
+</guide>
diff --git a/ebuild-writing/variables/text.xml b/ebuild-writing/variables/text.xml
new file mode 100644
index 0000000..d6f5aec
--- /dev/null
+++ b/ebuild-writing/variables/text.xml
@@ -0,0 +1,424 @@
+<?xml version="1.0"?>
+<guide self="ebuild-writing/variables/">
+<chapter>
+<title>Variables</title>
+
+<body>
+<p>
+There are a number of special variables which must be set in ebuilds, and many
+more which can optionally be specified. There are also some predefined variables
+which are of use throughout the ebuild.
+</p>
+</body>
+
+<section>
+<title>Predefined Read-Only Variables</title>
+<body>
+
+<p>
+The following variables are defined for you. You must not attempt to set
+them.
+</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Purpose</th>
+ </tr>
+ <tr>
+ <ti><c>P</c></ti>
+ <ti>Package name and version (excluding revision, if any), for example <c>vim-6.3</c>.</ti>
+ </tr>
+ <tr>
+ <ti><c>PN</c></ti>
+ <ti>Package name, for example <c>vim</c>.</ti>
+ </tr>
+ <tr>
+ <ti><c>PV</c></ti>
+ <ti>Package version (excluding revision, if any), for example <c>6.3</c>.</ti>
+ </tr>
+ <tr>
+ <ti><c>PR</c></ti>
+ <ti>Package revision, or <c>r0</c> if no revision exists.</ti>
+ </tr>
+ <tr>
+ <ti><c>PVR</c></ti>
+ <ti>Package version and revision, for example <c>6.3-r0</c>, <c>6.3-r1</c>.</ti>
+ </tr>
+ <tr>
+ <ti><c>PF</c></ti>
+ <ti>Package name, version and revision, for example <c>vim-6.3-r1</c>.</ti>
+ </tr>
+ <tr>
+ <ti><c>A</c></ti>
+ <ti>
+ All the source files for the package (excluding those
+ which are not available because of <c>USE</c> flags).
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>CATEGORY</c></ti>
+ <ti>Package's category, for example <c>app-editors</c>.</ti>
+ </tr>
+ <tr>
+ <ti><c>FILESDIR</c></ti>
+ <ti>
+ Path to the ebuild's <c>files/</c> directory, commonly used
+ for small patches and files. Value:
+ <c>"${PORTDIR}/${CATEGORY}/${PN}/files"</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>WORKDIR</c></ti>
+ <ti>
+ Path to the ebuild's root build directory. Value:
+ <c>"${PORTAGE_TMPDIR}/portage/${PF}/work"</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>T</c></ti>
+ <ti>
+ Path to a temporary directory which may be used by the
+ ebuild. Value: <c>"${PORTAGE_TMPDIR}/portage/${PF}/temp"</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>D</c></ti>
+ <ti>
+ Path to the temporary install directory. Value:
+ <c>"${PORTAGE_TMPDIR}/portage/${PF}/image"</c>.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>ROOT</c></ti>
+ <ti>
+ Path to the root directory. When not using <c>${D}</c>,
+ always prepend <c>${ROOT}</c> to the path.
+ </ti>
+ </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>Required Variables</title>
+<body>
+
+<p>
+The following variables must be defined by every ebuild.
+</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Purpose</th>
+ </tr>
+ <tr>
+ <ti><c>DESCRIPTION</c></ti>
+ <ti>
+ A short (less than 80 characters) description of the
+ package's purpose.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>SRC_URI</c></ti>
+ <ti>
+ A list of source URIs for the package. Can contain
+ <c>USE</c>-conditional parts, see `SRC_URI`_.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>HOMEPAGE</c></ti>
+ <ti>Package's homepage</ti>
+ </tr>
+ <tr>
+ <ti><c>KEYWORDS</c></ti>
+ <ti>See `KEYWORDS`_ and `Keywording`_.</ti>
+ </tr>
+ <tr>
+ <ti><c>SLOT</c></ti>
+ <ti>The package's <c>SLOT</c>. See `SLOT`_.</ti>
+ </tr>
+ <tr>
+ <ti><c>LICENSE</c></ti>
+ <ti>
+ The package's license, corresponding exactly (including
+ case) to a file in <c>licenses/</c>. See `LICENSE`_.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>IUSE</c></ti>
+ <ti>
+ A list of all <c>USE</c> flags (excluding arch and auto
+ expand flags) used within the ebuild. See `IUSE`_.
+ </ti>
+ </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>Optional Variables</title>
+<body>
+
+<p>
+Specifying the following variables is optional:
+</p>
+
+<table>
+ <tr>
+ <th>Variable</th>
+ <th>Purpose</th>
+ </tr>
+ <tr>
+ <ti><c>S</c></ti>
+ <ti>
+ Path to the temporary build directory, used by
+ <c>src_compile</c> and <c>src_install</c>. Default:
+ <c>"${WORKDIR}/${P}"</c>. Ebuilds should <b>not</b> provide a
+ value for this ebuild if it is the default.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>DEPEND</c></ti>
+ <ti>
+ A list of the package's build dependencies. See
+ `Dependencies`_.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>RDEPEND</c></ti>
+ <ti>
+ A list of the package's runtime dependencies. See
+ `Dependencies`_.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>PDEPEND</c></ti>
+ <ti>
+ A list of packages to be installed after the package
+ is merged. Should only be used where <c>RDEPEND</c> is not
+ possible. See `Dependencies`_.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>RESTRICT</c></ti>
+ <ti>
+ A space-delimited list of portage features to restrict.
+ Valid values are <c>nostrip</c>, <c>nomirror</c>, <c>nouserpriv</c>
+ and <c>fetch</c>. See `ebuild-5`_ for details.
+ </ti>
+ </tr>
+ <tr>
+ <ti><c>PROVIDE</c></ti>
+ <ti>
+ Any virtuals provided by this package, for example
+ <c>"virtual/editor virtual/emacs"</c>.
+ </ti>
+ </tr>
+</table>
+
+</body>
+</section>
+
+<section>
+<title>SLOT</title>
+<body>
+
+<p>
+When slots are not needed, use <c>SLOT="0"</c>. Do <b>not</b> use <c>SLOT=""</c>, as
+this will disable slotting for this package.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>KEYWORDS</title>
+<body>
+
+<p>
+The only valid construct involving a <c>*</c> inside <c>KEYWORDS</c> is a <c>-*</c>. Do
+<b>not</b> use <c>KEYWORDS="*"</c> or <c>KEYWORDS="~*"</c>.
+</p>
+
+<p>
+See `Keywording`_ for how to handle this variable.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>SRC_URI</title>
+
+<subsection>
+<title>Conditional Sources</title>
+<body>
+
+<p>
+Conditional source files based upon USE flags are allowed using the usual
+<c>flag? ( )</c> syntax. This is often useful for arch-specific code or for binary
+packages -- downloading sparc binaries on ppc would be a waste of bandwidth.
+</p>
+
+<codesample lang="ebuild">
+SRC_URI="http://example.com/files/${P}-core.tar.bz2
+ x86? ( http://example.com/files/${P}/${P}-sse-asm.tar.bz2 )
+ ppc? ( http://example.com/files/${P}/${P}-vmx-asm.tar.bz2 )
+ sparc? ( http://example.com/files/${P}/${P}-vis-asm.tar.bz2 )
+ doc? ( http://example.com/files/${P}/${P}-docs.tar.bz2 )"
+</codesample>
+
+<p>
+When creating digests it may be necessary to have <e>all</e> SRC_URI components
+downloaded. If you have <c>FEATURES="cvs"</c> set, portage should get this right,
+although you may end up downloading more than necessary.
+</p>
+
+<p>
+If a <c>USE_EXPAND</c> variable is used to control whether certain optional
+components are installed, the correct thing to do if the variable is unset is
+generally to install <e>all</e> available components.
+</p>
+
+<codesample lang="ebuild">
+SRC_URI="http://example.com/files/${P}-core.tar.bz2
+ examplecards_foo? ( http://example.com/files/${P}-foo.tar.bz2 )
+ examplecards_bar? ( http://example.com/files/${P}-bar.tar.bz2 )
+ examplecards_baz? ( http://example.com/files/${P}-baz.tar.bz2 )
+ !examplecards_foo? ( !examplecards_bar? ( !examplecards_baz? (
+ http://example.com/files/${P}-foo.tar.bz2
+ http://example.com/files/${P}-bar.tar.bz2
+ http://example.com/files/${P}-baz.tar.bz2 ) ) )"
+</codesample>
+
+</body>
+</subsection>
+</section>
+
+<section>
+<title>IUSE</title>
+<body>
+
+<p>
+Note that the <c>IUSE</c> variable is cumulative, so there is no need to specify
+USE flags used only within inherited eclasses within the ebuild's IUSE. Also
+note that it's really really broken in portage versions before 2.0.51.
+</p>
+
+<p>
+Arch USE flags (<c>sparc</c>, <c>mips</c>, <c>x86-fbsd</c> and so on) should not be
+listed. Neither should auto-expand flags (<c>linguas_en</c> and so on).
+</p>
+
+</body>
+</section>
+
+<section>
+<title>LICENSE</title>
+<body>
+
+<p>
+It is possible to specify multiple <c>LICENSE</c> entries, and entries which only
+apply if a particular <c>USE</c> flag is set. The format is the same as for
+<c>DEPEND</c>. See `GLEP 23`_ for details.
+</p>
+
+</body>
+</section>
+
+<section>
+<title>Version Formatting Issues</title>
+<body>
+
+<p>
+Often upstream's tarball versioning format doesn't quite follow Gentoo
+conventions. Differences in how underscores and hyphens are used are
+particularly common. For example, what Gentoo calls <c>foo-1.2.3b</c> may be
+expecting a tarball named <c>foo-1.2-3b.tar.bz2</c>. Rather than hard coding version
+numbers, it is preferable to make a <c>MY_PV</c> variable and use that. The easy
+way to do this, which should be used unless you are sure you know what you are
+doing, is to use the <c>versionator</c> eclass:
+</p>
+
+<codesample lang="ebuild">
+inherit versionator
+MY_PV=$(replace_version_separator 2 '-')
+</codesample>
+
+<p>
+This code has the advantage that it will carry on working even if upstream
+switches to a format like <c>foo-1.3-4.5.tar.bz2</c> (yes, this really happens).
+</p>
+
+<p>
+It is also possible to use bash substitution to achieve the same effect (this is
+how versionator works internally), but this is complicated, error prone and hard
+to read.
+</p>
+
+<p>
+Some ebuilds use calls to <c>sed</c>, <c>awk</c> and / or <c>cut</c> to do this. This
+must <e>not</e> be done for any new code, and should be fixed to use either
+versionator or bash substitution where possible. Global scope non-bash code is
+highly discouraged.
+</p>
+
+<p>
+The <c>versionator</c> eclass can also be used to extract particular components
+from a version string. See `versionator.eclass-5`_ and the eclass source code
+for further documentation and examples. A brief summary of the functions
+follows.
+</p>
+
+<table>
+ <tr>
+ <th>Function</th>
+ <th>Purpose</th>
+ </tr>
+ <tr>
+ <ti><c>get_all_version_components</c></ti>
+ <ti>Split up a version string into its component parts.</ti>
+ </tr>
+ <tr>
+ <ti><c>get_version_components</c></ti>
+ <ti>Get important version components, excluding '.', '-' and '_'.</ti>
+ </tr>
+ <tr>
+ <ti><c>get_major_version</c></ti>
+ <ti>Get the major version.</ti>
+ </tr>
+ <tr>
+ <ti><c>get_version_component_range</c></ti>
+ <ti>Extract a range of subparts from a version string.</ti>
+ </tr>
+ <tr>
+ <ti><c>get_after_major_version</c></ti>
+ <ti>Get everything after the major version.</ti>
+ </tr>
+ <tr>
+ <ti><c>replace_version_separator</c></ti>
+ <ti>Replace a particular version separator.</ti>
+ </tr>
+ <tr>
+ <ti><c>replace_all_version_separators</c></ti>
+ <ti>Replace all version separators.</ti>
+ </tr>
+ <tr>
+ <ti><c>delete_version_separator</c></ti>
+ <ti>Delete a version separator.</ti>
+ </tr>
+ <tr>
+ <ti><c>delete_all_version_separators</c></ti>
+ <ti>Delete all version separators.</ti>
+ </tr>
+</table>
+
+</body>
+</section>
+
+</chapter>
+</guide>