2 ebuild - the internal format, variables, and functions in
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,
15 Here's a simple example ebuild:
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"
26 DEPEND="virtual/glibc"
27 RDEPEND="virtual/glibc"
30 econf || die "could not configure"
31 emake || die "emake failed"
41 dosym /bin/sed /usr/bin/sed
42 dodoc COPYING NEWS README* THANKS TODO AUTHORS BUGS
48 - PORTAGE* and PORTDIR* variables may be found in
50 - When assigning values to variables in ebuilds,
51 you cannot have a space between the variable name
54 P This variable contains the package name without the
55 ebuild revision. This variable must NEVER be modi
57 xfree-4.2.1-r2.ebuild --> $P=='xfree-4.2.1'
59 PN Contains the name of the script without the version
61 xfree-4.2.1-r2.ebuild --> $PN=='xfree'
63 PV Contains the version number without the revision.
64 xfree-4.2.1-r2.ebuild --> $PV=='4.2.1'
66 PR Contains the revision number or 'r0' if no revision
68 xfree-4.2.1-r2.ebuild --> $PR=='r2'
70 PF Contains the full package name [PN]-[PV]-r[PR]
71 xfree-4.2.1-r2.ebuild --> $PF=='xfree-4.2.1-r2'
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.
77 WORKDIR = "${PORTAGE_TMPDIR}/portage/${PF}/work"
78 Contains the path to the package build root. Do
79 not modify this variable.
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.
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
94 T = "${PORTAGE_TMPDIR}/portage/${PF}/temp"
95 Contains the path to a temporary directory. You
96 may use this for whatever you like.
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
105 DESCRIPTION = "A happy little package"
106 Should contain a short description of the package.
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.
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
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.
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
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
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).
151 DEPEND This should contain a list of all packages that are
152 required for the program to compile.
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.
162 The base atom is just a full cate
163 gory/packagename. Hence, these are
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
180 sys-libs/zlib-1.1.4-r1
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
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
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
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',
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:
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 )
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.
242 RESTRICT = [nostrip,nomirror,fetch]
243 This should be a space delimited list
244 of portage features to restrict.
246 final binaries/libraries will
247 not be stripped of debug sym
250 files in SRC_URI will not be
251 downloaded from the GEN
253 fetch like nomirror but the files
254 will not be fetched via
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
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
276 This function can be used if the
277 package needs specific setup actions
278 or checks to be preformed before any
280 Initial working directory of
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
290 Initial working directory of
294 All necessary steps for configuration
295 and compilation should be done in
297 Initial working directory of $S.
300 Should contain everything required to
301 install the package in the temporary
303 Initial working directory of $S.
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
312 Initial working directory of $PWD.
315 Like the pkg_*inst functions but for
317 Initial working directory of $PWD.
319 config This function should contain optional
320 basic configuration steps.
321 Initial working directory of $PWD.
323 HELPER FUNCTIONS: GENERAL
325 Causes the current emerge process to
326 be aborted. The final display will
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
337 if [ `use gnome` ] ; then
340 elif [ `use gtk` ] ; then
341 guiconf="--enable-gui=gtk
343 elif [ `use X` ] ; then
347 # No gui version will be
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
366 myconf="`use_with jpeg lib
368 (myconf now has the value
372 myconf="`use_with jpeg lib
374 (myconf now has the value
378 myconf="`use_with pic`"
379 (myconf now has the value
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
393 See use_with for an example.
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.
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
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.
424 VERINS=`best_version net-
426 (VERINS now has the value
427 "net-ftp/glftpd-1.27" if
428 glftpd-1.27 is installed)
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
438 HELPER FUNCTIONS: COMPILE
439 econf [configure options]
440 This is used as a replacement for
445 --mandir=/usr/share/man \
446 --infodir=/usr/share/info \
447 --datadir=/usr/share \
449 --localstatedir=/var/lib \
452 *Note: There is no need to use '||
453 die' because econf checks for you
456 This is used as a replacement for
457 make. Performs default is
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_
468 *Note: Be sure to use '|| die' con
469 structs to ensure emake success
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
478 infodir=${D}/usr/share/info
480 datadir=${D}/usr/share \
481 sysconfdir=${D}/etc \
486 *Note: There is no need to use '||
487 die' because einstall checks for you
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.
504 Runs prepallman, prepallinfo,
505 prepallstrip, sets libraries
506 +x, and then checks aclocal
507 directories. Please note this
508 does *not* run prepalldocs.
510 Compresses all doc files in
513 Compresses all info files in
516 Compresses all man files in
519 Strips all executable files of
520 debugging symboles. This
528 Similiar to the prepall functions,
529 these are subtle in their differ
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
538 If a dir is not specified,
539 then preplib will assume the
540 dir usr. preplib will then run
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.
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
556 All the files found in
557 ${D}/dir will be stripped.
558 You may specify multiple
562 Performs commands with python and
565 dosed "s:orig:change:g" <filename>
566 Performs sed (including cp/mv file
568 'dosed "s:/usr/local:/usr:g"
569 /usr/bin/some-script' runs sed on
570 ${D}/usr/bin/some-script
573 Creates a directory inside of ${D}.
574 'dodir /usr/lib/apache' creates
578 Sets the root (DESTTREE) for other
579 functions like dobin, dosbin, doman,
581 The default root is /usr.
584 Tells portage to leave a directory
585 behind even if it is empty.
586 Functions the same as dodir.
588 dobin <binary> [list of more binaries]
589 Installs a binary or a list of bina
590 ries into DESTTREE/bin. Creates all
593 dosbin <binary> [list of more binaries]
594 Installs a binary or a list of bina
595 ries into DESTTREE/sbin. Creates all
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
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.
612 dohard <filename> <linkname>
613 dosym <filename> <linkname>
614 Performs the ln command as either a
615 hard link or symlink.
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
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.
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.
639 domo <locale-file> [list of more
641 Installs locale-files into DEST
642 DIR/usr/share/locale/[LANG] depending
643 on local-file's ending. Creates all
646 fowners <permissions> <file> [files]
647 fperms <permissions> <file> [files]
648 Performs chown (fowners) or chmod
649 (fperms), applying permissions to
653 Sets the root (INSDESTTREE) for the
655 The default root is /.
657 insopts [options for install(1)]
658 Can be used to define options for the
659 install function used in doins. The
662 doins <file> [list of more files]
663 Installs files into INSDESTTREE.
664 This function uses install(1).
667 Sets the root (EXEDESTTREE) for the
669 The default root is /.
671 exeopts [options for install(1)]
672 Can be used to define options for the
673 install function used in doexe. The
676 doexe <executable> [list of more executa
678 Installs a executable or a list of
679 executable into EXEDESTTREE. This
680 function uses install(1).
683 Sets the relative subdir (DOCDEST
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.
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
708 Please report bugs via http://bugs.gen
712 ebuild(1), make.conf(5)
714 The /usr/sbin/ebuild.sh script.
716 The helper apps in /usr/lib/portage/bin.
720 Contains variables for the build-pro
721 cess and overwrites those in
725 Contains the default variables for
726 the build-process, you should edit
727 /etc/make.conf instead.
730 Achim Gottinger <achim@gentoo.org>
731 Mark Guertin <gerk@gentoo.org>
732 Nicholas Jones <carpaski@gentoo.org>
733 Mike Frysinger <vapier@gentoo.org>