Basic guide to write Gentoo Ebuilds

This article contains instructions for beginners on ebuild development.

Portage, the heart of Gentoo, runs on ebuilds![edit | edit source]

An ebuild file is a text file, used by Gentoo package managers, which identifies a specific software package and how the Gentoo package manager should handle it. It uses a bash-like syntax style and is standardized through the EAPI version.

Gentoo Linux uses ebuilds as the package management format for individual software titles. These ebuilds contain metadata about the software (the name and version of the software, which license the software uses, and the home page), dependency information (both build-time as well as run-time dependencies), and instructions on how to deal with the software (configure, build, install, test ...).

Ebuilds: Where do they live?[edit | edit source]

The location of ebuilds from the Gentoo repository (available in the snapshot) are usually at /var/db/repos/gentoo[1] or in /usr/portage for older installs. The location is determined by the repos.conf file. Custom ebuilds are recommended to be placed in a custom ebuild repository, say /var/db/repos/larry.

How to create an ebuild[edit | edit source]

Users of vim get the basic skeleton automatically (provided by app-vim/gentoo-syntax):

root #vim ./foobar.ebuild
FILE foobar.ebuildvim starts from the template
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
 
EAPI=7
 
DESCRIPTION=""
HOMEPAGE=""
SRC_URI=""
 
LICENSE=""
SLOT="0"
KEYWORDS="~amd64 ~x86"
IUSE=""
 
DEPEND=""
RDEPEND="${DEPEND}"
BDEPEND=""

A similar tool is available for users of GNU Emacs or XEmacs (provided by app-emacs/ebuild-mode or app-xemacs/ebuild-mode, respectively).

Users of other editors can manually copy the skel.ebuild file located in the Gentoo ebuild repository:

root #cp /var/db/repos/gentoo/skel.ebuild ./foobar.ebuild

Essential information of the new package should be known and added to the ebuild-defined variables DESCRIPTION, HOMEPAGE, SRC_URI, LICENSE.

Example for a given source tarball[edit | edit source]

Creating an ebuild for scrub, version 2.6.1 (if it didn't already exist) might read:

root #mkdir -p /var/db/repos/larry/app-misc/scrub
root #cd $_
root #vim ./scrub-2.6.1.ebuild
FILE scrub-2.6.1.ebuildvim starts from the template
# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2
 
EAPI=7
 
DESCRIPTION="Some words here"
HOMEPAGE="https://github.com/chaos/scrub"
SRC_URI="https://github.com/chaos/scrub/releases/download/2.6.1/scrub-2.6.1.tar.gz"
 
LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~amd64 ~x86"
IUSE=""
 
DEPEND=""
RDEPEND="${DEPEND}"
BDEPEND=""
Note
Using ${PN} variable inside SRC_URI is allowed, but not suggested. While it may shrink the line, some reasoning why not to use it is worth consideration as well.
CODE SRC_URI using variables
SRC_URI="https://github.com/chaos/${PN}/releases/download/${PV}/${P}.tar.gz"

It can be tested using the ebuild command like:

root #ebuild ./scrub-2.6.1.ebuild clean unpack
Appending /var/db/repos/larry to PORTDIR_OVERLAY...
>>> Downloading 'https://ftp.halifax.rwth-aachen.de/gentoo/distfiles/scrub-2.6.1.tar.gz'
--2019-06-03 16:42:57--  https://ftp.halifax.rwth-aachen.de/gentoo/distfiles/scrub-2.6.1.tar.gz
Resolving ftp.halifax.rwth-aachen.de... 137.226.34.46, 2a00:8a60:e012:a00::21
Connecting to ftp.halifax.rwth-aachen.de|137.226.34.46|:443... connected.
HTTP request sent, awaiting response... 200 OK
Length: 362536 (354K) [application/octet-stream]
Saving to: '/usr/portage/distfiles/scrub-2.6.1.tar.gz.__download__'
 
/usr/portage/distfiles/scrub-2.6.1.tar.gz.__download__             100%[==============================================================================================================================================================>] 354.04K  --.-KB/s    in 0.08s   
 
2019-06-03 16:42:58 (4.24 MB/s) - '/usr/portage/distfiles/scrub-2.6.1.tar.gz.__download__' saved [362536/362536]
 
 * scrub-2.6.1.tar.gz BLAKE2B SHA512 size ;-) ...                                                                                                                                                                                                                  [ ok ]
>>> Unpacking source...
>>> Unpacking scrub-2.6.1.tar.gz to /var/tmp/portage/app-misc/scrub-2.6.1/work
>>> Source unpacked in /var/tmp/portage/app-misc/scrub-2.6.1/work

This should download and unpack the source tarball. In some rare cases the package should work and no further adjustments is needed in the ebuild.

Patching[edit | edit source]

In case the source code needs to get patched the patch can be created from the unpacked source code as explained in the patches article.

user $cd /var/tmp/portage/app-misc/scrub-2.6.1/work/scrub-2.6.1/

The patch will then be listed in an array called PATCHES as is explained in the devmanual.

CODE Patches will be applied during src_prepare
PATCHES=(
	"${FILESDIR}"/${P}-foo.patch
	"${FILESDIR}"/${P}-bar.patch
)
 
src_prepare() {
    default
    ...
}

Adding support for user patches to ebuilds[edit | edit source]

Since EAPI 6, the support for user patches is provided by eapply_user. This can be done by putting default on top in the src_prepare function:

CODE sample src_prepare
src_prepare() {
    default
    ...
}

EAPI versions prior to EAPI 7 should not be used for new ebuilds.

See also[edit | edit source]

External resources[edit | edit source]

References[edit | edit source]

  1. ↑ Change /usr/portage council approved locations (bug 378603)
    This article is issued from Gentoo. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.