[bug-gnulib] uniform #serial number for M4 macros, and `aclocal --install'

[Alexandre Duret-Lutz]

Hi people,

Since yesterday the CVS version of aclocal can install
system-wide macros (and their dependencies) in your package, and
will honor #serial lines when upgrading local macros.

One problem is that many people have used different #serial
syntax, and that is would be hard (and IMHO unsane) for aclocal
to accept all of them.  Even gnulib is inconsistent
w.r.t. #serial lines, so I believe this is a good time to settle
a some syntax we can all use.

So I'll state the constraints of aclocal, then you'll add those
of gnulib or other packages you know, and we'll see if we can
reach something.

For background here is how the Automake manual currently
presents the `aclocal --install' feature.

| 5.4 aclocal options
| ===================
| 
[...]
| 
| `--install'
|      Install system-wide third-party macros into the first directory
|      specified with `-I DIR' instead of copying them in the output
|      file.
| 
|      When this option is used, `aclocal' will also honor `#serial
|      NUMBER' lines that appear in macros: an M4 file is ignored if
|      there exists another M4 file with the same basename and a greater
|      serial number in the search path.
| 
[...]
| 
| 5.8 Handling Local Macros
| =========================
| 
[...]
| 
|    However there is no consensus on the distribution of third-party
| macros that your package may use.  Many libraries install their own
| macro in the system-wide `aclocal' directory (*note Extending
| aclocal::).  For instance Guile ships with a file called `guile.m4'
| that contains the macro `GUILE_FLAGS' which can be used to define setup
| compiler and linker flags appropriate for using Guile.  Using
| `GUILE_FLAGS' in `configure.ac' will cause `aclocal' to copy `guile.m4'
| into `aclocal.m4', but as `guile.m4' is not part of the project, it
| will not be distributed.  Technically, that means a user which needs to
| rebuild `aclocal.m4' will have to install Guile first.  This is
| probably OK, if Guile already is a requirement to build the package.
| However, if Guile is only an optional feature, or if your package might
| run on architectures where Guile cannot be installed, this requirement
| will hinder development.  An easy solution is to copy such third-party
| macros in your local `m4/' directory so they get distributed.
| 
|    Since Automake 1.10, `aclocal' offers an option to copy these
| system-wide third-party macros in your local macro directory, solving
| the above problem.  Simply use:
| 
|       ACLOCAL_AMFLAGS = -I m4 --install
| 
| With this setup, system-wide macros will be copied to `m4/' the first
| time you run `autoreconf'.  Then the locally installed macros will have
| precedence over the system-wide installed macros each time `aclocal' is
| run again.
| 
|    One reason why you should keep `--install' in the flags even after
| the first run is that when you later edit `configure.ac' and depend on
| a new macro, this macro will be installed in your `m4/' automatically.
| Another one is that serial numbers can be used to update the macros in
| your source tree automatically when new system-wide versions are
| installed.  A serial number should be a single line of the form
| 
|      #serial NNN
| 
| where NNN contains only digits and dots.  It should appear in the M4
| file before any macro definition.  It is a good practice to maintain a
| serial number for each macro you distribute, even if you do not use the
| `--install' option of `aclocal': this allows other people to use it.
| 
[...]

That #serial syntax contains all the information aclocal needs,
i.e., a serial number and nothing more.

It allows version-like strings such as `1.2.3' because I saw CVS
libtool was using one, and I find it to be the only practical
way to handle branches and forks.

Another constraint is that since aclocal will parse the serial
number it must be able to tell users when it failed to grok the
line.  For instance it should not silently parse `# serial 1a'
and `# serial 1b' as the same serial (this is what the venerable
`acinstall' script does, ignoring any garbage after the digits).

Currently the procedure works as follows:

 1. Find the first line that matches '^#\s*serial\s*(.*?)\s*$'
 2. Try to match $1 against '^\d+(?:\.\d+)*$'

If #2 fails, aclocal presently emits a warning and ignores the
serial number.  For instance

libtool.m4:30: malformed serial number `49 LT_INIT', expecting only digits and 
dots

this is a warning similar to all those 'underquoted definition'
messages introduced in Automake 1.8, it doesn't prevent aclocal
from actually doing its job (except that the serial is ignored).


Yesterday, I didn't know why libtool.m4 was using LT_INIT on its
serial line, and it seemed pointless to me so I planned to
submit a patch to remove this extra tag.  However the libtool
folks reacted before I even start working on it, and Gary
explained it was so libtoolize could grep the serial number in
aclocal.m4.

I also saw that gnulib was using several #serial schemes:

1. #serial NNN
2. # serial NNN
3. # FILENAME serial NNN
4. # FILENAME serial NNN (PACKAGES) 
5. # FILENAME serial STRING (PACKAGES) 

None of these cause aclocal warnings, but the latter 3 schemes
will be ignored by aclocal.  At least in the current implementation.

Maybe the FILENAME part serves the same purpose as the `LT_INIT'
tag in the aforementioned libtool.m4 example, but I'm not sure
about this because I couldn't find any occurrence of `serial' in
gnulib-tool, gettextize, and autopoint.

I could not understand why some macros use a string `AM1',
`AM4', ... instead of a number and what this string stood for.

Can someone explains the purpose of these syntaxical elements in
serial line?  If they are useless, can we remove them (or move
them on another line)?

Otherwise, what syntax would you suggest aclocal use?

The current proposal to cope with libtool is to assume that the
serial number is the second word, and ignore anything past that.

# serial NNN ANYTHING

Thanks for any idea and suggestion.
-- 
Alexandre Duret-Lutz