summaryrefslogtreecommitdiffstats
path: root/release_docs/USING_Windows.txt
diff options
context:
space:
mode:
Diffstat (limited to 'release_docs/USING_Windows.txt')
-rw-r--r--release_docs/USING_Windows.txt629
1 files changed, 629 insertions, 0 deletions
diff --git a/release_docs/USING_Windows.txt b/release_docs/USING_Windows.txt
new file mode 100644
index 0000000..03dbc67
--- /dev/null
+++ b/release_docs/USING_Windows.txt
@@ -0,0 +1,629 @@
+
+***********************************************************************
+* HDF5 Build and Install Instructions for Windows XP/VISTA *
+* (Full Version) *
+***********************************************************************
+
+The following instructions assume that the HDF5 binary 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 provide?
+ Section II : How to build examples (optional)
+ Section III : How to build an application using the HDF5 library or DLL
+ Section IV : How to build HDF5 for 64-bit Windows
+ Section V : How to build HDF5 applications using Visual Studio 2010
+ Section VI : Misc.
+
+
+========================================================================
+ Preconditions and Notes
+========================================================================
+
+Preconditions:
+
+ 1. Installed Microsoft Visual Studio. This document is written for Visual
+ Studio 2008. Express Editions may work with the project files
+ but not from the command line. We do not support the Express Editions.
+
+ 2. (Optional) Installed Intel Compiler 10.1 or 11.1 if you want to use 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.
+
+ 5. Set up a directory structure to unpack the library. For example:
+
+ c:\ (any drive)
+ MyHDFstuff\ (any folder name)
+
+ 6. Download the hdf5-1.8.x binary 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".
+
+ 7. HDF5 provide options to do in-memory compression within HDF5 library.
+ Currently, two external compression libraries Zlib and Szip can be used
+ with HDF5.
+
+ 7.1 HDF5 uses Zlib version 1.2.5 for compression and Zlib is
+ distributed with HDF5 library in 1.8.x release.
+
+ 7.2 HDF5 uses Szip version 2.1 for compression and Szip compression
+ software is provided with HDF5 products in 1.8.x release.
+
+ 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 enabled by default.
+
+ 8. Set up path for libraries and headers
+
+ Invoke Microsoft Visual Studio and go to "Tools" and select "Options",
+ find "Projects", and then "VC++ Directories".
+
+ 8.1 If you are building on 64-bit Windows, find the "Platform" dropdown
+ and select "x64".
+
+ 8.2 Find the box "Show directories for", choose "Include files", if you
+ can not find your HDF5 header path (for example,
+ c:\MyHDFstuff\include) from the directory list, add the
+ header path (c:\MyHDFstuff\include) to the included
+ directories.
+
+ 8.3 Find the box "Show directories for", choose "Library files". If you
+ cannot find your HDF5 library path (for example,
+ c:\MyHDFstuff\dll) from the directory list, add the library
+ path (c:\MyHDFstuff\dll) to the library directories.
+
+ 8.4 If building Fortran applications, you will also need to setup the path
+ for the Intel Fortran compiler. Please see Section VI.
+
+Notes:
+
+ 1. 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
+
+ 2. For Fortran users, Intel Fortran Compiler 10.1 is currently supported
+ -- please see Section VI. Intel Compiler 11.1 can be used but the project files
+ must be upgraded within the Visual Studio IDE.
+
+
+========================================================================
+ Section I: What do we provide?
+========================================================================
+
+ 1. Provide
+
+ HDF5 static library:
+ release version
+
+ HDF5 Dynamic Link Library(DLL):
+ 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
+
+ HDF5 tool library:
+ release version
+
+ HDF5 tool export library for DLL:
+ release version
+
+ 2. 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 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 installed 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 installed in step I.
+
+ 4) By default, the HDF5 binary distribution 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.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 "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 III: 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, and 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:\zlib\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:\zlib\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, and 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:\zlib\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:\zlib\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 "zlib.lib, libszip.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 IV: How to build HDF5 for 64-bit Windows
+========================================================================
+
+HDF5 is available for 64-bit Windows in Visual Studio 2008.
+
+Prerequisites:
+
+ 1. A 64-bit Windows machine.
+
+ 2. Microsoft Visual Studio 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 applications must be built with 64-bit external libraries.
+ 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.
+
+========================================================================
+ Section V: How to build HDF5 applications using Visual Studio 2010
+========================================================================
+Building with Visual Studio 2010 is very similar to building with Visual Studio
+2008, with some minor changes. Therefore, follow the build instructions above,
+with the following considerations:
+
+ 1. Visual Studio 2010 uses a new format for project files, but Visual Studio
+ 2008 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 2008 solution file as in Section II
+ (all.sln)
+
+ NOTE. Intel Fortran 11.1 currently does not integrate with Visual Studio 2010.
+
+ 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 VI: 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.