| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gnatmetric
The gnatmetric tool is an ASIS-based utility
for computing various program metrics.
It takes an Ada source file as input and generates a file containing the
metrics data as output. Various switches control which
metrics are computed and output.
gnatmetric generates and uses the ASIS
tree for the input source and thus requires the input to be syntactically and
semantically legal.
If this condition is not met, gnatmetric will generate
an error message; no metric information for this file will be
computed and reported.
If the compilation unit contained in the input source depends semantically
upon units in files located outside the current directory, you have to provide
the source search path when invoking gnatmetric.
If it depends semantically upon units that are contained
in files with names that do not follow the GNAT file naming rules, you have to
provide the configuration file describing the corresponding naming scheme (see
the description of the gnatmetric switches below.)
Alternatively, you may use a project file and invoke gnatmetric
through the gnat driver.
The gnatmetric command has the form
$ gnatmetric [switches] {filename} [-cargs gcc_switches]
|
where
gnatmetric Switches).
Including both a `-files' switch and one or more
filename arguments is permitted.
gcc. They will be passed on to all compiler invocations made by
gnatmetric to generate the ASIS trees. Here you can provide
`-I' switches to form the source search path,
and use the `-gnatec' switch to set the configuration file,
use the `-gnat05' switch if sources should be compiled in
Ada 2005 mode etc.
15.1 Switches for gnatmetric
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gnatmetric
The following subsections describe the various switches accepted by
gnatmetric, organized by category.
15.1.1 Output File Control 15.1.2 Disable Metrics For Local Units 15.1.3 Specifying a set of metrics to compute 15.1.4 Other gnatmetricSwitches15.1.5 Generate project-wide metrics
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gnatmetric has two output formats. It can generate a
textual (human-readable) form, and also XML. By default only textual
output is generated.
When generating the output in textual form, gnatmetric creates
for each Ada source file a corresponding text file
containing the computed metrics, except for the case when the set of metrics
specified by gnatmetric parameters consists only of metrics that are computed
for the whole set of analyzed sources, but not for each Ada source.
By default, this file is placed in the same directory as where the source
file is located, and its name is obtained
by appending the `.metrix' suffix to the name of the
input file.
All the output information generated in XML format is placed in a single file. By default this file is placed in the current directory and has the name `metrix.xml'.
Some of the computed metrics are summed over the units passed to
gnatmetric; for example, the total number of lines of code.
By default this information is sent to `stdout', but a file
can be specified with the `-og' switch.
The following switches control the gnatmetric output:
gnatmetric
output includes the name(s) of the Ada source file(s) from which the metrics
are computed. By default each name includes the absolute path. The
`-sfn' switch causes gnatmetric
to exclude all directory information from the file names that are output.)
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gnatmetric relies on the GNAT compilation model -
one compilation
unit per one source file. It computes line metrics for the whole source
file, and it also computes syntax
and complexity metrics for the file's outermost unit.
By default, gnatmetric will also compute all metrics for certain
kinds of locally declared program units:
These kinds of entities will be referred to as eligible local program units, or simply eligible local units, in the discussion below.
Note that a subprogram declaration, generic instantiation, or renaming declaration only receives metrics computation when it appear as the outermost entity in a source file.
Suppression of metrics computation for eligible local units can be obtained via the following switch:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default all the metrics are computed and reported. The switches described in this subsection allow you to control, on an individual basis, whether metrics are computed and reported. If at least one positive metric switch is specified (that is, a switch that defines that a given metric or set of metrics is to be computed), then only explicitly specified metrics are reported.
15.1.3.1 Line Metrics Control 15.1.3.2 Syntax Metrics Control 15.1.3.3 Complexity Metrics Control 15.1.3.4 Object-Oriented Metrics Control
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For any (legal) source file, and for each of its
eligible local program units, gnatmetric computes the following
metrics:
gnatmetric sums the values of the line metrics for all the
files being processed and then generates the cumulative results. The tool
also computes for all the files being processed the average number of code
lines in bodies.
You can use the following switches to select the specific line metrics to be computed and reported.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gnatmetric computes various syntactic metrics for the
outermost unit and for each eligible local unit:
For the outermost unit in the file, gnatmetric additionally computes
the following metrics:
Along with the total number of public types, the following types are counted and reported separately:
By default, all the syntax metrics are computed and reported. You can use the following switches to select specific syntax metrics.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
For a program unit that is an executable body (a subprogram body (including
generic bodies), task body, entry body or a package body containing
its own statement sequence) gnatmetric computes the following
complexity metrics:
The McCabe complexity metrics are defined in http://www.mccabe.com/pdf/nist235r.pdf
According to McCabe, both control statements and short-circuit control forms should be taken into account when computing cyclomatic complexity. For each body, we compute three metric values:
When computing cyclomatic and essential complexity, gnatmetric skips
the code in the exception handlers and in all the nested program units.
By default, all the complexity metrics are computed and reported. For more fine-grained control you can use the following switches:
exit statements as gotos when
computing Essential Complexity
return statements and raise statements in case when the
raised exception is not handled in the same body. In case of a function this
metric subtracts 1 from the number of exit points, because a function body
must contain at least one return statement.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Coupling metrics are object-oriented metrics that measure the dependencies between a given class (or a group of classes) and the "external world" (that is, the other classes in the program). In this subsection the term "class" is used in its traditional object-oriented programming sense (an instantiable module that contains data and/or method members). A category (of classes) is a group of closely related classes that are reused and/or modified together.
A class K's efferent coupling is the number of classes
that K depends upon.
A category's efferent coupling is the number of classes outside the
category that the classes inside the category depend upon.
A class K's afferent coupling is the number of classes
that depend upon K.
A category's afferent coupling is the number of classes outside the
category that depend on classes belonging to the category.
Ada's implementation of the object-oriented paradigm does not use the traditional class notion, so the definition of the coupling metrics for Ada maps the class and class category notions onto Ada constructs.
For the coupling metrics, several kinds of modules -- a library package, a library generic package, and a library generic package instantiation -- that define a tagged type or an interface type are considered to be a class. A category consists of a library package (or a library generic package) that defines a tagged or an interface type, together with all its descendant (generic) packages that define tagged or interface types. For any package counted as a class, its body and subunits (if any) are considered together with its spec when counting the dependencies, and coupling metrics are reported for spec units only. For dependencies between classes, the Ada semantic dependencies are considered. For coupling metrics, only dependencies on units that are considered as classes, are considered.
When computing coupling metrics, gnatmetric counts only
dependencies between units that are arguments of the gnatmetric call.
Coupling metrics are program-wide (or project-wide) metrics, so to
get a valid result, you should call gnatmetric for
the whole set of sources that make up your program. It can be done
by calling gnatmetric from the GNAT driver with `-U'
option (see See 12.2 The GNAT Driver and Project Files for details.
By default, all the coupling metrics are disabled. You can use the following switches to specify the coupling metrics to be computed and reported:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
gnatmetric Switches
Additional gnatmetric switches are as follows:
gnatmetric. You also can combine this switch with
an explicit list of files.
gnatmetric generates version information and then
a trace of sources being processed.
gnatmetric generates various messages useful to understand what
happens during the metrics computation
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In order to compute metrics on all units of a given project, you can use
the gnat driver along with the `-P' option:
gnat metric -Pproj |
If the project proj depends upon other projects, you can compute
the metrics on the project closure using the `-U' option:
gnat metric -Pproj -U |
Finally, if not all the units are relevant to a particular main program in the project closure, you can generate metrics for the set of units needed to create a given main program (unit closure) using the `-U' option followed by the name of the main unit:
gnat metric -Pproj -U main |
| [ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |