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

*******************************************************************************
Section IV: HDF-EOS2/netCDF-4 Verifier (optional) (UNIX only)

H4H5TOOLS includes a stand-alone program that verifies the HDF-EOS2 to
netCDF-4 conversion. This program takes the source HDF-EOS2 file and the
netCDF-4-compliant HDF5 file generated by h4toh5 conversion utility, and
checks if each object in the HDF-EOS2 file is correctly converted into an
equivalent object in the netCDF-4-compliant HDF5 file.

Windows is not supported at this point.

1. Prerequisites

  HDF4 library (--disable-netcdf)
  HDF5 library
  HDF-EOS2 library
  netCDF-4 library
  C++ compiler

  One important requirement is that --disable-netcdf configuration option should
  be used when HDF4 is configured. This is required because HDF4 enables the
  netcdf interface by default and the netcdf interface interferes with the
  netCDF-4 library.

  This tool requires both HDF-EOS2 library and netCDF-4 library because it opens
  the HDF-EOS2 file and the netCDF-4-compliant HDF5 file using HDF-EOS2 library
  and netCDF-4 library, respectively.

  Since the verifier contains both C and C++ code, C++ compiler is required.

2. Configure
  Note that the verifier is a stand-alone program. It has its own configure
  script.

  C Compiler (CC), C++ Compiler (CXX)
    Using h4cc is not recommended. Just leave CC and CXX as the system specifies.

  C Compiler option (CFLAGS), C++ Compiler option (CXXFLAGS)
    You don't need to specify -DH5_USE_16_API even if you use HDF5 1.8 or higher.

  HDF4 library (--with-hdf4=)
    The location of HDF4 library should be specified. As mentioned earlier,
    HDF4 library should be built without netcdf interface.

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

  HDF-EOS2 library (--with-hdfeos2=)
    The location of HDF-EOS2 library should be specified. This switch is not
    optional, but mandated.

  netCDF-4 library (--with-netcdf4=)  
    The location of netCDF-4 library should be specified.

  ZLIB (--with-zlib=), JPEG library (--with-jpeg=), SZLIB (--with-szlib=)
    Usually, users do not need to specify these options because the configure
    script automatically detects from HDF4 library and HDF5 library. If the
    configure cannot detect, you may need to manually specify them.

  Example:
     ./configure \
        --with-hdf4=<hdf4libpath> --with-hdf5=<hdf5libpath> \
        --with-hdfeos2=<hdfeos2libpath> --with-netcdf4=<netcdf4libpath>

     If ZLIB, JPEG library or SZLIB was not detected, you may get error
     messages while executing the configure script. You may want to try the
     following:

     ./configure \
        --with-hdf4=<hdf4libpath> --with-hdf5=<hdf5libpath> \
        --with-hdfeos2=<hdfeos2libpath> --with-netcdf4=<netcdf4libpath> \
        --with-zlib=<zlibpath> --with-jpeg=<jpeglibpath> --with-szlib=<szlibpath>

3. Build
  GNU make is recommended to build HDF-EOS2/netCDF-4 verifier.
    $ gmake

4. Usage
  Two options are available. Both of them are about verbosity of messages.

  -v
    This option lets the verifier show verified objects. By default, the verifier
    shows messages only when it finds some problems.

  -p
    This option makes the verifier print all object names it accesses. Since
    it gives more readable output, this option is useful when an error is
    detected.

  Using both options is recommended unless you want to get just the result.
  For example, one can use the following command to compare an HDF-EOS2 file
  "AR_RnGd.hdf" with a netCDF-4-compliant HDF5 file "AR_RnGd.nc".

  $ verify -p -v AR_RnGd.hdf AR_RnGd.nc

5. Note about false alarms
  The HDF-EOS2/netCDF-4 verifier is neither sound nor complete in the sense
  that it may give false alarams and it may miss wrong conversion. False alarms
  can be introduced by either netCDF-4 library problem or excessive strictness
  of HDF-EOS2/netCDF-4 verifier. We found one problem when we used netCDF-4.0.0,
  and the problem disappeared after moving to netCDF-4.0.1-beta2. So, you may
  need to upgrade netCDF-4.

  Also, the HDF-EOS2/netCDF-4 verifier does not catch all wrong conversions.
  The verifier traverses each object as HDF-EOS2 API leads. If some objects
  are invisible by HDF-EOS2 library, those objects are not verified.

