----------------------------------------------------------------
Instructions for the installation of H4H5TOOLS in UNIX platforms
----------------------------------------------------------------

CONTENTS

1.  Obtaining h4h5tools
2.  Warnings about compilers
3.  Introduction to configuration
4.  h4toh5 installation
5.  Using the library
6.  Platform specific hints
7.  Supported platforms and compilers
8.  Support

--------------------------------------
1. Obtaining h4h5tools
--------------------------------------
h4h5tools source codes can be obtained from ftp://hdf.ncsa.uiuc.edu

--------------------------------------
2.  Warnings about compilers
--------------------------------------
Due to the use of both HDF4 and HDF5 libraries, some redefinition warnings are 
generated. These will be automatically fixed when HDF4 and HDF5 libraries are fixed.

--------------------------------------
3. Introduction to configuration
--------------------------------------
H4H5TOOLS uses the GNU autoconf system for configuration, which detects various 
features of the host system and creates the Makefiles.

The configuration process can be controlled through environment variables, 
command-line switches, and host configuration files.
For a complete list of switches type:
$ ./configure --help

The host configuration files are located in the `config' directory and are based 
on architecture name, vendor name, and/or operating system, which are displayed 
near the beginning of the`configure' output. The host config file influences 
the behavior of configure by setting or augmenting shell variables.

--------------------------------------
4. h4h5tools installation
--------------------------------------

By default, h4h5tools will be built with shared library. Process 1) to 4) is 
the instruction of building shared version of H4toH5 libraries.

1) Configuration  
To correctly generate the configuration process for h4toh5 library, one has to use:

% setenv CC  /<where_HDF5_is_installed>/bin/h5cc
% ./configure --with-hdf4=/<where_HDF4_is_installed> --prefix=/<where_to_install>

Assume:
HDF5 public header files are stored at /*your hdf5 path*/include,
HDF5 libraries are stored at /*your hdf5 path*/lib
HDF4 public header files are stored at /*your hdf4 path*/include
HDF4 libraries are stored at /*your hdf4 path*/lib

2) Generate library

type 'gmake' (GNU make) or 'make'

3) Check the library

type 'gmake check' or 'make check'

You should see "All h4toh5 tests passed."
   
4) Install the library

type 'gmake install' will install your library into the directory you set. 
Without setting prefix, the library will be stalled at /usr/local

To build the static library, disable-shared has to be used. 
Step 1) in the above should be added --disable-shared 
 
--------------------------------------
5.Using the H4toH5 conversion library
--------------------------------------

In order to use the H4toH5 conversion library, you have to include "h4toh5.h" 
in your header file and link with HDF4, HDF5, H4TOH5 and zlib libraries. 
Please see the User's guide 
at http://hdf.ncsa.uiuc.edu/h4toh5/h4toh5lib_UG.pdf 

--------------------------------------
6. Platform specific hints
--------------------------------------

1) Solaris 2.7 and 2.8

This environment variable has to be manually set:

    setenv LD_LIBRARY_PATH <my_hdf5_install/lib>:${LD_LIBRARY_PATH}

This will force the linking with the hdf5 installed library.

2) Linux 2.4

When using the h5cc script built using the PGI compiler (pgcc), this
environment variable may have to be set manually:

    setenv LIBS "-ljpeg"

This will use the system's JPEG library to resolve symbols not found in
the HDF4 JPEG library.
 
3) AIX 5.1 

Use --enable-static --disable-shared with configire.

4) IA64 system
  On IA64 systems one has to use -DIA64 compilation flag to compile
  h4h5tools. After configuration step manually modify
  Makefile in the lib/src,lib/test, utils/h4toh5 and utils/h5toh4 
  directories to add -DIA64 to the compilation flags.

	* On IA32 and IA64 systems, if you use a compiler other than GCC (such as
	  Intel's ecc or icc compilers), you will need to modify the generated
	  "libtool" program after configuration is finished. On or around line 104
	  of the libtool file, there are lines which look like:

          # How to pass a linker flag through the compiler.
          wl=""

      change these lines to this:

          # How to pass a linker flag through the compiler.
          wl="-Wl,"

--------------------------------------
7. Supported platforms and compilers
--------------------------------------

For supported platforms and compilers see 
http://hdf.ncsa.uiuc.edu/HDF5/release/SuppConfigFeats.html and REELASE.txt
file in the release_docs directory of the HDF5 source code distribution.

--------------------------------------
8. Support
--------------------------------------

Contact with hdfhelp@ncsa.uiuc.edu

