Google Git
Sign in
gnu / gcc / refs/heads/releases/gcc-9 / . / gcc / ada / doc / gnat_ugn / gnat_utility_programs.rst
blob: 17ce45a4543fbcf663ed8632dbac3b79ac77685a [file] [log] [blame]
.. role:: switch(samp)
.. |rightarrow| unicode:: 0x2192
.. _GNAT_Utility_Programs:
*********************
GNAT Utility Programs
*********************
This chapter describes a number of utility programs:
.. only:: PRO or GPL
* :ref:`The_File_Cleanup_Utility_gnatclean`
* :ref:`The_GNAT_Library_Browser_gnatls`
* :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
* :ref:`The_Ada_to_HTML_Converter_gnathtml`
* :ref:`The_Ada-to-XML_Converter_gnat2xml`
* :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_Unit_Test_Generator_gnattest`
* :ref:`The_Backtrace_Symbolizer_gnatsymbolize`
It also describes how several of these tools can be used in conjunction
with project files: :ref:`Using_Project_Files_with_GNAT_Tools`
.. only:: FSF
* :ref:`The_File_Cleanup_Utility_gnatclean`
* :ref:`The_GNAT_Library_Browser_gnatls`
* :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
* :ref:`The_Ada_to_HTML_Converter_gnathtml`
Other GNAT utilities are described elsewhere in this manual:
* :ref:`Handling_Arbitrary_File_Naming_Conventions_with_gnatname`
* :ref:`File_Name_Krunching_with_gnatkr`
* :ref:`Renaming_Files_with_gnatchop`
* :ref:`Preprocessing_with_gnatprep`
.. _The_File_Cleanup_Utility_gnatclean:
The File Cleanup Utility ``gnatclean``
======================================
.. index:: File cleanup tool
.. index:: gnatclean
``gnatclean`` is a tool that allows the deletion of files produced by the
compiler, binder and linker, including ALI files, object files, tree files,
expanded source files, library files, interface copy source files, binder
generated files and executable files.
.. _Running_gnatclean:
Running ``gnatclean``
---------------------
The ``gnatclean`` command has the form:
::
$ gnatclean switches names
where ``names`` is a list of source file names. Suffixes :file:`.ads` and
:file:`adb` may be omitted. If a project file is specified using switch
:switch:`-P`, then ``names`` may be completely omitted.
In normal mode, ``gnatclean`` delete the files produced by the compiler and,
if switch :switch:`-c` is not specified, by the binder and
the linker. In informative-only mode, specified by switch
:switch:`-n`, the list of files that would have been deleted in
normal mode is listed, but no file is actually deleted.
.. _Switches_for_gnatclean:
Switches for ``gnatclean``
--------------------------
``gnatclean`` recognizes the following switches:
.. index:: --version (gnatclean)
:switch:`--version`
Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatclean)
:switch:`--help`
If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
:switch:`--subdirs={subdir}`
Actual object directory of each project file is the subdirectory subdir of the
object directory specified or defaulted in the project file.
:switch:`--unchecked-shared-lib-imports`
By default, shared library projects are not allowed to import static library
projects. When this switch is used on the command line, this restriction is
relaxed.
.. index:: -c (gnatclean)
:switch:`-c`
Only attempt to delete the files produced by the compiler, not those produced
by the binder or the linker. The files that are not to be deleted are library
files, interface copy files, binder generated files and executable files.
.. index:: -D (gnatclean)
:switch:`-D {dir}`
Indicate that ALI and object files should normally be found in directory ``dir``.
.. index:: -F (gnatclean)
:switch:`-F`
When using project files, if some errors or warnings are detected during
parsing and verbose mode is not in effect (no use of switch
-v), then error lines start with the full path name of the project
file, rather than its simple file name.
.. index:: -h (gnatclean)
:switch:`-h`
Output a message explaining the usage of ``gnatclean``.
.. index:: -n (gnatclean)
:switch:`-n`
Informative-only mode. Do not delete any files. Output the list of the files
that would have been deleted if this switch was not specified.
.. index:: -P (gnatclean)
:switch:`-P{project}`
Use project file ``project``. Only one such switch can be used.
When cleaning a project file, the files produced by the compilation of the
immediate sources or inherited sources of the project files are to be
deleted. This is not depending on the presence or not of executable names
on the command line.
.. index:: -q (gnatclean)
:switch:`-q`
Quiet output. If there are no errors, do not output anything, except in
verbose mode (switch -v) or in informative-only mode
(switch -n).
.. index:: -r (gnatclean)
:switch:`-r`
When a project file is specified (using switch -P),
clean all imported and extended project files, recursively. If this switch
is not specified, only the files related to the main project file are to be
deleted. This switch has no effect if no project file is specified.
.. index:: -v (gnatclean)
:switch:`-v`
Verbose mode.
.. index:: -vP (gnatclean)
:switch:`-vP{x}`
Indicates the verbosity of the parsing of GNAT project files.
:ref:`Switches_Related_to_Project_Files`.
.. index:: -X (gnatclean)
:switch:`-X{name}={value}`
Indicates that external variable ``name`` has the value ``value``.
The Project Manager will use this value for occurrences of
``external(name)`` when parsing the project file.
See :ref:`Switches_Related_to_Project_Files`.
.. index:: -aO (gnatclean)
:switch:`-aO{dir}`
When searching for ALI and object files, look in directory ``dir``.
.. index:: -I (gnatclean)
:switch:`-I{dir}`
Equivalent to :switch:`-aO{dir}`.
.. index:: -I- (gnatclean)
.. index:: Source files, suppressing search
:switch:`-I-`
Do not look for ALI or object files in the directory
where ``gnatclean`` was invoked.
.. _The_GNAT_Library_Browser_gnatls:
The GNAT Library Browser ``gnatls``
===================================
.. index:: Library browser
.. index:: ! gnatls
``gnatls`` is a tool that outputs information about compiled
units. It gives the relationship between objects, unit names and source
files. It can also be used to check the source dependencies of a unit
as well as various characteristics.
.. _Running_gnatls:
Running ``gnatls``
------------------
The ``gnatls`` command has the form
::
$ gnatls switches object_or_ali_file
The main argument is the list of object or :file:`ali` files
(see :ref:`The_Ada_Library_Information_Files`)
for which information is requested.
In normal mode, without additional option, ``gnatls`` produces a
four-column listing. Each line represents information for a specific
object. The first column gives the full path of the object, the second
column gives the name of the principal unit in this object, the third
column gives the status of the source and the fourth column gives the
full path of the source representing this unit.
Here is a simple example of use:
::
$ gnatls *.o
./demo1.o demo1 DIF demo1.adb
./demo2.o demo2 OK demo2.adb
./hello.o h1 OK hello.adb
./instr-child.o instr.child MOK instr-child.adb
./instr.o instr OK instr.adb
./tef.o tef DIF tef.adb
./text_io_example.o text_io_example OK text_io_example.adb
./tgef.o tgef DIF tgef.adb
The first line can be interpreted as follows: the main unit which is
contained in
object file :file:`demo1.o` is demo1, whose main source is in
:file:`demo1.adb`. Furthermore, the version of the source used for the
compilation of demo1 has been modified (DIF). Each source file has a status
qualifier which can be:
*OK (unchanged)*
The version of the source file used for the compilation of the
specified unit corresponds exactly to the actual source file.
*MOK (slightly modified)*
The version of the source file used for the compilation of the
specified unit differs from the actual source file but not enough to
require recompilation. If you use gnatmake with the option
:switch:`-m` (minimal recompilation), a file marked
MOK will not be recompiled.
*DIF (modified)*
No version of the source found on the path corresponds to the source
used to build this object.
*??? (file not found)*
No source file was found for this unit.
*HID (hidden, unchanged version not first on PATH)*
The version of the source that corresponds exactly to the source used
for compilation has been found on the path but it is hidden by another
version of the same source that has been modified.
.. _Switches_for_gnatls:
Switches for ``gnatls``
-----------------------
``gnatls`` recognizes the following switches:
.. index:: --version (gnatls)
:switch:`--version`
Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatls)
:switch:`--help`
If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatls)
:switch:`-a`
Consider all units, including those of the predefined Ada library.
Especially useful with :switch:`-d`.
.. index:: -d (gnatls)
:switch:`-d`
List sources from which specified units depend on.
.. index:: -h (gnatls)
:switch:`-h`
Output the list of options.
.. index:: -o (gnatls)
:switch:`-o`
Only output information about object files.
.. index:: -s (gnatls)
:switch:`-s`
Only output information about source files.
.. index:: -u (gnatls)
:switch:`-u`
Only output information about compilation units.
.. index:: -files (gnatls)
: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:: -aO (gnatls)
.. index:: -aI (gnatls)
.. index:: -I (gnatls)
.. index:: -I- (gnatls)
:switch:`-aO{dir}`, :switch:`-aI{dir}`, :switch:`-I{dir}`, :switch:`-I-`, :switch:`-nostdinc`
Source path manipulation. Same meaning as the equivalent ``gnatmake``
flags (:ref:`Switches_for_gnatmake`).
.. index:: -aP (gnatls)
:switch:`-aP{dir}`
Add ``dir`` at the beginning of the project search dir.
.. index:: --RTS (gnatls)
:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -v (gnatls)
:switch:`-v`
Verbose mode. Output the complete source, object and project paths. Do not use
the default column layout but instead use long format giving as much as
information possible on each requested units, including special
characteristics such as:
* *Preelaborable*: The unit is preelaborable in the Ada sense.
* *No_Elab_Code*: No elaboration code has been produced by the compiler for this unit.
* *Pure*: The unit is pure in the Ada sense.
* *Elaborate_Body*: The unit contains a pragma Elaborate_Body.
* *Remote_Types*: The unit contains a pragma Remote_Types.
* *Shared_Passive*: The unit contains a pragma Shared_Passive.
* *Predefined*: This unit is part of the predefined environment and cannot be modified
by the user.
* *Remote_Call_Interface*: The unit contains a pragma Remote_Call_Interface.
.. _Example_of_gnatls_Usage:
Example of ``gnatls`` Usage
---------------------------
Example of using the verbose switch. Note how the source and
object paths are affected by the -I switch.
::
$ gnatls -v -I.. demo1.o
GNATLS 5.03w (20041123-34)
Copyright 1997-2004 Free Software Foundation, Inc.
Source Search Path:
<Current_Directory>
../
/home/comar/local/adainclude/
Object Search Path:
<Current_Directory>
../
/home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
Project Search Path:
<Current_Directory>
/home/comar/local/lib/gnat/
./demo1.o
Unit =>
Name => demo1
Kind => subprogram body
Flags => No_Elab_Code
Source => demo1.adb modified
The following is an example of use of the dependency list.
Note the use of the -s switch
which gives a straight list of source files. This can be useful for
building specialized scripts.
::
$ gnatls -d demo2.o
./demo2.o demo2 OK demo2.adb
OK gen_list.ads
OK gen_list.adb
OK instr.ads
OK instr-child.ads
$ gnatls -d -s -a demo1.o
demo1.adb
/home/comar/local/adainclude/ada.ads
/home/comar/local/adainclude/a-finali.ads
/home/comar/local/adainclude/a-filico.ads
/home/comar/local/adainclude/a-stream.ads
/home/comar/local/adainclude/a-tags.ads
gen_list.ads
gen_list.adb
/home/comar/local/adainclude/gnat.ads
/home/comar/local/adainclude/g-io.ads
instr.ads
/home/comar/local/adainclude/system.ads
/home/comar/local/adainclude/s-exctab.ads
/home/comar/local/adainclude/s-finimp.ads
/home/comar/local/adainclude/s-finroo.ads
/home/comar/local/adainclude/s-secsta.ads
/home/comar/local/adainclude/s-stalib.ads
/home/comar/local/adainclude/s-stoele.ads
/home/comar/local/adainclude/s-stratt.ads
/home/comar/local/adainclude/s-tasoli.ads
/home/comar/local/adainclude/s-unstyp.ads
/home/comar/local/adainclude/unchconv.ads
.. _The_Cross-Referencing_Tools_gnatxref_and_gnatfind:
The Cross-Referencing Tools ``gnatxref`` and ``gnatfind``
=========================================================
.. index:: ! gnatxref
.. index:: ! gnatfind
The compiler generates cross-referencing information (unless
you set the :switch:`-gnatx` switch), which are saved in the :file:`.ali` files.
This information indicates where in the source each entity is declared and
referenced. Note that entities in package Standard are not included, but
entities in all other predefined units are included in the output.
Before using any of these two tools, you need to compile successfully your
application, so that GNAT gets a chance to generate the cross-referencing
information.
The two tools ``gnatxref`` and ``gnatfind`` take advantage of this
information to provide the user with the capability to easily locate the
declaration and references to an entity. These tools are quite similar,
the difference being that ``gnatfind`` is intended for locating
definitions and/or references to a specified entity or entities, whereas
``gnatxref`` is oriented to generating a full report of all
cross-references.
To use these tools, you must not compile your application using the
:switch:`-gnatx` switch on the ``gnatmake`` command line
(see :ref:`The_GNAT_Make_Program_gnatmake`). Otherwise, cross-referencing
information will not be generated.
.. _gnatxref_Switches:
``gnatxref`` Switches
---------------------
The command invocation for ``gnatxref`` is:
::
$ gnatxref [ switches ] sourcefile1 [ sourcefile2 ... ]
where
``sourcefile1`` [, ``sourcefile2`` ...]
identify the source files for which a report is to be generated. The
``with``\ ed units will be processed too. You must provide at least one file.
These file names are considered to be regular expressions, so for instance
specifying :file:`source\*.adb` is the same as giving every file in the current
directory whose name starts with :file:`source` and whose extension is
:file:`adb`.
You shouldn't specify any directory name, just base names. ``gnatxref``
and ``gnatfind`` will be able to locate these files by themselves using
the source path. If you specify directories, no result is produced.
The following switches are available for ``gnatxref``:
.. index:: --version (gnatxref)
:switch:`--version`
Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatxref)
:switch:`--help`
If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatxref)
:switch:`-a`
If this switch is present, ``gnatfind`` and ``gnatxref`` will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
libraries from being parsed, thus making ``gnatfind`` and ``gnatxref``
much faster, and their output much smaller. Read-only here refers to access
or permissions status in the file system for the current user.
.. index:: -aIDIR (gnatxref)
:switch:`-aI{DIR}`
When looking for source files also look in directory DIR. The order in which
source file search is undertaken is the same as for ``gnatmake``.
.. index:: -aODIR (gnatxref)
:switch:`aO{DIR}`
When -searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
``gnatmake``.
.. index:: -nostdinc (gnatxref)
:switch:`-nostdinc`
Do not look for sources in the system default directory.
.. index:: -nostdlib (gnatxref)
:switch:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --ext (gnatxref)
:switch:`--ext={extension}`
Specify an alternate ali file extension. The default is ``ali`` and other
extensions (e.g. ``gli`` for C/C++ sources) may be specified via this switch.
Note that if this switch overrides the default, only the new extension will
be considered.
.. index:: --RTS (gnatxref)
:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -d (gnatxref)
:switch:`-d`
If this switch is set ``gnatxref`` will output the parent type
reference for each matching derived types.
.. index:: -f (gnatxref)
:switch:`-f`
If this switch is set, the output file names will be preceded by their
directory (if the file was found in the search path). If this switch is
not set, the directory will not be printed.
.. index:: -g (gnatxref)
:switch:`-g`
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
``gnatfind`` and ``gnatxref``.
.. index:: -IDIR (gnatxref)
:switch:`-I{DIR}`
Equivalent to :switch:`-aODIR -aIDIR`.
.. index:: -pFILE (gnatxref)
:switch:`-p{FILE}`
Specify a configuration file to use to list the source and object directories.
If a file is specified, then the content of the source directory and object
directory lines are added as if they had been specified respectively
by :switch:`-aI` and :switch:`-aO`.
See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
of this configuration file.
:switch:`-u`
Output only unused symbols. This may be really useful if you give your
main compilation unit on the command line, as ``gnatxref`` will then
display every unused entity and 'with'ed package.
:switch:`-v`
Instead of producing the default output, ``gnatxref`` will generate a
:file:`tags` file that can be used by vi. For examples how to use this
feature, see :ref:`Examples_of_gnatxref_Usage`. The tags file is output
to the standard output, thus you will have to redirect it to a file.
All these switches may be in any order on the command line, and may even
appear after the file names. They need not be separated by spaces, thus
you can say ``gnatxref -ag`` instead of ``gnatxref -a -g``.
.. _gnatfind_Switches:
``gnatfind`` Switches
---------------------
The command invocation for ``gnatfind`` is:
::
$ gnatfind [ switches ] pattern[:sourcefile[:line[:column]]]
[file1 file2 ...]
with the following iterpretation of the command arguments:
*pattern*
An entity will be output only if it matches the regular expression found
in *pattern*, see :ref:`Regular_Expressions_in_gnatfind_and_gnatxref`.
Omitting the pattern is equivalent to specifying ``*``, which
will match any entity. Note that if you do not provide a pattern, you
have to provide both a sourcefile and a line.
Entity names are given in Latin-1, with uppercase/lowercase equivalence
for matching purposes. At the current time there is no support for
8-bit codes other than Latin-1, or for wide characters in identifiers.
*sourcefile*
``gnatfind`` will look for references, bodies or declarations
of symbols referenced in :file:`sourcefile`, at line ``line``
and column ``column``. See :ref:`Examples_of_gnatfind_Usage`
for syntax examples.
*line*
A decimal integer identifying the line number containing
the reference to the entity (or entities) to be located.
*column*
A decimal integer identifying the exact location on the
line of the first character of the identifier for the
entity reference. Columns are numbered from 1.
*file1 file2 ...*
The search will be restricted to these source files. If none are given, then
the search will be conducted for every library file in the search path.
These files must appear only after the pattern or sourcefile.
These file names are considered to be regular expressions, so for instance
specifying :file:`source\*.adb` is the same as giving every file in the current
directory whose name starts with :file:`source` and whose extension is
:file:`adb`.
The location of the spec of the entity will always be displayed, even if it
isn't in one of :file:`file1`, :file:`file2`, ... The
occurrences of the entity in the separate units of the ones given on the
command line will also be displayed.
Note that if you specify at least one file in this part, ``gnatfind`` may
sometimes not be able to find the body of the subprograms.
At least one of 'sourcefile' or 'pattern' has to be present on
the command line.
The following switches are available:
.. index:: --version (gnatfind)
:switch:`--version`
Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatfind)
:switch:`--help`
If :switch:`--version` was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatfind)
:switch:`-a`
If this switch is present, ``gnatfind`` and ``gnatxref`` will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
libraries from being parsed, thus making ``gnatfind`` and ``gnatxref``
much faster, and their output much smaller. Read-only here refers to access
or permission status in the file system for the current user.
.. index:: -aIDIR (gnatfind)
:switch:`-aI{DIR}`
When looking for source files also look in directory DIR. The order in which
source file search is undertaken is the same as for ``gnatmake``.
.. index:: -aODIR (gnatfind)
:switch:`-aO{DIR}`
When searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
``gnatmake``.
.. index:: -nostdinc (gnatfind)
:switch:`-nostdinc`
Do not look for sources in the system default directory.
.. index:: -nostdlib (gnatfind)
:switch:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --ext (gnatfind)
:switch:`--ext={extension}`
Specify an alternate ali file extension. The default is ``ali`` and other
extensions may be specified via this switch. Note that if this switch
overrides the default, only the new extension will be considered.
.. index:: --RTS (gnatfind)
:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: -d (gnatfind)
:switch:`-d`
If this switch is set, then ``gnatfind`` will output the parent type
reference for each matching derived types.
.. index:: -e (gnatfind)
:switch:`-e`
By default, ``gnatfind`` accept the simple regular expression set for
``pattern``. If this switch is set, then the pattern will be
considered as full Unix-style regular expression.
.. index:: -f (gnatfind)
:switch:`-f`
If this switch is set, the output file names will be preceded by their
directory (if the file was found in the search path). If this switch is
not set, the directory will not be printed.
.. index:: -g (gnatfind)
:switch:`-g`
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
``gnatfind`` and ``gnatxref``.
.. index:: -IDIR (gnatfind)
:switch:`-I{DIR}`
Equivalent to :switch:`-aODIR -aIDIR`.
.. index:: -pFILE (gnatfind)
:switch:`-p{FILE}`
Specify a configuration file to use to list the source and object directories.
If a file is specified, then the content of the source directory and object
directory lines are added as if they had been specified respectively
by :switch:`-aI` and :switch:`-aO`.
See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
of this configuration file.
.. index:: -r (gnatfind)
:switch:`-r`
By default, ``gnatfind`` will output only the information about the
declaration, body or type completion of the entities. If this switch is
set, the ``gnatfind`` will locate every reference to the entities in
the files specified on the command line (or in every file in the search
path if no file is given on the command line).
.. index:: -s (gnatfind)
:switch:`-s`
If this switch is set, then ``gnatfind`` will output the content
of the Ada source file lines were the entity was found.
.. index:: -t (gnatfind)
:switch:`-t`
If this switch is set, then ``gnatfind`` will output the type hierarchy for
the specified type. It act like -d option but recursively from parent
type to parent type. When this switch is set it is not possible to
specify more than one file.
All these switches may be in any order on the command line, and may even
appear after the file names. They need not be separated by spaces, thus
you can say ``gnatxref -ag`` instead of
``gnatxref -a -g``.
As stated previously, ``gnatfind`` will search in every directory in the
search path. You can force it to look only in the current directory if
you specify ``*`` at the end of the command line.
.. _Configuration_Files_for_gnatxref_and_gnatfind:
Configuration Files for ``gnatxref`` and ``gnatfind``
-----------------------------------------------------
Configuration files are used by ``gnatxref`` and ``gnatfind`` to specify
the list of source and object directories to consider. They can be
specified via the :switch:`-p` switch.
The following lines can be included, in any order in the file:
* *src_dir=DIR*
[default: ``"./"``].
Specifies a directory where to look for source files. Multiple ``src_dir``
lines can be specified and they will be searched in the order they
are specified.
* *obj_dir=DIR*
[default: ``"./"``].
Specifies a directory where to look for object and library files. Multiple
``obj_dir`` lines can be specified, and they will be searched in the order
they are specified
Any other line will be silently ignored.
.. _Regular_Expressions_in_gnatfind_and_gnatxref:
Regular Expressions in ``gnatfind`` and ``gnatxref``
----------------------------------------------------
As specified in the section about ``gnatfind``, the pattern can be a
regular expression. Two kinds of regular expressions
are recognized:
* *Globbing pattern*
These are the most common regular expression. They are the same as are
generally used in a Unix shell command line, or in a DOS session.
Here is a more formal grammar:
::
regexp ::= term
term ::= elmt -- matches elmt
term ::= elmt elmt -- concatenation (elmt then elmt)
term ::= * -- any string of 0 or more characters
term ::= ? -- matches any character
term ::= [char {char}] -- matches any character listed
term ::= [char - char] -- matches any character in range
* *Full regular expression*
The second set of regular expressions is much more powerful. This is the
type of regular expressions recognized by utilities such as ``grep``.
The following is the form of a regular expression, expressed in same BNF
style as is found in the Ada Reference Manual:
::
regexp ::= term {| term} -- alternation (term or term ...)
term ::= item {item} -- concatenation (item then item)
item ::= elmt -- match elmt
item ::= elmt * -- zero or more elmt's
item ::= elmt + -- one or more elmt's
item ::= elmt ? -- matches elmt or nothing
elmt ::= nschar -- matches given character
elmt ::= [nschar {nschar}] -- matches any character listed
elmt ::= [^ nschar {nschar}] -- matches any character not listed
elmt ::= [char - char] -- matches chars in given range
elmt ::= \\ char -- matches given character
elmt ::= . -- matches any single character
elmt ::= ( regexp ) -- parens used for grouping
char ::= any character, including special characters
nschar ::= any character except ()[].*+?^
Here are a few examples:
``abcde|fghi``
will match any of the two strings ``abcde`` and ``fghi``,
``abc*d``
will match any string like ``abd``, ``abcd``, ``abccd``,
``abcccd``, and so on,
``[a-z]+``
will match any string which has only lowercase characters in it (and at
least one character.
.. _Examples_of_gnatxref_Usage:
Examples of ``gnatxref`` Usage
------------------------------
General Usage
^^^^^^^^^^^^^
For the following examples, we will consider the following units:
.. code-block:: ada
main.ads:
1: with Bar;
2: package Main is
3: procedure Foo (B : in Integer);
4: C : Integer;
5: private
6: D : Integer;
7: end Main;
main.adb:
1: package body Main is
2: procedure Foo (B : in Integer) is
3: begin
4: C := B;
5: D := B;
6: Bar.Print (B);
7: Bar.Print (C);
8: end Foo;
9: end Main;
bar.ads:
1: package Bar is
2: procedure Print (B : Integer);
3: end bar;
The first thing to do is to recompile your application (for instance, in
that case just by doing a ``gnatmake main``, so that GNAT generates
the cross-referencing information.
You can then issue any of the following commands:
* ``gnatxref main.adb``
``gnatxref`` generates cross-reference information for main.adb
and every unit 'with'ed by main.adb.
The output would be:
::
B Type: Integer
Decl: bar.ads 2:22
B Type: Integer
Decl: main.ads 3:20
Body: main.adb 2:20
Ref: main.adb 4:13 5:13 6:19
Bar Type: Unit
Decl: bar.ads 1:9
Ref: main.adb 6:8 7:8
main.ads 1:6
C Type: Integer
Decl: main.ads 4:5
Modi: main.adb 4:8
Ref: main.adb 7:19
D Type: Integer
Decl: main.ads 6:5
Modi: main.adb 5:8
Foo Type: Unit
Decl: main.ads 3:15
Body: main.adb 2:15
Main Type: Unit
Decl: main.ads 2:9
Body: main.adb 1:14
Print Type: Unit
Decl: bar.ads 2:15
Ref: main.adb 6:12 7:12
This shows that the entity ``Main`` is declared in main.ads, line 2, column 9,
its body is in main.adb, line 1, column 14 and is not referenced any where.
The entity ``Print`` is declared in :file:`bar.ads`, line 2, column 15 and it
is referenced in :file:`main.adb`, line 6 column 12 and line 7 column 12.
* ``gnatxref package1.adb package2.ads``
``gnatxref`` will generates cross-reference information for
:file:`package1.adb`, :file:`package2.ads` and any other package ``with``\ ed by any
of these.
Using ``gnatxref`` with ``vi``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
``gnatxref`` can generate a tags file output, which can be used
directly from ``vi``. Note that the standard version of ``vi``
will not work properly with overloaded symbols. Consider using another
free implementation of ``vi``, such as ``vim``.
::
$ gnatxref -v gnatfind.adb > tags
The following command will generate the tags file for ``gnatfind`` itself
(if the sources are in the search path!):
::
$ gnatxref -v gnatfind.adb > tags
From ``vi``, you can then use the command :samp:`:tag {entity}`
(replacing ``entity`` by whatever you are looking for), and vi will
display a new file with the corresponding declaration of entity.
.. _Examples_of_gnatfind_Usage:
Examples of ``gnatfind`` Usage
------------------------------
* ``gnatfind -f xyz:main.adb``
Find declarations for all entities xyz referenced at least once in
main.adb. The references are search in every library file in the search
path.
The directories will be printed as well (as the ``-f``
switch is set)
The output will look like:
::
directory/main.ads:106:14: xyz <= declaration
directory/main.adb:24:10: xyz <= body
directory/foo.ads:45:23: xyz <= declaration
I.e., one of the entities xyz found in main.adb is declared at
line 12 of main.ads (and its body is in main.adb), and another one is
declared at line 45 of foo.ads
* ``gnatfind -fs xyz:main.adb``
This is the same command as the previous one, but ``gnatfind`` will
display the content of the Ada source file lines.
The output will look like:
::
directory/main.ads:106:14: xyz <= declaration
procedure xyz;
directory/main.adb:24:10: xyz <= body
procedure xyz is
directory/foo.ads:45:23: xyz <= declaration
xyz : Integer;
This can make it easier to find exactly the location your are looking
for.
* ``gnatfind -r "*x*":main.ads:123 foo.adb``
Find references to all entities containing an x that are
referenced on line 123 of main.ads.
The references will be searched only in main.ads and foo.adb.
* ``gnatfind main.ads:123``
Find declarations and bodies for all entities that are referenced on
line 123 of main.ads.
This is the same as ``gnatfind "*":main.adb:123```
* ``gnatfind mydir/main.adb:123:45``
Find the declaration for the entity referenced at column 45 in
line 123 of file main.adb in directory mydir. Note that it
is usual to omit the identifier name when the column is given,
since the column position identifies a unique reference.
The column has to be the beginning of the identifier, and should not
point to any character in the middle of the identifier.
.. _The_Ada_to_HTML_Converter_gnathtml:
The Ada to HTML Converter ``gnathtml``
======================================
.. index:: ! gnathtml
``gnathtml`` is a Perl script that allows Ada source files to be browsed using
standard Web browsers. For installation information, see :ref:`Installing_gnathtml`.
Ada reserved keywords are highlighted in a bold font and Ada comments in
a blue font. Unless your program was compiled with the gcc :switch:`-gnatx`
switch to suppress the generation of cross-referencing information, user
defined variables and types will appear in a different color; you will
be able to click on any identifier and go to its declaration.
.. _Invoking_gnathtml:
Invoking ``gnathtml``
---------------------
The command line is as follows:
::
$ perl gnathtml.pl [ switches ] ada-files
You can specify as many Ada files as you want. ``gnathtml`` will generate
an html file for every ada file, and a global file called :file:`index.htm`.
This file is an index of every identifier defined in the files.
The following switches are available:
.. index:: -83 (gnathtml)
:samp:`83`
Only the Ada 83 subset of keywords will be highlighted.
.. index:: -cc (gnathtml)
:samp:`cc {color}`
This option allows you to change the color used for comments. The default
value is green. The color argument can be any name accepted by html.
.. index:: -d (gnathtml)
:samp:`d`
If the Ada files depend on some other files (for instance through
``with`` clauses, the latter files will also be converted to html.
Only the files in the user project will be converted to html, not the files
in the run-time library itself.
.. index:: -D (gnathtml)
:samp:`D`
This command is the same as :switch:`-d` above, but ``gnathtml`` will
also look for files in the run-time library, and generate html files for them.
.. index:: -ext (gnathtml)
:samp:`ext {extension}`
This option allows you to change the extension of the generated HTML files.
If you do not specify an extension, it will default to :file:`htm`.
.. index:: -f (gnathtml)
:samp:`f`
By default, gnathtml will generate html links only for global entities
('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.
.. index:: -l (gnathtml)
:samp:`l {number}`
If this switch is provided and ``number`` is not 0, then
``gnathtml`` will number the html files every ``number`` line.
.. index:: -I (gnathtml)
:samp:`I {dir}`
Specify a directory to search for library files (:file:`.ALI` files) and
source files. You can provide several -I switches on the command line,
and the directories will be parsed in the order of the command line.
.. index:: -o (gnathtml)
:samp:`o {dir}`
Specify the output directory for html files. By default, gnathtml will
saved the generated html files in a subdirectory named :file:`html/`.
.. index:: -p (gnathtml)
:samp:`p {file}`
If you are using Emacs and the most recent Emacs Ada mode, which provides
a full Integrated Development Environment for compiling, checking,
running and debugging applications, you may use :file:`.gpr` files
to give the directories where Emacs can find sources and object files.
Using this switch, you can tell gnathtml to use these files.
This allows you to get an html version of your application, even if it
is spread over multiple directories.
.. index:: -sc (gnathtml)
:samp:`sc {color}`
This switch allows you to change the color used for symbol
definitions.
The default value is red. The color argument can be any name accepted by html.
.. index:: -t (gnathtml)
:samp:`t {file}`
This switch provides the name of a file. This file contains a list of
file names to be converted, and the effect is exactly as though they had
appeared explicitly on the command line. This
is the recommended way to work around the command line length limit on some
systems.
.. _Installing_gnathtml:
Installing ``gnathtml``
-----------------------
``Perl`` needs to be installed on your machine to run this script.
``Perl`` is freely available for almost every architecture and
operating system via the Internet.
On Unix systems, you may want to modify the first line of the script
``gnathtml``, to explicitly specify where Perl
is located. The syntax of this line is:
::
#!full_path_name_to_perl
Alternatively, you may run the script using the following command line:
::
$ perl gnathtml.pl [ switches ] files
.. -- +---------------------------------------------------------------------+
.. -- | The following sections are present only in the PRO and GPL editions |
.. -- +---------------------------------------------------------------------+
.. only:: PRO or GPL
.. _The_Ada-to-XML_converter_gnat2xml:
The Ada-to-XML converter ``gnat2xml``
=====================================
.. index:: ! gnat2xml
.. index:: XML generation
The ``gnat2xml`` tool is an ASIS-based utility that converts
Ada source code into XML.
``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
``gnat2xml`` switches is named ``gnat2xml``.
.. _Switches_for_``gnat2xml``:
Switches for ``gnat2xml``
-------------------------
``gnat2xml`` takes Ada source code as input, and produces XML
that conforms to the schema.
Usage:
::
$ gnat2xml [options] filenames [-files filename] [-cargs gcc_switches]
Options:
:switch:`--help`
Generate usage information and quit, ignoring all other options
:switch:`-h`
Same as ``--help``
:switch:`--version`
Print version and quit, ignoring all other options
: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.
:switch:`-U`
If a project file is specified and no argument source is explicitly
specified, 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.
: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.
:switch:`--RTS={rts-path}`
Specifies the default location of the runtime
library. Same meaning as the equivalent ``gnatmake`` flag
(:ref:`Switches_for_gnatmake`).
:switch:`--incremental`
Incremental processing on a per-file basis. Source files are
only processed if they have been modified, or if files they depend
on have been modified. This is similar to the way gnatmake/gprbuild
only compiles files that need to be recompiled. A project file
is required in this mode.
:switch:`-j{n}`
In :switch:`--incremental` mode, use ``n`` ``gnat2xml``
processes to perform XML generation in parallel. If ``n`` is 0, then
the maximum number of parallel tree creations is the number of core
processors on the platform.
:switch:`--output-dir={dir}`
Generate one .xml file for each Ada source file, in
directory :file:`dir`. (Default is to generate the XML to standard
output.)
:switch:`-I{include-dir}`
Directories to search for dependencies.
You can also set the ADA_INCLUDE_PATH environment variable for this.
:switch:`--compact`
Debugging version, with interspersed source, and a more
compact representation of "sloc". This version does not conform
to any schema.
:switch:`--rep-clauses`
generate representation clauses (see :ref:`Generating_Representation_Clauses`).
: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 simultaneously.
:switch:`--ignore={filename}`
Do not process the sources listed in a specified file. This option cannot
be used in incremental mode.
:switch:`-q`
Quiet
:switch:`-v`
Verbose
:switch:`-cargs` ...
Options to pass to gcc
If a project file is specified and no argument source is explicitly
specified, and no :switch:`-U` is specified, then the set of processed
sources is all the immediate units of the argument project.
Example:
::
$ gnat2xml -v -output-dir=xml-files *.ad[sb]
The above will create \*.xml files in the :file:`xml-files` subdirectory.
For example, if there is an Ada package Mumble.Dumble, whose spec and
body source code lives in mumble-dumble.ads and mumble-dumble.adb,
the above will produce xml-files/mumble-dumble.ads.xml and
xml-files/mumble-dumble.adb.xml.
.. _Other_Programs:
Other Programs
--------------
The distribution includes two other programs that are related to
``gnat2xml``:
``gnat2xsd`` is the schema generator, which generates the schema
to standard output, based on the structure of Ada as encoded by
ASIS. You don't need to run ``gnat2xsd`` in order to use
``gnat2xml``. To generate the schema, type:
::
$ gnat2xsd > ada-schema.xsd
``gnat2xml`` generates XML files that will validate against
:file:`ada-schema.xsd`.
``xml2gnat`` is a back-translator that translates the XML back into
Ada source code. This is primarily for the purpose of testing
``gnat2xml``, rather than for users. The Ada generated by ``xml2gnat``
has identical semantics to the original Ada code passed to
``gnat2xml``. It is not textually identical, however --- for example,
no attempt is made to preserve the original indentation.
The ``xml2gnat`` command line contains a list of the same Ada files
passed to gnat2xml (not the names of xml files). The xml files are
assumed to be in an 'xml' subdirectory of the directory in which the
Ada source files are. So for example, if the Ada source file is
some/dir/mumble.adb, then the xml file is found in
some/dir/xml/mumble.adb.xml. You should use the :switch:`--output-dir`
switch of ``gnat2xml`` to tell it to generate the output in the xml
subdirectory, so ``xml2gnat`` can find it.
Output goes into subdirectories "generated_ada" and "self_rep" of the
output directory, which is the current directory by default, but can
be overridden with --output-dir=dir on the command line.
.. _Structure_of_the_XML:
Structure of the XML
--------------------
The primary documentation for the structure of the XML generated by
``gnat2xml`` is the schema (see ``gnat2xsd`` above). The
following documentation gives additional details needed to understand
the schema and therefore the XML.
The elements listed under Defining Occurrences, Usage Occurrences, and
Other Elements represent the syntactic structure of the Ada program.
Element names are given in lower case, with the corresponding element
type Capitalized_Like_This. The element and element type names are
derived directly from the ASIS enumeration type Flat_Element_Kinds,
declared in Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_``
removed. For example, the ASIS enumeration literal
An_Assignment_Statement corresponds to the XML element
assignment_statement of XML type Assignment_Statement.
To understand the details of the schema and the corresponding XML, it is
necessary to understand the ASIS standard, as well as the GNAT-specific
extension to ASIS.
A defining occurrence is an identifier (or character literal or operator
symbol) declared by a declaration. A usage occurrence is an identifier
(or ...) that references such a declared entity. For example, in:
.. code-block:: ada
type T is range 1..10;
X, Y : constant T := 1;
The first 'T' is the defining occurrence of a type. The 'X' is the
defining occurrence of a constant, as is the 'Y', and the second 'T' is
a usage occurrence referring to the defining occurrence of T.
Each element has a 'sloc' (source location), and subelements for each
syntactic subtree, reflecting the Ada grammar as implemented by ASIS.
The types of subelements are as defined in the ASIS standard. For
example, for the right-hand side of an assignment_statement we have
the following comment in asis-statements.ads:
.. code-block:: ada
------------------------------------------------------------------------------
-- 18.3 function Assignment_Expression
------------------------------------------------------------------------------
function Assignment_Expression
(Statement : Asis.Statement)
return Asis.Expression;
------------------------------------------------------------------------------
...
-- Returns the expression from the right hand side of the assignment.
...
-- Returns Element_Kinds:
-- An_Expression
The corresponding sub-element of type Assignment_Statement is:
::
<xsd:element name="assignment_expression_q" type="Expression_Class"/>
where Expression_Class is defined by an xsd:choice of all the
various kinds of expression.
The 'sloc' of each element indicates the starting and ending line and
column numbers. Column numbers are character counts; that is, a tab
counts as 1, not as however many spaces it might expand to.
Subelements of type Element have names ending in '_q' (for ASIS
"Query"), and those of type Element_List end in '_ql'
("Query returning List").
Some subelements are 'Boolean'. For example, Private_Type_Definition
has has_abstract_q and has_limited_q, to indicate whether those
keywords are present, as in ``type T is abstract limited private;``.
False is represented by a Nil_Element. True is represented
by an element type specific to that query (for example, Abstract and
Limited).
The root of the tree is a Compilation_Unit, with attributes:
* unit_kind, unit_class, and unit_origin. These are strings that match the
enumeration literals of types Unit_Kinds, Unit_Classes, and Unit_Origins
in package Asis.
* unit_full_name is the full expanded name of the unit, starting from a
root library unit. So for ``package P.Q.R is ...``,
``unit_full_name="P.Q.R"``. Same for ``separate (P.Q) package R is ...``.
* def_name is the same as unit_full_name for library units; for subunits,
it is just the simple name.
* source_file is the name of the Ada source file. For example, for
the spec of ``P.Q.R``, ``source_file="p-q-r.ads"``. This allows one to
interpret the source locations --- the 'sloc' of all elements
within this Compilation_Unit refers to line and column numbers
within the named file.
Defining occurrences have these attributes:
* def_name is the simple name of the declared entity, as written in the Ada
source code.
* def is a unique URI of the form:
::
ada://kind/fully/qualified/name
where:
* kind indicates the kind of Ada entity being declared (see below), and
* fully/qualified/name, is the fully qualified name of the Ada
entity, with each of 'fully', 'qualified', and 'name' being
mangled for uniqueness. We do not document the mangling
algorithm, which is subject to change; we just guarantee that the
names are unique in the face of overloading.
* type is the type of the declared object, or ``null`` for
declarations of things other than objects.
Usage occurrences have these attributes:
* ref_name is the same as the def_name of the corresponding defining
occurrence. This attribute is not of much use, because of
overloading; use ref for lookups, instead.
* ref is the same as the def of the corresponding defining
occurrence.
In summary, ``def_name`` and ``ref_name`` are as in the source
code of the declaration, possibly overloaded, whereas ``def`` and
``ref`` are unique-ified.
Literal elements have this attribute:
* lit_val is the value of the literal as written in the source text,
appropriately escaped (e.g. ``"`` |rightarrow| ``&quot;``). This applies
only to numeric and string literals. Enumeration literals in Ada are
not really "literals" in the usual sense; they are usage occurrences,
and have ref_name and ref as described above. Note also that string
literals used as operator symbols are treated as defining or usage
occurrences, not as literals.
Elements that can syntactically represent names and expressions (which
includes usage occurrences, plus function calls and so forth) have this
attribute:
* type. If the element represents an expression or the name of an object,
'type' is the 'def' for the defining occurrence of the type of that
expression or name. Names of other kinds of entities, such as package
names and type names, do not have a type in Ada; these have type="null"
in the XML.
Pragma elements have this attribute:
* pragma_name is the name of the pragma. For language-defined pragmas, the
pragma name is redundant with the element kind (for example, an
assert_pragma element necessarily has pragma_name="Assert"). However, all
implementation-defined pragmas are lumped together in ASIS as a single
element kind (for example, the GNAT-specific pragma Unreferenced is
represented by an implementation_defined_pragma element with
pragma_name="Unreferenced").
Defining occurrences of formal parameters and generic formal objects have this
attribute:
* mode indicates that the parameter is of mode 'in', 'in out', or 'out'.
All elements other than Not_An_Element have this attribute:
* checks is a comma-separated list of run-time checks that are needed
for that element. The possible checks are: do_accessibility_check,
do_discriminant_check,do_division_check,do_length_check,
do_overflow_check,do_range_check,do_storage_check,do_tag_check.
The "kind" part of the "def" and "ref" attributes is taken from the ASIS
enumeration type Flat_Declaration_Kinds, declared in
Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_`` removed, and
any trailing ``_Declaration`` or ``_Specification`` removed. Thus, the
possible kinds are as follows:
::
ordinary_type
task_type
protected_type
incomplete_type
tagged_incomplete_type
private_type
private_extension
subtype
variable
constant
deferred_constant
single_task
single_protected
integer_number
real_number
enumeration_literal
discriminant
component
loop_parameter
generalized_iterator
element_iterator
procedure
function
parameter
procedure_body
function_body
return_variable
return_constant
null_procedure
expression_function
package
package_body
object_renaming
exception_renaming
package_renaming
procedure_renaming
function_renaming
generic_package_renaming
generic_procedure_renaming
generic_function_renaming
task_body
protected_body
entry
entry_body
entry_index
procedure_body_stub
function_body_stub
package_body_stub
task_body_stub
protected_body_stub
exception
choice_parameter
generic_procedure
generic_function
generic_package
package_instantiation
procedure_instantiation
function_instantiation
formal_object
formal_type
formal_incomplete_type
formal_procedure
formal_function
formal_package
formal_package_declaration_with_box
.. _Generating_Representation_Clauses:
Generating Representation Clauses
---------------------------------
If the :switch:`--rep-clauses` switch is given, ``gnat2xml`` will
generate representation clauses for certain types showing the
representation chosen by the compiler. The information is produced by
the ASIS 'Data Decomposition' facility --- see the
``Asis.Data_Decomposition`` package for details.
Not all types are supported. For example, ``Type_Model_Kind`` must
be ``A_Simple_Static_Model``. Types declared within generic units
have no representation. The clauses that are generated include
``attribute_definition_clauses`` for ``Size`` and
``Component_Size``, as well as
``record_representation_clauses``.
There is no guarantee that the generated representation clauses could
have actually come from legal Ada code; Ada has some restrictions that
are not necessarily obeyed by the generated clauses.
The representation clauses are surrounded by comment elements to
indicate that they are automatically generated, something like this:
::
<comment text="--gen+">
...
<attribute_definition_clause>
...
<comment text="--gen-">
...
.. only:: PRO or GPL
.. _The_Coding_Standard_Verifier_gnatcheck:
The Coding Standard Verifier ``gnatcheck``
==========================================
.. index:: ! gnatcheck
.. index:: ASIS
The ``gnatcheck`` tool is an ASIS-based utility that checks coding standard
compliance of Ada source files according to a given set of semantic rules.
``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
``gnatcheck`` switches is named ``Check``.
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
This documentation is for the new libadalang-based version
of ``gnatmetric``, which replaces the ASIS-based version.
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.
``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 (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.
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:: 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 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.
.. _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 (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.
You can use the following switches to select the specific line metrics
to be computed and 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. The
metric is computed and reported for the whole set of processed Ada
sources only.
: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.
.. _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 computed and reported.
By default, all the syntax metrics are computed and 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
.. _Complexity_Metrics_Control:
Complexity Metrics Control
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. index:: Complexity metrics control in gnatmetric
For a program unit that is an executable body (a subprogram body
(including generic bodies), task body, entry body or a package body
containing its own statement sequence) ``gnatmetric`` computes the
following complexity metrics:
* McCabe cyclomatic complexity;
* McCabe essential complexity;
* maximal loop nesting level;
* extra exit points (for subprograms);
The McCabe cyclomatic complexity metric is defined
in `http://www.mccabe.com/pdf/mccabe-nist235r.pdf <http://www.mccabe.com/pdf/mccabe-nist235r.pdf>`_
According to McCabe, both control statements and short-circuit control
forms should be taken into account when computing cyclomatic
complexity. For Ada 2012 we have also take into account conditional
expressions and quantified expressions. For each body, we compute
three metric values:
* the complexity introduced by control
statements only, without taking into account short-circuit forms
(referred as ``statement complexity`` in ``gnatmetric`` output),
* the complexity introduced by short-circuit control forms only
(referred as ``expression complexity`` in ``gnatmetric`` output),
and
* the total
cyclomatic complexity, which is the sum of these two values
(referred as ``cyclomatic complexity`` in ``gnatmetric`` output).
The cyclomatic complexity is also computed for Ada 2012 expression functions.
An expression function cannot have statements as its components, so only one
metric value is computed as a cyclomatic complexity of an expression function.
The origin of cyclomatic complexity metric is the need to estimate the number
of independent paths in the control flow graph that in turn gives the number
of tests needed to satisfy paths coverage testing completeness criterion.
Considered from the testing point of view, a static Ada ``loop`` (that is,
the ``loop`` statement having static subtype in loop parameter
specification) does not add to cyclomatic complexity. By providing
:switch:`--no-static-loop` option a user
may specify that such loops should not be counted when computing the
cyclomatic complexity metric
The Ada essential complexity metric is a McCabe cyclomatic complexity metric
counted for the code that is reduced by excluding all the pure structural Ada
control statements. An compound statement is considered as a non-structural
if it contains a ``raise`` or ``return`` statement as it subcomponent,
or if it contains a ``goto`` statement that transfers the control outside
the operator. A selective ``accept`` statement with a ``terminate`` alternative
is considered a non-structural statement. When computing this metric,
``exit`` statements are treated in the same way as ``goto``
statements unless the :switch:`-ne` option is specified.
The Ada essential complexity metric defined here is intended to quantify
the extent to which the software is unstructured. It is adapted from
the McCabe essential complexity metric defined in
http://www.mccabe.com/pdf/mccabe-nist235r.pdf
but is modified to be more
suitable for typical Ada usage. For example, short circuit forms
are not penalized as unstructured in the Ada essential complexity metric.
When computing cyclomatic and essential complexity, ``gnatmetric`` skips
the code in the exception handlers and in all the nested program units. The
code of assertions and predicates (that is, subprogram preconditions and
postconditions, subtype predicates and type invariants) is also skipped.
By default, all the complexity metrics are computed and 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 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 computed and 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 disabled. You can use the following
switches to specify the coupling metrics to be computed and reported:
.. 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:: -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:
The GNAT Pretty Printer ``gnatpp``
==================================
.. 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
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
``gnatpp`` switches is named ``Pretty_Printer``.
``gnatpp`` cannot process sources that contain preprocessing
directives.
The ``gnatpp`` command has the form
::
$ gnatpp [ switches ] filename
where
* ``switches`` is an optional sequence of switches defining such properties as
the formatting rules, the source search path, and the destination for the
output source file
* ``filename`` is the name of the source file to reformat; wildcards
or several file names on the same gnatpp command are allowed. The
file name may contain path information; it does not have to follow
the GNAT file naming rules
.. _Switches_for_gnatpp:
Switches for ``gnatpp``
-----------------------
The following subsections describe the various switches accepted by
``gnatpp``, organized by category.
You specify a switch by supplying a name and generally also a value.
In many cases the values for a switch with a given name are incompatible with
each other
(for example the switch that controls the casing of a reserved word may have
exactly one value: upper case, lower case, or
mixed case) and thus exactly one such switch can be in effect for an
invocation of ``gnatpp``.
If more than one is supplied, the last one is used.
However, some values for the same switch are mutually compatible.
You may supply several such switches to ``gnatpp``, but then
each must be specified in full, with both the name and the value.
Abbreviated forms (the name appearing once, followed by each value) are
not permitted.
.. _Alignment_Control:
Alignment Control
^^^^^^^^^^^^^^^^^
.. index:: Alignment control in gnatpp
Programs can be easier to read if certain constructs are vertically aligned.
By default, alignment of the following constructs is set ON:
* ``:`` in declarations,
* ``:=`` in initializations in declarations,
* ``:=`` in assignment statements,
* ``=>`` in associations, and
* ``at`` keywords in the component clauses in record representation clauses.
In addition, ``in`` and ``out`` in parameter specifications are lined up.
.. index:: --no-alignment (gnatpp)
.. index:: --alignment (gnatpp)
.. index:: --no-align-modes (gnatpp)
:switch:`--no-alignment`
Set alignment to OFF
:switch:`--alignment`
Set alignment to ON
:switch:`--no-align-modes`
Do not line up ``in`` and ``out`` in parameter specifications.
.. _Casing_Control:
Casing Control
^^^^^^^^^^^^^^
.. index:: Casing control in gnatpp
``gnatpp`` allows you to specify the casing for reserved words,
pragma names, attribute designators and identifiers.
For identifiers you may define a
general rule for name casing but also override this rule
via a set of dictionary files.
Three types of casing are supported: lower case, upper case, and mixed case.
'Mixed case' means that the first letter, and also each letter immediately
following an underscore, are converted to their uppercase forms;
all the other letters are converted to their lowercase forms.
(Note: the casing switches are not yet fully supported in the
libadalang-based version of gnatpp.)
.. index:: --name-case-as-declared (gnatpp)
:switch:`--name-case-as-declared`
Name casing for defining occurrences are as they appear in the source file
(this is the default)
.. index:: --name-upper-case (gnatpp)
:switch:`--name-upper-case`
Names are in upper case
.. index:: --name-lower-case (gnatpp)
:switch:`--name-lower-case`
Names are in lower case
.. index:: --name-mixed-case (gnatpp)
:switch:`--name-mixed-case`
Names are in mixed case
.. index:: --attribute-lower-case (gnatpp)
:switch:`--attribute-lower-case`
Attribute designators are lower case
.. index:: --attribute-upper-case (gnatpp)
:switch:`--attribute-upper-case`
Attribute designators are upper case
.. index:: --attribute-mixed-case (gnatpp)
:switch:`--attribute-mixed-case`
Attribute designators are mixed case (this is the default)
.. index:: --keyword-lower-case (gnatpp)
:switch:`--keyword-lower-case`
Keywords (technically, these are known in Ada as *reserved words*) are
lower case (this is the default)
.. index:: --keyword-upper-case (gnatpp)
:switch:`--keyword-upper-case`
Keywords are upper case
.. index:: --enum-case-as-declared (gnatpp)
:switch:`--enum-case-as-declared`
Enumeration literal casing for defining occurrences are as they appear in the
source file. Overrides -n casing setting.
.. index:: --enum-upper-case (gnatpp)
:switch:`--enum-upper-case`
Enumeration literals are in upper case. Overrides -n casing
setting.
.. index:: --enum-lower-case (gnatpp)
:switch:`--enum-lower-case`
Enumeration literals are in lower case. Overrides -n casing
setting.
.. index:: --enum-mixed-case (gnatpp)
:switch:`--enum-mixed-case`
Enumeration literals are in mixed case. Overrides -n casing
setting.
.. index:: --type-case-as-declared (gnatpp)
:switch:`--type-case-as-declared`
Names introduced by type and subtype declarations are always
cased as they appear in the declaration in the source file.
Overrides -n casing setting.
.. index:: --type-upper-case (gnatpp)
:switch:`--type-upper-case`
Names introduced by type and subtype declarations are always in
upper case. Overrides -n casing setting.
.. index:: --type-lower-case (gnatpp)
:switch:`--type-lower-case`
Names introduced by type and subtype declarations are always in
lower case. Overrides -n casing setting.
.. index:: --type-mixed-case (gnatpp)
:switch:`--type-mixed-case`
Names introduced by type and subtype declarations are always in
mixed case. Overrides -n casing setting.
.. index:: --number-upper-case (gnatpp)
:switch:`--number-upper-case`
Names introduced by number declarations are always in
upper case. Overrides -n casing setting.
.. index:: --number-lower-case (gnatpp)
:switch:`--number-lower-case`
Names introduced by number declarations are always in
lower case. Overrides -n casing setting.
.. index:: --number-mixed-case (gnatpp)
:switch:`--number-mixed-case`
Names introduced by number declarations are always in
mixed case. Overrides -n casing setting.
.. index:: --pragma-lower-case (gnatpp)
:switch:`--pragma-lower-case`
Pragma names are lower case
.. index:: --pragma-upper-case (gnatpp)
:switch:`--pragma-upper-case`
Pragma names are upper case
.. index:: --pragma-mixed-case (gnatpp)
:switch:`--pragma-mixed-case`
Pragma names are mixed case (this is the default)
.. index:: --syntax-only (gnatpp)
:switch:`--syntax-only`
Disable the semantic analysis (name resolution) done by libadalang.
This means gnatpp will not be able to support any of the
"as-declared" switches.
.. index:: --dictionary (gnatpp)
:switch:`--dictionary={file}`
Use ``file`` as a *dictionary file* that defines
the casing for a set of specified names,
thereby overriding the effect on these names by
any explicit or implicit
-n switch.
To supply more than one dictionary file,
use several ``--dictionary`` switches.
``gnatpp`` implicitly uses a *default dictionary file*
to define the casing for the Ada predefined names and
the names declared in the GNAT libraries.
.. index:: --dictionary=- (gnatpp)
:switch:`--dictionary=-`
Do not use the default dictionary file;
instead, use the casing
defined by a ``-n`` switch and any explicit
dictionary file(s)
The structure of a dictionary file, and details on the conventions
used in the default dictionary file, are defined in :ref:`Name_Casing`.
The :switch:`--dictionary=-` and
:switch:`--dictionary={file}` switches are mutually
compatible.
This group of ``gnatpp`` switches controls the layout of comments and
complex syntactic constructs. See :ref:`Formatting_Comments` for details
on their effect.
.. index:: -c (gnatpp)
:switch:`--comments-unchanged`
All comments remain unchanged.
:switch:`--comments-gnat-indentation`
GNAT-style comment line indentation.
This is the default.
:switch:`--comments-gnat-beginning`
GNAT-style comment beginning.
:switch:`--comments-fill`
Fill comment blocks.
:switch:`--comments-special`
Keep unchanged special form comments.
This is the default.
.. index:: --comments-only (gnatpp)
:switch:`--comments-only`
Format just the comments.
.. index:: --no-end-id (gnatpp)
:switch:`--no-end-id`
Do not insert the name of a unit after ``end``; leave whatever comes
after ``end``, if anything, alone.
.. index:: --no-separate-is (gnatpp)
:switch:`--no-separate-is`
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-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.
.. 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.
.. index:: --use-on-new-line (gnatpp)
:switch:`--use-on-new-line`
Start each USE clause in a context clause from a separate line.
.. index:: --insert-blank-lines (gnatpp)
:switch:`--insert-blank-lines`
Insert blank lines where appropriate (between bodies and other large
constructs).
.. index:: --preserve-blank-lines (gnatpp)
:switch:`--preserve-blank-lines`
Preserve blank lines in the input. By default, gnatpp will squeeze
multiple blank lines down to one.
.. index:: --preserve-line-breaks (gnatpp)
:switch:`--preserve-line-breaks`
Preserve line breaks in the input, to the extent possible.
The ``--comments`` switches are compatible with one another, except
that the ``--comments-unchanged`` switch disables all other comment
formatting switches.
.. _General_Text_Layout_Control:
General Text Layout Control
^^^^^^^^^^^^^^^^^^^^^^^^^^^
These switches allow control over line length and indentation.
.. index:: --max-line-length (gnatpp)
:switch:`--max-line-length={nnn}`
Maximum line length, ``nnn`` from 32...256, the default value is 79
.. index:: --indentation (gnatpp)
:switch:`--indentation={nnn}`
Indentation level, ``nnn`` from 1...9, the default value is 3
.. index:: --indent-continuation (gnatpp)
:switch:`--indent-continuation={nnn}`
Indentation level for continuation lines (relative to the line being
continued), ``nnn`` from 1...9.
The default
value is one less than the (normal) indentation level, unless the
indentation is set to 1 (in which case the default value for continuation
line indentation is also 1)
.. _Other_Formatting_Options:
Other Formatting Options
^^^^^^^^^^^^^^^^^^^^^^^^
These switches control other formatting not listed above.
.. index:: --decimal-grouping (gnatpp)
:switch:`--decimal-grouping={n}`
Put underscores in decimal literals (numeric literals without a base)
every ``n`` characters. If a literal already has one or more
underscores, it is not modified. For example, with
``--decimal-grouping=3``, ``1000000`` will be changed to
``1_000_000``.
.. index:: --based-grouping (gnatpp)
:switch:`--based-grouping={n}`
Same as ``--decimal-grouping``, but for based literals. For
example, with ``--based-grouping=4``, ``16#0001FFFE#`` will be
changed to ``16#0001_FFFE#``.
.. index:: --split-line-before-record (gnatpp)
:switch:`--split-line-before-record`
Split the line just before ``record`` in a record type declaration.
.. index:: --indent-named-statements (gnatpp)
:switch:`--indent-named-statements`
Named block and loop statements are indented with respect to
the name.
.. index:: --split-line-before-op (gnatpp)
:switch:`--split-line-before-op`
If it is necessary to split a line at a binary operator, by default
the line is split after the operator. With this option, it is split
before the operator.
.. index:: --RM-style-spacing (gnatpp)
:switch:`--RM-style-spacing`
Do not insert an extra blank before various occurrences of
'(' 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}`
If the number of parameter associations is greater than ``nnn`` and if at
least one association uses named notation, start each association from
a new line. If ``nnn`` is 0, no check for the number of associations
is made; this is the default.
.. index:: --par_threshold (gnatpp)
:switch:`--par_threshold={nnn}`
If the number of parameter specifications is greater than ``nnn``
(or equal to ``nnn`` in case of a function), start each specification from
a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not specified, then
the ``is`` is placed on a separate line. This feature is disabled by default.
.. index:: --vertical-enum-types (gnatpp)
:switch:`--vertical-enum-types`
Format enumeration type declarations "vertically", e.g. each
enumeration literal goes on a separate line.
.. index:: --vertical-array-types (gnatpp)
:switch:`--vertical-array-types`
Format array type declarations "vertically", e.g. for
multidimensional arrays, each index_subtype_definition or
discrete_subtype_definition goes on a separate line.
.. index:: --vertical-named-aggregates (gnatpp)
:switch:`--vertical-named-aggregates`
Format aggregates "vertically" if named notation is used for all
component_associations, e.g. each component_association
goes on a separate line.
.. index:: --vertical-case-alternatives (gnatpp)
:switch:`--vertical-case-alternatives`
Format case statements, case expressions, and variant parts with
additional line breaks.
.. _Setting_the_Source_Search_Path:
Setting the Source Search Path
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To define the search path for the input source file, ``gnatpp``
uses the same switches as the GNAT compiler, with the same effects:
.. index:: -I (gnatpp)
:switch:`-I{dir}`
.. index:: -I- (gnatpp)
:switch:`-I-`
.. index:: -gnatec (gnatpp)
:switch:`-gnatec={path}`
.. _Output_File_Control-gnatpp:
Output File Control
^^^^^^^^^^^^^^^^^^^
By default the output overwrites the input file.
The output may be redirected by the following switches:
.. index:: --replace (gnatpp)
:switch:`--replace`
This is the default.
Replace the input source file with the reformatted output without
creating any backup copy of the input source.
.. index:: --output-dir (gnatpp)
:switch:`--output-dir={dir}`
Generate output file in directory :file:`dir` with the same name as
the input file. If :file:`dir` is the same as the directory
containing the input file, the input file is not processed; use
``--replace`` if you want to update the input file in
place.
.. index:: --pipe (gnatpp)
:switch:`--pipe`
Send the output to ``Standard_Output``
.. index:: --output (gnatpp)
:switch:`--output={output_file}`
Write the output into ``output_file``.
If ``output_file`` already exists, ``gnatpp`` terminates without
reading or processing the input file.
.. index:: --output-force (gnatpp)
:switch:`--output-force={output_file}`
Write the output into ``output_file``, overwriting the existing file
(if one is present).
.. index:: --replace-backup (gnatpp)
:switch:`--replace-backup`
Replace the input source file with the reformatted output, and copy the
original input source into the file whose name is obtained by appending the
:file:`.npp` suffix to the name of the input file.
If a file with this name already exists, ``gnatpp`` terminates without
reading or processing the input file.
.. index:: --replace-force-backup (gnatpp)
:switch:`--replace-force-backup`
Like ``--replace-backup`` except that if the file with the specified name
already exists, it is overwritten.
.. index:: --eol (gnatpp)
:switch:`--eol={xxx}`
Specifies the line-ending style of the reformatted output file. The
``xxx`` string specified with the switch may be:
* *dos* - MS DOS style, lines end with CR LF characters*
* *crlf* - the same as *dos*
* *unix* - UNIX style, lines end with LF character*
* *lf* - the same as *unix*
.. index:: --wide-character-encoding (gnatpp)
: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)
Options ``--output-file`` and ``--output-force`` are allowed only if
the call to gnatpp contains only one file to reformat.
Option ``--eol`` and ``--wide-character-encoding`` cannot be used together
with the ``--pipe`` option.
.. _Other_gnatpp_Switches:
Other ``gnatpp`` Switches
^^^^^^^^^^^^^^^^^^^^^^^^^
The additional ``gnatpp`` switches are defined in this subsection.
.. index:: --version (gnatpp)
:switch:`--version`
Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatpp)
:switch:`--help`
Display usage, then exit disregarding all other options.
.. index:: -P (gnatpp)
: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.
.. index:: -U (gnatpp)
:switch:`-U`
If a project file is specified and no argument source is explicitly
specified (either directly or by means of ``--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 ``--files`` option), process
the closure of units rooted at ``main_unit``. Otherwise this option
has no effect.
.. index:: -X (gnatpp)
: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 (gnatpp)
:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: --incremental (gnatpp)
:switch:`--incremental`
Incremental processing on a per-file basis. Source files are only
processed if they have been modified, or if files they depend on have
been modified. This is similar to the way gnatmake/gprbuild only
compiles files that need to be recompiled. A project file is required
in this mode, and the gnat driver (as in *gnat pretty*) is not
supported.
(Note: this switch is not yet supported in the libadalang-based
version of gnatpp.)
.. index:: --pp-off (gnatpp)
:switch:`--pp-off={xxx}`
Use :switch:`--xxx` as the command to turn off pretty printing, instead
of the default ``--!pp off``.
.. index:: --pp-on (gnatpp)
:switch:`--pp-on={xxx}`
Use :switch:`--xxx` as the command to turn pretty printing back on, instead
of the default ``--!pp on``.
.. index:: --files (gnatpp)
: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 simultaneously.
.. index:: --ignore (gnatpp)
:switch:`--ignore={filename}`
Do not process the sources listed in a specified file. This option cannot
be used in incremental mode.
.. index:: --jobs (gnatpp)
:switch:`--jobs={n}`
With ``--incremental``, use *n* ``gnatpp`` processes to perform
pretty printing in parallel. If *n* is 0, then the maximum number
processes is the number of core processors on the platform.
.. index:: --verbose (gnatpp)
:switch:`--verbose`
Verbose mode
.. index:: --quiet (gnatpp)
:switch:`--quiet`
Quiet mode
If a project file is specified and no argument source is explicitly
specified (either directly or by means of ``--files`` option), and no
``-U`` is specified, then the set of processed sources is
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
----------------
The following subsections show how ``gnatpp`` treats white space,
comments, program layout, and name casing.
They provide detailed descriptions of the switches shown above.
.. _Disabling_Pretty_Printing:
Disabling Pretty Printing
^^^^^^^^^^^^^^^^^^^^^^^^^
Pretty printing is highly heuristic in nature, and sometimes doesn't
do exactly what you want. If you wish to format a certain region of
code by hand, you can turn off pretty printing in that region by
surrounding it with special comments that start with ``--!pp off``
and ``--!pp on``. The text in that region will then be reproduced
verbatim in the output with no formatting.
To disable pretty printing for the whole file, put ``--!pp off`` at
the top, with no following ``--!pp on``.
The comments must appear on a line by themselves, with nothing
preceding except spaces. The initial text of the comment must be
exactly ``--!pp off`` or ``--!pp on`` (case sensitive), but may
be followed by arbitrary additional text. For example:
.. code-block:: ada
package Interrupts is
--!pp off -- turn off pretty printing so "Interrupt_Kind" lines up
type Interrupt_Kind is
(Asynchronous_Interrupt_Kind,
Synchronous_Interrupt_Kind,
Green_Interrupt_Kind);
--!pp on -- reenable pretty printing
...
You can specify different comment strings using the ``--pp-off``
and ``--pp-on`` switches. For example, if you say:
::
$ gnatpp --pp-off=' pp-' *.ad?
then gnatpp will recognize comments of the form
``-- pp-`` instead of ``--!pp off`` for disabling pretty
printing. Note that the leading ``--`` of the comment is not
included in the argument to these switches.
.. _White_Space_and_Empty_Lines:
White Space and Empty Lines
^^^^^^^^^^^^^^^^^^^^^^^^^^^
``gnatpp`` does not have an option to control space characters.
It will add or remove spaces according to the style illustrated by the
examples in the :title:`Ada Reference Manual`.
The output file will contain no lines with trailing white space.
By default, a sequence of one or more blank lines in the input is
converted to a single blank line in the output; multiple blank lines
are squeezed down to one.
The ``--preserve-blank-lines`` option
turns off the squeezing; each blank line in the input is copied
to the output.
The ``--insert-blank-lines`` option
causes additional blank lines to be inserted if not already
present in the input (e.g. between bodies).
.. _Formatting_Comments:
Formatting Comments
^^^^^^^^^^^^^^^^^^^
Comments in Ada code are of two kinds:
* a *whole-line comment*, which appears by itself (possibly preceded by
white space) on a line
* an *end-of-line comment*, which follows some other Ada code on
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
SPARK-style ``--#...`` are left alone.
For an end-of-line comment, ``gnatpp`` tries to leave the same
number of spaces between the end of the preceding Ada code and the
beginning of the comment as appear in the original source.
The ``--comments-gnat-beginning`` switch (GNAT style comment
beginning) has the following effect:
* For each whole-line comment that does not end with two hyphens,
``gnatpp`` inserts spaces if necessary after the starting two
hyphens to ensure that there are at least two spaces between
these hyphens and the first non-blank character of the comment.
The ``--comments-fill`` switch specifies that whole-line comments
that form a paragraph will be filled in typical word processor style
(that is, moving words between lines to make the lines other than the
last similar in length ).
The ``--comments-only`` switch specifies that only the comments are
formatted; the rest of the program text is left alone. The comments
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
--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
``--comments-gnat-beginning`` or ``--comments-fill``, then gnatpp
doesn't format anything.
.. _Name_Casing:
Name Casing
^^^^^^^^^^^
``gnatpp`` always converts the usage occurrence of a (simple) name to
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,
defining occurrences appear exactly as in the source file where they
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
``gnatpp`` changes the casing of a defining occurrence, it
analogously changes the casing of all the usage occurrences of this
name.
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
as though the switch had affected the casing for the defining
occurrence of the name.
The options
:switch:`--attribute...`,
:switch:`--keyword...`,
:switch:`--enum...`,
:switch:`--type...`,
:switch:`--number...`, and
:switch:`--pragma...`
allow finer-grained control over casing for
attributes, keywords, enumeration literals,
types, named numbers and pragmas, respectively.
:switch:`--type...` cover subtypes as well.
Some names may need to be spelled with casing conventions that are not
covered by the upper-, lower-, and mixed-case transformations.
You can arrange correct casing by placing such names in a
*dictionary file*,
and then supplying a ``--dictionary`` switch.
The casing of names from dictionary files overrides
any ``--name...`` switch.
To handle the casing of Ada predefined names and the names from GNAT libraries,
``gnatpp`` assumes a default dictionary file.
The name of each predefined entity is spelled with the same casing as is used
for the entity in the :title:`Ada Reference Manual` (usually mixed case).
The name of each entity in the GNAT libraries is spelled with the same casing
as is used in the declaration of that entity.
The ``--dictionary=-`` switch suppresses the use of
the default dictionary file. Instead, the casing for predefined and
GNAT-defined names will be established by the
``-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
such names are rendered in uppercase, additionally supply the
--dictionary=- switch (or else place these names
in upper case in a dictionary file).
A dictionary file is a plain text file; each line in this file can be
either a blank line (containing only space characters), an Ada comment
line, or the specification of exactly one *casing schema*.
A casing schema is a string that has the following syntax:
::
casing_schema ::= identifier | simple_identifier
simple_identifier ::= letter{letter_or_digit}
(See :title:`Ada Reference Manual`, Section 2.3) for the definition of the
``identifier`` lexical element and the ``letter_or_digit`` category.)
The casing schema string can be followed by white space and/or an Ada-style
comment; any amount of white space is allowed before the string.
If a dictionary file is passed as
the value of a :switch:`--dictionary={file}` switch
then for every
simple name and every identifier, ``gnatpp`` checks if the dictionary
defines the casing for the name or for some of its parts (the term 'subword'
is used below to denote the part of a name which is delimited by '_' or by
the beginning or end of the word and which does not contain any '_' inside):
* if the whole name is in the dictionary, ``gnatpp`` uses for this name
the casing defined by the dictionary; no subwords are checked for this word
* for every subword ``gnatpp`` checks if the dictionary contains the
corresponding string of the form ``simple_identifier``,
and if it does, the casing of this ``simple_identifier`` is used
for this subword
* if the whole name does not contain any '_' inside, and if for this name
the dictionary contains two entries -- one of the form ``identifier``,
and another of the form ``simple_identifier`` -- then the first one
is applied to define the casing of this name
* if more than one dictionary file is passed as ``gnatpp`` switches, each
dictionary adds new casing exceptions and overrides all the existing casing
exceptions set by the previous dictionaries
* when ``gnatpp`` checks if the word or subword is in the dictionary,
this check is not case sensitive
For example, suppose we have the following source to reformat:
.. code-block:: ada
procedure test is
name1 : integer := 1;
name4_name3_name2 : integer := 2;
name2_name3_name4 : Boolean;
name1_var : Float;
begin
name2_name3_name4 := name4_name3_name2 > name1;
end;
And suppose we have two dictionaries:
::
*dict1:*
NAME1
*NaMe3*
*Name1*
*dict2:*
*NAME3*
If ``gnatpp`` is called with the following switches:
::
$ gnatpp --name-mixed-case --dictionary=dict1 --dictionary=dict2 test.adb
then we will get the following name casing in the ``gnatpp`` output:
.. code-block:: ada
procedure Test is
NAME1 : Integer := 1;
Name4_NAME3_Name2 : Integer := 2;
Name2_NAME3_Name4 : Boolean;
Name1_Var : Float;
begin
Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
end Test;
Legacy Switches
^^^^^^^^^^^^^^^
Some switches have a short form, mostly for legacy reasons,
as shown below.
.. index:: -n (gnatpp)
:switch:`-nD`
:switch:`--name-case-as-declared`
:switch:`-nU`
:switch:`--name-upper-case`
:switch:`-nL`
:switch:`--name-lower-case`
:switch:`-nM`
:switch:`--name-mixed-case`
.. index:: -a (gnatpp)
:switch:`-aL`
:switch:`--attribute-lower-case`
:switch:`-aU`
:switch:`--attribute-upper-case`
:switch:`-aM`
:switch:`--attribute-mixed-case`
.. index:: -k (gnatpp)
:switch:`-kL`
:switch:`--keyword-lower-case`
:switch:`-kU`
:switch:`--keyword-upper-case`
.. index:: -ne (gnatpp)
:switch:`-neD`
:switch:`--enum-case-as-declared`
:switch:`-neU`
:switch:`--enum-upper-case`
:switch:`-neL`
:switch:`--enum-lower-case`
:switch:`-neM`
:switch:`--enum-mixed-case`
.. index:: -nt (gnatpp)
:switch:`-ntD`
:switch:`--type-case-as-declared`
:switch:`-ntU`
:switch:`--type-upper-case`
:switch:`-ntL`
:switch:`--type-lower-case`
:switch:`-ntM`
:switch:`--type-mixed-case`
:switch:`-nnU`
:switch:`--number-upper-case`
:switch:`-nnL`
:switch:`--number-lower-case`
:switch:`-nnM`
:switch:`--number-mixed-case`
.. index:: -p (gnatpp)
:switch:`-pL`
:switch:`--pragma-lower-case`
:switch:`-pU`
:switch:`--pragma-upper-case`
:switch:`-pM`
:switch:`--pragma-mixed-case`
.. index:: -D (gnatpp)
:switch:`-D{file}`
:switch:`--dictionary={file}`
.. index:: -D- (gnatpp)
:switch:`-D-`
:switch:`--dictionary=-`
.. index:: -c (gnatpp)
:switch:`-c0`
:switch:`--comments-unchanged`
:switch:`-c1`
:switch:`--comments-gnat-indentation`
:switch:`-c3`
:switch:`--comments-gnat-beginning`
:switch:`-c4`
:switch:`--comments-fill`
:switch:`-c5`
:switch:`--comments-special`
.. index:: -M (gnatpp)
:switch:`-M{nnn}`
:switch:`--max-line-length={nnn}`
.. index:: -i (gnatpp)
:switch:`-i{nnn}`
:switch:`--indentation={nnn}`
.. index:: -cl (gnatpp)
:switch:`-cl{nnn}`
:switch:`--indent-continuation={nnn}`
.. index:: -ff (gnatpp)
:switch:`-ff`
:switch:`--ff-after-pragma-page`
.. index:: -pipe (gnatpp)
:switch:`-pipe`
:switch:`--pipe`
.. index:: -o (gnatpp)
:switch:`-o {output-file}`
:switch:`--output={output-file}`
.. index:: -of (gnatpp)
:switch:`-of {output-file}`
:switch:`--output-force={output-file}`
.. index:: -r (gnatpp)
:switch:`-rnb`
:switch:`--replace`
:switch:`-r`
:switch:`--replace-backup`
.. index:: -rf (gnatpp)
:switch:`-rf`
:switch:`--replace-force-backup`
.. index:: -rnb (gnatpp)
.. index:: --eol (gnatpp)
.. index:: -W (gnatpp)
:switch:`-W{e}`
:switch:`--wide-character-encoding={e}`
.. index:: -files (gnatpp)
:switch:`-files {filename}`
:switch:`--files={filename}`
.. index:: -j (gnatpp)
:switch:`-j{n}`
:switch:`--jobs={n}`
.. index:: -v (gnatpp)
:switch:`-v`
:switch:`--verbose`
.. index:: -q (gnatpp)
:switch:`-q`
:switch:`--quiet`
.. only:: PRO or GPL
.. _The_Body_Stub_Generator_gnatstub:
The Body Stub Generator *gnatstub*
==================================
.. index:: ! gnatstub
``gnatstub`` creates empty but compilable bodies
for library unit declarations, and empty but compilable
subunits for body stubs.
``gnatstub`` is a project-aware tool.
(See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches but note that ``gnatstub`` does not support
the :switch:`-U`, :switch:`-U {main_unit}`, :switch:`--subdirs={dir}`, or
:switch:`--no_objects_dir` switches.)
The project file package that can specify
``gnatstub`` switches is named ``gnatstub``.
By default, all the program unit bodies generated by ``gnatstub``
raise ``Program_Error``, which will catch accidental calls of
generated stubs. This behavior can be changed with option
``--no-exception`` (see below).
.. _Running_gnatstub:
Running ``gnatstub``
--------------------
``gnatstub`` invocation has the following form:
::
$ gnatstub [ switches ] {filename}
where
* *filename*
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 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:`--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``
takes the naming conventions for the generated source from the
project file provided as a parameter of ``-P`` switch if any,
or creates the name file to generate using the standard GNAT
naming conventions.
* *switches*
is an optional sequence of switches as described in the next section
.. _Switches_for_gnatstub:
Switches for ``gnatstub``
-------------------------
.. index:: --version (gnatstub)
:switch:`--version`
Display copyright and version, then exit disregarding all other options.
.. index:: --help (gnatstub)
:switch:`--help`
Display usage, then exit disregarding all other options.
.. index:: -P (gnatstub)
:switch:`-P {file}`
Indicates the name of the project file that describes the set of sources
to be processed. An aggregate project is allowed as the file parameter only
if it has exactly one non-aggregate project being aggregated.
.. index:: -X (gnatstub)
: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 (gnatstub)
:switch:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
equivalent ``gnatmake`` flag (:ref:`Switches_for_gnatmake`).
.. index:: --subunits (gnatstub)
:switch:`--subunits`
Generate subunits for body stubs. If this switch is specified,
``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:: --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:: --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:: --comment-header-sample (gnatstub)
:switch:`--comment-header-sample`
Put a sample comment header into the body stub.
.. index:: --header-file (gnatstub)
:switch:`--header-file={filename}`
Use the content of the file as the comment header for a generated body stub.
.. 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:: --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:: --no-exception (gnatstub)
:switch:`--no-exception`
Avoid raising Program_Error in the generated bodies of program unit stubs,
except in the case of functions, where we have no value to return.
.. index:: --no-local-header (gnatstub)
:switch:`--no-local-header`
Do not place local comment header with unit name before body stub for a
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:: --gnat83 (gnatstub)
:switch:`--gnat83`
Ada 83 mode
.. index:: --gnat95 (gnatstub)
:switch:`--gnat95`
Ada 95 mode
.. index:: --gnat2005 (gnatstub)
:switch:`--gnat2005`
Ada 2005 mode
.. index:: --gnat2012 (gnatstub)
:switch:`--gnat2012`
Ada 2012 mode
.. 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 {output-file}`
:switch:`--output={output-file}`
.. index:: -dir (gnatstub)
:switch:`-dir {dir-name}`
:switch:`--output-dir={dir-name}`
.. index:: -W (gnatstub)
:switch:`-W{e}`
:switch:`--wide-character-encoding={e}`
.. index:: -files (gnatstub)
:switch:`-files {filename}`
:switch:`--files={filename}`
.. only:: PRO or GPL
.. _The_Unit_Test_Generator_gnattest:
The Unit Test Generator ``gnattest``
====================================
.. index:: ! gnattest
``gnattest`` is an ASIS-based utility that creates unit-test skeletons
as well as a test driver infrastructure (harness). ``gnattest`` creates
a skeleton for each visible subprogram in the packages under consideration when
they do not exist already.
``gnattest`` is a project-aware tool.
(See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches but note that ``gnattest`` does not support
the :switch:`-U`, :switch:`-eL`, :switch:`--subdirs={dir}`, or
:switch:`--no_objects_dir` switches.)
The project file package that can specify
``gnattest`` switches is named ``gnattest``.
The user can choose to generate a single test driver
that will run all individual tests, or separate test drivers for each test. The