5. GNAT Utility Programs
This chapter describes a number of utility programs:
It also describes how you can use several of these tools in conjunction with project files: Using Project Files with GNAT Tools
Other GNAT utilities are described elsewhere in this manual:
5.1. The File Cleanup Utility gnatclean
gnatclean
is a tool that deletes some 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.
5.1.1. Running gnatclean
You run the gnatclean
command as follow:
$ gnatclean switches names
where names
is a list of source file names. You may omit suffixes .ads
and
adb
. If a project file is specified using switch
-P
, then you may completely omit names
.
In normal mode, gnatclean
deletes the files produced by the compiler and,
if switch -c
is not specified, produced by the binder and
linker. In information-only mode, specified by switch
-n
, gnatclean
lists the files that would have been deleted in
normal mode, but doesn’t actually delete any files.
5.1.2. Switches for gnatclean
gnatclean
recognizes the following switches:
--version
Display copyright and version, then exit, disregarding all other options.
--help
If
--version
was not specified, display usage, then exit disregarding all other options.--subdirs=subdir
Actual object directory of each project file, which is the subdirectory
subdir
of the object directory specified or defaulted in the project file.--unchecked-shared-lib-imports
By default, shared library projects are not allowed to import static library projects. When this switch is specified, this restriction is lifted.
-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.
-D dir
Indicate that ALI and object files should normally be found in directory
dir
.
-F
When using project files, if some errors or warnings are detected during parsing and verbose mode is not in effect (the switch
-v
is not specified), error lines start with the full path name of the project file, rather than its simple file name.
-h
Output a message explaining the usage of
gnatclean
.
-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.
-Pproject
Use project file
project
. You can specify only one such switch. When cleaning a project file,gnatclean
deletes the files produced by the compilation of the immediate sources or inherited sources of the project files. This does not depend on whether or not you include executable names on the command line.
-q
Quiet output. If there are no errors, do not output anything, except in verbose mode (
-v
) or in information-only mode (-n
).
-r
When a project file is specified (using
-P
), clean all imported and extended project files, recursively. If you don’t specify this switch,gnatclean
only deletes the files related to the main project file. This switch has no effect if you don’t specify a project file.
-v
Verbose mode.
-vPx
Indicates the verbosity of the parsing of GNAT project files. Switches Related to Project Files.
-Xname=value
Indicates that external variable
name
has the valuevalue
. The Project Manager will use this value for occurrences ofexternal(name)
when parsing the project file. See Switches Related to Project Files.
-aOdir
When searching for ALI and object files, look in directory
dir
.
-Idir
Equivalent to
-aOdir
.
-I-
Do not look for ALI or object files in the directory where
gnatclean
was invoked.
5.2. The GNAT Library Browser gnatls
gnatls
is a tool that outputs information about compiled
units. It gives the relationship between objects, unit names and source
files. You can also use it to check the source dependencies of a unit
as well as various characteristics.
5.2.1. Running gnatls
You run the gnatls
command as follows:
$ gnatls switches object_or_ali_file
The main argument is the list of object or ali
files
(see The Ada Library Information Files)
for which you are requesting information.
In the default mode, without additional options, gnatls
produces a
four-column listing. Each line contains 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 the 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’s a simple example:
$ 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
You should interpret the first line as follows: the main unit, which is
contained in
object file demo1.o
, is demo1, whose main source is in
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 (e.g., only comments have been changed). If you run
gnatmake
with the option-m
(minimal recompilation), it will not recompile a file marked MOK.- 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.
5.2.2. Switches for gnatls
You can specify the following switches to gnatls
:
--version
Display copyright and version, then exit, disregarding all other options.
--help
If
--version
was not specified, display usage, then exit, disregarding all other options.
-a
Consider all units, including those of the predefined Ada library. Especially useful with
-d
.
-d
List sources that specified units depend on.
-h
Output the list of options.
-o
Only output information about object files.
-s
Only output information about source files.
-u
Only output information about compilation units.
-files=file
Take as arguments the files listed in text file
file
, which may contain empty lines that are ignored. Each nonempty line should contain the name of an existing file. Several such switches may be specified on the same command.
-aOdir
,-aIdir
,-Idir
,-I-
,-nostdinc
Source path manipulation. It has the same meaning as the equivalent
gnatmake
switches (Switches for gnatmake).
-aPdir
Add
dir
at the beginning of the project search dir.
--RTS=rts-path
Specifies the default location of the runtime library. It has the same meaning as the equivalent
gnatmake
switch (Switches for gnatmake).
-v
Verbose mode. Output the complete source, object and project paths. Don’t 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.
5.2.3. Example of gnatls
Usage
Here’s an 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
Here’s an example of use of the dependency list.
Note the use of the -s
switch,
which gives a simple list of source files. You may find this 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
5.3. The GNAT Pretty Printer gnatpp
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 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 filefilename
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
Note that you no longer need to specify the Ada language version;
gnatpp
can process Ada source code written in any version from Ada 83
onward without specifying any language version switch.
5.3.1. 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 usually 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
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.
5.3.1.1. Layout Control
gnatpp
provides a layout switch which controls the general
formatting style:
--layout=default|minimal|compact|tall
default
The default layout is a compact style, but
gnatpp
adds alignment and puts some keywords on a separate line.gnatpp
adds alignment in the the following constructs::
in declarations,:=
in initializations in declarations,:=
in assignment statements,=>
in associations, andat
keywords in the component clauses in record representation clauses.
In addition,
gnatpp
also lines upin
andout
keywords in parameter specifications.gnatpp
places the keywordis
on a separate line in a subprogram body in case the spec occupies more than one line.gnatpp
places the keywordreturn
on a separate line if a subprogram spec does not fit on one line.minimal
The minimal layout will avoid changing the source layout by keeping all line breaks from the original source (it will not insert or delete any). It will add indentation where appropriate as long as it does not exceed the line length limit.
compact
The compact layout avoids adding line breaks and alignment by packing as many subexpressions on the same line as possible.
Whole-line comments that form a paragraph are filled in typical word processor style (that is, moving words between lines to make them similar in length, except the last one which may be shorter).
For each whole-line comment that does not end with two hyphens, inserts spaces if necessary after the starting two hyphens to ensure that there are at least two spaces preceding the first non-blank character of the comment.
tall
The tall layout favors adding lines breaks and alignment. It adds all the alignment and line breaks defined in the
default
option, and in addition:Places the keyword
loop
in FOR and WHILE loop statements on a separate linePlaces the keyword
then
in IF statements on a separate linePlaces each keyword
use
in USE clauses on a separate lineSplits the line just before the keyword
record
in a RECORD type declarationIndents named blocks and loop statments with respect to the name
When necessary, splits binary operators always before the operator
Inserts an extra blank before various occurrences of
(
and:
When it is necessary to split a line between two subexpressions (because otherwise the construct would exceed –max-line-length), then all such subexpressions are placed on separate lines
Formats enumeration type declarations “vertically”, e.g. each enumeration literal goes on a separate line
Formats array type declarations “vertically”, e.g. for multidimensional arrays, each index_subtype_definition or discrete_subtype_definition goes on a separate line
Format aggregates “vertically” if named notation is used for all component_associations, e.g. each component_association goes on a separate line
Formats case statements, case expressions, and variant parts with additional line breaks
Inserts blank lines where appropriate (between bodies and other large constructs)
Similarly to the
compact
layout, two spaces are added in the beginning of a whole-line comment when needed
5.3.1.2. Casing Control
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 each letter immediately following an underscore are converted to their uppercase forms and all other letters are converted to their lowercase forms.
--name-case-as-declared, -nD
Name casing for defining occurrences are as they appear in the source file (this is the default).
--name-upper-case, -nU
Names are in upper case.
--name-lower-case, -nL
Names are in lower case.
--name-mixed-case, -nM
Names are in mixed case.
--attribute-lower-case, -aL
Attribute designators are lower case.
--attribute-upper-case, -aU
Attribute designators are upper case.
--attribute-mixed-case, -aM
Attribute designators are mixed case (this is the default).
--keyword-lower-case, -kL
Keywords (technically, these are known in Ada as reserved words) are lower case (this is the default).
--keyword-upper-case, -kU
Keywords are upper case.
--enum-case-as-declared, -neD
Enumeration literal casing for defining occurrences are as they appear in the source file. Overrides the
-n
casing setting.
--enum-upper-case, -neU
Enumeration literals are in upper case. Overrides the
-n
casing setting.
--enum-lower-case, -neL
Enumeration literals are in lower case. Overrides the
-n
casing setting.
--enum-mixed-case, -neM
Enumeration literals are in mixed case. Overrides the
-n
casing setting.
--type-case-as-declared, -ntD
Names introduced by type and subtype declarations are always cased as they appear in the declaration in the source file. Overrides the
-n
casing setting.
--type-upper-case, -ntU
Names introduced by type and subtype declarations are always in upper case. Overrides the
-n
casing setting.
--type-lower-case, -ntL
Names introduced by type and subtype declarations are always in lower case. Overrides the
-n
casing setting.
--type-mixed-case, -ntM
Names introduced by type and subtype declarations are always in mixed case. Overrides the
-n
casing setting.
--number-upper-case, -nnU
Names introduced by number declarations are always in upper case. Overrides the
-n
casing setting.
--number-lower-case, -nnL
Names introduced by number declarations are always in lower case. Overrides the
-n
casing setting.
--number-mixed-case, -nnM
Names introduced by number declarations are always in mixed case. Overrides -n casing setting.
--pragma-lower-case, -pL
Pragma names are lower case.
--pragma-upper-case, -pU
Pragma names are upper case.
--pragma-mixed-case, -pM
Pragma names are mixed case (this is the default).
--constant-case-as-non-constant, -cN
Constant object declaration names have the same case as the name casing (this is the default).
--constant-case-as-declared, -cD
Constant object declaration names are as they appear in the source file.
--constant-lower-case, -cL
Constant object declaration names are lower case.
--constan-upper-case, -cU
Constant object declaration names are upper case.
--constant-mixed-case, -cM
Constant object declaration names are mixed case.
--syntax-only
Disable the semantic analysis (name resolution) done by libadalang. This means
gnatpp
is not able to support any of the “as-declared” switches.
--dictionary=file, -D=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.
--dictionary=-, -D=-
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 Name Casing.
The --dictionary=-
and
--dictionary=file
switches are mutually
compatible.
This group of gnatpp
switches controls the layout of comments and
complex syntactic constructs. See Formatting Comments for details
on their effect.
5.3.1.3. General Text Layout Control
These switches allow control over line length and indentation.
--max-line-length=nnn, -M=nnn
Maximum line length,
nnn
from 32…256. The default value is 79
--indentation=nnn, -i=nnn
Indentation level,
nnn
from 1…9. The default value is 3
--indent-continuation=nnn, -cl=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)
5.3.1.4. Other Formatting Options
These switches control other formatting not listed above.
--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,gnatpp
will not modify it. For example, with--decimal-grouping=3
,1000000
is changed to1_000_000
.
--based-grouping=n
Same as
--decimal-grouping
, but for based literals. For example, with--based-grouping=4
,16#0001FFFE#
is changed to16#0001_FFFE#
.
--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. Ifnnn
is 0,gnatpp
does not check for the number of associations; this is the default.
--par-threshold=nnn
If the number of parameter specifications is greater than
nnn
(or equal tonnn
in case of a function), start each specification from a new line. Ifnnn
is 0, and--no-separate-is
was not specified, then theis
is placed on a separate line. This option is disabled by default.
5.3.1.5. Setting the Source Search Path
To define the search path for the input source file, pass gnatpp
the same switches as the GNAT compiler, with the same effects:
-Idir
-I-
-gnatec=path
5.3.1.6. Output File Control
By default, the output overwrites the input file. You can specify the location of the output with the following switches:
--replace, -rnb
This is the default. Replace the input source file with the reformatted output without creating any backup copy of the input source.
--output-dir=dir
Generate the output file in directory
dir
with the same name as the input file. Ifdir
is the same as the directory containing the input file,gnatpp
does not read or process the input file; use--replace
if you want to update the input file in place.
--pipe, -pipe
Send the output to
Standard_Output
--output=output_file, -o=output_file
Write the output into
output_file
. Ifoutput_file
already exists,gnatpp
terminates without reading or processing the input file.
--output-force=output_file, -of=output_file
Write the output into
output_file
, overwriting the existing file (if one is present).
--replace-backup, -r
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
.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.
--replace-force-backup, -rf
Like
--replace-backup
except that if the file with the specified name already exists, it is overwritten.
--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
The default is to use the same end-of-line convention as the input.
--wide-character-encoding=e, -W=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)
You may only specify options --output-file
and
--output-force
if the call to gnatpp
contains only
one file to reformat.
You may not use the option --eol
or
--wide-character-encoding
together with the
--pipe
option.
5.3.1.7. Other gnatpp
Switches
You can also use the additional gnatpp
switches defined in
this subsection.
--version
Display copyright and version, then exit, disregarding all other options.
--help
Display usage, then exit, disregarding all other options.
-P file
Specifies 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.
-U
If you specify a project file but don’t specify a source file, either directly or by means of a
--files
option,gnatpp
processes all the units of the closure of the specifed project. Otherwise this option has no effect.-U main_unit
If you specify a project file but don’t specify a source file, either directly or by means of
--files
option,gnatpp
will process the closure of units rooted atmain_unit
. Otherwise this option has no effect.
-Xname=value
Indicates that external variable
name
in the specified project has the valuevalue
. Has no effect if you don’t specify a project.
--RTS=rts-path
Specifies the default location of the runtime library. It has the same meaning as the equivalent
gnatmake
switch (Switches for gnatmake).
--incremental
gnatpp
will perform incremental processing on a per-file basis. It will only process a source file if it has been modified, or if files it depends on have been modified. This is similar to the waygnatmake
/gprbuild
only compiles files that need to be recompiled. You must specify a project file 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 ofgnatpp
.)
--pp-off=xxx
Use
--xxx
as the command to turn off pretty printing, instead of the default--!pp off
.
--pp-on=xxx
Use
--xxx
as the command to turn pretty printing back on, instead of the default--!pp on
.
--files=filename, -files=filename
Take as arguments the files listed in text file
file
, which may contain empty lines that are ignored. Each nonempty line should contain the name of an existing file. You may specify several such switches on the same command line.
--ignore=filename
gnatpp
will not process the sources listed in the specified file. You can’t specify this option in incremental mode.
--jobs=n, -j=n
With
--incremental
, use ngnatpp
processes to perform pretty printing in parallel. If n is 0, the maximum number processes is the number of core processors on the host.
--verbose, -v
Verbose mode
--quiet, -q
Quiet mode
If you specify a project file, but no source files
(either directly or by means of a --files
option), and you
specify the -U
, then the set of processed sources is
all the immediate units of the argument project.
5.3.2. Formatting Rules
The following subsections show how gnatpp
treats comments,
program layout, and name casing as well as how to disable gnatpp
in
source code regions. They provide more details of the switches
shown above.
5.3.2.1. Disabling Pretty Printing
Pretty printing is highly heuristic in nature and sometimes doesn’t
do exactly what you want. If you want 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 is reproduced
verbatim in the output with no formatting.
To disable pretty printing for an entire file, put --!pp off
at
the top, with no following --!pp on
.
You must place each of these comments on a line by themselves, with nothing
preceding except spaces. You must have the initial text of the comment be
exactly --!pp off
or --!pp on
(case sensitive), but you may
follow it by arbitrary additional text. For example:
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?
gnatpp
will recognize comments of the form -- pp-
instead
of --!pp off
for disabling pretty printing. Note that you do
not include the leading --
of the comment in the argument to
these switches.
5.3.2.2. Formatting Comments
Only --layout=compact
and --layout=tall
format comments.
Comments in Ada code are of two kinds:
whole-line comments, which appear by themselves (possibly preceded by white space) on a line
end-of-line comments, which follows some other Ada code on the same line.
gnatpp
indents whole-line comment 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. 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 it appears in the original source.
For each whole-line comment that does not end with two hyphens or that are
not special-form comments, 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.
With --layout=compact
, gnatpp
fills in whole-line
comments that form a paragraph in typical word processor style
(that is, moving words between lines to make the lines other than
the last similar in length).
5.3.2.3. 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
, and
--name-mixed-case
– result in upper, lower, or mixed case, respectively. If
gnatpp
changes the casing of a defining occurrence, it
similarly 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
,
gnatpp
changes the casing of each reference to this name
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
--attribute...
,
--keyword...
,
--enum...
,
--type...
,
--number...
, and
--pragma...
allow finer-grained control over casing for
attributes, keywords, enumeration literals,
types, named numbers and pragmas, respectively.
--type...
cover subtypes as well.
You may need some names to be spelled with casing conventions that
are not covered by the upper-, lower-, and mixed-case
transformations. You can have gnatpp
produce the correct
casing by placing such names in a dictionary file, and
specifying a --dictionary
switch. Specifying any
dictionary files overrides any --name...
switch.
gnatpp
uses a default dictionary file to choose the casing of
Ada predefined names and the names from GNAT libraries,
Each predefined entity is converted to the same casing as the entity in the Ada Reference Manual (usually mixed case) and each entity in the GNAT libraries is cased the same as its declaration in the library.
You can specify the --dictionary=-
switch to suppress
the use of the default dictionary file. Instead, the casing for
predefined and GNAT-defined names is given by the -n
switch or explicit dictionary files. For example, by default the
names Ada.Text_IO
and GNAT.OS_Lib
appear as just shown,
even in the presence of a --name-upper-case
switch. To
ensure that even such names are rendered in uppercase, you must
specify the --dictionary=-
switch or place these names
in upper case in a dictionary file.
A dictionary file is a plain text file; each line in this file is 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 with the following syntax:
casing_schema ::= identifier | simple_identifier simple_identifier ::= letter{letter_or_digit}
(See Ada Reference Manual, Section 2.3) for the definition of the
identifier
lexical element and the letter_or_digit
category.)
You can follow a casing schema string by white space and/or an Ada-style comment. You can also have any amount of white space before the string.
If you pass a dictionary file as the value of a
--dictionary=file
switch, gnatpp
checks every
simple name and identifier to see 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 that is
delimited by ‘_’ or by the beginning or end of the word that
doesn’t contain any ‘_’ characters):
if the complete name is in the dictionary,
gnatpp
uses the casing defined by the dictionary for this name; it does not check any subwordsfor every subword,
gnatpp
checks if the dictionary contains the corresponding string of the formsimple_identifier
, and if it does, the casing of thissimple_identifier
is used for this subwordif the complete name does not contain any ‘_’ characters and if for this name the dictionary contains two entries – one of the form
identifier
, and another of the formsimple_identifier
–gnatpp
uses the first one to obtain the casing of this nameif you pass more than one dictionary file as
gnatpp
switches, each dictionary adds new casing exceptions and overrides all the existing casing exceptions set by the previous dictionarieswhen
gnatpp
checks if the word or subword is in the dictionary, it uses a check that’s not case sensitive
For example, suppose we have the following source to reformat:
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 get the following name casing in the gnatpp
output:
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;
5.3.2.4. Preprocessor Directives
gnatpp
has some support for preprocessor directives.
You can use preprocessor symbols such as $symbol
.
In addition, you can use conditional compilation as
long as the program text is syntactically legal Ada code
after removing all the preprocessor directives (lines starting
with #
). For example, gnatpp
can format the following:
package P is #IF SOMETHING X : constant Integer := 123; #ELSE X : constant Integer := 456; #END IF; end P;
which will be formatted as if it were:
package P is X : constant Integer := 123; X : constant Integer := 456; end P;
except that the #
lines will be preserved.
However, gnatpp
cannot format the following:
procedure P is begin #IF SOMETHING if X = 0 then #ELSE if X = 1 then #END IF; null; end if; end P;
because removing the #
lines gives:
procedure P is begin if X = 0 then if X = 1 then null; end if; end P;
which is not syntactically legal.
5.3.2.5. Legacy Switches
--alignment, --no-alignment
Programs can be easier to read if certain constructs are vertically aligned.
:
in declarations,:=
in initializations in declarations,:=
in assignment statements,=>
in associations, andat
keywords in the component clauses in record representation clauses.
--align-modes, --no-align-modes
Line up
in
andout
in parameter specifications.
--compact, --no-compact
In calls and similar constructs,
--compact
packs as many subexpressions into the same line as is possible. Example:Some_Procedure (Short_One, Another_Short_One, A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
On the other hand, if you specify
--no-compact
,gnatpp
places all such subexpressions on separate lines if it’s necessary to split a line between two subexpressions to avoid the construct exceeding--max-line-length
. For example:Some_Procedure (Short_One, Another_Short_One, A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
--end-id, --no-end-id
Insert the name of a unit after
end
. Otherwise, leave whatever comes afterend
, if anything, alone.
--separate-is, --no-separate-is
Place the keyword
is
on a separate line in a subprogram body in case if the spec occupies more than one line.
--separate-return, --no-separate-return
If a subprogram spec does not fit on one line, place the
return
on a separate line. Otherwise try to place it in the same line as the last parameter specification.
--separate-loop, --no-separate-loop
Place the keyword
loop
in FOR and WHILE loop statements on a separate line.
--separate-then, --no-separate-then
Place the keyword
then
in IF statements on a separate line.
--separate-loop-then, --no-separate-loop-then
Equivalent to
--separate-loop
--separate-then
.
--split-line-before-record, --no-split-line-before-record
Split the line just before
record
in a record type declaration.
--indent-named-statements, --no-indent-named-statements
Indent block and loop statements with respect to the name.
--split-line-before-op, --no-split-line-before-op
If itis necessary to split a line at a binary operator, by default the line is split after the operator. When you specify this switch, it is split before the operator.
--use-on-new-line, --no-use-one-new-line
Start each USE clause in a context clause from a separate line.
--vertical-enum-types, --no-vertical-enum-types
Format enumeration type declarations “vertically”, e.g. each enumeration literal goes on a separate line.
--vertical-array-types, --no-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.
--vertical-named-aggregates, --no-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.
--vertical-case-alternatives, --no-vertical-case-alternatives
Format case statements, case expressions, and variant parts with additional line breaks.
--RM-style-spacing
Do not insert an extra blank before various occurrences of ‘(’ and ‘:’. Alignment is off by default in this mode; use
--alignment
to turn it on.
--insert-blank-lines, --no-insert-blank-lines
Insert blank lines where appropriate (between bodies and other large constructs).
--preserve-blank-lines, --no-preserve-blank-lines
Preserve blank lines in the input. By default, gnatpp will squeeze multiple blank lines down to one.
--preserve-line-breaks, --no-preserve-line-breaks
Preserve line breaks in the input, to the extent possible. By default, line breaks are also inserted at appropriate places.
--source-line-breaks, --no-source-line-breaks
Keep the line breaks from the source; do not insert or delete any line breaks.
--spaces-only, --no-spaces-only
Disable all formatting except for inserting and removing spaces. This implies –source-line-breaks.
--comments-unchanged, -c0
All comments remain unchanged.
--comments-gnat-indentation, -c1
GNAT-style comment line indentation.
--comments-gnat-beginning, -c3
GNAT-style comment beginning.
--comments-fill, -c4
Fill comment blocks.
--comments-special, -c5
Keep unchanged special form comments.
--comments-only
Format just the comments.
5.4. The Body Stub Generator 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 Using Project Files with GNAT Tools for a description of
the project-related switches but note that gnatstub
does not support
the -U
, -U main_unit
, --subdirs=dir
, or
--no-objects-dir
switches.)
The project file package that can specify
gnatstub
switches is named gnatstub
.
By default, all program unit bodies generated by gnatstub
raise Program_Error
, which will catch accidental calls of
generated stubs. You can change this behavior with switch
--no-exception
(see below).
5.4.1. Running gnatstub
You invoke gnatstub
like this:
$ gnatstub [ switches ] {filename}
where
- filename is the name of the source file that contains a library
unit declaration for which you want a body to be created or a library unit body for which you want subunits to 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, you must explicitly provide the name of the body file as the value of the
--output=body-name
switch. If the file name follows the GNAT file naming conventions and you do not provide the name of the body filegnatstub
uses the naming conventions for the generated source from the project file provided as a parameter of a-P
switch if any, or creates the name file using the standard GNAT naming conventions.Note that you no longer need to specify the Ada language version;
gnatstub
can process Ada source code written in any version from Ada 83 onward without specifying any language version switch.
- switches
is an optional sequence of switches as described in the next section
5.4.2. Switches for gnatstub
--version
Display copyright and version, then exit, disregarding all other options.
--help
Display usage, then exit, disregarding all other options.
-P file
Indicates the name of the project file that describes the set of sources to be processed. You can specify an aggregate project as the file parameter only if it has exactly one non-aggregate project being aggregated.
-Xname=value
Indicates that external variable
name
in the argument project has the valuevalue
. Has no effect if no project is specified.
--RTS=rts-path
Specifies the default location of the runtime library. It has the same meaning as the equivalent
gnatmake
flag (Switches for gnatmake).
--subunits
Generate subunits for body stubs. If you specify this switch,
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.
--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
.
--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.
--comment-header-sample
Put a sample comment header into the body stub.
--header-file=filename
Use the content of the file as the comment header for a generated body stub.
--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 you can specify is 32767.
--indentation=n
(
n
is an integer from 1 to 9). Set the indentation level in the generated files ton
. The default indentation is 3.
--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.
--no-exception
Avoid raising Program_Error in the generated bodies of program unit stubs, except in the case of functions, where there will be value to return.
--no-local-header
Do not place a local comment header with unit name before body stub for a unit.
--files=filename
Take as arguments the files listed in text file
file
, which may contain empty lines that are ignored. You should specify the name of an existing file in each non-empty line. You may specify multiple--files=
switches.
--output=body-name
Body file name. You should set thisif 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 you omit both this switch and
-P
,gnatpp
will choose the name for the body according to the default GNAT file naming conventions.
--output-dir=dir-name
The directory in which to placethe output files. If you do not specify this switch,
gnatpp
places the generated library unit body in the current directory and generated sununits in the directory where the argument body is located.
--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)
--quiet
/-q
Quiet mode.
--verbose
/-v
Verbose mode.
5.4.2.1. Legacy Switches
Some switches have a short form, mostly for legacy reasons, as shown below.
-gnatyMnnn
--max-line-length=nnn
-innn
--indentation=nnn
-gnatynnn
--indentation=nnn
-f
--force
-gnatyo
--alphabetical-order
-hg
--comment-header-sample
-hs
--comment-header-spec
-o output-file
--output=output-file
-dir dir-name
--output-dir=dir-name
-We
--wide-character-encoding=e
-files filename
--files=filename
5.5. Translating Code Addresses into Source Locations with gnatsymbolize
gnatsymbolize
is a program which translates addresses into
their corresponding filename, line number, and function names.
5.5.1. Running gnatsymbolize
$ gnatsymbolize [ switches ] filename [ addresses ]
For example, consider the following Ada program:
package Pck is Global_Val : Integer := 0; procedure Call_Me_First; end Pck; with GNAT.IO; use GNAT.IO; with GNAT.Traceback; use GNAT.Traceback; with GNAT.Debug_Utilities; package body Pck is procedure Call_Me_Third is TB : Tracebacks_Array (1 .. 5); TB_len : Natural; begin Global_Val := Global_Val + 1; Call_Chain (TB, TB_Len); for K in 1 .. TB_Len loop Put_Line (GNAT.Debug_Utilities.Image_C (TB (K))); end loop; end Call_Me_Third; procedure Call_Me_Second is begin Call_Me_Third; end Call_Me_Second; procedure Call_Me_First is begin Call_Me_Second; end Call_Me_First; end Pck; with GNAT.IO; use GNAT.IO; with GNAT.Debug_Utilities; with GNAT.Traceback; with System; with Pck; use Pck; procedure Foo is LA : constant System.Address := \ GNAT.Traceback.Executable_Load_Address; use type System.Address; begin if LA /= System.Null_Address then Put_Line ("Load address: " & GNAT.Debug_Utilities.Image_C (LA)); end if; Global_Val := 123; Call_Me_First; end Foo;
This program, when built and run, prints a list of addresses which
correspond to the traceback when inside function Call_Me_Third
.
For example, on x86-64 GNU/Linux:
$ gnatmake -g -q foo.adb $ ./foo Load address: 0x00005586C9D7D000 0x00005586C9D81105 0x00005586C9D8119B 0x00005586C9D811A7 0x00005586C9D8128C 0x00005586C9D81069
You can use gnatsymbolize
to translate those addresses into
code locations as follows:
$ gnatsymbolize --load foo 0x00005586C9D7D000 0x00005586C9D81105 \ 0x00005586C9D8119B 0x00005586C9D811A7 0x00005586C9D8128C \ 0x00005586C9D81069 0x5586c9d81105 Pck.Call_Me_Third at pck.adb:12 0x5586c9d8119b Pck.Call_Me_Second at pck.adb:20 0x5586c9d811a7 Pck.Call_Me_First at pck.adb:25 0x5586c9d8128c Foo at foo.adb:6 0x5586c9d81069 Main at b~foo.adb:199
5.5.2. Switches for gnatsymbolize
You can specify the following switches for gnatsymbolize
:
--help
Display the program’s usage, and then exit, disregarding all other options.
--cache
Read the symbolic information from the executable and cache them in memory to accelerate the translation of each address into a symbolic location.
Depending on the size of the executable and the number of addresses to translate, this may not always make
gnatsymbolize
faster overall.--dump
If you have specified
--cache
, dump the contents of the cache to Standard Output. Has no effect otherwise.--count=N
Compute the symbolic traceback
N
times in a row. You use this switch mostly for measuring the performance ofgnatsymbolize
, particularly in the case where you have specified the cache to be used.--load
Interpret the first address as the load address of the executable. This is needed for position-independent executables on Linux and Windows.
5.5.3. Requirements for Correct Operation
The translation is performed by reading the DWARF debugging
information produced by the compiler for each unit. You must
therefore compile all units for which the translation is to be done
in a way that DWARF debugging information is produced. In most cases,
you do this by simply compiling with -g
.
This program provides a functionality similar to addr2line
.
It has fewer options to tailor its output, but has been designed
to require fewer DWARF sections to be present in the
executable. In particular, it works for code compiled with -g1
.
5.6. Using Project Files with GNAT Tools
This section describes how you can use project files in conjunction with a number of GNAT tools. For a comprehensive description of project files and the overall GNAT Project Manager facility, please refer to the GNAT Project Manager chapter in the GPRbuild and GPR Companion Tools User’s Guide.
If a tool can take a project file as an option and extract the needed information, such a tool is called a project-aware tool.
5.6.2. Tool-specific packages in project files
Each project-aware tool may have a corresponding package in a project file; the package names are given elsewhere in this manual, in the sections that describe the respective tools.
A tool-specific package in a project file may define the
Default_Switches
attribute indexed by “ada” (as language
name). You set the value of this attribute to a list of switches
that you want the tool to use when it’s invoked. You cannot
specify project-specific switches through this attribute.