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-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
DESCRIPTION="Exuberant ctags generates tags files for quick source navigation"
HOMEPAGE="https://ctags.io/ https://github.com/universal-ctags/ctags"
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 spaces. 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 URI scheme, for example https://
).
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
or (at your option) any later version).
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 and stabilization 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).
emake DESTDIR="${D}" install
. This will
work with any properly written standard Makefile
. If this gives sandbox
errors, 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 phase 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
.
|| 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-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
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"
BDEPEND="sys-devel/bison"
src_configure() {
econf --with-popt
}
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).
We define src_configure
only. src_install
does not need to
be defined since the default implementation calling emake install
and installing common documentation files works correctly for the package.
The BDEPEND
, DEPEND
, and RDEPEND
variables are how Portage
determines which packages are needed to build and run the package. The
BDEPEND
variable lists build-time (executable) dependencies,
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 either by defining the
PATCHES
array in global scope or in the src_prepare
function
using the eapply
helper function. To use eapply
,
one must use EAPI 7. Here's app-misc/detox/detox-1.1.0.ebuild
:
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
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"
BDEPEND="sys-devel/bison"
src_prepare() {
eapply "${FILESDIR}"/${P}-destdir.patch \
"${FILESDIR}"/${P}-parallel_build.patch
eapply_user
}
src_configure() {
econf --with-popt
}
Note the ${FILESDIR}/${P}-destdir.patch
— this refers to
detox-1.1.0-destdir.patch
, which lives in the files/
subdirectory in the Gentoo repository. Larger patch files must go on your
developer's space at dev.gentoo.org
rather than in files/
or
mirrors —
see Suitable download hosts and
Patching with eapply.
When the src_prepare
phase is overridden, it must be ensured
that eapply_user
is called.
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-2022 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
DESCRIPTION="GNU charset conversion library for libc which doesn't implement it"
HOMEPAGE="https://www.gnu.org/software/libiconv/"
SRC_URI="ftp://ftp.gnu.org/pub/gnu/libiconv/${P}.tar.gz"
LICENSE="LGPL-2+ GPL-3+"
SLOT="0"
KEYWORDS="~amd64 ~ppc ~sparc ~x86"
IUSE="nls"
RDEPEND="!sys-libs/glibc"
DEPEND="${RDEPEND}"
src_configure() {
econf $(use_enable nls)
}
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-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
EAPI=8
inherit desktop
DESCRIPTION="A lightweight email client and newsreader"
HOMEPAGE="https://sylpheed.good-day.net/"
SRC_URI="mirror://sourceforge/${PN}/${P}.tar.bz2"
LICENSE="GPL-2+ LGPL-2.1+"
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}"
BDEPEND="dev-util/pkgconfig
nls? ( >=sys-devel/gettext-0.12.1 )"
PATCHES=(
"${FILESDIR}"/${PN}-namespace.patch
"${FILESDIR}"/${PN}-procmime.patch
)
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.