Installation for Developers

In order to start developing, clone the QCEC repository using

$ git clone --recurse-submodules https://github.com/cda-tum/qcec

Note the --recurse-submodules flag. It is required to also clone all the required submodules. If you happen to forget passing the flag on your initial clone, you can initialize all the submodules by executing git submodule update --init --recursive in the main project directory.

A C++ compiler supporting C++17 and a minimum CMake version of 3.14 is required to build the project.

Note

We noticed some issues when compiling with Microsoft’s MSCV compiler toolchain. If you want to start development on this project under Windows, consider using the clang compiler toolchain. A detailed description of how to set this up can be found here.

Working on the core C++ library

Our projects use CMake as the main build configuration tool. Building a project using CMake is a two-stage process. First, CMake needs to be configured by calling

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release

This tells CMake to search the current directory . (passed via -S) for a CMakeLists.txt file and process it into a directory build (passed via -B). The flag -DCMAKE_BUILD_TYPE=Release tells CMake to configure a Release build (as opposed to, e.g., a Debug build).

After configuring with CMake, the project can be built by calling

$ cmake --build build --config Release

This tries to build the project in the build directory (passed via --build). Some operating systems and developer environments explicitly require a configuration to be set, which is why the --config flag is also passed to the build command. The flag --parallel <NUMBER_OF_THREADS> may be added to trigger a parallel build.

Building the project this way generates

  • the main library libqcec.a (Unix) / qcec.lib (Windows) in the build/src directory

  • a test executable qcec_test containing unit tests in the build/test directory (this requires passing -DBUILD_QCEC_TESTS=ON to CMake during configuration)

  • the Python bindings library pyqcec.<...> in the build/mqt/qcec directory (this requires passing -DBINDINGS=ON to CMake during configuration)

Working on the Python module

The mqt.qcec Python module can be conveniently built locally by calling

(venv) $ pip install --editable .[dev]

The --editable flag ensures that changes in the Python code are instantly available without re-running the command. The [dev] extra makes sure that all dependencies for running the Python tests and building the documentation are available.

Note

When using the zsh shell it might be necessary to add double quotes around the .[dev] part of the command.

Pybind11 is used for providing bindings of the C++ core library to Python (see bindings.cpp). If parts of the C++ code have been changed, the above command has to be run again to make the changes visible in Python.

Running tests

C++ core library

The C++ part of the code base is tested by unit tests using the googletest framework. The corresponding test files can be found in the test directory. In order to build the tests, CMake first has to be configured with the -DBUILD_QCEC_TESTS=ON flag, i.e.,

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DBUILD_QCEC_TESTS=ON

Then, the test executable qcec_test is built in the build/test directory by calling

$ cmake --build build --config Release --target qcec_test

From there, the tests can be started by simply calling

[.../build/test] $ ./qcec_test

Python interface and functionality

The Python part of the code base is tested by unit tests using the pytest framework. The corresponding test files can be found in the test/python directory. To start the tests, simply call

(venv) $ python -m pytest ./test/python

Note

If you haven’t already installed the package with the [dev] extra as demonstrated above, the necessary dependencies for running the Python tests can be installed by calling

(venv) $ pip install --editable .[test]

Building the documentation

Building this documentation locally is as easy as calling

(venv) [.../docs] $ make clean && make html

The resulting HTML documentation (index.html) can be found in the docs/build/html directory.

Note

If you haven’t already installed the package with the [dev] extra as demonstrated above, the necessary dependencies for building the documentation can be installed by calling

(venv) $ pip install --editable .[docs]