9.3. c29cov - Emit Coverage Information¶

The c29cov tool is used to show code coverage information for programs that are instrumented to emit profile data.

9.3.1. Usage¶

c29cov command [arguments]

c29cov - Command used to invoke the code coverage display tool.
command - One of the available c29cov modes of operation: show, report, or export
arguments

9.3.2. Commands¶

9.3.2.1. show¶

c29cov show [options] -instr-profile profile binary [sources]

The c29cov show command shows line by line coverage of one or more binary files using the profile data file. It can optionally be filtered to only show the coverage for the files listed in sources.

A binary can be an executable, an object file, or an archive.

To use c29cov show, you need a program that is compiled with instrumentation to emit profile and coverage data. To build such a program with c29clang use the -fprofile-instr-generate and -fcoverage-mapping flags. If linking with using the c29clang command, the -fprofile-instr-generate option will be passed to the linker 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 c29cov show as a binary 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 c29profdata merge tool.

Options

-show-line-counts¶: Show the execution counts for each line. Defaults to true, unless another -show option is used.

-show-expansions¶: Expand inclusions, such as preprocessor macros or textual inclusions, inline in the display of the source file. Defaults to false.

-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.

-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.

-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.

-use-color¶: Enable or disable color output. By default this is autodetected.

-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.

-name=*<function>*¶: Show code coverage only for named function

-name-allowlist=*<file>*¶: Show code coverage only for functions listed in the given <file>. Each line in the file should start with “allowlist_fun:”, immediately followed by the name of the function to accept. This name can be a wildcard expression.

-filename-allowlist=*<file>*¶: Show code coverage only for files that match a regular expression listed in the given <file>. Each line in the file should start with “allowlist_file:”.

-name-regex=*<pattern>*¶: Show code coverage only for functions that match the given regular expression <pattern>.

-ignore-filename-regex=*<pattern>*¶: Skip source code files with file paths that match the given regular expression <pattern>.

-format=*<format>*¶: Use the specified output <format>. The supported formats are: text or html.

-tab-size=*<size>*¶: Replace tabs with <size> spaces when preparing reports. Currently, this is only supported for the html format.

-output-dir=*<path>*¶: Specify a directory <path> 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.

-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. 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.

-num-threads=*<N>*, -j=*<N>*¶: Use <N> threads to write file reports (only applicable when -output-dir is specified). When N=0, c29cov auto-detects an appropriate number of threads to use. This is the default.

-line-coverage-gt=*<N>*¶: Show code coverage only for functions with line coverage greater than the given threshold <N>.

-line-coverage-lt=*<N>*¶: Show code coverage only for functions with line coverage less than the given threshold <N>.

-region-coverage-gt=*<N>*¶: Show code coverage only for functions with region coverage greater than the given threshold <N>.

-region-coverage-lt=*<N>*¶: Show code coverage only for functions with region coverage less than the given threshold <N>.

-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 c29cov on a different machine where you have the same files on a different path.

9.3.2.2. report¶

c29cov report [options] -instr-profile profile binary [sources]

The c29cov report command displays a summary of the coverage of one or more binary files, using the profile data profile. It can optionally be filtered to only show the coverage for the files listed in sources.

A binary may be an executable, an object file, or an archive.

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.

Options

-use-color[=*<value>*]¶: Enable or disable color output. By default this is autodetected.

-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.

-show-functions¶: Show coverage summaries for each function. Defaults to false.

-show-instantiation-summary¶: Show statistics for all function instantiations. Defaults to false.

-show-call-region-summary¶: Show statistics for all regions containing function calls instantiations. Defaults to false.

-ignore-filename-regex=*<pattern>*¶: Skip source code files with file paths that match the given regular expression <pattern>.

9.3.2.3. export¶

c29cov export [options] -instr-profile profile binary [sources]

The c29cov export command exports coverage data of one or more binary files, using the profile data profile in either JSON, csv, 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. When exporting a csv trace file, an aggregation of data, including summaries as well as individual file and function metrics will be generated.

The exported data can optionally be filtered to only export the coverage for the files listed in sources.

Options

-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.

-format=*<format>*¶: Use the specified output <format>. The supported formats are: text, csv, or lcov. The csv format generates an aggregation of data in a comma-separated format that can be easily imported as an Excel document and saved to correspond with a TI-specific Code Coverage report format.

-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 c29cov report command, but presented in JSON or lcov format rather than text.

-ignore-filename-regex=*<pattern>*¶: Skip source code files with file paths that match the given regular expression <pattern>.

-skip-expansions¶: Skip exporting macro expansion coverage data.

-skip-functions¶: Skip exporting per-function coverage data.

-num-threads=*<N>*, -j=*<N>*¶: Use <N> threads to export coverage data. When N=0, c29cov auto-detects an appropriate number of threads to use. This is the default.

9.3.3. Exit Status¶

c29cov returns 1 if the command is omitted or is invalid, if it cannot read input files, or if there is a mismatch between their data.