LLVM2LCOV(1)

NAME
llvm2lcov - llvm2lcov documentation

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) <file://../man/lcov.1.html> and lcovrc(5) <file://../man/lcovrc.5.html> 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) <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>,

•   LLVM documentation: <https://llvm.org/docs/CoverageMappingFormat.html>

•   llvm-cov documentation: <https://llvm.org/docs/CommandGuide/llvm-cov.html>

Copyright
2024-2026, LCOV Project