Contributing

This guide covers everything you need to contribute to the ADA codebase.

Architecture Overview

ADA is a multi-language project with these core components:

Build System

Cargo is the single build driver. Never run CMake, xcodebuild, or pytest directly.

cargo build --release     # Build everything
cargo test --all          # Run all tests

C/C++ components (tracer_backend, runtime) are built via CMake, orchestrated by Cargo’s build.rs scripts. The CMake integration is transparent — Cargo handles it automatically.

Development Setup

Prerequisites

• macOS with Xcode Command Line Tools
• Rust toolchain (stable)
• Apple Developer Certificate ($99/year) — required for code signing

First-Time Setup

# 1. Initialize Frida SDK (required for tracer_backend)
./utils/init_third_parties.sh

# 2. Initialize media tools (ffmpeg, whisper-cli)
./utils/init_media_tools.sh

# 3. Build everything
cargo build --release

# 4. Run all tests
cargo test --all

# 5. Run coverage
./utils/run_coverage.sh

clangd Setup (C/C++ IDE Support)

After building, generate the compile commands database for clangd:

./utils/update_compile_commands.sh

This merges compile_commands.json from all C/C++ components into a single file at the project root.

Test Conventions

Naming

All tests use behavioral naming:

<unit>__<condition>__then_<expected>

Examples:

• ring_buffer__overflow__then_wraps_around
• index_reader__invalid_magic__then_error
• session_reader__empty_threads__then_time_range_zero

Frameworks

• Rust: cargo test (standard)
• C/C++: Google Test (orchestrated via Cargo)
• Coverage: diff-cover for enforcement, lcov/genhtml for reports

Integration Test Naming

Integration tests follow a dimensional naming pattern:

integration_<platform>_<org>_<toolchain>_<lang>_<framework>_<fixture>

For example: integration_macos_llvm_org_clang_c_cf_cli_input_box

Adding C/C++ Tests

When adding C/C++ tests, remember two places:

1. CMakeLists.txt — add add_executable(test_xyz ...)
2. build.rs — add ("build/test_xyz", "test/test_xyz") mapping

Missing step 2 means the test won’t be accessible via Cargo.

Cross-Language Boundaries

ADA uses specific patterns for cross-language interop:

• C++ ↔ Rust: Opaque handles with C API. C++ owns concrete types; Rust sees only opaque pointers.
• Shared memory: Plain memory with atomic operations. No complex types across FFI boundaries. Cache-line aligned for performance.

Interface-Driven Development

ADA follows an interface-first workflow:

1. Define interfaces — compilable interface definitions first
2. Skeleton implementations — minimal stubs that compile and link
3. Triple-check protocol — interfaces compile in isolation, skeletons link with tests, FFI boundaries validate
4. TDD implementation — write failing tests, then implement until tests pass

Code Style

• Component directories use snake_case
• Public headers: #include <tracer_backend/module/header.h>
• Private headers: #include "header_private.h" (within module)
• Never commit binaries to git
• All build outputs go to target/

Iteration Workflow

Each development iteration follows this TDD-based workflow:

1. Plan — Tech Design, Test Plan, Backlogs
2. Prepare — Minimal compilable skeletons
3. Specify — Write failing unit tests
4. Build — Implement until tests pass
5. Verify — Module integration tests
6. Validate — System integration tests
7. Accept — User story validation
8. Prove — Performance benchmarks
9. Close — 100% coverage, docs updated

What Not to Build

ADA focuses engineering effort on core tracing innovation. For everything else, use existing tools:

• Coverage → diff-cover, lcov, genhtml
• Testing → Google Test, cargo test
• Linting → clippy, clang-format
• CI/CD → GitHub Actions

Decision rule: If it’s not part of the ADA system shipped to the user, prefer an existing solution.