From: Ralf Wildenhues Date: Fri, 18 Sep 2009 05:15:18 +0000 (+0200) Subject: New FAQ node: Debugging. X-Git-Tag: v2.65~40 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3ab3c9b3570d0507ae0aaa590713cc088182c5c7;p=thirdparty%2Fautoconf.git New FAQ node: Debugging. * doc/autoconf.texi (Debugging): New node. (Top, FAQ): Adjust menus. Report by Bruno Haible. Signed-off-by: Ralf Wildenhues --- diff --git a/ChangeLog b/ChangeLog index 4e58536a..d534115c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,10 @@ 2009-09-18 Ralf Wildenhues + 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 e5ecb6f9..f3c5ef2e 100644 --- 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