Chapter 8: Building a GNU autotools project
Table of Contents
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 smallest project requires you provide only two files:
Before writing any code for a new project you need to decide on the directory structure the project will use.
The following steps will take you through creating and building the XfcApp project. The top-level directory for XfcApp is <examples/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>.
The SUBDIRS variable is used to list the subdirectories that must be built.
Next, in the <examples/tutorial/chapter08/src> subdirectory create another text file called 'Makefile.am' and add the following lines to the file and save it:
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.
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.
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:
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:
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:
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.
Now you can run Automake to create Makefile.in:
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 <examples/tutorial/chapter08> directory should be looking a lot like the top level directory of any GNU package you may have installed before:
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.
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:
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.
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:
Now you can easily run the following commands to update your project's output files, and rebuild the project: