
	$Id$

Updated for version 3.7.2

Installing the OPeNDAP Matlab client

This version of loaddap has been tested with Matlab 2012a. It may build
with versions as old as Matlab 5, but that has not been tested.

Note to maintainers: 'make dist' works but 'make distcheck' fails because
mex does not find the source files.

On OS/X 10.7 with XCode 4.2 or later, see
http://www.mathworks.com.au/support/solutions/en/data/1-FR6LXJ/ for
information about a patch needed so that mex will find the correct compiler.
This patch is needed even though the default build does not use XCode.

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

BUILDING THE SOFTWARE
REQUIREMENTS
NOTES

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

BUILDING THE SOFTWARE

  To build the OPeNDAP Matlab Client 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 client, `make check' to run the helper
     app tests. You will need to run the loaddap tests from within
     Matlab itself. To do so, start Matlab and add the path to the
     source directory ('src') and $src/testsuite/matlab using the
     addpath command. The run the script 'test_loaddap'.

  3. Type `make install' to install the client binary and it's helper
     programs. By default the software installs in /usr/local/bin. To
     change the root directory from /usr/local to something else, use
     the --prefix option of configure.

Building from Our SVN Repository

  If you are building from a SVN checkout, run 'autoreconf --force --install' 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 --install' and
  then './configure; make; make install'.

REQUIREMENTS

  o To build from a fresh SVN checkout, you'll need automake 1.11, autoconf
    2.68 and libtool 2.4. Earlier versions may work, but may cause
    problems, particularly with the 'distcheck' target for make. Given those
    requirements, use 'autoreconf --force --install' and then build as
    described above.
    
  o The software requires libdap 3.8.0 or newer.
  
  o We test loaddap using Matlab 7 although it's possible the software will
    work with Matlab 5 or 6. The $MATLAB/bin directory must be on your path
    or given to configure using the --with-matlab option.

  o You should have gcc/g++ 4.1 or greater.

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 To build a rpm file for a source or binary distribution: 1) Use 'make
    dist' to build a tar.gz file; and 2) Use 'make srpm' and 'make rpm' to
    build the binary distributions. You may have to to be root to do
    this, depending on how RPM is set up for you.

  o To build a Mac OS/X package, use the 'pkg' target of the Makefile
    and then start PackageMaker and open loaddap_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 software uses the following debugging aids that may be of help
      to you in developing new OPeNDAP applications.

    - DBG: simple program instrumentation -- see the file defines.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.
