Installing from Source#

This document describes the procedure of how to install (and possibly compile) the Constellation framework from source. The source code can be obtained from the Constellation Git repository:

git clone https://gitlab.desy.de/constellation/constellation.git

Constellation has two separate implementations, one in C++ and one in Python. The tabs below discuss the installation procedure for the two versions separately, but installing both in parallel on the same machine is possible and encouraged.

Python Version#

Prerequisites for Python#

The Python version of Constellation requires

  • Python 3.11 or newer

  • The Python venv module

The prerequisites can be installed as follows:

sudo apt install python3 python3-venv

sudo dnf install python3.11
alias python3=python3.11

sudo dnf install python3

brew install python

Setting up a Python Virtual Environment#

python3 -m venv venv
source venv/bin/activate
pip install meson-python meson ninja

Installing the Constellation Package#

pip install --no-build-isolation --editable .

To install optional components of the framework, you can install those by replacing . with .[component]. A recommended installation includes the cli and influx components:

pip install --no-build-isolation --editable ".[cli,influx]"

C++ Version#

Prerequisites for C++#

The C++ version of Constellation requires:

  • Meson 0.61 or newer

  • C++20 capable compiler like GCC 12 or newer and clang 16 or newer

  • C++20 enabled standard library (GCC’s libstdc++ 12 or newer and LLVM’s libc++ 18 or newer)

  • Qt 5 or 6 (optional, required for GUI components; required Qt components: Core, Gui, Widgets, Svg, Charts)

The prerequisites can be installed as follows:

Starting with Ubuntu 24.04 and Debian 12 or newer, the official packages can be used:

sudo apt install meson g++
sudo apt install qt6-base-dev qt6-qtsvg-dev qt6-charts-dev

Ubuntu 22.04 requires a newer version of GCC than installed by default. Version 12 is recommended and available in the regular package repositories:

sudo apt install meson g++-12
sudo apt install qtbase5-dev qt5-qtsvg-dev libqt5charts5-dev
export CXX="g++-12"

Note

Since Ubuntu 22.04 does not offer Qt6, build_gui needs to be set to qt5 (see also Build Options).

Ubuntu 20.04 requires newer versions of GCC and Meson than available from the standard package repositories. They are available in official PPAs:

sudo add-apt-repository ppa:ubuntu-toolchain-r/test
sudo add-apt-repository ppa:ubuntu-support-team/meson
sudo apt update
sudo apt install meson g++-13
sudo apt install qtbase5-dev qt5-qtsvg-dev qt5-qtsvglibqt5charts5-dev
export CXX="g++-13"

Note

Since Ubuntu 20.04 does not offer Qt6, build_gui needs to be set to qt5 (see also Build Options).

Warning

Ubuntu 20.04 is not officially supported.

For Fedora the official packages can be used:

sudo dnf install meson gcc-c++
sudo dnf install qt6-qtbase-devel qt6-qtsvg-devel qt6-qtcharts-devel

AlmaLinux 9 requires the CRB repository for Meson, which can be enabled via:

sudo dnf install epel-release
sudo crb enable

AlmaLinux 9 also requires a newer version of GCC than available by default:

sudo dnf install meson gcc-toolset-14
sudo dnf install qt5-qtbase-devel qt5-qtsvg-devel qt5-qtcharts-devel

To use the latest GCC a terminal session has to be started with the scl command:

scl enable gcc-toolset-14 bash

Note

Since AlmaLinux 9 does not offer Qt6, build_gui needs to be set to qt5 (see also Build Options).

Building on MacOS requires the installation of the XCode Command Line Tools via:

xcode-select --install

For MacOS Sequoia (version 15) or newer, the XCode clang compiler can be used. The Apple clang version needs to be 17.0.0 or newer, which can be checked via:

$(xcode-select -p)/usr/bin/clang --version

Additionally, Meson and Qt from Homebrew are required:

brew install meson qt

For older MacOS versions, the LLVM compiler toolchain from Homebrew is required:

brew install llvm lld

The minimum required LLVM version via Homebrew is 20. In order to use clang from Homebrew, the following environment variables need to be set:

export CXX="$(brew --prefix)/opt/llvm/bin/clang++"
export CXX_LD="lld"
export CC="$(brew --prefix)/opt/llvm/bin/clang"
export CC_LD="lld"
export LDFLAGS="-L$(brew --prefix)/opt/llvm/lib/c++ -L$(brew --prefix)/opt/llvm/lib/unwind -lunwind"

Building & Installing#

meson setup build -Dbuildtype=debugoptimized -Dwerror=false
meson compile -C build

For some use-cases, such as externally built satellites, Constellation needs to be installed explicitly system-wide after compilation. This can be done via:

meson install -C build

Alternatively, the Meson Development Environment can be activated for this purpose using meson devenv -C build. More detailed information can be found in the Meson documentation.

Details on installing Constellation for developing satellites can be found in the Application Developer Guide.

Build Options#

Build options can be set during the setup via

meson setup build -Doption=value

or after the setup via

meson configure build -Doption=value

Relevant build options are:

  • buildtype:
    Build type for the C++ version.
    Possible values are debug, debugoptimized and release.
    Defaults to debug.

  • build_satellites:
    Whether to build any satellite or not.
    Possible values are true and false.
    Defaults to true.

  • build_gui:
    Which Qt version to use for the Graphical User Interface (GUI) library.
    Possible values are none (disables all GUI components), qt5 and qt6.
    Defaults to qt6.

  • cxx_tests:
    Whether or not to build the C++ tests.
    Possible values are auto, enabled and disabled.
    Defaults to auto.

  • cxx_tools:
    Whether or not to build a set of C++ debugging tools.
    Possible values are true and false.
    Defaults to true.

  • memory_allocator:
    Which memory allocator to use (can improve data transmission performance).
    Possible values are auto, jemalloc, mimalloc and system.
    Defaults to auto.