Xfce Foundation Classes

« Index | Adding a client area and context menu

Chapter 8: Building a GNU autotools project

If you're unfamiliar with the GNU autotools and want to know how to build and maintain an autotools project you should read this chapter. It will take you step-by-step through the process of creating and building a small project, and at the end provide you with some helpful links to more documentation and examples. You should also work through the next chapter on Internationalization and Localization. It will show you how to add international support to an autotools project.

Autoconf and Automake provide an effective build system to maintain your software, usually on someone else's system. Automake examines source files, determines how they depend on each other, and generates a Makefile so the files can be compiled in the correct order. Autoconf permits automatic configuration of software installation, handling a large number of system quirks to increase portability. Libtool (not discussed here) is a command-line interface to the compiler and linker that makes it easy to generate static and shared libraries.

The Essential Files

The smallest project requires you provide only two files:

Makefile.am - an input file to Automake that specifies a project's build requirements: what needs to be built, and where it goes when installed.
configure.ac - an input file to Autoconf that provides the macro invocations and shell code fragments Autoconf uses to build a configure script.

The GNU autotools will generate the rest of the files needed to build the project.

The Directory Structure

Before writing any code for a new project you need to decide on the directory structure the project will use.

The top-level directory is used for configuration files, such as configure.ac, and other sundry files like ChangeLog, COPY (a copy of the project license) and README.
Any unique library should have its own subdirectory containing all headers and sources, a Makefile.am, and any other library specific files.
The headers and sources for the main application should be in another subdirectory, typically called <src>.
Other directories can include: <config> for intermediate files, <docs> for the project documentation and <test> for the project self-test suite.

The following steps will take you through creating and building the XfcApp project. The top-level directory for XfcApp is <tutorial/chapter08>. You will find the project's header files and source files in the <src> subdirectory. There are six files: main.cc xfcapp.cc, xfcapp.hh, xfcapp.ui, statusbar.cc and statusbar.hh. The only change from the previous chapter is that the main function has been moved out of <xfcapp.cc> and into the file <main.cc>.

Makefile.am

You must provide a Makefile.am file for each directory in your source tree. Makefile.am for the top-level directory is simple. Create a new text file called 'Makefile.am' in the <tutorial/chapter08> subdirectory and add the following line to the file and save it:

SUBDIRS
= src

The SUBDIRS variable is used to list the subdirectories that must be built.

Next, in the <tutorial/chapter08/src> subdirectory create another text file called 'Makefile.am' and add the following lines to the file and save it:

bin_PROGRAMS
= xfcapp

      

AM_CXXFLAGS = $(XFCUI_CFLAGS) $(GCONF_CFLAGS)

xfcapp_SOURCES = main.cc xfcapp

.cc

xfcapp.ui statusbar.cc

xfcapp_LDADD = $(XFCUI_LIBS)$(GCONF_LIBS)

The bin_PROGRAMS variable specifies that we want a program called xfcapp to be built and installed in the bin directory when 'make install' is run.

The AM_CXXFLAGS macro sets the compiler flags. You should not use CXXFLAGS in Makefile.am because it's unsafe. CXXFLAGS is a user variable that users expect to be able to override.

The xfcapp_SOURCES variable specifies the source files used to build the xfcapp target. Note that the SOURCES variable for a target is prefixed by the name of the target, in this case xfcapp.

The last variable, xfcapp_LDADD, specifies the libraries that must be passed to the linker to build the target. This variable is only used by programs and libraries. Note that LDADD uses the same naming rule as the SOURCES variable.

configure.ac

A configure.ac file must in the project's top-level directory. Change to the <tutorial/chapter08> directory and create a text file called 'configure.ac'. Add the following lines to the file and save it:

AC_INIT(src/main.cc)

      

PACKAGE=xfcapp

VERSION=0.1.0

      

AM_INIT_AUTOMAKE($PACKAGE, $VERSION)

      

XFCUI_REQUIRED_VERSION=4.3

PKG_CHECK_MODULES(XFCUI, xfcui-4.3 >= $XFCUI_REQUIRED_VERSION)

AC_SUBST(XFCUI_CFLAGS)

AC_SUBST(XFCUI_LIBS)

      

GCONF_REQUIRED_VERSION=2.0.0

PKG_CHECK_MODULES(GCONF, gconf-2.0 >= $GCONF_REQUIRED_VERSION)

AC_SUBST(GCONF_CFLAGS)

AC_SUBST(GCONF_LIBS)

      

AC_PROG_CXX

AC_PROG_LIBTOOL

      

AC_OUTPUT(Makefile src/Makefile)

The AC_INIT macro performs essential initialization for the generated configure script. It takes as an argument a filename from the <src> subdirectory, to ensure that the <src> subdirectory has been specified correctly.

The PACKAGE and VERSION variables declare the name and version of the package respectively.

The AM_INIT_AUTOMAKE macro does all the standard initialization required by Automake and takes two arguments, the package name and version number.

The XFCUI_REQUIRED_VERSION variable specifies the minimum required libXFCui version, in this case 4.3.

The PKG_CHECK_MODULES macro checks for the specified version of the libXFCui library and if found places the necessary include flags in $(XFCUI_CFLAGS) and the libraries to link with in $(XFCUI_LIBS). If the correct version is not found configure will report an error.

The GCONF_REQUIRED_VERSION variable specifies the minimum required GConf version, in this case 2.0.0.

The PKG_CHECK_MODULES macro checks for the specified version of the GConf library and if found places the necessary include flags in $(GCONF_CFLAGS) and the libraries to link with $(GCONF_LIBS). If the correct version is not found configure will report an error.

The AC_PROG_CXX macro checks for the C++ compiler and sets the variables CXX, GXX and CXXFLAGS.

The AC_PROG_LIBTOOL macro integrates libtool support into the configure script.

The last macro AC_OUTPUT must be called at the end of configure.ac to create the Makefiles in each directory.

Generating the Output Files

Now we need to generate the required output files from the two input files configure.ac and Makefile.am. First we need to collect all the macro invocations in configure.ac that Autoconf will need to build the configure script. This is done with the following command:

$
aclocal

This generates the file aclocal.m4 and adds it to the current directory.

Now run libtoolize to add the necessary libtool files to the project:

libtoolize
--force --copy

The '--force' argument forces libtoolize to overwrite existing files and the '--copy' argument copies files to the project instead of linking to them.

Next run autoconf:

$
autoconf

After running autoconf you will find the 'configure' script in the current directory. It's important to run aclocal first because Automake relies on the contents on configure.ac and aclocal.m4.

There are a few files that the GNU standard says must be present in the top-level directory, and if not found Automake will report an error. Enter the following command to create these files:

$
touch AUTHORS NEWS README ChangeLog

Now you can run Automake to create Makefile.in:

$
automake --add-missing --copy

The '--add-missing' argument copies some boilerplate files from your Automake installation into the current directory and the '--copy' argument copies files instead of linking to them.

By now, the contents of the <tutorial/chapter08> directory should be looking a lot like the top level directory of any GNU package you may have installed before:

autom4te.cache 
src

 
AUTHORS

aclocal.m4

ChangeLog

config.guess config.sub

configure

configure.ac COPYING

depcomp

INSTALL

install-sh 
Makefile.in

Makefile.am

mkinstalldirs

missing NEWS README

You should delete the <autom4te.cache> directory from any a source tarball you release. This directory is a cache that is created and used by Automake only.

Building and Installing the Project

At this point you should be able to package up your source tree in a tarball and give it to other users to install on their own systems. A user just has to unpack the tarball and run the following commands:

$
./configure --prefix=some_directory

$ make

$ make install

If you run the above commands and look in your bin directory you will find xfcapp. Have a look at the size of the executable. Wow! Its 510 kbytes. That's because it contains all the debugging and compiler symbols needed to debug the program.

Now run the following command:

$
make install-strip

If you look at the size of xfcapp now it's a lot smaller, only 63 kbytes. The command 'make install-strip' strips out all the debugging symbols. The resulting executable is much smaller and faster but you won't be able to debug the program. As a rule, you should only strip a program when installing a stable version.

Maintaining the Input Files

Everytime you edit any of the GNU autotools input files in your package, you must regenerate the output files. If you add a new source file to the xfcapp_SOURCES variable in Makefile.am you must regenerate Makefile.in. If you are building your package you will need to rerun configure to regenerate the Makefile's. Many project maintainers put the necessary commands to do this into a script called 'autogen.sh' and run this script whenever the output files need to be regenerated.

Create a text file called 'autogen.sh' in the top-level directory and make sure you change its file mode to make it executable. Add the following commands to the file and save it:

#!
/bin/sh

      

aclocal \

&& automake --add-missing --copy\

&& autoconf

Now you can easily run the following commands to update your project's output files, and rebuild the project:

$./autogen.sh

$ ./configure --prefix=/some_directory

$ make

$ make install

Some helpful links

This tutorial should get you started using the GNU autotools and that should be enough, for a while. Eventually you will need to know more, like how to build a shared library or what other macros should be added to configure.ac. I found the following links very useful:

In the next chapter you will learn add international language support to the XfcApp project.

Top

XFC 4.4

Index