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 Ebuild Writing. The General Concepts 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).

# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$

EAPI=6

DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="http://ctags.sourceforge.net"
SRC_URI="mirror://sourceforge/ctags/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~mips ~sparc ~x86"

src_configure() {
    econf --with-posix-regex
}

src_install() {
    emake DESTDIR="${D}" install

    dodoc FAQ NEWS README
}

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 Ebuild File Format.

Information Variables

Next, there are a series of variables. These tell Portage various things about the ebuild and package in question.

The EAPI of the ebuild, see EAPI Usage and Description.

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 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 LICENSE is GPL-2 (the GNU General Public License version 2).

The SLOT variable tells Portage which slot this package installs to. If you've not seen slots before, either just use "0" or read Slotting.

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 Keywording for details.

Build Functions

Next, a function named src_configure. Portage will call this function when it wants to configure the package. The econf function is a wrapper for calling ./configure. If for some reason an error occurs in econf, Portage will stop rather than trying to continue with the install.

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 Install Destinations and Sandbox).

Note: 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 src_install for how to do manual installs.

The dodoc is a helper function for installing files into the relevant part of /usr/share/doc.

Ebuilds can define other functions (see Ebuild Functions). In all cases, Portage provides a reasonable default implementation which quite often does the 'right thing'. There was no need to define src_unpack and src_compile functions here, for example — the src_unpack 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. Similarly, the default src_compile function will call emake which is a wrapper for make.

Note: Formerly, the || die construct had to be used after every command to check for errors. This is no longer necessary in EAPI 4 — functions provided by Portage will die by themselves if something failed.

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 Implicit System Dependency 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:

# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$

EAPI=5

DESCRIPTION="detox safely removes spaces and strange characters from filenames"
HOMEPAGE="http://detox.sourceforge.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"

LICENSE="BSD"
SLOT="0"
KEYWORDS="~hppa ~mips sparc x86"

RDEPEND="dev-libs/popt"
DEPEND="${RDEPEND}
    sys-devel/flex
    sys-devel/bison"

src_configure() {
    econf --with-popt
}

src_install() {
    emake DESTDIR="${D}" install
    dodoc README CHANGES
}

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 Predefined Read-Only Variables).

Again, we define src_configure 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 Dependencies for some more complex examples.

Ebuild with Patches

Often we need to apply patches. This is done in the src_prepare 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:

# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$

EAPI=5

inherit eutils

DESCRIPTION="detox safely removes spaces and strange characters from filenames"
HOMEPAGE="http://detox.sourceforge.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"

LICENSE="BSD"
SLOT="0"
KEYWORDS="~hppa ~mips ~sparc ~x86"

RDEPEND="dev-libs/popt"
DEPEND="${RDEPEND}
    sys-devel/flex
    sys-devel/bison"

src_prepare() {
    epatch "${FILESDIR}"/${P}-destdir.patch \
        "${FILESDIR}"/${P}-parallel_build.patch
}

src_configure() {
    econf --with-popt
}

src_install() {
    emake DESTDIR="${D}" install
    dodoc README CHANGES
}

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 your developer's space at dev.gentoo.org rather than in files/ or mirrors — see Gentoo Mirrors and Patching with epatch.

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.

# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$

EAPI=5

DESCRIPTION="GNU charset conversion library for libc which doesn't implement it"
HOMEPAGE="http://www.gnu.org/software/libiconv/"
SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz"

LICENSE="LGPL-2.1"
SLOT="0"
KEYWORDS="~amd64 ~ppc ~sparc ~x86"
IUSE="nls"

DEPEND="!sys-libs/glibc"

src_configure() {
    econf $(use_enable nls)
}

src_install() {
    emake DESTDIR="${D}" install
}

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 Query Functions Reference).

Another more complicated example, this time based upon mail-client/sylpheed/sylpheed-1.0.4.ebuild:

# Copyright 1999-2016 Gentoo Foundation
# Distributed under the terms of the GNU General Public License v2
# $Id$

EAPI=5

inherit eutils

DESCRIPTION="A lightweight email client and newsreader"
HOMEPAGE="http://sylpheed.good-day.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="alpha amd64 hppa ia64 ppc ppc64 sparc x86"
IUSE="crypt imlib ipv6 ldap nls pda ssl xface"

RDEPEND="=x11-libs/gtk+-2*
    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_prepare() {
    epatch "${FILESDIR}"/${PN}-namespace.diff \
        "${FILESDIR}"/${PN}-procmime.diff
}

src_configure() {
    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)
}

src_install() {
    emake DESTDIR="${D}" install

    doicon sylpheed.png
    domenu sylpheed.desktop

    dodoc [A-Z][A-Z]* ChangeLog*
}

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.