automake: Serials
1
1 6.3.5 Serial Numbers
1 --------------------
1
1 Because third-party macros defined in ‘*.m4’ files are naturally shared
1 between multiple projects, some people like to version them. This makes
1 it easier to tell which of two M4 files is newer. Since at least 1996,
1 the tradition is to use a ‘#serial’ line for this.
1
1 A serial number should be a single line of the form
1
1 # serial VERSION
1
1 where VERSION is a version number containing only digits and dots.
1 Usually people use a single integer, and they increment it each time
1 they change the macro (hence the name of “serial”). Such a line should
1 appear in the M4 file before any macro definition.
1
1 The ‘#’ must be the first character on the line, and it is OK to have
1 extra words after the version, as in
1
1 #serial VERSION GARBAGE
1
1 Normally these serial numbers are completely ignored by ‘aclocal’ and
1 ‘autoconf’, like any genuine comment. However when using ‘aclocal’’s
1 ‘--install’ feature, these serial numbers will modify the way ‘aclocal’
1 selects the macros to install in the package: if two files with the same
1 basename exist in your search path, and if at least one of them uses a
1 ‘#serial’ line, ‘aclocal’ will ignore the file that has the older
1 ‘#serial’ line (or the file that has none).
1
1 Note that a serial number applies to a whole M4 file, not to any
1 macro it contains. A file can contains multiple macros, but only one
1 serial.
1
1 Here is a use case that illustrates the use of ‘--install’ and its
1 interaction with serial numbers. Let’s assume we maintain a package
1 called MyPackage, the ‘configure.ac’ of which requires a third-party
1 macro ‘AX_THIRD_PARTY’ defined in ‘/usr/share/aclocal/thirdparty.m4’ as
1 follows:
1
1 # serial 1
1 AC_DEFUN([AX_THIRD_PARTY], [...])
1
1 MyPackage uses an ‘m4/’ directory to store local macros as explained
1 in ⇒Local Macros, and has
1
1 AC_CONFIG_MACRO_DIRS([m4])
1
1 in its ‘configure.ac’.
1
1 Initially the ‘m4/’ directory is empty. The first time we run
1 ‘aclocal --install’, it will notice that
1
1 • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
1 • No local macros define ‘AX_THIRD_PARTY’
1 • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
1 serial 1.
1
1 Because ‘/usr/share/aclocal/thirdparty.m4’ is a system-wide macro and
1 ‘aclocal’ was given the ‘--install’ option, it will copy this file in
1 ‘m4/thirdparty.m4’, and output an ‘aclocal.m4’ that contains
1 ‘m4_include([m4/thirdparty.m4])’.
1
1 The next time ‘aclocal --install’ is run, something different
1 happens. ‘aclocal’ notices that
1
1 • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
1 • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1.
1 • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
1 serial 1.
1
1 Because both files have the same serial number, ‘aclocal’ uses the first
1 it found in its search path order (⇒Macro Search Path).
1 ‘aclocal’ therefore ignores ‘/usr/share/aclocal/thirdparty.m4’ and
1 outputs an ‘aclocal.m4’ that contains ‘m4_include([m4/thirdparty.m4])’.
1
1 Local directories specified with ‘-I’ are always searched before
1 system-wide directories, so a local file will always be preferred to the
1 system-wide file in case of equal serial numbers.
1
1 Now suppose the system-wide third-party macro is changed. This can
1 happen if the package installing this macro is updated. Let’s suppose
1 the new macro has serial number 2. The next time ‘aclocal --install’ is
1 run the situation is the following:
1
1 • ‘configure.ac’ uses ‘AX_THIRD_PARTY’
1 • ‘m4/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with serial 1.
1 • ‘/usr/share/aclocal/thirdparty.m4’ defines ‘AX_THIRD_PARTY’ with
1 serial 2.
1
1 When ‘aclocal’ sees a greater serial number, it immediately forgets
1 anything it knows from files that have the same basename and a smaller
1 serial number. So after it has found ‘/usr/share/aclocal/thirdparty.m4’
1 with serial 2, ‘aclocal’ will proceed as if it had never seen
1 ‘m4/thirdparty.m4’. This brings us back to a situation similar to that
1 at the beginning of our example, where no local file defined the macro.
1 ‘aclocal’ will install the new version of the macro in
1 ‘m4/thirdparty.m4’, in this case overriding the old version. MyPackage
1 just had its macro updated as a side effect of running ‘aclocal’.
1
1 If you are leery of letting ‘aclocal’ update your local macro, you
1 can run ‘aclocal --diff’ to review the changes ‘aclocal --install’ would
1 perform on these macros.
1
1 Finally, note that the ‘--force’ option of ‘aclocal’ has absolutely
1 no effect on the files installed by ‘--install’. For instance, if you
1 have modified your local macros, do not expect ‘--install --force’ to
1 replace the local macros by their system-wide versions. If you want to
1 do so, simply erase the local macros you want to revert, and run
1 ‘aclocal --install’.
1