H4H5TOOLS Install Instructions for UNIX

*******************************************************************************
Section I: What do we Build and Install

  H4H5 library
  h4toh5 utility
  h5toh4 utility
  HDF-EOS2/netCDF-4 verifier (optional)

  h4toh5 utility can be configured to support the conversion of HDF-EOS2 files 
  to HDF5 files that can be read by netCDF-4 library.

*******************************************************************************
Section II: Building and Testing h4toh5 libraries and utilities

1. Prerequisites

  HDF4 library
  HDF5 library
  HDF-EOS2 library (optional)

  The support of special conversion of HDF-EOS2 files requires HDF-EOS2
  library which can be downloaded from the following URL:
    http://newsroom.gsfc.nasa.gov/sdptoolkit/toolkit.html

2. Configure
  The previous release needs preprocessor option (CPPFLAGS) to be defined if
  you use HDF5 1.8 or higher. This release removes this limitation, that means 
  you do not need to pass it to the configure script if you use HDF5 1.8 or 
  higher. The removement also keeps backword compatibility with HDF5 1.6. 


  C Compiler (CC)
    HDF4 library installs h4cc scripts which can replace cc. h4cc should be
    specified as the C Compiler. This can be done by passing the following
    to the configure script:

      CC=<hdf4-directory>/bin/h4cc

  C Compiler option (CFLAGS)
    Generally, nothing needs to be done for the compiler option. However, some
    strict compiler will complain. We could see cc in Solaris complain the
    lack of uint64_t. -xc99 can be used to correct this problem.

  HDF5 library (--with-hdf5=)
    The location of HDF5 library should be specified.

  HDF-EOS2 Support (optional)
    To use the special conversion of HDF-EOS2 files, --with-hdfeos2=<path>
    option should be specified. The path should contain both include/ and lib/
    directory.

  Example:
      ./configure CC=/hdf4/bin/h4cc --with-hdf5=<hdf5libpath> --prefix=<your own directory for h4h5tools>

      or to activate the support of converting  HDF-EOS2 files,
      ./configure CC=/hdf4/bin/h4cc --with-hdf5=<hdf5libpath> --with-hdfeos2=<hdfeos2libpath> --prefix=<your own directory for h4h4tools>

      For platforms such as solaris, set "-xc99" at CFLAGS, or
      setenv CC "/hdf4/bin/cc -xc99"
      then run configure shown above.
      
               

3. Build
  GNU make is recommended to build H4H5TOOLS.
    $ gmake

4. Test
  The following command will test if H4H5TOOLS works as expected.
    $ gmake check

  Note that the above command will also test the conversion from HDF-EOS2
  to HDF5 that can be accessed by netCDF4. If shared HDF5 and GCTP libraries(for
  --with-hdfeos2 configuration option only) are used, one should include
  the paths of these two libraries in the LD_LIBRARY_PATH on Linux.

  test_ncdump.sh (optional)
    You can run this test script when you would like to use convert an 
    HDF-EOS2 file to an HDF5 file that can be read by netCDF-4.
    This test driver is not executed automatically. It should be noted that 
    this test works with HDF5 1.8 or higher only.

    You can execute test_ncdump.sh from utils/h4toh5/ directory.  To run this
    test, you need to have ncdump which is part of netCDF-4 library and define
    the path to ncdump binary as an environment variable. Under bash,
      $ export NCDUMP=/netcdf4/bin/ncdump
      $ ./test_ncdump.sh
  
    This will convert several hdf-eos2 files and use ncdump to check if the
    converted files can be read by netCDF-4 library. Users may see the output
    from ncdump on the screen. This is okay. Finally you should see  a message
    "all h4toh5 tests passed."

5. Install
  You can install H4H5TOOLS library and utilities by the following command:
    $ gmake install


*******************************************************************************
Section III: Usage

  If --with-hdfeos2 option is used, h4toh5 conversion utility recognizes four
  additional command line arguments.

  -eos
    This option makes h4toh5 recognize HDF-EOS2 data structures. When h4toh5
    reads an HDF4 file, it also uses HDF-EOS2 API to retrieve EOS2-specific 
    information.

  -nc4strict
    This option will make the generated HDF5 file netCDF4-readable.
    It will assure that the generated HDF5 files can be
    accessed by any netCDF-4 APIs.  The conversion tool will issue an error
    message and exit the program if conversion of any objects doesn't follow
    netcdf4 data model.


  One can type the following command to convert an
  HDF-EOS2 file "AR_RnGd.hdf" to a netCDF-4-compliant HDF5 file "AR_RnGd.nc".

    $ h4toh5 -eos -nc4strict AR_RnGd.hdf AR_RnGd.nc

  The previous version (2.2.0) also supports -nc4 and -nc4fakedim options. In
  this version(2.2.1) these two options are not supported. Users should refer
  to the version (2.2.0) on how to use these two options.


*******************************************************************************
*******************************************************************************
Additional Software: HDF-EOS2/netCDF-4 Verifier (optional) (UNIX only)

  The H4H5TOOLS distribution includes a stand-alone program that verifies 
  the HDF-EOS2 to netCDF-4 conversion. 

  See misc/verify_eos2nc4/README.txt for configuration and installation 
  instructions.

