| .TH "EBUILD" "1" "Nov 2002" "Portage 2.0.51" "Portage" |
| .SH "NAME" |
| ebuild \- manual page for the ebuild program, a low level interface to |
| the Portage system. |
| .SH "SYNOPSIS" |
| .B ebuild |
| .I file command [command]\fR... |
| .SH "DESCRIPTION" |
| The ebuild program is a direct interface to the Portage system. It |
| allows for direct action upon an ebuild with specific subcommands or |
| groups of commands to perform in a specific ebuild's context and |
| functions. Accepting an ebuild script and one or more commands |
| as arguments, the ebuild program parses the ebuild script and |
| execute the specified commands. Commands exist to fetch sources, |
| unpack sources, compile sources, install object files into a temporary |
| directory "image", merge the image to the local filesystem, create a |
| bzipped tarball package out of the image, and more. |
| .SH "FILE" |
| This must be a valid ebuild script. For further information read |
| \fBebuild\fR(5). |
| .SH "COMMANDS" |
| .TP |
| .BR help |
| Show a condensed form of the man page along with a lot of package |
| specific information. |
| .TP |
| .BR setup |
| Run all package specific setup actions and exotic system checks. |
| .TP |
| .BR clean |
| Cleans the temporary build directory that Portage has created for |
| this particular ebuild file. The temporary build directory normally |
| contains the extracted source files as well as a possible |
| "install image" (all the files that will be merged to the local |
| filesystem or stored in a package). The location of the build |
| directory is set by the BUILD_PREFIX variable. For information |
| on what this variable is, run \fIemerge [\-v] info\fR, or to override |
| this variable, see \fBmake.conf\fR(5). |
| |
| Note: Portage cleans up almost everything after a package has been |
| successfully merged unless FEATURES contains 'noclean'. Adding noclean |
| to FEATURES will cause a lot of files to remain and will consume large |
| amounts of space, very quickly. It is not recommended to leave this on |
| unless you have use for the sources post\-merge. Optionally one may, |
| manual clean \fIrm \-rf /var/tmp/portage\fR will take care of all |
| of these files. |
| .TP |
| .BR fetch |
| Checks to see if all the sources specified in SRC_URI are available in |
| DISTDIR (see \fBmake.conf\fR(5) for more information) and have a valid |
| md5 checksum. If the sources aren't available, an attempt is made to |
| download them from the locations specified in SRC_URI. If multiple |
| download locations are listed for a particular file, Portage pings |
| each location to see which location is closer. (May not be true |
| presently.) The Gentoo Linux mirrors defined by GENTOO_MIRRORS is |
| always considered first. If for some reason the current or |
| just\-downloaded sources' md5 digests don't match those recorded |
| in files/digest\-[package]\-[version\-rev], a warning is printed |
| and ebuild exits with an error code of 1. |
| .TP |
| .BR digest |
| Creates a digest file for the package in |
| /usr/portage/[category]/[package]/files/. This digest file lists the |
| md5sum's of all the files found in the SRC_URI. If the fetched source |
| of the package is corrupt/bogus in some way, the md5sum will catch this. |
| .TP |
| .BR unpack |
| Extracts the sources to a subdirectory in the \fIbuild directory\fR |
| (BUILD_PREFIX) by running the \fIsrc_unpack()\fR function in the ebuild |
| file. If no src_unpack() function has been specified, a default |
| src_unpack() function is used that extracts all the files specified in |
| SRC_URI. The sources are normally extracted to |
| ${BUILD_PREFIX}/[package]\-[version\-rev]/work. This particular directory |
| can be referenced by using the ${WORKDIR} variable. |
| |
| If you're creating an ebuild, you'll want to make sure that the S |
| (source directory) variable defined at at the top of your ebuild script |
| points to the directory that contains your extracted sources. This |
| directory is defined by default to be ${WORKDIR}/${P}, so it is not |
| often required. The src_unpack() function is also responsible for |
| making the appropriate patches to the sources so that they're ready |
| for compilation. |
| .TP |
| .BR compile |
| Compiles the extracted sources by running the the \fIsrc_compile()\fR |
| function specified in the ebuild file. When src_compile() starts, the |
| current working directory will be set to ${S}. When src_compile() |
| completes, the sources should be fully compiled. |
| .TP |
| .BR test |
| Run package specific test cases to verify that everything was built |
| properly. |
| .TP |
| .BR preinst |
| Run package specific actions that need to be done before the package |
| is installed into the live filesystem. |
| .TP |
| .BR install |
| Installs the package to the temporary \fIinstall directory\fR by running |
| the \fIsrc_install()\fR function. When completed, the |
| \fIinstall directory\fR (${BUILD_PREFIX}/[package]\-[version\-rev]/image) |
| will contain all the files that should either be merged to the local |
| file system or included in a binary package. |
| .TP |
| .BR postinst |
| Run package specific actions that need to be done after the package |
| is installed into the live filesystem. Usually helpful messages are |
| shown here. |
| .TP |
| .BR qmerge |
| This function installs all the files in the \fIinstall directory\fR |
| to the live filesystem. The process works as follows: first, the |
| \fIpkg_preinst()\fR function (if specified) is run. Then, the files |
| are merged into the live filesystem, and the installed files' md5 |
| digests are recorded in |
| \fI/var/db/pkg/${CATEOGRY}/${PN}\-[version\-rev]/CONTENTS\fR. After |
| all the files have been merged, the \fIpkg_postinst()\fR function |
| (if specified) is executed. |
| .TP |
| .BR merge |
| Normally, to merge an ebuild, you need to \fIfetch\fR, \fIunpack\fR, |
| \fIcompile\fR, \fIinstall\fR and \fIqmerge\fR. If you're simply |
| interested in merging the ebuild, you can use this command, which |
| will perform all these steps for you, stopping along the way if a |
| particular step doesn't complete successfully. |
| .TP |
| .BR unmerge |
| This function first executes the \fIpkg_prerm\fR function (if specified). |
| Then it removes all files from the live filesystem that have a valid md5 |
| checksum and mtime in the package contents file. Any empty directories |
| are recursively removed. Finally, it runs \fIpkg_postrm\fR function (if |
| specified). It is safe to merge a new version of a package first and |
| then unmerge the old one. In fact, this is the recommended package |
| upgrade method. |
| .TP |
| .BR prerm |
| Run package specific actions that need to be executed before the package is |
| removed from the filesystem. See also \fIunmerge\fR. |
| .TP |
| .BR postrm |
| Run package specific actions that need to be executed after the package is |
| removed from the filesystem. See also \fIunmerge\fR. |
| .TP |
| .BR config |
| Run package specific actions needed to be executed after the emerge |
| process has completed. This usually entails configuration file |
| setup or other similar setups that the user may wish to run. |
| .TP |
| .BR package |
| This command is a lot like the \fImerge\fR command, except that after |
| fetching, unpacking, compiling and installing, a .tbz2 binary package |
| tarball is created and stored in ${PKGDIR}/All (${PKGDIR} defaults to |
| /usr/portage/packages). A symbolic link is created in |
| ${PKGDIR}/${CATEGORY} that points to the package in ${PKGDIR}/All. |
| .TP |
| .BR rpm |
| Builds a RedHat RPM package from the files in the temporary |
| \fIinstall directory\fR. At the moment, the ebuild's dependency |
| information is not incorporated into the RPM. |
| .SH "REPORTING BUGS" |
| Please report bugs via http://bugs.gentoo.org/ |
| .SH "SEE ALSO" |
| .BR emerge (1), |
| .BR ebuild (5), |
| .BR make.conf (5) |
| .TP |
| The \fI/usr/sbin/ebuild.sh\fR script. |
| .TP |
| The helper apps in \fI/usr/lib/portage/bin\fR. |
| .SH "FILES" |
| .TP |
| \fB/etc/make.conf\fR |
| Contains variables for the build\-process and overwrites those |
| in make.globals. |
| .SH "AUTHORS" |
| Achim Gottinger <achim@gentoo.org> |
| .br |
| Daniel Robbins <drobbins@gentoo.org> |
| .br |
| Nicholas Jones <carpaski@gentoo.org> |
| .br |
| Mike Frysinger <vapier@gentoo.org> |
| .SH "CVS HEADER" |
| $Id: /var/cvsroot/gentoo-src/portage/man/ebuild.1,v 1.16 2004/09/17 00:17:10 vapier Exp $" |