Autobuilding Projects

From the autoconf manual: Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of UNIX-like systems.

Autoconf works by producing system-specific variants of files - the input files are named filename. and contain @varname@ symbols. Compilation is controlled by a script named configure which takes all of the filename.in sources and substitutes @varname@ with values determined by the configure script.

The companion of autoconf is automake which attempts to provide standard mechanisms for producing the input files to autoconf. The most important function of automake is to generate Makefile.in files for use by autoconf. It generates these files from Makefile.am files written by the programmer.

Setup
Each project has a unique home directory (usually the name of the project). This directory contains configuration and top-level documentation files used by autoconf and automake. Since the directory is rather cluttered, source code is kept in a subdirectory (by convention named src).

To use automake, you must create a series of files in the top-level directory. The list of files consists of:

configure.in Specifies configuration for autoconf and automake

acinclude.m4 Optional file for any local macros for autoconf

Makefile.am Input file for automake. At the top level, it contains only one line, "SUBDIRS = src", which tells automake that all source code can be found in the src subdirectory.

NEWS Contains any news about the project.

README The readme file of the project.

AUTHORS Lists the authors of the project along with contact information.

ChangeLog Contains a list of changes between versions.

Source code can be placed directly in src or in subdirectories of src. If the project involves libraries and test programs it is wise to use at least two subdirectories: one for the library sources and another for the test programs. If you are using a subdirectory structure, the Makefile.am in src should contain a single single line "SUBDIRS = xxx yyy zzz" listing the subdirectory names. Compilation will proceed in the order specified, so in this case xxx will be compiled before yyy.

To add a directory containing code, you need to create a Makefile.am, add the subdirectory to the parent directory's Makefile.am and list the Makefile to be generated in configure.in in the toplevel directory. If, for example, I was to add a new subdirectory daemons to a project named Statmon in /home/kkaugars/Statmon, I would:
mkdir /home/kkaugars/Statmon/src/daemons
create /home/kkaugars/Statmon/src/daemons/Makefile.am
edit /home/kkaugars/Statmon/src/Makefile.am to include daemons on the SUBDIRS = line
edit /home/kkaugars/Statmon/configure.in and add src/daemons/Makefile to the AC_OUTPUT section.

Makefile.am
The input to automake is Makefile.am. This is a highly simplified form of a makefile which automake uses to generate the complex Makefile.in files used by autoconf. The automatic building system takes care of dependency checks, installation paths, project packaging, etc...

To write a Makefile.am for a binary program, you need at least two lines in the file:
bin_PROGRAMS = progname
progname_SOURCES = file1.C file2.C ...
The first line tells automake to build the program named progname, the second tells automake that this program consists of the source code files file1.C file2.C and so on.

Automake takes care of everything else. There are a few common special cases that deserve mention:

Adding other libraries.

This occurs frequently when you have one directory of library code and another of test code. To tell automake to add other objects to the final link of progrname, add another line to Makefile.am
progname_LDADD = ../dirname/libname.a where the ../dirname/libname.a is the other library.

Debugging.

Automake assumes that you are going to build a fully debugged program and sets default compilation flags to optimize the code. This makes is very difficult to debug. You can override the compilation flags using:
CXXFLAGS = -g (for C++)
CFLAGS = -g (for C)
in the Makefile.am file.

After completing setup, there is a sequence of three commands which initialize the system:

aclocal Takes the macros in acinclude.m4 along with any other local macros defined on the system and places them into aclocal.m4 which will be picked up by the configure script.

automake -a Translates the Makefile.am files into Makefile.in files. The -a flag stands for "add any missing files" and will add a series of support files into the project home directory.

autoconf Generates the configure script.

The standard configure script accepts a number of standard parameters, type ./configure --help in the project home directory to see a complete list. The one flag most commonly used is --prefix to set the prefix of the home directory, but you do not need to specify even this flag for development. Just run ./configure to generate the Makefiles needed for your project.

Making

The generated makefiles contain a lot of targets.

Common development targets:

make the project will be compiled in place.

make clean will delete all of the object and other temporary files.

make dist will build a .tar.gz file suitable for distribution.

An for users of the project:

make install will install the project onto the system

make uninstall will remove the project from the system

The manuals are also available for on-line browsing through www.gnu.org at:
http://www.gnu.org/manual/autoconf-2.52/autoconf.html
http://www.gnu.org/manual/autoconf-2.52/autoconf.html

I also have them installed locally:
autoconf
automake

And you can download a tar.gz file with the html documentation for use at home:
autoconf
automake