doc/ebuild.1.txt

   1 NAME
   2        ebuild  -  manual page for the ebuild program, a low level
   3        interface to the Portage system.
   4
   5 SYNOPSIS
   6        ebuild file command [command]...
   7
   8 DESCRIPTION
   9        The ebuild program is a direct interface  to  the  Portage
  10        system.  It  allows  for direct action upon an ebuild with
  11        specific subcommands or groups of commands to perform in a
  12        specific  ebuild's  context  and  functions.  Accepting an
  13        ebuild script and one or more commands as  arguments,  the
  14        ebuild  program  parses  the ebuild script and execute the
  15        specified commands.   Commands  exist  to  fetch  sources,
  16        unpack sources, compile sources, install object files into
  17        a temporary directory "image",  merge  the  image  to  the
  18        local  filesystem, create a bzipped tarball package out of
  19        the image, and more.
  20
  21 FILE
  22        This must be a valid ebuild script.  For further  informa�
  23        tion read ebuild(5).
  24
  25 COMMANDS
  26        help   Show  a condensed form of the man page along with a
  27               lot of package specific information.
  28
  29        setup  Run all package specific setup actions  and  exotic
  30               system checks.
  31
  32        clean  Cleans  the  temporary build directory that Portage
  33               has created for this particular ebuild  file.   The
  34               temporary  build  directory  normally  contains the
  35               extracted  source  files  as  well  as  a  possible
  36               "install  image" (all the files that will be merged
  37               to the local filesystem or stored  in  a  package).
  38               The  location  of the build directory is set by the
  39               BUILD_PREFIX variable.   For  information  on  what
  40               this variable is, run emerge [-v] info, or to over�
  41               ride this variable, see make.conf(5).
  42
  43               Note: Portage cleans up almost everything  after  a
  44               package  has  been  successfully merged unless FEA�
  45               TURES contains 'noclean'. Adding  noclean  to  FEA�
  46               TURES  will cause a lot of files to remain and will
  47               consume large amounts of space, very quickly. It is
  48               not  recommended  to  leave this on unless you have
  49               use for the sources post-merge. Optionally one may,
  50               manual clean rm -rf /var/tmp/portage will take care
  51               of these files.
  52
  53        fetch  Checks to see  if  all  the  sources  specified  in
  54               SRC_URI  are available in DISTDIR (see make.conf(5)
  55               for more information) and have a valid  md5  check�
  56               sum.   If  the sources aren't available, an attempt
  57               is made to download them from the locations  speci�
  58               fied  in  SRC_URI.   If multiple download locations
  59               are listed for a  particular  file,  Portage  pings
  60               each location to see which location is closer. (May
  61               not be true presently.)  The Gentoo  Linux  mirrors
  62               defined  by  GENTOO_MIRRORS  is  always  considered
  63               first. If for some reason the current or just-down�
  64               loaded  sources'  md5  digests  don't  match  those
  65               recorded in files/digest-[package]-[version-rev], a
  66               warning  is  printed and ebuild exits with an error
  67               code of 1.
  68
  69        digest Creates  a  digest  file   for   the   package   in
  70               /usr/portage/[category]/[package]/files/.      This
  71               digest file lists the md5sum's  of  all  the  files
  72               found in the SRC_URI.  If the fetched source of the
  73               package is corrupt/bogus in some  way,  the  md5sum
  74               will catch this.
  75
  76        unpack Extracts the sources to a subdirectory in the build
  77               directory    (BUILD_PREFIX)    by    running    the
  78               src_unpack()  function  in  the ebuild file.  If no
  79               src_unpack() function has been specified, a default
  80               src_unpack() function is used that extracts all the
  81               files specified in SRC_URI.  The sources  are  nor�
  82               mally  extracted to ${BUILD_PREFIX}/[package]-[ver�
  83               sion-rev]/work. This particular  directory  can  be
  84               referenced by using the ${WORKDIR} variable.
  85
  86               If  you're  creating an ebuild, you'll want to make
  87               sure that the S (source directory) variable defined
  88               at  at  the top of your ebuild script points to the
  89               directory that  contains  your  extracted  sources.
  90               This   directory   is  defined  by  default  to  be
  91               ${WORKDIR}/${P}, so it is not often required.   The
  92               src_unpack()  function is also responsible for mak�
  93               ing the appropriate patches to the sources so  that
  94               they're ready for compilation.
  95
  96        compile
  97               Compiles  the  extracted sources by running the the
  98               src_compile()  function  specified  in  the  ebuild
  99               file.  When src_compile() starts, the current work�
 100               ing directory will be set to ${S}.   When  src_com�
 101               pile()  completes, the sources should be fully com�
 102               piled.
 103
 104        preinst
 105               Run package specific actions that need to  be  done
 106               before  the  package  is  installed  into  the live
 107               filesystem.
 108
 109        install
 110               Installs  the  package  to  the  temporary  install
 111               directory  by  running  the src_install() function.
 112               When completed, the install directory (${BUILD_PRE�
 113               FIX}/[package]-[version-rev]/image)   will  contain
 114               all the files that should either be merged  to  the
 115               local  file system or included in a binary package.
 116
 117        postinst
 118               Run package specific actions that need to  be  done
 119               after  the  package  is  installed  into  the  live
 120               filesystem.  Usually  helpful  messages  are  shown
 121               here.
 122
 123        qmerge This function installs all the files in the install
 124               directory to the live filesystem. The process works
 125               as  follows:  first, the pkg_preinst() function (if
 126               specified) is run.  Then, the files are merged into
 127               the  live  filesystem, and the installed files' md5
 128               digests          are          recorded           in
 129               /var/db/pkg/${CATEOGRY}/${PN}-[version-rev]/CON�
 130               TENTS.  After all the files have been  merged,  the
 131               pkg_postinst() function (if specified) is executed.
 132
 133        merge  Normally, to merge an ebuild, you  need  to  fetch,
 134               unpack,  compile,  install  and  qmerge.  If you're
 135               simply interested in merging the  ebuild,  you  can
 136               use  this  command,  which  will  perform all these
 137               steps for you, stopping along the way if a particu�
 138               lar step doesn't complete successfully.
 139
 140        unmerge
 141               This function first executes the pkg_prerm function
 142               (if specified).  Then it removes all files from the
 143               live  filesystem that have a valid md5 checksum and
 144               mtime in the  package  contents  file.   Any  empty
 145               directories  are  recursively removed.  Finally, it
 146               runs pkg_postrm function  (if  specified).   It  is
 147               safe  to merge a new version of a package first and
 148               then unmerge the old one.  In  fact,  this  is  the
 149               recommended package upgrade method.
 150
 151        package
 152               This  command  is  a  lot  like  the merge command,
 153               except that after  fetching,  unpacking,  compiling
 154               and  installing,  a .tbz2 binary package tarball is
 155               created and  stored  in   ${PKGDIR}/All  (${PKGDIR}
 156               defaults  to  /usr/portage/packages).   A  symbolic
 157               link  is  created  in  ${PKGDIR}/${CATEGORY}   that
 158               points to the package in ${PKGDIR}/All.
 159
 160        rpm    Builds  a  RedHat RPM package from the files in the
 161               temporary install directory.  At  the  moment,  the
 162               ebuild's dependency information is not incorporated
 163               into the RPM.
 164
 165 REPORTING BUGS
 166        Please report bugs via http://bugs.gentoo.org/
 167
 168 SEE ALSO
 169        ebuild(5), make.conf(5)
 170
 171        The /usr/sbin/ebuild.sh script.
 172
 173        The helper apps in /usr/lib/portage/bin.
 174
 175 FILES
 176        /etc/make.conf
 177               Contains variables for the build-process and  over�
 178               writes those in make.globals.
 179
 180 AUTHORS
 181        Achim Gottinger <achim@gentoo.org>
 182        Daniel Robbins <drobbins@gentoo.org>
 183        Nicholas Jones <carpaski@gentoo.org>
 184        Mike Frysinger <vapier@gentoo.org>