From patchwork Mon Sep 26 09:17:39 2022 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: =?utf-8?q?Marc_Poulhi=C3=A8s?= X-Patchwork-Id: 1682492 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=gcc.gnu.org (client-ip=8.43.85.97; helo=sourceware.org; envelope-from=gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org; receiver=) Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=gcc.gnu.org header.i=@gcc.gnu.org header.a=rsa-sha256 header.s=default header.b=u6XiXdEB; dkim-atps=neutral Received: from sourceware.org (server2.sourceware.org [8.43.85.97]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (P-384) server-digest SHA384) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4Mbcgb6VQQz1ypX for ; Mon, 26 Sep 2022 19:20:59 +1000 (AEST) Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id D6A0E3858C52 for ; Mon, 26 Sep 2022 09:20:57 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org D6A0E3858C52 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gcc.gnu.org; s=default; t=1664184057; bh=EkvAq58QAeDllI59nIc2qorqy0FmdXSw1jTnKoBPicY=; h=To:Subject:Date:List-Id:List-Unsubscribe:List-Archive:List-Post: List-Help:List-Subscribe:From:Reply-To:Cc:From; b=u6XiXdEBjFjgrkUo8jlOK4WSswcKsWln12eO5PTILHccxa5E0Npyy4m6ayzFmgljz 6ypZ9wlcwcbhjS4trinG95cDlT+dpZKs/dE7EKxh4kREzregIhw7Np/HAchVICrnKx R/4kQwtas2HWwbNDRQgeTDK/eeb4cuEY7SENIKuw= X-Original-To: gcc-patches@gcc.gnu.org Delivered-To: gcc-patches@gcc.gnu.org Received: from mail-wr1-x430.google.com (mail-wr1-x430.google.com [IPv6:2a00:1450:4864:20::430]) by sourceware.org (Postfix) with ESMTPS id 2F73D3852756 for ; Mon, 26 Sep 2022 09:18:12 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.1 sourceware.org 2F73D3852756 Received: by mail-wr1-x430.google.com with SMTP id s14so9276656wro.0 for ; Mon, 26 Sep 2022 02:18:12 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-message-state:from:to:cc:subject:date; bh=EkvAq58QAeDllI59nIc2qorqy0FmdXSw1jTnKoBPicY=; b=nh36wEZT4Qrpf/OcCzinHi0hKuknjfPy6V6GrjyLxW/kIsS1u70bdLRMTAFPuAJHvi fvhQmFWLhPjB08VEyhp7IgW7/Zea9htQ0jAqSFywPvVI/POmBiEsl0qI+iorxInwpDah uvtqKlcgoPgRlV9ZDJZtgTzp4tRoHJxDDQrPQrtPlsrVIn7P9jgCd1TYxmaK+4BD8UGE khZ467Z0MFUteDHMCox2Q7WadGHUt3phdC7abtc+uqOWU0Ww+tlPWftCt8RgNCJJIG9g gVXfzx+88miLP1sYNOVMcvL9UlaFvGQHhnFDtuH5huvk0Z/fTFwIVT8LZCMlPIsANS3x +ePw== X-Gm-Message-State: ACrzQf1g0vIB7BTxnIF2Bhxz5fyoFQ3IEUIEWXosbt8IUR2AE1ueMu6e ffyfjU4BJ7ckMEMZZ0RLNGRWrWewiQtEfg== X-Google-Smtp-Source: AMsMyM5vknifj0enTzr29BBPFhK4e5O+bwXTrfQtTJDF5PQ42DUqNZvvTFsCIhrqbbCbacL2VkS2Dw== X-Received: by 2002:a5d:6090:0:b0:22c:ace8:493d with SMTP id w16-20020a5d6090000000b0022cace8493dmr993244wrt.366.1664183890267; Mon, 26 Sep 2022 02:18:10 -0700 (PDT) Received: from localhost.localdomain (static-176-191-105-132.ftth.abo.bbox.fr. [176.191.105.132]) by smtp.gmail.com with ESMTPSA id bs5-20020a056000070500b002253fd19a6asm16332731wrb.18.2022.09.26.02.18.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Mon, 26 Sep 2022 02:18:09 -0700 (PDT) To: gcc-patches@gcc.gnu.org Subject: [COMMITED] ada: Remove GNATmetric's documentation from GNAT's documentation Date: Mon, 26 Sep 2022 11:17:39 +0200 Message-Id: <20220926091739.274489-1-poulhies@adacore.com> X-Mailer: git-send-email 2.25.1 MIME-Version: 1.0 X-Spam-Status: No, score=-12.7 required=5.0 tests=BAYES_00, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, KAM_ASCII_DIVIDERS, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_PASS, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: gcc-patches@gcc.gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Gcc-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-Patchwork-Original-From: =?utf-8?q?Marc_Poulhi=C3=A8s_via_Gcc-patches?= From: =?utf-8?q?Marc_Poulhi=C3=A8s?= Reply-To: =?utf-8?q?Marc_Poulhi=C3=A8s?= Cc: Boris Yakobowski Errors-To: gcc-patches-bounces+incoming=patchwork.ozlabs.org@gcc.gnu.org Sender: "Gcc-patches" From: Boris Yakobowski 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(-) diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst index d67083979cc..92877a2d172 100644 --- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst +++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst @@ -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 `_ - - 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*