5. GNAT Utility Programs

This chapter describes a number of utility programs:

It also describes how several of these tools can be used 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 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.

5.1.1. Running gnatclean

The gnatclean command has the form:

$ gnatclean switches names

where names is a list of source file names. Suffixes .ads and adb may be omitted. If a project file is specified using switch -P, then names may be completely omitted.

In normal mode, gnatclean delete the files produced by the compiler and, if switch -c is not specified, by the binder and the linker. In informative-only mode, specified by switch -n, the list of files that would have been deleted in normal mode is listed, but no file is actually deleted.

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 used, display usage, then exit disregarding all other options.

--subdirs=subdir

Actual object directory of each project file 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 used on the command line, this restriction is relaxed.

-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 (no use of switch -v), then 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. 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.

-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).

-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.

-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 value value. The Project Manager will use this value for occurrences of external(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. It can also be used to check the source dependencies of a unit as well as various characteristics.

5.2.1. Running gnatls

The gnatls command has the form

$ 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 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 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. If you use gnatmake with the option -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.

5.2.2. Switches for gnatls

gnatls recognizes the following switches:

--version

Display copyright and version, then exit disregarding all other options.

--help

If --version was not used, 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 from which 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. 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.

-aOdir, -aIdir, -Idir, -I-, -nostdinc

Source path manipulation. Same meaning as the equivalent gnatmake flags (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. Same meaning as the equivalent gnatmake flag (Switches for gnatmake).

-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.

5.2.3. 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

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 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

Note that it is no longer necessary to specify the Ada language version; gnatpp can process Ada source code written in any version from Ada 83 onward without specifying any language version switch.

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 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.

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 will follow a compact style but add aligment and put some keywords on a separate line.

Alignment is added in the the following constructs:

  • : 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 keywords in parameter specifications are also lined up.

The keyword is is placed on a separate line in a subprogram body in case the spec occupies more than one line.

The keyword return is placed 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 will avoid adding line breaks and alignment by packing as many subexpressions on the same line as possible.

Whole-line comments that form a paragraph will be 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 will favor 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 line

  • Places the keyword then in IF statements on a separate line

  • Places each keyword use in USE clauses on a separate line

  • Splits the line just before the keyword record in a RECORD type declaration

  • Indents 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 also each letter immediately following an underscore, are converted to their uppercase forms and all the 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 -n casing setting.

--enum-upper-case, -neU

Enumeration literals are in upper case. Overrides -n casing setting.

--enum-lower-case, -neL

Enumeration literals are in lower case. Overrides -n casing setting.

--enum-mixed-case, -neM

Enumeration literals are in mixed case. Overrides -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 -n casing setting.

--type-upper-case, -ntU

Names introduced by type and subtype declarations are always in upper case. Overrides -n casing setting.

--type-lower-case, -ntL

Names introduced by type and subtype declarations are always in lower case. Overrides -n casing setting.

--type-mixed-case, -ntM

Names introduced by type and subtype declarations are always in mixed case. Overrides -n casing setting.

--number-upper-case, -nnU

Names introduced by number declarations are always in upper case. Overrides -n casing setting.

--number-lower-case, -nnL

Names introduced by number declarations are always in lower case. Overrides -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 will not be 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, it is not modified. For example, with --decimal-grouping=3, 1000000 will be changed to 1_000_000.

--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#.

--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.

--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 --no-separate-is was not specified, then the is is placed on a separate line. This feature is disabled by default.

5.3.1.5. 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:

-Idir

-I-

-gnatec=path

5.3.1.6. Output File Control

By default the output overwrites the input file. The output may be redirected by 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 output file in directory dir with the same name as the input file. If 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.

--pipe, -pipe

Send the output to Standard_Output

--output=output_file, -o=output_file

Write the output into output_file. If output_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)

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.

5.3.1.7. Other gnatpp Switches

The additional gnatpp switches are 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

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.

-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.

-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.

-Xname=value

Indicates that external variable name in the argument project has the value value. Has no effect if no project is specified.

--RTS=rts-path

Specifies the default location of the runtime library. Same meaning as the equivalent gnatmake flag (Switches for gnatmake).

--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.)

--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. 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.

--ignore=filename

Do not process the sources listed in a specified file. This option cannot be used in incremental mode.

--jobs=n, -j=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.

--verbose, -v

Verbose mode

--quiet, -q

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.

5.3.2. Formatting Rules

The following subsections show how gnatpp treats, comments, program layout, name casing and 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 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:

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.

5.3.2.2. Formatting Comments

Only --layout=compact and --layout=tall format 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. 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.

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, 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).

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, --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 --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.

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 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 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 --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:

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:

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, as in $symbol. In addition, you can use conditional compilation, so long as the program text is syntactically legal Ada code after removing all the preprocessor directives (lines starting with #). For example, gnatpp can format the following:

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, and

  • at keywords in the component clauses in record representation clauses.

--align-modes, --no-align-modes

Line up in and out in parameter specifications.

--compact, --no-compact

In calls and similar, --compact packs as many subexpressions on the same line as possible. Example:

Some_Procedure
  (Short_One, Another_Short_One,
   A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);

On the contrary, with --no-compact, in calls and similar, if 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. 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 after end, 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

Named block and loop statements are indented with respect to the name.

--split-line-before-op, --no-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.

--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 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).

5.4.1. 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 --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.

    Note that it is no longer necessary 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. An aggregate project is allowed 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 value value. Has no effect if no project is specified.

--RTS=rts-path

Specifies the default location of the runtime library. Same meaning as the equivalent gnatmake flag (Switches for gnatmake).

--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.

--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 can be specified is 32767.

--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.

--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 we have no value to return.

--no-local-header

Do not place local comment header with unit name before body stub for a unit.

--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.

--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.

--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.

--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 instance, 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 instance, on x86-64 GNU/Linux:

$ gnatmake -g -q foo.adb
$ ./foo
Load address: 0x00005586C9D7D000
0x00005586C9D81105
0x00005586C9D8119B
0x00005586C9D811A7
0x00005586C9D8128C
0x00005586C9D81069

gnatsymbolize can be used to translate those addresses into code locations as follow:

$ 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

gnatsymbolize recognizes the following switches:

--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 in order 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 --cache is used, dump the contents of the cache on Standard Output. Has no effect otherwise.

--count=N

Compute the symbolic traceback N times in a row. This option is mostly useful for measuring the performance of gnatsymbolize, particularly in the case where the cache is being 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. All units for which the translation is to be done must therefore be compiled such that DWARF debugging information is produced. In most cases, this is done 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 of the 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 project files can be used 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). The value of this attribute is a list of switches that will be supplied at tool invocation. Project-specific switches cannot be specified through this attribute.