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=/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= option should be specified. The path should contain both the include/ and lib/ directories. Example: ./configure CC=/hdf4/bin/h4cc --with-hdf5= --prefix= or to activate the support of converting HDF-EOS2 files, use ./configure CC=/hdf4/bin/h4cc --with-hdf5= --with-hdfeos2= --prefix= 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.