Mercurial > hg > CbC > CbC_gcc
diff gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst @ 145:1830386684a0
gcc-9.2.0
| author | anatofuz |
|---|---|
| date | Thu, 13 Feb 2020 11:34:05 +0900 |
| parents | 84e7813d76e9 |
| children |
line wrap: on
line diff
--- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst Thu Oct 25 07:37:49 2018 +0900 +++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst Thu Feb 13 11:34:05 2020 +0900 @@ -87,7 +87,7 @@ .. index:: --version (gnatclean) :switch:`--version` - Display Copyright and version, then exit disregarding all other options. + Display copyright and version, then exit disregarding all other options. .. index:: --help (gnatclean) @@ -289,7 +289,7 @@ .. index:: --version (gnatls) :switch:`--version` - Display Copyright and version, then exit disregarding all other options. + Display copyright and version, then exit disregarding all other options. .. index:: --help (gnatls) @@ -535,7 +535,7 @@ .. index:: --version (gnatxref) :switch:`--version` - Display Copyright and version, then exit disregarding all other options. + Display copyright and version, then exit disregarding all other options. .. index:: --help (gnatxref) @@ -724,7 +724,7 @@ .. index:: --version (gnatfind) :switch:`--version` - Display Copyright and version, then exit disregarding all other options. + Display copyright and version, then exit disregarding all other options. .. index:: --help (gnatfind) @@ -1214,7 +1214,7 @@ :samp:`f` By default, gnathtml will generate html links only for global entities - ('with'ed units, global variables and types,...). If you specify + ('with'ed units, global variables and types,...). If you specify :switch:`-f` on the command line, then links will be generated for local entities too. @@ -1310,7 +1310,7 @@ ``gnat2xml`` 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 + the project-related switches). The project file package that can specify ``gnat2xml`` switches is named ``gnat2xml``. .. _Switches_for_``gnat2xml``: @@ -1357,7 +1357,7 @@ :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 as tool argument. + project is specified. :switch:`--RTS={rts-path}` Specifies the default location of the runtime @@ -1780,7 +1780,7 @@ ``gnatcheck`` 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 + the project-related switches). The project file package that can specify ``gnatcheck`` switches is named ``Check``. For full details, plese refer to :title:`GNATcheck Reference Manual`. @@ -1797,59 +1797,38 @@ .. index:: ! gnatmetric .. index:: Metric tool - The ``gnatmetric`` tool is an ASIS-based utility + 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 computed and output. + 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 + the project-related switches). The project file package that can specify ``gnatmetric`` switches is named ``Metrics``. - To compute program metrics, ``gnatmetric`` invokes the Ada - compiler and generates and uses the ASIS tree for the input source; - thus the input must be legal Ada code, and the tool should have all the - information needed to compile the input source. To provide this information, - you may specify as a tool parameter the project file the input source belongs to. - Another possibility is to specify the source search - path and needed configuration files in :switch:`-cargs` section of ``gnatmetric`` - call, see the description of the ``gnatmetric`` switches below. - - If the set of sources to be processed by ``gnatmetric`` contains sources with - preprocessing directives - then the needed options should be provided to run preprocessor as a part of - the ``gnatmetric`` call, and the computed metrics - will correspond to preprocessed sources. - The ``gnatmetric`` command has the form :: - $ gnatmetric [ switches ] { filename } [ -cargs gcc_switches ] + $ gnatmetric [ switches ] { filename } where: * ``switches`` specify the metrics to compute and define the destination for the output - * Each ``filename`` is the name (including the extension) of a source - file to process. 'Wildcards' are allowed, and - the file name may contain path information. - If no ``filename`` is supplied, then the ``switches`` list must contain - at least one - :switch:`-files` switch (see :ref:`Other_gnatmetric_Switches`). - Including both a :switch:`-files` switch and one or more - ``filename`` arguments is permitted. - - * ``gcc_switches`` is a list of switches for - ``gcc``. They will be passed on to all compiler invocations made by - ``gnatmetric`` to generate the ASIS trees. Here you can provide - :switch:`-I` switches to form the source search path, - and use the :switch:`-gnatec` switch to set the configuration file, - use the :switch:`-gnat05` switch if sources should be compiled in - Ada 2005 mode etc. + * 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. @@ -1877,76 +1856,86 @@ 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 objects directory), if :switch:`--subdirs` option + 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 + 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:`-og` switch. + can be specified with the :switch:`--global-file-name` switch. The following switches control the ``gnatmetric`` output: - .. index:: -x (gnatmetric) - - :switch:`-x` - Generate the XML output - - .. index:: -xs (gnatmetric) - - :switch:`-xs` - Generate the XML output and the XML schema file that describes the structure - of the XML metric report, this schema is assigned to the XML file. The schema + .. 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:: -nt (gnatmetric) - - - :switch:`-nt` - Do not generate the output in text form (implies :switch:`-x`) - - .. index:: -d (gnatmetric) - - - :switch:`-d {output_dir}` - Put text files with detailed metrics into ``output_dir`` - - .. index:: -o (gnatmetric) - - - :switch:`-o {file_suffix}` + 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:: -og (gnatmetric) - - - :switch:`-og {file_name}` - Put global metrics into ``file_name`` - - .. index:: -ox (gnatmetric) - - - :switch:`-ox {file_name}` - Put the XML output into ``file_name`` (also implies :switch:`-x`) - - .. index:: -sfn (gnatmetric) - - - :switch:`-sfn` - Use 'short' source file names in the output. (The ``gnatmetric`` - output includes the name(s) of the Ada source file(s) from which the metrics - are computed. By default each name includes the absolute path. The - :switch:`-sfn` switch causes ``gnatmetric`` - to exclude all directory information from the file names that are output.) + .. 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 @@ -1988,11 +1977,11 @@ obtained via the following switch: - .. index:: -nolocal (gnatmetric) - - - :switch:`-nolocal` - Do not compute detailed metrics for eligible local program units + .. 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: @@ -2000,13 +1989,11 @@ Specifying a set of metrics to compute -------------------------------------- - By default all the metrics are computed and reported. The switches - described in this subsection allow you to control, on an individual - basis, whether metrics are computed and - reported. If at least one positive metric - switch is specified (that is, a switch that defines that a given - metric or set of metrics is to be computed), then only - explicitly specified metrics are reported. + 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: @@ -2015,35 +2002,35 @@ .. index:: Line metrics control in gnatmetric - For any (legal) source file, and for each of its - eligible local program units, ``gnatmetric`` computes the following - metrics: + 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 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 (this metric is only computed - across the whole set of the analyzed units) - - ``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. + * 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 computed and reported. + to be reported. .. index:: --lines (gnatmetric) @@ -2110,8 +2097,7 @@ :switch:`--lines-average` Report the average number of code lines in subprogram bodies, task bodies, - entry bodies and statement sequences in package bodies. The metric is computed - and reported for the whole set of processed Ada sources only. + entry bodies and statement sequences in package bodies. :switch:`--no-lines-average` @@ -2119,6 +2105,14 @@ 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 @@ -2130,79 +2124,78 @@ 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. - - Thus the results from this metric will be significantly greater than might - be expected from a naive view of counting semicolons. + 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." + "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`) + 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: + 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). + 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 + 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. + 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. + 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 + * *Root tagged types^ (abstract, non-abstract, private, + non-private). Type extensions are *not* counted * *Private types* (including private extensions) @@ -2211,16 +2204,16 @@ * *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. + This metric is computed for any compilation unit. It is equal to + the total number of the declarations of different types given in + the compilation unit. The private and the corresponding full type + declaration are counted as one type declaration. Incomplete type + declarations and generic formal types are not counted. No distinction is made among different kinds of types (abstract, - private etc.); the total number of types is computed and reported. - - By default, all the syntax metrics are computed and reported. You can use the - following switches to select specific syntax metrics. + 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) @@ -2306,6 +2299,53 @@ 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-all` + Report the McCabe complexity of public subprograms + + + :switch:`--no-contract-all` + Do not report the McCabe complexity of public subprograms + + .. _Complexity_Metrics_Control: Complexity Metrics Control @@ -2313,10 +2353,10 @@ .. 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: + 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; @@ -2329,17 +2369,19 @@ 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: + 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 + (referred as ``expression complexity`` in ``gnatmetric`` output), + and * the total cyclomatic complexity, which is the sum of these two values @@ -2382,12 +2424,11 @@ 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 computed and reported. - For more fine-grained control you can use - the following switches: - - - .. index:: -complexity (gnatmetric) + 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) @@ -2396,7 +2437,7 @@ :switch:`--no-complexity-all` - Do not report any of complexity metrics + Do not report any of the complexity metrics :switch:`--complexity-cyclomatic` @@ -2426,18 +2467,17 @@ :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 computed and reported for whole set of processed Ada sources - only. + 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:: -ne (gnatmetric) - - - :switch:`-ne` + .. 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 @@ -2641,8 +2681,8 @@ by invoking ``gnatmetric`` with the corresponding project file and with the :switch:`-U` option. - By default, all the coupling metrics are disabled. You can use the following - switches to specify the coupling metrics to be computed and reported: + 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) @@ -2696,7 +2736,7 @@ .. index:: --version (gnatmetric) :switch:`--version` - Display Copyright and version, then exit disregarding all other options. + Display copyright and version, then exit disregarding all other options. .. index:: --help (gnatmetric) @@ -2734,8 +2774,7 @@ :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 as - tool argument. + has the value ``value``. Has no effect if no project is specified. .. index:: --RTS (gnatmetric) @@ -2754,18 +2793,9 @@ tool argument r if :switch:`--no_objects_dir` is specified. - .. index:: --no_objects_dir (gnatmetric) - - :switch:`--no_objects_dir` - Place all the result files into the current directory instead of - project objects directory. This corresponds to the ``gnatcheck`` - behavior when it is called with the project file from the - GNAT driver. Has no effect if no project is specified. - - - .. index:: -files (gnatmetric) - - :switch:`-files {filename}` + .. 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. @@ -2777,32 +2807,18 @@ :switch:`--ignore={filename}` Do not process the sources listed in a specified file. - .. index:: -j (gnatmetric) - - :switch:`-j{n}` - Use ``n`` processes to carry out the tree creations (internal representations - of the argument sources). On a multiprocessor machine this speeds up processing - of big sets of argument sources. If ``n`` is 0, then the maximum number of - parallel tree creations is the number of core processors on the platform. - - .. index:: -t (gnatmetric) - - - :switch:`-t` - Print out execution time. - - - .. index:: -v (gnatmetric) - - :switch:`-v` + + .. index:: --verbose (gnatmetric) + + :switch:`--verbose` Verbose mode; ``gnatmetric`` generates version information and then a trace of sources being processed. - .. index:: -q (gnatmetric) - - :switch:`-q` + .. index:: --quiet (gnatmetric) + + :switch:`--quiet` Quiet mode. If a project file is specified and no argument source is explicitly @@ -2811,6 +2827,82 @@ 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: @@ -2821,18 +2913,15 @@ .. index:: ! gnatpp .. index:: pretty printer - This documentation is for the new libadalang-based version - of ``gnatpp``, which replaces the ASIS-based version. - The ``gnatpp`` tool is a utility for source reformatting / pretty - printing. It takes an Ada source file as input and generates a - reformatted version as output. You can specify various style + printing. It takes an Ada source file as input and generates a + reformatted version as output. You can specify various style directives via switches; e.g., identifier case conventions, rules of indentation, and comment layout. ``gnatpp`` 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 + the project-related switches). The project file package that can specify ``gnatpp`` switches is named ``Pretty_Printer``. ``gnatpp`` cannot process sources that contain preprocessing @@ -2855,6 +2944,10 @@ file name may contain path information; it does not have to follow the GNAT file naming rules + Note that it is no longer necessary to specify the Ada language version; + ``gnatpp`` can process Ada source code written in any version from + Ada 83 onward without specifying any language version switch. + .. _Switches_for_gnatpp: @@ -2990,7 +3083,7 @@ .. index:: --enum-upper-case (gnatpp) :switch:`--enum-upper-case` - Enumeration literals are in upper case. Overrides -n casing + Enumeration literals are in upper case. Overrides -n casing setting. .. index:: --enum-lower-case (gnatpp) @@ -3104,7 +3197,7 @@ compatible. This group of ``gnatpp`` switches controls the layout of comments and - complex syntactic constructs. See :ref:`Formatting_Comments` for details + complex syntactic constructs. See :ref:`Formatting_Comments` for details on their effect. @@ -3152,20 +3245,47 @@ Do not place the keyword ``is`` on a separate line in a subprogram body in case if the spec occupies more than one line. + .. index:: --separate-loop (gnatpp) + + + :switch:`--separate-loop` + Place the keyword ``loop`` in FOR and WHILE loop statements + on a separate line. + + .. index:: --no-separate-then (gnatpp) + + + :switch:`--separate-then` + Place the keyword ``then`` in IF statements + on a separate line. + + .. index:: --no-separate-loop (gnatpp) + + + :switch:`--no-separate-loop` + Do not place the keyword ``loop`` in FOR and WHILE loop statements + on a separate line. This option is + incompatible with the :switch:`--separate-loop` option. + + .. index:: --no-separate-then (gnatpp) + + + :switch:`--no-separate-then` + Do not place the keyword ``then`` in IF statements + on a separate line. This option is + incompatible with the :switch:`--separate-then` option. + .. index:: --separate-loop-then (gnatpp) :switch:`--separate-loop-then` - Place the keyword ``loop`` in FOR and WHILE loop statements and the - keyword ``then`` in IF statements on a separate line. + Equivalent to :switch:`--separate-loop` :switch:`--separate-then`. .. index:: --no-separate-loop-then (gnatpp) :switch:`--no-separate-loop-then` - Do not place the keyword ``loop`` in FOR and WHILE loop statements and the - keyword ``then`` in IF statements on a separate line. This option is - incompatible with the :switch:`--separate-loop-then` option. + Equivalent to :switch:`--no-separate-loop` :switch:`--no-separate-then`. .. index:: --use-on-new-line (gnatpp) @@ -3192,6 +3312,20 @@ :switch:`--preserve-line-breaks` Preserve line breaks in the input, to the extent possible. + By default, line breaks are also inserted at appropriate + places. + + .. index:: --source-line-breaks (gnatpp) + + :switch:`--source-line-breaks` + Keep the line breaks from the source; do not insert or delete any + line breaks. + + .. index:: --spaces-only (gnatpp) + + :switch:`--spaces-only` + Disable all formatting except for inserting and removing spaces. + This implies --source-line-breaks. The ``--comments`` switches are compatible with one another, except that the ``--comments-unchanged`` switch disables all other comment @@ -3281,12 +3415,6 @@ '(' and ':'. This also turns off alignment. - .. index:: --ff-after-pragma-page (gnatpp) - - :switch:`--ff-after-pragma-page` - Insert a Form Feed character after a pragma Page. - - .. index:: --call_threshold (gnatpp) :switch:`--call_threshold={nnn}` @@ -3429,6 +3557,8 @@ * *unix* - UNIX style, lines end with LF character* * *lf* - the same as *unix* + The default is to use the same end-of-line convention as the input. + .. index:: --wide-character-encoding (gnatpp) :switch:`--wide-character-encoding={e}` @@ -3494,8 +3624,7 @@ :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 as - tool argument. + has the value ``value``. Has no effect if no project is specified. .. index:: --RTS (gnatpp) @@ -3572,30 +3701,6 @@ all the immediate units of the argument project. - .. index:: --gnat83 (gnatpp) - - :switch:`--gnat83` - Ada 83 mode - - - .. index:: --gnat95 (gnatpp) - - :switch:`--gnat95` - Ada 95 mode - - - .. index:: --gnat2005 (gnatpp) - - :switch:`--gnat2005` - Ada 2005 mode - - - .. index:: --gnat2012 (gnatpp) - - :switch:`--gnat2012` - Ada 2012 mode - - .. _Formatting_Rules: Formatting Rules @@ -3685,10 +3790,10 @@ the same line. A whole-line comment is indented according to the surrounding code, - with some exceptions. Comments that start in column 1 are kept - there. If possible, comments are not moved so far to the right that - the maximum line length is exceeded. The ``--comments-unchanged`` - option turns off comment formatting. Special-form comments such as + with some exceptions. Comments that start in column 1 are kept + there. If possible, comments are not moved so far to the right that + the maximum line length is exceeded. The ``--comments-unchanged`` + option turns off comment formatting. Special-form comments such as SPARK-style ``--#...`` are left alone. For an end-of-line comment, ``gnatpp`` tries to leave the same @@ -3713,7 +3818,7 @@ are formatted according to the ``--comments-gnat-beginning`` and ``--comments-fill`` switches; other formatting switches are ignored. For example, ``--comments-only --comments-fill`` means to fill comment - paragraphs, and do nothing else. Likewise, ``--comments-only + paragraphs, and do nothing else. Likewise, ``--comments-only --comments-gnat-beginning`` ensures comments start with at least two spaces after ``--``, and ``--comments-only --comments-gnat-beginning --comments-fill`` does both. If ``--comments-only`` is given without @@ -3730,11 +3835,11 @@ the same casing as the corresponding defining identifier. You control the casing for defining occurrences via the ``--name...`` - switches. With ``--name-case-as-declared``, which is the default, + switches. With ``--name-case-as-declared``, which is the default, defining occurrences appear exactly as in the source file where they - are declared. The other values for this switch -- + are declared. The other values for this switch -- ``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case`` - -- result in upper, lower, or mixed case, respectively. If + -- result in upper, lower, or mixed case, respectively. If ``gnatpp`` changes the casing of a defining occurrence, it analogously changes the casing of all the usage occurrences of this name. @@ -3742,7 +3847,7 @@ If the defining occurrence of a name is not in the source compilation unit currently being processed by ``gnatpp``, the casing of each reference to this name is changed according to the switch (subject to - the dictionary file mechanism described below). Thus ``gnatpp`` acts + the dictionary file mechanism described below). Thus ``gnatpp`` acts as though the switch had affected the casing for the defining occurrence of the name. @@ -3779,7 +3884,7 @@ ``-n`` switch or explicit dictionary files. For example, by default the names ``Ada.Text_IO`` and ``GNAT.OS_Lib`` will appear as just shown, even in the presence of - a ``--name-upper-case`` switch. To ensure that even + a ``--name-upper-case`` switch. To ensure that even such names are rendered in uppercase, additionally supply the --dictionary=- switch (or else place these names in upper case in a dictionary file). @@ -3876,6 +3981,67 @@ Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1; end Test; + .. _Preprocessor_directives: + + Preprocessor Directives + ^^^^^^^^^^^^^^^^^^^^^^^ + + ``gnatpp`` has some support for preprocessor directives. + You can use preprocessor symbols, as in ``$symbol``. + In addition, you can use conditional compilation, + so long as the program text is syntactically legal Ada code + after removing all the preprocessor directives (lines starting + with ``#``). For example, ``gnatpp`` can format the following: + + .. code-block:: ada + + package P is + #IF SOMETHING + X : constant Integer := 123; + #ELSE + X : constant Integer := 456; + #END IF; + end P; + + which will be formatted as if it were: + + .. code-block:: ada + + package P is + X : constant Integer := 123; + X : constant Integer := 456; + end P; + + except that the ``#`` lines will be preserved. + However, ``gnatpp`` cannot format the following: + + .. code-block:: ada + + procedure P is + begin + #IF SOMETHING + if X = 0 then + #ELSE + if X = 1 then + #END IF; + null; + end if; + end P; + + because removing the ``#`` lines gives: + + .. code-block:: ada + + procedure P is + begin + if X = 0 then + if X = 1 then + null; + end if; + end P; + + which is not syntactically legal. + Legacy Switches ^^^^^^^^^^^^^^^ @@ -4005,11 +4171,6 @@ :switch:`-cl{nnn}` :switch:`--indent-continuation={nnn}` - .. index:: -ff (gnatpp) - - :switch:`-ff` - :switch:`--ff-after-pragma-page` - .. index:: -pipe (gnatpp) :switch:`-pipe` @@ -4079,7 +4240,7 @@ ``gnatstub`` creates empty but compilable bodies for library unit declarations, and empty but compilable - subunit for body stubs. + subunits for body stubs. ``gnatstub`` is a project-aware tool. (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of @@ -4090,24 +4251,10 @@ ``gnatstub`` switches is named ``gnatstub``. - To create a body or a subunit, ``gnatstub`` invokes the Ada - compiler and generates and uses the ASIS tree for the input source; - thus the input must be legal Ada code, and the tool should have all the - information needed to compile the input source. To provide this information, - you may specify as a tool parameter the project file the input source belongs to. - Another possibility is to specify the source search - path and needed configuration files in ``-cargs`` section of ``gnatstub`` - call, see the description of the ``gnatstub`` switches below. - - If the ``gnatstub`` argument source contains preprocessing directives - then the needed options should be provided to run preprocessor as a part of - the ``gnatstub`` call, and the generated body stub will correspond to - the preprocessed source. - By default, all the program unit bodies generated by ``gnatstub`` - raise the predefined ``Program_Error`` exception, which will catch - accidental calls of generated stubs. This behavior can be changed with - option ``--no-exception`` (see below). + raise ``Program_Error``, which will catch accidental calls of + generated stubs. This behavior can be changed with option + ``--no-exception`` (see below). .. _Running_gnatstub: @@ -4118,7 +4265,7 @@ :: - $ gnatstub [ switches ] filename [ -cargs gcc_switches ] + $ gnatstub [ switches ] {filename} where @@ -4126,12 +4273,12 @@ is the name of the source file that contains a library unit declaration for which a body must be created or a library unit body for which subunits must be created for the body stubs declared in this body. - The file name may contain the path information. + The file name may contain path information. If the name does not follow GNAT file naming conventions and the set of switches does not contain a project file that defines naming conventions, the name of the body file must be provided - explicitly as the value of the :switch:`-o{body-name}` option. + explicitly as the value of the :switch:`--output={body-name}` option. If the file name follows the GNAT file naming conventions and the name of the body file is not provided, ``gnatstub`` @@ -4140,13 +4287,9 @@ or creates the name file to generate using the standard GNAT naming conventions. - * *gcc_switches* is a list of switches for *gcc*. - They will be passed on to all compiler invocations made by - ``gnatstub`` to generate the ASIS trees. Here you can provide - ``-I`` switches to form the source search path, - use the ``-gnatec`` switch to set the configuration file, - use the ``-gnat05`` switch if sources should be compiled in - Ada 2005 mode etc. + 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. * *switches* is an optional sequence of switches as described in the next section @@ -4160,7 +4303,7 @@ .. index:: --version (gnatstub) :switch:`--version` - Display Copyright and version, then exit disregarding all other options. + Display copyright and version, then exit disregarding all other options. .. index:: --help (gnatstub) @@ -4181,8 +4324,7 @@ :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 as - tool argument. + has the value ``value``. Has no effect if no project is specified. .. index:: --RTS (gnatstub) @@ -4196,32 +4338,32 @@ :switch:`--subunits` Generate subunits for body stubs. If this switch is specified, - ``gnatstub`` expects a library unit body as an argument file, + ``gnatstub`` expects a library unit body as an argument file; otherwise a library unit declaration is expected. If a body stub already has a corresponding subunit, ``gnatstub`` does not generate anything for it. - .. index:: -f (gnatstub) - - :switch:`-f` + .. index:: --force (gnatstub) + + :switch:`--force` If the destination directory already contains a file with the name of the body file for the argument spec file, replace it with the generated body stub. This switch cannot be used together with ``--subunits``. - .. index:: -hs (gnatstub) - - :switch:`-hs` + .. index:: --comment-header-spec (gnatstub) + + :switch:`--comment-header-spec` Put the comment header (i.e., all the comments preceding the compilation unit) from the source of the library unit declaration into the body stub. - .. index:: -hg (gnatstub) - - :switch:`-hg` + .. index:: --comment-header-sample (gnatstub) + + :switch:`--comment-header-sample` Put a sample comment header into the body stub. @@ -4231,68 +4373,28 @@ Use the content of the file as the comment header for a generated body stub. - .. index:: -IDIR (gnatstub) - .. index:: -I- (gnatstub) - - :switch:`-I{DIR}`, :switch:`-I-` - These switches have the same meaning as in calls to - ``gcc``. - They define the source search path in the call to - ``gcc`` issued - by ``gnatstub`` to compile an argument source file. - - - .. index:: -gnatec (gnatstub) - - :switch:`-gnatec{PATH}` - This switch has the same meaning as in calls to ``gcc``. - It defines the additional configuration file to be passed to the call to - ``gcc`` issued - by ``gnatstub`` to compile an argument source file. - - - .. index:: -gnatyM (gnatstub) - - :switch:`-gnatyM{n}` - (``n`` is a non-negative integer). Set the maximum line length that is - allowed in a source file. The default is 79. The maximum value that can be - specified is 32767. Note that in the special case of configuration - pragma files, the maximum is always 32767 regardless of whether or - not this switch appears. - - - .. index:: -gnaty (gnatstub) - - :switch:`-gnaty{n}` - (``n`` is a non-negative integer from 1 to 9). Set the indentation level in - the generated body sample to ``n``. + .. index:: --max-line-length (gnatstub) + + :switch:`--max-line-length={n}` + (``n`` is a non-negative integer). Set the maximum line length for + the output files. The default is 79. The maximum value that can be + specified is 32767. + + + .. index:: --indentation (gnatstub) + + :switch:`--indentation={n}` + (``n`` is an integer from 1 to 9). Set the indentation level in + the generated files to ``n``. The default indentation is 3. - .. index:: -gnatyo (gnatstub) - - :switch:`-gnatyo` + .. index:: --alphabetical-order (gnatstub) + + :switch:`--alphabetical-order` Order local bodies alphabetically. (By default local bodies are ordered - in the same way as the corresponding local specs in the argument spec file.) - - - .. index:: -i (gnatstub) - - :switch:`-i{n}` - Same as :switch:`-gnaty{n}`` - - - .. index:: -k (gnatstub) - - :switch:`-k` - Do not remove the tree file (i.e., the snapshot of the compiler internal - structures used by ``gnatstub``) after creating the body stub. - - - .. index:: -l (gnatstub) - - :switch:`-l{n}` - Same as ``-gnatyM`n``` + in the same way as the corresponding local specs in the argument + spec file.) .. index:: --no-exception (gnatstub) @@ -4309,78 +4411,118 @@ unit. + .. index:: --files (gnatstub) + + :switch:`--files={filename}` + 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. + + + .. index:: --output (gnatstub) + + :switch:`--output={body-name}` + Body file name. This should be set if the argument file name does + not follow the default GNAT file naming conventions, and the naming + conventions are not specified by a project file. If this switch and + ``-P`` are both omitted, the name for the body will be obtained + according to the default GNAT file naming conventions. + + + .. index:: --output-dir (gnatstub) + + :switch:`--output-dir={dir-name}` + The directory in which to place the output files. + If this switch is not set, the generated library unit body is + placed in the current directory, and generated sununits + in the directory where the argument body is located. + + + .. index:: --wide-character-encoding (gnatstub) + + :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:: --quiet (gnatstub) + .. index:: -q (gnatstub) + + :switch:`--quiet` / :switch:`-q` + Quiet mode. + + + .. index:: --verbose (gnatstub) + .. index:: -v (gnatstub) + + :switch:`--verbose` / :switch:`-v` + Verbose mode. + + Legacy Switches + ^^^^^^^^^^^^^^^ + + Some switches have a short form, mostly for legacy reasons, + as shown below. + + .. index:: -M (gnatstub) + + :switch:`-gnatyM{nnn}` + :switch:`--max-line-length={nnn}` + + .. index:: -i (gnatstub) + + :switch:`-i{nnn}` + :switch:`--indentation={nnn}` + + .. index:: -gnaty (gnatstub) + + :switch:`-gnaty{nnn}` + :switch:`--indentation={nnn}` + + .. index:: -f (gnatstub) + + :switch:`-f` + :switch:`--force` + + .. index:: -gnatyo (gnatstub) + + :switch:`-gnatyo` + :switch:`--alphabetical-order` + + .. index:: -hg (gnatstub) + + :switch:`-hg` + :switch:`--comment-header-sample` + + .. index:: -hs (gnatstub) + + :switch:`-hs` + :switch:`--comment-header-spec` + .. index:: -o (gnatstub) - :switch:`-o {body-name}` - Body file name. This should be set if the argument file name does not - follow - the GNAT file naming - conventions. If this switch is omitted the default name for the body will be - obtained - from the argument file name according to the GNAT file naming conventions. - - - .. index:: --dir (gnatstub) - - :switch:`--dir={dir-name}` - The path to the directory to place the generated files into. - If this switch is not set, the generated library unit body is - placed in the current directory, and generated sununits - - in the directory where the argument body is located. - + :switch:`-o {output-file}` + :switch:`--output={output-file}` + + .. index:: -dir (gnatstub) + + :switch:`-dir {dir-name}` + :switch:`--output-dir={dir-name}` .. index:: -W (gnatstub) :switch:`-W{e}` - Specify the wide character encoding method for the output body file. - ``e`` is one of the following: - - ==== ================================== - *h* Hex encoding - *u* Upper half encoding - *s* Shift/JIS encoding - *e* EUC encoding - *8* UTF-8 encoding - *b* Brackets encoding (default value) - ==== ================================== - - - .. index:: -q (gnatstub) - - :switch:`-q` - Quiet mode: do not generate a confirmation when a body is - successfully created, and do not generate a message when a body is not - required for an - argument unit. - - - .. index:: -r (gnatstub) - - :switch:`-r` - Reuse the tree file (if it exists) instead of creating it. Instead of - creating the tree file for the library unit declaration, ``gnatstub`` - tries to find it in the current directory and use it for creating - a body. If the tree file is not found, no body is created. This option - also implies ``-k``, whether or not - the latter is set explicitly. - - - .. index:: -t (gnatstub) - - :switch:`-t` - Overwrite the existing tree file. If the current directory already - contains the file which, according to the GNAT file naming rules should - be considered as a tree file for the argument source file, - ``gnatstub`` - will refuse to create the tree file needed to create a sample body - unless this option is set. - - - .. index:: -v (gnatstub) - - :switch:`-v` - Verbose mode: generate version information. - + :switch:`--wide-character-encoding={e}` + + .. index:: -files (gnatstub) + + :switch:`-files {filename}` + :switch:`--files={filename}` .. only:: PRO or GPL @@ -4632,7 +4774,7 @@ :switch:`--subdir={dirname}` Test packages are placed in a subdirectory of the corresponding source directory, with the name ``dirname``. Thus, each set of unit tests is located - in a subdirectory of the code under test. If the sources are in separate + in a subdirectory of the code under test. If the sources are in separate directories, each source directory has a test subdirectory named ``dirname``.