autoconf: Debugging

1 
1 20.9 Debugging `configure' scripts
1 ==================================
1 
1 While in general, `configure' scripts generated by Autoconf strive to
1 be fairly portable to various systems, compilers, shells, and other
1 tools, it may still be necessary to debug a failing test, broken script
1 or makefile, or fix or override an incomplete, faulty, or erroneous
1 test, especially during macro development.  Failures can occur at all
1 levels, in M4 syntax or semantics, shell script issues, or due to bugs
1 in the test or the tools invoked by `configure'.  Together with the
1 rather arcane error message that `m4' and `make' may produce when their
1 input contains syntax errors, this can make debugging rather painful.
1 
1    Nevertheless, here is a list of hints and strategies that may help:
1 
1    * When `autoconf' fails, common causes for error include:
1 
11         * mismatched or unbalanced parentheses or braces (⇒
           Balancing Parentheses),
1 
DONTPRINTYET 11         * under- or overquoted macro arguments (⇒Autoconf
           Language, ⇒Quoting and Parameters, *noteQuotation
1DONTPRINTYET 11         * under- or overquoted macro arguments (⇒Autoconf
           Language, ⇒Quoting and Parameters, ⇒Quotation

           and Nested Macros),
1 
11         * spaces between macro name and opening parenthesis (⇒
           Autoconf Language).
1 
1      Typically, it helps to go back to the last working version of the
1      input and compare the differences for each of these errors.
1      Another possibility is to sprinkle pairs of `m4_traceon' and
1      `m4_traceoff' judiciously in the code, either without a parameter
1      or listing some macro names and watch `m4' expand its input
1      verbosely (⇒Debugging via autom4te).
1 
1    * Sometimes `autoconf' succeeds but the generated `configure' script
1      has invalid shell syntax.  You can detect this case by running
1      `bash -n configure' or `sh -n configure'.  If this command fails,
1      the same tips apply, as if `autoconf' had failed.
1 
1    * Debugging `configure' script execution may be done by sprinkling
1      pairs of `set -x' and `set +x' into the shell script before and
1      after the region that contains a bug.  Running the whole script
1      with `SHELL -vx ./configure 2>&1 | tee LOG-FILE' with a decent
1      SHELL may work, but produces lots of output.  Here, it can help to
1      search for markers like `checking for' a particular test in the
1      LOG-FILE.
1 
1    * Alternatively, you might use a shell with debugging capabilities
1      like bashdb (http://bashdb.sourceforge.net/).
1 
1    * When `configure' tests produce invalid results for your system, it
1      may be necessary to override them:
1 
1         * For programs, tools or libraries variables, preprocessor,
1           compiler, or linker flags, it is often sufficient to override
11           them at `make' run time with some care (⇒Macros and
           Submakes).  Since this normally won't cause `configure' to
1           be run again with these changed settings, it may fail if the
1           changed variable would have caused different test results
1           from `configure', so this may work only for simple
1           differences.
1 
1         * Most tests which produce their result in a substituted
1           variable allow to override the test by setting the variable
DONTPRINTYET 11           on the `configure' command line (⇒Compilers and
           Options, ⇒Defining Variables, *noteParticular
1DONTPRINTYET 11           on the `configure' command line (⇒Compilers and
           Options, ⇒Defining Variables, ⇒Particular

           Systems).
1 
11         * Many tests store their result in a cache variable (⇒
           Caching Results).  This lets you override them either on the
1           `configure' command line as above, or through a primed cache
1           or site file (⇒Cache Files, ⇒Site Defaults).
1           The name of a cache variable is documented with a test macro
1           or may be inferred from ⇒Cache Variable Names; the
1           precise semantics of undocumented variables are often
1           internal details, subject to change.
1 
1    * Alternatively, `configure' may produce invalid results because of
1      uncaught programming errors, in your package or in an upstream
1      library package.  For example, when `AC_CHECK_LIB' fails to find a
1      library with a specified function, always check `config.log'.  This
1      will reveal the exact error that produced the failing result: the
1      library linked by `AC_CHECK_LIB' probably has a fatal bug.
1 
1    Conversely, as macro author, you can make it easier for users of your
1 macro:
1 
1    * by minimizing dependencies between tests and between test results
1      as far as possible,
1 
1    * by using `make' variables to factorize and allow override of
1      settings at `make' run time,
1 
1    * by honoring the GNU Coding Standards and not overriding flags
1      reserved for the user except temporarily during `configure' tests,
1 
1    * by not requiring users of your macro to use the cache variables.
1      Instead, expose the result of the test via RUN-IF-TRUE and
1      RUN-IF-FALSE parameters.  If the result is not a boolean, then
1      provide it through documented shell variables.
1