Source-Based Code Coverage
Source-based code coverage is a code-coverage methodology in which the compiler embeds instrumentation directly into the generated program at compile time. Rather than relying on external instrumentation or post-link rewriting, the compiled binary itself records which executable regions, branches, and source lines were actually executed when the program ran.
How it works
The source-based approach is centered on inserting lightweight counters into the compiled code. When the instrumented program executes, these counters are updated in place and later read back by a companion reporting tool, which correlates the counter values with the original source code to produce coverage reports.
Key characteristics include:
- Compile-time instrumentation: instrumentation is added by the compiler (e.g., Clang) into the produced machine code.
- Runtime data collection: the instrumented binary itself accumulates execution counts during a run.
- Source-level reporting: a dedicated reporting tool (e.g., llvm-cov) converts raw profile data into human-readable coverage reports annotated against the original source.
Implementing tools
The technique is implemented by Clang, which is responsible for inserting the source-based instrumentation, and by llvm-cov, which is the reporting tool that interprets the collected profile data and renders the coverage report.
Interpreting reports
Coverage reports produced via this technique expose per-line, per-branch, and per-region counters tied to source locations. Consumers of these reports refer to the canonical documentation provided by the LLVM project for guidance on how to read the highlighted regions, branch flags, and aggregated counters.
Evidence
A concrete coverage report generated by this pipeline confirms the end-to-end flow: instrumentation inserted by Clang at build time, profile data captured at run time, and a final HTML report rendered by llvm-cov (LLVM version 21.1.8-rust-1.94.0-stable). The report itself links to the LLVM documentation for interpreting the per-line, per-branch, and per-region data it contains.