From 2f1019880e3fca33b8c7ac8f8bd272e546d930ac Mon Sep 17 00:00:00 2001 From: Vedant Kumar Date: Thu, 22 Sep 2016 15:34:33 +0000 Subject: [PATCH] [docs] Touch up the coverage docs some more git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@282169 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/SourceBasedCodeCoverage.rst | 42 +++++++++++++++----------------- 1 file changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/SourceBasedCodeCoverage.rst b/docs/SourceBasedCodeCoverage.rst index feaf725ac7..abb682355b 100644 --- a/docs/SourceBasedCodeCoverage.rst +++ b/docs/SourceBasedCodeCoverage.rst @@ -61,7 +61,7 @@ To compile code with coverage enabled, pass ``-fprofile-instr-generate % clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo Note that linking together code with and without coverage instrumentation is -supported: any uninstrumented code simply won't be accounted for. +supported. Uninstrumented code simply won't be accounted for in reports. Running the instrumented program ================================ @@ -95,28 +95,22 @@ Creating coverage reports ========================= Raw profiles have to be **indexed** before they can be used to generate -coverage reports. This is done using the "merge" tool in ``llvm-profdata``, so -named because it can combine and index profiles at the same time: +coverage reports. This is done using the "merge" tool in ``llvm-profdata`` +(which can combine multiple raw profiles and index them at the same time): .. code-block:: console # Step 3(a): Index the raw profile. % llvm-profdata merge -sparse foo.profraw -o foo.profdata -There are multiple different ways to render coverage reports. One option is to -generate a line-oriented report: +There are multiple different ways to render coverage reports. The simplest +option is to generate a line-oriented report: .. code-block:: console # Step 3(b): Create a line-oriented coverage report. % llvm-cov show ./foo -instr-profile=foo.profdata -To generate the same report in html with demangling turned on, use: - -.. code-block:: console - - % llvm-cov show ./foo -instr-profile=foo.profdata -format html -o report.dir -Xdemangler c++filt -Xdemangler -n - This report includes a summary view as well as dedicated sub-views for templated functions and their instantiations. For our example program, we get distinct views for ``foo(...)`` and ``foo(...)``. If @@ -145,8 +139,8 @@ region counts (even in macro expansions): | 4| 1|} ------------------ -It's possible to generate a file-level summary of coverage statistics (instead -of a line-oriented report) with: +To generate a file-level summary of coverage statistics instead of a +line-oriented report, try: .. code-block:: console @@ -158,6 +152,11 @@ of a line-oriented report) with: -------------------------------------------------------------------------------------------------------------------------------------- TOTAL 13 0 100.00% 3 0 100.00% 13 0 100.00% +The ``llvm-cov`` tool supports specifying a custom demangler, writing out +reports in a directory structure, and generating html reports. For the full +list of options, please refer to the `command guide +`_. + A few final notes: * The ``-sparse`` flag is optional but can result in dramatically smaller @@ -190,7 +189,7 @@ Interpreting reports There are four statistics tracked in a coverage summary: * Function coverage is the percentage of functions which have been executed at - least once. A function is treated as having been executed if any of its + least once. A function is considered to be executed if any of its instantiations are executed. * Instantiation coverage is the percentage of function instantiations which @@ -200,13 +199,12 @@ There are four statistics tracked in a coverage summary: * Line coverage is the percentage of code lines which have been executed at least once. Only executable lines within function bodies are considered to be - code lines, so e.g coverage for macro definitions in a header might not be - included. + code lines. * Region coverage is the percentage of code regions which have been executed at - least once. A code region may span multiple lines (e.g a large function with - no control flow). However, it's also possible for a single line to contain - multiple code regions or even nested code regions (e.g "return x || y && z"). + least once. A code region may span multiple lines (e.g in a large function + body with no control flow). However, it's also possible for a single line to + contain multiple code regions (e.g in "return x || y && z"). Of these four statistics, function coverage is usually the least granular while region coverage is the most granular. The project-wide totals for each @@ -224,9 +222,9 @@ Format compatibility guarantees These formats are not forwards-compatible: i.e, a tool which uses format version X will not be able to understand format version (X+k). -* There is a third format in play: the format of the coverage mappings emitted - into instrumented binaries. Tools must retain **backwards** compatibility - with these formats. These formats are not forwards-compatible. +* Tools must also retain **backwards** compatibility with the format of the + coverage mappings emitted into instrumented binaries. These formats are not + forwards-compatible. * The JSON coverage export format has a (major, minor, patch) version triple. Only a major version increment indicates a backwards-incompatible change. A -- 2.40.0