Re: Quick divert() 2.13/2.6x portability macro

[Eric Blake]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

According to Rasmus Lerdorf on 11/28/2009 6:42 AM:
> Basically the diversions are there to organize the phases of the checks.
>  From
> http://svn.php.net/viewvc/php/php-src/branches/PHP_5_3/configure.in?view=markup
> 
> ## Diversion 1 is the autoconf + automake setup phase. We also
> ## set the PHP version, deal with platform-specific compile
> ## options and check for the basic compile tools.

Autoconf itself now uses multiple diversions under the hood for setup, and
you cannot assume which diversion number is in use.  You can use named
diversions to ease the pain.  The named diversion BODY is (currently)
equivalent to 1000; that is the diversion that is used if you don't use
m4_divert at all.  But WHY do you need diversions in the first place?
Looking at the above link, EVERY one of the diversions occurs in textual
order, meaning there is NO rearranging of the output text.  So everything
you do will occur in the SAME order even if you don't play with raw
diversions (unless I'm missing some diverts that you are using in
secondary files being used with sinclude).

> 
> ## Diversion 2 is the initial checking of OS features, programs,
> ## libraries and so on.
> 
> ## In diversion 3 we check for compile-time options to the PHP
> ## core and how to deal with different system dependencies.
> ## This includes whether debugging or short tags are enabled
> ## and the default behaviour of php.ini options.
> ## This is also where a SAPI interface is selected (choosing between
> ## Apache module, CGI etc.)
> 
> ## In diversion 4 we check user-configurable general settings.
> 
> ## In diversion 5 we check which extensions should be compiled.
> ## All of these are normally in the extension directories.
> ## Diversion 5 is the last one.  Here we generate files and clean up.
> 
> I changed these from 1-5 to 1001-1005, but that breaks the build under
> 2.13 and even under 2.65 it messes up the output of configure --help

configure --help output is a special case where diversion magic is
necessary.  Using diversion BODY is too late.  But what's wrong with using
the documented AC_ARG_ENABLE and AC_ARG_WITH, which properly manage the
diversions on your behalf?  Under the hood, they are using
m4_divert_text([HELP_ENABLE], [text]) or m4_divert_text([HELP_WITH]) to
output text into the --help stream.  So technically, if you needed to use
these (intentionally undocumented) named diversions, you could likewise
impact the --help output.  Reading lib/autoconf/general.m4 to learn about
named diversions may be useful.  But again, what's wrong with the
documented interfaces, or what is a specific example of a particular
string that outputs in a different location in the --help output than
where you want?

> 
> I would love to get off of 2.13, but it would be easier to do if I had a
> migration phase where things worked in both.

Good luck with that.  2.13 is so old, that it may be easier to not try
this approach, and just bite the bullet and use the newer release.  Ask
the gcc folks how they did their conversion from 2.13 to 2.5x.

> As far as my little naiive attempt at replacing my divert() calls with a
> little macro that will use different diversions in 2.65 go, changing it
> to use m4_divert() didn't make a difference.  And I don't really
> understand how I messed up the diversion stack.

The diversion stack tracks which diversion you were in.  After AC_INIT,
the stack looks like:

KILL (aka -1)
BODY (aka 1000)

calling m4_divert(1001) is the equivalent of calling
m4_divert_pop()m4_divert_push(1001), leaving the stack at:

KILL
1001

But autoconf expects the stack to be on BODY when you exit.  Since 1001 is
not BODY, you have broken the stack behind autoconf's back.

> Why does that change the stack?  Shouldn't it still be pushing those
> diversions onto the stack in exactly the same order or is there some m4
> scoping thing going on?

You should consider using m4_divert_push/m4_divert_pop rather than
m4_divert; but if you must use m4_divert, then remember to change
m4_divert back to the diversion that was in use before you started
changing diversions behind autoconf's back.  Also, you may be interested
in m4_divert_text, which is a friendlier wrapper that automatically puts
text in the right diversion, then restores the diversion stack.

- --
Don't work too hard, make some time for fun as well!

Eric Blake             address@hidden
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.9 (Cygwin)
Comment: Public key at home.comcast.net/~ericblake/eblake.gpg
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAksRM3sACgkQ84KuGfSFAYC8VQCg1NePCMfjRRW0xu0NlM3pTiHI
AtcAoKTxXRCfk6HbOW7hkeyhwm7KKVy3
=yPZm
-----END PGP SIGNATURE-----