
Updated for version 1.2.3 (10 September 2013)

---------------------------------------------------------------------------
Installation instructions for the OPeNDAP NcML Data Handling Module 
for the Hyrax Server

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

INTRO
BUILDING THE SOFTWARE
BUILDING FROM THE SVN REPOSITORY
BUILD REQUIREMENTS
      MAKE AND INSTALL
      TESTSUITE
CONFIGURATION NOTES
DEBUGGING AIDS
NOTES
     

---------------------------------------------------------------------------
INTRO

If you encounter any build problems after making sure you have
followed the BUILD REQUIREMENTS section, please send e-mail with as
much information about your operating system and the problem as you
can to <support@opendap.org>.

Thanks!

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

BUILDING THE SOFTWARE

0) Please read the BUILD REQUIREMENTS and NOTES sections of this file
   (below) before reporting problems.  

   This module is designed to work with Hyrax 1.6+ and will not work
   with older versions!  Make sure you have a working installation of
   Hyrax 1.6 before beginning this installation!

   You will also need 3.6 or higher of the ICU (International
   Components for Unicode) libs and headers.  See BUILD_REQUIREMENTS
   for more information.

   If you are building from the SVN repository, please also follow the
   instructions in BUILDING FROM THE SVN REPOSITORY before continuing.


1) Type `./configure' at the system prompt. On some systems you may
   have to type `sh configure.' 

   The default location for the install is "/usr/local".  If your BES
   is installed in a different location, please use the configure
   option "--prefix=$prefix" to change the prefix to the BES install
   location, where $prefix is where the Hyrax BES is installed.  (For
   this document $prefix will refer to this directory).

   NOTE: the CentOS RPM's install the BES to "/usr" and not
   "/usr/local".  If you are not sure, the BES will tell you its
   install dir when you run it with "besctl start".

   ** NON-STANDARD ICU LOCATION ** 

   If your ICU library and headers are installed in a non-standard
   (not /usr/local or /usr) location, the configure script optionally
   takes the argument "--with-icu-prefix=the_prefix_where_icu_is" to
   point at the installation.  It will then look for icu-config
   executable in the specified prefix location and use that version
   for the build.

   If you use this approach, note that you will likely need to also
   set an environment variable for finding the library at run-time,
   for example:

	bash$ export LD_LIBRARY_PATH=/the/icu/path/prefix/lib:${LD_LIBRARY_PATH}

   On Mac OS X, you need to set DYLD_LIBRARY_PATH instead:
   
	bash$ export DYLD_LIBRARY_PATH=/the/icu/path/prefix/lib:${DYLD_LIBRARY_PATH}
   
   These will need to be done in the shell you run the Hyrax server
   from or in the login file for the account running the server
   (presumably root).


2) Type `make' to build the handler.  


3*) (*Optional): You can perform a 'make check' to test the build,
    but note that this REQUIRES that you have all of the netcdf, hdf4,
    and hdf5 handlers already installed and working in Hyrax 1.6!  The
    testsuite uses netcdf, hdf4 and hdf5 datasets for testing.  Please
    see the BUILD REQUIREMENTS section under TESTSUITE if you wish to
    run the tests and do not have these handlers installed.
    Otherwise, you may skip this step.


4) Install the module into the BES by running `make install'.

   The install will also add the new ncml.conf file to the
   $prefix/etc/bes/modules directory. The BES configuration file
   bes.conf will automatically load any module configuration files in
   that directory. The ncml.conf file contains ncml_module 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 based on their suffix.

   
5) For many 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, DYLD_LIBRARY_PATH, or by editing
   /etc/ld.so.conf. Different operating systems handle this in
   different ways.


6) Restart Hyrax (BOTH the BES and OLFS) to load the module!


7*) (*Optional): Look at test data!
     
    First, check the installed sample_virtual_dataset.ncml which does
    not require any other handlers installed to test.  By default it's
    at: http://localhost:8080/opendap/ncml/sample_virtual_dataset.ncml

    Second, test the dataset wrapping by looking at the DDX response
    of the ncml test data that was installed, for example
    fnoc1_improved.ncml.ddx.  To view this file, you MUST have the
    netcdf module installed since it wraps the fnoc1.nc dataset.  See
    REQUIREMENTS->TESTSUITE below for more information.

    If you see an error like "Unable to add container, type of data
    must be specified", then your BES probably is not configured to
    serve netcdf data properly.  Set it up to serve netcdf data, test
    it, clear the cache, and try again.


---------------------------------------------------------------------------
BUILDING FROM THE SVN REPOSITORY

  If you are building from a SVN checkout, run 'autoreconf --install --verbose'
  before './configure; make'. If you try to run autoconf, etc., 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.  Make sure you have all the GNU tools necessary --- see BUILD
  REQUIREMENTS below.


---------------------------------------------------------------------------
BUILD REQUIREMENTS

  o MAKE AND INSTALL (no tests)
  
    o To build from a fresh SVN checkout, you'll need:

      	 o autoconf 2.62
      	 o automake 1.11
	 o libtool 2.2.6

      Earlier versions may work, but may cause problems, particularly
      with the 'distcheck' target for make. Given those requirements,
      use 'autoreconf --force --install --verbose' and then build as
      described above.

      You may check the versions being used by the build with, e.g.:

      `which automake` --version

      at a command prompt if you have any build issues to be sure you
      are finding correct versions. (Substitute automake for the
      other gnu tools)
      

    o You should have gcc/g++ 3.3.x or greater. You'll also need to
      get the stdc++ library that matches the compiler (whatever
      version). NB: gcc 2.8.x and earlier *won't* build the
      software. We're working on modifying the software so that it
      will build with a variety of compilers. As of 01/22/03 we have
      built the code using Microsoft's Visual C++ 6.0 and GNU gcc/++
      3.2.1, 3.3, 3.4 and 4.0

    o You need the libdap library version 3.10.0 or greater to build
      and install this software. If you're using Linux, this means
      either building from source or using the libdap and libdap-devel
      RPM packages.  These are available at
      http://www.opendap.org/download/hyrax.html.  NOTE: libdap
      requires libxml2 2.6.16 and libcurl 7.10.6 as well.
      	  
    o You'll need version 3.8.0 or greater of the BES software
      installed before building the handler.  This is part of Hyrax
      1.6.  Build, install, and test it BEFORE you build this handler.
      
      For Linux, you can get the bes and bes-devel RPM packages from
      http://www.opendap.org/download/hyrax.html.

    o You'll also need the OLFS for Hyrax 1.6 though it is not needed
    to build and install the software, only for the final test.

    o The NcML Module itself uses libxml2 2.6.16 which should be
      satisfied since libdap requires it as well.
      
    o ICU 3.6 (or higher): You will need the ICU (International
      Components for Unicode) libraries and headers version 3.6 or
      higher (we have successfully compiled up to the stable 4.2.1
      release).  ICU is commonly found in most Linux package managers
      like yum, or you may compile and install from src.

      If using Linux RPM's, you will need the following two RPM's:

            libicu 
      	    libicu-devel

      Otherwise, the source distributions may be found at:
      
            http://site.icu-project.org/download

      We have successfully tested with 3.6 --> 4.2.1 of the ICU
      distributions, so if you have a newer one that is fine (Note:
      you'll need autoconf 2.63 for 4.2.1).  Follow the directions in
      the distribution for installing ICU carefully since it is not
      standard GNU.  For example, you will need to start by running
      the script "runConfigureICU machineType" instead of configure
      directly.  The machineType is the OS you are on, you can read
      the runConfigureICU script to see those available.  The download
      site has more information for some platforms as well.

      If the ICU headers and libs are installed in the default
      /usr/local (or for RPM's in /usr), configure should find them.
      Otherwise, configure can be explicitly pointed at the
      distribution dir with the "--with-icu-prefix=prefix" arg.
      Please see the non-standard ICU install note in the configure
      step of the installation for more information.


  o TESTSUITE: (for 'make check')

    o In order for the 'make check' tests to succeed, you will need:

       o perl: If you don't have a valid `readlink -f` command (Max OS
       	 X, e.g.)  then configure uses perl instead.

       o The current version of the NetCDF Data Handling Module for
       	 Hyrax and its dependency: libnetcdf 3.x (or greater).  The
       	 handler itself is found at
       	 http://www.opendap.org/download/hyrax.html.

	 o Mac Users: Mac users can get netcdf in DarwinPorts

       o The current version of the HDF4 Data Handling Module for
       	 Hyrax and its dependencies: libjpeg, zlib and slib usually.
       	 The handler is found at
       	 http://www.opendap.org/download/hyrax.html.

       o The current version of the HDF5 Data Handling Module for
       	 Hyrax and its dependencies.
       	 The handler is found at
       	 http://www.opendap.org/download/hyrax.html.

       o The new testsuite now also uses Autotest, which is part of
         Autoconf.  This should work fine if you have autoconf
         installed (a prereq) but please let us know if it does not!

    o In order to view the test NcML file fnoc1_improved.ncml, you will
      need:
	
       o The current version of the netCDF Data Handling Module (see
       above for more info).


---------------------------------------------------------------------------
CONFIGURATION NOTES

  o The NcML Data Handler is a module dynamically loaded into the BES.
    The BES uses the ncml.conf configuration file installed in
    $prefix/etc/bes/modules to configure itself.  Right now the module
    has no specific runtime configuration options, but this is where
    they will be found in the future.

---------------------------------------------------------------------------
DEBUGGING AIDS

   o The NcML handler uses the BES debugging channels ("ncml" channel)
     which can be turned on as documented in
     http://docs.opendap.org/index.php/BES_-_How_to_Debug_the_BES.

     In short, you need to compile a BES with --enable-developer and
     then run it standalone or as server with the -d "cerr,ncml"
     option.  For example,

    	     > besctl start -d "cerr,ncml"

     This will turn on the NcML debug channel which will output
     detailed information as the parse proceeds.  In most cases the
     error response from the server should be enough to create a bug
     report if there's an internal error reported.  If you see an
     internal error, please report it!

     We also have more verbose output in the "ncml:2" channel, and
     information on our memory pool operation is in the "ncml:memory"
     channel.  These can be added with -d
     "cerr,ncml,ncml:2,ncml:memory".

   o You can create a debuggable version of the handler with:
     
     ./configure --enable-developer CXXFLAGS="-g3 -O0 -W -Wall -Wcast-align -fno-defer-pop"

     in addition to the other options at configure time.

---------------------------------------------------------------------------
NOTES

  o The NcML Module was built to work with Hyrax 1.6 server and will
  not work on earlier versions of Hyrax!


