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

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 2008 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 release 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.5 and JPEG release 6b or 8b 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 or jpeg-8b.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 2008 is supported on Windows in this release.  Visual
      Studio 2008 is available as an "express" version free of charge from
      Microsoft.  If you are using older versions of Visual Studio, we recommend
      you upgrade.  We no longer support VS2005.


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:\HDF4.  Under c:\HDF4 it 
   should at least include the following directories: 

   lib where release version of hdf and mfhdf libraries are stored

   include where HDF4 public header files are included
   
   bin where HDF4 utilities are included
   
3. Define an environment variable for the HDF4 top level path:

          HDF4_PATH
      
4. We assume that you've installed HDF5(hdf5) libraries into drive C. 
   The top level path, for example, might be c:\HDF5.  Under c:\HDF5 it 
   should at least include the following directories: 

   lib where release version of hdf5 libraries are stored

   include where HDF5 public header files are included
   
   bin where HDF5 utilities are included
   
5. Define an environment variable for the HDF5 top level path:

          HDF5_PATH


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

7. 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.
      
8. 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 zlib1.lib, then click OK.
      
      Similarly, you can set:

      HDF4_EXT_JPEG environment variable as libjpeg.lib
      HDF4_EXT_SZIP environment variable as libszip.lib
    
    and also the paths for:
    
    HDF4_PATH environment variable as c:\HDF4
    HDF5_PATH environment variable as c:\HDF5
      
      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_hdf.bat from the .\windows directory.
      
    2. Invoke Visual Studio, go to "File" and select the "Open Solution" 
       option. 
    
    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:\zlib125\include 
              c:\szip21\include
              c:\jpeg-8b (or jpeg-6b)
              c:\HDF5\include
              c:\HDF4\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:\zlib125\lib
              c:\szip21\dll
              c:\jpeg-8b (or jpeg-6b)
              c:\HDF4\lib
              c:\HDF5\lib

  4. To build within Visual Studio:
  
       4.1 Then open the c:\MyH4toH5stuff\h4h5tools\windows\proj\all.sln
       workspace. 

     4.2 Select "Build", then Select "Configuration 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.
  
  5. To build from the command line:
  
     5.1 In a visual studio command prompt window run "h4h5build.bat" which resides in the 
         h4h5tools root directory. You will need to pass as an argument the version of 
         Visual Studio you are using; vs9 for VS2008.
       
Step 2. Test the h4toh5 library and tools

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

Before testing, you must have defined the two variables in your environment, HDF4_PATH
and HDF5_PATH.  Use the directions in Section II pre-conditions, step 2, to define them.  
For example, set them as:

    HDF4_PATH environment variable as  c:\HDF4\release
    HDF5_PATH environment variable as  c:\HDF5\release
    
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 2008 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, and 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.sln in another directory, relative to 
    h4h5tools\, 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 
    all.sln as text (contrary to the explicit warnings in the files).

