Update TODO
[bitbake.git] / 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>