How to Download and Install MB-System

MB-System is an open source software package written for Unix-like operating systems, and is distributed for free as source code for download. In order to install MB-System, prerequisites need to be installed and the source distribution must be downloaded, unpacked, compiled, linked, and installed locally. The necessary steps are specific to different operating systems, so are presented separately below, after more general advice. Lastly, see the “Additional setup” toggle for steps that may be required for modules to be found by MB-System.  If you are updating an existing installation, first see the toggle “Updating an MB-System Installation”.

The source code for MB-System is available from a repository on Github:
https://github.com/dwcaress/MB-System

This link will open the page for the most recent stable release of MB-System. The source code distribution can be downloaded as zip or tar.gz archives from the “Assets” section at the bottom.
https://github.com/dwcaress/MB-System/releases/latest

This link will open a page listing all recent MB-System releases, with the most recent release at the top. The most recent release could be a beta or pre-release. The source code distribution can be downloaded as zip or tar.gz archives from the “Assets” section at the bottom.
https://github.com/dwcaress/MB-System/releases

This link will download the current state of the master branch of the MB-System repository:
https://github.com/dwcaress/MB-System/archive/refs/heads/master.zip

MB-System now includes two methods for building and installing the software, which are presented as options in the instructions. The recommended method is using the CMake package (which is not available for all operating systems). The other method is based on GNU Autotools. The CMake build system is new to MB-System with version 5.7.9, and is intended to replace the older Autotools approach for current and future operating systems. The old Autotools build system will continue to be included in MB-System distributions for the forseeable future to enable building and installation on legacy operating systems. The Autotools build system will not be maintained to enable its use on current or future operating systems, and the CMake build system will not be modified to support building on legacy systems.

The sequence of commands by which one builds and installs a package using CMake is very different from Autotools. For CMake, one creates a new directory to hold the package build (commonly named “build” by convention) in the top level of the source structure, then cd’s into that directory, and then executes cmake with the argument “..”, which provides cmake the path to the top level of the source directory. CMake then copies the source into a build tree and generates Makefiles in that tree to enable compilation, linkage, and installation, again using the program make.

The GNU Autotools build system includes a script named configure at the top of the distribution structure which, when executed, generates a set of files named “Makefile” throughout the structure that hold compilation and linkage instructions used by the program make. These compilation and linkage instructions vary depending on the operating system and which versions of prerequisite software packages are installed, and in some cases special arguments must be included in the configure command. Once configure has been successfully executed, running the program make at the top level then actually invokes the local compiler and linker to build and install MB-System. Several Autotools programs, including autoconf, automake, and libtool, are used to generate the configure script included in each distribution. This build system had been the sole means by which MB-System could be built since 2011.

MB-System depends on a number of other software packages. For some operating systems, special arguments to the configure script are required to integrate the MB-System source to prerequisite software packages.

Among the software packages that are prerequisite for MB-System are:

  • GMT (Generic Mapping Tools)
  • Proj
  • GDAL
  • netCDF
  • FFTW (Fastest Fourier Transform in the West)
  • X11
  • OpenMotif
  • OpenGL
  • OpenCV (for optional photomosaicing tools)
  • PCL (Point Cloud Library) (planned, not yet in release 5.8.0)

The sections below provide instructions for building MB-System on a few common operating systems, including MacOs, Ubuntu Linux, Debian Linux, CentOs Linux, and the CygWin environment on Windows. These instructions include the installation of the prerequisite software packages using a package manager relevant to each OS and the special arguments needed for the cmake command or the configure script.

Note that a bonafide 3-button mouse is necessary for operations within the GUIs for viewing grids and editing and navigation adjustment of survey data.  

The use of MacPorts to install the MB-System prerequisite packages is recommended on Apple Mac computers, particularly because this approach enables cleanly building with a complete X11 + Motif + OpenGL infrastructure separate from the libraries and header files associated with the XQuartz package. One usually still installs XQuartz and uses it as the X11 display server, but confining the MB-System compilation and linking to headers and libraries within the MacPorts structure avoids several issues. At present, we are not able to successfully run the MB-System graphical utilities when the prerequisite packages have been installed using the Fink or Homebrew package managers.

To state it again succinctly, if you want to build and install MB-System in MacOs, use MacPorts, and **do not** use Fink or HomeBrew.

This example is relevant for MacOS 10.13 High Sierra to the current MacOS 13 Ventura on both Intel and ARM (Apple Silicon) architecture computers.

From the Apple App Store, install Xcode developer tools, which includes the LLVM compiler suite.

Install the XQuartz X11 server from https://www.xquartz.org. XQuartz 2.8.5 or later is required for all MB-System installations.

Install MacPorts using the appropriate downloadable installer package from:
https://www.macports.org/install.php

After MacPorts installation, first make sure the default port packages are current by running selfupdate and then install the MB-System prerequisites.

  sudo port -v selfupdate
  sudo port install gmt6 fftw-3 mesa libGLU openmotif xorg opencv4 pkgconfig

Also make sure that a current version of Python3 is available. First list the available Python3 versions, install the most recent, and then set port to link that version to python3:

  port select --list python

Versions of Python available through MacPorts (November 6, 2023):

  • python27
  • python311
  • python312

The most recent version is python312, so install it:

  sudo port install python312
  sudo port select --set python python312
  sudo port select --set python3 python312

Also install the most recent Python imaging library Pillow:

  sudo port install py312-Pillow

Download the MB-System source package from the repository at GitHub:
https://github.com/dwcaress/MB-System

There are often beta releases that are more recent than the current stable release. The most recent beta release will be at the top of this page: https://github.com/dwcaress/MB-System/releases

We recommend using Chrome for the download rather than Safari, because Chrome does not prematurely unpack the tarball. 

Copy the MB-System distribution tarball to /usr/local/src (or somewhere else, if you prefer – this is our convention for consistency when managing many installations) and unpack it there. If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. Replace the filename with the name of the current release.

   mv MB-System-5.8.0.tar.gz /usr/local/src
   cd /usr/local/src
   tar xvzf MB-System-5.8.0.tar.gz

and then cd into the top directory of the resulting structure.

   cd MB-System-5.8.0

Option 1: **CMake Build System** (recommended)  

At that location (/usr/local/src/MB-System-5.8.0/), create a working directory named “build”, cd into “build”, and then execute cmake at the location /usr/local/src/MB-System-5.8.0/build/. The cmake command should successfully enable building the entire current MB-System (5.7.9 or later) on any Mac computer with the prerequisites installed using MacPorts (this has been tested with computers running Monterey through Ventura.) Finally, make and install MB-System.

   mkdir build
   cd build
   cmake ..
   sudo make
   sudo make install

Option 2: **Autotools Build System** (not recommended).

At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script named **configure**, with the options necessary for your context. The XCode compiler tools do not look for header files or libraries in the locations used by MacPorts, and so it is  necessary to specify these locations for several of the prerequisite packages. This command should successfully enable building the current core MB-System (5.7.9 or later) on any Mac computer with the prerequisites installed through MacPorts. This has been tested with computers running Ventura and Monterey.

   ./configure \
     --prefix=/usr/local \
     --disable-static \
     --enable-shared \
     --enable-hardening \
     --enable-test \
     --with-proj-lib=/opt/local/lib/proj9/lib \
     --with-proj-include=/opt/local/lib/proj9/include \
     --with-gmt-config=/opt/local/lib/gmt6/bin \
     --with-fftw-lib=/opt/local/lib \
     --with-fftw-include=/opt/local/include \
     --with-x11-lib=/opt/local/lib \
     --with-x11-include=/opt/local/include \
     --with-motif-lib=/opt/local/lib \
     --with-motif-include=/opt/local/include \
     --with-opengl-include=/opt/local/include \
     --with-opengl-lib=/opt/local/lib \
     --with-otps-dir=/usr/local/src/otps

Further for Option 2: The MB-System codebase includes some components that are optional when using the Autotools build system, such as OpenCV based photomosaicing (enabled with –enable-opencv) and  a realtime Terrain Relative Navigation infrastructure and toolset (–enable-mtrn and –enable-mbtnav). This configure command should enable building the entire MB-System package, including these optional tools:

   ./configure \
     --prefix=/usr/local \
     --disable-static \
     --enable-shared \
     --enable-hardening \
     --enable-test \
     --with-proj-lib=/opt/local/lib/proj9/lib \
     --with-proj-include=/opt/local/lib/proj9/include \
     --with-gmt-config=/opt/local/lib/gmt6/bin \
     --with-fftw-lib=/opt/local/lib \
     --with-fftw-include=/opt/local/include \
     --with-x11-lib=/opt/local/lib \
     --with-x11-include=/opt/local/include \
     --with-motif-lib=/opt/local/lib \
     --with-motif-include=/opt/local/include \
     --with-opengl-include=/opt/local/include \
     --with-opengl-lib=/opt/local/lib \
     --enable-mbtrn \
     --enable-mbtnav \
     --enable-opencv \
     --with-opencv-include=/opt/local/include/opencv4 \
     --with-opencv-lib=/opt/local/lib/opencv4 \
     --with-otps-dir=/usr/local/src/otps

Finally, make and install MB-System:

   sudo make
   sudo make install
This example is relevant for both Ubuntu 20.04 and 22.04 because the prerequisite package names are the same.
 
Ubuntu and Debian Linux distributions include multiple tools for managing software distributions. We recommend using the command line program apt to install the prerequisite software for MB-System.
 
Install Ubuntu 20 or 22 from an ISO image of the release (https://ubuntu.com/download/desktop).
 
Update the starting packages:
   sudo apt upgrade
Install compilers and other essential software:
   sudo apt install build-essential
Install MB-System prerequisites:
   sudo apt install libtirpc-dev \
netcdf-bin libnetcdf-dev libgdal-dev \      gmt libgmt6 libgmt-dev libproj-dev \      libfftw3-3 libfftw3-dev libmotif-dev \      xfonts-100dpi libglu1-mesa-dev \    libopencv-dev cmake gfortran

MB-System also requires Python3 and the Pillow library for Python3. Both of these packages are installed by default in Ubuntu 20 and 22.

Download the MB-System source package from the repository at GitHub:
 
There are often beta releases that are more recent than the current stable release. The most recent beta release will be at the top of this page:
 
We recommend using Chrome for the download rather than Safari, because Chrome does not prematurely unpack the tarball. Although MB-System can be installed from a source tree located anywhere, we generally place the tarball in /usr/local/src and then unpack and build MB-System there.
 
Unpack the MB-System distribution tarball in /usr/local/src/ (or somewhere else, if you prefer – this is our convention for consistency when managing many installations). If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. (Replace the filename with the name of the current release.)
        mv MB-System-5.8.0-tar.gz /usr/local/src
        cd /usr/local/src
        tar xvzf MB-System-5.8.0.tar.gz

and then cd into the top directory of the resulting structure:

        cd MB-System-5.8.0
Option 1: **CMake Build System** (recommended)
 
At that location (/usr/local/src/MB-System-5.8.0/), create a working directory named “build”, **cd** into “build”, and then  execute **cmake** at the location /usr/local/src/MB-System-5.8.0/build/). The cmake command should successfully enable building the entire current MB-System (5.7.9 or later) on either Ubuntu 20 or 22 as long as the prerequisite  software packages have been installed. Finally, install MB-System.
   mkdir build
   cd build
   cmake ..
   make
   sudo make install
Option 2: **Autotools Build System** (not recommended)
 
At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script, named configure, with the following options to build the entire MB-System package.
   ./configure \
          --enable-mbtrn --enable-mbtnav --enable-opencv \
          --with-opencv-include=/usr/include/opencv4 \
          --with-opencv-lib=/lib/x86_64-linux-gnu
The MB-System libraries will be placed in /usr/local/lib/, but the runtime dynamic linker does not look for shared libraries in this directory by default. Users can add /usr/local/lib to the directories searched for shared libraries by adding “/usr/local/lib” to the environment variable LD_LIBRARY_PATH. This is accomplished by placing the command
   export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
in an environment file in the user’s home directory named .zprofile (if using the zsh shell) or .profile (if using the bash shell). Other user environment files can be used, such as .zshrc for zsh or .bashrc for bash. The preferred alternative to using LD_LIBRARY_PATH is to embed the shared library location in the compiled libraries and executables by passing an rpath command to the linker by setting the LD_FLAGS environment variable available to the configure command:
   LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \
     ./configure \
        --enable-mbtrn --enable-mbtnav --enable-opencv \
        --with-opencv-include=/usr/include/opencv4 \
        --with-opencv-lib=/lib/x86_64-linux-gnu
(Note that the CMake build system, Option 1, builds the binaries such that the runtime libraries are reliably found without any additional commands or argument.)
 
Finally, install MB-System:
   make
   sudo make install
Ubuntu 18 has a version of CMake that is too old to work with MB-System’s CMake build system. Therefore MB-System can only be built and installed on Ubuntu 18 using the old Autotools based build  system. Ubuntu 18 also has a version of OpenCV that is too old to allow building the MB-System photomosaicing tools. Ubuntu and Debian Linux distributions include multiple tools for managing software distributions. We recommend using the command line program apt to install the prerequisite software for MB-System. Install Ubuntu 18 from an ISO image of the release (https://ubuntu.com/download/desktop). Update the starting packages:
   sudo apt upgrade
Install compilers and other essential software:
   sudo apt install build-essential
Install MB-System prerequisites:
        sudo apt install gmt libgmt5 libgmt-dev gmt-common \
          proj-bin proj-data libproj-dev libgdal-dev \
          libfftw3-3 libfftw3-dev libmotif-dev \
          xfonts-100dpi libglu1-mesa-dev gfortran
MB-System also requires Python3 and the Pillow library for Python3. Both of these packages are installed by default in Ubuntu 18. Download the MB-System source package from the repository at GitHub: https://github.com/dwcaress/MB-System There are often beta releases that are more recent than the current stable release. The most recent beta release will be at the top of this page: https://github.com/dwcaress/MB-System/releases We recommend using Chrome for the download rather than Safari, because Chrome does not prematurely unpack the tarball. Although MB-System can be installed from a source tree located anywhere, we generally place the tarball in /usr/local/src and then unpack and build MB-System there. Unpack the MB-System distribution tarball in /usr/local/src/ (or somewhere else, if you prefer – this is our convention for consistency when managing many installations). If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. (Replace this filename with the name of the current release.)
        mv MB-System-5.8.0-tar.gz /usr/local/src
        cd /usr/local/src
        tar xvzf MB-System-5.8.0.tar.gz
and then cd into the top directory of the resulting structure:
        cd MB-System-5.8.0
Only option for this operating system: **Autotools Build System** At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script, named configure, with the following options to build the entire MB-System package.
   ./configure \
          --enable-mbtrn --enable-mbtnav --enable-opencv \
          --with-opencv-include=/usr/include/opencv4 \
          --with-opencv-lib=/lib/x86_64-linux-gnu
The MB-System libraries will be placed in /usr/local/lib/, but the runtime dynamic linker does not look for shared libraries in this directory by default. Users can add /usr/local/lib to the directories searched for shared libraries by adding “/usr/local/lib” to the environment variable LD_LIBRARY_PATH. This is accomplished by placing the command
   export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
in an environment file in the user’s home directory named .zprofile (if using the zsh shell) or .profile (if using the bash shell). Other user environment files can be used, such as .zshrc for zsh or .bashrc for bash. The preferred alternative to using LD_LIBRARY_PATH is to embed the shared library location in the compiled libraries and executables by passing an rpath command to the linker by setting the LD_FLAGS environment variable available to the configure command:
   LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \
     ./configure \
        --enable-mbtrn --enable-mbtnav --enable-opencv \
        --with-opencv-include=/usr/include/opencv4 \
        --with-opencv-lib=/lib/x86_64-linux-gnu
Once the makefiles have been generated configure, build and install MB-System using:
   make
   sudo make install
This example is relevant for both Debian 11 and 12 because the prerequisite package names are the same. Ubuntu and Debian Linux distributions include multiple tools for managing software distributions. We recommend using the command line program apt to install the prerequisite software for MB-System. Install Debian 11 or 12 from an ISO image of the release downloaded from https://www.debian.org. Update the starting packages:
   sudo apt upgrade
Install compilers and other essential software:
   sudo apt install build-essential
Install MB-System prerequisites:
     sudo apt install netcdf-bin libnetcdf-dev libgdal-dev \
     gmt libgmt6 libgmt-dev libproj-dev \
       libfftw3-3 libfftw3-dev libmotif-dev \
     xfonts-100dpi libglu1-mesa-dev \
     libopencv-dev gfortran
MB-System also requires Python3 and the Pillow library for Python3. Both of these packages are installed by default in Debian 11 and 12. Download the MB-System source package from the repository at GitHub: https://github.com/dwcaress/MB-System There are often beta releases that are more recent than the current stable release. The most recent beta release will be at the top of this page: https://github.com/dwcaress/MB-System/releases We recommend using Chrome for the download rather than Safari, because Chrome does not prematurely unpack the tarball. Although MB-System can be installed from a source tree located anywhere, we generally place the tarball in /usr/local/src and then unpack and build MB-System there. Unpack the MB-System distribution tarball in /usr/local/src/ (or somewhere else, if you prefer – this is our convention for consistency when managing many installations). If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. (Replace the filename with the name of the current release.)
        mv MB-System-5.8.0-tar.gz /usr/local/src
        cd /usr/local/src
        tar xvzf MB-System-5.8.0.tar.gz
and then cd into the top directory of the resulting structure:
        cd MB-System-5.8.0
Option 1: **CMake Build System** (recommended)   At that location (/usr/local/src/MB-System-5.8.0/), create a working directory named “build”, **cd** into “build”, and then  execute **cmake** at the location /usr/local/src/MB-System-5.8.0/build/). The cmake command should successfully enable building the entire current MB-System (5.7.9 or later) on either Debian 11 or 12 as long as the prerequisite  software packages have been installed. Finally, install MB-System.
   mkdir build
   cd build
   cmake ..

   make
   sudo make install
Option 2: **Autotools Build System** (not recommended)   At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script, named configure, with the following options to build the entire MB-System package.
   ./configure \
          --enable-mbtrn --enable-mbtnav --enable-opencv \
          --with-opencv-include=/usr/include/opencv4 \
          --with-opencv-lib=/lib/x86_64-linux-gnu
The MB-System libraries will be placed in /usr/local/lib/, but the runtime dynamic linker does not look for shared libraries in this directory by default. Users can add /usr/local/lib to the directories searched for shared libraries by adding “/usr/local/lib” to the environment variable LD_LIBRARY_PATH. This is accomplished by placing the command
   export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
in an environment file in the user’s home directory named .zprofile (if using the zsh shell) or .profile (if using the bash shell). Other user environment files can be used, such as .zshrc for zsh or .bashrc for bash. The preferred alternative to using LD_LIBRARY_PATH is to embed the shared library location in the compiled libraries and executables by passing an rpath command to the linker by setting the LD_FLAGS environment variable available to the configure command:
   LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \
     ./configure \
        --enable-mbtrn --enable-mbtnav --enable-opencv \
        --with-opencv-include=/usr/include/opencv4 \
        --with-opencv-lib=/lib/x86_64-linux-gnu
(Note that the CMake build system, option 1 above, builds the binaries such that the runtime libraries are reliably found without any additional commands or argument.) Once the makefiles have been generated, install MB-System:
   make
   sudo make install 
This example is relevant for CentOs 7, and includes building the core MB-System programs plus the Terrain Relative Navigation tools, but not the photomosaicing tools (which require a more recent version of OpenCV than included in CentOs 7). CentOs and Red Hat Linux distributions include multiple tools for managing software distributions. We recommend using the command line program yum to install the prerequisite software for MB-System. Install CentOs 7 from an ISO image of the release downloaded from https://www.centos.org/download/ Update the starting packages:
      sudo yum upgrade
Install EPEL repo:
      sudo yum install epel-release
Install MB-System prerequisites:
      sudo yum install openmotif openmotif-devel \
        fftw fftw-devel netcdf netcdf-devel \
        proj proj-devel gdal-devel gmt gmt-devel gv \
        mesa-libGL mesa-libGL-devel \
        mesa-libGLU mesa-libGLU-devel
Download the MB-System source package from the repository at GitHub: https://github.com/dwcaress/MB-System There are often beta releases that are more recent than the current stable release. The most recent beta release will be at the top of this page: https://github.com/dwcaress/MB-System/releases Although MB-System can be installed from a source tree located anywhere, we generally place the tarball in /usr/local/src and then unpack and build MB-System there. Unpack the MB-System distribution tarball in /usr/local/src/ (or somewhere else, if you prefer – this is our convention for consistency when managing many installations). If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. (Replace the filename with the name of the current release.)
     mv MB-System-5.8.0-tar.gz /usr/local/src
     cd /usr/local/src
     tar xvzf MB-System-5.8.0.tar.gz
and then cd into the top directory of the resulting structure:
     cd MB-System-5.8.0
Only option for this operating system: Autotools Build System At that location (for this example, /usr/local/src/MB-System-5.7.9/), execute the configure script, named configure, with the following options to build the entire MB-System package.
     ./configure --enable-mbtrn --enable-mbtnav
The MB-System libraries will be placed in /usr/local/lib/, but the runtime dynamic linker does not look for shared libraries in this directory by default. Users can add /usr/local/lib to the directories searched for shared libraries by adding “/usr/local/lib” to the environment variable LD_LIBRARY_PATH. This is accomplished by placing the command
     export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH
in an environment file in the user’s home directory named .zprofile (if using the zsh shell) or .profile (if using the bash shell). Other user environment files can be used, such as .zshrc for zsh or .bashrc for bash. The preferred alternative to using LD_LIBRARY_PATH is to embed the shared library location in the compiled libraries and executables by passing an rpath command to the linker by setting the LD_FLAGS environment variable available to the configure command:
     LDFLAGS="-Wl,-rpath -Wl,/usr/local/lib" \
       ./configure --enable-mbtrn --enable-mbtnav
Once the makefiles have been generated by configure, build and install MB-System using:
     make
     sudo make install
CygWin is a collection of software tools that augment Windows computers with a Unix-style environment within which one can build, install, and run Unix-y packages like MB-System. If Cygwin has been installed on a Windows system, then one must install a number of additional prerequisite packages before building MB-System. The package installation is done using the Cygwin setup program **setyo0x86_64,exe** rather than through Linux-style package managers like **apt** or **yum**. This example installs the core command lineprograms of MB-System without any of the graphical tools. For this purpose the prerequisite packages include:
    • gcc
    • g++
    • rpc-devel
    • gambas3-devel
    • libproj-devel
    • libproj12
    • libnetcdf-devel
    • libnetcdf
    • libgdal-devl
    • libgdal19
    • libfftw3-devel
    • libfftw3
    • cmake
    • make
    • fftw
    • fftw-devel
    • ghostscript
    • gv
    • libcurl-devel
    • libnpcr0
    • libnpcr0-devel
    • libpcre
    • pcre-devel
    • openssh
    • subversion
    • xinit
    • zlib
    • zlib-devel
    • liblapack-devel
Once Cygwin and the prerequisite packages are installed, proceed as follows: Download the MB-System source package from the repository at GitHub: https://github.com/dwcaress/MB-System There are often beta releases that are more recent than the current stable release. The most recent beta release will be at the top of this page: https://github.com/dwcaress/MB-System/releases Although MB-System can be installed from a source tree located anywhere, we generally place the tarball in /usr/local/src and then unpack and build MB-System there. Unpack the MB-System distribution tarball in /usr/local/src/ (or somewhere else, if you prefer – this is our convention for consistency when managing many installations). If you do not have write privilege in /usr/local/src/ then you will need to execute the following commands using sudo. (Replace the filename with the name of the current release.)
        mv MB-System-5.8.0-tar.gz /usr/local/src
        cd /usr/local/src
        tar xvzf MB-System-5.8.0.tar.gz
and then cd into the top directory of the resulting structure:
        cd MB-System-5.8.0
Only option for this operating system: Autotools Build System At that location (/usr/local/src/MB-System-5.8.0/), execute the configure script, named configure, with the following options to build MB-System without any graphical tools:
       ./configure \
         --enable-mbtrn --enable-mbtnav  \
         --disable-dependency-tracking --disable-mbtools
Once the makefiles have been generated by configure, install MB-System:
        make
        sudo make install

1. PATH environment variable

Unless one specified otherwise, the MB-System executable programs are installed in the directory /usr/local/bin. For MB-System programs to execute from a command line, the /usr/local/bin directory must be included in a user’s \$PATH environment variable. This is typically accomplished by adding a statement like

   export PATH=/usr/local/bin:$PATH

in an environment file in the user’s home directory. These are often named .zshenv (if using the zsh shell), or .profile (if using the bash shell); other user environment files can be used, such as .zshrc for zsh or .bashrc for bash.

2. Enable MB-System GMT Modules (gmt.conf)

A key prerequisite for MB-System is the software package Generic Mapping Tools, or GMT. The programs mbcontour, mbswath, mbgrdtiff, and mbgrd2obj are actually GMT plug-in modules invoked as commands of the program gmt:

   gmt mbcontour (…various arguments…)  
   gmt mbswath (…various arguments…)  
   gmt mbgrdtiff (…various arguments…)
   gmt mbgrd2obj (…various arguments…)

These modules are contained in a dynamically loaded or shared library that is installed into /usr/local/lib. This library is named mbsystem.so on Linux computers and either mbsystem.dylib (when installed using CMake) or mbsystem.so (when installed using Autotools) on MacOS. For GMT to successfully execute these MB-System modules, the location of this library must be known to GMT. GMT looks for the modules using an internal variable GMT_CUSTOM_LIBS loaded from a configuration file named gmt.conf. One usually enables use of the MB-System GMT modules by creating (or altering) a gmt.conf file in the user’s home directory using the gmtset module of GMT:

   gmt gmtset GMT_CUSTOM_LIBS /usr/local/lib/mbsystem.so

or

   gmt gmtset GMT_CUSTOM_LIBS /usr/local/lib/mbsystem.dylib

as appropriate.

Some users modify additional GMT parameters using the gmt.conf file, for example, changing the COLOR_NAN parameter to be white so transparency can be set to 255,255,255 easily in a GIS. A description of all of the gmt.conf parameters is at:
https://docs.generic-mapping-tools.org/dev/gmt.conf.html.
To see what GMT parameter settings are being used, type:

   gmt defaults

A complexity not mentioned in the gmt.conf manual page is that GMT looks for gmt.conf first in the current working directory, then if not found, looks for it in the users home directory, and if still not found, uses the system defaults. A number of programs and plotting scripts using GMT create a gmt.conf file in the local directory, alter some of the settings in that file, use it, and then delete it before exiting. If one of these programs crashes or is interrupted before the temporary gmt.conf file is deleted, then a stray gmt.conf file is left that will become the default the next time GMT is run in that directory; we recommend deleting these extra gmt.conf files.

3. Perl ForkManager module

Several MB-System programs are written in the scripting language Perl. Three of these (mbm_multiprocess, mbm_multicopy, mbm_multidatalist) utilize a Perl library called ForkManager that enables parallel processing, and thus require that this library be installed. The management of Perl libraries is done with a tool named cpan rather than with the package managers used to install other MB-System prerequisites. Perl and cpan are available on all of the relevant operating systems. In all cases, execute:

   cpan Parallel:ForkManager

MB-System installations made using these directions will install files into the following locations:

  • /usr/local/bin/         Executable programs
  • /usr/local/lib/       Shared libraries
  • /usr/local/include/        Header files
  • /usr/local/share/man/        Unix style manual pages
  • /usr/local/share/doc/mbsystem/html/        Web site manual pages
  • /usr/local/share/mbsystem/        Resource data files

When one updates to a new MB-System version, we recommend uninstalling the previous version before installing the next. In the directory for the previous version (e.g., /usr/local/src/MB-System5.7.9/build/ if using CMake, or /usr/local/src/MB-System5.7.9/ if using Autotools), use the following command:

   sudo make uninstall
   sudo make clean

Then follow the installation instructions appropriate for your operating system, starting with downloading the next version from GitHub.

An updated MB-System Docker Image is generated each time that a new release is created in the MB-System Github repository. This Docker is based on Debian 12 Linux, and can be run on MacOs, Linux, and Windows computers. Data present on the host computer’s filesystems can be processed using the MB-System programs in the Docker container.

The MB-System docker image is available at
https://hub.docker.com/r/mbari/mbsystem

Documentation is available in the Github repository at:
https://github.com/dwcaress/MB-System/tree/master/docker/README.md
https://github.com/dwcaress/MB-System/tree/master/docker/README.pdf


There currently are no packaged distributions of MB-System. We are working on establishing them again.