Note: This install instruction is very similar to the HDF5 instruction
for Windows platform. Users who are familiar with the installation of
HDF5 library should find the instruction easy to understand. 


H4TOH5 Library Build and Install Instructions for Windows XP
------------------------------------------------------------------------

The following instructions assume that you will be using the source code
release 'zip' file (h4h5tools.zip).

***************************WARNINGS*************************************
Please read CAREFULLY about Preconditions before you go to the following
sections.

Preconditions 

   1. Installed Microsoft Visual 2005 and WinZip or 7-zip.

   2. Set up a directory structure to unpack the library.  For example:

         c:\                                (any drive)
         MyH4toH5stuff\                     (any folder name)

   3. Run WinZip or 7-zip on h4h5tools.zip (the entire source tree) and extract
      h4h5tool package into c:\MyH4toH5stuff(or whatever drive and folder name 
      you would like to choose). This creates a directory called 'h4h5tools'(If 
      you find that the folder name is not 'h4h5tools', change it to 
      'h4h5tools').

   4. You do need HDF4 (hdf and mfhdf) release static library, as well
      as HDF5 releaase static library.  If you would like to build
      debug version of h4h5tools, you will need to build your own debug versions
      of HDF4 (hdf and mfhdf) and HDF5.

      a) You may get hdf4 binary distribution from
         http://hdfgroup.org/release4/obtain.html .  Find the Windows binary 
         according to the instruction.

      b) You may get hdf5 binary distribution from 
       http://hdfgroup.org/HDF5/release/obtain5.html .  Find the Windows binary 
       according to the instruction.

   5. zlib and jpeg libraries are required for HDF4. Users need to have these 
      two libraries for building the H4H5 library.

      zlib 1.2.3 and JPEG release 6b are used inside HDF4. To use zlib library, 
      you have to install your own zlib DLL or go to 
      tp://ftp.hdfgroup.org/lib-external/zlib/1.2/bin to download the zlib 
      library.
      
      To use JPEG library, you have to install your own JPEG library or go to
      ftp://ftp.hdfgroup.org/lib-external/jpeg/bin to download the JPEG library 
      archive file jpeg-6b.exe.

   6. Szip library is optional for HDF4, HDF5, and H4H5 tools.  Szip is not  
      completely open-source free software.  Szip decoder is free for 
      distribution.  To use Szip library, you can download Szip source code and 
      binaries from ftp://ftp.hdfgroup.org/lib-external/szip/2.0 .  For 
      licensing issue of Szip, please check "Licensing terms" at
      http://hdfgroup.org/doc_resource/SZIP .
      
   7. Only Visual Studio 2005 is supported on Windows in this release.  Visual
      Studio 2005 is available as an "express" version free of charge from
      Microsoft.  If you are using older versions of Visual Studio, we recommend
      you upgrade.  However, if you need Visual Studio .NET 2003 support, please
      email help@hdfgroup.org.


The following sections discuss installation procedures in detail:                         

   Section I:    What do we Build and Install
   Section II:   Building and Testing h4toh5 libraries and utilities
   Section III:  Building an Application using libh4toh5
   Section IV:   Disabling szip 
   Section V:    Enable HDFEOS2 Support 
   Section VI:   Helpful Pointers
************************************************************************

Section I: What do we Build and Install

   H4TOH5 static library: 
        release and debug version

   H4TOH5 library testing programs:
        h4toh5 library related tests
                
   H4TOH5 example:
        A simple H4TOH5 example

   H4TOH5 conversion utility:
        release and debug version

   H5TOH4 conversion utility:
        release and debug version
                                
************************************************************************

Section II: Building and Testing h4toh5 libraries and utilities

1. This section builds and tests all versions of h4toh5 libraries,
   testing programs.

2. We assume that you've installed HDF4(mfhdf and hdf) libraries into drive C. 
   The top level path, for example, might be c:\HDF42r3.  Under c:\HDF42r3 it 
   should at least include the following directories: 

   c:\HDF42r1\release\lib where release version of hdf and mfhdf libraries are 
   stored

   c:\HDF42r1\release\include where HDF4 public header files are included

3. We assume that you've installed zlib, szip and jpeg library into drive c. 
   The top level path, for example, may be c:\zlib123, c:\szip21, c:\jpeg-6b.

4. Set up environment variables

   Define the following environment variables: 

          HDF4_EXT_ZLIB
          HDF4_EXT_JPEG
          HDF4_EXT_SZIP
                    
      In this section, szip compression software is assumed to be used. Please 
      read Section IV as well as this section if you do not want to use Szip 
      compression feature inside H4H5tools.
      
      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 three environment variables, click "New" 
      under "System Variables" box; otherwise, click "New" under "User 
      Variables" box.
      
      In the New Variable window, set "Variable name" as HDF4_EXT_ZLIB and 
      "Variable value" as zdll.lib, then click OK.
      
      Similarly, you can set:

      HDF4_EXT_JPEG environment variable as libjpeg.lib
      HDF4_EXT_SZIP environment variable as szlibdll.lib
      
      Notes:

         a. You might have to close and reopen running programs for the
            new environment variable settings to take effect. 

Step 1. Build the h4h5 tool.
========================================================================

    1. Run copy_h4h5.bat from the .\windows directory.
      
    2. Invoke Visual Studio, go to "File" and select the "Open Project" 
       option. 

       Then open the c:\MyH4toH5stuff\h4h5tools\windows\proj\all.sln
       workspace. 
    
    3. Go to "Tools" and select "Options", find "Directories";

       3.1 Find the box "Show directories for", choose "Include files",
           See whether you can find the include path of HDF4, HDF5
           and external libraries.  For example:

              c:\zlib122\include 
              c:\szip20\include
              c:\jpeg-6b
              c:\5-181-win\include
              c:\HDF42r3\include

           If not, add the above pathes to the included directories.
            
       3.2 Find the box "Show directories for", choose "Library files",
           Make sure that you have the following paths added to the box:

              c:\zlib123\lib
              c:\szip20\dll
              c:\jpeg-6b
              c:\HDF42r3\lib
              c:\5-181-win\lib


    4. Select "Build", then Select "Confiuration Manager".

       On Windows platform select as the active configuration:

          "Debug" to build debug versions, and then "Release" to build release
          version

       You receive no errors when building.  Warnings can be ignored.
       
       
Step 2. Test the h4toh5 library and tools

In a command prompt window run "h4h5check.bat" which resides in theh h4h5tools 
root directory, to make sure that the library was built correctly.

Before testing, you must define two more variables in your environment, H4PATH
and HDF5PATH.  Define these to be the release "bin" directory, which includes
hdiff.exe and h5diff.exe, respectively.  Use the directions in Section II 
pre-conditions, step 2, to define them.  For example, set them as:

    H4PATH environment variable as    c:\HDF42r3\bin
    HDF5PATH environment variable as  c:\5-181-win\bin
    
Substitute your actual directory path as needed.

The options for the h4h5check batch file are:

   h4h5check                -- Tests all h4h5 configurations
   h4h5check enableeos      -- Tests all h4h5 configurations with HDFEOS support
                               (See Section V)

                               
We strongly suggest you to redirect your testing results into an output file so
you can easily check the testing results.  You should find no *FAILED* marks
in the results.


Step 3. Install the h4toh5 library

This step is optional. Users can use a simple batch file "installh4h5lib.bat" 
under the h4h5tools root directory to copy H4toH5 static libraries, tools and 
public headers to the directory c:\MyH4toH5stuff\h4h5tools\h4h5lib

                

Section III:  Building an Application using libh4toh5
========================================================================

We only provide one example currently.

   1. Invoke Microsoft Visual Studio, go to "File" and select the "Open Project" 
      option. 
      
      Then open the solution
      c:\MyH4toH5stuff\h4h5tools\windows\proj\all_examples.sln

    2. Select "Build", then Select "Confiuration Manager".

       On Windows platform select as the active configuration:

          "Debug" to build debug versions, and then "Release" to build release
          version

       You receive no errors when building.  Warnings can be ignored.
       
    3. Test the example project.
        
        After copy_h4h5.BAT has been run, there will be a script in the root
        directory named .\testexamples.bat.  When the example has been built
        for both release and debug configurations, run this script from the
        commandline with the following parameters:
        
            testexamples.BAT debug              -- Test debug configuration
            testexamples.BAT release            -- Test release configuration
            testexamples.BAT                    -- Test both configurations
            
        When the script is run, you should see no FAILED marks.
      

Section IV:   Disabling szip 
========================================================================

For building, you don't need to do anything inside H4H5tools to disable szip 
filter. You do need to build HDF4 and HDF5 libraries with szip disabled, and 
then use these libraries to build H4H5tools.  Also, you do not need to define
the environment variable HDF4_EXT_SZIP

To test h4h5tools, the following change needs to be made:

    1. In your favorite text editor, open testh4toh5.bat from the 
       .\windows\utils\h4toh5 directory.
    
    2. Find the lines
    
            call :setfilter H5_USE_FILTER_SZIP          yes
            call :setfilter H5_USE_FILTER_SZIP_ENCODE   yes
        
       and change them to
       
            call :setfilter H5_USE_FILTER_SZIP          no
            call :setfilter H5_USE_FILTER_SZIP_ENCODE   no
            
    3. Save the file, and re-run copy_h4h5.bat from the .\windows directory.

    
Please refer to Windows installation files for HDF4 and HDF5 on how to disable 
szip in HDF4 and HDF5.


Section IV:   Enable HDFEOS2 Support
========================================================================
H4H5 Tools now has support for HDFEOS2 conversions.  However, this feature
is not enabled by default.  To build libh4h5 and tools with HDFEOS2 support,
make the following modifications:

    -- You will need to build HDF4, HDF5, and now HDFEOS2 before you can build
       libh4h5tools.  Follow the instructions packaged with each library, and
       install in a directory.  We will assume HDFEOS2 is installed in
       C:\hdfeos2.
       
    -- Open all.sln in Visual Studio 2005 as above.  Go to Tools > Options >
       Projects and Solutions > VC++ Directories.  Select "Include files", and
       add the path for HDFEOS2.  For example, C:\hdfeos2\include.  Then select
       "Library files", and add the path for HDFEOS2 library.  For example,
       C:\hdfeos2\lib
       
    -- In Visual Studio, go to View > Property Manager.  Select all projects in
       the Property Manager pane using the Shift key.  Right click on the
       projects and select "Add Existing Property Sheet..".  Navigate to
       C:\MyH4H5Stuff\h4h5tools\windows\property-sheets\ and select 
       depends-hdfeos.vsprops.  Then press OK.
       
    -- Build release and debug libraries as above.
       
    -- When you test using the h4h5check.BAT script, use the "enableeos"
       parameter to test the eos capabilities.  For example
       
            h4h5check enableeos > myoutput.txt
        
       You should see no FAILED marks.
       

Section VI:    Helpful Pointers
========================================================================

Preconditions:

1. You must have release versions of HDF4 and HDF5 static static library installed
   on your machine for building an application with libh4toh5.

2. If you are building an application that uses libh4toh5, the following 
   locations will need to be specified for locating header files and linking 
   the HDF4 and HDF5 libraries of binary release:

   <top-level HDF4 directory>\include
   <top-level HDF5 directory>\include
   <top-level H4TOH5 directory>\include

where <top-level HDF5 directory> may be 

   C:\MyH4toH5stuff\hdf5\

3. There are two ways to tune your project settings:

    1. Go to Tools-->Options-->Directories

    Add the corresponding include paths and library paths.  Those paths
    should include HDF4, HDF5, external library includes, HDF4,HDF5 and external
    library paths.

    2. To specify these locations in the settings for your VC++ project:

       1.) Open your VC project in Microsoft Visual C++ and make sure it is
           the active project.

       2.) Go to the Project menu and choose the 'Settings' option.

       3.) Choose the build configuration you would like to modify in the
           drop down menu labeled with 'Settings For:'

       4.) Choose the C/C++ tab

       5.) At the bottom of the window, there should be a text-area labeled
           with 'Additional include directories:'. type the 
           HDF4 path(<top-level HDF4 directory>\include) 
           HDF5 path(<top-level HDF5 directory>\include)
           H4TOH5 path(<top-level H4TOH5 directory>\include)
          
           then click OK.
            
          
4. Project name and location issues: 
       
    If you must install all.dsw and all.dsp in another directory, relative to 
    h4h5tools\, 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 
    all.sln as text (contrary to the explicit warnings in the files).

  
5. 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 Microsoft Visual 
    Studio project settings dialog.

    Project
       Settings
          C/C++
             Category
                PreProcessor
                   Code Generation
                      Use run-time Library

