diff options
Diffstat (limited to 'ebuild-writing')
-rw-r--r-- | ebuild-writing/error-handling/text.xml | 134 | ||||
-rw-r--r-- | ebuild-writing/file-format/text.xml | 150 | ||||
-rw-r--r-- | ebuild-writing/messages/text.xml | 149 | ||||
-rw-r--r-- | ebuild-writing/text.xml | 15 | ||||
-rw-r--r-- | ebuild-writing/use-conditional-code/text.xml | 62 | ||||
-rw-r--r-- | ebuild-writing/users-and-groups/text.xml | 90 | ||||
-rw-r--r-- | ebuild-writing/using-eclasses/text.xml | 98 | ||||
-rw-r--r-- | ebuild-writing/variables/text.xml | 424 |
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 ]] && ( 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 < 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 && 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 && ( 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 && epatch ${FILESDIR}/${P}-ssl.patch + use sparc && 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 <name> [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 <user> [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> |