Code Coverage - The LLVM C Library
Hide navigation sidebar Hide table of contents sidebar Back to top Edit this page Toggle table of contents sidebar Code Coverage # Code coverage is a software testing metric that measures the proportion of source code executed while running an automated test suite. It provides insight into test thoroughness by identifying untested functions, dead code paths, and unexercised conditional branches across library entrypoints and internal utilities.
LLVM-libc supports Modified Condition / Decision Coverage (MC/DC). MC/DC evaluates compound boolean decisions composed of multiple sub-conditions (such as if (A && (B || C)) ). Under MC/DC criteria, each individual boolean condition must: Evaluate to both true and false across the test suite. Demonstrate that it can independently affect the outcome of the overall decision while other conditions remain fixed. This provides rigorous structural verification for safety-critical algorithms without requiring exhaustive testing of all 2 n condition permutations.
Continuous Profiling Architecture # LLVM-libc uses Clang’s continuous profiling mode ( -fprofile-continuous ) to record execution metrics directly into memory-mapped profile files during test execution. Compiler Counter Relocation # When compiled with -fprofile-continuous , Clang configures the LLVM code generator ( -mllvm -runtime-counter-relocation=true ) so that execution counter increments reference a dynamic base pointer ( *(bias + &counter) += 1 ).
Each branch and basic block counter dynamically resolves to an address within a dedicated profile buffer mapped at program startup. Runtime Memory Mapping # During binary initialization, the profiling runtime ( libclang_rt.profile ) resolves the target .profraw file and maps the execution counter section into process memory using mmap with MAP_SHARED . The runtime sets the global bias pointer to this mapped region, routing live counter increments directly into the file-backed buffer.
Kernel Page-Cache Synchronization # Execution counts are written directly to shared memory-mapped pages and synchronized by the operating system kernel’s page cache. Subprocesses created via fork() share the same underlying memory mapping, committing statements executed across parent and child processes directly to the profile file. Build System Integration # Setting -DLIBC_ENABLE_COVERAGE=ON in the CMake configuration passes -fprofile-instr-generate=libc_cov_%p.profraw , -fcoverage-mapping , and -fprofile-continuous across all LLVM-libc compilation units and test link steps.
When -fprofile-continuous is enabled, Clang automatically prepends %c to the profile file template, avoiding duplicate specifier warnings at runtime. Setting -DLIBC_ENABLE_COVERAGE_MCDC=ON additionally enables -fcoverage-mcdc . Running Code Coverage Locally # Prerequisites & Toolchain Setup # Generating coverage reports requires Clang 24, LLVM profile tools, CMake, and Ninja: Compiler: Clang 24 (or Clang built from HEAD).
Full-build hermetic tests link libclang_rt.profile.a , which must match the compiler version and cannot rely on distro-built libraries with glibc source fortification. LLVM Utilities: Matching Clang 24 versions of llvm-profdata and llvm-cov . Linker: lld is recommended when configuring full-build mode. Build System: CMake 3.28+ and Ninja. Toolchain Discovery # If your Linux distribution packages version-suffixed binaries (e.g. clang-24 , llvm-profdata-24 ), discover and export them: CLANG_MAJOR = $( clang --version | sed -n 's/.*version \([0-9]*\).*/\1/p' ) export LLVM_PROFDATA = $( which llvm-profdata- $CLANG_MAJOR 2 >/dev/null \ || which llvm-profdata ) export LLVM_COV = $( which llvm-cov- $CLANG_MAJOR 2 >/dev/null \ || which llvm-cov ) If version-agnostic tools are directly available in your PATH , export: export LLVM_PROFDATA = llvm-profdata export LLVM_COV = llvm-cov Subsequent merge and report commands reference $LLVM_PROFDATA and $LLVM_COV .
Building Clang 24 with Profiling Support # Full-build hermetic tests link libclang_rt.profile.a . Distro-built compiler-rt packages on distributions like Debian or Ubuntu are built with glibc source fortification enabled, which LLVM-libc does not support because it introduces unresolved symbols such as __vfprintf_chk . Furthermore, compiler-rt must match the exact version of the compiler used to build. The recommended approach is building Clang 24, lld, and compiler-rt from HEAD: cmake -G Ninja -S llvm -B build-clang \ -DCMAKE_BUILD_TYPE = Release \ -DCMAKE_INSTALL_PREFIX = " $HOME /clang" \ -DLLVM_ENABLE_PROJECTS = "clang;clang-tools-extra;lld" \ -DLLVM_ENABLE_RUNTIMES = "compiler-rt" \ -DLLVM_USE_LINKER = lld ninja -C build-clang install Cleaning Profile Counters # Removes previously generated raw profile counter files ( .profraw ) and merged profile databases ( .profdata ) so that new coverage runs record clean, non-aggregated execution data: find . -name "libc_cov_*.profraw" -delete 2 >/dev/null || true rm -f libc_full.profdata libc_mcdc.profdata libc_single.profdata \ profraw_list.txt Standard Statement & Branch Coverage # Standard coverage measures physical line execution and conditional branch outcomes across all LLVM-libc entrypoints and internal support utilities.
1. Clean Prior Profile Artifacts # Removes previously generated raw profile counters and profile data to maintain a clean baseline: rm -f build-cov/libc_cov_*.profraw libc_cov_*.profraw profraw_list.txt libc_full.profdata 2. Configure Full-Build Coverage with Clang 24 # Configures CMake to build LLVM-libc with code coverage enabled using Clang 24 and LLD: cmake -G Ninja -S runtimes -B build-cov \ -DCMAKE_C_COMPILER = " $PWD /build-clang/bin/clang" \ -DCMAKE_CXX_COMPILER = " $PWD /build-clang/bin/clang++" \ -DLLVM_USE_LINKER = lld \ -DCMAKE_BUILD_TYPE = Debug \ -DLLVM_ENABLE_RUNTIMES = "libc" \ -DLLVM_LIBC_FULL_BUILD = ON \ -DLIBC_ENABLE_COVERAGE = ON 3.
Export Environment Variables # Exports the profile output pattern and Clang 24 tool paths: export LLVM_PROFILE_FILE = "libc_cov_%p.profraw" export LLVM_PROFDATA = " $PWD /build-clang/bin/llvm-profdata" export LLVM_COV = " $PWD /build-clang/bin/llvm-cov" 4. Build and Execute Tests # Compiles and executes the test suite: ninja -k 0 -C build-cov libc-tests Note The -k 0 flag ensures Ninja continues executing all remaining test targets even if an individual edge-case test encounters an error.
To only compile test binaries without executing them, use ninja -C build-cov libc-tests-build . 5. Merge Profile Counters # Scans the build tree for all generated .profraw files and indexes them into a unified, sparse .profdata archive using $LLVM_PROFDATA : find build-cov -name "libc_cov_*.profraw" > profraw_list.txt " $LLVM_PROFDATA " merge -sparse -f profraw_list.txt -o libc_full.profdata 6. Generate Coverage Reports # Collects all compiled test binary paths and invokes $LLVM_COV to correlate recorded profile counters against the libc source tree: TEST_BINS =( $( find build-cov -type f -executable -name "*__build__" ) ) OBJECT_FLAGS =() for bin in " ${ TEST_BINS [@]: 1 } " ; do OBJECT_FLAGS +=( "-object= $bin " ) done Reports can be generated in different formats: Option 1: Terminal Summary Report # Prints an aggregated terminal summary showing line, region, and branch coverage percentages for each file: " $LLVM_COV " report \ -instr-profile = libc_full.profdata \ " ${ TEST_BINS [0] } " " ${ OBJECT_FLAGS [@] } " \ --show-branch-summary \ -ignore-filename-regex = ".*(test|utils).*" To restrict the terminal report to a specific source file: " $LLVM_COV " report \ -instr-profile = libc_full.profdata \ " ${ TEST_BINS [0] } " " ${ OBJECT_FLAGS [@] } " \ libc/src/string/strlen.cpp Option 2: Interactive HTML Dashboard # Generates an interactive HTML dashboard containing sortable directory metrics and syntax-highlighted source views: " $LLVM_COV " show \ -format = html \ -output-dir = coverage_html \ -instr-profile = libc_full.profdata \ " ${ TEST_BINS [0] } " " ${ OBJECT_FLAGS [@] } " \ --sho
The rest of this page is on the live site.