Autoconf, Automake, and Libtool: Installing Header Files

> | ## 12.3 Installing Header Files One of the more difficult problems with GNU Autotools driven projects is that each of them depends on ``config.h'` (or its equivalent) and the project specific symbols that it defines. The purpose of this file is to be `#include`d from all of the project source files. The preprocessor can tailor then the code in these files to the target environment. It is often difficult and sometimes impossible to not introduce a dependency on ``config.h'` from one of the project's installable header files. It would be nice if you could simply install the generated ``config.h'`, but even if you name it carefully or install it to a subdirectory to avoid filename problems, the macros it defines will clash with those from any other GNU Autotools based project which also installs its ``config.h'`. For example, if Sic installed its ``config.h'` as ``/usr/include/sic/config.h'`, and had ``#include <sic/config.h>'` in the installed ``common.h'`, when another GNU Autotools based project came to use the Sic library it might begin like this:
>     #if HAVE_CONFIG_H
>     #  include <config.h>
>     #endif

>     #if HAVE_SIC_H
>     #  include <sic.h>
>     #endif

>     static const char version_number[] = VERSION;
But, ``sic.h'` says ``#include <sic/common.h>'`, which in turn says ``#include <sic/config.h>'`. Even though the other project has the correct value for ``VERSION'` in its own ``config.h'`, by the time the preprocessor reaches the ``version_number'` definition, it has been redefined to the value in ``sic/config.h'`. Imagine the mess you could get into if you were using several libraries which each installed their own ``config.h'` definitions. GCC issues a warning when a macro is redefined to a different value which would help you to catch this error. Some compilers do not issue a warning, and perhaps worse, other compilers will warn even if the repeated definitions have the same value, flooding you with hundreds of warnings for each source file that reads multiple ``config.h'` headers. The Autoconf macro `AC_OUTPUT_COMMANDS`(25) provides a way to solve this problem. The idea is to generate a system specific but installable header from the results of the various tests performed by `configure`. There is a 1-to-1 mapping between the preprocessor code that relied on the configure results written to ``config.h'`, and the new shell code that relies on the configure results saved in ``config.cache'`. The following code is a snippet from ``configure.in'`, in the body of the `AC_OUTPUT_COMMANDS` macro:
        # Add the code to include these headers only if autoconf has
        # shown them to be present.
        if test x$ac_cv_header_stdlib_h = xyes; then
          echo '#include <stdlib.h>' >> $tmpfile
        fi
        if test x$ac_cv_header_unistd_h = xyes; then
          echo '#include <unistd.h>' >> $tmpfile
        fi
        if test x$ac_cv_header_sys_wait_h = xyes; then
          echo '#include <sys/wait.h>' >> $tmpfile
        fi
        if test x$ac_cv_header_errno_h = xyes; then
          echo '#include <errno.h>' >> $tmpfile
        fi
        cat >> $tmpfile << '_EOF_'
    #ifndef errno
    /* Some sytems #define this! */
    extern int errno;
    #endif
    _EOF_
        if test x$ac_cv_header_string_h = xyes; then
          echo '#include <string.h>' >> $tmpfile
        elif test x$ac_cv_header_strings_h = xyes; then
          echo '#include <strings.h>' >> $tmpfile
        fi
        if test x$ac_cv_header_assert_h = xyes; then
          cat >> $tmpfile << '_EOF_'

    #include <assert.h>
    #define SIC_ASSERT assert

    _EOF_
        else
            echo '#define SIC_ASSERT(expr)  ((void) 0)' >> $tmpfile
        fi
Compare this with the equivalent C pre-processor code from ``sic/common.h'`, which it replaces:
    #if STDC_HEADERS || HAVE_STDLIB_H
    #  include <stdlib.h>
    #endif

    #if HAVE_UNISTD_H
    #  include <unistd.h>
    #endif

    #if HAVE_SYS_WAIT_H
    #  include <sys/wait.h>
    #endif

    #if HAVE_ERRNO_H
    #  include <errno.h>
    #endif
    #ifndef errno
    /* Some systems #define this! */
    extern int errno;
    #endif

    #if HAVE_STRING_H
    #  include <string.h>
    #else
    #  if HAVE_STRING_H
    #    include <strings.h>
    #  endif
    #endif

    #if HAVE_ASSERT_H
    #  include <assert.h>
    #  define SIC_ASSERT assert
    #else
    #  define SIC_ASSERT(expr) ((void) 0)
    #endif
Apart from the mechanical process of translating the preprocessor code, there is some plumbing needed to ensure that the ``common.h'` file generated by the new code in ``configure.in'` is functionally equivalent to the old code, and is generated in a correct and timely fashion. Taking my lead from some of the Automake generated `make` rules to regenerate ``Makefile'` from ``Makefile.in'` by calling ``config.status'`, I have added some similar rules to ``sic/Makefile.am'` to regenerate ``common.h'` from ``common-h.in'`.
    # Regenerate common.h with config.status whenever common-h.in changes.
    common.h: stamp-common
            @:
    stamp-common: $(srcdir)/common-h.in $(top_builddir)/config.status
            cd $(top_builddir) \
              && CONFIG_FILES= CONFIG_HEADERS= CONFIG_OTHER=sic/common.h \
              $(SHELL) ./config.status
            echo timestamp > $@
The way that `AC_OUTPUT_COMMANDS` works, is to copy the contained code into `config.status` (see section C. Generated File Dependencies). It is actually `config.status` that creates the generated files -- for example, `automake` generated ``Makefile'`s are able to regenerate themselves from corresponding ``Makefile.in'`s by calling `config.status` if they become out of date. Unfortunately, this means that `config.status` doesn't have direct access to the cache values generated while `configure` was running (because it has finished its work by the time `config.status` is called). It is tempting to read in the cache file at the top of the code inside `AC_OUTPUT_COMMANDS`, but that only works if you know where the cache file is saved. Also the package installer can use the ``--cache-file'` option of `configure` to change the location of the file, or turn off caching entirely with ``--cache-file=/dev/null'`. `AC_OUTPUT_COMMANDS` accepts a second argument which can be used to pass the variable settings discovered by `configure` into `config.status`. It's not pretty, and is a little error prone. In the first argument to `AC_OUTPUT_COMMANDS`, you must be careful to check that every single configure variable referenced is correctly set somewhere in the second argument. A slightly stripped down example from the sic project ``configure.in'` looks like this:
    # ----------------------------------------------------------------------
    # Add code to config.status to create an installable host dependent
    # configuration file.
    # ----------------------------------------------------------------------
    AC_OUTPUT_COMMANDS([
      if test -n "$CONFIG_FILES" && test -n "$CONFIG_HEADERS"; then
        # If both these vars are non-empty, then config.status wasn't run by
        # automake rules (which always set one or the other to empty).
        CONFIG_OTHER=${CONFIG_OTHER-sic/common.h}
      fi
      case "$CONFIG_OTHER" in
      *sic/common.h*)
        outfile=sic/common.h
        stampfile=sic/stamp-common
        tmpfile=${outfile}T
        dirname="sed s,^.*/,,g"

        echo creating $outfile
        cat > $tmpfile << _EOF_
    /*  -*- Mode: C -*-
     * --------------------------------------------------------------------
     * DO NOT EDIT THIS FILE!  It has been automatically generated
     * from:    configure.in and `echo $outfile|$dirname`.in
     * on host: `(hostname || uname -n) 2>/dev/null | sed 1q`
     * --------------------------------------------------------------------
     */

    #ifndef SIC_COMMON_H
    #define SIC_COMMON_H 1

    #include <stdio.h>
    #include <sys/types.h>
    _EOF_

        if test x$ac_cv_func_bzero = xno && \
           test x$ac_cv_func_memset = xyes; then
          cat >> $tmpfile << '_EOF_'
    #define bzero(buf, bytes) ((void) memset (buf, 0, bytes))
    _EOF_
        fi
        if test x$ac_cv_func_strchr = xno; then
          echo '#define strchr index' >> $tmpfile
        fi
        if test x$ac_cv_func_strrchr = xno; then
          echo '#define strrchr rindex' >> $tmpfile
        fi

        # The ugly but portable cpp stuff comes from here
        infile=$srcdir/sic/`echo $outfile | sed 's,.*/,,g;s,\..*$,,g'`-h.in
        sed '/^##.*$/d' $infile >> $tmpfile

    ],[
      srcdir=$srcdir
      ac_cv_func_bzero=$ac_cv_func_bzero
      ac_cv_func_memset=$ac_cv_func_memset
      ac_cv_func_strchr=$ac_cv_func_strchr
      ac_cv_func_strrchr=$ac_cv_func_strrchr
    ])
You will notice that the contents of ``common-h.in'` are copied into ``common.h'` verbatim as it is generated. It's just an easy way of collecting together the code that belongs in ``common.h'`, but which doesn't rely on configuration tests, without cluttering ``configure.in'` any more than necessary. I should point out that, although this method has served me well for a number of years now, it is inherently fragile because it relies on undocumented internals of both Autoconf and Automake. There is a very real possibility that if you also track the latest releases of GNU Autotools, it may stop working. Future releases of GNU Autotools will address the interface problems that force us to use code like this, for the lack of a better way to do things.

This document was generated by Gary V. Vaughan on February, 8 2006 using texi2html