
    Installation Instructions for HDF4 on Unix and Mac OSX Platforms
    ===================================================================

CONTENTS

1. Third-party Software Requirements
2. Optional Szip Compression Library
3. HDF4 Source Code and Precompiled Binaries 
4. Unix and Mac OSX Configuration and Build
5. Using HDF/MFHDF Libraries with the netCDF Library (libnetcdf.a)



1. Third-party Software Requirements
   =================================

C and Fortran compilers. If a Fortran compiler is not available, use 
the --disable-fortran configure flag to build the HDF4 C library and 
utilities. For the list of the supported compilers see RELEASE.txt in the 
release_notes directory.

JPEG Distribution Release 6b or later (libjpeg.a(so)). The source code can 
be downloaded from http://www.ijg.org/.

ZLIB 1.1.4(libz.a) or later. The software can be downloaded from: https://zlib.net/ 



2. Optional Szip Compression Library
   =================================

HDF4 may be configured to use the Szip compression library. For more 
information about the Szip library, see:

   https://portal.hdfgroup.org/display/HDF4/Szip+Compression+in+HDF+Products 

The Szip compression library is free for non-commercial use. For information 
regarding commercial use, see: 

   https://portal.hdfgroup.org/display/HDF4/Szip+Copyright+and+License+Statement%2C+as+Distributed+in+the+HDF+Source+Code



3. HDF4 Source Code and Precompiled Binaries
   =========================================

The HDF Group provides source code and pre-compiled binaries from the
HDF4 download page:

   https://portal.hdfgroup.org/display/support/Download+HDF4 
   
As of HDF 4.2.6, binaries are packed with the ZLIB, JPEG, and Szip libraries
that were used to build the binaries. 

HDF4 pre-built utilities come with Szip compression. To use these binaries, 
you must install the Szip library on your system. 

To build the Szip library, follow the instructions in the Szip source code
distribution, which can be obtained from:

    https://portal.hdfgroup.org/display/HDF4/Szip+Compression+in+HDF+Products



4. Unix and Mac OSX Configuration and Build
   =======================================

See RELEASE.txt in the release_notes/ directory for the list of platforms 
tested for this release.

Before You Start:

   1)  Make sure that the ZLIB and JPEG libraries are installed on your
       system.

   2)  Optional: Install the Szip version 2.1 library (you may use
       Szip 2.0 binaries). 

   3)  Extract the source from the hdf-X.Y.Z.tar file and change
       directory to hdf-X.Y.Z.

   4)  Fortran Notes:
         4.a)  g77 may require compiler flag, FFLAGS, "-fno-second-underscore"

To Configure:

   4)  Use the configure command in the top level HDF4 directory hdf-X.Y.Z:

       Note: On macOS platforms version 10.13 or newer, XDR functions from the 
       system libraries do not work with HDF4.  It is therefore necessary
       to build the internal HDF4 XDR library, using --enable-hdf4-xdr for 
       autotools configure, or adding the corresponding CMake option:
       set (ADD_BUILD_OPTIONS "${ADD_BUILD_OPTIONS} -DHDF4_BUILD_XDR_LIB:BOOL=ON")
       to HDF4options.cmake.  The options may also be used but are not required
       on Linux platforms. 

       ./configure --with-zlib=/path_to_ZLIB_install_directory 
                   --with-jpeg=/path_to_JPEG_install_directory 
                   [--with-szlib=/path_to_SZIP_install_directory]
                   [--enable-hdf4-xdr]
                   --prefix=/path_to_HDF4_install_directory

       * Please note that when the szlib option is not used, the Szip 
         library will not be configured in and Szip compression will not 
         be enabled.
       * If your system has the ZLIB and/or JPEG libraries installed under a
         system library directory (such as /usr/lib), configure will
         automatically find the library. In this case, the corresponding
         configure flag may be omitted.
       * Note that --prefix defines where the installation path is.
         The default is set as <hdf4_build_directory>/hdf4.

To Build and Test:

   5)  To build the library:

       gmake >& gmake.out

   6)  To build and run the tests:

       gmake check >& check.out

To Install:

   7)  To install the HDF4 library and tools:

       gmake install

   8)  To install C and Fortran examples:
    
       gmake install-examples

   9)  To test the installation:

       gmake installcheck

   10) By default, the current configuration uses vendor compilers; to use
       another compiler, run the following commands before running configure: 

       setenv CC   "foo -flags"
       setenv F77  "fffoo -flags"

       See the configure help page (configure --help) for a list of
       environment variables that have an affect on building the library.

   11) You may build HDF4 in a directory other than hdf-X.Y.Z by using
       the "srcdir" option. Simply create a build directory and type:

       <path_to_hdf-X.Y.Z>/configure ...

       where "..." are your configuration options.



5. Using HDF/MFHDF Libraries with the netCDF Library (libnetcdf.a)
   ===============================================================

   To use the HDF/MFHDF libraries (libdf.a, libmfhdf.a) with the 
   netCDF library (libnetcdf.a), the HDF4 distribution must be configured 
   with the --disable-netcdf configuration flag. 

   When this flag is used, the HDF versions of the C netCDF functions 
   (as of netCDF version 2.3.2) are renamed from ncxxx to sd_ncxxx, 
   and HDF Fortran netCDF wrappers are disabled to avoid name clashes with 
   the netCDF C and Fortran functions from libnetcdf.a.

   Please report all problems to help@hdfgroup.org.


6. Windows Configuration and Build
   ===============================

See RELEASE.txt in the release_notes/ directory for the list of platforms 
tested for this release.

We now recommend that users build, test, and install HDF4 using CMake.

Instructions for building and testing HDF4 using CMake can be found in the
INSTALL_CMake.txt file found in this folder.

For instructions on building and testing an application with HDF4, see the 
USING_HDF4_CMake.txt file found in this folder.

Users who want to build and run an application with HDF4 in Visual Studio
without using CMake should consult the USING_HDF4_VS.txt file.

Additional Third-party Software Requirements:

   1)  Flex and Bison programs are required to regenerate the ncgen parsers.
       This is not required to build the library and is only necessary if you
       change the input files.
   
   2)  The Win flex-bison project, a port of Flex & Bison tools 
       to the Windows platform, is recommended. Download from:
           http://sourceforge.net/projects/winflexbison

   3)  CMake version 2.8.11.1 or higher is needed to use Win flex-bison. 
       Using an earlier version of CMake will require renaming the executables
       without the "win_" prefix.

