From a4ede54bbd1a45021f93bc409b2dd81ec1b32a01 Mon Sep 17 00:00:00 2001 From: Fang Guo Date: Tue, 2 Aug 2005 10:24:57 -0500 Subject: [svn-r11182] Purpose: Maintenance on windows Description: Add high level dll and multithread contents into the document Solution: Platforms tested: Misc. update: --- release_docs/INSTALL_Windows.html | 4249 +++++++++++++++++++++---------------- 1 file changed, 2450 insertions(+), 1799 deletions(-) diff --git a/release_docs/INSTALL_Windows.html b/release_docs/INSTALL_Windows.html index da7de21..9ff3545 100755 --- a/release_docs/INSTALL_Windows.html +++ b/release_docs/INSTALL_Windows.html @@ -3,11 +3,19 @@ - HDF5 Build and Install Instructions for Windows XP (Full Version) @@ -99,1812 +131,2431 @@ hr.second{color:#0000FF;height:2px; width:100%;magin-top:5px;margin-bottom:5px;b

HDF5 Build and Install Instructions for Windows XP (Full Version)

-
+

Notes:

-

The following instructions assume that the HDF5 source code package from -HDF website (http://hdf.ncsa.uiuc.edu) -is used. -

-

Table of Contents:

- -

Preconditions

-

Section I: What do we build and install

-

Section II: How to build and test HDF5 libraries and tools

-

Section III: How to build an application using the HDF5 library or DLL

-

Section IV: Helpful pointers

-

Section V: How to disable Gzip(Zlib)/Szip compression

-

Section VI: How to build HDF5 in VS 7.0(.NET)

-

Section VII: How to build HDF5 with INTEL Compiler

-

Section VIII: How to build and test HDF5 snapshot release

-

Section VIIII: Misc.

- -
- +

The following instructions assume that the HDF5 source code package from +HDF website (http://hdf.ncsa.uiuc.edu) is used.

+

Table of Contents:

+ +

Preconditions

+

Section I    :  What do we build and +install

+

Section II   :  How to build and test HDF5 +libraries and tools

+

Section III  :  How to build an application using +the HDF5 library or DLL

+

Section IV  :  Helpful pointers

+

Section V   :  How to disable Gzip(Zlib)/Szip +compression

+

Section VI  :  How to build HDF5 in VS 7.0(.NET)

+

Section VII :  How to build HDF5 with INTEL Compiler

+

Section VIII:  How to build Multi-threaded version +of HDF5 library

+

Section IX  :  How to build and test HDF5 snapshot +release

+

Section X   :  Misc.

+

Preconditions

-
- +

Please read CAREFULLY about the following preconditions and notes first.

- -

1. Installed Microsoft Visual C++ 6.0 or Intel C compiler and WinZip.

-

Installed Compaq Visual Fortran compiler(6.0 or higher version), - or Intel Fortran compiler if you want to build HDF5 Fortran - libraries. -

-

Notes:

-

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

-

2. Set up a directory structure to unpack the library.

-

For example:

-

c:\ (any drive)

-

MyHDFstuff\ (any folder name)

-

3. Download the hdf5-1.8.x source code package

-

Use 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". -

+

1. Installed Microsoft Visual C++ 6.0 or Intel C compiler and WinZip.

+

Installed Compaq Visual Fortran compiler(6.0 or higher version), or Intel Fortran +compiler if you want to build HDF5 Fortran libraries.

+

Notes:

+

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.

+

2. Set up a directory structure to unpack the library.

+

For example:

+

c:\ (any drive)

+

MyHDFstuff\ (any folder name)

+

3. Download the hdf5-1.8.x source code package

+

Use 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".

4. HDF5 provide options to do in-memory compress within HDF5 library.

-

Currently, two external compression libraries Zlib and - Szip can be used with HDF5. -

- -

5. Define the following environment variables:

- - - -

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 zdll.lib, then click OK. -

-

Similarly, you can set:

-

HDF5_EXT_SZIP environment variable as szlibdll.lib

- -

Notes:

- - -

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 C++ and go to "Tools" and select - "Options", find "Directories"; -

- -

Notes:

- -

Go to Table of Contents

-
- -

Section I: What do we build and install?

-
- -

Go to Table of Contents

-
+

Currently, two external compression libraries Zlib and Szip can be used with +HDF5.

+ +

5. Define the following environment variables:

+ +

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 zdll.lib, +then click OK.

+

Similarly, you can set:

+

HDF5_EXT_SZIP environment variable as +szlibdll.lib

+

Notes:

+ +

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 C++ and go to "Tools" and select "Options", find "Directories"; +

+ +

Notes:

+ +

Go to Table of Contents

+
+

Section I: What do we build and install?

+
+ +

Go to Table of Contents

+

Section II: How to build and test HDF5 libraries and tools -

-
- + +

STEP 1: Building HDF5 libraries and tools

- - +

STEP 2: Testing HDF5 libraries and tools

HDF5 libraries and tools should be tested to make sure that they were built correctly.

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: -

-
- - - - - - - - - - - - - - - - - - - - - -
OptionsIllustration

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 step I.

-

hdf5check enableall

test HDF5 C/C++/FORTRAN libraries and tools

-

To use this option, HDF5 C++ and Fortran libraries must have been built in step I.

-
-
-

Invoke a command prompt window and run hdf5check with appropriate option.

-

Test results are saved in two files:

-

c:\MyHDFstuff\hdf5\check_results.txt

-

c:\MyHDFstuff\hdf5\tests_results.txt.

-

In general, you only need to check tests_results.txt. If all the - tests passed, then you do not have to check check_results.txt. - If some tests failed, check check_results.txt can help you - figure out what was wrong. -

- -

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: -

- -

We strongly suggest you to redirect your testing results into an - output file so that you can easily check the testing results. You - may use either Notepad or WordPad or whatever other windows word - processor to check the results. For the purpose of printing, - please choose font less than 14 for better alignment of the text. -

-

DLLs listed below 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 the - following HDF5 DLLs will be copied to the system directory. -

- - - +

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:

+
+ + + + + + + + + + + + + + + + + + + + + +
OptionsIllustration
+

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 + step I.

+
+

hdf5check enableall

+ 		+

test HDF5 C/C++/FORTRAN libraries and tools

+

To use this option, HDF5 C++ and Fortran libraries must have been built + in step I.

+
+
+

Invoke a command prompt window and run hdf5check with appropriate option.

+

Test results are saved in two files:

+

c:\MyHDFstuff\hdf5\check_results.txt

+

c:\MyHDFstuff\hdf5\tests_results.txt.

+

In general, you only need to check tests_results.txt. +If all the tests passed, then you do not have to check check_results.txt. +If some tests failed, check check_results.txt can +help you figure out what was wrong.

+

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:

+ +

We strongly suggest you to redirect your testing results into an output file +so that you can easily check the testing results. You may use either Notepad or +WordPad or whatever other windows word processor to check the results. For the purpose +of printing, please choose font less than 14 for better alignment of the text. +

+

DLLs listed below 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 the following HDF5 DLLs will be copied to the system directory.

+ +

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). 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. +

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). 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:

- -

You may also find the similar layout for the <debug>. - -

STEP 4: Building HDF5 C/C++/Fortran examples (Optional)

-

Simple examples have been provided for users to test HDF5 C/C++/Fortran library and tools.

+ +

You may also find the similar layout for the <debug>.

+

STEP 4: Building HDF5 C/C++/Fortran and High Level +C Examples (Optional)

+

Simple examples have been provided for users to test HDF5 C/C++/Fortran library +and tools.

Notes:

- - + + +
  • +
    To build and test HDF5 C++ examples:
    + +
    • +
  • +
    To build and test HDF5 Fortran example:
    + +
    • +
  • +
    To build and test HDF5 High Level C example:
    + +
    • + +

    Go to Table of Contents

    +
    +

    Section III: Building an application using the HDF5 library +or DLL

    +
    +

    Warnings:

    +

    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.

    -

    Go to Table of Contents

    -
    +
  • +

    To use HDF5 static library

    +

    To build an application using HDF5 Static Library, the following locations + will need to be specified for locating header files and linking with the HDF static + library, for example:

    + +

    If you have installed HDF5 library in + Section II, step 3, We assume that + you will use Zlib and Szip compression with HDF5 library.

    +

    To specify these locations in the settings for your VC++ project, you may choose + one of the following two methods.

    + +
    • +
  • +

    To use HDF5 DLL

    +
      +
    1. +

      Follow the steps for specifying the location of the header files as shown + in Method One.

      +
      2. +
    2. +

      Follow the steps for linking the HDF5 library as shown in + Method One. 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.

      +
      3. +
    3. +

      Place the DLL in a location that Windows will be able to locate it. The searched + path and order for DLL's is

      +
        +
      1. +

        The Windows system directory. The GetSystemDirectory function retrieves + the path of this directory.

        +
        2. +
      2. +

        The Windows directory. The GetWindowsDirectory function retrieves the path + of this directory.

        +
        3. +
      3. +

        The directories listed in the PATH environment variable.

        +
        4. +
      +
      4. +
    4. +

      To modify your own application settings, please DO FOLLOW the + "DLL Hints" at section IV "HELPFUL POINTERS".

      +
      5. +
    +
    • + +

    Go to Table of Contents

    +

    Section IV: HELPFUL POINTERS

    -
    -

    Here are some notes that may be of help if you are not familiar with using the Visual C++ Development Environment.

    +
    +

    Here are some notes that may be of help if you are not familiar with using the +Visual C++ Development Environment.

    Project name and location issues:

    -

    If you must install all.dsw and all.dsp in another directory, - relative to hdf5 directory, you will be asked to locate the - sub-project files, when you open the project all.dsw. -

    -

    - If you want to rename all (the entire project), you will need to - modify two files all.dsw and all.dsp as text (contrary to the - explicit warnings in the files). -

    -

    - You can also modify all.dsw and all.dsp as text, to allow these two - files to be installed in another directory. -

    +

    If you must install all.dsw and +all.dsp in another directory, relative to +hdf5 directory, you will be asked to locate the sub-project +files, when you open the project all.dsw.

    +

    If you want to rename all (the entire project), you will need to modify two files +all.dsw and all.dsp +as text (contrary to the explicit warnings in the files).

    +

    You can also modify all.dsw and +all.dsp as text, to allow these two files to be installed +in another directory.

    Settings... details:

    -

    If you create your own project, the necessary settings can be read - from the all.dsp file(as text), or from the Project Settings in the - Developer Studio project settings dialog. -

    +

    If you create your own project, the necessary settings can be read from the +all.dsp file(as text), or from the Project Settings +in the Developer Studio project settings dialog.

    Project

    -

        Settings

    -

            C/C++

    -

                Category

    -

                    Code Generation

    -

                        Use run-time Library

    +

        Settings

    +

            C/C++

    +

                Category

    +

                    +Code Generation

    +

                        +Use run-time Library

    These are all set to use Single-Threaded

    DLL... hints:

    If you want to use DLL versions of HDF5 library in your application, you should

    -
      -

    1. Put HDF5 DLL into windows system directory

      -

    2. Add HDF5 DLL export library into your project

      -

    3. Follow "Settings... details" into the last line: - change Single-Threaded into Multithreaded DLL or - Debug Multithreaded DLL

      -

    4. Follow "Settings.. details" into PreProcessor:

      -

      Project

      -

          Settings

      -

              C/C++

      -

                  Category

      -

                      PreProcessor

      -

      Find PreProcessor definations and Add _HDF5USEDLL_ at the end of the PreProcessor definitions to use HDF5 C DLL.

      -

    5. (optional) repeat 4), add HDF5CPP_USEDLL at the - end of the PreProcessor definitions to use HDF5 C++ DLL.

      -

    6. (optional)Follow - Project->Settings->Fortran->Category->General->Predefined Preprocess or Symbols, and add - "HDF5F90_WINDOWS" to use HDF5 Fortran DLL.

      -
      7. -
    -

    Go to Table of Contents

    -
    +
      +
    1. +

      Put HDF5 DLL into windows system directory

      +
      2. +
    2. +

      Add HDF5 DLL export library into your project

      +
      3. +
    3. +

      Follow "Settings... details" into the last line: + change Single-Threaded into + Multithreaded DLL or Debug + Multithreaded DLL

      +
      4. +
    4. +

      Follow "Settings.. details" into PreProcessor:

      +

      +

      Project

      +

          Settings

      +

              C/C++

      +

                  Category

      +

                      + PreProcessor

      +

      Find PreProcessor definations and + Add _HDF5USEDLL_ at the end of the PreProcessor + definitions to use HDF5 C DLL.

      +
      5. +
    5. +

      (optional) Repeat 4), add HDF5CPP_USEDLL at the + end of the PreProcessor definitions to use HDF5 C++ DLL.

      +
      6. +
    6. +

      (optional) Follow Project->Settings->Fortran->Category->General->Predefined + Preprocess or Symbols, and add "HDF5F90_WINDOWS" + to use HDF5 Fortran DLL.

      +
      7. +
    +

    Go to Table of Contents

    +

    Section V: How to disable Gzip(Zlib)/Szip compression

    -
    +

    Warnings:

    -

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

    - -

    Go to Table of Contents

    -
    - -

    Section VI: How to build HDF5 in Microsoft Visual Studio .Net 2003

    -
    -

    We just briefly introduce you how to build HDF5 in VS 7.1(.NET)2003;

    +

    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:

    -