* 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
+...@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 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:
+
+...@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 wrong or insufficient 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. 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.
+
+...@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 allows to 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.
+...@end itemize
+
+
@c ===================================================== History of Autoconf.
@node History
--
1.6.3.2.388.gb7132
