CONTRIBUTING.md

Contributing to Reactor Debugger

Development Environment

• Compiler: MSVC 2022 (Windows), GCC 11+ or Clang 14+ (Linux/macOS)
• Build System: CMake 3.20+
• Language: C++20
• Platform: Windows (primary), Linux/macOS (secondary)

Building

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure

Running Sanitizers (Linux/macOS)

cmake -S . -B build-san -DCMAKE_BUILD_TYPE=Debug -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined"
cmake --build build-san
./build-san/reactor_tests

Project Structure

include/reactor/
├── common/      # Core utilities (handles, versions, time, cacheline)
├── graph/       # Dependency graph (CSR format)
├── lockfree/    # Lock-free data structures (rings, MPMC queue)
├── memory/      # Allocators (arena, frame, pool)
├── proto/       # Wire protocol (framing, varint encoding)
├── reactive/    # Runtime system (signals, effects, selectors)
├── trace/       # Instrumentation and binary trace format
├── format/      # Trace archive format (header, chunks, CRC, footer)
├── replay/      # Replay engine (deterministic reconstruction)
├── query/       # Query engine (search, reverse lookup, aggregation)
└── ui/          # Desktop UI (Windows-only, Win32 GUI)

src/
├── runtime.cpp      # Reactive runtime implementation
├── test_framework.cpp   # Test runner implementation
├── trace_archive.cpp    # Trace archive serialization
└── ui/ui_main.cpp   # Desktop UI application

tests/unit/        # Unit tests organized by chapter
bench/             # Microbenchmarks
docs/              # Design documents and spec mapping