• 1. Introduction
• 2. How it all fits together
• 3. A Simple Project
  • 3.1. The Makefile.am file
  • 3.2. The configure.in file
• 4. Commonly Used configure.in macros
  • 4.1. AC_DEFINE
  • 4.2. AC_CHECK_LIB
  • 4.3. AC_ARG_ENABLE
  • 4.4. AC_OUTPUT
  • 4.5. AC_CHECK_FUNCS
  • 4.6. AC_CHECK_HEADERS
• 5. Using changequote
• 6. Format of the Makefile.am File
  • 6.1. Super Targets
  • 6.2. Specifying the source files
  • 6.3. Linking with internal libraries
  • 6.4. Library Headers
  • 6.5. EXTRA_DIST
  • 6.6. Plain Rules
  • 6.7. Libtool Library Versioning
• 7. Format of acconfig.h
  • 7.1. Example
• 8. Various Issues
  • 8.1. Creating a Sub-Directory with a Different Configuration
  • 8.2. mylibrary-config program
  • 8.3. Creating an RPM Spec
• 9. Links and References

• The GNU Autotools (Autoconf, Automake and Libtool) are the de-facto standard for portably building C and C++ applications.
• They support all UNIX platforms as well as Microsoft Win32
• As far as the installer is concerned, building the program depends on nothing but a Bourne shell implementation, a C compiler and a standard "make" program.
• The developer requires other tools such as the Autoconf package, Perl, the Automake package and GNU m4.

Philosophy

• Autoconf performs some system-wide tests to check for common system parameters: the location of programs, the existence of functions and system calls, their behaviour, the availability of libraries, etc.
• Using this it builds (on each target system) an appropriate makefile and a header file, which can be used to build the package natively
• This is superior than writing various "#ifdef" for every system out there, or writing a different makefile for every system.

• Automake takes as input the file Makefile.am and produces Makefile.in.
• The "autoconf" program takes as input the file configure.in (or in Autoconf 2.5 the file configure.ac) and generates the ./configure script out of it.
• Autoheader takes as input the files acconfig.h and generates the config.h.in template by parsing configure.in.
• ./configure, when ran by the user generates the normal Makefile out of Makefile.in and optionally processes other files (such as config.h.in -> config.h, an optional RPM Spec, Makefiles in other directories, etc.

• The project in question is the First-Come First-Served Readers/Writers Lock, which is a very small-scope project with very limited use of Autoconf.

This section will cover some commonly used Autoconf Macros.

• 4.1. AC_DEFINE
• 4.2. AC_CHECK_LIB
• 4.3. AC_ARG_ENABLE
• 4.4. AC_OUTPUT
• 4.5. AC_CHECK_FUNCS
• 4.6. AC_CHECK_HEADERS

• The macro AC_DEFINE can be used anywhere in the script, to define a C preprocessor macro.
• It accepts an optional argument indicating the value of the macro.
• If you want to do shell expansion for the value, use AC_DEFINE_UNQUOTED instead.
• Some Examples:

AC_DEFINE(HELLO)

AC_DEFINE(VERSION, "5.6")

myvar="foo"
othervar="bar"
AC_DEFINE_UNQUOTED(TEST, "${myvar}${othervar}")

• AC_CHECK_LIB checks for a presence of a symbol inside a library.
• It can run optional shell codes, (accepted as the third and fourth arguments) if it succeeds or fails.
• If it succeeds it will prepend -l[library] to compiler flags, and define the preprocessor macro HAVE_LIB[library].
• Examples:

AC_CHECK_LIB(m, pow)

if test "x$requires_libavl" = "xyes" ; then
    AC_CHECK_LIB(avl, avl_create, [], [
        echo "Error! You need to have libavl around."
        exit -1
        ])
fi

• AC_ARG_ENABLE allows you to define another command line option.
• It accepts three arguments:
  
  1. The flag base: the flag would be --enable-[option base]
  2. The help for this option
  3. The code to execute when the configure script is invoked with this option. In it the command line variable enableval would be set to the argument
• Examples:

AC_ARG_ENABLE(debug-rwlock,
 [  --enable-debug-rwlock  Enable an RWLock that prints debug notices \
  on the screen. This is a debugging feature which should not be \
  usually enabled],
 [ debug_rwlock=yes
 ])

AC_ARG_ENABLE(states-type,
 [  --enable-states-type[=state type] Specify the states type:
                      compact [default]: Compact States
                      debug: Debug States (very slow)
                      indirect: Indirect Stack States],
 [ if   test "x$enableval" = "xcompact" ; then
      states_type=compact
   elif test "x$enableval" = "xdebug" ; then
      states_type=debug
   elif test "x$enableval" = "xindirect" ; then
      states_type=indirect
   else
      echo
      echo "Error!"
      echo "Unknown states' type"
      exit -1
   fi
 ])

• AC_OUTPUT generates files that are required for building the packages.
• Its first argument is a whitespace separated list of files. The script will look for these files along with the suffix .in and convert them to their output files while substituting the output variable values.
• Two optional argument are commands to be executed afterwards, and commands to be executed beforehand.
• Example:

AC_OUTPUT([Makefile freecell-solver-config freecell-solver.spec], [chmod +x freecell-solver-config])

• AC_CHECK_FUNCS checks for the existence of functions in the C standard library.
• If found, the preprocessor macro HAVE_[function] is defined.

• AC_CHECK_HEADERS check for the existence of the header files specified as the first argument.
• If they are found the preprocessor macro HAVE_[header] (in all caps) is defined.

• The m4 preprocessor which is used to process configure.in uses [ and ] for grouping arguments.
• If you want to use them yourself, type changequote(, ) at the beginning of the offending code and changequote([, ]) afterwards.
• Here's an example:

AC_ARG_ENABLE(max-num-stacks,
[  --enable-max-num-stacks[=stacks num] Set the maximal number of Stacks],
[ if   test "x$enableval" = "x" ; then
     max_num_stacks=8
  else
      changequote(, )
      # Check if it's indeed a number
      if echo "0$enableval" | grep '[^0-9]' > /dev/null ; then
          echo
          echo "Error!"
          echo "max-num-stacks should be a number!"
          exit -1
      elif expr $enableval \< 8 > /dev/null ; then
          echo
          echo "Error!"
          echo "max-num-stacks cannot be lower than 8"
          exit -1
      elif expr $enableval \> 20 > /dev/null ; then
          echo
          echo "Error!"
          echo "max-num-stacks cannot be greater than 20"
          exit -1
      else
          max_num_stacks="$enableval"
      fi
      changequote([, ])
  fi])

• 6.1. Super Targets
• 6.2. Specifying the source files
• 6.3. Linking with internal libraries
• 6.4. Library Headers
• 6.5. EXTRA_DIST
• 6.6. Plain Rules
• 6.7. Libtool Library Versioning

• There are several top targets available. In each one, you can specify several targets to build.
• A partial list is:
  
  1. bin_PROGRAMS - programs that should be compiled and installed.
  2. bin_SCRIPTS - programs that should be installed but not compiled
  3. man_MANS - man pages that should be installed.
  4. lib_LTLIBRARIES - Libraries that should be built using libtool.
  5. noinst_PROGRAMS - Programs that should be compiled but not installed.

• One can specify the source files for each super target by typing the base name of the package (with _'s instead of -'s etc) followed by _SOURCES followed by an equal sign and a list of the sources.
• Example:

lib_LTLIBRARIES = libpthread_rwlock_fcfs.la
libpthread_rwlock_fcfs_la_SOURCES = rwlock.c queue.c

• To link a target with an internal library specify the target name as before along with _LDADD variable and type the library name ending with .la.

• Headers of libraries to be installed during the installation are specified using the _HEADERS directive.

• The EXTRA_DIST argument holds a list of all the files that are part of the package, but are not installed by default and were not specified in any other way.
• It includes such odds and ends as README files, internal headers and maintenance scripts.

• It is possible to specify plain rules in an Automake file, just as you would in a normal makefile.
• Within these rules one can use the meta-variables $< as the source and $@ as the target.

• In the flag mylibrary_LDFLAGS one should specify an option like that: -version-info [CURRENT]:[REVISION]:[AGE].
• [CURRENT] is the most recent version of the library that the library supports.
• [REVISION] is the implementation number of the current interface (i.e: patch releases)
• [AGE] is the number of versions back that this version is still backwards compatible with.

• acconfig.h is used to generate config.h.in, which is the file used to generate config.h.
• It should contain all the macro definitions needed to control the program.
• In it, a line of #undef MYMACRO specifies that the macro should not be defined by default. If it was defined during the run of the ./configure script, it would replace it as such.
• A line containing #define MYMACRO specifies that the macro would always be defined, but its value may vary.
• The utility autoheader can help in creating an initial config.h.in file.

• 8.1. Creating a Sub-Directory with a Different Configuration
• 8.2. mylibrary-config program
• 8.3. Creating an RPM Spec

• To have a directory with its own separate configure script, first put it in the SUBDIRS variable of Makefile.am
• Then use the AC_CONFIG_SUBDIRS macro in configure.in to configure them as separate sub-directories.
• If a sub-directory inherits from the same subdirectory, then they will also be linked against all the shared libraries, which may not be desirable.

• To have a mylibrary-config script, you need to put it in AC_OUTPUT.
• configure would expect a mylibrary-config.in file to be present, so you'll need to write a template for it there.
• You can look at pre-existing packages such as Freecell Solver or GLib for reference.

• To generate an RPM Spec, include a template for the RPM as mypackage.spec.in in the main directory of the package.
• The template is identical to the spec except that the Version: field should contain @VERSION@ as its contents.
• Add mypackage.spec to AC_OUTPUT.
• And add both mypackage.spec and mypackage.spec.in to the EXTRA_DIST of Makefile.am.
• Now, invoking rpm -tb with the archive name as a parameter would build an RPM out of it.

Manuals

The Autoconf Manual

The Automake Manual

The Libtool Manual

GNU m4

Other Sources of Information

Autoconf, Automake and Libtool
Autobook - an online book about the GNU Autotools
An Autoconf Tutorial
Autotut - an Autotools tutorial

Autoconf Macros Archive

Contains a lot of predefined macros which are free for use.