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
  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 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 CPPFLAGS=-DH5_USE_16_API CC=/hdf4/bin/h4cc --with-hdf5=<hdf5libpath> --prefix=<your own directory for h4h5tools>

      or to activate the support of converting  HDF-EOS2 files,
      ./configure CPPFLAGS=-DH5_USE_16_API 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

  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.

    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.

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

  -nc4fakedim
    This option is similar to -nc4 option in the sense that h4toh5 generates
    a netCDF-4-compliant HDF5 file. Additionally, this option will make
    h4toh5 generate dimensions even though the source file does not have them.
    This option is useful when the source file is a hybrid HDF-EOS2 file that
    has SDS or Vdata that do not belong to the HDF-EOS2 structure and do not
    have dimensions. For this file, passing both -nc4fakedim and -nc4strict
    will let h4toh5 generate a netCDF-4-compliant HDF5 file.

    If only -nc4 is specified, the conversion may succeed, but the generated
    file may not be read by netCDF-4 due to the lack of dimensions. On the other
    hand, if only -nc4strict is specified, the conversion will fail.

  If the source file is an HDF-EOS2 file, using -eos and -nc4strict options is
  most recommended; e.g. 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

  If the source file is an HDF-EOS2 file but it has additional SDS or Vdata,
  using -eos, -nc4strict and -nc4fakedim is recommended as follows:

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


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

