Migration (without history) of the current stable line to subversion.

svn path=/main/branches/2.0/; revision=1941

1 files changed, 184 insertions, 0 deletions

diff --git a/man/ebuild.1 b/man/ebuild.1
new file mode 100644
index 000000000..af5f493fd
--- /dev/null
+++ b/man/ebuild.1
@@ -0,0 +1,184 @@
+.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"
+$Header: /var/cvsroot/gentoo-src/portage/man/ebuild.1,v 1.16 2004/09/17 00:17:10 vapier Exp $"