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_CXXONLY
Only install the C++ headers, also sets
POLYCLIPPER_MODULE_GEN
toOFF
– defaults toOFF
.- 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