     Instructions for Using HDF4 on Windows
========================================================================

The preferred method of using the HDF4 libraries uses the binaries built using CMake.
See the file USING_CMake.txt for further guidance.

The following information is considered obsolete:

The instructions which follow assume that you will be using the HDF4 binary 
archive from HDF website (http://hdfgroup.org).

***************************WARNINGS*************************************
Please read CAREFULLY about the following preconditions first.

Preconditions

To use the HDF4 and MFHDF libraries ( multi-threaded static or multi-threaded 
DLL) and utilities, it is assumed that you have done the following:
      
   1. Installed Microsoft Visual Studio. Express Editions may work with the 
      project files but not from the command line. We do not support the 
      Express Editions.
   
      1.1 This document is written for Visual Studio 2008.

      1.2 To build Fortran libraries, you must install the Intel Fortran 
          10.1 or 11.1 compiler.

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

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

   3. Download the HDF-X.Y.Z binary archive HDF-X.Y.Z.zip from
      ftp://ftp.hdfgroup.org/HDF/HDF_Current/bin/windows and use 7zip or WinZip
      to extract HDF4 libraries and utilities into c:\MyHDFstuff.  This creates a 
      directory called 'HDF-X.Y.Z' under MyHDFstuff which contains 
      several files and directories.  Rename "HDF-X.Y.Z" to "HDFXYZ".  

   4. HDF4 provides options to do in-memory compress within HDF4
      library.  Currently, three external compression libraries ZLIB,
      JPEG, and SZIP can be used with HDF4.

      4.1 HDF4 uses Zlib version 1.2.5 for compression.  A Zlib
          library compiled for the binary is provided in the release.
      
      4.2 HDF4 uses JPEG release 6b/8b for compression.  A JPEG
          library compiled for the binary is provided in the release.

      4.3 HDF4 uses Szip version 2.1 for compression. A Szip
          library compiled for the binary is provided in the 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.
      
   5. Define the following environment variables: 

          HDF4_EXT_ZLIB
          HDF4_EXT_JPEG
          HDF4_EXT_SZIP
      
      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 zlib.lib, then click OK.
      
      Similarly, you can set:

      HDF4_EXT_JPEG environment variable as jpeg.lib
      HDF4_EXT_SZIP environment variable as szip.lib

      Notes:

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

         b. If you did not add HDF4 to the PATH after unzipping,
            jpeg.dll, zlib.dll and szip.dll should be copied into the location 
            that the application can find.
      
   6. Set up paths for libraries and headers
 
      Invoke Microsoft Visual Studio and go to "Tools" and select
      "Options", find "Projects", and then "VC++ Directories"
      
      6.1 If you are building on 64-bit Windows, find the "Platform" dropdown
          and select "x64".
      
      6.2 Find the box "Show directories for", choose "Include files",
          If you cannot find your HDF4, Zlib, JPEG, and Szip header path
          (for example, c:\MyHDFstuff\HDF42x\include) from the directory list, 
          add the header path (c:\MyHDFstuff\HDF42x\include) to
          the included directories.
      
      6.3 Find the box "Show directories for", choose "Library files",
          If you cannot find your HDF4, Zlib, JPEG, and Szip library path
          (for example, c:\MyHDFstuff\HDF42x\dll) from the directory list, 
          add the library path (c:\MyHDFstuff\HDF42x\dll) to the library
          directories.
          
      NOTE:
          If you are using VS2010, the path settings will need to be in project
          property sheets. Go to "Project" and select "Properties", find 
          "Configuration Properties", and then "VC++ Directories".
          
          6.1 If you are building on 64-bit Windows, find the "Platform" dropdown
              and select "x64".
          6.2 Add the header path to the "Include Directories" setting.
          6.3 Add the library path to the "Library Directories" setting.

************************************************************************

The following sections discuss the procedures in detail:

   Section I:    Build an Application Using the HDF4 Library
   Section II.   Using HDF4 with Fortran Libraries
   
************************************************************************

   
The layout of <hdf4lib> should be:
    
   include   --  HDF4 header files
   bin       --  HDF4 static utility executables
   lib       --  HDF4 static libraries
   dll       --  HDF4 multi-threaded libraries and DLLs
       
   
Section I. Build an Application Using the HDF4 Library
======================================================================

If you are building an application that uses the HDF4 library, the
following locations will need to be specified for locating header files
and linking in the HDF4 libraries:
 
   <top-level HDF directory>\lib
   <top-level HDF directory>\dll
   <top-level HDF directory>\include

where <top-level HDF directory> may be
c:\MyHDFstuff\HDF42x\hdf4lib\

To specify these locations in the settings for your VC++ project with
Microsoft Visual Studio:

Under Tools->Options, select the folder "Projects", and then "VC++ Directories":
   Under "Show directories for", select "Include files".
   Add the following directories:
      c:<path to HDF includes>\include  

Under "Show directories for", select "Library files":
   Add the following directories:
      c:<path to HDF libs>\lib
      c:<path to HDF libs>\dll

Under Project->Properties, select folder, Linker, and then Input:
   Add the following libraries to the beginning of the list of "Additional
   Dependencies":
      hd42x.lib hm42x.lib xdr.lib Ws2_32.lib (static release version)

      hd42xm.lib hm42xm.lib xdr_for_dll.lib Ws2_32.lib(shared DLL release version)

      (Optional) For applications which use HDF4 Fortran libraries, except the 
      libraries listed above, users should also add the following libraries to 
      the list of Additional Dependencies:
      
      For static release version:
        mfhdf_fortran.lib hdf_fortran.lib

      For shared DLL release version:
        mfhdf_fortrandll.lib hdf_fortrandll.lib

      HDF4_EXT_ZLIB
      HDF4_EXT_JPEG
      HDF4_EXT_SZIP

Note: The above three environment variables should have been defined in
      the preconditions.  Paths for these external libraries and
      headers should also have been set up in preconditions.

      Follow the instructions in preconditions to define these three
      environment variables and set up path for these external libraries
      and headers if you can not find them.

If you did not add HDF4 to the PATH after unzipping, HDF4 DLLs should also be copied 
to a directory where the application can find them. 

Note: If you can not find the binary distribution matching with your Windows 
      platforms and compilers, you will have to build HDF4 libraries and 
      utilities from the source codes.

      Also, these binary distributions were pre-compiled with Szip compression 
      feature inside HDF4 library.  If you do not want to use the Szip 
      compression feature, you will have to build HDF4 libraries and utilities 
      from the source code.
     

Section II. Using HDF4 with Fortran Libraries
======================================================================

Currently, HDF4 is supported with Intel Fortran Compilers 10.1 or 11.1 under 
Visual Studio 2008.

Step 1: Building HDF4 Examples 

In addition to the C examples, we also provide a suite of Fortran examples
to test the HDF4 Fortran libraries.  To build and test HDF4 Fortran example:

   1. Invoke Visual Studio, go to "File" and select the "Open Solution" option.

      Then open the soltuion
      c:\MyHDFstuff\HDF42x\examples\fortran\proj\allf90examples.sln.

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

      In "Active Soltuion Configuration", select the active configuration
          "Release" to build release versions the Fortran examples.
       
   3. Due to some dependencies between the examples, the createtest.exe should 
      be executed before gitest.exe and sattrtest.exe, and rattrtest should be 
      executed immediately after sattrtest.exe due to the dependencies among these files.

                                       
*************************************************************
Please send email to help@hdfgroup.org for further assistance.
