Skip to content

AGENTS.md

Latest commit

 

History

History
95 lines (70 loc) · 3.91 KB

AGENTS.md

File metadata and controls

95 lines (70 loc) · 3.91 KB

MQT Debugger

C++

  • Configure: cmake -S . -B build_cpp -DCMAKE_BUILD_TYPE=Release
  • Build: cmake --build build_cpp --config Release
  • Test: ctest --test-dir build_cpp -C Release
  • Single test binary: ./build_cpp/test/path/to/binary
  • For debug builds, replace Release with Debug.

Python

  • Set up build and test dependencies: uv sync --inexact --only-group build --only-group test
  • Install package without build isolation (fast rebuilds): uv sync --inexact --no-dev --no-build-isolation-package mqt-debugger
  • Run tests: uv run --no-sync pytest
  • Nox test shortcuts: uvx nox -s tests, uvx nox -s minimums
  • Python 3.14 variants: uvx nox -s tests-3.14, uvx nox -s minimums-3.14

Documentation

  • Sources: docs/
  • Build docs locally: uvx nox --non-interactive -s docs
  • Link check: uvx nox -s docs -- -b linkcheck

Tech Stack

General

  • prek for pre-commit hooks

C++

  • Targets Linux (glibc 2.28+), macOS (11.0+), and Windows on x86_64 and arm64 architectures
  • C++20
  • CMake 3.24+
  • FetchContent for dependency management (configured in cmake/ExternalDependencies.cmake)
  • clang-format and clang-tidy for formatting/linting (see .clang-format and .clang-tidy)
  • GoogleTest for unit tests (located in test/)

Python

  • Python 3.10+
  • Stable ABI wheels for 3.12+; free-threading support for 3.14+
  • scikit-build-core as build backend
  • nanobind for bindings
  • uv for installation, packaging, and tooling
  • ruff for formatting/linting (configured in pyproject.toml)
  • ty for type checking
  • pytest for unit tests (located in test/python/)
  • nox for task orchestration (tests, linting, docs)

Documentation

  • sphinx
  • MyST (Markdown)
  • Furo theme
  • breathe for C++ API docs

Development Guidelines

General

  • MUST run uvx nox -s lint after every batch of changes. This runs the full prek hook set from .pre-commit-config.yaml (including ruff, typos, ty, formatting, and metadata checks). All hooks must pass before submitting.
  • MUST add or update tests for every code change, even if not explicitly requested.
  • MUST follow existing code style by checking neighboring files for patterns.
  • MUST include a commit footer attribution in the form Assisted-by: [Model Name] via [Tool Name] (example: Assisted-by: Claude Sonnet 4.6 via GitHub Copilot) if AI tools are used to prepare a commit.
  • NEVER modify files that start with "This file has been generated from an external template. Please do not modify it directly." These files are managed by the MQT templates action and changes will be overwritten.
  • PREFER running targeted tests over the full test suite during development.

C++

  • MUST use Doxygen-style comments.
  • MUST use #pragma once for header guards.
  • MUST regenerate stubs via uvx nox -s stubs when files in bindings/ are added or modified.
  • NEVER edit .pyi files in python/mqt/debugger/ manually; they are auto-generated by nanobind stubgen.
  • PREFER C++20 STL features over custom implementations.

Python

  • MUST use Google-style docstrings
  • PREFER running a single Python version over the full test suite during development.
  • PREFER fixing reported warnings over suppressing them (e.g., with # noqa comments for ruff); only add ignore rules when necessary and document why.
  • PREFER fixing typing issues reported by ty before adding suppression comments (# ty: ignore[code]); suppressions are sometimes necessary for incompletely typed libraries (e.g., Qiskit).

Self-Review Checklist

  • Did uvx nox -s lint pass without errors?
  • Are all changes covered by at least one automated test?
  • Were Python stubs regenerated via uvx nox -s stubs if bindings were modified?