
$Id: INSTALL 22721 2010-05-12 16:43:05Z jimg $

Installing the HDF4 handler for the OPeNDAP server.

Updated for 3.8.1

---------------------------------------------------------------------------

BUILDING THE SOFTWARE
REQUIREMENTS
NOTES

---------------------------------------------------------------------------

BUILDING THE SOFTWARE

0) Please skim REQUIREMENTS and NOTES sections of this file before reporting
   problems. Thanks.

*) IMPORTANT NOTE: The versions of hdf4 that are installed by package
    managers such as Yum and rpm often are not capable of being linked with a
    shared library/module, whcih is how the hdf4 handler must be built. To
    correct this, you may need to build the HDF4 library from soruce and
    specify the '--with-pic' option to configure. This may be a problem only
    on non-i386 linux machines; reports vary. To build the handler on OS/X
    and an AMD 64-bit machine running Fedora Core 10 Linux (very similar to
    Red Hat or CentOS) it was necessary to build hdf4. To d so I ran
    configure as './configure --with-pic --disable-fortran --disable-netcdf'

1) Type `./configure' at the system prompt. On some systems you may have to
   type `sh configure.' If you want this part of the server to install
   someplace other than /usr/local/bin, use --prefix to change the prefix
   from the default "/use/local/." 

   OPTIONAL: 

   To support HDF-EOS2 files better for OPeNDAP visualization clients, 
   you may want to configure with two more options. 

   Type `./configure --enable-cf --with-hdfeos2=/path/to/HDF-EOS2_library'

   They will include the enhancement work for HDF4 handler supported by 
   a NASA grant.

   This requires the installation of HDF-EOS2 library. You can download it
   from http://newsroom.gsfc.nasa.gov/sdptoolkit/tookit.html.

   Another possibility is to install with '--enable-cf' option only.

   Type `./configure --enable-cf'

   This doesn't require the installation of HDF-EOS2 library and it works
   for some HDF-EOS2 Grid / Swath files. This is less recommended option 
   since HDF-EOS2 library can support more HDF-EOS2 files.

    NB: To build the HDFEOS library on a 64-bit fedora core platform
    using the FC RPMs for hdf4, do the following: First download
    HDF-EOS2.16v1.00.tar.Z (Google should be abe to locate it). Then
    define CFLAGS, CPPFLAGS and LDFLAGS as:

    	   CPPFLAGS=-I/usr/include/hdf
	   CFLAGS="-g -O2 -fPIC"
	   LDFLAGS="-L/usr/lib64/hdf"

    I was not able to get the --with-hdf4 option to find the library
    file or the header and the -fPIC option is needed even though the
    library builds a static archive only because we're going to link
    it into a shared object. 

    Lastly, 'make install' installs the archive into 'hdfeos2/' in the
    top-level directory of the distribution. I had to copy the include
    directory, also at the top-level of the distribution, into
    'hdfeos2/' to get the code here to compile and link. I made a link
    to /usr/local/hdfeos2 and then ran configure here as:

           ./configure --enable-cf --with-hdfeos2=/usr/local/hdfeos2

    jhrg 8/7/09

2) Type `make' to build the server module.

3) Install the server module in $prefix by running `make install'. This
   will also add the new h4.conf file to the $prefix/etc/bes/modules directoy.
   The BES configuration file bes.conf will automatically load any module
   configuration files in that directory. The h4.conf file contains hdf4_handler
   specific configurations for use with the BES Framework. This includes
   some parameters that used to be in the bes.conf file, such as the TypeMatch
   parameter for finding your files.

4) For some installations, you must arrange for your operating system to find
   the shared libraries installed by default in $prefix/lib. Do this by
   either setting an environment variable such as LD_LIBRARY_PATH or by
   editing /etc/ld.so.conf. Different operating systems handle this in
   different ways.

Building from Our SVN Repository

  If you are building from a SVN checkout, run 'autoreconf --verbose'
  before './configure; make'. If you try to run autoconf, et c., by
  hand and wind up with build files that don't work, use 'autoreconf
  --force --install --verbose'. Once autoreconf has made the configure
  and Makefile.in files, do ./configure; make; make install as
  outlined above.

REQUIREMENTS

  o You need the libdap library version 3.10.0 to build and install this
    software. If you're using Linux, this means either building form source
    or using the libdap and libdap-devel RPM packages.

  o If you're planning on using this with the OPeNDAP 4 Data Server (Hyrax),
    you'll need version 3.8.0 of the BES software. Make sure to build that 
    first.

  o You also need a recent copy of HDF4. We've tested this server with
    version 4.2r1 and 4.2r4, although any recent version should work fine. 
    In order to link with 4.2r4 on Linux (and maybe other platforms) I had to
    compile HDF4 using --without-fortran --with-pic and I also used 
    --without-netcdf (because some sites need their HDF4 libraries built that
    way and I wanted to be sure the handler would build with that 
    configuration). If the configure script cannot find your copy of hdf4, use
    the --with-hdf options to tell it where to look (see configure --help).

NOTES

  o This handler uses a configuration parameter, set in the bes.conf file, to
    control where copies of some metadata objects built by the server are 
    cached. By default this cache is in /tmp - you are encouraged to change
    that. Set the location using the 'HDF4.CacheDir' parameter. For example,
    if you have set the BES.CacheDir parameter to /var/run/bes/cache you might
    set HDF4.CacheDir to /var/run/bes/hdf4_cache. 

  o DEBUGGING AIDS

    - The OPeNDAP libdap library includes the following debugging aids that
      may be of help to you in developing new applications.

    - DBG: simple program instrumentation -- see the file debug.h distributed
      with libdap (which is installed in the libdap header directory; use
      'config-libdap --cflags' and look at the value if -I).

    - DBG2: more elaborate program instrumentation -- by convention this is
      used for output that is half a page or more, while DEBUG is used for
      single line output.

    - To build with program instrumentation use `--enable-debug=<level>'
      where <level> is 1 or 2.

    - By default, both debug and dbnew are *not* enabled. Thus, if you want
      to build a straight version of the libraries and test code, use
      `./configure'. If you want the extra features, use:

      ./configure --enable-dbnew --enable-debug=2
