Autoconf, Automake, and Libtool: Debugging with M4

| ### 21.5.2 Debugging with M4 After writing a new macro or a ``configure.in'` template, the generated ``configure'` script may not contain what you expect. Frequently this is due to a problem in quoting (see section 21.3.3 Quoting), but the interactions between macros can be complex. When you consider that the arguments to GNU Autotools macros are often shell scripts, things can get rather hairy. A number of techniques exist for helping you to debug these kinds of problems. Expansion problems due to over-quoting and under-quoting can be difficult to pinpoint. Autoconf half-heartedly tries to detect this condition by scanning the generated ``configure'` script for any remaining invocations of the `AC_` and `AM_` families of macros. However, this only works for the `AC_` and `AM_` macros and not for third party macros. M4 provides a comprehensive facility for tracing expansions. This makes it possible to see how macro arguments are expanded and how a macro is finally expanded. Often, this can be half the battle in discovering if the macro definition or the invocation is at fault. Autoconf 2.15 will include this tracing mechanism. To trace the generation of ``configure'`, Autoconf can be invoked like so:
    $ autoconf --trace=AC_PROG_CC
Autoconf provides fine control over which macros are traced and the format of the trace output. You should refer to the Autoconf manual for further details. GNU `m4` also provides a debugging mode that can be helpful in discovering problems such as infinite recursion. This mode is activated with the ``-d'` option. In order to pass options to `m4`, invoke Autoconf like so:
    $ M4='m4 -dV' autoconf
Another situation that can arise is the presence of shell syntax errors in the generated ``configure'` script. These errors are usually obvious, as the shell will abort ``configure'` when the syntax error is encountered. The task of then locating the troublesome shell code in the input files can be potentially quite difficult. If the erroneous shell code appears in ``configure.in'`, it should be easy to spot--presumably because you wrote it recently! If the code is imported from a third party macro, though, it may only be present because you invoked that macro. A trick to help locate these kinds of errors is to place some magic text (`__MAGIC__`) throughout ``configure.in'`:
    AC_INIT
    AC_PROG_CC
    __MAGIC__
    MY_SUSPECT_MACRO
    __MAGIC__
    AC_OUTPUT(Makefile)
After `autoconf` has generated ``configure'`, you can search through it for the magic text to determine the extremities of the suspect macro. If your erroneous code appears within the magic text markers, you've found the culprit! Don't be afraid to hack up ``configure'`. It can easily be regenerated. Finally, due to an error on your part, `m4` may generate a ``configure'` script that contains semantic errors. Something as simple as inverted logic may lead to a nonsense test result:
    checking for /etc/passwd... no
Semantic errors of this kind are usually easy to solve once you can spot them. A fast and simple way of tracing the shell execution is to use the shell's ``-x'` and ``-v'` options to turn on its own tracing. This can be done by explicitly placing the required `set` commands into ``configure.in'`:
    AC_INIT
    AC_PROG_CC
    set -x -v
    MY_BROKEN_MACRO
    set +x +v
    AC_OUTPUT(Makefile)
This kind of tracing is invaluable in debugging shell code containing semantic errors.

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