Ebuild file format

An ebuild is a bash script which is executed within a special environment. Files should be simple text files with a .ebuild extension.

File naming rules

An ebuild should be named in the form name-version.ebuild.

The name section should contain only lowercase non-accented letters, the digits 0-9, hyphens, underscores and plus characters. Uppercase characters are strongly discouraged, but technically valid.

Note: This is the same as IEEE Std 1003.1-2017, section 3.282 (Portable Filename Character Set), with the exception of the period character and with the addition of the plus character to keep GTK+ and friends happy.

The name must not begin with a hyphen or a plus sign, and must not end in a hyphen followed by anything that could be mistaken for a version.

The version section is more complicated. It consists of one or more numbers separated by full stop (or period, or dot, or decimal point) characters (eg 1.2.3, 20050108). The final number may have a single letter following it (e.g. 1.2b). This letter should not be used to indicate 'beta' status — Portage treats 1.2b as being a later version than 1.2 or 1.2a.

There can be a suffix to version indicating the kind of release. In the following table, what Portage considers to be the 'lowest' version comes first.

Suffix	Meaning
`_alpha`	Alpha release (earliest)
`_beta`	Beta release
`_pre`	Pre release
`_rc`	Release candidate
(no suffix)	Normal release
`_p`	Patch release

Any of these suffixes may be followed by an unsigned integer.

These suffixes can be chained together and will be processed iteratively. To give some examples (the following list is from lowest version to highest):

foo-1.0.0_alpha_pre
foo-1.0.0_alpha_rc1
foo-1.0.0_beta_pre
foo-1.0.0_beta_p1

No integer part of the version may be longer than 18 digits.

Finally, version may have a Gentoo revision number in the form -r1. The initial Gentoo version should have no revision suffix, the first revision should be -r1, the second -r2 and so on. See Ebuild revisions. Revision numbers are distinguished from patch releases by revision bumps being changes by Gentoo developers, while patch releases are new releases by upstream (with the exception of snapshots, see below).

Overall, this gives us a filename like libfoo-1.2.5b_pre5-r2.ebuild.

The EAPI 7 version commands may be used to manipulate and extract ebuild version components.

The formal definition of the version format and the comparison algorithm can be found in the Package Manager Specification.

Snapshots and live ebuilds

When packaging a snapshot of a source repository, there are two commonly used formats. The first treats the snapshot as a patch to the previous version, and so the ebuild version is in the format $(last-released-version)_pYYYYMMDD. Alternatively, the snapshot may be treated as a pre-release to an upcoming version, usually used when a release is anticipated but not out yet. The format for this is $(upcoming-version)_preYYYYMMDD.

The policy for so-called live ebuilds (see src_unpack actions) is to use 9999 as the version (or as the last version component). For packages with more than 4 digits e.g. YYYYMMDD format, 99999999 is an acceptable alternative.

Binary packages

Gentoo usually builds its packages from source. Exceptionally, a binary package can be provided instead (e.g., if upstream does not provide a source). Such packages should still follow normal naming conventions and do not need any special suffix.

If a binary package is provided in addition to its open-source based equivalent, the name of the former should be suffixed with -bin if necessary for distinction. Examples are packages that are heavy on resources like CPU time or memory when being built from source.

Ebuild header

All ebuilds committed to the tree should have a two line header immediately at the start indicating copyright, followed by an empty line. This must be an exact copy of the contents of header.txt in the top directory of the Gentoo repository.

# Copyright 1999-2024 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

Note: The header previously included a third line with a CVS $Id$ or $Header$ keyword. That line was abolished after conversion to Git by decision of the Gentoo Council on 28 February 2017 and must not be added any more.

Indenting and whitespace

Indenting in ebuilds must be done with tabs, one tab per indent level. Each tab represents four spaces. Tabs should only be used for indenting, never inside strings.

Avoid trailing whitespace: pkgcheck will warn you about this if your ebuild contains trailing or leading whitespace (whitespace instead of tabs for indentation) when you commit.

Where possible, try to keep lines no wider than 80 positions. A 'position' is generally the same as a character — tabs are four positions wide, and multibyte characters are just one position wide.

Character set

All ebuilds (and eclasses, metadata files, etc.) must use the UTF-8 character set. See GLEP 31 for details.