Hi tech@,
Now that we have llvm-profdata in base, I would like to propose adding
llvm-cov as well. Just like llvm-profdata, it is fast to build and
only takes a few seconds on my amd64 machine.
Having it in base would allow producing reports from coverage data
processed with llvm-profdata without having to install the devel/llvm
port.
Comments? OK?
Index: gnu/usr.bin/clang/Makefile
===================================================================
RCS file: /cvs/src/gnu/usr.bin/clang/Makefile,v
retrieving revision 1.25
diff -u -p -r1.25 Makefile
--- gnu/usr.bin/clang/Makefile 26 Jul 2022 15:37:34 -0000 1.25
+++ gnu/usr.bin/clang/Makefile 29 Jul 2022 20:21:18 -0000
@@ -108,6 +108,7 @@ SUBDIR+=include/llvm-readobj
SUBDIR+=llvm-readobj
SUBDIR+=llvm-profdata
+SUBDIR+=llvm-cov
.if ${AR_VERSION:L} == "llvm" || make(obj)
SUBDIR+=libLLVMDlltoolDriver
Index: gnu/usr.bin/clang/llvm-cov/Makefile
===================================================================
RCS file: gnu/usr.bin/clang/llvm-cov/Makefile
diff -N gnu/usr.bin/clang/llvm-cov/Makefile
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ gnu/usr.bin/clang/llvm-cov/Makefile 29 Jul 2022 20:21:18 -0000
@@ -0,0 +1,29 @@
+# $OpenBSD$
+
+.include <bsd.own.mk>
+
+PROG= llvm-cov
+BINDIR= /usr/bin
+
+SRCS= llvm-cov.cpp \
+ gcov.cpp \
+ CodeCoverage.cpp \
+ CoverageExporterJson.cpp \
+ CoverageExporterLcov.cpp \
+ CoverageFilters.cpp \
+ CoverageReport.cpp \
+ CoverageSummaryInfo.cpp \
+ SourceCoverageView.cpp \
+ SourceCoverageViewHTML.cpp \
+ SourceCoverageViewText.cpp \
+ TestingSupport.cpp \
+
+MAN+= llvm-cov.1
+
+.PATH: ${.CURDIR}/../../../llvm/llvm/tools/llvm-cov
+
+LLVM_LIBDEPS= LLVM
+
+LDADD+= -L ${.OBJDIR}/../libLLVM -lLLVM
+
+.include <bsd.prog.mk>
Index: gnu/usr.bin/clang/llvm-cov/llvm-cov.1
===================================================================
RCS file: gnu/usr.bin/clang/llvm-cov/llvm-cov.1
diff -N gnu/usr.bin/clang/llvm-cov/llvm-cov.1
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ gnu/usr.bin/clang/llvm-cov/llvm-cov.1 29 Jul 2022 20:21:18 -0000
@@ -0,0 +1,528 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.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 "LLVM-COV" "1" "2022-05-23" "13" "LLVM"
+.SH NAME
+llvm-cov \- emit coverage information
+.SH SYNOPSIS
+.sp
+\fBllvm\-cov\fP \fIcommand\fP [\fIargs...\fP]
+.SH DESCRIPTION
+.sp
+The \fBllvm\-cov\fP tool shows code coverage information for
+programs that are instrumented to emit profile data. It can be used to
+work with \fBgcov\fP\-style coverage or with \fBclang\fP\(aqs instrumentation
+based profiling.
+.sp
+If the program is invoked with a base name of \fBgcov\fP, it will behave as if
+the \fBllvm\-cov gcov\fP command were called. Otherwise, a command should
+be provided.
+.SH COMMANDS
+.INDENT 0.0
+.IP \(bu 2
+\fI\%gcov\fP
+.IP \(bu 2
+\fI\%show\fP
+.IP \(bu 2
+\fI\%report\fP
+.IP \(bu 2
+\fI\%export\fP
+.UNINDENT
+.SH GCOV COMMAND
+.SS SYNOPSIS
+.sp
+\fBllvm\-cov gcov\fP [\fIoptions\fP] \fISOURCEFILE\fP
+.SS DESCRIPTION
+.sp
+The \fBllvm\-cov gcov\fP tool reads code coverage data files and displays
+the coverage information for a specified source file. It is compatible with the
+\fBgcov\fP tool from version 4.2 of \fBGCC\fP and may also be compatible with
some
+later versions of \fBgcov\fP\&.
+.sp
+To use \fBllvm\-cov gcov\fP, you must first build an instrumented version
+of your application that collects coverage data as it runs. Compile with the
+\fB\-fprofile\-arcs\fP and \fB\-ftest\-coverage\fP options to add the
+instrumentation. (Alternatively, you can use the \fB\-\-coverage\fP option,
which
+includes both of those other options.)
+.sp
+At the time you compile the instrumented code, a \fB\&.gcno\fP data file will
be
+generated for each object file. These \fB\&.gcno\fP files contain half of the
+coverage data. The other half of the data comes from \fB\&.gcda\fP files that
are
+generated when you run the instrumented program, with a separate \fB\&.gcda\fP
+file for each object file. Each time you run the program, the execution counts
+are summed into any existing \fB\&.gcda\fP files, so be sure to remove any old
+files if you do not want their contents to be included.
+.sp
+By default, the \fB\&.gcda\fP files are written into the same directory as the
+object files, but you can override that by setting the \fBGCOV_PREFIX\fP and
+\fBGCOV_PREFIX_STRIP\fP environment variables. The \fBGCOV_PREFIX_STRIP\fP
+variable specifies a number of directory components to be removed from the
+start of the absolute path to the object file directory. After stripping those
+directories, the prefix from the \fBGCOV_PREFIX\fP variable is added. These
+environment variables allow you to run the instrumented program on a machine
+where the original object file directories are not accessible, but you will
+then need to copy the \fB\&.gcda\fP files back to the object file directories
+where \fBllvm\-cov gcov\fP expects to find them.
+.sp
+Once you have generated the coverage data files, run \fBllvm\-cov gcov\fP
+for each main source file where you want to examine the coverage results. This
+should be run from the same directory where you previously ran the
+compiler. The results for the specified source file are written to a file named
+by appending a \fB\&.gcov\fP suffix. A separate output file is also created for
+each file included by the main source file, also with a \fB\&.gcov\fP suffix
added.
+.sp
+The basic content of an \fB\&.gcov\fP output file is a copy of the source file
with
+an execution count and line number prepended to every line. The execution
+count is shown as \fB\-\fP if a line does not contain any executable code. If
+a line contains code but that code was never executed, the count is displayed
+as \fB#####\fP\&.
+.SS OPTIONS
+.INDENT 0.0
+.TP
+.B \-a, \-\-all\-blocks
+Display all basic blocks. If there are multiple blocks for a single line of
+source code, this option causes llvm\-cov to show the count for each block
+instead of just one count for the entire line.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-b, \-\-branch\-probabilities
+Display conditional branch probabilities and a summary of branch information.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-c, \-\-branch\-counts
+Display branch counts instead of probabilities (requires \-b).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-m, \-\-demangled\-names
+Demangle function names.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-f, \-\-function\-summaries
+Show a summary of coverage for each function instead of just one summary for
+an entire source file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-help
+Display available options (\-\-help\-hidden for more).
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-l, \-\-long\-file\-names
+For coverage output of files included from the main source file, add the
+main file name followed by \fB##\fP as a prefix to the output file names. This
+can be combined with the \-\-preserve\-paths option to use complete paths for
+both the main file and the included file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-n, \-\-no\-output
+Do not output any \fB\&.gcov\fP files. Summary information is still
+displayed.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-o=<DIR|FILE>, \-\-object\-directory=<DIR>, \-\-object\-file=<FILE>
+Find objects in DIR or based on FILE\(aqs path. If you specify a particular
+object file, the coverage data files are expected to have the same base name
+with \fB\&.gcno\fP and \fB\&.gcda\fP extensions. If you specify a directory,
the
+files are expected in that directory with the same base name as the source
+file.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-p, \-\-preserve\-paths
+Preserve path components when naming the coverage output files. In addition
+to the source file name, include the directories from the path to that
+file. The directories are separate by \fB#\fP characters, with \fB\&.\fP
directories
+removed and \fB\&..\fP directories replaced by \fB^\fP characters. When used
with
+the \-\-long\-file\-names option, this applies to both the main file name and
the
+included file name.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-r
+Only dump files with relative paths or absolute paths with the prefix specified
+by \fB\-s\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-s=<string>
+Source prefix to elide.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-t, \-\-stdout
+Print to stdout instead of producing \fB\&.gcov\fP files.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-u, \-\-unconditional\-branches
+Include unconditional branches in the output for the \-\-branch\-probabilities
+option.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-version
+Display the version of llvm\-cov.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-x, \-\-hash\-filenames
+Use md5 hash of file name when naming the coverage output files. The source
+file name will be suffixed by \fB##\fP followed by MD5 hash calculated for it.
+.UNINDENT
+.SS EXIT STATUS
+.sp
+\fBllvm\-cov gcov\fP returns 1 if it cannot read input files. Otherwise,
+it exits with zero.
+.SH SHOW COMMAND
+.SS SYNOPSIS
+.sp
+\fBllvm\-cov show\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP \fIBIN\fP
[\fI\-object BIN,...\fP] [[\fI\-object BIN\fP]] [\fISOURCES\fP]
+.SS DESCRIPTION
+.sp
+The \fBllvm\-cov show\fP command shows line by line coverage of the
+binaries \fIBIN\fP,... using the profile data \fIPROFILE\fP\&. It can
optionally be
+filtered to only show the coverage for the files listed in \fISOURCES\fP\&.
+.sp
+\fIBIN\fP may be an executable, object file, dynamic library, or archive (thin
or
+otherwise).
+.sp
+To use \fBllvm\-cov show\fP, you need a program that is compiled with
+instrumentation to emit profile and coverage data. To build such a program with
+\fBclang\fP use the \fB\-fprofile\-instr\-generate\fP and
\fB\-fcoverage\-mapping\fP
+flags. If linking with the \fBclang\fP driver, pass
\fB\-fprofile\-instr\-generate\fP
+to the link stage to make sure the necessary runtime libraries are linked in.
+.sp
+The coverage information is stored in the built executable or library itself,
+and this is what you should pass to \fBllvm\-cov show\fP as a \fIBIN\fP
+argument. The profile data is generated by running this instrumented program
+normally. When the program exits it will write out a raw profile file,
+typically called \fBdefault.profraw\fP, which can be converted to a format that
+is suitable for the \fIPROFILE\fP argument using the \fBllvm\-profdata merge\fP
+tool.
+.SS OPTIONS
+.INDENT 0.0
+.TP
+.B \-show\-branches=<VIEW>
+Show coverage for branch conditions in terms of either count or percentage.
+The supported views are: "count", "percent".
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-line\-counts
+Show the execution counts for each line. Defaults to true, unless another
+\fB\-show\fP option is used.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-expansions
+Expand inclusions, such as preprocessor macros or textual inclusions, inline
+in the display of the source file. Defaults to false.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-instantiations
+For source regions that are instantiated multiple times, such as templates in
+\fBC++\fP, show each instantiation separately as well as the combined summary.
+Defaults to true.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-regions
+Show the execution counts for each region by displaying a caret that points to
+the character where the region starts. Defaults to false.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-line\-counts\-or\-regions
+Show the execution counts for each line if there is only one region on the
+line, but show the individual regions if there are multiple on the line.
+Defaults to false.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-use\-color
+Enable or disable color output. By default this is autodetected.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-arch=[*NAMES*]
+Specify a list of architectures such that the Nth entry in the list
+corresponds to the Nth specified binary. If the covered object is a universal
+binary, this specifies the architecture to use. It is an error to specify an
+architecture that is not included in the universal binary or to use an
+architecture that does not match a non\-universal binary.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-name=<NAME>
+Show code coverage only for functions with the given name.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-name\-whitelist=<FILE>
+Show code coverage only for functions listed in the given file. Each line in
+the file should start with \fIwhitelist_fun:\fP, immediately followed by the
name
+of the function to accept. This name can be a wildcard expression.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-name\-regex=<PATTERN>
+Show code coverage only for functions that match the given regular expression.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-ignore\-filename\-regex=<PATTERN>
+Skip source code files with file paths that match the given regular expression.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-format=<FORMAT>
+Use the specified output format. The supported formats are: "text", "html".
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-tab\-size=<TABSIZE>
+Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is
+only supported for the html format.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-output\-dir=PATH
+Specify a directory to write coverage reports into. If the directory does not
+exist, it is created. When used in function view mode (i.e when \-name or
+\-name\-regex are used to select specific functions), the report is written to
+PATH/functions.EXTENSION. When used in file view mode, a report for each file
+is written to PATH/REL_PATH_TO_FILE.EXTENSION.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-Xdemangler=<TOOL>|<TOOL\-OPTION>
+Specify a symbol demangler. This can be used to make reports more
+human\-readable. This option can be specified multiple times to supply
+arguments to the demangler (e.g \fI\-Xdemangler c++filt \-Xdemangler \-n\fP
for C++).
+The demangler is expected to read a newline\-separated list of symbols from
+stdin and write a newline\-separated list of the same length to stdout.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-num\-threads=N, \-j=N
+Use N threads to write file reports (only applicable when \-output\-dir is
+specified). When N=0, llvm\-cov auto\-detects an appropriate number of threads
to
+use. This is the default.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-compilation\-dir=<dir>
+Directory used as a base for relative coverage mapping paths. Only applicable
+when binaries have been compiled with one of \fI\-fcoverage\-prefix\-map\fP
+\fI\-fcoverage\-compilation\-dir\fP, or \fI\-ffile\-compilation\-dir\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-line\-coverage\-gt=<N>
+Show code coverage only for functions with line coverage greater than the
+given threshold.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-line\-coverage\-lt=<N>
+Show code coverage only for functions with line coverage less than the given
+threshold.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-region\-coverage\-gt=<N>
+Show code coverage only for functions with region coverage greater than the
+given threshold.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-region\-coverage\-lt=<N>
+Show code coverage only for functions with region coverage less than the given
+threshold.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-path\-equivalence=<from>,<to>
+Map the paths in the coverage data to local source file paths. This allows you
+to generate the coverage data on one machine, and then use llvm\-cov on a
+different machine where you have the same files on a different path.
+.UNINDENT
+.SH REPORT COMMAND
+.SS SYNOPSIS
+.sp
+\fBllvm\-cov report\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP
\fIBIN\fP [\fI\-object BIN,...\fP] [[\fI\-object BIN\fP]] [\fISOURCES\fP]
+.SS DESCRIPTION
+.sp
+The \fBllvm\-cov report\fP command displays a summary of the coverage of
+the binaries \fIBIN\fP,... using the profile data \fIPROFILE\fP\&. It can
optionally be
+filtered to only show the coverage for the files listed in \fISOURCES\fP\&.
+.sp
+\fIBIN\fP may be an executable, object file, dynamic library, or archive (thin
or
+otherwise).
+.sp
+If no source files are provided, a summary line is printed for each file in the
+coverage data. If any files are provided, summaries can be shown for each
+function in the listed files if the \fB\-show\-functions\fP option is enabled.
+.sp
+For information on compiling programs for coverage and generating profile data,
+see \fI\%SHOW COMMAND\fP\&.
+.SS OPTIONS
+.INDENT 0.0
+.TP
+.B \-use\-color[=VALUE]
+Enable or disable color output. By default this is autodetected.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-arch=<name>
+If the covered binary is a universal binary, select the architecture to use.
+It is an error to specify an architecture that is not included in the
+universal binary or to use an architecture that does not match a
+non\-universal binary.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-region\-summary
+Show statistics for all regions. Defaults to true.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-branch\-summary
+Show statistics for all branch conditions. Defaults to true.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-functions
+Show coverage summaries for each function. Defaults to false.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-show\-instantiation\-summary
+Show statistics for all function instantiations. Defaults to false.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-ignore\-filename\-regex=<PATTERN>
+Skip source code files with file paths that match the given regular expression.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-compilation\-dir=<dir>
+Directory used as a base for relative coverage mapping paths. Only applicable
+when binaries have been compiled with one of \fI\-fcoverage\-prefix\-map\fP
+\fI\-fcoverage\-compilation\-dir\fP, or \fI\-ffile\-compilation\-dir\fP\&.
+.UNINDENT
+.SH EXPORT COMMAND
+.SS SYNOPSIS
+.sp
+\fBllvm\-cov export\fP [\fIoptions\fP] \-instr\-profile \fIPROFILE\fP
\fIBIN\fP [\fI\-object BIN,...\fP] [[\fI\-object BIN\fP]] [\fISOURCES\fP]
+.SS DESCRIPTION
+.sp
+The \fBllvm\-cov export\fP command exports coverage data of the binaries
+\fIBIN\fP,... using the profile data \fIPROFILE\fP in either JSON or lcov
trace file
+format.
+.sp
+When exporting JSON, the regions, functions, branches, expansions, and
+summaries of the coverage data will be exported. When exporting an lcov trace
+file, the line\-based coverage, branch coverage, and summaries will be
exported.
+.sp
+The exported data can optionally be filtered to only export the coverage
+for the files listed in \fISOURCES\fP\&.
+.sp
+For information on compiling programs for coverage and generating profile data,
+see \fI\%SHOW COMMAND\fP\&.
+.SS OPTIONS
+.INDENT 0.0
+.TP
+.B \-arch=<name>
+If the covered binary is a universal binary, select the architecture to use.
+It is an error to specify an architecture that is not included in the
+universal binary or to use an architecture that does not match a
+non\-universal binary.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-format=<FORMAT>
+Use the specified output format. The supported formats are: "text" (JSON),
+"lcov".
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-summary\-only
+Export only summary information for each file in the coverage data. This mode
+will not export coverage information for smaller units such as individual
+functions or regions. The result will contain the same information as produced
+by the \fBllvm\-cov report\fP command, but presented in JSON or lcov
+format rather than text.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-ignore\-filename\-regex=<PATTERN>
+Skip source code files with file paths that match the given regular expression.
+.INDENT 7.0
+.TP
+.B \-skip\-expansions
+.UNINDENT
+.sp
+Skip exporting macro expansion coverage data.
+.INDENT 7.0
+.TP
+.B \-skip\-functions
+.UNINDENT
+.sp
+Skip exporting per\-function coverage data.
+.INDENT 7.0
+.TP
+.B \-num\-threads=N, \-j=N
+.UNINDENT
+.sp
+Use N threads to export coverage data. When N=0, llvm\-cov auto\-detects an
+appropriate number of threads to use. This is the default.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-compilation\-dir=<dir>
+Directory used as a base for relative coverage mapping paths. Only applicable
+when binaries have been compiled with one of \fI\-fcoverage\-prefix\-map\fP
+\fI\-fcoverage\-compilation\-dir\fP, or \fI\-ffile\-compilation\-dir\fP\&.
+.UNINDENT
+.SH AUTHOR
+Maintained by the LLVM Team (https://llvm.org/).
+.SH COPYRIGHT
+2003-2022, LLVM Project
+.\" Generated by docutils manpage writer.
+.
