docs(install): add scripts/install-dev.sh + Building from source guide

[christophergeyer]

Summary

pip install -e . / uv pip install -e . only builds the artifact-hash-py pyo3 extension — the tracer binaries (roar-tracer*, roard, roar-proxy) live in separate cargo crates outside the maturin manifest and don't get built. The PyPI wheel bundles them under roar/bin/; an editable source install ends up silently missing them and roar run fails with "No tracer binary found" the first time you try it.

This was nowhere in the README. The only way to discover it was install → run → preflight fail → roar tracer status → infer the missing binaries → find the cargo build commands somewhere.

Fix

scripts/install-dev.sh — one-shot dev install:

1. pip install -e ".[dev]" (preferring uv when available)
2. cargo build --release for the per-platform tracer set:
   • Linux: roar-tracer + roar-tracer-preload + roar-tracer-ebpf + roar-proxy
   • macOS: roar-tracer-preload + roar-proxy
3. Stage the built binaries (and the preload .so/.dylib) into roar/bin/ so the editable install finds them at runtime
4. Smoke-test with roar tracer status

Idempotent (cargo build is incremental, pip install -e no-ops on rerun) and degrades gracefully when bpf-linker is missing — just skips the eBPF build with a warning that names the install commands. The other tracers still work.

README — new "Building from source" section under Development that documents both the script and the manual steps it runs (so the magic isn't opaque), plus the bpf-linker + Rust nightly toolchain prereqs for eBPF on Linux. The existing "Development Installation" block points at the script first.

After-fix output

$ bash scripts/install-dev.sh

▶ Installing Python package (editable, with dev extras)
  ✓ uv pip install -e .[dev]

▶ Building tracer crates: roar-tracer roar-tracer-preload roar-tracer-ebpf roar-proxy
    Finished `release` profile [optimized] target(s) in 0.20s
  ✓ cargo build complete

▶ Staging binaries into /home/ubuntu/roar/roar/bin
  ✓ roar-tracer
  ✓ roar-tracer-preload
  ✓ roar-tracer-ebpf
  ✓ roard
  ✓ roar-proxy
  ✓ libroar_tracer_preload.so

▶ Smoke-testing the install
  ✓ roar CLI is on PATH

✓ Dev install complete. Try: roar run python your_script.py

Test plan

• Ran bash scripts/install-dev.sh from a clean roar/bin/; all 5 binaries + preload .so produced (Linux aarch64)
• Re-ran (idempotency check): clean
• shellcheck scripts/install-dev.sh: clean
• Existing pytest unit suite still green (no Python code changed; sanity-only): 1387 passed, 3 skipped
• ruff check . / ruff format --check: clean

Stacks on #86.

🤖 Generated with Claude Code