serial number format

serial number format

[Sam James]

[-- Attachment #1: Type: text/plain, Size: 894 bytes --]

Hi all,

For reasons once might be able to guess, I'm currently playing with
"known" M4 macros vs unseen serials and such.

At the moment, my tool uses the format described at
https://www.gnu.org/software/automake/manual/html_node/Serials.html.

My reading of it implies that the use in e.g. m4/build-to-host.m4
as '# build-to-host.m4 serial 3' isn't valid (I would expect "# serial 3
build-to-host.m4" or similar, closest analogue).

If I grep for serial in gnulib, I see a mix of both the format I
expected and this other format which uses the macro name too.

Are both formats valid (I know it's largely a convention)? Is there a
reason for the apparent inconsistency in format used within e.g. gnulib?
Is there anywhere else I should go read up on conventions for this?

I'll inevitably have to try deal with both formats as they will be in
the wild anyway, but got curious ;)

thanks,
sam

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 377 bytes --]

Re: serial number format

[Bruno Haible]

[-- Attachment #1: Type: text/plain, Size: 2730 bytes --]

Sam James wrote:
> For reasons once might be able to guess, I'm currently playing with
> "known" M4 macros vs unseen serials and such.
> 
> At the moment, my tool uses the format described at
> https://www.gnu.org/software/automake/manual/html_node/Serials.html.
> 
> My reading of it implies that the use in e.g. m4/build-to-host.m4
> as '# build-to-host.m4 serial 3' isn't valid (I would expect "# serial 3
> build-to-host.m4" or similar, closest analogue).
> 
> If I grep for serial in gnulib, I see a mix of both the format I
> expected and this other format which uses the macro name too.
> 
> Are both formats valid (I know it's largely a convention)?

The handling of the 'serial' lines happens in $PREFIX/bin/aclocal,
lines 149..151:

  # Match a serial number.
  my $serial_line_rx = '^#\s*serial\s+(\S*)';
  my $serial_number_rx = '^\d+(?:\.\d+)*$';

and lines 604..709. This means, the format is a line that starts
with '#', followed by optional whitespace, then the word 'serial',
then some whitespace, then some consecutive non-whitespace characters.
The latter must consist only of digits and dots and start with a digit
(see also the error message at line 611:
  "expecting a version string with only digits and dots").

So, a line
  # build-to-host.m4 serial 3
has no effect.

The format with fractional digits is, of course, useful for git branches,
where we can have
  # serial 4.1
if on the 'master' branch the serial 4 and 5 already exist.

> Is there a
> reason for the apparent inconsistency in format used within e.g. gnulib?

Yes: In some cases (see $PREFIX/bin/aclocal, lines 910..936) the generated
aclocal.m4 file does not contain a reference to the .m4 file but its entire
contents. In order to make it clear which .m4 file is where in the aclocal.m4
file, I added a comment indicating the original file name. But having not
read the Automake documentation, I thought I could merge it with the 'serial'
line...

> I'll inevitably have to try deal with both formats as they will be in
> the wild anyway, but got curious ;)

No, you need to deal only with the valid format, not with the ineffective one.

I am applying these three patches:


2024-04-04  Bruno Haible  <bruno@clisp.org>

	Add serial numbers to *.m4 files that did not have them.
	* m4/*.m4: Ensure the usual file header with file name and serial
	number.

	Make the file header of *.m4 files consistent:
	1. The file name.
	2. The serial number.
	3. The copyright and license header.
	* m4/*.m4: Adjust file headers.

	Make the serial numbers in *.m4 files effective.
	Reported by Sam James in
	<https://lists.gnu.org/archive/html/bug-gnulib/2024-04/msg00051.html>.
	* m4/*.m4: Apply sed -e '1s|^# \(.*[.]m4\) serial |# \1\n# serial |'.


[-- Attachment #2: 0001-Make-the-serial-numbers-in-.m4-files-effective.patch.gz --]
[-- Type: application/gzip, Size: 38560 bytes --]

[-- Attachment #3: 0002-Make-the-file-header-of-.m4-files-consistent.patch.gz --]
[-- Type: application/gzip, Size: 11090 bytes --]

[-- Attachment #4: 0003-Add-serial-numbers-to-.m4-files-that-did-not-have-th.patch --]
[-- Type: text/x-patch, Size: 25509 bytes --]

From 81a4c1e3b7692e95c0806d948cbab9148ad85ef2 Mon Sep 17 00:00:00 2001
From: Bruno Haible <bruno@clisp.org>
Date: Thu, 4 Apr 2024 12:22:38 +0200
Subject: [PATCH 3/3] Add serial numbers to *.m4 files that did not have them.

* m4/*.m4: Ensure the usual file header with file name and serial
number.
---
 ChangeLog                              |  4 ++++
 m4/__inline.m4                         |  5 ++++-
 m4/assert_h.m4                         |  3 ++-
 m4/builtin-expect.m4                   |  6 ++++--
 m4/c-bool.m4                           |  6 ++++--
 m4/config-h.m4                         |  6 ++++--
 m4/execinfo.m4                         |  6 ++++--
 m4/explicit_bzero.m4                   |  2 ++
 m4/extern-inline.m4                    |  6 ++++--
 m4/fnmatch.m4                          | 12 +++++++-----
 m4/gnu-make.m4                         | 13 +++++++------
 m4/ieee754-h.m4                        |  6 ++++--
 m4/isapipe.m4                          |  7 ++++---
 m4/largefile.m4                        | 12 +++++++-----
 m4/lib-ignore.m4                       |  6 ++++--
 m4/libgcrypt.m4                        |  4 +++-
 m4/limits-h.m4                         |  6 ++++--
 m4/mkancesdirs.m4                      |  5 ++++-
 m4/mpsort.m4                           | 13 +++++++------
 m4/non-recursive-gnulib-prefix-hack.m4 |  2 ++
 m4/nullptr.m4                          |  6 ++++--
 m4/obstack.m4                          |  6 ++++--
 m4/open-cloexec.m4                     |  6 ++++--
 m4/posix-shell.m4                      | 13 +++++++------
 m4/qsort_r.m4                          |  6 ++++--
 m4/savewd.m4                           |  6 ++++--
 m4/selinux-label-h.m4                  | 10 ++++++----
 m4/stat-time.m4                        | 14 +++++++-------
 m4/std-gnu11.m4                        |  3 +++
 m4/stdalign.m4                         |  6 ++++--
 m4/stdnoreturn.m4                      |  6 ++++--
 m4/time_r.m4                           |  6 ++++--
 m4/time_rz.m4                          |  6 ++++--
 m4/timespec_getres.m4                  |  3 ++-
 m4/totalorder.m4                       |  1 +
 m4/utimens.m4                          |  4 ++--
 m4/wchar_h.m4                          |  6 ++++--
 m4/write-any-file.m4                   | 13 +++++++------
 38 files changed, 160 insertions(+), 91 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 13bb61bc14..536c69737e 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2024-04-04  Bruno Haible  <bruno@clisp.org>
 
+	Add serial numbers to *.m4 files that did not have them.
+	* m4/*.m4: Ensure the usual file header with file name and serial
+	number.
+
 	Make the file header of *.m4 files consistent:
 	1. The file name.
 	2. The serial number.
diff --git a/m4/__inline.m4 b/m4/__inline.m4
index 992e16f4ea..20baf16437 100644
--- a/m4/__inline.m4
+++ b/m4/__inline.m4
@@ -1,9 +1,12 @@
-# Test for __inline keyword
+# __inline.m4
+# serial 1
 dnl Copyright 2017-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Test for __inline keyword
+
 AC_DEFUN([gl___INLINE],
 [
   AC_CACHE_CHECK([whether the compiler supports the __inline keyword],
diff --git a/m4/assert_h.m4 b/m4/assert_h.m4
index d3d4c42519..b90d0f1939 100644
--- a/m4/assert_h.m4
+++ b/m4/assert_h.m4
@@ -1,4 +1,5 @@
-# assert-h.m4
+# assert_h.m4
+# serial 1
 dnl Copyright (C) 2011-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
diff --git a/m4/builtin-expect.m4 b/m4/builtin-expect.m4
index 8faffc5035..c7af926b34 100644
--- a/m4/builtin-expect.m4
+++ b/m4/builtin-expect.m4
@@ -1,10 +1,12 @@
-dnl Check for __builtin_expect.
-
+# builtin-expect.m4
+# serial 1
 dnl Copyright 2016-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+dnl Check for __builtin_expect.
+
 dnl Written by Paul Eggert.
 
 AC_DEFUN([gl___BUILTIN_EXPECT],
diff --git a/m4/c-bool.m4 b/m4/c-bool.m4
index 44fba3c012..0fb0de3b59 100644
--- a/m4/c-bool.m4
+++ b/m4/c-bool.m4
@@ -1,10 +1,12 @@
-# Check for bool that conforms to C2023.
-
+# c-bool.m4
+# serial 1
 dnl Copyright 2022-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Check for bool that conforms to C2023.
+
 AC_DEFUN([gl_C_BOOL],
 [
   AC_CACHE_CHECK([for bool, true, false], [gl_cv_c_bool],
diff --git a/m4/config-h.m4 b/m4/config-h.m4
index 9f3ab6ae53..9e03194650 100644
--- a/m4/config-h.m4
+++ b/m4/config-h.m4
@@ -1,10 +1,12 @@
-# Say that -DHAVE_CONFIG_H is not needed.
-
+# config-h.m4
+# serial 1
 dnl Copyright (C) 2006, 2009-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Say that -DHAVE_CONFIG_H is not needed.
+
 dnl Written by Paul Eggert.
 
 # This package's source files all include config.h unconditionally,
diff --git a/m4/execinfo.m4 b/m4/execinfo.m4
index a76c33525e..9dc8d6d489 100644
--- a/m4/execinfo.m4
+++ b/m4/execinfo.m4
@@ -1,10 +1,12 @@
-# Check for GNU-style execinfo.h.
-
+# execinfo.m4
+# serial 1
 dnl Copyright 2012-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Check for GNU-style execinfo.h.
+
 AC_DEFUN([gl_EXECINFO_H],
 [
   AC_CHECK_HEADERS_ONCE([execinfo.h])
diff --git a/m4/explicit_bzero.m4 b/m4/explicit_bzero.m4
index 3b5af5eea3..13417d65b4 100644
--- a/m4/explicit_bzero.m4
+++ b/m4/explicit_bzero.m4
@@ -1,3 +1,5 @@
+# explicit_bzero.m4
+# serial 1
 dnl Copyright 2017-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
diff --git a/m4/extern-inline.m4 b/m4/extern-inline.m4
index 680250ec77..547da82afa 100644
--- a/m4/extern-inline.m4
+++ b/m4/extern-inline.m4
@@ -1,10 +1,12 @@
-dnl 'extern inline' a la ISO C99.
-
+# extern-inline.m4
+# serial 1
 dnl Copyright 2012-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+dnl 'extern inline' a la ISO C99.
+
 AC_DEFUN([gl_EXTERN_INLINE],
 [
   AC_CACHE_CHECK([whether ctype.h defines __header_inline],
diff --git a/m4/fnmatch.m4 b/m4/fnmatch.m4
index 54d5c7bbdf..48b7c04764 100644
--- a/m4/fnmatch.m4
+++ b/m4/fnmatch.m4
@@ -1,9 +1,11 @@
-# Check for fnmatch - serial 20  -*- coding: utf-8 -*-
+# fnmatch.m4
+# serial 20  -*- coding: utf-8 -*-
+dnl Copyright (C) 2000-2007, 2009-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
 
-# Copyright (C) 2000-2007, 2009-2024 Free Software Foundation, Inc.
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
+# Check for fnmatch
 
 # Autoconf defines AC_FUNC_FNMATCH, but that is obsolescent.
 # New applications should use the macros below instead.
diff --git a/m4/gnu-make.m4 b/m4/gnu-make.m4
index c8831a98ab..fdc0e6a0b2 100644
--- a/m4/gnu-make.m4
+++ b/m4/gnu-make.m4
@@ -1,10 +1,11 @@
-# Determine whether recent-enough GNU Make is being used.
-
-# Copyright (C) 2007, 2009-2024 Free Software Foundation, Inc.
+# gnu-make.m4
+# serial 1
+dnl Copyright (C) 2007, 2009-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
 
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
+# Determine whether recent-enough GNU Make is being used.
 
 # Written by Paul Eggert.
 
diff --git a/m4/ieee754-h.m4 b/m4/ieee754-h.m4
index cc8ef32bd3..fa41db5c94 100644
--- a/m4/ieee754-h.m4
+++ b/m4/ieee754-h.m4
@@ -1,10 +1,12 @@
-# Configure ieee754-h module
-
+# ieee754-h.m4
+# serial 1
 dnl Copyright 2018-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Configure ieee754-h module
+
 AC_DEFUN([gl_IEEE754_H],
 [
   AC_REQUIRE([AC_C_BIGENDIAN])
diff --git a/m4/isapipe.m4 b/m4/isapipe.m4
index 95f44ad447..a23563328e 100644
--- a/m4/isapipe.m4
+++ b/m4/isapipe.m4
@@ -1,11 +1,12 @@
-# Test whether a file descriptor is a pipe.
-
+# isapipe.m4
+# serial 1
 dnl Copyright (C) 2006, 2009-2024 Free Software Foundation, Inc.
-
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Test whether a file descriptor is a pipe.
+
 dnl Written by Paul Eggert.
 
 AC_DEFUN([gl_ISAPIPE],
diff --git a/m4/largefile.m4 b/m4/largefile.m4
index cbe9bc1f63..cf97e986a3 100644
--- a/m4/largefile.m4
+++ b/m4/largefile.m4
@@ -1,11 +1,13 @@
+# largefile.m4
+# serial 1
+dnl Copyright 1992-1996, 1998-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
+
 # Enable large files on systems where this is not the default.
 # Enable support for files on Linux file systems with 64-bit inode numbers.
 
-# Copyright 1992-1996, 1998-2024 Free Software Foundation, Inc.
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
-
 # The following macro works around a problem in Autoconf's AC_FUNC_FSEEKO:
 # It does not set _LARGEFILE_SOURCE=1 on HP-UX/ia64 32-bit, although this
 # setting of _LARGEFILE_SOURCE is needed so that <stdio.h> declares fseeko
diff --git a/m4/lib-ignore.m4 b/m4/lib-ignore.m4
index 431b7e7472..4493c764cf 100644
--- a/m4/lib-ignore.m4
+++ b/m4/lib-ignore.m4
@@ -1,10 +1,12 @@
-# If possible, ignore libraries that are not depended on.
-
+# lib-ignore.m4
+# serial 1
 dnl Copyright (C) 2006, 2009-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# If possible, ignore libraries that are not depended on.
+
 dnl Written by Paul Eggert.
 
 # gl_IGNORE_UNUSED_LIBRARIES
diff --git a/m4/libgcrypt.m4 b/m4/libgcrypt.m4
index cd4249e87b..e4a1a1095b 100644
--- a/m4/libgcrypt.m4
+++ b/m4/libgcrypt.m4
@@ -1,4 +1,5 @@
-# libgcrypt.m4 - Autoconf macros to detect libgcrypt
+# libgcrypt.m4
+# serial 1
 # Copyright (C) 2002, 2003, 2004, 2011, 2014, 2018, 2020 g10 Code GmbH
 #
 # This file is free software; as a special exception the author gives
@@ -11,6 +12,7 @@
 #
 # Last-changed: 2022-11-01
 
+# libgcrypt.m4 - Autoconf macros to detect libgcrypt
 
 dnl AM_PATH_LIBGCRYPT([MINIMUM-VERSION,
 dnl                   [ACTION-IF-FOUND [, ACTION-IF-NOT-FOUND ]]])
diff --git a/m4/limits-h.m4 b/m4/limits-h.m4
index 1825328380..1b619e1eb2 100644
--- a/m4/limits-h.m4
+++ b/m4/limits-h.m4
@@ -1,10 +1,12 @@
-dnl Check whether limits.h has needed features.
-
+# limits-h.m4
+# serial 1
 dnl Copyright 2016-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+dnl Check whether limits.h has needed features.
+
 dnl From Paul Eggert.
 
 AC_DEFUN_ONCE([gl_LIMITS_H],
diff --git a/m4/mkancesdirs.m4 b/m4/mkancesdirs.m4
index 914f534ff1..3fb4081a1f 100644
--- a/m4/mkancesdirs.m4
+++ b/m4/mkancesdirs.m4
@@ -1,9 +1,12 @@
-# Make a file's ancestor directories.
+# mkancesdirs.m4
+# serial 1
 dnl Copyright (C) 2006, 2009-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Make a file's ancestor directories.
+
 AC_DEFUN([gl_MKANCESDIRS],
 [
   :
diff --git a/m4/mpsort.m4 b/m4/mpsort.m4
index 3f592e9dab..0153263e84 100644
--- a/m4/mpsort.m4
+++ b/m4/mpsort.m4
@@ -1,10 +1,11 @@
-# Sort a vector of pointers to data.
-
-# Copyright (C) 2007, 2009-2024 Free Software Foundation, Inc.
+# mpsort.m4
+# serial 1
+dnl Copyright (C) 2007, 2009-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
 
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
+# Sort a vector of pointers to data.
 
 AC_DEFUN([gl_MPSORT],
 [
diff --git a/m4/non-recursive-gnulib-prefix-hack.m4 b/m4/non-recursive-gnulib-prefix-hack.m4
index 744c252987..83d9ccb3a1 100644
--- a/m4/non-recursive-gnulib-prefix-hack.m4
+++ b/m4/non-recursive-gnulib-prefix-hack.m4
@@ -1,3 +1,5 @@
+# non-recursive-gnulib-prefix-hack.m4
+# serial 1
 dnl Copyright (C) 2012-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
diff --git a/m4/nullptr.m4 b/m4/nullptr.m4
index f5721e5c33..eeeee99495 100644
--- a/m4/nullptr.m4
+++ b/m4/nullptr.m4
@@ -1,10 +1,12 @@
-# Check for nullptr that conforms to C23 and C++11.
-
+# nullptr.m4
+# serial 1
 dnl Copyright 2023-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Check for nullptr that conforms to C23 and C++11.
+
 AC_DEFUN([gl_NULLPTR],
 [
   m4_provide_if([AC_PROG_CC],
diff --git a/m4/obstack.m4 b/m4/obstack.m4
index be553cfb78..bfab293f7a 100644
--- a/m4/obstack.m4
+++ b/m4/obstack.m4
@@ -1,10 +1,12 @@
-# See if we need to provide obstacks.
-
+# obstack.m4
+# serial 1
 dnl Copyright 1996-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# See if we need to provide obstacks.
+
 dnl Autoconf's AC_FUNC_OBSTACK is marked obsolete since version 2.70.
 dnl We provide our own macro here.
 
diff --git a/m4/open-cloexec.m4 b/m4/open-cloexec.m4
index a2d50329b9..6defdfb400 100644
--- a/m4/open-cloexec.m4
+++ b/m4/open-cloexec.m4
@@ -1,10 +1,12 @@
-# Test whether O_CLOEXEC is defined.
-
+# open-cloexec.m4
+# serial 1
 dnl Copyright 2017-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Test whether O_CLOEXEC is defined.
+
 AC_DEFUN([gl_PREPROC_O_CLOEXEC],
 [
   AC_CACHE_CHECK([for O_CLOEXEC],
diff --git a/m4/posix-shell.m4 b/m4/posix-shell.m4
index 36f8fb8ca8..ea90c8d286 100644
--- a/m4/posix-shell.m4
+++ b/m4/posix-shell.m4
@@ -1,10 +1,11 @@
-# Find a POSIX-conforming shell.
-
-# Copyright (C) 2007-2024 Free Software Foundation, Inc.
+# posix-shell.m4
+# serial 1
+dnl Copyright (C) 2007-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
 
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
+# Find a POSIX-conforming shell.
 
 # Written by Paul Eggert.
 
diff --git a/m4/qsort_r.m4 b/m4/qsort_r.m4
index 0ff79f30f4..67cd556cd1 100644
--- a/m4/qsort_r.m4
+++ b/m4/qsort_r.m4
@@ -1,10 +1,12 @@
-dnl Reentrant sort function.
-
+# qsort_r.m4
+# serial 1
 dnl Copyright 2014-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+dnl Reentrant sort function.
+
 dnl Written by Paul Eggert.
 
 AC_DEFUN([gl_FUNC_QSORT_R],
diff --git a/m4/savewd.m4 b/m4/savewd.m4
index ebbe65d0c1..7d61bb673c 100644
--- a/m4/savewd.m4
+++ b/m4/savewd.m4
@@ -1,8 +1,10 @@
-# Save and restore the working directory, possibly using a child process.
-
+# savewd.m4
+# serial 1
 dnl Copyright (C) 2004, 2009-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Save and restore the working directory, possibly using a child process.
+
 AC_DEFUN([gl_SAVEWD], [:])
diff --git a/m4/selinux-label-h.m4 b/m4/selinux-label-h.m4
index 87a19e1c04..2f46ec9caf 100644
--- a/m4/selinux-label-h.m4
+++ b/m4/selinux-label-h.m4
@@ -1,7 +1,9 @@
-# Copyright 2020-2024 Free Software Foundation, Inc.
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
+# selinux-label-h.m4
+# serial 1
+dnl Copyright 2020-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
 
 # From Paul Eggert
 # Provide <selinux/label.h>, if necessary.
diff --git a/m4/stat-time.m4 b/m4/stat-time.m4
index 8bec2f5f81..e8ee7d5125 100644
--- a/m4/stat-time.m4
+++ b/m4/stat-time.m4
@@ -1,11 +1,11 @@
-# Checks for stat-related time functions.
-
-# Copyright (C) 1998-1999, 2001, 2003, 2005-2007, 2009-2024 Free Software
-# Foundation, Inc.
+# stat-time.m4
+# serial 1
+dnl Copyright (C) 1998-1999, 2001, 2003, 2005-2007, 2009-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
 
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
+# Checks for stat-related time functions.
 
 dnl From Paul Eggert.
 
diff --git a/m4/std-gnu11.m4 b/m4/std-gnu11.m4
index 59998c17cf..37324c158e 100644
--- a/m4/std-gnu11.m4
+++ b/m4/std-gnu11.m4
@@ -1,3 +1,6 @@
+# std-gnu11.m4
+# serial 1
+
 # Prefer GNU C11 and C++11 to earlier versions.  -*- coding: utf-8 -*-
 
 # This implementation is taken from GNU Autoconf lib/autoconf/c.m4
diff --git a/m4/stdalign.m4 b/m4/stdalign.m4
index e3c1e60923..2b4762f320 100644
--- a/m4/stdalign.m4
+++ b/m4/stdalign.m4
@@ -1,10 +1,12 @@
-# Check for alignas and alignof that conform to C23.
-
+# stdalign.m4
+# serial 1
 dnl Copyright 2011-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Check for alignas and alignof that conform to C23.
+
 dnl Written by Paul Eggert and Bruno Haible.
 
 # Prepare for substituting <stdalign.h> if it is not supported.
diff --git a/m4/stdnoreturn.m4 b/m4/stdnoreturn.m4
index 02c0dd5252..cb8e103eaf 100644
--- a/m4/stdnoreturn.m4
+++ b/m4/stdnoreturn.m4
@@ -1,10 +1,12 @@
-# Check for stdnoreturn.h that conforms to C11.
-
+# stdnoreturn.m4
+# serial 1
 dnl Copyright 2012-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+# Check for stdnoreturn.h that conforms to C11.
+
 # Prepare for substituting <stdnoreturn.h> if it is not supported.
 
 AC_DEFUN([gl_STDNORETURN_H],
diff --git a/m4/time_r.m4 b/m4/time_r.m4
index 4ee2175b69..3675390e87 100644
--- a/m4/time_r.m4
+++ b/m4/time_r.m4
@@ -1,10 +1,12 @@
-dnl Reentrant time functions: localtime_r, gmtime_r.
-
+# time_r.m4
+# serial 1
 dnl Copyright (C) 2003, 2006-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+dnl Reentrant time functions: localtime_r, gmtime_r.
+
 dnl Written by Paul Eggert.
 
 AC_DEFUN([gl_TIME_R],
diff --git a/m4/time_rz.m4 b/m4/time_rz.m4
index c3b72b7603..8f45f2b1d3 100644
--- a/m4/time_rz.m4
+++ b/m4/time_rz.m4
@@ -1,10 +1,12 @@
-dnl Time zone functions: tzalloc, localtime_rz, etc.
-
+# time_rz.m4
+# serial 1
 dnl Copyright (C) 2015-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+dnl Time zone functions: tzalloc, localtime_rz, etc.
+
 dnl Written by Paul Eggert.
 
 AC_DEFUN([gl_TIME_RZ],
diff --git a/m4/timespec_getres.m4 b/m4/timespec_getres.m4
index 72edcebf03..b366c814ee 100644
--- a/m4/timespec_getres.m4
+++ b/m4/timespec_getres.m4
@@ -1,4 +1,5 @@
-# timespec_getres serial 2
+# timespec_getres.m4
+# serial 2
 dnl Copyright 2021-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
diff --git a/m4/totalorder.m4 b/m4/totalorder.m4
index 6be25cb312..92166de484 100644
--- a/m4/totalorder.m4
+++ b/m4/totalorder.m4
@@ -1,4 +1,5 @@
 # totalorder.m4
+# serial 1
 dnl Copyright 2023-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
diff --git a/m4/utimens.m4 b/m4/utimens.m4
index 0f5bfd4c84..9996e3ef33 100644
--- a/m4/utimens.m4
+++ b/m4/utimens.m4
@@ -1,10 +1,10 @@
+# utimens.m4
+# serial 16
 dnl Copyright (C) 2003-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
-dnl serial 16
-
 AC_DEFUN([gl_UTIMENS],
 [
   dnl Prerequisites of lib/utimens.c.
diff --git a/m4/wchar_h.m4 b/m4/wchar_h.m4
index 173f42a45a..a7b660defd 100644
--- a/m4/wchar_h.m4
+++ b/m4/wchar_h.m4
@@ -1,10 +1,12 @@
-dnl A placeholder for ISO C99 <wchar.h>, for platforms that have issues.
-
+# wchar_h.m4
+# serial 1
 dnl Copyright (C) 2007-2024 Free Software Foundation, Inc.
 dnl This file is free software; the Free Software Foundation
 dnl gives unlimited permission to copy and/or distribute it,
 dnl with or without modifications, as long as this notice is preserved.
 
+dnl A placeholder for ISO C99 <wchar.h>, for platforms that have issues.
+
 dnl Written by Eric Blake.
 
 # wchar_h.m4 serial 63
diff --git a/m4/write-any-file.m4 b/m4/write-any-file.m4
index 0c7e9af2a3..50e5aa0c2a 100644
--- a/m4/write-any-file.m4
+++ b/m4/write-any-file.m4
@@ -1,10 +1,11 @@
-# Determine whether we can write any file.
+# write-any-file.m4
+# serial 1
+dnl Copyright (C) 2007, 2009-2024 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
 
-# Copyright (C) 2007, 2009-2024 Free Software Foundation, Inc.
-#
-# This file is free software; the Free Software Foundation
-# gives unlimited permission to copy and/or distribute it,
-# with or without modifications, as long as this notice is preserved.
+# Determine whether we can write any file.
 
 # Written by Paul Eggert.
 
-- 
2.34.1

Re: serial number format

[Sam James]

[-- Attachment #1: Type: text/plain, Size: 2771 bytes --]

Bruno Haible <bruno@clisp.org> writes:

> Sam James wrote:
>> For reasons once might be able to guess, I'm currently playing with
>> "known" M4 macros vs unseen serials and such.
>> 
>> At the moment, my tool uses the format described at
>> https://www.gnu.org/software/automake/manual/html_node/Serials.html.
>> 
>> My reading of it implies that the use in e.g. m4/build-to-host.m4
>> as '# build-to-host.m4 serial 3' isn't valid (I would expect "# serial 3
>> build-to-host.m4" or similar, closest analogue).
>> 
>> If I grep for serial in gnulib, I see a mix of both the format I
>> expected and this other format which uses the macro name too.
>> 
>> Are both formats valid (I know it's largely a convention)?
>
> The handling of the 'serial' lines happens in $PREFIX/bin/aclocal,
> lines 149..151:
>
>   # Match a serial number.
>   my $serial_line_rx = '^#\s*serial\s+(\S*)';
>   my $serial_number_rx = '^\d+(?:\.\d+)*$';
>
> and lines 604..709. This means, the format is a line that starts
> with '#', followed by optional whitespace, then the word 'serial',
> then some whitespace, then some consecutive non-whitespace characters.
> The latter must consist only of digits and dots and start with a digit
> (see also the error message at line 611:
>   "expecting a version string with only digits and dots").
>
> So, a line
>   # build-to-host.m4 serial 3
> has no effect.
>
> The format with fractional digits is, of course, useful for git branches,
> where we can have
>   # serial 4.1
> if on the 'master' branch the serial 4 and 5 already exist.
>
>> Is there a
>> reason for the apparent inconsistency in format used within e.g. gnulib?
>
> Yes: In some cases (see $PREFIX/bin/aclocal, lines 910..936) the generated
> aclocal.m4 file does not contain a reference to the .m4 file but its entire
> contents. In order to make it clear which .m4 file is where in the aclocal.m4
> file, I added a comment indicating the original file name. But having not
> read the Automake documentation, I thought I could merge it with the 'serial'
> line...
>
>> I'll inevitably have to try deal with both formats as they will be in
>> the wild anyway, but got curious ;)
>
> No, you need to deal only with the valid format, not with the ineffective one.
>
> I am applying these three patches:

Thank you very much Bruno -- for the quick fix, explanation, and prompt
reply. Cheers!

At a glance, it looks like gettext's m4/fixautomake.m4 at
least might be affected. There's some in GNU Autoconf's testsuite, but
that requires further inspection in case it's deliberately testing the
parsing.

I should really have all the GNU projects in one directory so I can
easily grep in future.

> [...]

best,
sam

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 377 bytes --]

Re: serial number format

[Bruno Haible]

Sam James wrote:
> At a glance, it looks like gettext's m4/fixautomake.m4 at
> least might be affected.

Yes, some *.m4 files in other packages are affected as well. Fixed now.

> I should really have all the GNU projects in one directory so I can
> easily grep in future.

For searching across many packages, I use (and can recommend)
https://codesearch.debian.net/ .

Bruno

Re: serial number format

[Paul Eggert]

I've not been a fan of those .m4 serial numbers, which may help to 
explain why so many .m4 files lack them. Although I still have doubts 
whether they're worth the trouble, perhaps it'd help if we added a file 
m4/.dir-locals.el (or something similar) that would cause Emacs to 
update these serial numbers automatically.

Re: serial number format

[Bruno Haible]

Paul Eggert wrote:
> Although I still have doubts whether they're worth the trouble

While I personally have not encountered the benefits of the serial
numbers — since I don't use 'aclocal --install' —, other people
surely do.

> perhaps it'd help if we added a file 
> m4/.dir-locals.el (or something similar) that would cause Emacs to 
> update these serial numbers automatically.

This sounds useful, yes. Any Emacs Lisp hacker volunteers?

Bruno

Re: serial number format

[Sam James]

Paul Eggert <eggert@cs.ucla.edu> writes:

> I've not been a fan of those .m4 serial numbers, which may help to
> explain why so many .m4 files lack them. Although I still have doubts
> whether they're worth the trouble, perhaps it'd help if we added a
> file m4/.dir-locals.el (or something similar) that would cause Emacs
> to update these serial numbers automatically.

Not quite it, but autoconf-archive has some tooling around it:
* https://github.com/autoconf-archive/autoconf-archive/blob/81e26138e807b9ecb3c19b953e8776ff9e415fdf/macro.py#L112
* https://github.com/autoconf-archive/autoconf-archive/blob/81e26138e807b9ecb3c19b953e8776ff9e415fdf/set-serial.sh#L20

Maintainer mode is integrated with this so it updates serial numbers
automatically.