LLVM2LCOV(1)                         LCOV                         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:

       o Use LLVM 18 or newer (LLVM 21+ recommended for cleaner MC/DC data)

       o Enable MC/DC instrumentation in compile/link steps with
         -fcoverage-mcdc

       o 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>,

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

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

Copyright
       2024-2026, LCOV Project

2.5                               2026-07-07                      LLVM2LCOV(1)