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

[Jim Meyering]

Ralf Wildenhues wrote:
...
> address@hidden Debugging
> address@hidden Debugging @command{configure} scripts

Nice tips!
I've proposed an addition to one of your lists
and made a few very subjective style suggestions:

> +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,

s/wrong/faulty or erroneous/

> +especially during macro development.  Failures can occur on all levels,

s/on/at/

> +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

s/which/that/

> +produce when their input has syntax errors, this can make debugging

s/has/contains/

> +rather painful.
> +
...
> address@hidden
> +When @command{configure} tests produce wrong or insufficient results for

How about s/wrong or insufficient/invalid/ ?

> +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

Imho this reads better:
s/allow to/let you/

> +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

s/allows to/lets you/

> 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:

One more tip:

  Do not require users of your macro to use the cache variables.
  Instead, expose the result of the test via RUN-IF-TRUE and RUN-IF-FALSE
  parameters.

> 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