HDF5 Release Version Numbers

1. Introduction

The HDF5 version number is a set of three integer values written as either hdf5-1.2.3 or hdf5 version 1.2 release 3.

The 5 is part of the library name and will only change if the entire file format and library are redesigned similar in scope to the changes between HDF4 and HDF5.

The 1 is the major version number and changes when there is an extensive change to the file format or library API. Such a change will likely require files to be translated and applications to be modified. This number is not expected to change frequently.

The 2 is the minor version number and is incremented by each public release that presents new features. Even numbers are reserved for stable public versions of the library while odd numbers are reserved for developement versions. See the diagram below for examples.

The 3 is the release number. For public versions of the library, the release number is incremented each time a bug is fixed and the fix is made available to the public. For development versions, the release number is incremented more often (perhaps almost daily).

2. Abbreviated Versions

It's often convenient to drop the release number when referring to a version of the library, like saying version 1.2 of HDF5. The release number can be any value in this case.

3. Special Versions

Version 1.0.0 was released for alpha testing the first week of March, 1998. The developement version number was incremented to 1.0.1 and remained constant until the the last week of April, when the release number started to increase and development versions were made available to people outside the core HDF5 development team.

Version 1.0.23 was released mid-July as a second alpha version.

Version 1.1.0 will be the first official beta release but the 1.1 branch will also serve as a development branch since we're not concerned about providing bug fixes separate from normal development for the beta version.

After the beta release we rolled back the version number so the first release is version 1.0 and development will continue on version 1.1. We felt that an initial version of 1.0 was more important than continuing to increment the pre-release version numbers.

4. Public versus Development

The motivation for separate public and development versions is that the public version will receive only bug fixes while the development version will receive new features. This also allows us to release bug fixes expediently without waiting for the development version to reach a stable state.

Eventually, the development version will near completion and a new development branch will fork while the original one enters a feature freeze state. When the original development branch is ready for release the minor version number will be incremented to an even value.

Fig 1: Version Example

5. Version Support from the Library

The library provides a set of macros and functions to query and check version numbers.

H5_VERS_MAJOR

H5_VERS_MINOR

H5_VERS_RELEASE

These preprocessor constants are defined in the public include file and determine the version of the include files.

herr_t H5get_libversion (unsigned *majnum, unsigned *minnum, unsigned *relnum)

This function returns through its arguments the version numbers for the library to which the application is linked.

void H5check(void)

This is a macro that verifies that the version number of the HDF5 include file used to compile the application matches the version number of the library to which the application is linked. This check occurs automatically when the first HDF5 file is created or opened and is important because a mismatch between the include files and the library is likely to result in corrupted data and/or segmentation faults. If a mismatch is detected the library issues an error message on the standard error stream and aborts with a core dump.

herr_t H5check_version (unsigned majnum, unsigned minnum, unsigned relnum)

This function is called by the H5check() macro with the include file version constants. The function compares its arguments to the result returned by H5get_libversion() and if a mismatch is detected prints an error message on the standard error stream and aborts.