INSTALL

Updated for version 3.20.8 of the OPeNDAP BES.

Building and Installing the BES

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

BUILDING FROM A GIT CLONE
BUILDING FROM A SOURCE DISTRIBUTION
BUILDING AN RPM
RUNNING DISTCHECK
BUILD REQUIREMENTS
NOTES
CONFIGURATION AND TESTING

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.

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

BUILDING FROM A GIT CLONE

Also see http://docs.opendap.org/index.php/Hyrax_GitHub_Source_Build

Note that as of 2/3/15 the BES master branch software supports DAP4
and DAP2, and thus requires libdap4. If you want to build the older
DAP2-only software, checkout the 'dap2' branch here and for each of
the modules.

1. The BES repo on GitHub can be built two ways. The cloned
repo can be configured to build the framework only or it can be
configured to build both the framework and all of the modules included
in a 'stock' Hyrax distribution. Either way, it starts out the same:

    'git clone https://github.com/opendap/bes'

Then...

2. If you're going to build the BES plus the modules, there is one
more command you'll have to do. Use 'git submodule' to clone all of
the modules so they can be built (by default, while there is a
'modules' dir in the BES git repo, and some of its directories are
empty until you clone the modules repos. Use this command to get the
modules:

    'git submodule update --remote --init'

If you think you will make changes to the any of the modules code, you
will need to 'git checkout master' (or whatever branch you need/want).
If you want all of the modules on a branch (e.g., 'master) use: 

    'git submodule foreach 'git checkout master'

3. Run 'autoreconf --force --install --verbose' 

4. Run './configure' It's quite likely you will want to set the
install directory for the BES to be something other than
/usr/local/bin, etc., so use --prefix to set the BES prefix. If you're
building the modules and you have the dependencies installed in a
'non-standard' location, use --with-dependencies=<path> to provide the
prefix to those packages. Note that we have a repo/tar-ball called
'hyrax-dependencies' that will build all of the dependencies needed by
hyrax. There are many more --with-* options including once for each
individual third-party package; --help will list them all.

5. Run 'make'. If you have several cores, use -j <n> to speed things
up.

6. Test it: 'make check'. Try -j here, but some of the tests may balk
at a parallel build. Without -j they should all pass or have an
'expected failure'.

7. Install it: 'make install'

BUILDING FROM A SOURCE DISTRIBUTION (a tar.gz file)

To build the BES software, follow these steps:

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

There are several targets in the BES Makefile that can be used to build
RPM packages. The target 'rpm' will assume you want to use the bes.spec
file and build an RPM for either the bes alone or bes w/modules (depending
on the file that configure.ac is linked to). In the latter case, only
modules with dependencies that are installed using RPM will be built.

The BES Makefile also has another set of targets that are intended for 
use with a BES + modules build and will build _all_ of the modules, using
static linkage for the one that don't have their dependencies provided by
an RPM. To build this kind of RPM, you need to first get and build the 
hyrax-dependencies package and do so using one of the special targets in its
Makefile for 'static-rpms'. You will also need to force it to build only
static libraries using CONFIGURE_FLAGS=--disable-shared when you rum 'make'.

RUNNING DISTCHECK

If you've used the hyrax-dependencies package to build the BES + modules,
and you're using automake 1.13 or older, run the Makefile's distcheck
using 'make distcheck DISTCHECK_CONFIGURE_FLAGS=--with-dependencies=...'
Without setting that environment variable, the distcheck build won't
find any of the dependencies. Also using MFLAGS=-j9 (use whatever
number is appropriate or your machine) will speed things up.

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 and configured, you 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.
  Use 'besctl kill' to stop everything right away and 'besctl pids' to
  see if there are any BES processing still hanging around. 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 git clone, you'll need automake 1.12, autoconf
  2.68 and libtool 2.2+. 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 and build them

o The BES optionally uses libdap, but is not required. For Hyrax, you
  will need libdap version 3.13.2 or greater to build this software.
  See http://www.opendap.org/download/. You will need libxml2, 2.7.0
  or newer. We provide source versions of the packages on our web
  site; the official web page for libxml2 is: http://xmlsoft.org/.

o If you are concerned about introducing problems with your OS's
  package system, build and install libdap, libxml2, etc., into a
  special directory (e.g., /opt/opendap/) and then be sure to set PATH
  to include the dap-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. This code has
  also been built on OSX 10.9 using Apple LLVM version 5.1
  (clang-503.0.40) (based on LLVM 3.4svn).

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. 

  o If you are developing code that uses the DAP, use the GitHub repo

  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/bes.*.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,
      simply 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. Any modules installed will have their
      own configuration file in the modules directory. So, if you
      installed in /usr/local, then this file will be located in
      /usr/local/etc/bes/bes.conf and the modules directory where module
      configuration files will go is /usr/local/etc/bes/modules.

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