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