Re: document how to override test results

[Ralf Wildenhues]

Hello Bruno,

* Bruno Haible wrote on Tue, Sep 01, 2009 at 10:46:41PM CEST:
> Ralf Wildenhues wrote:
> > the user
> > will prefer the simplest and fastest way to get over a build failure.
> 
> So, please document the possible ways of getting over a build failure.
> Currently, the manual is silent about this.

I understand that you would like the process to be formalized; and I
agree with you that formalizing it where it is possible and not
detrimental may be useful.  However, to some extent debugging will
always remain an area that requires some experimentation, and also
allows (and sometimes requires) looking under the hood: when debugging,
internal details are fair game, and nothing is forbidden, no full
portability is needed, only whatever necessary to build the package at
hand, or similar task.

That said, let's see how we can improve the documentation here.

> > I think it would be better if Automake stated plainly:
> > 
> >    Prefer using $(variable) over @address@hidden  That enables the user
> >    to override the setting of the variable at `make' run time.
> > 
> > I thought the manual already said this, but I can't find it right now.
> 
> This is only a partial answer to the problem. It helps only if one of
> the AC_PROG_*, AC_CHECK_PROG*, AC_CHECK_TOOL* macros guessed wrong.

Sure.  But often, package authors also know of other potential trouble
spots.  As a practical example I happened to run over, cross compilation
of packages that also use generator programs (i.e., code written for the
$build compiler, not the $host compiler), as a very first preliminary
step for good cross compilation support you can often get away with
putting this in your Makefile.am:
  CC_FOR_BUILD = $(CC)
  CFLAGS_FOR_BUILD = $(CFLAGS)
  FOOLIB_FOR_BUILD = $(FOOLIB)

  generator:
        $(CC_FOR_BUILD) ...

That way, the package works for a native setup, and fails for a cross
setup, but one can easily override CC_FOR_BUILD and FOOLIB_FOR_BUILD
at 'make' time , and proceed from there (those of your users that cross
compile typically aren't afraid to use such workarounds to proceed,
either); you can then take your time to set up a properly
cross-compilable package.

> What if the user wants to override the results of the following
> autoconf tests?
>   - AC_CHECK_TYPES([uid_t])
>   - AC_CHECK_LIB([nsl], [gethostname])
>   - AC_FUNC_GETGROUPS
>   - AC_FUNC_MKTIME
>   - AC_CHECK_FUNC([foo])
>   - AC_REPLACE_FUNCS([foo])
>   - AC_CHECK_HEADER([stdbool.h])
>   - AC_CHECK_DECL([errno],,,[#include <errno.h>])
>   - AC_CHECK_MEMBER([struct stat.st_blksize])
>   - AC_SYS_LARGEFILE
>   - AC_CANONICAL_HOST
> 
> Currently only a few autoconf wizards know how to do it. The doc does
> not say it.

It is true that the docs do not say it.  However, configure is still a
shell script, and while granted that they are pretty complex, it is not
impossible to find out how things work or how variables are named, even
if they are not defined.  Debuggability was one of the main reasons to
use a scripting language IIRC.  Maybe we have departed too far from that
today, I don't know.

Anyway, it may be a good idea to go through the list of tests, both
particular and generic ones, and consider documenting the cache
variables and their semantics where feasible.  I'll reply with a patch
series to start the ball on this, on autoconf-patches.

Documenting cache variables (names and semantics) of course make changes
to them interface changes.  While this has been a problem in practice on
several occasions already anyway, we'd definitely now need to treat them
as such: keep them at the minimum amount, list changes in NEWS etc.

Thanks,
Ralf