H4H5TOOLS version 2.2.4 released on 2018-09-14
================================================================================

1. Introduction
===============

This document describes the H4H5TOOLS and contains information on
the platforms tested and limitations. The H4H5TOOLS distribution includes
three products: H4toH5 conversion library, H4toH5 conversion utility,
and H5toH4 conversion utility.

Both the H4toH5 conversion library and the H4toH5 conversion utility follow
the HDF4 to HDF5 mapping document.  This document can be found at:
    https://portal.hdfgroup.org/display/HDF5/Mapping+HDF4+Objects+to+HDF5+Objects

The H4toH5 conversion library user guide and reference manual can be found at:
    https://portal.hdfgroup.org/display/support/h4h5+User%27s+Guide
    https://portal.hdfgroup.org/display/support/h4h5+Reference+Manual

If you have any questions or comments, please send them to:
    help@hdfgroup.org


2. Platforms Tested
===================
This release is tested with HDF4 v4.2.14 and HDF5 v1.8.21 and v1.10.4 on the following
platforms and compilers:

    Linux 2.6.32-696.16.1.el6.ppc64 gcc (GCC) 4.4.7 20120313 (Red Hat 4.4.7-18)
    #1 SMP ppc64 GNU/Linux        IBM XL C/C++ V13.1
    (ostrich)

    Linux 3.10.0-327.10.1.el7   GNU C (gcc)
    #1 SMP x86_64 GNU/Linux       compilers:
    (kituo/moohan)                Version 4.8.5 20150623 (Red Hat 4.8.5-4)
                                    Version 4.9.3, Version 5.2.0,
                                  Intel(R) C (icc)
                                  compilers:
                                     Version 17.0.0.098 Build 20160721

    SunOS 5.11 32- and 64-bit     Sun C 5.12 SunOS_sparc
    (emu)

    Windows 7                     Visual Studio 2015 (cmake)

    Windows 7 x64                 Visual Studio 2012 (cmake)
                                  Visual Studio 2013 (cmake)
                                  Visual Studio 2015 (cmake)
                                  Visual Studio 2015 w/ Intel C (cmake)

    Windows 10                    Visual Studio 2015 (cmake)

    Windows 10 x64                Visual Studio 2015 (cmake)
                                  Visual Studio 2017 (cmake)

    Mac OS X Yosemite 10.10.5     Apple clang/clang++ version 6.1 from Xcode 7.0
    64-bit
    (osx1010dev/osx1010test)      Intel icc version 15.0.3

    Mac OS X El Capitan 10.11.6   Apple clang/clang++ version 7.3.0 from Xcode 7.3
    64-bit
    (osx1011dev/osx1011test)      Intel icc version 16.0.2

    Mac OS Sierra 10.12.6         Apple LLVM version 8.1.0 (clang/clang++-802.0.42)
    64-bit
    (kite)                        Intel icc 17.0.2

2.1 Optional Feature
====================
The h4toh5 command-line utility, with the options (-eos -nc4 -nc4strict)
that can convert HDF-EOS2 to netCDF-4, is tested with HDF4 V4.2.14,
HDF5 1.8.21 and HDF5 1.10.3, HDF-EOS2 2.20, and ncdump from the netCDF 4.4.1.1 
distribution on the following platform and compiler:

   Linux 3.10 (x86_64), gcc 4.8.5
   Mac OS X EI Capitan 10.11.4 Apple LLVM version 7.3.0 (clang-703.0.29)
   MacOS X Sierra 10.12.6 Apple LLVM version 8.1.0 (clang-802.0.42)


3. New Features and Bug Fixes Since Version 2.2.3
=================================================
   Configuration
   -------------
    - CMake

      Update CMake commands configuration.

      A number of improvements were made to the CMake commands. Most
      changes simplify usage or eliminate unused constructs. Also,
      some changes support better cross-platform support. Changes
      follow from hdf5.

      (ADB - 2018/02/01, HDFFV-10398)

   Library
   -------
   - The HDF5 1.8.21 and HDF5 1.10.3 fix a bug that causes the failures of
     dumping the converted NASA AIRS and MODIS HDF5 files.

   Tools
   -----
   - When the HDF4 SDS has dimension names but doesn't specific the dimension 
     scales, the conversion tool will check if there is a 1-dimensional SDS 
     that shares the above mentioned dimension names; if yes, the conversion
     tool will use treat this SDS as the dimension scale. With this improvement,
     NASA MODIS level 1B products can be successfully converted to HDF5 files
     that follow the netCDF-4 data model. This option is only available for
     the default option(./h4toh5 M1.hdf M1.h5).
     

   Documentation
   -------------
   - No major update


4. Known problems
=================

   - [None]

5. Optional HDF-EOS2/netCDF-4 Verifier
======================================
An optional HDF-EOS2/netCDF-4 verifier utility is available with the
2.2.3 release in the subdirectory misc/verify_eos2nc4/.  See the
README.txt file under that directory.

6. Limitations
==============
1. h4toh5: For the option -na(h4toh5 -na), if a dimension name is assigned to 
           an HDF4 SDS dimension, that dimension must have a dimension scale.
           Otherwise, an error will be generated.
2. h5toh4: Check the h5toh4_limitation.txt under /release_docs.



CMake vs. Autotools installations
=================================
While both build systems produce similar results, there are differences.
Each system produces the same set of folders on linux (only CMake works
on standard Windows); bin, include, lib and share. Autotools places the
COPYING and RELEASE.txt file in the root folder, CMake places them in
the share folder.

The bin folder contains the tools and the build scripts (autotools only).
Additionally, CMake creates dynamic versions of the tools with the suffix
"-shared". Autotools installs one set of tools depending on the
"--enable-shared" configuration option.
  build scripts
  -------------
  Autotools: h4h5cc

The include folder holds the header files.

The lib folder contains the library files.

The share folder will have the most differences because CMake builds include
a number of CMake specific files for support of CMake's find_package and support
for the H4H5 Examples CMake package.

