To install programs, Gentoo uses ebuilds to automatically compile and install packages from source code including their dependency. Check the chapter ebuilds in the Gentoo developer manual.

See: https://devmanual.gentoo.org/general-concepts/index.html

Ebuilds in Portage

The Gentoo ebuilds are in /usr/portage and represent the heart of the Gentoo Linux meta distribution with 10000 thousands of ebuilds.

Additionally /usr/portage contains some directories not containing ebuilds as /usr/portage/distfiles that holds the compressed sources of the single packages that got installed,

The /usr/portage directory will be updated (synchronized with the mirror defined in /etc/portage/make.conf ) using the command emerge --sync.

There is the portage tool that can query portage. Type portageq --help for more.

Working with different version of an ebuild

=<ebuild-version> is used to mean an specific ebuild containing its version

>=<ebuild-version> means ebuilds newer or equal

<ebuild>:<slot> means the ebuild with the slot number

Creating an ebuild

Before writing an ebuild, you should check if nobody else has already written this ebuild. Places to look are the overlays that you can observe with emerge --search when installed and emerge eix when you like to look in overlays that are not installed. An other place where you might find ebuilds is https://bugs.gentoo.org/. This is usually the place where people put the request to have an ebuild. So ebuilds under development and under test appear there.

The internals of /usr/portage can be observed as help to create some ebuilds yourself.

Create the Overlay

To get more help read https://devmanual.gentoo.org/ or the development manual under https://www.gentoo.org/.

Ebuilds are best developed in a local overlay and when done they can be moved to an overlay residing on th Internet. Using a local overlay avoids that commands to move and copy files to the Internet. The ebuild should not be on both overlays the local and the one on the Internet, since then Gentoo and probably yourself gets confused.

So add the overlay directory to /etc/portage/make.conf

Inside the overlay directory there must be a subdirectory metadata containing a file layout.conf with inside

masters = gentoo

Additionally there must be a subdirectory profiles inside the overlay directory containing a file repo_name with inside a name of the overlay as


Run the following to make your console aware of it:

source /etc/portage/make.conf


The ebuild directory

Beside the ebuild you need a metadata.xml file in the directors containing the maintainers e-mail address. A skeleton can be found /usr/portage/skel.metadata.xml

Further there are the following files and directories:

  1. The file ChangeLog that contains the history of the ebuild

  2. The Manifest and of course the ebuild itself are the only files necessary to emerge an ebuild. The file Manifest contains all the checksum of all the ebuild versions plus all the files to be downloaded. When one file gets changed or one file is missing (e.g. old ebuild version) then the emerge will fail with a digest failure, to get around that the Manifest could be re-created.

  3. The directory files that contains patches to the source archives and digest files containing checksums of the source archives. Digest files will be obsolete when the Manifest format Manifest2 is used. Small files that come not with the package as *.desktop files can also be added here.

Create a subdirectory (ebuild category) in the local overlay as app-misc and then add subdirectory below that with the name of the ebuild. Finally copy /usr/portage/skel.ebuild or some other file to it and give it an ebuild name <name>-<version>.ebuild

The ebuild file

Ebuild are shell scripts using the bash syntax plus helper functions. They follow the package manager specification and this has currently the version number EAPI=5

There are different standard ways how to install a package under Linux as make, automake, distutils. Packages making use of a standard way can inherit the corresponding eclasses in their ebuilds so the ebuild gets very simple and can contain just the package definitions and no code at all.

A good way to get familiar is browsing through /usr/portage and look for real and simple ebuilds and use them as examples (start with the simple ones).


The name of the ebuild contains the name of the software package, the version or the software package. A released ebuild might require later a modification. To identify that this happens, also the ebuilds have versions, to the first revision of a released ebuild -r1 will be added to the ebuilds name.

Ebuilds with the number 9999 are live ebuilds and can be considered as ebuilds without version.


Once live ebuilds are emerged they are frozen regarding future updates. To update them emerge @live-rebuild or emerge -1 <name>-9999.ebuild

There is a very rich set of solutions available for writing the ebuild. The difficult part is to know what is available and understand it and get the documentation.

A more complex ebuild would have the DEPEND (build dependency) or RDEPEND (run dependency) line showing what dependencies to other ebuilds including their version ranges.

Ebuilds can also include eclasses in /usr/portage/eclass to not have to repeat the same lines over and over.

There is also a collection scripts to be used in ebuilds in /usr/lib/portage/bin

The KEYWORDS variable shows if the ebuild is for stable architectures (e.g. x86) or/and to be tested (e.g. ~x86). If you write an ebuild then it should to be tested and therefore something like ~x86 applies. Therefore it is not yet to be considered stable and has to be unmasked in /etc/portage/package.keywords . Edit this file manually or append a line as:

echo "<my ebuild> ~x86" >> /etc/portage/package.keywords

See also:

man 1 emerge

man 1 ebuild

man 5 ebuild (it contains an example)

man 5 portage

man 5 make.conf

man 1 ebuild

and about writing ebuilds

man 5 ebuild

The ebuild (at least when making it official) must have a header as /usr/portage/header.txt

To have something to work more efficient see: http://www.linurs.org/ebuildtool.html


On of the available license from /usr/portage/license should be selected.

GPL license means also that you have also some duties. You have to make your source code and all of its published versions available for public for a certain amount of time, therefore you might choose an other license see /usr/portage/licenses . By the way, this is the reason why I prefer sometimes not using GPL, since I do not want to keep track of releases and versions.

Create Links

Avoid making copies, do links instead

dosym <source> <destination>

Install executables

Install executable files are done with

exeinto /usr/bin 
doexe <some runable>

Install man pages

The installation of man pages is done with doman

src_install() {

  <other code>
  doman girttools/girt2html.1
  doman girttools/ggirt.1
  doman girttools/girtd.1

Install documentation

To install documentation the files can be listed in the DOCS variable as

        DOCS=( README.txt COPYING.txt )

this makes installing them using the dodoc function.

Install files

Try to avoid this but if non of the specific installs can be found in https://devmanual.gentoo.org/function-reference/install-functions/index.html or in https://devmanual.gentoo.org/eclass-reference/eutils.eclass/, then the file they can be installed as

insinto <path> 
doins <file>

Install a desktop file

If a desktop file exist within the package install it to /usr/share/applications and the menu

domenu slic3r.desktop

If there is no desktop file, create one. This is best done by just copy and rename an existing one and edit it.

If you are the developer, add it to the package.

If you are not the developer add it to the ebuilds directory in the subdirectory file. Then add it

        domenu ${FILESDIR}/serna-free-bin.desktop 

There is also a function to create a desktop file using the ebuild (see: https://devmanual.gentoo.org/eclass-reference/eutils.eclass/)

make_desktop_entry <command> <name of desktop file> <icon> <Category>

Unfortunately it ends up with a desktop file having an odd file name. In graphical environments the file name is usual replaced by the name inside the desktop file. So it is fine to simply ignore this file name.

ebuilds with useflags

Declare the useflag (in the example bleow hyphenation) with IUSE and then use it in an if condition. Use it in the package dependencies if applies.


        hyphenation? (

src_configure() {

 if use hyphenation; then
  elog "do things here when usflag is set"


Object oriented ebuild writing has also arrived using eclasses https://devmanual.gentoo.org/eclass-reference/index.html. Since non object oriented ebuild functions and object oriented ebuild functions are used in parallel some confusion might occur what is now object oriented and what not. Additional some non object oriented helper functions as doicon come from an eclass.

The eclass https://devmanual.gentoo.org/eclass-reference/eutils.eclass/ is the universal eclass that holds all modern features and should therefore inherited by most ebuilds (if not already inherited by an other eclass used).

inherit eutils

Objects have methods and they can be overwritten. This way eclasses can overwrite the generic or empty methods and then have some useful code to emerge ebuild for specific build methods as automake or dist. In the simplest cases the ebuild has no code at all and just inherits the proper eclass.

emerge app-portage/eclass-manpages allows to type man epatch.eclass to get the manual pages.

Overwriting eclass method


When inheriting eclasses function calls as src_install() will be overwritten. Additionally eclasses can overwrite eclasses. However when adding src_install() in the ebuild the eclass install methods are overwritten.

Adding customized stuff to an method can be done by overwriting it, add the custom commands and then recall it.

For distutils-r1, overwrite python_install_all to insert your commands but recall distutils-r1_python_install_all to not disturb the installation (check the eclass reference pages for the names):

python_install_all() {
  doman girttools/girt2html.1
  doman girttools/ggirt.1
  doman girttools/girtd.1

Ebuilds with patches

Inside the directory where the ebuild is a subdirectory files has to be added where the patch can be copied (assuming the patch is not coming from the Internet). Using

inherit eutils

gives the support for patches to the ebuild and

src_prepare() { 
 epatch "${FILESDIR}/<name>.patch"

will do the job.


epatch handles the patch -p command line option automatically, but there must be a long enough path inside the patch files that points to the file being patched.

Binary ebuilds

Binary ebuilds are not the Gentoo way but sometimes still necessary and Gentoo supports also that. Binary ebuilds should have a filename as <name>-<version>-bin.ebuild to not get in conflict with the regular source ebuilds. Since binary depends on the architecture they need multiple version to download and restriction to the architecture, so SRC_URI will be a list:

  amd64? ( <uri for amd64> )
  x86? ( <uri for x86> )" 

Installing ebuilds

Ebuilds are installed using the following sequential steps:

  1. fetch (download)

  2. unpack

  3. patch

  4. compile

  5. install to temporary location (BUILD_PREF variable showed by emerge -v info. To manually clean rm -rf /var/tmp/portage)

  6. merge from temporary location

  7. and maybe unmerge

Using the command

emerge /usr/portage/<category>/<ebuild>/<ebuild>.ebuild <command>

all those steps are executed automatically. Optionally the program ebuild allows you to do it individually what is an advantage for trouble shooting. To get more help about the use:

Install an ebuild using the command ebuild

Using the command ebuild instead of emerge lets you observe what is going on during installation and you can do a step by step installation.

After that being satisfied with the ebuild, it can be emerged:

emerge -va<program name>


ebuild wants to be smart and avoids to do things already be done. But you are smarter and want during development on an ebuild have ebuild repeating the steps. The command clean resets ebuild's memory:

ebuild /usr/locale/portage/local-overlay/app-misc/<program name>/<program name>-< version number>.ebuild clean


The ebuild needs a digest (a checksum) that ends up in a Manifest file. For that it needs the package usually tar.gz file found on the Internet as defined inside the ebuild. This fetch from the Internet places it into /usr/portage/distfiles . If the file is not yet on the Internet then this can be done manually by copy the tar.gz file to . After that the digest can be created with

ebuild /usr/locale/portage/local-overlay/app-misc/<program name>/<program name>-< version number>.ebuild digest

or the following that should do the same

ebuild /usr/locale/portage/local-overlay/app-misc/<program name>/<program name>-< version number>.ebuild manifest

When developing an ebuild then it might be annoying to recreate the Manifest file after each modification.

There is also the option --skip-manifest

Additional creating the manifest file is omitted when ebuild thinks there is nothing to do since nothing has changed, this behavior can be overwritten using --force


ebuild /<absolute directory where ebuild is>/<ebuild name>.ebuild fetch

The zipped package gets downloaded to /usr/portage/distfiles and the checksums get checked. If the package is not yet on the Internet (e.g. if you are the developer of it) then the package can simply get copied to /usr/portage/distfiles or make a link.


Live ebuilds seem to be the way for development, but they get always fetched from the Internet. During package development it is therefore better to avoid them.

Packages that can not automatically be downloaded due to logging requirements need to be copied manually there.


ebuild /<absolute directory where ebuild is>/<ebuild name>.ebuild unpack

The package gets unpacked in /var/tmp/portage/<category and file name>/work additional directories are created under /var/tmp/portage/<category and file name>/ as distdir, homedir, temp

Prepare and Configure

After prepare follows configure are these are good steps to fix and modify everything before compilation starts. If everything is already well done then prepare and configure can be empty.


ebuild /<absolute directory where ebuild is>/<ebuild name>.ebuild compile

The package gets compiled in the /var/tmp/portage/<category and file name>/work directory. Compilation works in a sandbox that prevents that accidentally writes out of the working directories can be performed.


ebuild /<absolute directory where ebuild is>/<ebuild name>.ebuild install

Installs everything under /var/tmp/portage/<category and file name>/image. This directory serves as temporary root directory. Also for this step the sandbox is active.


ebuild /<absolute directory where ebuild is>/<ebuild name>.ebuild merge

Copies all the files over from /var/tmp/portage/<category and file name>/image to the root directory and deletes the files in /var/tmp/portage/


ebuild /<absolute directory where ebuild is>/<ebuild name>.ebuild unmerge

Finally removes all files installed in the system (merged)

Debugging emerge and ebuilds

Both programs are python scripts and are in /usr/lib/portage/bin . In the same location also the bash helper functions are located.

To get familiar with the variables an ebuild uses, print them out as:

Example 14.2. ebuild variables

          # to get familiar with the ebuild variables 
 einfo "P=${P}" 
 einfo "PN=${PN}" 
 einfo "PV=${PV}" 
 einfo "PR=${PR}" 
 einfo "A=${A}" 
 einfo "D=${D}" 
 einfo "S=${S}" 

For fop-2,0-r100 this will get

* P=fop-2.0

* PN=fop

* PV=2.0

* PR=r100

* A=fop-2.0-src.zip

* D=/var/tmp/portage/dev-java/fop-2.0-r100/image/

* S=/var/tmp/portage/dev-java/fop-2.0-r100/work/fop-2.0

* WORKDIR=/var/tmp/portage/dev-java/fop-2.0-r100/work

* FILESDIR=/var/tmp/portage/dev-java/fop-2.0-r100/files

Record of the installation

All files the user installs are listed in /var/lib/portage What is installed will be written in the following directories:


Top directory


Here is all detail data of the packages installed.


Holds all directories installed plus all files including their checksums.


Web applications installed with web-config

Linurs Servernest startpage