LLVM2LCOV(1) LCOV LLVM2LCOV(1)

llvm2lcov - llvm2lcov documentation

1
LCOV Tools

Translate LLVM coverage data from llvm-cov profdata to LCOV format

llvm2lcov [--output filename] [--testname name] [options] json_file [json_file ...]

llvm2lcov traverses C/C++ coverage data in JSON format (generated by llvm-cov export -format=text ...) and translates it into LCOV .info format.

Note that LLVM supports two coverage data collection paths: the one described in this page - based on profile data - and a gcov path - similar to that supported by gcc. See the LLVM documentation for more details about the gcov support in LLVM.

To generate MC/DC data:

  • Use LLVM 18 or newer (LLVM 21+ recommended for cleaner MC/DC data)
  • Enable MC/DC instrumentation in compile/link steps with -fcoverage-mcdc
  • Pass the --mcdc-coverage flag to llvm2lcov

Note that LLVM does not support MC/DC metrics when using the gcov data collection path.

In addition to common options supported by other tools in the LCOV suite (e.g., --comment, --version-script, --ignore-error, --substitute, --exclude, etc.), the tool provides the following options:

The LCOV data will be written to the specified file. If this option is not used, data is written to llvm2lcov.info in the current directory.
Coverage info will be associated with the testcase name provided. It is not necessary to provide a name.
Include branch coverage data in the output.
Include MC/DC data in the output. Requires LLVM 18 or higher with MC/DC instrumentation enabled during compilation.

See lcov(1) <file://../man/lcov.1.html> and lcovrc(5) <file://../man/lcovrc.5.html> for details of other options and configuration settings.

Basic workflow:

# Compile with coverage instrumentation (including MC/DC)
$ clang++ -o myExe -fprofile-inst-generate -fcoverage-mapping \
    -fcoverage-mcdc myCode.cpp
# Run your testcases
$ ./myExe ...
# Convert profile data
$ llvm-profdata merge -o myExe.profdata --sparse *.profraw
# Export coverage data in JSON format
$ llvm-cov export -format=text -instr-profile=myExe.profdata \
    ./myExe > myExe.json
# Convert to LCOV format
$ llvm2lcov --output myExe.info --test-name myTestcase \
    --mcdc-coverage --branch-coverage myExe.json ...
# Generate HTML coverage report
$ genhtml -o html_report myExe.info ...

(... indicates other tool options that you might be using - e.g., for filtering and exclusion.)

Executing the same example via gcov looks like:

# Compile with gcov instrumentation
$ clang++ -o myExe --coverage myCode.cpp
# Run your testcases
$ ./myExe ...
# Convert to LCOV format
#   Note that the '--gcov-tool' option appears *twice*: once to name
#   the tool and once to pass a tool option.  See the lcov man page
#   for more information.
$ lcov --capture -d . --branch-coverage -o myExe.info --gcov-tool llvm-cov --gcov-tool gcov ...
# Generate HTML coverage report
$ genhtml -o html_report myExe.info ...

Henry Cox <<henry.cox@mediatek.com>>

lcov(1) <file://../man/lcov.1.html>, genhtml(1) <file://../man/genhtml.1.html>, geninfo(1) <file://../man/geninfo.1.html>, lcovrc(5) <file://../man/lcovrc.5.html>,

2024-2026, LCOV Project

2026-07-07 2.5