✦ For everyone, free.

Practical knowledge for real and everyday life

Home

Ebuilds and EAPI

Ebuilds and EAPI are core to Gentoo Linux, defining how software is packaged and managed across different system versions.

Ebuilds and EAPI define the core structure and behavior of Gentoo Linux’s package management system, Portage. An ebuild is a specialized script written in a domain-specific language based on Bash. It contains all the information and instructions necessary to fetch, configure, compile, and install a software package on Gentoo systems. The EAPI (Ebuild API) is a versioned specification that dictates the syntax, features, and functions available to ebuilds, ensuring consistency, backward compatibility, and enhancements across different Gentoo releases.

Ebuilds

Ebuilds are text files with a .ebuild extension stored in Gentoo’s Portage tree. Each ebuild corresponds to a single software package version and acts as the recipe for building and installing that package. Ebuilds encapsulate metadata, dependencies, configuration options, and custom build instructions.

Structure and Content of an Ebuild

An ebuild typically contains the following components:

  • Metadata variables: These include DESCRIPTION, HOMEPAGE, SRC_URI, LICENSE, KEYWORDS, and others that describe the package and its source.
  • Dependencies: Variables such as DEPEND, RDEPEND, and BDEPEND specify build-time, runtime, and build-time dependencies respectively.
  • Functions: Ebuilds define functions corresponding to phases of the build process, such as src_unpack(), src_configure(), src_compile(), src_install(), and others. These functions can be overridden or extended to customize the build.
  • EAPI declaration: The ebuild must declare which EAPI version it supports via the EAPI variable at the top, e.g., EAPI=8.

Purpose and Role

Ebuilds automate the process of managing software on Gentoo by allowing Portage to:

  • Download source code from various locations.
  • Verify integrity and authenticity.
  • Apply patches and configure build options.
  • Compile and install software into the system.
  • Handle dependency resolution and slotting.
  • Manage package updates and removals.

They are designed to be flexible and extensible, letting package maintainers adapt builds to different environments or user preferences.

EAPI (Ebuild API)

The Ebuild API (EAPI) is a formal specification that defines the features, syntax, and behavior available to ebuild scripts. It serves as a contract between ebuild authors and the Portage system, ensuring that ebuilds behave predictably regardless of the Portage version.

Versioning and Compatibility

EAPI is versioned using integers (e.g., 0, 1, 2, …, 8, 9), with each new version introducing new functionalities, deprecations, or stricter syntax rules. An ebuild declares the EAPI it implements to guarantee Portage can interpret it correctly.

Backward compatibility is a key concern: newer Portage versions understand older EAPIs, ensuring older ebuilds continue to work. However, older Portage versions may not support newer EAPIs, which may limit ebuild usability in certain environments.

Features Defined by EAPI

EAPI controls:

  • Syntax enhancements: Including new variable types, function signatures, and shell constructs allowed in ebuilds.
  • New functions and helpers: Providing advanced build helpers, improved dependency handling, and simplified patching mechanisms.
  • Standardized behavior: For tasks such as fetching sources, unpacking archives, applying patches, setting environment variables, and error handling.
  • Slotting and USE flags: Mechanisms to enable multiple versions or feature variants of software.
  • Security improvements: Enforcing stricter checks for source verification and build sandboxing.
  • Packaging conventions: Guidelines for file layout, logging, and metadata management.

Common EAPI Versions

  • EAPI=0: The original, minimal API with basic functionality.
  • EAPI=2: Introduced significant enhancements in dependency management and variable handling.
  • EAPI=4: Added support for USE_EXPAND, improved multilib support, and functions to simplify common tasks.
  • EAPI=7 and later: Introduced stricter sandboxing, improved parallel build support, and enhanced support for new features like binary packages.
  • EAPI=8 and 9: Continued evolving with new helpers, optimized build processes, and extended metadata capabilities.

Interaction Between Ebuilds and EAPI

The ebuild’s declared EAPI determines what language features and functions it can use. For example, an ebuild with EAPI=8 can use helpers and variables introduced in EAPI 8, but an ebuild with EAPI=2 cannot. Portage uses this declaration to parse and execute the ebuild appropriately.

This separation allows Gentoo maintainers to modernize the Portage system and introduce new features without breaking older ebuilds, while also enabling package authors to adopt newer APIs for better functionality.

Practical Example of an Ebuild Header

EAPI=8

DESCRIPTION="Example software package"
HOMEPAGE="https://www.example.org"
SRC_URI="https://downloads.example.org/${P}.tar.gz"

LICENSE="GPL-2"
SLOT="0"
KEYWORDS="~amd64 ~x86"
IUSE="feature1 feature2"

DEPEND="dev-libs/libfoo"
RDEPEND="${DEPEND}"

This snippet illustrates declaration of EAPI, metadata, dependencies, and USE flags, which together guide Portage on how to handle the package.

Summary

Ebuilds are the scripts that define how software is built and installed on Gentoo, while EAPI is the formal specification that governs how these scripts are written and interpreted. Together, they provide the flexible, powerful, and consistent foundation for Gentoo’s source-based package management system, enabling fine-grained control over software installation and system customization.

Related content