Documenting _AS_PREPARE [was: [PATCH] more cleanup before adding shell functions]

[Eric Blake]

Paolo Bonzini <bonzini <at> gnu.org> writes:

> Definitely.  Only whoever needs _AS_PREPARE would need AS_PREPARE, the
> others should just expect AS_REQUIRE to work.
> 
> Also, the following renames should be done:
> 
> - AS_SHELL_SANITIZE => _AS_SHELL_SANITIZE

Hmm.  This one's already documented, and libtool.m4 already uses it, so we 
really shouldn't be changing it (even making AS_SHELL_SANITIZE an m4_defun_once 
would be wrong).  On the other hand, libtool.m4 is also using the undocumented 
_AS_PREPARE in the very next line; so we technically could be mean and change 
the semantics of AS_SHELL_SANITIZE on the grounds that it was only useful if 
you violated the rule of sticking to public API, and rub it in to clients that 
have failed to write bug reports against our deficient public API (not that I 
want to be that mean).  At this point, I think the best action is to just 
deprecate AS_SHELL_SANITIZE, and mention that it outputs initialization code 
every time it is expanded (which is typically either redundant since AS_INIT 
already implicitly does this for the primary script, or incomplete since 
secondary scripts cannot use full m4sh features without also expanding 
_AS_PREPARE).

> 
> - _AS_SHELL_SANITIZE+_AS_PREPARE => AS_INIT_GENERATED or something like that

I like the idea.  This will benefit libtool, too (if you can't tell, I'm a fan 
of getting libtool to the point where it only uses publicly documented 
interfaces, even if it takes some shims to allow interoperability with older 
autoconf versions).

> 
> - furthermore, AS_INIT_GENERATED should assert that AS_PREPARE has been
> called.

Why?  AS_INIT_GENERATED guarantees that the child script will have all m4sh 
features initialized (no optimizations of omitted initialization, because the 
init code is produced by shell code rather than on demand by m4 macros).  But 
AS_PREPARE only affects the primary script, and the generated child script 
should not behave any differently based on whether or not the primary script 
used $as_me (or any of the other _PREPARE features).  In other words, the only 
time that I can see where AS_PREPARE is useful is in the primary script, and 
then, only if you can't guarantee that AS_REQUIRE was used properly.  Put 
another way, autoconf.as should _not_ use AS_PREPARE (the entire script is 
under our control), while configure scripts must _always_ use AS_PREPARE (we 
can't guarantee that user.m4 included in configure.ac properly required all the 
features it used; in fact, we have already proven that libtool.m4 uses $as_me 
without _AS_ME_PREPARE).

> 
> Agreed.  Yet another cleanup to do before introducing shell functions?
> I'm passing the ball.  

The AS_INIT_GENERATED can be committed either before or after shell functions; 
I don't have a preference.  Do you want me to write that one?  On the other 
hand, I'd like to nail down the desired AS_BASENAME interface before spending 
time turning it into functions, only to have to change it yet again.  And yes, 
I guess that means I'm volunteering to do the proper implementation of 
AS_BASENAME.

-- 
Eric Blake