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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
|
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>
<title>TechNote: HDF5 Library Version Numbers</title>
<!--( Begin styles definition )=====================================-->
<link href="../UG/ed_styles/NewUGelect.css" rel="stylesheet" type="text/css">
<!--( End styles definition )=======================================-->
</head>
<!--
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
* Copyright by The HDF Group. *
* Copyright by the Board of Trustees of the University of Illinois. *
* All rights reserved. *
* *
* This file is part of HDF5. The full HDF5 copyright notice, including *
* terms governing use, modification, and redistribution, is contained in *
* the files COPYING and Copyright.html. COPYING can be found at the root *
* of the source code distribution tree; Copyright.html can be found at the *
* root level of an installed copy of the electronic HDF5 document set and *
* is linked from the top-level documents page. It can also be found at *
* http://hdfgroup.org/HDF5/doc/Copyright.html. If you do not have *
* access to either file, you may request a copy from help@hdfgroup.org. *
* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
-->
<body>
<div align="center">
<h1>HDF5 Library Version Numbers</h1>
</div>
<p>HDF5 software is updated on a regular basis. These updates, known
as releases, range in scope and size from small to large. Some updates
may only fix bugs, and some updates may require a change in the format
of the data file. The version numbers that are applied to updates give
information about the kinds of changes made in the updates. This Tech
Note describes what the version numbers mean.</p>
<p>Each software release of the HDF5 Library is labeled with a version
number. The version number is a set of three integers written as HDF5-1.2.3,
HDF5 version 1.2 release 3, or HDF5 Release 1.2.3. The version number
might also include text. A patch version might be labeled HDF5-1.2.3-patch1.
The ‘5’ in ‘HDF5’ is part of the product name and
will not change during the life of the project.</p>
<p>The key components in HDF5 Library version numbers are the major version
number, the minor version number, the release number, and an optional text
string. </p>
<p>The first integer in a version number is the <b>major version
number</b>. This integer increments when there is an extensive change
to the file format or library API. Such a change may require files to
be translated and will likely require applications to be modified. </p>
<p>The second integer, 2 in the examples above, is the <b>minor version
number</b>. This number is incremented when there are new features that
require a change in the file format. For example, a change in file format
was required during the change from version 1.6 to version 1.8. Stable
released versions of the library are given <i>even</i> minor version
numbers such as 1.6 and 1.8 while <i>odd</i> minor version numbers such
as 1.7 and 1.9 are used on the trunk for major development. See the
section below for more information.</p>
<p>The third integer, 3 in the examples above, is the <b>release
number</b>. A change in this number indicates that the library has
been updated. The updates might include bug fixes, performance
improvements, and new features that do not require a file format
change. </p>
<p>A version number might also include some text. The two current
possibilities are <b>patch</b> and <b>snap</b>. A patch version might
be made to a released version to make available a feature or a bug
fix. In the figure below, a patch to the 1.8.5 release is labeled
1.8.5-patch1. A snapshot is an intermediate posting of the software
in a branch or in the trunk. Snapshots are made available so that users
may begin to test changes in the software that affect their software.
The changes may range from bug fixes to new features. Snapshots are made
and released regularly. How regularly depends on whether the software
passes the tests done on each build. A possible version number for a
snapshot might be 1.9-snap81. This version would hold the 81st snapshot
off the 1.9 development branch (the current trunk). For the available
snapshots, see the “Downloads” page at
<a href="http://www.hdfgroup.org/downloads/index.html">
www.hdfgroup.org/downloads</a>.</p>
<h2>1. The Trunk, Release Branches, and Feature Branches</h2>
<p>The HDF Group uses a version control system to manage the HDF5
project. Within the system, a trunk and branches are used to track
changes. The version numbers described above identify where a given
piece of software was produced in the system. The figure below shows
the general scheme.</p>
<table align="center" width="750" border="0">
<tr valign="center" align="center">
<td>
<hr color="green" size="3"/>
<img height="400" src="TrunkAndBranches.jpg"
alt="The trunk, release branches, and feature branches"></td>
</tr>
<tr valign="center" align="left">
<td>
<hr color="green" size="1"/>
<b>Figure 1. The trunk, release branches, and feature branches</b>
<hr color="green" size="3"/>
</td>
</tr>
</table>
<p>The <b>trunk</b> is the center of the system. New features are
implemented in <b>feature branches</b> and aggregated in the trunk.
<b>Release branches</b> are then created from the trunk.</p>
<p>The minor version number of the trunk is always an odd number. From
the time of Release 1.8.0 to the first 1.10 release, the trunk will be
version 1.9. The trunk was version 1.7 from the time of release 1.6.0
until the first 1.8 release.</p>
<p>Projects that add new features, bug fixes, and performance improvements
are developed on <b>feature branches</b>. When a project is completed,
its feature branch is merged into the trunk. In the figure above, the
merging of a feature branch is represented by a dashed arrow from the
feature branch to the trunk. If a feature requires a file format change,
then the feature will stay in the trunk until the next significant
release. This would mean in the figure above that the new feature would
be released in a future 1.10 release branch. If a feature does not
require a file format change, then it might be merged into one or more
release branches. This would mean in the figure above that the new
feature could be merged into the 1.8 branch and could be included in
the 1.8.6 release. If the feature was added to the 1.8.5 branch, then a
patch version might be released.</p>
<p><b>Release branches</b> hold software that is distributed to general
users. In the figure above, a few release branches are shown below the
trunk. Work is done in release branches for a period of time. Branches
further from the trunk have less work done in them. For example, a patch
branch such as 1.8.5-patch1 may contain only one or two changes. A release
branch such as 1.8.5 may contain a number of bug fixes and new functions,
but these changes are small in number compared to the number of changes in
the 1.8 branch. </p>
<p>We aim to make available to the public two maintenance releases a year.
The releases occur usually in the spring near May 15 and in the fall near
November 15. If two release branches are being maintained, then
maintenance releases may be made for each release branch. For example,
there was a time when both the 1.6 and 1.8 branches were actively
maintained. In one maintenance release, the 1.6.10 and 1.8.4 versions were
released at the same time. The 1.6 and 1.8 branches were both actively
maintained to give early adopters access to new features and to give most
users plenty of time to make the change to 1.8 software from 1.6.</p>
<p>As we improve any branch, we consider the effect of any change on the
readability of objects. Applications built, for example, with version
1.8.5 will be able to read data files written with any prior version
of the library. So, a 1.8.5 application will be able to read a dataset
written with 1.4.5. A 1.8.5 application may be able to read a dataset
written under the 1.8.7 library if no new features, features not known
to 1.8.5, were used. For more information, see the discussion of
backward and forward compatibility in the FAQ at
<a href="http://www.hdfgroup.org/HDF5/faq/bkfwd-compat.html">
www.hdfgroup.org/HDF5/faq/bkfwd-compat.html</a>.</p>
<h2>2. Version Support from the Library</h2>
<p>The library provides macros and functions to query and check
version numbers.</p>
<p>The following constants are defined in the file <code>H5public.h</code>
and determine the version of the include files.</p>
<ul>
<li><code>H5_VERS_MAJOR</code></li>
<li><code>H5_VERS_MINOR</code></li>
<li><code>H5_VERS_RELEASE</code></li>
<li><code>H5_VERS_SUBRELEASE</code></li>
<li><code>H5_VERS_INFO</code></li>
</ul>
<p>The table below describes some of the function calls and macros
that can be used to query and check version numbers.</p>
<table width="600" cellspacing="0" align="center">
<tr valign="bottom">
<td colspan="2" align="left" valign="bottom">
<b>Table 1. Version function calls and macros</b></td>
</tr>
<tr><td colspan="2"><hr color="green" size="2" /></td></tr>
<tr valign="top">
<td width="35%">
<b>Function Call or Macro</b></td>
<td width="65%">
<b>Comments</b></td>
<tr><td colspan="2"><hr color="green" size="1" /></td></tr>
<tr valign="top">
<td><code>H5get_libversion</code></td>
<td>This function returns through its arguments the version
numbers for the library to which the application is linked.</td>
</tr>
<tr><td colspan="2"><hr color="green" size="1" /></td></tr>
<tr valign="top">
<td><code>H5check</code></td>
<td>This macro uses the <code>H5check_version</code> function
to verify 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. </td>
</tr>
<tr><td colspan="2"><hr color="green" size="1" /></td></tr>
<tr valign="top">
<td><code>H5check_version</code></td>
<td><p>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>.
If a mismatch is detected, it prints an error message on the standard
error stream and aborts.</p>
<p>The behavior of this function can be modified by the
<code>HDF5_DISABLE_VERSION_CHECK</code> environment variable. Setting
the environment variable to a value of ‘1’ will issue a
warning but continue without aborting. Setting the environment
variable to a value of ‘2’ will suppress the warning
and continue silently without aborting.</p></td>
</tr>
<tr><td colspan="2"><hr color="green" size="1" /></td></tr>
<tr valign="top">
<td><code>H5_VERSION_GE</code> and
<code>H5_VERSION_LE</code></td>
<td>These macros compare the version of the HDF5 library being used
against the version number specified in the parameters. At compile
time, they can be used to conditionally include or exclude code
based on the librarys version.</td>
</tr>
<tr><td colspan="2"><hr color="green" size="1" /></td></tr>
<tr valign="top">
<td><code>H5Pset_libver_bounds</code></td>
<td>This function can be used to control the versions of the object
formats that will be used when creating objects in a file. </td>
</tr>
<tr><td colspan="2"><hr color="green" size="2" /></td></tr>
</table>
<p>For more information on these and other function calls and macros,
see the <a href="../RM/RM_H5Front.html" target="RMwindow">
<cite>HDF5 Reference Manual</cite></a>. </p>
<h2>3. Use Cases</h2>
<p>The purpose of this section is to describe how some of the version
functions, macros, and constants might be used. </p>
<h3>3.1. Application Version Checking</h3>
<p>Suppose first that a developer builds an application that will read
from and write to an HDF5 file. When the application is compiled, a
version of the HDF5 Library such as 1.8.6 will be used. The version
constants (<code>H5_VERS_MAJOR</code>, <code>H5_VERS_MINOR</code>,
and <code>H5_VERS_RELEASE</code>) are included in the application when
it is compiled. </p>
<p>Suppose next that a user gets a copy of the application and starts it
up on a workstation. The executable is put into memory along with the
HDF5 Library. However, an application may only work successfully with
the version of the library with which the application was compiled. In
other words, the version of the library that is loaded when the application
is started must be the same version as the version of the library with
which the application was compiled. This is verified by the library when
the first HDF5 API routine is called. If an application wants to confirm
early in its startup procedure that the version of the library that will
be loaded into memory at the workstation will work with the application,
then it can use the <code>H5get_libversion</code> and
<code>H5check_version</code> function calls. </p>
<h3>3.2. Conditional Inclusions or Exclusions Based on the Version</h3>
<p>The <code>H5_VERSION_GE</code> and <code>H5_VERSION_LE</code> version
macros compare the version of the HDF5 Library being used against the
version number specified in the parameters. At compile time, they can be
used to conditionally include or exclude code based on the librarys
version. For example, the link functions, <code>H5Lxxx</code>, are
new in version 1.8, and some group functions, <code>H5Gxxx</code>,
are deprecated in 1.8. With the <code>H5_VERSION_GE</code> macro, an
application could use <code>H5Ldelete</code> if the library version is
1.8.0 or greater, or it could use <code>H5Gunlink</code> if the library
version is less than 1.8.0. </p>
<h3>3.3. Specifying a Format</h3>
<p>Suppose a data file has three datasets. It is possible that the three
datasets were added to the data file with applications using different
versions of HDF5. The different versions could be 1.4.5, 1.6.10, and
1.8.6. If another dataset is written to the data file, then it will be
written by default in the oldest format possible that has all of the
features needed to successfully write the dataset. If a newer feature
such as compact storage, a new parameter for a function, or a partially
compressed dataset is used, then a newer format will be used.
<code>H5Pset_libver_bounds</code> could be used to specify the oldest
format used. In the situation above, the owners of the data file might
want all data written to the file in the future to be in a 1.8 format
rather than 1.6 or 1.4. </p>
<br />
<hr />
<pre>
The HDF Group Help Desk: <img src="../Graphics/help.png" align=top height=14>
Last modified: 30 October 1998
Last modified: 27 March 2007 (Help Desk contact only)
Last modified: 9 June 2011
</pre>
<br /><br /><br />
</body>
</html>
|
