.\" Man page generated from reStructuredText
.\" by the Docutils 0.23 manpage writer.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "LLVM2LCOV" "1" "2026-07-07" "2.5" "LCOV"
.SH NAME
llvm2lcov \- llvm2lcov documentation
.INDENT 0.0
.TP
.B Manual section
1
.TP
.B Manual group
LCOV Tools
.UNINDENT
.SH NAME
.INDENT 0.0
.TP
.B llvm2lcov
Translate LLVM coverage data from \fBllvm\-cov\fP profdata to LCOV format
.UNINDENT
.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
llvm2lcov [\-\-output filename] [\-\-testname name] [options] json_file [json_file ...]
.EE
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBllvm2lcov\fP traverses C/C++ coverage data in JSON format (generated by
\fBllvm\-cov export \-format=text ...\fP) and translates it into LCOV \fB\&.info\fP
format.
.sp
Note that LLVM supports two coverage data collection paths:  the one described in this page \- based on profile data \- and a \fIgcov path\fP \- similar to that supported by \fBgcc\fP\&.  See the LLVM documentation for more details about the \fBgcov\fP support in LLVM.
.SH MC/DC COVERAGE
.sp
To generate MC/DC data:
.INDENT 0.0
.IP \(bu 2
Use LLVM 18 or newer (LLVM 21+ recommended for cleaner MC/DC data)
.IP \(bu 2
Enable MC/DC instrumentation in compile/link steps with \fB\-fcoverage\-mcdc\fP
.IP \(bu 2
Pass the \fB\-\-mcdc\-coverage\fP flag to \fBllvm2lcov\fP
.UNINDENT
.sp
Note that LLVM does not support MC/DC metrics when using the \fBgcov\fP data
collection path.
.SH OPTIONS
.sp
In addition to common options supported by other tools in the LCOV suite
(\fIe.g.\fP, \fB\-\-comment\fP, \fB\-\-version\-script\fP, \fB\-\-ignore\-error\fP, \fB\-\-substitute\fP,
\fB\-\-exclude\fP, \fIetc.\fP), the tool provides the following options:
.INDENT 0.0
.TP
.B \fB\-\-output\fP \fIfilename\fP, \fB\-o\fP \fIfilename\fP
The LCOV data will be written to the specified file. If this option is
not used, data is written to \fBllvm2lcov.info\fP in the current directory.
.TP
.B \fB\-\-testname\fP \fIname\fP, \fB\-t\fP \fIname\fP
Coverage info will be associated with the testcase name provided.
It is not necessary to provide a name.
.TP
.B \fB\-\-branch\-coverage\fP
Include branch coverage data in the output.
.TP
.B \fB\-\-mcdc\-coverage\fP
Include MC/DC data in the output. Requires LLVM 18 or higher with MC/DC
instrumentation enabled during compilation.
.UNINDENT
.sp
See \fBlcov(1) \%<file://\:\:../\:man/\:lcov\:.1\:.html>\fP and \fBlcovrc(5) \%<file://\:\:../\:man/\:lcovrc\:.5\:.html>\fP for details of other options
and configuration settings.
.SH EXAMPLES
.sp
Basic workflow:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Compile with coverage instrumentation (including MC/DC)
$ clang++ \-o myExe \-fprofile\-inst\-generate \-fcoverage\-mapping \e
    \-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 \e
    ./myExe > myExe.json

# Convert to LCOV format
$ llvm2lcov \-\-output myExe.info \-\-test\-name myTestcase \e
    \-\-mcdc\-coverage \-\-branch\-coverage myExe.json ...

# Generate HTML coverage report
$ genhtml \-o html_report myExe.info ...
.EE
.UNINDENT
.UNINDENT
.sp
(\fB\&...\fP indicates other tool options that you might be using \- \fIe.g.\fP,
for filtering and exclusion.)
.sp
Executing the same example via \fBgcov\fP looks like:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
# Compile with gcov instrumentation
$ clang++ \-o myExe \-\-coverage myCode.cpp

# Run your testcases
$ ./myExe ...

# Convert to LCOV format
#   Note that the \(aq\-\-gcov\-tool\(aq 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 ...
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
.sp
Henry Cox <\%<henry\:.cox@\:mediatek\:.com>>
.SH SEE ALSO
.sp
\fBlcov(1) \%<file://\:\:../\:man/\:lcov\:.1\:.html>\fP, \fBgenhtml(1) \%<file://\:\:../\:man/\:genhtml\:.1\:.html>\fP, \fBgeninfo(1) \%<file://\:\:../\:man/\:geninfo\:.1\:.html>\fP,
\fBlcovrc(5) \%<file://\:\:../\:man/\:lcovrc\:.5\:.html>\fP,
.INDENT 0.0
.IP \(bu 2
LLVM documentation: \%<https://\:llvm\:.org/\:docs/\:CoverageMappingFormat\:.html>
.IP \(bu 2
\fBllvm\-cov\fP documentation: \%<https://\:llvm\:.org/\:docs/\:CommandGuide/\:llvm-cov\:.html>
.UNINDENT
.SH Copyright
2024-2026, LCOV Project
.\" End of generated man page.