
	$Id: INSTALL 15976 2007-03-12 21:08:30Z jimg $

Updated for version 3.7.6 of the OPeNDAP DAP 3.1 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 run the tests. You
     must have DejaGNU to run `make check.' If you have the CppUnit unit-test
     software, then 'cd unit-tests; make check' will build and run the unit
     tests.

  3. Type `make install' to install the library files. The libraries
     (libdap.a. libdapclient.a and libdapserver.a), their 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, ...

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 --verbose' and
  then './configure; make'.

AFTER INSTALLING

  o Set PATH environment variable to include the bin directory of
    where libdap was installed. For example, if using the default
    installation directory, which is /usr/local, make sure that
    /usr/local/bin is on your path. This is important because often
    libdap is built so that some other software can then be built, but
    without setting PATH, those other packages might use older
    versions of libdap that are still lingering on you system.

  o Set LD_LIBRARY_PATH environment variable to include the lib
    directory of where libdap was installed. For example, if using the
    default installation directory, which is /usr/local, make sure
    that /usr/local/lib is part of LD_LIBRARY_PATH. If you have set
    $prefix so that the libraries are installed in a directory that's
    included in ld.so.conf (on linux; other systems may use a slightly
    different name) you don't have to use LD_LIBRARY_PATH but, but if
    you don't use LD_LIBRARY_PATH, make sure to re-run ldconfig.

REQUIREMENTS

  o To build from a fresh SVN checkout, you'll need automake 1.9.6, autoconf
    2.59 and libtool 1.5.18. Earlier versions may work, but may cause
    problems, particularly with the 'distcheck' target for make. Given those
    requirements, use 'autoreconf --force --verbose' and then build as
    described above.

  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.10.6 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 (really, you should probably be
    using gcc/++ 4.x, but you _can_ use 2.95 on our code). 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, 4.0 and 4.1. The library has also been
    built using the native AIX compiler; see INSTALL.AIX.

  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
    build the C++ sources from the grammar files, you'll need bison 1.25 and
    flex 2.5.4.

NOTES

  o Check for other INSTALL.* files to see if there's information specific to
    your OS (e.g., AIX).
    
  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 the CppUnit unit testing package. 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 SVN. We
    maintain a SVN-managed source tree that people outside the group may
    access. See http://scm.opendap.org:8090/trac/

  o The gnulib software is used to provide replacement functions when
    autoconf detects that is necessary. To update the gnulib, check it out
    from CVS and run '$gnulib_home/gnulib-tool --lgpl --import' in this
    directory. Macros in configure.ac supply gnulib-tool with all the
    information it needs. Only developers working on libdap should ever have
    to do this.

  o To build a rpm file for a source or binary distribution use 'make rpm' or 
    'make srpm'. These targets should run 'make dist' to build the required
    tar.gz file first. You may need root privleges for these targets to work.
    
  o To build a Mac OS/X package, use the 'pkg' target of the Makfile
    and then start PackageMaker and open libdap_osx_package.pmsp.
    Make sure to update Welcome.html, ReadMe.txt and License.txt. Note
    that those files can be edited fairly easily in emacs using
    set-fill-column 55 (if they are wider than 55 columns they look
    awful). Since a .pkg file is really a directory (aka bundle) you'll
    need to put the in either a tar.gz file or a disk image. To make a
    disk image use DiskUtility and choose 'New Image.' Make the disk
    image 300k bigger then the size of the package. Once created, copy
    the package to the image.

  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 use these, don't hack up the
      Makefile.am. Instead export CXXFLAGS with the values you want and then
      run configure. For example:

	  export CXXFLAGS="-g3 -O0 -Wall -fno-defer-pop"; ./configure

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