An eclass is a collection of code which can be used by more than one ebuild. At the time of writing, all eclasses live in the eclass/ directory in the tree. Roughly speaking, there are three kinds of eclass:

• Those which provide common functions which are used by many ebuilds (for example, autotools, bash-completion-r1, flag-o-matic, toolchain-funcs)
• Those which provide a basic build system for many similar packages (for example, perl-module, vim-plugin)
• Those which handle one or a small number of packages with complex build systems (for example, kernel-2, toolchain)

Before committing a new eclass to the tree, it must be emailed to the gentoo-dev mailing list with a justification and a proposed implementation. Do not skip this step sometimes a better implementation or an alternative which does not require a new eclass will be suggested.

Before updating any eclass, email patches to the gentoo-dev list. It may be that your proposed change is broken in a way you had not anticipated, or that there is an existing function which performs the same purpose, or that your function may be better off in its own eclass. If you don't email gentoo-dev first, and end up breaking something, expect to be in a lot of trouble.

Note that you should also, when sending your patch, CC any maintainers of the eclass listed in the @MAINTAINER tag. You may want to contact them ahead of time and get their opinions too.

The exceptions to this rule are updates to per-package eclasses. For example, the apache-2 eclass is only used by the www-servers/apache package, and thus does not typically require changes to be emailed for review.

When removing a function or changing the API of an eclass, make sure that it doesn't break any ebuilds in the Gentoo repository. Optionally, you may wish to do a survey of some (official) overlays like ::guru, ::musl, or ::science in order to better understand how it is currently used and where possible avoid breakage by pinging the maintainers directly.

If there is an existing maintainer for an eclass (this is usually the case), you must talk to the maintainer before committing any changes.

A simple way to verify syntax is bash -n foo.eclass.

Eclasses that are no longer in use may be removed from the tree, but developers must adhere to the following process:

1. Make sure that no packages or other eclasses in the tree inherit the eclass.
2. Send a lastrite message to the gentoo-dev and gentoo-dev-announce mailing-lists, announcing that the not-used eclass will be removed in 30 days.
3. Add a one line comment to the eclass, saying exactly # @DEAD so that the eclass-manpages package will not attempt to document it.
4. Wait for the 30-day period to pass, then remove the eclass from the tree.

Eclasses are documented with comment blocks that follow a special markup syntax. The comment blocks are separated by blank lines and each block documents an individual element of an eclass.

Documentation tags for various eclass elements are explained in their respective sections below. Common to all the tags that accept multiline freetext, the @CODE tag should be used when necessary to create unformatted code chunks (such as example code) by placing the tag at the beginning and the end. The @SUBSECTION tag inserts a subsection heading; it is allowed only in the main @DESCRIPTION.

Note that pkgcheck can check for issues in eclass documentation. You could run e.g. pkgcheck scan -s eclass to check for issues in the tree or pkgcheck scan --commits to check for issues in your staged git commits.

An eclass is a bash script which is sourced within the ebuild environment. Files should be a simple text file with a .eclass extension. Allowed characters in the filename are lowercase letters, the digits 0-9, hyphens, underscores and dots. Eclasses are not intrinsically versioned.

Eclasses should start with the standard ebuild header, along with comments explaining the maintainer and purpose of the eclass, and any other relevant documentation. Eclass documentation block should be the first documentation block to appear in the eclass. The following table summarizes the available documentation tags:

Top level variables may be defined as for ebuilds. If any USE flags are used, IUSE must be set. The KEYWORDS variable must not be set in an eclass.

You should document the meaning, usage, and default value of every variable in your eclass. The tags available for documenting eclass variables are as follows:

Eclasses may define functions. These functions will be visible to anything which inherits the eclass.

You should document the purpose, arguments, usage, and return value of every function in your eclass. The standard tags available for documentation are:

Eclass functions may make use of variables just like any other bash function. Special function-specific variables should be documented using the following tags:

As an example, the following eclass was written to illustrate a better way of installing OSX application files during a discussion on this subject. It defines a single function, domacosapp.

An eclass may provide default implementations for any of the ebuild phase functions (src_unpack, pkg_postinst, etc). This can be done either as a simple function definition (which is not multiple eclass friendly) or using EXPORT_FUNCTIONS. Functions given to EXPORT_FUNCTIONS are implemented as normal, but have their name prefixed ("namespaced") with ${ECLASS}_.

If multiple eclasses export the same function, the latest (inherited last) defined version wins. If an ebuild defines a function that is exported, this gets priority over any eclass version. This can be used to override eclass-defined defaults for example, say we had fnord.eclass:

Then an ebuild could do this:

Eclasses may inherit other eclasses to make use of their functionality, and historically there have been instances of eclasses calling EXPORT_FUNCTIONS and then inheriting another eclass. As inherited eclasses may also execute EXPORT_FUNCTIONS, it was not fully defined which defaults should take effect. The general recommendation is now that eclasses should not inherit other eclasses after calling EXPORT_FUNCTIONS.

It is common practice to surround the main contents of an eclass with an "inherit guard". Much like header guards known from C, inherit guards help ensure that an eclass can be inherited multiple times and have its functions and variables defined only once. An inherit guard is only needed for an eclass that can be inherited more than once.

A typical inherit guard looks as follows (for a hypothetical foo.eclass):

When it comes to EXPORT_FUNCTIONS and inherit guards, the call to EXPORT_FUNCTIONS must be placed at the very end of the eclass outside any inherit guards, like this:

This helps to ensure that the last inherited eclass gets to define the default phase functions. Consider two eclasses foo.eclass and bar.eclass that define the same default phase function via EXPORT_FUNCTIONS. If an ebuild inherits both as inherit foo bar, then the default phases are defined by bar.eclass. If foo.eclass is then modified to inherit bar as well, then the ebuild's default functions could suddenly become those from foo if EXPORT_FUNCTIONS was placed inside the inherit guard.

Sometimes an eclass is used incorrectly by an ebuild and the eclass knows it is being used incorrectly the common example is an eclass that only works with a specific set of EAPIs, but is being accessed (inherited) by an ebuild with a different EAPI. In those cases, used sparingly as a last resort, it is allowed for an eclass to invoke die from the global scope. For example:

Here is an example of how a simple eclass for a hypothetical jmake build system might look. The eclass defines a few functions, along with default implementations for the src_configure and src_compile phase functions.