Two Backends, One Test Suite

The whole plan rests on one property of this codebase, which I checked before writing anything else: every test in ObjectUtilsTests constructs its object through a factory function and asserts only through an abstract interface. ElfFileImpl lives in an anonymous namespace; no test can see it. That means the existing 659-line ElfFileTest.cpp is already an implementation-independent conformance suite, and a Rust implementation can be dropped behind CreateElfFile() and judged by it without editing a single test.

The mechanism: one factory, three backends

The obvious way to do this is to build a second copy of each test target linked against the Rust library. It works, but it only proves that both implementations pass the same assertions — not that they produce the same answers. Two implementations can both satisfy EXPECT_EQ(symbols.size(), 4) and still disagree about every address.

So instead: keep one factory, and give it a third mode that runs both and compares.

Three small things make this work, and none of them touches a test:

1. Split the headers into their own target. ObjectUtilsInterface carries include/ObjectUtils/*.h and nothing else, so the Rust shim can implement ElfFile without depending on the LLVM implementation. Pure BUILD refactor, no source change.
2. Rename the existing factory to CreateElfFileCpp() in an internal header, and add a ~60-line Backend.cpp whose CreateElfFile() dispatches. The public signature in include/ObjectUtils/ElfFile.h does not change, so all 16 dependents keep compiling untouched.
3. Default to cpp. An unset variable means today's behaviour, exactly. Nothing in production changes until a phase is finished and the default is flipped deliberately.

Four verification gates

Each is cheap to run, runs in CI, and catches a different class of mistake. A phase is not done until all four are green.

Where the Rust lives

A new top-level rust/ workspace, deliberately separate from src/OrbitLiveViewer. Two reasons: the symbol parsers should not share a lockfile with a tokio-and-wgpu dependency tree, and keeping the new work in one directory is what makes the side-by-side comparison legible.

rust/
├── Cargo.toml            workspace root; resolved by crate_universe as @orbit_crates
├── Cargo.lock
├── rust-toolchain.toml    pinned; independent of OrbitLiveViewer's 1.88
├── BUILD.bazel            rust_library / rust_test / rust_static_library per crate
├── README.md              what lives here, and the backend switch
│
├── crates/
│   ├── orbit-maps/          Phase 1 — /proc/pid/maps parsing
│   ├── orbit-object/        Phase 2 — ELF, COFF, PDB; object · gimli · addr2line
│   ├── orbit-demangle/      Phase 2 — Itanium + MSVC demangling
│   └── orbit-perf-merge/    Phase 3 — ordered stream merge, thread state, uprobe maps
│
├── ffi/                   thin #[no_mangle] extern "C" layers, one per crate
│   ├── orbit-maps-ffi/
│   ├── orbit-object-ffi/
│   └── orbit-perf-merge-ffi/
│       └── include/       the .h each one exports, hand-written like pyspy_ffi.h
│
├── shims/                 C++ that implements Orbit's existing interfaces over the FFI
│   ├── ModuleUtilsRust/
│   └── ObjectUtilsRust/   RustElfFile, RustCoffFile, ComparingElfFile
│
└── tools/
    ├── symbol_dump/       gate 2 — dumps ModuleSymbols as text proto
    └── ab_bench/          gate 4 — same binary, two backends, wall time + peak RSS

The C++ shims live under rust/ rather than beside the module they serve. That is slightly unusual, and it is the right trade here: it keeps src/ObjectUtils at one new file (Backend.cpp) and one changed BUILD.bazel, so git diff on the C++ tree stays readable for the whole port.

Phase 0 — scaffolding

No behaviour change, no Rust logic. This phase exists so that Phase 1 is a single small commit rather than a single large one.

• rust/ workspace, rust-toolchain.toml, @orbit_crates wired into MODULE.bazel next to the two that already exist.
• A orbit_dual_backend_test() Starlark macro in bazel/: given a cc_test's attributes and a backend variable name, it emits the three targets so no BUILD file repeats itself three times.
• A no-op Rust crate with one FFI function and one rust_test, linked into a throwaway cc_test, to prove the toolchain end to end before any real code depends on it.
• CI: add the new targets to .github/workflows/build-and-test.yml. They should be gating from the first commit — a non-gating conformance suite is not a gate.

Phase 1 — the 73-line pilot

orbit_module_utils::ParseMaps is the smallest real thing in the tree that is worth porting, and it is close to a perfect first target:

// src/ModuleUtils/include/ModuleUtils/ReadLinuxMaps.h
[[nodiscard]] std::vector<LinuxMemoryMapping> ParseMaps(std::string_view proc_pid_maps_content);

A pure function. Text in, five integers and a string out, per row. No I/O, no allocation policy to match, no error type to reproduce — it cannot fail, it just returns fewer rows. 73 lines of implementation, 89 lines of test, four test cases. If the machinery from Phase 0 works, this lands in a day; if it doesn't, it fails cheaply and visibly.

It is also genuinely on the hot path — ReadModules parses the whole maps file for every process listed, and the process list is polled — so it gives gate 4 something real to measure on the first try.

FFI shape: one call in, one flat buffer out. Rust returns a count plus a pointer to an array of { start, end, perms, offset, inode, path_offset, path_len } and a separate string blob; the shim walks it once building std::vector<LinuxMemoryMapping>, then frees. No per-row allocation across the boundary, no ownership subtleties, and it is the same pattern every later crate will use.

Phase 2 — ObjectUtils, and deleting LLVM

This is the phase with the payoff. I checked the dependency graph specifically: //bazel/deps:llvm has exactly one dependent in the entire tree, and it is //src/ObjectUtils. There is one other LLVM include anywhere — llvm/Demangle/Demangle.h in CaptureClient/CaptureEventProcessor.cpp, which does not even declare the dependency and picks it up transitively.

Sub-stages, and the tests each one lights up

Each row is a mergeable commit. :ObjectUtilsTestsRust and :ObjectUtilsTestsBoth stay green throughout, because everything not yet ported still delegates to C++.

Phase 3 — the pure-logic half of LinuxTracing

Seven classes in src/LinuxTracing do no I/O, open no file descriptors, and touch no kernel interface. They are algorithms with unusually good test coverage — 1,355 lines of implementation against 3,053 lines of test, a ratio of better than two to one.

The FFI here is different in kind from Phase 2, and worth thinking about before starting rather than during. These classes sit on the hot path and traffic in PerfEvent, a large C++ variant. Copying it across a boundary per event would swamp any gain.

The shape that works: the Rust side never sees a PerfEvent. It owns only the ordering keys — (timestamp, stream_id, u64 handle) — and the C++ side keeps the events in a slab, passing indices. PerfEventQueue becomes a Rust data structure over three integers per element, which is what it actually is; the payload never moves. Same for the state managers, which key on (tid, timestamp, state).

This phase is also where gate 4 earns its keep, because it is the one place where a Rust port could plausibly be slower — an FFI call per event is not free, and the batching has to be designed rather than discovered.

The endgame — phases 4 to 8, to full Rust

Ordering rationale: the collector goes first because it is the only phase that pays a debt already on the books (the toll), and because its wire format is a prerequisite for Phase 7. The unwinder goes second because it unblocks the two welded classes and because a shipping precedent exists — samply is an all-Rust Linux profiler built on framehop, so Phase 5 is engineering, not research. Phases 6 and 7 have no ordering constraint between them. Phase 8 is last by construction: the C++ tests are the parity oracle, and translating them earlier would destroy the guarantee they exist to provide.

Phase 4 milestones, each with its own differential

1. 4a — record layouts. The packed ring-buffer record structs in a orbit-perf-records crate, with a cross-language layout parity test: a C++ test compares sizeof/offsetof of every struct in PerfEventRecords.h against the sizes the Rust crate exports. Layout is the spec for a wire parser; this is the cheapest differential in the whole plan.
2. 4b — the reader. Ring-buffer byte streams parsed by both sides: identical raw bytes in, identical parsed records out.
3. 4c — the loop. perf_event_open, the mmap ring buffers, and the TracerImpl event loop in Rust, calling the Phase 3 crates natively.
4. 4d — whole-capture differential. C++ tracer and Rust tracer run against the same workload; event streams compared modulo the noise a real kernel injects. This is gate 2 scaled up from symbols to captures.

How each goal gets measured

Record all four at every phase boundary, in the commit. A port that cannot show its numbers is indistinguishable from a rewrite that felt good.

The log, and what counts as proof

Every phase is written up in docs/blog/ as it happens. The posts are not a summary written afterwards — they are the record, and the discipline they impose on the work is the point: a phase is not finished until its numbers are reproducible by someone else.

Four rules, chosen because each one is a way the write-up could otherwise become worthless:

1. No claim without a committed number. Every figure a post cites comes from a script in scripts/ whose output is checked in under docs/blog/metrics/. A reader can re-run it and disagree.
2. The C++ test files are never edited. They are the specification. A port that adjusts its own exam has not passed anything — and this is the single easiest corner to cut, because a failing assertion always looks like it might be the test's fault.
3. Numbers that get worse get reported. A strangler port makes the tree bigger before it makes it smaller. Hiding that would make the good numbers worth less, and the first post already reports a dependency count going up by 56 and a module gaining 137 lines.
4. Every hurdle is written down, including the ones that are self-inflicted. Post 01 records eight, of which two were bugs in the new code and one was a bug in a new test.

The two instruments

The baseline snapshot was taken before any Rust existed, on the commit the branch was cut from. That is what makes every later delta meaningful, and it is the one measurement that cannot be retaken.

Post index

What can go wrong

object and gimli are not LLVM. They are excellent and they are what the Firefox profiler and Sentry run on, but they are not bug-for-bug identical. The likely friction points are already named by the test suite: CompressedDebugInfo (the Bazel port had to patch LLVM just to turn zlib on for SHF_COMPRESSED), LineInfoInlining (inlined frames in DWARF line tables), and DWARF 5 forms. Gate 2 over a real corpus is how these surface early rather than in a user's capture.

Error strings are load-bearing. Eight assertions match on exact Orbit error text. That is a small, bounded requirement, but it is easy to forget until CI fails — and easier still to "fix" by editing the test, which would quietly destroy the value of gate 1. The rule: the test file is never edited during a port. If a test seems wrong, that is a separate commit, made against the C++ backend, before the port touches it.

both mode has a cost. Running two implementations on every call roughly doubles the work in that suite. That is fine for a test target and would not be fine anywhere near production, so the mode must be reachable only via the environment variable and never become a default.

The PDB stage may not land. Covered above. If pdb cannot reproduce PdbFileLlvm, LLVM survives for one library and the build-time win mostly evaporates while the correctness and dependency wins remain. Worth deciding in advance whether that outcome is acceptable, because it changes what "finished" means for Phase 2.

The C++ never gets deleted. The failure mode of a strangler is that both implementations live forever and every change has to be made twice. The countermeasure is the delegation counter: it is a number, it should only ever go down, and when it reaches zero the deletion commit is already written.

The first pull request

Scoped so it either works or fails visibly, in about a day, with no Rust logic in it at all beyond a parser that four existing tests already specify.

If that PR is green in all three modes and the benchmark does not regress, everything after it is the same moves at larger scale. If it isn't, the problem is in the machinery rather than in 73 lines of maps parsing, and it is worth finding out there.

Say the word and I'll start on it. My suggestion is to do PR 1 exactly as scoped — resist adding ObjectUtils to it, because the point of PR 1 is to be small enough that when something breaks it is obvious which of the eight items broke it.