GEOS -- Geometry Engine, Open Source

GEOS is a C++11 library for performing operations on two-dimensional vector geometries. It is primarily a port of the JTS Topology Suite Java library. It provides many of the algorithms used by PostGIS, the Shapely package for Python, the sf package for R, and others.

More information is available the project homepage.

Build status

branch / CI	Debbie	Winnie	Dronie	Travis CI	GitLab CI	AppVeyor	Bessie	Bessie32
master
3.7
3.6

Building GEOS From Source

Prerequisites

GEOS has no external library dependencies and can be built with any C++11 compiler.

Unix

GEOS can be built on Unix systems using either the autotools or CMake build systems.

Using Autotools:

When building GEOS using autotools, a configure script must first be generated using the autogen.sh file included in the root of the repository:

./autogen.sh

An out-of-tree build can then be initiated by creating a subdirectory and running the generated configure script from that subdirectory:

mkdir obj && cd obj && ../configure

Once the configure script has run, GEOS can be built by running make and installed by running make install. The test suite can be run using make check.

Using CMake:

To build GEOS using CMake, create a build directory and run the cmake command from that location:

mkdir build && cd build && cmake -DCMAKE_BUILD_TYPE=Release ..

Setting CMAKE_BUILD_TYPE to Release is necessary to enable compiler optimizations.

Once the cmake tool has run, GEOS can be built by running make and installed by running make install. The test suite can be run using make check.

Microsoft Windows

GEOS can be built with Microsoft Visual C++ by opening the CMakeLists.txt in the project root using File > Open > CMake.

If you prefer the command-line

Build with CMake generator for Ninja (fast)

In the Visual Studio 2019 command prompt, x64 Native Tools Command Prompt for VS 2019 or x64_x86 Cross Tools Command Prompt for VS 2019:

cmake -S . -B _build_vs2019_ninja -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build _build_vs2019_ninja -j 16 --verbose

Build with CMake generator for MSBuild (default)

In the non-specific Command Prompt:

64-bit

cmake -S . -B _build_vs2019x64 -G "Visual Studio 16 2019" -A x64 -DCMAKE_GENERATOR_TOOLSET=host=x64
cmake --build _build_vs2019x64 --config Release -j 16 --verbose

32-bit

cmake -S . -B _build_vs2019x32 -G "Visual Studio 16 2019" -A x32 -DCMAKE_GENERATOR_TOOLSET=host=x64
cmake --build _build_vs2019x32 --config Release -j 16 --verbose

Test using CMake

cd <build directory>
ctest --show-only
ctest
ctest --output-on-failure
ctest -V
ctest -VV

Client applications

Using the C interface

GEOS promises long-term stability of the C API. In general, successive releases of the C API may add new functions but will not remove or change existing types or function signatures. The C library uses the C++ interface, but the C library follows normal ABI-change-sensitive versioning, so programs that link only against the C library should work without relinking when GEOS is upgraded. For this reason, it is recommended to use the C API for software that is intended to be dynamically linked to a system install of GEOS.

The geos-config program can be used to determine appropriate compiler and linker flags for building against the C library:

CFLAGS += `geos-config --cflags`
LDFLAGS += `geos-config --ldflags` -lgeos_c

All functionality of the C API is available through the geos_c.h header file.

Documentation for the C API is provided via comments in the geos_c.h header file. C API usage examples can be found in the GEOS unit tests and in the source code of software that uses GEOS, such as PostGIS and the sf package for R.

Using the C++ interface

The C++ interface to GEOS provides a more natural API for C++ programs, as well as additional functionality that has not been exposed in the C API. However, developers who decide to use the C++ interface should be aware that GEOS does not promise API or ABI stability of the C++ API between releases. Breaking changes in the C++ API/ABI are not typically announced or included in the NEWS file.

The C++ library name will change on every minor release.

The geos-config program can be used to determine appropriate compiler and linker flags for building against the C++ library:

CFLAGS += `geos-config --cflags`
LDFLAGS += `geos-config --ldflags` -lgeos

A compiler warning may be issued when building against the C++ library. To remove the compiler warning, define USE_UNSTABLE_GEOS_CPP_API somewhere in the program.

Commonly-used functionality of GEOS is available in the geos.h header file. Less-common functionality can be accessed by including headers for individual classes, e.g. #include <geos/algorithm/distance/DiscreteHausdorffDistance.h>.

#include <geos.h>

Documentation for the C++ API is available at https://geos.osgeo.org/doxygen/, and basic C++ usage examples can be found in doc/example.cpp.

Scripting language bindings

Ruby

Ruby bindings are part of GEOS. To build, use the --enable-ruby option when configuring:

./configure .. --enable-ruby

PHP

PHP bindings for GEOS are available separately from php-geos.

Python

Python bindings are available via:

1. Shapely package.
2. Calling functions from libgeos_c via Python ctypes.

Documentation

To build Doxygen documentation:

cd doc
make doxygen-html

Style

To format your code into the desired style, use the astyle version included in source tree:

tools/astyle.sh <yourfile.cpp>