= Status Notice =

The CMake build configuration is a community-maintained non-officially supported build setup for GEOS. All GEOS users who aim to rely on CMake, please respect Sandro's request stated in comment on ticket #576 :
{{{
#!html
<p style="font-size: 100%; color: red; "> 
*** <em>The official build system is the GNU Automake one (for versions prior to GEOS 3.5). Starting at GEOS 3.5, we officially also support CMake. 
We will happily accept tickets for GEOS 3.5 against CMake. We would appreciate a patch if you have one, but not required.</em>. ***
</p>
}}}
= 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.

The CMake configuration for GEOS was introduced shortly after the [milestone:3.2.0 GEOS 3.2.0] release (ticket #317).

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 set by user to control various aspects of compilation and installation. For instance ''CMAKE_INSTALL_PREFIX'' variable which by default is set to ''/usr/local'' directory.

=== List of 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

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], which is distributed together with CMake.

After the build is ready, tests can be executed in ''BUILDDIR''. Natively, CMake uses a target named ''test'':

{{{
$ make test
}}}

For convenience, an Autotools-like target is available:

{{{
$ make check
}}}

It is possible to run the ''ctest'' program directly, without using a ''make'' target. This gives access to ''ctest'' command line options (see ''ctest --help'' for a listing).

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

A list of GEOS test suites can be 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)]]