Skip to content

Development

Native Setup (Linux)

Required tools:

Project Dependencies

Required for MQSS development, testing, and documentation generation:

sudo apt install build-essential cmake protobuf-compiler libprotobuf-dev \
  libgtest-dev librabbitmq-dev libboost-chrono-dev libboost-system-dev \
  doxygen graphviz python3 python3-venv

For building the documentation site, install the pinned MkDocs dependencies in a Python virtual environment:

python3 -m venv .venv-docs
. .venv-docs/bin/activate
python -m pip install "mkdocs==1.6.1" "mkdocs-material==9.7.7"

Project Examples

Additional dependencies required by the project examples:

sudo apt install libspdlog-dev libfmt-dev

MQSSCI Dependencies

Additional dependencies required by the MQSSCI toolchain integration:

sudo apt install curl wget ninja-build libbz2-dev libssl-dev libffi-dev libboost-system-dev libboost-graph-dev libz3-dev \
  libncurses-dev libreadline-dev libsqlite3-dev liblzma-dev libzstd-dev

examples/qrm_workflow resolves the following as external CMake dependencies, pulled in automatically via FetchContent (see examples/qrm_workflow/cmake/) rather than as apt packages:

Dependency Repository Pinned Ref Notes
MQSSCI MQSS-Quantum-Compilation-Suite v2.1.0 Compiler passes and pipelines (mqss-ci::mqss-ci); declared in cmake/FindMQSSCI.cmake
QDMI QDMI v1.3.2 Quantum Device Management Interface (qdmi::qdmi); declared in cmake/Findqdmi.cmake
QInfo QInfo develop Device/circuit info utilities; declared in cmake/Findqinfo.cmake
CUDA-Q cuda-quantum 0.15.0 MLIR Quake/CC/QEC dialects consumed by MQSSCI; auto-fetched and built from source on first configure (CUDAQ_AUTO_FETCH, set by FindMQSSCI.cmake)
Catalyst catalyst v0.15.0 MLIR Quantum/QRef/MBQC dialects consumed by MQSSCI; auto-fetched and built from source on first configure (CATALYST_AUTO_FETCH, set by FindMQSSCI.cmake)

CUDA-Q and Catalyst are built from source against this project's LLVM/MLIR on first configure, which can take a long time; subsequent configures reuse the cached build under build/_deps/. Both require LLVM_DIR/MLIR_DIR to already be set (i.e. find_package(MLIR CONFIG) must run before find_package(MQSSCI)).

Build

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release  # or Debug
cmake --build build

Run Tests

ctest --test-dir build

Install

cmake --install build --prefix /tmp/mqss-install

The installation provides:

  • public MQSS headers
  • generated protobuf headers
  • MQSS libraries
  • vendored SimpleAmqpClient runtime library
  • CMake package files for find_package(mqss)

Use Installed Package

A consuming CMake project can use the installed package with:

find_package(mqss REQUIRED)

target_link_libraries(app
  PRIVATE
    mqss::mqss
)

Configure the consumer with:

cmake -S . -B build -DCMAKE_PREFIX_PATH=/tmp/mqss-install
cmake --build build

Build Installed Consumer Example

cmake -S examples/mqss_consumer -B examples/mqss_consumer/build \
  -DCMAKE_PREFIX_PATH=/tmp/mqss-install

cmake --build examples/mqss_consumer/build

./examples/mqss_consumer/build/mqss_consumer

Full Build and Installation Check

The helper script below performs:

  • configure/build
  • unit tests
  • installation
  • external consumer example configure/build/run
scripts/check_install.sh

Optional environment overrides:

CLEAN=1 \
BUILD_TYPE=Debug \
BUILD_DIR=build-debug \
INSTALL_DIR=/tmp/mqss-debug-install \
RUN_RABBITMQ_TESTS=1 \
scripts/check_install.sh

Build and Run QRM Workflow Example

Perform an end-to-end build and execution check:

scripts/check_qrm_workflow.sh

See QRM Workflow Example for details.

Build and Test QOffload Service

Perform an end-to-end build and execution check:

scripts/check_qoffload_service.sh

See QOffload Service for details.

Docker Development Container

Build and enter the MQSS development container:

NO_CACHE=1 scripts/docker_dev.sh

Docker Workflow Environment

Start the RabbitMQ-backed workflow development environment:

scripts/docker_workflow.sh

This command builds the development image if needed, starts RabbitMQ using Docker Compose, and opens a shell in the workflow container.

The workflow container is configured to connect to the RabbitMQ service as:

QRM_AMQP_HOST=rabbitmq

Stop the workflow environment:

DOWN=1 scripts/docker_workflow.sh

Generate Protocol Documentation

scripts/gen_proto_docs.sh

Build Documentation

Generate the Doxygen API documentation and build the complete documentation site:

doxygen Doxyfile
mkdocs build --strict

The generated site is written to site/.

For local development and live preview:

doxygen Doxyfile
mkdocs serve