[PATCH 2/5] New FAQ node: Debugging.

[Ralf Wildenhues]

* doc/autoconf.texi (Debugging): New node.
(Top, FAQ): Adjust menus.
Report by Bruno Haible.
---
 doc/autoconf.texi |  105 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 105 insertions(+), 0 deletions(-)

diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 5a425d7..1244ef3 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -621,6 +621,7 @@ Top
 * 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
 
@@ -23326,6 +23327,7 @@ FAQ
 * 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
@@ -23851,6 +23853,109 @@ Expanded Before Required
 @end example
 
 
address@hidden Debugging
address@hidden 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 or wrong test,
+especially during macro development.  Failures can occur on 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 which @command{m4} and @command{make} may
+produce when their input has syntax errors, this can make debugging
+rather painful.
+
+Nevertheless, here is a list of hints and strategies that may help:
+
address@hidden
address@hidden
+When @command{autoconf} fails, common causes for error include:
+
address@hidden
address@hidden
+mismatched or unbalanced parentheses or braces (@pxref{Balancing
+Parentheses}),
+
address@hidden under- or overquoted macro arguments (@pxref{Autoconf
+Language}, @pxref{Quoting and Parameters}, @pxref{Quotation and Nested
+Macros}),
+
address@hidden spaces between macro name and opening parenthesis 
(@pxref{Autoconf
+Language}).
address@hidden 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
address@hidden 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}).
+
address@hidden
+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
address@hidden@var{shell} ./configure -vx 2>&1 | tee @var{log-file}} with a 
decent
address@hidden may work, but produces lots of output.  Here, it can help to
+search for markers like @samp{checking for} a particular test in the
address@hidden
+
address@hidden
+When @command{configure} tests produce wrong or insufficient results for
+your system, it may be necessary to override them:
+
address@hidden
address@hidden
+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.  Erroneous test results that only define macros
+in a @file{config.h} header file may be worked around by editing said
+header file and rebuilding; be sure to have dependency tracking enabled
+or run @code{make clean} beforehand, so that objects are recompiled
+appropriately.
+
address@hidden
+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},
address@hidden Systems}).
+
address@hidden
+Many tests store their result in a cache variable (@pxref{Caching
+Results}).  This allows to override them either on the
address@hidden 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
address@hidden Variable Names}; the precise semantics of undocumented
+variables are often internal details, subject to change.
address@hidden itemize
address@hidden itemize
+
+Conversely, as macro author, you can make it easier for users of your
+macro:
+
address@hidden
address@hidden
+by minimizing dependencies between tests and between test results as far
+as possible,
+
address@hidden
+by using @command{make} variables to factorize and allow
+override of settings at @command{make} run time,
+
address@hidden
+by honoring the @acronym{GNU} Coding Standards and not overriding flags
+reserved for the user except temporarily during @command{configure}
+tests.
address@hidden itemize
+
+
 @c ===================================================== History of Autoconf.
 
 @node History
-- 
1.6.3.2.388.gb7132