
	$Id: INSTALL 18355M 2008-06-25 22:13:09Z (local) $

Updated for version 3.6.2 of the OPeNDAP BES.

Installing the BES

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

BUILDING THE SOFTWARE
BUILD REQUIREMENTS
NOTES
CONFIGURATION AND TESTING

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

BUILDING THE SOFTWARE

  To build the BES software, follow these steps:

  0. Please skim BUILD REQUIREMENTS and NOTES sections of this file before
     reporting problems. Also, this software _requires_ other software
     components be built and installed and that its configuration file be
     edited. Make sure you read over the CONFIGURATION AND TESTING section!
     Thanks.

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

  2. Type `make' to build the software, `make check' to run the tests. You
     must have DejaGNU to run `make check.' If you have cppunit installed
     then additional tests will be run. We recommend that you install
     cppunit if you have not already.

  3. Type `make install' to install the BES software. The package installs
     in /usr/local/ by default; use --prefix to change that.

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 See the CONFIGURATION section once you have finished building the BES.

  o Set PATH environment variable to include the bin directory of where
  bes was installed. For example, if using the default installation
  directory, which is /usr/local, make sure that /usr/local/bin is on your
  path.

  o Set LD_LIBRARY_PATH environment variable to include the lib directory of
  where bes 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. You might want to add the following about LIBRARY PATH:
  If you have set $prefix so that the libraries are installed in a directory
  that's included in ld.so.conf (linux, other systems may use a slightly
  different name) you don't have to use LD_LIBRARY_PATH but, if you don't,
  make sure to re-run ldconfig.

  o Once built you and configured will start and stop the BES using the
  besctl script located in the installation directories bin directory. To
  start the BES:

  besctl start

  To stop the BES:

  besctl stop

  Note: Stopping the BES only stops the daemon and the main listener. If you
  have clients connected to the BES then the listeners handling requests
  from those clients will remain up until the connections are closed. This
  is only the case in the servers 'multiple' mode and not its 'single' mode
  (refer to the BES configuration file for more on this topic).


BUILD REQUIREMENTS

  o You will need a copy of the readline library. You can get a copy
    from http://cnswww.cns.cwru.edu/~chet/readline/rltop.html. Most
    unix OSs have something that will fit the bill, but OS/X does not
    (as of 10.3). The configure script will look for a suitable
    library and stop with an error if nothing is found, so the easiest
    thing to do is to run configure and see if it complains. If it
    does, go to the above link and grab the library.

  o To build from a fresh SVN checkout, you'll need automake 1.9.2, autoconf
    2.59 (2.57 will probably work and that's what's listed in the configure.ac
    file) and libtool 1.5.6. 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.

    If you have an Intel Mac and you are experiencing configuration issues
    then you might need to download the latest and greatest autoconf,
    automake, and libtool using the DarwinPorts tool. We've tried using
    other download tools, like fink, and building from source these
    packages, but only DarwinPorts seems to resolve the issues. We continue
    to watch this issue and hope to get it resolved soon.

  o The library uses libdap, but is not required. You will need version
    3.7.3 or greater to build this software. See
    http://www.opendap.org/download/. Since libdap uses libcurl and libxml2,
    you will need these libraries, too. 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++ 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 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 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: 1) Use 'make
    dist' to build a *.tar.gz file; 2) Copy that to ~/rpm/SOURCES,
    and; 3) Run 'rpmbuild -ts ~/rpm/SOURCES/libdap-3.5.1.tar.gz' to make the
    source package. Use '-tb' to make the binary package. I use a
    ~/.rpmmacros file that contains:

	%_topdir		/home/jimg/rpm
	%_tmppath               /home/jimg/rpm/tmp
	
    Or, use the 'rpm' target in the Makefile.

  o DEBUGGING AIDS

    - Debugging is built in to the BES and does not require any special
      debug flags during compile time. To activate debugging in the BES,
      simpy use the -d cerr|<filename> option to besctl, besdaemon, and
      beslistener. You should just need to use besctl. You can either
      specify cerr or a file name with the -d option. If you specify cerr
      then debug output will go to standard error. If you specify a file
      name, then debug output will go to that file. You can not specify
      cout, as standard output is redirected to the socket.

    - You can also check the BES log file, where the location is specified
      in the BES configuration file. There might be some useful information
      in that file.

    - 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

CONFIGURATION AND TESTING

  o CONFIGURATION

    - The configuration file is located in the installation directory under
      etc/bes and is called bes.conf. This file will need to be edited, and
      is fairly well documented. So, if you installed in /usr/local, then
      this file will be located in /usr/local/etc/bes/bes.conf.

    - If you want to include libdap in the build then you will need to
      either have dap-config on your path, or you can specify
      --with-dap=<path_to_dap> if it is not on your path.

    - Using openssl with the BES. The BES client/server code can include the
      use of openssl for secure connections. You can specify the
      --with-openssl=<path_to_openssl> on the command line if it is not
      installed in any of the default locations.

  o TESTING

    - Once you have built the software you can run 'make check' to make sure
      that the software is working properly. There are also tests in the
      bes/cmdln directory that can be used to test as well, but is not a
      part of the default test environment. To use the tests in bes/cmdln
      please contact OPeNDAP for assistance.

