GNU build system: shallow topology

From GPWiki
Jump to: navigation, search

This tutorial demonstrates how to start a project with a shallow topology based on the GNU build system, particularly autoconf v2.67 and automake v1.11.1. The project itself is a simple "hello, world" program written in C++, consisting of a single file, main.c++, located in ./src/.

To start off, a GNU build system project which uses both autoconf and automake consists basically of two source files, and, which the GNU build system routines process and, from the instructions contained in those files, generate the scripts needed to perform sanity tests and generate the project's Makefile.


A project with a shallow topology consists of a source tree where all the source files are stored in a specific subdirectory present in the project's root directory, henceforth referred as ./. Therefore, in order to set the GNU build system to be able to build a project in this particular configuration, the programmer must provide the following files:

  • ./src/ file present in ./src/ which is used to specify the project's source files
  • ./ the file present in ./ which is used to specify the project directories which are used to store the source code files.
  • ./, autoconf's input file, located in ./, which refers to the files.

Project source files

AC_INIT([project_name], [0.1], [email_address@server])
AC_CONFIG_FILES([Makefile src/Makefile])

The file lists a set of instructions. The second instruction, AC_INIT, is used to state that this project is titled project_name and it's current version is 0.1. It also specifies an email address which can be used to contact the developers.


This file, located in ./, is only used to set a variable which is used to state all subdirectories where make should run recursively. In this case, as this project is designed with a shallow topology in mind, it only lists a single subdir.


bin_PROGRAMS = project_name
project_name_SOURCES = main.c++

Setting the project

Now, that we specified all the files needed by autoconf and automake, we can proceed to generate the project's ./configure script, the script which will perform all the sanity checks and generate the project's makefiles. We do that by running the following commands:

automake --add-missing --copy

If all succeeds then there will be a ./configure file present in your project's root directory. From here we proceed to run the script in order to perform the sanity checks and generate the makefiles.

As a side note, it is preferable that a softare package is build in a dedicated directory and thus avoiding mixing temporary files and files that you do want to keep, or at least remain unchanged by the build process. Another advantage of relying on dedicated directories to run your builds is that it enables you to have multiple concurrent builds, each one configured in a different way.

With the GNU build system, in order to set a build process in a dedicated directory you only need to:

  • create the directory
  • run the ./configure script from within that directory

For example, in order to have simultaneously a release build and a debug build you only need to perform the following commands:

mkdir build
mkdir build/{debug,release}
pushd build/debug
../../configure CXXFLAGS="-g -O0 -Wall -Werror"
pushd build/release
../../configure CXXFLAGS="-O3"

See also