Next Up Previous Contents
Next: 2.4 A few remarks on state
Up: 2 Tools
Previous: 2.2 Starconf, and the Starlink autoconf macros
[ID index][Keyword index]

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.
This is illustrated in Figure 5.

gif89a image
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 (from the prm component):

libprm_la_SOURCES = \
libprm_la_LDFLAGS = -version-info $(libprm_la_version_info)

libprm_a_la_SOURCES = \
libprm_a_la_LDFLAGS = -version-info $(libprm_a_la_version_info)
and then the corresponding section from

AC_INIT(prm, 1.3-1,
# Version-info specifications.  See SSN/78 for guidelines, and update the table
# below for ANY change of version number.
# Release
#  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)

There is no automake magic to the libprm_la_version_info variable name -- it is just mnemonic, and you are free to change it if you have a good reason to do so. Since there is no fixed relationship between the component version number and the -version-info specification, it is important to maintain a simple table of associations between the two, and the file is a sensible place to do that.

Next Up Previous Contents
Next: 2.4 A few remarks on state
Up: 2 Tools
Previous: 2.2 Starconf, and the Starlink autoconf macros
[ID index][Keyword index]
The Starlink Build System
Starlink System Note 78
Norman Gray, Peter W Draper, Mark B Taylor, Steven E Rankin
11 April 2005. Release snapshot: $Revision: 1.116 $. Last updated 28 May 2006