pmp-library  1.2.1
Installation

In this section, we describe how to configure, build, and install the pmp-library in detail.

# System Requirements

The pmp-library uses CMake as its build configuration system. Version 3.0.2 or greater is required. The pmp-library requires a C++11-compliant compiler. We continuously build and test the pmp-library with the following compilers and operating systems:

Operating System Compiler
Linux gcc 4.8.4, clang 3.9.0
Mac OS-X AppleClang 8.1.0
Windows Visual Studio 2015, 2017

# Dependencies

Some parts of the pmp-library depends on the following third-party libraries:

Library Description Version
Eigen C++ linear algebra library ≥ 3.3.7
OpenGL Open Graphics Library ≥ 3.3
GLEW OpenGL Extension Wrangler Library ≥ 2.1.0
GLFW Graphics Library Framework ≥ 3.3
ImGui Immediate Mode GUI ≥ 1.70
Google Test C++ Test Framework ≥ 1.8.0

By default, we include the corresponding libraries using git submodules. Note that OpenGL and related dependencies are optional. They are only needed if you want to use the viewer classes. Google Test is optional as well and only required if you want to run the unit test suite.

# Configuration

The pmp-library relies on CMake as its build and configuration system. CMake is a cross-platform build-system capable of generating different build files (so-called generators) for a specific platform, e.g., Makefiles for Linux/Unix, Xcode projects for Mac OS-X and Visual Studio projects for Windows.

On the command line change to the top-level pmp-library directory, create a build directory and run cmake:

cd pmp
mkdir build
cd build
cmake ..


The configuration procedure can be fine-tuned by specifying flags using the -D option of cmake:

cmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_COMPILER=/usr/bin/g++


The command above would configure CMake to use release mode as its build type and /usr/bin/g++ as its C++ compiler.

In order to compile the included examples configure CMake with

cmake -DWITH_EXAMPLES=true ..


Commonly used flags are shown below.

Flag Description
CMAKE_BUILD_TYPE Specify the build type, e.g. Debug or Release.
CMAKE_CXX_COMPILER Specify the compiler to be used.
CMAKE_CXX_FLAGS Specify additional compiler flags, e.g. -DNDEBUG

For additional information on using CMake and customizing its configuration see the CMake documentation.

# Building

After successful configuration pmp-library can be build using the chosen build system. For a Unix-like environment the default generator is Makefiles. In order to build pmp-library just call

make


from the top-level build directory. In order to build pmp in parallel use the -j option of make:

make -j


The resulting library is named libpmp.so and located in the current working directory.

In order to build the full HTML manual and reference documentation call

make doxygen


The resulting HTML documentation can be found in the docs/html/ sub-directory. Note: this requires Doxygen to be installed. In order to generate proper bibliographical references please install BibTex as well.

# Installation

In order to install pmp-library just call

sudo make install


Upon installation, both the library and headers will be installed to the directory given via CMAKE_INSTALL_PREFIX, which defaults to /usr/local/ on Unix-like systems. If you need to install to a custom location set the install prefix during build configuration:

cmake -DCMAKE_INSTALL_PREFIX=<your custom path> ..


The library can be uninstalled using

make uninstall


To use the pmp-library in your own CMake-based projects simply include the library by using find_package(pmp) and point CMake to the directory containing the pmp-library CMake configuration file pmpConfig.cmake. This can be either the pmp-library build directory

cmake -Dpmp_DIR=<path-to-pmp-build-directory>


or the installed version

cmake -Dpmp_DIR=<your custom path>/lib/cmake/pmp


target_link_libraries(your_target pmp)


Note: The usage described above is currently limited to the core and algorithms modules of the pmp-library. If you want to use the visualization module you need to link your target against pmp_vis and its dependencies: stb_image, imgui, glfw, glew, as well as your platform OpenGL library. In this case, however, we recommend to use the project template. See also Quickstart.

# Build Options

## Index Type

By default, the pmp-libray uses 32-bit unsigned integers as internal index type to reference entities. However, if you need to process very large data sets this might not be sufficient. In this case, you can change the index type to be 64-bit by specifying

cmake -DPMP_INDEX_TYPE=64


during build configuration.

## Scalar Type

By default, the pmp-library uses float as Scalar type. In case you require higher floating point precision you can change the Scalar type to double by specifying

cmake -DPMP_SCALAR_TYPE=64


during build configuration.

# Building Bundled JavaScript Applications

In order to build the JavaScript/WebAssembly applications using emscripten, download the SDK from https://github.com/kripken/emscripten and follow the installation instructions.

Next, source the environment setup script:

source <path_to_install_dir>/emsdk_env.sh


Create a build directory, run cmake and build:

mkdir html
cd html
emcmake cmake ..
make


Finally, start a local webserver and open the HTML apps:

python3 -m http.server
<your-browser> localhost:8000


You can also run HTML/WASM apps using emrun mpview.html, but you might have to adjust some browser settings first.