llvm2lcov - Translate llvm-cov profdata to LCOV format — LCOV 2.5 documentation

# 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),

- LLVM documentation: https://llvm.org/docs/CoverageMappingFormat.html

- `llvm-cov` documentation: https://llvm.org/docs/CommandGuide/llvm-cov.html