Note:
There is a manpage which talks about the internal format, variables and function
s in an ebuild script: man 5 ebuild.
|
1. Variable Settings:
The first part of every ebuild file is made up of a number of
variable settings. The variables you can set are:
| P |
the name and version of the package; you must not set this, as it is determined by portage for you. |
| S |
the source directory for your package; normally ${WORKDIR}/${P} |
| T |
the temporary directory for your package. It is used as a virtual /tmp directory while processing the ebuild. |
| D |
the root directory that is installed to, treat it as the virtual / |
| SLOT |
Portage handles different versions of the same installed programs. If you would want, say GCC 2.95 and GCC 3.x installed at the same time, you would specify the slot in each ebuild. i.e GCC 2.95 would be slot 0, and GCC 3.x would be slot 1.
|
| LICENSE |
This variable specifies what license the program is covered under, i.e. GPL-2, BSD, etc... This field must be set to a valid license (which is any license found in ${PORTDIR}/license/). If the license does not already exist there, it must be added before the ebuild can be added to the portage tree. |
| KEYWORDS |
This variable now supports a couple of different functions. First of all, this variable specifies what architecture the ebuild is meant for. These keywords include: x86, ppc, alpha, sparc, sparc64 . Obviously,
you would set this to reflect the architecture of the target machine. Portage will not allow an x86 machine to build anything but x86, as specified by the KEYWORDS USE variable. Packages that are not the native architecture are automatically
masked by Portage. If the KEYWORDS flag has a preceeding ~, then that indicates that the particular ebuild
works, but is not considered stable with the given keyword. If the KEYWORDS flag has a preceeding -, then
the package does not work with the given keyword. If there is nothing leading KEYWORDS, then the package
is considered stable. You can allow installation of these different types of packages through
make.conf. |
| DESCRIPTION |
a short, one line description of your package |
| SRC_URI |
the URIs for every source file in your package, separated by whitespace; normally the first one is something like "ftp://ftp.company.com/pub/somepackage/${A}" |
| HOMEPAGE |
your package's homepage |
| IUSE |
This is set to what USE variables your package uses. If your package uses none, you must set it
to IUSE="" . |
| DEPEND |
build dependencies; see the section Package Dependencies
|
| RDEPEND |
runtime dependencies; see the section Package Dependencies
|
2. ebuild Functions
There are a number of different functions that you can define in ebuild files that control the building and installation process of your package.
| pkg_setup |
Use this function to perform any miscellaneous prerequisite tasks. This might include adding system accounts or checking for an existing configuration file. This function must return 0 in order for processing to proceed. |
| pkg_nofetch |
Inform the user about required actions if for some reason (such as licensing issues) the sources may not be downloaded by Portage automatically. |
| src_unpack |
Use this function to unpack your sources and run autoconf/automake/etc. if necessary. By default, it unpacks the packages in ${A}. The default starting directory is ${WORKDIR}. |
| src_compile |
Use this function to configure and build the package. Default starting directory is ${S}. |
| src_install |
Use this function install the package to an image in ${D}. If your package uses automake, you can do this simply with make DESTDIR=${D} install. Make sure your package installs all its files using ${D} as the root!
|
| pkg_preinst |
The commands in this function are run just prior to merging a package image into the filesystem. |
| pkg_postinst |
The commands in this function are run just following merging a package image into the filesystem. |
| pkg_prerm |
The commands in this function are run just prior to unmerging a package image from the filesystem. |
| pkg_postrm |
The commands in this function are run just following unmerging a package image from the filesystem. |
| pkg_config |
You use this function to setup an initial configuration for the package after it's installed. All paths in this function should be prefixed with ${ROOT}. This function is only executed if and when the user runs: ebuild /var/db/pkg/${CATEGORY}/${PF}/${PF}.ebuild config. |
You can also use the following functions in your ebuilds.
| use |
Check if one or more given use-flags are defined. If so, the function will echo the use-flags. To check the existence of a use-flag, you can use [ -z "`use foobar`"]. |
| has_version |
Returns 1 if the system has the requested version of a certain package. For instance has_version >=glibc-2.3.0. |
| best_version |
Returns category/package-version of the requested category/package. For instance best_version x11-libs/gtk+extra. |
| use_with |
This function checks if a use-flag has been defined and returns "--with-foobar" or "--without-foobar" accordingly. If you only use one argument, that argument is both use-flag and with(out)-string. Otherwise the first argument is the use-flag and the second argument the with(out)-string. For instance use_with truetype freetype. |
| use_enable |
The same as use_with, but returns "--enable-foobar" or "--disable-foobar" accordingly. |
| check_KV |
Checks if Portage knows kernel version. If not, display an error and die. If you need the kernel version in your script, use the ${KV} variable which is automatically defined by Portage. |
| keepdir |
Creates (if necessary) a .keep file in the given directory so that it isn't auto-cleaned. |
| econf |
Issues ./configure with the necessary path-changes (prefix, host, mandir, infodir, datadir, sysconfdir, localstatedir). You can optionally give extra arguments for ./configure. |
| einstall |
Issues make install so that Portage knows where the files are being placed. |
| die |
Causes the current process to be aborted. It will notify the user with the given argument as reason. |
| einfo |
Inform the user about something important. The argument given to einfo is the message that the user will see. |
Portage scripts and utilities
These are scripts used to test your ebuild step-by-step, install and remove packages, and maintain the package database.
ebuild is the main engine of the Portage system; it performs all major tasks such as unpacking, compiling, installing, merging, and unmerging packages. It is called using the command: ebuild path/to/package.ebuild command. The commands available are:
| Command |
Description |
Related ebuild Function |
| *setup
|
performs any miscellaneous commands required before the ebuild can proceed |
pkg_setup |
| depend |
displays the dependencies required to build the package |
n/a |
| merge |
unpacks, compiles, installs, and merges the package into your filesystem |
n/a |
| *qmerge
|
merges the package into your filesystem, assuming that the the unpack, compile, and install stages have already been executed |
n/a |
| *unpack
|
unpacks the source tarballs into the work directory |
src_unpack |
| *compile
|
compiles the package |
src_compile |
| rpm |
creates an RPM from the package |
n/a |
| package |
creates a Gentoo tbz2 package |
n/a |
| *prerm
|
executes the pre-removal stage of the package |
pkg_prerm |
| *postrm
|
executes the post-removal stage of the package |
pkg_postrm |
| *preinst
|
executes the pre-installation stage of the package |
pkg_preinst |
| *postinst
|
executes the post-installation stage of the package |
pkg_postinst |
| config |
sets up a default configuration once the package is merged |
pkg_config |
| *touch
|
updates the mtimes for each source archive in the package |
n/a |
| *clean
|
cleans the work directory for the package |
n/a |
| *fetch
|
fetches the package source tarballs |
n/a |
| *digest
|
creates a digest file for the package |
n/a |
| *install
|
installs the package into the image directory |
src_install |
| unmerge |
unmerges the package from your filesystem |
n/a |
Note: commands with an asterisk (*) are normally only used by the developer.
Private Scripts and Commands
These are scripts you can use in your ebuild files to perform common tasks.
For more detailed instructions, look at the scripts themselves in /usr/lib/portage/bin.
| into |
sets the target prefix (DESTTREE) for dobin, dolib, dolib.a, dolib.so, domo, dosbin
|
| dobin |
installs the specified binaries into DESTTREE/bin
|
| dodoc |
installs the specified files into the package's documentation directory (/usr/share/doc/${PF}/DOCDESTTREE) where DOCDESTREE is settable with docinto
|
| doexe |
installs the specified files with mode EXEOPTIONS into EXEDESTTREE. EXEOPTIONS defaults to -m0755 and is settable via the exeopts command. EXEDESTTREE is settable via the exeinto command. |
| dohard |
creates a hardlink, handles ${D} transparently |
| dohtml |
installs the specified files and directories into /usr/share/doc/${PF}/html
|
| doinfo |
installs the specified files into /usr/share/info, then compresses them with gzip |
| doins |
installs the specified files with mode INSOPTIONS into INSDESTTREE. INSOPTIONS defaults to -m0644 and is settable via the insopts command. INSDESTTREE is settable via the insinto command. |
| dolib |
installs the specified libraries with mode LIBOPTIONS into DESTTREE/lib. LIBOPTIONS defaults to -m0644 and is settable via the libopts command |
| dolib.a |
installs the specified libraries into DESTTREE/lib with mode 0644 |
| dolib.so |
installs the specified libraries into DESTTREE/lib with mode 0755 |
| doman |
installs the specified files into /usr/share/man/manX, according to the suffix X |
| domo |
used for manually installing .mo files, which are used for storing localized string data |
| donewins |
same as newins; its actually a symlink to it. this is deprecated and exists for compatibility with old ebuilds. use newins instead |
| dosbin |
installs a binary into DESTTREE/sbin, marking it as executable |
| dosed |
removes all occurences of ${D} (the installation prefix path) in the specified files |
| dosym |
creates a symlink, handles ${D} transparently |
| emake |
runs a parallell make. some projects cannot be made in parallell; use make |
| fowners |
applies the specified ownership (first argument) to the specified file (second argument) via the chown command, handles ${D} transparently |
| fperms |
applies the specified permissions (first argument) to the specified file (second argument) via the chmod command, handles ${D} transparently |
| newbin |
wrapper around dobin which installs the specified binary (first argument) in DESTTREE/bin, transparently renaming to the second argument |
| newdoc |
wrapper around dodoc which installs the specified file (first argument) in /usr/share/doc/${PF}/DOCDESTTREE, transparently renaming to the second argument |
| newexe |
wrapper around doexe which installs the specified file with mode EXEOPTIONS into EXEDESTTREE, transparently renaming to the second argument |
| newins |
wrapper around doins which installs the specified file with mode INSOPTIONS into INSDESTTREE, transparently renaming to the second argument |
| newlib.a |
wrapper around dolib.a which installs the specified library into DESTTREE/lib, transparently renaming to the second argument |
| newlib.so |
wrapper around dolib.so which installs the specified library into DESTTREE/lib, transparently renaming to the second argument |
| newman |
wrapper around doman which installs the specified file into /usr/share/man/manX, transparently renaming to the second argument |
| newsbin |
wrapper around dosbin which installs the specified file into DESTTREE/sbin, transparently renaming to the second argument |
| pmake |
deprecated; use emake instead |
| prepalldocs |
recursively gzips all doc files in /usr/share/doc, transparently fixing up any symlink paths |
| prepallinfo |
recursively gzips all info files in /usr/share/info
|
| prepallman |
recursively gzips all man pages in /opt/*/man/*, /usr/share/man/*, /usr/local/man/*, /usr/X11R6/share/man/* and transparently fixes up any symlink paths |
| prepall |
wrapper around prepallman, prepallinfo and prepallstrip. also ensures all libraries in /opt/*/lib, /lib, /usr/lib and /usr/X11R6/lib are executable. also moves any stray aclocal macros into /usr/share/aclocal
|
| try |
deprecated. Use the || die construct instead. |
|