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:
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.
Open a terminal and execute:
$ mkdir <BUILD-DIR>
$ cd <BUILD-DIR>
$ cmake <SOURCE-DIR>
Open a MSYS2 MinGW 64-bit command prompt and execute:
$ mkdir <BUILD-DIR>
$ cd <BUILD-DIR>
$ cmake <SOURCE-DIR> -G "MinGW Makefiles"
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
$ make
$ mingw32-make
> 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
$ make doc
$ mingw32-make doc
> 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
$ make install
$ mingw32-make install
> 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 .