-------------------------------------------------------------------------------
MB-SYSTEM INSTALLATION NOTES FILE:
-------------------------------------------------------------------------------
Version: $Id: NOTES 2159 2014-01-18 23:19:37Z caress $
-------------------------------------------------------------------------------

This file contains installation notes for the MB-System open source software
package for the processing and display of swath sonar data. This file is located
at the top of the MB-System source code distribution directory structure.

-------------------------------------------------------------------------------
THE MB-SYSTEM SOURCE CODE DISTRIBUTION:
-------------------------------------------------------------------------------
MB-System is distributed as a compressed tar archive named according to the
release version. For example, release 5.4.2081 was distributed in a file named:
    mbsystem-5.4.2081.tar.gz
Here the major release is 5, the minor release is 4, and the third number is the
corresponding revision number for the source code archive (which is managed
using the Subversion package).

The source code archive can be accessed directly at:
    http://svn.ilab.ldeo.columbia.edu

The tar utility is used to extract the distribution:
    % tar xvzf mbsystem-5.4.2081.tar.gz
yielding a directory named "mbsystem-5.4.2081".

Listing the contents of the top directory and then the src directory below
reveals:
    % cd mbsystem-5.4.2081
    % ls -s
	total 2920
	  8 AUTHORS		  8 NEWS		 40 configure.in
	 16 COPYING		 16 NOTES		 48 depcomp
	224 ChangeLog		 56 README		 32 install-sh
	 72 GPL			 88 config.guess	 64 install_makefiles
	 32 INSTALL		 72 config.sub*		576 libtool*
	 48 Makefile.in		944 configure		560 ltmain.sh
	  8 Makefile.template	  8 configure.cmd*	  0 src/
    % ls -s src
	total 80
	48 Makefile.in			 8 mbsystem_config.h
	 8 Makefile.template		 8 mbsystem_config.h.in
	 0 gmt/				 0 mbvelocitytool/
	 0 gsf/				 0 mbview/
	 0 html/			 0 mr1pr/
	 0 macros/			 0 otps/
	 0 man/				 0 proj/
	 0 mbaux/			 0 ps/
	 0 mbedit/			 0 share/
	 0 mbio/			 8 stamp-h1
	 0 mbnavadjust/			 0 surf/
	 0 mbnavedit/			 0 utilities/
The src/html, src/man, and src/ps directories contain documentation in web page,
man page, and postscript formats respectively. The other directories under src
contain either C source files that are compiled into programs or Perl script
source files.

-------------------------------------------------------------------------------
MB-SYSTEM BUILD SYSTEMS:
-------------------------------------------------------------------------------
MB-System source distributions come with two build systems. Both create a
set of recursive makefiles so that the make utility can be used to compile and
install the package. The primary build system uses a configure script that has
been created using the GNU autotools package. Users customize the makefiles for
the local system by using arguments to configure. The older approach uses a
perl script called install_makefiles that must first be edited to reflect the
local system. The install_makefiles script is maintained for backward
compatibility, but we expect most users to use the configure script.

-------------------------------------------------------------------------------
BUILDING AND INSTALLING MB-SYSTEM WITH CONFIGURE
-------------------------------------------------------------------------------

The basic steps for building MB-System using the configure script are:

    1. Move to the top of the MB-System distribution directory:
        % cd mbsystem-5.4.2081

    2. Run the configure script to generate the Makefile files throughout the
    distribution directory structure. The command line options for configure
    are discussed below.
        % [...pre-options...]./configure [...options...]

    3. Run the make utility to build the software within the source distribution.
        % make

    4. Run the make utility with the install option to install the software
    within the target location that was specified while running configure.
        % make
        % make install

The configure script is intended to discern the enviroment, locate prerequisite
packages, and construct the makefiles with a minimum of user intervention. In
practice, users generally need to set at least some options when using the
configure script in order to successfully build, install, and run MB-System.
If NetCDF and GMT installations cannot be located, MB-System cannot be built. If
FFTW3, Motif, or OpenGL cannot be found MB-System will be built, but without
the applications that depend on these packages.

Depending on how user permissions are set on your system and where the package
is to be installed, it may be necessary to execute some or all of the above
commands with superuser privileges. On older styles of Unix and Linux, this
was typically accomplished by using the su command to become root, or
superuser, a step that requires knowing the root password for the system.
Following a successful invocation of su in a command shell, all commands have
superuser privileges. On MacOsX and other "modern" flavors of Unix and Linux,
it's more common to use the sudo command in front of other commands in order
to execute them with superuser privileges. An administrator password is
required for the first instance of sudo, but not for subsequent instances (at
least for a period of time, typically five minutes). In this case, the commands
become:

	% sudo ./configure
	% sudo make
	% sudo make install

The available configure options are:
    --prefix=install      - location for mbsystem (/usr/local/mbsystem)"])
    --with-netcdf-lib     - location of NetCDF libs"])
    --with-netcdf-include - location of NetCDF headers"])
    --with-proj-lib       - location of PROJ libs"])
    --with-proj-include   - location of PROJ headers"])
    --with-gmt-lib        - location of GMT libs"])
    --with-gmt-include    - location of GMT headers"])
    --with-fftw-lib       - location of FFTW3 libs (optional)"])
    --with-fftw-include   - location of FFTW3 headers (optional)"])
    --with-motif-lib      - location of Motif libs (optional)"])
    --with-motif-include  - location of Motif headers (optional)"])
    --with-opengl-lib     - location of OpenGL libs (optional)"])
    --with-opengl-include - location of OpenGL headers (optional)"])
    --with-otps-dir       - location of OTPS installation (optional)"])
    --without-gsf         - build without including or supporting GSF"])
    --enable-bundledproj  - build using bundled proj package - the
				default is to link with libproj"])

Users can also define custom compiler flags on the command line to be used by
configure. For example, the command:
        % CFLAGS="-g -W -DBYTESWAPPED" ./configure \
          --prefix=/usr/local/mbsystem
will override the system default CFLAGS with "-g, -W, and -DBYTESWAPPED", build
the package in the distribution directory with shared libraries, and install
the package in /usr/local/mbsystem. The destination directories will be:
        /usr/local/mbsystem/bin                      executable binaries and scripts
        /usr/local/mbsystem/lib                      libraries
        /usr/local/mbsystem/include                  header files
        /usr/local/mbsystem/share/mbsystem           projection and levitus data
        /usr/local/mbsystem/share/doc/mbsystem/html  web page documentation
        /usr/local/mbsystem/share/doc/mbsystem/ps    postscript documentation
        /usr/local/mbsystem/man                      man page documentation

If one is installing on a Mac in which some or all of the prerequisite packages
have been installed with Fink or MacPorts, then the locations of those
prerequisite packages must be explicitly defined. Fink installs packages in
/sw, and MacPorts installs into /opt. An example for installing in a Fink-centric
system is:
	% CFLAGS="-g -I/opt/X11/include" \
	    LDFLAGS="-L/opt/X11/lib" \
	    ./configure \
	    --prefix=/Users/caress/sandbox/mbsystem \
	    --with-netcdf-include=/sw/include \
	    --with-netcdf-lib=/sw/lib \
	    --with-proj-include=/sw/include \
	    --with-proj-lib=/sw/lib \
	    --with-gmt-include=/sw/include \
	    --with-gmt-lib=/sw/lib \
	    --with-fftw-include=/sw/include \
	    --with-fftw-lib=/sw/lib \
	    --with-motif-include=/sw/include \
	    --with-motif-lib=/sw/lib \
	    --with-otps-dir=/usr/local/OTPS
This is for MacOSX 10.9 (Mavericks), in which X11 must be obtained from X.org
and is installed in /opt. Previous versions of MacOsX installed X11 in /usr/X11R6.
The only non-Fink package specified is OTPS (which is not available through
package managers) in /usr/local.

-------------------------------------------------------------------------------
BUILDING AND INSTALLING MB-SYSTEM WITH INSTALL_MAKEFILES:
-------------------------------------------------------------------------------

The original, and now alternate, method for generating the makefiles is to use
a script named install_makefiles that is also present at the top of the
MB-System distribution. In contrast to configure, which can be controlled by
command line options, install_makefiles must be customized to the local
environment by manual editing before this perl script is executed.
In order to configure your installation. In particular, the user must explicitly
set the library locations, header file locations, compile flags, and link flags.

The important parameters to be set in install_makefiles are:

     Required parameters:
     $MBSYSTEM_HOME - absolute path to the MB-System installation location
     $OS - Operating system (e.g. DARWIN, LINUX).
     $CFLAGS - Compile flags for C source files.
     $LFLAGS - Load flags for all object files.
     $NETCDFLIBDIR - Location of NetCDF library.
     $NETCDFINCDIR - Location of NetCDF header files.
     $GMTLIBDIR - Location of GMT libraries.
     $GMTINCDIR - Location of GMT header files.

     Required parameters for spectrogram program mbsegypsd
	- mbsegypsd will not be built if these are commented out
     $FFTWLIBDIR - Location of the FFTW3 library.
     $FFTWINCDIR - Location of FFTW3 header files.

     Required parameters for graphical tools
	- graphical tools will not be built if these
	  are commented out
     $MOTIFINCDIR - Location of the Motif header files.
     $MOTIFLIBS - Location of the Motif libraries.

     Required parameter for visualization tools
	- visualization tools will not be built if this
	  is commented out
     $OPENGLLIBS - Link flags for the OpenGL libraries: "-lGLU -lGL";

     Required parameter for mblevitus program
     $LEVITUS - Location of the Levitus library (usually "$MBSYSTEM_HOME/share/LevitusAnnual82.dat").

     Required parameter for mbotps program
     $OTPSDIR - Location of the OTPSnc installation (usually "/usr/local/OTPSnc").

     Optional name of C compiler (if other than "cc").
     $CC - Usually "cc", but could be "gcc".

     Optional parameters for use of independent GSF library installation
	- GSF library included with MB-System will be used
	  if these are commented out
     $GSFLIB - Location of GSF library.
     $GSFINCDIR - Location of GSF header files.

     Optional parameters for use of independent PROJ4 library installation
	- PROJ4 library included with MB-System will be used
	  if these are commented out
     $PROJLIB - Location of PROJ4 library.
     $PROJINCDIR - Location of PROJ4 header files.

An example of the parameters for installing a distribution in /usr/local on a
current (MacOs X 10.8) Fink-centric Mac is:
     $MBSYSTEM_HOME = "/usr/local/mbsystem-5.4.2081";
     $OS = "DARWIN";
     $CFLAGS = "-I/usr/X11R6/include ";
     $LFLAGS = "-lm -L/sw/lib -lgdal";
     $NETCDFLIBDIR = "/sw/lib";
     $NETCDFINCDIR = "/sw/include";
     $GMTLIBDIR = "/sw/lib";
     $GMTINCDIR = "/usr/include";
     $PROJECTIONS = "$MBSYSTEM_HOME/share/mbsystem/Projections.dat";
     $FFTWLIBDIR = "/sw/lib";
     $FFTWINCDIR = "/sw/include";
     $MOTIFINCDIR = "/sw/include";
     $MOTIFLIBS = "-L/sw/lib -L/usr/X11R6/lib -lXm -lXt -lX11";
     $OPENGLLIBS = "-lGLU -lGL";
     $LEVITUS = "$MBSYSTEM_HOME/share/mbsystem/LevitusAnnual82.dat";
     $OTPSDIR = "/usr/local/OTPSnc";

To execute install_makefiles, do the following:

     % cd mbsystem-5.4.2081
     % ./install_makefiles

Because install_makefiles is a perl script, the executable perl must be
available in the installer's path. Once install_makefiles has been correctly
configured and run, give the command "make all" to generate the executable
programs:

     % make all

The make command will descend recursively down through the directory structure,
compiling source files, linking object files, and copying executables and manual
pages to the appropriate directories.
The destination directories will be:
        /usr/local/mbsystem-5.4.2081/bin                      executable binaries and scripts
        /usr/local/mbsystem-5.4.2081/lib                      libraries
        /usr/local/mbsystem-5.4.2081/include                  header files
        /usr/local/mbsystem-5.4.2081/share/mbsystem           projection and levitus data
        /usr/local/mbsystem-5.4.2081/share/doc/mbsystem/html  web page documentation
        /usr/local/mbsystem-5.4.2081/share/doc/mbsystem/ps    postscript documentation
        /usr/local/mbsystem-5.4.2081/man                      man page documentation

-------------------------------------------------------------------------------
SETTING THE USER ENVIRONMENT:
-------------------------------------------------------------------------------

Naturally, in order for users to use the MB-System utilities, the directory
containing the executables must be included in their path. The executable perl
must also be available in the user's path for most of the macros to work. This
is generally achieved by editing the environment files in a user's home
directory. For csh users, the relevant files are .cshrc and .login; for sh or
bash users, the relevant files are .bashrc and .bash_profile.

Most users will also wish to specify which program they generally use to view
Postscript plots on their screen. This parameter can be set with the mbdefaults
program. The recommended Postscript viewer is a program called gv.
-------------------------------------------------------------------------------
