summaryrefslogtreecommitdiffstats
path: root/doc/html/TechNotes/Version.html
blob: 0e0853bd1e878b646a3e0ecbe82c8f27fc355262 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
  <head>
    <title>Version Numbers</title>
  </head>

  <body>
    <h1>HDF5 Release Version Numbers</h1>

    <h2>1. Introduction</h2>

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

    <p>The <code>5</code> 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.

    <p>The <code>1</code> is the <em>major version number</em> 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.

    <p>The <code>2</code> is the <em>minor version number</em> 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.

    <p>The <code>3</code> is the <em>release number</em>.  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).

    <h2>2. Abbreviated Versions</h2>

    <p>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.

    <h2>3. Special Versions</h2>

    <p>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.

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

    <p>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.

    <p>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.

    <h2>4. Public versus Development</h2>

    <p>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.

    <p>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.

    <p>
      <center>
	<img alt="Version Example" src="version.gif">
	<br><b>Fig 1: Version Example</b>
      </center>

    <h2>5. Version Support from the Library</h2>

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

    <dl>
      <dt><code>H5_VERS_MAJOR</code>
      <dt><code>H5_VERS_MINOR</code>
      <dt><code>H5_VERS_RELEASE</code>
      <dd>These preprocessor constants are defined in the public
	include file and determine the version of the include files.

	<br><br>
      <dt><code>herr_t H5get_libversion (unsigned *<em>majnum</em>, unsigned
	  *<em>minnum</em>, unsigned *<em>relnum</em>)</code>
      <dd>This function returns through its arguments the version
	numbers for the library to which the application is linked.

	<br><br>
      <dt><code>void H5check(void)</code>
      <dd>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.

	<br><br>
      <dt><code>herr_t H5check_version (unsigned <em>majnum</em>,
	  unsigned <em>minnum</em>, unsigned <em>relnum</em>)</code>
      <dd>This function is called by the <code>H5check()</code> macro
	with the include file version constants.  The function
	compares its arguments to the result returned by
	<code>H5get_libversion()</code> and if a mismatch is detected prints
	an error message on the standard error stream and aborts.
    </dl>

<hr>
<address><a href="mailto:hdfhelp@ncsa.uiuc.edu">HDF Help Desk</a></address>
<br>

<!-- Created: Wed Apr 22 11:24:40 EDT 1998 -->
<!-- hhmts start -->
Last modified: Fri Oct 30 10:32:50 EST 1998
<!-- hhmts end -->

  </body>
</html>