#########################################################
Obtaining, building, installing, and testing PolyClipper
#########################################################

PolyClipper minimally requires a C++11 compliant compiler.  In order to build the Python interface you also need a Python 2 installation -- porting to Python 3 is forthcoming.  If you use git to clone the PolyClipper source note PolyClipper includes three submodules: `BLT <https://github.com/LLNL/blt>`_, `pybind11 <https://github.com/pybind/pybind11>`_, and `PYB11Generator <https://github.com/jmikeowen/PYB11Generator>`_.  In order to ensure these are properly downloaded when cloning PolyClipper be sure to use the ``--recurse-submodules`` git option::

  git clone --recursive https://github.com/LLNL/PolyClipper.git

If you forget to use the ``--recursive`` argument or if you checkout from a different branch you should execute::

  git submodule update --init --recursive

The C++ installation of PolyClipper is header only: to use from your own C++ code you simply need to ``#include <polyclipper2d.hh>`` or ``#include <polyclipper3d.hh>``, as appropriate.  The Python install consists of a single compiled library, ``PolyClipper``.

----------
Building
----------

PolyClipper uses the `CMake <https://cmake.org/>`_ build system for configuration, followed by whatever native build is available on your own platform as appropriately generated by CMake.  In this example we'll consider a Unix makefile style installation.

.. note::
   For C++ PolyClipper is a header only library, so if you just want to try it out without "building" and installing from C++, you can simply point your C++ include paths wherever you download and put PolyClippers header files (from the ``src`` directory in PolyClipper).

Generally building PolyClipper on a Unix-like system is as simple as::
  
  cd <PolyClipper download directory>
  mkdir build
  cd build
  cmake -DCMAKE_INSTALL_PREFIX=<some_path> ..
  make
  make install

If you also want these documentation files to be built you need to specify a Sphinx executable, and optionally a theme if you don't have/want the ``readthedocs`` Sphinx theme.  Useful CMake options that can be specified on the configuration line include:

CMake variables
--------------------

CMAKE_BUILD_TYPE : (Debug, Release, RelWithDebInfo, MinSizeRel)
  Choose the type of build -- for more information see the `CMake documentation <https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html>`_.

CMAKE_INSTALL_PREFIX
  The top-level path for installing PolyClipper include files, libraries, and any Python modules or documentation.

POLYCLIPPER_PYTHON_INSTALL
  Optionally specify a path for installing the PolyClipper Python module.  If not specified the Python module is installed to ``${CMAKE_INSTALL_PREFIX}/lib/python/site-packages/PolyClipper``.

PYTHON_EXE
  Optionally specify a specific Python executable to use when building Python module.  If this is not given PolyClipper checks to see if a suitable Python can be found and used automatically.

LOOKUP_PYBIND11_INCLUDE_PATH
  Optionally force the PYTHON_EXE to try and import pybind11 and deduce its include path.  If this parameter is not specified the pybind11 downloaded with PolyClipper is used.

PYBIND11_INCLUDE_PATH
  If desired you can explicitly specify the path to a pybind11 installation.  By default the PolyClipper downloaded version is used.

PYB11GENERATOR_ROOT_DIR
  Similarly you can explicitly specify a path to a PYB11Generator installation.  By default the PolyClipper downloaded version is used.

POLYCLIPPER_ENABLE_DOCS
  Turn Sphinx documentation generation on/off.

SPHINX_EXECUTABLE
  Specify where the Sphinx executable is that should be used to build documentation.  If not given, the executable path is searched for ``sphinx-build``.

SPHINX_THEME
  Give the Sphinx theme to use when generating documentation -- defaults to ``default``.

SPHINX_THEME_DIR
  Where to look for Sphinx themes.

POLYCLIPPER_MODULE_GEN
  Generate the PolyClipper python modules -- defaults to ``ON``.

POLYCLIPPER_ENABLE_PYTHON
  Install python interface, disables ``POLYCLIPPER_MODULE_GEN`` if turned off -- defaults to ``ON``.

POLYCLIPPER_INSTALL_DIR
  Specify where the header files will be installed -- defaults to ``include``.

-------
Testing
-------

PolyClipper can be tested using the Python module (if built).  There are two unit test classes in the ``test`` directory: ``testPolyClipper2d.py`` and ``testPolyClipper3d.py``.  So, once you have added the location of the ``PolyClipper.so`` file to your PYTHONPATH, testing is as simple as executing::

  cd test
  python testPolyClipper2d.py -v
  python testPolyClipper3d.py -v