-.TH "EBUILD" "5" "Sep 2010" "Portage VERSION" "Portage"
+.TH "EBUILD" "5" "Sep 2012" "Portage VERSION" "Portage"
.SH "NAME"
ebuild \- the internal format, variables, and functions in an ebuild script
.SH "DESCRIPTION"
Contains the path to the 'files' sub folder in the package specific
location in the portage tree. Do not modify this variable.
.TP
+.B EBUILD_PHASE
+Contains the abreviated name of the phase function that is
+currently executing, such as "setup", "unpack", "compile", or
+"preinst".
+.TP
+.B EBUILD_PHASE_FUNC
+Beginning with \fBEAPI 5\fR, contains the full name of the phase
+function that is currently executing, such as "pkg_setup",
+"src_unpack", "src_compile", or "pkg_preinst".
+.TP
.B EPREFIX
Beginning with \fBEAPI 3\fR, contains the offset
that this Portage was configured for during
package will be required to have a version of portage that recognizes
the EAPI to which this package conforms.
.TP
-\fBSRC_URI\fR = \fI"http://happy.com/little/${P}.tar.gz"\fR
+\fBSRC_URI\fR = \fI"http://example.com/path/${P}.tar.gz"\fR
Contains a list of URIs for the required source files. It can contain
multiple URIs for a single source file. The list is processed in order
if the file was not found on any of the \fIGENTOO_MIRRORS\fR.
desired output file name. All tokens, including the operator and output
file name, should be separated by whitespace.
.TP
-\fBHOMEPAGE\fR = \fI"http://happy.com/"\fR
+\fBHOMEPAGE\fR = \fI"http://example.com/"\fR
Should contain a list of URIs for the sources main sites and other further
package dependent information.
.TP
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.
+
+Beginning with \fBEAPI 5\fR, the SLOT variable may contain
+an optional sub\-slot part that follows the regular slot and
+is delimited by a / character. The sub\-slot must be a valid
+slot name. The sub\-slot is used to represent cases in which
+an upgrade to a new version of a package with a different
+sub\-slot may require dependent packages to be rebuilt. When
+the sub\-slot part is omitted from the SLOT definition, the
+package is considered to have an implicit sub\-slot which is
+equal to the regular slot. Refer to the \fBAtom Slot
+Operators\fR section for more information about sub\-slot
+usage.
.TP
\fBLICENSE\fR
This should be a space delimited list of licenses that the package falls
that respectively enable or disable the corresponding \fBUSE\fR flags. For
details about \fBUSE\fR flag stacking order, refer to the \fBUSE_ORDER\fR
variable in \fBmake.conf\fR(5). Given the default \fBUSE_ORDER\fR setting,
-negative IUSE default settings are ineffective since profile and user
-configuration settings override them.
+negative IUSE default settings are effective only for negation of
+repo\-level USE settings, since profile and user configuration settings
+override them.
.TP
\fBDEPEND\fR
This should contain a list of all packages that are required for the
\fI>=\fRx11\-libs/qt-3.3.8:3
\fI=\fRx11\-libs/qt-3.3*:3
.fi
+
+Beginning with \fBEAPI 5\fR, a slot dependency may contain an
+optional sub\-slot part that follows the regular slot and is
+delimited by a \fB/\fR character.
+
+.I Examples:
+
+.nf
+dev\-libs/icu:0/0
+dev\-libs/icu:0/49
+dev\-lang/perl:0/5.12
+dev\-libs/glib:2/2.30
+.fi
+
+.TP
+.B Atom Slot Operators
+Beginning with \fBEAPI 5\fR, slot operator dependency consists
+of a colon followed by one of the following operators:
+.RS
+.TP
+.I *
+Indicates that any slot value is acceptable. In addition,
+for runtime dependencies, indicates that the package will not
+break if the matched package is uninstalled and replaced by
+a different matching package in a different slot.
+
+.I Examples:
+
+.nf
+dev\-libs/icu:*
+dev\-lang/perl:*
+dev-libs/glib:*
+.fi
+.TP
+.I =
+Indicates that any slot value is acceptable. In addition,
+for runtime dependencies, indicates that the package will
+break unless a matching package with slot and sub\-slot equal
+to the slot and sub\-slot of the best installed version at the
+time the package was installed is available.
+
+.I Examples:
+
+.nf
+dev\-libs/icu:=
+dev\-lang/perl:=
+dev-libs/glib:=
+.fi
+.TP
+.I slot=
+Indicates that only a specific slot value is acceptable, and
+otherwise behaves identically to the plain equals slot operator.
+
+.I Examples:
+
+.nf
+dev\-libs/icu:0=
+dev\-lang/perl:0=
+dev-libs/glib:2=
+.fi
+.PP
+To implement the equals slot operator, the package manager
+will need to store the slot/sub\-slot pair of the best installed
+version of the matching package. This syntax is only for package
+manager use and must not be used by ebuilds. The package manager
+may do this by inserting the appropriate slot/sub\-slot pair
+between the colon and equals sign when saving the package's
+dependencies. The sub\-slot part must not be omitted here
+(when the SLOT variable omits the sub\-slot part, the package
+is considered to have an implicit sub\-slot which is equal to
+the regular slot).
+
+.I Examples:
+
+.nf
+dev\-libs/icu:0/0=
+dev\-libs/icu:0/49=
+dev\-lang/perl:0/5.12=
+dev-libs/glib:2/2.30=
+.fi
+.RE
.TP
.B Atom USE
Beginning with \fBEAPI 2\fR, any atom can be constrained to match specific
.TE
.RE
.TP
-.B Atom USE defauts
+.B Atom USE defaults
Beginning with \fBEAPI 4\fR, \fBUSE\fR dependencies may specify default
assumptions about values for flags that may or may not be missing from
the \fBIUSE\fR of the matched package. Such defaults are specified by
.RS
.nf
media\-video/ffmpeg[threads(+)]
-media\-video/ffmpeg[threads(\-)]
+media\-video/ffmpeg[-threads(\-)]
.fi
.RE
.RE
.TP
\fBRDEPEND\fR
This should contain a list of all packages that are required for this
-program to run (aka runtime depend). If this is not set in \fBEAPI\fR
-3 or earlier, then it defaults to the value of \fBDEPEND\fR. In
-EAPI 4 or later, \fBRDEPEND\fR will never be implicitly set.
+program to run (aka runtime depend). If this is not set in \fBEAPI 3\fR
+or earlier, then it defaults to the value of \fBDEPEND\fR. In
+\fBEAPI 4\fR or later, \fBRDEPEND\fR will never be implicitly set.
.br
You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR.
.TP
Behavior Expression
If flag1 enabled then flag2 disabled flag1? ( !flag2 )
-If flag1 enabled then flag2 disabled flag1? ( flag2 )
+If flag1 enabled then flag2 enabled flag1? ( flag2 )
If flag1 disabled then flag2 enabled !flag1? ( flag2 )
If flag1 disabled then flag2 disabled !flag1? ( !flag2 )
Must enable any one or more (inclusive or) || ( flag1 flag2 flag3 )
Must enable exactly one but not more (exclusive or) ^^ ( flag1 flag2 flag3 )
+May enable at most one (EAPI 5 or later) ?? ( flag1 flag2 flag3 )
.TE
.TP
\fBRESTRICT\fR = \fI[strip,mirror,fetch,userpriv]\fR
For example, blackdown\-jdk and sun\-jdk provide \fIvirtual/jdk\fR. This
allows for packages to depend on \fIvirtual/jdk\fR rather than on blackdown
or sun specifically.
+.TP
+\fBDOCS\fR
+Beginning with \fBEAPI 4\fR, an array or space\-delimited list of documentation
+files for the default src_install function to install using dodoc. If
+undefined, a reasonable default list is used. See the documentation for
+src_install below.
.SH "QA CONTROL VARIABLES"
.TP
.B USAGE NOTES
files that contain writable and executable segments. These are rare.
The paths may contain fnmatch patterns.
.TP
+\fBQA_FLAGS_IGNORED\fR
+This should contain a list of file paths, relative to the image directory, of
+files that do not contain .GCC.command.line sections or contain .hash sections.
+The paths may contain regular expressions with escape\-quoted special characters.
+.br
+This variable is intended to be used on files of binary packages which ignore
+CFLAGS, CXXFLAGS, FFLAGS, FCFLAGS, and LDFLAGS variables.
+.TP
+.TP
\fBQA_DT_HASH\fR
This should contain a list of file paths, relative to the image directory, of
files that contain .hash sections. The paths may contain regular expressions
-with escape\-quoted special characters.
+with escape\-quoted special characters. This variable is deprecated. Use
+\fBQA_FLAGS_IGNORED\fR instead.
.br
This variable is intended to be used on files of binary packages which ignore
LDFLAGS variable.
shared libraries that lack SONAMEs. The paths may contain regular expressions
with escape\-quoted special characters.
.TP
+\fBQA_SONAME_NO_SYMLINK\fR
+This should contain a list of file paths, relative to the image directory, of
+shared libraries that have SONAMEs but should not have a corresponding SONAME
+symlink in the same directory. The paths may contain regular expressions
+with escape\-quoted special characters.
+.TP
\fBQA_DT_NEEDED\fR
This should contain a list of file paths, relative to the image directory, of
shared libraries that lack NEEDED entries. The paths may contain regular
available in phases that execute afterwards.
.TP
.B pkg_nofetch
-If you turn on \fIfetch\fR in \fBRESTRICT\fR, then this function will be
-run when the files in \fBSRC_URI\fR cannot be found. Useful for
-displaying information to the user on *how* to obtain said files. All
+This function will be executed when the files in \fBSRC_URI\fR
+cannot be fetched for any reason. If you turn on \fIfetch\fR in
+\fBRESTRICT\fR, this is useful for displaying information to the
+user on *how* to obtain said files. All
you have to do is output a message and let the function return. Do not
end the function with a call to \fBdie\fR.
.TP
Initial working directory of $S.
.TP
.B src_test
-Run all package specific test cases. The default is to run 'make check'
-followed 'make test'.
+Run all package specific test cases. The default is to run
+\'emake check\' followed \'emake test\'. Prior to \fBEAPI 5\fR,
+the default src_test implementation will automatically pass the
+\-j1 option as the last argument to emake, and beginning with
+\fBEAPI 5\fR it will allow the tests to run in parallel.
.br
Initial working directory of $S.
.TP
emake DESTDIR="${D}" install
fi
- if [[ \-z $DOCS ]] ; then
+ if ! declare -p DOCS &>/dev/null ; then
local d
for d in README* ChangeLog AUTHORS NEWS TODO CHANGES \\
THANKS BUGS FAQ CREDITS CHANGELOG ; do
.fi
.RE
.TP
+\fBusex\fR \fI<USE flag>\fR \fI[true output]\fR \fI[false output]\fR \fI[true suffix]\fR \fI[false suffix]\fR
+If USE flag is set, echo [true output][true suffix] (defaults to
+"yes"), otherwise echo [false output][false suffix] (defaults to
+"no"). The usex helper is available beginning with \fBEAPI 5\fR.
+.TP
\fBuse_with\fR \fI<USE item>\fR \fI[configure name]\fR \fI[configure opt]\fR
Useful for creating custom options to pass to a configure script. If \fIUSE
item\fR is in the \fBUSE\fR variable and a \fIconfigure opt\fR is specified,
argument is recognized. In \fBEAPI 3\fR and earlier, an empty
\fIconfigure opt\fR argument is treated as if it weren't provided.
.TP
-\fBhas\fR \fI<item>\fR \fI<item list>\fR
-If \fIitem\fR is in \fIitem list\fR, then \fIitem\fR is echoed and \fBhas\fR
+\fBhasv\fR \fI<item>\fR \fI<item list>\fR
+If \fIitem\fR is in \fIitem list\fR, then \fIitem\fR is echoed and \fBhasv\fR
returns 0. Otherwise, nothing is echoed and 1 is returned. As indicated with
-use, there is a non\-echoing version \fBhasq\fR. Please use \fBhasq\fR in all
+use, there is a non\-echoing version \fBhas\fR. Please use \fBhas\fR in all
places where output is to be disregarded. Never use the output for calculation.
.br
The \fIitem list\fR is delimited by the \fIIFS\fR variable. This variable
Beginning with \fBEAPI 3\fR, \fBeconf\fR uses the \fB${EPREFIX}\fR
variable which is disregarded for prior \fBEAPI\fR values.
Beginning with \fBEAPI 4\fR, \fBeconf\fR adds
-\fI\-\-disable\-dependency\-tracking\fR to the arguments.
+\fI\-\-disable\-dependency\-tracking\fR to the arguments if the
+string \fIdisable\-dependency\-tracking\fR occurs in the output
+of \fIconfigure \-\-help\fR.
.TP
\fBemake\fR \fI[make options]\fR
This is used as a replacement for make. Performs 'make ${MAKEOPTS}
.TP
\fBprepstrip\fR \fI[dir]\fR
.PD 1
-Similiar to the \fBprepall\fR functions, these are subtle in their differences.
+Similar to the \fBprepall\fR functions, these are subtle in their differences.
.RS
.PD 0
.TP
.BR 'dosed\ "s:/usr/local:/usr:g"\ /usr/bin/some\-script'
runs sed on ${ED}/usr/bin/some\-script
.TP
-\fBdodir\fR \fI<path>\fR
-Creates a directory inside of ${ED}.
+\fBdodir\fR \fI<path> [more paths]\fR
+Creates directories inside of ${ED}.
.br
.BR 'dodir\ /usr/lib/apache'
creates ${ED}/usr/lib/apache. Note that the do* functions will run
.br
The default root is /usr.
.TP
-\fBkeepdir\fR \fI<path>\fR
-Tells portage to leave a directory behind even if it is empty. Functions
+\fBkeepdir\fR \fI<path> [more paths]\fR
+Tells portage to leave directories behind even if they're empty. Functions
the same as \fBdodir\fR.
.TP
\fBdobin\fR \fI<binary> [list of more binaries]\fR
projects / portage.git / blobdiff