
       H4toH5 Conversion Library, and h4toh5/h5toh4 tools 
       ===================================================
                 installation instructions
                 =========================

NOTE: PLEASE LOOK AT 3.3 BEFORE YOU DECIDE NOT TO READ THE DOCUMENT.


 1. Obtaining H4toH5 library and tools
 2. Preconditions
 3. Quick installation instructions for UNIX platforms 
 4. Quick installation instructions for Windows platforms 
 5. General remarks and known problems
 6. Platforms tested
 

 1. Obtaining H4toH5 library and tools source code
 -------------------------------------------------

	The latest supported public release of the H4toH5 Conversion Library 
        and tools is available from ftp://hdf.ncsa.uiuc.edu/HDF/HDF5/h4toh5. 

 2. Preconditions
 ----------------

	The following libraries have to be installed on the system:
		HDF4 Library
		HDF5 Library
                ZLIB (required for HDF4)
                JPEG (required for HDF4)
                SZIP (optional for HDF4 and HDF5)
	Check http://hdf.ncsa.uiuc.edu for source code and installation 
	instructions, or for prebuilt binaries. Also see 4.2 below.

 3. Quick installation instructions for UNIX platforms
 -----------------------------------------------------

    0. Before you start, make sure that the h4cc script under the bin/ directory of
       the HDF4 installation works. (Try to use it to compile and run any
       HDF4 program. Programs may be found under
       http://hdf.ncsa.uiuc.edu/tutorial4.html .)

    1. Unpack the source tar ball.
		$ gunzip h4h5tools-1.2.tar.gz | tar xf -

    2. Change directory to h4h5tools-1.2/ .
  		$ cd h4h5tools-1.2

    3. Set environment variables:
 
       Set environment variable CC to use h4cc. (THIS IS IMPORTANT!!!)
		$ setenv CC /HDF4PATH/bin/h4cc
       Set environment variable LD_LIBRARY_PATH if you use HDF5 shared 
       library, and/or SZIP 2.0 shared library.
    
                $ setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/HDF5PATH/lib:
                         /SZIP-2.0PATH/lib
       See also 4.1

    4. Run configure specifying the HDF5 location and installation directory.
		$ ./configure --with-hdf5=HDF5PATH --prefix=H4toH5PATH  

    5. Build library and tools.
		$ make

    6. Build and run tests.
		$ make check

    7. Install library and tools.
		$ make install

    8. You may find a compiled h4toh5 programming example under
       the lib/examples/ directory of the h4h5tools distribution.

    9. Clean after the build.
		$ make clean     (deletes object, executable and library)
                   or
		$ make distclean  (deletes all files above and files created by
                                   running the configuration step)

   10. Report all problems to hdfhelp@ncsa.uiuc.edu after you check the 
       sections below.	

 4. Quick installation instructions for Windows platforms
 -----------------------------------------------------
    
    For Windows installation instructions see install_windows.txt
    in the windows/h4h5proj.zip archive

 5. General remarks and known problems
 --------------------------------------

    1. If you built and/or installed the shared HDF5 library, make sure that
       LD_LIBRARY_PATH is set to include HDF5
     		setenv LD_LIBRARY_PATH ${LD_LIBRARY_PATH}:/HDF5PATH/lib
       Note that this must be set at configure time to detect compression settings
       properly.

    2. If you built the HDF4 and HDF5 libraries yourself, make sure you used
       consistent settings for both libraries:
 		* the same C compiler
		* HDF5 is built with GZIP compression enabled (i.e. with the ZLIB
                  library) if you want to create compressed HDF5 files from
                  compressed HDF4 files
		* HDF4 and HDF5 are built with SZIP compression enabled, 
                  if you want to use optional SZIP compression. 
                  SZIP is a licensed software. Check
                  http://hdf.ncsa.uiuc.edu/doc_resource/SZIP/ for terms
                  and conditions.

    
    3. Platform specific notes:

		Solaris 2.8

		Use -Xa flag with h4cc; you may use the CFLAGS environment variable
                to set additional compiler flags.

    4. Known problems:

       The --scrdir configure option doesn't work

       If HDF4 and/or HDF5 libraries do not include GZIP and/or 
       SZIP compression, tools will be unable to read compressed files.


   6. Platforms tested
   --------------------
   
      This release is tested with the HDF4 r2.1, HDF5-1.6.4 and SZIP-2.0
      libraries on the following platforms:

      Solaris 2.8 32 and 64-bit
      Linux 2.4
      FreeBSD
      AIX 5.1 32 and 64-bit
      HPUX 11.00
      IRIX64-6.5 64bit only
      OSF1 V5.1
      Mac OSX
      AMD Opteron
      Windows XP with MSVC++
