Installing HDF-EOS5 using Autoconf/Automake

For hdfeos5 supported platforms linux64, linux32, Mac, and Cywin, and sun11 the easy and consistent
 method of hdf-eos5 installation is the use of INSTALL in /hdfeos5/bin directory where also installs 
jpeg, zlib, szip, hdf5, used in hdf-eos5. For other unsupported platform one may need to use autoconfig
installation as directed bellow.


1)  Quick Start (here we assume hdfeos5 directory is inside a directory 
considered as <target-dir>, and that the brand is linux. You may replace 
it with another supported brand name if you are installing hdfeos5 in a 
different platform)

To build HDF-EOS5 from <target-dir>/hdfeos5 and install the HDF-EOS5 library
into <target-dir>/hdfeos5/lib/linux :
    $ cd <target-dir>/hdfeos5
    $ ./configure --with-hdf5=/path/to/hdf5 --libdir=<target-dir>/hdfeos5/lib/linux
    $ make
    $ make install

If your HDF5 is 1.8.X version you will need -DH5_USE_16_API flag for compiling of HDF-EOS5.
If you are using HDF5 1.6.X version, then this flag is not needed. There reason is that 
with 1.8.X the HDF Group modified some HDF5 APIs, increasing number of their arguments. In
HDFD-EOS5 we did not change the calls for those APIS, using the same number of arguments 
as in HDF5-1.6.X releases. So HDF group provided this flag so that HDF5-1.8.X work as 
HDF5-1.6.X, and let HDF-EOS5 compile without changing APIs.

For example you may need to do the following before running ./configure

    $ setenv CFLAGS "-g -DH5_USE_16_API"

See also example in section 10 below.

You may also need one of the following flags if you are using the corresponding platform:

flag			platform
--------               ---------
DEC_ALPHA		dec alpha	
IRIX			sgi
SGI64			64-bit sgi compilation
UNICOS			cray
LINUX64			linux 64-bit compilation
IA64			linux (in PC with itanium chip)
MACINTOSH		power mac
MACINTEL		intel mac (32 and 64-bit compilation)
IBM6000			ibm
CYGWIN			cygwin

So for example for 64-bit linux compilation with HDF5-1.8.19 you will need to set:

    $ setenv CFLAGS "-g -DH5_USE_16_API -DLINUX64"

2)  Configuration

HDF-EOS5 uses the GNU autoconf system for configuration, which detects various
features of the host system and creates the Makefiles. On most systems with
HDF-EOS5 installed it should be sufficient to say:

    $ ./configure               OR      
    $ sh configure

The configuration process can be controlled through environment variables
and command-line switches.  For a complete list of switches type:

    $ ./configure --help

Configure must be re-run for each platform, and the source tree can only be
configured for one platform at a time.

In 64-bit machines one must set the desired compiler flag for the compilation
 mode before running ./configure. For example to install HDF-EOS5 in 32-bit
 mode in SGI one must set CC as:
setenv CC "cc  -n32"

or to install HDF-EOS5 in 64-bit mode in SGI one must set CC as:
setenv CC "cc  -64"

In a 64-bit linux or Macs Intel the 32-bit flag is "-m32". So for 32-bit installation
one must set CC as:
setenv CC "gcc  -m32"

The same is applied to the FORTRAN compiler flag.

3)  Building against HDF5

On systems without HDF5 installed, where HDF5 is not found automatically,
or to link against a different version of the HDF5 library, the user must
specify the path to HDF5.  This can be done either by giving the path to
configure directly:

    $ ./configure --with-hdf5=/path/to/hdf5

or by setting the environment variable CC to be the h5cc script installed
with HDF5:

    $ H5CC=/path/to/hdf5/bin/h5cc
    $ ./configure
or 
    $ setenv H5CC /path/to/hdf5/bin/h5cc
    $ ./configure


4)  Building against ZLIB and SZLIB

HDF-EOS5 does not require the zlib and szlib libraries to build,
but some of the tests in the testdrivers directory require them.  Their
paths can be given to configure using the --with-zlib and --with-szlib
switches:

    $ ./configure --with-zlib=/usr/local/zlib --with-szlib=/usr/local/szlib


5)  Specifying install locations

The location where the HDF-EOS5 library will be installed is controlled by
the --libdir switch.  To set the install location to
<target-dir>/hdfeos5/lib/linux :

    $ ./configure --libdir=<target-dir>/hdfeos5/lib/linux

HDF-EOS5 tradionally installs libraries into the hdfeos5/lib/* directories
and does not install header files.  Users who wish to install both libraries
and header files should use the --enable-install-include switch to enable
this feature and the --prefix switch to control where they are installed.
To install into /usr/local/hdfeos5/include and /usr/local/hdfeos5/lib :

    $ ./configure --enable-install-include --prefix=/usr/local/hdfeos5

The default installation location if no flags are specified is a directory
named hdfeos5 in the current directory, with libraries in hdfeos5/lib and
include files in hdfeos5/include (if installing include files is enabled).


6)  Building and Installing

Once HDF-EOS5 has been configured, its makefiles can be used to build, test,
and install.  To build the library:

    $ make

To run tests (if present):

    $ make check

To install to the location specified during configure:

    $ make install

These commands do not need to be run in order; if the library has not been
built, 'make install' will build it before installing.  However, configure
must always have been run on the current system before running make.


7)  The Testdrivers Directory

The testdrivers directory contains test to verify that HDF-EOS5 has built
correctly.  Users who wish to run these tests should copy the testdrivers
directory into the hdfeos5 directory before running configure.  Configure
will detect the presence of this directory and 'make check' will run all
the tests it contains.


8)  For More Information

For more information about using autoconf and automake, see the
documentation online at
http://sources.redhat.com/autobook/autobook/autobook.html
or HDF5's documentation.


9) Fortran compiler options
This section explains what FCFLAGS is expected when you get errors.

1. -fno-second-underscore option
Linkers may complain undefined references; e.g.

   undefined reference to `swrdfld__`

Mostly, this error is caused by different name mangling methods.  In the
HDF-EOS library, Fortran API functions have one underscore; e.g. 'swrdfld_'.
However, some Fortran compilers assumes external functions have two
underscores like 'swrdfld__', which doesn't exist in the library.

Other Fortran compilers may have different name mangling methods, and the user
may need to read their documents to match the name mangling method.

2. Linking errors
You may get some linking errors while Fortran testdrivers are built. Some
systems may require additional libraries. Generally, h5cc can detect these
additional libraries and pass them to the linker. That's the reason why you
may not encounter linking errors while building the HDF-EOS5 library.

To build Fortran testdrivers, however, pure Fortran compilers are used, which
means there is no helper that can do what h5cc does. So, if you get some
linking errors, you need to set additional libraries before executing
configure script:

    $ LIBS=<additional libraries>
or
    $ setenv LIBS <additional libraries>

We got a problem under Solaris, and we had to set LIBS environment variable as
the following:

    $ LIBS=-lnsl
or
   $ setenv LIBS -lnsl


10} Example

1.  In 64-bit Linux  machine for 32-bit installation:

>setenv CC "/tools/pgs/ataaheri/TOOLKIT/hdf5/linux32/hdf5-1.8.19/bin/h5cc -Df2cFortran -DH5_USE_16_API"
>setenv FC "/usr/bin/g77 -fno-second-underscore -DH5_USE_16_API"
>setenv CFLAGS -m32
>setenv FCFLAGS -m32
>setenv LDFLAGS -m32
>./configure --libdir=/User_Home/hdfeos5_autoconfig/hdfeos/lib/linux32 --enable-install-include --prefix=/User_Home/hdfeos5_autoconfig/hdfeos --with-hdf5=/User_Home/TOOLKIT/hdf5/linux32/hdf5-1.8.19 --with-zlib=/User_Home/TOOLKIT/zlib/linux32/zlib-1.2.11 --with-szlib=/User_Home/TOOLKIT/szip/linux32/szip-2.1.1 --with-jpeg=/User_Home/TOOLKIT/jpeg/linux32/jpeg-9b
>make
>make check
>make install

2  In 64-bit Linux  machine for 64-bit installation:

>setenv CC "/tools/pgs/ataaheri/TOOLKIT/hdf5/linux64/hdf5-1.8.19/bin/h5cc -Df2cFortran -DH5_USE_16_API"
>setenv FC "/usr/bin/g77 -fno-second-underscore -DH5_USE_16_API"
>setenv CFLAGS  -DLINUX64
>setenv FCFLAGS  -DLINUX64
>setenv LDFLAGS  -DLINUX64
>./configure --libdir=/User_Home/hdfeos5_autoconfig/hdfeos/lib/linux64 --enable-install-include --prefix=/User_Home/hdfeos5_autoconfig/hdfeos --with-hdf5=/User_Home/TOOLKIT/hdf5/linux64/hdf5-1.8.19 --with-zlib=/User_Home/TOOLKIT/zlib/linux64/zlib-1.2.11 --with-szlib=/User_Home/TOOLKIT/szip/linux64/szip-2.1.1 --with-jpeg=/User_Home/TOOLKIT/jpeg/linux64/jpeg-9b
>make
>make check
>make install
