1. Overview

This guide mainly focuses upon how to build and deploy software projects which build system is based upon eBuild. This document mainly targets software package integration.

eBuild is distributed under the GNU General Public License.

2. Prerequisites

Minimal requirements

The following installed package is required to build eBuild based packages :

Documentation generation

In addition, you might need the following installed packages to build the documentation :

Full-feature requirements

For a full-featured eBuild based package, the following is also required in addition to the above :

3. Workflow

The typical build and install workflow for a software project based upon eBuild is the following:

  1. Configure the construction logic

  2. Build programs, libraries and other objects required at running time,

  3. Install components, copying files previously built to system-wide directories

The 3 phases mentioned above are subject to customization thanks to multiple make variable settings that may be passed on the command line. You are encouraged to adjust values according to your specific needs. Most of the time, setting BUILDDIR, PREFIX and CROSS_COMPILE is sufficient. Refer to the following sections for further informations.

After a successful Install phase, final constructed objects are located under the directory pointed to by $(DESTDIR)$(PREFIX) where DESTDIR and PREFIX are 2 make variables the user may specify on the command line to customize the final install location.

Alternatively, you are also provided with the ability to :

To begin with, configure the build process according to the following section.

3.1. Configure

To apply the project’s default build configuration, run the following command from the top-level project’s source tree:

$ make defconfig

You may specify an alternate default build configuration file by giving make a DEFCONFIG variable which value points to an arbitrary file path:

$ make defconfig DEFCONFIG=$HOME/build/config/project.defconfig

This alternate default build configuration file may be generated from current configuration into the defconfig file located under directory pointed to by the BUILDDIR variable:

$ make saveconfig BUILDDIR=$HOME/build/project
  KSAVE   /home/worker/build/project/defconfig

Optionally, you may tweak build options interactively:

$ make menuconfig BUILDDIR=$HOME/build/project

The menuconfig target runs a menu-driven user interface allowing you to configure build options. You may run alternate user interfaces using the following make targets :

  • xconfig for a QT menu-driven interface,

  • and gconfig for GTK menu-driven interface.

The default build directory location is overwritten by giving make the BUILDDIR variable which value points to an arbitrary pathname. Intermediate objects are built under the passed directory to prevent from polluting the project’s source tree as in the following example:

$ make defconfig BUILDDIR=$HOME/build/project

You may refine the configuration logic by giving make additional variables. You are encouraged to adjust values according to your specific needs. Section Variables describes the following variables which are available for configuration customization purpose:

You may also customize tools used at configuration time. Refer to section Tools for more informations.

You can now proceed to the Build phase.

3.2. Build

To build / compile / link programs, libraries, etc., run the make command like so:

$ make build

To store intermediate objects under an alternate location, give make the BUILDDIR variable like so:

$ make build BUILDDIR=$HOME/build/project

If not completed, the build target performs the configuration phase implicitly using default configuration settings.

In addition, you may specify the PREFIX variable to change the default final install location:

$ make build BUILDDIR=$HOME/build/project PREFIX=/

You may refine the build logic by giving make additional variables. You are encouraged to adjust values according to your specific needs. Section Reference describes the following variables which are available for build customization purpose:

You may also customize tools used at build time. Refer to section Tools for more informations.

You can now proceed to the Install phase.

3.3. Install

To install programs, libraries, etc., run the make command like so:

$ make install

To store intermediate objects under an alternate location, give make the BUILDDIR variable like so:

$ make install BUILDDIR=$HOME/build/project

If not completed, the install target performs the Build phase implicitly. Files are installed under directory pointed to by the PREFIX make variable which defaults to /usr/local.

You may specify the PREFIX variable to change the default final install location:

$ make install BUILDDIR=$HOME/build/project PREFIX=/

You may refine the install logic by giving make additional variables. You are encouraged to adjust values according to your specific needs. Section Reference describes the following variables which are available for install customization purpose:

You may also customize tools used at install time. Refer to section Tools for more informations.

3.4. Staged install

DESTDIR make variable allows support for staged install, i.e. an install workflow where files are deployed under an alternate top-level root directory instead of the usual directory pointed to by PREFIX.

Basically, the DESTDIR variable is prepended to each installed target file so that an install recipe might look something like:

install:
     $(INSTALL) foo $(DESTDIR)$(BINDIR)/foo
     $(INSTALL) libfoo.a $(DESTDIR)$(LIBDIR)/libfoo.a

The DESTDIR variable should be specified by the user on the make command line as an absolute file name. For example:

$ make install DESTDIR=$HOME/staging

If usual installation step would normally install $(BINDIR)/foo and $(LIBDIR)/libfoo.a, then an installation invoked as in the example above would install $(HOME)/staging/$(BINDIR)/foo and $(HOME)/staging/$(LIBDIR)/libfoo.a instead.

Prepending the variable DESTDIR to each target in this way provides for staged installs, where the installed files are not placed directly into their expected location but are instead copied into a temporary location (DESTDIR). However, installed files maintain their relative directory structure and any embedded file names will not be modified.

DESTDIR support is commonly used in package creation. It is also helpful to users who want to understand what a given package will install where, and to allow users who don’t normally have permissions to install into protected areas to build and install before gaining those permissions.

Finally, it can be usefull when installing in a cross compile environment where installation is performed according to a 2 stages process. An initial stage installs files under a top-level root directory hierarchy pointed to by the DESTDIR variable onto the development host. This step is generally part of a larger process which constructs the whole final system image to install onto the target host. Then, the second stage carries out final system image installation onto the target host thanks to a specific installer runtime that is out of scope of this document.

Refer to DESTDIR: support for staged installs for more informations.

3.5. Cleanup

3 additional make targets are available to cleanup generated objects.

The clean target remove built objects from the BUILDDIR directory without cleaning up installed objects. In other words, this performs the inverse operation of Build target:

$ make clean BUILDDIR=$HOME/build/project

The distclean target runs clean target then removes build configuration objects and distribution tarball from the BUILDDIR directory. In other words, this removes every intermediate objects, i.e., all generated objects that have not been installed:

$ make distclean BUILDDIR=$HOME/build/project

The uninstall target removes installed objects from the $(DESTDIR)$(PREFIX) directory. In other words, this performs the inverse operation of Install target:

$ make uninstall PREFIX= DESTDIR=$HOME/staging

3.6. Documentation

When enabled internally by a project, eBuild may also generates project’s documentation thanks to (and restricted to) the Sphinx ecosystem.

3.6.1. Generation

The doc make target builds documentation under $(BUILDDIR)/doc directory :

$ make doc BUILDDIR=$HOME/build/project

In addition, objects generated by the doc target may be removed using the clean-doc or clean target as described into section cleanup.

You may refine the build logic by giving make additional variables. You are encouraged to adjust values according to your specific needs. Section Reference describes the following variables which are available for documentation generation customization purpose:

3.6.2. Installation

To install documentation built thanks to doc target under DOCDIR directory, use the install-doc target.

$ make install-doc BUILDDIR=$HOME/build/project

If not completed, the install-doc target builds the documentation implicitly. Files are installed under directory pointed to by the DOCDIR make variable.

In addition, objects installed by the install-doc target may be removed using the uninstall-doc or uninstall target as described into section cleanup.

You may refine the documentation (un)install logic by giving make additional variables. You are encouraged to adjust values according to your specific needs. Section Reference describes the following variables which are available for documentation generation customization purpose:

In addition, when following a Staged install workflow, you may alter final installation directory thanks to the DESTDIR variable so that final documentation is deployed under $(DESTDIR)$(DOCDIR) filesystem hierarchy instead.

3.7. Source tags

A tags make target is also available to generate source code tag databases using Exuberant Ctags and / or Cscope tools.

When available, Exuberant Ctags database is generated into the $(BUILDDIR)/tags file whereas Cscope database is generated into $(BUILDDIR)/cscope.out file.

$ make tags BUILDDIR=$HOME/build/project

In addition, objects generated by the tags target may be removed using the clean-tags or clean target as described into section cleanup.

You may refine the build logic by giving make additional variables. You are encouraged to adjust values according to your specific needs. Section Reference describes the following variables which are available for source tags generation customization purpose:

3.8. Distribution

A dist make target is also available to generate a source distribution tarball compressed according to the XZ Utils format into $(BUILDDIR)/<package_name>-<package_version>.tar.xz.

Basically, the dist target generates, collects and include the following components into the tarball :

  • files required to build the project when no eBuild installation is found ;

  • project’s files found under revision control ;

  • if any, the project’s documentation files.

$ make dist BUILDDIR=$HOME/build/project

In addition, objects generated by the dist target may be removed using the distclean target as described into section cleanup.

3.9. Tools

You may customize tools used during construction phases by giving make additional variables like so:

$ make build CROSS_COMPILE='armv7-linaro-linux-gnueabihf-'

Section Variables describes the following variables which are available for tool customization purpose:

4. Reference

4.1. Targets

This section describes all make targets that may be given on the command line to run a particular construction phase.

4.1.1. build

Compile / link objects and optionally, build documentation objects. Built objects are stored under BUILDDIR directory.

If not completed, the build target performs the configuration phase implicitly using default configuration settings.

Refer to section Build for a list of variables affecting this target behavior.

4.1.2. clean

Remove built objects and documentation from the BUILDDIR directory.

Refer to sections Build and Tools for a list of variables affecting this target behavior.

4.1.3. clean-doc

Remove built documentation from the $(BUILDDIR)/doc directory.

Refer to section Tools for a list of variables affecting this target behavior.

4.1.4. clean-tags

Remove built tag databases from the BUILDDIR directory.

Refer to section Tools for a list of variables affecting this target behavior.

4.1.5. defconfig

Configure build using default settings. Created configuration objects are stored under the BUILDDIR directory.

Refer to section Configure for a list of variables affecting this target behavior.

4.1.6. dist

Build source distribution tarball including :

  • eBuild files required to build a project under ebuild directory,

  • project’s documentation under docs directory,

  • project’s files that are under revision control.

Tarball will be located under the BUILDDIR directory and named after the following scheme : <package_name>-<package_version>.tar.xz.

4.1.7. distclean

Run clean target then remove build configuration objects created by the build configuration and distribution targets from the BUILDDIR directory.

Refer to section Configure for a list of configuration targets variables affecting this target behavior.

4.1.8. doc

Build documentation under $(BUILDDIR)/doc directory.

Refer to section Documentation for a list of variables affecting this target behavior.

4.1.9. gconfig

Edit build configuration using an interactive GTK menu-driven interface.

An arbitrary file containing default options may be specified using DEFCONFIG variable. These default options are applied when no previous configuration target has been run.

Refer to section Configure for a list of variables affecting this target behavior.

4.1.10. help

Show a brief help message.

4.1.11. help-full

Show a detailed help message.

4.1.12. install

Install objects and optionally documentation constructed at building time. Objects are basically installed under PREFIX directory.

If not completed, the install target performs the build phase implicitly using default configuration settings.

Refer to section Install for a list of variables affecting this target behavior.

In addition, when following a Staged install workflow, you may alter final installation directory thanks to the DESTDIR variable so that final objects are deployed under $(DESTDIR)$(PREFIX) instead.

4.1.13. install-doc

Install documentation built thanks to doc target under DOCDIR directory.

Refer to section Documentation for a list of variables affecting this target behavior.

In addition, when following a Staged install workflow, you may alter final installation directory thanks to the DESTDIR variable so that final objects are deployed under $(DESTDIR)$(DOCDIR) instead.

4.1.14. install-strip

Run install target and discard symbols from installed objects.

4.1.16. saveconfig

Save current build configuration into $(BUILDDIR)/defconfig default settings file that can be loaded using a subsequent defconfig target run.

Refer to section Configure for a list of variables affecting this target behavior.

4.1.17. tags

Build source tag databases under BUILDDIR directory.

Refer to section Source tags for a list of variables affecting this target behavior.

4.1.18. uninstall

Remove installed objects and documentation from the PREFIX directory.

In addition, when following a Staged install workflow, you may alter final installation directory thanks to the DESTDIR variable so that final objects are removed from the $(DESTDIR)$(PREFIX) directory instead.

Refer to sections Install and Cleanup for a list of variables affecting this target behavior.

4.1.19. uninstall-doc

Remove installed documentation from the DOCDIR directory.

In addition, when following a Staged install workflow, you may alter final installation directory thanks to the DESTDIR variable so that final objects are removed from the $(DESTDIR)$(DOCDIR) directory instead.

Refer to sections Documentation and Cleanup for a list of variables affecting this target behavior.

4.1.20. xconfig

Edit build configuration using an interactive QT menu-driven interface.

An arbitrary file containing default options may be specified using DEFCONFIG variable. These default options are applied when no previous configuration target has been run.

Refer to section Configure for a list of variables affecting this target behavior.

4.2. Variables

This section describes all make variables that may be given on the command line to customize the construction logic.

4.2.1. AR

Object archiver

Default:

${CROSS_COMPILE}ar

Mutable:

yes

Tool used to create static libraries, i.e. built objects archives.

See ar(1).

4.2.2. BINDIR

Executable programs install directory

Default:

${PREFIX}/bin

Mutable:

yes

Pathname to directory where to install executable programs. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.3. BUILDDIR

Build directory

Default:

${TOPDIR}/build

Mutable:

yes

Pathname to directory under which intermediate objects are generated. Applies to all construction phases.

4.2.4. CC

C compiler

Default:

${CROSS_COMPILE}gcc

Mutable:

yes

Tool used to build C objects.

See gcc(1).

4.2.5. CROSS_COMPILE

Cross compile tool prefix

Default:

empty

Mutable:

yes

Optional prefix prepended to build tools used during construction. The following variables are affected: AR, CC, LD, STRIP.

4.2.6. CSCOPE

Cscope source tag database generation tool

Default:

cscope

Mutable:

yes

Tool used to generate Cscope source code tag database. See also CTAGS.

4.2.7. CTAGS

Exuberant Ctags source tag database generation tool

Default:

ctags

Mutable:

yes

Tool used to generate Exuberant Ctags source code tag database. See also CSCOPE.

4.2.8. DEFCONFIG

Defaut build configuration file

Default:

empty

Mutable:

yes

Pathname to optional file containing default build configuration settings. This file may be generated from current configuration as explained into section configure.

4.2.9. DATADIR

Read-only architecture-independent data install directory

Default:

${PREFIX}/share

Mutable:

yes

Pathname to directory where to install read-only architecture-independent data files.

See GNU variables for installation Directories.

4.2.10. DESTDIR

Top-level staged / root install directory

Default:

empty

Mutable:

yes

DESTDIR variable is prepended to each installed target file so that the installed files are not placed directly into their expected location but are instead copied into an alternate location, DESTDIR. However, installed files maintain their relative directory structure and any embedded file names will not be modified.

DESTDIR is commonly used in package creation and cross compile environment. See section Staged install and DESTDIR: support for staged installs for more informations.

4.2.11. DOCDIR

Documentation install directory

Default:

${DATADIR}/doc

Mutable:

yes

Pathname to directory where to install documentation files other than man pages and info files.

See GNU variables for installation Directories.

4.2.12. DOXY

Doxygen documentation generation tool

Default:

doxygen

Mutable:

yes

Tool used to generate source code documentation. See doxygen(1).

4.2.13. EBUILDDIR

Ebuild directory

Default:

empty

Mutable:

yes

Pathname to directory where ebuild logic is located.

4.2.14. ECHOE

Shell escaped string echo’ing tool

Default:

/bin/echo -e

Mutable:

yes

Tool used to print strings to console with shell backslash escapes interpretation enabled. See echo(1).

4.2.15. GIT

Git, the stupid content tracker command line tool

Default:

git

Mutable:

yes

Tool used to build source distribution tarballs for Git based projects. See git(1).

4.2.16. INFODIR

Info files install directory

Default:

${DATADIR}/info

Mutable:

yes

Pathname to directory where to install Info files.

See GNU variables for installation Directories.

4.2.17. INCLUDEDIR

Header files install directory

Default:

${PREFIX}/include

Mutable:

yes

Pathname to directory where to install development header files to be included by the C #include preprocessor directive.

See GNU variables for installation Directories.

4.2.18. INSTALL

Install tool

Default:

install

Mutable:

yes

Tool used to copy filesytem entries and set their attributes. See install(1).

4.2.19. INSTALL_INFO

Info files page installer tool

Default:

install-info

Mutable:

yes

Tool used to install texinfo(5) documentation system info(5) pages generated using makeinfo(1) tool. See also install-info(1).

4.2.20. KCONF

KConfig line-oriented tool

Default:

kconfig-conf

Mutable:

yes

Tool used to configure the build logic thanks to a line-oriented user interface (questions - answers).

See KConfig.

4.2.21. KGCONF

KConfig GTK menu based tool

Default:

kconfig-gconf

Mutable:

yes

Tool used to configure the build logic thanks to a GTK menu driven user interface.

See KConfig.

4.2.22. KMCONF

KConfig NCurses menu based tool

Default:

kconfig-mconf

Mutable:

yes

Tool used to configure the build logic thanks to a text menu driven user interface.

See KConfig.

4.2.23. KXCONF

KConfig QT menu based tool

Default:

kconfig-qconf

Mutable:

yes

Tool used to configure the build logic thanks to a QT menu driven user interface.

See KConfig.

4.2.24. LATEXMK

LaTeX documentation builder tool

Default:

latexmk

Mutable:

yes

Tool used to automate the process of building LaTeX documents. See also latexmk(1).

4.2.25. LD

Program linker

Default:

${CROSS_COMPILE}gcc

Mutable:

yes

Tool used to link objects.

See gcc(1) and ld(1).

4.2.26. LIBDIR

Libraries install directory

Default:

${PREFIX}/lib

Mutable:

yes

Pathname to directory where to install object files and libraries of object code. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.27. LIBEXECDIR

Executable programs install directory

Default:

${PREFIX}/libexec

Mutable:

yes

Pathname to directory where to install executable programs to be run by other programs rather than by users. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.28. LN

Link maker tool

Default:

ln -f

Mutable:

yes

Tool used to make links between filesystem entries. See ln(1).

4.2.29. LOCALSTATEDIR

Machine specific persistent data files install directory

Default:

${PREFIX}/var

Mutable:

yes

Pathname to directory where to install data files which the programs modify while they run, and that pertain to one specific machine. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.30. MAKEINFO

Info files documentation conversion tool

Default:

makeinfo

Mutable:

yes

Tool used to generate info(5) pages for the texinfo(5) documentation system. See also install-info(1).

4.2.31. MANDB

Man pages index maintainer tool

Default:

mandb

Mutable:

yes

mandb(8) is the tool used to maintain man(7) page index caches.

4.2.32. MANDIR

Man pages install directory

Default:

${DATADIR}/man

Mutable:

yes

Pathname to top-level directory where to install man pages.

See GNU variables for installation Directories and man-pages(7).

4.2.33. PREFIX

Prefix prepended to install variable default values.

Default:

/usr/local

Mutable:

yes

A prefix used in constructing the default values of some of the variables listed in the Variables section. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.34. PKG_CONFIG

pkg-config compile and link helper tool

Default:

pkg-config

Mutable:

yes

Helper tool used to retrieve flags when compiling applications and libraries. See pkg-config and pkg-config(1).

4.2.35. PKGCONFIGDIR

pkg-config metadata files install directory

Default:

${LIBDIR}/pkgconfig

Mutable:

yes

Pathname to directory where to install pkg-config(1) metadata files.

See GNU variables for installation Directories.

4.2.36. PYTHON

The Python interpreter version 3.x

Default:

python3

Mutable:

yes

Python interpreter required by the Sphinx documentation system. See python3(1) and SPHINXBUILD.

4.2.37. RM

Filesystem entry removal tool

Default:

rm -f

Mutable:

yes

Tool used to delete filesystem entries. See rm(1).

4.2.38. RSYNC

Rsync filesystem synchronization tool

Default:

rsync

Mutable:

yes

Tool used to copy / synchronize filesystem hierarchies. See rsync(1).

4.2.39. RUNSTATEDIR

Machine specific temporary data files install directory

Default:

${PREFIX}/run

Mutable:

yes

Pathname to directory where to install data files which the programs modify while they run, and that pertain to one specific machine, and which need not persist longer than the execution of the program. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.40. SBINDIR

System administration executable programs install directory

Default:

${PREFIX}/sbin

Mutable:

yes

Pathname to directory where to install executable programs that are only generally useful to system administrators. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.41. SPHINXBUILD

Sphinx documentation generation tool

Default:

sphinx-build

Mutable:

yes

Tool used to generate documentation from a reStructuredText file hierarchy. sphinx-build(1) may output documentation to multiple format, i.e. Info files, LaTeX, PDF and HTML. See also PYTHON, MAKEINFO, LATEXMK and DOXY.

4.2.42. STRIP

Object symbols discarding tool.

Default:

${CROSS_COMPILE}strip

Mutable:

yes

Tool used to discard symbols from compiled and linked object files. See strip(1).

4.2.43. SVN

Subversion, the Subversion version control system command line tool

Default:

svn

Mutable:

yes

Tool used to build source distribution tarballs for Subversion based projects. See svn(1).

4.2.44. SYSCONFDIR

Machine specific read-only configuration install directory

Default:

${PREFIX}/etc

Mutable:

yes

Pathname to directory where to install read-only data files that pertain to a single machine, i.e., files for configuring a host. Note that final install location is also affected by the DESTDIR variable.

See GNU variables for installation Directories.

4.2.45. TOPDIR

Source tree top-level directory

Default:

not applicable

Mutable:

no

Pathname to source tree top-level directory.

5. Troubleshooting

In case an error happens such as the one below:

$ make help
Makefile:10: *** '/usr/share/ebuild': no valid Ebuild install found !.  Stop.

This means the project is not able to find the location where ebuild is installed. This may happen when working with a project source tree that has been retrieved from version control system, i.e., not extracted from a source distribution tarball.

Give make an EBUILDDIR variable pointing to the top-level ebuild read-only data directory like so:

$ make help EBUILDDIR=/usr/local/share/ebuild