llvm.org GIT mirror llvm / 534ec26
Add some details to the llvm-cov documentation. <rdar://problem/15819496> git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@208098 91177308-0d34-0410-b5e6-96231b3b80d8 Bob Wilson 5 years ago
1 changed file(s) with 96 addition(s) and 13 deletion(s). Raw diff Collapse all Expand all
33 SYNOPSIS
44 --------
55
6 :program:`llvm-cov` [-gcno=filename] [-gcda=filename] [dump]
6 :program:`llvm-cov` [options] SOURCEFILE
77
88 DESCRIPTION
99 -----------
1010
11 The experimental :program:`llvm-cov` tool reads in description file generated
12 by compiler and coverage data file generated by instrumented program. This
13 program assumes that the description and data file uses same format as gcov
14 files.
11 The :program:`llvm-cov` tool reads code coverage data files and displays the
12 coverage information for a specified source file. It is compatible with the
13 ``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with
14 some later versions of ``gcov``.
15
16 To use llvm-cov, you must first build an instrumented version of your
17 application that collects coverage data as it runs. Compile with the
18 ``-fprofile-arcs`` and ``-ftest-coverage`` options to add the
19 instrumentation. (Alternatively, you can use the ``--coverage`` option, which
20 includes both of those other options.) You should compile with debugging
21 information (``-g``) and without optimization (``-O0``); otherwise, the
22 coverage data cannot be accurately mapped back to the source code.
23
24 At the time you compile the instrumented code, a ``.gcno`` data file will be
25 generated for each object file. These ``.gcno`` files contain half of the
26 coverage data. The other half of the data comes from ``.gcda`` files that are
27 generated when you run the instrumented program, with a separate ``.gcda``
28 file for each object file. Each time you run the program, the execution counts
29 are summed into any existing ``.gcda`` files, so be sure to remove any old
30 files if you do not want their contents to be included.
31
32 By default, the ``.gcda`` files are written into the same directory as the
33 object files, but you can override that by setting the ``GCOV_PREFIX`` and
34 ``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP``
35 variable specifies a number of directory components to be removed from the
36 start of the absolute path to the object file directory. After stripping those
37 directories, the prefix from the ``GCOV_PREFIX`` variable is added. These
38 environment variables allow you to run the instrumented program on a machine
39 where the original object file directories are not accessible, but you will
40 then need to copy the ``.gcda`` files back to the object file directories
41 where llvm-cov expects to find them.
42
43 Once you have generated the coverage data files, run llvm-cov for each main
44 source file where you want to examine the coverage results. This should be run
45 from the same directory where you previously ran the compiler. The results for
46 the specified source file are written to a file named by appending a ``.gcov``
47 suffix. A separate output file is also created for each file included by the
48 main source file, also with a ``.gcov`` suffix added.
49
50 The basic content of an llvm-cov output file is a copy of the source file with
51 an execution count and line number prepended to every line. The execution
52 count is shown as ``-`` if a line does not contain any executable code. If
53 a line contains code but that code was never executed, the count is displayed
54 as ``#####``.
55
1556
1657 OPTIONS
1758 -------
1859
19 .. option:: -gcno=filename
60 .. option:: -a, --all-blocks
2061
21 This option selects input description file generated by compiler while
22 instrumenting program.
62 Display all basic blocks. If there are multiple blocks for a single line of
63 source code, this option causes llvm-cov to show the count for each block
64 instead of just one count for the entire line.
2365
24 .. option:: -gcda=filename
66 .. option:: -b, --branch-probabilities
2567
26 This option selects coverage data file generated by instrumented compiler.
68 Display conditional branch probabilities and a summary of branch information.
2769
28 .. option:: -dump
70 .. option:: -c, --branch-counts
2971
30 This options enables output dump that is suitable for a developer to help
31 debug :program:`llvm-cov` itself.
72 Display branch counts instead of probabilities (requires -b).
73
74 .. option:: -f, --function-summaries
75
76 Show a summary of coverage for each function instead of just one summary for
77 an entire source file.
78
79 .. option:: --help
80
81 Display available options (--help-hidden for more).
82
83 .. option:: -l, --long-file-names
84
85 For coverage output of files included from the main source file, add the
86 main file name followed by ``##`` as a prefix to the output file names. This
87 can be combined with the --preserve-paths option to use complete paths for
88 both the main file and the included file.
89
90 .. option:: -o=, --object-directory=, --object-file=
91
92 Find objects in DIR or based on FILE's path. If you specify a particular
93 object file, the coverage data files are expected to have the same base name
94 with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the
95 files are expected in that directory with the same base name as the source
96 file.
97
98 .. option:: -p, --preserve-paths
99
100 Preserve path components when naming the coverage output files. In addition
101 to the source file name, include the directories from the path to that
102 file. The directories are separate by ``#`` characters, with ``.`` directories
103 removed and ``..`` directories replaced by ``^`` characters. When used with
104 the --long-file-names option, this applies to both the main file name and the
105 included file name.
106
107 .. option:: -u, --unconditional-branches
108
109 Include unconditional branches in the output for the --branch-probabilities
110 option.
111
112 .. option:: -version
113
114 Display the version of llvm-cov.
32115
33116 EXIT STATUS
34117 -----------