ebuild

Build and install software packages

TLDR

Create or update the package manifest

$ ebuild [path/to/file.ebuild] manifest

Clean the temporary build directories for the build file

$ ebuild [path/to/file.ebuild] clean

Fetch sources if they do not exist

$ ebuild [path/to/file.ebuild] fetch

Extract the sources to a temporary build directory

$ ebuild [path/to/file.ebuild] unpack

Compile the extracted sources

$ ebuild [path/to/file.ebuild] compile

Install the package to a temporary install directory

$ ebuild [path/to/file.ebuild] install

Install the temporary files to the live filesystem

$ ebuild [path/to/file.ebuild] qmerge

Fetch, unpack, compile, install, and qmerge the specified ebuild file

$ ebuild [path/to/file.ebuild] merge

SYNOPSIS

ebuild [options] <ebuild> <action> [<action> ...]

--debug
    Enable shell tracing and verbose debug output

--quiet
    Suppress non-error output

--quiet-build
    Hide build process output (e.g., compiler noise)

--help
    Display usage summary and exit

--version
    Show ebuild version information

--ignore-default-opts
    Skip loading default Portage options

--skip-manifest
    Bypass manifest checksum checks

--force
    Override some safety checks (use cautiously)

DESCRIPTION

The ebuild command is a fundamental tool in Gentoo Linux's Portage package management system. It processes ebuild scripts, which are shell scripts defining how to build, install, and manage software packages from source. Ebuild executes discrete phases such as fetching source tarballs, unpacking them, configuring build options, compiling code, running tests, installing binaries, and cleaning up temporary files.

While emerge orchestrates full package builds by chaining these phases automatically, ebuild allows direct invocation for debugging, resuming interrupted builds, or custom workflows. It operates within the Portage environment, respecting variables like DISTDIR (download directory), WORKDIR (build directory), and PKGDIR (package staging). Ebuild supports USE flags for conditional compilation, sandboxing for security, and features like binary packages.

Primarily used by developers and advanced users, it enables precise control over Gentoo's source-based packaging, ensuring reproducible builds across systems. Output includes colored status messages, with debug modes for troubleshooting failures in specific phases.

CAVEATS

Gentoo-specific; requires Portage environment (EROOT, PORTAGE_CONFIGROOT). Not for general use—prefer emerge. May leave artifacts if phases skipped. Sandbox must be enabled for security.

COMMON ACTIONS/PHASES

fetch: Download sources
unpack: Extract archives
configure: Run ./configure
compile: Build binaries
install: Stage to ${D}
merge: Install to live system
clean: Remove build dir

KEY ENVIRONMENT VARS

EBUILD_PHASE: Current phase name
EROOT: Root filesystem path
WORKDIR: Build workspace
DISTDIR: Source downloads

HISTORY

Developed as part of Gentoo Portage since 1999-2000 by Gentoo founders. Evolved through Portage releases (e.g., 2.x to 3.x), adding features like sandboxing (2003), USE expansion, and EAPI versions (EAPI-0 to EAPI-9) for backward compatibility and new capabilities.