Working with ebuild

Updated 7 November 2026

This page applies to Portage 3.0.82 and Calculate Utilities 3.8.

Purpose

The man page defines the utility in a single phrase: "ebuild - a low level interface to the Portage system". The full description from the same page:

The ebuild program is a direct interface to the Portage system. It allows for direct action upon an ebuild with specific subcommands or groups of commands to perform in a specific ebuild’s context and functions.

Accepting an ebuild script and one or more commands as arguments, the ebuild program parses the ebuild script and executes the specified commands.

You handle everyday tasks - searching, installing, updating and removing packages - through emerge: it resolves dependencies (see Introduction to Portage). ebuild works on one single file and is not a replacement for emerge in routine package management.

The low-level utility is needed when you work with the file by hand:

  • check your own ebuild in your own repository - build it step by step and see at which stage the build fails;
  • update the Manifest file of a package you wrote yourself;
  • download and verify the sources without starting the installation;
  • debug an ebuild script by looking at what you get after each function.

The man page carries the full reference text of the utility:

man ebuild

Syntax

ebuild file command [command]...

The first argument is the path to the file, followed by one or more commands: all of them run in a single call. The man page makes a single requirement of the file:

It must be a working ebuild script.

The syntax of the ebuild script itself is described in the reference page ebuild(5):

man 5 ebuild

Commands

man ebuild prints the full wording.

Execution order

By default, portage runs every function in order up to and including the specified one, except functions that have already been called in previous ebuild calls.

For example, if you give the compile command, you also invoke the functions that precede it (such as setup and unpack), unless they ran in a previous ebuild call. If you want to be sure that all of them have run, you need to use the clean command first.

If you want only one command to run, you should add the noauto option to the value of the FEATURES environment variable.

Portage features are set with the FEATURES variable; in Calculate Linux you change it in the user file /etc/portage/make.conf/custom (see Portage features and Configuring your system with variables).

Build commands

Command Action
help Prints condensed help about the program, plus a range of information about the package.
setup Runs all the setup actions for this package, including exotic system checks.
fetch Checks that every source listed in SRC_URI is available in the DISTDIR directory (see make.conf(5)) and has the correct checksum. If the sources are not available, an attempt is made to download them from the servers listed in SRC_URI.
unpack Extracts the sources into a subdirectory of the build directory (BUILD_PREFIX), calling the src_unpack() function inside the ebuild file.
prepare Prepares the unpacked sources by calling the src_prepare() function defined in the ebuild file. When src_prepare() runs, the working directory is ${S}. The function is supported from EAPI 2 onward.
configure Configures the unpacked sources by calling the src_configure() function defined in the ebuild file. When src_configure() runs, the working directory is ${S}. The function is supported from EAPI 2 onward.
compile Compiles the unpacked sources by calling the src_compile() function defined in the ebuild file. When src_compile() runs, the working directory is ${S}. By the time src_compile() finishes, the sources must be fully compiled.
test Runs specific tests for certain packages to check the build.
install Installs the package into the temporary install directory by calling the src_install() function.
clean Cleans up the temporary build directory that Portage created specifically for this ebuild file.
digest Currently an equivalent of the manifest command.
manifest Updates the Manifest file of the package. This creates checksums for all files found in the same directory as the ebuild being processed, and for the contents of the nested directories of the files subdirectory.

If the checksums do not match, the fetch command fixes nothing: it prints a warning and exits with error code 1.

If for any reason the checksum of the current or freshly downloaded sources does not match the checksum recorded in the files/digest-[package]-[version-revision] file, a warning is printed and the ebuild program exits with error code 1.

Unpack directory

Normally the sources are unpacked into the ${BUILD_PREFIX}/[package]-[version-revision]/work directory. You can access it through the ${WORKDIR} variable.

When you write an ebuild file yourself, make sure that the S variable (the source directory), defined at the beginning of the ebuild script, points to the directory that really contains the unpacked sources. By default it is defined as ${WORKDIR}/${P}, so usually nothing has to be changed.

Patches are applied at the unpack stage too: "The src_unpack() function is also responsible for applying all patches prior to package compilation."

Install and unmerge commands

Command Action
qmerge This function installs every file in the install directory onto the current filesystem. It is done as follows: first the pkg_preinst() function is run (if it exists). Then all files are installed into the filesystem and their checksums are recorded in /var/db/pkg/${CATEGORY}/${PN}-${PVR}/CONTENTS. Finally, once all files are installed, the pkg_postinst() function is run (if it exists).
merge Normally, to install an ebuild file you have to run the following actions in sequence: fetch, unpack, compile, install and qmerge. If all you want is to install the ebuild file, use this command: it runs all of those operations itself and stops mid-way only if some function fails.
unmerge This command first calls the pkg_prerm() function (if it exists). Then it removes from the current filesystem all files whose package contents file has the correct checksum and modification time. All empty directories are removed along with the nested ones.
package This command is very similar to merge, except that after fetching, unpacking, compiling and installing, it creates a .tbz2 binary package archive, which is then saved in the PKGDIR directory (see make.conf(5)).
rpm Builds a RedHat RPM package from the files in the temporary install directory. At the moment, the dependency information of the ebuild file is not included in the RPM.
config Runs the actions that a specific package needs performed before the installation begins. These are usually configuration file setup or other configuration actions that the user may want to carry out.
preinst Runs package-specific actions that must be performed before the package is installed into the current filesystem.
postinst Runs package-specific actions that must be performed after the package is installed into the current filesystem. This usually prints useful messages.
prerm Runs the actions that a specific package needs performed before it is removed from the filesystem.
postrm Runs the actions that a specific package needs performed after it has been removed from the filesystem.

In Calculate Linux the binary package directory PKGDIR is /var/calculate/packages/x86_64, where files like vim-9.2.1202.tbz2 live (the path map is on the Files and directories page).

It is safe to merge a new version of a package first and then unmerge the old one. In fact, this is the recommended package upgrade method.

Options

Option Action
--force When used together with the digest or manifest command, this option forces the generation of new digests for all source files that belong to this ebuild file. If the required sources are missing from the ${DISTDIR} directory, they are downloaded automatically.
--skip-manifest Skip checking the Manifest files.
--debug Run bash with the -x option, so that the standard output contains detailed debugging information.
--ignore-default-opts Do not use the EBUILD_DEFAULT_OPTS environment variable.

man ebuild prints the full list of options.

Temporary build directory

clean works with the directory that Portage creates for each ebuild file:

The location of the build directory is determined by the value of the PORTAGE_TMPDIR variable. To find out its current value, run emerge --info.

It is important to keep in mind what Portage does with the build leftovers:

Note: Portage removes almost all the data left after a successful package install, except when 'noclean' is explicitly specified in FEATURES.

If you add noclean to the FEATURES value, it will not take long before a large amount of disk space is filled with useless files. It is not recommended to keep this mode on permanently; use it only if you will need the package sources after the installation.

Optionally, one may manually clean these files with rm -rf /var/tmp/portage. In Calculate Linux the build directory is set by the PORTAGE_TMPDIR variable and equals /var/calculate/tmp (the path map is on the Files and directories page). Before removing anything, check what value the PORTAGE_TMPDIR variable has on your system:

emerge --info | grep PORTAGE_TMPDIR

Example: checking a local ebuild

Below is how to check your own ebuild file - the one you wrote or edited yourself. In Calculate Linux such files are kept in the user repository custom at /var/calculate/repos/custom with the calculate and gentoo masters: its directory structure mirrors the official tree, but you create the category and package directories yourself when you move an ebuild file out of the official tree (details on the Stepping aside from the official tree page). The file takes a path of the form /var/calculate/repos/custom/category/package/package-version.ebuild.

Throughout the text below, [HTML_REMOVED] is the full path to your ebuild file, and [HTML_REMOVED]/[HTML_REMOVED] is the category and name of your package.

Step 1. Check the sources and checksums. The command installs nothing - it only verifies and, when needed, downloads the archives:

ebuild [HTML_REMOVED] fetch

Step 2. Update the Manifest. For your own file the checksums are recomputed over every file next to the ebuild, over the files subdirectory, and over everything listed in SRC_URI:

ebuild [HTML_REMOVED] manifest

The manifest command does not change the system and runs as an ordinary user; root rights are needed only for commands that change the system: install, qmerge, unmerge.

If the required sources are missing from DISTDIR and have to be downloaded while the sums are recomputed, add --force to the same command:

ebuild [HTML_REMOVED] manifest --force

Step 3. Build step by step. Clean the build directory first - functions that have already run are not run again, and the result may rely on stale data:

ebuild [HTML_REMOVED] clean

Then walk the chain one step at a time, checking the result after each:

ebuild [HTML_REMOVED] unpack

ebuild [HTML_REMOVED] prepare

Next come configuration and compilation:

ebuild [HTML_REMOVED] configure

ebuild [HTML_REMOVED] compile

You can give several commands in a single call:

ebuild [HTML_REMOVED] unpack prepare compile

If each command must run in isolation, without the preceding functions, add noauto to FEATURES.

Step 4. Look at the install image. Once install finishes, the install directory holds all the files that are to be installed into the filesystem or included in the binary package:

ebuild [HTML_REMOVED] install

Step 5. Install the package. When the file works, do the installation through emerge: it will resolve the dependencies and run the needed stages:

emerge -a [HTML_REMOVED]/[HTML_REMOVED]

Precautions

  • emerge resolves dependencies, not ebuild: the utility runs the commands of the given file and does not check which packages must be built first.
  • qmerge moves the files from the install directory "to the live filesystem", while unmerge removes only those of them whose package contents file has the correct checksum and modification time. Running these commands without need leaves files in the live system that you will have to delete by hand.
  • Running clean before the full chain is mandatory: functions that have already run are not run again, and the build result may rely on stale data.
  • --skip-manifest turns off checking of the Manifest files, and --force re-creates the digests from whatever sources were found in DISTDIR. Apply them deliberately: after --force a checksum mismatch will no longer be visible.
  • The manifest command is meant for your own file. Do not re-create manifests of official-tree packages to clear a checksum mismatch message: in that case, update the tree first and find out its state (see Introduction to Portage).

See also