Skip to content

AGENTS.md

Latest commit

 

History

History
100 lines (75 loc) · 4.37 KB

AGENTS.md

File metadata and controls

100 lines (75 loc) · 4.37 KB

MQT Core

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-core
  • 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 MLIR docs: cmake --build build_cpp --target mlir-doc --config Release
  • 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)
  • LLVM 22.1+ for building MLIR code
  • GoogleTest for unit tests (located in test/ and mlir/unittests/)

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 update CHANGELOG.md and UPGRADING.md when changes are user-facing, breaking, or otherwise noteworthy.
  • 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/core/ manually; they are auto-generated by nanobind stubgen.
  • PREFER C++20 STL features over custom implementations.
  • PREFER LLVM data structures and methods in mlir/ (llvm::SmallVector, llvm::function_ref, etc.) over the STL.

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?
  • Are CHANGELOG.md and UPGRADING.md updated when changes are user-facing, breaking, or otherwise noteworthy?