Installing CDPKit

CDPKit can be installed in different ways:

By means of an official binary installer package. This is the best approach for most users. It will provide a full-featured stable CDPKit version and pre-built installers are available for most platforms.
Build and install from source. This is the best option for users who want the latest-and-greatest features and aren’t afraid of compiling C++ code and/or run brand-new software. This is also needed for users who run an operating system version for which no installer has been provided and for users who wish to contribute to the project.
Installation via pip. pip will only install the CDPL Python bindings. This is the best option for users who only want to develop or run Python software that uses CDPL functionality.

Installation via installer package

Installers for macOS (DMG-file, Apple Silicon processors only), Linux x86_64 (self-extracting archive) and Windows 10 (graphical installer based on NSIS) can be downloaded from the Releases page of the CDPKit GitHub repository. These installer packages will provide everything CDPKit has to offer:

Command line tools and GUI applications
CDPL binaries for dynamic linking
CDPL binaries for static linking
CDPL C++ header files
CDPL Python bindings
Python example scripts
Offline CDPKit documentation

Installations of CDPKit are self-contained, i.e., after finishing the installation process no additional software packages have to be installed.

Note

After the installation process the PATH environment variable needs to be edited to include the full path to the Bin folder below the CDPKit installation directory. Furthermore, to enable the use of the CDPL Python bindings, the PYTHONPATH environment variable must include the full path to the corresponding Python subfolder.

Installation from source

Build requirements

Compilation of the CDPKit sources requires a properly set up build environment. This includes a C++ compiler toolchain that supports the C++17 standard, the CMake makefile generator, and the development version of several software libraries. The following table provides a complete list of the CDPKit build requirements and dependencies:

Build requirement	Version	Comment
C++17 compliant compiler 1	-	mandatory
cmake	3.17+	mandatory
Python interpreter	3.6+	mandatory
boost-devel	1.63+	mandatory
boost-python3-devel	1.63+	optional, required for building CDPL Python bindings
python-devel	3.6+	optional, required for building CDPL Python bindings
NumPy	1.17+	optional, recommended to be installed for CDPL Python NumPy-conversion features
Qt5-devel	5.6+	optional, required for building Qt rendering backend and GUI applications
cairo-devel	1.14+	optional, required for building cairo rendering backend
Sphinx	4.5+	optional, required for generating CDPKit documentation pages
sphinx-rtd-theme	1.0.0+	optional, required for generating CDPKit documentation pages
sphinx-inline-tabs	2021.4.11b8+	optional, required for generating CDPKit documentation pages
sphinx-sitemap	2.5.1+	optional, required for generating CDPKit documentation pages
sphinxcontrib-bibtex	2.5.5+	optional, required for generating CDPKit documentation pages
Doxygen	1.8.5+	optional, required for generating C++ and Python API documentation

1: Known to work: gcc V4.8+, Apple Clang V12.0+ , and MSVC V1930+

Build environment setup

Linux

Package managers on modern Linux systems usually provide all listed software packages in the required minimum versions.

macOS

On macOS (Big Sur is the minimum supported version) the recommended way to install everything that is needed for a successful build is to use the Homebrew package manager.

Windows

On Windows (8/10/11) the least error prone way to get started is to set up a MinGW build environment by installing packages from the MSYS2 software distribution. However, the downside heare is that the built CDPL Python bindings will only work with the Python interpreter shipped with MSYS2. In order to make the CDPL Python bindings work with an official Python distribution obtained from https://www.python.org, a build using Microsoft’s Visual C++ compiler (MSVC) toolchain is required.

Recommended sources for the software packages listed above are:

MSVC: https://visualstudio.microsoft.com/vs/features/cplusplus
CMake: https://cmake.org/download
Python: https://www.python.org/downloads/windows
Qt5: https://www.qt.io/download
boost: https://sourceforge.net/projects/boost/files/boost-binaries
cairo: https://github.com/preshing/cairo-windows
Doxygen: https://www.doxygen.nl/download.html

Build system configuration

The configuration and generation of the build system files is performed by the command cmake. In the following <BUILD-DIR> refers to the directory that will contain the CDPKit build ouput and <SOURCE-DIR> refers to the directory hosting the CDPKit source tree. The description of the build steps on Windows depends on whether the build environment is based on MSYS2 (employing the MinGW gcc port as C++ compiler) or utilizes the MSVC toolset.

Linux and macOS

Open a terminal and execute:

$ mkdir <BUILD-DIR>
$ cd <BUILD-DIR>
$ cmake <SOURCE-DIR>

Windows/MinGW

Open a MSYS2 MinGW 64-bit command prompt and execute:

$ mkdir <BUILD-DIR>
$ cd <BUILD-DIR>
$ cmake <SOURCE-DIR> -G "MinGW Makefiles"

Windows/MSVC

Open a x64 Native Tools Command Promp via the Windows start menu and execute:

> mkdir <BUILD-DIR>
> cd <BUILD-DIR>
> cmake <SOURCE-DIR> -DCMAKE_PREFIX_PATH=/path/to/Qt/installation/subdir/msvc<VER>_64 -DCAIRO_LIBRARIES=/path/to/cairo/cairo.lib -DCAIRO_INCLUDE_DIR=/path/to/cairo/include -G "NMake Makefiles"

If cmake is executed as shown above the default build type will be Release. Configuring for a different build type can be achieved via the argument -DCMAKE_BUILD_TYPE=<BUILD-TYPE> on the cmake command line. Possible values of <BUILD-TYPE> are:

Debug
Releasex
RelWithDebInfo
MinSizeRel

Compilation

If the build system configuration step proceeded without errors

Linux and macOS

$ make

Windows/MinGW

$ mingw32-make

Windows/MSVC

> nmake

will start the build process.

Build of HTML documentation

This step is optional and needs to be carried out only if a build of offline CDPKit documentation pages is required or desired. If the documentation should be installed together with the built binaries then this step must be executed before carrying out the installation procedure (see next section). Mandatory for a successful build is the availability of the Sphinx documentation generator plus the listed extensions (see Build requirements). Furthermore, for generating CDPL C++ and Python API-documentation (optional), the program Doxygen has to be installed.

Hint

Sphinx and its extensions can be installed via the Python package installer pip.

If all prerequisites are fulfilled

Linux and macOS

$ make doc

Windows/MinGW

$ mingw32-make doc

Windows/MSVC

> nmake doc

should successfully build the CDPKit documentation pages which can then be found in <BUILD-DIR>/Doc/html.

Installation of the generated binaries

If the previous steps proceeded without errors

Linux and macOS

$  make install

Windows/MinGW

$ mingw32-make install

Windows/MSVC

> nmake install

will install CDPKit in a platform specific default directory (Linux: /opt, macOS: /Users/Shared, and Windows: C:\Program Files). A different installation location can be specified by the argument -DCMAKE_INSTALL_PREFIX=<INSTALL-DIR> on the cmake command line (see Build system configuration).

Installation using pip

Note

pip will only install the CDPL Python bindings. This is the recommended option for users who only want to develop or run Python software that uses CDPL functionality.

Installation of the latest binary release

The latest binary release of the CDPL Python bindings deposited on PyPI can be installed by issuing the following command in a terminal session:

$ pip install cdpkit

If no wheel file for the platform (defined by OS, processor architecture and Python version) the command was executed on is available, an on-the-fly build of the CDPKit sources is attempted. This will only proceed without errors if a proper build environment has been set up (see next section).

Installation via a build of the sources

For a successful build of the CDPL Python bindings the information provided in section Installation from source applies also here. However, since a full-featured CDPKit build is not required the list of requirements is a bit shorter:

Build requirement	Version	Comment
C++17 compliant compiler	-	mandatory
Python interpreter	3.6+	mandatory, implicitly fulfilled
boost-devel	1.63+	mandatory
boost-python3-devel	1.63+	mandatary
python-devel	3.6+	mandatory
NumPy	1.17+	optional, will be installed automatically (listed as pip installation requirement)
cairo-devel	1.14+	optional, required for building cairo rendering backend

Option 1: Build the CDPKit sources deposited on PyPI

This will be done automatically if no pre-built binary package is available (see previous section) or can be enforced by adding the argument –no-binary :all::

$ pip install cpkit --no-binary :all:

Option 2: Installation of the current development version by specifying the GitHub repository URL

$ pip install git+https://github.com/molinfo-vienna/CDPKit.git

Option 3: Installation under specification of a local directory containing the CDPKit sources

Enter (cd) the CDPKit source code folder and then from within the folder run

$ pip install .