# crabgrind AGENTS.md
## Build Requirements
- **Valgrind headers required**: The build script (`build.rs`) searches for Valgrind headers in this order:
1. `VALGRIND_INCLUDE` environment variable
2. `pkg-config` query for `valgrind`
3. Compiler default include paths
- **Runtime panic if missing**: If headers aren't found, the crate compiles but requests panic at runtime
- **Feature-gated**: `valgrind` feature (enabled by default) controls native compilation; without it, requests become no-ops
## Developer Commands
- **Test all targets**: `just cross test --all-targets` (requires `just` installed)
- **Cross-compile for all targets**: `scripts/cross_all.sh build` or `just cross build --all-targets`
- **Current target only**: `cargo test` / `cargo build`
- **Generate docs**: `just docs` (requires `just`)
- **Update bindings**: `just gen` (requires `just`)
## Architecture
- **entrypoint**: `src/lib.rs` re-exports Request modules under `crabgrind::{valgrind, callgrind, memcheck, drd, dhat, helgrind, cachegrind}`
- **build.rs**: Generates FFI bindings via `bindgen` from `valgrind/wrapper.h`, compiles `valgrind/native.c`
- **No external dependencies without `valgrind` feature**: `default-features = false` yields pure Rust stubs
## Testing
- **Integration tests**: `tests/{valgrind,callgrind,memcheck,drd,dhat,helgrind,cachegrind,helgrind}.rs`
- **Test runner macro**: Use `valgrind! { tool => test_fn, output_fn }` to execute tests under Valgrind
- **Common utilities**: `tests/common/mod.rs` provides harness macros, FFI helpers (`cstr!`, `as_str!`), and test fixtures (`oob_read_heap`, `leak`, `race_unsafe`)
- **Run tests under Valgrind**: `cargo test` — tests auto-detect when running under Valgrind via `TEST_RUNNER` env var
## Code Style
- **MSRV**: 1.64
- **Formatting**: `rustfmt` with Two-space version, `use_small_heuristics = "Max"`, `imports_granularity = "Module"`, `group_imports = "StdExternalCrate"`
- **Lints**: `unsafe_op_in_unsafe_fn = "warn"`, `missing_errors_doc = "deny"`, `pedantic = "warn"` with priority -1
- **doc comments**: Code examples in `doc/*.md` files, merged into docs via `scripts/merge_docs.sh`
## Cross-Compilation
- **Targets**: x86_64, i686, s390x, aarch64, armv7, riscv64gc, powerpc64, powerpc64le, powerpc
- **Image base**: `ghcr.io/cross-rs/{target}:main`
- **QEMU runner**: All cross targets use `qemu-system` runner in `Cross.toml`
- **Pre-build installs**: `pkg-config valgrind:$CROSS_DEB_ARCH valgrind.dbg:$CROSS_DEB_ARCH`
## Important Constraints
- **no_std by design**: Works in bare-metal environments
- **Runtime version checking**: Compiles against headers at build time; mismatches with runtime Valgrind panic immediately with version info
- **Graceful degradation**: Without Valgrind, client requests are harmless machine code with negligible overhead
- **Feature `opt-out` removed**: Use `default-features = false` instead (v0.3+)