diff options
Diffstat (limited to 'docs/CommandGuide/llvm-cov.rst')
| -rw-r--r-- | docs/CommandGuide/llvm-cov.rst | 212 |
1 files changed, 191 insertions, 21 deletions
diff --git a/docs/CommandGuide/llvm-cov.rst b/docs/CommandGuide/llvm-cov.rst index e0b2fe9..dff3375 100644 --- a/docs/CommandGuide/llvm-cov.rst +++ b/docs/CommandGuide/llvm-cov.rst @@ -4,18 +4,49 @@ llvm-cov - emit coverage information SYNOPSIS -------- -:program:`llvm-cov` [options] SOURCEFILE +:program:`llvm-cov` *command* [*args...*] DESCRIPTION ----------- -The :program:`llvm-cov` tool reads code coverage data files and displays the -coverage information for a specified source file. It is compatible with the -``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with -some later versions of ``gcov``. +The :program:`llvm-cov` tool shows code coverage information for +programs that are instrumented to emit profile data. It can be used to +work with ``gcov``\-style coverage or with ``clang``\'s instrumentation +based profiling. -To use llvm-cov, you must first build an instrumented version of your -application that collects coverage data as it runs. Compile with the +If the program is invoked with a base name of ``gcov``, it will behave as if +the :program:`llvm-cov gcov` command were called. Otherwise, a command should +be provided. + +COMMANDS +-------- + +* :ref:`gcov <llvm-cov-gcov>` +* :ref:`show <llvm-cov-show>` +* :ref:`report <llvm-cov-report>` + +.. program:: llvm-cov gcov + +.. _llvm-cov-gcov: + +GCOV COMMAND +------------ + +SYNOPSIS +^^^^^^^^ + +:program:`llvm-cov gcov` [*options*] *SOURCEFILE* + +DESCRIPTION +^^^^^^^^^^^ + +The :program:`llvm-cov gcov` tool reads code coverage data files and displays +the coverage information for a specified source file. It is compatible with the +``gcov`` tool from version 4.2 of ``GCC`` and may also be compatible with some +later versions of ``gcov``. + +To use :program:`llvm-cov gcov`, you must first build an instrumented version +of your application that collects coverage data as it runs. Compile with the ``-fprofile-arcs`` and ``-ftest-coverage`` options to add the instrumentation. (Alternatively, you can use the ``--coverage`` option, which includes both of those other options.) You should compile with debugging @@ -39,24 +70,23 @@ directories, the prefix from the ``GCOV_PREFIX`` 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 ``.gcda`` files back to the object file directories -where llvm-cov expects to find them. +where :program:`llvm-cov gcov` expects to find them. -Once you have generated the coverage data files, run llvm-cov 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 ``.gcov`` -suffix. A separate output file is also created for each file included by the -main source file, also with a ``.gcov`` suffix added. +Once you have generated the coverage data files, run :program:`llvm-cov gcov` +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 ``.gcov`` suffix. A separate output file is also created for +each file included by the main source file, also with a ``.gcov`` suffix added. -The basic content of an llvm-cov output file is a copy of the source file with +The basic content of an ``.gcov`` 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 ``-`` 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 ``#####``. - OPTIONS -------- +^^^^^^^ .. option:: -a, --all-blocks @@ -66,7 +96,7 @@ OPTIONS .. option:: -b, --branch-probabilities - Display conditional branch probabilities and a summary of branch information. + Display conditional branch probabilities and a summary of branch information. .. option:: -c, --branch-counts @@ -120,8 +150,148 @@ OPTIONS Display the version of llvm-cov. EXIT STATUS ------------ +^^^^^^^^^^^ + +:program:`llvm-cov gcov` returns 1 if it cannot read input files. Otherwise, +it exits with zero. + + +.. program:: llvm-cov show + +.. _llvm-cov-show: + +SHOW COMMAND +------------ + +SYNOPSIS +^^^^^^^^ + +:program:`llvm-cov show` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*] + +DESCRIPTION +^^^^^^^^^^^ + +The :program:`llvm-cov show` command shows line by line coverage of a binary +*BIN* using the profile data *PROFILE*. It can optionally be filtered to only +show the coverage for the files listed in *SOURCES*. + +To use :program:`llvm-cov show`, you need a program that's compiled with +instrumentation to emit profile and coverage data. To build such a program with +``clang`` use the ``-fprofile-instr-generate`` and ``-fcoverage-mapping`` +flags. If linking with the ``clang`` driver, pass ``-fprofile-instr-generate`` +to the link stage to make sure the necessary runtime libraries are linked in. + +The coverage information is stored in the built executable or library itself, +and this is what you should pass to :program:`llvm-cov show` as the *BIN* +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 ``default.profraw``, which can be converted to a format that +is suitable for the *PROFILE* argument using the :program:`llvm-profdata merge` +tool. + +OPTIONS +^^^^^^^ + +.. option:: -show-line-counts + + Show the execution counts for each line. This is enabled by default, unless + another ``-show`` option is used. + +.. option:: -show-expansions + + Expand inclusions, such as preprocessor macros or textual inclusions, inline + in the display of the source file. + +.. option:: -show-instantiations + + For source regions that are instantiated multiple times, such as templates in + ``C++``, show each instantiation separately as well as the combined summary. + +.. option:: -show-regions + + Show the execution counts for each region by displaying a caret that points to + the character where the region starts. + +.. option:: -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. + +.. option:: -use-color[=VALUE] + + Enable or disable color output. By default this is autodetected. + +.. option:: -arch=<name> + + If the covered binary is a universal binary, select the architecture to use + when looking up the coverage map. Errors out if the supplied architecture is + not found in the universal binary, or if used on a non-universal binary of + a different architecture. + +.. option:: -name=<NAME> + + Show code coverage only for functions with the given name. + +.. option:: -name-regex=<PATTERN> + + Show code coverage only for functions that match the given regular expression. + +.. option:: -line-coverage-gt=<N> + + Show code coverage only for functions with line coverage greater than the + given threshold. + +.. option:: -line-coverage-lt=<N> + + Show code coverage only for functions with line coverage less than the given + threshold. + +.. option:: -region-coverage-gt=<N> + + Show code coverage only for functions with region coverage greater than the + given threshold. + +.. option:: -region-coverage-lt=<N> + + Show code coverage only for functions with region coverage less than the given + threshold. + +.. program:: llvm-cov report + +.. _llvm-cov-report: + +REPORT COMMAND +-------------- + +SYNOPSIS +^^^^^^^^ + +:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*SOURCES*] + +DESCRIPTION +^^^^^^^^^^^ + +The :program:`llvm-cov report` command displays a summary of the coverage of a +binary *BIN* using the profile data *PROFILE*. It can optionally be filtered to +only show the coverage for the files listed in *SOURCES*. + +If no source files are provided, a summary line is printed for each file in the +coverage data. If any files are provided, summaries are shown for each function +in the listed files instead. + +For information on compiling programs for coverage and generating profile data, +see :ref:`llvm-cov-show`. + +OPTIONS +^^^^^^^ + +.. option:: -use-color[=VALUE] + + Enable or disable color output. By default this is autodetected. -:program:`llvm-cov` returns 1 if it cannot read input files. Otherwise, it -exits with zero. +.. option:: -arch=<name> + If the covered binary is a universal binary, select the architecture to use + when looking up the coverage map. Errors out if the supplied architecture is + not found in the universal binary, or if used on a non-universal binary of + a different architecture. |