Quickstart Ebuild Guide
This page provides a very brief introduction to ebuild writing. It does not attempt to cover
many of the details or problems that will be encountered by developers — rather, it gives some trivial examples
which may be of use when trying to grasp the basic idea of how ebuilds work.
For proper coverage of all the ins and outs, see . The chapter will also be of use.
Note that the examples used here, whilst based upon real tree ebuilds, have had several parts chopped out, changed
and simplified.
First Ebuild
We'll start with an ebuild for the Exuberant Ctags utility, a source code indexing
tool. Here's a simplified dev-util/ctags/ctags-5.5.4.ebuild (you can see real ebuilds in the
main tree).
Basic Format
As you can see, ebuilds are just bash scripts that are executed within a special environment.
At the top of the ebuild is a header block. This is present in all ebuilds.
Ebuilds are indented using tabs, with each tab representing four places. See .
Information Variables
Next, there are a series of variables. These tell Portage various things about the ebuild and package in
question.
The DESCRIPTION variable is set to a short description of the package
and its purpose.
The HOMEPAGE is a link to the package's homepage (remember to include the
http:// part).
The LICENSE is GPL-2 (the GNU General Public License version 2).
The SRC_URI tells Portage the address to use for downloading the source tarball. Here,
mirror://sourceforge/ is a special notation meaning “any of the Sourceforge mirrors”.
${P} is a read-only variable set by Portage which is the package's name and version — in this
case, it would be ctags-5.5.4.
The SLOT variable tells Portage which slot this package installs to. If you've not seen slots
before, either just use "0" or read .
The KEYWORDS variable is set to archs upon which this ebuild has been tested. We use
~ keywords for newly written ebuilds — packages are not committed straight to stable, even
if they seem to work. See for details.
Build Functions
Next, a function named src_compile. Portage will call this function when it wants to
compile the package. The econf function is a wrapper for calling
./configure, and emake is a wrapper for make>. In the
case of emake, the common || die "something went wrong" idiom is used — this is to
ensure that if for some reason an error occurs, Portage will stop rather than trying to continue with the
install. Note that econf does not need the || die idiom, as it dies by
itself if something failed.
The src_install function is called by Portage when it wants to install
the package. A slight subtlety here — rather than installing straight to the live filesystem, we must install to
a special location which is given by the ${D} variable (Portage sets this — see and ). Again, we
check for errors using the || die construct.
The canonical install method is emake DESTDIR="${D}" install. This will work with
any properly written standard Makefile. If this gives sandbox errors, try
einstall instead. If this still fails, see for how to do manual installs.
The dodoc and dohtml are helper functions for installing files into the
relevant part of /usr/share/doc
Ebuilds can define other functions (see ). In all cases, Portage
provides a reasonable default implementation which quite often does the 'right thing'. There was no need to
define a src_unpack function here, for example — this function is used to do any unpacking
of tarballs or patching of source files, but the default implementation does everything we need in this case.
Ebuild with Dependencies
In the ctags example, we didn't tell Portage about any dependencies. As it happens, that's ok, because ctags only
needs a basic toolchain to compile and run (see for why we don't need to depend upon those
explicitly). However, life is rarely that simple.
Here's app-misc/detox/detox-1.1.1.ebuild:
Again, you can see the ebuild header and the various informational variables. In SRC_URI,
${PN} is used to get the package's name without the version suffix (there
are more of these variables — see ).
Again, we define src_compile and src_install functions.
The DEPEND and RDEPEND variables are how Portage determines which packages
are needed to build and run the package. The DEPEND variable lists compile-time dependencies,
and the RDEPEND lists runtime dependencies. See for some more complex examples.
Ebuild with Patches
Often we need to apply patches. This is done in the src_unpack function
using the epatch helper function. To use epatch one must
first tell Portage that the eutils eclass (an eclass is like a library)
is required — this is done via inherit eutils at the top of the
ebuild. Here's app-misc/detox/detox-1.1.0.ebuild:
Note the ${FILESDIR}/${P}-destdir.patch — this refers to
detox-1.1.0-destdir.patch, which lives in the files/
subdirectory in the Portage tree. Larger patch files must go on the mirrors rather than in
files/ — see .
Ebuild with USE Flags
Now for some USE flags. Here's
dev-libs/libiconv/libiconv-1.9.2.ebuild, a replacement iconv for
libc implementations which don't have their own.
Note the IUSE variable. This lists all (non-special) use flags that are
used by the ebuild. This is used for the emerge -pv output, amongst other
things.
The package's ./configure script takes the usual
--enable-nls or --disable-nls argument. We use
the use_enable utility function to generate this automatically, depending
on the user's USE flags (see ).
Another more complicated example, this time based upon
mail-client/sylpheed/sylpheed-1.0.4.ebuild:
=sys-devel/gettext-0.12.1 )
crypt? ( >=app-crypt/gpgme-0.4.5 )
imlib? ( media-libs/imlib2 )
ldap? ( >=net-nds/openldap-2.0.11 )
pda? ( app-pda/jpilot )
ssl? ( dev-libs/openssl )
xface? ( >=media-libs/compface-1.4 )
app-misc/mime-types
x11-misc/shared-mime-info"
DEPEND="${RDEPEND}
dev-util/pkgconfig
nls? ( >=sys-devel/gettext-0.12.1 )"
src_unpack() {
cd "${S}"
epatch "${FILESDIR}"/${PN}-namespace.diff \
"${FILESDIR}"/${PN}-procmime.diff
}
src_compile() {
econf \
$(use_enable nls) \
$(use_enable ssl) \
$(use_enable crypt gpgme) \
$(use_enable pda jpilot) \
$(use_enable ldap) \
$(use_enable ipv6) \
$(use_enable imlib) \
$(use_enable xface compface)
emake || die
}
src_install() {
emake DESTDIR="${D}" install || die
doicon sylpheed.png
domenu sylpheed.desktop
dodoc [A-Z][A-Z]* ChangeLog* || die
}
]]>
Note the optional dependencies. Some of the use_enable lines use the
two-argument version — this is helpful when the USE flag name does not exactly match the
./configure argument.