llvm2lcov - Translate llvm-cov profdata to LCOV format

Manual section:

1

Manual group:

LCOV Tools

NAME

llvm2lcov

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

SYNOPSIS

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

DESCRIPTION

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.

MC/DC Coverage

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.

OPTIONS

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:

--output filename, -o filename

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.

--testname name, -t name

Coverage info will be associated with the testcase name provided. It is not necessary to provide a name.

--branch-coverage

Include branch coverage data in the output.

--mcdc-coverage

Include MC/DC data in the output. Requires LLVM 18 or higher with MC/DC instrumentation enabled during compilation.

See lcov(1) and lcovrc(5) for details of other options and configuration settings.

EXAMPLES

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 ...

AUTHOR

Henry Cox <henry.cox@mediatek.com>

SEE ALSO

lcov(1), genhtml(1), geninfo(1), lcovrc(5),