diff options
| -rw-r--r-- | man/ebuild.5 | 60 |
1 files changed, 38 insertions, 22 deletions
diff --git a/man/ebuild.5 b/man/ebuild.5 index af8443df1..9a03e7d58 100644 --- a/man/ebuild.5 +++ b/man/ebuild.5 @@ -1,4 +1,4 @@ -.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" @@ -8,13 +8,14 @@ program accepts a single ebuild script as an argument. This script 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: $ @@ -51,10 +52,11 @@ src_install() { .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. @@ -92,7 +94,7 @@ Contains the package category name. .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. @@ -121,8 +123,8 @@ Should contain a short description of the package. .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 @@ -137,17 +139,18 @@ being submitted for inclusion, it must have ~arch set for architectures 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 @@ -342,13 +345,14 @@ or sun specifically. .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 @@ -507,6 +511,16 @@ Same as \fBeinfo\fR, but should be used when showing a warning to the user. .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 @@ -540,7 +554,9 @@ This is used as a replacement for make. Performs 'make ${MAKEOPTS} .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 |