==========================================================
llvm2lcov - Translate ``llvm-cov`` profdata to LCOV format
==========================================================

:Manual section: 1
:Manual group: |ToolName| 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 |ToolName| suite
(*e.g.*, ``--comment``, ``--version-script``, ``--ignore-error``, ``--substitute``,
``--exclude``, *etc.*), the tool provides the following options:

``--output`` *filename*, ``-o`` *filename*
   The |ToolName| 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 :manpage:`lcov(1)` and :manpage:`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
--------

:manpage:`lcov(1)`, :manpage:`genhtml(1)`, :manpage:`geninfo(1)`,
:manpage:`lcovrc(5)`,

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