Installing CDPKit ================= .. index:: Installation CDPKit can be installed in different ways: - :ref:`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. - :ref:`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. - :ref:`Installation via pip `. :program:`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: 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 :file:`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 :file:`Python` subfolder. .. _installation_from_source: 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 [#]_ \- 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 ============================= ============= ================================================================================ .. [#] Known to work: :program:`gcc` V4.8+, :program:`Apple Clang` V12.0+ , and :program:`MSVC` V1930+ Build environment setup ^^^^^^^^^^^^^^^^^^^^^^^ .. rubric:: Linux Package managers on modern Linux systems usually provide all listed software packages in the required minimum versions. .. rubric:: 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. .. rubric:: Windows On Windows (8/10/11) the least error prone way to get started is to set up a :program:`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 (:program:`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 :command:`cmake`. In the following :file:`` refers to the directory that will contain the CDPKit build ouput and :file:`` 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 :program:`MinGW gcc` port as C++ compiler) or utilizes the :program:`MSVC` toolset. .. tab:: Linux and macOS Open a terminal and execute: .. code-block:: shell $ mkdir $ cd $ cmake .. tab:: Windows/MinGW Open a `MSYS2 MinGW 64-bit `_ command prompt and execute: .. code-block:: shell $ mkdir $ cd $ cmake -G "MinGW Makefiles" .. tab:: Windows/MSVC Open a `x64 Native Tools Command Promp `_ via the Windows start menu and execute: .. code-block:: shell > mkdir > cd > cmake -DCMAKE_PREFIX_PATH=/path/to/Qt/installation/subdir/msvc_64 -DCAIRO_LIBRARIES=/path/to/cairo/cairo.lib -DCAIRO_INCLUDE_DIR=/path/to/cairo/include -G "NMake Makefiles" If :command:`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=* on the :command:`cmake` command line. Possible values of ```` are: - Debug - Releasex - RelWithDebInfo - MinSizeRel Compilation ^^^^^^^^^^^ If the build system configuration step proceeded without errors .. tab:: Linux and macOS .. code-block:: shell $ make .. tab:: Windows/MinGW .. code-block:: shell $ mingw32-make .. tab:: Windows/MSVC .. code-block:: shell > 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 :program:`pip`. If all prerequisites are fulfilled .. tab:: Linux and macOS .. code-block:: shell $ make doc .. tab:: Windows/MinGW .. code-block:: shell $ mingw32-make doc .. tab:: Windows/MSVC .. code-block:: shell > nmake doc should successfully build the CDPKit documentation pages which can then be found in :file:`/Doc/html`. Installation of the generated binaries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If the previous steps proceeded without errors .. tab:: Linux and macOS .. code-block:: shell $ make install .. tab:: Windows/MinGW .. code-block:: shell $ mingw32-make install .. tab:: Windows/MSVC .. code-block:: shell > nmake install will install CDPKit in a platform specific default directory (Linux: :file:`/opt`, macOS: :file:`/Users/Shared`, and Windows: :file:`C:\\Program Files`). A different installation location can be specified by the argument *-DCMAKE_INSTALL_PREFIX=* on the :program:`cmake` command line (see `Build system configuration`_). .. index:: pip, PyPI .. _installation_using_pip: Installation using :program:`pip` --------------------------------- .. note:: :program:`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: .. code-block:: shell $ 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 :program:`pip` installation requirement) cairo-devel 1.14+ optional, required for building cairo rendering backend ============================= ============= ================================================================================ .. rubric:: 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:*: .. code-block:: shell $ pip install cpkit --no-binary :all: .. rubric:: Option 2: Installation of the current development version by specifying the GitHub repository URL .. code-block:: shell $ pip install git+https://github.com/molinfo-vienna/CDPKit.git .. rubric:: Option 3: Installation under specification of a local directory containing the CDPKit sources Enter (:command:`cd`) the CDPKit source code folder and then from within the folder run .. code-block:: shell $ pip install .