Update TODO
[vuplus_bitbake] / doc / ebuild.5.txt
1 NAME
2        ebuild  - the internal format, variables, and functions in
3        an ebuild script
4
5 DESCRIPTION
6        The ebuild(1) program accepts a single ebuild script as an
7        argument.   This  script  contains  variables and commands
8        that specify how  to  download,  unpack,  patch,  compile,
9        install  and  merge a particular software package from its
10        original sources.  In addition to all of this, the  ebuild
11        script  can also contain pre/post install/remove commands,
12        as required.
13
14 EXAMPLES
15        Here's a simple example ebuild:
16
17        DESCRIPTION="Super-useful stream editor (sed)"
18        SRC_URI="ftp://alpha.gnu.org/pub/gnu/sed/${P}.tar.gz"
19        HOMEPAGE="http://www.gnu.org/software/sed/sed.html"
20
21        KEYWORDS="~x86"
22        SLOT="0"
23        LICENSE="GPL-2"
24        IUSE=""
25
26        DEPEND="virtual/glibc"
27        RDEPEND="virtual/glibc"
28
29        src_compile() {
30             econf || die "could not configure"
31             emake || die "emake failed"
32        }
33
34        src_install() {
35             into /usr
36             doinfo doc/sed.info
37             doman doc/sed.1
38             into /
39             dobin sed/sed
40             dodir /usr/bin
41             dosym /bin/sed /usr/bin/sed
42             dodoc  COPYING  NEWS README* THANKS TODO AUTHORS BUGS
43        ANNOUNCE
44        }
45
46 VARIABLES
47        MISC USAGE NOTES
48               - PORTAGE* and PORTDIR* variables may be  found  in
49               make.conf(5).
50               -  When  assigning  values to variables in ebuilds,
51               you cannot have a space between the  variable  name
52               and the equal sign.
53
54        P      This variable contains the package name without the
55               ebuild revision.  This variable must NEVER be modi­
56               fied.
57               xfree-4.2.1-r2.ebuild --> $P=='xfree-4.2.1'
58
59        PN     Contains the name of the script without the version
60               number.
61               xfree-4.2.1-r2.ebuild --> $PN=='xfree'
62
63        PV     Contains the version number without the revision.
64               xfree-4.2.1-r2.ebuild --> $PV=='4.2.1'
65
66        PR     Contains the revision number or 'r0' if no revision
67               number exists.
68               xfree-4.2.1-r2.ebuild --> $PR=='r2'
69
70        PF     Contains the full package name [PN]-[PV]-r[PR]
71               xfree-4.2.1-r2.ebuild --> $PF=='xfree-4.2.1-r2'
72
73        A      Contains all source files required for the package.
74               This variable must not be defined. It is autogener­
75               ated from the SRC_URI variables.
76
77        WORKDIR = "${PORTAGE_TMPDIR}/portage/${PF}/work"
78               Contains  the  path  to the package build root.  Do
79               not modify this variable.
80
81        FILESDIR = "${PORTDIR}/${CATEGORY}/${PF}/files"
82               Contains the path to the 'files' sub folder in  the
83               package  specific location in the portage tree.  Do
84               not modify this variable.
85
86        S = "${WORKDIR}/${P}"
87               Contains the path to the temporary build directory.
88               This  variable is used by the functions src_compile
89               and src_install.  Both are executed with S  as  the
90               current  directory.   This variable may be modified
91               to match the extraction directory of a tarball  for
92               the package.
93
94        T = "${PORTAGE_TMPDIR}/portage/${PF}/temp"
95               Contains  the  path  to a temporary directory.  You
96               may use this for whatever you like.
97
98        D = "${PORTAGE_TMPDIR}/portage/${PF}/image"
99               Contains the path to the temporary  install  direc­
100               tory.   Every write operation that does not involve
101               the helper tools and functions (found below) should
102               be  prefixed  with  ${D}.  Do not modify this vari­
103               able.
104
105        DESCRIPTION = "A happy little package"
106               Should contain a short description of the  package.
107
108        SRC_URI = "http://happy.com/little/${P}.tar.gz"
109               Contains  a  list  of URI's for the required source
110               files.  It can contain multiple URI's for a  single
111               source file.  The fastest location is chosen if the
112               file was not found at GENTOO_MIRROR.
113
114        HOMEPAGE = "http://happy.com/"
115               Should contain a list of URL's for the sources main
116               sites  and other further package dependent informa­
117               tion.
118
119        KEYWORDS = [-~][x86,ppc,sparc,mips,alpha,arm,hppa]
120               Should contain appropriate list of arches that  the
121               ebuild is know to work/not work.  By default if you
122               do not know if an ebuild runs  under  a  particular
123               arch  simply omit that KEYWORD.  If the ebuild will
124               not work on that arch include it as -ppc for  exam­
125               ple.   If  the ebuild is being submitted for inclu­
126               sion, it must  have  ~arch  set  for  architectures
127               where  it  has been PROVEN TO WORK.  (Packages KEY­
128               WORDed this way may be unmasked for testing by set­
129               ting  ACCEPT_KEYWORDS="~arch"  on the command line,
130               or  in  make.conf(5))  For  an  authoritative  list
131               please review /usr/portage/profiles/arch.list.
132
133        SLOT   This  sets  the  SLOT for packages that may need to
134               co-exist.   By  default  you  should  set  SLOT="0"
135               unless  you  know what you are doing and need to do
136               otherwise.  This value should NEVER be  left  unde­
137               fined.
138
139        LICENSE
140               This  should  be a space delimited list of licenses
141               that the package falls under.  This _must_  be  set
142               to a matching license in /usr/portage/licenses/. If
143               the license does not exist in portage yet you  must
144               add it first.
145
146        IUSE   This should be a list of any and all USE flags that
147               are leveraged within your build script.   The  only
148               USE  flags  that should not be listed here are arch
149               related flags (see KEYWORDS).
150
151        DEPEND This should contain a list of all packages that are
152               required for the program to compile.
153
154               DEPEND Atoms
155                      A depend atom is simply a dependency that is
156                      used by portage when  calculating  relation­
157                      ships between packages.  Please note that if
158                      the atom has not already been emerged,  then
159                      the latest version available is matched.
160
161                      Atom Bases
162                              The  base  atom is just a full cate­
163                              gory/packagename.  Hence, these  are
164                              base atoms:
165
166                              sys-apps/sed
167                              sys-libs/zlib
168                              net-misc/dhcp
169
170                      Atom Versions
171                              It  is  nice to be more specific and
172                              say that only  certain  versions  of
173                              atoms  are  acceptable.   Note  that
174                              versions must  be  combined  with  a
175                              prefix  (see  below).  Hence you may
176                              add a version number as a postfix to
177                              the base:
178
179                              sys-apps/sed-4.0.5
180                              sys-libs/zlib-1.1.4-r1
181                              net-misc/dhcp-3.0_p2
182
183                      Atom Prefix Operators [> >= = <= =]
184                              Sometimes  you  want  to  be able to
185                              depend on  general  versions  rather
186                              than  specifying  exact versions all
187                              the time.  Hence we provide standard
188                              boolean operators:
189
190                              >media-libs/libgd-1.6
191                              >=media-libs/libgd-1.6
192                              =media-libs/libgd-1.6
193                              <=media-libs/libgd-1.6
194                              <media-libs/libgd-1.6
195
196                      Extended Atom Prefixes [!] and Postfixes [*]
197                              Now  to get even fancier, we provide
198                              the ability to define blocking pack­
199                              ages  and  version  range  matching.
200                              Also note that these  extended  pre­
201                              fixes/postfixes  may  be combined in
202                              any  way  with  the   atom   classes
203                              defined above.  Here are some common
204                              examples you may find in the portage
205                              tree:
206
207                              !app-text/dos2unix
208                              =dev-libs/glib-2*
209                              !net-fs/samba-2*
210
211                              !  means  block  packages from being
212                              installed at the same time.  * means
213                              match  any version of the package so
214                              long  as  the  specified   base   is
215                              matched.  So with a version of '2*',
216                              we can match '2.1', '2.2',  '2.2.1',
217                              etc...  and not match version '1.0',
218                              '3.0', '4.1', etc...
219
220               USE Variation
221                      Sometimes programs may depend  on  different
222                      things  depending  on  the USE variable.  To
223                      vary the packages the  program  depends  on,
224                      just use this syntax:
225
226                      DEPEND="media-libs/libsdl
227                           jpeg? ( >=media-libs/jpeg-6b )
228                           tiff? ( >=media-libs/tiff-3.5.5 )
229                           png? ( >=media-libs/libpng-1.2.1 )
230                           X? ( virtual/x11 )"
231
232
233        RDEPEND
234               This  should  contain  a  list of all
235               packages that are required  for  this
236               program  to run (aka runtime depend).
237               If this is not set, then it  defaults
238               to the value of DEPEND.
239               You  may  use the same syntax to vary
240               dependencies as seen above in DEPEND.
241
242        RESTRICT = [nostrip,nomirror,fetch]
243               This should be a space delimited list
244               of portage features to restrict.
245               nostrip
246                      final binaries/libraries  will
247                      not  be stripped of debug sym­
248                      bols.
249               nomirror
250                      files in SRC_URI will  not  be
251                      downloaded   from   the   GEN­
252                      TOO_MIRRORS.
253               fetch  like nomirror  but  the  files
254                      will   not   be   fetched  via
255                      SRC_URI either.
256
257        PROVIDE = "virtual/TARGET"
258               This variable  should  only  be  used
259               when  a  package  provides  a virtual
260               target.  For  example,  blackdown-jdk
261               and   sun-jdk   provide  virtual/jdk.
262               This allows for packages to depend on
263               virtual/jdk  rather than on blackdown
264               or sun specifically.
265
266 FUNCTIONS
267        pkg_nofetch
268               If you turn  on  fetch  in  RESTRICT,
269               then  this  function will be run when
270               the files in SRC_URI cannot be found.
271               Useful  for displaying information to
272               the user  on  *how*  to  obtain  said
273               files.
274
275        pkg_setup
276               This  function  can  be  used  if the
277               package needs specific setup  actions
278               or checks to be preformed before any­
279               thing else.
280               Initial    working    directory    of
281               ${PORTAGE_TMPDIR}.
282
283        src_unpack
284               This  function  is used to unpack all
285               the sources in A to WORKDIR.  If  not
286               defined in the ebuild script it calls
287               unpack ${A}. Any  patches  and  other
288               pre  configure/compile  modifications
289               should be done here.
290               Initial    working    directory    of
291               $WORKDIR.
292
293        src_compile
294               All necessary steps for configuration
295               and compilation  should  be  done  in
296               here.
297               Initial working directory of $S.
298
299        src_install
300               Should contain everything required to
301               install the package in the  temporary
302               install directory.
303               Initial working directory of $S.
304
305        pkg_preinst pkg_postinst
306               All  modifications  required  on  the
307               live-filesystem before and after  the
308               package  is  merged  should be placed
309               here. Also commentary  for  the  user
310               should  be  listed here as it will be
311               displayed last.
312               Initial working directory of $PWD.
313
314        pkg_prerm pkg_postrm
315               Like the pkg_*inst functions but  for
316               unmerge.
317               Initial working directory of $PWD.
318
319        config This function should contain optional
320               basic configuration steps.
321               Initial working directory of $PWD.
322
323 HELPER FUNCTIONS: GENERAL
324        die [reason]
325               Causes the current emerge process  to
326               be  aborted.  The  final display will
327               include reason.
328
329        use <USE item>
330               If USE item is in the  USE  variable,
331               USE item will be echoed and the func­
332               tion will return 0.  If USE  item  is
333               not in the USE variable, the function
334               will return 1.
335
336               Example:
337                      if [ `use gnome` ] ; then
338                           guiconf="--enable-
339                      gui=gnome --with-x"
340                      elif [ `use gtk` ] ; then
341                           guiconf="--enable-gui=gtk
342                      --with-x"
343                      elif [ `use X` ] ; then
344                           guiconf="--enable-
345                      gui=athena --with-x"
346                      else
347                           #  No gui version will be
348                      built
349                           guiconf=""
350                      fi
351
352        use_with <USE item> [configure option]
353               Useful for creating custom options to
354               pass  to  a  configure script. If USE
355               item is in the USE variable, then the
356               string --with-[configure option] will
357               be echoed.  If USE item is not in the
358               USE variable, then the string --with­
359               out-[configure   option]   will    be
360               echoed.   If  configure option is not
361               specified, than USE item will be used
362               in its place.
363
364               Example:
365                      USE="jpeg"
366                      myconf="`use_with   jpeg  lib­
367                      jpeg`"
368                      (myconf  now  has  the   value
369                      "--with-libjpeg")
370
371                      USE=""
372                      myconf="`use_with   jpeg  lib­
373                      jpeg`"
374                      (myconf  now  has  the   value
375                      "--without-libjpeg")
376
377                      USE="pic"
378                      myconf="`use_with pic`"
379                      (myconf   now  has  the  value
380                      "--with-pic")
381
382        use_enable <USE item> [configure option]
383               Useful for creating custom options to
384               pass  to  a  configure script. If USE
385               item is in the USE variable, then the
386               string   --enable-[configure  option]
387               will be echoed.  If USE item  is  not
388               in  the USE variable, then the string
389               --disable-[configure option] will  be
390               echoed.  If  configure  option is not
391               specified, than USE item will be used
392               in its place.
393               See use_with for an example.
394
395        has <item> <item list>
396               If item is in item list, then item is
397               echoed and has returns 0.  Otherwise,
398               nothing  is echoed and 1 is returned.
399               The item list is delimited by the IFS
400               variable.    This   variable   has  a
401               default value of ' ', or a space.  It
402               is a bash(1) setting.
403
404        has_version <category/package-version>
405               Check to see if category/package-ver­
406               sion is installed on the system.  The
407               parameter accepts all values that are
408               acceptable in  the  DEPEND  variable.
409               The   function  returns  0  if  cate­
410               gory/package-version is installed,  1
411               otherwise.
412
413        best_version <package name>
414               This  function  will  look up package
415               name in  the  database  of  currently
416               installed programs and echo the "best
417               version" of the package that is  cur­
418               rently   installed.    The   function
419               returns 0 if there is a package  that
420               matches package name.  Otherwise, the
421               function will return 1.
422
423               Example:
424                      VERINS=`best_version      net-
425                      ftp/glftpd`
426                      (VERINS   now  has  the  value
427                      "net-ftp/glftpd-1.27"       if
428                      glftpd-1.27 is installed)
429
430 HELPER FUNCTIONS: UNPACK
431        unpack <source> [list of more sources]
432               This   function  uncompresses  and/or
433               untars a list  of  sources  into  the
434               current  directory. The function will
435               append source to  the  DISTDIR  vari­
436               able.
437
438 HELPER FUNCTIONS: COMPILE
439        econf [configure options]
440               This  is  used  as  a replacement for
441               configure.  Performs:
442               configure \
443                    --prefix=/usr \
444                    --host=${CHOST} \
445                    --mandir=/usr/share/man \
446                    --infodir=/usr/share/info \
447                    --datadir=/usr/share \
448                    --sysconfdir=/etc \
449                    --localstatedir=/var/lib \
450                    configure options
451
452               *Note: There is no need  to  use  '||
453               die' because econf checks for you
454
455        emake [make options]
456               This  is  used  as  a replacement for
457               make.     Performs     default     is
458               MAKEOPTS="-j2".
459
460               ***warning***
461               if  you  are going to use emake, make
462               sure your build is  happy  with  par­
463               alell makes (make -j2).  It should be
464               tested thoroughly as  parallel  makes
465               are notorious for failing _sometimes_
466               but not always.
467
468               *Note: Be sure to use '||  die'  con­
469               structs to ensure emake success
470
471 HELPER FUNCTIONS: INSTALL
472        einstall [make options]
473               This  is  used  as  a replacement for
474               make install.  Performs:
475               make prefix=${D}/usr \
476                           mandir=${D}/usr/share/man
477               \
478                           infodir=${D}/usr/share/info
479               \
480                           datadir=${D}/usr/share \
481                           sysconfdir=${D}/etc \
482                           localstate­
483               dir=${D}/var/lib \
484                           make options install
485
486               *Note:  There  is  no need to use '||
487               die' because einstall checks for you
488
489        prepall
490        prepalldocs
491        prepallinfo
492        prepallman
493        prepallstrip
494               Useful for when  a  package  installs
495               into  ${D}  via  scripts  (i.e. make­
496               files).  If you want to be sure  that
497               libraries   are  executable,  aclocal
498               files are installed  into  the  right
499               place,  doc/info/man  files  are  all
500               compressed, and that executables  are
501               all  stripped  of  debugging symbols,
502               then use these suite of functions.
503               prepall:
504                      Runs prepallman,  prepallinfo,
505                      prepallstrip,  sets  libraries
506                      +x, and  then  checks  aclocal
507                      directories.  Please note this
508                      does *not* run prepalldocs.
509               prepalldocs:
510                      Compresses all  doc  files  in
511                      ${D}/usr/share/doc.
512               prepallinfo:
513                      Compresses  all  info files in
514                      ${D}/usr/share/info.
515               prepallman:
516                      Compresses all  man  files  in
517                      ${D}/usr/share/man.
518               prepallstrip:
519                      Strips all executable files of
520                      debugging   symboles.     This
521                      includes libraries.
522
523        prepinfo [dir]
524        preplib [dir]
525        preplib.so [dir]
526        prepman [dir]
527        prepstrip [dir]
528               Similiar  to  the  prepall functions,
529               these are  subtle  in  their  differ­
530               ences.
531               prepinfo:
532                      If  a  dir  is  not specified,
533                      then prepinfo will assume  the
534                      dir  usr.  prepinfo  will then
535                      compress  all  the  files   in
536                      ${D}/dir/info.
537               preplib:
538                      If  a  dir  is  not specified,
539                      then preplib will  assume  the
540                      dir usr. preplib will then run
541                      'ldconfig    -n     -N'     on
542                      ${D}/dir/lib.
543               preplib.so:
544                      All  the  files  with '.so' in
545                      their name and  are  found  in
546                      ${D}/dir  will  be stripped of
547                      their debug symbols.  You  may
548                      specify  multiple directories.
549               prepman:
550                      If a  dir  is  not  specified,
551                      then  prepman  will assume the
552                      dir  usr.  prepman  will  then
553                      compress   all  the  files  in
554                      ${D}/dir/man/*/.
555               prepstrip:
556                      All   the   files   found   in
557                      ${D}/dir   will  be  stripped.
558                      You   may   specify   multiple
559                      directories.
560
561        dopython <commands>
562               Performs  commands  with  python  and
563               returns the result.
564
565        dosed "s:orig:change:g" <filename>
566               Performs sed (including  cp/mv  file­
567               name) on filename.
568               'dosed          "s:/usr/local:/usr:g"
569               /usr/bin/some-script'  runs  sed   on
570               ${D}/usr/bin/some-script
571
572        dodir <path>
573               Creates a directory inside of ${D}.
574               'dodir /usr/lib/apache'       creates
575               ${D}/usr/lib/apache
576
577        into <path>
578               Sets the root  (DESTTREE)  for  other
579               functions  like dobin, dosbin, doman,
580               doinfo, dolib.
581               The default root is /usr.
582
583        keepdir <path>
584               Tells portage to  leave  a  directory
585               behind   even   if   it   is   empty.
586               Functions the same as dodir.
587
588        dobin <binary> [list of more binaries]
589               Installs a binary or a list of  bina­
590               ries  into DESTTREE/bin.  Creates all
591               necessary dirs.
592
593        dosbin <binary> [list of more binaries]
594               Installs a binary or a list of  bina­
595               ries into DESTTREE/sbin.  Creates all
596               necessary dirs.
597
598        dolib <library> [list of more libraries]
599        dolib.a <library> [list of more libraries]
600        dolib.so <library> [list of more libraries]
601               Installs  a  library  or  a  list  of
602               libraries into DESTTREE/lib.  Creates
603               all necessary dirs.
604
605        doman <man-page> [list of more man-pages]
606               Installs  manual-pages   into   DEST­
607               DIR/man/man[1-8n]  depending  on  the
608               manual file  ending.  The  files  are
609               gzipped if they are not already. Cre­
610               ates all necessary dirs.
611
612        dohard <filename> <linkname>
613        dosym <filename> <linkname>
614               Performs the ln command as  either  a
615               hard link or symlink.
616
617        dohtml      [-a    filetypes]    [-r]    [-x
618        list-of-dirs-to-ignore]
619        [list-of-files-and-dirs]
620               Installs  the  files  in  the list of
621               files  (space-separated  list)   into
622               /usr/share/doc/${PF}/html    provided
623               the file ends in .html, .png, .js, -A
624               appends  to the default list, setting
625               -x sets which dirs  to  exclude  (CVS
626               excluded  by default), -r sets recur­
627               sive.
628
629        doinfo <info-file> [list of more info-files]
630               Installs   info-pages   into    DEST­
631               DIR/info.   Files  are  automatically
632               gzipped.  Creates all necessary dirs.
633
634        dojar <jar file> [list of more jar files]
635               Installs      jar      files     into
636               /usr/share/${PN}/lib and adds them to
637               /usr/share/${PN}/classpath.env.
638
639        domo    <locale-file>    [list    of    more
640        locale-files]
641               Installs   locale-files   into  DEST­
642               DIR/usr/share/locale/[LANG] depending
643               on  local-file's ending.  Creates all
644               necessary dirs.
645
646        fowners <permissions> <file> [files]
647        fperms <permissions> <file> [files]
648               Performs  chown  (fowners)  or  chmod
649               (fperms),   applying  permissions  to
650               files.
651
652        insinto [path]
653               Sets the root (INSDESTTREE)  for  the
654               doins function.
655               The default root is /.
656
657        insopts [options for install(1)]
658               Can be used to define options for the
659               install function used in doins.   The
660               default is -m0644.
661
662        doins <file> [list of more files]
663               Installs   files   into  INSDESTTREE.
664               This function uses install(1).
665
666        exeinto [path]
667               Sets the root (EXEDESTTREE)  for  the
668               doexe function.
669               The default root is /.
670
671        exeopts [options for install(1)]
672               Can be used to define options for the
673               install function used in doexe.   The
674               default is -m0755.
675
676        doexe  <executable>  [list  of more executa­
677        bles]
678               Installs  a  executable  or a list of
679               executable  into  EXEDESTTREE.   This
680               function uses install(1).
681
682        docinto [path]
683               Sets  the  relative  subdir (DOCDEST­
684               TREE) used by dodoc.
685
686        dodoc <document> [list of more documents]
687               Installs a document or a list of doc­
688               ument   into  /usr/doc/${PV}/DOCDEST­
689               TREE.    Files   are    automatically
690               gzipped.  Creates all necessary dirs.
691
692        newbin <old file> <new filename>
693        newsbin <old file> <new filename>
694        newlib <old file> <new filename>
695        newlib.so <old file> <new filename>
696        newlib.a <old file> <new filename>
697        newman <old file> <new filename>
698        newinfo <old file> <new filename>
699        newins <old file> <new filename>
700        newexe <old file> <new filename>
701        newdoc <old file> <new filename>
702               All these functions act like the  do*
703               functions,  but  they  only work with
704               one file and the file is installed as
705               [new filename].
706
707 REPORTING BUGS
708        Please   report  bugs  via  http://bugs.gen­
709        too.org/
710
711 SEE ALSO
712        ebuild(1), make.conf(5)
713
714        The /usr/sbin/ebuild.sh script.
715
716        The helper apps in /usr/lib/portage/bin.
717
718 FILES
719        /etc/make.conf
720               Contains variables for the build-pro­
721               cess    and   overwrites   those   in
722               make.defaults.
723
724        /etc/make.globals
725               Contains the  default  variables  for
726               the  build-process,  you  should edit
727               /etc/make.conf instead.
728
729 AUTHORS
730        Achim Gottinger <achim@gentoo.org>
731        Mark Guertin <gerk@gentoo.org>
732        Nicholas Jones <carpaski@gentoo.org>
733        Mike Frysinger <vapier@gentoo.org>