Version Numbers

1. Introduction

The HDF5 version number is a set of three integer values and one lower-case letter written as, for example, hdf5-1.2.0a.

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. 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 0 is the release number. For public versions of the library, the release number is incremented each time a bug(s) is fixed and the fix is made available to the public. For development versions, the release number is incremented automatically each time a CVS commit occurs anywhere in the source tree.

The a is the patch level and is used only for public versions. It's incremented only for very minor changes that don't affect the usability of the library. For instance, fixing spelling errors, changing warning messages, or updating documentation.

2. Abbreviated Versions

It's often convenient to drop the patch level and release number when referring to a version of the library, like saying version 1.2 of HDF5. The release number and patch level 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.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.

Version 1.2 will be the first official HDF5 version. The version tree will fork at this point with public bug fixes provided on the 1.2 branch and development will continue on the 1.3 branch.

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.

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

H5_VERS_PATCH

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

herr_t H5version (unsigned *majnum, unsigned *minnum, unsigned *relnum, unsigned *patnum)

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 H5vers_check (unsigned majnum, unsigned minnum, unsigned relnum, unsigned patnum)

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