gnatcov coverage command lineΒΆ

Coverage analysis with GNATcoverage is performed by invoking gnatcov coverage for a set of critera queried via the --level command line option. The general interface synopsis is available from gnatcov --help:

gnatcov coverage OPTIONS TRACE_FILES

The available options are as follows:

-c, --level (mandatory) :
Tell the set of coverage criteria to be assessed. The possible values are branch and insn for object coverage analysis, and stmt, stmt+decision and stmt+mcdc for source coverage analysis.
-a, --annotate (mandatory) :
Request a specific output report format. All the criteria support xcov[+], html[+], dhtml and report formats, with interpretations that vary depending on the assessed criteria. See the corresponding sections in the Source and Object Coverage Analysis chapters of this documentation for more details.
-o :
Request that the synthetic report produced by --annotate=report be output in the provided filname instead of standard output by default. This is just ignored for other output formats.
--output-dir :
Request that the report files (index and annotated sources for the xcov, html and dhtml output formats) be output in the provided directory. If not specified, the default is the root project’s object directory if using projects, and the current directory if not. The directory must exist prior to invoking gnatcov.
--report-title :
Request that generated HTML documents (index and annotated sources for the html and dhtml output formats) are assigned a customized title. For instance, passing --report-title="Project ABC" will yield titles such as: Project ABC - GNATcoverage Report. If passed multiple times, passing an empty string last will restore the default behavior. This option is ignored is the selected output format does not support titles.
-t, --target :
State the target architecture/board/abi for which the analyzed program was built. This corresponds to the target prefix of your compilation toolchain, for example powerpc-elf or leon-elf, and can also be specified as a Target attribute within the project file designated by -P, if any. By default, gnatcov assumes that this target is the same as the host environment. Stating the correct target is required for correct processing of project files.
-T, --trace (mandatory), possibly repeated and accepting @listfile arguments :
Provide the set of execution traces for which a report is to be produced. When multiple traces are provided, gnatcov produces a consolidated result, as if there had been a single execution producing one trace that would have been the catenation of all the individual traces. See the Coverage Consolidation section for a description of the consolidation facility.
--exec:
Override executable from traces. Trace files contain an indication of the executable used to generate them. This option causes the named executable to be loaded for coverage analysis, and to override the indication contained in any trace specified after it on the command line. An empty executable name may be specified to restore the default behaviour of using the indication contained in each trace file. Note that --exec may appear last on the command line, in which case it applies to no trace file, but still causes the indicated executable to be included in the coverage analysis. This ensures that any code in that executable that is not exercised by some trace file will be reported as not covered.
--routines, possibly repeated and accepting @listfile arguments:
For object coverage analysis specifically, provide the list of object symbol names that correspond to routines for which the coverage assessment is to be performed. Each instance of this option on the command line adds to what is to be assessed eventually. See the Focusing on subprograms of interest (–routines) section for extra details and use examples.
-P:
Use the indicated project file as the root project to select the units of interest for the analysis and find default options. Default options are taken only from this project. In absence of --projects and of --no-subprojects, the units of interest are those designated by this project and all it’s transitive dependencies, minus those advertised as externally-built.
--non-coverable:
For source coverage analysis specifically, report about language statements for which no object code could be found in the surrounding suprogram (typically out of optimization).
--projects, possibly repeated and accepting @listfile arguments: When using -P, use the provided
projects to select units of interest, together with their transitive dependencies unless --no-subprojects is provided as well. The projects designated by --projects must all be part of the import transitive closure reachable from the root project designated by -P.
--no-subprojects:
Consider only the projects (and units) encompassed by the -P / --projects options as of-interest. Don’t include any project imported from there.
--units, possibly repeated and accepting @listfile arguments:
When using project files, override the list of units of interest for source coverage with those provided.
--subdirs:
When using project files, look for Library Information files in the indicated subdirectory of each project’s object directory.
--scos, possibly repeated and accepting @listfile arguments:
For source coverage analysis specifically, provide the set of Library Information files from which Source Coverage Obligations (SCOs) should be loaded. This low-level switch effectively overrides the project based units of interest selection by the -P family of options.
--alis, possibly repeated and accepting @listfile arguments:
Similar to --scos in primary intent: provide set of Library Information files. This is complementary to --scos for operations that rely on library information items and don’t require Source Coverage Obligations, in particular for gathering exemption regions applicable to object level criteria.
--ignore-source-files, possibly repeated and accepting @listfile arguments:
For source coverage analysis specifically, provide a list of globbing patterns (as in Unix or DOS shells). All source files whose name matches one pattern are excluded from the analysis, and from the output report. See the Ada subunits (“separates”) section for more information.
--save-checkpoint:
For source coverage analysis specifically, save the resulting coverage analysis to the named checkpoint file. It can then be consolidated in subsequent runs of the coverage using --checkpoint.
--checkpoint, possibly repeated and accepting @listfile arguments:
Load previously saved coverage analysis checkpoint(s), and continue coverage analysis from that initial state.

A lot of options are available to control the set of units for which coverage is to be assessed. They may be combined in multiple ways and attributed within the project files are available to refine the set of units to include or exclude from each designated project. See Using project files for a general overview of how the project file facilities operate and Specifying the units of interest for extra details and examples of use.

Saving coverage analysis state checkpoints allows the production of consolidated results from successive runs of the coverage command. In particular this allows coverage results to be computed incrementally, and allows consolidation with different sets of units of interest, in order to avoid incidental coverage. See Coverage State Checkpoints for a discussion of these use cases.

Elements on the command line that are not tied to a particular option are considered as trace file arguments. At least one trace file is required for the coverage command to operate, which may but need not be introduced with -T or --trace. Here are a few examples of valid command lines to illustrate. Other examples will be exposed along the course of the following sections:

gnatcov coverage --level=stmt --scos=@alis --annotate=report --trace=prog.trace
#                      (a)         (b)              (c)            (d)
# (a) Request Statement coverage assessment,
# (b) for units associated with the ALI files listed in the "alis" text file,
# (c) producing a synthetic text report on standard output (no -o option),
# (d) out of a single execution trace "prog.trace".

gnatcov coverage --level=stmt+decision --scos=@alis --annotate=html t1 t2
# Statement and Decision coverage assessments for two traces "t1" and "t2",
# producing html report files in the current directory.

gnatcov coverage --level=stmt+decision --scos=@alis --annotate=html @mytraces
# Same report, with t1 and t2 listed in the "mytraces" text file

gnatcov coverage --level=stmt -Papp.gpr --annotate=html @mytraces
# Same kind of report, for Statement coverage only, on source units owned
# by "app.gpr" and its transitive closure of project dependencies.

gnatcov coverage --level=stmt -Papp.gpr --no-subprojects --annotate=html @mytraces
# Likewise, considering only the units owned by app.gpr