[llvm] r232007 - docs: Document the llvm-cov show and report commands

[Justin Bogner]

Author: bogner
Date: Wed Mar 11 23:18:21 2015
New Revision: 232007

URL: http://llvm.org/viewvc/llvm-project?rev=232007&view=rev
Log:
docs: Document the llvm-cov show and report commands

Add a basic synopsis of how to work with instrprof based coverage
using the llvm-cov tools.

Modified:
    llvm/trunk/docs/CommandGuide/llvm-cov.rst

Modified: llvm/trunk/docs/CommandGuide/llvm-cov.rst
URL: http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CommandGuide/llvm-cov.rst?rev=232007&r1=232006&r2=232007&view=diff
==============================================================================
--- llvm/trunk/docs/CommandGuide/llvm-cov.rst (original)
+++ llvm/trunk/docs/CommandGuide/llvm-cov.rst Wed Mar 11 23:18:21 2015
@@ -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.
+
+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.
 
-To use llvm-cov, you must first build an instrumented version of your
-application that collects coverage data as it runs. Compile with the
+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_
 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:: -no-colors
+
+ Disable colorized output.
+
+.. 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:`report <llvm-cov-show>`.
+
+OPTIONS
+^^^^^^^
+
+.. option:: -no-colors
+
+ Disable colorized output.
 
-: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.