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