New FAQ node: Debugging.

* doc/autoconf.texi (Debugging): New node.
(Top, FAQ): Adjust menus.
Report by Bruno Haible.

Signed-off-by: Ralf Wildenhues <Ralf.Wildenhues@gmx.de>

diff --git a/ChangeLog b/ChangeLog
index 4e58536ac3bff28f495e004fa5c567a826eed368..d534115c9c59c708e3654cd2387fcfff65fb030f 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,10 @@
 2009-09-18  Ralf Wildenhues  <Ralf.Wildenhues@gmx.de>
 
+       New FAQ node: Debugging.
+       * doc/autoconf.texi (Debugging): New node.
+       (Top, FAQ): Adjust menus.
+       Report by Bruno Haible.
+
        Document AM_MAKEFLAGS workaround to the macro override problem.
        * doc/autoconf.texi (Macros and Submakes): Automake makefiles
        provide AM_MAKEFLAGS to help with overriding macros in submake

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index e5ecb6f98342e8a1b53b1a8a1e07c4012d2a072e..f3c5ef2e57e1070fb6b09cbe855a789aea271151 100644 (file)
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -622,6 +622,7 @@ Frequent Autoconf Questions, with answers
 * Autom4te Cache::              What is it?  Can I remove it?
 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
 * Expanded Before Required::    Expanded Before Required
+* Debugging::                   Debugging @command{configure} scripts
 
 History of Autoconf
 
@@ -23392,6 +23393,7 @@ are addressed.
 * Autom4te Cache::              What is it?  Can I remove it?
 * Present But Cannot Be Compiled::  Compiler and Preprocessor Disagree
 * Expanded Before Required::    Expanded Before Required
+* Debugging::                   Debugging @command{configure} scripts
 @end menu
 
 @node Distributing
@@ -23917,6 +23919,110 @@ BAR
 @end example
 
 
+@node Debugging
+@section Debugging @command{configure} scripts
+
+While in general, @command{configure} scripts generated by Autoconf
+strive to be fairly portable to various systems, compilers, shells, and
+other tools, it may still be necessary to debug a failing test, broken
+script or makefile, or fix or override an incomplete, faulty, or erroneous
+test, especially during macro development.  Failures can occur at all levels,
+in M4 syntax or semantics, shell script issues, or due to bugs in the
+test or the tools invoked by @command{configure}.  Together with the
+rather arcane error message that @command{m4} and @command{make} may
+produce when their input contains syntax errors, this can make debugging
+rather painful.
+
+Nevertheless, here is a list of hints and strategies that may help:
+
+@itemize
+@item
+When @command{autoconf} fails, common causes for error include:
+
+@itemize
+@item
+mismatched or unbalanced parentheses or braces (@pxref{Balancing
+Parentheses}),
+
+@item under- or overquoted macro arguments (@pxref{Autoconf
+Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested
+Macros}),
+
+@item spaces between macro name and opening parenthesis (@pxref{Autoconf
+Language}).
+@end itemize
+
+Typically, it helps to go back to the last working version of the input
+and compare the differences for each of these errors.  Another
+possibility is to sprinkle pairs of @code{m4_traceon} and
+@code{m4_traceoff} judiciously in the code, either without a parameter
+or listing some macro names and watch @command{m4} expand its input
+verbosely (@pxref{Debugging via autom4te}).
+
+@item
+Debugging @command{configure} script execution may be done by sprinkling
+pairs of @code{set -x} and @code{set +x} into the shell script before
+and after the region that contains a bug.  Running the whole script with
+@samp{@var{shell} ./configure -vx 2>&1 | tee @var{log-file}} with a decent
+@var{shell} may work, but produces lots of output.  Here, it can help to
+search for markers like @samp{checking for} a particular test in the
+@var{log-file}.
+
+@item
+When @command{configure} tests produce invalid results for your system,
+it may be necessary to override them:
+
+@itemize
+@item
+For programs, tools or libraries variables, preprocessor, compiler, or
+linker flags, it is often sufficient to override them at @command{make}
+run time with some care (@pxref{Macros and Submakes}).  Since this
+normally won't cause @command{configure} to be run again with these
+changed settings, it may fail if the changed variable would have caused
+different test results from @command{configure}, so this may work only
+for simple differences.
+
+@item
+Most tests which produce their result in a substituted variable allow to
+override the test by setting the variable on the @command{configure}
+command line (@pxref{Compilers and Options}, @pxref{Defining Variables},
+@pxref{Particular Systems}).
+
+@item
+Many tests store their result in a cache variable (@pxref{Caching
+Results}).  This lets you override them either on the
+@command{configure} command line as above, or through a primed cache or
+site file (@pxref{Cache Files}, @pxref{Site Defaults}).  The name of a
+cache variable is documented with a test macro or may be inferred from
+@ref{Cache Variable Names}; the precise semantics of undocumented
+variables are often internal details, subject to change.
+@end itemize
+@end itemize
+
+Conversely, as macro author, you can make it easier for users of your
+macro:
+
+@itemize
+@item
+by minimizing dependencies between tests and between test results as far
+as possible,
+
+@item
+by using @command{make} variables to factorize and allow
+override of settings at @command{make} run time,
+
+@item
+by honoring the @acronym{GNU} Coding Standards and not overriding flags
+reserved for the user except temporarily during @command{configure}
+tests,
+
+@item
+by not requiring users of your macro to use the cache variables.
+Instead, expose the result of the test via @var{run-if-true} and
+@var{run-if-false} parameters.
+@end itemize
+
+
 @c ===================================================== History of Autoconf.
 
 @node History