diff options
Diffstat (limited to 'gnu/usr.bin/clang/llvm-cov/llvm-cov.1')
| -rw-r--r-- | gnu/usr.bin/clang/llvm-cov/llvm-cov.1 | 528 |
1 files changed, 528 insertions, 0 deletions
diff --git a/gnu/usr.bin/clang/llvm-cov/llvm-cov.1 b/gnu/usr.bin/clang/llvm-cov/llvm-cov.1 new file mode 100644 index 00000000000..4e64d957e40 --- /dev/null +++ b/gnu/usr.bin/clang/llvm-cov/llvm-cov.1 @@ -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. +. |