mirror of
https://github.com/HDFGroup/hdf5.git
synced 2024-11-21 01:04:10 +08:00
2b50ce6983
Description: Write documentation for building HDF5 with the latest version of Visual Studio, 2008. The process is very similar to building with Visual Studio 2005, but with an automatic project-file conversion beforehand. Also adapt commandline build scripts for Visual Studio 2008 as well. Tested: VS2008 on WinXP
1801 lines
67 KiB
Plaintext
1801 lines
67 KiB
Plaintext
|
|
***********************************************************************
|
|
* HDF5 Build and Install Instructions for Windows XP/VISTA *
|
|
* (Full Version) *
|
|
***********************************************************************
|
|
|
|
The following instructions assume that the HDF5 source code package from
|
|
HDF website (http://hdfgroup.org) is used.
|
|
|
|
Warnings:
|
|
Please read CAREFULLY about the following preconditions and notes first.
|
|
|
|
Contents:
|
|
|
|
Section : Preconditions and Notes
|
|
Section I : What do we build and install
|
|
Section II : How to build and test HDF5 libraries and tools
|
|
Section III : How to build examples (optional)
|
|
Section IV : How to build an application using the HDF5 library or DLL
|
|
Section V : How to disable Gzip(Zlib)/Szip compression
|
|
Section VI : How to build HDF5 with Fortran Support
|
|
Section VII : How to build Multi-threaded version of HDF5 library
|
|
Section VIII : How to build HDF5 with Thread-Safe Feature
|
|
Section IX : How to build HDF5 for 64-bit Windows
|
|
Section X : How to build HDF5 on Windows Vista
|
|
Section XI : How to build HDF5 using Visual Studio 2008
|
|
Section XII : Backwards Compatibility with HDF5 1.6
|
|
Section XIII : Misc.
|
|
|
|
|
|
========================================================================
|
|
Preconditions and Notes
|
|
========================================================================
|
|
|
|
Preconditions:
|
|
|
|
1. Installed Microsoft Visual Studio. This document is written for Visual
|
|
Studio 2005, although we also support Visual Studio .NET 2003 and Visual
|
|
Studio 2008 as well. Most of the instructions are the same, although some
|
|
features are unsupported in Visual Studio .NET. For simple Visual Studio
|
|
.NET instructions, see the document INSTALL_Windows_NET.TXT.
|
|
|
|
2. (Optional) Installed Intel Compiler 9.1 or 10.1 if you want to build HDF5
|
|
Fortran libraries.
|
|
|
|
3. Install Winzip or 7-zip for extracting source tarball.
|
|
|
|
Note: 1. 7zip is an open-source alternative to WinZip. Some of the
|
|
advanced functionality is disabled in WinZip unless you buy the
|
|
software. With 7zip, most of this functionality is included for
|
|
free.
|
|
|
|
2. By default, WinZip will convert the Unix end of line format when
|
|
extracting .tar file. This conversion will cause "false" failure
|
|
in some HDF5 tools testings.
|
|
|
|
Please uncheck the "TAR file smart CR/LF conversion" option in your
|
|
WinZip to prevent the conversion when extracting .tar file. To
|
|
uncheck the "TAR file smart CR/LF conversion" option:
|
|
|
|
Invoke WinZip, go to "Options", select "Configuration..."
|
|
|
|
Click the "Miscellaneous" tab and uncheck "TAR file smart CR/LF
|
|
conversion" option, then click OK.
|
|
|
|
4. Set up a directory structure to unpack the library. For example:
|
|
|
|
c:\ (any drive)
|
|
MyHDFstuff\ (any folder name)
|
|
|
|
5. Download the hdf5-1.8.x source code package and use 7zip or WinZip to
|
|
extract the HDF5 package into c:\MyHDFstuff. This creates a directory
|
|
called 'hdf5-1.8.x' under MyHDFstuff which contains several files and
|
|
directories. Rename "hdf5-1.8.x" to "hdf5".
|
|
|
|
6. HDF5 provide options to do in-memory compression within HDF5 library.
|
|
Currently, two external compression libraries Zlib and Szip can be used
|
|
with HDF5.
|
|
|
|
6.1 HDF5 uses Zlib version 1.2.3 for compression and Zlib is NOT
|
|
distributed with HDF5 library in 1.8.x release. To use Zlib library,
|
|
you have to install your own Zlib DLL library or go to
|
|
ftp://ftp.hdfgroup.org/lib-external/zlib/1.2/bin/windows
|
|
to download the Zlib library.
|
|
|
|
|
|
6.2 HDF5 uses Szip version 2.1 for compression and Szip compression
|
|
software is provided with HDF5 products in 1.8.1 release. To use
|
|
Szip 2.1 library, you can download Szip source codes and binaries from
|
|
ftp://ftp.hdfgroup.org/lib-external/szip/2.1/bin/windows
|
|
|
|
Please note that Szip is not a totally open-source free software.
|
|
For licensing issue of Szip, please check "Licensing terms" at
|
|
http://hdfgroup.org/doc_resource/SZIP/index.html.
|
|
|
|
Szip compression feature inside HDF5 is optional.
|
|
|
|
7. Define the following environment variables:
|
|
|
|
HDF5_EXT_ZLIB
|
|
HDF5_EXT_SZIP
|
|
|
|
In this section, Zlib and Szip compression packages are assumed to be
|
|
used. Please read Section V as well as this section if you do not want
|
|
to use compression feature inside HDF5.
|
|
|
|
To define these environment variables:
|
|
|
|
Click "Start", click "Control Panel", and then double-click "System".
|
|
On the "Advanced" tab, click "Environment Variables".
|
|
|
|
If you are logged on as administrator to the local computer AND want to
|
|
let all other users use these two environment variables, click "New"
|
|
under "System Variables" box; otherwise, click "New" under "User
|
|
Variables" box.
|
|
|
|
In the New Variable window, set "Variable name" as HDF5_EXT_ZLIB and
|
|
"Variable value" as zlib1.lib, then click OK.
|
|
|
|
Similarly, you can set:
|
|
|
|
HDF5_EXT_SZIP environment variable as szlibdll.lib
|
|
|
|
Notes:
|
|
|
|
a. You will have to close and reopen running programs for the new
|
|
environment variable settings to take effect.
|
|
|
|
b. c:\zlib123\zlib1.dll and c:\szip\dll\szlibdll.dll should be copied
|
|
into the location that the application can find, one suggestion is
|
|
to use the c:\WINDOWS\system.
|
|
|
|
6. Set up path for external libraries and headers
|
|
|
|
Skip this part if you don't want to use ANY compression features provided
|
|
by HDF5. Please do read Section V.
|
|
|
|
You have to read this part even if you want to only use Zlib or Szip.
|
|
You also need to read Section V.
|
|
|
|
Invoke Microsoft Visual Studio and go to "Tools" and select "Options",
|
|
find "Projects", and then "VC++ Directories".
|
|
|
|
6.1 If you are building on 64-bit Windows, find the "Platform" dropdown
|
|
and select "x64".
|
|
|
|
6.2 Find the box "Show directories for", choose "Include files", if you
|
|
can not find your Zlib and Szip header path (for example,
|
|
c:\zlib123\include, c:\szip\include) from the directory list, add the
|
|
header path (c:\zlib123\include, c:\szip\include) to the included
|
|
directories.
|
|
|
|
6.3 Find the box "Show directories for", choose "Library files". If you
|
|
cannot find your Zlib and Szip library path (for example,
|
|
c:\zlib123\dll, c:\szip\dll) from the directory list, add the library
|
|
path (c:\zlib123\dll, c:\szip\dll) to the library directories.
|
|
|
|
6.4 If building Fortran libraries, you will also need to setup the path
|
|
for the Intel Fortran compiler. Please see Section VI.
|
|
|
|
Notes:
|
|
|
|
1. As of 1.8.0, all.zip is deprecated. Users should go to hdf5/windows
|
|
directory, run copy_hdf.bat first and then open all.sln under
|
|
hdf5/windows/proj/all to start building process.
|
|
|
|
2. Visual Studio 6.0 will not be supported in HDF5 1.8 or later release.
|
|
|
|
2. Users who prefer to use Visual Studio .NET can follow instructions in
|
|
INSTALL_Windows_Short_Net.txt. Note, however, HDF5 Fortran product
|
|
will not be supported in HDF5 1.8 release with Visual Studio .NET.
|
|
|
|
3. For users who want to quickly build HDF5 library or do not want to know
|
|
HDF5 building and installation details, please read the
|
|
INSTALL_Windows_Short_***.txt relating to your compiler.
|
|
|
|
4. For users who would like to build and test HDF5 package from the command
|
|
line, please read INSATLL_Windows_From_Command_Line.txt.
|
|
|
|
5. HDF4-related tools are not built and released with HDF5 library packages
|
|
any more. To obtain HDF4 related tools, please check
|
|
http://hdfgroup.org/h4toh5/ and ftp://ftp.hdfgroup.org/HDF5/h4toh5
|
|
|
|
6. For Fortran users, Intel fortran Compiler 9.1 and 10.1 is currently
|
|
supported-- please see Section VI. Intel Compiler verion 7.x and 8.x are
|
|
no longer supported.
|
|
|
|
7. For users who would like to build Muti-threaded version of HDF5 library,
|
|
please read Section VII.
|
|
|
|
8. To build HDF5 in Visual Studio 2008, be sure to read the instructions in
|
|
Section XI.
|
|
|
|
|
|
========================================================================
|
|
Section I: What do we build and install?
|
|
========================================================================
|
|
|
|
1. Build and Install
|
|
|
|
HDF5 static library:
|
|
debug and release version
|
|
|
|
HDF5 Dynamic Link Library(DLL):
|
|
debug and release version as well as export libraries for DLL
|
|
|
|
HDF5 High-Level Library (Optional):
|
|
HDF5 C++ Library
|
|
HDF5 HL-Fortran Library
|
|
|
|
HDF5 tools:
|
|
HDF5 tools
|
|
|
|
2. Build Only (Not included in the binary distribution)
|
|
|
|
HDF5 tool library:
|
|
debug and release version
|
|
|
|
HDF5 tool export library for DLL:
|
|
debug and release version
|
|
|
|
HDF5 library testing programs:
|
|
HDF5 library comprehensive tests
|
|
|
|
HDF5 related tools testing programs:
|
|
HDF5 tools comprehensive tests
|
|
|
|
3. Examples (Not included in the binary distribution)
|
|
|
|
HDF5 examples:
|
|
Simple HDF5 C/C++/Fortran and High level C/Fortran examples
|
|
|
|
========================================================================
|
|
Section II: How to build and test HDF5 libraries and tools
|
|
========================================================================
|
|
|
|
Note:
|
|
To build and test HDF5 with Fortran support, please read over Section VI.
|
|
|
|
|
|
STEP 1: Building HDF5 Libraries and Tools
|
|
|
|
|
|
1. Run batch file copy_hdf.bat
|
|
|
|
Go to c:\MyHDFstuff\hdf5\windows and run copy_hdf.bat. This process will
|
|
copy all the necessary batch files, Windows-specific source code and
|
|
text files saved under c:\MyHDFstuff\hdf5\windows directory to the
|
|
corresponding directories under hdf5.
|
|
|
|
2. Open the HDF5 library project in Visual Studio
|
|
|
|
Invoke Microsoft Visual Studio. From the main menu, go to "File" and
|
|
select the "Open Solution" option. Then open the
|
|
c:\MyHDFstuff\hdf5\windows\proj\all\all.sln solution.
|
|
|
|
You should find Windows project files listed as "all", "big", etc. on the
|
|
left.
|
|
|
|
3. (Optional) Disable HDF5 C++ and High level C++
|
|
|
|
In HDF5 1.8, C++ and HL C++ libraries are built by default. To opt-out,
|
|
you must explicitly disable them.
|
|
|
|
3.1 Skip this step if you do want to build HDF5 High-Level C++ libraries
|
|
|
|
Go to "Project" and select "Project Dependencies". Select "all", and
|
|
disable all of the following projects:
|
|
|
|
hdf5_hl_cpp
|
|
hdf5_hl_cppdll
|
|
hl_test_table_cpp
|
|
hl_test_table_cppdll
|
|
|
|
3.2 Skip this step if you do want to build HDF5 High-Level libraries
|
|
|
|
Go to "Project" and select "Project Dependencies". Select "all", and
|
|
disable all of the project files listed in the previous step, as well
|
|
as the following projects:
|
|
|
|
hdf5_hl
|
|
hdf5_hldll
|
|
hl_test_image
|
|
hl_test_imagedll
|
|
hl_test_lite
|
|
hl_test_litedll
|
|
hl_test_table
|
|
hl_test_tabledll
|
|
hl_test_ds
|
|
hl_test_dsdll
|
|
hl_test_packet
|
|
hl_test_packetdll
|
|
|
|
Note: Disabling some projects will likely produce false errors in the
|
|
testing script. Check the output carefully to ensure that the
|
|
errors are related to the disabled projects, and then safely
|
|
ignore them.
|
|
|
|
|
|
4. Select "Build", then Select "Configuration Manager".
|
|
|
|
4.1 To build debug static libraries, debug multithreaded DLLs, and tests:
|
|
|
|
In "Active Solution Configuration", select "Debug". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build debug
|
|
version of project "all".
|
|
|
|
4.2 To build release static libraries, multithreaded DLLs and tests:
|
|
|
|
In "Active Solution Configuration", select "Release". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build release
|
|
version of project "all".
|
|
|
|
Both debug and release versions must be built for testing.
|
|
|
|
Warning messages can be ignored.
|
|
|
|
When the debug or release build is done the directories
|
|
listed below will contain the following files:
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5\debug -
|
|
|
|
hdf5d.lib- the hdf5 static library
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5\release -
|
|
|
|
hdf5.lib- the hdf5 static library
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5dll\debug -
|
|
|
|
hdf5ddll.dll- DLL
|
|
hdf5ddll.lib- the DLL export library
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5dll\release -
|
|
|
|
hdf5dll.dll- DLL
|
|
hdf5dll.lib- the DLL export library
|
|
|
|
c:\MyHDFstuff\hdf5\test\libtest\debug -
|
|
and c:\MyHDFstuff\hdf5\test\libtest\release -
|
|
|
|
libtest.lib - the internal library for test
|
|
|
|
c:\MyHDFstuff\hdf5\test\libtestdll\debug -
|
|
|
|
libtestddll.dll - the internal DLL for test
|
|
libtestddll.lib - the internal DLL export library for test
|
|
|
|
c:\MyHDFstuff\hdf5\test\libtestdll\release -
|
|
|
|
libtestdll.dll - the internal DLL for test
|
|
libtestdll.lib - the internal DLL export library for test
|
|
|
|
c:\MyHDFstuff\hdf5\tools\toolslib\debug -
|
|
and c:\MyHDFstuff\hdf5\tools\toolslib\release -
|
|
|
|
toolslib.lib- the internal tools library
|
|
|
|
c:\MyHDFstuff\hdf5\tools\toolslibD\debug -
|
|
and c:\MyHDFstuff\hdf5\tools\toolslibD\release -
|
|
|
|
toolslibD.dll- DLL
|
|
toolslibD.lib- the internal DLL export library for tools
|
|
|
|
c:\MyHDFstuff\hdf5\tools\"tools directory"-
|
|
where tools are located
|
|
|
|
The directories listed below will contain the following files
|
|
ONLY when you choose to build HDF5 C++ libraries:
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5_cpp\debug -
|
|
|
|
hdf5_cppd.lib- the HDF5 C++ API static library
|
|
|
|
and c:\MyHDFstuff\hdf5\proj\hdf5_cpp\release -
|
|
|
|
hdf5_cpp.lib- the HDF5 C++ API static library
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5_cppdll\debug -
|
|
|
|
hdf5_cppddll.dll- the HDF5 C++ API DLL
|
|
hdf5_cppddll.lib - the C++ API export library
|
|
|
|
and c:\MyHDFstuff\hdf5\proj\hdf5_cppdll\release -
|
|
|
|
hdf5_cppdll.dll- the HDF5 C++ API DLL
|
|
hdf5_cppdll.lib- the C++ API DLL export library
|
|
|
|
|
|
The directories listed below will contain the following files
|
|
ONLY when you choose to build HDF5 High Level libraries:
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5_hl\Release -
|
|
hdf5_hl.lib - HDF5 High Level static Library
|
|
|
|
and c:\MyHDFstuff\hdf5\proj\hdf5_hl\Debug -
|
|
|
|
hdf5_hld.lib - HDF5 High Level Static Library
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5_hldll\Release -
|
|
hdf5_hldll.dll - HDF5 High Level DLL
|
|
hdf5_hldll.lib - HDF5 High Level export Library
|
|
|
|
and c:\MyHDFstuff\hdf5\proj\hdf5_hldll\Debug -
|
|
|
|
hdf5_hlddll.dll - HDF5 High Level DLL
|
|
hdf5_hlddll.lib - HDF5 High Level export Library
|
|
|
|
The directories listed below will contain the following files
|
|
ONLY when you choose to build HDF5 High Level C++ libraries:
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5_hl_cpp\Release -
|
|
|
|
hdf5_hl_cpp.lib - HDF5 High Level C++ Static Library
|
|
|
|
and c:\MyHDFstuff\hdf5\proj\hdf5_hl_cpp\Debug -
|
|
|
|
hdf5_hl_cppd.lib - HDF5 High Level C++ Static Library
|
|
|
|
c:\MyHDFstuff\hdf5\proj\hdf5_hl_cppdll\Release -
|
|
and c:\MyHDFstuff\hdf5\proj\hdf5_hl_cppdll\Debug -
|
|
|
|
hdf5_hl_cppddll.dll - HDF5 High Level C++ DLL
|
|
hdf5_hl_cppddll.lib - HDF5 High Level C++ export Library
|
|
|
|
|
|
STEP 2: Testing HDF5 Libraries and Tools
|
|
|
|
HDF5 libraries and tools should be tested to make sure that they were built
|
|
correctly.
|
|
|
|
Note: The complete testing suite can take a long time to run on even fast
|
|
machines. Some of the longer tests can be automatically shortened by
|
|
defining an environment variable HDF5TestExpress. Set HDF5TestExpress
|
|
to 3 for fastest, or 0 for slowest. For example:
|
|
|
|
set HDF5TestExpress=3
|
|
|
|
If the variable is unset, it takes on the value 1. Note that when
|
|
HDF5TestExpress is set to 2 or 3, some features may not be thoroughly
|
|
tested. For most users, we recommend not setting this variable.
|
|
|
|
|
|
We provide 2 options for users to test HDF5 libraries and tools.
|
|
|
|
Option 1: Automatic testings
|
|
|
|
HDF5 comes with various test suites, all of which can be tested with
|
|
hdf5check.bat batch file in c:\MyHDFstuff\hdf5 directory.
|
|
|
|
hdf5check batch file can be run with one of the following four options:
|
|
|
|
hdf5check Test HDF5 C library and tools only.
|
|
|
|
hdf5check enablecpp Test HDF5 C/C++ libraries and tools. To use
|
|
this option, HDF5 C++ libraries must have been
|
|
built in step I.
|
|
|
|
hdf5check enablefortran Test HDF5 C/Fortran libraries and tools. To
|
|
use this option, HDF5 Fortran libraries must
|
|
have been built in Section VI.
|
|
|
|
hdf5check enableall Test HDF5 C/C++/Fortran libraries and tools.
|
|
To use this option, HDF5 C++ and Fortran
|
|
libraries must have been built.
|
|
|
|
Invoke a command prompt window and run hdf5check with appropriate option.
|
|
Users are encouraged to pipe the test output into a file. You should find
|
|
no "*FAILED*" marks.
|
|
|
|
Option 2: Step-by-step HDF5 libraries and tools testings
|
|
|
|
You can also test HDF5 libraries and tools one by one. There are possibly
|
|
four versions of HDF5 libraries and tools testings.
|
|
|
|
They are:
|
|
|
|
release
|
|
release dll
|
|
debug
|
|
debug dll
|
|
|
|
We strongly suggest you to redirect your testing results into an output file
|
|
so that you can easily check the testing results.
|
|
|
|
HDF5 DLLs should be placed into the Windows system directory. A batch file
|
|
named install_dll.bat is included in c:\MyHDFstuff\hdf5 directory. Run this
|
|
batch file and all neccessary HDF5 DLLS will be placed in the system
|
|
directory.
|
|
|
|
|
|
1. HDF5 library testing
|
|
|
|
Open a command prompt in the hdf5\test directory
|
|
|
|
(1) Basic tests
|
|
|
|
a) Release Static, type:
|
|
checktests release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checktests release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checktests debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checktests debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
2. HDF5 performance testing
|
|
|
|
Open a command prompt in the hdf5\perform directory
|
|
|
|
a) Release Static, type:
|
|
checkperformtests release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checkperformtests release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checkperformtests debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checkperformtests debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
3. HDF5 tools testing
|
|
|
|
Open a command prompt in the hdf5\tools directory
|
|
|
|
a) Release Static, type:
|
|
checktools release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checktools release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checktools debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checktools debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
4. HDF5 C++ library test
|
|
|
|
Skip this step UNLESS you have built HDF5 C++ libraries and want to test
|
|
them.
|
|
|
|
Open a command prompt in the hdf5\c++\test directory
|
|
|
|
a) Release Static, type:
|
|
checkcpptests release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checkcpptests release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checkcpptests debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checkcpptests debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
4. HDF5 High-Level library test
|
|
|
|
Skip this step UNLESS you have built HDF5 High-Level libraries and want to
|
|
test them.
|
|
|
|
Open a command prompt in the hdf5\hl\test directory
|
|
|
|
a) Release Static, type:
|
|
checkhltests release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checkhltests release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checkhltests debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checkhltests debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
5. HDF5 High-Level C++ library test
|
|
|
|
Skip this step UNLESS you have built HDF5 High-Level C++ libraries and want
|
|
to test them.
|
|
|
|
Open a command prompt in the hdf5\hl\c++\test directory
|
|
|
|
a) Release Static, type:
|
|
checkhlcpptests release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checkhlcpptests release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checkhlcpptests debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checkhlcpptests debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
Note: See Section VI for instructions on testing Fortran libraries.
|
|
|
|
STEP 3: Installing HDF5 Libraries
|
|
|
|
We provide a batch file for users to relocate all HDF5 libraries in one folder
|
|
(C++ and Fortran libraries will also be copied into this folder if they have
|
|
been built in step I or Section VI, respectively). The file is called
|
|
installhdf5lib.bat under c:\MyHDFstuff\hdf5 directory. Run the batch file, you
|
|
may see a folder called hdf5lib under c:\MyHDFstuff\hdf5.
|
|
|
|
The <release> layout of <hdf5lib> should be:
|
|
|
|
release\include -- HDF5 header files
|
|
release\bin -- HDF5 static tool executables
|
|
release\bindll -- HDF5 DLL tool executables
|
|
release\lib -- HDF5 static libraries
|
|
release\dll -- HDF5 DLLs
|
|
|
|
You may also find the similar layout for the <debug>.
|
|
|
|
========================================================================
|
|
Section III: How To Build Examples (Optional)
|
|
========================================================================
|
|
|
|
Simple examples have been provided for users to test HDF5 C/C++/Fortran and
|
|
High level C/Fortran library and tools.
|
|
|
|
Note:
|
|
1) To build HDF5 C++ examples, HDF5 C++ library must have been built in
|
|
Step I.
|
|
|
|
2) To build HDF5 Fortran or HL Fortran examples, please see Section VI,
|
|
Step 3.
|
|
|
|
3) To build HDF5 High Level C examples, HDF5 High level library must have
|
|
been built in step I.
|
|
|
|
4) By default, the debug versions of HDF5 C/C++/HL examples are linked
|
|
with the debug versions of HDF5 C/C++/HL libraries and DLLs. The
|
|
debug versions of HDF5 C/C++/HL examples will fail if they are linked
|
|
with HDF5 binary distribution, which only includes the release
|
|
versions of HDF5 C/C++ libraries and DLLs.
|
|
|
|
To build and test HDF5 C examples:
|
|
----------------------------------
|
|
1. Invoke Microsoft Visual Studio, go to "File" and select the "Open
|
|
Solution" option.
|
|
|
|
Then open the solution
|
|
c:\MyHDFstuff\hdf5\windows\examples\allexamples\allexamples.sln.
|
|
|
|
2. Select "Build", and "Configuration Manager".
|
|
|
|
2.1 To build debug versions of C examples:
|
|
|
|
In "Active Solution Configuration", select "Debug". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
debug version of project "allexamples".
|
|
|
|
2.2 To build release versions of C examples.
|
|
|
|
In "Active Solution Configuration", select "Release". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
release version of project "allexamples".
|
|
|
|
When the debug and release build is done, there should be the following
|
|
subdirectories in c:\MyHDFstuff\hdf5\examples\
|
|
|
|
attributetest
|
|
attributetestdll
|
|
chunkread
|
|
chunkreaddll
|
|
compoundtest
|
|
compoundtestdll
|
|
extendwritetest
|
|
extendwritetestdll
|
|
grouptest
|
|
grouptestdll
|
|
readtest
|
|
readtestdll
|
|
selectest
|
|
selectestdll
|
|
writetest
|
|
writetestdll
|
|
|
|
3. Invoke a command prompt window and run the batch file InstallExamples.bat
|
|
which resides in the top level directory (c:\MyHDFstuff\hdf5). This file
|
|
creates 4 new directories, examplesREL, examplesRELDLL, examplesDBG, and
|
|
examplesDBGDLL, in the c:\MyHDFstuff\hdf5\examples directory and places
|
|
all the executables in it. Both the release and debug versions of the
|
|
examples should be built before this step is done.
|
|
|
|
4. We provide a batch file named testExamples.bat and an expected examples
|
|
tests output file named testExamples_exp_output.txt in
|
|
c:\MyHDFstuff\hdf5\examples directory for you to test HDF5 C examples.
|
|
|
|
testExamples.bat batch file has 4 options:
|
|
|
|
testExamples release -- for release version
|
|
|
|
testExamples release dll -- for release DLL version
|
|
|
|
testExamples debug -- for debug version
|
|
|
|
testExamples debug dll -- for debug DLL version
|
|
|
|
Invoke a command prompt and run testExamples.bat with appropriate options.
|
|
You should get "All HDF5 C examples tests passed." when the C examples are
|
|
built successfully. Otherwise, the difference between the expected
|
|
outputs and actual outputs will be given.
|
|
|
|
To build and test HDF5 C++ examples:
|
|
------------------------------------
|
|
|
|
1. Invoke Microsoft Visual Studio, go to "File" and select the "Open
|
|
Solution" option.
|
|
|
|
Then open the solution
|
|
c:\MyHDFstuff\hdf5\windows\examples\allexamples\allcppexamples.sln.
|
|
|
|
2. Select "Build", and "Configuration Manager".
|
|
|
|
2.1 To build debug versions of C examples:
|
|
|
|
In "Active Solution Configuration", select "Debug". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
debug version of project "allcppexamples".
|
|
|
|
2.2 To build release versions of C examples.
|
|
|
|
In "Active Solution Configuration", select "Release". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
release version of project "allcppexamples".
|
|
|
|
When the debug build or release build is done, there should be the following
|
|
subdirectories in c:\MyHDFstuff\hdf5\c++\examples\
|
|
|
|
chunks
|
|
chunksdll
|
|
compound
|
|
compounddll
|
|
create
|
|
createdll
|
|
extend_ds
|
|
extend_dsll
|
|
h5group
|
|
h5groupdll
|
|
readdata
|
|
readdatadll
|
|
writedata
|
|
writedatadll
|
|
|
|
3. Invoke a command prompt window and run the batch file
|
|
InstallcppExamples.bat which resides in the top level directory
|
|
(c:\MyHDFstuff\hdf5). This file creates 4 new directories,
|
|
cppexamplesREL, cppexamplesRELDLL, cppexamplesDBG, and cppexamplesDBGDLL,
|
|
in the c:\MyHDFstuff\c++\examples directory and places all the executables
|
|
in it. Both the release and debug versions of the examples should be
|
|
built before this step is done.
|
|
|
|
4. We provide a batch file named testcppExamples.bat in
|
|
c:\MyHDFstuff\hdf5\c++\examples directory for you to test HDF5 C++
|
|
examples.
|
|
|
|
testcppExamples.bat batch file has 4 options:
|
|
|
|
testcppExamples release -- for release version
|
|
|
|
testcppExamples release dll -- for release DLL version
|
|
|
|
testcppExamples debug -- for debug version
|
|
|
|
testcppExamples debug dll -- for debug DLL version
|
|
|
|
Invoke a command prompt and run testcppExamples.bat with appropriate
|
|
options. You should get "All HDF5 C++ examples tests passed." when the
|
|
C++ examples are built successfully. Otherwise, the difference between
|
|
the expected outputs and actual outputs will be given.
|
|
|
|
|
|
To build and test HDF5 High Level C examples:
|
|
---------------------------------------------
|
|
|
|
1. Invoke Microsoft Visual Studio, go to "File" and select the "Open
|
|
Solution" option.
|
|
|
|
Then open the solution
|
|
c:\MyHDFstuff\hdf5\windows\hl\examples\allhlcexamples\allhlcexamples.dsw
|
|
|
|
2. Select "Build", and "Configuration Manager".
|
|
|
|
2.1 To build debug versions of C examples:
|
|
|
|
In "Active Solution Configuration", select "Debug". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
debug version of project "allhlcexamples".
|
|
|
|
2.2 To build release versions of C examples.
|
|
|
|
In "Active Solution Configuration", select "Release". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
release version of project "allhlcexamples".
|
|
|
|
When the debug and release build is done, binaries will be built in the
|
|
following subdirectories of c:\MyHDFstuff\hdf5\examples\
|
|
|
|
ex_image[1-2](dll)
|
|
ex_lite1(dll)
|
|
ex_table[01-12](dll)
|
|
ex_ds1(dll)
|
|
ptExample[FL+VL](dll)
|
|
|
|
3. Invoke a command prompt and run the batch file Install_hlcexamples.bat
|
|
which resides in the top level directory (c:\MyHDFstuff\hdf5). This file
|
|
creates 4 new directories, HLCexamplesRELEASE, HLCexamplesRELEASEDLL,
|
|
HLCexamplesDEBUG, and HLCexamplesDEBUGDLL, in the
|
|
c:\MyHDFstuff\hdf5\hl\examples directory and places all the executables in
|
|
it. Both the release and debug versions of the examples should be built
|
|
before this step is done.
|
|
|
|
4. We provide a batch file named test_hl_cexamples.bat in
|
|
c:\MyHDFstuff\hdf5\hl\examples directory for you to test HDF5 high level C
|
|
examples.
|
|
|
|
test_hl_cexamples.bat batch file has 4 options:
|
|
|
|
Options purpose
|
|
|
|
test_hl_cexamples release -- for release version
|
|
|
|
test_hl_cexamples release dll -- for release DLL version
|
|
|
|
test_hl_cexamples debug -- for debug version
|
|
|
|
test_hl_cexamples debug dll -- for debug DLL version
|
|
|
|
Invoke a command prompt window and run test_hl_cexamples with
|
|
appropriate options.
|
|
|
|
Invoke a command prompt and run testExamples.bat with appropriate options.
|
|
You should get "All of the HL C Examples Passed!" when the HL C examples
|
|
are built successfully. Otherwise, the difference between the expected
|
|
outputs and actual outputs will be given.
|
|
|
|
|
|
========================================================================
|
|
Section IV: Building an application using the HDF5 library or DLL
|
|
========================================================================
|
|
|
|
Waring: The instructions below will only describe how to build an application
|
|
using the release version of the HDF5 library or DLL. To use the debug
|
|
version of the HDF5 library or DLL, you need to substitute the release
|
|
version of the HDF5 library or DLL with the debug version.
|
|
|
|
|
|
To build an application that uses the HDF5 static library the following
|
|
locations will need to be specified for locating header files and linking with
|
|
the HDF static library, for example:
|
|
|
|
c:\MyHDFstuff\hdf5\hdf5lib\release\include
|
|
c:\MyHDFstuff\hdf5\hdf5lib\release\lib
|
|
|
|
We assume that you will use Zlib and Szip compression with HDF5 library.
|
|
|
|
1. Specifying Include Directories
|
|
|
|
To specify the include directories in the settings for your Visual Studio
|
|
project, you may choose one of the following two methods.
|
|
|
|
Method One: Project-wide Settings
|
|
|
|
1. Open your project in Microsoft Visual Studio and make sure it is the
|
|
active project.
|
|
|
|
2. Go to the Project menu and chose the "Properties" option.
|
|
|
|
3. Choose the build configuration you would like to modify in the drop
|
|
down menu labeled "Configuration:"
|
|
|
|
4. Choose the "C/C++" tab, anc select "General".
|
|
|
|
5. In a text-area labeled with "Additional Include Directories:", add
|
|
HDF5, Zlib, and Szip header files directories. For example:
|
|
|
|
c:\MyHDFstuff\hdf5\hdf5lib\release\include
|
|
c:\zlib123\include
|
|
c:\szip\include
|
|
|
|
Then click OK.
|
|
|
|
6. (Optional) To use HDF5 Fortran static library, the location of
|
|
Fortran module files should be specified by following Project->
|
|
Settings->Fortran->Preprocessor, and in the text-area labeled
|
|
"Additional Include Directories", add HDF5 Fortran module files
|
|
directories. For example:
|
|
|
|
c:\MyHDFstuff\hdf5\hdf5lib\release\include
|
|
|
|
Method Two: Visual Studio Settings
|
|
|
|
1. In Visual STudio, go to Tools->Options->Projects->
|
|
VC++ Directories. Under "Show Directories For", select "Include files"
|
|
|
|
2. Insert the correct HDF5, Zlib, Szip paths for headers(include). For
|
|
example,
|
|
|
|
c:\MyHDFstuff\hdf5\hdf5lib\release\include
|
|
c:\zlib123\include
|
|
c:\szip\include
|
|
|
|
|
|
2. Specifying Library Directories
|
|
|
|
To specify the library directories in the settings for your Visual Studio
|
|
project, you may choose one of the following two methods.
|
|
|
|
Method One: Project-wide Settings
|
|
|
|
1. Open your project in Microsoft Visual Studio and make sure it is the
|
|
active project.
|
|
|
|
2. Go to the Project menu and chose the "Properties" option.
|
|
|
|
3. Choose the build configuration you would like to modify in the drop
|
|
down menu labeled "Configuration:"
|
|
|
|
4. Choose the "Linker" tab, anc select "General".
|
|
|
|
5. In a text-area labeled with "Additional Library Directories:", add
|
|
HDF5, Zlib, and Szip library files directories. For example:
|
|
|
|
c:\MyHDFstuff\hdf5\hdf5lib\release\lib
|
|
c:\zlib123\dll
|
|
c:\szip\dll
|
|
|
|
Note: To link with HDF5 DLLs rathern that static libraries, simply
|
|
specify the "dll" directory rather than "lib", and link with the
|
|
corresponding DLL link library below.
|
|
|
|
Then click OK.
|
|
|
|
|
|
Method Two: Visual Studio Settings
|
|
|
|
1. In Visual STudio, go to Tools->Options->Projects->
|
|
VC++ Directories. Under "Show Directories For", select "Library files"
|
|
|
|
2. Insert the correct HDF5, Zlib, Szip paths for link libraries. For
|
|
example,
|
|
|
|
c:\MyHDFstuff\hdf5\hdf5lib\release\lib
|
|
c:\zlib123\dll
|
|
c:\szip\dll
|
|
|
|
Note: To link with HDF5 DLLs rathern that static libraries, simply
|
|
specify the "dll" directory rather than "lib", and link with the
|
|
corresponding DLL link library below.
|
|
|
|
|
|
3. Specifying Libraries to Link
|
|
|
|
To link the HDF5 static library with your application:
|
|
|
|
1. In Visual Studio, go to the Project menu and choose "Properties".
|
|
|
|
2. Find the "Link" option and "Input" category. In the "Additional
|
|
Dependencies" field, insert "zdll.lib, szlibdll.lib, hdf5.lib".
|
|
|
|
3. (Optional) Also insert "hdf5_cpp.lib" if you want to use HDF5 C++
|
|
static library.
|
|
|
|
4. (Optional) Also insert "hdf5_fortran.lib" if you want to use HDF5
|
|
Fortran static library.
|
|
|
|
5. (Optional) Also insert "hdf5_hl.lib" if you want to use HDF5 high
|
|
level static library.
|
|
|
|
6. (Optional) Also insert "hdf5_hl_cpp.lib" if you want to use HDF5 High
|
|
Level C++ static library.
|
|
|
|
7. (Optional) Also insert "hdf5_hl_fortran.lib" if you want to use HDF5
|
|
High Level Fortran static library.
|
|
|
|
|
|
To link the HDF5 DLL library with your application:
|
|
|
|
1. Follow the steps for linking the HDF5 static library as shown above,
|
|
except now link the export library that is created with the DLL.
|
|
|
|
The export library is called hdf5dll.lib for HDF5 C libray,
|
|
hdf5_cppdll.lib for HDF5 C++ library, and hdf5_fortrandll.lib
|
|
for HDF5 Fortran library.
|
|
|
|
2. In the Project Properties dialog, go to the C/C++ > Preprocessor
|
|
subsection. In the "Preprocessor Definitions" box, add "_HDF5USEDLL_"
|
|
to the list.
|
|
|
|
3. (Optional) Also add HDF5CPP_USEDLL to use HDF5 C++ DLL.
|
|
|
|
4. (Optional) Also add _HDF5USEHLDLL_ to use HDF5 high level DLL.
|
|
|
|
5. (Optional) Also add HDF5USE_HLCPPDLL use HDF5 high level C++ DLL.
|
|
|
|
6. (Optional) Follow Project->Settings->Fortran->Category->General->
|
|
Predefined Preprocess or Symbols, and add "HDF5F90_WINDOWS" to use HDF5
|
|
Fortran DLL.
|
|
|
|
7. Place the DLLs in a location that Windows will be able to locate. The
|
|
searched path and order for DLL's is
|
|
|
|
a) The directory where the executable module for the current
|
|
process is located.
|
|
b) The current directory.
|
|
c} The Windows system directory. The GetSystemDirectory function
|
|
retrieves the path of this directory.
|
|
d) The Windows directory. The GetWindowsDirectory function
|
|
retrieves the path of this directory.
|
|
e) The directories listed in the PATH environment variable.
|
|
|
|
========================================================================
|
|
Section V: How to disable Gzip(Zlib)/Szip compression
|
|
========================================================================
|
|
|
|
Warning: When you modify the H5pubconf.h file as described below, DO NOT just
|
|
change the values of these macros from 1 to 0. Please DO remove (or
|
|
comment out) appropriate lines.
|
|
|
|
Notes:
|
|
|
|
To disable Gzip and Szip at the same time, just make the appropriate
|
|
modifications to H5pubconf.h and the environmental variables all together,
|
|
and then Run-compile.
|
|
|
|
These instructions assume that copy_hdf.bat has already been run in Section
|
|
II. If you can't find H5pubconf.h file in the specified directory, please
|
|
verify that this script has been run.
|
|
|
|
1. Disable Gzip (Zlib) Compression
|
|
|
|
If you would like to remove Gzip compression from the HDF5 library, follow
|
|
the steps below.
|
|
|
|
1.1 Open the H5pubconf.h file from the c:\MyHDFstuff\hdf5\src directory
|
|
and remove (or comment out) the following two lines:
|
|
|
|
#define H5_HAVE_ZLIB_H 1
|
|
#define H5_HAVE_FILTER_DEFLATE 1
|
|
|
|
Then save the file.
|
|
|
|
1.2 Delete HDF5_EXT_ZLIB environment variable if you have set it in
|
|
preconditions.
|
|
|
|
1.3 Run-compile HDF5 library according to Section II.
|
|
|
|
When you disable Gzip, you may get the following message when building
|
|
HDF5 libraries: "The following environment variables were not found:
|
|
$(HDF5_EXT_ZLIB)". This message can be ignored.
|
|
|
|
2. Disable Szip Compression (both encoder and decoder)
|
|
|
|
If you would like to remove Szip compression from the HDF5 library, follow
|
|
the steps below.
|
|
|
|
2.1 Open the H5pubconf.h file from the c:\MyHDFstuff\hdf5\src directory
|
|
and remove (or comment out) the following two lines:
|
|
|
|
#define H5_HAVE_SZLIB_H 1
|
|
#define H5_HAVE_FILTER_SZIP 1
|
|
|
|
Then save the file.
|
|
|
|
2.2 Delete HDF5_EXT_SZIP environment variable if you have set it in
|
|
preconditions.
|
|
|
|
2.3 Run-compile HDF5 library according to Section II.
|
|
|
|
When you disable Szip, you may get the following message when building
|
|
HDF5 libraries: "The following environment variables were not found:
|
|
$(HDF5_EXT_SZIP)". This message can be ignored.
|
|
|
|
3. Disable Szip Encoder
|
|
|
|
If you would like to just disable Szip encoder from the HDF5
|
|
library while keeping Szip decoder enabled, follow the steps
|
|
below.
|
|
|
|
3.1 Download Szip library without encoder
|
|
|
|
Szip library is different if you want to disable Szip encoder.
|
|
Download szip-noenc binaries from
|
|
ftp://ftp.hdfgroup.org/lib-external/szip/2.1/bin/windows. The Szip
|
|
library and header path should also be set up accordingly (refer to
|
|
precondition 6).
|
|
|
|
3.2 Run-compile HDF5 library according to Section II. The encoding
|
|
functionality is detected dynamically.
|
|
|
|
========================================================================
|
|
Section VI: How to build HDF5 with Fortran Support
|
|
========================================================================
|
|
|
|
Notes: 1. For Intel Compiler users, Intel fortran Compiler 9.1 and 10.1 are
|
|
currently supported-- please see below. Intel Compiler verion 7.x and
|
|
8.x are no longer supported.
|
|
|
|
2. The Compaq Fortran Compiler is no longer supported for HDF5 1.8.
|
|
|
|
3. Intel Fortran 9.1 works only under Visual Studio 2005 environments.
|
|
Building Fortran libraries under Visual Studio .NET is unsupported.
|
|
Visual Studio 2008 is supported only with Intel Fortran 10.1.
|
|
|
|
4. Parallel builds should be disabled. To do so: Go to Tools >
|
|
Options > Projects and Solutions > Build and Run. Set "Maximum Number
|
|
of Parallel Project Builds" to 1.
|
|
|
|
|
|
Preconditions:
|
|
|
|
a. Setup Szip Library for Intel Compiler.
|
|
|
|
Szip source codes or binaries for Windows compilers can be downloaded
|
|
from the following address:
|
|
|
|
ftp://ftp.hdfgroup.org/lib-external/szip/2.1/bin/windows.
|
|
|
|
b. Set up path for external libraries and headers
|
|
|
|
Skip this part if you don't want to use ANY compression features
|
|
provided by HDF5. Instead, read Section V.
|
|
|
|
You have to read this part even if you want to use only Zlib
|
|
or Szip. You also need to read Section V.
|
|
|
|
1) Invoke Microsoft Visual Studio 2005 or 2008.
|
|
|
|
2) From the main menu, Go to Tools > Options > Intel(R) Fortran. In the
|
|
right panel, make sure your "Selected Compiler" is Intel Fortran.
|
|
|
|
3) Select the right-most box for "Libraries", and add Zlib and Szip
|
|
library paths (c:\zlib123\dll, c:\szip\dll for example).
|
|
|
|
4) Select right-most box for "Includes", and add Zlib and Szip header
|
|
paths (c:\zlib123\include c:\szip\include, for example).
|
|
|
|
5) Then click "OK".
|
|
|
|
|
|
1. Build with Intel Fortran Compiler 9.1 or 10.1 under Visual Studio 2005 or 2008
|
|
|
|
Note: This step will build HDF5 Static and DLL C and C++ Library using
|
|
Visual Studio compiler as well as HDF5 Static and High Level
|
|
Fortran Library using Intel Fortran 9.1 or 10.1 Compiler.
|
|
|
|
1.1 Open all_fortran.sln
|
|
|
|
Invoke Microsoft Visual Studio. From the main menu,
|
|
go to "File" and select "Open Solution". Choose "all_fortran.sln"
|
|
under the directory c:\MyHDFstuff\hdf5\windows\proj\all_fortran.
|
|
|
|
|
|
1.2 Build as Normal
|
|
|
|
Follow steps as in Section II to build all HDF5 library files, including
|
|
Fortran and HL Fortran libraries.
|
|
|
|
|
|
2. Test HDF5 Static and High Level Fortran Library
|
|
|
|
We provide 2 options for users to test HDF5 libraries and tools.
|
|
|
|
Option 1: Automatic testings
|
|
|
|
HDF5 comes with various test suites, all of which can be tested with
|
|
hdf5check.bat batch file in c:\MyHDFstuff\hdf5 directory.
|
|
|
|
hdf5check batch file can used to test HDF libraries with Fortran with
|
|
the following options:
|
|
|
|
hdf5check enablefortran Test HDF5 C/Fortran libraries and tools
|
|
|
|
|
|
hdf5check enableall Test HDF5 C/C++/Fortran libraries and tools
|
|
To use this option, HDF5 C++ and Fortran
|
|
libraries must have been built.
|
|
|
|
Invoke a command prompt window and run hdf5check with appropriate option.
|
|
Users are encouraged to redirect their ouput into a file. There should
|
|
be no "*FAILED*" marks.
|
|
|
|
Option 2: Step-by-step HDF5 libraries and tools testings
|
|
|
|
Note: This section provides step-by-step instructions for testing the
|
|
Fortran librariy and tools only. To test the rest of the HDF5 library
|
|
and tools, please see Section II, Step 2.
|
|
|
|
|
|
a. Test HDF5 Static Fortran Library
|
|
|
|
Open a command prompt in the hdf5\fortran\test directory
|
|
|
|
a) Release Static, type:
|
|
checkfortrantests release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checkfortrantests release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checkfortrantests debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checkfortrantests debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
b. Test HDF5 High Level Fortran Library
|
|
|
|
Open a command prompt in the hdf5\hl\fortran\test directory
|
|
|
|
a) Release Static, type:
|
|
checkhlfortrantests release >"Your output filename"
|
|
|
|
b) Release DLL, type:
|
|
checkhlfortrantests release dll >"Your output filename"
|
|
|
|
c) Debug Static, type:
|
|
checkhlfortrantests debug >"Your output filename"
|
|
|
|
d) Debug DLL, type:
|
|
checkhlfortrantests debug dll >"Your output filename"
|
|
|
|
Use a text editor to check results. You should not find any FAILED marks
|
|
in your output files.
|
|
|
|
|
|
3. (Optional) Build HDF5 Fortan and HL Fortran Examples
|
|
|
|
Note: This section only covers building Fortran and HL Fortran examples.
|
|
For other examples, please see Section III.
|
|
|
|
To build and test HDF5 Fortran example:
|
|
---------------------------------------
|
|
|
|
1. Open allf90examples.sln
|
|
|
|
Invoke Microsoft Visual Studio. From the main menu,
|
|
go to "File" and select "Open Solution". Choose "allf90examples.sln"
|
|
under the directory
|
|
c:\MyHDFstuff\hdf5\windows\fortran\examples\allf90examples.
|
|
|
|
2. Select "Build", then Select "Configuration Manager".
|
|
|
|
2.1 To build debug versions of Fortran examples.
|
|
|
|
In "Active Solution Configuration", select "Debug". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
debug version of project "allf90examples".
|
|
|
|
2.2 To build release versions of Fortran examples.
|
|
|
|
In "Active Solution Configuration", select "Release". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
release version of project "allf90examples".
|
|
|
|
When the debug build or release build is done, there should be the
|
|
following subdirectories in c:\MyHDFstuff\hdf5\fortran\examples\
|
|
|
|
attreexampletest
|
|
attreexampletestdll
|
|
compoundtest
|
|
compoundtestdll
|
|
dsetexampletest
|
|
dsetexampletestdll
|
|
fileexampletest
|
|
fileexampletestdll
|
|
groupexampletest
|
|
groupexampletestdll
|
|
grpdsetexampletest
|
|
grpdsetexampletestdll
|
|
grpittest
|
|
grpittestdll
|
|
grpsexampletest
|
|
grpsexampletestdll
|
|
hyperslabtest
|
|
hyperslabtestdll
|
|
mountexampletest
|
|
mountexampletest
|
|
refobjexampletest
|
|
refobjexampletestdll
|
|
refregexampletest
|
|
refregexampletestdll
|
|
rwdsetexampletest
|
|
rwdsetexampletestdll
|
|
selecteletest
|
|
selecteletestdll
|
|
|
|
3. Invoke a command prompt and run the batch file Installf90Examples.bat
|
|
which resides in the top level directory (c:\MyHDFstuff\hdf5). This
|
|
file creates 4 new directories, f90examplesREL, f90examplesRELDLL,
|
|
f90examplesDBG, and f90examplesDBGDLL, in the
|
|
c:\MyHDFstuff\fortran\examples directory and places all the
|
|
executables in it. Both the release and debug versions of the
|
|
examples should be built before this step is done.
|
|
|
|
|
|
To build and test HDF5 High Level Fortran examples:
|
|
---------------------------------------------------
|
|
|
|
1. Open allhlf90examples.sln
|
|
|
|
Invoke Microsoft Visual Studio. From the main menu,
|
|
go to "File" and select "Open Solution". Choose
|
|
"allhlf90examples.sln" under the directory
|
|
c:\MyHDFstuff\hdf5\windows\hl\fortran\examples\allhlf90examples.
|
|
|
|
2. Select "Build", then Select "Configuration Manager".
|
|
|
|
2.1 To build debug versions of Fortran examples.
|
|
|
|
In "Active Solution Configuration", select "Debug". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
debug version of project "allhlf90examples".
|
|
|
|
2.2 To build release versions of Fortran examples.
|
|
|
|
In "Active Solution Configuration", select "Release". Select "Close".
|
|
Select "Build" -> "Build Solution" or "Rebuild Solution" to build
|
|
release version of project "allhlf90examples".
|
|
|
|
When the debug build or release build is done, there should be the
|
|
following subdirectories in c:\MyHDFstuff\hdf5\hl\fortran\examples
|
|
|
|
ex_lite
|
|
ex_litedll
|
|
|
|
3. Invoke a command prompt and run the batch file
|
|
Install_hlf90examples.bat which resides in the top level directory
|
|
(c:\MyHDFstuff\hdf5). This file creates 4 new directories,
|
|
HLf90examplesRELEASE, HLf90examplesRELEASEDLL, HLf90examplesDEBUG,
|
|
and HLf90examplesDEBUGDLL, in the
|
|
c:\MyHDFstuff\hdf5\hl\fortran\examples directory and places all
|
|
the executables in it. Both the release and debug versions of the
|
|
examples should be built before this step is done.
|
|
|
|
4. We provide a batch file named test_hl_f90examples.bat in
|
|
c:\MyHDFstuff\hdf5\hl\fortran\examples directory for you to test
|
|
HDF5 high level fortran examples.
|
|
|
|
test_hl_f90examples.bat batch file has 4 options:
|
|
|
|
Options purpose
|
|
|
|
test_hl_f90examples release -- for release version
|
|
|
|
test_hl_f90examples release dll -- for release DLL version
|
|
|
|
test_hl_f90examples debug -- for debug version
|
|
|
|
test_hl_f90examples debug dll -- for debug DLL version
|
|
|
|
Invoke a command prompt and run test_hl_f90examples with
|
|
appropriate options.
|
|
|
|
When you run "test_hl_f90examples release", the output will look
|
|
like:
|
|
|
|
release version of High Level Fortran examples PASSED
|
|
|
|
Similar messages should be generated with another three options
|
|
If the high level Fortran examples are built successfully.
|
|
|
|
========================================================================
|
|
Section VII : How to build Multi-threaded version of HDF5 library
|
|
========================================================================
|
|
|
|
Notes: In Visual Studio 2005, the Single-threaded runtime libraries have been
|
|
depreciated, and Multi-threaded is built by default. Therefore, no extra
|
|
work needs to be done to build Multi-threaded libraries in Visual Studio
|
|
2005. This section applies only to Visual Studio .NET
|
|
|
|
Preconditions and Section I also apply to this section. Users who
|
|
want to build Multi-threaded version of HDF5 library, please read
|
|
those two sections carefully before go to the following part.
|
|
|
|
|
|
In Visual Studio .NET, users have the option of building multi-threaded
|
|
libraries by manipulating the project settings. Otherwise, the build process
|
|
is very much the same. Therefore, follow the instructions below, and refer
|
|
to the earlier sections of this document for details on building and testing.
|
|
|
|
|
|
1. Open the solution file
|
|
|
|
Refer to previous sections to open the appropriate solution file,
|
|
depending on whether you are building with or without Fortran libraries.
|
|
|
|
2. Change Project Settings
|
|
|
|
a) In Visual Studio, go to "Projects->Properties".
|
|
|
|
b) Make sure in the "Configuration" box, "Release" is selected.
|
|
|
|
c) Select all of the static project file in the main window by holding
|
|
the "Ctrl" key while clicking the project file name.
|
|
|
|
d) In the "Properties" window, choose "C/C++", and then "Code
|
|
Generation".
|
|
|
|
e) Under "Run-time Library", "Single-Threaded" should appear. If it is
|
|
blank inside this box, check if you highlight some DLL project files.
|
|
|
|
d) Change "Single-Threaded" to "Multithreaded".
|
|
|
|
e) In the "Configuration" box, change to "Debug", keeping the static
|
|
projects selected.
|
|
|
|
f) Under "Run-time Library", change "Debug Single-Threaded" to "Debug
|
|
Multithreaded".
|
|
|
|
3. Build as Normal
|
|
|
|
Refer to previous sections to build and test the HDF5 libraries
|
|
and tools.
|
|
|
|
|
|
========================================================================
|
|
Section VIII: How To Build And Test HDF5 With Thread-Safe Feature
|
|
========================================================================
|
|
|
|
All of the preconditions in "Preconditions" Section at the beginning of this
|
|
document also apply to this section. There are some extra preconditions for
|
|
this section only as following.
|
|
|
|
Pre1. Pthread-Win32 Installed
|
|
|
|
Posix Threads for Windows is a open source free software. Users can download
|
|
it from http://sources.redhat.com/pthreads-win32/.
|
|
|
|
HDF5 release 1.8 supports Pthread-Win32 2.7.0 (2005-06-04) or later. Since
|
|
pthreadVC2.dll used by HDF5 1.8 is the release version dll of
|
|
pthread-win32, ONLY HDF5 1.8 release dll are supported and tested on
|
|
Windows XP.
|
|
|
|
Pre2. Set Path for Pthread-Win32 header and library
|
|
|
|
Invoke Microsoft Visual Studio, go to Tools->Options->Projects->VC++
|
|
Directories.
|
|
|
|
From the drop-down box under "Show directories for:",
|
|
|
|
Choose "Include files", add in the path to Pthread-Win32 header file (For
|
|
example: C:\PTHREADS_WIN32\INCLUDE).
|
|
|
|
Choose "Library files", add in the path to Pthread-Winew library (For
|
|
example: C:\PTHREADS_WIN32\LIB).
|
|
|
|
Pre3. Enable HDF5 Thread-safe Feature on Windows
|
|
|
|
Go to directory c:\MYHDFstuff\hdf5\windows\src, open H5pubconf.h and find the
|
|
following messages and remove those comment signs referred to by those two
|
|
arrows and save H5pubconf.h
|
|
|
|
|
|
/*Users want to build and test hdf5 library with thread safe enabled,
|
|
Make the following block active
|
|
*/
|
|
|
|
/* <----
|
|
#if defined _DLL
|
|
#define H5_HAVE_THREADSAFE
|
|
#define H5_HAVE_SYSTEM_SCOPE_THREADS 1
|
|
#if defined TTSAFE_H
|
|
#define sleep Sleep
|
|
#endif
|
|
#endif
|
|
*/ <----
|
|
|
|
|
|
Pre4. Define Environment Variable(HDF5_EXT_PTHREAD) for PthreadVC2.lib
|
|
|
|
To define this environment variable:
|
|
|
|
Click "Start" -> "Control Panel" -> "System" -> "Advanced" ->
|
|
"Environment Variables".
|
|
|
|
If you are logged on as administrator to the local computer AND want to
|
|
let all other users use these two environment variables, click "New" under
|
|
"System Variables" box; otherwise, click "New" under "User Variables" box.
|
|
|
|
In the New Variable window, set
|
|
"Variable name" as HDF5_EXT_PTHREAD
|
|
"Variable value" as pthreadVC2.lib
|
|
|
|
Click OK.
|
|
|
|
pre5. Copy pthreadVC2.dll to System Directory
|
|
|
|
pthreadVC2.dll should be copied into the location that applications can
|
|
find. One suggestion is to use the c:\WINDOWS\system.
|
|
|
|
|
|
1. Build HDF5 Release DLL with Thread-safe Feature
|
|
|
|
1.1 Run batch file copy_hdf.bat.
|
|
|
|
Go to c:\MyHDFstuff\hdf5\windows and run copy_hdf.bat. This process will
|
|
copy all the necessary batch files, Windows-specific source code and text
|
|
files saved under c:\MyHDFstuff\hdf5\windows directory to the corresponding
|
|
directories under hdf5.
|
|
|
|
|
|
1.2 Invoke Microsoft Visual Studio
|
|
|
|
Invoke Microsoft Visual Studio. From the main menu, go to "File" and select
|
|
the "Open Solution" option. Then open the
|
|
c:\MyHDFstuff\hdf5\windows\proj\all\all.sln workspace.
|
|
|
|
1.3 Add in Thread-safe Source Code for HDF5 Library
|
|
|
|
Expand project "hdf5dll", right click on "source" and choose "Add Files to
|
|
Folder...", browse to add in file "H5TS.c" under directory
|
|
c:\MYHDFSTUFF\hdf5\src.
|
|
|
|
1.4 Link to pthreadVC2.lib
|
|
|
|
Right click on project "hdf5dll", choose "Set as Active Project".
|
|
|
|
Go to Project->Properties
|
|
|
|
On the left pane, choose "Release" to the right of "Configuration:"
|
|
|
|
Choose "Linker", choose "Input" from the left pane.
|
|
|
|
Under "Additional Dependencies", add in "$(HDF5_EXT_PTHREAD)" (No
|
|
quotation marks).
|
|
|
|
Click on "OK".
|
|
|
|
1.5 Set Project Active Configurations
|
|
|
|
Go to Build->Set Active Configuration, choose "Release" under "Project
|
|
Configurations:", Click "OK".
|
|
|
|
1.6 Build HDF5 Release DLL with Thread-safe Feature
|
|
|
|
Right-click on project hdf5dll and click "Build" to build HDF5 Release DLL
|
|
with thread-safe feature.
|
|
|
|
Warning messages can be ignored. But there should be no failures at all.
|
|
|
|
2. Test Thread-safe Feature of HDF5 Release DLL
|
|
|
|
2.1 Build Release Version of Project libtestdll
|
|
|
|
Go to Build->Set Active Configuration, choose
|
|
"libtestdll-Win32 Release" under "Project configurations:", Click "OK".
|
|
|
|
Go to Build->Build libtestdll.dll to build release version of Project
|
|
libtestdll.
|
|
|
|
2.2 Build Release Version of Project ttsafedll
|
|
|
|
Go to Build->Set Active Configuration, choose "Release" under "Project
|
|
Configurations:", Click "OK".
|
|
|
|
Right-click on project ttsafedll and click "Build" to build release version
|
|
of Project ttsafedll.exe.
|
|
|
|
2.3 Install hdf5dll.dll
|
|
|
|
Invoke a comand prompt, change directory to c:\MYHDFSTUFF\hdf5, run batch
|
|
file install_dll.bat to copy
|
|
c:\MYHDFSTUFF\hdf5\proj\hdf5dll\release\hdf5dll.dll into system directory.
|
|
|
|
2.4 Test Thread-safe Feature of HDF5 Release DLL
|
|
|
|
Set project ttsafedll as the active project file if it is not. Go to
|
|
Build->Execute ttsafedll.exe, the following is the test messages users
|
|
should get:
|
|
|
|
For help use: ttsafedll.exe -help
|
|
Linked with hdf5 version 1.8 release 0
|
|
Testing -- multi-dataset creation (dcreate)
|
|
Testing -- per-thread error stacks (error)
|
|
Testing -- thread cancellation safety test (cancel)
|
|
Testing -- multi-attribute creation (acreate)
|
|
|
|
|
|
All tests were successful.
|
|
|
|
|
|
Cleaning Up temp files...
|
|
|
|
Users who got the same messages as above have successfully built the release
|
|
version of hdf5dll.dll.
|
|
|
|
3. Build, Test and Install HDF5 Library and Tools
|
|
|
|
Go back to Section II, Step I(2) to Build, test and install HDF5 libary and
|
|
tools.
|
|
|
|
========================================================================
|
|
Section IX: How to build HDF5 for 64-bit Windows
|
|
========================================================================
|
|
|
|
HDF5 can be built for 64-bit Windows in Visual Studio 2005 or 2008. Visual
|
|
Studio .NET has very primative 64-bit support, but it is very difficult to
|
|
set up, and debugging is not supported. Therefore, we recommend all users
|
|
switch to Visual Studio 2005 or 2008 for 64-bit builds.
|
|
|
|
Notes:
|
|
|
|
1. Building 64-bit HDF5 from a 32-bit machine is also unsupported. Because
|
|
we generate source file H5tinit.c from a generated 64-bit executable,
|
|
this must be done on a 64-bit machine.
|
|
|
|
|
|
Prerequisites:
|
|
|
|
1. A 64-bit Windows machine. Either AMD64 and Itanium is supported.
|
|
|
|
2. Microsoft Visual Studio 2005 or 2008 installed with x64 Extensions.
|
|
|
|
|
|
Building:
|
|
|
|
Building 64-bit Windows binaries is very similar to the process for 32-bit.
|
|
Therefore, you may follow the instructions in Section II with the following
|
|
modifications.
|
|
|
|
1. The x64 platform must be selected in the build configuration for
|
|
debug and release versions. Before building, go to "Build",
|
|
"Configuration Manager". In the "Active solution platform" box,
|
|
select "x64", and press "Close".
|
|
|
|
2. 64-bit HDF5 must be built with 64-bit external libraries, unless
|
|
external library support is disabled. You must add the include and
|
|
library paths for x64 configurations as you have in the
|
|
"Prerequisites" section. This is also true for Intel Fortran if
|
|
Fortran libraries are to be built. If you do not wish to use
|
|
external libraries, please read Section V about disabling them.
|
|
|
|
Testing:
|
|
|
|
We provide a test suite to verify all libraries and tools were built
|
|
successfully. This test suite should work identically on 32- and 64-bit
|
|
builds. Therefore, you may follow the instructions in Section II about
|
|
testing. Note that because 64-bit binaries were built, these tests must
|
|
run on a 64-bit machine.
|
|
|
|
Installing:
|
|
|
|
We provide a script that will install all headers, libraries, and tools
|
|
into one folder, hdf5lib. This script should work identically on 32- and
|
|
64-bit builds. Therefore, you may follow the instructions in Section II
|
|
about installing.
|
|
|
|
========================================================================
|
|
Section X: How to build HDF5 on Windows Vista
|
|
========================================================================
|
|
Building on Windows Vista is very similar to building on Windows XP, with
|
|
some minor changes. Therefore, follow the build instructions above, with the
|
|
following considerations:
|
|
|
|
1. Only Visual Studio 2005 and 2008 is currently supported on Windows Vista.
|
|
This is because Microsoft has ended their support for and .NET.
|
|
|
|
2. Building Fortran libraries has not been tested, and is therefore also
|
|
unsupported. You may attempt to build Fortran libraries following the
|
|
instructions above, but they should be considered experimental and used
|
|
for testing only.
|
|
|
|
3. Elevated security permissions are required to test the HDF5 libraries.
|
|
This is because DLLs are installed in the system directory. To enable
|
|
elevated security:
|
|
|
|
1. In the Start menu, search for "Command Prompt". Right click on
|
|
the "Command Prompt" program, and select "Run as administrator."
|
|
|
|
2. A security dialog will pop up. Make sure you select "Continue."
|
|
|
|
3. Test HDF5 libraries and tools as usual using "hdf5check.bat"
|
|
script.
|
|
|
|
|
|
========================================================================
|
|
Section XI: How to build HDF5 using Visual Studio 2008
|
|
========================================================================
|
|
Building with Visual Studio 2008 is very similar to building with Visual Studio
|
|
2005, with some minor changes. Therefore, follow the build instructions above,
|
|
with the following considerations:
|
|
|
|
1. Visual Studio 2008 uses a new format for project files, but Visual Studio
|
|
2005 project files can be easily converted. The HDF5 project files
|
|
will need to be converted on first use. To do so:
|
|
|
|
1.1. Open the HDF5 Visual Studio 2005 solution file as in Section II
|
|
(either all.sln or all_fortran.sln if building Fortran.)
|
|
|
|
1.2. You will be prompted with an automatic conversion wizard. Click
|
|
through, accepting the default values. You may choose to create
|
|
backups of the project files, although it isn't necessary.
|
|
|
|
1.3. When it is finished, it should state that all projects were
|
|
converted successfully with no errors. Warnings can be ignored.
|
|
|
|
2. Once the project files have been converted, build and test normally.
|
|
Note that the converted project files aren't backwards compatible with
|
|
previous versions of Visual Studio.
|
|
|
|
|
|
========================================================================
|
|
Section XII: Backwards Compatibility with HDF5 1.6
|
|
========================================================================
|
|
|
|
Several basic HDF5 functions have changed over the years as requirements on
|
|
the library and data format have evolved. To enable existing applications to
|
|
run properly, all versions of these functions have been retained; for
|
|
flexibility and ease-of-use, macros have been created that can be mapped
|
|
either globally to broad sets of function versions or on a
|
|
function-by-function basis to specific versions. For example, an overall
|
|
approach can be determined by means global setting; function-level settings
|
|
can then be used to override the global setting then for specific functions.
|
|
|
|
To enable 1.6 API symbols in your application:
|
|
|
|
1. Build and test HDF5 normally (see Section II).
|
|
|
|
2. Open your application in Visual Studio. Right click on the
|
|
project file, and select properties.
|
|
|
|
3. Select the C/C++ > Preprocessor pane on the left. In the list of
|
|
"Preprocessor Definitions", add "H5_USE_16_API". (Note: macros in
|
|
the list are separated by a semi-colon.)
|
|
|
|
4. Repeat this for each project and project configuration that uses
|
|
HDF5 libraries.
|
|
|
|
5. Continue to build and test your application normally.
|
|
|
|
|
|
========================================================================
|
|
Section XIII: Misc.
|
|
========================================================================
|
|
|
|
1. Helpful Pointers
|
|
|
|
Here are some helpful notes if you are not familiar with
|
|
using the Visual C++ Development Environment.
|
|
|
|
1.1 Project name and location issues:
|
|
|
|
It is recommended that you use the given directory structure for building
|
|
HDF5. However, it is possible to create your own structure. If you must
|
|
install all.sln and all.vcproj in another directory, relative to hdf5
|
|
directory, you will be asked to locate the sub-project files, when you open
|
|
the project all.sln.
|
|
|
|
If you want to rename "all" (the entire project), you will need to modify
|
|
two files all.sln and all.vcproj as text (contrary to the explicit warnings
|
|
in the files).
|
|
|
|
|
|
1.2 Settings... details:
|
|
|
|
If you create your own project, the necessary settings can be read
|
|
from the all.vcproj file (as text), or from the Project Settings in the
|
|
Visual Studio project settings dialog.
|
|
|
|
1.3 FAQ
|
|
|
|
Many other common questions and hints are located online and being updated
|
|
in the HDF5 FAQ. For Windows-specific questions, please see:
|
|
|
|
http://www.hdfgroup.uiuc.edu/windows/faq.html
|
|
|
|
For all other general questions, you can look in the general FAQ:
|
|
|
|
http://hdfgroup.org/HDF5-FAQ.html
|
|
|
|
|
|
************************************************************************
|
|
Please send email to help@hdfgroup.org for further assistance.
|