Skip to content

Latest commit

 

History

History
378 lines (264 loc) · 12.1 KB

BUILDING.md

File metadata and controls

378 lines (264 loc) · 12.1 KB
Raw

Building GMT

Contents

Build and runtime dependencies

To build GMT, you must install:

Optionally install for more capabilities within GMT:

  • GDAL (Ability to read and write numerous grid and image formats)
  • PCRE or PCRE2 (Regular expression support)
  • FFTW single-precision (Fast FFTs, >=3.3 [not needed under macOS])
  • LAPACK (Fast matrix inversion [not needed under macOS])
  • BLAS (Fast matrix multiplications [not needed under macOS])

For movie-making capabilities these executables are needed:

Optionally install for building GMT documentations and running tests:

  • Sphinx (>=1.4.x, for building the manpage, HTML and PDF documentation)
  • TeXLive (for building the PDF documentation)
  • GraphicsMagick (for running the tests)

You also need download support data:

  • GSHHG: A Global Self-consistent, Hierarchical, High-resolution Geography Database (>=2.2.0)
  • DCW-GMT: The Digital Chart of the World (optional, >=1.0.5)

Install dependencies

Ubuntu/Debian

For Ubuntu and Debian, there are prepackaged development binaries available. Install the GMT dependencies with:

# Install required dependencies
sudo apt-get install build-essential cmake libcurl4-gnutls-dev libnetcdf-dev ghostscript

# Install optional dependencies
sudo apt-get install libgdal1-dev libfftw3-dev libpcre3-dev liblapack-dev libblas-dev

# to enable movie-making
sudo apt-get install graphicsmagick ffmpeg

# to enable testing
sudo apt-get install graphicsmagick

# to build the documentation
sudo apt-get install python-sphinx

# to build the documentation in PDF format
sudo apt-get install texlive-latex-recommended texlive-fonts-recommended texlive-latex-extra latexmk

RHEL/CentOS

For RHEL and CentOS, GMT's dependencies are available from Extra Packages for Enterprise Linux. You can add this repository by telling yum:

sudo yum install epel-release

You then can install the GMT dependencies with:

# Install necessary dependencies
sudo yum install cmake libcurl-devel netcdf-devel ghostscript

# Install optional dependencies
sudo yum install gdal-devel pcre-devel fftw3-devel lapack-devel openblas-devel

# to enable movie-making
# ffmpeg is provided by [rmpfusion](https://rpmfusion.org/)
sudo yum localinstall --nogpgcheck https://download1.rpmfusion.org/free/el/rpmfusion-free-release-7.noarch.rpm
sudo yum install GraphicsMagick ffmpeg

# to enable testing
sudo yum install GraphicsMagick

# to build the documentation
sudo yum install python-sphinx

# to build the documentation in PDF format
sudo yum install python3-sphinx-latex

Fedora

For Fedora, there are prepackaged development binaries available. Install the GMT dependencies with:

# Install necessary dependencies
sudo dnf install cmake libcurl-devel netcdf-devel ghostscript

# Install optional dependencies
sudo dnf install gdal-devel pcre-devel fftw3-devel lapack-devel openblas-devel

# to enable movie-making
# ffmpeg is provided by [rmpfusion](https://rpmfusion.org/)
sudo dnf install https://download1.rpmfusion.org/free/fedora/rpmfusion-free-release-$(rpm -E %fedora).noarch.rpm
sudo dnf install GraphicsMagick ffmpeg

# to enable testing
sudo dnf install GraphicsMagick

# to build the documentation
sudo dnf install python-sphinx

# to build the documentation in PDF format
sudo dnf install python-sphinx-latex

Archlinux

For Archlinux, there are prepackaged development binaries available. Install the gmt dependencies with:

# install necessary dependencies
sudo pacman -S base-devel cmake libcurl-gnutls netcdf ghostscript

# install optional dependencies
sudo pacman -S gdal pcre fftw lapack openblas

# to enable movie-making
sudo pacman -S graphicsmagick ffmpeg

# to enable testing
sudo pacman -S graphicsmagick

# to build the documentation
sudo pacman -S python-sphinx

FreeBSD

For FreeBSD, there are prepackaged development binaries available. Install the gmt dependencies with:

# install necessary dependencies
sudo pkg install shells/bash devel/cmake ftp/curl science/netcdf print/ghostscript9

# install optional dependencies
sudo pkg install graphics/gdal devel/pcre math/fftw3-float math/lapack math/openblas

# to enable movie-making
sudo pkg install graphics/GraphicsMagick multimedia/ffmpeg

# to enable testing
sudo pkg install graphics/GraphicsMagick

# to build the documentation
sudo pkg install py36-sphinx

macOS with homebrew

For macOS with homebrew installed, you can install the dependencies with:

# Install necessary dependencies
brew install cmake curl netcdf ghostscript

# Install optional dependencies
brew install gdal pcre fftw

# to enable movie-making
brew install graphicsmagick ffmpeg

# to enable testing
brew install graphicsmagick

# to build the documentation
brew install sphinx-doc

# to build the documentation in PDF format
brew cask install mactex-no-gui

Get GMT source codes

The latest stable release of the GMT source codes (filename: gmt-x.x.x-src.tar.gz) are available from:

You can also get supporting data GSHHG and DCW (filename: gshhg-gmt-x.x.x.tar.gz and dcw-gmt-x.x.x.tar.gz) from:

Extract the files and put them in a separate directory (need not be where you eventually want to install GMT).

If you want to build/use the latest developing/unstable GMT, you can get the source codes from GitHub by:

git clone https://github.com/GenericMappingTools/gmt

Configuring

GMT can be built on any platform supported by CMake. CMake is a cross-platform, open-source system for managing the build process. The building process is controlled by two configuration files in the cmake directory:

  • ConfigDefault.cmake: is version controlled and used to add new default variables and set defaults for everyone. You should not edit this file.
  • ConfigUser.cmake: is not version controlled and used to override defaults on a per-user basis. There is a template file, ConfigUserTemplate.cmake, that you should copy to ConfigUser.cmake and make your changes therein.

In the source tree, copy cmake/ConfigUserTemplate.cmake to cmake/ConfigUser.cmake, and edit the file according to your demands. This is an example:

set (CMAKE_INSTALL_PREFIX /opt/gmt)
set (GSHHG_ROOT <path to gshhg>)
set (DCW_ROOT <path to dcw>)

See the additional comments in cmake/ConfigUserTemplate.cmake for more details.

Now that you made your configuration choices, it is time for invoking CMake. Create a subdirectory where the build files will be generated, e.g., in the source tree mkdir build and then cd build.

In the build subdirectory, type

cmake ..

For advanced users, you can append the option -G Ninja to use the build tool Ninja, which is a small build system with a focus on speed.

Building GMT source codes

In the build directory, type

cmake --build .

which will compile all the programs. You can also append --parallel [<jobs>] to enable parallel build, in which jobs is the maximum number of concurrent processes to use when building. If jobs is omitted the native build tool's default number is used.

Building documentation

The GMT documentations are available in different formats and can be generated with:

cmake --build . --target docs_man           # UNIX manual pages
cmake --build . --target docs_html          # HTML manual, cookbook, and API reference
cmake --build . --target docs_pdf           # PDF manual, cookbook, and API reference
cmake --build . --target docs_pdf_shrink    # Like docs_pdf but with reduced size

To generate the documentation you need to install the Sphinx documentation builder, and for PDFs you also need LaTeX. You can choose to install the documentation files from an external location instead of generating the Manpages, PDF, and HTML files from the sources. This is convenient if Sphinx and/or LaTeX are not available. Set GMT_INSTALL_EXTERNAL_DOC in cmake/ConfigUser.cmake.

Install

cmake --build . --target install

will install gmt executable, library, development headers and built-in data to the specified GMT install location. Optionally it will also install the GSHHG shorelines (if found), DCW (if found), UNIX manpages, and HTML and PDF documentation.

Depending on where GMT is being installed, you might need write permission for this step so you can copy files to system directories. Using sudo will often do the trick.

Set path

Make sure you set the PATH to include the directory containing the GMT executables (BINDIR) if this is not a standard directory like /usr/local/bin. Then, you should now be able to run GMT programs.

Running tests

A complete set of the example scripts used to create all the example plots, including all necessary data files, are provided by the installation. To enable testing, you need following lines in your ConfigUser.cmake:

enable_testing()
set (DO_EXAMPLES TRUE)
set (DO_TESTS TRUE)
set (DO_ANIMATIONS TRUE)

Then run:

cmake --build . --target check

Optionally set N_TEST_JOBS to the number of ctest jobs to run simultaneously.

You can also select individual tests using regexp with ctest, e.g.:

ctest -R ex2[3-6]

Updating the development source codes

Assuming you did not delete the build directory, this is just as simple as

cd path-to-gmt
git pull
cd build
cmake --build .
cmake --build . --target install

CMake will detect any changes to the source files and will automatically reconfigure. If you deleted all files inside the build directory you have to run cmake again manually.

Packaging

Currently, packaging with CPack works on macOS (Bundle, TGZ, TBZ2), Windows (ZIP, NSIS), and UNIX (TGZ, TBZ2). On Windows you need to install NSIS. After building GMT and the documentation run either one of these:

cmake --build . --target package
cpack -G <TGZ|TBZ2|Bundle|ZIP|NSIS>

Creating a source package

Set GMT_RELEASE_PREFIX in cmake/ConfigUser.cmake and run cmake. Then do

cmake --build . --target gmt_release      # export the source tree and install doc

You should then edit ${GMT_RELEASE_PREFIX}/cmake/ConfigDefault.cmake and set GMT_PACKAGE_VERSION_MAJOR, GMT_PACKAGE_VERSION_MINOR, and GMT_PACKAGE_VERSION_PATCH. Also uncomment and set GMT_SOURCE_CODE_CONTROL_VERSION_STRING to the current git version. Then create tarballs with:

cmake --build . --target gmt_release_tar