@@ -15,7 +15,6 @@ This chapter describes a number of utility programs:
* :ref:`The_File_Cleanup_Utility_gnatclean`
* :ref:`The_GNAT_Library_Browser_gnatls`
* :ref:`The_Coding_Standard_Verifier_gnatcheck`
- * :ref:`The_GNAT_Metrics_Tool_gnatmetric`
* :ref:`The_GNAT_Pretty_Printer_gnatpp`
* :ref:`The_Body_Stub_Generator_gnatstub`
* :ref:`The_Backtrace_Symbolizer_gnatsymbolize`
@@ -487,1123 +486,6 @@ building specialized scripts.
For full details, plese refer to :title:`GNATcheck Reference Manual`.
-
-.. only:: PRO or GPL
-
- .. _The_GNAT_Metrics_Tool_gnatmetric:
-
- The GNAT Metrics Tool ``gnatmetric``
- ====================================
-
- .. index:: ! gnatmetric
- .. index:: Metric tool
-
- The ``gnatmetric`` tool is a 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 reported.
-
- ``gnatmetric`` is a project-aware tool
- (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
- the project-related switches). The project file package that can specify
- ``gnatmetric`` switches is named ``Metrics``.
-
- The ``gnatmetric`` command has the form
-
- ::
-
- $ gnatmetric [ switches ] { filename }
-
- where:
-
- * ``switches`` specify the metrics to compute and define the destination for
- the output
-
- * Each ``filename`` is the name 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 :switch:`--files` switch (see :ref:`Other_gnatmetric_Switches`).
- Including both a :switch:`--files` switch and one or more ``filename``
- arguments is permitted.
-
- Note that it is no longer necessary to specify the Ada language version;
- ``gnatmetric`` can process Ada source code written in any version from
- Ada 83 onward without specifying any language version switch.
-
- The following subsections describe the various switches accepted by
- ``gnatmetric``, organized by category.
-
- .. _Output_File_Control-gnatmetric:
-
- Output File Control
- -------------------
-
- .. index:: Output file control in gnatmetric
-
- ``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, the name of the file containing metric information for a source
- is obtained by appending the :file:`.metrix` suffix to the
- name of the input source file. If not otherwise specified and no project file
- is specified as ``gnatmetric`` option this file is placed in the same
- directory as where the source file is located. If ``gnatmetric`` has a
- project file as its parameter, it places all the generated files in the
- object directory of the project (or in the project source directory if the
- project does not define an object directory). If :switch:`--subdirs` option
- is specified, the files are placed in the subrirectory of this directory
- specified by this option.
-
- All the output information generated in XML format is placed in a single
- file. By default the name of this file is :file:`metrix.xml`.
- If not otherwise specified and if no project file is specified
- as ``gnatmetric`` option this file is placed in the
- current directory.
-
- 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 :file:`stdout`, but a file
- can be specified with the :switch:`--global-file-name` switch.
-
- The following switches control the ``gnatmetric`` output:
-
- .. index:: --generate-xml-output (gnatmetric)
-
- :switch:`--generate-xml-output`
- Generate XML output.
-
- .. index:: --generate-xml-schema (gnatmetric)
-
- :switch:`--generate-xml-schema`
- Generate XML output and an XML schema file that describes the structure
- of the XML metric report. This schema is assigned to the XML file. The schema
- file has the same name as the XML output file with :file:`.xml` suffix replaced
- with :file:`.xsd`.
-
- .. index:: --no-text-output (gnatmetric)
-
-
- :switch:`--no-text-output`
- Do not generate the output in text form (implies :switch:`-x`).
-
- .. index:: --output-dir (gnatmetric)
-
-
- :switch:`--output-dir={output_dir}`
- Put text files with detailed metrics into ``output_dir``.
-
- .. index:: --output-suffix (gnatmetric)
-
-
- :switch:`--output-suffix={file_suffix}`
- Use ``file_suffix``, instead of :file:`.metrix`
- in the name of the output file.
-
- .. index:: --global-file-name (gnatmetric)
-
- :switch:`--global-file-name={file_name}`
- Put global metrics into ``file_name``.
-
- .. index:: --xml-file-name (gnatmetric)
-
-
- :switch:`--xml-file-name={file_name}`
- Put the XML output into ``file_name``
- (also implies :switch:`--generate-xml-output`).
-
- .. index:: --short-file-names (gnatmetric)
-
- :switch:`--short-file-names`
- 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 :switch:`--short-file-names` switch causes ``gnatmetric``
- to exclude all directory information from the file names that are
- output.)
-
- .. index:: --wide-character-encoding (gnatmetric)
-
- :switch:`--wide-character-encoding={e}`
- Specify the wide character encoding method for the input and output
- files. ``e`` is one of the following:
-
- * *8* - UTF-8 encoding
-
- * *b* - Brackets encoding (default value)
-
-
- .. index:: Disable Metrics For Local Units in gnatmetric
-
- .. _Disable_Metrics_For_Local_Units:
-
- 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) specs and bodies;
-
- * task object and type specifications and bodies;
-
- * protected object and type specifications and bodies.
-
- .. index:: Eligible local unit (for gnatmetric)
-
- 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:
-
-
- .. index:: --no-local-metrics (gnatmetric)
-
-
- :switch:`--no-local-metrics`
- Do not compute detailed metrics for eligible local program units.
-
-
- .. _Specifying_a_set_of_metrics_to_compute:
-
- Specifying a set of metrics to compute
- --------------------------------------
-
- By default all the metrics are reported. The switches described in this
- subsection allow you to control, on an individual basis, whether metrics are
- 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.
-
- .. _Line_Metrics_Control:
-
- Line Metrics Control
- ^^^^^^^^^^^^^^^^^^^^
-
- .. index:: Line metrics control in gnatmetric
-
- For each 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 comment percentage: the ratio between the number of lines that
- contain comments and the number of all non-blank lines, expressed as
- a percentage
-
- * the number of empty lines and lines containing only space characters
- and/or format effectors (blank lines)
-
- * the average number of code lines in subprogram bodies, task bodies,
- entry bodies and statement sequences in package bodies
-
- ``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 reported.
-
-
- .. index:: --lines (gnatmetric)
- .. index:: --no-lines (gnatmetric)
-
-
- :switch:`--lines-all`
- Report all the line metrics
-
-
- :switch:`--no-lines-all`
- Do not report any of line metrics
-
-
- :switch:`--lines`
- Report the number of all lines
-
-
- :switch:`--no-lines`
- Do not report the number of all lines
-
-
- :switch:`--lines-code`
- Report the number of code lines
-
-
- :switch:`--no-lines-code`
- Do not report the number of code lines
-
-
- :switch:`--lines-comment`
- Report the number of comment lines
-
-
- :switch:`--no-lines-comment`
- Do not report the number of comment lines
-
-
- :switch:`--lines-eol-comment`
- Report the number of code lines containing
- end-of-line comments
-
-
- :switch:`--no-lines-eol-comment`
- Do not report the number of code lines containing
- end-of-line comments
-
-
- :switch:`--lines-ratio`
- Report the comment percentage in the program text
-
-
- :switch:`--no-lines-ratio`
- Do not report the comment percentage in the program text
-
-
- :switch:`--lines-blank`
- Report the number of blank lines
-
-
- :switch:`--no-lines-blank`
- Do not report the number of blank lines
-
-
- :switch:`--lines-average`
- Report the average number of code lines in subprogram bodies, task bodies,
- entry bodies and statement sequences in package bodies.
-
-
- :switch:`--no-lines-average`
- Do not report the average number of code lines in subprogram bodies,
- task bodies, entry bodies and statement sequences in package bodies.
-
-
- :switch:`--lines-spark`
- Report the number of lines written in SPARK.
-
-
- :switch:`--no-lines-spark`
- Do not report the number of lines written in SPARK.
-
-
- .. _Syntax_Metrics_Control:
-
- Syntax Metrics Control
- ^^^^^^^^^^^^^^^^^^^^^^
-
- .. index:: Syntax metrics control in gnatmetric
-
- ``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. Note that the definition of declarations is the one
- given in the reference manual:
-
- "Each of the following is defined to be a declaration: any
- basic_declaration; an enumeration_literal_specification; a
- discriminant_specification; a component_declaration; a
- loop_parameter_specification; a parameter_specification; a
- subprogram_body; an entry_declaration; an
- entry_index_specification; a choice_parameter_specification; a
- generic_formal_parameter_declaration."
-
- This means for example that each enumeration literal adds one to
- the count, as well as each subprogram parameter.
-
- * *Maximal static nesting level of inner program units*
- According to :title:`Ada 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 :ref:`Style_Checking`).
-
- * *Number of formal parameters*
- Number of formal parameters of a subprogram; if a subprogram does
- have parameters, then numbers of "in", "out" and "in out"
- parameters are also reported. This metric is reported for
- subprogram specifications and for subprogram instantiations. For
- subprogram bodies, expression functions and null procedures this
- metric is reported if the construct acts as a subprogram
- declaration but is not a completion of previous declaration. This
- metric is not reported for generic and formal subprograms.
-
- For the outermost unit in the file, ``gnatmetric`` additionally
- computes the following metrics:
-
- * *Public subprograms*
- This metric is computed for package specs. It is the number of
- subprograms and generic subprograms declared in the visible part
- (including the visible part of 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 specs 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 reported.
-
- By default, all the syntax metrics are reported. You can use the following
- switches to select specific syntax metrics.
-
-
- .. index:: --syntax (gnatmetric)
- .. index:: --no-syntax (gnatmetric)
-
-
- :switch:`--syntax-all`
- Report all the syntax metrics
-
-
- :switch:`--no-syntax-all`
- Do not report any of syntax metrics
-
-
- :switch:`--declarations`
- Report the total number of declarations
-
-
- :switch:`--no-declarations`
- Do not report the total number of declarations
-
-
- :switch:`--statements`
- Report the total number of statements
-
-
- :switch:`--no-statements`
- Do not report the total number of statements
-
-
- :switch:`--public-subprograms`
- Report the number of public subprograms in a compilation unit
-
-
- :switch:`--no-public-subprograms`
- Do not report the number of public subprograms in a compilation unit
-
-
- :switch:`--all-subprograms`
- Report the number of all the subprograms in a compilation unit
-
-
- :switch:`--no-all-subprograms`
- Do not report the number of all the subprograms in a compilation unit
-
-
- :switch:`--public-types`
- Report the number of public types in a compilation unit
-
-
- :switch:`--no-public-types`
- Do not report the number of public types in a compilation unit
-
-
- :switch:`--all-types`
- Report the number of all the types in a compilation unit
-
-
- :switch:`--no-all-types`
- Do not report the number of all the types in a compilation unit
-
-
- :switch:`--unit-nesting`
- Report the maximal program unit nesting level
-
-
- :switch:`--no-unit-nesting`
- Do not report the maximal program unit nesting level
-
-
- :switch:`--construct-nesting`
- Report the maximal construct nesting level
-
-
- :switch:`--no-construct-nesting`
- Do not report the maximal construct nesting level
-
- :switch:`--param-number`
- Report the number of subprogram parameters
-
-
- :switch:`--no-param-number`
- Do not report the number of subprogram parameters
-
-
- .. _Contract_Metrics_Control:
-
- Contract Metrics Control
- ^^^^^^^^^^^^^^^^^^^^^^^^
-
- .. index:: Contract metrics control in gnatmetric
-
- :switch:`--contract-all`
- Report all the contract metrics
-
-
- :switch:`--no-contract-all`
- Do not report any of the contract metrics
-
-
- :switch:`--contract`
- Report the number of public subprograms with contracts
-
-
- :switch:`--no-contract`
- Do not report the number of public subprograms with contracts
-
-
- :switch:`--post`
- Report the number of public subprograms with postconditions
-
-
- :switch:`--no-post`
- Do not report the number of public subprograms with postconditions
-
-
- :switch:`--contract-complete`
- Report the number of public subprograms with complete contracts
-
-
- :switch:`--no-contract-complete`
- Do not report the number of public subprograms with complete contracts
-
-
- :switch:`--contract-cyclomatic`
- Report the McCabe complexity of public subprograms
-
-
- :switch:`--no-contract-cyclomatic`
- Do not report the McCabe complexity of public subprograms
-
-
- .. _Complexity_Metrics_Control:
-
- Complexity Metrics Control
- ^^^^^^^^^^^^^^^^^^^^^^^^^^
-
- .. index:: Complexity metrics control in gnatmetric
-
- 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;
-
- * extra exit points (for subprograms);
-
- The McCabe cyclomatic complexity metric is defined
- in `http://www.mccabe.com/pdf/mccabe-nist235r.pdf <http://www.mccabe.com/pdf/mccabe-nist235r.pdf>`_
-
- According to McCabe, both control statements and short-circuit control
- forms should be taken into account when computing cyclomatic
- complexity. For Ada 2012 we have also take into account conditional
- expressions and quantified expressions. For each body, we compute
- three metric values:
-
- * the complexity introduced by control
- statements only, without taking into account short-circuit forms
- (referred as ``statement complexity`` in ``gnatmetric`` output),
-
- * the complexity introduced by short-circuit control forms only
- (referred as ``expression complexity`` in ``gnatmetric`` output),
- and
-
- * the total
- cyclomatic complexity, which is the sum of these two values
- (referred as ``cyclomatic complexity`` in ``gnatmetric`` output).
-
- The cyclomatic complexity is also computed for Ada 2012 expression functions.
- An expression function cannot have statements as its components, so only one
- metric value is computed as a cyclomatic complexity of an expression function.
-
- The origin of cyclomatic complexity metric is the need to estimate the number
- of independent paths in the control flow graph that in turn gives the number
- of tests needed to satisfy paths coverage testing completeness criterion.
- Considered from the testing point of view, a static Ada ``loop`` (that is,
- the ``loop`` statement having static subtype in loop parameter
- specification) does not add to cyclomatic complexity. By providing
- :switch:`--no-static-loop` option a user
- may specify that such loops should not be counted when computing the
- cyclomatic complexity metric
-
- The Ada essential complexity metric is a McCabe cyclomatic complexity metric
- counted for the code that is reduced by excluding all the pure structural Ada
- control statements. An compound statement is considered as a non-structural
- if it contains a ``raise`` or ``return`` statement as it subcomponent,
- or if it contains a ``goto`` statement that transfers the control outside
- the operator. A selective ``accept`` statement with a ``terminate`` alternative
- is considered a non-structural statement. When computing this metric,
- ``exit`` statements are treated in the same way as ``goto``
- statements unless the :switch:`-ne` option is specified.
-
- The Ada essential complexity metric defined here is intended to quantify
- the extent to which the software is unstructured. It is adapted from
- the McCabe essential complexity metric defined in
- http://www.mccabe.com/pdf/mccabe-nist235r.pdf
- but is modified to be more
- suitable for typical Ada usage. For example, short circuit forms
- are not penalized as unstructured in the Ada essential complexity metric.
-
- When computing cyclomatic and essential complexity, ``gnatmetric`` skips
- the code in the exception handlers and in all the nested program units. The
- code of assertions and predicates (that is, subprogram preconditions and
- postconditions, subtype predicates and type invariants) is also skipped.
-
- By default, all the complexity metrics are reported. For more fine-grained
- control you can use the following switches:
-
-
- .. index:: --complexity (gnatmetric)
- .. index:: --no-complexity (gnatmetric)
-
-
- :switch:`--complexity-all`
- Report all the complexity metrics
-
-
- :switch:`--no-complexity-all`
- Do not report any of the complexity metrics
-
-
- :switch:`--complexity-cyclomatic`
- Report the McCabe Cyclomatic Complexity
-
-
- :switch:`--no-complexity-cyclomatic`
- Do not report the McCabe Cyclomatic Complexity
-
-
- :switch:`--complexity-essential`
- Report the Essential Complexity
-
-
- :switch:`--no-complexity-essential`
- Do not report the Essential Complexity
-
-
- :switch:`--loop-nesting`
- Report maximal loop nesting level
-
-
- :switch:`--no-loop-nesting`
- Do not report maximal loop nesting level
-
-
- :switch:`--complexity-average`
- Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
- task bodies, entry bodies and statement sequences in package bodies.
- The metric is reported for whole set of processed Ada sources only.
-
-
- :switch:`--no-complexity-average`
- Do not report the average McCabe Cyclomatic Complexity for all the subprogram
- bodies, task bodies, entry bodies and statement sequences in package bodies
-
- .. index:: --no-treat-exit-as-goto (gnatmetric)
-
-
- :switch:`--no-treat-exit-as-goto`
- Do not consider ``exit`` statements as ``goto``\ s when
- computing Essential Complexity
-
- .. index:: --no-static-loop (gnatmetric)
-
-
- :switch:`--no-static-loop`
- Do not consider static loops when computing cyclomatic complexity
-
-
- :switch:`--extra-exit-points`
- Report the extra exit points for subprogram bodies. As an exit point, this
- metric counts ``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.
-
-
- :switch:`--no-extra-exit-points`
- Do not report the extra exit points for subprogram bodies
-
-
- .. _Coupling_Metrics_Control:
-
- Coupling Metrics Control
- ^^^^^^^^^^^^^^^^^^^^^^^^
-
- .. index:: Coupling metrics control in gnatmetric
-
- .. index:: Coupling metrics (in gnatmetric)
-
- Coupling metrics measure the dependencies between a given entity and other
- entities in the program. This information is useful since high coupling
- may signal potential issues with maintainability as the program evolves.
-
- ``gnatmetric`` computes the following coupling metrics:
-
-
- * *object-oriented coupling*, for classes in traditional object-oriented
- sense;
-
- * *unit coupling*, for all the program units making up a program;
-
- * *control coupling*, reflecting dependencies between a unit and
- other units that contain subprograms.
-
- .. index:: fan-out coupling
- .. index:: efferent coupling
-
- Two kinds of coupling metrics are computed:
-
- * fan-out coupling ('efferent coupling'):
- the number of entities the given entity depends upon. This metric
- reflects how the given entity depends on the changes in the
- 'external world'.
-
- .. index:: fan-in coupling
- .. index:: afferent coupling
-
- * fan-in coupling ('afferent' coupling):
- the number of entities that depend on a given entity.
- This metric reflects how the 'external world' depends on the changes in a
- given entity.
-
- Object-oriented coupling metrics measure the dependencies
- between a given class (or a group of classes) and 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 fan-out coupling is the number of classes
- that ``K`` depends upon.
- A category's fan-out coupling is the number of classes outside the
- category that the classes inside the category depend upon.
-
- A class ``K``\ 's fan-in coupling is the number of classes
- that depend upon ``K``.
- A category's fan-in coupling is the number of classes outside the
- category that depend on classes belonging to the category.
-
- Ada's object-oriented paradigm separates the instantiable entity
- (type) from the module (package), 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 that define a tagged type
- or an interface type -- library packages, library generic packages, and
- library generic package instantiations -- are considered to be classes.
- 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. Thus a
- category is an Ada hierarchy of library-level program units. Class
- coupling in Ada is referred to as 'tagged coupling', and category coupling
- is referred to as 'hierarchy coupling'.
-
- For any package serving as a class, its body and subunits (if any) are
- considered together with its spec when computing dependencies, and coupling
- metrics are reported for spec units only. Dependencies between classes
- mean Ada semantic dependencies. For object-oriented coupling
- metrics, only dependencies on units treated as classes are
- considered.
-
- Similarly, for unit and control coupling an entity is considered to be the
- conceptual construct consisting of the entity's specification, body, and
- any subunits (transitively).
- ``gnatmetric`` computes
- the dependencies of all these units as a whole, but
- metrics are only reported for spec
- units (or for a subprogram body unit in case if there is no
- separate spec for the given subprogram).
-
- For unit coupling, dependencies are computed between all kinds of program
- units. For control coupling, the dependencies of a given unit are limited to
- those units that define subprograms. Thus control fan-out coupling is reported
- for all units, but control fan-in coupling is only reported for units
- that define subprograms.
-
- The following simple example illustrates the difference between unit coupling
- and control coupling metrics:
-
- .. code-block:: ada
-
- package Lib_1 is
- function F_1 (I : Integer) return Integer;
- end Lib_1;
-
- package Lib_2 is
- type T_2 is new Integer;
- end Lib_2;
-
- package body Lib_1 is
- function F_1 (I : Integer) return Integer is
- begin
- return I + 1;
- end F_1;
- end Lib_1;
-
- with Lib_2; use Lib_2;
- package Pack is
- Var : T_2;
- function Fun (I : Integer) return Integer;
- end Pack;
-
- with Lib_1; use Lib_1;
- package body Pack is
- function Fun (I : Integer) return Integer is
- begin
- return F_1 (I);
- end Fun;
- end Pack;
-
- If we apply ``gnatmetric`` with the :switch:`--coupling-all` option to
- these units, the result will be:
-
- ::
-
- Coupling metrics:
- =================
- Unit Lib_1 (C:\\customers\\662\\L406-007\\lib_1.ads)
- control fan-out coupling : 0
- control fan-in coupling : 1
- unit fan-out coupling : 0
- unit fan-in coupling : 1
-
- Unit Pack (C:\\customers\\662\\L406-007\\pack.ads)
- control fan-out coupling : 1
- control fan-in coupling : 0
- unit fan-out coupling : 2
- unit fan-in coupling : 0
-
- Unit Lib_2 (C:\\customers\\662\\L406-007\\lib_2.ads)
- control fan-out coupling : 0
- unit fan-out coupling : 0
- unit fan-in coupling : 1
-
- The result does not contain values for object-oriented
- coupling because none of the argument units contains a tagged type and
- therefore none of these units can be treated as a class.
-
- The ``Pack`` package (spec and body) depends on two
- units -- ``Lib_1`` and ``Lib_2`` -- and so its unit fan-out coupling
- is 2. Since nothing depends on it, its unit fan-in coupling is 0, as
- is its control fan-in coupling. Only one of the units ``Pack`` depends
- upon defines a subprogram, so its control fan-out coupling is 1.
-
- ``Lib_2`` depends on nothing, so its fan-out metrics are 0. It does
- not define any subprograms, so it has no control fan-in metric.
- One unit (``Pack``) depends on it , so its unit fan-in coupling is 1.
-
- ``Lib_1`` is similar to ``Lib_2``, but it does define a subprogram.
- Its control fan-in coupling is 1 (because there is one unit
- depending on it).
-
- When computing coupling metrics, ``gnatmetric`` counts only
- dependencies between units that are arguments of the ``gnatmetric``
- invocation. Coupling metrics are program-wide (or project-wide) metrics, so
- you should invoke ``gnatmetric`` for
- the complete set of sources comprising your program. This can be done
- by invoking ``gnatmetric`` with the corresponding project file
- and with the :switch:`-U` option.
-
- By default, all the coupling metrics are reported. You can use the following
- switches to select specific syntax metrics.
-
- .. index:: --tagged-coupling (gnatmetric)
- .. index:: --hierarchy-coupling (gnatmetric)
- .. index:: --unit-coupling (gnatmetric)
- .. index:: --control-coupling (gnatmetric)
-
- :switch:`--coupling-all`
- Report all the coupling metrics
-
-
- :switch:`--tagged-coupling-out`
- Report tagged (class) fan-out coupling
-
-
- :switch:`--tagged-coupling-in`
- Report tagged (class) fan-in coupling
-
-
- :switch:`--hierarchy-coupling-out`
- Report hierarchy (category) fan-out coupling
-
-
- :switch:`--hierarchy-coupling-in`
- Report hierarchy (category) fan-in coupling
-
-
- :switch:`--unit-coupling-out`
- Report unit fan-out coupling
-
-
- :switch:`--unit-coupling-in`
- Report unit fan-in coupling
-
-
- :switch:`--control-coupling-out`
- Report control fan-out coupling
-
-
- :switch:`--control-coupling-in`
- Report control fan-in coupling
-
-
- .. _Other_gnatmetric_Switches:
-
- Other ``gnatmetric`` Switches
- -----------------------------
-
- Additional ``gnatmetric`` switches are as follows:
-
-
- .. index:: --version (gnatmetric)
-
- :switch:`--version`
- Display copyright and version, then exit disregarding all other options.
-
-
- .. index:: --help (gnatmetric)
-
- :switch:`--help`
- Display usage, then exit disregarding all other options.
-
-
- .. index:: -P (gnatmetric)
-
- :switch:`-P {file}`
- Indicates the name of the project file that describes the set of sources
- to be processed. The exact set of argument sources depends on other options
- specified, see below. An aggregate project is allowed as the file parameter
- only if it has exactly one non-aggregate project being aggregated.
-
-
- .. index:: -U (gnatmetric)
-
- :switch:`-U`
- If a project file is specified and no argument source is explicitly
- specified (either directly or by means of :switch:`-files` option), process
- all the units of the closure of the argument project. Otherwise this option
- has no effect.
-
-
- :switch:`-U {main_unit}`
- If a project file is specified and no argument source is explicitly
- specified (either directly or by means of :switch:`-files` option), process
- the closure of units rooted at ``main_unit``. Otherwise this option
- has no effect.
-
-
- .. index:: -X (gnatmetric)
-
- :switch:`-X{name}={value}`
- Indicates that external variable ``name`` in the argument project
- has the value ``value``. Has no effect if no project is specified.
-
-
- .. index:: --RTS (gnatmetric)
-
- :switch:`--RTS={rts-path}`
- Specifies the default location of the runtime library. Same meaning as the
- equivalent ``gnatmake`` flag (see :ref:`Switches_for_gnatmake`).
-
-
- .. index:: --subdirs=dir (gnatmetric)
-
- :switch:`--subdirs={dir}`
- Use the specified subdirectory of the project objects file (or of the
- project file directory if the project does not specify an object directory)
- for tool output files. Has no effect if no project is specified as
- tool argument r if :switch:`--no-objects-dir` is specified.
-
-
- .. index:: --files (gnatmetric)
-
- :switch:`--files={file}`
- Take as arguments the files listed in text file ``file``.
- Text file ``file`` may contain empty lines that are ignored.
- Each nonempty line should contain the name of an existing file.
- Several such switches may be specified simultaneously.
-
-
- .. index:: --ignore (gnatmetric)
-
- :switch:`--ignore={filename}`
- Do not process the sources listed in a specified file.
-
-
- .. index:: --verbose (gnatmetric)
-
- :switch:`--verbose`
- Verbose mode;
- ``gnatmetric`` generates version information and then
- a trace of sources being processed.
-
-
- .. index:: --quiet (gnatmetric)
-
- :switch:`--quiet`
- Quiet mode.
-
- If a project file is specified and no argument source is explicitly
- specified (either directly or by means of :switch:`-files` option), and no
- :switch:`-U` is specified, then the set of processed sources is
- all the immediate units of the argument project.
-
-
- Legacy Switches
- ^^^^^^^^^^^^^^^
-
- Some switches have a short form, mostly for legacy reasons,
- as shown below.
-
- .. index:: -x (gnatmetric)
-
- :switch:`-x`
- :switch:`--generate-xml-output`
-
- .. index:: -xs (gnatmetric)
-
- :switch:`-xs`
- :switch:`--generate-xml-schema`
-
- .. index:: -nt (gnatmetric)
-
- :switch:`-nt`
- :switch:`--no-text-output`
-
- .. index:: -d (gnatmetric)
-
- :switch:`-d {output-dir}`
- :switch:`--output-dir`
-
- .. index:: -o (gnatmetric)
-
- :switch:`-o {file-suffix}`
- :switch:`--output-suffix`
-
- .. index:: -og (gnatmetric)
-
- :switch:`-og {file-name}`
- :switch:`--global-file-name`
-
- .. index:: -ox (gnatmetric)
-
- :switch:`-ox {file-name}`
- :switch:`--xml-file-name`
-
- .. index:: -sfn (gnatmetric)
-
- :switch:`-sfn`
- :switch:`--short-file-names`
-
- .. index:: -W (gnatsmetric)
-
- :switch:`-W{e}`
- :switch:`--wide-character-encoding={e}`
-
- .. index:: -nolocal (gnatmetric)
-
- :switch:`-nolocal`
- :switch:`--no-local-metrics`
-
- .. index:: -ne (gnatmetric)
-
- :switch:`-ne`
- :switch:`--no-treat-exit-as-goto`
-
- .. index:: -files (gnatmetric)
-
- :switch:`-files {filename}`
- :switch:`--files`
-
- .. index:: -v (gnatmetric)
-
- :switch:`-v`
- :switch:`--verbose`
-
- .. index:: -q (gnatmetric)
-
- :switch:`-q`
- :switch:`--quiet`
-
.. only:: PRO or GPL
.. _The_GNAT_Pretty_Printer_gnatpp:
@@ -3026,7 +1908,7 @@ building specialized scripts.
naming conventions.
Note that it is no longer necessary to specify the Ada language version;
- ``gnatmetric`` can process Ada source code written in any version from
+ ``gnatstub`` can process Ada source code written in any version from
Ada 83 onward without specifying any language version switch.
* *switches*
From: Boris Yakobowski <yakobowski@adacore.com> gcc/ada/ * doc/gnat_ugn/gnat_utility_programs.rst: Remove documentation for gnatmetric. --- .../doc/gnat_ugn/gnat_utility_programs.rst | 1120 +---------------- 1 file changed, 1 insertion(+), 1119 deletions(-)