Basic guide to write Gentoo Ebuilds

This is a guide to Article description::getting started writing [[ebuilds, to harness the power of Portage, to install and manage even more software.]]

Write an ebuild to install a piece of software on Gentoo, when there are no suitable preexisting ebuilds. It's a relatively straight forward task, and is the only way to cleanly install most "third party" software system-wide. The ebuild will allow the package manager to track every file installed to the system, to allow clean updates and removal.

Once an ebuild is working, it can be shared by submitting it in a pull request or putting it in an ebuild repository and making it accessible publicly. With a little effort, ebuilds can be proposed and maintained in the GURU repository.

Ebuild repositories
In order for ebuilds to be available to Portage, they are placed in an ebuild repository that is configured for Portage through (see the section on repository management for general information about working with ebuild repositories).

Create an ebuild repository to experiment in, while following on with this guide. The rest of the article will consider a repository in.

makes creating a repository simple:

How to create an ebuild
Ebuilds are simply text files, in their most basic form. All that is needed to start writing ebuilds is a text editor, to provide installable software packages for Gentoo.

Some editors have optional ebuild functionality, in that case there skip to the appropriate section. Otherwise a skeleteon ("template") may be used to get started quicker.

Start with the skeleton
If the editor does not have integrated ebuild functionality to help to start off, there is a skeleton ebuild file located in the Gentoo ebuild repository. To start with that file as a base, simply copy it to an appropriate location ( is used as the text editor in this example):

Vim
There is a vim plugin to automatically start from a skeleton when creating an empty ebuild file.

After installing, simply create the appropriate folder for the ebuild, then launch vim with a new ".ebuild" filename provided on the command line, to be automatically met with a basic skeleton that can be modified and saved:

Emacs
A similar tool is available for users of Emacs, provided by or, depending on Emacs distribution.

Demonstration by example
This example will create an ebuild for scrub, version 2.6.1 (if it didn't already exist), to show how a typical process might go.

Create a directory to house the ebuild, in the ebuild repository created earlier:

Change the shell working directory to the new path:

This example will use Vim to create the ebuild file and provide a skeleton to serve as a basis to write the ebuild on, but use editor of choice (see previous section about using Emacs, or the skeleton file):

Add important information about the new package by setting the ebuild-defined variables: DESCRIPTION, HOMEPAGE, SRC_URI, LICENSE:

This is the minimum information necessary to get something that will work. Save the file - voila an ebuild, in it's most basic form, it's that simple!

It is possible to test fetching and unpacking the upstream sources by the new ebuild, using the command:

This should download and unpack the source tarball, without error, as in the example output.

For some exceptionally simple packages like this one, that do not need patching or other more advanced treatment, the ebuild may work just so - with no further adjustments needed.

For best practice, the test suite may be run at this stage - this is particularly true when starting out:

To actually install the new ebuild on the system, run:

Patching upstream source in an ebuild
The source can be patched at installation time, to adapt to Gentoo specificities for example, by setting up patches from an ebuild.

Put the patches in the right directory:

A patch can be created from the unpacked source code as explained in the patches article. Patches should then be listed in an array called PATCHES as explained in the devmanual:

QA testing
Use or  to check for QA errors in an ebuild:

External resources

 * Gentoo Policy Guide
 * Quickstart Ebuild Guide
 * Gentoo Development guide
 * Michał Górny: Category: Ebuild writing
 * Michał Górny: The ultimate guide to EAPI 7
 * Michał Górny: The ultimate guide to EAPI 8
 * - The ebuild command's man page.
 * - The ebuild file format man page.
 * - To check for QA errors, QA keywords are explained in the last part of.
 * The skel.ebuild
 * Adding new packages via proxy-maint project