diff options
Diffstat (limited to 'gnu/llvm/docs/CommandGuide/llvm-cov.rst')
| -rw-r--r-- | gnu/llvm/docs/CommandGuide/llvm-cov.rst | 416 |
1 files changed, 0 insertions, 416 deletions
diff --git a/gnu/llvm/docs/CommandGuide/llvm-cov.rst b/gnu/llvm/docs/CommandGuide/llvm-cov.rst deleted file mode 100644 index 71924e997d9..00000000000 --- a/gnu/llvm/docs/CommandGuide/llvm-cov.rst +++ /dev/null @@ -1,416 +0,0 @@ -llvm-cov - emit coverage information -==================================== - -SYNOPSIS --------- - -:program:`llvm-cov` *command* [*args...*] - -DESCRIPTION ------------ - -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. - -COMMANDS --------- - -* :ref:`gcov <llvm-cov-gcov>` -* :ref:`show <llvm-cov-show>` -* :ref:`report <llvm-cov-report>` -* :ref:`export <llvm-cov-export>` - -.. 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 -information (``-g``) and without optimization (``-O0``); otherwise, the -coverage data cannot be accurately mapped back to the source code. - -At the time you compile the instrumented code, a ``.gcno`` data file will be -generated for each object file. These ``.gcno`` files contain half of the -coverage data. The other half of the data comes from ``.gcda`` files that are -generated when you run the instrumented program, with a separate ``.gcda`` -file for each object file. Each time you run the program, the execution counts -are summed into any existing ``.gcda`` files, so be sure to remove any old -files if you do not want their contents to be included. - -By default, the ``.gcda`` files are written into the same directory as the -object files, but you can override that by setting the ``GCOV_PREFIX`` and -``GCOV_PREFIX_STRIP`` environment variables. The ``GCOV_PREFIX_STRIP`` -variable specifies a number of directory components to be removed from the -start of the absolute path to the object file directory. After stripping those -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 :program:`llvm-cov gcov` expects to find them. - -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 ``.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 - - Display all basic blocks. If there are multiple blocks for a single line of - source code, this option causes llvm-cov to show the count for each block - instead of just one count for the entire line. - -.. option:: -b, --branch-probabilities - - Display conditional branch probabilities and a summary of branch information. - -.. option:: -c, --branch-counts - - Display branch counts instead of probabilities (requires -b). - -.. option:: -f, --function-summaries - - Show a summary of coverage for each function instead of just one summary for - an entire source file. - -.. option:: --help - - Display available options (--help-hidden for more). - -.. option:: -l, --long-file-names - - For coverage output of files included from the main source file, add the - main file name followed by ``##`` as a prefix to the output file names. This - can be combined with the --preserve-paths option to use complete paths for - both the main file and the included file. - -.. option:: -n, --no-output - - Do not output any ``.gcov`` files. Summary information is still - displayed. - -.. option:: -o=<DIR|FILE>, --object-directory=<DIR>, --object-file=<FILE> - - Find objects in DIR or based on FILE's path. If you specify a particular - object file, the coverage data files are expected to have the same base name - with ``.gcno`` and ``.gcda`` extensions. If you specify a directory, the - files are expected in that directory with the same base name as the source - file. - -.. option:: -p, --preserve-paths - - Preserve path components when naming the coverage output files. In addition - to the source file name, include the directories from the path to that - file. The directories are separate by ``#`` characters, with ``.`` directories - removed and ``..`` directories replaced by ``^`` characters. When used with - the --long-file-names option, this applies to both the main file name and the - included file name. - -.. option:: -u, --unconditional-branches - - Include unconditional branches in the output for the --branch-probabilities - option. - -.. option:: -version - - 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* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*] - -DESCRIPTION -^^^^^^^^^^^ - -The :program:`llvm-cov show` command shows line by line coverage of the -binaries *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 is 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 a *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. Defaults to true, 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. Defaults to false. - -.. 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. - Defaults to true. - -.. option:: -show-regions - - Show the execution counts for each region by displaying a caret that points to - the character where the region starts. Defaults to false. - -.. 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. - Defaults to false. - -.. option:: -use-color - - Enable or disable color output. By default this is autodetected. - -.. option:: -arch=[*NAMES*] - - Specify a list of architectures such that the Nth entry in the list - corresponds to the Nth specified binary. If the covered object is a universal - binary, this specifies the architecture to use. It is an error to specify an - architecture that is not included in the universal binary or to use an - architecture that does not match a non-universal binary. - -.. option:: -name=<NAME> - - Show code coverage only for functions with the given name. - -.. option:: -name-whitelist=<FILE> - - Show code coverage only for functions listed in the given file. Each line in - the file should start with `whitelist_fun:`, immediately followed by the name - of the function to accept. This name can be a wildcard expression. - -.. option:: -name-regex=<PATTERN> - - Show code coverage only for functions that match the given regular expression. - -.. option:: -ignore-filename-regex=<PATTERN> - - Skip source code files with file paths that match the given regular expression. - -.. option:: -format=<FORMAT> - - Use the specified output format. The supported formats are: "text", "html". - -.. option:: -tab-size=<TABSIZE> - - Replace tabs with <TABSIZE> spaces when preparing reports. Currently, this is - only supported for the html format. - -.. option:: -output-dir=PATH - - Specify a directory to write coverage reports into. If the directory does not - exist, it is created. When used in function view mode (i.e when -name or - -name-regex are used to select specific functions), the report is written to - PATH/functions.EXTENSION. When used in file view mode, a report for each file - is written to PATH/REL_PATH_TO_FILE.EXTENSION. - -.. option:: -Xdemangler=<TOOL>|<TOOL-OPTION> - - Specify a symbol demangler. This can be used to make reports more - human-readable. This option can be specified multiple times to supply - arguments to the demangler (e.g `-Xdemangler c++filt -Xdemangler -n` for C++). - The demangler is expected to read a newline-separated list of symbols from - stdin and write a newline-separated list of the same length to stdout. - -.. option:: -num-threads=N, -j=N - - Use N threads to write file reports (only applicable when -output-dir is - specified). When N=0, llvm-cov auto-detects an appropriate number of threads to - use. This is the default. - -.. 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. - -.. option:: -path-equivalence=<from>,<to> - - Map the paths in the coverage data to local source file paths. This allows you - to generate the coverage data on one machine, and then use llvm-cov on a - different machine where you have the same files on a different path. - -.. program:: llvm-cov report - -.. _llvm-cov-report: - -REPORT COMMAND --------------- - -SYNOPSIS -^^^^^^^^ - -:program:`llvm-cov report` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*] - -DESCRIPTION -^^^^^^^^^^^ - -The :program:`llvm-cov report` command displays a summary of the coverage of -the binaries *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 can be shown for each -function in the listed files if the ``-show-functions`` option is enabled. - -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. - -.. option:: -arch=<name> - - If the covered binary is a universal binary, select the architecture to use. - It is an error to specify an architecture that is not included in the - universal binary or to use an architecture that does not match a - non-universal binary. - -.. option:: -show-functions - - Show coverage summaries for each function. Defaults to false. - -.. option:: -show-instantiation-summary - - Show statistics for all function instantiations. Defaults to false. - -.. option:: -ignore-filename-regex=<PATTERN> - - Skip source code files with file paths that match the given regular expression. - -.. program:: llvm-cov export - -.. _llvm-cov-export: - -EXPORT COMMAND --------------- - -SYNOPSIS -^^^^^^^^ - -:program:`llvm-cov export` [*options*] -instr-profile *PROFILE* *BIN* [*-object BIN,...*] [[*-object BIN*]] [*SOURCES*] - -DESCRIPTION -^^^^^^^^^^^ - -The :program:`llvm-cov export` command exports coverage data of the binaries -*BIN*,... using the profile data *PROFILE* in either JSON or lcov trace file -format. - -When exporting JSON, the regions, functions, expansions, and summaries of the -coverage data will be exported. When exporting an lcov trace file, the -line-based coverage and summaries will be exported. - -The exported data can optionally be filtered to only export the coverage -for the files listed in *SOURCES*. - -For information on compiling programs for coverage and generating profile data, -see :ref:`llvm-cov-show`. - -OPTIONS -^^^^^^^ - -.. option:: -arch=<name> - - If the covered binary is a universal binary, select the architecture to use. - It is an error to specify an architecture that is not included in the - universal binary or to use an architecture that does not match a - non-universal binary. - -.. option:: -format=<FORMAT> - - Use the specified output format. The supported formats are: "text" (JSON), - "lcov". - -.. option:: -summary-only - - Export only summary information for each file in the coverage data. This mode - will not export coverage information for smaller units such as individual - functions or regions. The result will contain the same information as produced - by the :program:`llvm-cov report` command, but presented in JSON or lcov - format rather than text. - -.. option:: -ignore-filename-regex=<PATTERN> - - Skip source code files with file paths that match the given regular expression. |