H4H5TOOLS Installation Instructions for Unix

*******************************************************************************
Section I: What Do We Build and Install

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

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

*******************************************************************************
Section II: Building and Testing h4toh5 Libraries and Utilities

1. Prerequisites

  HDF4 Library
  HDF5 Library
  HDF-EOS2 Library (optional)

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

2. Configure
  The previous release needed the preprocessor option CPPFLAGS to be defined if
  you used HDF5 1.8 or higher. This release removes this limitation: you 
  do not need to pass the option to the configure script if you use HDF5 1.8 or 
  higher. This change also maintains backward compatibility with HDF5 1.6. 


  C Compiler (CC)
    The 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 compilers might complain. We could see cc in Solaris complain about 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, the --with-hdfeos2=<path>
    option should be specified. The path should contain both the include/ and lib/
    directories.

  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, use
      ./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"
      and then run configure as shown above.
      
               

3. Build
  GNU make is recommended to build H4H5TOOLS. Use the following:
    $ 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 netCDF-4. If shared HDF5 and GCTP libraries(for
  the --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 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 the netCDF-4 library and to define
    the path to the 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 the netCDF-4 library. Users may see the output
    from ncdump on the screen. This is okay. Finally you should see the message
    "all h4toh5 tests passed."

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


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

  If the --with-hdfeos2 option is used, the h4toh5 conversion utility will recognize 
  the following 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 netCDF-4-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 the conversion of any object does not follow
    the netCDF-4 data model.


  One can type the following command to convert the
  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

  Version 2.2.0 also supported the -nc4 and -nc4fakedim options. In
  version 2.2.1 and later, these two options are not supported. Users should refer
  to the 2.2.0 version for information on how to use these two options.


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

  The H4H5TOOLS distributions for version 2.2.1 and later 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.

