Re: user upgrade path for renamed macros

[Filippo Giunchedi]

On Mon, Aug 10, 2009 at 07:39:58PM +0200, Peter Simons wrote:
> Hi Filippo,
> 
>  > Since aclocal prefers files with serial we can set a serial 0 on old
>  > files with renamed macros thus aclocal --diff|--install will pick them.
>  > Note that these files are bound to be removed anyway from the archive so
>  > having them serialized should do no harm beside making the user aware of
>  > replacements.
> 
> first of all, thank you for taking the time to investigate this approach. My
> understanding of the way those serial numbers are handled is very limited,
> so please bear with me if I don't get everything right away.
> 
> In my perception, the problem we're trying to solve is this one: a macro
> AC_FOO_BAR has been renamed to AX_FOO_BAR, and now we'd like users of
> AC_FOO_BAR to notice that this change has occurred so that they can update
> their configure.ac script. I don't quite see, though, how serial lines would
> play into this. I assumed that aclocal would treat those two macros as
> distinct (because they have different names)? You said aclocal "prefers"
> files with a serial line. What exactly does that mean in our context?

perhaps my scenario wasn't completely clear, I'm referring to the situation of a
user having a project shipping a m4/ directory with macros inside (from
aa[1] also). (which IIRC is the recommended practice nowadays[2])

glossary:
old file: our file AC_DEFUNing the macro under the oldname, containing also the
"renamed into: newname" and AU_ALIAS([oldname], [newname])
new file: our file defining the macro under the new name

When the user uses a new version of aa most probably it is included in search
path via -I switch or it is already in /usr/share/aclocal (as done in debian for
example).
At this point aclocal --install/--diff won't pick up the old file because the
user already has a file defining such macro (cfr. aclocal --verbose) and in turn
not noticing the macro renaming.
However, if old file has a serial aclocal _will_ pick it up because the user's
file doesn't have a serial, thus old file will show up in aclocal --diff.

This hack might be also used for macros changing name and API, explaining
everything inside comments of old file.

This would (I hope) solve at least the user noticing the renaming, AU_ALIAS is a
related but orthogonal issue:

>  > In addition to the serial provide also a AU_ALIAS([old_name],[new_name])
>  > for autoupdate to pick up (not strictly necessary but read on)
> 
> Yes, that makes perfect sense. The obsolete macros should feature an
> AU_ALIAS call that points users to the new macro name. From the looks of it,
> it shouldn't be too hard to add an appropriate line to all obsolete macros
> in the repository. We could probably use sed(1) to serach-and-replace the
> corresponding calls to AC_DEFUN.

AFAICT AU_ALIAS call should be in addition to AC_DEFUN, read on:

On Mon, Aug 10, 2009 at 08:13:58PM +0100, Reuben Thomas wrote:
> > If you're interested in making that change (or rather, in writing a script
> > that automates those that changes), I'd be delighted.
> 
> I am unclear after reading the docs precisely how AU_ALIAS should be
> used, or where. If you can enlighten me I'll happily do this.

>From what I can understand and tried AU_ALIAS([oldname],[newname]) replaces
calls to oldname with newname into configure.ac when autoupdate is called.

A nice side effect of this is that then aclocal --install will be willing to
install new file, IOW that's what should happen:

$ aclocal -I m4 -I latest_aa --install
# old file is copied into m4 (including AU_ALIAS([oldname],[newname])
$ autoupdate
# calls to oldname are replaced by newname
$ aclocal -I m4 -I latest_aa --install
# new file is copied into m4, epic win

This of course has at least two drawbacks:
- calls inside user macros in m4/ are not replaced (marginally a problem, old
  macro files are still there)
- old macro files are not removed (marginally a problem as this would break the
  previous point)

hope that helps clarifying,
filippo

[1]: we should really really have a shortcut for referring to the project, it is
tedious to write autoconf-archive all the time, I'll use aa for this mail :)
[2]: if the user is not using m4/ dir then the same applies more or less
-- 
Filippo Giunchedi - http://esaurito.net - 0x6B79D401

Caelum, non animo mutant, qui trans mare currunt
Who crosses the sea changes the sky, not the soul.
-- Oratius