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, pybind11, and 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 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.

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