14. The GNAT Metric Tool 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

• switches specify the metrics to compute and define the destination for the output

• Each filename is the name (including the extension) of a source file to process. "Wildcards" are allowed, and the file name may contain path information. If no filename is supplied, then the switches list must contain at least one `-files' switch (see section 14.1.6 Other gnatmetric Switches). Including both a `-files' switch and one or more filename arguments is permitted.

• -cargs gcc_switches is a list of switches for 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.

14.1 Switches for gnatmetric

14.1 Switches for gnatmetric

The following subsections describe the various switches accepted by gnatmetric, organized by category.

14.1.1 Output File Control
14.1.2 Disable Metrics For Local Units
14.1.3 Line Metrics Control
14.1.4 Syntax Metrics Control
14.1.5 Complexity Metrics Control
14.1.6 Other gnatmetric Switches

14.1.1 Output File Control

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

`-x'

Generate the XML output

`-nt'

Do not generate the output in text form (implies `-x')

`-d output_dir'

Put textual files with detailed metrics into output_dir

`-o file_suffix'

Use file_suffix, instead of `.metrix' in the name of the output file.

`-og file_name'

Put global metrics into file_name

`-ox file_name'

Put the XML output into file_name (also implies `-x')

`-sfn'

Use "short" source file names in the output. (The 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.)

14.1.2 Disable Metrics For Local Units

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:

• subprogram (and generic subprogram) bodies;

• package (and generic package) specifications and bodies;

• task object and type specifications and bodies;

• protected object and type specifications and bodies.

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:

`-nolocal'

Do not compute detailed metrics for eligible local program units

14.1.3 Line Metrics Control

For any (legal) source file, and for each of its eligible local program units, gnatmetric computes the following metrics:

• the total number of lines;

• the total number of code lines (i.e., non-blank lines that are not comments)

• the number of comment lines

• the number of code lines containing end-of-line comments;

• the number of empty lines and lines containing only space characters and/or format effectors (blank lines)

If gnatmetric is invoked on more than one source file, it sums the values of the line metrics for all the files being processed and then generates the cumulative results.

By default, all the line metrics are computed and reported. You can use the following switches to select the specific line metrics to be computed and reported (if any of these parameters is set, only explicitly specified line metrics are computed).

`-la'

The number of all lines

`-lcode'

The number of code lines

`-lcomm'

The number of comment lines

`-leol'

The number of code lines containing end-of-line comments

`-lb'

The number of blank lines

14.1.4 Syntax Metrics Control

gnatmetric computes various syntactic metrics for the outermost unit and for each eligible local unit:

LSLOC ("Logical Source Lines Of Code")

The total number of declarations and the total number of statements

Maximal static nesting level of inner program units

According to Ada 95 Language Reference Manual, 10.1(1), "A program unit is either a package, a task unit, a protected unit, a protected entry, a generic unit, or an explicitly declared subprogram other than an enumeration literal."

Maximal nesting level of composite syntactic constructs

This corresponds to the notion of the maximum nesting level in the GNAT built-in style checks (see section 3.2.5 Style Checking)

For the outermost unit in the file, gnatmetric additionally computes the following metrics:

Public subprograms

This metric is computed for package specifications. It is the number of subprograms and generic subprograms declared in the visible part (including in nested packages, protected objects, and protected types).

All subprograms

This metric is computed for bodies and subunits. The metric is equal to a total number of subprogram bodies in the compilation unit. Neither generic instantiations nor renamings-as-a-body nor body stubs are counted. Any subprogram body is counted, independently of its nesting level and enclosing constructs. Generic bodies and bodies of protected subprograms are counted in the same way as "usual" subprogram bodies.

Public types

This metric is computed for package specifications and generic package declarations. It is the total number of types that can be referenced from outside this compilation unit, plus the number of types from all the visible parts of all the visible generic packages. Generic formal types are not counted. Only types, not subtypes, are included.

Along with the total number of public types, the following types are counted and reported separately:

• Abstract types

• Root tagged types (abstract, non-abstract, private, non-private). Type extensions are not counted

• Private types (including private extensions)

• Task types

• Protected types

All types

This metric is computed for any compilation unit. It is equal to the total number of the declarations of different types given in the compilation unit. The private and the corresponding full type declaration are counted as one type declaration. Incomplete type declarations and generic formal types are not counted. No distinction is made among different kinds of types (abstract, private etc.); the total number of types is computed and reported.

By default, all the syntax metrics are computed and reported. You can use the following switches to select specific syntax metrics; if any of these is set, only the explicitly specified metrics are computed.

`-ed'

The total number of declarations

`-es'

The total number of statements

`-eps'

The number of public subprograms in a compilation unit

`-eas'

The number of all the subprograms in a compilation unit

`-ept'

The number of public types in a compilation unit

`-eat'

The number of all the types in a compilation unit

`-enu'

The maximal program unit nesting level

`-ec'

The maximal construct nesting level

14.1.5 Complexity Metrics Control

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:

• McCabe cyclomatic complexity;

• McCabe essential complexity;

• maximal loop nesting level

The McCabe complexity metrics are defined in 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:

• the complexity introduced by control statements only, without taking into account short-circuit forms,

• the complexity introduced by short-circuit control forms only, and

• the total cyclomatic complexity, which is the sum of these two 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 finely-grained control you can use the following switches:

`-nocc'

Do not compute the McCabe Cyclomatic Complexity

`-noec'

Do not compute the Essential Complexity

`-nonl'

Do not compute maximal loop nesting level

`-ne'

Do not consider exit statements as gotos when computing Essential Complexity

14.1.6 Other gnatmetric Switches

Additional gnatmetric switches are as follows:

`-files filename'

Take the argument source files from the specified file. This file should be an ordinary textual file containing file names separated by spaces or line breaks. You can use this switch more then once in the same call to gnatmetric. You also can combine this switch with an explicit list of files.

`-v'

Verbose mode; gnatmetric generates version information and then a trace of sources being procesed.

`-dv'

Debug mode; gnatmetric generates various messages useful to understand what happens during the metrics computation

`-q'

Quiet mode.