Gentoo Logo

Disclaimer : This handbook has been replaced by a newer version and is not maintained anymore.

[ << ] [ < ] [ Home ] [ > ] [ >> ]

6. The Ebuild Application


6.a. Emerge and Ebuild

The ebuild application is a lower level interface to the Portage system. Using this application you can execute specific actions against a given ebuild. For instance, you can perform the individual merging steps by yourself.

Using ebuild is more for development purposes; more information about ebuild can therefore be found in the Developers Handbook. However, we will explain what ebuild instances are invoked by Portage during the merge process of a certain software title, and how to invoke the post-configuration steps some ebuilds allow you to perform.

6.b. Manually Installing Software

Fetching the Sources & Checksumming

Whenever you invoke ebuild against a given ebuild file, it will verify if the checksums of all involved files are equal to those given in the accompanying Manifest or files/digest-<name>-<version> file. This happens after the sources have been fetched.

To fetch the sources using ebuild, run:

Code Listing 2.1: Fetching the sources

# ebuild path/to/ebuild fetch

If the ebuild's md5sum does not match the one listed in the Manifest file, or one of the downloaded sources don't match those listed in the files/digest-<package> file, you will receive an error similar to this:

Code Listing 2.2: Ebuild checksum failure

!!! File is corrupt or incomplete. (Digests do not match)
>>> our recorded digest: db20421ce35e8e54346e3ef19e60e4ee
>>>  your file's digest: f10392b7c0b2bbc463ad09642606a7d6

The subsequent line will mention the erroneous file.

If you are certain that the sources you've fetched and the ebuild itself are valid, you can regenerate the Manifest and digest-<package> file using ebuild's digest functionality:

Code Listing 2.3: Regenerate Manifest and digest

# ebuild path/to/ebuild digest

Unpacking the Sources

To unpack the sources in /var/tmp/portage (or any other directory location you have specified in /etc/make.conf), run ebuild's unpack functionality:

Code Listing 2.4: Unpacking the sources

# ebuild path/to/ebuild unpack

This will execute the ebuild's src_unpack() function (which defaults to plain extraction if no src_unpack() function is defined). It is also in this step that all necessary patches are applied.

Compiling the Sources

The next step in the merge process is to compile the sources. The ebuild's compile functionality takes care of this step by executing the src_compile() function in the ebuild. This also includes the configure steps if appropriate.

Code Listing 2.5: Compiling the sources

# ebuild path/to/ebuild compile

You are advised to edit the ebuild's src_compile() function if you want to change the compilation instructions. However, you can also trick Portage into believing that the ebuild application has finished the compile steps. Run all necessary commands yourself and create an empty file called .compiled in the working directory:

Code Listing 2.6: Informing Portage about the finished compilation jobs

# touch .compiled

Installing the Files in a Temporary Location

In the next step Portage will install all necessary files in a temporary location. This directory will then contain all files that are to be merged on the live filesystem. You can accomplish this by running ebuild's install functionality, which executes the ebuild's src_install() function:

Code Listing 2.7: Installing the files

# ebuild path/to/ebuild install

Merging the Files onto the Live Filesystem

The final step is to merge all files onto the live filesystem and register those in the Portage backend. ebuild calls this step "qmerge" and involves the following steps:

  • Execute the pkg_preinst() function if specified
  • Copy over all files to the live filesystem
  • Register the files in the Portage backend
  • Execute the pkg_postinst() function if specified

Run ebuild's qmerge functionality to accomplish these steps:

Code Listing 2.8: Merging the files on the live filesystem

# ebuild path/to/ebuild qmerge

Cleaning the Temporary Directory

Finally you can clean the temporary directory using ebuild's clean functionality:

Code Listing 2.9: Cleaning the temporary directory

# ebuild path/to/ebuild clean

6.c. Additional Ebuild Features

Running all Merge-related Commands

Using ebuild's merge functionality you can run the fetch, unpack, compile, install and qmerge commands in one go:

Code Listing 3.1: Installing software

# ebuild path/to/ebuild merge

Performing Configuration Actions

Some applications include instructions that configure the package further on your system. These instructions can be interactive and are therefore not automatically executed. To run these configuration steps, which are enlisted in the ebuild's (optional) config() function, use ebuild's config functionality:

Code Listing 3.2: Configuring a package

# ebuild path/to/ebuild config

Building an (RPM) Package

You can instruct Portage to create a binary package of an ebuild or even an RPM file. Use ebuild's package or rpm functionality to create these archives. There are a few differences between those functionalities though:

  • The package functionality is a lot like the merge functionality, executing all necessary steps (fetch, unpack, compile, install) before creating the package
  • The rpm functionality builds an RPM package from the files created after having run ebuild's install functionality

Code Listing 3.3: Creating packages

(For a Portage-compatible binary package)
# ebuild path/to/ebuild package

(For an RPM package)
# ebuild path/to/ebuild rpm

The created RPM file however does not contain the ebuild's dependency information.

6.d. More Information

Please consult the following man pages for more information about Portage, the ebuild application and the ebuild files:

Code Listing 4.1: Man pages

$ man portage    (Portage itself)
$ man emerge     (The emerge command)
$ man ebuild     (The ebuild command)
$ man 5 ebuild   (The ebuild file syntax)

You will also find more development-related information in the Developers Handbook.

[ << ] [ < ] [ Home ] [ > ] [ >> ]


View all

Page updated October 24, 2004

Summary: In "The Ebuild Application" you are informed about the steps Portage takes while installing software and how you can do this yourself using the ebuild application.

Sven Vermeulen

Daniel Robbins

Chris Houser

Jerry Alexandratos

Seemant Kulleen
Gentoo x86 Developer

Tavis Ormandy
Gentoo Alpha Developer

Jason Huebel
Gentoo AMD64 Developer

Guy Martin
Gentoo HPPA developer

Pieter Van den Abeele
Gentoo PPC developer

Joe Kallar
Gentoo SPARC developer

John P. Davis

Pierre-Henri Jondot

Eric Stockbridge

Rajiv Manglani

Jungmin Seo

Stoyan Zhekov

Jared Hudson

Colin Morey

Jorge Paulo

Carl Anderson

Jon Portnoy

Zack Gilburd

Jack Morgan

Benny Chuang


Joshua Kinard

Tobias Scherbaum

Lars Weiler

Jochen Maes

Grant Goodyear

Gerald J. Normandin Jr.

Donnie Berkholz

Ken Nowack

Donate to support our development efforts.

Copyright 2001-2015 Gentoo Foundation, Inc. Questions, Comments? Contact us.