
	$Id: INSTALL,v 1.18 2005/05/13 20:18:58 jimg Exp $

Updated for version 3.5.1 beta of the OPeNDAP DAP2 library software.

Installing the DAP2 library

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

BUILDING THE SOFTWARE
REQUIREMENTS
NOTES

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

BUILDING THE SOFTWARE

  To build the OPeNDAP DAP2 library and the getdap client program, follow
  these steps:

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

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

  2. Type `make' to build the library, `make check' to build the test
     software.  You must have the GNU automated testing software DejaGNU
     to run `make check.' If you have the CppUnit unit-test software, then
     'make unit-check' should build and run the unit tests.

  3. Type `make install' to install the DAP2 library. The library
     (libdap++.a), its header files and the getdap and dap-config utilities
     install under /usr/local/ in lib, include/libdap and bin by default. The
     deflate utility is installed in /usr/local/sbin by default. Use the
     --prefix option to specify a different root directory. For example,
     './configure --prefix=/opt/opendap' would set the build so that the
     library was installed in /opt/opendap/lib, ...


REQUIREMENTS

  o The library uses libcurl and libxml2. You will need these libraries
    installed on your system to successfully run configure and build the
    library. You must have libcurl version 7.12.0 or newer and libxml2 2.5.7
    or newer. We provide source versions of the packages on the web site; the
    web pages for these projects are: http://curl.haxx.se/ and
    http://xmlsoft.org/.

  o If you are concerned about introducing problems with your OS's package
    system, build and install curl, et c., into a special directory (e.g.,
    /opt/opendap/) and then be sure to set PATH to include the curl-config
    and xml2-config scripts before running configure (e.g., run configure as
    'PATH="$PATH:/opt/opendap/bin';./configure'). You probably should install
    libdap++.a under /opt/opendap as well, so set prefix to that path:
    
	'PATH="$PATH:/opt/opendap/bin';./configure --prefix=/opt/opendap'

  o You should have gcc/g++ 2.95.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.

  O We ship the C++ source files generated using bison and flex so these
    programs are no longer required to build the source code. However, to do
    a complete build from the sources after running the `grammar-clean'
    target, you'll need bison 1.25 and flex 2.5.4.

  o You may need GNU Make. You will need the GNU auto tools (autoconf 2.57
    and its associated programs) if you're building from CVS or need/want to
    hack the configure.ac, acinclude.m4, et c., files. Use autoreconf to
    rebuild configure; if you call autoconf directly the aclocal.m4 file
    won't get built from acinclude.m4 correctly. 

NOTES

  o If the build fails because make reports that it does not know how to make
    a particular file, try ruining `make depend' to rebuild the Makefile's
    dependencies. 

  o If you are building on a new platform (one for which we don't supply
    binaries), please run the tests and tell us about any failures. To do a
    really complete job of this you'll need to get the GNU test system called
    DejaGNU and CppUnit. It is very simple to install these and we're very
    willing to help, so don't be shy! 

  o If you are developing code that uses the DAP, get autoconf and CVS (both
    from GNU). We maintain a CVS-managed source tree that people outside the
    group may access.

  o Older versions of Linux have an xdr.h include file that won't compile
    properly with g++. The error shows up when building software that calls
    xdr_destroy and the compiler complains that it's being called with too
    many arguments. If this happens to you, take the xdr.h.linux file and
    rename it to xdr.h. Note that the changes are very minor and there should
    be no problem installing xdr.h in /usr/include/rpc if that's what you
    want to do.

  o DEBUGGING AIDS

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

    - DBG: simple program instrumentation -- see the file debug.h.

    - 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.

    - In the past we used efence and dbnew to help debug dynamic memory
      programming errors. We are now using valgrind and suggest you do the
      same. On some Linux platforms you should export MALLOC_CHECK_=0 in the
      shell before running valgrind. This is true for the unit tests and may
      be true for other code. You'll also notice that the Makefile contains
      CXX and C compile-time flags for debugging. These will greatly simplify
      using valgrind and/or a debugger.

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