documenting config.status instantiation order (was: AC_CONFIG_LINKS([sub/file:file]) with abs srcdir creates a bad link)

[Ralf Wildenhues]

[ dropping bug-autoconf ]

Hello,

* Peter Breitenlohner wrote on Wed, Dec 23, 2009 at 12:31:08PM CET:
> On Tue, 22 Dec 2009, Ralf Wildenhues wrote:
> 
> >Thanks.  I've reworked your test case into a couple of testsuite
> >additions.  Below is what I have now.  Unless I hear complaints,
> >I will commit it soonish.

I have committed it now, but without the change to the manual.

> >>Finally, the manual states that AC_CONFIG_LINKS creates (sym)links from the
> >>source tree to the build tree.  ...
> 
> Writing this, I had misinterpreted the description of AC_CONFIG_LINKS in
> section 4.11 of the manual to say that SOURCE must be in the source
> tree. My mistake.

Well, is there text that encourages this interpretation?  If yes then it
should be fixed.

> >>....  That sentence might need to be revised.
> >
> >Do you mean a change like in the patch below?
> 
> Not quite. IMHO the addition makes it even less clear. I'd like to say
> something like:
> 
> @noindent
> creates in the current directory @file{host.h} and @file{object.h} as links
> to @file{config/$machine.h} and @file{config/$obj_format.h} if such files
> exist, or @address@hidden/config/$machine.h} and
> @address@hidden/config/$obj_format.h} otherwise.  The file
> @file{config/$machine.h} must exist when @var{srcdir} is @samp{.} or could
> previously have been created in the build tree, e.g., through
> @code{AC_CONFIG_FILES}.

That is quite long-winded, and I don't think it make matters all that
much clearer.  However, your related questions maybe point to a better
way to address the issue:

> A somewhat related issue: the description of AC_OUTPUT in section 4.5 states
> that "`config.status' performs all the configuration actions" including
> subdirectories to configure.  There are three points where this description
> could be corrected/improved.
> 
> (1) It might be useful to state explicitly that config.status (as invoked by
> configure) does this in the indicated order: first files, then headers, and
> finally links.
> 
> (2) config.status does not descend into subdirectories, this is done at the
> end of configure.
> 
> (3) any code afterwards (after `AC_OUTPUT') "is executed by `configure' once
> `config.status' was run", but before configuring any subdirectories.
> 
> We use this last fact in TeX Live cross compilations to configure a 
> subdirectory
> natively, i.e., for the build system.

This is an interesting question, and ultimately about both fixing and
documenting more of the config.status API.  For the following, I'll
ignore the fact that makefile rebuilding rules can easily cause more
than one config.status invocation (with one or more arguments) to run in
parallel.

The current semantics are as follows: config.status instantiates any
arguments in the $CONFIG_{FILES,...} variables, defaulting to the
arguments on the command line, defaulting to all listed in configure.ac,

a) first all files, then headers, then links, then commands,
b) sequentially,
c) working on each sub group in the order they were passed on the command
   line.

d) since the subdir/configure invocations are done by configure, they
   happen after config.status has finished (unless --no-recursive).

It is quite conceivable that a future config.status could create several
files or headers in parallel; in fact, that would probably be fairly
straight-forward to implement for well-behaved shells; and for packages
with many config files it would seem desirable.

My view would be to fix and document (a) and (d) but not (b) nor (c),
and we should probably mention that rebuilding rules can recreate files
in arbitrary order (i.e., the rebuilding rules need to take care of
order through dependencies etc).

In any case, whatever part of the API we document, we should also expose
it in the testsuite.

Comments?

Thanks,
Ralf