-.TH "EBUILD" "5" "Dec 2005" "Portage 2.1" "portage"
+.TH "EBUILD" "5" "Mar 2006" "Portage 2.1" "portage"
.SH "NAME"
ebuild \- the internal format, variables, and functions in an ebuild script
.SH "DESCRIPTION"
contains variables and commands that specify how to download, unpack,
patch, compile, install and merge a particular software package from
its original sources. In addition to all of this, the ebuild script
-can also contain pre/post install/remove commands, as required.
+can also contain pre/post install/remove commands, as required. All
+ebuild scripts are written in bash.
.SH "EXAMPLES"
Here's a simple example ebuild:
.DS
.nf
-# Copyright 1999\-2005 Gentoo Foundation
+# Copyright 1999\-2006 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Header: $
.SH "VARIABLES"
.TP
.B MISC USAGE NOTES
-- PORTAGE* and PORTDIR* variables may be found in \fBmake.conf\fR(5).
+- All variables defined in \fBmake.conf\fR(5) are available for use in
+ebuilds (such as the PORTAGE* and PORTDIR* variables)
.br
-- When assigning values to variables in ebuilds, you \fBcannot have a space\fR
-between the variable name and the equal sign.
+- When assigning values to variables in ebuilds, you \fBcannot have a
+space\fR between the variable name and the equal sign.
.TP
.B P
This variable contains the package name without the ebuild revision.
.TP
.B A
Contains all source files required for the package. This variable must
-not be defined. It is autogenerated from the \fISRC_URI\fR variables.
+not be defined. It is autogenerated from the \fISRC_URI\fR variable.
.TP
\fBWORKDIR\fR = \fI"${PORTAGE_TMPDIR}/portage/${PF}/work"\fR
Contains the path to the package build root. Do not modify this variable.
.TP
\fBSRC_URI\fR = \fI"http://happy.com/little/${P}.tar.gz"\fR
Contains a list of URI's for the required source files. It can contain
-multiple URI's for a single source file. The fastest location is chosen
-if the file was not found at \fIGENTOO_MIRROR\fB\fR.
+multiple URI's for a single source file. The list is processed in order
+if the file was not found on any of the \fIGENTOO_MIRROR\fRs.
.TP
\fBHOMEPAGE\fR = \fI"http://happy.com/"\fR
Should contain a list of URL's for the sources main sites and other further
where it has been PROVEN TO WORK. (Packages KEYWORDed this way may be
unmasked for testing by setting ACCEPT_KEYWORDS="~arch" on the command
line, or in \fBmake.conf\fR(5)) For an authoritative list please review
-/usr/portage/profiles/arch.list.
+/usr/portage/profiles/arch.list. Please keep this list in alphabetical order.
.TP
\fBSLOT\fR
-This sets the SLOT for packages that may need to co\-exist. By default
-you should set \fBSLOT\fR="0" unless you know what you are doing and need
-to do otherwise. This value should \fINEVER\fR be left undefined.
+This sets the SLOT for packages that may need to have multiple versions
+co\-exist. By default you should set \fBSLOT\fR="0". If you are unsure, then
+do not fiddle with this until you seek some guidance from some guru. This
+value should \fINEVER\fR be left undefined.
.TP
\fBLICENSE\fR
This should be a space delimited list of licenses that the package falls
under. This \fB_must_\fR be set to a matching license in
-/usr/portage/licenses/. If the license does not exist in portage yet you
+/usr/portage/licenses/. If the license does not exist in portage yet, you
must add it first.
.TP
\fBIUSE\fR
.SH "PORTAGE DECLARATIONS"
.TP
.B inherit
-Inherit is portage's maintainance of extra classes of functions that
-are external to ebuilds and provided as inheritable capabilities and
-data. They define functions and set data types as drop-in replacements,
-expanded, and simplified routines for extremely common tasks to streamline
-the build process. Inherit may only be called once in an ebuild and it may
-\fBnever be wrapped within any conditionals\fR of any kind. Specification of
-the eclasses contains only their name and not the \fI.eclass\fR extention.
+Inherit is portage's maintainance of extra classes of functions that are
+external to ebuilds and provided as inheritable capabilities and data. They
+define functions and set data types as drop-in replacements, expanded, and
+simplified routines for extremely common tasks to streamline the build
+process. Inherit may only be called once in an ebuild and it may \fBnever be
+wrapped within any conditionals\fR of any kind. Specification of the eclasses
+contains only their name and not the \fI.eclass\fR extention. Also note that
+the inherit statement must come before other variable declarations.
.SH "FUNCTIONS"
.TP
.B pkg_nofetch
.TP
\fBeerror\fR \fI"error message"\fR
Same as \fBeinfo\fR, but should be used when showing an error to the user.
+.TP
+\fBebegin\fR \fI"helpful message"\fR
+Like \fBeinfo\fR, we output a \fIhelpful message\fR and then hint that the
+following operation may take some time to complete. Once the task is
+finished, you need to call \fBeend\fR.
+.TP
+\fBeend\fR \fI<status>\fR \fI["error message"]\fR
+Followup the \fBebegin\fR message with an appropriate "OK" or "!!" (for
+errors) marker. If \fIstatus\fR is non-zero, then the additional \fIerror
+message\fR is displayed.
.SH "HELPER FUNCTIONS: UNPACK"
.TP
\fBunpack\fR \fI<source>\fR \fI[list of more sources]\fR
.br
if you are going to use \fBemake\fR, make sure your build is happy with
parallel makes (make \-j2). It should be tested thoroughly as parallel
-makes are notorious for failing _sometimes_ but not always.
+makes are notorious for failing _sometimes_ but not always. If you determine
+that your package fails to build in parallel, and you are unable to resolve
+the issue, then you should run '\fBemake\fR -j1' instead of 'make'.
.SH "HELPER FUNCTIONS: INSTALL"
.TP
\fBeinstall\fR \fI[make options]\fR
projects / portage.git / commitdiff