GeographicLib: Installing GeographicLib

GeographicLib 2.7

Loading...
Searching...
No Matches
Installing GeographicLib
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. It should compile on any systems with a C++17 compliant compiler. First download one of

- GeographicLib-2.7.tar.gz tar'ed sources
- GeographicLib-2.7.zip zipped sources
- GeographicLib-2.7-win32.exe 32-bit binary installer for Windows
- GeographicLib-2.7-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.7.tar.gz
        unzip -q GeographicLib-2.7.zip

  then enter the directory created with

        cd GeographicLib-2.7

- 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 17" -A win32 \
          -D CMAKE_INSTALL_PREFIX="C:/Program Files (x86)/GeographicLib-2.7" \
          ..
        cmake -G "Visual Studio 17" -A x64 \
          -D CMAKE_INSTALL_PREFIX="C:/Program Files/GeographicLib-2.7" \
          ..

  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.7`. 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 Setting BINDIR=OFF has the side effect of removing tools from the default all target for make. (The tools can still be built with make tools.)
  - `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` (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 testprograms test # run some tests
        make install    # as root, if CMAKE_INSTALL_PREFIX is a system directory

  Possible additional targets are

        make libs       # make the libraries only, not the utilities
        make tools      # make the utilities
        make testprograms    # make the programs needed for "make test"
        make exampleprograms # make the example programs

  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.
- CMake can create the build directory for you. This allows you to configure and run the build on Windows with

        cmake -G "Visual Studio 17" -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.7.tar.gz

  then enter the directory created

        cd GeographicLib-2.7

- 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 15 2017 or later (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.7-win32.exe or GeographicLib-2.7-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.7 or C:\\Program Files (x86)\\GeographicLib-2.7,
- 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.7/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 15 2017 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.7.
- 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.7.

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.7.tar.gz
      GeographicLib-2.7.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 17" -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.