diff options
Diffstat (limited to 'release_docs/USING_Windows.txt')
| -rw-r--r-- | release_docs/USING_Windows.txt | 629 |
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. |