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
andinsn
for object coverage analysis, andstmt
,stmt+decision
andstmt+mcdc
for source coverage analysis. -a
,--annotate
(mandatory) :- Request a specific output report format. All the criteria support
xcov[+]
,html[+]
,dhtml
andreport
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
anddhtml
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
anddhtml
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
orleon-elf
, and can also be specified as aTarget
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