From 831925e9c7fb2826679d677c6ca1762ed377d776 Mon Sep 17 00:00:00 2001 From: Zac Medico Date: Thu, 30 Dec 2010 23:12:16 -0800 Subject: ebuild(5): merge EAPI 4 docs from master --- man/ebuild.5 | 177 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 169 insertions(+), 8 deletions(-) (limited to 'man/ebuild.5') diff --git a/man/ebuild.5 b/man/ebuild.5 index 9fa3b89af..8e493f67a 100644 --- a/man/ebuild.5 +++ b/man/ebuild.5 @@ -19,7 +19,7 @@ Here's a simple example ebuild: # Distributed under the terms of the GNU General Public License v2 # $Header: $ -EAPI="3" +EAPI="4" inherit some_eclass another_eclass @@ -41,8 +41,8 @@ src_configure() { } src_install() { - emake install DESTDIR="${D}" || die "Install failed" - dodoc NEWS README* THANKS AUTHORS BUGS ChangeLog || die "dodoc failed" + emake DESTDIR="${D}" install + dodoc NEWS README* THANKS AUTHORS BUGS ChangeLog } .fi .SH "VARIABLES" @@ -137,10 +137,45 @@ not support \fB${ED}\fR, helpers use \fB${D}\fR where they would otherwise use \fB${ED}\fR. Do not modify this variable. .TP +.B MERGE_TYPE +Beginning with \fBEAPI 4\fR, the MERGE_TYPE variable can be used to +query the current merge type. This variable will contain one of the +following possible values: + +.RS +.TS +l l +__ +l l. +Value Meaning + +binary previously\-built which is scheduled for merge +buildonly source\-build which is not scheduled for merge +source source\-build which is scheduled for merge +.TE +.RE +.TP .B PORTAGE_LOG_FILE Contains the path of the build log. If \fBPORT_LOGDIR\fR variable is unset then \fBPORTAGE_LOG_FILE\fR=\fB"${T}/build.log"\fR. .TP +.B REPLACED_BY_VERSION +Beginning with \fBEAPI 4\fR, the REPLACED_BY_VERSION variable can be +used in pkg_prerm and pkg_postrm to query the package version that +is replacing the current package. If there is no replacement package, +the variable will be empty, otherwise it will contain a single version +number. +.TP +.B REPLACING_VERSIONS +Beginning with \fBEAPI 4\fR, the REPLACING_VERSIONS variable can be +used in pkg_pretend, pkg_setup, pkg_preinst and pkg_postinst to query +the package version(s) that the current package is replacing. If there +are no packages to replace, the variable will be empty, otherwise it +will contain a space\-separated list of version numbers corresponding +to the package version(s) being replaced. Typically, this variable will +not contain more than one version, but according to PMS it can contain +more. +.TP \fBROOT\fR = \fI"/"\fR Contains the path that portage should use as the root of the live filesystem. When packages wish to make changes to the live filesystem, they should do so in @@ -346,6 +381,21 @@ foo[bar=] bar? ( foo[bar] ) !bar? ( foo[\-bar] ) foo[!bar=] bar? ( foo[\-bar] ) !bar? ( foo[bar] ) .TE .RE +.TP +.B Atom USE defauts +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 +immediately following a flag with either \fB(+)\fR or \fB(\-)\fR. Use +\fB(+)\fR to behave as if a missing flag is present and enabled, or +\fB(\-)\fR to behave as if it is present and disabled: + +.RS +.nf +media\-video/ffmpeg[threads(+)] +media\-video/ffmpeg[threads(\-)] +.fi +.RE .RE .TP .B Dynamic DEPENDs @@ -429,6 +479,24 @@ but may be merged before if need be. .br You may use the same syntax to vary dependencies as seen above in \fBDEPEND\fR. .TP +\fBREQUIRED_USE\fR +Beginning with \fBEAPI 4\fR, the \fBREQUIRED_USE\fR variable can be +used to specify combinations of \fBUSE\fR flags that are allowed +or not allowed. Elements can be nested when necessary. +.TS +l l +__ +l l. +Behavior Expression + +If flag1 enabled then flag2 disabled flag1? ( !flag2 ) +If flag1 enabled then flag2 disabled 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 ) +.TE +.TP \fBRESTRICT\fR = \fI[strip,mirror,fetch,userpriv]\fR This should be a space delimited list of portage features to restrict. You may use conditional syntax to vary restrictions as seen above in DEPEND. @@ -563,6 +631,15 @@ before other variable declarations unless these variables are used in global scope of eclasses. .SH "PHASE FUNCTIONS" .TP +.B pkg_pretend +Beginning with \fBEAPI 4\fR, this function can be defined in order to +check that miscellaneous requirements are met. It is called as early +as possible, before any attempt is made to satisfy dependencies. If the +function detects a problem then it should call eerror and die. The +environment (variables, functions, temporary directories, etc..) that +is used to execute pkg_pretend is not saved and therefore is not +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 @@ -613,6 +690,29 @@ Should contain everything required to install the package in the temporary \fIinstall directory\fR. .br Initial working directory of $S. + +Beginning with \fBEAPI 4\fR, if src_install is undefined then the +following default implementation is used: + +.nf +src_install() { + if [[ \-f Makefile || \-f GNUmakefile || \-f makefile ]] ; then + emake DESTDIR="${D}" install + fi + + if [[ \-z $DOCS ]] ; then + local d + for d in README* ChangeLog AUTHORS NEWS TODO CHANGES \\ + THANKS BUGS FAQ CREDITS CHANGELOG ; do + [[ \-s "${d}" ]] && dodoc "${d}" + done + elif [[ $(declare \-p DOCS) == "declare \-a "* ]] ; then + dodoc "${DOCS[@]}" + else + dodoc ${DOCS} + fi +} +.fi .TP .B pkg_preinst pkg_postinst All modifications required on the live\-filesystem before and after the @@ -663,6 +763,14 @@ default_src_test \fBdie\fR \fI[reason]\fR Causes the current emerge process to be aborted. The final display will include \fIreason\fR. + +Beginning with \fBEAPI 4\fR, all helpers automatically call \fBdie\fR +whenever some sort of error occurs. Helper calls may be prefixed with +the \fBnonfatal\fR helper in order to prevent errors from being fatal. +.TP +\fBnonfatal\fR \fI\fR +Execute \fIhelper\fR and \fIdo not\fR call die if it fails. +The \fBnonfatal\fR helper is available beginning with \fBEAPI 4\fR. .TP \fBuse\fR \fI\fR If \fIUSE item\fR is in the \fBUSE\fR variable, the function will silently @@ -809,6 +917,7 @@ ${\fIECONF_SOURCE\fR:-.}/configure \\ \-\-mandir="${EPREFIX}"/usr/share/man \\ \-\-sysconfdir="${EPREFIX}"/etc \\ ${CTARGET:+\-\-target=${CTARGET}} \\ + \-\-disable\-dependency\-tracking \\ \fI${EXTRA_ECONF}\fR \\ \fIconfigure options\fR || die "econf failed" .fi @@ -818,6 +927,8 @@ extra arguments to \fBeconf\fR. Also note that \fBeconf\fR automatically calls \fBdie\fR if the configure script fails. 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. .TP \fBemake\fR \fI[make options]\fR This is used as a replacement for make. Performs 'make ${MAKEOPTS} @@ -915,7 +1026,49 @@ multiple directories. .RE .PD 1 .TP +\fBdocompress\fR \fI[\-x] [list of more paths]\fR +.RS +Beginning with \fBEAPI 4\fR, the \fBdocompress\fR helper is used to +manage lists of files to be included or excluded from optional compression. +If the first argument is \fB\-x\fR, add each of its subsequent arguments to +the exclusion list. Otherwise, add each argument to the inclusion list. +The inclusion list initially contains \fI/usr/share/doc\fR, +\fI/usr/share/info\fR, and \fI/usr/share/man\fR. The exclusion list +initially contains \fI/usr/share/doc/${PF}/html\fR. + +The optional compression shall be carried out after \fBsrc_install\fR +has completed, and before the execution of any subsequent phase +function. For each item in the inclusion list, pretend it has the +value of the \fBD\fR variable prepended, then: + +.RS +If it is a directory, act as if every file or directory immediately +under this directory were in the inclusion list. + +If the item is a file, it may be compressed unless it has been +excluded as described below. + +If the item does not exist, it is ignored. +.RE + +Whether an item is to be excluded is determined as follows: For each +item in the exclusion list, pretend it has the value of the \fBD\fR +variable prepended, then: + +.RS +If it is a directory, act as if every file or directory immediately +under this directory were in the exclusion list. + +If the item is a file, it shall not be compressed. + +If the item does not exist, it is ignored. +.RE +.RE +.TP \fBdosed\fR \fI"s:orig:change:g" \fR +Beginning with \fBEAPI 4\fR, the \fBdosed\fR helper no longer exists. Ebuilds +should call \fBsed(1)\fR directly (and assume that it is GNU sed). + Performs sed in place on \fIfilename\fR inside ${ED}. If no expression is given then \fI"s:${D}::g"\fR is used as the default expression. Note that this expression does \fBNOT\fR use the offset prefix. @@ -992,14 +1145,18 @@ in the file name will be installed in /usr/share/man/\fI\fR/man[0\-9n], with the locale portion of the file name removed, and the \fI\-i18n\fR option has no effect. For example, with \fBEAPI 2\fR, a manpage named foo.\fI\fR.1 will be installed as -/usr/share/man/\fI\fR/man1/foo.1. +/usr/share/man/\fI\fR/man1/foo.1. Beginning with \fBEAPI 4\fR, +the \fI\-i18n\fR option takes precedence over the locale suffix of the +file name. .PD 0 .TP \fBdohard\fR \fI \fR +Beginning with \fBEAPI 4\fR, the \fBdohard\fR helper no longer exists. Ebuilds +should call \fBln(1)\fR directly. .TP \fBdosym\fR \fI \fR .PD 1 -Performs the ln command as either a hard link or symlink. +Performs the ln command to create a symlink. .TP \fBdohtml\fR \fI [\-a filetypes] [\-r] [\-x list\-of\-dirs\-to\-ignore] [list\-of\-files\-and\-dirs]\fR Installs the files in the list of files (space\-separated list) into @@ -1034,10 +1191,12 @@ The default path is /. Can be used to define options for the install function used in \fBdoins\fR. The default is \fI\-m0644\fR. .TP -\fBdoins\fR \fI[-r] [list of more files]\fR +\fBdoins\fR \fI[\-r] [list of more files]\fR Installs files into the path controlled by \fBinsinto\fR. This function uses \fBinstall\fR(1). Creates all necessary dirs. -Setting -r sets recursive. +Setting \-r sets recursive. Beginning with \fBEAPI 4\fR, both +\fBdoins\fR and \fBnewins\fR preserve symlinks. In \fBEAPI 3\fR and +earlier, symlinks are dereferenced rather than preserved. .TP \fBexeinto\fR \fI[path]\fR Sets the destination path for the \fBdoexe\fR function. @@ -1057,9 +1216,11 @@ Sets the subdir used by \fBdodoc\fR and \fBdohtml\fR when installing into the document tree (based in /usr/share/doc/${PF}/). Default is no subdir, or just "". .TP -\fBdodoc\fR \fI [list of more documents]\fR +\fBdodoc\fR \fI[-r] [list of more documents]\fR Installs a document or a list of documents into /usr/share/doc/${PF}/\fI\fR. Documents are marked for compression. Creates all necessary dirs. +Beginning with \fBEAPI 4\fR, there is support for recursion, enabled by the +new \fI\-r\fR option. .PD 0 .TP -- cgit v1.2.3-1-g7c22