ebuild Command: Tutorial & Examples

Manage and run Gentoo ebuild scripts to build and install packages from source

The ebuild command is a core utility in the Gentoo Linux distribution used for executing ebuild scripts, which are specialized bash scripts describing how to fetch, build, and install software packages. This command allows advanced users and developers to perform individual phases of the package build process manually, customize builds, test and debug ebuild scripts, and gain fine-grained control over software compilation and installation within the Portage package management system.

How ebuild Works

Ebuild scripts are essentially structured bash shell scripts containing metadata and functions that define the steps to build and install a software package. The ebuild command runs one or more of these phases to process the package:

fetch: Downloads the source code archives from specified mirrors.
checksum: Verifies the integrity of the downloaded sources using cryptographic hashes.
unpack: Extracts the downloaded source archives into the working directory.
prepare: Applies patches or makes adjustments before compilation.
compile: Builds the software from source.
test: Runs optional test suites.
install: Installs the compiled software into a temporary directory.
qmerge: Merges the temporary installation into the live system.
clean: Removes temporary files from the build process.

Each phase corresponds to a specific function or set of commands inside the ebuild script. The ebuild command can be invoked to execute individual phases or multiple phases sequentially.

What ebuild Is Used For

The ebuild command serves several purposes for Gentoo users and developers:

Testing and Debugging: Developers can manually run phases to test or debug ebuild scripts before inclusion in the main repository.
Custom Builds: Users can build packages with custom configuration options or patches.
Manual Package Management: Allows building and installing packages from source without using the higher-level emerge tool.
Dependency Management: Helps in troubleshooting and resolving issues related to package dependencies.
Learning: Provides insight into how packages are built and installed on Gentoo.

Why ebuild Is Important

Gentoo's defining feature is its flexibility and source-based package management. The ebuild command is fundamental to this approach because it gives users granular control over every step of the build process. This enables customization, optimization, and fine-tuning that precompiled binaries cannot provide. It also supports Gentoo's continuous integration and testing workflows by allowing developers to execute and validate ebuild scripts independently.

How To Use ebuild And Common Command Line Parameters

The basic syntax of the ebuild command is:

ebuild /path/to/package-version.ebuild phase1 [phase2 ... phaseN]

Here, phaseN is one or more phases to execute. If no phase is specified, no action is performed.

Common Phases And Examples

fetch

Fetch the source code archives specified in the ebuild:
```
ebuild /usr/portage/app-editors/vim/vim-8.2.ebuild fetch
```

unpack

Unpack the fetched source archives:

ebuild /usr/portage/app-editors/vim/vim-8.2.ebuild unpack

compile

Compile the software:

ebuild /usr/portage/app-editors/vim/vim-8.2.ebuild compile

install

Install the compiled software into a temporary directory:
```
ebuild /usr/portage/app-editors/vim/vim-8.2.ebuild install
```

clean

Clean up temporary files:

ebuild /usr/portage/app-editors/vim/vim-8.2.ebuild clean

Combined phases

You can run multiple phases in sequence:

ebuild /usr/portage/app-editors/vim/vim-8.2.ebuild fetch unpack compile install clean

Example Output

Running the above combined command might produce output like:

>>> Fetching (1 of 1) app-editors/vim-8.2
>>> Unpacking source...
>>> Compiling source...
>>> Installing package...
>>> Cleaning up...

Potential Problems And Pitfalls

Using ebuild manually can expose some common challenges:

Dependency Issues

Missing or incorrect dependencies defined in the ebuild script will cause build failures.
Incorrect Ebuild Scripts

Syntax errors or logic errors in the ebuild can cause failures or unexpected behavior.
Permissions

Running ebuild often requires superuser privileges to install software and write to system directories.
Environment Variables

Incorrect or missing environment variables (such as PORTDIR or DISTDIR) can affect fetching and building.
Network Issues

Fetching sources requires network connectivity; proxies or firewall settings may block downloads.
Disk Space

Building from source can consume significant disk space; running out of space will cause failures.

Common Errors And Troubleshooting

Missing Dependencies

Error messages like:
```
!!! Missing dependencies: dev-libs/libfoo required.
```
Use emerge to install missing dependencies before retrying.
Permission Denied

Errors such as:
```
bash: /usr/portage/app-editors/vim/vim-8.2.ebuild: Permission denied
```
Run the command with superuser privileges using sudo or switch to root.
Build Failures

Compilation errors during the compile phase usually indicate missing libraries, misconfigured flags, or source code problems. Review the logs carefully.
Checksum Failures

If source archives fail integrity verification, try cleaning and fetching again.
Environment Variable Issues

Make sure variables like PORTDIR (path to the Portage tree) and DISTDIR (where source files are stored) are set correctly.

Advanced Usage And Integration

Using ebuild With emerge

While ebuild executes phases manually, emerge automates dependency resolution, fetching, building, and installation. Developers often use ebuild to test ebuilds before submitting them to the repository, and users rely on emerge for everyday package management.
Custom Ebuild Development

You can write or modify ebuild scripts to change build options or add patches. Use ebuild to test phases interactively.
Scripting And Automation

Combine ebuild commands in shell scripts to automate complex build or test workflows.
Using Portage Environment

Use ebuild within the Portage environment by sourcing make.conf and setting variables.

Automation And Scheduling

You can schedule ebuild commands using cron to automate package updates or rebuilds. For example, create a cron job to run an ebuild fetch and compile nightly:

0 3 * * * /usr/bin/ebuild /usr/portage/app-editors/vim/vim-8.2.ebuild fetch compile install clean >> /var/log/ebuild-vim.log 2>&1

This runs every day at 3 AM and logs output for review.

Monitoring And Logging

To monitor and log ebuild output:

Redirect standard output and error to log files:

ebuild /path/to/ebuild fetch compile install >> /var/log/ebuild.log 2>&1

Use the logger command to send output to the system log:

ebuild /path/to/ebuild fetch compile install 2>&1 | logger -t ebuild

Review logs in /var/log or use tail -f to watch live output.

Technical Background

Gentoo's package management is based on source builds using ebuild scripts stored in a structured tree (usually /usr/portage). Each ebuild defines variables like EAPI (Ebuild API version), metadata (e.g., homepage, license), dependencies, and functions implementing phases. The ebuild command is a helper that parses and runs these scripts with correct environment and variables, facilitating manual control of the build process.

Command History And Evolution

The ebuild command has been part of Gentoo's Portage system since its inception in early 2000s. Over time, it evolved to support multiple EAPI versions, improved debugging, and integration with other tools like emerge and repoman. It remains a fundamental tool for developers and advanced users working with Gentoo packages.

Security Considerations

Permissions

Running ebuild to install packages requires appropriate permissions, usually root. Avoid running as root unless necessary.
Environment Sanitization

Ensure environment variables are clean and correctly set to avoid injecting malicious code during build.
Source Verification

Always verify checksums and signatures of source archives.
Ebuild Script Trust

Only use ebuild scripts from trusted sources to avoid execution of harmful scripts.

Tips And Best Practices

Test ebuild scripts in a clean environment to avoid side effects.
Use ebuild to step through phases when debugging build failures.
Clean build directories with the clean phase regularly.
Use ebuild with --debug flag for verbose output.
Keep your Portage tree updated to avoid outdated ebuilds.
Use overlays for custom or third-party ebuilds.

Possible Alternatives Or Related Commands

emerge: Higher-level package manager automating dependency resolution and builds.
[repoman]: Tool for managing overlays and ebuild quality checks.
[portage]: The whole package management system including ebuilds and emerge.
ebuild is specific to Gentoo; other distros use different tools like rpm or apt.

Cheatsheet

Fetch sources:
```
ebuild /path/to/package.ebuild fetch
```
Unpack sources:
```
ebuild /path/to/package.ebuild unpack
```
Compile:
```
ebuild /path/to/package.ebuild compile
```
Install:
```
ebuild /path/to/package.ebuild install
```
Clean build files:
```
ebuild /path/to/package.ebuild clean
```

Run multiple phases:

ebuild /path/to/package.ebuild fetch unpack compile install clean