-------------------------------------------------------------------------------
MB-SYSTEM INSTALLATION NOTES FILE:
-------------------------------------------------------------------------------
-------------------------------------------------------------------------------

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 environment, 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-config  - location of NetCDF config script nc-config
    --with-gdal-config    - location of GDAL config script gdal-configx
    --with-gmt-config     - location of GMT config script gmt-config
    --with-proj-lib       - location of PROJ libs
    --with-proj-include   - location of PROJ 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)

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

As an example, if one is installing on a Mac in which all of the prerequisite
packages have been installed with Homebrew, then the locations of those
prerequisite packages must be explicitly defined. Homebrew installs packages in
/usr/local. For this, the configure command is:
	% CFLAGS=-g -I/opt/X11/include -L/opt/X11/lib \
	    ./configure \
	    −−with-proj-include=/usr/local/include \
	    −−with-proj-lib=/usr/local/lib \
	    −−with-fftw-include=/usr/local/include \
	    −−with-fftw-lib=/usr/local/lib \
	    −−with-motif-include=/usr/local/include \
	    −−with-motif-lib=/usr/local/lib \
	    −−with-otps-dir=/usr/local/opt/otps

This is for MacOSX 10.13 (High Sierra), in which X11 must be obtained from X.org
and is installed in /opt. 

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