Version Numbers¶
The SAF source code has various version numbers assigned to parts of the system: source files, header files, library, API definition, and database files.
Source file versions are identical to CVS file revision numbers. These numbers are not stored in the source file but rather maintained by CVS. (We don’t store them in the source file because it makes it more difficult to synchronize local and remote source trees since a `cvs commit’ would modify all the source files.) We use CVS in such a way that the main branch always contains the latest development version of SAF. When a public release is about to occur a new branch is created, version numbers are adjusted on both branches, and development stops on the new branch.
The header files and library each have a four-part version number: major, minor, patch, and comment. The version number of the header files must exactly match the version number of the library, or the library will refuse to operate. The major number is incremented only if the API changes in a way which is not backward compatible. The increment happens when the development branch is split to produce a new release branch, and the minor number is set to zero or one (depending on branch) and the patch number is reset to zero. The minor number is incremented each time the main branch is split to produce a release branch. The minor number is always even on a release branch and odd on the development branch (the latest development version minor number is one greater than the latest release version). The patch number is incremented each time bugs are fixed on the release branch, or each time a snapshot is produced on the development branch. The comment is a character string indicating the scope of the release and is the empty string for all public releases and snapshots. Library version numbers are printed as i.j.k-c where i is the major number, j is the minor number, k is the patch number, and -c is the comment string (the hyphen is printed only if the comment string is non-empty.
The API definition has a two-part version number which is the same as the major and minor version numbers of the header files and library. For any given release or snapshot the library must implement the corresponding version of the API. The API may document certain features as “not yet implemented”.
Database files will contain the library version number as an attribute named “SAF” attached to the group containing the VBT files. The attribute will be of compound type and contain all global SAF metadata.
Standard Comment Strings: The comment string for all development versions which have not yet passed the snapshot operation will be `devel’. When the main branch is split to create a release branch the comment string on the release branch will be cleared. Pre-releases will then be created from the release branch while holding the patch number at zero so the release can be tested by the developers. Such prereleases will be commented as `preN’ where n is a number beginning at zero. When a prerelease passes all developer tests the comment will be removed or changed to `beta’.
Almost all programs call saf_init and/or saf_open_database in order to do something useful. So we’ve chosen to wrap those functions in macros which also make a reference to a global variable whose name is derived from the SAF version number. This variable is declared in the SAF library so that if an application is compiled with SAF header files which have a different version than the SAF library a link-time error will result. A version mismatch will result in an error similar to undefined reference to ``SAF__version_0_1_0`’ from the linker.