Back to Introduction. Forward to Getting started. Up to Contents.

GeographicLib has been developed under Linux with the g++ compiler, under Mac OS X with Xcode, and under Windows with Visual Studio 2015 and later. It should compile on any systems with a C++11 compliant compiler. First download one of

GeographicLib-2.1.2.tar.gz tar'ed sources
GeographicLib-2.1.2.zip zipped sources
GeographicLib-2.1.2-win32.exe 32-bit binary installer for Windows
GeographicLib-2.1.2-win64.exe 64-bit binary installer for Windows

Then pick one of the first five options below:

Installation with cmake. This is the preferred installation method as it will work on the widest range of platforms. However it requires that you have cmake installed.
Installation using the autoconfigure tools. This method works for most Unix-like systems, including Linux and Mac OS X.
Using a binary installer. Use this installation method if you only need to use the Utility programs supplied with GeographicLib.
Maintainer tasks. This describes addition tasks of interest only to the maintainers of this code.

This section documents only how to install the software. If you wish to use GeographicLib to evaluate geoid heights or the earth's gravitational or magnetic fields, then you must also install the relevant data files. See Installing the geoid datasets, Installing the gravity models, and Installing the magnetic field models for instructions.

The first two installation methods use two important techniques which make software maintenance simpler

Out-of-source builds: This means that you create a separate directory for compiling the code. In the description here the directories are called BUILD and are located in the top-level of the source tree. You might want to use a suffix to denote the type of build, e.g., BUILD-vc14 for Visual Studio 14 (2015), or BUILD-shared for a build which creates a shared library. The advantages of out-of-source builds are:
- You don't mess up the source tree, so it's easy to "clean up". Indeed the source tree might be on a read-only file system.
- Builds for multiple platforms or compilers don't interfere with each other.
The library is installed: After compilation, there is a separate install step which copies the headers, libraries, tools, and documentation to a "central" location. You may at this point delete the source and build directories. If you have administrative privileges, you can install GeographicLib for the use of all users (e.g., in /usr/local). Otherwise, you can install it for your personal use (e.g., in $HOME/packages).

Installation with cmake

This is the recommended method of installation; however it requires that cmake, version 3.7.0 or later, be installed on your system. This permits GeographicLib to be built either as a shared or a static library on a wide variety of systems. cmake can also determine the capabilities of your system and adjust the compilation of the libraries and examples appropriately.

cmake is available for most computer platforms. On Linux systems cmake will typically be one of the standard packages and can be installed by a command like

  yum install cmake

(executed as root). The minimum version of cmake supported for building GeographicLib is 3.7.0 (which was released on 2016-11-11).

On other systems, download a binary installer from https://www.cmake.org click on download, and save and run the appropriate installer. Run the cmake command with no arguments to get help. Other useful tools are ccmake and cmake-gui which offer curses and graphical interfaces to cmake. Building under cmake depends on whether it is targeting an IDE (interactive development environment) or generating Unix-style makefiles. The instructions below have been tested with makefiles and g++ on Linux and with the Visual Studio IDE on Windows. It is known to work also for Visual Studio 2017 Build Tools.

Here are the steps to compile and install GeographicLib:

Unpack the source, running one of

  tar xfpz GeographicLib-2.1.2.tar.gz
  unzip -q GeographicLib-2.1.2.zip

then enter the directory created with

  cd GeographicLib-2.1.2

Create a separate build directory and enter it, for example,
```
  mkdir BUILD
  cd BUILD 
```
Run cmake, pointing it to the source directory (..). On Linux, Unix, and MacOSX systems, the command is
```
  cmake .. 
```
For Windows, the command is typically something like
```
  cmake -G "Visual Studio 14" -A win32 \
    -D CMAKE_INSTALL_PREFIX="C:/Program Files (x86)/GeographicLib-2.1.2" \
    ..
  cmake -G "Visual Studio 14" -A x64 \
    -D CMAKE_INSTALL_PREFIX="C:/Program Files/GeographicLib-2.1.2" \
    ..
```
The definitions of CMAKE_INSTALL_PREFIX point to system directories. You might instead prefer to install to a user directory such as C:/Users/jsmith/projects/GeographicLib-2.1.2. The settings given above are recommended to ensure that packages that use GeographicLib use the version compiled with the right compiler. If you need to rerun cmake, use
```
  cmake . 
```
possibly including some options via -D (see the next step).
cmake allows you to configure how GeographicLib is built and installed by supplying options, for example `
```
  cmake -D CMAKE_INSTALL_PREFIX=/tmp/geographic . 
```
The options you might need to change are
- CMAKE_INSTALL_PREFIX (default: /usr/local on non-Windows systems, C:/Program Files/GeographicLib on Windows systems) specifies where the library will be installed. For Windows systems, you might want to use a prefix which includes the compiler version, in order to keep the libraries built with different versions of the compiler in distinct locations. If you just want to try the library to see if it suits your needs, pick, for example, CMAKE_INSTALL_PREFIX=/tmp/geographic. Where under CMAKE_INSTALL_PREFIX the various components of the library are installed is governed by the following variables (a value of an empty string or "OFF" disables installation):
  - INCDIR header files (the GeographicLib subdirectory is used)
  - BINDIR tools
  - SBINDIR admin tools
  - LIBDIR libraries
  - DLLDIR dlls
  - MANDIR the man pages (the man1 and man8 subdirectories are used)
  - CMAKEDIR cmake configs
  - PKGDIR package config
  - DOCDIR documentation
  - EXAMPLEDIR examples
- GEOGRAPHICLIB_DATA (default: /usr/local/share/GeographicLib for non-Windows systems, C:/ProgramData/GeographicLib for Windows systems) specifies the default location for the various datasets for use by Geoid, GravityModel, and MagneticModel. See Installing the geoid datasets, Installing the gravity models, and Installing the magnetic field models for more information.
- BUILD_SHARED_LIBS (default ON) and BUILD_BOTH_LIBS (default OFF) specify the types of libraries to build. If BUILD_BOTH_LIBS is set, then both shared and static libraries are building. Otherwise a single library is built with the type determined by BUILD_SHARED_LIBS
- CMAKE_BUILD_TYPE (default: Release). This flags only affects non-IDE compile environments (like make + g++). The default is actually blank, but this is treated as Release. Choose one of
```
  Debug
  Release
  RelWithDebInfo
  MinSizeRel
```
  (With IDE compile environments, you get to select the build type in the IDE.)
- BUILD_DOCUMENTATION (default: OFF). If set to ON, then html documentation is created from the source files, provided a sufficiently recent version of doxygen can be found. Otherwise, the html documentation will redirect to the appropriate version of the online documentation.
- GEOGRAPHICLIB_PRECISION specifies the precision to be used for "real" (i.e., floating point) numbers. See Support for high precision arithmetic for additional information about using quad and arbitrary precision. Nearly all the testing has been carried out with doubles and that's the recommended configuration. In particular you should avoid "installing" the library with a precision different from double. Here are the possible values
  1. float (24-bit precision); typically this is far to inaccurate for geodetic applications.
  2. double precision (53-bit precision, the default).
  3. long double (64-bit precision); this does not apply for Visual Studio (long double is the same as double with that compiler).
  4. quad precision (113-bit precision).
  5. arbitrary precision.
- USE_BOOST_FOR_EXAMPLES (default: OFF). If set to ON, then the Boost library is searched for in order to build the NearestNeighbor example.
- APPLE_MULTIPLE_ARCHITECTURES (default: OFF). If set to ON, build for i386 and x86_64 and Mac OS X systems. Otherwise, build for the default architecture.
- CONVERT_WARNINGS_TO_ERRORS (default: OFF). If set to ON, then compiler warnings are treated as errors.
Build and install the software. In non-IDE environments, run
```
  make         # compile the library and utilities
  make test    # run some tests
  make install # as root, if CMAKE_INSTALL_PREFIX is a system directory
```
Possible additional targets are
```
  make dist
  make exampleprograms 
```
On IDE environments, run your IDE (e.g., Visual Studio), load GeographicLib.sln, pick the build type (e.g., Release), and select "Build Solution". If this succeeds, select "RUN_TESTS" to build; finally, select "INSTALL" to install (RUN_TESTS and INSTALL are in the CMakePredefinedTargets folder). Alternatively (for example, if you are using the Visual Studio 2017 Build Tools), you run the Visual Studio compiler from the command line with
```
  cmake --build . --config Release --target ALL_BUILD
  cmake --build . --config Release --target RUN_TESTS
  cmake --build . --config Release --target INSTALL 
```
For maximum flexibility, it's a good idea to build and install both the Debug and Release versions of the library (in that order). The installation directories will then contain the release versions of the tools and both versions (debug and release) of the libraries. If you use cmake to configure and build your programs, then the right version of the library (debug vs. release) will automatically be used.
The headers, library, and utilities are installed in the include/GeographicLib, lib, and bin directories under CMAKE_INSTALL_PREFIX. (dll dynamic libraries are installed in bin.) For documentation, open in a web browser share/doc/GeographicLib/html/index.html.

With cmake 3.13 and later, cmake can create the build directory for you. This allows you to configure and run the build on Windows with

  cmake -G "Visual Studio 14" -A x64 -S . -B BUILD
  cmake --build BUILD --config Release --target ALL_BUILD

or on Linux with

  cmake -S . -B BUILD
  make -C BUILD -j4

Installation using the autoconfigure tools

The method works on most Unix-like systems including Linux and Mac OS X. Here are the steps to compile and install GeographicLib:

Unpack the source, running

  tar xfpz GeographicLib-2.1.2.tar.gz

then enter the directory created

  cd GeographicLib-2.1.2

Create a separate build directory and enter it, for example,
```
  mkdir BUILD
  cd BUILD 
```
Configure the software, specifying the path of the source directory, with
```
  ../configure 
```
By default GeographicLib will be installed under /usr/local. You can change this with, for example
```
  ../configure --prefix=/tmp/geographic 
```
Compile and install the software with
```
  make
  make install 
```
The headers, library, and utilities are installed in the include/GeographicLib, lib, and bin directories under prefix. For documentation, open share/doc/GeographicLib/html/index.html in a web browser.

Using a binary installer

Binary installers are available for some platforms

Windows

Use this method if you only need to use the GeographicLib utilities. The header files and static and shared versions of library are also provided; these can only be used by Visual Studio 14 2015 or later (2017, 2019, or 2022) (in either release or debug mode). However, if you plan to use the library, it may be advisable to build it with the compiler you are using for your own code using Installation with cmake.

Download and run GeographicLib-2.1.2-win32.exe or GeographicLib-2.1.2-win64.exe:

read the MIT/X11 License agreement,
select whether you want your PATH modified,
select the installation folder, by default C:\\Program Files\\GeographicLib-2.1.2 or C:\\Program Files (x86)\\GeographicLib-2.1.2,
select the start menu folder,
and install.

(Note that the default installation folder adheres the the convention given in Installation with cmake.) The start menu will now include links to the documentation for the library and for the utilities (and a link for uninstalling the library). If you ask for your PATH to be modified, it will include C:/Program FilesGeographicLib-2.1.2/bin where the utilities are installed. The headers and library are installed in the include/GeographicLib and lib folders. The libraries were built using using Visual Studio 14 2015 in release and debug modes. The utilities were linked against the release-mode shared library.

MacOSX

GeographicLib is available as Homebrew package geographiclib. Follow the directions on https://brew.sh/ for installing this package manager. Then type

brew install geographiclib

Now links to GeographicLib are installed under /usr/local.

Linux

Some Linux distributions, Fedora, Debian, and Ubuntu, offer GeographicLib as a standard package. Typically these will be one or two versions behind the latest. It's also available with the follow package managers

Homebrew package geographiclib (also for MacOSX)
conda-forge package geographiclib-cpp (also for MacOSX and Windows)
vcpkg package geographiclib (also for MacOSX and Windows)

Maintainer tasks

Some aspects of library maintenance are covered in HOWTO-RELEASE.txt.

Check the code out of git with

  git clone git@github.com:geographiclib/geographiclib.git

There are three branches in the git repository:

main: the main branch for code maintenance. Releases are tagged on this branch as, e.g., v2.1.2.
devel: the development branch; changes made here are merged into main.
release: the release branch created by unpacking the source releases (git is not used to merge changes from the other branches into this branch). This differs from the main branch in that some administrative files are excluded while some intermediate files are included (in order to aid building on as many platforms as possible). Releases are tagged on this branch as, e.g., r2.1.2.

The autoconf configuration script and the formatted man pages are not checked into main branch of the repository. In order to create these, configure with cmake and run

  make dist

which will copy the man pages from the build directory back into the source tree and package the resulting source tree for distribution as

  GeographicLib-2.1.2.tar.gz
  GeographicLib-2.1.2.zip

Finally,

  make package

or building PACKAGE in Visual Studio will create a binary installer for GeographicLib. For Windows, this requires in the installation of NSIS. On Windows, you should configure GeographicLib with PACKAGE_DEBUG_LIBS=ON, build both Release and Debug versions of the library and finally build PACKAGE in Release mode. This will get the release and debug versions of the library included in the package. For example, the 64-bit binary installer is created with

  cmake -G "Visual Studio 14" -A x64 \
    -D BUILD_BOTH_LIBS=ON \
    -D PACKAGE_DEBUG_LIBS=ON \
    ..
  cmake --build . --config Debug --target ALL_BUILD
  cmake --build . --config Release --target ALL_BUILD
  cmake --build . --config Release --target PACKAGE

Prior to making a release, the script develop/test-distribution.sh is run on a Fedora system. This checked that the library compiles correctly is multiple configurations. In addition it creates a directory and scripts for checking the compilation on Windows.

The following Fedora packages are required by tests/test-distribution.sh

cmake
automake
autoconf-archive
libtool
gcc-c++
ccache
doxygen
boost-devel
mpfr-devel
mpreal.h, version 3.6.9 with PR #15, from https://github.com/advanpix/mpreal and installed in the include/ directory.

For all the tests to be run, the following datasets need to be installed

geoid models: egm96-5
magnetic models: wmm2010 emm2015
gravity models: egm2008 grs80

Back to Introduction. Forward to Getting started. Up to Contents.