= Status Notice =

The CMake build system is supported for GEOS versions 3.5 and after. 

The CMake configuration for GEOS was introduced shortly after the [milestone:3.2.0 GEOS 3.2.0] release (ticket #317).
GEOS version prior to 3.5 used GNU Automake as the only supported build system. 

= Building on Unix with CMake =

This article describes how to use the [http://www.cmake.org CMake] build system to build and install GEOS on Unix-like systems (Linux, Mac OS X, Solaris, *BSD, etc.) using GCC or any other supported compiler.

There are two ways of [http://www.cmake.org/cmake/help/runningcmake.html running CMake]:
 * cmake - [http://en.wikipedia.org/wiki/Command-line_interface CLI] program accepting options or running in ''interactive mode''
 * ccmake - program with curses-based GUI

== Requirements ==

 * [http://www.cmake.org CMake] 3.1 or later
 * Decent C++ compiler and C++ Standard Library, [http://gcc.gnu.org/ GNU GCC] 4.x or later recommended
 * GEOS source code.

== Configure ==

It is recommended to build GEOS outside of the source code tree. To do this, use a `build` directory beside the source directory `geos` (from now on referred to as ''BUILDDIR''):

{{{
$ git clone https://git.osgeo.org/gitea/geos/geos.git
$ mkdir build
$ ls
build geos
$ cd build
$ cmake ../geos
$ make help
}}}

There is collection of [http://cmake.org/cmake/help/cmake-2-8-docs.html#section_Variables CMake variables] available to control aspects of compilation and installation. They are specified on the `cmake` cmdline as `-DVAR=VALUE`.

=== Useful CMake options ===

 * `CMAKE_INSTALL_PREFIX` - by default is set to ''/usr/local'' directory
 * `CMAKE_BUILD_TYPE` - Values are `Release` or `Debug` (which is useful for debugging) 

=== CMake options specific to GEOS ===

 * GEOS_ENABLE_TESTS  - Set to OFF|ON (default) to control build of GEOS tests package
 * GEOS_ENABLE_INLINE - Set to OFF|ON (default) to control GEOS compilation with small functions inlining
 * GEOS_ENABLE_ASSERT - Set to ON|OFF (default) to build GEOS with assert() macro enabled (not available for Visual C++ compiler)
 * GEOS_ENABLE_MACOSX_FRAMEWORK - Set to ON|OFF (default) to build a Mac OS X framework
 * GEOS_ENABLE_MACOSX_FRAMEWORK_UNIXCOMPAT - Set to ON|OFF (default) to add compatibility with *nix library linking to the Mac OS X framework
 * -DDISABLE_OVERLAYNG=NO - Set to NO|YES (default) to enable OverlayNG use in Geometry overlay methods. (Note: as of GEOS 3.9 OverlayNG will be the default)

Example:

{{{
$ cmake ../geos -DGEOS_ENABLE_TESTS=ON -DGEOS_ENABLE_INLINE=OFF
}}}

Note: when building a Mac OS X framework, you must specify the CMAKE_INSTALL_PREFIX.  The default is /usr/local, and frameworks don't go there.

{{{
-DCMAKE_INSTALL_PREFIX=/Library/Frameworks
}}}

== Build == 

To build, run `make` in ''BUILDDIR'':

{{{
$ make
}}}

This creates:
* GEOS C++ and C libraries in `lib`
* Testing executables in `bin`

== Test == 

Under CMake testing is performed by [http://www.itk.org/Wiki/CTest:FAQ CTest].

After building, tests can be executed in ''BUILDDIR''. Natively, CMake uses a target named ''test'':

{{{
$ make test
}}}

For convenience an Autotools-like `check` target is available:

{{{
$ make check
}}}

It is possible to run `ctest` directly. This gives access to ''ctest'' command line options (see ''ctest --help'' for a listing).

{{{
$ ctest
$ ctest --verbose
}}}

A list of GEOS test suites is obtained by running ''ctest --show-only'':

{{{
$ ctest --show-only
# 
# Test project /home/dan/dev/libgeos/cmake-build-debug
#  Test #1: test_geos_unit
#  Test #2: test_xmltester
#  Test #3: test_bug234
#  Test #4: test_sweep_line_speed
}}}

A subset of test suites can be run using a regular expression (and in this case, running 4 jobs in parallel):

{{{
$ ctest --tests-regex test_ --parallel 4
}}}

Individual test classes within the ''test_geos_unit'' suite can be run by calling the ''test_geos_unit'' executable directly:

{{{
$ bin/test_geos_unit capi::GEOSNode
}}}

Individual tests within a test class can be run by specifying the test number:

{{{
$ bin/test_geos_unit capi::GEOSNode 1
}}}

There are additional tests (typically for performance) which are built, but not run as part of the standard test suite.
These can be run from the command line:

{{{
$ bin/perf_iterated_buffer
}}}

== Install == 

In order to install both C and C++ API libraries as well as headers, stay on in ''BUILDDIR'' and execute:

{{{
$ make install
}}}

== Uninstall == 

Still in ''BUILDDIR'', run:

{{{
$ make uninstall
}}}

= Open Tickets =

[[TicketQuery(status=new|assigned|reopened&component~=cmake&order=priority)]]