aboutsummaryrefslogtreecommitdiffstats
path: root/docs/CommandGuide
diff options
context:
space:
mode:
authorPirama Arumuga Nainar <pirama@google.com>2015-04-08 08:55:49 -0700
committerPirama Arumuga Nainar <pirama@google.com>2015-04-09 15:04:38 -0700
commit4c5e43da7792f75567b693105cc53e3f1992ad98 (patch)
tree1b2c9792582e12f5af0b1512e3094425f0dc0df9 /docs/CommandGuide
parentc75239e6119d0f9a74c57099d91cbc9bde56bf33 (diff)
downloadexternal_llvm-4c5e43da7792f75567b693105cc53e3f1992ad98.zip
external_llvm-4c5e43da7792f75567b693105cc53e3f1992ad98.tar.gz
external_llvm-4c5e43da7792f75567b693105cc53e3f1992ad98.tar.bz2
Update aosp/master llvm for rebase to r233350
Change-Id: I07d935f8793ee8ec6b7da003f6483046594bca49
Diffstat (limited to 'docs/CommandGuide')
-rw-r--r--docs/CommandGuide/FileCheck.rst27
-rw-r--r--docs/CommandGuide/llvm-cov.rst212
-rw-r--r--docs/CommandGuide/llvm-profdata.rst8
3 files changed, 221 insertions, 26 deletions
diff --git a/docs/CommandGuide/FileCheck.rst b/docs/CommandGuide/FileCheck.rst
index af01503..f48bf47 100644
--- a/docs/CommandGuide/FileCheck.rst
+++ b/docs/CommandGuide/FileCheck.rst
@@ -185,6 +185,31 @@ For example, something like this works as you'd expect:
newline between it and the previous directive. A "``CHECK-NEXT:``" cannot be
the first directive in a file.
+The "CHECK-SAME:" directive
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Sometimes you want to match lines and would like to verify that matches happen
+on the same line as the previous match. In this case, you can use "``CHECK:``"
+and "``CHECK-SAME:``" directives to specify this. If you specified a custom
+check prefix, just use "``<PREFIX>-SAME:``".
+
+"``CHECK-SAME:``" is particularly powerful in conjunction with "``CHECK-NOT:``"
+(described below).
+
+For example, the following works like you'd expect:
+
+.. code-block:: llvm
+
+ !0 = !MDLocation(line: 5, scope: !1, inlinedAt: !2)
+
+ ; CHECK: !MDLocation(line: 5,
+ ; CHECK-NOT: column:
+ ; CHECK-SAME: scope: ![[SCOPE:[0-9]+]]
+
+"``CHECK-SAME:``" directives reject the input if there are any newlines between
+it and the previous directive. A "``CHECK-SAME:``" cannot be the first
+directive in a file.
+
The "CHECK-NOT:" directive
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -339,7 +364,7 @@ simply uniquely match a single line in the file being verified.
FileCheck Pattern Matching Syntax
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The "``CHECK:``" and "``CHECK-NOT:``" directives both take a pattern to match.
+All FileCheck directives take a pattern to match.
For most uses of FileCheck, fixed string matching is perfectly sufficient. For
some things, a more flexible form of matching is desired. To support this,
FileCheck allows you to specify regular expressions in matching strings,
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.
diff --git a/docs/CommandGuide/llvm-profdata.rst b/docs/CommandGuide/llvm-profdata.rst
index 0762e2c..45f7073 100644
--- a/docs/CommandGuide/llvm-profdata.rst
+++ b/docs/CommandGuide/llvm-profdata.rst
@@ -15,12 +15,12 @@ data files.
COMMANDS
--------
-* `merge <profdata_merge_>`_
-* `show <profdata_show_>`_
+* :ref:`merge <profdata-merge>`
+* :ref:`show <profdata-show>`
.. program:: llvm-profdata merge
-.. _profdata_merge:
+.. _profdata-merge:
MERGE
-----
@@ -51,7 +51,7 @@ OPTIONS
.. program:: llvm-profdata show
-.. _profdata_show:
+.. _profdata-show:
SHOW
----