1# Building GMT
2
3This document describes how to build GMT from source codes
4(stable release or development version) on Linux, FreeBSD, OpenBSD, macOS and Windows.
5
6## Contents
7
8- [Build and runtime dependencies](#build-and-runtime-dependencies)
9- [Getting GMT source codes](#getting-gmt-source-codes)
10- [Configuring](#configuring)
11- [Building GMT source codes](#building-gmt-source-codes)
12- [Installing](#installing)
13- [Setting path](#setting-path)
14- [Advanced instructions](#advanced-instructions)
15
16## Build and runtime dependencies
17
18GMT is dependent on some software and libraries to run.
19Please refer to the [GMT wiki page](https://github.com/GenericMappingTools/gmt/wiki)
20for instructions to install these dependencies on various operation systems.
21
22### Required dependencies
23
24To build GMT, you have to install:
25
26- [CMake](https://cmake.org/) (>=2.8.12)
27- [netCDF](https://www.unidata.ucar.edu/software/netcdf/) (>=4.0, netCDF-4/HDF5 support mandatory)
28- [curl](https://curl.haxx.se/)
29
30### Optional dependencies
31
32Optionally install these for more capabilities within GMT:
33
34- [Ghostscript](https://www.ghostscript.com/) (Ability to convert PostScript plots to PDF and rasters)
35- [GDAL](https://www.gdal.org/) (Ability to read and write numerous grid and image formats)
36- [GEOS](https://trac.osgeo.org/geos/) (Ability to buffer lines and polygons)
37- [PCRE](https://www.pcre.org/) or PCRE2 (Regular expression support)
38- [FFTW](http://www.fftw.org/) single-precision (Fast FFTs, >=3.3 [not needed under macOS])
39- [GLib](https://wiki.gnome.org/Projects/GLib) GTHREAD support (>=2.32)
40- LAPACK (Fast matrix inversion [not needed under macOS])
41- BLAS (Fast matrix multiplications [not needed under macOS])
42
43For movie-making capabilities these executables are needed:
44
45- [GraphicsMagick](http://www.graphicsmagick.org/) (Convert images to animated GIFs)
46- [FFmpeg](http://www.ffmpeg.org/) (Convert images to videos)
47
48For viewing documentation under Linux via `gmt docs`, your need `xdg-open`:
49
50- xdg-open (Unified open for a variety of files)
51
52### Development dependencies
53
54Install for building GMT documentation and running tests (not required for general use):
55
56- [Sphinx](http://www.sphinx-doc.org) (>=1.8, for building the documentation)
57- [GraphicsMagick](http://www.graphicsmagick.org/) (for running the tests)
58- [Ninja](https://ninja-build.org/) (optional, build system focused on speed)
59- [pngquant](https://pngquant.org/) (optional, for optimizing PNG images in the documentation)
60
61### Required support data
62
63You also need to download support data:
64
65- [GSHHG](https://github.com/GenericMappingTools/gshhg-gmt): A Global Self-consistent, Hierarchical, High-resolution
66  Geography Database (>=2.2.0)
67- [DCW](https://github.com/GenericMappingTools/dcw-gmt): The Digital Chart of the World (optional, >=2.0.0)
68
69## Getting GMT source codes
70
71The latest stable release of the GMT source codes (filename: gmt-x.x.x-src.tar.gz)
72are available from [GMT repository on GitHub](https://github.com/GenericMappingTools/gmt/releases).
73
74If you want to build/use the latest developing/unstable GMT, you can get the source codes by cloning the
75[GMT repository on GitHub](https://github.com/GenericMappingTools/gmt). *Here we use `--depth 50` option for a shallow
76clone which can reduce the repository size to download.*
77
78    git clone --depth 50 https://github.com/GenericMappingTools/gmt
79
80You can also get supporting data GSHHG and DCW (filename: gshhg-gmt-x.x.x.tar.gz and dcw-gmt-x.x.x.tar.gz)
81from the [GMT main site](https://www.generic-mapping-tools.org/download/#support-data).
82
83Extract the files and put them in a separate directory (need not be where you eventually want to install GMT).
84
85> Note for developers: Refer to the [git workflow tutorial](http://www.asmeurer.com/git-workflow/) for more detailed
86> instructions on cloning and forking the repository. It is recommended that you use a full clone rather than a shallow
87> clone.
88
89## Configuring
90
91GMT can be built on any platform supported by CMake. CMake is a cross-platform,
92open-source system for managing the build process. The building process is
93controlled by three configuration files in the `cmake` directory:
94
95-   `ConfigDefault.cmake` is version controlled and used to add new default
96    variables and set defaults for everyone. **You should NOT edit this file.**
97-   `ConfigUser.cmake` is not version controlled and is used to override basic
98    default settings on a per-user basis.
99-   `ConfigUserAdvanced.cmake` is not version controlled and is used to override
100    more advanced default settings on a per-user basis.
101
102GMT provides two template files, `ConfigUserTemplate.cmake` and `ConfigUserAdvancedTemplate.cmake` in the `cmake`
103directory. In that directory, you may copy `ConfigUserTemplate.cmake` to `ConfigUser.cmake` and edit to change basic
104installation parameters. For more advanced parameters, you may copy `ConfigUserAdvancedTemplate.cmake` to
105`ConfigUserAdvanced.cmake` and edit.
106
107> Note for developers: It is necessary to create both `ConfigUser.cmake` and `ConfigUserAdvanced.cmake` in the `cmake`
108> directory using the templates provided in order to enable testing. Refer to the section
109> [setting up your environment](https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html#setting-up-your-environment) in the
110> [contributing guide](https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html)
111> for instructions on setting up `cmake/ConfigUserAdvanced.cmake`.
112
113Here is an example of settings you may want to change after copying `cmake/ConfigUserTemplate.cmake` to
114`cmake/ConfigUser.cmake`.
115
116```
117set (CMAKE_INSTALL_PREFIX "/opt/gmt")
118set (GSHHG_ROOT "/path/to/gshhg")
119set (DCW_ROOT "/path/to/dcw")
120```
121
122For Windows users, a good example is:
123
124```
125set (CMAKE_INSTALL_PREFIX "C:/programs/gmt6")
126set (GSHHG_ROOT "C:/path/to/gshhg")
127set (DCW_ROOT "C:/path/to/dcw")
128```
129
130See the additional comments in `cmake/ConfigUserTemplate.cmake` for more details.
131
132Now that you made your configuration choices, it is time for invoking CMake.
133To keep generated files separate from source files in the source tree,
134you should create a build directory in the top-level directory,
135where the build files will be generated, and change into your build directory:
136
137```
138mkdir build
139cd build
140cmake ..
141```
142
143For Windows users, you need to open a command prompt and run:
144
145**NOTE:** Commands below are valid only if you have GMT's dependency libraries installed
146via vcpkg following [these instructions](https://github.com/GenericMappingTools/gmt/wiki/Install-dependencies-on-Windows-via-vcpkg).
147
148```
149mkdir build
150cd build
151# For x64 build
152cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_GENERATOR_PLATFORM=x64
153# For x86 build
154cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_GENERATOR_PLATFORM=x86
155```
156
157For advanced users, you can append the option `-G Ninja` to use the
158build tool [Ninja](https://ninja-build.org/), which is a small build system
159with a focus on speed.
160
161
162## Building GMT source codes
163
164In the build directory, type
165
166```
167# Linux/macOS/FreeBSD/OpenBSD
168cmake --build .
169
170# Windows
171cmake --build . --config Release
172```
173
174which will compile all the programs. You can also append ``--parallel [jobs]`` to enable parallel build, in which
175``jobs`` is the maximum number of concurrent processes to use when building. If ``jobs`` is omitted the native build
176tool's default number is used.
177
178> Note: These instructions build the source code for GMT. Optionally, follow the instructions for
179> [building the documentation](https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html#building-the-documentation)
180> in the [contributing guide](https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html) to
181> build the documentation (for example, to develop the documentation or to use `gmt docs` without the GMT server).
182
183> Note for developers: Refer to the file `admin/bashrc_for_gmt` for useful aliases for configuring and building GMT.
184
185## Installing
186
187```
188# Linux/macOS/FreeBSD/OpenBSD
189cmake --build . --target install
190
191# Windows
192cmake --build . --target install --config Release
193```
194
195will install gmt executable, library, development headers and built-in data
196to the specified GMT install location.
197Optionally it will also install the GSHHG shorelines (if found), DCW (if found),
198UNIX manpages, and HTML documentations.
199
200Depending on where GMT is being installed, you might need
201write permission for this step so you can copy files to system directories.
202Using `sudo` will often do the trick.
203
204> Note for developers: Refer to the section
205> [Updating the development source codes](https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html#updating-the-development-source-codes) in the
206> [contributing guide](https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html) for instructions on how to update the development version of GMT. Also refer to
207> the file `admin/bashrc_for_gmt` for useful aliases for updating the development source code.
208
209## Setting path
210
211Make sure you set the `PATH` to include the directory containing the GMT executables
212if this is not a standard directory like `/usr/local/bin`.
213
214For Linux/macOS users, open your SHELL configuration file (usually `~/.bashrc`)
215and add the line below to it.
216
217```
218export PATH=${PATH}:/path/to/gmt/bin
219```
220
221Then, you should now be able to run GMT programs.
222
223## Advanced instructions
224
225For advanced users who are interested in building documentation, running tests, or
226contributing more to GMT, please refer the [contributing guide](https://docs.generic-mapping-tools.org/dev/devdocs/contributing.html).
227