H4H5TOOLS Install Instructions for UNIX

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

  H4H5 library
  h4toh5 utility
  h5toh4 utility

  h4toh5 utility can be configured to support the conversion of HDF-EOS2 files 
  to HDF5 files that can be read by NetCDF4 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
  Preprocessor option (CPPFLAGS)
    If you use HDF5 1.8 or higher, H5_USE_16_API should be defined. This can
    be done by passing the following to the configure script:

      CPPFLAGS=-DH5_USE_16_API

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

      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:
    1. Set up CPPFLAGS and CC
      CPPFLAGS=-DH5_USE_16_API 
      CC=/hdf4/bin/h4cc 

    2. Configuration
      ./configure --with-hdf5=<hdf5libpath> 

      or to activate the support of converting  HDF-EOS2 files,
      ./configure --with-hdf5=<hdf5libpath> --with-hdfeos2=<hdfeos2libpath>

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

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

  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 NetCDF4.
    This test driver is not executed automatically.

    You can execute test_ncdump.sh from utils/h4toh5/ directory.  To run this
    test, you need to have ncdump which is part of NetCDF4 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 NetCDF4 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 three
  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.

  -nc4
    This option generates HDF5 files that can be opened by netCDF4 APIs.
    However, some netCDF4 APIs such as nc_inq_dimlen() and nc_inq_dimname() may fail.

  -nc4strict
    This option is similar to -nc4 option; it will make the generated HDF5
    file netCDF4-readable. It will assure that the generated HDF5 files can be
    accessed by any NetCDF4 APIs.  The conversion tool will issue an error
    message and exit the program if conversion of any objects doesn't follow
    netcdf4 data model.
    the input file if the converted file cannot be fully read by netCDF4.

  Using -eos and -nc4strict options is recommended; e.g. For example, one can
  type the following command to convert an HDF-EOS2 file AR_RnGd.hdf to an
  HDF5 file AR_RnGd.h5 that can be read by NetCDF4.

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

