Contents
--------

1. What is gnatmetric
2. gnatmetric parameters
3. Metrics computed by gnatmetric
   3.1 Source files and program units
   3.2 Line metrics
   3.3. Syntax metrics
        3.3.1 Counting declarations and statements.
        3.3.2 Counting subprograms and types
        3.3.3 Counting program unit nesting level
        3.3.4 Computing Complexity metrics
4. Using projects with gnatmetric
5. Examples of the metrics report generated by gnatmetric


1. What is gnatmetric
   ------------------

gnatmetric is the GNAT metrics command-line-based tool. It takes a set of
compilable Ada sources as input, computes for them various programming metrics
and generates the output. Argument Ada sources may be provided as command line
arguments, or you can place the names of the Ada sources to compute the
metrics for into a textual file and to provide the name of this file as the
parameter of '-files' option.

gnatmetric has two output formats. It can generate the output in textual
(human-readable) form and in XML form. By default only textual output is
generated.

When generating the output in textual form, gnatmetric creates for each
argument Ada source file the corresponding textual file containing metrics
computed for the Ada unit contained in this file (line number, statement
number, complexity metrics etc.) By default, the name of this file is the name
of the argument file appended with '.metrix' ($METRIX for OpenVMS) suffix.
You can set another suffix as parameter of '-o' option.

By default, the textual file with the detailed metrics is placed in the same
directory where the argument Ada source file is located. You can set a
specific directory to place these detailed metrics files in by '-d' option.

Some of the computed metrics are summed over the units passed to gnatmetric
(for example, the total number of code lines is counted for all the sources
being processed). The results are placed into a file which can be set as a
parameter of -og option. If -og option is not set, this information is sent to
stdout.

When generating the metric output in XML format, gnatmetric puts all the
results into a single file. By default this output is placed into the file
named metrix.xml (METRIX$XML in OpenVMS). The name of the file to place the
XML output into may be specified with -ox option.

All diagnostic information and all information demonstrating the
progress in processing the given set of sources is sent to stderr.

gnatmetric is an ASIS-based tool. It compiles the given source to create the
corresponding tree file (all these compilations take place in the temporary
directory, this directory is created in the beginning of gnatmetric run and it
is deleted when the processing of the argument sources is completed). If a
source file specified as gnatmetric argument does not contain a legal Ada
program unit, gnatmetric cannot process it. If the specified source contains
an Ada unit which depends on Ada units located in other directories, the user
can specify the source search path by means of a -I gnatmetric option in the
same way as the source search path can be specified for GNAT.


2. gnatmetric parameters
   ---------------------

gnatmetric has the following command-line interface:

    gnatmetric [options] filename

gnatmetric options;

-v    - verbose mode
-q    - quiet mode
-dv   - generate debug output
-dd   - generate progress indicator-style messages

-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

 -nolocal - do not compute detailed metrics for local program units

line metrics (when not specified explicitly, all line metrics are set on,
otherwise only specified metrics are computed):
 -la    - compute and print out the number of all lines
 -lcode - compute and print out the number of code lines
 -lcomm - compute and print out the number of comment lines
 -leol  - compute and print out the number of code lines also containing
          comments (that is, End-OF-Line comments)
 -lb    - compute and print out the number of blank lines

element metrics (when not specified explicitly, all element metrics are set
on, otherwise only specified metrics are computed):
 -ed  - compute and print out the total number of declarations
 -es  - compute and print out 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

output file control:
 -d dirname     - put files with detailed metrics into 'dirname'
 -x             - generate the XML output
 -nt            - do not generate the output in text form, implies '-x'

 -o file-suffix - the suffix for the file to put the detailed metrics for a
                  source file (file-suffix should follow the OS file name
                  conventions
 -og filename   - the name of the file to put the global metrics info into
 -ox filename   - the name of the file to put the XML output into, implies '-x'
 -sfn           - use short source file name in the output

 -I<dir>       - the same as gcc -I option
 -I-           - the same as gcc -I- option
 -gnatec<path> - the same as GNAT -gnatec option

filename - the name of the Ada source file(s) for which metrics should be
computed. Wildcards are allowed

-files filemane - the name of the text file containing a list of Ada
                  source files for which metrics should be computed. This file
                  should contain names of the argument sources separated by
                  spaces and/or end of lines.

3. Metrics computed by gnatmetric
   ------------------------------

3.1 Source files and program units

Gnatmetric relies on the GNAT compilation model - one compilation unit per one
source file. It computes some metrics for the whole source file (mostly
"number of lines" metrics) and it always computes metrics for the top
program unit of the corresponding compilation unit. Metric computation for
nested program units may be turned off with -nolocal parameter.

gnatmetric considers the following constructs as program units to compute
metrics for:
  - a library item or a subunit into a compilation unit;
  - all kinds of bodies;
  - declarations of tasks and protected types and objects, package and generic
    package declarations;

That is, a subprogram declaration, a generic instantiation or a renaming is
considered as a program unit only if it is a library item of a compilation
unit.

3.2 Line metrics

For any source file containing a legal compilation unit, gnatmetric computes
the following metrics:

 - the number of all lines in the file;
 - the number of lines containing at least one character belonging to
   (non-comment) Ada (code lines);
 - the number of comment lines
 - the number of code lines containing a comment as well (or, in other words,
   the number of lines containing end-of-line comments;
 - the number of empty lines and lines containing only space characters and/or
   format effectors (blank lines)

The same metrics are computed for any program unit.

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

3.3. Syntax metrics

For program units gnatmetric computes the total number of declarations, the
total number of statements and complexity metrics. The sum of all the
statements and all the declarations is considered as LSLOC (Logical Source
Lines Of Code) and is reported as a separate metric. For library-level
program units gnatmetric also computes the number of public procedures and
the number of all the subprogram bodies. If gnatmetric processes more than one
source, it computes the total number of declarations, the total number of
statements and the total LSLOC for all the units being processed. If the
set of units processed by gnatmetric contains at least two units
defining public subprograms, gnatmetric computes and outputs the total
number of public subprograms as a global metric. The same holds for
subprogram bodies: if there are two or more compilation units containing
subprogram bodies, the total number of subprogram bodies is reported.

3.3.1 Counting declarations and statements

Statements are computed according to the definition of the notion "statement"
in RM 95.

All the declarations and statements being components of the syntax structure
of a given program unit are counted when computing metrics for this program
unit. That is, all the declarations and statements from the nested units are
counted, for a record type declarations all the component declarations are
counted as separate declarations and so on.

3.3.2 Counting subprograms and types

gnatmetric counts two subprogram-related values. The first represents
the number of public subprograms - that is, subprograms which can be called
outside the unit. The second represents the total number of the different
subprogram implementations, or subprogram bodies.

gnatmetric also counts two values related to types. The first one represents
the number of public types - that is, types which can be used by "withing"
the given unit. The second one represents the total number of different types
declared in the unit.

All these metrics can be computed for any program unit, including nested in
other units. But gnatmetric computes them only for the program units being
top-level units in compilation units (that is, for library items and
subunits). Having this in mind, in the detailed definitions of these
metrics below we will be saying that these metrics are computed for
compilation units.

- "Public subprograms" metric:

    - This metric is computed for non-private compilation units only.

    - This metric is computed for any compilation unit containing as a library
      unit:
       - a package declaration;
       - a subprogram declaration or a subprogram body if this body acts as
         the declaration of the subprogram;
       - a generic subprogram declaration;
       - a generic package declaration;

    - For subprogram declaration, generic subprogram declaration and
      subprogram body which acts as a subprogram declaration the corresponding
      metric is equal to 1 (we need this to compute the whole number of
      public subprograms for a set of compilation units).

    - For a package or a generic package declaration, the value of this
      metric is equal to the number of subprograms and general subprograms
      declared in the visible part of the package, including subprograms
      and generic subprograms declared in visible parts of nested packages,
      generic packages, protected types or objects (recursively).

    - Neither generic instantiations nor renamings are counted. If the
      body of some subprogram defined in the visible part of some package
      is defined by renaming-as-a-body, this subprogram is counted.

    - Protected subprograms are counted in the same way as non-protected ones.

- "All subprograms" metric:

    - This metric is computed for all the compilation units having as a library
      item a body or being a subunit.

    - This 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 enclosing
      context. Generic bodies and bodies of protected subprograms are counted
      in the same way as "usual" subprogram bodies.

    - For a subprogram body which is a library item and which also acts as the
      declaration of the subprogram, this body is counted both as an public
      subprogram and as a subprogram body

- "Public type" metric:

  - this metric is computed only for non-private package declarations and
    generic package declarations;

  - this metric is equal to the total number of types which can be referenced
    from outside this compilation unit (that is, declared in the visible part
    of this (generic) package and in the visible parts of all the nested
    (generic) packages;

  - in case of an incomplete type, this type is not counted (because the
    same visible part has to contain the corresponding full declaration);

  - generic formal types are not counted;

  - along with counting the total number of public types, the following
    types are counted and reported separately
     - abstract types
     - tagged types (abstract, non-abstract, private, non-private). Type
       extensions are NOT counted as tagged types - the idea is to count
       possible roots for classes of extendable types;
     - private types (including private extensions)
     - task types
     - protected types

- "All types"

   - This metric is computed for any compilation unit which may have type
     declarations as its components;

   - this metric 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. In case of
     incomplete type declarations, we do NOT count incomplete declarations.

   - generic formal types are not counted

   - no difference is made between different kinds of types (abstract,
     private etc.), the total number of types is computed and reported.

3.3.3 Computing program unit nesting level

For any body and any task, protected, package and generic package declaration a
maximal nesting level of nested program units is computed. According to RM95
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."

3.3.4 Computing Complexity metrics

gnatmetric computes McCabe cyclomatic complexity (referred as CC below) and
essential complexity (EC). These metrics are computed based on their
description provided at http://www.mccabe.com/pdf/nist235r.pdf

gnatmetric also computes the maximal loop nesting level.

All these complexity metrics are computed for executable bodies - that is, for
the subprogram bodies (including generic bodies), task bodies, entry bodies.
and package bodies containing statement sequences of their own.

According to McCabe, both control statements and short-circuit control forms
should be taken into account when computing CC. 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 CC which is the sum of these
two values.

The rules for computing the complexity are as follows:

1. Control statements:

   IF statement adds 1 + the number of ELSIF paths

   CASE statement adds the number of alternatives minus 1

   WHILE loop always adds 1

   FOR loop adds 1 unless we can detect that the iteration scheme is static
   and the loop will always be (or will never be) executed

   LOOP (condition-less loop statement) adds nothing

   EXIT statement adds 1 if contains the exit condition, otherwise adds nothing

   GOTO statement adds nothing

   RETURN statement adds nothing

   SELECT STATEMENTS:

      SELECTIVE_ACCEPT is treated as a CASE statement (number of alternatives
      minus 1). Opposite to IF statement, ELSE path adds 1 to the complexity
      (that is, for IF, both IF ... END IF; and IF ... ELSE ... END IF; adds 1,
      whereas
            SELECT
               ...
            OR
               ...
            END SELECT;

      adds 1, but

            SELECT
               ...
            OR
               ...
            ELSE
               ...
            END SELECT;
      adds 2

      TIMED_ENTRY_CALL, CONDITIONAL_ENTRY_CALL and ASYNCHRONOUS_SELECT add 1
      (they are considered as an IF statement with no ELSIF parts

2. We do not check if some code or some path is dead (unreachable)

3. We do not take into account the code in the exception handlers (only the
   main statement sequence is analyzed). RAISE statement adds nothing

4. A short-circuit control form add to the complexity value the number of
   AND THEN or OR ELSE at the given level (that is, if we have

     Bool := A and then (B or else C) and then E;

   we consider this as two short-circuit control forms: the outer adds to the
   complexity 2 and the inner adds 1.

   Any short-circuit control form is taken into account, including expressions
   being parts of type and object definitions.

5. Any enclosed body is just skipped and is not taken into account

Essential Complexity is a measure of the level of unstructuredness of the code.
McCabe defines it as the cyclomatic complexity of the program control flow
graph reduced by removing all the structures corresponding to the structural
programming primitives (that is, one-entry one-exit control structures).

We compute EC as CC introduced by the Ada control statements containing
non-structural control transfers outside these constructs. (All Ada
control structures are single-entry by definition). The following constructs
are considered to be non-structural transfer of control:

 - goto statement (if its target statement is not a component of the same
   sequence of statements);
 - return statement;
 - raise statement;
 - terminate alternative in a selective accept;
 - exit statement is considered as (non-structural) control transfer if -ne
   option is not set.


4. Using projects with gnatmetric
   ------------------------------

Support for GNAT projects is provided by means of gnat driver utility. Rather
than invoking gnatmetric directly, the user can call gnat driver, specifying
`metric' as its parameter. This allows to specify the GNAT Project Facility
switches -vPx, -Pprj and -Xnam=val in calls to gnatmetric. Please refer to
GNAT Project Facility documentation in GNAT User's Guide for more information.




5. Examples of the metrics report generated by gnatmetric
   ------------------------------------------------------

Summary report generated when gnatmetric was applied to the GNAT source
distribution (3.16w (20021006)):

Line metrics summed over 1301 units
  all lines           : 572438
  code lines          : 299699
  comment lines       : 161487
  end-of-line comments: 6427
  blank lines         : 111252

Element metrics summed over 1301 units
  all statements      : 98084
  all declarations    : 91911
  logical SLOC        : 189995

 1458 public types in 284 units
 including
    5 abstract types
    6 tagged types
    343 private types

 2403 type declarations in 510 units

 8144 public subprograms in 568 units

 10156 subprogram bodies in 588 units

Metrics generated for the following unit from the unit set used as gnatmetric
test:

pack.adb:

package body Pack is

   protected body Counter is
      procedure Increment(New_Value: out Positive) is
      begin
         Data := Data + 1;
         New_Value := Data;
      end Increment;
   end Counter;

   protected body Event is

      entry Wait when Occurred is
      begin
         Occurred := False; -- consume the signal
      end Wait;

      procedure Signal is
      begin
         Occurred := True;  -- set Wait barrier True
      end Signal;

   end Event;

end Pack;

The content of pack.adb.metrix and metrix.xml files created by the call
'gnatmetric -x pack.adb':

===  pack.adb.metrix ===

Metrics computed for pack.adb
containing package body Pack

=== Code line metrics ===
  all lines           : 26
  code lines          : 19
  comment lines       : 0
  end-of-line comments: 2
  blank lines         : 7

Pack (package body - library item at lines  2: 26)

=== Code line metrics ===
   all lines           : 25
   code lines          : 19
   comment lines       : 0
   end-of-line comments: 2
   blank lines         : 6

=== Element metrics ===
   all subprogram bodies    : 2
   all statements           : 4
   all declarations         : 7
   maximal unit nesting     : 2
   logical SLOC             : 11

   Counter (protected body at lines  4: 10)

   === Code line metrics ===
      all lines           : 7
      code lines          : 7
      comment lines       : 0
      end-of-line comments: 0
      blank lines         : 0

   === Element metrics ===
      all statements           : 2
      all declarations         : 3
      maximal unit nesting     : 1
      logical SLOC             : 5

      Increment (procedure body at lines  5: 9)

      === Code line metrics ===
         all lines           : 5
         code lines          : 5
         comment lines       : 0
         end-of-line comments: 0
         blank lines         : 0

      === Element metrics ===
         all statements           : 2
         all declarations         : 2
         logical SLOC             : 4

      === Complexity metrics ===
         statement complexity     : 1
         short-circuit complexity : 0
         cyclomatic complexity    : 1
         essential complexity     : 1
         maximum loop nesting     : 0

   Event (protected body at lines  12: 24)

   === Code line metrics ===
      all lines           : 13
      code lines          : 10
      comment lines       : 0
      end-of-line comments: 2
      blank lines         : 3

   === Element metrics ===
      all statements           : 2
      all declarations         : 3
      maximal unit nesting     : 1
      logical SLOC             : 5

      Wait (entry body at lines  14: 17)

      === Code line metrics ===
         all lines           : 4
         code lines          : 4
         comment lines       : 0
         end-of-line comments: 1
         blank lines         : 0

      === Element metrics ===
         all statements           : 1
         all declarations         : 1
         logical SLOC             : 2

      === Complexity metrics ===
         statement complexity     : 1
         short-circuit complexity : 0
         cyclomatic complexity    : 1
         essential complexity     : 1
         maximum loop nesting     : 0

      Signal (procedure body at lines  19: 22)

      === Code line metrics ===
         all lines           : 4
         code lines          : 4
         comment lines       : 0
         end-of-line comments: 1
         blank lines         : 0

      === Element metrics ===
         all statements           : 1
         all declarations         : 1
         logical SLOC             : 2

      === Complexity metrics ===
         statement complexity     : 1
         short-circuit complexity : 0
         cyclomatic complexity    : 1
         essential complexity     : 1
         maximum loop nesting     : 0


=== metrix.xml ===

<global>
   <file name="e:\metric-tests\test\pack.adb">
      <metric name="all_lines">26</metric>
      <metric name="code_lines">19</metric>
      <metric name="comment_lines">0</metric>
      <metric name="eol_comments">2</metric>
      <metric name="blank_lines">7</metric>
      <unit name="Pack" line="2" col="1">
         <metric name="all_lines">25</metric>
         <metric name="code_lines">19</metric>
         <metric name="comment_lines">0</metric>
         <metric name="eol_comments">2</metric>
         <metric name="blank_lines">6</metric>
         <metric name="all_subprograms">2</metric>
         <metric name="all_stmts">4</metric>
         <metric name="all_dcls">7</metric>
         <metric name="unit_nesting">2</metric>
         <metric name="lsloc">11</metric>
         <unit name="Counter" line="4" col="4">
            <metric name="all_lines">7</metric>
            <metric name="code_lines">7</metric>
            <metric name="comment_lines">0</metric>
            <metric name="eol_comments">0</metric>
            <metric name="blank_lines">0</metric>
            <metric name="all_stmts">2</metric>
            <metric name="all_dcls">3</metric>
            <metric name="unit_nesting">1</metric>
            <metric name="lsloc">5</metric>
            <unit name="Increment" line="5" col="7">
               <metric name="all_lines">5</metric>
               <metric name="code_lines">5</metric>
               <metric name="comment_lines">0</metric>
               <metric name="eol_comments">0</metric>
               <metric name="blank_lines">0</metric>
               <metric name="all_stmts">2</metric>
               <metric name="all_dcls">2</metric>
               <metric name="lsloc">4</metric>
               <metric name="statement_complexity">1</metric>
               <metric name="short_circuit_complexity">0</metric>
               <metric name="cyclomatic_complexity">1</metric>
               <metric name="essential_complexity">1</metric>
               <metric name="max_loop_nesting">0</metric>
            </unit>
         </unit>
         <unit name="Event" line="12" col="4">
            <metric name="all_lines">13</metric>
            <metric name="code_lines">10</metric>
            <metric name="comment_lines">0</metric>
            <metric name="eol_comments">2</metric>
            <metric name="blank_lines">3</metric>
            <metric name="all_stmts">2</metric>
            <metric name="all_dcls">3</metric>
            <metric name="unit_nesting">1</metric>
            <metric name="lsloc">5</metric>
            <unit name="Wait" line="14" col="7">
               <metric name="all_lines">4</metric>
               <metric name="code_lines">4</metric>
               <metric name="comment_lines">0</metric>
               <metric name="eol_comments">1</metric>
               <metric name="blank_lines">0</metric>
               <metric name="all_stmts">1</metric>
               <metric name="all_dcls">1</metric>
               <metric name="lsloc">2</metric>
               <metric name="statement_complexity">1</metric>
               <metric name="short_circuit_complexity">0</metric>
               <metric name="cyclomatic_complexity">1</metric>
               <metric name="essential_complexity">1</metric>
               <metric name="max_loop_nesting">0</metric>
            </unit>
            <unit name="Signal" line="19" col="7">
               <metric name="all_lines">4</metric>
               <metric name="code_lines">4</metric>
               <metric name="comment_lines">0</metric>
               <metric name="eol_comments">1</metric>
               <metric name="blank_lines">0</metric>
               <metric name="all_stmts">1</metric>
               <metric name="all_dcls">1</metric>
               <metric name="lsloc">2</metric>
               <metric name="statement_complexity">1</metric>
               <metric name="short_circuit_complexity">0</metric>
               <metric name="cyclomatic_complexity">1</metric>
               <metric name="essential_complexity">1</metric>
               <metric name="max_loop_nesting">0</metric>
            </unit>
         </unit>
      </unit>
   </file>
<metric name="all_lines">26</metric>
<metric name="code_lines">19</metric>
<metric name="comment_lines">0</metric>
<metric name="eol_comments">2</metric>
<metric name="blank_lines">7</metric>
<metric name="all_stmts">4</metric>
<metric name="all_dcls">7</metric>
<metric name="lsloc">11</metric>
<metric name="public_subprograms">0</metric>
<metric name="all_subprograms">2</metric>
<metric name="public_types">0</metric>
<metric name="all_types">0</metric>
</global>