2.3 Version numbers

The only place where you should specify a version number is as the second argument to the AC_INIT macro; if you need the version number anywhere else, such as a bit of code which reports the package version number, you should put it there with the @PACKAGE_VERSION@ substitution variable, or one of the variants of this defined by STAR_DEFAULTS (see Appendix A.17).

Starlink follows the usual practice of indicating release versions with a three-part version number, major.minor-release. We have no particularly precise rules controlling these, but the major version number is typically incremented for a release which contains a major change in functionality or implementation, the minor is incremented for changes of functionality less significant than this, and the release number is incremented for bugfix releases, involving no functionality changes at all.

If a component contains a shared library, then the maintainer may elect to maintain shared library versioning information [XXX: should we make this a requirement for libraries?]. Since we use libtool, we can use its -version-info interface to maintain library versions. This is documented in section `Updating library version information' of the libtool manual, but the explanation is repeated and elaborated below.

The crucial thing to remember is that the versioning information encoded in this -version-info option is not the component version number, but instead an encoding of which interface versions a given shared library implements, in the form of a triple current:revision:age. 'Current' is the interface version, as a monotonically increasing integer, and 'age' is a statement of how many interfaces are compatible with it: if a library has a triple c:r:a, then it implements all the interfaces between versions c-a and c, inclusive. When you're making a new release of a library which had the -version-info c:r:a,

1. If the interface is unchanged, but the implementation has changed or been fixed, then increment r.
2. Otherwise, increment c and zero r.
   1. If the interface has grown (that is, the new library is compatible with old code), increment a.
   2. If the interface has changed in an incompatible way (that is, functions have changed or been removed), then zero a.

Figure 5: Updating -version-info specifications

The libtool documentation suggests starting the version-info specifications at 0:0:0, and this is the default if no -version-info option is present. Since only some Starlink libraries have this versioning maintained, it is best if you start the specification at 1:0:0, to distinguish this from those libraries which have no version-info defined.

You add the -version-info specification to the libtool command using the library's LDFLAGS variable, as follows. First the Makefile.am (from the prm component):

libprm_la_SOURCES = \
    $(F_ROUTINES)
    $(PUBLIC_INCLUDES) \
    $(PRIVATE_INCLUDES) \
    PRM_PAR
libprm_la_LDFLAGS = -version-info $(libprm_la_version_info)

libprm_a_la_SOURCES = \
    $(PLATFORM_C)
libprm_a_la_LDFLAGS = -version-info $(libprm_a_la_version_info)
[...]

AC_INIT(prm, 1.3-1, ussc@star.rl.ac.uk)
# Version-info specifications.  See SSN/78 for guidelines, and update the table
# below for ANY change of version number.
#
# Release    libprm.la      libprm_a.la
#  1.3-1       1:0:0          1:0:0
AC_SUBST(libprm_la_version_info,   1:0:0)
AC_SUBST(libprm_a_la_version_info, 1:0:0)

[...]