Lines Matching +full:html +full:- +full:export
2 Source-based Code Coverage
11 This document explains how to use clang's source-based code coverage feature.
12 It's called "source-based" because it operates on AST and preprocessor
17 * :doc:`SanitizerCoverage` - A low-overhead tool meant for use alongside the
18 various sanitizers. It can provide up to edge-level coverage.
20 * gcov - A GCC-compatible coverage implementation which operates on DebugInfo.
21 This is enabled by ``-ftest-coverage`` or ``--coverage``.
23 From this point onwards "code coverage" will refer to the source-based kind.
36 The next few sections work through a complete, copy-'n-paste friendly example
39 .. code-block:: cpp
56 To compile code with coverage enabled, pass ``-fprofile-instr-generate
57 -fcoverage-mapping`` to the compiler:
59 .. code-block:: console
62 % clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo
68 pass ``-fcoverage-mcdc`` in addition to the clang options specified above.
79 ``LLVM_PROFILE_FILE`` contains a path to a non-existent directory, the missing
92 on-line profile merging. The runtime takes care of selecting a raw profile
106 .. code-block:: console
131 other platforms by passing the ``-runtime-counter-relocation`` option to the
134 For a program such as the `Lit <https://llvm.org/docs/CommandGuide/lit.html>`_
140 .. code-block:: console
142 …% clang++ -fprofile-instr-generate -fcoverage-mapping -mllvm -runtime-counter-relocation foo.cc -o…
148 coverage reports. This is done using the "merge" tool in ``llvm-profdata``
151 .. code-block:: console
154 % llvm-profdata merge -sparse foo.profraw -o foo.profdata
157 …M `coverage build script <https://github.com/llvm/llvm-zorg/blob/main/zorg/jenkins/jobs/jobs/llvm-…
160 option is to generate a line-oriented report:
162 .. code-block:: console
164 # Step 3(b): Create a line-oriented coverage report.
165 % llvm-cov show ./foo -instr-profile=foo.profdata
167 This report includes a summary view as well as dedicated sub-views for
170 ``-show-line-counts-or-regions`` is enabled, ``llvm-cov`` displays sub-line
173 .. code-block:: none
181 ------------------
187 ------------------
193 ------------------
195 If ``--show-branches=count`` and ``--show-expansions`` are also enabled, the
196 sub-views will show detailed branch coverage information in addition to the
199 .. code-block:: none
201 ------------------
206 | ------------------
209 | | | ------------------
212 | | | ------------------
213 | ------------------
215 | ------------------
217 ------------------
220 (MC/DC) using the clang option ``-fcoverage-mcdc``, an MC/DC subview can be
221 enabled using ``--show-mcdc`` that will show detailed MC/DC information for
224 To generate a file-level summary of coverage statistics instead of a
225 line-oriented report, try:
227 .. code-block:: console
230 % llvm-cov report ./foo -instr-profile=foo.profdata
232 …--------------------------------------------------------------------------------------------------…
234 …--------------------------------------------------------------------------------------------------…
237 The ``llvm-cov`` tool supports specifying a custom demangler, writing out
238 reports in a directory structure, and generating html reports. For the full
240 <https://llvm.org/docs/CommandGuide/llvm-cov.html>`_.
244 * The ``-sparse`` flag is optional but can result in dramatically smaller
253 * The ``llvm-profdata`` tool can be used to merge together multiple raw or
257 .. code-block:: console
259 % llvm-profdata merge -sparse foo1.profraw foo2.profdata -o foo3.profdata
264 Coverage data can be exported into JSON using the ``llvm-cov export``
265 sub-command. There is a comprehensive reference which defines the structure of
266 the exported data at a high level in the llvm-cov source code.
281 enabled via the ``-show-instantiation-summary`` option.
308 short-circuit semantics). MC/DC builds on top of branch coverage and
311 ``-show-mcdc-summary`` option as long as code was also compiled using the
312 clang option ``-fcoverage-mcdc``.
320 function implies 100% region coverage for a function. The project-wide totals
332 These formats are not forwards-compatible: i.e, a tool which uses format
337 forwards-compatible.
339 * The JSON coverage export format has a (major, minor, patch) version triple.
340 Only a major version increment indicates a backwards-incompatible change. A
364 * Export a ``int __llvm_profile_runtime`` symbol from each instrumented shared
369 * Forward-declare ``void __llvm_profile_initialize_file(void)`` and call it
377 * Forward-declare ``int __llvm_profile_write_file(void)`` and call it to write
378 out a profile. This function returns 0 when it succeeds, and a non-zero value
380 existing on-disk raw profile.
385 ------------------------------------------------
392 The first step is to export ``__llvm_profile_runtime``, as above, to disable
397 * Forward-declare ``uint64_t __llvm_profile_get_size_for_buffer(void)`` and
401 * Forward-declare ``int __llvm_profile_write_buffer(char *Buffer)`` and call it
405 * Optionally, forward-declare ``void __llvm_profile_reset_counters(void)`` and
415 To prepare a coverage report for llvm (and any of its sub-projects), add
416 ``-DLLVM_BUILD_INSTRUMENTED_COVERAGE=On`` to the cmake configuration. Raw
417 profiles will be written to ``$BUILD_DIR/profiles/``. To prepare an html
418 report, run ``llvm/utils/prepare-code-coverage-artifact.py``.
421 ``-DLLVM_PROFILE_DATA_DIR``. To change the size of the profile merge pool, use
422 ``-DLLVM_PROFILE_MERGE_POOL_SIZE``.
428 compiled with ``-fcoverage-mapping`` in its ``--gc-sections`` mode. Possible
429 workarounds include disabling ``--gc-sections``, upgrading to a newer version
436 .. code-block:: cpp
454 -----------
466 --------------
467 When viewing branch coverage details in source-based file-level sub-views using
468 ``--show-branches``, it is recommended that users show all macro expansions
469 (using option ``--show-expansions``) since macros may contain hidden branch
470 conditions. The coverage summary report will always include these macro-based
475 branches are not generated for these cases. In the source-based file-level
476 sub-view, these branches will simply be shown as ``[Folded - Ignored]`` so that
479 Branch coverage is tied directly to branch-generating conditions in the source
484 ---------------------
487 clang option ``-fcoverage-mcdc``, there are two hard limits.
491 use ``-Xclang -fmcdc-max-conditions=n``. Expressions with exceeded condition
499 expression with ``-Xclang -fmcdc-max-test-vectors=m``.
514 expression but separated by a non-logical operator, this is also not supported.
521 -----------------