@c o
@c G N A T _ U G N o
@c o
-@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
+@c Copyright (C) 1992-2010, AdaCore o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
Inc.
Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2 or
+under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts and with no Back-Cover
Texts. A copy of the license is included in the section entitled
@macro ovar{varname}
@r{[}@var{\varname\}@r{]}@c
@end macro
+@c Status as of November 2009:
+@c Unfortunately texi2pdf and texi2html treat the trailing "@c"
+@c differently, and faulty output is produced by one or the other
+@c depending on whether the "@c" is present or absent.
+@c As a result, the @ovar macro is not used, and all invocations
+@c of the @ovar macro have been expanded inline.
+
@settitle @value{EDITION} User's Guide @value{PLATFORM}
@dircategory GNU Ada tools
* Configuration Pragmas::
* Handling Arbitrary File Naming Conventions Using gnatname::
* GNAT Project Manager::
+* Tools Supporting Project Files::
* The Cross-Referencing Tools gnatxref and gnatfind::
* The GNAT Pretty-Printer gnatpp::
* The GNAT Metric Tool gnatmetric::
* File Name Krunching Using gnatkr::
* Preprocessing Using gnatprep::
-@ifset vms
-* The GNAT Run-Time Library Builder gnatlbr::
-@end ifset
* The GNAT Library Browser gnatls::
* Cleaning Up Using gnatclean::
@ifclear vms
Reducing Size of Ada Executables with gnatelim
* About gnatelim::
* Running gnatelim::
+* Processing Precompiled Libraries::
* Correcting the List of Eliminate Pragmas::
* Making Your Executables Smaller::
* Summary of the gnatelim Usage Cycle::
* Switches for gnatname::
* Examples of gnatname Usage::
-GNAT Project Manager
-
-* Introduction::
-* Examples of Project Files::
-* Project File Syntax::
-* Objects and Sources in Project Files::
-* Importing Projects::
-* Project Extension::
-* Project Hierarchy Extension::
-* External References in Project Files::
-* Packages in Project Files::
-* Variables from Imported Projects::
-* Naming Schemes::
-* Library Projects::
-* Stand-alone Library Projects::
-* Switches Related to Project Files::
-* Tools Supporting Project Files::
-* An Extended Example::
-* Project File Complete Syntax::
-
The Cross-Referencing Tools gnatxref and gnatfind
-* gnatxref Switches::
-* gnatfind Switches::
+* Switches for gnatxref::
+* Switches for gnatfind::
* Project Files for gnatxref and gnatfind::
* Regular Expressions in gnatfind and gnatxref::
* Examples of gnatxref Usage::
* Form of Definitions File::
* Form of Input Text for gnatprep::
-@ifset vms
-The GNAT Run-Time Library Builder gnatlbr
-
-* Running gnatlbr::
-* Switches for gnatlbr::
-* Examples of gnatlbr Usage::
-@end ifset
-
The GNAT Library Browser gnatls
* Running gnatls::
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
+* Example of gnatcheck Usage::
Sample Bodies Using gnatstub
* Ada Exceptions::
* Ada Tasks::
* Debugging Generic Units::
+* Remote Debugging using gdbserver::
* GNAT Abnormal Termination or Failure to Terminate::
* Naming Conventions for GNAT Source Files::
* Getting Internal Debugging Information::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
* Irix-Specific Considerations::
+* RTX-Specific Considerations::
+* HP-UX-Specific Considerations::
Example of Binder Output File
generate multiple or parameterized source files by means of macro
substitution.
-@ifset vms
-@item
-@ref{The GNAT Run-Time Library Builder gnatlbr}, describes @command{gnatlbr},
-a tool for rebuilding the GNAT run time with user-supplied
-configuration pragmas.
-@end ifset
-
@item
@ref{The GNAT Library Browser gnatls}, describes @code{gnatls}, a
utility that displays information about compiled units, including dependences
@noindent
The basic character set is Latin-1. This character set is defined by ISO
standard 8859, part 1. The lower half (character codes @code{16#00#}
-@dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper half
-is used to represent additional characters. These include extended letters
+@dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper
+half is used to represent additional characters. These include extended letters
used by European languages, such as French accents, the vowels with umlauts
used in German, and the extra letter A-ring used in Swedish.
@cindex cannot generate code
If you attempt to compile any of these files, you will get one of the
-following error messages (where @var{fff} is the name of the file you compiled):
+following error messages (where @var{fff} is the name of the file you
+compiled):
@smallexample
cannot generate code for file @var{fff} (package spec)
The basic command for compiling a file containing an Ada unit is
@smallexample
-$ gcc -c @ovar{switches} @file{file name}
+@c $ gcc -c @ovar{switches} @file{file name}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gcc -c @r{[}@var{switches}@r{]} @file{file name}
@end smallexample
@noindent
@item -fno-inline-functions
@cindex @option{-fno-inline-functions} (@command{gcc})
-Suppresses automatic inlining of simple subprograms, which is enabled
+Suppresses automatic inlining of subprograms, which is enabled
if @option{-O3} is used.
@item -fno-inline-small-functions
@cindex @option{-gnat05} (@command{gcc})
Allow full Ada 2005 features.
+@item -gnat2005
+@cindex @option{-gnat2005} (@command{gcc})
+Allow full Ada 2005 features (same as @option{-gnat05}
+
+@item -gnat12
+@cindex @option{-gnat12} (@command{gcc})
+
+@item -gnat2012
+@cindex @option{-gnat2012} (@command{gcc})
+Allow full Ada 2012 features (same as @option{-gnat12}
+
@item -gnata
@cindex @option{-gnata} (@command{gcc})
Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
@item -gnatB
@cindex @option{-gnatB} (@command{gcc})
-Assume no invalid (bad) values except for 'Valid attribute use.
+Assume no invalid (bad) values except for 'Valid attribute use
+(@pxref{Validity Checking}).
@item -gnatc
@cindex @option{-gnatc} (@command{gcc})
Check syntax and semantics only (no code generation attempted).
+@item -gnatC
+@cindex @option{-gnatC} (@command{gcc})
+Generate CodePeer information (no code generation attempted).
+This switch will generate an intermediate representation suitable for
+use by CodePeer (@file{.scil} files). This switch is not compatible with
+code generation (it will, among other things, disable some switches such
+as -gnatn, and enable others such as -gnata).
+
@item -gnatd
@cindex @option{-gnatd} (@command{gcc})
Specify debug options for the compiler. The string of characters after
@end ifclear
(@pxref{Integrated Preprocessing}).
+@item -gnateS
+@cindex @option{-gnateS} (@command{gcc})
+Generate SCO (Source Coverage Obligation) information in the ALI
+file. This information is used by advanced coverage tools. See
+unit @file{SCOs} in the compiler sources for details in files
+@file{scos.ads} and @file{scos.adb}.
+
@item -gnatE
@cindex @option{-gnatE} (@command{gcc})
Full dynamic elaboration checks.
@option{^-gnatwae^/WARNINGS=ALL,ERRORS^} and
@option{^-gnatyg^/STYLE_CHECKS=GNAT^}
so that all standard warnings and all standard style options are turned on.
-All warnings and style error messages are treated as errors.
+All warnings and style messages are treated as errors.
@ifclear vms
@item -gnatG=nn
@item -gnatn
@cindex @option{-gnatn} (@command{gcc})
Activate inlining for subprograms for which
-pragma @code{inline} is specified. This inlining is performed
+pragma @code{Inline} is specified. This inlining is performed
by the GCC back-end.
@item -gnatN
@item -gnatp
@cindex @option{-gnatp} (@command{gcc})
-Suppress all checks. See @ref{Run-Time Checks} for details.
+Suppress all checks. See @ref{Run-Time Checks} for details. This switch
+has no effect if cancelled by a subsequent @option{-gnat-p} switch.
+
+@item -gnat-p
+@cindex @option{-gnat-p} (@command{gcc})
+Cancel effect of previous @option{-gnatp} switch.
@item -gnatP
@cindex @option{-gnatP} (@command{gcc})
@item -gnatV
@cindex @option{-gnatV} (@command{gcc})
-Control level of validity checking. See separate section describing
-this feature.
+Control level of validity checking (@pxref{Validity Checking}).
@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^
@cindex @option{^-gnatw^/WARNINGS^} (@command{gcc})
@cindex @option{-gnatx} (@command{gcc})
Suppress generation of cross-reference information.
+@item -gnatX
+@cindex @option{-gnatX} (@command{gcc})
+Enable GNAT implementation extensions and latest Ada version.
+
@item ^-gnaty^/STYLE_CHECKS=(option,option@dots{})^
@cindex @option{^-gnaty^/STYLE_CHECKS^} (@command{gcc})
Enable built-in style checks (@pxref{Style Checking}).
Library (RTL) ALI files.
@ifclear vms
-@item -O@ovar{n}
+@c @item -O@ovar{n}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+@item -O@r{[}@var{n}@r{]}
@cindex @option{-O} (@command{gcc})
@var{n} controls the optimization level.
@item
The switches
-@option{^-gnatz^/DISTRIBUTION_STUBS^}, @option{-gnatzc}, and @option{-gnatzr}
-may not be combined with any other switches.
+^^@option{/DISTRIBUTION_STUBS=},^
+@option{-gnatzc} and @option{-gnatzr} may not be combined with any other
+switches, and only one of them may appear in the command line.
+
+@item
+The switch @option{-gnat-p} may not be combined with any other switch.
@ifclear vms
@item
@item
Once a ``V'' appears in the string (that is a use of the @option{-gnatV}
switch), then all further characters in the switch are interpreted
-as validity checking options (see description of @option{-gnatV}).
+as validity checking options (@pxref{Validity Checking}).
+
+@item
+Option ``em'', ``ec'', ``ep'', ``l='' and ``R'' must be the last options in
+a combined list of options.
@end ifclear
@end itemize
@itemize @bullet
@item
-Full details on entities not available in high integrity mode
-@item
Details on possibly non-portable unchecked conversion
@item
List possible interpretations for ambiguous calls
switch are
@option{-gnatwd} (implicit dereferencing),
@option{-gnatwh} (hiding),
+@option{-gnatw.h} (holes (gaps) in record layouts)
@option{-gnatwl} (elaboration warnings),
@option{-gnatw.o} (warn on values set by out parameters ignored)
and @option{-gnatwt} (tracking of deleted conditional code).
indexed components, slices, and selected components.
@item -gnatwe
-@emph{Treat warnings as errors.}
+@emph{Treat warnings and style checks as errors.}
@cindex @option{-gnatwe} (@command{gcc})
@cindex Warnings, treat as error
-This switch causes warning messages to be treated as errors.
+This switch causes warning messages and style check messages to be
+treated as errors.
The warning string still appears, but the warning messages are counted
-as errors, and prevent the generation of an object file.
+as errors, and prevent the generation of an object file. Note that this
+is the only -gnatw switch that affects the handling of style check messages.
@item -gnatw.e
@emph{Activate every optional warning}
@cindex @option{-gnatwH} (@command{gcc})
This switch suppresses warnings on hiding declarations.
+@item -gnatw.h
+@emph{Activate warnings on holes/gaps in records.}
+@cindex @option{-gnatw.h} (@command{gcc})
+@cindex Record Representation (gaps)
+This switch activates warnings on component clauses in record
+representation clauses that leave holes (gaps) in the record layout.
+If this warning option is active, then record representation clauses
+should specify a contiguous layout, adding unused fill fields if needed.
+Note that @option{-gnatwa} does not affect the setting of this warning option.
+
+@item -gnatw.H
+@emph{Suppress warnings on holes/gaps in records.}
+@cindex @option{-gnatw.H} (@command{gcc})
+This switch suppresses warnings on component clauses in record
+representation clauses that leave holes (haps) in the record layout.
+
@item -gnatwi
@emph{Activate warnings on implementation units.}
@cindex @option{-gnatwi} (@command{gcc})
This switch disables warnings for a @code{with} of an internal GNAT
implementation unit.
+@item -gnatw.i
+@emph{Activate warnings on overlapping actuals.}
+@cindex @option{-gnatw.i} (@command{gcc})
+This switch enables a warning on statically detectable overlapping actuals in
+a subprogram call, when one of the actuals is an in-out parameter, and the
+types of the actuals are not by-copy types. The warning is off by default,
+and is not included under -gnatwa.
+
+@item -gnatw.I
+@emph{Disable warnings on overlapping actuals.}
+@cindex @option{-gnatw.I} (@command{gcc})
+This switch disables warnings on overlapping actuals in a call..
+
@item -gnatwj
@emph{Activate warnings on obsolescent features (Annex J).}
@cindex @option{-gnatwj} (@command{gcc})
output of all warning messages from the GNAT front end.
Note that it does not suppress warnings from the @command{gcc} back end.
To suppress these back end warnings as well, use the switch @option{-w}
-in addition to @option{-gnatws}.
+in addition to @option{-gnatws}. Also this switch has no effect on the
+handling of style check messages.
+
+@item -gnatw.s
+@emph{Activate warnings on overridden size clauses.}
+@cindex @option{-gnatw.s} (@command{gcc})
+@cindex Record Representation (component sizes)
+This switch activates warnings on component clauses in record
+representation clauses where the length given overrides that
+specified by an explicit size clause for the component type. A
+warning is similarly given in the array case if a specified
+component size overrides an explicit size clause for the array
+component type.
+Note that @option{-gnatwa} does not affect the setting of this warning option.
+
+@item -gnatw.S
+@emph{Suppress warnings on overriddebn size clauses.}
+@cindex @option{-gnatw.S} (@command{gcc})
+This switch suppresses warnings on component clauses in record
+representation clauses that override size clauses, and similar
+warnings when an array component size overrides a size clause.
@item -gnatwt
@emph{Activate warnings for tracking of deleted conditional code.}
It also turns off warnings on unreferenced formals (and thus includes
the effect of @option{-gnatwF}).
+@item -gnatw.u
+@emph{Activate warnings on unordered enumeration types.}
+@cindex @option{-gnatw.u} (@command{gcc})
+This switch causes enumeration types to be considered as conceptually
+unordered, unless an explicit pragma @code{Ordered} is given for the type.
+The effect is to generate warnings in clients that use explicit comparisons
+or subranges, since these constructs both treat objects of the type as
+ordered. (A @emph{client} is defined as a unit that is other than the unit in
+which the type is declared, or its body or subunits.) Please refer to
+the description of pragma @code{Ordered} in the
+@cite{@value{EDITION} Reference Manual} for further details.
+
+@item -gnatw.U
+@emph{Deactivate warnings on unordered enumeration types.}
+@cindex @option{-gnatw.U} (@command{gcc})
+This switch causes all enumeration types to be considered as ordered, so
+that no warnings are given for comparisons or subranges for any type.
+
@item -gnatwv
@emph{Activate warnings on unassigned variables.}
@cindex @option{-gnatwv} (@command{gcc})
@findex Validity Checking
@noindent
-The Ada Reference Manual has specific requirements for checking
-for invalid values. In particular, RM 13.9.1 requires that the
-evaluation of invalid values (for example from unchecked conversions),
-not result in erroneous execution. In GNAT, the result of such an
-evaluation in normal default mode is to either use the value
-unmodified, or to raise Constraint_Error in those cases where use
-of the unmodified value would cause erroneous execution. The cases
-where unmodified values might lead to erroneous execution are case
-statements (where a wild jump might result from an invalid value),
-and subscripts on the left hand side (where memory corruption could
-occur as a result of an invalid value).
+The Ada Reference Manual defines the concept of invalid values (see
+RM 13.9.1). The primary source of invalid values is uninitialized
+variables. A scalar variable that is left uninitialized may contain
+an invalid value; the concept of invalid does not apply to access or
+composite types.
+
+It is an error to read an invalid value, but the RM does not require
+run-time checks to detect such errors, except for some minimal
+checking to prevent erroneous execution (i.e. unpredictable
+behavior). This corresponds to the @option{-gnatVd} switch below,
+which is the default. For example, by default, if the expression of a
+case statement is invalid, it will raise Constraint_Error rather than
+causing a wild jump, and if an array index on the left-hand side of an
+assignment is invalid, it will raise Constraint_Error rather than
+overwriting an arbitrary memory location.
+
+The @option{-gnatVa} may be used to enable additional validity checks,
+which are not required by the RM. These checks are often very
+expensive (which is why the RM does not require them). These checks
+are useful in tracking down uninitialized variables, but they are
+not usually recommended for production builds.
+
+The other @option{-gnatV^@var{x}^^} switches below allow finer-grained
+control; you can enable whichever validity checks you desire. However,
+for most debugging purposes, @option{-gnatVa} is sufficient, and the
+default @option{-gnatVd} (i.e. standard Ada behavior) is usually
+sufficient for non-debugging use.
The @option{-gnatB} switch tells the compiler to assume that all
values are valid (that is, within their declared subtype range)
except in the context of a use of the Valid attribute. This means
the compiler can generate more efficient code, since the range
-of values is better known at compile time.
+of values is better known at compile time. However, an uninitialized
+variable can cause wild jumps and memory corruption in this mode.
-The @option{-gnatV^@var{x}^^} switch allows more control over the validity
-checking mode.
+The @option{-gnatV^@var{x}^^} switch allows control over the validity
+checking mode as described below.
@ifclear vms
The @code{x} argument is a string of letters that
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifclear
@ifset vms
The options allowed for this qualifier
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifset
@table @option
enforce specified style rules. A limited set of style rules has been used
in writing the GNAT sources themselves. This switch allows user programs
to activate all or some of these checks. If the source program fails a
-specified style check, an appropriate warning message is given, preceded by
-the character sequence ``(style)''.
+specified style check, an appropriate message is given, preceded by
+the character sequence ``(style)''. This message does not prevent
+successful compilation (unless the @option{-gnatwe} switch is used).
+
+Note that this is by no means intended to be a general facility for
+checking arbitrary coding standards. It is simply an embedding of the
+style rules we have chosen for the GNAT sources. If you are starting
+a project which does not have established style standards, you may
+find it useful to adopt the entire set of GNAT coding standards, or
+some subset of them. If you already have an established set of coding
+standards, then it may be that selected style checking options do
+indeed correspond to choices you have made, but for general checking
+of an existing set of coding rules, you should look to the gnatcheck
+tool, which is designed for that purpose.
+
@ifset vms
@code{(option,option,@dots{})} is a sequence of keywords
@end ifset
rule, together with h (no horizontal tabs), is to enforce a canonical format
for the use of blanks to separate source tokens.
+@item ^B^BOOLEAN_OPERATORS^
+@emph{Check Boolean operators.}
+The use of AND/OR operators is not permitted except in the cases of modular
+operands, array operands, and simple stand-alone boolean variables or
+boolean constants. In all other cases AND THEN/OR ELSE are required.
+
@item ^c^COMMENTS^
@emph{Check comments.}
Comments must meet the following set of rules:
following the ``@code{--}'' at the start of the comment.
@item
-Full line comments must have two blanks following the ``@code{--}'' that
-starts the comment, with the following exceptions.
+Full line comments must have at least two blanks following the
+``@code{--}'' that starts the comment, with the following exceptions.
@item
A line consisting only of the ``@code{--}'' characters, possibly preceded
a space must separate the two tokens.
@item
+if the token following a right parenthesis starts with a letter or digit, then
+a space must separate the two tokens.
+
+@item
A right parenthesis must either be the first non-blank character on
a line, or it must be preceded by a non-blank character.
XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
@end ifset
-
-
The switch
@ifclear vms
@option{-gnatyN}
the condition being checked is true, which can result in disaster if
that assumption is wrong.
+The @option{-gnatp} switch has no effect if a subsequent
+@option{-gnat-p} switch appears.
+
+@item -gnat-p
+@cindex @option{-gnat-p} (@command{gcc})
+@cindex Suppressing checks
+@cindex Checks, suppressing
+@findex Suppress
+This switch cancels the effect of a previous @option{gnatp} switch.
+
@item -gnato
@cindex @option{-gnato} (@command{gcc})
@cindex Overflow checks
messages or warnings.
This switch also can be used to cancel the effect of a previous
-@option{-gnat83} or @option{-gnat05} switch earlier in the command line.
+@option{-gnat83}, @option{-gnat05/2005}, or @option{-gnat12/2012}
+switch earlier in the command line.
-@item -gnat05 (Ada 2005 mode)
+@item -gnat05 or -gnat2005 (Ada 2005 mode)
@cindex @option{-gnat05} (@command{gcc})
+@cindex @option{-gnat2005} (@command{gcc})
@cindex Ada 2005 mode
@noindent
This switch directs the compiler to implement the Ada 2005 version of the
-language.
+language, as documented in the official Ada standards document.
Since Ada 2005 is almost completely upwards
compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
may generally be compiled using this switch (see the description of the
@option{-gnat83} and @option{-gnat95} switches for further
information).
+Note that even though Ada 2005 is the current official version of the
+language, GNAT still compiles in Ada 95 mode by default, so if you are
+using Ada 2005 features in your program, you must use this switch (or
+the equivalent Ada_05 or Ada_2005 configuration pragmas).
+
+@item -gnat12 or -gnat2012 (Ada 2012 mode)
+@cindex @option{-gnat12} (@command{gcc})
+@cindex @option{-gnat2012} (@command{gcc})
+@cindex Ada 2012 mode
+
+@noindent
+This switch directs the compiler to implement the Ada 2012 version of the
+language.
+Since Ada 2012 is almost completely upwards
+compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
+Ada 83 and Ada 95 programs
+may generally be compiled using this switch (see the description of the
+@option{-gnat83}, @option{-gnat95}, and @option{-gnat05/2005} switches
+for further information).
+
For information about the approved ``Ada Issues'' that have been incorporated
-into Ada 2005, see @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}.
-Included with GNAT releases is a file @file{features-ada0y} that describes
-the set of implemented Ada 2005 features.
-@end table
+into Ada 2012, see @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}.
+Included with GNAT releases is a file @file{features-ada12} that describes
+the set of implemented Ada 2012 features.
+@item -gnatX (Enable GNAT Extensions)
+@cindex @option{-gnatX} (@command{gcc})
+@cindex Ada language extensions
+@cindex GNAT extensions
+
+@noindent
+This switch directs the compiler to implement the latest version of the
+language (currently Ada 2012) and also to enable certain GNAT implementation
+extensions that are not part of any Ada standard. For a full list of these
+extensions, see the GNAT reference manual.
+
+@end table
@node Character Set Control
@subsection Character Set Control
Used to list an equivalent declaration for an internally generated
type that is referenced elsewhere in the listing.
-@item freeze @var{type-name} @ovar{actions}
+@c @item freeze @var{type-name} @ovar{actions}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+@item freeze @var{type-name} @r{[}@var{actions}@r{]}
Shows the point at which @var{type-name} is frozen, with possible
associated actions to be performed at the freeze point.
@table @option
-@item -gnatem^^=^@var{path}
+@item -gnatem=@var{path}
@cindex @option{-gnatem} (@command{gcc})
A mapping file is a way to communicate to the compiler two mappings:
from unit names to file names (without any directory information) and from
sources are read over a slow network connection. In normal operation,
you need not be concerned with the format or use of mapping files,
and the @option{-gnatem} switch is not a switch that you would use
-explicitly. it is intended only for use by automatic tools such as
+explicitly. It is intended primarily for use by automatic tools such as
@command{gnatmake} running under the project file facility. The
description here of the format of mapping files is provided
for completeness and for possible use by other tools.
-A mapping file is a sequence of sets of three lines. In each set,
-the first line is the unit name, in lower case, with ``@code{%s}''
-appended for
-specs and ``@code{%b}'' appended for bodies; the second line is the
+A mapping file is a sequence of sets of three lines. In each set, the
+first line is the unit name, in lower case, with @code{%s} appended
+for specs and @code{%b} appended for bodies; the second line is the
file name; and the third line is the path name.
Example:
/gnat/project1/sources/main.2.ada
@end smallexample
-When the switch @option{-gnatem} is specified, the compiler will create
-in memory the two mappings from the specified file. If there is any problem
-(nonexistent file, truncated file or duplicate entries), no mapping will
-be created.
+When the switch @option{-gnatem} is specified, the compiler will
+create in memory the two mappings from the specified file. If there is
+any problem (nonexistent file, truncated file or duplicate entries),
+no mapping will be created.
-Several @option{-gnatem} switches may be specified; however, only the last
-one on the command line will be taken into account.
+Several @option{-gnatem} switches may be specified; however, only the
+last one on the command line will be taken into account.
-When using a project file, @command{gnatmake} create a temporary mapping file
-and communicates it to the compiler using this switch.
+When using a project file, @command{gnatmake} creates a temporary
+mapping file and communicates it to the compiler using this switch.
@end table
The form of the @code{gnatbind} command is
@smallexample
-$ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches}
+@c $ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatbind @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} @r{[}@var{switches}@r{]}
@end smallexample
@noindent
where @file{@var{mainprog}.adb} is the Ada file containing the main program
-unit body. If no switches are specified, @code{gnatbind} constructs an Ada
+unit body. @code{gnatbind} constructs an Ada
package in two files whose names are
@file{b~@var{mainprog}.ads}, and @file{b~@var{mainprog}.adb}.
For example, if given the
Ada code provided the @option{^-g^/DEBUG^} switch is used for
@command{gnatbind} and @command{gnatlink}.
-However for some purposes it may be convenient to generate the main
-program in C rather than Ada. This may for example be helpful when you
-are generating a mixed language program with the main program in C. The
-GNAT compiler itself is an example.
-The use of the @option{^-C^/BIND_FILE=C^} switch
-for both @code{gnatbind} and @command{gnatlink} will cause the program to
-be generated in C (and compiled using the gnu C compiler).
-
@node Switches for gnatbind
@section Switches for @command{gnatbind}
* Binder Error Message Control::
* Elaboration Control::
* Output Control::
+* Dynamic Allocation Control::
* Binding with Non-Ada Main Programs::
* Binding Programs with No Main Subprogram::
@end menu
@cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind})
Specify directory to be searched for source file.
-@item ^-A^/BIND_FILE=ADA^
-@cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatbind})
-Generate binder program in Ada (default)
+@item ^-A^/ALI_LIST^@r{[=}@var{filename}@r{]}
+@cindex @option{^-A^/ALI_LIST^} (@command{gnatbind})
+Output ALI list (to standard output or to the named file).
@item ^-b^/REPORT_ERRORS=BRIEF^
@cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@command{gnatbind})
@cindex @option{^-c^/NOOUTPUT^} (@command{gnatbind})
Check only, no generation of binder output file.
-@item ^-C^/BIND_FILE=C^
-@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind})
-Generate binder program in C
-
@item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}
@cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}} (@command{gnatbind})
This switch can be used to change the default task stack size value
@item ^-E^/STORE_TRACEBACKS^
@cindex @option{^-E^/STORE_TRACEBACKS^} (@command{gnatbind})
Store tracebacks in exception occurrences when the target supports it.
-This is the default with the zero cost exception mechanism.
@ignore
@c The following may get moved to an appendix
This option is currently supported on the following targets:
@cindex @option{^-h^/HELP^} (@command{gnatbind})
Output usage (help) information
+@item ^-H32^/32_MALLOC^
+@cindex @option{^-H32^/32_MALLOC^} (@command{gnatbind})
+Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types).
+For further details see @ref{Dynamic Allocation Control}.
+
+@item ^-H64^/64_MALLOC^
+@cindex @option{^-H32^/32_MALLOC^} (@command{gnatbind})
+Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types).
+@cindex @code{__gnat_malloc}
+For further details see @ref{Dynamic Allocation Control}.
+
@item ^-I^/SEARCH^
@cindex @option{^-I^/SEARCH^} (@command{gnatbind})
Specify directory to be searched for source and ALI files.
Note that if this option is used, then linking must be done manually,
gnatlink cannot be used.
-@item ^-O^/OBJECT_LIST^
+@item ^-O^/OBJECT_LIST^@r{[=}@var{filename}@r{]}
@cindex @option{^-O^/OBJECT_LIST^} (@command{gnatbind})
-Output object list.
+Output object list (to standard output or to the named file).
@item ^-p^/PESSIMISTIC_ELABORATION^
@cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@command{gnatbind})
@table @option
@c !sort!
-@item ^-A^/BIND_FILE=ADA^
-@cindex @option{^-A^/BIND_FILE=ADA^} (@code{gnatbind})
-Generate binder program in Ada (default). The binder program is named
-@file{b~@var{mainprog}.adb} by default. This can be changed with
-@option{^-o^/OUTPUT^} @code{gnatbind} option.
-
@item ^-c^/NOOUTPUT^
@cindex @option{^-c^/NOOUTPUT^} (@code{gnatbind})
Check only. Do not generate the binder output file. In this mode the
binder performs all error checks but does not generate an output file.
-@item ^-C^/BIND_FILE=C^
-@cindex @option{^-C^/BIND_FILE=C^} (@code{gnatbind})
-Generate binder program in C. The binder program is named
-@file{b_@var{mainprog}.c}.
-This can be changed with @option{^-o^/OUTPUT^} @code{gnatbind}
-option.
-
@item ^-e^/ELABORATION_DEPENDENCIES^
@cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@code{gnatbind})
Output complete list of elaboration-order dependencies, showing the
@cindex @option{^-o^/OUTPUT^} (@code{gnatbind})
Set name of output file to @var{file} instead of the normal
@file{b~@var{mainprog}.adb} default. Note that @var{file} denote the Ada
-binder generated body filename. In C mode you would normally give
-@var{file} an extension of @file{.c} because it will be a C source program.
+binder generated body filename.
Note that if this option is used, then linking must be done manually.
It is not possible to use gnatlink in this case, since it cannot locate
the binder file.
@end table
+@node Dynamic Allocation Control
+@subsection Dynamic Allocation Control
+
+@noindent
+The heap control switches -- @option{-H32} and @option{-H64} --
+determine whether dynamic allocation uses 32-bit or 64-bit memory.
+They only affect compiler-generated allocations via @code{__gnat_malloc};
+explicit calls to @code{malloc} and related functions from the C
+run-time library are unaffected.
+
+@table @option
+@item -H32
+Allocate memory on 32-bit heap
+
+@item -H64
+Allocate memory on 64-bit heap. This is the default
+unless explicitly overridden by a @code{'Size} clause on the access type.
+@end table
+
+@ifset vms
+@noindent
+See also @ref{Access types and 32/64-bit allocation}.
+@end ifset
+@ifclear vms
+@noindent
+These switches are only effective on VMS platforms.
+@end ifclear
+
+
@node Binding with Non-Ada Main Programs
@subsection Binding with Non-Ada Main Programs
The binder takes the name of its output file from the last specified ALI
file, unless overridden by the use of the @option{^-o file^/OUTPUT=file^}.
@cindex @option{^-o^/OUTPUT^} (@command{gnatbind})
-The output is an Ada unit in source form that can
-be compiled with GNAT unless the -C switch is used in which case the
-output is a C source file, which must be compiled using the C compiler.
+The output is an Ada unit in source form that can be compiled with GNAT.
This compilation occurs automatically as part of the @command{gnatlink}
processing.
bound using the standard switch settings. The generated main program is
@file{mainprog.adb} with the associated spec in
@file{mainprog.ads}. Note that you must specify the body here not the
-spec, in the case where the output is in Ada. Note that if this option
-is used, then linking must be done manually, since gnatlink will not
-be able to find the generated file.
-
-@ifclear vms
-@item gnatbind main -C -o mainprog.c -x
-@end ifclear
-@ifset vms
-@item gnatbind MAIN.ALI /BIND_FILE=C /OUTPUT=Mainprog.C /READ_SOURCES=NONE
-@end ifset
-The main program @code{Main} (source program in
-@file{main.adb}) is bound, excluding source files from the
-consistency checking, generating
-the file @file{mainprog.c}.
-
-@ifclear vms
-@item gnatbind -x main_program -C -o mainprog.c
-This command is exactly the same as the previous example. Switches may
-appear anywhere in the command line, and single letter switches may be
-combined into a single switch.
-@end ifclear
-
-@ifclear vms
-@item gnatbind -n math dbase -C -o ada-control.c
-@end ifclear
-@ifset vms
-@item gnatbind /NOMAIN math dbase /BIND_FILE=C /OUTPUT=ada-control.c
-@end ifset
-The main program is in a language other than Ada, but calls to
-subprograms in packages @code{Math} and @code{Dbase} appear. This call
-to @code{gnatbind} generates the file @file{ada-control.c} containing
-the @code{adainit} and @code{adafinal} routines to be called before and
-after accessing the Ada units.
+spec. Note that if this option is used, then linking must be done manually,
+since gnatlink will not be able to find the generated file.
@end table
@c ------------------------------------
The form of the @command{gnatlink} command is
@smallexample
-$ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]}
- @ovar{non-Ada objects} @ovar{linker options}
+@c $ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]}
+@c @ovar{non-Ada objects} @ovar{linker options}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatlink @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]}
+ @r{[}@var{non-Ada objects}@r{]} @r{[}@var{linker options}@r{]}
+
@end smallexample
@noindent
If @option{--version} was not used, display usage, then exit disregarding
all other options.
-@item ^-A^/BIND_FILE=ADA^
-@cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatlink})
-The binder has generated code in Ada. This is the default.
-
-@item ^-C^/BIND_FILE=C^
-@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatlink})
-If instead of generating a file in Ada, the binder has generated one in
-C, then the linker needs to know about it. Use this switch to signal
-to @command{gnatlink} that the binder has generated C code rather than
-Ada code.
-
@item ^-f^/FORCE_OBJECT_FILE_LIST^
@cindex Command line length
@cindex @option{^-f^/FORCE_OBJECT_FILE_LIST^} (@command{gnatlink})
The usual form of the @command{gnatmake} command is
@smallexample
-$ gnatmake @ovar{switches} @var{file_name}
- @ovar{file_names} @ovar{mode_switches}
+@c $ gnatmake @ovar{switches} @var{file_name}
+@c @ovar{file_names} @ovar{mode_switches}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatmake @r{[}@var{switches}@r{]} @var{file_name}
+ @r{[}@var{file_names}@r{]} @r{[}@var{mode_switches}@r{]}
@end smallexample
@noindent
@end ifclear
+@item ^--subdirs^/SUBDIRS^=subdir
+Actual object directory of each project file is the subdirectory subdir of the
+object directory specified or defaulted in the project file.
+
+@item ^--single-compile-per-obj-dir^/SINGLE_COMPILE_PER_OBJ_DIR^
+Disallow simultaneous compilations in the same object directory when
+project files are used.
+
+@item ^--unchecked-shared-lib-imports^/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.
+
+@ifclear vms
+@item --create-map-file
+When linking an executable, create a map file. The name of the map file
+has the same name as the executable with extension ".map".
+
+@item --create-map-file=mapfile
+When linking an executable, create a map file. The name of the map file is
+"mapfile".
+
+@end ifclear
+
@item ^-a^/ALL_FILES^
@cindex @option{^-a^/ALL_FILES^} (@command{gnatmake})
Consider all files in the make process, even the GNAT internal system
@item ^-C^/MAPPING^
@cindex @option{^-C^/MAPPING^} (@command{gnatmake})
-Use a temporary mapping file. A mapping file is a way to communicate to the
-compiler two mappings: from unit names to file names (without any directory
-information) and from file names to path names (with full directory
-information). These mappings are used by the compiler to short-circuit the path
-search. When @command{gnatmake} is invoked with this switch, it will create
-a temporary mapping file, initially populated by the project manager,
-if @option{^-P^/PROJECT_FILE^} is used, otherwise initially empty.
-Each invocation of the compiler will add the newly accessed sources to the
-mapping file. This will improve the source search during the next invocation
-of the compiler.
+Use a temporary mapping file. A mapping file is a way to communicate
+to the compiler two mappings: from unit names to file names (without
+any directory information) and from file names to path names (with
+full directory information). A mapping file can make the compiler's
+file searches faster, especially if there are many source directories,
+or the sources are read over a slow network connection. If
+@option{^-P^/PROJECT_FILE^} is used, a mapping file is always used, so
+@option{^-C^/MAPPING^} is unnecessary; in this case the mapping file
+is initially populated based on the project file. If
+@option{^-C^/MAPPING^} is used without
+@option{^-P^/PROJECT_FILE^},
+the mapping file is initially empty. Each invocation of the compiler
+will add any newly accessed sources to the mapping file.
@item ^-C=^/USE_MAPPING_FILE=^@var{file}
@cindex @option{^-C=^/USE_MAPPING^} (@command{gnatmake})
@ifclear vms
@item -eL
@cindex @option{-eL} (@command{gnatmake})
+@cindex symbolic links
Follow all symbolic links when processing project files.
+This should be used if your project uses symbolic links for files or
+directories, but is not needed in other cases.
+
+@cindex naming scheme
+This also assumes that no directory matches the naming scheme for files (for
+instance that you do not have a directory called "sources.ads" when using the
+default GNAT naming scheme).
+
+When you do not have to use this switch (ie by default), gnatmake is able to
+save a lot of system calls (several per source file and object file), which
+can result in a significant speed up to load and manipulate a project file,
+especially when using source files from a remote system.
+
@end ifclear
@item ^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^
the slowest compilation time.
@item ^-O3^/OPTIMIZE=INLINING^
-Full optimization as in @option{-O2},
-and also attempts automatic inlining of small
-subprograms within a unit (@pxref{Inlining of Subprograms}).
+Full optimization as in @option{-O2};
+also uses more aggressive automatic inlining of subprograms within a unit
+(@pxref{Inlining of Subprograms}) and attemps to vectorize loops.
@item ^-Os^/OPTIMIZE=SPACE^
-Optimize space usage of resulting program.
+Optimize space usage (code and data) of resulting program.
@end table
@noindent
Note regarding the use of @option{-O3}: The use of this optimization level
is generally discouraged with GNAT, since it often results in larger
-executables which run more slowly. See further discussion of this point
+executables which may run more slowly. See further discussion of this point
in @ref{Inlining of Subprograms}.
@node Debugging Optimized Code
@item
@cindex pragma Inline
@findex Inline
-Either @code{pragma Inline} applies to the subprogram, or it is local
-to the unit and called once from within it, or it is small and automatic
-inlining (optimization level @option{-O3}) is specified.
+Either @code{pragma Inline} applies to the subprogram and the
+@option{^-gnatn^/INLINE^} switch is used on the command line, or it is local
+to the unit and called once from within it, or it is small and optimization
+level @option{-O2} is specified, or automatic inlining (optimization level
+@option{-O3}) is specified.
@end itemize
@noindent
There is a @code{pragma Inline} for the subprogram.
@item
-@cindex @option{-gnatn} (@command{gcc})
-The @option{^-gnatn^/INLINE^} switch
-is used in the @command{gcc} command line
+The @option{^-gnatn^/INLINE^} switch is used on the command line.
@end itemize
Even if all these conditions are met, it may not be possible for
@cindex @option{-fno-inline-functions} (@command{gcc})
Note: The @option{-fno-inline-functions} switch can be used to prevent
-automatic inlining of small subprograms if @option{-O3} is used.
+automatic inlining of subprograms if @option{-O3} is used.
+
+@cindex @option{-fno-inline-small-functions} (@command{gcc})
+Note: The @option{-fno-inline-small-functions} switch can be used to prevent
+automatic inlining of small subprograms if @option{-O2} is used.
@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
Note: The @option{-fno-inline-functions-called-once} switch
@menu
* About gnatelim::
* Running gnatelim::
+* Processing Precompiled Libraries::
* Correcting the List of Eliminate Pragmas::
* Making Your Executables Smaller::
* Summary of the gnatelim Usage Cycle::
@xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more
information about this pragma.
-@code{gnatelim} needs as its input data the name of the main subprogram
-and a bind file for a main subprogram.
+@code{gnatelim} needs as its input data the name of the main subprogram.
+
+If a set of source files is specified as @code{gnatelim} arguments, it
+treats these files as a complete set of sources making up a program to
+analyse, and analyses only these sources.
-To create a bind file for @code{gnatelim}, run @code{gnatbind} for
-the main subprogram. @code{gnatelim} can work with both Ada and C
-bind files; when both are present, it uses the Ada bind file.
-The following commands will build the program and create the bind file:
+After a full successful build of the main subprogram @code{gnatelim} can be
+called without specifying sources to analyse, in this case it computes
+the source closure of the main unit from the @file{ALI} files.
+
+The following command will create the set of @file{ALI} files needed for
+@code{gnatelim}:
@smallexample
$ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^
-$ gnatbind main_prog
@end smallexample
-Note that @code{gnatelim} needs neither object nor ALI files.
+Note that @code{gnatelim} does not need object files.
@node Running gnatelim
@subsection Running @code{gnatelim}
@code{gnatelim} has the following command-line interface:
@smallexample
-$ gnatelim @ovar{options} name
+$ gnatelim [@var{switches}] ^-main^?MAIN^=@var{main_unit_name} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
-@code{name} should be a name of a source file that contains the main subprogram
-of a program (partition).
+@var{main_unit_name} should be a name of a source file that contains the main
+subprogram of a program (partition).
+
+Each @var{filename} is the name (including the extension) of a source
+file to process. ``Wildcards'' are allowed, and
+the file name may contain path information.
+
+@samp{@var{gcc_switches}} is a list of switches for
+@command{gcc}. They will be passed on to all compiler invocations made by
+@command{gnatelim} to generate the ASIS trees. Here you can provide
+@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
+use the @option{-gnatec} switch to set the configuration file,
+use the @option{-gnat05} switch if sources should be compiled in
+Ada 2005 mode etc.
@code{gnatelim} has the following switches:
@table @option
@c !sort!
+@item ^-files^/FILES^=@var{filename}
+@cindex @option{^-files^/FILES^} (@code{gnatelim})
+Take the argument source files from the specified file. This file should be an
+ordinary text file containing file names separated by spaces or
+line breaks. You can use this switch more than once in the same call to
+@command{gnatelim}. You also can combine this switch with
+an explicit list of files.
+
+@item ^-log^/LOG^
+@cindex @option{^-log^/LOG^} (@command{gnatelim})
+Duplicate all the output sent to @file{stderr} into a log file. The log file
+is named @file{gnatelim.log} and is located in the current directory.
+
+@item ^-log^/LOGFILE^=@var{filename}
+@cindex @option{^-log^/LOGFILE^} (@command{gnatelim})
+Duplicate all the output sent to @file{stderr} into a specified log file.
+
+@cindex @option{^--no-elim-dispatch^/NO_DISPATCH^} (@command{gnatelim})
+@item ^--no-elim-dispatch^/NO_DISPATCH^
+Do not generate pragmas for dispatching operations.
+
+@cindex @option{^-o^/OUTPUT^} (@command{gnatelim})
+@item ^-o^/OUTPUT^=@var{report_file}
+Put @command{gnatelim} output into a specified file. If this file already exists,
+it is overridden. If this switch is not used, @command{gnatelim} outputs its results
+into @file{stderr}
+
@item ^-q^/QUIET^
@cindex @option{^-q^/QUIET^} (@command{gnatelim})
Quiet mode: by default @code{gnatelim} outputs to the standard error
stream the number of program units left to be processed. This option turns
this trace off.
+@cindex @option{^-t^/TIME^} (@command{gnatelim})
+@item ^-t^/TIME^
+Print out execution time.
+
@item ^-v^/VERBOSE^
@cindex @option{^-v^/VERBOSE^} (@command{gnatelim})
Verbose mode: @code{gnatelim} version information is printed as Ada
program units left @code{gnatelim} will output the name of the current unit
being processed.
-@item ^-a^/ALL^
-@cindex @option{^-a^/ALL^} (@command{gnatelim})
-Also look for subprograms from the GNAT run time that can be eliminated. Note
-that when @file{gnat.adc} is produced using this switch, the entire program
-must be recompiled with switch @option{^-a^/ALL_FILES^} to @command{gnatmake}.
-
-@item ^-I^/INCLUDE_DIRS=^@var{dir}
-@cindex @option{^-I^/INCLUDE_DIRS^} (@command{gnatelim})
-When looking for source files also look in directory @var{dir}. Specifying
-@option{^-I-^/INCLUDE_DIRS=-^} instructs @code{gnatelim} not to look for
-sources in the current directory.
-
-@item ^-b^/BIND_FILE=^@var{bind_file}
-@cindex @option{^-b^/BIND_FILE^} (@command{gnatelim})
-Specifies @var{bind_file} as the bind file to process. If not set, the name
-of the bind file is computed from the full expanded Ada name
-of a main subprogram.
-
-@item ^-C^/CONFIG_FILE=^@var{config_file}
-@cindex @option{^-C^/CONFIG_FILE^} (@command{gnatelim})
-Specifies a file @var{config_file} that contains configuration pragmas. The
-file must be specified with full path.
-
-@item ^--GCC^/COMPILER^=@var{compiler_name}
-@cindex @option{^-GCC^/COMPILER^} (@command{gnatelim})
-Instructs @code{gnatelim} to use specific @command{gcc} compiler instead of one
-available on the path.
-
-@item ^--GNATMAKE^/GNATMAKE^=@var{gnatmake_name}
-@cindex @option{^--GNATMAKE^/GNATMAKE^} (@command{gnatelim})
-Instructs @code{gnatelim} to use specific @command{gnatmake} instead of one
-available on the path.
+@item ^-wq^/WARNINGS=QUIET^
+@cindex @option{^-wq^/WARNINGS=QUIET^} (@command{gnatelim})
+Quet warning mode - some warnings are suppressed. In particular warnings that
+indicate that the analysed set of sources is incomplete to make up a
+partition and that some subprogram bodies are missing are not generated.
@end table
-@noindent
-@code{gnatelim} sends its output to the standard output stream, and all the
-tracing and debug information is sent to the standard error stream.
-In order to produce a proper GNAT configuration file
-@file{gnat.adc}, redirection must be used:
-
-@smallexample
-@ifset vms
-$ PIPE GNAT ELIM MAIN_PROG.ADB > GNAT.ADC
-@end ifset
-@ifclear vms
-$ gnatelim main_prog.adb > gnat.adc
-@end ifclear
-@end smallexample
-
-@ifclear vms
-@noindent
-or
-
-@smallexample
-$ gnatelim main_prog.adb >> gnat.adc
-@end smallexample
+@node Processing Precompiled Libraries
+@subsection Processing Precompiled Libraries
@noindent
-in order to append the @code{gnatelim} output to the existing contents of
-@file{gnat.adc}.
-@end ifclear
+If some program uses a precompiled Ada library, it can be processed by
+@code{gnatelim} in a usual way. @code{gnatelim} will newer generate an
+Eliminate pragma for a subprogram if the body of this subprogram has not
+been analysed, this is a typical case for subprograms from precompiled
+libraries. Switch @option{^-wq^/WARNINGS=QUIET^} may be used to suppress
+warnings about missing source files and non-analyzed subprogram bodies
+that can be generated when processing precompiled Ada libraries.
@node Correcting the List of Eliminate Pragmas
@subsection Correcting the List of Eliminate Pragmas
compiler will generate an error message of the form:
@smallexample
-file.adb:106:07: cannot call eliminated subprogram "My_Prog"
+main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5
@end smallexample
@noindent
You will need to manually remove the wrong @code{Eliminate} pragmas from
-the @file{gnat.adc} file. You should recompile your program
-from scratch after that, because you need a consistent @file{gnat.adc} file
-during the entire compilation.
+the configuration file indicated in the error message. You should recompile
+your program from scratch after that, because you need a consistent
+configuration file(s) during the entire compilation.
@node Making Your Executables Smaller
@subsection Making Your Executables Smaller
@noindent
In order to get a smaller executable for your program you now have to
-recompile the program completely with the new @file{gnat.adc} file
-created by @code{gnatelim} in your current directory:
+recompile the program completely with the configuration file containing
+pragmas Eliminate generated by gnatelim. If these pragmas are placed in
+@file{gnat.adc} file located in your current directory, just do:
@smallexample
$ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^
Be aware that the set of @code{Eliminate} pragmas is specific to each
program. It is not recommended to merge sets of @code{Eliminate}
-pragmas created for different programs in one @file{gnat.adc} file.
+pragmas created for different programs in one configuration file.
@node Summary of the gnatelim Usage Cycle
-@subsection Summary of the gnatelim Usage Cycle
+@subsection Summary of the @code{gnatelim} Usage Cycle
@noindent
Here is a quick summary of the steps to be taken in order to reduce
@enumerate
@item
-Produce a bind file
+Create a complete set of @file{ALI} files (if the program has not been
+built already)
@smallexample
$ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^
-$ gnatbind main_prog
@end smallexample
@item
-Generate a list of @code{Eliminate} pragmas
+Generate a list of @code{Eliminate} pragmas in default configuration file
+@file{gnat.adc} in the current directory
@smallexample
@ifset vms
$ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC
The @code{gnatchop} command has the form:
@smallexample
+@c $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
+@c @ovar{directory}
+@c Expanding @ovar macro inline (explanation in macro def comments)
$ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
- @ovar{directory}
+ @r{[}@var{directory}@r{]}
@end smallexample
@noindent
Ada_95
Ada_05
Ada_2005
+ Ada_12
+ Ada_2012
Assertion_Policy
+ Assume_No_Invalid_Values
C_Pass_By_Copy
Check_Name
Check_Policy
Compile_Time_Warning
Compiler_Unit
Component_Alignment
+ Convention_Identifier
Debug_Policy
Detect_Blocking
Discard_Names
Elaboration_Checks
Eliminate
Extend_System
+ Extensions_Allowed
External_Name_Casing
Fast_Math
Favor_Top_Level
Restrictions
Restrictions_Warnings
Reviewable
+ Short_Circuit_And_Or
Source_File_Name
Source_File_Name_Project
Style_Checks
The usual form of the @code{gnatname} command is
@smallexample
-$ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}
- @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]}
+@c $ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}
+@c @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatname @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]}
+ @r{[}--and @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]}@r{]}
@end smallexample
@noindent
@noindent
One or several Naming Patterns may be given as arguments to @code{gnatname}.
-Each Naming Pattern is enclosed between double quotes.
+Each Naming Pattern is enclosed between double quotes (or single
+quotes on Windows).
A Naming Pattern is a regular expression similar to the wildcard patterns
used in file names by the Unix shells or the DOS prompt.
@c *****************************************
@c * G N A T P r o j e c t M a n a g e r *
@c *****************************************
-@node GNAT Project Manager
-@chapter GNAT Project Manager
-@menu
-* Introduction::
-* Examples of Project Files::
-* Project File Syntax::
-* Objects and Sources in Project Files::
-* Importing Projects::
-* Project Extension::
-* Project Hierarchy Extension::
-* External References in Project Files::
-* Packages in Project Files::
-* Variables from Imported Projects::
-* Naming Schemes::
-* Library Projects::
-* Stand-alone Library Projects::
-* Switches Related to Project Files::
-* Tools Supporting Project Files::
-* An Extended Example::
-* Project File Complete Syntax::
-@end menu
+@c ------ macros for projects.texi
+@c These macros are needed when building the gprbuild documentation, but
+@c should have no effect in the gnat user's guide
+
+@macro CODESAMPLE{TXT}
+@smallexample
+@group
+\TXT\
+@end group
+@end smallexample
+@end macro
-@c ****************
-@c * Introduction *
-@c ****************
+@macro PROJECTFILE{TXT}
+@CODESAMPLE{\TXT\}
+@end macro
-@node Introduction
-@section Introduction
+@c simulates a newline when in a @CODESAMPLE
+@macro NL{}
+@end macro
+@macro TIP{TXT}
+@quotation
@noindent
-This chapter describes GNAT's @emph{Project Manager}, a facility that allows
-you to manage complex builds involving a number of source files, directories,
-and compilation options for different system configurations. In particular,
-project files allow you to specify:
-@itemize @bullet
-@item
-The directory or set of directories containing the source files, and/or the
-names of the specific source files themselves
-@item
-The directory in which the compiler's output
-(@file{ALI} files, object files, tree files) is to be placed
-@item
-The directory in which the executable programs is to be placed
-@item
-^Switch^Switch^ settings for any of the project-enabled tools
-(@command{gnatmake}, compiler, binder, linker, @code{gnatls}, @code{gnatxref},
-@code{gnatfind}); you can apply these settings either globally or to individual
-compilation units.
-@item
-The source files containing the main subprogram(s) to be built
-@item
-The source programming language(s) (currently Ada and/or C)
-@item
-Source file naming conventions; you can specify these either globally or for
-individual compilation units
-@end itemize
-
-@menu
-* Project Files::
-@end menu
+\TXT\
+@end quotation
+@end macro
-@node Project Files
-@subsection Project Files
-
-@noindent
-Project files are written in a syntax close to that of Ada, using familiar
-notions such as packages, context clauses, declarations, default values,
-assignments, and inheritance. Finally, project files can be built
-hierarchically from other project files, simplifying complex system
-integration and project reuse.
-
-A @dfn{project} is a specific set of values for various compilation properties.
-The settings for a given project are described by means of
-a @dfn{project file}, which is a text file written in an Ada-like syntax.
-Property values in project files are either strings or lists of strings.
-Properties that are not explicitly set receive default values. A project
-file may interrogate the values of @dfn{external variables} (user-defined
-command-line switches or environment variables), and it may specify property
-settings conditionally, based on the value of such variables.
-
-In simple cases, a project's source files depend only on other source files
-in the same project, or on the predefined libraries. (@emph{Dependence} is
-used in
-the Ada technical sense; as in one Ada unit @code{with}ing another.) However,
-the Project Manager also allows more sophisticated arrangements,
-where the source files in one project depend on source files in other
-projects:
-@itemize @bullet
-@item
-One project can @emph{import} other projects containing needed source files.
-@item
-You can organize GNAT projects in a hierarchy: a @emph{child} project
-can extend a @emph{parent} project, inheriting the parent's source files and
-optionally overriding any of them with alternative versions
-@end itemize
+@macro TIPHTML{TXT}
+\TXT\
+@end macro
+@macro IMPORTANT{TXT}
+@quotation
@noindent
-More generally, the Project Manager lets you structure large development
-efforts into hierarchical subsystems, where build decisions are delegated
-to the subsystem level, and thus different compilation environments
-(^switch^switch^ settings) used for different subsystems.
+\TXT\
+@end quotation
-The Project Manager is invoked through the
-@option{^-P^/PROJECT_FILE=^@emph{projectfile}}
-switch to @command{gnatmake} or to the @command{^gnat^GNAT^} front driver.
-@ifclear vms
-There may be zero, one or more spaces between @option{-P} and
-@option{@emph{projectfile}}.
-@end ifclear
-If you want to define (on the command line) an external variable that is
-queried by the project file, you must use the
-@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch.
-The Project Manager parses and interprets the project file, and drives the
-invoked tool based on the project settings.
-
-The Project Manager supports a wide range of development strategies,
-for systems of all sizes. Here are some typical practices that are
-easily handled:
-@itemize @bullet
-@item
-Using a common set of source files, but generating object files in different
-directories via different ^switch^switch^ settings
-@item
-Using a mostly-shared set of source files, but with different versions of
-some unit or units
-@end itemize
+@end macro
+@macro NOTE{TXT}
+@quotation
@noindent
-The destination of an executable can be controlled inside a project file
-using the @option{^-o^-o^}
-^switch^switch^.
-In the absence of such a ^switch^switch^ either inside
-the project file or on the command line, any executable files generated by
-@command{gnatmake} are placed in the directory @code{Exec_Dir} specified
-in the project file. If no @code{Exec_Dir} is specified, they will be placed
-in the object directory of the project.
+\TXT\
+@end quotation
+@end macro
-You can use project files to achieve some of the effects of a source
-versioning system (for example, defining separate projects for
-the different sets of sources that comprise different releases) but the
-Project Manager is independent of any source configuration management tools
-that might be used by the developers.
+@include projects.texi
-The next section introduces the main features of GNAT's project facility
-through a sequence of examples; subsequent sections will present the syntax
-and semantics in more detail. A more formal description of the project
-facility appears in @ref{Project File Reference,,, gnat_rm, GNAT
-Reference Manual}.
+@c *****************************************
+@c * Cross-referencing tools
+@c *****************************************
-@c *****************************
-@c * Examples of Project Files *
-@c *****************************
+@node The Cross-Referencing Tools gnatxref and gnatfind
+@chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
+@findex gnatxref
+@findex gnatfind
-@node Examples of Project Files
-@section Examples of Project Files
@noindent
-This section illustrates some of the typical uses of project files and
-explains their basic structure and behavior.
+The compiler generates cross-referencing information (unless
+you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files.
+This information indicates where in the source each entity is declared and
+referenced. Note that entities in package Standard are not included, but
+entities in all other predefined units are included in the output.
-@menu
-* Common Sources with Different ^Switches^Switches^ and Directories::
-* Using External Variables::
-* Importing Other Projects::
-* Extending a Project::
-@end menu
+Before using any of these two tools, you need to compile successfully your
+application, so that GNAT gets a chance to generate the cross-referencing
+information.
+
+The two tools @code{gnatxref} and @code{gnatfind} take advantage of this
+information to provide the user with the capability to easily locate the
+declaration and references to an entity. These tools are quite similar,
+the difference being that @code{gnatfind} is intended for locating
+definitions and/or references to a specified entity or entities, whereas
+@code{gnatxref} is oriented to generating a full report of all
+cross-references.
+
+To use these tools, you must not compile your application using the
+@option{-gnatx} switch on the @command{gnatmake} command line
+(@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing
+information will not be generated.
-@node Common Sources with Different ^Switches^Switches^ and Directories
-@subsection Common Sources with Different ^Switches^Switches^ and Directories
+Note: to invoke @code{gnatxref} or @code{gnatfind} with a project file,
+use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}).
@menu
-* Source Files::
-* Specifying the Object Directory::
-* Specifying the Exec Directory::
-* Project File Packages::
-* Specifying ^Switch^Switch^ Settings::
-* Main Subprograms::
-* Executable File Names::
-* Source File Naming Conventions::
-* Source Language(s)::
+* Switches for gnatxref::
+* Switches for gnatfind::
+* Project Files for gnatxref and gnatfind::
+* Regular Expressions in gnatfind and gnatxref::
+* Examples of gnatxref Usage::
+* Examples of gnatfind Usage::
@end menu
-@noindent
-Suppose that the Ada source files @file{pack.ads}, @file{pack.adb}, and
-@file{proc.adb} are in the @file{/common} directory. The file
-@file{proc.adb} contains an Ada main subprogram @code{Proc} that @code{with}s
-package @code{Pack}. We want to compile these source files under two sets
-of ^switches^switches^:
-@itemize @bullet
-@item
-When debugging, we want to pass the @option{-g} switch to @command{gnatmake},
-and the @option{^-gnata^-gnata^},
-@option{^-gnato^-gnato^},
-and @option{^-gnatE^-gnatE^} switches to the
-compiler; the compiler's output is to appear in @file{/common/debug}
-@item
-When preparing a release version, we want to pass the @option{^-O2^O2^} switch
-to the compiler; the compiler's output is to appear in @file{/common/release}
-@end itemize
+@node Switches for gnatxref
+@section @code{gnatxref} Switches
@noindent
-The GNAT project files shown below, respectively @file{debug.gpr} and
-@file{release.gpr} in the @file{/common} directory, achieve these effects.
-
-Schematically:
+The command invocation for @code{gnatxref} is:
@smallexample
-@group
-^/common^[COMMON]^
- debug.gpr
- release.gpr
- pack.ads
- pack.adb
- proc.adb
-@end group
-@group
-^/common/debug^[COMMON.DEBUG]^
- proc.ali, proc.o
- pack.ali, pack.o
-@end group
-@group
-^/common/release^[COMMON.RELEASE]^
- proc.ali, proc.o
- pack.ali, pack.o
-@end group
-@end smallexample
-Here are the corresponding project files:
-
-@smallexample @c projectfile
-@group
-project Debug is
- for Object_Dir use "debug";
- for Main use ("proc");
-
- package Builder is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-g^-g^");
- for Executable ("proc.adb") use "proc1";
- end Builder;
-@end group
-
-@group
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("-fstack-check",
- "^-gnata^-gnata^",
- "^-gnato^-gnato^",
- "^-gnatE^-gnatE^");
- end Compiler;
-end Debug;
-@end group
-@end smallexample
-
-@smallexample @c projectfile
-@group
-project Release is
- for Object_Dir use "release";
- for Exec_Dir use ".";
- for Main use ("proc");
-
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-O2^-O2^");
- end Compiler;
-end Release;
-@end group
+@c $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatxref @r{[}@var{switches}@r{]} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
@end smallexample
@noindent
-The name of the project defined by @file{debug.gpr} is @code{"Debug"} (case
-insensitive), and analogously the project defined by @file{release.gpr} is
-@code{"Release"}. For consistency the file should have the same name as the
-project, and the project file's extension should be @code{"gpr"}. These
-conventions are not required, but a warning is issued if they are not followed.
+where
-If the current directory is @file{^/temp^[TEMP]^}, then the command
-@smallexample
-gnatmake ^-P/common/debug.gpr^/PROJECT_FILE=[COMMON]DEBUG^
-@end smallexample
-
-@noindent
-generates object and ALI files in @file{^/common/debug^[COMMON.DEBUG]^},
-as well as the @code{^proc1^PROC1.EXE^} executable,
-using the ^switch^switch^ settings defined in the project file.
-
-Likewise, the command
-@smallexample
-gnatmake ^-P/common/release.gpr^/PROJECT_FILE=[COMMON]RELEASE^
-@end smallexample
-
-@noindent
-generates object and ALI files in @file{^/common/release^[COMMON.RELEASE]^},
-and the @code{^proc^PROC.EXE^}
-executable in @file{^/common^[COMMON]^},
-using the ^switch^switch^ settings from the project file.
+@table @var
+@item sourcefile1
+@itemx sourcefile2
+identifies the source files for which a report is to be generated. The
+``with''ed units will be processed too. You must provide at least one file.
-@node Source Files
-@unnumberedsubsubsec Source Files
+These file names are considered to be regular expressions, so for instance
+specifying @file{source*.adb} is the same as giving every file in the current
+directory whose name starts with @file{source} and whose extension is
+@file{adb}.
-@noindent
-If a project file does not explicitly specify a set of source directories or
-a set of source files, then by default the project's source files are the
-Ada source files in the project file directory. Thus @file{pack.ads},
-@file{pack.adb}, and @file{proc.adb} are the source files for both projects.
+You shouldn't specify any directory name, just base names. @command{gnatxref}
+and @command{gnatfind} will be able to locate these files by themselves using
+the source path. If you specify directories, no result is produced.
-@node Specifying the Object Directory
-@unnumberedsubsubsec Specifying the Object Directory
+@end table
@noindent
-Several project properties are modeled by Ada-style @emph{attributes};
-a property is defined by supplying the equivalent of an Ada attribute
-definition clause in the project file.
-A project's object directory is another such a property; the corresponding
-attribute is @code{Object_Dir}, and its value is also a string expression,
-specified either as absolute or relative. In the later case,
-it is relative to the project file directory. Thus the compiler's
-output is directed to @file{^/common/debug^[COMMON.DEBUG]^}
-(for the @code{Debug} project)
-and to @file{^/common/release^[COMMON.RELEASE]^}
-(for the @code{Release} project).
-If @code{Object_Dir} is not specified, then the default is the project file
-directory itself.
-
-@node Specifying the Exec Directory
-@unnumberedsubsubsec Specifying the Exec Directory
+The switches can be:
+@table @option
+@c !sort!
+@item --version
+@cindex @option{--version} @command{gnatxref}
+Display Copyright and version, then exit disregarding all other options.
-@noindent
-A project's exec directory is another property; the corresponding
-attribute is @code{Exec_Dir}, and its value is also a string expression,
-either specified as relative or absolute. If @code{Exec_Dir} is not specified,
-then the default is the object directory (which may also be the project file
-directory if attribute @code{Object_Dir} is not specified). Thus the executable
-is placed in @file{^/common/debug^[COMMON.DEBUG]^}
-for the @code{Debug} project (attribute @code{Exec_Dir} not specified)
-and in @file{^/common^[COMMON]^} for the @code{Release} project.
+@item --help
+@cindex @option{--help} @command{gnatxref}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
-@node Project File Packages
-@unnumberedsubsubsec Project File Packages
+@item ^-a^/ALL_FILES^
+@cindex @option{^-a^/ALL_FILES^} (@command{gnatxref})
+If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
+the read-only files found in the library search path. Otherwise, these files
+will be ignored. This option can be used to protect Gnat sources or your own
+libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
+much faster, and their output much smaller. Read-only here refers to access
+or permissions status in the file system for the current user.
-@noindent
-A GNAT tool that is integrated with the Project Manager is modeled by a
-corresponding package in the project file. In the example above,
-The @code{Debug} project defines the packages @code{Builder}
-(for @command{gnatmake}) and @code{Compiler};
-the @code{Release} project defines only the @code{Compiler} package.
+@item -aIDIR
+@cindex @option{-aIDIR} (@command{gnatxref})
+When looking for source files also look in directory DIR. The order in which
+source file search is undertaken is the same as for @command{gnatmake}.
-The Ada-like package syntax is not to be taken literally. Although packages in
-project files bear a surface resemblance to packages in Ada source code, the
-notation is simply a way to convey a grouping of properties for a named
-entity. Indeed, the package names permitted in project files are restricted
-to a predefined set, corresponding to the project-aware tools, and the contents
-of packages are limited to a small set of constructs.
-The packages in the example above contain attribute definitions.
+@item -aODIR
+@cindex @option{-aODIR} (@command{gnatxref})
+When searching for library and object files, look in directory
+DIR. The order in which library files are searched is the same as for
+@command{gnatmake}.
-@node Specifying ^Switch^Switch^ Settings
-@unnumberedsubsubsec Specifying ^Switch^Switch^ Settings
+@item -nostdinc
+@cindex @option{-nostdinc} (@command{gnatxref})
+Do not look for sources in the system default directory.
-@noindent
-^Switch^Switch^ settings for a project-aware tool can be specified through
-attributes in the package that corresponds to the tool.
-The example above illustrates one of the relevant attributes,
-@code{^Default_Switches^Default_Switches^}, which is defined in packages
-in both project files.
-Unlike simple attributes like @code{Source_Dirs},
-@code{^Default_Switches^Default_Switches^} is
-known as an @emph{associative array}. When you define this attribute, you must
-supply an ``index'' (a literal string), and the effect of the attribute
-definition is to set the value of the array at the specified index.
-For the @code{^Default_Switches^Default_Switches^} attribute,
-the index is a programming language (in our case, Ada),
-and the value specified (after @code{use}) must be a list
-of string expressions.
+@item -nostdlib
+@cindex @option{-nostdlib} (@command{gnatxref})
+Do not look for library files in the system default directory.
-The attributes permitted in project files are restricted to a predefined set.
-Some may appear at project level, others in packages.
-For any attribute that is an associative array, the index must always be a
-literal string, but the restrictions on this string (e.g., a file name or a
-language name) depend on the individual attribute.
-Also depending on the attribute, its specified value will need to be either a
-string or a string list.
-
-In the @code{Debug} project, we set the switches for two tools,
-@command{gnatmake} and the compiler, and thus we include the two corresponding
-packages; each package defines the @code{^Default_Switches^Default_Switches^}
-attribute with index @code{"Ada"}.
-Note that the package corresponding to
-@command{gnatmake} is named @code{Builder}. The @code{Release} project is
-similar, but only includes the @code{Compiler} package.
-
-In project @code{Debug} above, the ^switches^switches^ starting with
-@option{-gnat} that are specified in package @code{Compiler}
-could have been placed in package @code{Builder}, since @command{gnatmake}
-transmits all such ^switches^switches^ to the compiler.
-
-@node Main Subprograms
-@unnumberedsubsubsec Main Subprograms
-
-@noindent
-One of the specifiable properties of a project is a list of files that contain
-main subprograms. This property is captured in the @code{Main} attribute,
-whose value is a list of strings. If a project defines the @code{Main}
-attribute, it is not necessary to identify the main subprogram(s) when
-invoking @command{gnatmake} (@pxref{gnatmake and Project Files}).
-
-@node Executable File Names
-@unnumberedsubsubsec Executable File Names
-
-@noindent
-By default, the executable file name corresponding to a main source is
-deduced from the main source file name. Through the attributes
-@code{Executable} and @code{Executable_Suffix} of package @code{Builder},
-it is possible to change this default.
-In project @code{Debug} above, the executable file name
-for main source @file{^proc.adb^PROC.ADB^} is
-@file{^proc1^PROC1.EXE^}.
-Attribute @code{Executable_Suffix}, when specified, may change the suffix
-of the executable files, when no attribute @code{Executable} applies:
-its value replace the platform-specific executable suffix.
-Attributes @code{Executable} and @code{Executable_Suffix} are the only ways to
-specify a non-default executable file name when several mains are built at once
-in a single @command{gnatmake} command.
-
-@node Source File Naming Conventions
-@unnumberedsubsubsec Source File Naming Conventions
-
-@noindent
-Since the project files above do not specify any source file naming
-conventions, the GNAT defaults are used. The mechanism for defining source
-file naming conventions -- a package named @code{Naming} --
-is described below (@pxref{Naming Schemes}).
-
-@node Source Language(s)
-@unnumberedsubsubsec Source Language(s)
-
-@noindent
-Since the project files do not specify a @code{Languages} attribute, by
-default the GNAT tools assume that the language of the project file is Ada.
-More generally, a project can comprise source files
-in Ada, C, and/or other languages.
-
-@node Using External Variables
-@subsection Using External Variables
-
-@noindent
-Instead of supplying different project files for debug and release, we can
-define a single project file that queries an external variable (set either
-on the command line or via an ^environment variable^logical name^) in order to
-conditionally define the appropriate settings. Again, assume that the
-source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are
-located in directory @file{^/common^[COMMON]^}. The following project file,
-@file{build.gpr}, queries the external variable named @code{STYLE} and
-defines an object directory and ^switch^switch^ settings based on whether
-the value is @code{"deb"} (debug) or @code{"rel"} (release), and where
-the default is @code{"deb"}.
+@item --ext=@var{extension}
+@cindex @option{--ext} (@command{gnatxref})
+Specify an alternate ali file extension. The default is @code{ali} and other
+extensions (e.g. @code{sli} for SPARK library files) may be specified via this
+switch. Note that if this switch overrides the default, which means that only
+the new extension will be considered.
-@smallexample @c projectfile
-@group
-project Build is
- for Main use ("proc");
+@item --RTS=@var{rts-path}
+@cindex @option{--RTS} (@command{gnatxref})
+Specifies the default location of the runtime library. Same meaning as the
+equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
- type Style_Type is ("deb", "rel");
- Style : Style_Type := external ("STYLE", "deb");
+@item ^-d^/DERIVED_TYPES^
+@cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref})
+If this switch is set @code{gnatxref} will output the parent type
+reference for each matching derived types.
- case Style is
- when "deb" =>
- for Object_Dir use "debug";
+@item ^-f^/FULL_PATHNAME^
+@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref})
+If this switch is set, the output file names will be preceded by their
+directory (if the file was found in the search path). If this switch is
+not set, the directory will not be printed.
- when "rel" =>
- for Object_Dir use "release";
- for Exec_Dir use ".";
- end case;
-@end group
+@item ^-g^/IGNORE_LOCALS^
+@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref})
+If this switch is set, information is output only for library-level
+entities, ignoring local entities. The use of this switch may accelerate
+@code{gnatfind} and @code{gnatxref}.
-@group
- package Builder is
-
- case Style is
- when "deb" =>
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-g^-g^");
- for Executable ("proc") use "proc1";
- when others =>
- null;
- end case;
-
- end Builder;
-@end group
+@item -IDIR
+@cindex @option{-IDIR} (@command{gnatxref})
+Equivalent to @samp{-aODIR -aIDIR}.
-@group
- package Compiler is
+@item -pFILE
+@cindex @option{-pFILE} (@command{gnatxref})
+Specify a project file to use @xref{GNAT Project Manager}.
+If you need to use the @file{.gpr}
+project files, you should use gnatxref through the GNAT driver
+(@command{gnat xref -Pproject}).
- case Style is
- when "deb" =>
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnata^-gnata^",
- "^-gnato^-gnato^",
- "^-gnatE^-gnatE^");
+By default, @code{gnatxref} and @code{gnatfind} will try to locate a
+project file in the current directory.
- when "rel" =>
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-O2^-O2^");
- end case;
+If a project file is either specified or found by the tools, then the content
+of the source directory and object directory lines are added as if they
+had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^}
+and @samp{^-aO^OBJECT_SEARCH^}.
+@item ^-u^/UNUSED^
+Output only unused symbols. This may be really useful if you give your
+main compilation unit on the command line, as @code{gnatxref} will then
+display every unused entity and 'with'ed package.
- end Compiler;
+@ifclear vms
+@item -v
+Instead of producing the default output, @code{gnatxref} will generate a
+@file{tags} file that can be used by vi. For examples how to use this
+feature, see @ref{Examples of gnatxref Usage}. The tags file is output
+to the standard output, thus you will have to redirect it to a file.
+@end ifclear
-end Build;
-@end group
-@end smallexample
+@end table
@noindent
-@code{Style_Type} is an example of a @emph{string type}, which is the project
-file analog of an Ada enumeration type but whose components are string literals
-rather than identifiers. @code{Style} is declared as a variable of this type.
-
-The form @code{external("STYLE", "deb")} is known as an
-@emph{external reference}; its first argument is the name of an
-@emph{external variable}, and the second argument is a default value to be
-used if the external variable doesn't exist. You can define an external
-variable on the command line via the @option{^-X^/EXTERNAL_REFERENCE^} switch,
-or you can use ^an environment variable^a logical name^
-as an external variable.
-
-Each @code{case} construct is expanded by the Project Manager based on the
-value of @code{Style}. Thus the command
-@ifclear vms
-@smallexample
-gnatmake -P/common/build.gpr -XSTYLE=deb
-@end smallexample
-@end ifclear
+All these switches may be in any order on the command line, and may even
+appear after the file names. They need not be separated by spaces, thus
+you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
+@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
-@ifset vms
-@smallexample
-gnatmake /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=deb
-@end smallexample
-@end ifset
+@node Switches for gnatfind
+@section @code{gnatfind} Switches
@noindent
-is equivalent to the @command{gnatmake} invocation using the project file
-@file{debug.gpr} in the earlier example. So is the command
+The command line for @code{gnatfind} is:
+
@smallexample
-gnatmake ^-P/common/build.gpr^/PROJECT_FILE=[COMMON]BUILD.GPR^
+@c $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
+@c @r{[}@var{file1} @var{file2} @dots{}]
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatfind @r{[}@var{switches}@r{]} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
+ @r{[}@var{file1} @var{file2} @dots{}@r{]}
@end smallexample
@noindent
-since @code{"deb"} is the default for @code{STYLE}.
+where
-Analogously,
+@table @var
+@item pattern
+An entity will be output only if it matches the regular expression found
+in @var{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}.
-@ifclear vms
-@smallexample
-gnatmake -P/common/build.gpr -XSTYLE=rel
-@end smallexample
-@end ifclear
+Omitting the pattern is equivalent to specifying @samp{*}, which
+will match any entity. Note that if you do not provide a pattern, you
+have to provide both a sourcefile and a line.
-@ifset vms
-@smallexample
-GNAT MAKE /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=rel
-@end smallexample
-@end ifset
+Entity names are given in Latin-1, with uppercase/lowercase equivalence
+for matching purposes. At the current time there is no support for
+8-bit codes other than Latin-1, or for wide characters in identifiers.
-@noindent
-is equivalent to the @command{gnatmake} invocation using the project file
-@file{release.gpr} in the earlier example.
+@item sourcefile
+@code{gnatfind} will look for references, bodies or declarations
+of symbols referenced in @file{@var{sourcefile}}, at line @var{line}
+and column @var{column}. See @ref{Examples of gnatfind Usage}
+for syntax examples.
-@node Importing Other Projects
-@subsection Importing Other Projects
-@cindex @code{ADA_PROJECT_PATH}
+@item line
+is a decimal integer identifying the line number containing
+the reference to the entity (or entities) to be located.
-@noindent
-A compilation unit in a source file in one project may depend on compilation
-units in source files in other projects. To compile this unit under
-control of a project file, the
-dependent project must @emph{import} the projects containing the needed source
-files.
-This effect is obtained using syntax similar to an Ada @code{with} clause,
-but where @code{with}ed entities are strings that denote project files.
+@item column
+is a decimal integer identifying the exact location on the
+line of the first character of the identifier for the
+entity reference. Columns are numbered from 1.
-As an example, suppose that the two projects @code{GUI_Proj} and
-@code{Comm_Proj} are defined in the project files @file{gui_proj.gpr} and
-@file{comm_proj.gpr} in directories @file{^/gui^[GUI]^}
-and @file{^/comm^[COMM]^}, respectively.
-Suppose that the source files for @code{GUI_Proj} are
-@file{gui.ads} and @file{gui.adb}, and that the source files for
-@code{Comm_Proj} are @file{comm.ads} and @file{comm.adb}, where each set of
-files is located in its respective project file directory. Schematically:
+@item file1 file2 @dots{}
+The search will be restricted to these source files. If none are given, then
+the search will be done for every library file in the search path.
+These file must appear only after the pattern or sourcefile.
-@smallexample
-@group
-^/gui^[GUI]^
- gui_proj.gpr
- gui.ads
- gui.adb
-@end group
+These file names are considered to be regular expressions, so for instance
+specifying @file{source*.adb} is the same as giving every file in the current
+directory whose name starts with @file{source} and whose extension is
+@file{adb}.
-@group
-^/comm^[COMM]^
- comm_proj.gpr
- comm.ads
- comm.adb
-@end group
-@end smallexample
+The location of the spec of the entity will always be displayed, even if it
+isn't in one of @file{@var{file1}}, @file{@var{file2}},@enddots{} The
+occurrences of the entity in the separate units of the ones given on the
+command line will also be displayed.
-@noindent
-We want to develop an application in directory @file{^/app^[APP]^} that
-@code{with} the packages @code{GUI} and @code{Comm}, using the properties of
-the corresponding project files (e.g.@: the ^switch^switch^ settings
-and object directory).
-Skeletal code for a main procedure might be something like the following:
+Note that if you specify at least one file in this part, @code{gnatfind} may
+sometimes not be able to find the body of the subprograms.
-@smallexample @c ada
-@group
-with GUI, Comm;
-procedure App_Main is
- @dots{}
-begin
- @dots{}
-end App_Main;
-@end group
-@end smallexample
+@end table
@noindent
-Here is a project file, @file{app_proj.gpr}, that achieves the desired
-effect:
-
-@smallexample @c projectfile
-@group
-with "/gui/gui_proj", "/comm/comm_proj";
-project App_Proj is
- for Main use ("app_main");
-end App_Proj;
-@end group
-@end smallexample
+At least one of 'sourcefile' or 'pattern' has to be present on
+the command line.
-@noindent
-Building an executable is achieved through the command:
-@smallexample
-gnatmake ^-P/app/app_proj^/PROJECT_FILE=[APP]APP_PROJ^
-@end smallexample
-@noindent
-which will generate the @code{^app_main^APP_MAIN.EXE^} executable
-in the directory where @file{app_proj.gpr} resides.
+The following switches are available:
+@table @option
+@c !sort!
-If an imported project file uses the standard extension (@code{^gpr^GPR^}) then
-(as illustrated above) the @code{with} clause can omit the extension.
+@cindex @option{--version} @command{gnatfind}
+Display Copyright and version, then exit disregarding all other options.
-Our example specified an absolute path for each imported project file.
-Alternatively, the directory name of an imported object can be omitted
-if either
-@itemize @bullet
-@item
-The imported project file is in the same directory as the importing project
-file, or
-@item
-You have defined ^an environment variable^a logical name^
-that includes the directory containing
-the needed project file. The syntax of @code{ADA_PROJECT_PATH} is the same as
-the syntax of @code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH}: a list of
-directory names separated by colons (semicolons on Windows).
-@end itemize
+@item --help
+@cindex @option{--help} @command{gnatfind}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
-@noindent
-Thus, if we define @code{ADA_PROJECT_PATH} to include @file{^/gui^[GUI]^} and
-@file{^/comm^[COMM]^}, then our project file @file{app_proj.gpr} can be written
-as follows:
+@item ^-a^/ALL_FILES^
+@cindex @option{^-a^/ALL_FILES^} (@command{gnatfind})
+If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
+the read-only files found in the library search path. Otherwise, these files
+will be ignored. This option can be used to protect Gnat sources or your own
+libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
+much faster, and their output much smaller. Read-only here refers to access
+or permission status in the file system for the current user.
-@smallexample @c projectfile
-@group
-with "gui_proj", "comm_proj";
-project App_Proj is
- for Main use ("app_main");
-end App_Proj;
-@end group
-@end smallexample
+@item -aIDIR
+@cindex @option{-aIDIR} (@command{gnatfind})
+When looking for source files also look in directory DIR. The order in which
+source file search is undertaken is the same as for @command{gnatmake}.
-@noindent
-Importing other projects can create ambiguities.
-For example, the same unit might be present in different imported projects, or
-it might be present in both the importing project and in an imported project.
-Both of these conditions are errors. Note that in the current version of
-the Project Manager, it is illegal to have an ambiguous unit even if the
-unit is never referenced by the importing project. This restriction may be
-relaxed in a future release.
+@item -aODIR
+@cindex @option{-aODIR} (@command{gnatfind})
+When searching for library and object files, look in directory
+DIR. The order in which library files are searched is the same as for
+@command{gnatmake}.
-@node Extending a Project
-@subsection Extending a Project
+@item -nostdinc
+@cindex @option{-nostdinc} (@command{gnatfind})
+Do not look for sources in the system default directory.
-@noindent
-In large software systems it is common to have multiple
-implementations of a common interface; in Ada terms, multiple versions of a
-package body for the same spec. For example, one implementation
-might be safe for use in tasking programs, while another might only be used
-in sequential applications. This can be modeled in GNAT using the concept
-of @emph{project extension}. If one project (the ``child'') @emph{extends}
-another project (the ``parent'') then by default all source files of the
-parent project are inherited by the child, but the child project can
-override any of the parent's source files with new versions, and can also
-add new files. This facility is the project analog of a type extension in
-Object-Oriented Programming. Project hierarchies are permitted (a child
-project may be the parent of yet another project), and a project that
-inherits one project can also import other projects.
+@item -nostdlib
+@cindex @option{-nostdlib} (@command{gnatfind})
+Do not look for library files in the system default directory.
-As an example, suppose that directory @file{^/seq^[SEQ]^} contains the project
-file @file{seq_proj.gpr} as well as the source files @file{pack.ads},
-@file{pack.adb}, and @file{proc.adb}:
+@item --ext=@var{extension}
+@cindex @option{--ext} (@command{gnatfind})
+Specify an alternate ali file extension. The default is @code{ali} and other
+extensions (e.g. @code{sli} for SPARK library files) may be specified via this
+switch. Note that if this switch overrides the default, which means that only
+the new extension will be considered.
-@smallexample
-@group
-^/seq^[SEQ]^
- pack.ads
- pack.adb
- proc.adb
- seq_proj.gpr
-@end group
-@end smallexample
+@item --RTS=@var{rts-path}
+@cindex @option{--RTS} (@command{gnatfind})
+Specifies the default location of the runtime library. Same meaning as the
+equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
-@noindent
-Note that the project file can simply be empty (that is, no attribute or
-package is defined):
-
-@smallexample @c projectfile
-@group
-project Seq_Proj is
-end Seq_Proj;
-@end group
-@end smallexample
-
-@noindent
-implying that its source files are all the Ada source files in the project
-directory.
-
-Suppose we want to supply an alternate version of @file{pack.adb}, in
-directory @file{^/tasking^[TASKING]^}, but use the existing versions of
-@file{pack.ads} and @file{proc.adb}. We can define a project
-@code{Tasking_Proj} that inherits @code{Seq_Proj}:
-
-@smallexample
-@group
-^/tasking^[TASKING]^
- pack.adb
- tasking_proj.gpr
-@end group
-
-@group
-project Tasking_Proj extends "/seq/seq_proj" is
-end Tasking_Proj;
-@end group
-@end smallexample
-
-@noindent
-The version of @file{pack.adb} used in a build depends on which project file
-is specified.
-
-Note that we could have obtained the desired behavior using project import
-rather than project inheritance; a @code{base} project would contain the
-sources for @file{pack.ads} and @file{proc.adb}, a sequential project would
-import @code{base} and add @file{pack.adb}, and likewise a tasking project
-would import @code{base} and add a different version of @file{pack.adb}. The
-choice depends on whether other sources in the original project need to be
-overridden. If they do, then project extension is necessary, otherwise,
-importing is sufficient.
+@item ^-d^/DERIVED_TYPE_INFORMATION^
+@cindex @option{^-d^/DERIVED_TYPE_INFORMATION^} (@code{gnatfind})
+If this switch is set, then @code{gnatfind} will output the parent type
+reference for each matching derived types.
-@noindent
-In a project file that extends another project file, it is possible to
-indicate that an inherited source is not part of the sources of the extending
-project. This is necessary sometimes when a package spec has been overloaded
-and no longer requires a body: in this case, it is necessary to indicate that
-the inherited body is not part of the sources of the project, otherwise there
-will be a compilation error when compiling the spec.
+@item ^-e^/EXPRESSIONS^
+@cindex @option{^-e^/EXPRESSIONS^} (@command{gnatfind})
+By default, @code{gnatfind} accept the simple regular expression set for
+@samp{pattern}. If this switch is set, then the pattern will be
+considered as full Unix-style regular expression.
-For that purpose, the attribute @code{Excluded_Source_Files} is used.
-Its value is a string list: a list of file names. It is also possible to use
-attribute @code{Excluded_Source_List_File}. Its value is a single string:
-the file name of a text file containing a list of file names, one per line.
+@item ^-f^/FULL_PATHNAME^
+@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatfind})
+If this switch is set, the output file names will be preceded by their
+directory (if the file was found in the search path). If this switch is
+not set, the directory will not be printed.
-@smallexample @c @projectfile
-project B extends "a" is
- for Source_Files use ("pkg.ads");
- -- New spec of Pkg does not need a completion
- for Excluded_Source_Files use ("pkg.adb");
-end B;
-@end smallexample
+@item ^-g^/IGNORE_LOCALS^
+@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatfind})
+If this switch is set, information is output only for library-level
+entities, ignoring local entities. The use of this switch may accelerate
+@code{gnatfind} and @code{gnatxref}.
-Attribute @code{Excluded_Source_Files} may also be used to check if a source
-is still needed: if it is possible to build using @command{gnatmake} when such
-a source is put in attribute @code{Excluded_Source_Files} of a project P, then
-it is possible to remove the source completely from a system that includes
-project P.
+@item -IDIR
+@cindex @option{-IDIR} (@command{gnatfind})
+Equivalent to @samp{-aODIR -aIDIR}.
-@c ***********************
-@c * Project File Syntax *
-@c ***********************
+@item -pFILE
+@cindex @option{-pFILE} (@command{gnatfind})
+Specify a project file (@pxref{GNAT Project Manager}) to use.
+By default, @code{gnatxref} and @code{gnatfind} will try to locate a
+project file in the current directory.
-@node Project File Syntax
-@section Project File Syntax
+If a project file is either specified or found by the tools, then the content
+of the source directory and object directory lines are added as if they
+had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} and
+@samp{^-aO^/OBJECT_SEARCH^}.
-@menu
-* Basic Syntax::
-* Qualified Projects::
-* Packages::
-* Expressions::
-* String Types::
-* Variables::
-* Attributes::
-* Associative Array Attributes::
-* case Constructions::
-@end menu
+@item ^-r^/REFERENCES^
+@cindex @option{^-r^/REFERENCES^} (@command{gnatfind})
+By default, @code{gnatfind} will output only the information about the
+declaration, body or type completion of the entities. If this switch is
+set, the @code{gnatfind} will locate every reference to the entities in
+the files specified on the command line (or in every file in the search
+path if no file is given on the command line).
-@noindent
-This section describes the structure of project files.
+@item ^-s^/PRINT_LINES^
+@cindex @option{^-s^/PRINT_LINES^} (@command{gnatfind})
+If this switch is set, then @code{gnatfind} will output the content
+of the Ada source file lines were the entity was found.
-A project may be an @emph{independent project}, entirely defined by a single
-project file. Any Ada source file in an independent project depends only
-on the predefined library and other Ada source files in the same project.
+@item ^-t^/TYPE_HIERARCHY^
+@cindex @option{^-t^/TYPE_HIERARCHY^} (@command{gnatfind})
+If this switch is set, then @code{gnatfind} will output the type hierarchy for
+the specified type. It act like -d option but recursively from parent
+type to parent type. When this switch is set it is not possible to
+specify more than one file.
-@noindent
-A project may also @dfn{depend on} other projects, in either or both of
-the following ways:
-@itemize @bullet
-@item It may import any number of projects
-@item It may extend at most one other project
-@end itemize
+@end table
@noindent
-The dependence relation is a directed acyclic graph (the subgraph reflecting
-the ``extends'' relation is a tree).
-
-A project's @dfn{immediate sources} are the source files directly defined by
-that project, either implicitly by residing in the project file's directory,
-or explicitly through any of the source-related attributes described below.
-More generally, a project @var{proj}'s @dfn{sources} are the immediate sources
-of @var{proj} together with the immediate sources (unless overridden) of any
-project on which @var{proj} depends (either directly or indirectly).
-
-@node Basic Syntax
-@subsection Basic Syntax
+All these switches may be in any order on the command line, and may even
+appear after the file names. They need not be separated by spaces, thus
+you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
+@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
-@noindent
-As seen in the earlier examples, project files have an Ada-like syntax.
-The minimal project file is:
-@smallexample @c projectfile
-@group
-project Empty is
+As stated previously, gnatfind will search in every directory in the
+search path. You can force it to look only in the current directory if
+you specify @code{*} at the end of the command line.
-end Empty;
-@end group
-@end smallexample
+@node Project Files for gnatxref and gnatfind
+@section Project Files for @command{gnatxref} and @command{gnatfind}
@noindent
-The identifier @code{Empty} is the name of the project.
-This project name must be present after the reserved
-word @code{end} at the end of the project file, followed by a semi-colon.
-
-Any name in a project file, such as the project name or a variable name,
-has the same syntax as an Ada identifier.
+Project files allow a programmer to specify how to compile its
+application, where to find sources, etc. These files are used
+@ifclear vms
+primarily by GPS, but they can also be used
+@end ifclear
+by the two tools
+@code{gnatxref} and @code{gnatfind}.
-The reserved words of project files are the Ada 95 reserved words plus
-@code{extends}, @code{external}, and @code{project}. Note that the only Ada
-reserved words currently used in project file syntax are:
+A project file name must end with @file{.gpr}. If a single one is
+present in the current directory, then @code{gnatxref} and @code{gnatfind} will
+extract the information from it. If multiple project files are found, none of
+them is read, and you have to use the @samp{-p} switch to specify the one
+you want to use.
-@itemize @bullet
-@item
-@code{all}
-@item
-@code{at}
-@item
-@code{case}
-@item
-@code{end}
-@item
-@code{for}
-@item
-@code{is}
-@item
-@code{limited}
-@item
-@code{null}
-@item
-@code{others}
-@item
-@code{package}
-@item
-@code{renames}
-@item
-@code{type}
-@item
-@code{use}
-@item
-@code{when}
-@item
-@code{with}
-@end itemize
+The following lines can be included, even though most of them have default
+values which can be used in most cases.
+The lines can be entered in any order in the file.
+Except for @file{src_dir} and @file{obj_dir}, you can only have one instance of
+each line. If you have multiple instances, only the last one is taken into
+account.
-@noindent
-Comments in project files have the same syntax as in Ada, two consecutive
-hyphens through the end of the line.
+@table @code
+@item src_dir=DIR
+[default: @code{"^./^[]^"}]
+specifies a directory where to look for source files. Multiple @code{src_dir}
+lines can be specified and they will be searched in the order they
+are specified.
-@node Qualified Projects
-@subsection Qualified Projects
+@item obj_dir=DIR
+[default: @code{"^./^[]^"}]
+specifies a directory where to look for object and library files. Multiple
+@code{obj_dir} lines can be specified, and they will be searched in the order
+they are specified
-@noindent
-Before the reserved @code{project}, there may be one or two "qualifiers", that
-is identifiers or other reserved words, to qualify the project.
+@item comp_opt=SWITCHES
+[default: @code{""}]
+creates a variable which can be referred to subsequently by using
+the @code{$@{comp_opt@}} notation. This is intended to store the default
+switches given to @command{gnatmake} and @command{gcc}.
-The current list of qualifiers is:
+@item bind_opt=SWITCHES
+[default: @code{""}]
+creates a variable which can be referred to subsequently by using
+the @samp{$@{bind_opt@}} notation. This is intended to store the default
+switches given to @command{gnatbind}.
-@itemize @bullet
-@item
-@code{abstract}: qualify a project with no sources. A qualified abstract
-project must either have no declaration of attributes @code{Source_Dirs},
-@code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
-@code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
-as empty. If it extends another project, the project it extends must also be a
-qualified abstract project.
+@item link_opt=SWITCHES
+[default: @code{""}]
+creates a variable which can be referred to subsequently by using
+the @samp{$@{link_opt@}} notation. This is intended to store the default
+switches given to @command{gnatlink}.
-@item
-@code{standard}: a standard project is a non library project with sources.
+@item main=EXECUTABLE
+[default: @code{""}]
+specifies the name of the executable for the application. This variable can
+be referred to in the following lines by using the @samp{$@{main@}} notation.
-@item
-@code{aggregate}: for future extension
+@ifset vms
+@item comp_cmd=COMMAND
+[default: @code{"GNAT COMPILE /SEARCH=$@{src_dir@} /DEBUG /TRY_SEMANTICS"}]
+@end ifset
+@ifclear vms
+@item comp_cmd=COMMAND
+[default: @code{"gcc -c -I$@{src_dir@} -g -gnatq"}]
+@end ifclear
+specifies the command used to compile a single file in the application.
-@item
-@code{aggregate library}: for future extension
+@ifset vms
+@item make_cmd=COMMAND
+[default: @code{"GNAT MAKE $@{main@}
+/SOURCE_SEARCH=$@{src_dir@} /OBJECT_SEARCH=$@{obj_dir@}
+/DEBUG /TRY_SEMANTICS /COMPILER_QUALIFIERS $@{comp_opt@}
+/BINDER_QUALIFIERS $@{bind_opt@} /LINKER_QUALIFIERS $@{link_opt@}"}]
+@end ifset
+@ifclear vms
+@item make_cmd=COMMAND
+[default: @code{"gnatmake $@{main@} -aI$@{src_dir@}
+-aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@}
+-bargs $@{bind_opt@} -largs $@{link_opt@}"}]
+@end ifclear
+specifies the command used to recompile the whole application.
-@item
-@code{library}: a library project must declare both attributes
-@code{Library_Name} and @code{Library_Dir}.
+@item run_cmd=COMMAND
+[default: @code{"$@{main@}"}]
+specifies the command used to run the application.
-@item
-@code{configuration}: a configuration project cannot be in a project tree.
-@end itemize
+@item debug_cmd=COMMAND
+[default: @code{"gdb $@{main@}"}]
+specifies the command used to debug the application
-@node Packages
-@subsection Packages
+@end table
@noindent
-A project file may contain @emph{packages}. The name of a package must be one
-of the identifiers from the following list. A package
-with a given name may only appear once in a project file. Package names are
-case insensitive. The following package names are legal:
+@command{gnatxref} and @command{gnatfind} only take into account the
+@code{src_dir} and @code{obj_dir} lines, and ignore the others.
-@itemize @bullet
-@item
-@code{Naming}
-@item
-@code{Builder}
-@item
-@code{Compiler}
-@item
-@code{Binder}
-@item
-@code{Linker}
-@item
-@code{Finder}
-@item
-@code{Cross_Reference}
-@item
-@code{Eliminate}
-@item
-@code{Pretty_Printer}
-@item
-@code{Metrics}
-@item
-@code{gnatls}
-@item
-@code{gnatstub}
-@item
-@code{IDE}
-@item
-@code{Language_Processing}
-@end itemize
+@node Regular Expressions in gnatfind and gnatxref
+@section Regular Expressions in @code{gnatfind} and @code{gnatxref}
@noindent
-In its simplest form, a package may be empty:
+As specified in the section about @command{gnatfind}, the pattern can be a
+regular expression. Actually, there are to set of regular expressions
+which are recognized by the program:
-@smallexample @c projectfile
+@table @code
+@item globbing patterns
+These are the most usual regular expression. They are the same that you
+generally used in a Unix shell command line, or in a DOS session.
+
+Here is a more formal grammar:
+@smallexample
@group
-project Simple is
- package Builder is
- end Builder;
-end Simple;
+@iftex
+@leftskip=.5cm
+@end iftex
+regexp ::= term
+term ::= elmt -- matches elmt
+term ::= elmt elmt -- concatenation (elmt then elmt)
+term ::= * -- any string of 0 or more characters
+term ::= ? -- matches any character
+term ::= [char @{char@}] -- matches any character listed
+term ::= [char - char] -- matches any character in range
@end group
@end smallexample
-@noindent
-A package may contain @emph{attribute declarations},
-@emph{variable declarations} and @emph{case constructions}, as will be
-described below.
-
-When there is ambiguity between a project name and a package name,
-the name always designates the project. To avoid possible confusion, it is
-always a good idea to avoid naming a project with one of the
-names allowed for packages or any name that starts with @code{gnat}.
+@item full regular expression
+The second set of regular expressions is much more powerful. This is the
+type of regular expressions recognized by utilities such a @file{grep}.
-@node Expressions
-@subsection Expressions
+The following is the form of a regular expression, expressed in Ada
+reference manual style BNF is as follows
-@noindent
-An @emph{expression} is either a @emph{string expression} or a
-@emph{string list expression}.
+@smallexample
+@iftex
+@leftskip=.5cm
+@end iftex
+@group
+regexp ::= term @{| term@} -- alternation (term or term @dots{})
-A @emph{string expression} is either a @emph{simple string expression} or a
-@emph{compound string expression}.
+term ::= item @{item@} -- concatenation (item then item)
-A @emph{simple string expression} is one of the following:
-@itemize @bullet
-@item A literal string; e.g.@: @code{"comm/my_proj.gpr"}
-@item A string-valued variable reference (@pxref{Variables})
-@item A string-valued attribute reference (@pxref{Attributes})
-@item An external reference (@pxref{External References in Project Files})
-@end itemize
-
-@noindent
-A @emph{compound string expression} is a concatenation of string expressions,
-using the operator @code{"&"}
-@smallexample
- Path & "/" & File_Name & ".ads"
-@end smallexample
-
-@noindent
-A @emph{string list expression} is either a
-@emph{simple string list expression} or a
-@emph{compound string list expression}.
-
-A @emph{simple string list expression} is one of the following:
-@itemize @bullet
-@item A parenthesized list of zero or more string expressions,
-separated by commas
-@smallexample
- File_Names := (File_Name, "gnat.adc", File_Name & ".orig");
- Empty_List := ();
-@end smallexample
-@item A string list-valued variable reference
-@item A string list-valued attribute reference
-@end itemize
-
-@noindent
-A @emph{compound string list expression} is the concatenation (using
-@code{"&"}) of a simple string list expression and an expression. Note that
-each term in a compound string list expression, except the first, may be
-either a string expression or a string list expression.
-
-@smallexample @c projectfile
+item ::= elmt -- match elmt
+item ::= elmt * -- zero or more elmt's
+item ::= elmt + -- one or more elmt's
+item ::= elmt ? -- matches elmt or nothing
+@end group
@group
- File_Name_List := () & File_Name; -- One string in this list
- Extended_File_Name_List := File_Name_List & (File_Name & ".orig");
- -- Two strings
- Big_List := File_Name_List & Extended_File_Name_List;
- -- Concatenation of two string lists: three strings
- Illegal_List := "gnat.adc" & Extended_File_Name_List;
- -- Illegal: must start with a string list
+elmt ::= nschar -- matches given character
+elmt ::= [nschar @{nschar@}] -- matches any character listed
+elmt ::= [^^^ nschar @{nschar@}] -- matches any character not listed
+elmt ::= [char - char] -- matches chars in given range
+elmt ::= \ char -- matches given character
+elmt ::= . -- matches any single character
+elmt ::= ( regexp ) -- parens used for grouping
+
+char ::= any character, including special characters
+nschar ::= any character except ()[].*+?^^^
@end group
@end smallexample
-@node String Types
-@subsection String Types
-
-@noindent
-A @emph{string type declaration} introduces a discrete set of string literals.
-If a string variable is declared to have this type, its value
-is restricted to the given set of literals.
-
-Here is an example of a string type declaration:
+Following are a few examples:
-@smallexample @c projectfile
- type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
-@end smallexample
+@table @samp
+@item abcde|fghi
+will match any of the two strings @samp{abcde} and @samp{fghi},
-@noindent
-Variables of a string type are called @emph{typed variables}; all other
-variables are called @emph{untyped variables}. Typed variables are
-particularly useful in @code{case} constructions, to support conditional
-attribute declarations.
-(@pxref{case Constructions}).
+@item abc*d
+will match any string like @samp{abd}, @samp{abcd}, @samp{abccd},
+@samp{abcccd}, and so on,
-The string literals in the list are case sensitive and must all be different.
-They may include any graphic characters allowed in Ada, including spaces.
+@item [a-z]+
+will match any string which has only lowercase characters in it (and at
+least one character.
-A string type may only be declared at the project level, not inside a package.
+@end table
+@end table
-A string type may be referenced by its name if it has been declared in the same
-project file, or by an expanded name whose prefix is the name of the project
-in which it is declared.
+@node Examples of gnatxref Usage
+@section Examples of @code{gnatxref} Usage
-@node Variables
-@subsection Variables
+@subsection General Usage
@noindent
-A variable may be declared at the project file level, or within a package.
-Here are some examples of variable declarations:
+For the following examples, we will consider the following units:
-@smallexample @c projectfile
+@smallexample @c ada
@group
- This_OS : OS := external ("OS"); -- a typed variable declaration
- That_OS := "GNU/Linux"; -- an untyped variable declaration
+@cartouche
+main.ads:
+1: with Bar;
+2: package Main is
+3: procedure Foo (B : in Integer);
+4: C : Integer;
+5: private
+6: D : Integer;
+7: end Main;
+
+main.adb:
+1: package body Main is
+2: procedure Foo (B : in Integer) is
+3: begin
+4: C := B;
+5: D := B;
+6: Bar.Print (B);
+7: Bar.Print (C);
+8: end Foo;
+9: end Main;
+
+bar.ads:
+1: package Bar is
+2: procedure Print (B : Integer);
+3: end bar;
+@end cartouche
@end group
@end smallexample
-@noindent
-The syntax of a @emph{typed variable declaration} is identical to the Ada
-syntax for an object declaration. By contrast, the syntax of an untyped
-variable declaration is identical to an Ada assignment statement. In fact,
-variable declarations in project files have some of the characteristics of
-an assignment, in that successive declarations for the same variable are
-allowed. Untyped variable declarations do establish the expected kind of the
-variable (string or string list), and successive declarations for it must
-respect the initial kind.
+@table @code
@noindent
-A string variable declaration (typed or untyped) declares a variable
-whose value is a string. This variable may be used as a string expression.
-@smallexample @c projectfile
- File_Name := "readme.txt";
- Saved_File_Name := File_Name & ".saved";
-@end smallexample
+The first thing to do is to recompile your application (for instance, in
+that case just by doing a @samp{gnatmake main}, so that GNAT generates
+the cross-referencing information.
+You can then issue any of the following commands:
-@noindent
-A string list variable declaration declares a variable whose value is a list
-of strings. The list may contain any number (zero or more) of strings.
+@item gnatxref main.adb
+@code{gnatxref} generates cross-reference information for main.adb
+and every unit 'with'ed by main.adb.
-@smallexample @c projectfile
- Empty_List := ();
- List_With_One_Element := ("^-gnaty^-gnaty^");
- List_With_Two_Elements := List_With_One_Element & "^-gnatg^-gnatg^";
- Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"
- "pack2.ada", "util_.ada", "util.ada");
+The output would be:
+@smallexample
+@iftex
+@leftskip=0cm
+@end iftex
+B Type: Integer
+ Decl: bar.ads 2:22
+B Type: Integer
+ Decl: main.ads 3:20
+ Body: main.adb 2:20
+ Ref: main.adb 4:13 5:13 6:19
+Bar Type: Unit
+ Decl: bar.ads 1:9
+ Ref: main.adb 6:8 7:8
+ main.ads 1:6
+C Type: Integer
+ Decl: main.ads 4:5
+ Modi: main.adb 4:8
+ Ref: main.adb 7:19
+D Type: Integer
+ Decl: main.ads 6:5
+ Modi: main.adb 5:8
+Foo Type: Unit
+ Decl: main.ads 3:15
+ Body: main.adb 2:15
+Main Type: Unit
+ Decl: main.ads 2:9
+ Body: main.adb 1:14
+Print Type: Unit
+ Decl: bar.ads 2:15
+ Ref: main.adb 6:12 7:12
@end smallexample
@noindent
-The same typed variable may not be declared more than once at project level,
-and it may not be declared more than once in any package; it is in effect
-a constant.
+that is the entity @code{Main} is declared in main.ads, line 2, column 9,
+its body is in main.adb, line 1, column 14 and is not referenced any where.
-The same untyped variable may be declared several times. Declarations are
-elaborated in the order in which they appear, so the new value replaces
-the old one, and any subsequent reference to the variable uses the new value.
-However, as noted above, if a variable has been declared as a string, all
-subsequent
-declarations must give it a string value. Similarly, if a variable has
-been declared as a string list, all subsequent declarations
-must give it a string list value.
+The entity @code{Print} is declared in bar.ads, line 2, column 15 and it
+it referenced in main.adb, line 6 column 12 and line 7 column 12.
-A @emph{variable reference} may take several forms:
+@item gnatxref package1.adb package2.ads
+@code{gnatxref} will generates cross-reference information for
+package1.adb, package2.ads and any other package 'with'ed by any
+of these.
-@itemize @bullet
-@item The simple variable name, for a variable in the current package (if any)
-or in the current project
-@item An expanded name, whose prefix is a context name.
-@end itemize
+@end table
-@noindent
-A @emph{context} may be one of the following:
+@ifclear vms
+@subsection Using gnatxref with vi
-@itemize @bullet
-@item The name of an existing package in the current project
-@item The name of an imported project of the current project
-@item The name of an ancestor project (i.e., a project extended by the current
-project, either directly or indirectly)
-@item An expanded name whose prefix is an imported/parent project name, and
-whose selector is a package name in that project.
-@end itemize
+@code{gnatxref} can generate a tags file output, which can be used
+directly from @command{vi}. Note that the standard version of @command{vi}
+will not work properly with overloaded symbols. Consider using another
+free implementation of @command{vi}, such as @command{vim}.
-@noindent
-A variable reference may be used in an expression.
-
-@node Attributes
-@subsection Attributes
-
-@noindent
-A project (and its packages) may have @emph{attributes} that define
-the project's properties. Some attributes have values that are strings;
-others have values that are string lists.
-
-There are two categories of attributes: @emph{simple attributes}
-and @emph{associative arrays} (@pxref{Associative Array Attributes}).
-
-Legal project attribute names, and attribute names for each legal package are
-listed below. Attributes names are case-insensitive.
-
-The following attributes are defined on projects (all are simple attributes):
-
-@multitable @columnfractions .4 .3
-@item @emph{Attribute Name}
-@tab @emph{Value}
-@item @code{Source_Files}
-@tab string list
-@item @code{Source_Dirs}
-@tab string list
-@item @code{Source_List_File}
-@tab string
-@item @code{Object_Dir}
-@tab string
-@item @code{Exec_Dir}
-@tab string
-@item @code{Excluded_Source_Dirs}
-@tab string list
-@item @code{Excluded_Source_Files}
-@tab string list
-@item @code{Excluded_Source_List_File}
-@tab string
-@item @code{Languages}
-@tab string list
-@item @code{Main}
-@tab string list
-@item @code{Library_Dir}
-@tab string
-@item @code{Library_Name}
-@tab string
-@item @code{Library_Kind}
-@tab string
-@item @code{Library_Version}
-@tab string
-@item @code{Library_Interface}
-@tab string
-@item @code{Library_Auto_Init}
-@tab string
-@item @code{Library_Options}
-@tab string list
-@item @code{Library_Src_Dir}
-@tab string
-@item @code{Library_ALI_Dir}
-@tab string
-@item @code{Library_GCC}
-@tab string
-@item @code{Library_Symbol_File}
-@tab string
-@item @code{Library_Symbol_Policy}
-@tab string
-@item @code{Library_Reference_Symbol_File}
-@tab string
-@item @code{Externally_Built}
-@tab string
-@end multitable
+@smallexample
+$ gnatxref -v gnatfind.adb > tags
+@end smallexample
@noindent
-The following attributes are defined for package @code{Naming}
-(@pxref{Naming Schemes}):
-
-@multitable @columnfractions .4 .2 .2 .2
-@item Attribute Name @tab Category @tab Index @tab Value
-@item @code{Spec_Suffix}
-@tab associative array
-@tab language name
-@tab string
-@item @code{Body_Suffix}
-@tab associative array
-@tab language name
-@tab string
-@item @code{Separate_Suffix}
-@tab simple attribute
-@tab n/a
-@tab string
-@item @code{Casing}
-@tab simple attribute
-@tab n/a
-@tab string
-@item @code{Dot_Replacement}
-@tab simple attribute
-@tab n/a
-@tab string
-@item @code{Spec}
-@tab associative array
-@tab Ada unit name
-@tab string
-@item @code{Body}
-@tab associative array
-@tab Ada unit name
-@tab string
-@item @code{Specification_Exceptions}
-@tab associative array
-@tab language name
-@tab string list
-@item @code{Implementation_Exceptions}
-@tab associative array
-@tab language name
-@tab string list
-@end multitable
+will generate the tags file for @code{gnatfind} itself (if the sources
+are in the search path!).
-@noindent
-The following attributes are defined for packages @code{Builder},
-@code{Compiler}, @code{Binder},
-@code{Linker}, @code{Cross_Reference}, and @code{Finder}
-(@pxref{^Switches^Switches^ and Project Files}).
-
-@multitable @columnfractions .4 .2 .2 .2
-@item Attribute Name @tab Category @tab Index @tab Value
-@item @code{^Default_Switches^Default_Switches^}
-@tab associative array
-@tab language name
-@tab string list
-@item @code{^Switches^Switches^}
-@tab associative array
-@tab file name
-@tab string list
-@end multitable
+From @command{vi}, you can then use the command @samp{:tag @var{entity}}
+(replacing @var{entity} by whatever you are looking for), and vi will
+display a new file with the corresponding declaration of entity.
+@end ifclear
-@noindent
-In addition, package @code{Compiler} has a single string attribute
-@code{Local_Configuration_Pragmas} and package @code{Builder} has a single
-string attribute @code{Global_Configuration_Pragmas}.
+@node Examples of gnatfind Usage
+@section Examples of @code{gnatfind} Usage
-@noindent
-Each simple attribute has a default value: the empty string (for string-valued
-attributes) and the empty list (for string list-valued attributes).
+@table @code
-An attribute declaration defines a new value for an attribute.
+@item gnatfind ^-f^/FULL_PATHNAME^ xyz:main.adb
+Find declarations for all entities xyz referenced at least once in
+main.adb. The references are search in every library file in the search
+path.
-Examples of simple attribute declarations:
+The directories will be printed as well (as the @samp{^-f^/FULL_PATHNAME^}
+switch is set)
-@smallexample @c projectfile
- for Object_Dir use "objects";
- for Source_Dirs use ("units", "test/drivers");
+The output will look like:
+@smallexample
+^directory/^[directory]^main.ads:106:14: xyz <= declaration
+^directory/^[directory]^main.adb:24:10: xyz <= body
+^directory/^[directory]^foo.ads:45:23: xyz <= declaration
@end smallexample
@noindent
-The syntax of a @dfn{simple attribute declaration} is similar to that of an
-attribute definition clause in Ada.
-
-Attributes references may be appear in expressions.
-The general form for such a reference is @code{<entity>'<attribute>}:
-Associative array attributes are functions. Associative
-array attribute references must have an argument that is a string literal.
-
-Examples are:
+that is to say, one of the entities xyz found in main.adb is declared at
+line 12 of main.ads (and its body is in main.adb), and another one is
+declared at line 45 of foo.ads
-@smallexample @c projectfile
- project'Object_Dir
- Naming'Dot_Replacement
- Imported_Project'Source_Dirs
- Imported_Project.Naming'Casing
- Builder'^Default_Switches^Default_Switches^("Ada")
-@end smallexample
+@item gnatfind ^-fs^/FULL_PATHNAME/SOURCE_LINE^ xyz:main.adb
+This is the same command as the previous one, instead @code{gnatfind} will
+display the content of the Ada source file lines.
-@noindent
-The prefix of an attribute may be:
-@itemize @bullet
-@item @code{project} for an attribute of the current project
-@item The name of an existing package of the current project
-@item The name of an imported project
-@item The name of a parent project that is extended by the current project
-@item An expanded name whose prefix is imported/parent project name,
-and whose selector is a package name
-@end itemize
+The output will look like:
-@noindent
-Example:
-@smallexample @c projectfile
-@group
- project Prj is
- for Source_Dirs use project'Source_Dirs & "units";
- for Source_Dirs use project'Source_Dirs & "test/drivers"
- end Prj;
-@end group
+@smallexample
+^directory/^[directory]^main.ads:106:14: xyz <= declaration
+ procedure xyz;
+^directory/^[directory]^main.adb:24:10: xyz <= body
+ procedure xyz is
+^directory/^[directory]^foo.ads:45:23: xyz <= declaration
+ xyz : Integer;
@end smallexample
@noindent
-In the first attribute declaration, initially the attribute @code{Source_Dirs}
-has the default value: an empty string list. After this declaration,
-@code{Source_Dirs} is a string list of one element: @code{"units"}.
-After the second attribute declaration @code{Source_Dirs} is a string list of
-two elements: @code{"units"} and @code{"test/drivers"}.
-
-Note: this example is for illustration only. In practice,
-the project file would contain only one attribute declaration:
-
-@smallexample @c projectfile
- for Source_Dirs use ("units", "test/drivers");
-@end smallexample
+This can make it easier to find exactly the location your are looking
+for.
-@node Associative Array Attributes
-@subsection Associative Array Attributes
+@item gnatfind ^-r^/REFERENCES^ "*x*":main.ads:123 foo.adb
+Find references to all entities containing an x that are
+referenced on line 123 of main.ads.
+The references will be searched only in main.ads and foo.adb.
-@noindent
-Some attributes are defined as @emph{associative arrays}. An associative
-array may be regarded as a function that takes a string as a parameter
-and delivers a string or string list value as its result.
+@item gnatfind main.ads:123
+Find declarations and bodies for all entities that are referenced on
+line 123 of main.ads.
-Here are some examples of single associative array attribute associations:
+This is the same as @code{gnatfind "*":main.adb:123}.
-@smallexample @c projectfile
- for Body ("main") use "Main.ada";
- for ^Switches^Switches^ ("main.ada")
- use ("^-v^-v^",
- "^-gnatv^-gnatv^");
- for ^Switches^Switches^ ("main.ada")
- use Builder'^Switches^Switches^ ("main.ada")
- & "^-g^-g^";
-@end smallexample
+@item gnatfind ^mydir/^[mydir]^main.adb:123:45
+Find the declaration for the entity referenced at column 45 in
+line 123 of file main.adb in directory mydir. Note that it
+is usual to omit the identifier name when the column is given,
+since the column position identifies a unique reference.
-@noindent
-Like untyped variables and simple attributes, associative array attributes
-may be declared several times. Each declaration supplies a new value for the
-attribute, and replaces the previous setting.
+The column has to be the beginning of the identifier, and should not
+point to any character in the middle of the identifier.
-@noindent
-An associative array attribute may be declared as a full associative array
-declaration, with the value of the same attribute in an imported or extended
-project.
+@end table
-@smallexample @c projectfile
- package Builder is
- for Default_Switches use Default.Builder'Default_Switches;
- end Builder;
-@end smallexample
+@c *********************************
+@node The GNAT Pretty-Printer gnatpp
+@chapter The GNAT Pretty-Printer @command{gnatpp}
+@findex gnatpp
+@cindex Pretty-Printer
@noindent
-In this example, @code{Default} must be either a project imported by the
-current project, or the project that the current project extends. If the
-attribute is in a package (in this case, in package @code{Builder}), the same
-package needs to be specified.
+^The @command{gnatpp} tool^GNAT PRETTY^ is an ASIS-based 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.
-@noindent
-A full associative array declaration replaces any other declaration for the
-attribute, including other full associative array declaration. Single
-associative array associations may be declare after a full associative
-declaration, modifying the value for a single association of the attribute.
+To produce a reformatted file, @command{gnatpp} generates and uses the ASIS
+tree for the input source and thus requires the input to be syntactically and
+semantically legal.
+If this condition is not met, @command{gnatpp} will terminate with an
+error message; no output file will be generated.
-@node case Constructions
-@subsection @code{case} Constructions
+If the source files presented to @command{gnatpp} contain
+preprocessing directives, then the output file will
+correspond to the generated source after all
+preprocessing is carried out. There is no way
+using @command{gnatpp} to obtain pretty printed files that
+include the preprocessing directives.
-@noindent
-A @code{case} construction is used in a project file to effect conditional
-behavior.
-Here is a typical example:
-
-@smallexample @c projectfile
-@group
-project MyProj is
- type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
+If the compilation unit
+contained in the input source depends semantically upon units located
+outside the current directory, you have to provide the source search path
+when invoking @command{gnatpp}, if these units are contained in files with
+names that do not follow the GNAT file naming rules, you have to provide
+the configuration file describing the corresponding naming scheme;
+see the description of the @command{gnatpp}
+switches below. Another possibility is to use a project file and to
+call @command{gnatpp} through the @command{gnat} driver
- OS : OS_Type := external ("OS", "GNU/Linux");
-@end group
+The @command{gnatpp} command has the form
-@group
- package Compiler is
- case OS is
- when "GNU/Linux" | "Unix" =>
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnath^-gnath^");
- when "NT" =>
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnatP^-gnatP^");
- when others =>
- end case;
- end Compiler;
-end MyProj;
-@end group
+@smallexample
+@c $ gnatpp @ovar{switches} @var{filename}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatpp @r{[}@var{switches}@r{]} @var{filename} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
-The syntax of a @code{case} construction is based on the Ada case statement
-(although there is no @code{null} construction for empty alternatives).
-
-The case expression must be a typed string variable.
-Each alternative comprises the reserved word @code{when}, either a list of
-literal strings separated by the @code{"|"} character or the reserved word
-@code{others}, and the @code{"=>"} token.
-Each literal string must belong to the string type that is the type of the
-case variable.
-An @code{others} alternative, if present, must occur last.
-
-After each @code{=>}, there are zero or more constructions. The only
-constructions allowed in a case construction are other case constructions,
-attribute declarations and variable declarations. String type declarations and
-package declarations are not allowed. Variable declarations are restricted to
-variables that have already been declared before the case construction.
-
-The value of the case variable is often given by an external reference
-(@pxref{External References in Project Files}).
+where
+@itemize @bullet
+@item
+@var{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
-@c ****************************************
-@c * Objects and Sources in Project Files *
-@c ****************************************
+@item
+@var{filename} is the name (including the extension) 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
-@node Objects and Sources in Project Files
-@section Objects and Sources in Project Files
+@item
+@samp{@var{gcc_switches}} is a list of switches for
+@command{gcc}. They will be passed on to all compiler invocations made by
+@command{gnatelim} to generate the ASIS trees. Here you can provide
+@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
+use the @option{-gnatec} switch to set the configuration file,
+use the @option{-gnat05} switch if sources should be compiled in
+Ada 2005 mode etc.
+@end itemize
@menu
-* Object Directory::
-* Exec Directory::
-* Source Directories::
-* Source File Names::
+* Switches for gnatpp::
+* Formatting Rules::
@end menu
-@noindent
-Each project has exactly one object directory and one or more source
-directories. The source directories must contain at least one source file,
-unless the project file explicitly specifies that no source files are present
-(@pxref{Source File Names}).
-
-@node Object Directory
-@subsection Object Directory
+@node Switches for gnatpp
+@section Switches for @command{gnatpp}
@noindent
-The object directory for a project is the directory containing the compiler's
-output (such as @file{ALI} files and object files) for the project's immediate
-sources.
+The following subsections describe the various switches accepted by
+@command{gnatpp}, organized by category.
-The object directory is given by the value of the attribute @code{Object_Dir}
-in the project file.
+@ifclear vms
+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 @command{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 @command{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.
+For example, to set
+the alignment of the assignment delimiter both in declarations and in
+assignment statements, you must write @option{-A2A3}
+(or @option{-A2 -A3}), but not @option{-A23}.
+@end ifclear
-@smallexample @c projectfile
- for Object_Dir use "objects";
-@end smallexample
+@ifset vms
+In many cases the set of options for a given qualifier are incompatible with
+each other (for example the qualifier that controls the casing of a reserved
+word may have exactly one option, which specifies either upper case, lower
+case, or mixed case), and thus exactly one such option can be in effect for
+an invocation of @command{gnatpp}.
+If more than one is supplied, the last one is used.
+However, some qualifiers have options that are mutually compatible,
+and then you may then supply several such options when invoking
+@command{gnatpp}.
+@end ifset
-@noindent
-The attribute @code{Object_Dir} has a string value, the path name of the object
-directory. The path name may be absolute or relative to the directory of the
-project file. This directory must already exist, and be readable and writable.
+In most cases, it is obvious whether or not the
+^values for a switch with a given name^options for a given qualifier^
+are compatible with each other.
+When the semantics might not be evident, the summaries below explicitly
+indicate the effect.
-By default, when the attribute @code{Object_Dir} is not given an explicit value
-or when its value is the empty string, the object directory is the same as the
-directory containing the project file.
+@menu
+* Alignment Control::
+* Casing Control::
+* Construct Layout Control::
+* General Text Layout Control::
+* Other Formatting Options::
+* Setting the Source Search Path::
+* Output File Control::
+* Other gnatpp Switches::
+@end menu
-@node Exec Directory
-@subsection Exec Directory
+@node Alignment Control
+@subsection Alignment Control
+@cindex Alignment control in @command{gnatpp}
@noindent
-The exec directory for a project is the directory containing the executables
-for the project's main subprograms.
-
-The exec directory is given by the value of the attribute @code{Exec_Dir}
-in the project file.
+Programs can be easier to read if certain constructs are vertically aligned.
+By default all alignments are set ON.
+Through the @option{^-A0^/ALIGN=OFF^} switch you may reset the default to
+OFF, and then use one or more of the other
+^@option{-A@var{n}} switches^@option{/ALIGN} options^
+to activate alignment for specific constructs.
-@smallexample @c projectfile
- for Exec_Dir use "executables";
-@end smallexample
+@table @option
+@cindex @option{^-A@var{n}^/ALIGN^} (@command{gnatpp})
-@noindent
-The attribute @code{Exec_Dir} has a string value, the path name of the exec
-directory. The path name may be absolute or relative to the directory of the
-project file. This directory must already exist, and be writable.
+@ifset vms
+@item /ALIGN=ON
+Set all alignments to ON
+@end ifset
-By default, when the attribute @code{Exec_Dir} is not given an explicit value
-or when its value is the empty string, the exec directory is the same as the
-object directory of the project file.
+@item ^-A0^/ALIGN=OFF^
+Set all alignments to OFF
-@node Source Directories
-@subsection Source Directories
+@item ^-A1^/ALIGN=COLONS^
+Align @code{:} in declarations
-@noindent
-The source directories of a project are specified by the project file
-attribute @code{Source_Dirs}.
+@item ^-A2^/ALIGN=DECLARATIONS^
+Align @code{:=} in initializations in declarations
-This attribute's value is a string list. If the attribute is not given an
-explicit value, then there is only one source directory, the one where the
-project file resides.
+@item ^-A3^/ALIGN=STATEMENTS^
+Align @code{:=} in assignment statements
-A @code{Source_Dirs} attribute that is explicitly defined to be the empty list,
-as in
+@item ^-A4^/ALIGN=ARROWS^
+Align @code{=>} in associations
-@smallexample @c projectfile
- for Source_Dirs use ();
-@end smallexample
+@item ^-A5^/ALIGN=COMPONENT_CLAUSES^
+Align @code{at} keywords in the component clauses in record
+representation clauses
+@end table
@noindent
-indicates that the project contains no source files.
-
-Otherwise, each string in the string list designates one or more
-source directories.
+The @option{^-A^/ALIGN^} switches are mutually compatible; any combination
+is allowed.
-@smallexample @c projectfile
- for Source_Dirs use ("sources", "test/drivers");
-@end smallexample
+@node Casing Control
+@subsection Casing Control
+@cindex Casing control in @command{gnatpp}
@noindent
-If a string in the list ends with @code{"/**"}, then the directory whose path
-name precedes the two asterisks, as well as all its subdirectories
-(recursively), are source directories.
+@command{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.
-@smallexample @c projectfile
- for Source_Dirs use ("/system/sources/**");
-@end smallexample
+Three types of casing are supported: lower case, upper case, and mixed case.
+Lower and upper case are self-explanatory (but since some letters in
+Latin1 and other GNAT-supported character sets
+exist only in lower-case form, an upper case conversion will have no
+effect on them.)
+``Mixed case'' means that the first letter, and also each letter immediately
+following an underscore, are converted to their uppercase forms;
+all the other letters are converted to their lowercase forms.
-@noindent
-Here the directory @code{/system/sources} and all of its subdirectories
-(recursively) are source directories.
+@table @option
+@cindex @option{^-a@var{x}^/ATTRIBUTE^} (@command{gnatpp})
+@item ^-aL^/ATTRIBUTE_CASING=LOWER_CASE^
+Attribute designators are lower case
-To specify that the source directories are the directory of the project file
-and all of its subdirectories, you can declare @code{Source_Dirs} as follows:
-@smallexample @c projectfile
- for Source_Dirs use ("./**");
-@end smallexample
+@item ^-aU^/ATTRIBUTE_CASING=UPPER_CASE^
+Attribute designators are upper case
-@noindent
-Each of the source directories must exist and be readable.
+@item ^-aM^/ATTRIBUTE_CASING=MIXED_CASE^
+Attribute designators are mixed case (this is the default)
-@node Source File Names
-@subsection Source File Names
+@cindex @option{^-k@var{x}^/KEYWORD_CASING^} (@command{gnatpp})
+@item ^-kL^/KEYWORD_CASING=LOWER_CASE^
+Keywords (technically, these are known in Ada as @emph{reserved words}) are
+lower case (this is the default)
-@noindent
-In a project that contains source files, their names may be specified by the
-attributes @code{Source_Files} (a string list) or @code{Source_List_File}
-(a string). Source file names never include any directory information.
+@item ^-kU^/KEYWORD_CASING=UPPER_CASE^
+Keywords are upper case
-If the attribute @code{Source_Files} is given an explicit value, then each
-element of the list is a source file name.
+@cindex @option{^-n@var{x}^/NAME_CASING^} (@command{gnatpp})
+@item ^-nD^/NAME_CASING=AS_DECLARED^
+Name casing for defining occurrences are as they appear in the source file
+(this is the default)
-@smallexample @c projectfile
- for Source_Files use ("main.adb");
- for Source_Files use ("main.adb", "pack1.ads", "pack2.adb");
-@end smallexample
+@item ^-nU^/NAME_CASING=UPPER_CASE^
+Names are in upper case
-@noindent
-If the attribute @code{Source_Files} is not given an explicit value,
-but the attribute @code{Source_List_File} is given a string value,
-then the source file names are contained in the text file whose path name
-(absolute or relative to the directory of the project file) is the
-value of the attribute @code{Source_List_File}.
+@item ^-nL^/NAME_CASING=LOWER_CASE^
+Names are in lower case
-Each line in the file that is not empty or is not a comment
-contains a source file name.
+@item ^-nM^/NAME_CASING=MIXED_CASE^
+Names are in mixed case
-@smallexample @c projectfile
- for Source_List_File use "source_list.txt";
-@end smallexample
+@cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp})
+@item ^-pL^/PRAGMA_CASING=LOWER_CASE^
+Pragma names are lower case
-@noindent
-By default, if neither the attribute @code{Source_Files} nor the attribute
-@code{Source_List_File} is given an explicit value, then each file in the
-source directories that conforms to the project's naming scheme
-(@pxref{Naming Schemes}) is an immediate source of the project.
+@item ^-pU^/PRAGMA_CASING=UPPER_CASE^
+Pragma names are upper case
-A warning is issued if both attributes @code{Source_Files} and
-@code{Source_List_File} are given explicit values. In this case, the attribute
-@code{Source_Files} prevails.
+@item ^-pM^/PRAGMA_CASING=MIXED_CASE^
+Pragma names are mixed case (this is the default)
+
+@item ^-D@var{file}^/DICTIONARY=@var{file}^
+@cindex @option{^-D^/DICTIONARY^} (@command{gnatpp})
+Use @var{file} as a @emph{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^/NAME_CASING^ switch.
+To supply more than one dictionary file,
+use ^several @option{-D} switches^a list of files as options^.
-Each source file name must be the name of one existing source file
-in one of the source directories.
+@noindent
+@option{gnatpp} implicitly uses a @emph{default dictionary file}
+to define the casing for the Ada predefined names and
+the names declared in the GNAT libraries.
-A @code{Source_Files} attribute whose value is an empty list
-indicates that there are no source files in the project.
+@item ^-D-^/SPECIFIC_CASING^
+@cindex @option{^-D-^/SPECIFIC_CASING^} (@command{gnatpp})
+Do not use the default dictionary file;
+instead, use the casing
+defined by a @option{^-n^/NAME_CASING^} switch and any explicit
+dictionary file(s)
+@end table
-If the order of the source directories is known statically, that is if
-@code{"/**"} is not used in the string list @code{Source_Dirs}, then there may
-be several files with the same source file name. In this case, only the file
-in the first directory is considered as an immediate source of the project
-file. If the order of the source directories is not known statically, it is
-an error to have several files with the same source file name.
+@noindent
+The structure of a dictionary file, and details on the conventions
+used in the default dictionary file, are defined in @ref{Name Casing}.
-Projects can be specified to have no Ada source
-files: the value of @code{Source_Dirs} or @code{Source_Files} may be an empty
-list, or the @code{"Ada"} may be absent from @code{Languages}:
+The @option{^-D-^/SPECIFIC_CASING^} and
+@option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually
+compatible.
-@smallexample @c projectfile
- for Source_Dirs use ();
- for Source_Files use ();
- for Languages use ("C", "C++");
-@end smallexample
+@node Construct Layout Control
+@subsection Construct Layout Control
+@cindex Layout control in @command{gnatpp}
@noindent
-Otherwise, a project must contain at least one immediate source.
+This group of @command{gnatpp} switches controls the layout of comments and
+complex syntactic constructs. See @ref{Formatting Comments} for details
+on their effect.
-Projects with no source files are useful as template packages
-(@pxref{Packages in Project Files}) for other projects; in particular to
-define a package @code{Naming} (@pxref{Naming Schemes}).
+@table @option
+@cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp})
+@item ^-c0^/COMMENTS_LAYOUT=UNTOUCHED^
+All the comments remain unchanged
-@c ****************************
-@c * Importing Projects *
-@c ****************************
+@item ^-c1^/COMMENTS_LAYOUT=DEFAULT^
+GNAT-style comment line indentation (this is the default).
-@node Importing Projects
-@section Importing Projects
-@cindex @code{ADA_PROJECT_PATH}
+@item ^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^
+Reference-manual comment line indentation.
-@noindent
-An immediate source of a project P may depend on source files that
-are neither immediate sources of P nor in the predefined library.
-To get this effect, P must @emph{import} the projects that contain the needed
-source files.
+@item ^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^
+GNAT-style comment beginning
-@smallexample @c projectfile
-@group
- with "project1", "utilities.gpr";
- with "/namings/apex.gpr";
- project Main is
- @dots{}
-@end group
-@end smallexample
+@item ^-c4^/COMMENTS_LAYOUT=REFORMAT^
+Reformat comment blocks
-@noindent
-As can be seen in this example, the syntax for importing projects is similar
-to the syntax for importing compilation units in Ada. However, project files
-use literal strings instead of names, and the @code{with} clause identifies
-project files rather than packages.
+@item ^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^
+Keep unchanged special form comments
-Each literal string is the file name or path name (absolute or relative) of a
-project file. If a string corresponds to a file name, with no path or a
-relative path, then its location is determined by the @emph{project path}. The
-latter can be queried using @code{gnatls -v}. It contains:
+Reformat comment blocks
-@itemize @bullet
-@item
-In first position, the directory containing the current project file.
-@item
-In last position, the default project directory. This default project directory
-is part of the GNAT installation and is the standard place to install project
-files giving access to standard support libraries.
-@ifclear vms
-@ref{Installing a library}
-@end ifclear
-
-@item
-In between, all the directories referenced in the
-^environment variable^logical name^ @env{ADA_PROJECT_PATH} if it exists.
-@end itemize
+@cindex @option{^-l@var{n}^/CONSTRUCT_LAYOUT^} (@command{gnatpp})
+@item ^-l1^/CONSTRUCT_LAYOUT=GNAT^
+GNAT-style layout (this is the default)
-@noindent
-If a relative pathname is used, as in
+@item ^-l2^/CONSTRUCT_LAYOUT=COMPACT^
+Compact layout
-@smallexample @c projectfile
- with "tests/proj";
-@end smallexample
-
-@noindent
-then the full path for the project is constructed by concatenating this
-relative path to those in the project path, in order, until a matching file is
-found. Any symbolic link will be fully resolved in the directory of the
-importing project file before the imported project file is examined.
-
-If the @code{with}'ed project file name does not have an extension,
-the default is @file{^.gpr^.GPR^}. If a file with this extension is not found,
-then the file name as specified in the @code{with} clause (no extension) will
-be used. In the above example, if a file @code{project1.gpr} is found, then it
-will be used; otherwise, if a file @code{^project1^PROJECT1^} exists
-then it will be used; if neither file exists, this is an error.
-
-A warning is issued if the name of the project file does not match the
-name of the project; this check is case insensitive.
-
-Any source file that is an immediate source of the imported project can be
-used by the immediate sources of the importing project, transitively. Thus
-if @code{A} imports @code{B}, and @code{B} imports @code{C}, the immediate
-sources of @code{A} may depend on the immediate sources of @code{C}, even if
-@code{A} does not import @code{C} explicitly. However, this is not recommended,
-because if and when @code{B} ceases to import @code{C}, some sources in
-@code{A} will no longer compile.
-
-A side effect of this capability is that normally cyclic dependencies are not
-permitted: if @code{A} imports @code{B} (directly or indirectly) then @code{B}
-is not allowed to import @code{A}. However, there are cases when cyclic
-dependencies would be beneficial. For these cases, another form of import
-between projects exists, the @code{limited with}: a project @code{A} that
-imports a project @code{B} with a straight @code{with} may also be imported,
-directly or indirectly, by @code{B} on the condition that imports from @code{B}
-to @code{A} include at least one @code{limited with}.
-
-@smallexample @c 0projectfile
-with "../b/b.gpr";
-with "../c/c.gpr";
-project A is
-end A;
-
-limited with "../a/a.gpr";
-project B is
-end B;
+@item ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^
+Uncompact layout
-with "../d/d.gpr";
-project C is
-end C;
+@cindex @option{^-N^/NOTABS^} (@command{gnatpp})
+@item ^-N^/NOTABS^
+All the VT characters are removed from the comment text. All the HT characters
+are expanded with the sequences of space characters to get to the next tab
+stops.
-limited with "../a/a.gpr";
-project D is
-end D;
-@end smallexample
+@cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp})
+@item ^--no-separate-is^/NO_SEPARATE_IS^
+Do not place the keyword @code{is} on a separate line in a subprogram body in
+case if the spec occupies more then one line.
-@noindent
-In the above legal example, there are two project cycles:
-@itemize @bullet
-@item A-> B-> A
-@item A -> C -> D -> A
-@end itemize
+@cindex @option{^--separate-label^/SEPARATE_LABEL^} (@command{gnatpp})
+@item ^--separate-label^/SEPARATE_LABEL^
+Place statement label(s) on a separate line, with the following statement
+on the next line.
-@noindent
-In each of these cycle there is one @code{limited with}: import of @code{A}
-from @code{B} and import of @code{A} from @code{D}.
+@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
+@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
+Place the keyword @code{loop} in FOR and WHILE loop statements and the
+keyword @code{then} in IF statements on a separate line.
-The difference between straight @code{with} and @code{limited with} is that
-the name of a project imported with a @code{limited with} cannot be used in the
-project that imports it. In particular, its packages cannot be renamed and
-its variables cannot be referred to.
+@cindex @option{^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^} (@command{gnatpp})
+@item ^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^
+Do not place the keyword @code{loop} in FOR and WHILE loop statements and the
+keyword @code{then} in IF statements on a separate line. This option is
+incompatible with @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} option.
-An exception to the above rules for @code{limited with} is that for the main
-project specified to @command{gnatmake} or to the @command{GNAT} driver a
-@code{limited with} is equivalent to a straight @code{with}. For example,
-in the example above, projects @code{B} and @code{D} could not be main
-projects for @command{gnatmake} or to the @command{GNAT} driver, because they
-each have a @code{limited with} that is the only one in a cycle of importing
-projects.
+@cindex @option{^--use-on-new-line^/USE_ON_NEW_LINE^} (@command{gnatpp})
+@item ^--use-on-new-line^/USE_ON_NEW_LINE^
+Start each USE clause in a context clause from a separate line.
-@c *********************
-@c * Project Extension *
-@c *********************
+@cindex @option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^} (@command{gnatpp})
+@item ^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^
+Use a separate line for a loop or block statement name, but do not use an extra
+indentation level for the statement itself.
-@node Project Extension
-@section Project Extension
+@end table
+@ifclear vms
@noindent
-During development of a large system, it is sometimes necessary to use
-modified versions of some of the source files, without changing the original
-sources. This can be achieved through the @emph{project extension} facility.
+The @option{-c1} and @option{-c2} switches are incompatible.
+The @option{-c3} and @option{-c4} switches are compatible with each other and
+also with @option{-c1} and @option{-c2}. The @option{-c0} switch disables all
+the other comment formatting switches.
-@smallexample @c projectfile
- project Modified_Utilities extends "/baseline/utilities.gpr" is @dots{}
-@end smallexample
+The @option{-l1}, @option{-l2}, and @option{-l3} switches are incompatible.
+@end ifclear
+@ifset vms
@noindent
-A project extension declaration introduces an extending project
-(the @emph{child}) and a project being extended (the @emph{parent}).
-
-By default, a child project inherits all the sources of its parent.
-However, inherited sources can be overridden: a unit in a parent is hidden
-by a unit of the same name in the child.
+For the @option{/COMMENTS_LAYOUT} qualifier:
+@itemize @bullet
+@item
+The @option{DEFAULT} and @option{STANDARD_INDENT} options are incompatible.
+@item
+The @option{GNAT_BEGINNING} and @option{REFORMAT} options are compatible with
+each other and also with @option{DEFAULT} and @option{STANDARD_INDENT}.
+@end itemize
-Inherited sources are considered to be sources (but not immediate sources)
-of the child project; see @ref{Project File Syntax}.
+@noindent
+The @option{GNAT}, @option{COMPACT}, and @option{UNCOMPACT} options for the
+@option{/CONSTRUCT_LAYOUT} qualifier are incompatible.
+@end ifset
-An inherited source file retains any switches specified in the parent project.
+@node General Text Layout Control
+@subsection General Text Layout Control
-For example if the project @code{Utilities} contains the spec and the
-body of an Ada package @code{Util_IO}, then the project
-@code{Modified_Utilities} can contain a new body for package @code{Util_IO}.
-The original body of @code{Util_IO} will not be considered in program builds.
-However, the package spec will still be found in the project
-@code{Utilities}.
+@noindent
+These switches allow control over line length and indentation.
-A child project can have only one parent, except when it is qualified as
-abstract. But it may import any number of other projects.
+@table @option
+@item ^-M@var{nnn}^/LINE_LENGTH_MAX=@var{nnn}^
+@cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp})
+Maximum line length, @var{nnn} from 32@dots{}256, the default value is 79
-A project is not allowed to import directly or indirectly at the same time a
-child project and any of its ancestors.
+@item ^-i@var{nnn}^/INDENTATION_LEVEL=@var{nnn}^
+@cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp})
+Indentation level, @var{nnn} from 1@dots{}9, the default value is 3
-@c *******************************
-@c * Project Hierarchy Extension *
-@c *******************************
+@item ^-cl@var{nnn}^/CONTINUATION_INDENT=@var{nnn}^
+@cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp})
+Indentation level for continuation lines (relative to the line being
+continued), @var{nnn} from 1@dots{}9.
+The default
+value is one less then the (normal) indentation level, unless the
+indentation is set to 1 (in which case the default value for continuation
+line indentation is also 1)
+@end table
-@node Project Hierarchy Extension
-@section Project Hierarchy Extension
+@node Other Formatting Options
+@subsection Other Formatting Options
@noindent
-When extending a large system spanning multiple projects, it is often
-inconvenient to extend every project in the hierarchy that is impacted by a
-small change introduced. In such cases, it is possible to create a virtual
-extension of entire hierarchy using @code{extends all} relationship.
-
-When the project is extended using @code{extends all} inheritance, all projects
-that are imported by it, both directly and indirectly, are considered virtually
-extended. That is, the Project Manager creates "virtual projects"
-that extend every project in the hierarchy; all these virtual projects have
-no sources of their own and have as object directory the object directory of
-the root of "extending all" project.
+These switches control the inclusion of missing end/exit labels, and
+the indentation level in @b{case} statements.
-It is possible to explicitly extend one or more projects in the hierarchy
-in order to modify the sources. These extending projects must be imported by
-the "extending all" project, which will replace the corresponding virtual
-projects with the explicit ones.
+@table @option
+@item ^-e^/NO_MISSED_LABELS^
+@cindex @option{^-e^/NO_MISSED_LABELS^} (@command{gnatpp})
+Do not insert missing end/exit labels. An end label is the name of
+a construct that may optionally be repeated at the end of the
+construct's declaration;
+e.g., the names of packages, subprograms, and tasks.
+An exit label is the name of a loop that may appear as target
+of an exit statement within the loop.
+By default, @command{gnatpp} inserts these end/exit labels when
+they are absent from the original source. This option suppresses such
+insertion, so that the formatted source reflects the original.
-When building such a project hierarchy extension, the Project Manager will
-ensure that both modified sources and sources in virtual extending projects
-that depend on them, are recompiled.
+@item ^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^
+@cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp})
+Insert a Form Feed character after a pragma Page.
-By means of example, consider the following hierarchy of projects.
+@item ^-T@var{nnn}^/MAX_INDENT=@var{nnn}^
+@cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp})
+Do not use an additional indentation level for @b{case} alternatives
+and variants if there are @var{nnn} or more (the default
+value is 10).
+If @var{nnn} is 0, an additional indentation level is
+used for @b{case} alternatives and variants regardless of their number.
+@end table
-@enumerate
-@item
-project A, containing package P1
-@item
-project B importing A and containing package P2 which depends on P1
-@item
-project C importing B and containing package P3 which depends on P2
-@end enumerate
+@node Setting the Source Search Path
+@subsection Setting the Source Search Path
@noindent
-We want to modify packages P1 and P3.
+To define the search path for the input source file, @command{gnatpp}
+uses the same switches as the GNAT compiler, with the same effects.
-This project hierarchy will need to be extended as follows:
+@table @option
+@item ^-I^/SEARCH=^@var{dir}
+@cindex @option{^-I^/SEARCH^} (@code{gnatpp})
+The same as the corresponding gcc switch
-@enumerate
-@item
-Create project A1 that extends A, placing modified P1 there:
+@item ^-I-^/NOCURRENT_DIRECTORY^
+@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatpp})
+The same as the corresponding gcc switch
-@smallexample @c 0projectfile
-project A1 extends "(@dots{})/A" is
-end A1;
-@end smallexample
+@item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE^=@var{path}
+@cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@code{gnatpp})
+The same as the corresponding gcc switch
-@item
-Create project C1 that "extends all" C and imports A1, placing modified
-P3 there:
+@item ^--RTS^/RUNTIME_SYSTEM^=@var{path}
+@cindex @option{^--RTS^/RUNTIME_SYSTEM^} (@code{gnatpp})
+The same as the corresponding gcc switch
-@smallexample @c 0projectfile
-with "(@dots{})/A1";
-project C1 extends all "(@dots{})/C" is
-end C1;
-@end smallexample
-@end enumerate
+@end table
+
+@node Output File Control
+@subsection Output File Control
+
+@noindent
+By default the output is sent to the file whose name is obtained by appending
+the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file
+(if the file with this name already exists, it is unconditionally overwritten).
+Thus if the input file is @file{^my_ada_proc.adb^MY_ADA_PROC.ADB^} then
+@command{gnatpp} will produce @file{^my_ada_proc.adb.pp^MY_ADA_PROC.ADB$PP^}
+as output file.
+The output may be redirected by the following switches:
-When you build project C1, your entire modified project space will be
-recompiled, including the virtual project B1 that has been impacted by the
-"extending all" inheritance of project C.
+@table @option
+@item ^-pipe^/STANDARD_OUTPUT^
+@cindex @option{^-pipe^/STANDARD_OUTPUT^} (@code{gnatpp})
+Send the output to @code{Standard_Output}
-Note that if a Library Project in the hierarchy is virtually extended,
-the virtual project that extends the Library Project is not a Library Project.
+@item ^-o @var{output_file}^/OUTPUT=@var{output_file}^
+@cindex @option{^-o^/OUTPUT^} (@code{gnatpp})
+Write the output into @var{output_file}.
+If @var{output_file} already exists, @command{gnatpp} terminates without
+reading or processing the input file.
-@c ****************************************
-@c * External References in Project Files *
-@c ****************************************
+@item ^-of ^/FORCED_OUTPUT=^@var{output_file}
+@cindex @option{^-of^/FORCED_OUTPUT^} (@code{gnatpp})
+Write the output into @var{output_file}, overwriting the existing file
+(if one is present).
-@node External References in Project Files
-@section External References in Project Files
+@item ^-r^/REPLACE^
+@cindex @option{^-r^/REPLACE^} (@code{gnatpp})
+Replace the input source file with the reformatted output, and copy the
+original input source into the file whose name is obtained by appending the
+^@file{.npp}^@file{$NPP}^ suffix to the name of the input file.
+If a file with this name already exists, @command{gnatpp} terminates without
+reading or processing the input file.
-@noindent
-A project file may contain references to external variables; such references
-are called @emph{external references}.
+@item ^-rf^/OVERRIDING_REPLACE^
+@cindex @option{^-rf^/OVERRIDING_REPLACE^} (@code{gnatpp})
+Like @option{^-r^/REPLACE^} except that if the file with the specified name
+already exists, it is overwritten.
-An external variable is either defined as part of the environment (an
-environment variable in Unix, for example) or else specified on the command
-line via the @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch.
-If both, then the command line value is used.
+@item ^-rnb^/REPLACE_NO_BACKUP^
+@cindex @option{^-rnb^/REPLACE_NO_BACKUP^} (@code{gnatpp})
+Replace the input source file with the reformatted output without
+creating any backup copy of the input source.
-The value of an external reference is obtained by means of the built-in
-function @code{external}, which returns a string value.
-This function has two forms:
+@item ^--eol=@var{xxx}^/END_OF_LINE=@var{xxx}^
+@cindex @option{^--eol^/END_OF_LINE^} (@code{gnatpp})
+Specifies the format of the reformatted output file. The @var{xxx}
+^string specified with the switch^option^ may be either
@itemize @bullet
-@item @code{external (external_variable_name)}
-@item @code{external (external_variable_name, default_value)}
+@item ``@option{^dos^DOS^}'' MS DOS style, lines end with CR LF characters
+@item ``@option{^crlf^CRLF^}''
+the same as @option{^crlf^CRLF^}
+@item ``@option{^unix^UNIX^}'' UNIX style, lines end with LF character
+@item ``@option{^lf^LF^}''
+the same as @option{^unix^UNIX^}
@end itemize
-@noindent
-Each parameter must be a string literal. For example:
-
-@smallexample @c projectfile
- external ("USER")
- external ("OS", "GNU/Linux")
-@end smallexample
+@item ^-W^/RESULT_ENCODING=^@var{e}
+@cindex @option{^-W^/RESULT_ENCODING=^} (@command{gnatpp})
+Specify the wide character encoding method used to write the code in the
+result file
+@var{e} is one of the following:
-@noindent
-In the form with one parameter, the function returns the value of
-the external variable given as parameter. If this name is not present in the
-environment, the function returns an empty string.
+@itemize @bullet
-In the form with two string parameters, the second argument is
-the value returned when the variable given as the first argument is not
-present in the environment. In the example above, if @code{"OS"} is not
-the name of ^an environment variable^a logical name^ and is not passed on
-the command line, then the returned value is @code{"GNU/Linux"}.
+@item ^h^HEX^
+Hex encoding
-An external reference may be part of a string expression or of a string
-list expression, and can therefore appear in a variable declaration or
-an attribute declaration.
+@item ^u^UPPER^
+Upper half encoding
-@smallexample @c projectfile
-@group
- type Mode_Type is ("Debug", "Release");
- Mode : Mode_Type := external ("MODE");
- case Mode is
- when "Debug" =>
- @dots{}
-@end group
-@end smallexample
+@item ^s^SHIFT_JIS^
+Shift/JIS encoding
-@c *****************************
-@c * Packages in Project Files *
-@c *****************************
+@item ^e^EUC^
+EUC encoding
-@node Packages in Project Files
-@section Packages in Project Files
+@item ^8^UTF8^
+UTF-8 encoding
-@noindent
-A @emph{package} defines the settings for project-aware tools within a
-project.
-For each such tool one can declare a package; the names for these
-packages are preset (@pxref{Packages}).
-A package may contain variable declarations, attribute declarations, and case
-constructions.
+@item ^b^BRACKETS^
+Brackets encoding (default value)
+@end itemize
-@smallexample @c projectfile
-@group
- project Proj is
- package Builder is -- used by gnatmake
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-v^-v^",
- "^-g^-g^");
- end Builder;
- end Proj;
-@end group
-@end smallexample
+@end table
@noindent
-The syntax of package declarations mimics that of package in Ada.
-
-Most of the packages have an attribute
-@code{^Default_Switches^Default_Switches^}.
-This attribute is an associative array, and its value is a string list.
-The index of the associative array is the name of a programming language (case
-insensitive). This attribute indicates the ^switch^switch^
-or ^switches^switches^ to be used
-with the corresponding tool.
-
-Some packages also have another attribute, @code{^Switches^Switches^},
-an associative array whose value is a string list.
-The index is the name of a source file.
-This attribute indicates the ^switch^switch^
-or ^switches^switches^ to be used by the corresponding
-tool when dealing with this specific file.
+Options @option{^-pipe^/STANDARD_OUTPUT^},
+@option{^-o^/OUTPUT^} and
+@option{^-of^/FORCED_OUTPUT^} are allowed only if the call to gnatpp
+contains only one file to reformat.
+Option
+@option{^--eol^/END_OF_LINE^}
+and
+@option{^-W^/RESULT_ENCODING^}
+cannot be used together
+with @option{^-pipe^/STANDARD_OUTPUT^} option.
-Further information on these ^switch^switch^-related attributes is found in
-@ref{^Switches^Switches^ and Project Files}.
+@node Other gnatpp Switches
+@subsection Other @code{gnatpp} Switches
-A package may be declared as a @emph{renaming} of another package; e.g., from
-the project file for an imported project.
+@noindent
+The additional @command{gnatpp} switches are defined in this subsection.
-@smallexample @c projectfile
-@group
- with "/global/apex.gpr";
- project Example is
- package Naming renames Apex.Naming;
- @dots{}
- end Example;
-@end group
-@end smallexample
+@table @option
+@item ^-files @var{filename}^/FILES=@var{filename}^
+@cindex @option{^-files^/FILES^} (@code{gnatpp})
+Take the argument source files from the specified file. This file should be an
+ordinary text file containing file names separated by spaces or
+line breaks. You can use this switch more than once in the same call to
+@command{gnatpp}. You also can combine this switch with an explicit list of
+files.
-@noindent
-Packages that are renamed in other project files often come from project files
-that have no sources: they are just used as templates. Any modification in the
-template will be reflected automatically in all the project files that rename
-a package from the template.
+@item ^-v^/VERBOSE^
+@cindex @option{^-v^/VERBOSE^} (@code{gnatpp})
+Verbose mode;
+@command{gnatpp} generates version information and then
+a trace of the actions it takes to produce or obtain the ASIS tree.
+
+@item ^-w^/WARNINGS^
+@cindex @option{^-w^/WARNINGS^} (@code{gnatpp})
+Warning mode;
+@command{gnatpp} generates a warning whenever it cannot provide
+a required layout in the result source.
+@end table
+
+@node Formatting Rules
+@section Formatting Rules
-In addition to the tool-oriented packages, you can also declare a package
-named @code{Naming} to establish specialized source file naming conventions
-(@pxref{Naming Schemes}).
+@noindent
+The following subsections show how @command{gnatpp} treats ``white space'',
+comments, program layout, and name casing.
+They provide the detailed descriptions of the switches shown above.
-@c ************************************
-@c * Variables from Imported Projects *
-@c ************************************
+@menu
+* White Space and Empty Lines::
+* Formatting Comments::
+* Construct Layout::
+* Name Casing::
+@end menu
-@node Variables from Imported Projects
-@section Variables from Imported Projects
+@node White Space and Empty Lines
+@subsection White Space and Empty Lines
@noindent
-An attribute or variable defined in an imported or parent project can
-be used in expressions in the importing / extending project.
-Such an attribute or variable is denoted by an expanded name whose prefix
-is either the name of the project or the expanded name of a package within
-a project.
+@command{gnatpp} does not have an option to control space characters.
+It will add or remove spaces according to the style illustrated by the
+examples in the @cite{Ada Reference Manual}.
-@smallexample @c projectfile
-@group
- with "imported";
- project Main extends "base" is
- Var1 := Imported.Var;
- Var2 := Base.Var & ".new";
-@end group
+The only format effectors
+(see @cite{Ada Reference Manual}, paragraph 2.1(13))
+that will appear in the output file are platform-specific line breaks,
+and also format effectors within (but not at the end of) comments.
+In particular, each horizontal tab character that is not inside
+a comment will be treated as a space and thus will appear in the
+output file as zero or more spaces depending on
+the reformatting of the line in which it appears.
+The only exception is a Form Feed character, which is inserted after a
+pragma @code{Page} when @option{-ff} is set.
-@group
- package Builder is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use Imported.Builder'Ada_^Switches^Switches^ &
- "^-gnatg^-gnatg^" &
- "^-v^-v^";
- end Builder;
-@end group
+The output file will contain no lines with trailing ``white space'' (spaces,
+format effectors).
-@group
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use Base.Compiler'Ada_^Switches^Switches^;
- end Compiler;
- end Main;
-@end group
-@end smallexample
+Empty lines in the original source are preserved
+only if they separate declarations or statements.
+In such contexts, a
+sequence of two or more empty lines is replaced by exactly one empty line.
+Note that a blank line will be removed if it separates two ``comment blocks''
+(a comment block is a sequence of whole-line comments).
+In order to preserve a visual separation between comment blocks, use an
+``empty comment'' (a line comprising only hyphens) rather than an empty line.
+Likewise, if for some reason you wish to have a sequence of empty lines,
+use a sequence of empty comments instead.
-@noindent
-In this example:
+@node Formatting Comments
+@subsection Formatting Comments
+@noindent
+Comments in Ada code are of two kinds:
@itemize @bullet
@item
-The value of @code{Var1} is a copy of the variable @code{Var} defined
-in the project file @file{"imported.gpr"}
-@item
-the value of @code{Var2} is a copy of the value of variable @code{Var}
-defined in the project file @file{base.gpr}, concatenated with @code{".new"}
-@item
-attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package
-@code{Builder} is a string list that includes in its value a copy of the value
-of @code{Ada_^Switches^Switches^} defined in the @code{Builder} package
-in project file @file{imported.gpr} plus two new elements:
-@option{"^-gnatg^-gnatg^"}
-and @option{"^-v^-v^"};
+a @emph{whole-line comment}, which appears by itself (possibly preceded by
+``white space'') on a line
+
@item
-attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package
-@code{Compiler} is a copy of the variable @code{Ada_^Switches^Switches^}
-defined in the @code{Compiler} package in project file @file{base.gpr},
-the project being extended.
+an @emph{end-of-line comment}, which follows some other Ada lexical element
+on the same line.
@end itemize
-@c ******************
-@c * Naming Schemes *
-@c ******************
-
-@node Naming Schemes
-@section Naming Schemes
-
@noindent
-Sometimes an Ada software system is ported from a foreign compilation
-environment to GNAT, and the file names do not use the default GNAT
-conventions. Instead of changing all the file names (which for a variety
-of reasons might not be possible), you can define the relevant file
-naming scheme in the @code{Naming} package in your project file.
+The indentation of a whole-line comment is that of either
+the preceding or following line in
+the formatted source, depending on switch settings as will be described below.
-@noindent
-Note that the use of pragmas described in
-@ref{Alternative File Naming Schemes} by mean of a configuration
-pragmas file is not supported when using project files. You must use
-the features described in this paragraph. You can however use specify
-other configuration pragmas (@pxref{Specifying Configuration Pragmas}).
+For an end-of-line comment, @command{gnatpp} leaves the same number of spaces
+between the end of the preceding Ada lexical element and the beginning
+of the comment as appear in the original source,
+unless either the comment has to be split to
+satisfy the line length limitation, or else the next line contains a
+whole line comment that is considered a continuation of this end-of-line
+comment (because it starts at the same position).
+In the latter two
+cases, the start of the end-of-line comment is moved right to the nearest
+multiple of the indentation level.
+This may result in a ``line overflow'' (the right-shifted comment extending
+beyond the maximum line length), in which case the comment is split as
+described below.
-@ifclear vms
-For example, the following
-package models the Apex file naming rules:
+There is a difference between @option{^-c1^/COMMENTS_LAYOUT=DEFAULT^}
+(GNAT-style comment line indentation)
+and @option{^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^}
+(reference-manual comment line indentation).
+With reference-manual style, a whole-line comment is indented as if it
+were a declaration or statement at the same place
+(i.e., according to the indentation of the preceding line(s)).
+With GNAT style, a whole-line comment that is immediately followed by an
+@b{if} or @b{case} statement alternative, a record variant, or the reserved
+word @b{begin}, is indented based on the construct that follows it.
-@smallexample @c projectfile
-@group
- package Naming is
- for Casing use "lowercase";
- for Dot_Replacement use ".";
- for Spec_Suffix ("Ada") use ".1.ada";
- for Body_Suffix ("Ada") use ".2.ada";
- end Naming;
-@end group
+For example:
+@smallexample @c ada
+@cartouche
+if A then
+ null;
+ -- some comment
+else
+ null;
+end if;
+@end cartouche
@end smallexample
-@end ifclear
-@ifset vms
-For example, the following package models the HP Ada file naming rules:
+@noindent
+Reference-manual indentation produces:
-@smallexample @c projectfile
-@group
- package Naming is
- for Casing use "lowercase";
- for Dot_Replacement use "__";
- for Spec_Suffix ("Ada") use "_.^ada^ada^";
- for Body_Suffix ("Ada") use ".^ada^ada^";
- end Naming;
-@end group
+@smallexample @c ada
+@cartouche
+if A then
+ null;
+ -- some comment
+else
+ null;
+end if;
+@end cartouche
@end smallexample
@noindent
-(Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file
-names in lower case)
-@end ifset
-
-@noindent
-You can define the following attributes in package @code{Naming}:
-
-@table @code
+while GNAT-style indentation produces:
-@item @code{Casing}
-This must be a string with one of the three values @code{"lowercase"},
-@code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive.
+@smallexample @c ada
+@cartouche
+if A then
+ null;
+-- some comment
+else
+ null;
+end if;
+@end cartouche
+@end smallexample
@noindent
-If @code{Casing} is not specified, then the default is @code{"lowercase"}.
-
-@item @code{Dot_Replacement}
-This must be a string whose value satisfies the following conditions:
+The @option{^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^} switch
+(GNAT style comment beginning) has the following
+effect:
@itemize @bullet
-@item It must not be empty
-@item It cannot start or end with an alphanumeric character
-@item It cannot be a single underscore
-@item It cannot start with an underscore followed by an alphanumeric
-@item It cannot contain a dot @code{'.'} except if the entire string
-is @code{"."}
+@item
+For each whole-line comment that does not end with two hyphens,
+@command{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.
@end itemize
@noindent
-If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
-
-@item @code{Spec_Suffix}
-This is an associative array (indexed by the programming language name, case
-insensitive) whose value is a string that must satisfy the following
-conditions:
+For an end-of-line comment, if in the original source the next line is a
+whole-line comment that starts at the same position
+as the end-of-line comment,
+then the whole-line comment (and all whole-line comments
+that follow it and that start at the same position)
+will start at this position in the output file.
-@itemize @bullet
-@item It must not be empty
-@item It must include at least one dot
-@end itemize
@noindent
-If @code{Spec_Suffix ("Ada")} is not specified, then the default is
-@code{"^.ads^.ADS^"}.
+That is, if in the original source we have:
-@item @code{Body_Suffix}
-This is an associative array (indexed by the programming language name, case
-insensitive) whose value is a string that must satisfy the following
-conditions:
+@smallexample @c ada
+@cartouche
+begin
+A := B + C; -- B must be in the range Low1..High1
+ -- C must be in the range Low2..High2
+ --B+C will be in the range Low1+Low2..High1+High2
+X := X + 1;
+@end cartouche
+@end smallexample
-@itemize @bullet
-@item It must not be empty
-@item It must include at least one dot
-@item It cannot be the same as @code{Spec_Suffix ("Ada")}
-@end itemize
@noindent
-If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
-same string, then a file name that ends with the longest of these two suffixes
-will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec
-if the longest suffix is @code{Spec_Suffix ("Ada")}.
-
-If the suffix does not start with a '.', a file with a name exactly equal
-to the suffix will also be part of the project (for instance if you define
-the suffix as @code{Makefile}, a file called @file{Makefile} will be part
-of the project. This is not interesting in general when using projects to
-compile. However, it might become useful when a project is also used to
-find the list of source files in an editor, like the GNAT Programming System
-(GPS).
-
-If @code{Body_Suffix ("Ada")} is not specified, then the default is
-@code{"^.adb^.ADB^"}.
+Then in the formatted source we get
-@item @code{Separate_Suffix}
-This must be a string whose value satisfies the same conditions as
-@code{Body_Suffix}. The same "longest suffix" rules apply.
+@smallexample @c ada
+@cartouche
+begin
+ A := B + C; -- B must be in the range Low1..High1
+ -- C must be in the range Low2..High2
+ -- B+C will be in the range Low1+Low2..High1+High2
+ X := X + 1;
+@end cartouche
+@end smallexample
@noindent
-If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same
-value as @code{Body_Suffix ("Ada")}.
+A comment that exceeds the line length limit will be split.
+Unless switch
+@option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} (reformat comment blocks) is set and
+the line belongs to a reformattable block, splitting the line generates a
+@command{gnatpp} warning.
+The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that whole-line
+comments may be reformatted in typical
+word processor style (that is, moving words between lines and putting as
+many words in a line as possible).
-@item @code{Spec}
@noindent
-You can use the associative array attribute @code{Spec} to define
-the source file name for an individual Ada compilation unit's spec. The array
-index must be a string literal that identifies the Ada unit (case insensitive).
-The value of this attribute must be a string that identifies the file that
-contains this unit's spec (case sensitive or insensitive depending on the
-operating system).
-
-@smallexample @c projectfile
- for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
-@end smallexample
-
-When the source file contains several units, you can indicate at what
-position the unit occurs in the file, with the following. The first unit
-in the file has index 1
-
-@smallexample @c projectfile
- for Body ("top") use "foo.a" at 1;
- for Body ("foo") use "foo.a" at 2;
-@end smallexample
-
-@item @code{Body}
+The @option{^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^} switch specifies, that comments
+that has a special format (that is, a character that is neither a letter nor digit
+not white space nor line break immediately following the leading @code{--} of
+the comment) should be without any change moved from the argument source
+into reformatted source. This switch allows to preserve comments that are used
+as a special marks in the code (e.g.@: SPARK annotation).
-You can use the associative array attribute @code{Body} to
-define the source file name for an individual Ada compilation unit's body
-(possibly a subunit). The array index must be a string literal that identifies
-the Ada unit (case insensitive). The value of this attribute must be a string
-that identifies the file that contains this unit's body or subunit (case
-sensitive or insensitive depending on the operating system).
+@node Construct Layout
+@subsection Construct Layout
-@smallexample @c projectfile
- for Body ("MyPack.MyChild") use "mypack.mychild.body";
-@end smallexample
-@end table
+@noindent
+In several cases the suggested layout in the Ada Reference Manual includes
+an extra level of indentation that many programmers prefer to avoid. The
+affected cases include:
-@c ********************
-@c * Library Projects *
-@c ********************
-
-@node Library Projects
-@section Library Projects
-
-@noindent
-@emph{Library projects} are projects whose object code is placed in a library.
-(Note that this facility is not yet supported on all platforms).
-
-@code{gnatmake} or @code{gprbuild} will collect all object files into a
-single archive, which might either be a shared or a static library. This
-library can later on be linked with multiple executables, potentially
-reducing their sizes.
-
-If your project file specifies languages other than Ada, but you are still
-using @code{gnatmake} to compile and link, the latter will not try to
-compile your sources other than Ada (you should use @code{gprbuild} if that
-is your intent). However, @code{gnatmake} will automatically link all object
-files found in the object directory, whether or not they were compiled from
-an Ada source file. This specific behavior only applies when multiple
-languages are specified.
-
-To create a library project, you need to define in its project file
-two project-level attributes: @code{Library_Name} and @code{Library_Dir}.
-Additionally, you may define other library-related attributes such as
-@code{Library_Kind}, @code{Library_Version}, @code{Library_Interface},
-@code{Library_Auto_Init}, @code{Library_Options} and @code{Library_GCC}.
-
-The @code{Library_Name} attribute has a string value. There is no restriction
-on the name of a library. It is the responsibility of the developer to
-choose a name that will be accepted by the platform. It is recommended to
-choose names that could be Ada identifiers; such names are almost guaranteed
-to be acceptable on all platforms.
-
-The @code{Library_Dir} attribute has a string value that designates the path
-(absolute or relative) of the directory where the library will reside.
-It must designate an existing directory, and this directory must be writable,
-different from the project's object directory and from any source directory
-in the project tree.
-
-If both @code{Library_Name} and @code{Library_Dir} are specified and
-are legal, then the project file defines a library project. The optional
-library-related attributes are checked only for such project files.
-
-The @code{Library_Kind} attribute has a string value that must be one of the
-following (case insensitive): @code{"static"}, @code{"dynamic"} or
-@code{"relocatable"} (which is a synonym for @code{"dynamic"}). If this
-attribute is not specified, the library is a static library, that is
-an archive of object files that can be potentially linked into a
-static executable. Otherwise, the library may be dynamic or
-relocatable, that is a library that is loaded only at the start of execution.
-
-If you need to build both a static and a dynamic library, you should use two
-different object directories, since in some cases some extra code needs to
-be generated for the latter. For such cases, it is recommended to either use
-two different project files, or a single one which uses external variables
-to indicate what kind of library should be build.
-
-The @code{Library_ALI_Dir} attribute may be specified to indicate the
-directory where the ALI files of the library will be copied. When it is
-not specified, the ALI files are copied to the directory specified in
-attribute @code{Library_Dir}. The directory specified by @code{Library_ALI_Dir}
-must be writable and different from the project's object directory and from
-any source directory in the project tree.
-
-The @code{Library_Version} attribute has a string value whose interpretation
-is platform dependent. It has no effect on VMS and Windows. On Unix, it is
-used only for dynamic/relocatable libraries as the internal name of the
-library (the @code{"soname"}). If the library file name (built from the
-@code{Library_Name}) is different from the @code{Library_Version}, then the
-library file will be a symbolic link to the actual file whose name will be
-@code{Library_Version}.
-
-Example (on Unix):
+@itemize @bullet
-@smallexample @c projectfile
-@group
-project Plib is
+@item Record type declaration (RM 3.8)
- Version := "1";
+@item Record representation clause (RM 13.5.1)
- for Library_Dir use "lib_dir";
- for Library_Name use "dummy";
- for Library_Kind use "relocatable";
- for Library_Version use "libdummy.so." & Version;
+@item Loop statement in case if a loop has a statement identifier (RM 5.6)
-end Plib;
-@end group
-@end smallexample
+@item Block statement in case if a block has a statement identifier (RM 5.6)
+@end itemize
@noindent
-Directory @file{lib_dir} will contain the internal library file whose name
-will be @file{libdummy.so.1}, and @file{libdummy.so} will be a symbolic link to
-@file{libdummy.so.1}.
+In compact mode (when GNAT style layout or compact layout is set),
+the pretty printer uses one level of indentation instead
+of two. This is achieved in the record definition and record representation
+clause cases by putting the @code{record} keyword on the same line as the
+start of the declaration or representation clause, and in the block and loop
+case by putting the block or loop header on the same line as the statement
+identifier.
-When @command{gnatmake} detects that a project file
-is a library project file, it will check all immediate sources of the project
-and rebuild the library if any of the sources have been recompiled.
+@noindent
+The difference between GNAT style @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^}
+and compact @option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^}
+layout on the one hand, and uncompact layout
+@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} on the other hand,
+can be illustrated by the following examples:
-Standard project files can import library project files. In such cases,
-the libraries will only be rebuilt if some of its sources are recompiled
-because they are in the closure of some other source in an importing project.
-Sources of the library project files that are not in such a closure will
-not be checked, unless the full library is checked, because one of its sources
-needs to be recompiled.
+@iftex
+@cartouche
+@multitable @columnfractions .5 .5
+@item @i{GNAT style, compact layout} @tab @i{Uncompact layout}
-For instance, assume the project file @code{A} imports the library project file
-@code{L}. The immediate sources of A are @file{a1.adb}, @file{a2.ads} and
-@file{a2.adb}. The immediate sources of L are @file{l1.ads}, @file{l1.adb},
-@file{l2.ads}, @file{l2.adb}.
+@item
+@smallexample @c ada
+type q is record
+ a : integer;
+ b : integer;
+end record;
+@end smallexample
+@tab
+@smallexample @c ada
+type q is
+ record
+ a : integer;
+ b : integer;
+ end record;
+@end smallexample
-If @file{l1.adb} has been modified, then the library associated with @code{L}
-will be rebuilt when compiling all the immediate sources of @code{A} only
-if @file{a1.ads}, @file{a2.ads} or @file{a2.adb} includes a statement
-@code{"with L1;"}.
+@item
+@smallexample @c ada
+for q use record
+ a at 0 range 0 .. 31;
+ b at 4 range 0 .. 31;
+end record;
+@end smallexample
+@tab
+@smallexample @c ada
+for q use
+ record
+ a at 0 range 0 .. 31;
+ b at 4 range 0 .. 31;
+ end record;
+@end smallexample
-To be sure that all the sources in the library associated with @code{L} are
-up to date, and that all the sources of project @code{A} are also up to date,
-the following two commands needs to be used:
+@item
+@smallexample @c ada
+Block : declare
+ A : Integer := 3;
+begin
+ Proc (A, A);
+end Block;
+@end smallexample
+@tab
+@smallexample @c ada
+Block :
+ declare
+ A : Integer := 3;
+ begin
+ Proc (A, A);
+ end Block;
+@end smallexample
-@smallexample
-gnatmake -Pl.gpr
-gnatmake -Pa.gpr
+@item
+@smallexample @c ada
+Clear : for J in 1 .. 10 loop
+ A (J) := 0;
+end loop Clear;
+@end smallexample
+@tab
+@smallexample @c ada
+Clear :
+ for J in 1 .. 10 loop
+ A (J) := 0;
+ end loop Clear;
@end smallexample
+@end multitable
+@end cartouche
+@end iftex
-When a library is built or rebuilt, an attempt is made first to delete all
-files in the library directory.
-All @file{ALI} files will also be copied from the object directory to the
-library directory. To build executables, @command{gnatmake} will use the
-library rather than the individual object files.
+@ifnottex
+@smallexample
+@cartouche
+GNAT style, compact layout Uncompact layout
-@ifclear vms
-It is also possible to create library project files for third-party libraries
-that are precompiled and cannot be compiled locally thanks to the
-@code{externally_built} attribute. (See @ref{Installing a library}).
-@end ifclear
+type q is record type q is
+ a : integer; record
+ b : integer; a : integer;
+end record; b : integer;
+ end record;
-@c *******************************
-@c * Stand-alone Library Projects *
-@c *******************************
+for q use record for q use
+ a at 0 range 0 .. 31; record
+ b at 4 range 0 .. 31; a at 0 range 0 .. 31;
+end record; b at 4 range 0 .. 31;
+ end record;
-@node Stand-alone Library Projects
-@section Stand-alone Library Projects
+Block : declare Block :
+ A : Integer := 3; declare
+begin A : Integer := 3;
+ Proc (A, A); begin
+end Block; Proc (A, A);
+ end Block;
-@noindent
-A Stand-alone Library is a library that contains the necessary code to
-elaborate the Ada units that are included in the library. A Stand-alone
-Library is suitable to be used in an executable when the main is not
-in Ada. However, Stand-alone Libraries may also be used with an Ada main
-subprogram.
+Clear : for J in 1 .. 10 loop Clear :
+ A (J) := 0; for J in 1 .. 10 loop
+end loop Clear; A (J) := 0;
+ end loop Clear;
+@end cartouche
+@end smallexample
+@end ifnottex
-A Stand-alone Library Project is a Library Project where the library is
-a Stand-alone Library.
+@noindent
+A further difference between GNAT style layout and compact layout is that
+GNAT style layout inserts empty lines as separation for
+compound statements, return statements and bodies.
-To be a Stand-alone Library Project, in addition to the two attributes
-that make a project a Library Project (@code{Library_Name} and
-@code{Library_Dir}, see @ref{Library Projects}), the attribute
-@code{Library_Interface} must be defined.
+Note that the layout specified by
+@option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^}
+for named block and loop statements overrides the layout defined by these
+constructs by @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^},
+@option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} or
+@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} option.
-@smallexample @c projectfile
-@group
- for Library_Dir use "lib_dir";
- for Library_Name use "dummy";
- for Library_Interface use ("int1", "int1.child");
-@end group
-@end smallexample
+@node Name Casing
+@subsection Name Casing
-Attribute @code{Library_Interface} has a nonempty string list value,
-each string in the list designating a unit contained in an immediate source
-of the project file.
+@noindent
+@command{gnatpp} always converts the usage occurrence of a (simple) name to
+the same casing as the corresponding defining identifier.
-When a Stand-alone Library is built, first the binder is invoked to build
-a package whose name depends on the library name
-(^b~dummy.ads/b^B$DUMMY.ADS/B^ in the example above).
-This binder-generated package includes initialization and
-finalization procedures whose
-names depend on the library name (dummyinit and dummyfinal in the example
-above). The object corresponding to this package is included in the library.
+You control the casing for defining occurrences via the
+@option{^-n^/NAME_CASING^} switch.
+@ifclear vms
+With @option{-nD} (``as declared'', which is the default),
+@end ifclear
+@ifset vms
+With @option{/NAME_CASING=AS_DECLARED}, which is the default,
+@end ifset
+defining occurrences appear exactly as in the source file
+where they are declared.
+The other ^values for this switch^options for this qualifier^ ---
+@option{^-nU^UPPER_CASE^},
+@option{^-nL^LOWER_CASE^},
+@option{^-nM^MIXED_CASE^} ---
+result in
+^upper, lower, or mixed case, respectively^the corresponding casing^.
+If @command{gnatpp} changes the casing of a defining
+occurrence, it analogously changes the casing of all the
+usage occurrences of this name.
-A dynamic or relocatable Stand-alone Library is automatically initialized
-if automatic initialization of Stand-alone Libraries is supported on the
-platform and if attribute @code{Library_Auto_Init} is not specified or
-is specified with the value "true". A static Stand-alone Library is never
-automatically initialized.
+If the defining occurrence of a name is not in the source compilation unit
+currently being processed by @command{gnatpp}, the casing of each reference to
+this name is changed according to the value of the @option{^-n^/NAME_CASING^}
+switch (subject to the dictionary file mechanism described below).
+Thus @command{gnatpp} acts as though the @option{^-n^/NAME_CASING^} switch
+had affected the
+casing for the defining occurrence of the name.
-Single string attribute @code{Library_Auto_Init} may be specified with only
-two possible values: "false" or "true" (case-insensitive). Specifying
-"false" for attribute @code{Library_Auto_Init} will prevent automatic
-initialization of dynamic or relocatable libraries.
+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
+@emph{dictionary file},
+and then supplying a @option{^-D^/DICTIONARY^} switch.
+The casing of names from dictionary files overrides
+any @option{^-n^/NAME_CASING^} switch.
-When a non-automatically initialized Stand-alone Library is used
-in an executable, its initialization procedure must be called before
-any service of the library is used.
-When the main subprogram is in Ada, it may mean that the initialization
-procedure has to be called during elaboration of another package.
+To handle the casing of Ada predefined names and the names from GNAT libraries,
+@command{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 @cite{Ada Reference Manual}.
+The name of each entity in the GNAT libraries is spelled with the same casing
+as is used in the declaration of that entity.
-For a Stand-Alone Library, only the @file{ALI} files of the Interface Units
-(those that are listed in attribute @code{Library_Interface}) are copied to
-the Library Directory. As a consequence, only the Interface Units may be
-imported from Ada units outside of the library. If other units are imported,
-the binding phase will fail.
+The @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of the
+default dictionary file.
+Instead, the casing for predefined and GNAT-defined names will be established
+by the @option{^-n^/NAME_CASING^} switch or explicit dictionary files.
+For example, by default the names @code{Ada.Text_IO} and @code{GNAT.OS_Lib}
+will appear as just shown,
+even in the presence of a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch.
+To ensure that even such names are rendered in uppercase,
+additionally supply the @w{@option{^-D-^/SPECIFIC_CASING^}} switch
+(or else, less conveniently, place these names in upper case in a dictionary
+file).
-When a Stand-Alone Library is bound, the switches that are specified in
-the attribute @code{Default_Switches ("Ada")} in package @code{Binder} are
-used in the call to @command{gnatbind}.
+A dictionary file is
+a plain text file; each line in this file can be either a blank line
+(containing only space characters and ASCII.HT characters), an Ada comment
+line, or the specification of exactly one @emph{casing schema}.
-The string list attribute @code{Library_Options} may be used to specified
-additional switches to the call to @command{gcc} to link the library.
+A casing schema is a string that has the following syntax:
-The attribute @code{Library_Src_Dir}, may be specified for a
-Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
-single string value. Its value must be the path (absolute or relative to the
-project directory) of an existing directory. This directory cannot be the
-object directory or one of the source directories, but it can be the same as
-the library directory. The sources of the Interface
-Units of the library, necessary to an Ada client of the library, will be
-copied to the designated directory, called Interface Copy directory.
-These sources includes the specs of the Interface Units, but they may also
-include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
-are used, or when there is a generic units in the spec. Before the sources
-are copied to the Interface Copy directory, an attempt is made to delete all
-files in the Interface Copy directory.
+@smallexample
+@cartouche
+ @var{casing_schema} ::= @var{identifier} | *@var{simple_identifier}*
-@c *************************************
-@c * Switches Related to Project Files *
-@c *************************************
-@node Switches Related to Project Files
-@section Switches Related to Project Files
+ @var{simple_identifier} ::= @var{letter}@{@var{letter_or_digit}@}
+@end cartouche
+@end smallexample
@noindent
-The following switches are used by GNAT tools that support project files:
+(See @cite{Ada Reference Manual}, Section 2.3) for the definition of the
+@var{identifier} lexical element and the @var{letter_or_digit} category.)
-@table @option
+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.
-@item ^-P^/PROJECT_FILE=^@var{project}
-@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
-Indicates the name of a project file. This project file will be parsed with
-the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
-if any, and using the external references indicated
-by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any.
+If a dictionary file is passed as
@ifclear vms
-There may zero, one or more spaces between @option{-P} and @var{project}.
+the value of a @option{-D@var{file}} switch
@end ifclear
+@ifset vms
+an option to the @option{/DICTIONARY} qualifier
+@end ifset
+then for every
+simple name and every identifier, @command{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):
-@noindent
-There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line.
+@itemize @bullet
+@item
+if the whole name is in the dictionary, @command{gnatpp} uses for this name
+the casing defined by the dictionary; no subwords are checked for this word
-@noindent
-Since the Project Manager parses the project file only after all the switches
-on the command line are checked, the order of the switches
-@option{^-P^/PROJECT_FILE^},
-@option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}}
-or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
+@item
+for every subword @command{gnatpp} checks if the dictionary contains the
+corresponding string of the form @code{*@var{simple_identifier}*},
+and if it does, the casing of this @var{simple_identifier} is used
+for this subword
-@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
-@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
-Indicates that external variable @var{name} has the value @var{value}.
-The Project Manager will use this value for occurrences of
-@code{external(name)} when parsing the project file.
+@item
+if the whole name does not contain any ``_'' inside, and if for this name
+the dictionary contains two entries - one of the form @var{identifier},
+and another - of the form *@var{simple_identifier}*, then the first one
+is applied to define the casing of this name
-@ifclear vms
-@noindent
-If @var{name} or @var{value} includes a space, then @var{name=value} should be
-put between quotes.
-@smallexample
- -XOS=NT
- -X"user=John Doe"
-@end smallexample
-@end ifclear
+@item
+if more than one dictionary file is passed as @command{gnatpp} switches, each
+dictionary adds new casing exceptions and overrides all the existing casing
+exceptions set by the previous dictionaries
-@noindent
-Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously.
-If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same
-@var{name}, only the last one is used.
+@item
+when @command{gnatpp} checks if the word or subword is in the dictionary,
+this check is not case sensitive
+@end itemize
@noindent
-An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch
-takes precedence over the value of the same name in the environment.
+For example, suppose we have the following source to reformat:
-@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
-@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
-Indicates the verbosity of the parsing of GNAT project files.
+@smallexample @c ada
+@cartouche
+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;
+@end cartouche
+@end smallexample
-@ifclear vms
-@option{-vP0} means Default;
-@option{-vP1} means Medium;
-@option{-vP2} means High.
-@end ifclear
+@noindent
+And suppose we have two dictionaries:
-@ifset vms
-There are three possible options for this qualifier: DEFAULT, MEDIUM and
-HIGH.
-@end ifset
+@smallexample
+@cartouche
+@i{dict1:}
+ NAME1
+ *NaMe3*
+ *Name1*
+@end cartouche
-@noindent
-The default is ^Default^DEFAULT^: no output for syntactically correct
-project files.
-@noindent
-If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
-only the last one is used.
+@cartouche
+@i{dict2:}
+ *NAME3*
+@end cartouche
+@end smallexample
-@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
-@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
-Add directory <dir> at the beginning of the project search path, in order,
-after the current working directory.
+@noindent
+If @command{gnatpp} is called with the following switches:
+@smallexample
@ifclear vms
-@item -eL
-@cindex @option{-eL} (any project-aware tool)
-Follow all symbolic links when processing project files.
+@command{gnatpp -nM -D dict1 -D dict2 test.adb}
@end ifclear
-
-@item ^--subdirs^/SUBDIRS^=<subdir>
-@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
-This switch is recognized by gnatmake and gnatclean. It indicate that the real
-directories (except the source directories) are the subdirectories <subdir>
-of the directories specified in the project files. This applies in particular
-to object directories, library directories and exec directories. If the
-subdirectories do not exist, they are created automatically.
-
-@end table
-
-@c **********************************
-@c * Tools Supporting Project Files *
-@c **********************************
-
-@node Tools Supporting Project Files
-@section Tools Supporting Project Files
-
-@menu
-* gnatmake and Project Files::
-* The GNAT Driver and Project Files::
-@end menu
-
-@node gnatmake and Project Files
-@subsection gnatmake and Project Files
+@ifset vms
+@command{gnatpp test.adb /NAME_CASING=MIXED_CASE /DICTIONARY=(dict1, dict2)}
+@end ifset
+@end smallexample
@noindent
-This section covers several topics related to @command{gnatmake} and
-project files: defining ^switches^switches^ for @command{gnatmake}
-and for the tools that it invokes; specifying configuration pragmas;
-the use of the @code{Main} attribute; building and rebuilding library project
-files.
-
-@menu
-* ^Switches^Switches^ and Project Files::
-* Specifying Configuration Pragmas::
-* Project Files and Main Subprograms::
-* Library Project Files::
-@end menu
+then we will get the following name casing in the @command{gnatpp} output:
-@node ^Switches^Switches^ and Project Files
-@subsubsection ^Switches^Switches^ and Project Files
+@smallexample @c ada
+@cartouche
+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;
+@end cartouche
+@end smallexample
-@ifset vms
-It is not currently possible to specify VMS style qualifiers in the project
-files; only Unix style ^switches^switches^ may be specified.
-@end ifset
+@c *********************************
+@node The GNAT Metric Tool gnatmetric
+@chapter The GNAT Metric Tool @command{gnatmetric}
+@findex gnatmetric
+@cindex Metric tool
@noindent
-For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and
-@code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^}
-attribute, a @code{^Switches^Switches^} attribute, or both;
-as their names imply, these ^switch^switch^-related
-attributes affect the ^switches^switches^ that are used for each of these GNAT
-components when
-@command{gnatmake} is invoked. As will be explained below, these
-component-specific ^switches^switches^ precede
-the ^switches^switches^ provided on the @command{gnatmake} command line.
+^The @command{gnatmetric} tool^@command{GNAT METRIC}^ is an ASIS-based utility
+for computing various program metrics.
+It takes an Ada source file as input and generates a file containing the
+metrics data as output. Various switches control which
+metrics are computed and output.
-The @code{^Default_Switches^Default_Switches^} attribute is an associative
-array indexed by language name (case insensitive) whose value is a string list.
-For example:
+@command{gnatmetric} generates and uses the ASIS
+tree for the input source and thus requires the input to be syntactically and
+semantically legal.
+If this condition is not met, @command{gnatmetric} will generate
+an error message; no metric information for this file will be
+computed and reported.
-@smallexample @c projectfile
-@group
-package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnaty^-gnaty^",
- "^-v^-v^");
-end Compiler;
-@end group
-@end smallexample
+If the compilation unit contained in the input source depends semantically
+upon units in files located outside the current directory, you have to provide
+the source search path when invoking @command{gnatmetric}.
+If it depends semantically upon units that are contained
+in files with names that do not follow the GNAT file naming rules, you have to
+provide the configuration file describing the corresponding naming scheme (see
+the description of the @command{gnatmetric} switches below.)
+Alternatively, you may use a project file and invoke @command{gnatmetric}
+through the @command{gnat} driver.
-@noindent
-The @code{^Switches^Switches^} attribute is also an associative array,
-indexed by a file name (which may or may not be case sensitive, depending
-on the operating system) whose value is a string list. For example:
+The @command{gnatmetric} command has the form
-@smallexample @c projectfile
-@group
-package Builder is
- for ^Switches^Switches^ ("main1.adb")
- use ("^-O2^-O2^");
- for ^Switches^Switches^ ("main2.adb")
- use ("^-g^-g^");
-end Builder;
-@end group
+@smallexample
+@c $ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatmetric @r{[}@var{switches}@r{]} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
-For the @code{Builder} package, the file names must designate source files
-for main subprograms. For the @code{Binder} and @code{Linker} packages, the
-file names must designate @file{ALI} or source files for main subprograms.
-In each case just the file name without an explicit extension is acceptable.
-
-For each tool used in a program build (@command{gnatmake}, the compiler, the
-binder, and the linker), the corresponding package @dfn{contributes} a set of
-^switches^switches^ for each file on which the tool is invoked, based on the
-^switch^switch^-related attributes defined in the package.
-In particular, the ^switches^switches^
-that each of these packages contributes for a given file @var{f} comprise:
-
+where
@itemize @bullet
@item
-the value of attribute @code{^Switches^Switches^ (@var{f})},
-if it is specified in the package for the given file,
-@item
-otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")},
-if it is specified in the package.
-@end itemize
-
-@noindent
-If neither of these attributes is defined in the package, then the package does
-not contribute any ^switches^switches^ for the given file.
-
-When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise
-two sets, in the following order: those contributed for the file
-by the @code{Builder} package;
-and the switches passed on the command line.
-
-When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file,
-the ^switches^switches^ passed to the tool comprise three sets,
-in the following order:
+@var{switches} specify the metrics to compute and define the destination for
+the output
-@enumerate
@item
-the applicable ^switches^switches^ contributed for the file
-by the @code{Builder} package in the project file supplied on the command line;
+Each @var{filename} is the name (including the extension) of a source
+file to process. ``Wildcards'' are allowed, and
+the file name may contain path information.
+If no @var{filename} is supplied, then the @var{switches} list must contain
+at least one
+@option{-files} switch (@pxref{Other gnatmetric Switches}).
+Including both a @option{-files} switch and one or more
+@var{filename} arguments is permitted.
@item
-those contributed for the file by the package (in the relevant project file --
-see below) corresponding to the tool; and
+@samp{@var{gcc_switches}} is a list of switches for
+@command{gcc}. They will be passed on to all compiler invocations made by
+@command{gnatmetric} to generate the ASIS trees. Here you can provide
+@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
+and use the @option{-gnatec} switch to set the configuration file,
+use the @option{-gnat05} switch if sources should be compiled in
+Ada 2005 mode etc.
+@end itemize
-@item
-the applicable switches passed on the command line.
-@end enumerate
+@menu
+* Switches for gnatmetric::
+@end menu
-@noindent
-The term @emph{applicable ^switches^switches^} reflects the fact that
-@command{gnatmake} ^switches^switches^ may or may not be passed to individual
-tools, depending on the individual ^switch^switch^.
+@node Switches for gnatmetric
+@section Switches for @command{gnatmetric}
-@command{gnatmake} may invoke the compiler on source files from different
-projects. The Project Manager will use the appropriate project file to
-determine the @code{Compiler} package for each source file being compiled.
-Likewise for the @code{Binder} and @code{Linker} packages.
+@noindent
+The following subsections describe the various switches accepted by
+@command{gnatmetric}, organized by category.
-As an example, consider the following package in a project file:
+@menu
+* Output Files Control::
+* Disable Metrics For Local Units::
+* Specifying a set of metrics to compute::
+* Other gnatmetric Switches::
+* Generate project-wide metrics::
+@end menu
-@smallexample @c projectfile
-@group
-project Proj1 is
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-g^-g^");
- for ^Switches^Switches^ ("a.adb")
- use ("^-O1^-O1^");
- for ^Switches^Switches^ ("b.adb")
- use ("^-O2^-O2^",
- "^-gnaty^-gnaty^");
- end Compiler;
-end Proj1;
-@end group
-@end smallexample
+@node Output Files Control
+@subsection Output File Control
+@cindex Output file control in @command{gnatmetric}
@noindent
-If @command{gnatmake} is invoked with this project file, and it needs to
-compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then
-@file{a.adb} will be compiled with the ^switch^switch^
-@option{^-O1^-O1^},
-@file{b.adb} with ^switches^switches^
-@option{^-O2^-O2^}
-and @option{^-gnaty^-gnaty^},
-and @file{c.adb} with @option{^-g^-g^}.
-
-The following example illustrates the ordering of the ^switches^switches^
-contributed by different packages:
-
-@smallexample @c projectfile
-@group
-project Proj2 is
- package Builder is
- for ^Switches^Switches^ ("main.adb")
- use ("^-g^-g^",
- "^-O1^-)1^",
- "^-f^-f^");
- end Builder;
-@end group
+@command{gnatmetric} has two output formats. It can generate a
+textual (human-readable) form, and also XML. By default only textual
+output is generated.
-@group
- package Compiler is
- for ^Switches^Switches^ ("main.adb")
- use ("^-O2^-O2^");
- end Compiler;
-end Proj2;
-@end group
-@end smallexample
+When generating the output in textual form, @command{gnatmetric} creates
+for each Ada source file a corresponding text file
+containing the computed metrics, except for the case when the set of metrics
+specified by gnatmetric parameters consists only of metrics that are computed
+for the whole set of analyzed sources, but not for each Ada source.
+By default, this file is placed in the same directory as where the source
+file is located, and its name is obtained
+by appending the ^@file{.metrix}^@file{$METRIX}^ suffix to the name of the
+input file.
-@noindent
-If you issue the command:
+All the output information generated in XML format is placed in a single
+file. By default this file is placed in the current directory and has the
+name ^@file{metrix.xml}^@file{METRIX$XML}^.
-@smallexample
- gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main
-@end smallexample
+Some of the computed metrics are summed over the units passed to
+@command{gnatmetric}; for example, the total number of lines of code.
+By default this information is sent to @file{stdout}, but a file
+can be specified with the @option{-og} switch.
-@noindent
-then the compiler will be invoked on @file{main.adb} with the following
-sequence of ^switches^switches^
+The following switches control the @command{gnatmetric} output:
-@smallexample
- ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^
-@end smallexample
+@table @option
+@cindex @option{^-x^/XML^} (@command{gnatmetric})
+@item ^-x^/XML^
+Generate the XML output
-with the last @option{^-O^-O^}
-^switch^switch^ having precedence over the earlier ones;
-several other ^switches^switches^
-(such as @option{^-c^-c^}) are added implicitly.
+@cindex @option{^-xs^/XSD^} (@command{gnatmetric})
+@item ^-xs^/XSD^
+Generate the XML output and the XML schema file that describes the structure
+of the XML metric report, this schema is assigned to the XML file. The schema
+file has the same name as the XML output file with @file{.xml} suffix replaced
+with @file{.xsd}
-The ^switches^switches^
-@option{^-g^-g^}
-and @option{^-O1^-O1^} are contributed by package
-@code{Builder}, @option{^-O2^-O2^} is contributed
-by the package @code{Compiler}
-and @option{^-O0^-O0^} comes from the command line.
+@cindex @option{^-nt^/NO_TEXT^} (@command{gnatmetric})
+@item ^-nt^/NO_TEXT^
+Do not generate the output in text form (implies @option{^-x^/XML^})
-The @option{^-g^-g^}
-^switch^switch^ will also be passed in the invocation of
-@command{Gnatlink.}
+@cindex @option{^-d^/DIRECTORY^} (@command{gnatmetric})
+@item ^-d @var{output_dir}^/DIRECTORY=@var{output_dir}^
+Put text files with detailed metrics into @var{output_dir}
-A final example illustrates switch contributions from packages in different
-project files:
+@cindex @option{^-o^/SUFFIX_DETAILS^} (@command{gnatmetric})
+@item ^-o @var{file_suffix}^/SUFFIX_DETAILS=@var{file_suffix}^
+Use @var{file_suffix}, instead of ^@file{.metrix}^@file{$METRIX}^
+in the name of the output file.
-@smallexample @c projectfile
-@group
-project Proj3 is
- for Source_Files use ("pack.ads", "pack.adb");
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnata^-gnata^");
- end Compiler;
-end Proj3;
-@end group
+@cindex @option{^-og^/GLOBAL_OUTPUT^} (@command{gnatmetric})
+@item ^-og @var{file_name}^/GLOBAL_OUTPUT=@var{file_name}^
+Put global metrics into @var{file_name}
-@group
-with "Proj3";
-project Proj4 is
- for Source_Files use ("foo_main.adb", "bar_main.adb");
- package Builder is
- for ^Switches^Switches^ ("foo_main.adb")
- use ("^-s^-s^",
- "^-g^-g^");
- end Builder;
-end Proj4;
-@end group
+@cindex @option{^-ox^/XML_OUTPUT^} (@command{gnatmetric})
+@item ^-ox @var{file_name}^/XML_OUTPUT=@var{file_name}^
+Put the XML output into @var{file_name} (also implies @option{^-x^/XML^})
-@group
--- Ada source file:
-with Pack;
-procedure Foo_Main is
- @dots{}
-end Foo_Main;
-@end group
-@end smallexample
+@cindex @option{^-sfn^/SHORT_SOURCE_FILE_NAME^} (@command{gnatmetric})
+@item ^-sfn^/SHORT_SOURCE_FILE_NAME^
+Use ``short'' source file names in the output. (The @command{gnatmetric}
+output includes the name(s) of the Ada source file(s) from which the metrics
+are computed. By default each name includes the absolute path. The
+@option{^-sfn^/SHORT_SOURCE_FILE_NAME^} switch causes @command{gnatmetric}
+to exclude all directory information from the file names that are output.)
-If the command is
-@smallexample
-gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato
-@end smallexample
+@end table
-@noindent
-then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are
-@option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and
-@option{^-gnato^-gnato^} (passed on the command line).
-When the imported package @code{Pack} is compiled, the ^switches^switches^ used
-are @option{^-g^-g^} from @code{Proj4.Builder},
-@option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler},
-and @option{^-gnato^-gnato^} from the command line.
+@node Disable Metrics For Local Units
+@subsection Disable Metrics For Local Units
+@cindex Disable Metrics For Local Units in @command{gnatmetric}
@noindent
-When using @command{gnatmake} with project files, some ^switches^switches^ or
-arguments may be expressed as relative paths. As the working directory where
-compilation occurs may change, these relative paths are converted to absolute
-paths. For the ^switches^switches^ found in a project file, the relative paths
-are relative to the project file directory, for the switches on the command
-line, they are relative to the directory where @command{gnatmake} is invoked.
-The ^switches^switches^ for which this occurs are:
-^-I^-I^,
-^-A^-A^,
-^-L^-L^,
-^-aO^-aO^,
-^-aL^-aL^,
-^-aI^-aI^, as well as all arguments that are not switches (arguments to
-^switch^switch^
-^-o^-o^, object files specified in package @code{Linker} or after
--largs on the command line). The exception to this rule is the ^switch^switch^
-^--RTS=^--RTS=^ for which a relative path argument is never converted.
-
-@node Specifying Configuration Pragmas
-@subsubsection Specifying Configuration Pragmas
+@command{gnatmetric} relies on the GNAT compilation model @minus{}
+one compilation
+unit per one source file. It computes line metrics for the whole source
+file, and it also computes syntax
+and complexity metrics for the file's outermost unit.
-When using @command{gnatmake} with project files, if there exists a file
-@file{gnat.adc} that contains configuration pragmas, this file will be
-ignored.
+By default, @command{gnatmetric} will also compute all metrics for certain
+kinds of locally declared program units:
-Configuration pragmas can be defined by means of the following attributes in
-project files: @code{Global_Configuration_Pragmas} in package @code{Builder}
-and @code{Local_Configuration_Pragmas} in package @code{Compiler}.
+@itemize @bullet
+@item
+subprogram (and generic subprogram) bodies;
-Both these attributes are single string attributes. Their values is the path
-name of a file containing configuration pragmas. If a path name is relative,
-then it is relative to the project directory of the project file where the
-attribute is defined.
+@item
+package (and generic package) specs and bodies;
-When compiling a source, the configuration pragmas used are, in order,
-those listed in the file designated by attribute
-@code{Global_Configuration_Pragmas} in package @code{Builder} of the main
-project file, if it is specified, and those listed in the file designated by
-attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of
-the project file of the source, if it exists.
+@item
+task object and type specifications and bodies;
-@node Project Files and Main Subprograms
-@subsubsection Project Files and Main Subprograms
-
-@noindent
-When using a project file, you can invoke @command{gnatmake}
-with one or several main subprograms, by specifying their source files on the
-command line.
-
-@smallexample
- gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3
-@end smallexample
+@item
+protected object and type specifications and bodies.
+@end itemize
@noindent
-Each of these needs to be a source file of the same project, except
-when the switch ^-u^/UNIQUE^ is used.
+These kinds of entities will be referred to as
+@emph{eligible local program units}, or simply @emph{eligible local units},
+@cindex Eligible local unit (for @command{gnatmetric})
+in the discussion below.
-@noindent
-When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the
-same project, one of the project in the tree rooted at the project specified
-on the command line. The package @code{Builder} of this common project, the
-"main project" is the one that is considered by @command{gnatmake}.
+Note that a subprogram declaration, generic instantiation,
+or renaming declaration only receives metrics
+computation when it appear as the outermost entity
+in a source file.
-@noindent
-When ^-u^/UNIQUE^ is used, the specified source files may be in projects
-imported directly or indirectly by the project specified on the command line.
-Note that if such a source file is not part of the project specified on the
-command line, the ^switches^switches^ found in package @code{Builder} of the
-project specified on the command line, if any, that are transmitted
-to the compiler will still be used, not those found in the project file of
-the source file.
+Suppression of metrics computation for eligible local units can be
+obtained via the following switch:
-@noindent
-When using a project file, you can also invoke @command{gnatmake} without
-explicitly specifying any main, and the effect depends on whether you have
-defined the @code{Main} attribute. This attribute has a string list value,
-where each element in the list is the name of a source file (the file
-extension is optional) that contains a unit that can be a main subprogram.
+@table @option
+@cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric})
+@item ^-nolocal^/SUPPRESS=LOCAL_DETAILS^
+Do not compute detailed metrics for eligible local program units
-If the @code{Main} attribute is defined in a project file as a non-empty
-string list and the switch @option{^-u^/UNIQUE^} is not used on the command
-line, then invoking @command{gnatmake} with this project file but without any
-main on the command line is equivalent to invoking @command{gnatmake} with all
-the file names in the @code{Main} attribute on the command line.
+@end table
-Example:
-@smallexample @c projectfile
-@group
- project Prj is
- for Main use ("main1", "main2", "main3");
- end Prj;
-@end group
-@end smallexample
+@node Specifying a set of metrics to compute
+@subsection Specifying a set of metrics to compute
@noindent
-With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"}
-is equivalent to
-@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}.
-
-When the project attribute @code{Main} is not specified, or is specified
-as an empty string list, or when the switch @option{-u} is used on the command
-line, then invoking @command{gnatmake} with no main on the command line will
-result in all immediate sources of the project file being checked, and
-potentially recompiled. Depending on the presence of the switch @option{-u},
-sources from other project files on which the immediate sources of the main
-project file depend are also checked and potentially recompiled. In other
-words, the @option{-u} switch is applied to all of the immediate sources of the
-main project file.
-
-When no main is specified on the command line and attribute @code{Main} exists
-and includes several mains, or when several mains are specified on the
-command line, the default ^switches^switches^ in package @code{Builder} will
-be used for all mains, even if there are specific ^switches^switches^
-specified for one or several mains.
-
-But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be
-the specific ^switches^switches^ for each main, if they are specified.
+By default all the metrics are computed and reported. The switches
+described in this subsection allow you to control, on an individual
+basis, whether metrics are computed and
+reported. If at least one positive metric
+switch is specified (that is, a switch that defines that a given
+metric or set of metrics is to be computed), then only
+explicitly specified metrics are reported.
-@node Library Project Files
-@subsubsection Library Project Files
+@menu
+* Line Metrics Control::
+* Syntax Metrics Control::
+* Complexity Metrics Control::
+* Object-Oriented Metrics Control::
+@end menu
-@noindent
-When @command{gnatmake} is invoked with a main project file that is a library
-project file, it is not allowed to specify one or more mains on the command
-line.
+@node Line Metrics Control
+@subsubsection Line Metrics Control
+@cindex Line metrics control in @command{gnatmetric}
@noindent
-When a library project file is specified, switches ^-b^/ACTION=BIND^ and
-^-l^/ACTION=LINK^ have special meanings.
-
-@itemize @bullet
-@item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
-to @command{gnatmake} that @command{gnatbind} should be invoked for the
-library.
-
-@item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates
-to @command{gnatmake} that the binder generated file should be compiled
-(in the case of a stand-alone library) and that the library should be built.
-
-@end itemize
-
-@node The GNAT Driver and Project Files
-@subsection The GNAT Driver and Project Files
-
-@noindent
-A number of GNAT tools, other than @command{^gnatmake^gnatmake^}
-can benefit from project files:
-@command{^gnatbind^gnatbind^},
-@command{^gnatcheck^gnatcheck^}),
-@command{^gnatclean^gnatclean^}),
-@command{^gnatelim^gnatelim^},
-@command{^gnatfind^gnatfind^},
-@command{^gnatlink^gnatlink^},
-@command{^gnatls^gnatls^},
-@command{^gnatmetric^gnatmetric^},
-@command{^gnatpp^gnatpp^},
-@command{^gnatstub^gnatstub^},
-and @command{^gnatxref^gnatxref^}. However, none of these tools can be invoked
-directly with a project file switch (@option{^-P^/PROJECT_FILE=^}).
-They must be invoked through the @command{gnat} driver.
-
-The @command{gnat} driver is a wrapper that accepts a number of commands and
-calls the corresponding tool. It was designed initially for VMS platforms (to
-convert VMS qualifiers to Unix-style switches), but it is now available on all
-GNAT platforms.
-
-On non-VMS platforms, the @command{gnat} driver accepts the following commands
-(case insensitive):
+For any (legal) source file, and for each of its
+eligible local program units, @command{gnatmetric} computes the following
+metrics:
@itemize @bullet
@item
-BIND to invoke @command{^gnatbind^gnatbind^}
-@item
-CHOP to invoke @command{^gnatchop^gnatchop^}
-@item
-CLEAN to invoke @command{^gnatclean^gnatclean^}
-@item
-COMP or COMPILE to invoke the compiler
-@item
-ELIM to invoke @command{^gnatelim^gnatelim^}
-@item
-FIND to invoke @command{^gnatfind^gnatfind^}
-@item
-KR or KRUNCH to invoke @command{^gnatkr^gnatkr^}
-@item
-LINK to invoke @command{^gnatlink^gnatlink^}
-@item
-LS or LIST to invoke @command{^gnatls^gnatls^}
-@item
-MAKE to invoke @command{^gnatmake^gnatmake^}
-@item
-NAME to invoke @command{^gnatname^gnatname^}
-@item
-PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^}
-@item
-PP or PRETTY to invoke @command{^gnatpp^gnatpp^}
-@item
-METRIC to invoke @command{^gnatmetric^gnatmetric^}
+the total number of lines;
+
@item
-STUB to invoke @command{^gnatstub^gnatstub^}
+the total number of code lines (i.e., non-blank lines that are not comments)
+
@item
-XREF to invoke @command{^gnatxref^gnatxref^}
-@end itemize
+the number of comment lines
-@noindent
-(note that the compiler is invoked using the command
-@command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
+@item
+the number of code lines containing end-of-line comments;
-@noindent
-On non-VMS platforms, between @command{gnat} and the command, two
-special switches may be used:
+@item
+the comment percentage: the ratio between the number of lines that contain
+comments and the number of all non-blank lines, expressed as a percentage;
-@itemize @bullet
@item
-@command{-v} to display the invocation of the tool.
+the number of empty lines and lines containing only space characters and/or
+format effectors (blank lines)
+
@item
-@command{-dn} to prevent the @command{gnat} driver from removing
-the temporary files it has created. These temporary files are
-configuration files and temporary file list files.
+the average number of code lines in subprogram bodies, task bodies, entry
+bodies and statement sequences in package bodies (this metric is only computed
+across the whole set of the analyzed units)
+
@end itemize
@noindent
-The command may be followed by switches and arguments for the invoked
-tool.
+@command{gnatmetric} sums the values of the line metrics for all the
+files being processed and then generates the cumulative results. The tool
+also computes for all the files being processed the average number of code
+lines in bodies.
-@smallexample
- gnat bind -C main.ali
- gnat ls -a main
- gnat chop foo.txt
-@end smallexample
+You can use the following switches to select the specific line metrics
+to be computed and reported.
-@noindent
-Switches may also be put in text files, one switch per line, and the text
-files may be specified with their path name preceded by '@@'.
+@table @option
+@cindex @option{^--lines@var{x}^/LINE_COUNT_METRICS^} (@command{gnatmetric})
-@smallexample
- gnat bind @@args.txt main.ali
-@end smallexample
+@ifclear vms
+@cindex @option{--no-lines@var{x}}
+@end ifclear
-@noindent
-In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
-METRIC, PP or PRETTY, STUB and XREF, the project file related switches
-(@option{^-P^/PROJECT_FILE^},
-@option{^-X^/EXTERNAL_REFERENCE^} and
-@option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to
-the switches of the invoking tool.
+@item ^--lines-all^/LINE_COUNT_METRICS=ALL^
+Report all the line metrics
-@noindent
-When GNAT PP or GNAT PRETTY is used with a project file, but with no source
-specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all
-the immediate sources of the specified project file.
+@item ^--no-lines-all^/LINE_COUNT_METRICS=NONE^
+Do not report any of line metrics
-@noindent
-When GNAT METRIC is used with a project file, but with no source
-specified on the command line, it invokes @command{^gnatmetric^gnatmetric^}
-with all the immediate sources of the specified project file and with
-@option{^-d^/DIRECTORY^} with the parameter pointing to the object directory
-of the project.
+@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES^
+Report the number of all lines
-@noindent
-In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
-a project file, no source is specified on the command line and
-switch ^-U^/ALL_PROJECTS^ is specified on the command line, then
-the underlying tool (^gnatpp^gnatpp^ or
-^gnatmetric^gnatmetric^) is invoked for all sources of all projects,
-not only for the immediate sources of the main project.
-@ifclear vms
-(-U stands for Universal or Union of the project files of the project tree)
-@end ifclear
+@item ^--no-lines^/LINE_COUNT_METRICS=NOALL_LINES^
+Do not report the number of all lines
-@noindent
-For each of the following commands, there is optionally a corresponding
-package in the main project.
+@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES^
+Report the number of code lines
-@itemize @bullet
-@item
-package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^})
+@item ^--no-lines-code^/LINE_COUNT_METRICS=NOCODE_LINES^
+Do not report the number of code lines
-@item
-package @code{Check} for command CHECK (invoking
-@code{^gnatcheck^gnatcheck^})
+@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES^
+Report the number of comment lines
-@item
-package @code{Compiler} for command COMP or COMPILE (invoking the compiler)
+@item ^--no-lines-comment^/LINE_COUNT_METRICS=NOCOMMENT_LINES^
+Do not report the number of comment lines
-@item
-package @code{Cross_Reference} for command XREF (invoking
-@code{^gnatxref^gnatxref^})
+@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES^
+Report the number of code lines containing
+end-of-line comments
-@item
-package @code{Eliminate} for command ELIM (invoking
-@code{^gnatelim^gnatelim^})
+@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=NOCODE_COMMENT_LINES^
+Do not report the number of code lines containing
+end-of-line comments
-@item
-package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^})
+@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE^
+Report the comment percentage in the program text
-@item
-package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^})
+@item ^--no-lines-ratio^/LINE_COUNT_METRICS=NOCOMMENT_PERCENTAGE^
+Do not report the comment percentage in the program text
-@item
-package @code{Gnatstub} for command STUB
-(invoking @code{^gnatstub^gnatstub^})
+@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES^
+Report the number of blank lines
-@item
-package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
+@item ^--no-lines-blank^/LINE_COUNT_METRICS=NOBLANK_LINES^
+Do not report the number of blank lines
-@item
-package @code{Metrics} for command METRIC
-(invoking @code{^gnatmetric^gnatmetric^})
+@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES^
+Report the average number of code lines in subprogram bodies, task bodies,
+entry bodies and statement sequences in package bodies. The metric is computed
+and reported for the whole set of processed Ada sources only.
-@item
-package @code{Pretty_Printer} for command PP or PRETTY
-(invoking @code{^gnatpp^gnatpp^})
+@item ^--no-lines-average^/LINE_COUNT_METRICS=NOAVERAGE_BODY_LINES^
+Do not report the average number of code lines in subprogram bodies,
+task bodies, entry bodies and statement sequences in package bodies.
-@end itemize
+@end table
+
+@node Syntax Metrics Control
+@subsubsection Syntax Metrics Control
+@cindex Syntax metrics control in @command{gnatmetric}
@noindent
-Package @code{Gnatls} has a unique attribute @code{^Switches^Switches^},
-a simple variable with a string list value. It contains ^switches^switches^
-for the invocation of @code{^gnatls^gnatls^}.
+@command{gnatmetric} computes various syntactic metrics for the
+outermost unit and for each eligible local unit:
-@smallexample @c projectfile
-@group
-project Proj1 is
- package gnatls is
- for ^Switches^Switches^
- use ("^-a^-a^",
- "^-v^-v^");
- end gnatls;
-end Proj1;
-@end group
-@end smallexample
+@table @emph
+@item LSLOC (``Logical Source Lines Of Code'')
+The total number of declarations and the total number of statements
-@noindent
-All other packages have two attribute @code{^Switches^Switches^} and
-@code{^Default_Switches^Default_Switches^}.
+@item Maximal static nesting level of inner program units
+According to
+@cite{Ada Reference Manual}, 10.1(1), ``A program unit is either a
+package, a task unit, a protected unit, a
+protected entry, a generic unit, or an explicitly declared subprogram other
+than an enumeration literal.''
-@noindent
-@code{^Switches^Switches^} is an associative array attribute, indexed by the
-source file name, that has a string list value: the ^switches^switches^ to be
-used when the tool corresponding to the package is invoked for the specific
-source file.
+@item Maximal nesting level of composite syntactic constructs
+This corresponds to the notion of the
+maximum nesting level in the GNAT built-in style checks
+(@pxref{Style Checking})
+@end table
@noindent
-@code{^Default_Switches^Default_Switches^} is an associative array attribute,
-indexed by the programming language that has a string list value.
-@code{^Default_Switches^Default_Switches^ ("Ada")} contains the
-^switches^switches^ for the invocation of the tool corresponding
-to the package, except if a specific @code{^Switches^Switches^} attribute
-is specified for the source file.
+For the outermost unit in the file, @command{gnatmetric} additionally computes
+the following metrics:
-@smallexample @c projectfile
-@group
-project Proj is
+@table @emph
+@item Public subprograms
+This metric is computed for package specs. It is the
+number of subprograms and generic subprograms declared in the visible
+part (including the visible part of nested packages, protected objects, and
+protected types).
- for Source_Dirs use ("./**");
+@item All subprograms
+This metric is computed for bodies and subunits. The
+metric is equal to a total number of subprogram bodies in the compilation
+unit.
+Neither generic instantiations nor renamings-as-a-body nor body stubs
+are counted. Any subprogram body is counted, independently of its nesting
+level and enclosing constructs. Generic bodies and bodies of protected
+subprograms are counted in the same way as ``usual'' subprogram bodies.
- package gnatls is
- for ^Switches^Switches^ use
- ("^-a^-a^",
- "^-v^-v^");
- end gnatls;
-@end group
-@group
+@item Public types
+This metric is computed for package specs and
+generic package declarations. It is the total number of types
+that can be referenced from outside this compilation unit, plus the
+number of types from all the visible parts of all the visible generic
+packages. Generic formal types are not counted. Only types, not subtypes,
+are included.
- package Compiler is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-gnatv^-gnatv^",
- "^-gnatwa^-gnatwa^");
- end Binder;
-@end group
-@group
+@noindent
+Along with the total number of public types, the following
+types are counted and reported separately:
- package Binder is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-C^-C^",
- "^-e^-e^");
- end Binder;
-@end group
-@group
+@itemize @bullet
+@item
+Abstract types
- package Linker is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-C^-C^");
- for ^Switches^Switches^ ("main.adb")
- use ("^-C^-C^",
- "^-v^-v^",
- "^-v^-v^");
- end Linker;
-@end group
-@group
+@item
+Root tagged types (abstract, non-abstract, private, non-private). Type
+extensions are @emph{not} counted
- package Finder is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-a^-a^",
- "^-f^-f^");
- end Finder;
-@end group
-@group
+@item
+Private types (including private extensions)
- package Cross_Reference is
- for ^Default_Switches^Default_Switches^ ("Ada")
- use ("^-a^-a^",
- "^-f^-f^",
- "^-d^-d^",
- "^-u^-u^");
- end Cross_Reference;
-end Proj;
-@end group
-@end smallexample
+@item
+Task types
-@noindent
-With the above project file, commands such as
+@item
+Protected types
-@smallexample
- ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^
- ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^
- ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^
- ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^
- ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^
-@end smallexample
+@end itemize
-@noindent
-will set up the environment properly and invoke the tool with the switches
-found in the package corresponding to the tool:
-@code{^Default_Switches^Default_Switches^ ("Ada")} for all tools,
-except @code{^Switches^Switches^ ("main.adb")}
-for @code{^gnatlink^gnatlink^}.
-It is also possible to invoke some of the tools,
-@code{^gnatcheck^gnatcheck^}),
-@code{^gnatmetric^gnatmetric^}),
-and @code{^gnatpp^gnatpp^})
-on a set of project units thanks to the combination of the switches
-@option{-P}, @option{-U} and possibly the main unit when one is interested
-in its closure. For instance,
-@smallexample
-gnat metric -Pproj
-@end smallexample
-will compute the metrics for all the immediate units of project
-@code{proj}.
-@smallexample
-gnat metric -Pproj -U
-@end smallexample
-will compute the metrics for all the units of the closure of projects
-rooted at @code{proj}.
-@smallexample
-gnat metric -Pproj -U main_unit
-@end smallexample
-will compute the metrics for the closure of units rooted at
-@code{main_unit}. This last possibility relies implicitly
-on @command{gnatbind}'s option @option{-R}.
+@item All types
+This metric is computed for any compilation unit. It is equal to the total
+number of the declarations of different types given in the compilation unit.
+The private and the corresponding full type declaration are counted as one
+type declaration. Incomplete type declarations and generic formal types
+are not counted.
+No distinction is made among different kinds of types (abstract,
+private etc.); the total number of types is computed and reported.
-@c **********************
-@node An Extended Example
-@section An Extended Example
+@end table
@noindent
-Suppose that we have two programs, @var{prog1} and @var{prog2},
-whose sources are in corresponding directories. We would like
-to build them with a single @command{gnatmake} command, and we want to place
-their object files into @file{build} subdirectories of the source directories.
-Furthermore, we want to have to have two separate subdirectories
-in @file{build} -- @file{release} and @file{debug} -- which will contain
-the object files compiled with different set of compilation flags.
+By default, all the syntax metrics are computed and reported. You can use the
+following switches to select specific syntax metrics.
-In other words, we have the following structure:
+@table @option
-@smallexample
-@group
- main
- |- prog1
- | |- build
- | | debug
- | | release
- |- prog2
- |- build
- | debug
- | release
-@end group
-@end smallexample
+@cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric})
-@noindent
-Here are the project files that we must place in a directory @file{main}
-to maintain this structure:
+@ifclear vms
+@cindex @option{--no-syntax@var{x}} (@command{gnatmetric})
+@end ifclear
-@enumerate
+@item ^--syntax-all^/SYNTAX_METRICS=ALL^
+Report all the syntax metrics
-@item We create a @code{Common} project with a package @code{Compiler} that
-specifies the compilation ^switches^switches^:
+@item ^--no-syntax-all^/SYNTAX_METRICS=NONE^
+Do not report any of syntax metrics
-@smallexample
-File "common.gpr":
-@group
-@b{project} Common @b{is}
+@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS^
+Report the total number of declarations
- @b{for} Source_Dirs @b{use} (); -- No source files
-@end group
+@item ^--no-declarations^/SYNTAX_METRICS=NODECLARATIONS^
+Do not report the total number of declarations
-@group
- @b{type} Build_Type @b{is} ("release", "debug");
- Build : Build_Type := External ("BUILD", "debug");
-@end group
-@group
- @b{package} Compiler @b{is}
- @b{case} Build @b{is}
- @b{when} "release" =>
- @b{for} ^Default_Switches^Default_Switches^ ("Ada")
- @b{use} ("^-O2^-O2^");
- @b{when} "debug" =>
- @b{for} ^Default_Switches^Default_Switches^ ("Ada")
- @b{use} ("^-g^-g^");
- @b{end case};
- @b{end} Compiler;
-
-@b{end} Common;
-@end group
-@end smallexample
+@item ^--statements^/SYNTAX_METRICS=STATEMENTS^
+Report the total number of statements
-@item We create separate projects for the two programs:
+@item ^--no-statements^/SYNTAX_METRICS=NOSTATEMENTS^
+Do not report the total number of statements
-@smallexample
-@group
-File "prog1.gpr":
+@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS^
+Report the number of public subprograms in a compilation unit
-@b{with} "common";
-@b{project} Prog1 @b{is}
+@item ^--no-public-subprograms^/SYNTAX_METRICS=NOPUBLIC_SUBPROGRAMS^
+Do not report the number of public subprograms in a compilation unit
- @b{for} Source_Dirs @b{use} ("prog1");
- @b{for} Object_Dir @b{use} "prog1/build/" & Common.Build;
+@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS^
+Report the number of all the subprograms in a compilation unit
- @b{package} Compiler @b{renames} Common.Compiler;
+@item ^--no-all-subprograms^/SYNTAX_METRICS=NOALL_SUBPROGRAMS^
+Do not report the number of all the subprograms in a compilation unit
-@b{end} Prog1;
-@end group
-@end smallexample
+@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES^
+Report the number of public types in a compilation unit
-@smallexample
-@group
-File "prog2.gpr":
+@item ^--no-public-types^/SYNTAX_METRICS=NOPUBLIC_TYPES^
+Do not report the number of public types in a compilation unit
-@b{with} "common";
-@b{project} Prog2 @b{is}
+@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES^
+Report the number of all the types in a compilation unit
- @b{for} Source_Dirs @b{use} ("prog2");
- @b{for} Object_Dir @b{use} "prog2/build/" & Common.Build;
+@item ^--no-all-types^/SYNTAX_METRICS=NOALL_TYPES^
+Do not report the number of all the types in a compilation unit
- @b{package} Compiler @b{renames} Common.Compiler;
+@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING^
+Report the maximal program unit nesting level
-@end group
-@b{end} Prog2;
-@end smallexample
+@item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^
+Do not report the maximal program unit nesting level
-@item We create a wrapping project @code{Main}:
+@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING^
+Report the maximal construct nesting level
-@smallexample
-@group
-File "main.gpr":
+@item ^--no-construct-nesting^/SYNTAX_METRICS=NOCONSTRUCT_NESTING^
+Do not report the maximal construct nesting level
-@b{with} "common";
-@b{with} "prog1";
-@b{with} "prog2";
-@b{project} Main @b{is}
+@end table
- @b{package} Compiler @b{renames} Common.Compiler;
+@node Complexity Metrics Control
+@subsubsection Complexity Metrics Control
+@cindex Complexity metrics control in @command{gnatmetric}
-@b{end} Main;
-@end group
-@end smallexample
+@noindent
+For a program unit that is an executable body (a subprogram body (including
+generic bodies), task body, entry body or a package body containing
+its own statement sequence) @command{gnatmetric} computes the following
+complexity metrics:
-@item Finally we need to create a dummy procedure that @code{with}s (either
-explicitly or implicitly) all the sources of our two programs.
+@itemize @bullet
+@item
+McCabe cyclomatic complexity;
-@end enumerate
+@item
+McCabe essential complexity;
-@noindent
-Now we can build the programs using the command
+@item
+maximal loop nesting level
-@smallexample
- gnatmake ^-P^/PROJECT_FILE=^main dummy
-@end smallexample
+@end itemize
@noindent
-for the Debug mode, or
+The McCabe complexity metrics are defined
+in @url{http://www.mccabe.com/pdf/nist235r.pdf}
-@ifclear vms
-@smallexample
- gnatmake -Pmain -XBUILD=release
-@end smallexample
-@end ifclear
+According to McCabe, both control statements and short-circuit control forms
+should be taken into account when computing cyclomatic complexity. For each
+body, we compute three metric values:
-@ifset vms
-@smallexample
- GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release
-@end smallexample
-@end ifset
+@itemize @bullet
+@item
+the complexity introduced by control
+statements only, without taking into account short-circuit forms,
-@noindent
-for the Release mode.
+@item
+the complexity introduced by short-circuit control forms only, and
-@c ********************************
-@c * Project File Complete Syntax *
-@c ********************************
+@item
+the total
+cyclomatic complexity, which is the sum of these two values.
+@end itemize
-@node Project File Complete Syntax
-@section Project File Complete Syntax
+@noindent
+When computing cyclomatic and essential complexity, @command{gnatmetric} skips
+the code in the exception handlers and in all the nested program units.
-@smallexample
-project ::=
- context_clause project_declaration
+By default, all the complexity metrics are computed and reported.
+For more fine-grained control you can use
+the following switches:
-context_clause ::=
- @{with_clause@}
+@table @option
+@cindex @option{^-complexity@var{x}^/COMPLEXITY_METRICS^} (@command{gnatmetric})
-with_clause ::=
- @b{with} path_name @{ , path_name @} ;
+@ifclear vms
+@cindex @option{--no-complexity@var{x}}
+@end ifclear
-path_name ::=
- string_literal
+@item ^--complexity-all^/COMPLEXITY_METRICS=ALL^
+Report all the complexity metrics
-project_declaration ::=
- simple_project_declaration | project_extension
+@item ^--no-complexity-all^/COMPLEXITY_METRICS=NONE^
+Do not report any of complexity metrics
-simple_project_declaration ::=
- @b{project} <project_>simple_name @b{is}
- @{declarative_item@}
- @b{end} <project_>simple_name;
+@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC^
+Report the McCabe Cyclomatic Complexity
-project_extension ::=
- @b{project} <project_>simple_name @b{extends} path_name @b{is}
- @{declarative_item@}
- @b{end} <project_>simple_name;
+@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=NOCYCLOMATIC^
+Do not report the McCabe Cyclomatic Complexity
-declarative_item ::=
- package_declaration |
- typed_string_declaration |
- other_declarative_item
+@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL^
+Report the Essential Complexity
-package_declaration ::=
- package_spec | package_renaming
+@item ^--no-complexity-essential^/COMPLEXITY_METRICS=NOESSENTIAL^
+Do not report the Essential Complexity
-package_spec ::=
- @b{package} package_identifier @b{is}
- @{simple_declarative_item@}
- @b{end} package_identifier ;
+@item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^
+Report maximal loop nesting level
-package_identifier ::=
- @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} |
- @code{Linker} | @code{Finder} | @code{Cross_Reference} |
- @code{^gnatls^gnatls^} | @code{IDE} | @code{Pretty_Printer}
+@item ^--no-loop-nesting^/COMPLEXITY_METRICS=NOLOOP_NESTING^
+Do not report maximal loop nesting level
-package_renaming ::==
- @b{package} package_identifier @b{renames}
- <project_>simple_name.package_identifier ;
+@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY^
+Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
+task bodies, entry bodies and statement sequences in package bodies.
+The metric is computed and reported for whole set of processed Ada sources
+only.
-typed_string_declaration ::=
- @b{type} <typed_string_>_simple_name @b{is}
- ( string_literal @{, string_literal@} );
+@item ^--no-complexity-average^/COMPLEXITY_METRICS=NOAVERAGE_COMPLEXITY^
+Do not report the average McCabe Cyclomatic Complexity for all the subprogram
+bodies, task bodies, entry bodies and statement sequences in package bodies
-other_declarative_item ::=
- attribute_declaration |
- typed_variable_declaration |
- variable_declaration |
- case_construction
+@cindex @option{^-ne^/NO_EXITS_AS_GOTOS^} (@command{gnatmetric})
+@item ^-ne^/NO_EXITS_AS_GOTOS^
+Do not consider @code{exit} statements as @code{goto}s when
+computing Essential Complexity
-attribute_declaration ::=
- full_associative_array_declaration |
- @b{for} attribute_designator @b{use} expression ;
+@item ^--extra-exit-points^/EXTRA_EXIT_POINTS^
+Report the extra exit points for subprogram bodies. As an exit point, this
+metric counts @code{return} statements and raise statements in case when the
+raised exception is not handled in the same body. In case of a function this
+metric subtracts 1 from the number of exit points, because a function body
+must contain at least one @code{return} statement.
-full_associative_array_declaration ::=
- @b{for} <associative_array_attribute_>simple_name @b{use}
- <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ;
+@item ^--no-extra-exit-points^/NOEXTRA_EXIT_POINTS^
+Do not report the extra exit points for subprogram bodies
+@end table
-attribute_designator ::=
- <simple_attribute_>simple_name |
- <associative_array_attribute_>simple_name ( string_literal )
-typed_variable_declaration ::=
- <typed_variable_>simple_name : <typed_string_>name := string_expression ;
+@node Object-Oriented Metrics Control
+@subsubsection Object-Oriented Metrics Control
+@cindex Object-Oriented metrics control in @command{gnatmetric}
-variable_declaration ::=
- <variable_>simple_name := expression;
+@noindent
+@cindex Coupling metrics (in in @command{gnatmetric})
+Coupling metrics are object-oriented metrics that measure the
+dependencies between a given class (or a group of classes) and the
+``external world'' (that is, the other classes in the program). In this
+subsection the term ``class'' is used in its
+traditional object-oriented programming sense
+(an instantiable module that contains data and/or method members).
+A @emph{category} (of classes)
+is a group of closely related classes that are reused and/or
+modified together.
-expression ::=
- term @{& term@}
+A class @code{K}'s @emph{efferent coupling} is the number of classes
+that @code{K} depends upon.
+A category's efferent coupling is the number of classes outside the
+category that the classes inside the category depend upon.
-term ::=
- literal_string |
- string_list |
- <variable_>name |
- external_value |
- attribute_reference
+A class @code{K}'s @emph{afferent coupling} is the number of classes
+that depend upon @code{K}.
+A category's afferent coupling is the number of classes outside the
+category that depend on classes belonging to the category.
-string_literal ::=
- (same as Ada)
+Ada's implementation of the object-oriented paradigm does not use the
+traditional class notion, so the definition of the coupling
+metrics for Ada maps the class and class category notions
+onto Ada constructs.
-string_list ::=
- ( <string_>expression @{ , <string_>expression @} )
+For the coupling metrics, several kinds of modules -- a library package,
+a library generic package, and a library generic package instantiation --
+that define a tagged type or an interface type are
+considered to be a class. A category consists of a library package (or
+a library generic package) that defines a tagged or an interface type,
+together with all its descendant (generic) packages that define tagged
+or interface types. For any package counted as a class,
+its body and subunits (if any) are considered
+together with its spec when counting the dependencies, and coupling
+metrics are reported for spec units only. For dependencies
+between classes, the Ada semantic dependencies are considered.
+For coupling metrics, only dependencies on units that are considered as
+classes, are considered.
-external_value ::=
- @b{external} ( string_literal [, string_literal] )
+When computing coupling metrics, @command{gnatmetric} counts only
+dependencies between units that are arguments of the gnatmetric call.
+Coupling metrics are program-wide (or project-wide) metrics, so to
+get a valid result, you should call @command{gnatmetric} for
+the whole set of sources that make up your program. It can be done
+by calling @command{gnatmetric} from the GNAT driver with @option{-U}
+option (see See @ref{The GNAT Driver and Project Files} for details.
-attribute_reference ::=
- attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ]
+By default, all the coupling metrics are disabled. You can use the following
+switches to specify the coupling metrics to be computed and reported:
-attribute_prefix ::=
- @b{project} |
- <project_>simple_name | package_identifier |
- <project_>simple_name . package_identifier
+@table @option
-case_construction ::=
- @b{case} <typed_variable_>name @b{is}
- @{case_item@}
- @b{end case} ;
+@ifclear vms
+@cindex @option{--package@var{x}} (@command{gnatmetric})
+@cindex @option{--no-package@var{x}} (@command{gnatmetric})
+@cindex @option{--category@var{x}} (@command{gnatmetric})
+@cindex @option{--no-category@var{x}} (@command{gnatmetric})
+@end ifclear
-case_item ::=
- @b{when} discrete_choice_list =>
- @{case_construction | attribute_declaration@}
+@ifset vms
+@cindex @option{/COUPLING_METRICS} (@command{gnatmetric})
+@end ifset
-discrete_choice_list ::=
- string_literal @{| string_literal@} |
- @b{others}
+@item ^--coupling-all^/COUPLING_METRICS=ALL^
+Report all the coupling metrics
-name ::=
- simple_name @{. simple_name@}
+@item ^--no-coupling-all^/COUPLING_METRICS=NONE^
+Do not report any of metrics
-simple_name ::=
- identifier (same as Ada)
+@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT^
+Report package efferent coupling
-@end smallexample
+@item ^--no-package-efferent-coupling^/COUPLING_METRICS=NOPACKAGE_EFFERENT^
+Do not report package efferent coupling
-@node The Cross-Referencing Tools gnatxref and gnatfind
-@chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
-@findex gnatxref
-@findex gnatfind
+@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT^
+Report package afferent coupling
-@noindent
-The compiler generates cross-referencing information (unless
-you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files.
-This information indicates where in the source each entity is declared and
-referenced. Note that entities in package Standard are not included, but
-entities in all other predefined units are included in the output.
-
-Before using any of these two tools, you need to compile successfully your
-application, so that GNAT gets a chance to generate the cross-referencing
-information.
+@item ^--no-package-afferent-coupling^/COUPLING_METRICS=NOPACKAGE_AFFERENT^
+Do not report package afferent coupling
-The two tools @code{gnatxref} and @code{gnatfind} take advantage of this
-information to provide the user with the capability to easily locate the
-declaration and references to an entity. These tools are quite similar,
-the difference being that @code{gnatfind} is intended for locating
-definitions and/or references to a specified entity or entities, whereas
-@code{gnatxref} is oriented to generating a full report of all
-cross-references.
+@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT^
+Report category efferent coupling
-To use these tools, you must not compile your application using the
-@option{-gnatx} switch on the @command{gnatmake} command line
-(@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing
-information will not be generated.
+@item ^--no-category-efferent-coupling^/COUPLING_METRICS=NOCATEGORY_EFFERENT^
+Do not report category efferent coupling
-Note: to invoke @code{gnatxref} or @code{gnatfind} with a project file,
-use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}).
+@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT^
+Report category afferent coupling
-@menu
-* gnatxref Switches::
-* gnatfind Switches::
-* Project Files for gnatxref and gnatfind::
-* Regular Expressions in gnatfind and gnatxref::
-* Examples of gnatxref Usage::
-* Examples of gnatfind Usage::
-@end menu
+@item ^--no-category-afferent-coupling^/COUPLING_METRICS=NOCATEGORY_AFFERENT^
+Do not report category afferent coupling
-@node gnatxref Switches
-@section @code{gnatxref} Switches
+@end table
-@noindent
-The command invocation for @code{gnatxref} is:
-@smallexample
-$ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
-@end smallexample
+@node Other gnatmetric Switches
+@subsection Other @code{gnatmetric} Switches
@noindent
-where
+Additional @command{gnatmetric} switches are as follows:
-@table @var
-@item sourcefile1
-@itemx sourcefile2
-identifies the source files for which a report is to be generated. The
-``with''ed units will be processed too. You must provide at least one file.
+@table @option
+@item ^-files @var{filename}^/FILES=@var{filename}^
+@cindex @option{^-files^/FILES^} (@code{gnatmetric})
+Take the argument source files from the specified file. This file should be an
+ordinary text file containing file names separated by spaces or
+line breaks. You can use this switch more than once in the same call to
+@command{gnatmetric}. You also can combine this switch with
+an explicit list of files.
-These file names are considered to be regular expressions, so for instance
-specifying @file{source*.adb} is the same as giving every file in the current
-directory whose name starts with @file{source} and whose extension is
-@file{adb}.
+@item ^-v^/VERBOSE^
+@cindex @option{^-v^/VERBOSE^} (@code{gnatmetric})
+Verbose mode;
+@command{gnatmetric} generates version information and then
+a trace of sources being processed.
-You shouldn't specify any directory name, just base names. @command{gnatxref}
-and @command{gnatfind} will be able to locate these files by themselves using
-the source path. If you specify directories, no result is produced.
+@item ^-dv^/DEBUG_OUTPUT^
+@cindex @option{^-dv^/DEBUG_OUTPUT^} (@code{gnatmetric})
+Debug mode;
+@command{gnatmetric} generates various messages useful to understand what
+happens during the metrics computation
+@item ^-q^/QUIET^
+@cindex @option{^-q^/QUIET^} (@code{gnatmetric})
+Quiet mode.
@end table
-@noindent
-The switches can be:
-@table @option
-@c !sort!
-@item --version
-@cindex @option{--version} @command{gnatxref}
-Display Copyright and version, then exit disregarding all other options.
-
-@item --help
-@cindex @option{--help} @command{gnatxref}
-If @option{--version} was not used, display usage, then exit disregarding
-all other options.
-
-@item ^-a^/ALL_FILES^
-@cindex @option{^-a^/ALL_FILES^} (@command{gnatxref})
-If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
-the read-only files found in the library search path. Otherwise, these files
-will be ignored. This option can be used to protect Gnat sources or your own
-libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
-much faster, and their output much smaller. Read-only here refers to access
-or permissions status in the file system for the current user.
+@node Generate project-wide metrics
+@subsection Generate project-wide metrics
-@item -aIDIR
-@cindex @option{-aIDIR} (@command{gnatxref})
-When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @command{gnatmake}.
+In order to compute metrics on all units of a given project, you can use
+the @command{gnat} driver along with the @option{-P} option:
+@smallexample
+ gnat metric -Pproj
+@end smallexample
-@item -aODIR
-@cindex @option{-aODIR} (@command{gnatxref})
-When searching for library and object files, look in directory
-DIR. The order in which library files are searched is the same as for
-@command{gnatmake}.
+@noindent
+If the project @code{proj} depends upon other projects, you can compute
+the metrics on the project closure using the @option{-U} option:
+@smallexample
+ gnat metric -Pproj -U
+@end smallexample
-@item -nostdinc
-@cindex @option{-nostdinc} (@command{gnatxref})
-Do not look for sources in the system default directory.
+@noindent
+Finally, if not all the units are relevant to a particular main
+program in the project closure, you can generate metrics for the set
+of units needed to create a given main program (unit closure) using
+the @option{-U} option followed by the name of the main unit:
+@smallexample
+ gnat metric -Pproj -U main
+@end smallexample
-@item -nostdlib
-@cindex @option{-nostdlib} (@command{gnatxref})
-Do not look for library files in the system default directory.
-@item --RTS=@var{rts-path}
-@cindex @option{--RTS} (@command{gnatxref})
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
+@c ***********************************
+@node File Name Krunching Using gnatkr
+@chapter File Name Krunching Using @code{gnatkr}
+@findex gnatkr
-@item ^-d^/DERIVED_TYPES^
-@cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref})
-If this switch is set @code{gnatxref} will output the parent type
-reference for each matching derived types.
+@noindent
+This chapter discusses the method used by the compiler to shorten
+the default file names chosen for Ada units so that they do not
+exceed the maximum length permitted. It also describes the
+@code{gnatkr} utility that can be used to determine the result of
+applying this shortening.
+@menu
+* About gnatkr::
+* Using gnatkr::
+* Krunching Method::
+* Examples of gnatkr Usage::
+@end menu
-@item ^-f^/FULL_PATHNAME^
-@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref})
-If this switch is set, the output file names will be preceded by their
-directory (if the file was found in the search path). If this switch is
-not set, the directory will not be printed.
+@node About gnatkr
+@section About @code{gnatkr}
-@item ^-g^/IGNORE_LOCALS^
-@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref})
-If this switch is set, information is output only for library-level
-entities, ignoring local entities. The use of this switch may accelerate
-@code{gnatfind} and @code{gnatxref}.
+@noindent
+The default file naming rule in GNAT
+is that the file name must be derived from
+the unit name. The exact default rule is as follows:
+@itemize @bullet
+@item
+Take the unit name and replace all dots by hyphens.
+@item
+If such a replacement occurs in the
+second character position of a name, and the first character is
+^@samp{a}, @samp{g}, @samp{s}, or @samp{i}, ^@samp{A}, @samp{G}, @samp{S}, or @samp{I},^
+then replace the dot by the character
+^@samp{~} (tilde)^@samp{$} (dollar sign)^
+instead of a minus.
+@end itemize
+The reason for this exception is to avoid clashes
+with the standard names for children of System, Ada, Interfaces,
+and GNAT, which use the prefixes
+^@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},^@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},^
+respectively.
-@item -IDIR
-@cindex @option{-IDIR} (@command{gnatxref})
-Equivalent to @samp{-aODIR -aIDIR}.
+The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}}
+switch of the compiler activates a ``krunching''
+circuit that limits file names to nn characters (where nn is a decimal
+integer). For example, using OpenVMS,
+where the maximum file name length is
+39, the value of nn is usually set to 39, but if you want to generate
+a set of files that would be usable if ported to a system with some
+different maximum file length, then a different value can be specified.
+The default value of 39 for OpenVMS need not be specified.
-@item -pFILE
-@cindex @option{-pFILE} (@command{gnatxref})
-Specify a project file to use @xref{Project Files}.
-If you need to use the @file{.gpr}
-project files, you should use gnatxref through the GNAT driver
-(@command{gnat xref -Pproject}).
+The @code{gnatkr} utility can be used to determine the krunched name for
+a given file, when krunched to a specified maximum length.
-By default, @code{gnatxref} and @code{gnatfind} will try to locate a
-project file in the current directory.
+@node Using gnatkr
+@section Using @code{gnatkr}
-If a project file is either specified or found by the tools, then the content
-of the source directory and object directory lines are added as if they
-had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^}
-and @samp{^-aO^OBJECT_SEARCH^}.
-@item ^-u^/UNUSED^
-Output only unused symbols. This may be really useful if you give your
-main compilation unit on the command line, as @code{gnatxref} will then
-display every unused entity and 'with'ed package.
+@noindent
+The @code{gnatkr} command has the form
@ifclear vms
-@item -v
-Instead of producing the default output, @code{gnatxref} will generate a
-@file{tags} file that can be used by vi. For examples how to use this
-feature, see @ref{Examples of gnatxref Usage}. The tags file is output
-to the standard output, thus you will have to redirect it to a file.
+@smallexample
+@c $ gnatkr @var{name} @ovar{length}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatkr @var{name} @r{[}@var{length}@r{]}
+@end smallexample
@end ifclear
-@end table
-
-@noindent
-All these switches may be in any order on the command line, and may even
-appear after the file names. They need not be separated by spaces, thus
-you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
-@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
-
-@node gnatfind Switches
-@section @code{gnatfind} Switches
-
-@noindent
-The command line for @code{gnatfind} is:
-
+@ifset vms
@smallexample
-$ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
- @r{[}@var{file1} @var{file2} @dots{}]
+$ gnatkr @var{name} /COUNT=nn
@end smallexample
+@end ifset
@noindent
-where
+@var{name} is the uncrunched file name, derived from the name of the unit
+in the standard manner described in the previous section (i.e., in particular
+all dots are replaced by hyphens). The file name may or may not have an
+extension (defined as a suffix of the form period followed by arbitrary
+characters other than period). If an extension is present then it will
+be preserved in the output. For example, when krunching @file{hellofile.ads}
+to eight characters, the result will be hellofil.ads.
-@table @var
-@item pattern
-An entity will be output only if it matches the regular expression found
-in @var{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}.
+Note: for compatibility with previous versions of @code{gnatkr} dots may
+appear in the name instead of hyphens, but the last dot will always be
+taken as the start of an extension. So if @code{gnatkr} is given an argument
+such as @file{Hello.World.adb} it will be treated exactly as if the first
+period had been a hyphen, and for example krunching to eight characters
+gives the result @file{hellworl.adb}.
-Omitting the pattern is equivalent to specifying @samp{*}, which
-will match any entity. Note that if you do not provide a pattern, you
-have to provide both a sourcefile and a line.
+Note that the result is always all lower case (except on OpenVMS where it is
+all upper case). Characters of the other case are folded as required.
-Entity names are given in Latin-1, with uppercase/lowercase equivalence
-for matching purposes. At the current time there is no support for
-8-bit codes other than Latin-1, or for wide characters in identifiers.
+@var{length} represents the length of the krunched name. The default
+when no argument is given is ^8^39^ characters. A length of zero stands for
+unlimited, in other words do not chop except for system files where the
+implied crunching length is always eight characters.
-@item sourcefile
-@code{gnatfind} will look for references, bodies or declarations
-of symbols referenced in @file{@var{sourcefile}}, at line @var{line}
-and column @var{column}. See @ref{Examples of gnatfind Usage}
-for syntax examples.
+@noindent
+The output is the krunched name. The output has an extension only if the
+original argument was a file name with an extension.
-@item line
-is a decimal integer identifying the line number containing
-the reference to the entity (or entities) to be located.
+@node Krunching Method
+@section Krunching Method
-@item column
-is a decimal integer identifying the exact location on the
-line of the first character of the identifier for the
-entity reference. Columns are numbered from 1.
+@noindent
+The initial file name is determined by the name of the unit that the file
+contains. The name is formed by taking the full expanded name of the
+unit and replacing the separating dots with hyphens and
+using ^lowercase^uppercase^
+for all letters, except that a hyphen in the second character position is
+replaced by a ^tilde^dollar sign^ if the first character is
+^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^.
+The extension is @code{.ads} for a
+spec and @code{.adb} for a body.
+Krunching does not affect the extension, but the file name is shortened to
+the specified length by following these rules:
-@item file1 file2 @dots{}
-The search will be restricted to these source files. If none are given, then
-the search will be done for every library file in the search path.
-These file must appear only after the pattern or sourcefile.
+@itemize @bullet
+@item
+The name is divided into segments separated by hyphens, tildes or
+underscores and all hyphens, tildes, and underscores are
+eliminated. If this leaves the name short enough, we are done.
-These file names are considered to be regular expressions, so for instance
-specifying @file{source*.adb} is the same as giving every file in the current
-directory whose name starts with @file{source} and whose extension is
-@file{adb}.
+@item
+If the name is too long, the longest segment is located (left-most
+if there are two of equal length), and shortened by dropping
+its last character. This is repeated until the name is short enough.
-The location of the spec of the entity will always be displayed, even if it
-isn't in one of @file{@var{file1}}, @file{@var{file2}},@enddots{} The
-occurrences of the entity in the separate units of the ones given on the
-command line will also be displayed.
+As an example, consider the krunching of @*@file{our-strings-wide_fixed.adb}
+to fit the name into 8 characters as required by some operating systems.
-Note that if you specify at least one file in this part, @code{gnatfind} may
-sometimes not be able to find the body of the subprograms.
+@smallexample
+our-strings-wide_fixed 22
+our strings wide fixed 19
+our string wide fixed 18
+our strin wide fixed 17
+our stri wide fixed 16
+our stri wide fixe 15
+our str wide fixe 14
+our str wid fixe 13
+our str wid fix 12
+ou str wid fix 11
+ou st wid fix 10
+ou st wi fix 9
+ou st wi fi 8
+Final file name: oustwifi.adb
+@end smallexample
-@end table
+@item
+The file names for all predefined units are always krunched to eight
+characters. The krunching of these predefined units uses the following
+special prefix replacements:
-@noindent
-At least one of 'sourcefile' or 'pattern' has to be present on
-the command line.
+@table @file
+@item ada-
+replaced by @file{^a^A^-}
-The following switches are available:
-@table @option
-@c !sort!
+@item gnat-
+replaced by @file{^g^G^-}
-@cindex @option{--version} @command{gnatfind}
-Display Copyright and version, then exit disregarding all other options.
+@item interfaces-
+replaced by @file{^i^I^-}
-@item --help
-@cindex @option{--help} @command{gnatfind}
-If @option{--version} was not used, display usage, then exit disregarding
-all other options.
+@item system-
+replaced by @file{^s^S^-}
+@end table
-@item ^-a^/ALL_FILES^
-@cindex @option{^-a^/ALL_FILES^} (@command{gnatfind})
-If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
-the read-only files found in the library search path. Otherwise, these files
-will be ignored. This option can be used to protect Gnat sources or your own
-libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref}
-much faster, and their output much smaller. Read-only here refers to access
-or permission status in the file system for the current user.
+These system files have a hyphen in the second character position. That
+is why normal user files replace such a character with a
+^tilde^dollar sign^, to
+avoid confusion with system file names.
-@item -aIDIR
-@cindex @option{-aIDIR} (@command{gnatfind})
-When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @command{gnatmake}.
+As an example of this special rule, consider
+@*@file{ada-strings-wide_fixed.adb}, which gets krunched as follows:
-@item -aODIR
-@cindex @option{-aODIR} (@command{gnatfind})
-When searching for library and object files, look in directory
-DIR. The order in which library files are searched is the same as for
-@command{gnatmake}.
+@smallexample
+ada-strings-wide_fixed 22
+a- strings wide fixed 18
+a- string wide fixed 17
+a- strin wide fixed 16
+a- stri wide fixed 15
+a- stri wide fixe 14
+a- str wide fixe 13
+a- str wid fixe 12
+a- str wid fix 11
+a- st wid fix 10
+a- st wi fix 9
+a- st wi fi 8
+Final file name: a-stwifi.adb
+@end smallexample
+@end itemize
-@item -nostdinc
-@cindex @option{-nostdinc} (@command{gnatfind})
-Do not look for sources in the system default directory.
+Of course no file shortening algorithm can guarantee uniqueness over all
+possible unit names, and if file name krunching is used then it is your
+responsibility to ensure that no name clashes occur. The utility
+program @code{gnatkr} is supplied for conveniently determining the
+krunched name of a file.
-@item -nostdlib
-@cindex @option{-nostdlib} (@command{gnatfind})
-Do not look for library files in the system default directory.
+@node Examples of gnatkr Usage
+@section Examples of @code{gnatkr} Usage
-@item --RTS=@var{rts-path}
-@cindex @option{--RTS} (@command{gnatfind})
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
+@smallexample
+@iftex
+@leftskip=0cm
+@end iftex
+@ifclear vms
+$ gnatkr very_long_unit_name.ads --> velounna.ads
+$ gnatkr grandparent-parent-child.ads --> grparchi.ads
+$ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
+$ gnatkr grandparent-parent-child --> grparchi
+@end ifclear
+$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
+$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
+@end smallexample
-@item ^-d^/DERIVED_TYPE_INFORMATION^
-@cindex @option{^-d^/DERIVED_TYPE_INFORMATION^} (@code{gnatfind})
-If this switch is set, then @code{gnatfind} will output the parent type
-reference for each matching derived types.
+@node Preprocessing Using gnatprep
+@chapter Preprocessing Using @code{gnatprep}
+@findex gnatprep
-@item ^-e^/EXPRESSIONS^
-@cindex @option{^-e^/EXPRESSIONS^} (@command{gnatfind})
-By default, @code{gnatfind} accept the simple regular expression set for
-@samp{pattern}. If this switch is set, then the pattern will be
-considered as full Unix-style regular expression.
+@noindent
+This chapter discusses how to use GNAT's @code{gnatprep} utility for simple
+preprocessing.
+Although designed for use with GNAT, @code{gnatprep} does not depend on any
+special GNAT features.
+For further discussion of conditional compilation in general, see
+@ref{Conditional Compilation}.
-@item ^-f^/FULL_PATHNAME^
-@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatfind})
-If this switch is set, the output file names will be preceded by their
-directory (if the file was found in the search path). If this switch is
-not set, the directory will not be printed.
+@menu
+* Preprocessing Symbols::
+* Using gnatprep::
+* Switches for gnatprep::
+* Form of Definitions File::
+* Form of Input Text for gnatprep::
+@end menu
-@item ^-g^/IGNORE_LOCALS^
-@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatfind})
-If this switch is set, information is output only for library-level
-entities, ignoring local entities. The use of this switch may accelerate
-@code{gnatfind} and @code{gnatxref}.
+@node Preprocessing Symbols
+@section Preprocessing Symbols
-@item -IDIR
-@cindex @option{-IDIR} (@command{gnatfind})
-Equivalent to @samp{-aODIR -aIDIR}.
+@noindent
+Preprocessing symbols are defined in definition files and referred to in
+sources to be preprocessed. A Preprocessing symbol is an identifier, following
+normal Ada (case-insensitive) rules for its syntax, with the restriction that
+all characters need to be in the ASCII set (no accented letters).
-@item -pFILE
-@cindex @option{-pFILE} (@command{gnatfind})
-Specify a project file (@pxref{Project Files}) to use.
-By default, @code{gnatxref} and @code{gnatfind} will try to locate a
-project file in the current directory.
+@node Using gnatprep
+@section Using @code{gnatprep}
-If a project file is either specified or found by the tools, then the content
-of the source directory and object directory lines are added as if they
-had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} and
-@samp{^-aO^/OBJECT_SEARCH^}.
+@noindent
+To call @code{gnatprep} use
-@item ^-r^/REFERENCES^
-@cindex @option{^-r^/REFERENCES^} (@command{gnatfind})
-By default, @code{gnatfind} will output only the information about the
-declaration, body or type completion of the entities. If this switch is
-set, the @code{gnatfind} will locate every reference to the entities in
-the files specified on the command line (or in every file in the search
-path if no file is given on the command line).
+@smallexample
+@c $ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatprep @r{[}@var{switches}@r{]} @var{infile} @var{outfile} @r{[}@var{deffile}@r{]}
+@end smallexample
-@item ^-s^/PRINT_LINES^
-@cindex @option{^-s^/PRINT_LINES^} (@command{gnatfind})
-If this switch is set, then @code{gnatfind} will output the content
-of the Ada source file lines were the entity was found.
+@noindent
+where
+@table @var
+@item switches
+is an optional sequence of switches as described in the next section.
-@item ^-t^/TYPE_HIERARCHY^
-@cindex @option{^-t^/TYPE_HIERARCHY^} (@command{gnatfind})
-If this switch is set, then @code{gnatfind} will output the type hierarchy for
-the specified type. It act like -d option but recursively from parent
-type to parent type. When this switch is set it is not possible to
-specify more than one file.
+@item infile
+is the full name of the input file, which is an Ada source
+file containing preprocessor directives.
+
+@item outfile
+is the full name of the output file, which is an Ada source
+in standard Ada form. When used with GNAT, this file name will
+normally have an ads or adb suffix.
+
+@item deffile
+is the full name of a text file containing definitions of
+preprocessing symbols to be referenced by the preprocessor. This argument is
+optional, and can be replaced by the use of the @option{-D} switch.
@end table
-@noindent
-All these switches may be in any order on the command line, and may even
-appear after the file names. They need not be separated by spaces, thus
-you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
-@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
+@node Switches for gnatprep
+@section Switches for @code{gnatprep}
-As stated previously, gnatfind will search in every directory in the
-search path. You can force it to look only in the current directory if
-you specify @code{*} at the end of the command line.
+@table @option
+@c !sort!
-@node Project Files for gnatxref and gnatfind
-@section Project Files for @command{gnatxref} and @command{gnatfind}
+@item ^-b^/BLANK_LINES^
+@cindex @option{^-b^/BLANK_LINES^} (@command{gnatprep})
+Causes both preprocessor lines and the lines deleted by
+preprocessing to be replaced by blank lines in the output source file,
+preserving line numbers in the output file.
-@noindent
-Project files allow a programmer to specify how to compile its
-application, where to find sources, etc. These files are used
-@ifclear vms
-primarily by GPS, but they can also be used
-@end ifclear
-by the two tools
-@code{gnatxref} and @code{gnatfind}.
+@item ^-c^/COMMENTS^
+@cindex @option{^-c^/COMMENTS^} (@command{gnatprep})
+Causes both preprocessor lines and the lines deleted
+by preprocessing to be retained in the output source as comments marked
+with the special string @code{"--! "}. This option will result in line numbers
+being preserved in the output file.
-A project file name must end with @file{.gpr}. If a single one is
-present in the current directory, then @code{gnatxref} and @code{gnatfind} will
-extract the information from it. If multiple project files are found, none of
-them is read, and you have to use the @samp{-p} switch to specify the one
-you want to use.
+@item ^-C^/REPLACE_IN_COMMENTS^
+@cindex @option{^-C^/REPLACE_IN_COMMENTS^} (@command{gnatprep})
+Causes comments to be scanned. Normally comments are ignored by gnatprep.
+If this option is specified, then comments are scanned and any $symbol
+substitutions performed as in program text. This is particularly useful
+when structured comments are used (e.g., when writing programs in the
+SPARK dialect of Ada). Note that this switch is not available when
+doing integrated preprocessing (it would be useless in this context
+since comments are ignored by the compiler in any case).
-The following lines can be included, even though most of them have default
-values which can be used in most cases.
-The lines can be entered in any order in the file.
-Except for @file{src_dir} and @file{obj_dir}, you can only have one instance of
-each line. If you have multiple instances, only the last one is taken into
-account.
+@item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^
+@cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep})
+Defines a new preprocessing symbol, associated with value. If no value is given
+on the command line, then symbol is considered to be @code{True}. This switch
+can be used in place of a definition file.
-@table @code
-@item src_dir=DIR
-[default: @code{"^./^[]^"}]
-specifies a directory where to look for source files. Multiple @code{src_dir}
-lines can be specified and they will be searched in the order they
-are specified.
+@ifset vms
+@item /REMOVE
+@cindex @option{/REMOVE} (@command{gnatprep})
+This is the default setting which causes lines deleted by preprocessing
+to be entirely removed from the output file.
+@end ifset
-@item obj_dir=DIR
-[default: @code{"^./^[]^"}]
-specifies a directory where to look for object and library files. Multiple
-@code{obj_dir} lines can be specified, and they will be searched in the order
-they are specified
+@item ^-r^/REFERENCE^
+@cindex @option{^-r^/REFERENCE^} (@command{gnatprep})
+Causes a @code{Source_Reference} pragma to be generated that
+references the original input file, so that error messages will use
+the file name of this original file. The use of this switch implies
+that preprocessor lines are not to be removed from the file, so its
+use will force @option{^-b^/BLANK_LINES^} mode if
+@option{^-c^/COMMENTS^}
+has not been specified explicitly.
-@item comp_opt=SWITCHES
-[default: @code{""}]
-creates a variable which can be referred to subsequently by using
-the @code{$@{comp_opt@}} notation. This is intended to store the default
-switches given to @command{gnatmake} and @command{gcc}.
+Note that if the file to be preprocessed contains multiple units, then
+it will be necessary to @code{gnatchop} the output file from
+@code{gnatprep}. If a @code{Source_Reference} pragma is present
+in the preprocessed file, it will be respected by
+@code{gnatchop ^-r^/REFERENCE^}
+so that the final chopped files will correctly refer to the original
+input source file for @code{gnatprep}.
-@item bind_opt=SWITCHES
-[default: @code{""}]
-creates a variable which can be referred to subsequently by using
-the @samp{$@{bind_opt@}} notation. This is intended to store the default
-switches given to @command{gnatbind}.
+@item ^-s^/SYMBOLS^
+@cindex @option{^-s^/SYMBOLS^} (@command{gnatprep})
+Causes a sorted list of symbol names and values to be
+listed on the standard output file.
-@item link_opt=SWITCHES
-[default: @code{""}]
-creates a variable which can be referred to subsequently by using
-the @samp{$@{link_opt@}} notation. This is intended to store the default
-switches given to @command{gnatlink}.
+@item ^-u^/UNDEFINED^
+@cindex @option{^-u^/UNDEFINED^} (@command{gnatprep})
+Causes undefined symbols to be treated as having the value FALSE in the context
+of a preprocessor test. In the absence of this option, an undefined symbol in
+a @code{#if} or @code{#elsif} test will be treated as an error.
-@item main=EXECUTABLE
-[default: @code{""}]
-specifies the name of the executable for the application. This variable can
-be referred to in the following lines by using the @samp{$@{main@}} notation.
+@end table
-@ifset vms
-@item comp_cmd=COMMAND
-[default: @code{"GNAT COMPILE /SEARCH=$@{src_dir@} /DEBUG /TRY_SEMANTICS"}]
-@end ifset
@ifclear vms
-@item comp_cmd=COMMAND
-[default: @code{"gcc -c -I$@{src_dir@} -g -gnatq"}]
+@noindent
+Note: if neither @option{-b} nor @option{-c} is present,
+then preprocessor lines and
+deleted lines are completely removed from the output, unless -r is
+specified, in which case -b is assumed.
@end ifclear
-specifies the command used to compile a single file in the application.
-@ifset vms
-@item make_cmd=COMMAND
-[default: @code{"GNAT MAKE $@{main@}
-/SOURCE_SEARCH=$@{src_dir@} /OBJECT_SEARCH=$@{obj_dir@}
-/DEBUG /TRY_SEMANTICS /COMPILER_QUALIFIERS $@{comp_opt@}
-/BINDER_QUALIFIERS $@{bind_opt@} /LINKER_QUALIFIERS $@{link_opt@}"}]
-@end ifset
-@ifclear vms
-@item make_cmd=COMMAND
-[default: @code{"gnatmake $@{main@} -aI$@{src_dir@}
--aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@}
--bargs $@{bind_opt@} -largs $@{link_opt@}"}]
-@end ifclear
-specifies the command used to recompile the whole application.
+@node Form of Definitions File
+@section Form of Definitions File
-@item run_cmd=COMMAND
-[default: @code{"$@{main@}"}]
-specifies the command used to run the application.
+@noindent
+The definitions file contains lines of the form
-@item debug_cmd=COMMAND
-[default: @code{"gdb $@{main@}"}]
-specifies the command used to debug the application
+@smallexample
+symbol := value
+@end smallexample
-@end table
+@noindent
+where symbol is a preprocessing symbol, and value is one of the following:
+
+@itemize @bullet
+@item
+Empty, corresponding to a null substitution
+@item
+A string literal using normal Ada syntax
+@item
+Any sequence of characters from the set
+(letters, digits, period, underline).
+@end itemize
@noindent
-@command{gnatxref} and @command{gnatfind} only take into account the
-@code{src_dir} and @code{obj_dir} lines, and ignore the others.
+Comment lines may also appear in the definitions file, starting with
+the usual @code{--},
+and comments may be added to the definitions lines.
-@node Regular Expressions in gnatfind and gnatxref
-@section Regular Expressions in @code{gnatfind} and @code{gnatxref}
+@node Form of Input Text for gnatprep
+@section Form of Input Text for @code{gnatprep}
@noindent
-As specified in the section about @command{gnatfind}, the pattern can be a
-regular expression. Actually, there are to set of regular expressions
-which are recognized by the program:
+The input text may contain preprocessor conditional inclusion lines,
+as well as general symbol substitution sequences.
-@table @code
-@item globbing patterns
-These are the most usual regular expression. They are the same that you
-generally used in a Unix shell command line, or in a DOS session.
+The preprocessor conditional inclusion commands have the form
-Here is a more formal grammar:
@smallexample
@group
-@iftex
-@leftskip=.5cm
-@end iftex
-regexp ::= term
-term ::= elmt -- matches elmt
-term ::= elmt elmt -- concatenation (elmt then elmt)
-term ::= * -- any string of 0 or more characters
-term ::= ? -- matches any character
-term ::= [char @{char@}] -- matches any character listed
-term ::= [char - char] -- matches any character in range
+@cartouche
+#if @i{expression} @r{[}then@r{]}
+ lines
+#elsif @i{expression} @r{[}then@r{]}
+ lines
+#elsif @i{expression} @r{[}then@r{]}
+ lines
+@dots{}
+#else
+ lines
+#end if;
+@end cartouche
@end group
@end smallexample
-@item full regular expression
-The second set of regular expressions is much more powerful. This is the
-type of regular expressions recognized by utilities such a @file{grep}.
-
-The following is the form of a regular expression, expressed in Ada
-reference manual style BNF is as follows
-
+@noindent
+In this example, @i{expression} is defined by the following grammar:
@smallexample
-@iftex
-@leftskip=.5cm
-@end iftex
-@group
-regexp ::= term @{| term@} -- alternation (term or term @dots{})
-
-term ::= item @{item@} -- concatenation (item then item)
+@i{expression} ::= <symbol>
+@i{expression} ::= <symbol> = "<value>"
+@i{expression} ::= <symbol> = <symbol>
+@i{expression} ::= <symbol> 'Defined
+@i{expression} ::= not @i{expression}
+@i{expression} ::= @i{expression} and @i{expression}
+@i{expression} ::= @i{expression} or @i{expression}
+@i{expression} ::= @i{expression} and then @i{expression}
+@i{expression} ::= @i{expression} or else @i{expression}
+@i{expression} ::= ( @i{expression} )
+@end smallexample
-item ::= elmt -- match elmt
-item ::= elmt * -- zero or more elmt's
-item ::= elmt + -- one or more elmt's
-item ::= elmt ? -- matches elmt or nothing
-@end group
-@group
-elmt ::= nschar -- matches given character
-elmt ::= [nschar @{nschar@}] -- matches any character listed
-elmt ::= [^^^ nschar @{nschar@}] -- matches any character not listed
-elmt ::= [char - char] -- matches chars in given range
-elmt ::= \ char -- matches given character
-elmt ::= . -- matches any single character
-elmt ::= ( regexp ) -- parens used for grouping
+The following restriction exists: it is not allowed to have "and" or "or"
+following "not" in the same expression without parentheses. For example, this
+is not allowed:
-char ::= any character, including special characters
-nschar ::= any character except ()[].*+?^^^
-@end group
+@smallexample
+ not X or Y
@end smallexample
-Following are a few examples:
+This should be one of the following:
-@table @samp
-@item abcde|fghi
-will match any of the two strings @samp{abcde} and @samp{fghi},
+@smallexample
+ (not X) or Y
+ not (X or Y)
+@end smallexample
-@item abc*d
-will match any string like @samp{abd}, @samp{abcd}, @samp{abccd},
-@samp{abcccd}, and so on,
+@noindent
+For the first test (@i{expression} ::= <symbol>) the symbol must have
+either the value true or false, that is to say the right-hand of the
+symbol definition must be one of the (case-insensitive) literals
+@code{True} or @code{False}. If the value is true, then the
+corresponding lines are included, and if the value is false, they are
+excluded.
-@item [a-z]+
-will match any string which has only lowercase characters in it (and at
-least one character.
+The test (@i{expression} ::= <symbol> @code{'Defined}) is true only if
+the symbol has been defined in the definition file or by a @option{-D}
+switch on the command line. Otherwise, the test is false.
-@end table
-@end table
+The equality tests are case insensitive, as are all the preprocessor lines.
-@node Examples of gnatxref Usage
-@section Examples of @code{gnatxref} Usage
+If the symbol referenced is not defined in the symbol definitions file,
+then the effect depends on whether or not switch @option{-u}
+is specified. If so, then the symbol is treated as if it had the value
+false and the test fails. If this switch is not specified, then
+it is an error to reference an undefined symbol. It is also an error to
+reference a symbol that is defined with a value other than @code{True}
+or @code{False}.
-@subsection General Usage
+The use of the @code{not} operator inverts the sense of this logical test.
+The @code{not} operator cannot be combined with the @code{or} or @code{and}
+operators, without parentheses. For example, "if not X or Y then" is not
+allowed, but "if (not X) or Y then" and "if not (X or Y) then" are.
-@noindent
-For the following examples, we will consider the following units:
+The @code{then} keyword is optional as shown
-@smallexample @c ada
-@group
-@cartouche
-main.ads:
-1: with Bar;
-2: package Main is
-3: procedure Foo (B : in Integer);
-4: C : Integer;
-5: private
-6: D : Integer;
-7: end Main;
+The @code{#} must be the first non-blank character on a line, but
+otherwise the format is free form. Spaces or tabs may appear between
+the @code{#} and the keyword. The keywords and the symbols are case
+insensitive as in normal Ada code. Comments may be used on a
+preprocessor line, but other than that, no other tokens may appear on a
+preprocessor line. Any number of @code{elsif} clauses can be present,
+including none at all. The @code{else} is optional, as in Ada.
-main.adb:
-1: package body Main is
-2: procedure Foo (B : in Integer) is
-3: begin
-4: C := B;
-5: D := B;
-6: Bar.Print (B);
-7: Bar.Print (C);
-8: end Foo;
-9: end Main;
+The @code{#} marking the start of a preprocessor line must be the first
+non-blank character on the line, i.e., it must be preceded only by
+spaces or horizontal tabs.
-bar.ads:
-1: package Bar is
-2: procedure Print (B : Integer);
-3: end bar;
-@end cartouche
-@end group
-@end smallexample
+Symbol substitution outside of preprocessor lines is obtained by using
+the sequence
-@table @code
+@smallexample
+$symbol
+@end smallexample
@noindent
-The first thing to do is to recompile your application (for instance, in
-that case just by doing a @samp{gnatmake main}, so that GNAT generates
-the cross-referencing information.
-You can then issue any of the following commands:
+anywhere within a source line, except in a comment or within a
+string literal. The identifier
+following the @code{$} must match one of the symbols defined in the symbol
+definition file, and the result is to substitute the value of the
+symbol in place of @code{$symbol} in the output file.
-@item gnatxref main.adb
-@code{gnatxref} generates cross-reference information for main.adb
-and every unit 'with'ed by main.adb.
+Note that although the substitution of strings within a string literal
+is not possible, it is possible to have a symbol whose defined value is
+a string literal. So instead of setting XYZ to @code{hello} and writing:
-The output would be:
@smallexample
-@iftex
-@leftskip=0cm
-@end iftex
-B Type: Integer
- Decl: bar.ads 2:22
-B Type: Integer
- Decl: main.ads 3:20
- Body: main.adb 2:20
- Ref: main.adb 4:13 5:13 6:19
-Bar Type: Unit
- Decl: bar.ads 1:9
- Ref: main.adb 6:8 7:8
- main.ads 1:6
-C Type: Integer
- Decl: main.ads 4:5
- Modi: main.adb 4:8
- Ref: main.adb 7:19
-D Type: Integer
- Decl: main.ads 6:5
- Modi: main.adb 5:8
-Foo Type: Unit
- Decl: main.ads 3:15
- Body: main.adb 2:15
-Main Type: Unit
- Decl: main.ads 2:9
- Body: main.adb 1:14
-Print Type: Unit
- Decl: bar.ads 2:15
- Ref: main.adb 6:12 7:12
+Header : String := "$XYZ";
@end smallexample
@noindent
-that is the entity @code{Main} is declared in main.ads, line 2, column 9,
-its body is in main.adb, line 1, column 14 and is not referenced any where.
-
-The entity @code{Print} is declared in bar.ads, line 2, column 15 and it
-it referenced in main.adb, line 6 column 12 and line 7 column 12.
-
-@item gnatxref package1.adb package2.ads
-@code{gnatxref} will generates cross-reference information for
-package1.adb, package2.ads and any other package 'with'ed by any
-of these.
-
-@end table
-
-@ifclear vms
-@subsection Using gnatxref with vi
-
-@code{gnatxref} can generate a tags file output, which can be used
-directly from @command{vi}. Note that the standard version of @command{vi}
-will not work properly with overloaded symbols. Consider using another
-free implementation of @command{vi}, such as @command{vim}.
+you should set XYZ to @code{"hello"} and write:
@smallexample
-$ gnatxref -v gnatfind.adb > tags
+Header : String := $XYZ;
@end smallexample
@noindent
-will generate the tags file for @code{gnatfind} itself (if the sources
-are in the search path!).
-
-From @command{vi}, you can then use the command @samp{:tag @var{entity}}
-(replacing @var{entity} by whatever you are looking for), and vi will
-display a new file with the corresponding declaration of entity.
-@end ifclear
+and then the substitution will occur as desired.
-@node Examples of gnatfind Usage
-@section Examples of @code{gnatfind} Usage
+@node The GNAT Library Browser gnatls
+@chapter The GNAT Library Browser @code{gnatls}
+@findex gnatls
+@cindex Library browser
-@table @code
+@noindent
+@code{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.
-@item gnatfind ^-f^/FULL_PATHNAME^ xyz:main.adb
-Find declarations for all entities xyz referenced at least once in
-main.adb. The references are search in every library file in the search
-path.
+Note: to invoke @code{gnatls} with a project file, use the @code{gnat}
+driver (see @ref{The GNAT Driver and Project Files}).
-The directories will be printed as well (as the @samp{^-f^/FULL_PATHNAME^}
-switch is set)
+@menu
+* Running gnatls::
+* Switches for gnatls::
+* Examples of gnatls Usage::
+@end menu
-The output will look like:
-@smallexample
-^directory/^[directory]^main.ads:106:14: xyz <= declaration
-^directory/^[directory]^main.adb:24:10: xyz <= body
-^directory/^[directory]^foo.ads:45:23: xyz <= declaration
-@end smallexample
+@node Running gnatls
+@section Running @code{gnatls}
@noindent
-that is to say, one of the entities xyz found in main.adb is declared at
-line 12 of main.ads (and its body is in main.adb), and another one is
-declared at line 45 of foo.ads
-
-@item gnatfind ^-fs^/FULL_PATHNAME/SOURCE_LINE^ xyz:main.adb
-This is the same command as the previous one, instead @code{gnatfind} will
-display the content of the Ada source file lines.
-
-The output will look like:
+The @code{gnatls} command has the form
@smallexample
-^directory/^[directory]^main.ads:106:14: xyz <= declaration
- procedure xyz;
-^directory/^[directory]^main.adb:24:10: xyz <= body
- procedure xyz is
-^directory/^[directory]^foo.ads:45:23: xyz <= declaration
- xyz : Integer;
+$ gnatls switches @var{object_or_ali_file}
@end smallexample
@noindent
-This can make it easier to find exactly the location your are looking
-for.
+The main argument is the list of object or @file{ali} files
+(@pxref{The Ada Library Information Files})
+for which information is requested.
-@item gnatfind ^-r^/REFERENCES^ "*x*":main.ads:123 foo.adb
-Find references to all entities containing an x that are
-referenced on line 123 of main.ads.
-The references will be searched only in main.ads and foo.adb.
+In normal mode, without additional option, @code{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:
-@item gnatfind main.ads:123
-Find declarations and bodies for all entities that are referenced on
-line 123 of main.ads.
+@smallexample
+$ 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
+@end smallexample
-This is the same as @code{gnatfind "*":main.adb:123}.
+@noindent
+The first line can be interpreted as follows: the main unit which is
+contained in
+object file @file{demo1.o} is demo1, whose main source is in
+@file{demo1.adb}. Furthermore, the version of the source used for the
+compilation of demo1 has been modified (DIF). Each source file has a status
+qualifier which can be:
-@item gnatfind ^mydir/^[mydir]^main.adb:123:45
-Find the declaration for the entity referenced at column 45 in
-line 123 of file main.adb in directory mydir. Note that it
-is usual to omit the identifier name when the column is given,
-since the column position identifies a unique reference.
+@table @code
+@item OK (unchanged)
+The version of the source file used for the compilation of the
+specified unit corresponds exactly to the actual source file.
-The column has to be the beginning of the identifier, and should not
-point to any character in the middle of the identifier.
+@item 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 qualifier
+@option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}, a file marked
+MOK will not be recompiled.
+
+@item DIF (modified)
+No version of the source found on the path corresponds to the source
+used to build this object.
+
+@item ??? (file not found)
+No source file was found for this unit.
+
+@item 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.
@end table
-@c *********************************
-@node The GNAT Pretty-Printer gnatpp
-@chapter The GNAT Pretty-Printer @command{gnatpp}
-@findex gnatpp
-@cindex Pretty-Printer
+@node Switches for gnatls
+@section Switches for @code{gnatls}
@noindent
-^The @command{gnatpp} tool^GNAT PRETTY^ is an ASIS-based 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.
+@code{gnatls} recognizes the following switches:
-To produce a reformatted file, @command{gnatpp} generates and uses the ASIS
-tree for the input source and thus requires the input to be syntactically and
-semantically legal.
-If this condition is not met, @command{gnatpp} will terminate with an
-error message; no output file will be generated.
+@table @option
+@c !sort!
+@cindex @option{--version} @command{gnatls}
+Display Copyright and version, then exit disregarding all other options.
-If the source files presented to @command{gnatpp} contain
-preprocessing directives, then the output file will
-correspond to the generated source after all
-preprocessing is carried out. There is no way
-using @command{gnatpp} to obtain pretty printed files that
-include the preprocessing directives.
+@item --help
+@cindex @option{--help} @command{gnatls}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
-If the compilation unit
-contained in the input source depends semantically upon units located
-outside the current directory, you have to provide the source search path
-when invoking @command{gnatpp}, if these units are contained in files with
-names that do not follow the GNAT file naming rules, you have to provide
-the configuration file describing the corresponding naming scheme;
-see the description of the @command{gnatpp}
-switches below. Another possibility is to use a project file and to
-call @command{gnatpp} through the @command{gnat} driver
+@item ^-a^/ALL_UNITS^
+@cindex @option{^-a^/ALL_UNITS^} (@code{gnatls})
+Consider all units, including those of the predefined Ada library.
+Especially useful with @option{^-d^/DEPENDENCIES^}.
-The @command{gnatpp} command has the form
+@item ^-d^/DEPENDENCIES^
+@cindex @option{^-d^/DEPENDENCIES^} (@code{gnatls})
+List sources from which specified units depend on.
-@smallexample
-$ gnatpp @ovar{switches} @var{filename}
-@end smallexample
+@item ^-h^/OUTPUT=OPTIONS^
+@cindex @option{^-h^/OUTPUT=OPTIONS^} (@code{gnatls})
+Output the list of options.
-@noindent
-where
-@itemize @bullet
-@item
-@var{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
+@item ^-o^/OUTPUT=OBJECTS^
+@cindex @option{^-o^/OUTPUT=OBJECTS^} (@code{gnatls})
+Only output information about object files.
-@item
-@var{filename} is the name (including the extension) 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
-@end itemize
+@item ^-s^/OUTPUT=SOURCES^
+@cindex @option{^-s^/OUTPUT=SOURCES^} (@code{gnatls})
+Only output information about source files.
-@menu
-* Switches for gnatpp::
-* Formatting Rules::
-@end menu
+@item ^-u^/OUTPUT=UNITS^
+@cindex @option{^-u^/OUTPUT=UNITS^} (@code{gnatls})
+Only output information about compilation units.
-@node Switches for gnatpp
-@section Switches for @command{gnatpp}
+@item ^-files^/FILES^=@var{file}
+@cindex @option{^-files^/FILES^} (@code{gnatls})
+Take as arguments the files listed in text file @var{file}.
+Text file @var{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.
-@noindent
-The following subsections describe the various switches accepted by
-@command{gnatpp}, organized by category.
+@item ^-aO^/OBJECT_SEARCH=^@var{dir}
+@itemx ^-aI^/SOURCE_SEARCH=^@var{dir}
+@itemx ^-I^/SEARCH=^@var{dir}
+@itemx ^-I-^/NOCURRENT_DIRECTORY^
+@itemx -nostdinc
+@cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatls})
+@cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatls})
+@cindex @option{^-I^/SEARCH^} (@code{gnatls})
+@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatls})
+Source path manipulation. Same meaning as the equivalent @command{gnatmake}
+flags (@pxref{Switches for gnatmake}).
-@ifclear vms
-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 @command{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 @command{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.
-For example, to set
-the alignment of the assignment delimiter both in declarations and in
-assignment statements, you must write @option{-A2A3}
-(or @option{-A2 -A3}), but not @option{-A23}.
-@end ifclear
+@item --RTS=@var{rts-path}
+@cindex @option{--RTS} (@code{gnatls})
+Specifies the default location of the runtime library. Same meaning as the
+equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
-@ifset vms
-In many cases the set of options for a given qualifier are incompatible with
-each other (for example the qualifier that controls the casing of a reserved
-word may have exactly one option, which specifies either upper case, lower
-case, or mixed case), and thus exactly one such option can be in effect for
-an invocation of @command{gnatpp}.
-If more than one is supplied, the last one is used.
-However, some qualifiers have options that are mutually compatible,
-and then you may then supply several such options when invoking
-@command{gnatpp}.
-@end ifset
+@item ^-v^/OUTPUT=VERBOSE^
+@cindex @option{^-v^/OUTPUT=VERBOSE^} (@code{gnatls})
+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:
-In most cases, it is obvious whether or not the
-^values for a switch with a given name^options for a given qualifier^
-are compatible with each other.
-When the semantics might not be evident, the summaries below explicitly
-indicate the effect.
+@table @code
+@item Preelaborable
+The unit is preelaborable in the Ada sense.
-@menu
-* Alignment Control::
-* Casing Control::
-* Construct Layout Control::
-* General Text Layout Control::
-* Other Formatting Options::
-* Setting the Source Search Path::
-* Output File Control::
-* Other gnatpp Switches::
-@end menu
+@item No_Elab_Code
+No elaboration code has been produced by the compiler for this unit.
-@node Alignment Control
-@subsection Alignment Control
-@cindex Alignment control in @command{gnatpp}
+@item Pure
+The unit is pure in the Ada sense.
-@noindent
-Programs can be easier to read if certain constructs are vertically aligned.
-By default all alignments are set ON.
-Through the @option{^-A0^/ALIGN=OFF^} switch you may reset the default to
-OFF, and then use one or more of the other
-^@option{-A@var{n}} switches^@option{/ALIGN} options^
-to activate alignment for specific constructs.
+@item Elaborate_Body
+The unit contains a pragma Elaborate_Body.
-@table @option
-@cindex @option{^-A@var{n}^/ALIGN^} (@command{gnatpp})
+@item Remote_Types
+The unit contains a pragma Remote_Types.
-@ifset vms
-@item /ALIGN=ON
-Set all alignments to ON
-@end ifset
+@item Shared_Passive
+The unit contains a pragma Shared_Passive.
-@item ^-A0^/ALIGN=OFF^
-Set all alignments to OFF
+@item Predefined
+This unit is part of the predefined environment and cannot be modified
+by the user.
-@item ^-A1^/ALIGN=COLONS^
-Align @code{:} in declarations
+@item Remote_Call_Interface
+The unit contains a pragma Remote_Call_Interface.
-@item ^-A2^/ALIGN=DECLARATIONS^
-Align @code{:=} in initializations in declarations
-
-@item ^-A3^/ALIGN=STATEMENTS^
-Align @code{:=} in assignment statements
-
-@item ^-A4^/ALIGN=ARROWS^
-Align @code{=>} in associations
-
-@item ^-A5^/ALIGN=COMPONENT_CLAUSES^
-Align @code{at} keywords in the component clauses in record
-representation clauses
@end table
-@noindent
-The @option{^-A^/ALIGN^} switches are mutually compatible; any combination
-is allowed.
+@end table
-@node Casing Control
-@subsection Casing Control
-@cindex Casing control in @command{gnatpp}
+@node Examples of gnatls Usage
+@section Example of @code{gnatls} Usage
+@ifclear vms
@noindent
-@command{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.
+Example of using the verbose switch. Note how the source and
+object paths are affected by the -I switch.
-Three types of casing are supported: lower case, upper case, and mixed case.
-Lower and upper case are self-explanatory (but since some letters in
-Latin1 and other GNAT-supported character sets
-exist only in lower-case form, an upper case conversion will have no
-effect on them.)
-``Mixed case'' means that the first letter, and also each letter immediately
-following an underscore, are converted to their uppercase forms;
-all the other letters are converted to their lowercase forms.
+@smallexample
+$ gnatls -v -I.. demo1.o
-@table @option
-@cindex @option{^-a@var{x}^/ATTRIBUTE^} (@command{gnatpp})
-@item ^-aL^/ATTRIBUTE_CASING=LOWER_CASE^
-Attribute designators are lower case
+GNATLS 5.03w (20041123-34)
+Copyright 1997-2004 Free Software Foundation, Inc.
-@item ^-aU^/ATTRIBUTE_CASING=UPPER_CASE^
-Attribute designators are upper case
+Source Search Path:
+ <Current_Directory>
+ ../
+ /home/comar/local/adainclude/
-@item ^-aM^/ATTRIBUTE_CASING=MIXED_CASE^
-Attribute designators are mixed case (this is the default)
+Object Search Path:
+ <Current_Directory>
+ ../
+ /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
-@cindex @option{^-k@var{x}^/KEYWORD_CASING^} (@command{gnatpp})
-@item ^-kL^/KEYWORD_CASING=LOWER_CASE^
-Keywords (technically, these are known in Ada as @emph{reserved words}) are
-lower case (this is the default)
+Project Search Path:
+ <Current_Directory>
+ /home/comar/local/lib/gnat/
-@item ^-kU^/KEYWORD_CASING=UPPER_CASE^
-Keywords are upper case
+./demo1.o
+ Unit =>
+ Name => demo1
+ Kind => subprogram body
+ Flags => No_Elab_Code
+ Source => demo1.adb modified
+@end smallexample
-@cindex @option{^-n@var{x}^/NAME_CASING^} (@command{gnatpp})
-@item ^-nD^/NAME_CASING=AS_DECLARED^
-Name casing for defining occurrences are as they appear in the source file
-(this is the default)
+@noindent
+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.
-@item ^-nU^/NAME_CASING=UPPER_CASE^
-Names are in upper case
+@smallexample
+$ 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
-@item ^-nL^/NAME_CASING=LOWER_CASE^
-Names are in lower case
+$ 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
+@end smallexample
+@end ifclear
-@item ^-nM^/NAME_CASING=MIXED_CASE^
-Names are in mixed case
+@ifset vms
+@smallexample
+GNAT LIST /DEPENDENCIES /OUTPUT=SOURCES /ALL_UNITS DEMO1.ADB
-@cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp})
-@item ^-pL^/PRAGMA_CASING=LOWER_CASE^
-Pragma names are lower case
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]ada.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-finali.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-filico.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-stream.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-tags.ads
+demo1.adb
+gen_list.ads
+gen_list.adb
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]gnat.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]g-io.ads
+instr.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]system.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-exctab.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finimp.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finroo.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-secsta.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stalib.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stoele.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stratt.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-tasoli.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-unstyp.ads
+GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]unchconv.ads
+@end smallexample
+@end ifset
-@item ^-pU^/PRAGMA_CASING=UPPER_CASE^
-Pragma names are upper case
+@node Cleaning Up Using gnatclean
+@chapter Cleaning Up Using @code{gnatclean}
+@findex gnatclean
+@cindex Cleaning tool
-@item ^-pM^/PRAGMA_CASING=MIXED_CASE^
-Pragma names are mixed case (this is the default)
+@noindent
+@code{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.
-@item ^-D@var{file}^/DICTIONARY=@var{file}^
-@cindex @option{^-D^/DICTIONARY^} (@command{gnatpp})
-Use @var{file} as a @emph{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^/NAME_CASING^ switch.
-To supply more than one dictionary file,
-use ^several @option{-D} switches^a list of files as options^.
+@menu
+* Running gnatclean::
+* Switches for gnatclean::
+@c * Examples of gnatclean Usage::
+@end menu
+
+@node Running gnatclean
+@section Running @code{gnatclean}
@noindent
-@option{gnatpp} implicitly uses a @emph{default dictionary file}
-to define the casing for the Ada predefined names and
-the names declared in the GNAT libraries.
+The @code{gnatclean} command has the form:
-@item ^-D-^/SPECIFIC_CASING^
-@cindex @option{^-D-^/SPECIFIC_CASING^} (@command{gnatpp})
-Do not use the default dictionary file;
-instead, use the casing
-defined by a @option{^-n^/NAME_CASING^} switch and any explicit
-dictionary file(s)
-@end table
+@smallexample
+$ gnatclean switches @var{names}
+@end smallexample
@noindent
-The structure of a dictionary file, and details on the conventions
-used in the default dictionary file, are defined in @ref{Name Casing}.
+@var{names} is a list of source file names. Suffixes @code{.^ads^ADS^} and
+@code{^adb^ADB^} may be omitted. If a project file is specified using switch
+@code{^-P^/PROJECT_FILE=^}, then @var{names} may be completely omitted.
-The @option{^-D-^/SPECIFIC_CASING^} and
-@option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually
-compatible.
+@noindent
+In normal mode, @code{gnatclean} delete the files produced by the compiler and,
+if switch @code{^-c^/COMPILER_FILES_ONLY^} is not specified, by the binder and
+the linker. In informative-only mode, specified by switch
+@code{^-n^/NODELETE^}, the list of files that would have been deleted in
+normal mode is listed, but no file is actually deleted.
-@node Construct Layout Control
-@subsection Construct Layout Control
-@cindex Layout control in @command{gnatpp}
+@node Switches for gnatclean
+@section Switches for @code{gnatclean}
@noindent
-This group of @command{gnatpp} switches controls the layout of comments and
-complex syntactic constructs. See @ref{Formatting Comments} for details
-on their effect.
+@code{gnatclean} recognizes the following switches:
@table @option
-@cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp})
-@item ^-c0^/COMMENTS_LAYOUT=UNTOUCHED^
-All the comments remain unchanged
-
-@item ^-c1^/COMMENTS_LAYOUT=DEFAULT^
-GNAT-style comment line indentation (this is the default).
+@c !sort!
+@cindex @option{--version} @command{gnatclean}
+Display Copyright and version, then exit disregarding all other options.
-@item ^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^
-Reference-manual comment line indentation.
+@item --help
+@cindex @option{--help} @command{gnatclean}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
-@item ^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^
-GNAT-style comment beginning
+@item ^--subdirs^/SUBDIRS^=subdir
+Actual object directory of each project file is the subdirectory subdir of the
+object directory specified or defauted in the project file.
-@item ^-c4^/COMMENTS_LAYOUT=REFORMAT^
-Reformat comment blocks
+@item ^--unchecked-shared-lib-imports^/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.
-@item ^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^
-Keep unchanged special form comments
+@item ^-c^/COMPILER_FILES_ONLY^
+@cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean})
+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.
-Reformat comment blocks
+@item ^-D ^/DIRECTORY_OBJECTS=^@var{dir}
+@cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatclean})
+Indicate that ALI and object files should normally be found in directory
+@var{dir}.
-@cindex @option{^-l@var{n}^/CONSTRUCT_LAYOUT^} (@command{gnatpp})
-@item ^-l1^/CONSTRUCT_LAYOUT=GNAT^
-GNAT-style layout (this is the default)
+@item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^
+@cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@code{gnatclean})
+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^/VERBOSE^), then error lines start with the full path name of the project
+file, rather than its simple file name.
-@item ^-l2^/CONSTRUCT_LAYOUT=COMPACT^
-Compact layout
+@item ^-h^/HELP^
+@cindex @option{^-h^/HELP^} (@code{gnatclean})
+Output a message explaining the usage of @code{^gnatclean^gnatclean^}.
-@item ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^
-Uncompact layout
+@item ^-n^/NODELETE^
+@cindex @option{^-n^/NODELETE^} (@code{gnatclean})
+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.
-@cindex @option{^-N^/NOTABS^} (@command{gnatpp})
-@item ^-N^/NOTABS^
-All the VT characters are removed from the comment text. All the HT characters
-are expanded with the sequences of space characters to get to the next tab
-stops.
+@item ^-P^/PROJECT_FILE=^@var{project}
+@cindex @option{^-P^/PROJECT_FILE^} (@code{gnatclean})
+Use project file @var{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.
-@cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp})
-@item ^--no-separate-is^/NO_SEPARATE_IS^
-Do not place the keyword @code{is} on a separate line in a subprogram body in
-case if the spec occupies more then one line.
+@item ^-q^/QUIET^
+@cindex @option{^-q^/QUIET^} (@code{gnatclean})
+Quiet output. If there are no errors, do not output anything, except in
+verbose mode (switch ^-v^/VERBOSE^) or in informative-only mode
+(switch ^-n^/NODELETE^).
-@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
-@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
-Place the keyword @code{loop} in FOR and WHILE loop statements and the
-keyword @code{then} in IF statements on a separate line.
+@item ^-r^/RECURSIVE^
+@cindex @option{^-r^/RECURSIVE^} (@code{gnatclean})
+When a project file is specified (using switch ^-P^/PROJECT_FILE=^),
+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.
-@cindex @option{^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^} (@command{gnatpp})
-@item ^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^
-Do not place the keyword @code{loop} in FOR and WHILE loop statements and the
-keyword @code{then} in IF statements on a separate line. This option is
-incompatible with @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} option.
+@item ^-v^/VERBOSE^
+@cindex @option{^-v^/VERBOSE^} (@code{gnatclean})
+Verbose mode.
-@cindex @option{^--use-on-new-line^/USE_ON_NEW_LINE^} (@command{gnatpp})
-@item ^--use-on-new-line^/USE_ON_NEW_LINE^
-Start each USE clause in a context clause from a separate line.
+@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
+@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean})
+Indicates the verbosity of the parsing of GNAT project files.
+@xref{Switches Related to Project Files}.
-@cindex @option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^} (@command{gnatpp})
-@item ^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^
-Use a separate line for a loop or block statement name, but do not use an extra
-indentation level for the statement itself.
+@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
+@cindex @option{^-X^/EXTERNAL_REFERENCE^} (@code{gnatclean})
+Indicates that external variable @var{name} has the value @var{value}.
+The Project Manager will use this value for occurrences of
+@code{external(name)} when parsing the project file.
+@xref{Switches Related to Project Files}.
-@end table
+@item ^-aO^/OBJECT_SEARCH=^@var{dir}
+@cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean})
+When searching for ALI and object files, look in directory
+@var{dir}.
-@ifclear vms
-@noindent
-The @option{-c1} and @option{-c2} switches are incompatible.
-The @option{-c3} and @option{-c4} switches are compatible with each other and
-also with @option{-c1} and @option{-c2}. The @option{-c0} switch disables all
-the other comment formatting switches.
+@item ^-I^/SEARCH=^@var{dir}
+@cindex @option{^-I^/SEARCH^} (@code{gnatclean})
+Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir}}.
-The @option{-l1}, @option{-l2}, and @option{-l3} switches are incompatible.
-@end ifclear
+@item ^-I-^/NOCURRENT_DIRECTORY^
+@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatclean})
+@cindex Source files, suppressing search
+Do not look for ALI or object files in the directory
+where @code{gnatclean} was invoked.
-@ifset vms
-@noindent
-For the @option{/COMMENTS_LAYOUT} qualifier:
-@itemize @bullet
-@item
-The @option{DEFAULT} and @option{STANDARD_INDENT} options are incompatible.
-@item
-The @option{GNAT_BEGINNING} and @option{REFORMAT} options are compatible with
-each other and also with @option{DEFAULT} and @option{STANDARD_INDENT}.
-@end itemize
+@end table
-@noindent
-The @option{GNAT}, @option{COMPACT}, and @option{UNCOMPACT} options for the
-@option{/CONSTRUCT_LAYOUT} qualifier are incompatible.
-@end ifset
+@c @node Examples of gnatclean Usage
+@c @section Examples of @code{gnatclean} Usage
-@node General Text Layout Control
-@subsection General Text Layout Control
+@ifclear vms
+@node GNAT and Libraries
+@chapter GNAT and Libraries
+@cindex Library, building, installing, using
@noindent
-These switches allow control over line length and indentation.
+This chapter describes how to build and use libraries with GNAT, and also shows
+how to recompile the GNAT run-time library. You should be familiar with the
+Project Manager facility (@pxref{GNAT Project Manager}) before reading this
+chapter.
-@table @option
-@item ^-M@var{nnn}^/LINE_LENGTH_MAX=@var{nnn}^
-@cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp})
-Maximum line length, @var{nnn} from 32@dots{}256, the default value is 79
+@menu
+* Introduction to Libraries in GNAT::
+* General Ada Libraries::
+* Stand-alone Ada Libraries::
+* Rebuilding the GNAT Run-Time Library::
+@end menu
-@item ^-i@var{nnn}^/INDENTATION_LEVEL=@var{nnn}^
-@cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp})
-Indentation level, @var{nnn} from 1@dots{}9, the default value is 3
+@node Introduction to Libraries in GNAT
+@section Introduction to Libraries in GNAT
-@item ^-cl@var{nnn}^/CONTINUATION_INDENT=@var{nnn}^
-@cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp})
-Indentation level for continuation lines (relative to the line being
-continued), @var{nnn} from 1@dots{}9.
-The default
-value is one less then the (normal) indentation level, unless the
-indentation is set to 1 (in which case the default value for continuation
-line indentation is also 1)
-@end table
+@noindent
+A library is, conceptually, a collection of objects which does not have its
+own main thread of execution, but rather provides certain services to the
+applications that use it. A library can be either statically linked with the
+application, in which case its code is directly included in the application,
+or, on platforms that support it, be dynamically linked, in which case
+its code is shared by all applications making use of this library.
-@node Other Formatting Options
-@subsection Other Formatting Options
+GNAT supports both types of libraries.
+In the static case, the compiled code can be provided in different ways. The
+simplest approach is to provide directly the set of objects resulting from
+compilation of the library source files. Alternatively, you can group the
+objects into an archive using whatever commands are provided by the operating
+system. For the latter case, the objects are grouped into a shared library.
+
+In the GNAT environment, a library has three types of components:
+@itemize @bullet
+@item
+Source files.
+@item
+@file{ALI} files.
+@xref{The Ada Library Information Files}.
+@item
+Object files, an archive or a shared library.
+@end itemize
@noindent
-These switches control the inclusion of missing end/exit labels, and
-the indentation level in @b{case} statements.
+A GNAT library may expose all its source files, which is useful for
+documentation purposes. Alternatively, it may expose only the units needed by
+an external user to make use of the library. That is to say, the specs
+reflecting the library services along with all the units needed to compile
+those specs, which can include generic bodies or any body implementing an
+inlined routine. In the case of @emph{stand-alone libraries} those exposed
+units are called @emph{interface units} (@pxref{Stand-alone Ada Libraries}).
-@table @option
-@item ^-e^/NO_MISSED_LABELS^
-@cindex @option{^-e^/NO_MISSED_LABELS^} (@command{gnatpp})
-Do not insert missing end/exit labels. An end label is the name of
-a construct that may optionally be repeated at the end of the
-construct's declaration;
-e.g., the names of packages, subprograms, and tasks.
-An exit label is the name of a loop that may appear as target
-of an exit statement within the loop.
-By default, @command{gnatpp} inserts these end/exit labels when
-they are absent from the original source. This option suppresses such
-insertion, so that the formatted source reflects the original.
+All compilation units comprising an application, including those in a library,
+need to be elaborated in an order partially defined by Ada's semantics. GNAT
+computes the elaboration order from the @file{ALI} files and this is why they
+constitute a mandatory part of GNAT libraries.
+@emph{Stand-alone libraries} are the exception to this rule because a specific
+library elaboration routine is produced independently of the application(s)
+using the library.
-@item ^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^
-@cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp})
-Insert a Form Feed character after a pragma Page.
+@node General Ada Libraries
+@section General Ada Libraries
-@item ^-T@var{nnn}^/MAX_INDENT=@var{nnn}^
-@cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp})
-Do not use an additional indentation level for @b{case} alternatives
-and variants if there are @var{nnn} or more (the default
-value is 10).
-If @var{nnn} is 0, an additional indentation level is
-used for @b{case} alternatives and variants regardless of their number.
-@end table
+@menu
+* Building a library::
+* Installing a library::
+* Using a library::
+@end menu
-@node Setting the Source Search Path
-@subsection Setting the Source Search Path
+@node Building a library
+@subsection Building a library
@noindent
-To define the search path for the input source file, @command{gnatpp}
-uses the same switches as the GNAT compiler, with the same effects.
-
-@table @option
-@item ^-I^/SEARCH=^@var{dir}
-@cindex @option{^-I^/SEARCH^} (@code{gnatpp})
-The same as the corresponding gcc switch
-
-@item ^-I-^/NOCURRENT_DIRECTORY^
-@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatpp})
-The same as the corresponding gcc switch
+The easiest way to build a library is to use the Project Manager,
+which supports a special type of project called a @emph{Library Project}
+(@pxref{Library Projects}).
-@item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE^=@var{path}
-@cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@code{gnatpp})
-The same as the corresponding gcc switch
+A project is considered a library project, when two project-level attributes
+are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to
+control different aspects of library configuration, additional optional
+project-level attributes can be specified:
+@table @code
+@item Library_Kind
+This attribute controls whether the library is to be static or dynamic
-@item ^--RTS^/RUNTIME_SYSTEM^=@var{path}
-@cindex @option{^--RTS^/RUNTIME_SYSTEM^} (@code{gnatpp})
-The same as the corresponding gcc switch
+@item Library_Version
+This attribute specifies the library version; this value is used
+during dynamic linking of shared libraries to determine if the currently
+installed versions of the binaries are compatible.
+@item Library_Options
+@item Library_GCC
+These attributes specify additional low-level options to be used during
+library generation, and redefine the actual application used to generate
+library.
@end table
-@node Output File Control
-@subsection Output File Control
-
@noindent
-By default the output is sent to the file whose name is obtained by appending
-the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file
-(if the file with this name already exists, it is unconditionally overwritten).
-Thus if the input file is @file{^my_ada_proc.adb^MY_ADA_PROC.ADB^} then
-@command{gnatpp} will produce @file{^my_ada_proc.adb.pp^MY_ADA_PROC.ADB$PP^}
-as output file.
-The output may be redirected by the following switches:
-
-@table @option
-@item ^-pipe^/STANDARD_OUTPUT^
-@cindex @option{^-pipe^/STANDARD_OUTPUT^} (@code{gnatpp})
-Send the output to @code{Standard_Output}
-
-@item ^-o @var{output_file}^/OUTPUT=@var{output_file}^
-@cindex @option{^-o^/OUTPUT^} (@code{gnatpp})
-Write the output into @var{output_file}.
-If @var{output_file} already exists, @command{gnatpp} terminates without
-reading or processing the input file.
-
-@item ^-of ^/FORCED_OUTPUT=^@var{output_file}
-@cindex @option{^-of^/FORCED_OUTPUT^} (@code{gnatpp})
-Write the output into @var{output_file}, overwriting the existing file
-(if one is present).
-
-@item ^-r^/REPLACE^
-@cindex @option{^-r^/REPLACE^} (@code{gnatpp})
-Replace the input source file with the reformatted output, and copy the
-original input source into the file whose name is obtained by appending the
-^@file{.npp}^@file{$NPP}^ suffix to the name of the input file.
-If a file with this name already exists, @command{gnatpp} terminates without
-reading or processing the input file.
-
-@item ^-rf^/OVERRIDING_REPLACE^
-@cindex @option{^-rf^/OVERRIDING_REPLACE^} (@code{gnatpp})
-Like @option{^-r^/REPLACE^} except that if the file with the specified name
-already exists, it is overwritten.
-
-@item ^-rnb^/REPLACE_NO_BACKUP^
-@cindex @option{^-rnb^/REPLACE_NO_BACKUP^} (@code{gnatpp})
-Replace the input source file with the reformatted output without
-creating any backup copy of the input source.
-
-@item ^--eol=@var{xxx}^/END_OF_LINE=@var{xxx}^
-@cindex @option{^--eol^/END_OF_LINE^} (@code{gnatpp})
-Specifies the format of the reformatted output file. The @var{xxx}
-^string specified with the switch^option^ may be either
-@itemize @bullet
-@item ``@option{^dos^DOS^}'' MS DOS style, lines end with CR LF characters
-@item ``@option{^crlf^CRLF^}''
-the same as @option{^crlf^CRLF^}
-@item ``@option{^unix^UNIX^}'' UNIX style, lines end with LF character
-@item ``@option{^lf^LF^}''
-the same as @option{^unix^UNIX^}
-@end itemize
-
-@item ^-W^/RESULT_ENCODING=^@var{e}
-@cindex @option{^-W^/RESULT_ENCODING=^} (@command{gnatpp})
-Specify the wide character encoding method used to write the code in the
-result file
-@var{e} is one of the following:
-
-@itemize @bullet
-
-@item ^h^HEX^
-Hex encoding
-
-@item ^u^UPPER^
-Upper half encoding
-
-@item ^s^SHIFT_JIS^
-Shift/JIS encoding
-
-@item ^e^EUC^
-EUC encoding
-
-@item ^8^UTF8^
-UTF-8 encoding
-
-@item ^b^BRACKETS^
-Brackets encoding (default value)
-@end itemize
-
-@end table
-
-@noindent
-Options @option{^-pipe^/STANDARD_OUTPUT^},
-@option{^-o^/OUTPUT^} and
-@option{^-of^/FORCED_OUTPUT^} are allowed only if the call to gnatpp
-contains only one file to reformat.
-Option
-@option{^--eol^/END_OF_LINE^}
-and
-@option{^-W^/RESULT_ENCODING^}
-cannot be used together
-with @option{^-pipe^/STANDARD_OUTPUT^} option.
-
-@node Other gnatpp Switches
-@subsection Other @code{gnatpp} Switches
-
-@noindent
-The additional @command{gnatpp} switches are defined in this subsection.
-
-@table @option
-@item ^-files @var{filename}^/FILES=@var{output_file}^
-@cindex @option{^-files^/FILES^} (@code{gnatpp})
-Take the argument source files from the specified file. This file should be an
-ordinary textual file containing file names separated by spaces or
-line breaks. You can use this switch more then once in the same call to
-@command{gnatpp}. You also can combine this switch with explicit list of
-files.
-
-@item ^-v^/VERBOSE^
-@cindex @option{^-v^/VERBOSE^} (@code{gnatpp})
-Verbose mode;
-@command{gnatpp} generates version information and then
-a trace of the actions it takes to produce or obtain the ASIS tree.
-
-@item ^-w^/WARNINGS^
-@cindex @option{^-w^/WARNINGS^} (@code{gnatpp})
-Warning mode;
-@command{gnatpp} generates a warning whenever it cannot provide
-a required layout in the result source.
-@end table
-
-@node Formatting Rules
-@section Formatting Rules
-
-@noindent
-The following subsections show how @command{gnatpp} treats ``white space'',
-comments, program layout, and name casing.
-They provide the detailed descriptions of the switches shown above.
-
-@menu
-* White Space and Empty Lines::
-* Formatting Comments::
-* Construct Layout::
-* Name Casing::
-@end menu
-
-@node White Space and Empty Lines
-@subsection White Space and Empty Lines
-
-@noindent
-@command{gnatpp} does not have an option to control space characters.
-It will add or remove spaces according to the style illustrated by the
-examples in the @cite{Ada Reference Manual}.
-
-The only format effectors
-(see @cite{Ada Reference Manual}, paragraph 2.1(13))
-that will appear in the output file are platform-specific line breaks,
-and also format effectors within (but not at the end of) comments.
-In particular, each horizontal tab character that is not inside
-a comment will be treated as a space and thus will appear in the
-output file as zero or more spaces depending on
-the reformatting of the line in which it appears.
-The only exception is a Form Feed character, which is inserted after a
-pragma @code{Page} when @option{-ff} is set.
-
-The output file will contain no lines with trailing ``white space'' (spaces,
-format effectors).
-
-Empty lines in the original source are preserved
-only if they separate declarations or statements.
-In such contexts, a
-sequence of two or more empty lines is replaced by exactly one empty line.
-Note that a blank line will be removed if it separates two ``comment blocks''
-(a comment block is a sequence of whole-line comments).
-In order to preserve a visual separation between comment blocks, use an
-``empty comment'' (a line comprising only hyphens) rather than an empty line.
-Likewise, if for some reason you wish to have a sequence of empty lines,
-use a sequence of empty comments instead.
-
-@node Formatting Comments
-@subsection Formatting Comments
-
-@noindent
-Comments in Ada code are of two kinds:
-@itemize @bullet
-@item
-a @emph{whole-line comment}, which appears by itself (possibly preceded by
-``white space'') on a line
-
-@item
-an @emph{end-of-line comment}, which follows some other Ada lexical element
-on the same line.
-@end itemize
-
-@noindent
-The indentation of a whole-line comment is that of either
-the preceding or following line in
-the formatted source, depending on switch settings as will be described below.
-
-For an end-of-line comment, @command{gnatpp} leaves the same number of spaces
-between the end of the preceding Ada lexical element and the beginning
-of the comment as appear in the original source,
-unless either the comment has to be split to
-satisfy the line length limitation, or else the next line contains a
-whole line comment that is considered a continuation of this end-of-line
-comment (because it starts at the same position).
-In the latter two
-cases, the start of the end-of-line comment is moved right to the nearest
-multiple of the indentation level.
-This may result in a ``line overflow'' (the right-shifted comment extending
-beyond the maximum line length), in which case the comment is split as
-described below.
-
-There is a difference between @option{^-c1^/COMMENTS_LAYOUT=DEFAULT^}
-(GNAT-style comment line indentation)
-and @option{^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^}
-(reference-manual comment line indentation).
-With reference-manual style, a whole-line comment is indented as if it
-were a declaration or statement at the same place
-(i.e., according to the indentation of the preceding line(s)).
-With GNAT style, a whole-line comment that is immediately followed by an
-@b{if} or @b{case} statement alternative, a record variant, or the reserved
-word @b{begin}, is indented based on the construct that follows it.
-
-For example:
-@smallexample @c ada
-@cartouche
-if A then
- null;
- -- some comment
-else
- null;
-end if;
-@end cartouche
-@end smallexample
-
-@noindent
-Reference-manual indentation produces:
-
-@smallexample @c ada
-@cartouche
-if A then
- null;
- -- some comment
-else
- null;
-end if;
-@end cartouche
-@end smallexample
-
-@noindent
-while GNAT-style indentation produces:
-
-@smallexample @c ada
-@cartouche
-if A then
- null;
--- some comment
-else
- null;
-end if;
-@end cartouche
-@end smallexample
-
-@noindent
-The @option{^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^} switch
-(GNAT style comment beginning) has the following
-effect:
-
-@itemize @bullet
-@item
-For each whole-line comment that does not end with two hyphens,
-@command{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.
-@end itemize
-
-@noindent
-For an end-of-line comment, if in the original source the next line is a
-whole-line comment that starts at the same position
-as the end-of-line comment,
-then the whole-line comment (and all whole-line comments
-that follow it and that start at the same position)
-will start at this position in the output file.
-
-@noindent
-That is, if in the original source we have:
-
-@smallexample @c ada
-@cartouche
-begin
-A := B + C; -- B must be in the range Low1..High1
- -- C must be in the range Low2..High2
- --B+C will be in the range Low1+Low2..High1+High2
-X := X + 1;
-@end cartouche
-@end smallexample
-
-@noindent
-Then in the formatted source we get
-
-@smallexample @c ada
-@cartouche
-begin
- A := B + C; -- B must be in the range Low1..High1
- -- C must be in the range Low2..High2
- -- B+C will be in the range Low1+Low2..High1+High2
- X := X + 1;
-@end cartouche
-@end smallexample
-
-@noindent
-A comment that exceeds the line length limit will be split.
-Unless switch
-@option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} (reformat comment blocks) is set and
-the line belongs to a reformattable block, splitting the line generates a
-@command{gnatpp} warning.
-The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that whole-line
-comments may be reformatted in typical
-word processor style (that is, moving words between lines and putting as
-many words in a line as possible).
-
-@noindent
-The @option{^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^} switch specifies, that comments
-that has a special format (that is, a character that is neither a letter nor digit
-not white space nor line break immediately following the leading @code{--} of
-the comment) should be without any change moved from the argument source
-into reformatted source. This switch allows to preserve comments that are used
-as a special marks in the code (e.g.@: SPARK annotation).
-
-@node Construct Layout
-@subsection Construct Layout
-
-@noindent
-In several cases the suggested layout in the Ada Reference Manual includes
-an extra level of indentation that many programmers prefer to avoid. The
-affected cases include:
-
-@itemize @bullet
-
-@item Record type declaration (RM 3.8)
-
-@item Record representation clause (RM 13.5.1)
-
-@item Loop statement in case if a loop has a statement identifier (RM 5.6)
-
-@item Block statement in case if a block has a statement identifier (RM 5.6)
-@end itemize
-
-@noindent
-In compact mode (when GNAT style layout or compact layout is set),
-the pretty printer uses one level of indentation instead
-of two. This is achieved in the record definition and record representation
-clause cases by putting the @code{record} keyword on the same line as the
-start of the declaration or representation clause, and in the block and loop
-case by putting the block or loop header on the same line as the statement
-identifier.
-
-@noindent
-The difference between GNAT style @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^}
-and compact @option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^}
-layout on the one hand, and uncompact layout
-@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} on the other hand,
-can be illustrated by the following examples:
-
-@iftex
-@cartouche
-@multitable @columnfractions .5 .5
-@item @i{GNAT style, compact layout} @tab @i{Uncompact layout}
-
-@item
-@smallexample @c ada
-type q is record
- a : integer;
- b : integer;
-end record;
-@end smallexample
-@tab
-@smallexample @c ada
-type q is
- record
- a : integer;
- b : integer;
- end record;
-@end smallexample
-
-@item
-@smallexample @c ada
-for q use record
- a at 0 range 0 .. 31;
- b at 4 range 0 .. 31;
-end record;
-@end smallexample
-@tab
-@smallexample @c ada
-for q use
- record
- a at 0 range 0 .. 31;
- b at 4 range 0 .. 31;
- end record;
-@end smallexample
-
-@item
-@smallexample @c ada
-Block : declare
- A : Integer := 3;
-begin
- Proc (A, A);
-end Block;
-@end smallexample
-@tab
-@smallexample @c ada
-Block :
- declare
- A : Integer := 3;
- begin
- Proc (A, A);
- end Block;
-@end smallexample
-
-@item
-@smallexample @c ada
-Clear : for J in 1 .. 10 loop
- A (J) := 0;
-end loop Clear;
-@end smallexample
-@tab
-@smallexample @c ada
-Clear :
- for J in 1 .. 10 loop
- A (J) := 0;
- end loop Clear;
-@end smallexample
-@end multitable
-@end cartouche
-@end iftex
-
-@ifnottex
-@smallexample
-@cartouche
-GNAT style, compact layout Uncompact layout
-
-type q is record type q is
- a : integer; record
- b : integer; a : integer;
-end record; b : integer;
- end record;
-
-for q use record for q use
- a at 0 range 0 .. 31; record
- b at 4 range 0 .. 31; a at 0 range 0 .. 31;
-end record; b at 4 range 0 .. 31;
- end record;
-
-Block : declare Block :
- A : Integer := 3; declare
-begin A : Integer := 3;
- Proc (A, A); begin
-end Block; Proc (A, A);
- end Block;
-
-Clear : for J in 1 .. 10 loop Clear :
- A (J) := 0; for J in 1 .. 10 loop
-end loop Clear; A (J) := 0;
- end loop Clear;
-@end cartouche
-@end smallexample
-@end ifnottex
-
-@noindent
-A further difference between GNAT style layout and compact layout is that
-GNAT style layout inserts empty lines as separation for
-compound statements, return statements and bodies.
-
-Note that the layout specified by
-@option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^}
-for named block and loop statements overrides the layout defined by these
-constructs by @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^},
-@option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} or
-@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} option.
-
-@node Name Casing
-@subsection Name Casing
-
-@noindent
-@command{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
-@option{^-n^/NAME_CASING^} switch.
-@ifclear vms
-With @option{-nD} (``as declared'', which is the default),
-@end ifclear
-@ifset vms
-With @option{/NAME_CASING=AS_DECLARED}, which is the default,
-@end ifset
-defining occurrences appear exactly as in the source file
-where they are declared.
-The other ^values for this switch^options for this qualifier^ ---
-@option{^-nU^UPPER_CASE^},
-@option{^-nL^LOWER_CASE^},
-@option{^-nM^MIXED_CASE^} ---
-result in
-^upper, lower, or mixed case, respectively^the corresponding casing^.
-If @command{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 @command{gnatpp}, the casing of each reference to
-this name is changed according to the value of the @option{^-n^/NAME_CASING^}
-switch (subject to the dictionary file mechanism described below).
-Thus @command{gnatpp} acts as though the @option{^-n^/NAME_CASING^} switch
-had affected the
-casing for the defining occurrence of the name.
-
-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
-@emph{dictionary file},
-and then supplying a @option{^-D^/DICTIONARY^} switch.
-The casing of names from dictionary files overrides
-any @option{^-n^/NAME_CASING^} switch.
-
-To handle the casing of Ada predefined names and the names from GNAT libraries,
-@command{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 @cite{Ada Reference Manual}.
-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 @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of the
-default dictionary file.
-Instead, the casing for predefined and GNAT-defined names will be established
-by the @option{^-n^/NAME_CASING^} switch or explicit dictionary files.
-For example, by default the names @code{Ada.Text_IO} and @code{GNAT.OS_Lib}
-will appear as just shown,
-even in the presence of a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch.
-To ensure that even such names are rendered in uppercase,
-additionally supply the @w{@option{^-D-^/SPECIFIC_CASING^}} switch
-(or else, less conveniently, 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 and ASCII.HT characters), an Ada comment
-line, or the specification of exactly one @emph{casing schema}.
-
-A casing schema is a string that has the following syntax:
-
-@smallexample
-@cartouche
- @var{casing_schema} ::= @var{identifier} | *@var{simple_identifier}*
-
- @var{simple_identifier} ::= @var{letter}@{@var{letter_or_digit}@}
-@end cartouche
-@end smallexample
-
-@noindent
-(See @cite{Ada Reference Manual}, Section 2.3) for the definition of the
-@var{identifier} lexical element and the @var{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
-@ifclear vms
-the value of a @option{-D@var{file}} switch
-@end ifclear
-@ifset vms
-an option to the @option{/DICTIONARY} qualifier
-@end ifset
-then for every
-simple name and every identifier, @command{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):
-
-@itemize @bullet
-@item
-if the whole name is in the dictionary, @command{gnatpp} uses for this name
-the casing defined by the dictionary; no subwords are checked for this word
-
-@item
-for every subword @command{gnatpp} checks if the dictionary contains the
-corresponding string of the form @code{*@var{simple_identifier}*},
-and if it does, the casing of this @var{simple_identifier} is used
-for this subword
-
-@item
-if the whole name does not contain any ``_'' inside, and if for this name
-the dictionary contains two entries - one of the form @var{identifier},
-and another - of the form *@var{simple_identifier}*, then the first one
-is applied to define the casing of this name
-
-@item
-if more than one dictionary file is passed as @command{gnatpp} switches, each
-dictionary adds new casing exceptions and overrides all the existing casing
-exceptions set by the previous dictionaries
-
-@item
-when @command{gnatpp} checks if the word or subword is in the dictionary,
-this check is not case sensitive
-@end itemize
-
-@noindent
-For example, suppose we have the following source to reformat:
-
-@smallexample @c ada
-@cartouche
-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;
-@end cartouche
-@end smallexample
-
-@noindent
-And suppose we have two dictionaries:
-
-@smallexample
-@cartouche
-@i{dict1:}
- NAME1
- *NaMe3*
- *Name1*
-@end cartouche
-
-@cartouche
-@i{dict2:}
- *NAME3*
-@end cartouche
-@end smallexample
-
-@noindent
-If @command{gnatpp} is called with the following switches:
-
-@smallexample
-@ifclear vms
-@command{gnatpp -nM -D dict1 -D dict2 test.adb}
-@end ifclear
-@ifset vms
-@command{gnatpp test.adb /NAME_CASING=MIXED_CASE /DICTIONARY=(dict1, dict2)}
-@end ifset
-@end smallexample
-
-@noindent
-then we will get the following name casing in the @command{gnatpp} output:
-
-@smallexample @c ada
-@cartouche
-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;
-@end cartouche
-@end smallexample
-
-@c *********************************
-@node The GNAT Metric Tool gnatmetric
-@chapter The GNAT Metric Tool @command{gnatmetric}
-@findex gnatmetric
-@cindex Metric tool
-
-@noindent
-^The @command{gnatmetric} tool^@command{GNAT METRIC}^ is an ASIS-based utility
-for computing various program metrics.
-It takes an Ada source file as input and generates a file containing the
-metrics data as output. Various switches control which
-metrics are computed and output.
-
-@command{gnatmetric} generates and uses the ASIS
-tree for the input source and thus requires the input to be syntactically and
-semantically legal.
-If this condition is not met, @command{gnatmetric} will generate
-an error message; no metric information for this file will be
-computed and reported.
-
-If the compilation unit contained in the input source depends semantically
-upon units in files located outside the current directory, you have to provide
-the source search path when invoking @command{gnatmetric}.
-If it depends semantically upon units that are contained
-in files with names that do not follow the GNAT file naming rules, you have to
-provide the configuration file describing the corresponding naming scheme (see
-the description of the @command{gnatmetric} switches below.)
-Alternatively, you may use a project file and invoke @command{gnatmetric}
-through the @command{gnat} driver.
-
-The @command{gnatmetric} command has the form
-
-@smallexample
-$ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
-@end smallexample
-
-@noindent
-where
-@itemize @bullet
-@item
-@var{switches} specify the metrics to compute and define the destination for
-the output
-
-@item
-Each @var{filename} is the name (including the extension) of a source
-file to process. ``Wildcards'' are allowed, and
-the file name may contain path information.
-If no @var{filename} is supplied, then the @var{switches} list must contain
-at least one
-@option{-files} switch (@pxref{Other gnatmetric Switches}).
-Including both a @option{-files} switch and one or more
-@var{filename} arguments is permitted.
-
-@item
-@samp{-cargs @var{gcc_switches}} is a list of switches for
-@command{gcc}. They will be passed on to all compiler invocations made by
-@command{gnatmetric} to generate the ASIS trees. Here you can provide
-@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
-and use the @option{-gnatec} switch to set the configuration file.
-@end itemize
-
-@menu
-* Switches for gnatmetric::
-@end menu
-
-@node Switches for gnatmetric
-@section Switches for @command{gnatmetric}
-
-@noindent
-The following subsections describe the various switches accepted by
-@command{gnatmetric}, organized by category.
-
-@menu
-* Output Files Control::
-* Disable Metrics For Local Units::
-* Specifying a set of metrics to compute::
-* Other gnatmetric Switches::
-* Generate project-wide metrics::
-@end menu
-
-@node Output Files Control
-@subsection Output File Control
-@cindex Output file control in @command{gnatmetric}
-
-@noindent
-@command{gnatmetric} has two output formats. It can generate a
-textual (human-readable) form, and also XML. By default only textual
-output is generated.
-
-When generating the output in textual form, @command{gnatmetric} creates
-for each Ada source file a corresponding text file
-containing the computed metrics, except for the case when the set of metrics
-specified by gnatmetric parameters consists only of metrics that are computed
-for the whole set of analyzed sources, but not for each Ada source.
-By default, this file is placed in the same directory as where the source
-file is located, and its name is obtained
-by appending the ^@file{.metrix}^@file{$METRIX}^ suffix to the name of the
-input file.
-
-All the output information generated in XML format is placed in a single
-file. By default this file is placed in the current directory and has the
-name ^@file{metrix.xml}^@file{METRIX$XML}^.
-
-Some of the computed metrics are summed over the units passed to
-@command{gnatmetric}; for example, the total number of lines of code.
-By default this information is sent to @file{stdout}, but a file
-can be specified with the @option{-og} switch.
-
-The following switches control the @command{gnatmetric} output:
-
-@table @option
-@cindex @option{^-x^/XML^} (@command{gnatmetric})
-@item ^-x^/XML^
-Generate the XML output
-
-@cindex @option{^-xs^/XSD^} (@command{gnatmetric})
-@item ^-xs^/XSD^
-Generate the XML output and the XML schema file that describes the structure
-of the XML metric report, this schema is assigned to the XML file. The schema
-file has the same name as the XML output file with @file{.xml} suffix replaced
-with @file{.xsd}
-
-@cindex @option{^-nt^/NO_TEXT^} (@command{gnatmetric})
-@item ^-nt^/NO_TEXT^
-Do not generate the output in text form (implies @option{^-x^/XML^})
-
-@cindex @option{^-d^/DIRECTORY^} (@command{gnatmetric})
-@item ^-d @var{output_dir}^/DIRECTORY=@var{output_dir}^
-Put textual files with detailed metrics into @var{output_dir}
-
-@cindex @option{^-o^/SUFFIX_DETAILS^} (@command{gnatmetric})
-@item ^-o @var{file_suffix}^/SUFFIX_DETAILS=@var{file_suffix}^
-Use @var{file_suffix}, instead of ^@file{.metrix}^@file{$METRIX}^
-in the name of the output file.
-
-@cindex @option{^-og^/GLOBAL_OUTPUT^} (@command{gnatmetric})
-@item ^-og @var{file_name}^/GLOBAL_OUTPUT=@var{file_name}^
-Put global metrics into @var{file_name}
-
-@cindex @option{^-ox^/XML_OUTPUT^} (@command{gnatmetric})
-@item ^-ox @var{file_name}^/XML_OUTPUT=@var{file_name}^
-Put the XML output into @var{file_name} (also implies @option{^-x^/XML^})
-
-@cindex @option{^-sfn^/SHORT_SOURCE_FILE_NAME^} (@command{gnatmetric})
-@item ^-sfn^/SHORT_SOURCE_FILE_NAME^
-Use ``short'' source file names in the output. (The @command{gnatmetric}
-output includes the name(s) of the Ada source file(s) from which the metrics
-are computed. By default each name includes the absolute path. The
-@option{^-sfn^/SHORT_SOURCE_FILE_NAME^} switch causes @command{gnatmetric}
-to exclude all directory information from the file names that are output.)
-
-@end table
-
-@node Disable Metrics For Local Units
-@subsection Disable Metrics For Local Units
-@cindex Disable Metrics For Local Units in @command{gnatmetric}
-
-@noindent
-@command{gnatmetric} relies on the GNAT compilation model @minus{}
-one compilation
-unit per one source file. It computes line metrics for the whole source
-file, and it also computes syntax
-and complexity metrics for the file's outermost unit.
-
-By default, @command{gnatmetric} will also compute all metrics for certain
-kinds of locally declared program units:
-
-@itemize @bullet
-@item
-subprogram (and generic subprogram) bodies;
-
-@item
-package (and generic package) specs and bodies;
-
-@item
-task object and type specifications and bodies;
-
-@item
-protected object and type specifications and bodies.
-@end itemize
-
-@noindent
-These kinds of entities will be referred to as
-@emph{eligible local program units}, or simply @emph{eligible local units},
-@cindex Eligible local unit (for @command{gnatmetric})
-in the discussion below.
-
-Note that a subprogram declaration, generic instantiation,
-or renaming declaration only receives metrics
-computation when it appear as the outermost entity
-in a source file.
-
-Suppression of metrics computation for eligible local units can be
-obtained via the following switch:
-
-@table @option
-@cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric})
-@item ^-nolocal^/SUPPRESS=LOCAL_DETAILS^
-Do not compute detailed metrics for eligible local program units
-
-@end table
-
-@node Specifying a set of metrics to compute
-@subsection Specifying a set of metrics to compute
-
-@noindent
-By default all the metrics are computed and reported. The switches
-described in this subsection allow you to control, on an individual
-basis, whether metrics are computed and
-reported. If at least one positive metric
-switch is specified (that is, a switch that defines that a given
-metric or set of metrics is to be computed), then only
-explicitly specified metrics are reported.
-
-@menu
-* Line Metrics Control::
-* Syntax Metrics Control::
-* Complexity Metrics Control::
-* Object-Oriented Metrics Control::
-@end menu
-
-@node Line Metrics Control
-@subsubsection Line Metrics Control
-@cindex Line metrics control in @command{gnatmetric}
-
-@noindent
-For any (legal) source file, and for each of its
-eligible local program units, @command{gnatmetric} computes the following
-metrics:
-
-@itemize @bullet
-@item
-the total number of lines;
-
-@item
-the total number of code lines (i.e., non-blank lines that are not comments)
-
-@item
-the number of comment lines
-
-@item
-the number of code lines containing end-of-line comments;
-
-@item
-the comment percentage: the ratio between the number of lines that contain
-comments and the number of all non-blank lines, expressed as a percentage;
-
-@item
-the number of empty lines and lines containing only space characters and/or
-format effectors (blank lines)
-
-@item
-the average number of code lines in subprogram bodies, task bodies, entry
-bodies and statement sequences in package bodies (this metric is only computed
-across the whole set of the analyzed units)
-
-@end itemize
-
-@noindent
-@command{gnatmetric} sums the values of the line metrics for all the
-files being processed and then generates the cumulative results. The tool
-also computes for all the files being processed the average number of code
-lines in bodies.
-
-You can use the following switches to select the specific line metrics
-to be computed and reported.
-
-@table @option
-@cindex @option{^--lines@var{x}^/LINE_COUNT_METRICS^} (@command{gnatmetric})
-
-@ifclear vms
-@cindex @option{--no-lines@var{x}}
-@end ifclear
-
-@item ^--lines-all^/LINE_COUNT_METRICS=ALL^
-Report all the line metrics
-
-@item ^--no-lines-all^/LINE_COUNT_METRICS=NONE^
-Do not report any of line metrics
-
-@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES^
-Report the number of all lines
-
-@item ^--no-lines^/LINE_COUNT_METRICS=NOALL_LINES^
-Do not report the number of all lines
-
-@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES^
-Report the number of code lines
-
-@item ^--no-lines-code^/LINE_COUNT_METRICS=NOCODE_LINES^
-Do not report the number of code lines
-
-@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES^
-Report the number of comment lines
-
-@item ^--no-lines-comment^/LINE_COUNT_METRICS=NOCOMMENT_LINES^
-Do not report the number of comment lines
-
-@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES^
-Report the number of code lines containing
-end-of-line comments
-
-@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=NOCODE_COMMENT_LINES^
-Do not report the number of code lines containing
-end-of-line comments
-
-@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE^
-Report the comment percentage in the program text
-
-@item ^--no-lines-ratio^/LINE_COUNT_METRICS=NOCOMMENT_PERCENTAGE^
-Do not report the comment percentage in the program text
-
-@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES^
-Report the number of blank lines
-
-@item ^--no-lines-blank^/LINE_COUNT_METRICS=NOBLANK_LINES^
-Do not report the number of blank lines
-
-@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES^
-Report the average number of code lines in subprogram bodies, task bodies,
-entry bodies and statement sequences in package bodies. The metric is computed
-and reported for the whole set of processed Ada sources only.
-
-@item ^--no-lines-average^/LINE_COUNT_METRICS=NOAVERAGE_BODY_LINES^
-Do not report the average number of code lines in subprogram bodies,
-task bodies, entry bodies and statement sequences in package bodies.
-
-@end table
-
-@node Syntax Metrics Control
-@subsubsection Syntax Metrics Control
-@cindex Syntax metrics control in @command{gnatmetric}
-
-@noindent
-@command{gnatmetric} computes various syntactic metrics for the
-outermost unit and for each eligible local unit:
-
-@table @emph
-@item LSLOC (``Logical Source Lines Of Code'')
-The total number of declarations and the total number of statements
-
-@item Maximal static nesting level of inner program units
-According to
-@cite{Ada Reference Manual}, 10.1(1), ``A program unit is either a
-package, a task unit, a protected unit, a
-protected entry, a generic unit, or an explicitly declared subprogram other
-than an enumeration literal.''
-
-@item Maximal nesting level of composite syntactic constructs
-This corresponds to the notion of the
-maximum nesting level in the GNAT built-in style checks
-(@pxref{Style Checking})
-@end table
-
-@noindent
-For the outermost unit in the file, @command{gnatmetric} additionally computes
-the following metrics:
-
-@table @emph
-@item Public subprograms
-This metric is computed for package specs. It is the
-number of subprograms and generic subprograms declared in the visible
-part (including the visible part of nested packages, protected objects, and
-protected types).
-
-@item All subprograms
-This metric is computed for bodies and subunits. The
-metric is equal to a total number of subprogram bodies in the compilation
-unit.
-Neither generic instantiations nor renamings-as-a-body nor body stubs
-are counted. Any subprogram body is counted, independently of its nesting
-level and enclosing constructs. Generic bodies and bodies of protected
-subprograms are counted in the same way as ``usual'' subprogram bodies.
-
-@item Public types
-This metric is computed for package specs and
-generic package declarations. It is the total number of types
-that can be referenced from outside this compilation unit, plus the
-number of types from all the visible parts of all the visible generic
-packages. Generic formal types are not counted. Only types, not subtypes,
-are included.
-
-@noindent
-Along with the total number of public types, the following
-types are counted and reported separately:
-
-@itemize @bullet
-@item
-Abstract types
-
-@item
-Root tagged types (abstract, non-abstract, private, non-private). Type
-extensions are @emph{not} counted
-
-@item
-Private types (including private extensions)
-
-@item
-Task types
-
-@item
-Protected types
-
-@end itemize
-
-@item All types
-This metric is computed for any compilation unit. It is equal to the total
-number of the declarations of different types given in the compilation unit.
-The private and the corresponding full type declaration are counted as one
-type declaration. Incomplete type declarations and generic formal types
-are not counted.
-No distinction is made among different kinds of types (abstract,
-private etc.); the total number of types is computed and reported.
-
-@end table
-
-@noindent
-By default, all the syntax metrics are computed and reported. You can use the
-following switches to select specific syntax metrics.
-
-@table @option
-
-@cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric})
-
-@ifclear vms
-@cindex @option{--no-syntax@var{x}} (@command{gnatmetric})
-@end ifclear
-
-@item ^--syntax-all^/SYNTAX_METRICS=ALL^
-Report all the syntax metrics
-
-@item ^--no-syntax-all^/SYNTAX_METRICS=NONE^
-Do not report any of syntax metrics
-
-@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS^
-Report the total number of declarations
-
-@item ^--no-declarations^/SYNTAX_METRICS=NODECLARATIONS^
-Do not report the total number of declarations
-
-@item ^--statements^/SYNTAX_METRICS=STATEMENTS^
-Report the total number of statements
-
-@item ^--no-statements^/SYNTAX_METRICS=NOSTATEMENTS^
-Do not report the total number of statements
-
-@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS^
-Report the number of public subprograms in a compilation unit
-
-@item ^--no-public-subprograms^/SYNTAX_METRICS=NOPUBLIC_SUBPROGRAMS^
-Do not report the number of public subprograms in a compilation unit
-
-@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS^
-Report the number of all the subprograms in a compilation unit
-
-@item ^--no-all-subprograms^/SYNTAX_METRICS=NOALL_SUBPROGRAMS^
-Do not report the number of all the subprograms in a compilation unit
-
-@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES^
-Report the number of public types in a compilation unit
-
-@item ^--no-public-types^/SYNTAX_METRICS=NOPUBLIC_TYPES^
-Do not report the number of public types in a compilation unit
-
-@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES^
-Report the number of all the types in a compilation unit
-
-@item ^--no-all-types^/SYNTAX_METRICS=NOALL_TYPES^
-Do not report the number of all the types in a compilation unit
-
-@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING^
-Report the maximal program unit nesting level
-
-@item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^
-Do not report the maximal program unit nesting level
-
-@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING^
-Report the maximal construct nesting level
-
-@item ^--no-construct-nesting^/SYNTAX_METRICS=NOCONSTRUCT_NESTING^
-Do not report the maximal construct nesting level
-
-@end table
-
-@node Complexity Metrics Control
-@subsubsection Complexity Metrics Control
-@cindex Complexity metrics control in @command{gnatmetric}
-
-@noindent
-For a program unit that is an executable body (a subprogram body (including
-generic bodies), task body, entry body or a package body containing
-its own statement sequence) @command{gnatmetric} computes the following
-complexity metrics:
-
-@itemize @bullet
-@item
-McCabe cyclomatic complexity;
-
-@item
-McCabe essential complexity;
-
-@item
-maximal loop nesting level
-
-@end itemize
-
-@noindent
-The McCabe complexity metrics are defined
-in @url{http://www.mccabe.com/pdf/nist235r.pdf}
-
-According to McCabe, both control statements and short-circuit control forms
-should be taken into account when computing cyclomatic complexity. For each
-body, we compute three metric values:
-
-@itemize @bullet
-@item
-the complexity introduced by control
-statements only, without taking into account short-circuit forms,
-
-@item
-the complexity introduced by short-circuit control forms only, and
-
-@item
-the total
-cyclomatic complexity, which is the sum of these two values.
-@end itemize
-
-@noindent
-When computing cyclomatic and essential complexity, @command{gnatmetric} skips
-the code in the exception handlers and in all the nested program units.
-
-By default, all the complexity metrics are computed and reported.
-For more fine-grained control you can use
-the following switches:
-
-@table @option
-@cindex @option{^-complexity@var{x}^/COMPLEXITY_METRICS^} (@command{gnatmetric})
-
-@ifclear vms
-@cindex @option{--no-complexity@var{x}}
-@end ifclear
-
-@item ^--complexity-all^/COMPLEXITY_METRICS=ALL^
-Report all the complexity metrics
-
-@item ^--no-complexity-all^/COMPLEXITY_METRICS=NONE^
-Do not report any of complexity metrics
-
-@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC^
-Report the McCabe Cyclomatic Complexity
-
-@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=NOCYCLOMATIC^
-Do not report the McCabe Cyclomatic Complexity
-
-@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL^
-Report the Essential Complexity
-
-@item ^--no-complexity-essential^/COMPLEXITY_METRICS=NOESSENTIAL^
-Do not report the Essential Complexity
-
-@item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^
-Report maximal loop nesting level
-
-@item ^--no-loop-nesting^/COMPLEXITY_METRICS=NOLOOP_NESTING^
-Do not report maximal loop nesting level
-
-@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY^
-Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
-task bodies, entry bodies and statement sequences in package bodies.
-The metric is computed and reported for whole set of processed Ada sources
-only.
-
-@item ^--no-complexity-average^/COMPLEXITY_METRICS=NOAVERAGE_COMPLEXITY^
-Do not report the average McCabe Cyclomatic Complexity for all the subprogram
-bodies, task bodies, entry bodies and statement sequences in package bodies
-
-@cindex @option{^-ne^/NO_EXITS_AS_GOTOS^} (@command{gnatmetric})
-@item ^-ne^/NO_EXITS_AS_GOTOS^
-Do not consider @code{exit} statements as @code{goto}s when
-computing Essential Complexity
-
-@item ^--extra-exit-points^/EXTRA_EXIT_POINTS^
-Report the extra exit points for subprogram bodies. As an exit point, this
-metric counts @code{return} statements and raise statements in case when the
-raised exception is not handled in the same body. In case of a function this
-metric subtracts 1 from the number of exit points, because a function body
-must contain at least one @code{return} statement.
-
-@item ^--no-extra-exit-points^/NOEXTRA_EXIT_POINTS^
-Do not report the extra exit points for subprogram bodies
-@end table
-
-
-@node Object-Oriented Metrics Control
-@subsubsection Object-Oriented Metrics Control
-@cindex Object-Oriented metrics control in @command{gnatmetric}
-
-@noindent
-@cindex Coupling metrics (in in @command{gnatmetric})
-Coupling metrics are object-oriented metrics that measure the
-dependencies between a given class (or a group of classes) and the
-``external world'' (that is, the other classes in the program). In this
-subsection the term ``class'' is used in its
-traditional object-oriented programming sense
-(an instantiable module that contains data and/or method members).
-A @emph{category} (of classes)
-is a group of closely related classes that are reused and/or
-modified together.
-
-A class @code{K}'s @emph{efferent coupling} is the number of classes
-that @code{K} depends upon.
-A category's efferent coupling is the number of classes outside the
-category that the classes inside the category depend upon.
-
-A class @code{K}'s @emph{afferent coupling} is the number of classes
-that depend upon @code{K}.
-A category's afferent coupling is the number of classes outside the
-category that depend on classes belonging to the category.
-
-Ada's implementation of the object-oriented paradigm does not use the
-traditional class notion, so the definition of the coupling
-metrics for Ada maps the class and class category notions
-onto Ada constructs.
-
-For the coupling metrics, several kinds of modules -- a library package,
-a library generic package, and a library generic package instantiation --
-that define a tagged type or an interface type are
-considered to be a class. A category consists of a library package (or
-a library generic package) that defines a tagged or an interface type,
-together with all its descendant (generic) packages that define tagged
-or interface types. For any package counted as a class,
-its body and subunits (if any) are considered
-together with its spec when counting the dependencies, and coupling
-metrics are reported for spec units only. For dependencies
-between classes, the Ada semantic dependencies are considered.
-For coupling metrics, only dependencies on units that are considered as
-classes, are considered.
-
-When computing coupling metrics, @command{gnatmetric} counts only
-dependencies between units that are arguments of the gnatmetric call.
-Coupling metrics are program-wide (or project-wide) metrics, so to
-get a valid result, you should call @command{gnatmetric} for
-the whole set of sources that make up your program. It can be done
-by calling @command{gnatmetric} from the GNAT driver with @option{-U}
-option (see See @ref{The GNAT Driver and Project Files} for details.
-
-By default, all the coupling metrics are disabled. You can use the following
-switches to specify the coupling metrics to be computed and reported:
-
-@table @option
-
-@ifclear vms
-@cindex @option{--package@var{x}} (@command{gnatmetric})
-@cindex @option{--no-package@var{x}} (@command{gnatmetric})
-@cindex @option{--category@var{x}} (@command{gnatmetric})
-@cindex @option{--no-category@var{x}} (@command{gnatmetric})
-@end ifclear
-
-@ifset vms
-@cindex @option{/COUPLING_METRICS} (@command{gnatmetric})
-@end ifset
-
-@item ^--coupling-all^/COUPLING_METRICS=ALL^
-Report all the coupling metrics
-
-@item ^--no-coupling-all^/COUPLING_METRICS=NONE^
-Do not report any of metrics
-
-@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT^
-Report package efferent coupling
-
-@item ^--no-package-efferent-coupling^/COUPLING_METRICS=NOPACKAGE_EFFERENT^
-Do not report package efferent coupling
-
-@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT^
-Report package afferent coupling
-
-@item ^--no-package-afferent-coupling^/COUPLING_METRICS=NOPACKAGE_AFFERENT^
-Do not report package afferent coupling
-
-@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT^
-Report category efferent coupling
-
-@item ^--no-category-efferent-coupling^/COUPLING_METRICS=NOCATEGORY_EFFERENT^
-Do not report category efferent coupling
-
-@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT^
-Report category afferent coupling
-
-@item ^--no-category-afferent-coupling^/COUPLING_METRICS=NOCATEGORY_AFFERENT^
-Do not report category afferent coupling
-
-@end table
-
-@node Other gnatmetric Switches
-@subsection Other @code{gnatmetric} Switches
-
-@noindent
-Additional @command{gnatmetric} switches are as follows:
-
-@table @option
-@item ^-files @var{filename}^/FILES=@var{filename}^
-@cindex @option{^-files^/FILES^} (@code{gnatmetric})
-Take the argument source files from the specified file. This file should be an
-ordinary text file containing file names separated by spaces or
-line breaks. You can use this switch more then once in the same call to
-@command{gnatmetric}. You also can combine this switch with
-an explicit list of files.
-
-@item ^-v^/VERBOSE^
-@cindex @option{^-v^/VERBOSE^} (@code{gnatmetric})
-Verbose mode;
-@command{gnatmetric} generates version information and then
-a trace of sources being processed.
-
-@item ^-dv^/DEBUG_OUTPUT^
-@cindex @option{^-dv^/DEBUG_OUTPUT^} (@code{gnatmetric})
-Debug mode;
-@command{gnatmetric} generates various messages useful to understand what
-happens during the metrics computation
-
-@item ^-q^/QUIET^
-@cindex @option{^-q^/QUIET^} (@code{gnatmetric})
-Quiet mode.
-@end table
-
-@node Generate project-wide metrics
-@subsection Generate project-wide metrics
-
-In order to compute metrics on all units of a given project, you can use
-the @command{gnat} driver along with the @option{-P} option:
-@smallexample
- gnat metric -Pproj
-@end smallexample
-
-@noindent
-If the project @code{proj} depends upon other projects, you can compute
-the metrics on the project closure using the @option{-U} option:
-@smallexample
- gnat metric -Pproj -U
-@end smallexample
-
-@noindent
-Finally, if not all the units are relevant to a particular main
-program in the project closure, you can generate metrics for the set
-of units needed to create a given main program (unit closure) using
-the @option{-U} option followed by the name of the main unit:
-@smallexample
- gnat metric -Pproj -U main
-@end smallexample
-
-
-@c ***********************************
-@node File Name Krunching Using gnatkr
-@chapter File Name Krunching Using @code{gnatkr}
-@findex gnatkr
-
-@noindent
-This chapter discusses the method used by the compiler to shorten
-the default file names chosen for Ada units so that they do not
-exceed the maximum length permitted. It also describes the
-@code{gnatkr} utility that can be used to determine the result of
-applying this shortening.
-@menu
-* About gnatkr::
-* Using gnatkr::
-* Krunching Method::
-* Examples of gnatkr Usage::
-@end menu
-
-@node About gnatkr
-@section About @code{gnatkr}
-
-@noindent
-The default file naming rule in GNAT
-is that the file name must be derived from
-the unit name. The exact default rule is as follows:
-@itemize @bullet
-@item
-Take the unit name and replace all dots by hyphens.
-@item
-If such a replacement occurs in the
-second character position of a name, and the first character is
-^@samp{a}, @samp{g}, @samp{s}, or @samp{i}, ^@samp{A}, @samp{G}, @samp{S}, or @samp{I},^
-then replace the dot by the character
-^@samp{~} (tilde)^@samp{$} (dollar sign)^
-instead of a minus.
-@end itemize
-The reason for this exception is to avoid clashes
-with the standard names for children of System, Ada, Interfaces,
-and GNAT, which use the prefixes
-^@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},^@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},^
-respectively.
-
-The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}}
-switch of the compiler activates a ``krunching''
-circuit that limits file names to nn characters (where nn is a decimal
-integer). For example, using OpenVMS,
-where the maximum file name length is
-39, the value of nn is usually set to 39, but if you want to generate
-a set of files that would be usable if ported to a system with some
-different maximum file length, then a different value can be specified.
-The default value of 39 for OpenVMS need not be specified.
-
-The @code{gnatkr} utility can be used to determine the krunched name for
-a given file, when krunched to a specified maximum length.
-
-@node Using gnatkr
-@section Using @code{gnatkr}
-
-@noindent
-The @code{gnatkr} command has the form
-
-@ifclear vms
-@smallexample
-$ gnatkr @var{name} @ovar{length}
-@end smallexample
-@end ifclear
-
-@ifset vms
-@smallexample
-$ gnatkr @var{name} /COUNT=nn
-@end smallexample
-@end ifset
-
-@noindent
-@var{name} is the uncrunched file name, derived from the name of the unit
-in the standard manner described in the previous section (i.e., in particular
-all dots are replaced by hyphens). The file name may or may not have an
-extension (defined as a suffix of the form period followed by arbitrary
-characters other than period). If an extension is present then it will
-be preserved in the output. For example, when krunching @file{hellofile.ads}
-to eight characters, the result will be hellofil.ads.
-
-Note: for compatibility with previous versions of @code{gnatkr} dots may
-appear in the name instead of hyphens, but the last dot will always be
-taken as the start of an extension. So if @code{gnatkr} is given an argument
-such as @file{Hello.World.adb} it will be treated exactly as if the first
-period had been a hyphen, and for example krunching to eight characters
-gives the result @file{hellworl.adb}.
-
-Note that the result is always all lower case (except on OpenVMS where it is
-all upper case). Characters of the other case are folded as required.
-
-@var{length} represents the length of the krunched name. The default
-when no argument is given is ^8^39^ characters. A length of zero stands for
-unlimited, in other words do not chop except for system files where the
-implied crunching length is always eight characters.
-
-@noindent
-The output is the krunched name. The output has an extension only if the
-original argument was a file name with an extension.
-
-@node Krunching Method
-@section Krunching Method
-
-@noindent
-The initial file name is determined by the name of the unit that the file
-contains. The name is formed by taking the full expanded name of the
-unit and replacing the separating dots with hyphens and
-using ^lowercase^uppercase^
-for all letters, except that a hyphen in the second character position is
-replaced by a ^tilde^dollar sign^ if the first character is
-^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^.
-The extension is @code{.ads} for a
-spec and @code{.adb} for a body.
-Krunching does not affect the extension, but the file name is shortened to
-the specified length by following these rules:
-
-@itemize @bullet
-@item
-The name is divided into segments separated by hyphens, tildes or
-underscores and all hyphens, tildes, and underscores are
-eliminated. If this leaves the name short enough, we are done.
-
-@item
-If the name is too long, the longest segment is located (left-most
-if there are two of equal length), and shortened by dropping
-its last character. This is repeated until the name is short enough.
-
-As an example, consider the krunching of @*@file{our-strings-wide_fixed.adb}
-to fit the name into 8 characters as required by some operating systems.
-
-@smallexample
-our-strings-wide_fixed 22
-our strings wide fixed 19
-our string wide fixed 18
-our strin wide fixed 17
-our stri wide fixed 16
-our stri wide fixe 15
-our str wide fixe 14
-our str wid fixe 13
-our str wid fix 12
-ou str wid fix 11
-ou st wid fix 10
-ou st wi fix 9
-ou st wi fi 8
-Final file name: oustwifi.adb
-@end smallexample
-
-@item
-The file names for all predefined units are always krunched to eight
-characters. The krunching of these predefined units uses the following
-special prefix replacements:
-
-@table @file
-@item ada-
-replaced by @file{^a^A^-}
-
-@item gnat-
-replaced by @file{^g^G^-}
-
-@item interfaces-
-replaced by @file{^i^I^-}
-
-@item system-
-replaced by @file{^s^S^-}
-@end table
-
-These system files have a hyphen in the second character position. That
-is why normal user files replace such a character with a
-^tilde^dollar sign^, to
-avoid confusion with system file names.
-
-As an example of this special rule, consider
-@*@file{ada-strings-wide_fixed.adb}, which gets krunched as follows:
-
-@smallexample
-ada-strings-wide_fixed 22
-a- strings wide fixed 18
-a- string wide fixed 17
-a- strin wide fixed 16
-a- stri wide fixed 15
-a- stri wide fixe 14
-a- str wide fixe 13
-a- str wid fixe 12
-a- str wid fix 11
-a- st wid fix 10
-a- st wi fix 9
-a- st wi fi 8
-Final file name: a-stwifi.adb
-@end smallexample
-@end itemize
-
-Of course no file shortening algorithm can guarantee uniqueness over all
-possible unit names, and if file name krunching is used then it is your
-responsibility to ensure that no name clashes occur. The utility
-program @code{gnatkr} is supplied for conveniently determining the
-krunched name of a file.
-
-@node Examples of gnatkr Usage
-@section Examples of @code{gnatkr} Usage
-
-@smallexample
-@iftex
-@leftskip=0cm
-@end iftex
-@ifclear vms
-$ gnatkr very_long_unit_name.ads --> velounna.ads
-$ gnatkr grandparent-parent-child.ads --> grparchi.ads
-$ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads
-$ gnatkr grandparent-parent-child --> grparchi
-@end ifclear
-$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
-$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
-@end smallexample
-
-@node Preprocessing Using gnatprep
-@chapter Preprocessing Using @code{gnatprep}
-@findex gnatprep
-
-@noindent
-This chapter discusses how to use GNAT's @code{gnatprep} utility for simple
-preprocessing.
-Although designed for use with GNAT, @code{gnatprep} does not depend on any
-special GNAT features.
-For further discussion of conditional compilation in general, see
-@ref{Conditional Compilation}.
-
-@menu
-* Preprocessing Symbols::
-* Using gnatprep::
-* Switches for gnatprep::
-* Form of Definitions File::
-* Form of Input Text for gnatprep::
-@end menu
-
-@node Preprocessing Symbols
-@section Preprocessing Symbols
-
-@noindent
-Preprocessing symbols are defined in definition files and referred to in
-sources to be preprocessed. A Preprocessing symbol is an identifier, following
-normal Ada (case-insensitive) rules for its syntax, with the restriction that
-all characters need to be in the ASCII set (no accented letters).
-
-@node Using gnatprep
-@section Using @code{gnatprep}
-
-@noindent
-To call @code{gnatprep} use
-
-@smallexample
-$ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile}
-@end smallexample
-
-@noindent
-where
-@table @var
-@item switches
-is an optional sequence of switches as described in the next section.
-
-@item infile
-is the full name of the input file, which is an Ada source
-file containing preprocessor directives.
-
-@item outfile
-is the full name of the output file, which is an Ada source
-in standard Ada form. When used with GNAT, this file name will
-normally have an ads or adb suffix.
-
-@item deffile
-is the full name of a text file containing definitions of
-preprocessing symbols to be referenced by the preprocessor. This argument is
-optional, and can be replaced by the use of the @option{-D} switch.
-
-@end table
-
-@node Switches for gnatprep
-@section Switches for @code{gnatprep}
-
-@table @option
-@c !sort!
-
-@item ^-b^/BLANK_LINES^
-@cindex @option{^-b^/BLANK_LINES^} (@command{gnatprep})
-Causes both preprocessor lines and the lines deleted by
-preprocessing to be replaced by blank lines in the output source file,
-preserving line numbers in the output file.
-
-@item ^-c^/COMMENTS^
-@cindex @option{^-c^/COMMENTS^} (@command{gnatprep})
-Causes both preprocessor lines and the lines deleted
-by preprocessing to be retained in the output source as comments marked
-with the special string @code{"--! "}. This option will result in line numbers
-being preserved in the output file.
-
-@item ^-C^/REPLACE_IN_COMMENTS^
-@cindex @option{^-C^/REPLACE_IN_COMMENTS^} (@command{gnatprep})
-Causes comments to be scanned. Normally comments are ignored by gnatprep.
-If this option is specified, then comments are scanned and any $symbol
-substitutions performed as in program text. This is particularly useful
-when structured comments are used (e.g., when writing programs in the
-SPARK dialect of Ada). Note that this switch is not available when
-doing integrated preprocessing (it would be useless in this context
-since comments are ignored by the compiler in any case).
-
-@item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^
-@cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep})
-Defines a new preprocessing symbol, associated with value. If no value is given
-on the command line, then symbol is considered to be @code{True}. This switch
-can be used in place of a definition file.
-
-@ifset vms
-@item /REMOVE
-@cindex @option{/REMOVE} (@command{gnatprep})
-This is the default setting which causes lines deleted by preprocessing
-to be entirely removed from the output file.
-@end ifset
-
-@item ^-r^/REFERENCE^
-@cindex @option{^-r^/REFERENCE^} (@command{gnatprep})
-Causes a @code{Source_Reference} pragma to be generated that
-references the original input file, so that error messages will use
-the file name of this original file. The use of this switch implies
-that preprocessor lines are not to be removed from the file, so its
-use will force @option{^-b^/BLANK_LINES^} mode if
-@option{^-c^/COMMENTS^}
-has not been specified explicitly.
-
-Note that if the file to be preprocessed contains multiple units, then
-it will be necessary to @code{gnatchop} the output file from
-@code{gnatprep}. If a @code{Source_Reference} pragma is present
-in the preprocessed file, it will be respected by
-@code{gnatchop ^-r^/REFERENCE^}
-so that the final chopped files will correctly refer to the original
-input source file for @code{gnatprep}.
-
-@item ^-s^/SYMBOLS^
-@cindex @option{^-s^/SYMBOLS^} (@command{gnatprep})
-Causes a sorted list of symbol names and values to be
-listed on the standard output file.
-
-@item ^-u^/UNDEFINED^
-@cindex @option{^-u^/UNDEFINED^} (@command{gnatprep})
-Causes undefined symbols to be treated as having the value FALSE in the context
-of a preprocessor test. In the absence of this option, an undefined symbol in
-a @code{#if} or @code{#elsif} test will be treated as an error.
-
-@end table
-
-@ifclear vms
-@noindent
-Note: if neither @option{-b} nor @option{-c} is present,
-then preprocessor lines and
-deleted lines are completely removed from the output, unless -r is
-specified, in which case -b is assumed.
-@end ifclear
-
-@node Form of Definitions File
-@section Form of Definitions File
-
-@noindent
-The definitions file contains lines of the form
-
-@smallexample
-symbol := value
-@end smallexample
-
-@noindent
-where symbol is a preprocessing symbol, and value is one of the following:
-
-@itemize @bullet
-@item
-Empty, corresponding to a null substitution
-@item
-A string literal using normal Ada syntax
-@item
-Any sequence of characters from the set
-(letters, digits, period, underline).
-@end itemize
-
-@noindent
-Comment lines may also appear in the definitions file, starting with
-the usual @code{--},
-and comments may be added to the definitions lines.
-
-@node Form of Input Text for gnatprep
-@section Form of Input Text for @code{gnatprep}
-
-@noindent
-The input text may contain preprocessor conditional inclusion lines,
-as well as general symbol substitution sequences.
-
-The preprocessor conditional inclusion commands have the form
-
-@smallexample
-@group
-@cartouche
-#if @i{expression} @r{[}then@r{]}
- lines
-#elsif @i{expression} @r{[}then@r{]}
- lines
-#elsif @i{expression} @r{[}then@r{]}
- lines
-@dots{}
-#else
- lines
-#end if;
-@end cartouche
-@end group
-@end smallexample
-
-@noindent
-In this example, @i{expression} is defined by the following grammar:
-@smallexample
-@i{expression} ::= <symbol>
-@i{expression} ::= <symbol> = "<value>"
-@i{expression} ::= <symbol> = <symbol>
-@i{expression} ::= <symbol> 'Defined
-@i{expression} ::= not @i{expression}
-@i{expression} ::= @i{expression} and @i{expression}
-@i{expression} ::= @i{expression} or @i{expression}
-@i{expression} ::= @i{expression} and then @i{expression}
-@i{expression} ::= @i{expression} or else @i{expression}
-@i{expression} ::= ( @i{expression} )
-@end smallexample
-
-The following restriction exists: it is not allowed to have "and" or "or"
-following "not" in the same expression without parentheses. For example, this
-is not allowed:
-
-@smallexample
- not X or Y
-@end smallexample
-
-This should be one of the following:
-
-@smallexample
- (not X) or Y
- not (X or Y)
-@end smallexample
-
-@noindent
-For the first test (@i{expression} ::= <symbol>) the symbol must have
-either the value true or false, that is to say the right-hand of the
-symbol definition must be one of the (case-insensitive) literals
-@code{True} or @code{False}. If the value is true, then the
-corresponding lines are included, and if the value is false, they are
-excluded.
-
-The test (@i{expression} ::= <symbol> @code{'Defined}) is true only if
-the symbol has been defined in the definition file or by a @option{-D}
-switch on the command line. Otherwise, the test is false.
-
-The equality tests are case insensitive, as are all the preprocessor lines.
-
-If the symbol referenced is not defined in the symbol definitions file,
-then the effect depends on whether or not switch @option{-u}
-is specified. If so, then the symbol is treated as if it had the value
-false and the test fails. If this switch is not specified, then
-it is an error to reference an undefined symbol. It is also an error to
-reference a symbol that is defined with a value other than @code{True}
-or @code{False}.
-
-The use of the @code{not} operator inverts the sense of this logical test.
-The @code{not} operator cannot be combined with the @code{or} or @code{and}
-operators, without parentheses. For example, "if not X or Y then" is not
-allowed, but "if (not X) or Y then" and "if not (X or Y) then" are.
-
-The @code{then} keyword is optional as shown
-
-The @code{#} must be the first non-blank character on a line, but
-otherwise the format is free form. Spaces or tabs may appear between
-the @code{#} and the keyword. The keywords and the symbols are case
-insensitive as in normal Ada code. Comments may be used on a
-preprocessor line, but other than that, no other tokens may appear on a
-preprocessor line. Any number of @code{elsif} clauses can be present,
-including none at all. The @code{else} is optional, as in Ada.
-
-The @code{#} marking the start of a preprocessor line must be the first
-non-blank character on the line, i.e., it must be preceded only by
-spaces or horizontal tabs.
-
-Symbol substitution outside of preprocessor lines is obtained by using
-the sequence
-
-@smallexample
-$symbol
-@end smallexample
-
-@noindent
-anywhere within a source line, except in a comment or within a
-string literal. The identifier
-following the @code{$} must match one of the symbols defined in the symbol
-definition file, and the result is to substitute the value of the
-symbol in place of @code{$symbol} in the output file.
-
-Note that although the substitution of strings within a string literal
-is not possible, it is possible to have a symbol whose defined value is
-a string literal. So instead of setting XYZ to @code{hello} and writing:
-
-@smallexample
-Header : String := "$XYZ";
-@end smallexample
-
-@noindent
-you should set XYZ to @code{"hello"} and write:
-
-@smallexample
-Header : String := $XYZ;
-@end smallexample
-
-@noindent
-and then the substitution will occur as desired.
-
-@ifset vms
-@node The GNAT Run-Time Library Builder gnatlbr
-@chapter The GNAT Run-Time Library Builder @code{gnatlbr}
-@findex gnatlbr
-@cindex Library builder
-
-@noindent
-@code{gnatlbr} is a tool for rebuilding the GNAT run time with user
-supplied configuration pragmas.
-
-@menu
-* Running gnatlbr::
-* Switches for gnatlbr::
-* Examples of gnatlbr Usage::
-@end menu
-
-@node Running gnatlbr
-@section Running @code{gnatlbr}
-
-@noindent
-The @code{gnatlbr} command has the form
-
-@smallexample
-$ GNAT LIBRARY /@r{[}CREATE@r{|}SET@r{|}DELETE@r{]}=directory @r{[}/CONFIG=file@r{]}
-@end smallexample
-
-@node Switches for gnatlbr
-@section Switches for @code{gnatlbr}
-
-@noindent
-@code{gnatlbr} recognizes the following switches:
-
-@table @option
-@c !sort!
-@item /CREATE=directory
-@cindex @code{/CREATE} (@code{gnatlbr})
-Create the new run-time library in the specified directory.
-
-@item /SET=directory
-@cindex @code{/SET} (@code{gnatlbr})
-Make the library in the specified directory the current run-time library.
-
-@item /DELETE=directory
-@cindex @code{/DELETE} (@code{gnatlbr})
-Delete the run-time library in the specified directory.
-
-@item /CONFIG=file
-@cindex @code{/CONFIG} (@code{gnatlbr})
-With /CREATE: Use the configuration pragmas in the specified file when
-building the library.
-
-With /SET: Use the configuration pragmas in the specified file when
-compiling.
-
-@end table
-
-@node Examples of gnatlbr Usage
-@section Example of @code{gnatlbr} Usage
-
-@smallexample
-Contents of VAXFLOAT.ADC:
-pragma Float_Representation (VAX_Float);
-
-$ GNAT LIBRARY /CREATE=[.VAXFLOAT] /CONFIG=VAXFLOAT.ADC
-
-GNAT LIBRARY rebuilds the run-time library in directory [.VAXFLOAT]
-
-@end smallexample
-@end ifset
-
-@node The GNAT Library Browser gnatls
-@chapter The GNAT Library Browser @code{gnatls}
-@findex gnatls
-@cindex Library browser
-
-@noindent
-@code{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.
-
-Note: to invoke @code{gnatls} with a project file, use the @code{gnat}
-driver (see @ref{The GNAT Driver and Project Files}).
-
-@menu
-* Running gnatls::
-* Switches for gnatls::
-* Examples of gnatls Usage::
-@end menu
-
-@node Running gnatls
-@section Running @code{gnatls}
-
-@noindent
-The @code{gnatls} command has the form
-
-@smallexample
-$ gnatls switches @var{object_or_ali_file}
-@end smallexample
-
-@noindent
-The main argument is the list of object or @file{ali} files
-(@pxref{The Ada Library Information Files})
-for which information is requested.
-
-In normal mode, without additional option, @code{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:
-
-@smallexample
-$ 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
-@end smallexample
-
-@noindent
-The first line can be interpreted as follows: the main unit which is
-contained in
-object file @file{demo1.o} is demo1, whose main source is in
-@file{demo1.adb}. Furthermore, the version of the source used for the
-compilation of demo1 has been modified (DIF). Each source file has a status
-qualifier which can be:
-
-@table @code
-@item OK (unchanged)
-The version of the source file used for the compilation of the
-specified unit corresponds exactly to the actual source file.
-
-@item 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 qualifier
-@option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}, a file marked
-MOK will not be recompiled.
-
-@item DIF (modified)
-No version of the source found on the path corresponds to the source
-used to build this object.
-
-@item ??? (file not found)
-No source file was found for this unit.
-
-@item 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.
-
-@end table
-
-@node Switches for gnatls
-@section Switches for @code{gnatls}
-
-@noindent
-@code{gnatls} recognizes the following switches:
-
-@table @option
-@c !sort!
-@cindex @option{--version} @command{gnatls}
-Display Copyright and version, then exit disregarding all other options.
-
-@item --help
-@cindex @option{--help} @command{gnatls}
-If @option{--version} was not used, display usage, then exit disregarding
-all other options.
-
-@item ^-a^/ALL_UNITS^
-@cindex @option{^-a^/ALL_UNITS^} (@code{gnatls})
-Consider all units, including those of the predefined Ada library.
-Especially useful with @option{^-d^/DEPENDENCIES^}.
-
-@item ^-d^/DEPENDENCIES^
-@cindex @option{^-d^/DEPENDENCIES^} (@code{gnatls})
-List sources from which specified units depend on.
-
-@item ^-h^/OUTPUT=OPTIONS^
-@cindex @option{^-h^/OUTPUT=OPTIONS^} (@code{gnatls})
-Output the list of options.
-
-@item ^-o^/OUTPUT=OBJECTS^
-@cindex @option{^-o^/OUTPUT=OBJECTS^} (@code{gnatls})
-Only output information about object files.
-
-@item ^-s^/OUTPUT=SOURCES^
-@cindex @option{^-s^/OUTPUT=SOURCES^} (@code{gnatls})
-Only output information about source files.
-
-@item ^-u^/OUTPUT=UNITS^
-@cindex @option{^-u^/OUTPUT=UNITS^} (@code{gnatls})
-Only output information about compilation units.
-
-@item ^-files^/FILES^=@var{file}
-@cindex @option{^-files^/FILES^} (@code{gnatls})
-Take as arguments the files listed in text file @var{file}.
-Text file @var{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.
-
-@item ^-aO^/OBJECT_SEARCH=^@var{dir}
-@itemx ^-aI^/SOURCE_SEARCH=^@var{dir}
-@itemx ^-I^/SEARCH=^@var{dir}
-@itemx ^-I-^/NOCURRENT_DIRECTORY^
-@itemx -nostdinc
-@cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatls})
-@cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatls})
-@cindex @option{^-I^/SEARCH^} (@code{gnatls})
-@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatls})
-Source path manipulation. Same meaning as the equivalent @command{gnatmake}
-flags (@pxref{Switches for gnatmake}).
-
-@item --RTS=@var{rts-path}
-@cindex @option{--RTS} (@code{gnatls})
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
-
-@item ^-v^/OUTPUT=VERBOSE^
-@cindex @option{^-v^/OUTPUT=VERBOSE^} (@code{gnatls})
-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:
-
-@table @code
-@item Preelaborable
-The unit is preelaborable in the Ada sense.
-
-@item No_Elab_Code
-No elaboration code has been produced by the compiler for this unit.
-
-@item Pure
-The unit is pure in the Ada sense.
-
-@item Elaborate_Body
-The unit contains a pragma Elaborate_Body.
-
-@item Remote_Types
-The unit contains a pragma Remote_Types.
-
-@item Shared_Passive
-The unit contains a pragma Shared_Passive.
-
-@item Predefined
-This unit is part of the predefined environment and cannot be modified
-by the user.
-
-@item Remote_Call_Interface
-The unit contains a pragma Remote_Call_Interface.
-
-@end table
-
-@end table
-
-@node Examples of gnatls Usage
-@section Example of @code{gnatls} Usage
-@ifclear vms
-
-@noindent
-Example of using the verbose switch. Note how the source and
-object paths are affected by the -I switch.
-
-@smallexample
-$ 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
-@end smallexample
-
-@noindent
-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.
-
-@smallexample
-$ 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
-@end smallexample
-@end ifclear
-
-@ifset vms
-@smallexample
-GNAT LIST /DEPENDENCIES /OUTPUT=SOURCES /ALL_UNITS DEMO1.ADB
-
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]ada.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-finali.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-filico.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-stream.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-tags.ads
-demo1.adb
-gen_list.ads
-gen_list.adb
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]gnat.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]g-io.ads
-instr.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]system.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-exctab.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finimp.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finroo.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-secsta.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stalib.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stoele.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stratt.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-tasoli.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-unstyp.ads
-GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]unchconv.ads
-@end smallexample
-@end ifset
-
-@node Cleaning Up Using gnatclean
-@chapter Cleaning Up Using @code{gnatclean}
-@findex gnatclean
-@cindex Cleaning tool
-
-@noindent
-@code{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.
-
-@menu
-* Running gnatclean::
-* Switches for gnatclean::
-@c * Examples of gnatclean Usage::
-@end menu
-
-@node Running gnatclean
-@section Running @code{gnatclean}
-
-@noindent
-The @code{gnatclean} command has the form:
-
-@smallexample
-$ gnatclean switches @var{names}
-@end smallexample
-
-@noindent
-@var{names} is a list of source file names. Suffixes @code{.^ads^ADS^} and
-@code{^adb^ADB^} may be omitted. If a project file is specified using switch
-@code{^-P^/PROJECT_FILE=^}, then @var{names} may be completely omitted.
-
-@noindent
-In normal mode, @code{gnatclean} delete the files produced by the compiler and,
-if switch @code{^-c^/COMPILER_FILES_ONLY^} is not specified, by the binder and
-the linker. In informative-only mode, specified by switch
-@code{^-n^/NODELETE^}, the list of files that would have been deleted in
-normal mode is listed, but no file is actually deleted.
-
-@node Switches for gnatclean
-@section Switches for @code{gnatclean}
-
-@noindent
-@code{gnatclean} recognizes the following switches:
-
-@table @option
-@c !sort!
-@cindex @option{--version} @command{gnatclean}
-Display Copyright and version, then exit disregarding all other options.
-
-@item --help
-@cindex @option{--help} @command{gnatclean}
-If @option{--version} was not used, display usage, then exit disregarding
-all other options.
-
-@item ^-c^/COMPILER_FILES_ONLY^
-@cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean})
-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.
-
-@item ^-D ^/DIRECTORY_OBJECTS=^@var{dir}
-@cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatclean})
-Indicate that ALI and object files should normally be found in directory
-@var{dir}.
-
-@item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^
-@cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@code{gnatclean})
-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^/VERBOSE^), then error lines start with the full path name of the project
-file, rather than its simple file name.
-
-@item ^-h^/HELP^
-@cindex @option{^-h^/HELP^} (@code{gnatclean})
-Output a message explaining the usage of @code{^gnatclean^gnatclean^}.
-
-@item ^-n^/NODELETE^
-@cindex @option{^-n^/NODELETE^} (@code{gnatclean})
-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.
-
-@item ^-P^/PROJECT_FILE=^@var{project}
-@cindex @option{^-P^/PROJECT_FILE^} (@code{gnatclean})
-Use project file @var{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.
-
-@item ^-q^/QUIET^
-@cindex @option{^-q^/QUIET^} (@code{gnatclean})
-Quiet output. If there are no errors, do not output anything, except in
-verbose mode (switch ^-v^/VERBOSE^) or in informative-only mode
-(switch ^-n^/NODELETE^).
-
-@item ^-r^/RECURSIVE^
-@cindex @option{^-r^/RECURSIVE^} (@code{gnatclean})
-When a project file is specified (using switch ^-P^/PROJECT_FILE=^),
-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.
-
-@item ^-v^/VERBOSE^
-@cindex @option{^-v^/VERBOSE^} (@code{gnatclean})
-Verbose mode.
-
-@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
-@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean})
-Indicates the verbosity of the parsing of GNAT project files.
-@xref{Switches Related to Project Files}.
-
-@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
-@cindex @option{^-X^/EXTERNAL_REFERENCE^} (@code{gnatclean})
-Indicates that external variable @var{name} has the value @var{value}.
-The Project Manager will use this value for occurrences of
-@code{external(name)} when parsing the project file.
-@xref{Switches Related to Project Files}.
-
-@item ^-aO^/OBJECT_SEARCH=^@var{dir}
-@cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean})
-When searching for ALI and object files, look in directory
-@var{dir}.
-
-@item ^-I^/SEARCH=^@var{dir}
-@cindex @option{^-I^/SEARCH^} (@code{gnatclean})
-Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir}}.
-
-@item ^-I-^/NOCURRENT_DIRECTORY^
-@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatclean})
-@cindex Source files, suppressing search
-Do not look for ALI or object files in the directory
-where @code{gnatclean} was invoked.
-
-@end table
-
-@c @node Examples of gnatclean Usage
-@c @section Examples of @code{gnatclean} Usage
-
-@ifclear vms
-@node GNAT and Libraries
-@chapter GNAT and Libraries
-@cindex Library, building, installing, using
-
-@noindent
-This chapter describes how to build and use libraries with GNAT, and also shows
-how to recompile the GNAT run-time library. You should be familiar with the
-Project Manager facility (@pxref{GNAT Project Manager}) before reading this
-chapter.
-
-@menu
-* Introduction to Libraries in GNAT::
-* General Ada Libraries::
-* Stand-alone Ada Libraries::
-* Rebuilding the GNAT Run-Time Library::
-@end menu
-
-@node Introduction to Libraries in GNAT
-@section Introduction to Libraries in GNAT
-
-@noindent
-A library is, conceptually, a collection of objects which does not have its
-own main thread of execution, but rather provides certain services to the
-applications that use it. A library can be either statically linked with the
-application, in which case its code is directly included in the application,
-or, on platforms that support it, be dynamically linked, in which case
-its code is shared by all applications making use of this library.
-
-GNAT supports both types of libraries.
-In the static case, the compiled code can be provided in different ways. The
-simplest approach is to provide directly the set of objects resulting from
-compilation of the library source files. Alternatively, you can group the
-objects into an archive using whatever commands are provided by the operating
-system. For the latter case, the objects are grouped into a shared library.
-
-In the GNAT environment, a library has three types of components:
-@itemize @bullet
-@item
-Source files.
-@item
-@file{ALI} files.
-@xref{The Ada Library Information Files}.
-@item
-Object files, an archive or a shared library.
-@end itemize
-
-@noindent
-A GNAT library may expose all its source files, which is useful for
-documentation purposes. Alternatively, it may expose only the units needed by
-an external user to make use of the library. That is to say, the specs
-reflecting the library services along with all the units needed to compile
-those specs, which can include generic bodies or any body implementing an
-inlined routine. In the case of @emph{stand-alone libraries} those exposed
-units are called @emph{interface units} (@pxref{Stand-alone Ada Libraries}).
-
-All compilation units comprising an application, including those in a library,
-need to be elaborated in an order partially defined by Ada's semantics. GNAT
-computes the elaboration order from the @file{ALI} files and this is why they
-constitute a mandatory part of GNAT libraries.
-@emph{Stand-alone libraries} are the exception to this rule because a specific
-library elaboration routine is produced independently of the application(s)
-using the library.
-
-@node General Ada Libraries
-@section General Ada Libraries
-
-@menu
-* Building a library::
-* Installing a library::
-* Using a library::
-@end menu
-
-@node Building a library
-@subsection Building a library
-
-@noindent
-The easiest way to build a library is to use the Project Manager,
-which supports a special type of project called a @emph{Library Project}
-(@pxref{Library Projects}).
-
-A project is considered a library project, when two project-level attributes
-are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to
-control different aspects of library configuration, additional optional
-project-level attributes can be specified:
-@table @code
-@item Library_Kind
-This attribute controls whether the library is to be static or dynamic
-
-@item Library_Version
-This attribute specifies the library version; this value is used
-during dynamic linking of shared libraries to determine if the currently
-installed versions of the binaries are compatible.
-
-@item Library_Options
-@item Library_GCC
-These attributes specify additional low-level options to be used during
-library generation, and redefine the actual application used to generate
-library.
-@end table
-
-@noindent
-The GNAT Project Manager takes full care of the library maintenance task,
-including recompilation of the source files for which objects do not exist
-or are not up to date, assembly of the library archive, and installation of
-the library (i.e., copying associated source, object and @file{ALI} files
-to the specified location).
-
-Here is a simple library project file:
-@smallexample @c ada
-project My_Lib is
- for Source_Dirs use ("src1", "src2");
- for Object_Dir use "obj";
- for Library_Name use "mylib";
- for Library_Dir use "lib";
- for Library_Kind use "dynamic";
-end My_lib;
-@end smallexample
-
-@noindent
-and the compilation command to build and install the library:
-
-@smallexample @c ada
- $ gnatmake -Pmy_lib
-@end smallexample
-
-@noindent
-It is not entirely trivial to perform manually all the steps required to
-produce a library. We recommend that you use the GNAT Project Manager
-for this task. In special cases where this is not desired, the necessary
-steps are discussed below.
-
-There are various possibilities for compiling the units that make up the
-library: for example with a Makefile (@pxref{Using the GNU make Utility}) or
-with a conventional script. For simple libraries, it is also possible to create
-a dummy main program which depends upon all the packages that comprise the
-interface of the library. This dummy main program can then be given to
-@command{gnatmake}, which will ensure that all necessary objects are built.
-
-After this task is accomplished, you should follow the standard procedure
-of the underlying operating system to produce the static or shared library.
-
-Here is an example of such a dummy program:
-@smallexample @c ada
-@group
-with My_Lib.Service1;
-with My_Lib.Service2;
-with My_Lib.Service3;
-procedure My_Lib_Dummy is
-begin
- null;
-end;
-@end group
-@end smallexample
-
-@noindent
-Here are the generic commands that will build an archive or a shared library.
-
-@smallexample
-# compiling the library
-$ gnatmake -c my_lib_dummy.adb
-
-# we don't need the dummy object itself
-$ rm my_lib_dummy.o my_lib_dummy.ali
-
-# create an archive with the remaining objects
-$ ar rc libmy_lib.a *.o
-# some systems may require "ranlib" to be run as well
-
-# or create a shared library
-$ gcc -shared -o libmy_lib.so *.o
-# some systems may require the code to have been compiled with -fPIC
-
-# remove the object files that are now in the library
-$ rm *.o
-
-# Make the ALI files read-only so that gnatmake will not try to
-# regenerate the objects that are in the library
-$ chmod -w *.ali
-@end smallexample
-
-@noindent
-Please note that the library must have a name of the form @file{lib@var{xxx}.a}
-or @file{lib@var{xxx}.so} (or @file{lib@var{xxx}.dll} on Windows) in order to
-be accessed by the directive @option{-l@var{xxx}} at link time.
-
-@node Installing a library
-@subsection Installing a library
-@cindex @code{ADA_PROJECT_PATH}
-
-@noindent
-If you use project files, library installation is part of the library build
-process. Thus no further action is needed in order to make use of the
-libraries that are built as part of the general application build. A usable
-version of the library is installed in the directory specified by the
-@code{Library_Dir} attribute of the library project file.
-
-You may want to install a library in a context different from where the library
-is built. This situation arises with third party suppliers, who may want
-to distribute a library in binary form where the user is not expected to be
-able to recompile the library. The simplest option in this case is to provide
-a project file slightly different from the one used to build the library, by
-using the @code{externally_built} attribute. For instance, the project
-file used to build the library in the previous section can be changed into the
-following one when the library is installed:
-
-@smallexample @c projectfile
-project My_Lib is
- for Source_Dirs use ("src1", "src2");
- for Library_Name use "mylib";
- for Library_Dir use "lib";
- for Library_Kind use "dynamic";
- for Externally_Built use "true";
-end My_lib;
-@end smallexample
-
-@noindent
-This project file assumes that the directories @file{src1},
-@file{src2}, and @file{lib} exist in
-the directory containing the project file. The @code{externally_built}
-attribute makes it clear to the GNAT builder that it should not attempt to
-recompile any of the units from this library. It allows the library provider to
-restrict the source set to the minimum necessary for clients to make use of the
-library as described in the first section of this chapter. It is the
-responsibility of the library provider to install the necessary sources, ALI
-files and libraries in the directories mentioned in the project file. For
-convenience, the user's library project file should be installed in a location
-that will be searched automatically by the GNAT
-builder. These are the directories referenced in the @env{ADA_PROJECT_PATH}
-environment variable (@pxref{Importing Projects}), and also the default GNAT
-library location that can be queried with @command{gnatls -v} and is usually of
-the form $gnat_install_root/lib/gnat.
-
-When project files are not an option, it is also possible, but not recommended,
-to install the library so that the sources needed to use the library are on the
-Ada source path and the ALI files & libraries be on the Ada Object path (see
-@ref{Search Paths and the Run-Time Library (RTL)}. Alternatively, the system
-administrator can place general-purpose libraries in the default compiler
-paths, by specifying the libraries' location in the configuration files
-@file{ada_source_path} and @file{ada_object_path}. These configuration files
-must be located in the GNAT installation tree at the same place as the gcc spec
-file. The location of the gcc spec file can be determined as follows:
-@smallexample
-$ gcc -v
-@end smallexample
-
-@noindent
-The configuration files mentioned above have a simple format: each line
-must contain one unique directory name.
-Those names are added to the corresponding path
-in their order of appearance in the file. The names can be either absolute
-or relative; in the latter case, they are relative to where theses files
-are located.
-
-The files @file{ada_source_path} and @file{ada_object_path} might not be
-present in a
-GNAT installation, in which case, GNAT will look for its run-time library in
-the directories @file{adainclude} (for the sources) and @file{adalib} (for the
-objects and @file{ALI} files). When the files exist, the compiler does not
-look in @file{adainclude} and @file{adalib}, and thus the
-@file{ada_source_path} file
-must contain the location for the GNAT run-time sources (which can simply
-be @file{adainclude}). In the same way, the @file{ada_object_path} file must
-contain the location for the GNAT run-time objects (which can simply
-be @file{adalib}).
-
-You can also specify a new default path to the run-time library at compilation
-time with the switch @option{--RTS=rts-path}. You can thus choose / change
-the run-time library you want your program to be compiled with. This switch is
-recognized by @command{gcc}, @command{gnatmake}, @command{gnatbind},
-@command{gnatls}, @command{gnatfind} and @command{gnatxref}.
-
-It is possible to install a library before or after the standard GNAT
-library, by reordering the lines in the configuration files. In general, a
-library must be installed before the GNAT library if it redefines
-any part of it.
-
-@node Using a library
-@subsection Using a library
-
-@noindent Once again, the project facility greatly simplifies the use of
-libraries. In this context, using a library is just a matter of adding a
-@code{with} clause in the user project. For instance, to make use of the
-library @code{My_Lib} shown in examples in earlier sections, you can
-write:
-
-@smallexample @c projectfile
-with "my_lib";
-project My_Proj is
- @dots{}
-end My_Proj;
-@end smallexample
-
-Even if you have a third-party, non-Ada library, you can still use GNAT's
-Project Manager facility to provide a wrapper for it. For example, the
-following project, when @code{with}ed by your main project, will link with the
-third-party library @file{liba.a}:
-
-@smallexample @c projectfile
-@group
-project Liba is
- for Externally_Built use "true";
- for Source_Files use ();
- for Library_Dir use "lib";
- for Library_Name use "a";
- for Library_Kind use "static";
-end Liba;
-@end group
-@end smallexample
-This is an alternative to the use of @code{pragma Linker_Options}. It is
-especially interesting in the context of systems with several interdependent
-static libraries where finding a proper linker order is not easy and best be
-left to the tools having visibility over project dependence information.
-
-@noindent
-In order to use an Ada library manually, you need to make sure that this
-library is on both your source and object path
-(see @ref{Search Paths and the Run-Time Library (RTL)}
-and @ref{Search Paths for gnatbind}). Furthermore, when the objects are grouped
-in an archive or a shared library, you need to specify the desired
-library at link time.
-
-For example, you can use the library @file{mylib} installed in
-@file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands:
-
-@smallexample
-$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \
- -largs -lmy_lib
-@end smallexample
-
-@noindent
-This can be expressed more simply:
-@smallexample
-$ gnatmake my_appl
-@end smallexample
-@noindent
-when the following conditions are met:
-@itemize @bullet
-@item
-@file{/dir/my_lib_src} has been added by the user to the environment
-variable @env{ADA_INCLUDE_PATH}, or by the administrator to the file
-@file{ada_source_path}
-@item
-@file{/dir/my_lib_obj} has been added by the user to the environment
-variable @env{ADA_OBJECTS_PATH}, or by the administrator to the file
-@file{ada_object_path}
-@item
-a pragma @code{Linker_Options} has been added to one of the sources.
-For example:
-
-@smallexample @c ada
-pragma Linker_Options ("-lmy_lib");
-@end smallexample
-@end itemize
-
-@node Stand-alone Ada Libraries
-@section Stand-alone Ada Libraries
-@cindex Stand-alone library, building, using
-
-@menu
-* Introduction to Stand-alone Libraries::
-* Building a Stand-alone Library::
-* Creating a Stand-alone Library to be used in a non-Ada context::
-* Restrictions in Stand-alone Libraries::
-@end menu
-
-@node Introduction to Stand-alone Libraries
-@subsection Introduction to Stand-alone Libraries
-
-@noindent
-A Stand-alone Library (abbreviated ``SAL'') is a library that contains the
-necessary code to
-elaborate the Ada units that are included in the library. In contrast with
-an ordinary library, which consists of all sources, objects and @file{ALI}
-files of the
-library, a SAL may specify a restricted subset of compilation units
-to serve as a library interface. In this case, the fully
-self-sufficient set of files will normally consist of an objects
-archive, the sources of interface units' specs, and the @file{ALI}
-files of interface units.
-If an interface spec contains a generic unit or an inlined subprogram,
-the body's
-source must also be provided; if the units that must be provided in the source
-form depend on other units, the source and @file{ALI} files of those must
-also be provided.
-
-The main purpose of a SAL is to minimize the recompilation overhead of client
-applications when a new version of the library is installed. Specifically,
-if the interface sources have not changed, client applications do not need to
-be recompiled. If, furthermore, a SAL is provided in the shared form and its
-version, controlled by @code{Library_Version} attribute, is not changed,
-then the clients do not need to be relinked.
-
-SALs also allow the library providers to minimize the amount of library source
-text exposed to the clients. Such ``information hiding'' might be useful or
-necessary for various reasons.
-
-Stand-alone libraries are also well suited to be used in an executable whose
-main routine is not written in Ada.
-
-@node Building a Stand-alone Library
-@subsection Building a Stand-alone Library
-
-@noindent
-GNAT's Project facility provides a simple way of building and installing
-stand-alone libraries; see @ref{Stand-alone Library Projects}.
-To be a Stand-alone Library Project, in addition to the two attributes
-that make a project a Library Project (@code{Library_Name} and
-@code{Library_Dir}; see @ref{Library Projects}), the attribute
-@code{Library_Interface} must be defined. For example:
-
-@smallexample @c projectfile
-@group
- for Library_Dir use "lib_dir";
- for Library_Name use "dummy";
- for Library_Interface use ("int1", "int1.child");
-@end group
-@end smallexample
-
-@noindent
-Attribute @code{Library_Interface} has a non-empty string list value,
-each string in the list designating a unit contained in an immediate source
-of the project file.
-
-When a Stand-alone Library is built, first the binder is invoked to build
-a package whose name depends on the library name
-(@file{^b~dummy.ads/b^B$DUMMY.ADS/B^} in the example above).
-This binder-generated package includes initialization and
-finalization procedures whose
-names depend on the library name (@code{dummyinit} and @code{dummyfinal}
-in the example
-above). The object corresponding to this package is included in the library.
-
-You must ensure timely (e.g., prior to any use of interfaces in the SAL)
-calling of these procedures if a static SAL is built, or if a shared SAL
-is built
-with the project-level attribute @code{Library_Auto_Init} set to
-@code{"false"}.
-
-For a Stand-Alone Library, only the @file{ALI} files of the Interface Units
-(those that are listed in attribute @code{Library_Interface}) are copied to
-the Library Directory. As a consequence, only the Interface Units may be
-imported from Ada units outside of the library. If other units are imported,
-the binding phase will fail.
-
-The attribute @code{Library_Src_Dir} may be specified for a
-Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
-single string value. Its value must be the path (absolute or relative to the
-project directory) of an existing directory. This directory cannot be the
-object directory or one of the source directories, but it can be the same as
-the library directory. The sources of the Interface
-Units of the library that are needed by an Ada client of the library will be
-copied to the designated directory, called the Interface Copy directory.
-These sources include the specs of the Interface Units, but they may also
-include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
-are used, or when there is a generic unit in the spec. Before the sources
-are copied to the Interface Copy directory, an attempt is made to delete all
-files in the Interface Copy directory.
-
-Building stand-alone libraries by hand is somewhat tedious, but for those
-occasions when it is necessary here are the steps that you need to perform:
-@itemize @bullet
-@item
-Compile all library sources.
-
-@item
-Invoke the binder with the switch @option{-n} (No Ada main program),
-with all the @file{ALI} files of the interfaces, and
-with the switch @option{-L} to give specific names to the @code{init}
-and @code{final} procedures. For example:
-@smallexample
- gnatbind -n int1.ali int2.ali -Lsal1
-@end smallexample
-
-@item
-Compile the binder generated file:
-@smallexample
- gcc -c b~int2.adb
-@end smallexample
-
-@item
-Link the dynamic library with all the necessary object files,
-indicating to the linker the names of the @code{init} (and possibly
-@code{final}) procedures for automatic initialization (and finalization).
-The built library should be placed in a directory different from
-the object directory.
-
-@item
-Copy the @code{ALI} files of the interface to the library directory,
-add in this copy an indication that it is an interface to a SAL
-(i.e., add a word @option{SL} on the line in the @file{ALI} file that starts
-with letter ``P'') and make the modified copy of the @file{ALI} file
-read-only.
-@end itemize
-
-@noindent
-Using SALs is not different from using other libraries
-(see @ref{Using a library}).
-
-@node Creating a Stand-alone Library to be used in a non-Ada context
-@subsection Creating a Stand-alone Library to be used in a non-Ada context
-
-@noindent
-It is easy to adapt the SAL build procedure discussed above for use of a SAL in
-a non-Ada context.
-
-The only extra step required is to ensure that library interface subprograms
-are compatible with the main program, by means of @code{pragma Export}
-or @code{pragma Convention}.
-
-Here is an example of simple library interface for use with C main program:
-
-@smallexample @c ada
-package Interface is
-
- procedure Do_Something;
- pragma Export (C, Do_Something, "do_something");
-
- procedure Do_Something_Else;
- pragma Export (C, Do_Something_Else, "do_something_else");
-
-end Interface;
-@end smallexample
-
-@noindent
-On the foreign language side, you must provide a ``foreign'' view of the
-library interface; remember that it should contain elaboration routines in
-addition to interface subprograms.
-
-The example below shows the content of @code{mylib_interface.h} (note
-that there is no rule for the naming of this file, any name can be used)
-@smallexample
-/* the library elaboration procedure */
-extern void mylibinit (void);
-
-/* the library finalization procedure */
-extern void mylibfinal (void);
-
-/* the interface exported by the library */
-extern void do_something (void);
-extern void do_something_else (void);
-@end smallexample
-
-@noindent
-Libraries built as explained above can be used from any program, provided
-that the elaboration procedures (named @code{mylibinit} in the previous
-example) are called before the library services are used. Any number of
-libraries can be used simultaneously, as long as the elaboration
-procedure of each library is called.
-
-Below is an example of a C program that uses the @code{mylib} library.
-
-@smallexample
-#include "mylib_interface.h"
-
-int
-main (void)
-@{
- /* First, elaborate the library before using it */
- mylibinit ();
-
- /* Main program, using the library exported entities */
- do_something ();
- do_something_else ();
-
- /* Library finalization at the end of the program */
- mylibfinal ();
- return 0;
-@}
-@end smallexample
-
-@noindent
-Note that invoking any library finalization procedure generated by
-@code{gnatbind} shuts down the Ada run-time environment.
-Consequently, the
-finalization of all Ada libraries must be performed at the end of the program.
-No call to these libraries or to the Ada run-time library should be made
-after the finalization phase.
-
-@node Restrictions in Stand-alone Libraries
-@subsection Restrictions in Stand-alone Libraries
-
-@noindent
-The pragmas listed below should be used with caution inside libraries,
-as they can create incompatibilities with other Ada libraries:
-@itemize @bullet
-@item pragma @code{Locking_Policy}
-@item pragma @code{Queuing_Policy}
-@item pragma @code{Task_Dispatching_Policy}
-@item pragma @code{Unreserve_All_Interrupts}
-@end itemize
-
-@noindent
-When using a library that contains such pragmas, the user must make sure
-that all libraries use the same pragmas with the same values. Otherwise,
-@code{Program_Error} will
-be raised during the elaboration of the conflicting
-libraries. The usage of these pragmas and its consequences for the user
-should therefore be well documented.
-
-Similarly, the traceback in the exception occurrence mechanism should be
-enabled or disabled in a consistent manner across all libraries.
-Otherwise, Program_Error will be raised during the elaboration of the
-conflicting libraries.
-
-If the @code{Version} or @code{Body_Version}
-attributes are used inside a library, then you need to
-perform a @code{gnatbind} step that specifies all @file{ALI} files in all
-libraries, so that version identifiers can be properly computed.
-In practice these attributes are rarely used, so this is unlikely
-to be a consideration.
-
-@node Rebuilding the GNAT Run-Time Library
-@section Rebuilding the GNAT Run-Time Library
-@cindex GNAT Run-Time Library, rebuilding
-@cindex Building the GNAT Run-Time Library
-@cindex Rebuilding the GNAT Run-Time Library
-@cindex Run-Time Library, rebuilding
-
-@noindent
-It may be useful to recompile the GNAT library in various contexts, the
-most important one being the use of partition-wide configuration pragmas
-such as @code{Normalize_Scalars}. A special Makefile called
-@code{Makefile.adalib} is provided to that effect and can be found in
-the directory containing the GNAT library. The location of this
-directory depends on the way the GNAT environment has been installed and can
-be determined by means of the command:
-
-@smallexample
-$ gnatls -v
-@end smallexample
-
-@noindent
-The last entry in the object search path usually contains the
-gnat library. This Makefile contains its own documentation and in
-particular the set of instructions needed to rebuild a new library and
-to use it.
-
-@node Using the GNU make Utility
-@chapter Using the GNU @code{make} Utility
-@findex make
-
-@noindent
-This chapter offers some examples of makefiles that solve specific
-problems. It does not explain how to write a makefile (@pxref{Top,, GNU
-make, make, GNU @code{make}}), nor does it try to replace the
-@command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}).
-
-All the examples in this section are specific to the GNU version of
-make. Although @command{make} is a standard utility, and the basic language
-is the same, these examples use some advanced features found only in
-@code{GNU make}.
-
-@menu
-* Using gnatmake in a Makefile::
-* Automatically Creating a List of Directories::
-* Generating the Command Line Switches::
-* Overcoming Command Line Length Limits::
-@end menu
-
-@node Using gnatmake in a Makefile
-@section Using gnatmake in a Makefile
-@findex makefile
-@cindex GNU make
-
-@noindent
-Complex project organizations can be handled in a very powerful way by
-using GNU make combined with gnatmake. For instance, here is a Makefile
-which allows you to build each subsystem of a big project into a separate
-shared library. Such a makefile allows you to significantly reduce the link
-time of very big applications while maintaining full coherence at
-each step of the build process.
-
-The list of dependencies are handled automatically by
-@command{gnatmake}. The Makefile is simply used to call gnatmake in each of
-the appropriate directories.
-
-Note that you should also read the example on how to automatically
-create the list of directories
-(@pxref{Automatically Creating a List of Directories})
-which might help you in case your project has a lot of subdirectories.
-
-@smallexample
-@iftex
-@leftskip=0cm
-@font@heightrm=cmr8
-@heightrm
-@end iftex
-## This Makefile is intended to be used with the following directory
-## configuration:
-## - The sources are split into a series of csc (computer software components)
-## Each of these csc is put in its own directory.
-## Their name are referenced by the directory names.
-## They will be compiled into shared library (although this would also work
-## with static libraries
-## - The main program (and possibly other packages that do not belong to any
-## csc is put in the top level directory (where the Makefile is).
-## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
-## \_ second_csc (sources) __ lib (will contain the library)
-## \_ @dots{}
-## Although this Makefile is build for shared library, it is easy to modify
-## to build partial link objects instead (modify the lines with -shared and
-## gnatlink below)
-##
-## With this makefile, you can change any file in the system or add any new
-## file, and everything will be recompiled correctly (only the relevant shared
-## objects will be recompiled, and the main program will be re-linked).
-
-# The list of computer software component for your project. This might be
-# generated automatically.
-CSC_LIST=aa bb cc
-
-# Name of the main program (no extension)
-MAIN=main
-
-# If we need to build objects with -fPIC, uncomment the following line
-#NEED_FPIC=-fPIC
-
-# The following variable should give the directory containing libgnat.so
-# You can get this directory through 'gnatls -v'. This is usually the last
-# directory in the Object_Path.
-GLIB=@dots{}
-
-# The directories for the libraries
-# (This macro expands the list of CSC to the list of shared libraries, you
-# could simply use the expanded form:
-# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
-LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@}
-
-$@{MAIN@}: objects $@{LIB_DIR@}
- gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared
- gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@}
-
-objects::
- # recompile the sources
- gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@}
-
-# Note: In a future version of GNAT, the following commands will be simplified
-# by a new tool, gnatmlib
-$@{LIB_DIR@}:
- mkdir -p $@{dir $@@ @}
- cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
- cd $@{dir $@@ @} && cp -f ../*.ali .
-
-# The dependencies for the modules
-# Note that we have to force the expansion of *.o, since in some cases
-# make won't be able to do it itself.
-aa/lib/libaa.so: $@{wildcard aa/*.o@}
-bb/lib/libbb.so: $@{wildcard bb/*.o@}
-cc/lib/libcc.so: $@{wildcard cc/*.o@}
-
-# Make sure all of the shared libraries are in the path before starting the
-# program
-run::
- LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@}
-
-clean::
- $@{RM@} -rf $@{CSC_LIST:%=%/lib@}
- $@{RM@} $@{CSC_LIST:%=%/*.ali@}
- $@{RM@} $@{CSC_LIST:%=%/*.o@}
- $@{RM@} *.o *.ali $@{MAIN@}
-@end smallexample
-
-@node Automatically Creating a List of Directories
-@section Automatically Creating a List of Directories
-
-@noindent
-In most makefiles, you will have to specify a list of directories, and
-store it in a variable. For small projects, it is often easier to
-specify each of them by hand, since you then have full control over what
-is the proper order for these directories, which ones should be
-included.
-
-However, in larger projects, which might involve hundreds of
-subdirectories, it might be more convenient to generate this list
-automatically.
-
-The example below presents two methods. The first one, although less
-general, gives you more control over the list. It involves wildcard
-characters, that are automatically expanded by @command{make}. Its
-shortcoming is that you need to explicitly specify some of the
-organization of your project, such as for instance the directory tree
-depth, whether some directories are found in a separate tree, @enddots{}
-
-The second method is the most general one. It requires an external
-program, called @command{find}, which is standard on all Unix systems. All
-the directories found under a given root directory will be added to the
-list.
-
-@smallexample
-@iftex
-@leftskip=0cm
-@font@heightrm=cmr8
-@heightrm
-@end iftex
-# The examples below are based on the following directory hierarchy:
-# All the directories can contain any number of files
-# ROOT_DIRECTORY -> a -> aa -> aaa
-# -> ab
-# -> ac
-# -> b -> ba -> baa
-# -> bb
-# -> bc
-# This Makefile creates a variable called DIRS, that can be reused any time
-# you need this list (see the other examples in this section)
-
-# The root of your project's directory hierarchy
-ROOT_DIRECTORY=.
-
-####
-# First method: specify explicitly the list of directories
-# This allows you to specify any subset of all the directories you need.
-####
-
-DIRS := a/aa/ a/ab/ b/ba/
-
-####
-# Second method: use wildcards
-# Note that the argument(s) to wildcard below should end with a '/'.
-# Since wildcards also return file names, we have to filter them out
-# to avoid duplicate directory names.
-# We thus use make's @code{dir} and @code{sort} functions.
-# It sets DIRs to the following value (note that the directories aaa and baa
-# are not given, unless you change the arguments to wildcard).
-# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
-####
-
-DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/
- $@{ROOT_DIRECTORY@}/*/*/@}@}@}
-
-####
-# Third method: use an external program
-# This command is much faster if run on local disks, avoiding NFS slowdowns.
-# This is the most complete command: it sets DIRs to the following value:
-# DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
-####
-
-DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@}
-
-@end smallexample
-
-@node Generating the Command Line Switches
-@section Generating the Command Line Switches
-
-@noindent
-Once you have created the list of directories as explained in the
-previous section (@pxref{Automatically Creating a List of Directories}),
-you can easily generate the command line arguments to pass to gnatmake.
-
-For the sake of completeness, this example assumes that the source path
-is not the same as the object path, and that you have two separate lists
-of directories.
-
-@smallexample
-# see "Automatically creating a list of directories" to create
-# these variables
-SOURCE_DIRS=
-OBJECT_DIRS=
-
-GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@}
-GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@}
-
-all:
- gnatmake $@{GNATMAKE_SWITCHES@} main_unit
-@end smallexample
-
-@node Overcoming Command Line Length Limits
-@section Overcoming Command Line Length Limits
-
-@noindent
-One problem that might be encountered on big projects is that many
-operating systems limit the length of the command line. It is thus hard to give
-gnatmake the list of source and object directories.
-
-This example shows how you can set up environment variables, which will
-make @command{gnatmake} behave exactly as if the directories had been
-specified on the command line, but have a much higher length limit (or
-even none on most systems).
-
-It assumes that you have created a list of directories in your Makefile,
-using one of the methods presented in
-@ref{Automatically Creating a List of Directories}.
-For the sake of completeness, we assume that the object
-path (where the ALI files are found) is different from the sources patch.
-
-Note a small trick in the Makefile below: for efficiency reasons, we
-create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
-expanded immediately by @code{make}. This way we overcome the standard
-make behavior which is to expand the variables only when they are
-actually used.
-
-On Windows, if you are using the standard Windows command shell, you must
-replace colons with semicolons in the assignments to these variables.
-
-@smallexample
-@iftex
-@leftskip=0cm
-@font@heightrm=cmr8
-@heightrm
-@end iftex
-# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH.
-# This is the same thing as putting the -I arguments on the command line.
-# (the equivalent of using -aI on the command line would be to define
-# only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH).
-# You can of course have different values for these variables.
-#
-# Note also that we need to keep the previous values of these variables, since
-# they might have been set before running 'make' to specify where the GNAT
-# library is installed.
-
-# see "Automatically creating a list of directories" to create these
-# variables
-SOURCE_DIRS=
-OBJECT_DIRS=
-
-empty:=
-space:=$@{empty@} $@{empty@}
-SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@}
-OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@}
-ADA_INCLUDE_PATH += $@{SOURCE_LIST@}
-ADA_OBJECT_PATH += $@{OBJECT_LIST@}
-export ADA_INCLUDE_PATH
-export ADA_OBJECT_PATH
-
-all:
- gnatmake main_unit
-@end smallexample
-@end ifclear
-
-@node Memory Management Issues
-@chapter Memory Management Issues
-
-@noindent
-This chapter describes some useful memory pools provided in the GNAT library
-and in particular the GNAT Debug Pool facility, which can be used to detect
-incorrect uses of access values (including ``dangling references'').
-@ifclear vms
-It also describes the @command{gnatmem} tool, which can be used to track down
-``memory leaks''.
-@end ifclear
-
-@menu
-* Some Useful Memory Pools::
-* The GNAT Debug Pool Facility::
-@ifclear vms
-* The gnatmem Tool::
-@end ifclear
-@end menu
-
-@node Some Useful Memory Pools
-@section Some Useful Memory Pools
-@findex Memory Pool
-@cindex storage, pool
-
-@noindent
-The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
-storage pool. Allocations use the standard system call @code{malloc} while
-deallocations use the standard system call @code{free}. No reclamation is
-performed when the pool goes out of scope. For performance reasons, the
-standard default Ada allocators/deallocators do not use any explicit storage
-pools but if they did, they could use this storage pool without any change in
-behavior. That is why this storage pool is used when the user
-manages to make the default implicit allocator explicit as in this example:
-@smallexample @c ada
- type T1 is access Something;
- -- no Storage pool is defined for T2
- type T2 is access Something_Else;
- for T2'Storage_Pool use T1'Storage_Pool;
- -- the above is equivalent to
- for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
-@end smallexample
-
-@noindent
-The @code{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage
-pool. The allocation strategy is similar to @code{Pool_Local}'s
-except that the all
-storage allocated with this pool is reclaimed when the pool object goes out of
-scope. This pool provides a explicit mechanism similar to the implicit one
-provided by several Ada 83 compilers for allocations performed through a local
-access type and whose purpose was to reclaim memory when exiting the
-scope of a given local access. As an example, the following program does not
-leak memory even though it does not perform explicit deallocation:
-
-@smallexample @c ada
-with System.Pool_Local;
-procedure Pooloc1 is
- procedure Internal is
- type A is access Integer;
- X : System.Pool_Local.Unbounded_Reclaim_Pool;
- for A'Storage_Pool use X;
- v : A;
- begin
- for I in 1 .. 50 loop
- v := new Integer;
- end loop;
- end Internal;
-begin
- for I in 1 .. 100 loop
- Internal;
- end loop;
-end Pooloc1;
-@end smallexample
-
-@noindent
-The @code{System.Pool_Size} package implements the Stack_Bounded_Pool used when
-@code{Storage_Size} is specified for an access type.
-The whole storage for the pool is
-allocated at once, usually on the stack at the point where the access type is
-elaborated. It is automatically reclaimed when exiting the scope where the
-access type is defined. This package is not intended to be used directly by the
-user and it is implicitly used for each such declaration:
-
-@smallexample @c ada
- type T1 is access Something;
- for T1'Storage_Size use 10_000;
-@end smallexample
-
-@node The GNAT Debug Pool Facility
-@section The GNAT Debug Pool Facility
-@findex Debug Pool
-@cindex storage, pool, memory corruption
-
-@noindent
-The use of unchecked deallocation and unchecked conversion can easily
-lead to incorrect memory references. The problems generated by such
-references are usually difficult to tackle because the symptoms can be
-very remote from the origin of the problem. In such cases, it is
-very helpful to detect the problem as early as possible. This is the
-purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}.
-
-In order to use the GNAT specific debugging pool, the user must
-associate a debug pool object with each of the access types that may be
-related to suspected memory problems. See Ada Reference Manual 13.11.
-@smallexample @c ada
-type Ptr is access Some_Type;
-Pool : GNAT.Debug_Pools.Debug_Pool;
-for Ptr'Storage_Pool use Pool;
-@end smallexample
-
-@noindent
-@code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
-pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools,
-allow the user to redefine allocation and deallocation strategies. They
-also provide a checkpoint for each dereference, through the use of
-the primitive operation @code{Dereference} which is implicitly called at
-each dereference of an access value.
-
-Once an access type has been associated with a debug pool, operations on
-values of the type may raise four distinct exceptions,
-which correspond to four potential kinds of memory corruption:
-@itemize @bullet
-@item
-@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
-@item
-@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
-@item
-@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
-@item
-@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage }
-@end itemize
-
-@noindent
-For types associated with a Debug_Pool, dynamic allocation is performed using
-the standard GNAT allocation routine. References to all allocated chunks of
-memory are kept in an internal dictionary. Several deallocation strategies are
-provided, whereupon the user can choose to release the memory to the system,
-keep it allocated for further invalid access checks, or fill it with an easily
-recognizable pattern for debug sessions. The memory pattern is the old IBM
-hexadecimal convention: @code{16#DEADBEEF#}.
-
-See the documentation in the file g-debpoo.ads for more information on the
-various strategies.
-
-Upon each dereference, a check is made that the access value denotes a
-properly allocated memory location. Here is a complete example of use of
-@code{Debug_Pools}, that includes typical instances of memory corruption:
-@smallexample @c ada
-@iftex
-@leftskip=0cm
-@end iftex
-with Gnat.Io; use Gnat.Io;
-with Unchecked_Deallocation;
-with Unchecked_Conversion;
-with GNAT.Debug_Pools;
-with System.Storage_Elements;
-with Ada.Exceptions; use Ada.Exceptions;
-procedure Debug_Pool_Test is
-
- type T is access Integer;
- type U is access all T;
-
- P : GNAT.Debug_Pools.Debug_Pool;
- for T'Storage_Pool use P;
-
- procedure Free is new Unchecked_Deallocation (Integer, T);
- function UC is new Unchecked_Conversion (U, T);
- A, B : aliased T;
-
- procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
-
-begin
- Info (P);
- A := new Integer;
- B := new Integer;
- B := A;
- Info (P);
- Free (A);
- begin
- Put_Line (Integer'Image(B.all));
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- begin
- Free (B);
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- B := UC(A'Access);
- begin
- Put_Line (Integer'Image(B.all));
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- begin
- Free (B);
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- Info (P);
-end Debug_Pool_Test;
-@end smallexample
-
-@noindent
-The debug pool mechanism provides the following precise diagnostics on the
-execution of this erroneous program:
-@smallexample
-Debug Pool info:
- Total allocated bytes : 0
- Total deallocated bytes : 0
- Current Water Mark: 0
- High Water Mark: 0
-
-Debug Pool info:
- Total allocated bytes : 8
- Total deallocated bytes : 0
- Current Water Mark: 8
- High Water Mark: 8
-
-raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE
-Debug Pool info:
- Total allocated bytes : 8
- Total deallocated bytes : 4
- Current Water Mark: 4
- High Water Mark: 8
-@end smallexample
-
-@ifclear vms
-@node The gnatmem Tool
-@section The @command{gnatmem} Tool
-@findex gnatmem
-
-@noindent
-The @code{gnatmem} utility monitors dynamic allocation and
-deallocation activity in a program, and displays information about
-incorrect deallocations and possible sources of memory leaks.
-It is designed to work in association with a static runtime library
-only and in this context provides three types of information:
-@itemize @bullet
-@item
-General information concerning memory management, such as the total
-number of allocations and deallocations, the amount of allocated
-memory and the high water mark, i.e.@: the largest amount of allocated
-memory in the course of program execution.
-
-@item
-Backtraces for all incorrect deallocations, that is to say deallocations
-which do not correspond to a valid allocation.
-
-@item
-Information on each allocation that is potentially the origin of a memory
-leak.
-@end itemize
-
-@menu
-* Running gnatmem::
-* Switches for gnatmem::
-* Example of gnatmem Usage::
-@end menu
-
-@node Running gnatmem
-@subsection Running @code{gnatmem}
-
-@noindent
-@code{gnatmem} makes use of the output created by the special version of
-allocation and deallocation routines that record call information. This
-allows to obtain accurate dynamic memory usage history at a minimal cost to
-the execution speed. Note however, that @code{gnatmem} is not supported on
-all platforms (currently, it is supported on AIX, HP-UX, GNU/Linux,
-Solaris and Windows NT/2000/XP (x86).
-
-@noindent
-The @code{gnatmem} command has the form
-
-@smallexample
- $ gnatmem @ovar{switches} user_program
-@end smallexample
-
-@noindent
-The program must have been linked with the instrumented version of the
-allocation and deallocation routines. This is done by linking with the
-@file{libgmem.a} library. For correct symbolic backtrace information,
-the user program should be compiled with debugging options
-(see @ref{Switches for gcc}). For example to build @file{my_program}:
-
-@smallexample
-$ gnatmake -g my_program -largs -lgmem
-@end smallexample
-
-@noindent
-As library @file{libgmem.a} contains an alternate body for package
-@code{System.Memory}, @file{s-memory.adb} should not be compiled and linked
-when an executable is linked with library @file{libgmem.a}. It is then not
-recommended to use @command{gnatmake} with switch @option{^-a^/ALL_FILES^}.
-
-@noindent
-When @file{my_program} is executed, the file @file{gmem.out} is produced.
-This file contains information about all allocations and deallocations
-performed by the program. It is produced by the instrumented allocations and
-deallocations routines and will be used by @code{gnatmem}.
-
-In order to produce symbolic backtrace information for allocations and
-deallocations performed by the GNAT run-time library, you need to use a
-version of that library that has been compiled with the @option{-g} switch
-(see @ref{Rebuilding the GNAT Run-Time Library}).
-
-Gnatmem must be supplied with the @file{gmem.out} file and the executable to
-examine. If the location of @file{gmem.out} file was not explicitly supplied by
-@option{-i} switch, gnatmem will assume that this file can be found in the
-current directory. For example, after you have executed @file{my_program},
-@file{gmem.out} can be analyzed by @code{gnatmem} using the command:
-
-@smallexample
-$ gnatmem my_program
-@end smallexample
-
-@noindent
-This will produce the output with the following format:
-
-*************** debut cc
-@smallexample
-$ gnatmem my_program
-
-Global information
-------------------
- Total number of allocations : 45
- Total number of deallocations : 6
- Final Water Mark (non freed mem) : 11.29 Kilobytes
- High Water Mark : 11.40 Kilobytes
-
-.
-.
-.
-Allocation Root # 2
--------------------
- Number of non freed allocations : 11
- Final Water Mark (non freed mem) : 1.16 Kilobytes
- High Water Mark : 1.27 Kilobytes
- Backtrace :
- my_program.adb:23 my_program.alloc
-.
-.
-.
-@end smallexample
-
-The first block of output gives general information. In this case, the
-Ada construct ``@code{@b{new}}'' was executed 45 times, and only 6 calls to an
-Unchecked_Deallocation routine occurred.
-
-@noindent
-Subsequent paragraphs display information on all allocation roots.
-An allocation root is a specific point in the execution of the program
-that generates some dynamic allocation, such as a ``@code{@b{new}}''
-construct. This root is represented by an execution backtrace (or subprogram
-call stack). By default the backtrace depth for allocations roots is 1, so
-that a root corresponds exactly to a source location. The backtrace can
-be made deeper, to make the root more specific.
-
-@node Switches for gnatmem
-@subsection Switches for @code{gnatmem}
-
-@noindent
-@code{gnatmem} recognizes the following switches:
-
-@table @option
-
-@item -q
-@cindex @option{-q} (@code{gnatmem})
-Quiet. Gives the minimum output needed to identify the origin of the
-memory leaks. Omits statistical information.
-
-@item @var{N}
-@cindex @var{N} (@code{gnatmem})
-N is an integer literal (usually between 1 and 10) which controls the
-depth of the backtraces defining allocation root. The default value for
-N is 1. The deeper the backtrace, the more precise the localization of
-the root. Note that the total number of roots can depend on this
-parameter. This parameter must be specified @emph{before} the name of the
-executable to be analyzed, to avoid ambiguity.
-
-@item -b n
-@cindex @option{-b} (@code{gnatmem})
-This switch has the same effect as just depth parameter.
-
-@item -i @var{file}
-@cindex @option{-i} (@code{gnatmem})
-Do the @code{gnatmem} processing starting from @file{file}, rather than
-@file{gmem.out} in the current directory.
-
-@item -m n
-@cindex @option{-m} (@code{gnatmem})
-This switch causes @code{gnatmem} to mask the allocation roots that have less
-than n leaks. The default value is 1. Specifying the value of 0 will allow to
-examine even the roots that didn't result in leaks.
-
-@item -s order
-@cindex @option{-s} (@code{gnatmem})
-This switch causes @code{gnatmem} to sort the allocation roots according to the
-specified order of sort criteria, each identified by a single letter. The
-currently supported criteria are @code{n, h, w} standing respectively for
-number of unfreed allocations, high watermark, and final watermark
-corresponding to a specific root. The default order is @code{nwh}.
-
-@end table
-
-@node Example of gnatmem Usage
-@subsection Example of @code{gnatmem} Usage
-
-@noindent
-The following example shows the use of @code{gnatmem}
-on a simple memory-leaking program.
-Suppose that we have the following Ada program:
-
-@smallexample @c ada
-@group
-@cartouche
-with Unchecked_Deallocation;
-procedure Test_Gm is
-
- type T is array (1..1000) of Integer;
- type Ptr is access T;
- procedure Free is new Unchecked_Deallocation (T, Ptr);
- A : Ptr;
-
- procedure My_Alloc is
- begin
- A := new T;
- end My_Alloc;
-
- procedure My_DeAlloc is
- B : Ptr := A;
- begin
- Free (B);
- end My_DeAlloc;
-
-begin
- My_Alloc;
- for I in 1 .. 5 loop
- for J in I .. 5 loop
- My_Alloc;
- end loop;
- My_Dealloc;
- end loop;
-end;
-@end cartouche
-@end group
+The GNAT Project Manager takes full care of the library maintenance task,
+including recompilation of the source files for which objects do not exist
+or are not up to date, assembly of the library archive, and installation of
+the library (i.e., copying associated source, object and @file{ALI} files
+to the specified location).
+
+Here is a simple library project file:
+@smallexample @c ada
+project My_Lib is
+ for Source_Dirs use ("src1", "src2");
+ for Object_Dir use "obj";
+ for Library_Name use "mylib";
+ for Library_Dir use "lib";
+ for Library_Kind use "dynamic";
+end My_lib;
@end smallexample
@noindent
-The program needs to be compiled with debugging option and linked with
-@code{gmem} library:
+and the compilation command to build and install the library:
-@smallexample
-$ gnatmake -g test_gm -largs -lgmem
+@smallexample @c ada
+ $ gnatmake -Pmy_lib
@end smallexample
@noindent
-Then we execute the program as usual:
+It is not entirely trivial to perform manually all the steps required to
+produce a library. We recommend that you use the GNAT Project Manager
+for this task. In special cases where this is not desired, the necessary
+steps are discussed below.
-@smallexample
-$ test_gm
-@end smallexample
+There are various possibilities for compiling the units that make up the
+library: for example with a Makefile (@pxref{Using the GNU make Utility}) or
+with a conventional script. For simple libraries, it is also possible to create
+a dummy main program which depends upon all the packages that comprise the
+interface of the library. This dummy main program can then be given to
+@command{gnatmake}, which will ensure that all necessary objects are built.
-@noindent
-Then @code{gnatmem} is invoked simply with
-@smallexample
-$ gnatmem test_gm
+After this task is accomplished, you should follow the standard procedure
+of the underlying operating system to produce the static or shared library.
+
+Here is an example of such a dummy program:
+@smallexample @c ada
+@group
+with My_Lib.Service1;
+with My_Lib.Service2;
+with My_Lib.Service3;
+procedure My_Lib_Dummy is
+begin
+ null;
+end;
+@end group
@end smallexample
@noindent
-which produces the following output (result may vary on different platforms):
+Here are the generic commands that will build an archive or a shared library.
@smallexample
-Global information
-------------------
- Total number of allocations : 18
- Total number of deallocations : 5
- Final Water Mark (non freed mem) : 53.00 Kilobytes
- High Water Mark : 56.90 Kilobytes
+# compiling the library
+$ gnatmake -c my_lib_dummy.adb
-Allocation Root # 1
--------------------
- Number of non freed allocations : 11
- Final Water Mark (non freed mem) : 42.97 Kilobytes
- High Water Mark : 46.88 Kilobytes
- Backtrace :
- test_gm.adb:11 test_gm.my_alloc
+# we don't need the dummy object itself
+$ rm my_lib_dummy.o my_lib_dummy.ali
-Allocation Root # 2
--------------------
- Number of non freed allocations : 1
- Final Water Mark (non freed mem) : 10.02 Kilobytes
- High Water Mark : 10.02 Kilobytes
- Backtrace :
- s-secsta.adb:81 system.secondary_stack.ss_init
+# create an archive with the remaining objects
+$ ar rc libmy_lib.a *.o
+# some systems may require "ranlib" to be run as well
-Allocation Root # 3
--------------------
- Number of non freed allocations : 1
- Final Water Mark (non freed mem) : 12 Bytes
- High Water Mark : 12 Bytes
- Backtrace :
- s-secsta.adb:181 system.secondary_stack.ss_init
-@end smallexample
+# or create a shared library
+$ gcc -shared -o libmy_lib.so *.o
+# some systems may require the code to have been compiled with -fPIC
-@noindent
-Note that the GNAT run time contains itself a certain number of
-allocations that have no corresponding deallocation,
-as shown here for root #2 and root
-#3. This is a normal behavior when the number of non-freed allocations
-is one, it allocates dynamic data structures that the run time needs for
-the complete lifetime of the program. Note also that there is only one
-allocation root in the user program with a single line back trace:
-test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the
-program shows that 'My_Alloc' is called at 2 different points in the
-source (line 21 and line 24). If those two allocation roots need to be
-distinguished, the backtrace depth parameter can be used:
+# remove the object files that are now in the library
+$ rm *.o
-@smallexample
-$ gnatmem 3 test_gm
+# Make the ALI files read-only so that gnatmake will not try to
+# regenerate the objects that are in the library
+$ chmod -w *.ali
@end smallexample
@noindent
-which will give the following output:
-
-@smallexample
-Global information
-------------------
- Total number of allocations : 18
- Total number of deallocations : 5
- Final Water Mark (non freed mem) : 53.00 Kilobytes
- High Water Mark : 56.90 Kilobytes
-
-Allocation Root # 1
--------------------
- Number of non freed allocations : 10
- Final Water Mark (non freed mem) : 39.06 Kilobytes
- High Water Mark : 42.97 Kilobytes
- Backtrace :
- test_gm.adb:11 test_gm.my_alloc
- test_gm.adb:24 test_gm
- b_test_gm.c:52 main
+Please note that the library must have a name of the form @file{lib@var{xxx}.a}
+or @file{lib@var{xxx}.so} (or @file{lib@var{xxx}.dll} on Windows) in order to
+be accessed by the directive @option{-l@var{xxx}} at link time.
-Allocation Root # 2
--------------------
- Number of non freed allocations : 1
- Final Water Mark (non freed mem) : 10.02 Kilobytes
- High Water Mark : 10.02 Kilobytes
- Backtrace :
- s-secsta.adb:81 system.secondary_stack.ss_init
- s-secsta.adb:283 <system__secondary_stack___elabb>
- b_test_gm.c:33 adainit
+@node Installing a library
+@subsection Installing a library
+@cindex @code{ADA_PROJECT_PATH}
+@cindex @code{GPR_PROJECT_PATH}
-Allocation Root # 3
--------------------
- Number of non freed allocations : 1
- Final Water Mark (non freed mem) : 3.91 Kilobytes
- High Water Mark : 3.91 Kilobytes
- Backtrace :
- test_gm.adb:11 test_gm.my_alloc
- test_gm.adb:21 test_gm
- b_test_gm.c:52 main
+@noindent
+If you use project files, library installation is part of the library build
+process (@pxref{Installing a library with project files}).
-Allocation Root # 4
--------------------
- Number of non freed allocations : 1
- Final Water Mark (non freed mem) : 12 Bytes
- High Water Mark : 12 Bytes
- Backtrace :
- s-secsta.adb:181 system.secondary_stack.ss_init
- s-secsta.adb:283 <system__secondary_stack___elabb>
- b_test_gm.c:33 adainit
+When project files are not an option, it is also possible, but not recommended,
+to install the library so that the sources needed to use the library are on the
+Ada source path and the ALI files & libraries be on the Ada Object path (see
+@ref{Search Paths and the Run-Time Library (RTL)}. Alternatively, the system
+administrator can place general-purpose libraries in the default compiler
+paths, by specifying the libraries' location in the configuration files
+@file{ada_source_path} and @file{ada_object_path}. These configuration files
+must be located in the GNAT installation tree at the same place as the gcc spec
+file. The location of the gcc spec file can be determined as follows:
+@smallexample
+$ gcc -v
@end smallexample
@noindent
-The allocation root #1 of the first example has been split in 2 roots #1
-and #3 thanks to the more precise associated backtrace.
+The configuration files mentioned above have a simple format: each line
+must contain one unique directory name.
+Those names are added to the corresponding path
+in their order of appearance in the file. The names can be either absolute
+or relative; in the latter case, they are relative to where theses files
+are located.
-@end ifclear
+The files @file{ada_source_path} and @file{ada_object_path} might not be
+present in a
+GNAT installation, in which case, GNAT will look for its run-time library in
+the directories @file{adainclude} (for the sources) and @file{adalib} (for the
+objects and @file{ALI} files). When the files exist, the compiler does not
+look in @file{adainclude} and @file{adalib}, and thus the
+@file{ada_source_path} file
+must contain the location for the GNAT run-time sources (which can simply
+be @file{adainclude}). In the same way, the @file{ada_object_path} file must
+contain the location for the GNAT run-time objects (which can simply
+be @file{adalib}).
-@node Stack Related Facilities
-@chapter Stack Related Facilities
+You can also specify a new default path to the run-time library at compilation
+time with the switch @option{--RTS=rts-path}. You can thus choose / change
+the run-time library you want your program to be compiled with. This switch is
+recognized by @command{gcc}, @command{gnatmake}, @command{gnatbind},
+@command{gnatls}, @command{gnatfind} and @command{gnatxref}.
-@noindent
-This chapter describes some useful tools associated with stack
-checking and analysis. In
-particular, it deals with dynamic and static stack usage measurements.
+It is possible to install a library before or after the standard GNAT
+library, by reordering the lines in the configuration files. In general, a
+library must be installed before the GNAT library if it redefines
+any part of it.
-@menu
-* Stack Overflow Checking::
-* Static Stack Usage Analysis::
-* Dynamic Stack Usage Analysis::
-@end menu
+@node Using a library
+@subsection Using a library
-@node Stack Overflow Checking
-@section Stack Overflow Checking
-@cindex Stack Overflow Checking
-@cindex -fstack-check
+@noindent Once again, the project facility greatly simplifies the use of
+libraries. In this context, using a library is just a matter of adding a
+@code{with} clause in the user project. For instance, to make use of the
+library @code{My_Lib} shown in examples in earlier sections, you can
+write:
-@noindent
-For most operating systems, @command{gcc} does not perform stack overflow
-checking by default. This means that if the main environment task or
-some other task exceeds the available stack space, then unpredictable
-behavior will occur. Most native systems offer some level of protection by
-adding a guard page at the end of each task stack. This mechanism is usually
-not enough for dealing properly with stack overflow situations because
-a large local variable could ``jump'' above the guard page.
-Furthermore, when the
-guard page is hit, there may not be any space left on the stack for executing
-the exception propagation code. Enabling stack checking avoids
-such situations.
+@smallexample @c projectfile
+with "my_lib";
+project My_Proj is
+ @dots{}
+end My_Proj;
+@end smallexample
-To activate stack checking, compile all units with the gcc option
-@option{-fstack-check}. For example:
+Even if you have a third-party, non-Ada library, you can still use GNAT's
+Project Manager facility to provide a wrapper for it. For example, the
+following project, when @code{with}ed by your main project, will link with the
+third-party library @file{liba.a}:
-@smallexample
-gcc -c -fstack-check package1.adb
+@smallexample @c projectfile
+@group
+project Liba is
+ for Externally_Built use "true";
+ for Source_Files use ();
+ for Library_Dir use "lib";
+ for Library_Name use "a";
+ for Library_Kind use "static";
+end Liba;
+@end group
@end smallexample
+This is an alternative to the use of @code{pragma Linker_Options}. It is
+especially interesting in the context of systems with several interdependent
+static libraries where finding a proper linker order is not easy and best be
+left to the tools having visibility over project dependence information.
@noindent
-Units compiled with this option will generate extra instructions to check
-that any use of the stack (for procedure calls or for declaring local
-variables in declare blocks) does not exceed the available stack space.
-If the space is exceeded, then a @code{Storage_Error} exception is raised.
-
-For declared tasks, the stack size is controlled by the size
-given in an applicable @code{Storage_Size} pragma or by the value specified
-at bind time with @option{-d} (@pxref{Switches for gnatbind}) or is set to
-the default size as defined in the GNAT runtime otherwise.
+In order to use an Ada library manually, you need to make sure that this
+library is on both your source and object path
+(see @ref{Search Paths and the Run-Time Library (RTL)}
+and @ref{Search Paths for gnatbind}). Furthermore, when the objects are grouped
+in an archive or a shared library, you need to specify the desired
+library at link time.
-For the environment task, the stack size depends on
-system defaults and is unknown to the compiler. Stack checking
-may still work correctly if a fixed
-size stack is allocated, but this cannot be guaranteed.
-@ifclear vms
-To ensure that a clean exception is signalled for stack
-overflow, set the environment variable
-@env{GNAT_STACK_LIMIT} to indicate the maximum
-stack area that can be used, as in:
-@cindex GNAT_STACK_LIMIT
+For example, you can use the library @file{mylib} installed in
+@file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands:
@smallexample
-SET GNAT_STACK_LIMIT 1600
+$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \
+ -largs -lmy_lib
@end smallexample
@noindent
-The limit is given in kilobytes, so the above declaration would
-set the stack limit of the environment task to 1.6 megabytes.
-Note that the only purpose of this usage is to limit the amount
-of stack used by the environment task. If it is necessary to
-increase the amount of stack for the environment task, then this
-is an operating systems issue, and must be addressed with the
-appropriate operating systems commands.
-@end ifclear
-@ifset vms
-To have a fixed size stack in the environment task, the stack must be put
-in the P0 address space and its size specified. Use these switches to
-create a p0 image:
-
+This can be expressed more simply:
@smallexample
-gnatmake my_progs -largs "-Wl,--opt=STACK=4000,/p0image"
+$ gnatmake my_appl
@end smallexample
-
-@noindent
-The quotes are required to keep case. The number after @samp{STACK=} is the
-size of the environmental task stack in pagelets (512 bytes). In this example
-the stack size is about 2 megabytes.
-
-@noindent
-A consequence of the @option{/p0image} qualifier is also to makes RMS buffers
-be placed in P0 space. Refer to @cite{HP OpenVMS Linker Utility Manual} for
-more details about the @option{/p0image} qualifier and the @option{stack}
-option.
-@end ifset
-
-@node Static Stack Usage Analysis
-@section Static Stack Usage Analysis
-@cindex Static Stack Usage Analysis
-@cindex -fstack-usage
-
@noindent
-A unit compiled with @option{-fstack-usage} will generate an extra file
-that specifies
-the maximum amount of stack used, on a per-function basis.
-The file has the same
-basename as the target object file with a @file{.su} extension.
-Each line of this file is made up of three fields:
-
-@itemize
+when the following conditions are met:
+@itemize @bullet
@item
-The name of the function.
+@file{/dir/my_lib_src} has been added by the user to the environment
+variable @env{ADA_INCLUDE_PATH}, or by the administrator to the file
+@file{ada_source_path}
@item
-A number of bytes.
+@file{/dir/my_lib_obj} has been added by the user to the environment
+variable @env{ADA_OBJECTS_PATH}, or by the administrator to the file
+@file{ada_object_path}
@item
-One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
+a pragma @code{Linker_Options} has been added to one of the sources.
+For example:
+
+@smallexample @c ada
+pragma Linker_Options ("-lmy_lib");
+@end smallexample
@end itemize
-The second field corresponds to the size of the known part of the function
-frame.
+@node Stand-alone Ada Libraries
+@section Stand-alone Ada Libraries
+@cindex Stand-alone library, building, using
-The qualifier @code{static} means that the function frame size
-is purely static.
-It usually means that all local variables have a static size.
-In this case, the second field is a reliable measure of the function stack
-utilization.
+@menu
+* Introduction to Stand-alone Libraries::
+* Building a Stand-alone Library::
+* Creating a Stand-alone Library to be used in a non-Ada context::
+* Restrictions in Stand-alone Libraries::
+@end menu
-The qualifier @code{dynamic} means that the function frame size is not static.
-It happens mainly when some local variables have a dynamic size. When this
-qualifier appears alone, the second field is not a reliable measure
-of the function stack analysis. When it is qualified with @code{bounded}, it
-means that the second field is a reliable maximum of the function stack
-utilization.
+@node Introduction to Stand-alone Libraries
+@subsection Introduction to Stand-alone Libraries
-@node Dynamic Stack Usage Analysis
-@section Dynamic Stack Usage Analysis
+@noindent
+A Stand-alone Library (abbreviated ``SAL'') is a library that contains the
+necessary code to
+elaborate the Ada units that are included in the library. In contrast with
+an ordinary library, which consists of all sources, objects and @file{ALI}
+files of the
+library, a SAL may specify a restricted subset of compilation units
+to serve as a library interface. In this case, the fully
+self-sufficient set of files will normally consist of an objects
+archive, the sources of interface units' specs, and the @file{ALI}
+files of interface units.
+If an interface spec contains a generic unit or an inlined subprogram,
+the body's
+source must also be provided; if the units that must be provided in the source
+form depend on other units, the source and @file{ALI} files of those must
+also be provided.
+
+The main purpose of a SAL is to minimize the recompilation overhead of client
+applications when a new version of the library is installed. Specifically,
+if the interface sources have not changed, client applications do not need to
+be recompiled. If, furthermore, a SAL is provided in the shared form and its
+version, controlled by @code{Library_Version} attribute, is not changed,
+then the clients do not need to be relinked.
+
+SALs also allow the library providers to minimize the amount of library source
+text exposed to the clients. Such ``information hiding'' might be useful or
+necessary for various reasons.
+
+Stand-alone libraries are also well suited to be used in an executable whose
+main routine is not written in Ada.
+
+@node Building a Stand-alone Library
+@subsection Building a Stand-alone Library
@noindent
-It is possible to measure the maximum amount of stack used by a task, by
-adding a switch to @command{gnatbind}, as:
+GNAT's Project facility provides a simple way of building and installing
+stand-alone libraries; see @ref{Stand-alone Library Projects}.
+To be a Stand-alone Library Project, in addition to the two attributes
+that make a project a Library Project (@code{Library_Name} and
+@code{Library_Dir}; see @ref{Library Projects}), the attribute
+@code{Library_Interface} must be defined. For example:
-@smallexample
-$ gnatbind -u0 file
+@smallexample @c projectfile
+@group
+ for Library_Dir use "lib_dir";
+ for Library_Name use "dummy";
+ for Library_Interface use ("int1", "int1.child");
+@end group
@end smallexample
@noindent
-With this option, at each task termination, its stack usage is output on
-@file{stderr}.
-It is not always convenient to output the stack usage when the program
-is still running. Hence, it is possible to delay this output until program
-termination. for a given number of tasks specified as the argument of the
-@option{-u} option. For instance:
+Attribute @code{Library_Interface} has a non-empty string list value,
+each string in the list designating a unit contained in an immediate source
+of the project file.
+
+When a Stand-alone Library is built, first the binder is invoked to build
+a package whose name depends on the library name
+(@file{^b~dummy.ads/b^B$DUMMY.ADS/B^} in the example above).
+This binder-generated package includes initialization and
+finalization procedures whose
+names depend on the library name (@code{dummyinit} and @code{dummyfinal}
+in the example
+above). The object corresponding to this package is included in the library.
+
+You must ensure timely (e.g., prior to any use of interfaces in the SAL)
+calling of these procedures if a static SAL is built, or if a shared SAL
+is built
+with the project-level attribute @code{Library_Auto_Init} set to
+@code{"false"}.
+
+For a Stand-Alone Library, only the @file{ALI} files of the Interface Units
+(those that are listed in attribute @code{Library_Interface}) are copied to
+the Library Directory. As a consequence, only the Interface Units may be
+imported from Ada units outside of the library. If other units are imported,
+the binding phase will fail.
+
+The attribute @code{Library_Src_Dir} may be specified for a
+Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
+single string value. Its value must be the path (absolute or relative to the
+project directory) of an existing directory. This directory cannot be the
+object directory or one of the source directories, but it can be the same as
+the library directory. The sources of the Interface
+Units of the library that are needed by an Ada client of the library will be
+copied to the designated directory, called the Interface Copy directory.
+These sources include the specs of the Interface Units, but they may also
+include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
+are used, or when there is a generic unit in the spec. Before the sources
+are copied to the Interface Copy directory, an attempt is made to delete all
+files in the Interface Copy directory.
+
+Building stand-alone libraries by hand is somewhat tedious, but for those
+occasions when it is necessary here are the steps that you need to perform:
+@itemize @bullet
+@item
+Compile all library sources.
+@item
+Invoke the binder with the switch @option{-n} (No Ada main program),
+with all the @file{ALI} files of the interfaces, and
+with the switch @option{-L} to give specific names to the @code{init}
+and @code{final} procedures. For example:
@smallexample
-$ gnatbind -u100 file
+ gnatbind -n int1.ali int2.ali -Lsal1
@end smallexample
-@noindent
-will buffer the stack usage information of the first 100 tasks to terminate and
-output this info at program termination. Results are displayed in four
-columns:
+@item
+Compile the binder generated file:
+@smallexample
+ gcc -c b~int2.adb
+@end smallexample
-@noindent
-Index | Task Name | Stack Size | Stack Usage [Value +/- Variation]
+@item
+Link the dynamic library with all the necessary object files,
+indicating to the linker the names of the @code{init} (and possibly
+@code{final}) procedures for automatic initialization (and finalization).
+The built library should be placed in a directory different from
+the object directory.
+
+@item
+Copy the @code{ALI} files of the interface to the library directory,
+add in this copy an indication that it is an interface to a SAL
+(i.e., add a word @option{SL} on the line in the @file{ALI} file that starts
+with letter ``P'') and make the modified copy of the @file{ALI} file
+read-only.
+@end itemize
@noindent
-where:
+Using SALs is not different from using other libraries
+(see @ref{Using a library}).
-@table @emph
-@item Index
-is a number associated with each task.
+@node Creating a Stand-alone Library to be used in a non-Ada context
+@subsection Creating a Stand-alone Library to be used in a non-Ada context
-@item Task Name
-is the name of the task analyzed.
+@noindent
+It is easy to adapt the SAL build procedure discussed above for use of a SAL in
+a non-Ada context.
-@item Stack Size
-is the maximum size for the stack.
+The only extra step required is to ensure that library interface subprograms
+are compatible with the main program, by means of @code{pragma Export}
+or @code{pragma Convention}.
-@item Stack Usage
-is the measure done by the stack analyzer. In order to prevent overflow, the stack
-is not entirely analyzed, and it's not possible to know exactly how
-much has actually been used. The report thus contains the theoretical stack usage
-(Value) and the possible variation (Variation) around this value.
+Here is an example of simple library interface for use with C main program:
-@end table
+@smallexample @c ada
+package My_Package is
-@noindent
-The environment task stack, e.g., the stack that contains the main unit, is
-only processed when the environment variable GNAT_STACK_LIMIT is set.
+ procedure Do_Something;
+ pragma Export (C, Do_Something, "do_something");
+ procedure Do_Something_Else;
+ pragma Export (C, Do_Something_Else, "do_something_else");
-@c *********************************
-@c * GNATCHECK *
-@c *********************************
-@node Verifying Properties Using gnatcheck
-@chapter Verifying Properties Using @command{gnatcheck}
-@findex gnatcheck
-@cindex @command{gnatcheck}
+end My_Package;
+@end smallexample
@noindent
-The @command{gnatcheck} tool is an ASIS-based utility that checks properties
-of Ada source files according to a given set of semantic rules.
-@cindex ASIS
-
-In order to check compliance with a given rule, @command{gnatcheck} has to
-semantically analyze the Ada sources.
-Therefore, checks can only be performed on
-legal Ada units. Moreover, when a unit depends semantically upon units located
-outside the current directory, the source search path has to be provided when
-calling @command{gnatcheck}, either through a specified project file or
-through @command{gnatcheck} switches as described below.
-
-A number of rules are predefined in @command{gnatcheck} and are described
-later in this chapter.
-You can also add new rules, by modifying the @command{gnatcheck} code and
-rebuilding the tool. In order to add a simple rule making some local checks,
-a small amount of straightforward ASIS-based programming is usually needed.
+On the foreign language side, you must provide a ``foreign'' view of the
+library interface; remember that it should contain elaboration routines in
+addition to interface subprograms.
-Project support for @command{gnatcheck} is provided by the GNAT
-driver (see @ref{The GNAT Driver and Project Files}).
+The example below shows the content of @code{mylib_interface.h} (note
+that there is no rule for the naming of this file, any name can be used)
+@smallexample
+/* the library elaboration procedure */
+extern void mylibinit (void);
-Invoking @command{gnatcheck} on the command line has the form:
+/* the library finalization procedure */
+extern void mylibfinal (void);
-@smallexample
-$ gnatcheck @ovar{switches} @{@var{filename}@}
- @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
- @r{[}-cargs @var{gcc_switches}@r{]} @r{[}-rules @var{rule_options}@r{]}
+/* the interface exported by the library */
+extern void do_something (void);
+extern void do_something_else (void);
@end smallexample
@noindent
-where
-@itemize @bullet
-@item
-@var{switches} specify the general tool options
+Libraries built as explained above can be used from any program, provided
+that the elaboration procedures (named @code{mylibinit} in the previous
+example) are called before the library services are used. Any number of
+libraries can be used simultaneously, as long as the elaboration
+procedure of each library is called.
-@item
-Each @var{filename} is the name (including the extension) of a source
-file to process. ``Wildcards'' are allowed, and
-the file name may contain path information.
+Below is an example of a C program that uses the @code{mylib} library.
-@item
-Each @var{arg_list_filename} is the name (including the extension) of a text
-file containing the names of the source files to process, separated by spaces
-or line breaks.
+@smallexample
+#include "mylib_interface.h"
-@item
-@var{gcc_switches} is a list of switches for
-@command{gcc}. They will be passed on to all compiler invocations made by
-@command{gnatcheck} to generate the ASIS trees. Here you can provide
-@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
-and use the @option{-gnatec} switch to set the configuration file.
+int
+main (void)
+@{
+ /* First, elaborate the library before using it */
+ mylibinit ();
-@item
-@var{rule_options} is a list of options for controlling a set of
-rules to be checked by @command{gnatcheck} (@pxref{gnatcheck Rule Options}).
-@end itemize
+ /* Main program, using the library exported entities */
+ do_something ();
+ do_something_else ();
-@noindent
-Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be supplied.
+ /* Library finalization at the end of the program */
+ mylibfinal ();
+ return 0;
+@}
+@end smallexample
-@menu
-* Format of the Report File::
-* General gnatcheck Switches::
-* gnatcheck Rule Options::
-* Adding the Results of Compiler Checks to gnatcheck Output::
-* Project-Wide Checks::
-* Predefined Rules::
-@end menu
+@noindent
+Note that invoking any library finalization procedure generated by
+@code{gnatbind} shuts down the Ada run-time environment.
+Consequently, the
+finalization of all Ada libraries must be performed at the end of the program.
+No call to these libraries or to the Ada run-time library should be made
+after the finalization phase.
-@node Format of the Report File
-@section Format of the Report File
-@cindex Report file (for @code{gnatcheck})
+@node Restrictions in Stand-alone Libraries
+@subsection Restrictions in Stand-alone Libraries
@noindent
-The @command{gnatcheck} tool outputs on @file{stdout} all messages concerning
-rule violations.
-It also creates a text file that
-contains the complete report of the last gnatcheck run. By default this file is
-named named @file{^gnatcheck.out^GNATCHECK.OUT^} and it is located in the current
-directory, @option{^-o^/OUTPUT^} option can be used to change the name and/or
-location of the report file. This report contains:
+The pragmas listed below should be used with caution inside libraries,
+as they can create incompatibilities with other Ada libraries:
@itemize @bullet
-@item a list of the Ada source files being checked,
-@item a list of enabled and disabled rules,
-@item a list of the diagnostic messages, ordered in three different ways
-and collected in three separate
-sections. Section 1 contains the raw list of diagnostic messages. It
-corresponds to the output going to @file{stdout}. Section 2 contains
-messages ordered by rules.
-Section 3 contains messages ordered by source files.
+@item pragma @code{Locking_Policy}
+@item pragma @code{Queuing_Policy}
+@item pragma @code{Task_Dispatching_Policy}
+@item pragma @code{Unreserve_All_Interrupts}
@end itemize
-@node General gnatcheck Switches
-@section General @command{gnatcheck} Switches
-
@noindent
-The following switches control the general @command{gnatcheck} behavior
+When using a library that contains such pragmas, the user must make sure
+that all libraries use the same pragmas with the same values. Otherwise,
+@code{Program_Error} will
+be raised during the elaboration of the conflicting
+libraries. The usage of these pragmas and its consequences for the user
+should therefore be well documented.
-@table @option
-@c !sort!
-@cindex @option{^-a^/ALL^} (@command{gnatcheck})
-@item ^-a^/ALL^
-Process all units including those with read-only ALI files such as
-those from GNAT Run-Time library.
+Similarly, the traceback in the exception occurrence mechanism should be
+enabled or disabled in a consistent manner across all libraries.
+Otherwise, Program_Error will be raised during the elaboration of the
+conflicting libraries.
-@ifclear vms
-@ignore
-@cindex @option{-d} (@command{gnatcheck})
-@item -d
-Debug mode
-@end ignore
+If the @code{Version} or @code{Body_Version}
+attributes are used inside a library, then you need to
+perform a @code{gnatbind} step that specifies all @file{ALI} files in all
+libraries, so that version identifiers can be properly computed.
+In practice these attributes are rarely used, so this is unlikely
+to be a consideration.
-@cindex @option{-dd} (@command{gnatcheck})
-@item -dd
-Progress indicator mode (for use in GPS)
-@end ifclear
+@node Rebuilding the GNAT Run-Time Library
+@section Rebuilding the GNAT Run-Time Library
+@cindex GNAT Run-Time Library, rebuilding
+@cindex Building the GNAT Run-Time Library
+@cindex Rebuilding the GNAT Run-Time Library
+@cindex Run-Time Library, rebuilding
-@cindex @option{^-h^/HELP^} (@command{gnatcheck})
-@item ^-h^/HELP^
-List the predefined and user-defined rules. For more details see
-@ref{Predefined Rules}.
+@noindent
+It may be useful to recompile the GNAT library in various contexts, the
+most important one being the use of partition-wide configuration pragmas
+such as @code{Normalize_Scalars}. A special Makefile called
+@code{Makefile.adalib} is provided to that effect and can be found in
+the directory containing the GNAT library. The location of this
+directory depends on the way the GNAT environment has been installed and can
+be determined by means of the command:
-@cindex @option{^-l^/LOCS^} (@command{gnatcheck})
-@item ^-l^/LOCS^
-Use full source locations references in the report file. For a construct from
-a generic instantiation a full source location is a chain from the location
-of this construct in the generic unit to the place where this unit is
-instantiated.
+@smallexample
+$ gnatls -v
+@end smallexample
-@cindex @option{^-log^/LOG^} (@command{gnatcheck})
-@item ^-log^/LOG^
-Duplicate all the output sent to Stderr into a log file. The log file is
-named @var{gnatcheck.log} and is located in the current directory.
+@noindent
+The last entry in the object search path usually contains the
+gnat library. This Makefile contains its own documentation and in
+particular the set of instructions needed to rebuild a new library and
+to use it.
-@cindex @option{^-m^/DIAGNOSTIC_LIMIT^} (@command{gnatcheck})
-@item ^-m@i{nnn}^/DIAGNOSTIC_LIMIT=@i{nnn}^
-Maximum number of diagnoses to be sent to Stdout, @i{nnn} from o@dots{}1000,
-the default value is 500. Zero means that there is no limitation on
-the number of diagnostic messages to be printed into Stdout.
+@node Using the GNU make Utility
+@chapter Using the GNU @code{make} Utility
+@findex make
-@cindex @option{^-q^/QUIET^} (@command{gnatcheck})
-@item ^-q^/QUIET^
-Quiet mode. All the diagnoses about rule violations are placed in the
-@command{gnatcheck} report file only, without duplicating in @file{stdout}.
+@noindent
+This chapter offers some examples of makefiles that solve specific
+problems. It does not explain how to write a makefile (@pxref{Top,, GNU
+make, make, GNU @code{make}}), nor does it try to replace the
+@command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}).
-@cindex @option{^-s^/SHORT^} (@command{gnatcheck})
-@item ^-s^/SHORT^
-Short format of the report file (no version information, no list of applied
-rules, no list of checked sources is included)
+All the examples in this section are specific to the GNU version of
+make. Although @command{make} is a standard utility, and the basic language
+is the same, these examples use some advanced features found only in
+@code{GNU make}.
+
+@menu
+* Using gnatmake in a Makefile::
+* Automatically Creating a List of Directories::
+* Generating the Command Line Switches::
+* Overcoming Command Line Length Limits::
+@end menu
+
+@node Using gnatmake in a Makefile
+@section Using gnatmake in a Makefile
+@findex makefile
+@cindex GNU make
-@cindex @option{^-s1^/COMPILER_STYLE^} (@command{gnatcheck})
-@item ^-s1^/COMPILER_STYLE^
-Include the compiler-style section in the report file
+@noindent
+Complex project organizations can be handled in a very powerful way by
+using GNU make combined with gnatmake. For instance, here is a Makefile
+which allows you to build each subsystem of a big project into a separate
+shared library. Such a makefile allows you to significantly reduce the link
+time of very big applications while maintaining full coherence at
+each step of the build process.
-@cindex @option{^-s2^/BY_RULES^} (@command{gnatcheck})
-@item ^-s2^/BY_RULES^
-Include the section containing diagnoses ordered by rules in the report file
+The list of dependencies are handled automatically by
+@command{gnatmake}. The Makefile is simply used to call gnatmake in each of
+the appropriate directories.
-@cindex @option{^-s3^/BY_FILES_BY_RULES^} (@command{gnatcheck})
-@item ^-s3^/BY_FILES_BY_RULES^
-Include the section containing diagnoses ordered by files and then by rules
-in the report file
+Note that you should also read the example on how to automatically
+create the list of directories
+(@pxref{Automatically Creating a List of Directories})
+which might help you in case your project has a lot of subdirectories.
-@cindex @option{^-t^/TIME^} (@command{gnatcheck})
-@item ^-t^/TIME^
-Print out execution time.
+@smallexample
+@iftex
+@leftskip=0cm
+@font@heightrm=cmr8
+@heightrm
+@end iftex
+## This Makefile is intended to be used with the following directory
+## configuration:
+## - The sources are split into a series of csc (computer software components)
+## Each of these csc is put in its own directory.
+## Their name are referenced by the directory names.
+## They will be compiled into shared library (although this would also work
+## with static libraries
+## - The main program (and possibly other packages that do not belong to any
+## csc is put in the top level directory (where the Makefile is).
+## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
+## \_ second_csc (sources) __ lib (will contain the library)
+## \_ @dots{}
+## Although this Makefile is build for shared library, it is easy to modify
+## to build partial link objects instead (modify the lines with -shared and
+## gnatlink below)
+##
+## With this makefile, you can change any file in the system or add any new
+## file, and everything will be recompiled correctly (only the relevant shared
+## objects will be recompiled, and the main program will be re-linked).
-@cindex @option{^-v^/VERBOSE^} (@command{gnatcheck})
-@item ^-v^/VERBOSE^
-Verbose mode; @command{gnatcheck} generates version information and then
-a trace of sources being processed.
+# The list of computer software component for your project. This might be
+# generated automatically.
+CSC_LIST=aa bb cc
-@cindex @option{^-o ^/OUTPUT^} (@command{gnatcheck})
-@item ^-o ^/OUTPUT=^@var{report_file}
-Set name of report file file to @var{report_file} .
+# Name of the main program (no extension)
+MAIN=main
-@end table
+# If we need to build objects with -fPIC, uncomment the following line
+#NEED_FPIC=-fPIC
-@noindent
-Note that if any of the options @option{^-s1^/COMPILER_STYLE^},
-@option{^-s2^/BY_RULES^} or
-@option{^-s3^/BY_FILES_BY_RULES^} is specified,
-then the @command{gnatcheck} report file will only contain sections
-explicitly denoted by these options.
+# The following variable should give the directory containing libgnat.so
+# You can get this directory through 'gnatls -v'. This is usually the last
+# directory in the Object_Path.
+GLIB=@dots{}
-@node gnatcheck Rule Options
-@section @command{gnatcheck} Rule Options
+# The directories for the libraries
+# (This macro expands the list of CSC to the list of shared libraries, you
+# could simply use the expanded form:
+# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
+LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@}
-@noindent
-The following options control the processing performed by
-@command{gnatcheck}.
+$@{MAIN@}: objects $@{LIB_DIR@}
+ gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared
+ gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@}
-@table @option
-@cindex @option{+ALL} (@command{gnatcheck})
-@item +ALL
-Turn all the rule checks ON.
+objects::
+ # recompile the sources
+ gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@}
-@cindex @option{-ALL} (@command{gnatcheck})
-@item -ALL
-Turn all the rule checks OFF.
+# Note: In a future version of GNAT, the following commands will be simplified
+# by a new tool, gnatmlib
+$@{LIB_DIR@}:
+ mkdir -p $@{dir $@@ @}
+ cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
+ cd $@{dir $@@ @} && cp -f ../*.ali .
-@cindex @option{+R} (@command{gnatcheck})
-@item +R@var{rule_id}@r{[}:@var{param}@r{]}
-Turn on the check for a specified rule with the specified parameter, if any.
-@var{rule_id} must be the identifier of one of the currently implemented rules
-(use @option{^-h^/HELP^} for the list of implemented rules). Rule identifiers
-are not case-sensitive. The @var{param} item must
-be a string representing a valid parameter(s) for the specified rule.
-If it contains any space characters then this string must be enclosed in
-quotation marks.
+# The dependencies for the modules
+# Note that we have to force the expansion of *.o, since in some cases
+# make won't be able to do it itself.
+aa/lib/libaa.so: $@{wildcard aa/*.o@}
+bb/lib/libbb.so: $@{wildcard bb/*.o@}
+cc/lib/libcc.so: $@{wildcard cc/*.o@}
-@cindex @option{-R} (@command{gnatcheck})
-@item -R@var{rule_id}@r{[}:@var{param}@r{]}
-Turn off the check for a specified rule with the specified parameter, if any.
+# Make sure all of the shared libraries are in the path before starting the
+# program
+run::
+ LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@}
-@cindex @option{-from} (@command{gnatcheck})
-@item -from=@var{rule_option_filename}
-Read the rule options from the text file @var{rule_option_filename}, referred as
-``rule file'' below.
+clean::
+ $@{RM@} -rf $@{CSC_LIST:%=%/lib@}
+ $@{RM@} $@{CSC_LIST:%=%/*.ali@}
+ $@{RM@} $@{CSC_LIST:%=%/*.o@}
+ $@{RM@} *.o *.ali $@{MAIN@}
+@end smallexample
-@end table
+@node Automatically Creating a List of Directories
+@section Automatically Creating a List of Directories
@noindent
-The default behavior is that all the rule checks are disabled.
+In most makefiles, you will have to specify a list of directories, and
+store it in a variable. For small projects, it is often easier to
+specify each of them by hand, since you then have full control over what
+is the proper order for these directories, which ones should be
+included.
-A rule file is a text file containing a set of rule options.
-@cindex Rule file (for @code{gnatcheck})
-The file may contain empty lines and Ada-style comments (comment
-lines and end-of-line comments). The rule file has free format; that is,
-you do not have to start a new rule option on a new line.
+However, in larger projects, which might involve hundreds of
+subdirectories, it might be more convenient to generate this list
+automatically.
-A rule file may contain other @option{-from=@var{rule_option_filename}}
-options, each such option being replaced with the content of the
-corresponding rule file during the rule files processing. In case a
-cycle is detected (that is, @file{@var{rule_file_1}} reads rule options
-from @file{@var{rule_file_2}}, and @file{@var{rule_file_2}} reads
-(directly or indirectly) rule options from @file{@var{rule_file_1}}),
-the processing of rule files is interrupted and a part of their content
-is ignored.
+The example below presents two methods. The first one, although less
+general, gives you more control over the list. It involves wildcard
+characters, that are automatically expanded by @command{make}. Its
+shortcoming is that you need to explicitly specify some of the
+organization of your project, such as for instance the directory tree
+depth, whether some directories are found in a separate tree, @enddots{}
+The second method is the most general one. It requires an external
+program, called @command{find}, which is standard on all Unix systems. All
+the directories found under a given root directory will be added to the
+list.
-@node Adding the Results of Compiler Checks to gnatcheck Output
-@section Adding the Results of Compiler Checks to @command{gnatcheck} Output
+@smallexample
+@iftex
+@leftskip=0cm
+@font@heightrm=cmr8
+@heightrm
+@end iftex
+# The examples below are based on the following directory hierarchy:
+# All the directories can contain any number of files
+# ROOT_DIRECTORY -> a -> aa -> aaa
+# -> ab
+# -> ac
+# -> b -> ba -> baa
+# -> bb
+# -> bc
+# This Makefile creates a variable called DIRS, that can be reused any time
+# you need this list (see the other examples in this section)
-@noindent
-The @command{gnatcheck} tool can include in the generated diagnostic messages
-and in
-the report file the results of the checks performed by the compiler. Though
-disabled by default, this effect may be obtained by using @option{+R} with
-the following rule identifiers and parameters:
+# The root of your project's directory hierarchy
+ROOT_DIRECTORY=.
-@table @option
-@item Restrictions
-To record restrictions violations (that are performed by the compiler if the
-pragma @code{Restrictions} or @code{Restriction_Warnings} are given),
-use the rule named
-@code{Restrictions} with the same parameters as pragma
-@code{Restrictions} or @code{Restriction_Warnings}.
+####
+# First method: specify explicitly the list of directories
+# This allows you to specify any subset of all the directories you need.
+####
-@item Style_Checks
-To record compiler style checks(@pxref{Style Checking}), use the rule named
-@code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
-which enables all the standard style checks that corresponds to @option{-gnatyy}
-GNAT style check option, or a string that has exactly the same
-structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
-@code{Style_Checks} (for further information about this pragma,
-@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}). For example,
-@code{+RStyle_Checks:O} rule option activates and adds to @command{gnatcheck}
-output the compiler style check that corresponds to
-@code{-gnatyO} style check option.
+DIRS := a/aa/ a/ab/ b/ba/
-@item Warnings
-To record compiler warnings (@pxref{Warning Message Control}), use the rule
-named @code{Warnings} with a parameter that is a valid
-@i{static_string_expression} argument of GNAT pragma @code{Warnings}
-(for further information about this pragma, @pxref{Pragma Warnings,,,
-gnat_rm, GNAT Reference Manual}). Note, that in case of gnatcheck
-'s' parameter, that corresponds to the GNAT @option{-gnatws} option, disables
-all the specific warnings, but not suppresses the warning mode,
-and 'e' parameter, corresponding to @option{-gnatwe} that means
-"treat warnings as errors", does not have any effect.
+####
+# Second method: use wildcards
+# Note that the argument(s) to wildcard below should end with a '/'.
+# Since wildcards also return file names, we have to filter them out
+# to avoid duplicate directory names.
+# We thus use make's @code{dir} and @code{sort} functions.
+# It sets DIRs to the following value (note that the directories aaa and baa
+# are not given, unless you change the arguments to wildcard).
+# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
+####
-@end table
+DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/
+ $@{ROOT_DIRECTORY@}/*/*/@}@}@}
-To disable a specific restriction check, use @code{-RStyle_Checks} gnatcheck
-option with the corresponding restriction name as a parameter. @code{-R} is
-not available for @code{Style_Checks} and @code{Warnings} options, to disable
-warnings and style checks, use the corresponding warning and style options.
+####
+# Third method: use an external program
+# This command is much faster if run on local disks, avoiding NFS slowdowns.
+# This is the most complete command: it sets DIRs to the following value:
+# DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc
+####
-@node Project-Wide Checks
-@section Project-Wide Checks
-@cindex Project-wide checks (for @command{gnatcheck})
+DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@}
-@noindent
-In order to perform checks on all units of a given project, you can use
-the GNAT driver along with the @option{-P} option:
-@smallexample
- gnat check -Pproj -rules -from=my_rules
@end smallexample
-@noindent
-If the project @code{proj} depends upon other projects, you can perform
-checks on the project closure using the @option{-U} option:
-@smallexample
- gnat check -Pproj -U -rules -from=my_rules
-@end smallexample
+@node Generating the Command Line Switches
+@section Generating the Command Line Switches
@noindent
-Finally, if not all the units are relevant to a particular main
-program in the project closure, you can perform checks for the set
-of units needed to create a given main program (unit closure) using
-the @option{-U} option followed by the name of the main unit:
-@smallexample
- gnat check -Pproj -U main -rules -from=my_rules
-@end smallexample
+Once you have created the list of directories as explained in the
+previous section (@pxref{Automatically Creating a List of Directories}),
+you can easily generate the command line arguments to pass to gnatmake.
+For the sake of completeness, this example assumes that the source path
+is not the same as the object path, and that you have two separate lists
+of directories.
-@node Predefined Rules
-@section Predefined Rules
-@cindex Predefined rules (for @command{gnatcheck})
+@smallexample
+# see "Automatically creating a list of directories" to create
+# these variables
+SOURCE_DIRS=
+OBJECT_DIRS=
-@ignore
-@c (Jan 2007) Since the global rules are still under development and are not
-@c documented, there is no point in explaining the difference between
-@c global and local rules
-@noindent
-A rule in @command{gnatcheck} is either local or global.
-A @emph{local rule} is a rule that applies to a well-defined section
-of a program and that can be checked by analyzing only this section.
-A @emph{global rule} requires analysis of some global properties of the
-whole program (mostly related to the program call graph).
-As of @value{NOW}, the implementation of global rules should be
-considered to be at a preliminary stage. You can use the
-@option{+GLOBAL} option to enable all the global rules, and the
-@option{-GLOBAL} rule option to disable all the global rules.
+GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@}
+GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@}
-All the global rules in the list below are
-so indicated by marking them ``GLOBAL''.
-This +GLOBAL and -GLOBAL options are not
-included in the list of gnatcheck options above, because at the moment they
-are considered as a temporary debug options.
+all:
+ gnatmake $@{GNATMAKE_SWITCHES@} main_unit
+@end smallexample
-@command{gnatcheck} performs rule checks for generic
-instances only for global rules. This limitation may be relaxed in a later
-release.
-@end ignore
+@node Overcoming Command Line Length Limits
+@section Overcoming Command Line Length Limits
@noindent
-The following subsections document the rules implemented in
-@command{gnatcheck}.
-The subsection title is the same as the rule identifier, which may be
-used as a parameter of the @option{+R} or @option{-R} options.
+One problem that might be encountered on big projects is that many
+operating systems limit the length of the command line. It is thus hard to give
+gnatmake the list of source and object directories.
+This example shows how you can set up environment variables, which will
+make @command{gnatmake} behave exactly as if the directories had been
+specified on the command line, but have a much higher length limit (or
+even none on most systems).
-@menu
-* Abstract_Type_Declarations::
-* Anonymous_Arrays::
-* Anonymous_Subtypes::
-* Blocks::
-* Boolean_Relational_Operators::
-@ignore
-* Ceiling_Violations::
-@end ignore
-* Controlled_Type_Declarations::
-* Declarations_In_Blocks::
-* Default_Parameters::
-* Discriminated_Records::
-* Enumeration_Ranges_In_CASE_Statements::
-* Exceptions_As_Control_Flow::
-* Exits_From_Conditional_Loops::
-* EXIT_Statements_With_No_Loop_Name::
-* Expanded_Loop_Exit_Names::
-* Explicit_Full_Discrete_Ranges::
-* Float_Equality_Checks::
-* Forbidden_Pragmas::
-* Function_Style_Procedures::
-* Generics_In_Subprograms::
-* GOTO_Statements::
-* Implicit_IN_Mode_Parameters::
-* Implicit_SMALL_For_Fixed_Point_Types::
-* Improperly_Located_Instantiations::
-* Improper_Returns::
-* Library_Level_Subprograms::
-* Local_Packages::
-@ignore
-* Improperly_Called_Protected_Entries::
-@end ignore
-* Metrics::
-* Misnamed_Identifiers::
-* Multiple_Entries_In_Protected_Definitions::
-* Name_Clashes::
-* Non_Qualified_Aggregates::
-* Non_Short_Circuit_Operators::
-* Non_SPARK_Attributes::
-* Non_Tagged_Derived_Types::
-* Non_Visible_Exceptions::
-* Numeric_Literals::
-* OTHERS_In_Aggregates::
-* OTHERS_In_CASE_Statements::
-* OTHERS_In_Exception_Handlers::
-* Outer_Loop_Exits::
-* Overloaded_Operators::
-* Overly_Nested_Control_Structures::
-* Parameters_Out_Of_Order::
-* Positional_Actuals_For_Defaulted_Generic_Parameters::
-* Positional_Actuals_For_Defaulted_Parameters::
-* Positional_Components::
-* Positional_Generic_Parameters::
-* Positional_Parameters::
-* Predefined_Numeric_Types::
-* Raising_External_Exceptions::
-* Raising_Predefined_Exceptions::
-* Separate_Numeric_Error_Handlers::
-@ignore
-* Recursion::
-* Side_Effect_Functions::
-@end ignore
-* Slices::
-* Unassigned_OUT_Parameters::
-* Uncommented_BEGIN_In_Package_Bodies::
-* Unconditional_Exits::
-* Unconstrained_Array_Returns::
-* Universal_Ranges::
-* Unnamed_Blocks_And_Loops::
-@ignore
-* Unused_Subprograms::
-@end ignore
-* USE_PACKAGE_Clauses::
-* Volatile_Objects_Without_Address_Clauses::
-@end menu
+It assumes that you have created a list of directories in your Makefile,
+using one of the methods presented in
+@ref{Automatically Creating a List of Directories}.
+For the sake of completeness, we assume that the object
+path (where the ALI files are found) is different from the sources patch.
+Note a small trick in the Makefile below: for efficiency reasons, we
+create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
+expanded immediately by @code{make}. This way we overcome the standard
+make behavior which is to expand the variables only when they are
+actually used.
-@node Abstract_Type_Declarations
-@subsection @code{Abstract_Type_Declarations}
-@cindex @code{Abstract_Type_Declarations} rule (for @command{gnatcheck})
+On Windows, if you are using the standard Windows command shell, you must
+replace colons with semicolons in the assignments to these variables.
-@noindent
-Flag all declarations of abstract types. For an abstract private
-type, both the private and full type declarations are flagged.
+@smallexample
+@iftex
+@leftskip=0cm
+@font@heightrm=cmr8
+@heightrm
+@end iftex
+# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH.
+# This is the same thing as putting the -I arguments on the command line.
+# (the equivalent of using -aI on the command line would be to define
+# only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH).
+# You can of course have different values for these variables.
+#
+# Note also that we need to keep the previous values of these variables, since
+# they might have been set before running 'make' to specify where the GNAT
+# library is installed.
+
+# see "Automatically creating a list of directories" to create these
+# variables
+SOURCE_DIRS=
+OBJECT_DIRS=
-This rule has no parameters.
+empty:=
+space:=$@{empty@} $@{empty@}
+SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@}
+OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@}
+ADA_INCLUDE_PATH += $@{SOURCE_LIST@}
+ADA_OBJECT_PATH += $@{OBJECT_LIST@}
+export ADA_INCLUDE_PATH
+export ADA_OBJECT_PATH
+all:
+ gnatmake main_unit
+@end smallexample
+@end ifclear
-@node Anonymous_Arrays
-@subsection @code{Anonymous_Arrays}
-@cindex @code{Anonymous_Arrays} rule (for @command{gnatcheck})
+@node Memory Management Issues
+@chapter Memory Management Issues
@noindent
-Flag all anonymous array type definitions (by Ada semantics these can only
-occur in object declarations).
+This chapter describes some useful memory pools provided in the GNAT library
+and in particular the GNAT Debug Pool facility, which can be used to detect
+incorrect uses of access values (including ``dangling references'').
+@ifclear vms
+It also describes the @command{gnatmem} tool, which can be used to track down
+``memory leaks''.
+@end ifclear
-This rule has no parameters.
+@menu
+* Some Useful Memory Pools::
+* The GNAT Debug Pool Facility::
+@ifclear vms
+* The gnatmem Tool::
+@end ifclear
+@end menu
-@node Anonymous_Subtypes
-@subsection @code{Anonymous_Subtypes}
-@cindex @code{Anonymous_Subtypes} rule (for @command{gnatcheck})
+@node Some Useful Memory Pools
+@section Some Useful Memory Pools
+@findex Memory Pool
+@cindex storage, pool
@noindent
-Flag all uses of anonymous subtypes. A use of an anonymous subtype is
-any instance of a subtype indication with a constraint, other than one
-that occurs immediately within a subtype declaration. Any use of a range
-other than as a constraint used immediately within a subtype declaration
-is considered as an anonymous subtype.
+The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
+storage pool. Allocations use the standard system call @code{malloc} while
+deallocations use the standard system call @code{free}. No reclamation is
+performed when the pool goes out of scope. For performance reasons, the
+standard default Ada allocators/deallocators do not use any explicit storage
+pools but if they did, they could use this storage pool without any change in
+behavior. That is why this storage pool is used when the user
+manages to make the default implicit allocator explicit as in this example:
+@smallexample @c ada
+ type T1 is access Something;
+ -- no Storage pool is defined for T2
+ type T2 is access Something_Else;
+ for T2'Storage_Pool use T1'Storage_Pool;
+ -- the above is equivalent to
+ for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
+@end smallexample
-An effect of this rule is that @code{for} loops such as the following are
-flagged (since @code{1..N} is formally a ``range''):
+@noindent
+The @code{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage
+pool. The allocation strategy is similar to @code{Pool_Local}'s
+except that the all
+storage allocated with this pool is reclaimed when the pool object goes out of
+scope. This pool provides a explicit mechanism similar to the implicit one
+provided by several Ada 83 compilers for allocations performed through a local
+access type and whose purpose was to reclaim memory when exiting the
+scope of a given local access. As an example, the following program does not
+leak memory even though it does not perform explicit deallocation:
@smallexample @c ada
-for I in 1 .. N loop
- @dots{}
-end loop;
+with System.Pool_Local;
+procedure Pooloc1 is
+ procedure Internal is
+ type A is access Integer;
+ X : System.Pool_Local.Unbounded_Reclaim_Pool;
+ for A'Storage_Pool use X;
+ v : A;
+ begin
+ for I in 1 .. 50 loop
+ v := new Integer;
+ end loop;
+ end Internal;
+begin
+ for I in 1 .. 100 loop
+ Internal;
+ end loop;
+end Pooloc1;
@end smallexample
@noindent
-Declaring an explicit subtype solves the problem:
+The @code{System.Pool_Size} package implements the Stack_Bounded_Pool used when
+@code{Storage_Size} is specified for an access type.
+The whole storage for the pool is
+allocated at once, usually on the stack at the point where the access type is
+elaborated. It is automatically reclaimed when exiting the scope where the
+access type is defined. This package is not intended to be used directly by the
+user and it is implicitly used for each such declaration:
@smallexample @c ada
-subtype S is Integer range 1..N;
-@dots{}
-for I in S loop
- @dots{}
-end loop;
+ type T1 is access Something;
+ for T1'Storage_Size use 10_000;
+@end smallexample
+
+@node The GNAT Debug Pool Facility
+@section The GNAT Debug Pool Facility
+@findex Debug Pool
+@cindex storage, pool, memory corruption
+
+@noindent
+The use of unchecked deallocation and unchecked conversion can easily
+lead to incorrect memory references. The problems generated by such
+references are usually difficult to tackle because the symptoms can be
+very remote from the origin of the problem. In such cases, it is
+very helpful to detect the problem as early as possible. This is the
+purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}.
+
+In order to use the GNAT specific debugging pool, the user must
+associate a debug pool object with each of the access types that may be
+related to suspected memory problems. See Ada Reference Manual 13.11.
+@smallexample @c ada
+type Ptr is access Some_Type;
+Pool : GNAT.Debug_Pools.Debug_Pool;
+for Ptr'Storage_Pool use Pool;
@end smallexample
@noindent
-This rule has no parameters.
+@code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
+pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools,
+allow the user to redefine allocation and deallocation strategies. They
+also provide a checkpoint for each dereference, through the use of
+the primitive operation @code{Dereference} which is implicitly called at
+each dereference of an access value.
-@node Blocks
-@subsection @code{Blocks}
-@cindex @code{Blocks} rule (for @command{gnatcheck})
+Once an access type has been associated with a debug pool, operations on
+values of the type may raise four distinct exceptions,
+which correspond to four potential kinds of memory corruption:
+@itemize @bullet
+@item
+@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
+@item
+@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
+@item
+@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
+@item
+@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage }
+@end itemize
@noindent
-Flag each block statement.
+For types associated with a Debug_Pool, dynamic allocation is performed using
+the standard GNAT allocation routine. References to all allocated chunks of
+memory are kept in an internal dictionary. Several deallocation strategies are
+provided, whereupon the user can choose to release the memory to the system,
+keep it allocated for further invalid access checks, or fill it with an easily
+recognizable pattern for debug sessions. The memory pattern is the old IBM
+hexadecimal convention: @code{16#DEADBEEF#}.
+
+See the documentation in the file g-debpoo.ads for more information on the
+various strategies.
+
+Upon each dereference, a check is made that the access value denotes a
+properly allocated memory location. Here is a complete example of use of
+@code{Debug_Pools}, that includes typical instances of memory corruption:
+@smallexample @c ada
+@iftex
+@leftskip=0cm
+@end iftex
+with Gnat.Io; use Gnat.Io;
+with Unchecked_Deallocation;
+with Unchecked_Conversion;
+with GNAT.Debug_Pools;
+with System.Storage_Elements;
+with Ada.Exceptions; use Ada.Exceptions;
+procedure Debug_Pool_Test is
+
+ type T is access Integer;
+ type U is access all T;
+
+ P : GNAT.Debug_Pools.Debug_Pool;
+ for T'Storage_Pool use P;
+
+ procedure Free is new Unchecked_Deallocation (Integer, T);
+ function UC is new Unchecked_Conversion (U, T);
+ A, B : aliased T;
-This rule has no parameters.
+ procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
-@node Boolean_Relational_Operators
-@subsection @code{Boolean_Relational_Operators}
-@cindex @code{Boolean_Relational_Operators} rule (for @command{gnatcheck})
+begin
+ Info (P);
+ A := new Integer;
+ B := new Integer;
+ B := A;
+ Info (P);
+ Free (A);
+ begin
+ Put_Line (Integer'Image(B.all));
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ begin
+ Free (B);
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ B := UC(A'Access);
+ begin
+ Put_Line (Integer'Image(B.all));
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ begin
+ Free (B);
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ Info (P);
+end Debug_Pool_Test;
+@end smallexample
@noindent
-Flag each call to a predefined relational operator (``<'', ``>'', ``<='',
-``>='', ``='' and ``/='') for the predefined Boolean type.
-(This rule is useful in enforcing the SPARK language restrictions.)
+The debug pool mechanism provides the following precise diagnostics on the
+execution of this erroneous program:
+@smallexample
+Debug Pool info:
+ Total allocated bytes : 0
+ Total deallocated bytes : 0
+ Current Water Mark: 0
+ High Water Mark: 0
-Calls to predefined relational operators of any type derived from
-@code{Standard.Boolean} are not detected. Calls to user-defined functions
-with these designators, and uses of operators that are renamings
-of the predefined relational operators for @code{Standard.Boolean},
-are likewise not detected.
+Debug Pool info:
+ Total allocated bytes : 8
+ Total deallocated bytes : 0
+ Current Water Mark: 8
+ High Water Mark: 8
-This rule has no parameters.
+raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE
+Debug Pool info:
+ Total allocated bytes : 8
+ Total deallocated bytes : 4
+ Current Water Mark: 4
+ High Water Mark: 8
+@end smallexample
-@ignore
-@node Ceiling_Violations
-@subsection @code{Ceiling_Violations} (under construction, GLOBAL)
-@cindex @code{Ceiling_Violations} rule (for @command{gnatcheck})
+@ifclear vms
+@node The gnatmem Tool
+@section The @command{gnatmem} Tool
+@findex gnatmem
@noindent
-Flag invocations of a protected operation by a task whose priority exceeds
-the protected object's ceiling.
-
-As of @value{NOW}, this rule has the following limitations:
-
+The @code{gnatmem} utility monitors dynamic allocation and
+deallocation activity in a program, and displays information about
+incorrect deallocations and possible sources of memory leaks.
+It is designed to work in association with a static runtime library
+only and in this context provides three types of information:
@itemize @bullet
-
@item
- We consider only pragmas Priority and Interrupt_Priority as means to define
- a task/protected operation priority. We do not consider the effect of using
- Ada.Dynamic_Priorities.Set_Priority procedure;
+General information concerning memory management, such as the total
+number of allocations and deallocations, the amount of allocated
+memory and the high water mark, i.e.@: the largest amount of allocated
+memory in the course of program execution.
@item
- We consider only base task priorities, and no priority inheritance. That is,
- we do not make a difference between calls issued during task activation and
- execution of the sequence of statements from task body;
+Backtraces for all incorrect deallocations, that is to say deallocations
+which do not correspond to a valid allocation.
@item
- Any situation when the priority of protected operation caller is set by a
- dynamic expression (that is, the corresponding Priority or
- Interrupt_Priority pragma has a non-static expression as an argument) we
- treat as a priority inconsistency (and, therefore, detect this situation).
+Information on each allocation that is potentially the origin of a memory
+leak.
@end itemize
-@noindent
-At the moment the notion of the main subprogram is not implemented in
-gnatcheck, so any pragma Priority in a library level subprogram body (in case
-if this subprogram can be a main subprogram of a partition) changes the
-priority of an environment task. So if we have more then one such pragma in
-the set of processed sources, the pragma that is processed last, defines the
-priority of an environment task.
-
-This rule has no parameters.
-@end ignore
-
-@node Controlled_Type_Declarations
-@subsection @code{Controlled_Type_Declarations}
-@cindex @code{Controlled_Type_Declarations} rule (for @command{gnatcheck})
-
-@noindent
-Flag all declarations of controlled types. A declaration of a private type
-is flagged if its full declaration declares a controlled type. A declaration
-of a derived type is flagged if its ancestor type is controlled. Subtype
-declarations are not checked. A declaration of a type that itself is not a
-descendant of a type declared in @code{Ada.Finalization} but has a controlled
-component is not checked.
-
-This rule has no parameters.
-
-
-
-@node Declarations_In_Blocks
-@subsection @code{Declarations_In_Blocks}
-@cindex @code{Declarations_In_Blocks} rule (for @command{gnatcheck})
-
-@noindent
-Flag all block statements containing local declarations. A @code{declare}
-block with an empty @i{declarative_part} or with a @i{declarative part}
-containing only pragmas and/or @code{use} clauses is not flagged.
-
-This rule has no parameters.
-
+@menu
+* Running gnatmem::
+* Switches for gnatmem::
+* Example of gnatmem Usage::
+@end menu
-@node Default_Parameters
-@subsection @code{Default_Parameters}
-@cindex @code{Default_Parameters} rule (for @command{gnatcheck})
+@node Running gnatmem
+@subsection Running @code{gnatmem}
@noindent
-Flag all default expressions for subprogram parameters. Parameter
-declarations of formal and generic subprograms are also checked.
-
-This rule has no parameters.
-
-
-@node Discriminated_Records
-@subsection @code{Discriminated_Records}
-@cindex @code{Discriminated_Records} rule (for @command{gnatcheck})
+@code{gnatmem} makes use of the output created by the special version of
+allocation and deallocation routines that record call information. This
+allows to obtain accurate dynamic memory usage history at a minimal cost to
+the execution speed. Note however, that @code{gnatmem} is not supported on
+all platforms (currently, it is supported on AIX, HP-UX, GNU/Linux,
+Solaris and Windows NT/2000/XP (x86).
@noindent
-Flag all declarations of record types with discriminants. Only the
-declarations of record and record extension types are checked. Incomplete,
-formal, private, derived and private extension type declarations are not
-checked. Task and protected type declarations also are not checked.
-
-This rule has no parameters.
-
+The @code{gnatmem} command has the form
-@node Enumeration_Ranges_In_CASE_Statements
-@subsection @code{Enumeration_Ranges_In_CASE_Statements}
-@cindex @code{Enumeration_Ranges_In_CASE_Statements} (for @command{gnatcheck})
+@smallexample
+@c $ gnatmem @ovar{switches} user_program
+@c Expanding @ovar macro inline (explanation in macro def comments)
+ $ gnatmem @r{[}@var{switches}@r{]} @var{user_program}
+@end smallexample
@noindent
-Flag each use of a range of enumeration literals as a choice in a
-@code{case} statement.
-All forms for specifying a range (explicit ranges
-such as @code{A .. B}, subtype marks and @code{'Range} attributes) are flagged.
-An enumeration range is
-flagged even if contains exactly one enumeration value or no values at all. A
-type derived from an enumeration type is considered as an enumeration type.
-
-This rule helps prevent maintenance problems arising from adding an
-enumeration value to a type and having it implicitly handled by an existing
-@code{case} statement with an enumeration range that includes the new literal.
-
-This rule has no parameters.
-
+The program must have been linked with the instrumented version of the
+allocation and deallocation routines. This is done by linking with the
+@file{libgmem.a} library. For correct symbolic backtrace information,
+the user program should be compiled with debugging options
+(see @ref{Switches for gcc}). For example to build @file{my_program}:
-@node Exceptions_As_Control_Flow
-@subsection @code{Exceptions_As_Control_Flow}
-@cindex @code{Exceptions_As_Control_Flow} (for @command{gnatcheck})
+@smallexample
+$ gnatmake -g my_program -largs -lgmem
+@end smallexample
@noindent
-Flag each place where an exception is explicitly raised and handled in the
-same subprogram body. A @code{raise} statement in an exception handler,
-package body, task body or entry body is not flagged.
-
-The rule has no parameters.
-
-@node Exits_From_Conditional_Loops
-@subsection @code{Exits_From_Conditional_Loops}
-@cindex @code{Exits_From_Conditional_Loops} (for @command{gnatcheck})
+As library @file{libgmem.a} contains an alternate body for package
+@code{System.Memory}, @file{s-memory.adb} should not be compiled and linked
+when an executable is linked with library @file{libgmem.a}. It is then not
+recommended to use @command{gnatmake} with switch @option{^-a^/ALL_FILES^}.
@noindent
-Flag any exit statement if it transfers the control out of a @code{for} loop
-or a @code{while} loop. This includes cases when the @code{exit} statement
-applies to a @code{FOR} or @code{while} loop, and cases when it is enclosed
-in some @code{for} or @code{while} loop, but transfers the control from some
-outer (inconditional) @code{loop} statement.
+When @file{my_program} is executed, the file @file{gmem.out} is produced.
+This file contains information about all allocations and deallocations
+performed by the program. It is produced by the instrumented allocations and
+deallocations routines and will be used by @code{gnatmem}.
-The rule has no parameters.
+In order to produce symbolic backtrace information for allocations and
+deallocations performed by the GNAT run-time library, you need to use a
+version of that library that has been compiled with the @option{-g} switch
+(see @ref{Rebuilding the GNAT Run-Time Library}).
+Gnatmem must be supplied with the @file{gmem.out} file and the executable to
+examine. If the location of @file{gmem.out} file was not explicitly supplied by
+@option{-i} switch, gnatmem will assume that this file can be found in the
+current directory. For example, after you have executed @file{my_program},
+@file{gmem.out} can be analyzed by @code{gnatmem} using the command:
-@node EXIT_Statements_With_No_Loop_Name
-@subsection @code{EXIT_Statements_With_No_Loop_Name}
-@cindex @code{EXIT_Statements_With_No_Loop_Name} (for @command{gnatcheck})
+@smallexample
+$ gnatmem my_program
+@end smallexample
@noindent
-Flag each @code{exit} statement that does not specify the name of the loop
-being exited.
-
-The rule has no parameters.
-
+This will produce the output with the following format:
-@node Expanded_Loop_Exit_Names
-@subsection @code{Expanded_Loop_Exit_Names}
-@cindex @code{Expanded_Loop_Exit_Names} rule (for @command{gnatcheck})
+*************** debut cc
+@smallexample
+$ gnatmem my_program
-@noindent
-Flag all expanded loop names in @code{exit} statements.
+Global information
+------------------
+ Total number of allocations : 45
+ Total number of deallocations : 6
+ Final Water Mark (non freed mem) : 11.29 Kilobytes
+ High Water Mark : 11.40 Kilobytes
-This rule has no parameters.
+.
+.
+.
+Allocation Root # 2
+-------------------
+ Number of non freed allocations : 11
+ Final Water Mark (non freed mem) : 1.16 Kilobytes
+ High Water Mark : 1.27 Kilobytes
+ Backtrace :
+ my_program.adb:23 my_program.alloc
+.
+.
+.
+@end smallexample
-@node Explicit_Full_Discrete_Ranges
-@subsection @code{Explicit_Full_Discrete_Ranges}
-@cindex @code{Explicit_Full_Discrete_Ranges} rule (for @command{gnatcheck})
+The first block of output gives general information. In this case, the
+Ada construct ``@code{@b{new}}'' was executed 45 times, and only 6 calls to an
+Unchecked_Deallocation routine occurred.
@noindent
-Flag each discrete range that has the form @code{A'First .. A'Last}.
-
-This rule has no parameters.
+Subsequent paragraphs display information on all allocation roots.
+An allocation root is a specific point in the execution of the program
+that generates some dynamic allocation, such as a ``@code{@b{new}}''
+construct. This root is represented by an execution backtrace (or subprogram
+call stack). By default the backtrace depth for allocations roots is 1, so
+that a root corresponds exactly to a source location. The backtrace can
+be made deeper, to make the root more specific.
-@node Float_Equality_Checks
-@subsection @code{Float_Equality_Checks}
-@cindex @code{Float_Equality_Checks} rule (for @command{gnatcheck})
+@node Switches for gnatmem
+@subsection Switches for @code{gnatmem}
@noindent
-Flag all calls to the predefined equality operations for floating-point types.
-Both ``@code{=}'' and ``@code{/=}'' operations are checked.
-User-defined equality operations are not flagged, nor are ``@code{=}''
-and ``@code{/=}'' operations for fixed-point types.
+@code{gnatmem} recognizes the following switches:
-This rule has no parameters.
+@table @option
+@item -q
+@cindex @option{-q} (@code{gnatmem})
+Quiet. Gives the minimum output needed to identify the origin of the
+memory leaks. Omits statistical information.
-@node Forbidden_Pragmas
-@subsection @code{Forbidden_Pragmas}
-@cindex @code{Forbidden_Pragmas} rule (for @command{gnatcheck})
+@item @var{N}
+@cindex @var{N} (@code{gnatmem})
+N is an integer literal (usually between 1 and 10) which controls the
+depth of the backtraces defining allocation root. The default value for
+N is 1. The deeper the backtrace, the more precise the localization of
+the root. Note that the total number of roots can depend on this
+parameter. This parameter must be specified @emph{before} the name of the
+executable to be analyzed, to avoid ambiguity.
-@noindent
-Flag each use of the specified pragmas. The pragmas to be detected
-are named in the rule's parameters.
+@item -b n
+@cindex @option{-b} (@code{gnatmem})
+This switch has the same effect as just depth parameter.
-This rule has the following parameters:
+@item -i @var{file}
+@cindex @option{-i} (@code{gnatmem})
+Do the @code{gnatmem} processing starting from @file{file}, rather than
+@file{gmem.out} in the current directory.
-@itemize @bullet
-@item For the @option{+R} option
+@item -m n
+@cindex @option{-m} (@code{gnatmem})
+This switch causes @code{gnatmem} to mask the allocation roots that have less
+than n leaks. The default value is 1. Specifying the value of 0 will allow to
+examine even the roots that didn't result in leaks.
-@table @asis
-@item @emph{Pragma_Name}
-Adds the specified pragma to the set of pragmas to be
-checked and sets the checks for all the specified pragmas
-ON. @emph{Pragma_Name} is treated as a name of a pragma. If it
-does not correspond to any pragma name defined in the Ada
-standard or to the name of a GNAT-specific pragma defined
-in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
-Manual}, it is treated as the name of unknown pragma.
-
-@item @code{GNAT}
-All the GNAT-specific pragmas are detected; this sets
-the checks for all the specified pragmas ON.
-
-@item @code{ALL}
-All pragmas are detected; this sets the rule ON.
-@end table
+@item -s order
+@cindex @option{-s} (@code{gnatmem})
+This switch causes @code{gnatmem} to sort the allocation roots according to the
+specified order of sort criteria, each identified by a single letter. The
+currently supported criteria are @code{n, h, w} standing respectively for
+number of unfreed allocations, high watermark, and final watermark
+corresponding to a specific root. The default order is @code{nwh}.
-@item For the @option{-R} option
-@table @asis
-@item @emph{Pragma_Name}
-Removes the specified pragma from the set of pragmas to be
-checked without affecting checks for
-other pragmas. @emph{Pragma_Name} is treated as a name
-of a pragma. If it does not correspond to any pragma
-defined in the Ada standard or to any name defined in
-@ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
-this option is treated as turning OFF detection of all unknown pragmas.
-
-@item GNAT
-Turn OFF detection of all GNAT-specific pragmas
-
-@item ALL
-Clear the list of the pragmas to be detected and
-turn the rule OFF.
@end table
-@end itemize
-
-@noindent
-Parameters are not case sensitive. If @emph{Pragma_Name} does not have
-the syntax of an Ada identifier and therefore can not be considered
-as a pragma name, a diagnostic message is generated and the corresponding
-parameter is ignored.
-
-When more then one parameter is given in the same rule option, the parameters
-must be separated by a comma.
-
-If more then one option for this rule is specified for the @command{gnatcheck}
-call, a new option overrides the previous one(s).
-
-The @option{+R} option with no parameters turns the rule ON with the set of
-pragmas to be detected defined by the previous rule options.
-(By default this set is empty, so if the only option specified for the rule is
-@option{+RForbidden_Pragmas} (with
-no parameter), then the rule is enabled, but it does not detect anything).
-The @option{-R} option with no parameter turns the rule OFF, but it does not
-affect the set of pragmas to be detected.
-
-
-
-
-@node Function_Style_Procedures
-@subsection @code{Function_Style_Procedures}
-@cindex @code{Function_Style_Procedures} rule (for @command{gnatcheck})
-
-@noindent
-Flag each procedure that can be rewritten as a function. A procedure can be
-converted into a function if it has exactly one parameter of mode @code{out}
-and no parameters of mode @code{in out}. Procedure declarations,
-formal procedure declarations, and generic procedure declarations are always
-checked. Procedure
-bodies and body stubs are flagged only if they do not have corresponding
-separate declarations. Procedure renamings and procedure instantiations are
-not flagged.
-
-If a procedure can be rewritten as a function, but its @code{out} parameter is
-of a limited type, it is not flagged.
-Protected procedures are not flagged. Null procedures also are not flagged.
-
-This rule has no parameters.
-
-
-@node Generics_In_Subprograms
-@subsection @code{Generics_In_Subprograms}
-@cindex @code{Generics_In_Subprograms} rule (for @command{gnatcheck})
+@node Example of gnatmem Usage
+@subsection Example of @code{gnatmem} Usage
@noindent
-Flag each declaration of a generic unit in a subprogram. Generic
-declarations in the bodies of generic subprograms are also flagged.
-A generic unit nested in another generic unit is not flagged.
-If a generic unit is
-declared in a local package that is declared in a subprogram body, the
-generic unit is flagged.
-
-This rule has no parameters.
-
+The following example shows the use of @code{gnatmem}
+on a simple memory-leaking program.
+Suppose that we have the following Ada program:
-@node GOTO_Statements
-@subsection @code{GOTO_Statements}
-@cindex @code{GOTO_Statements} rule (for @command{gnatcheck})
+@smallexample @c ada
+@group
+@cartouche
+with Unchecked_Deallocation;
+procedure Test_Gm is
-@noindent
-Flag each occurrence of a @code{goto} statement.
+ type T is array (1..1000) of Integer;
+ type Ptr is access T;
+ procedure Free is new Unchecked_Deallocation (T, Ptr);
+ A : Ptr;
-This rule has no parameters.
+ procedure My_Alloc is
+ begin
+ A := new T;
+ end My_Alloc;
+ procedure My_DeAlloc is
+ B : Ptr := A;
+ begin
+ Free (B);
+ end My_DeAlloc;
-@node Implicit_IN_Mode_Parameters
-@subsection @code{Implicit_IN_Mode_Parameters}
-@cindex @code{Implicit_IN_Mode_Parameters} rule (for @command{gnatcheck})
+begin
+ My_Alloc;
+ for I in 1 .. 5 loop
+ for J in I .. 5 loop
+ My_Alloc;
+ end loop;
+ My_Dealloc;
+ end loop;
+end;
+@end cartouche
+@end group
+@end smallexample
@noindent
-Flag each occurrence of a formal parameter with an implicit @code{in} mode.
-Note that @code{access} parameters, although they technically behave
-like @code{in} parameters, are not flagged.
-
-This rule has no parameters.
-
+The program needs to be compiled with debugging option and linked with
+@code{gmem} library:
-@node Implicit_SMALL_For_Fixed_Point_Types
-@subsection @code{Implicit_SMALL_For_Fixed_Point_Types}
-@cindex @code{Implicit_SMALL_For_Fixed_Point_Types} rule (for @command{gnatcheck})
+@smallexample
+$ gnatmake -g test_gm -largs -lgmem
+@end smallexample
@noindent
-Flag each fixed point type declaration that lacks an explicit
-representation clause to define its @code{'Small} value.
-Since @code{'Small} can be defined only for ordinary fixed point types,
-decimal fixed point type declarations are not checked.
-
-This rule has no parameters.
-
+Then we execute the program as usual:
-@node Improperly_Located_Instantiations
-@subsection @code{Improperly_Located_Instantiations}
-@cindex @code{Improperly_Located_Instantiations} rule (for @command{gnatcheck})
+@smallexample
+$ test_gm
+@end smallexample
@noindent
-Flag all generic instantiations in library-level package specs
-(including library generic packages) and in all subprogram bodies.
+Then @code{gnatmem} is invoked simply with
+@smallexample
+$ gnatmem test_gm
+@end smallexample
-Instantiations in task and entry bodies are not flagged. Instantiations in the
-bodies of protected subprograms are flagged.
+@noindent
+which produces the following output (result may vary on different platforms):
-This rule has no parameters.
+@smallexample
+Global information
+------------------
+ Total number of allocations : 18
+ Total number of deallocations : 5
+ Final Water Mark (non freed mem) : 53.00 Kilobytes
+ High Water Mark : 56.90 Kilobytes
+Allocation Root # 1
+-------------------
+ Number of non freed allocations : 11
+ Final Water Mark (non freed mem) : 42.97 Kilobytes
+ High Water Mark : 46.88 Kilobytes
+ Backtrace :
+ test_gm.adb:11 test_gm.my_alloc
+Allocation Root # 2
+-------------------
+ Number of non freed allocations : 1
+ Final Water Mark (non freed mem) : 10.02 Kilobytes
+ High Water Mark : 10.02 Kilobytes
+ Backtrace :
+ s-secsta.adb:81 system.secondary_stack.ss_init
-@node Improper_Returns
-@subsection @code{Improper_Returns}
-@cindex @code{Improper_Returns} rule (for @command{gnatcheck})
+Allocation Root # 3
+-------------------
+ Number of non freed allocations : 1
+ Final Water Mark (non freed mem) : 12 Bytes
+ High Water Mark : 12 Bytes
+ Backtrace :
+ s-secsta.adb:181 system.secondary_stack.ss_init
+@end smallexample
@noindent
-Flag each explicit @code{return} statement in procedures, and
-multiple @code{return} statements in functions.
-Diagnostic messages are generated for all @code{return} statements
-in a procedure (thus each procedure must be written so that it
-returns implicitly at the end of its statement part),
-and for all @code{return} statements in a function after the first one.
-This rule supports the stylistic convention that each subprogram
-should have no more than one point of normal return.
+Note that the GNAT run time contains itself a certain number of
+allocations that have no corresponding deallocation,
+as shown here for root #2 and root
+#3. This is a normal behavior when the number of non-freed allocations
+is one, it allocates dynamic data structures that the run time needs for
+the complete lifetime of the program. Note also that there is only one
+allocation root in the user program with a single line back trace:
+test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the
+program shows that 'My_Alloc' is called at 2 different points in the
+source (line 21 and line 24). If those two allocation roots need to be
+distinguished, the backtrace depth parameter can be used:
-This rule has no parameters.
+@smallexample
+$ gnatmem 3 test_gm
+@end smallexample
+@noindent
+which will give the following output:
-@node Library_Level_Subprograms
-@subsection @code{Library_Level_Subprograms}
-@cindex @code{Library_Level_Subprograms} rule (for @command{gnatcheck})
+@smallexample
+Global information
+------------------
+ Total number of allocations : 18
+ Total number of deallocations : 5
+ Final Water Mark (non freed mem) : 53.00 Kilobytes
+ High Water Mark : 56.90 Kilobytes
-@noindent
-Flag all library-level subprograms (including generic subprogram instantiations).
+Allocation Root # 1
+-------------------
+ Number of non freed allocations : 10
+ Final Water Mark (non freed mem) : 39.06 Kilobytes
+ High Water Mark : 42.97 Kilobytes
+ Backtrace :
+ test_gm.adb:11 test_gm.my_alloc
+ test_gm.adb:24 test_gm
+ b_test_gm.c:52 main
-This rule has no parameters.
+Allocation Root # 2
+-------------------
+ Number of non freed allocations : 1
+ Final Water Mark (non freed mem) : 10.02 Kilobytes
+ High Water Mark : 10.02 Kilobytes
+ Backtrace :
+ s-secsta.adb:81 system.secondary_stack.ss_init
+ s-secsta.adb:283 <system__secondary_stack___elabb>
+ b_test_gm.c:33 adainit
+Allocation Root # 3
+-------------------
+ Number of non freed allocations : 1
+ Final Water Mark (non freed mem) : 3.91 Kilobytes
+ High Water Mark : 3.91 Kilobytes
+ Backtrace :
+ test_gm.adb:11 test_gm.my_alloc
+ test_gm.adb:21 test_gm
+ b_test_gm.c:52 main
-@node Local_Packages
-@subsection @code{Local_Packages}
-@cindex @code{Local_Packages} rule (for @command{gnatcheck})
+Allocation Root # 4
+-------------------
+ Number of non freed allocations : 1
+ Final Water Mark (non freed mem) : 12 Bytes
+ High Water Mark : 12 Bytes
+ Backtrace :
+ s-secsta.adb:181 system.secondary_stack.ss_init
+ s-secsta.adb:283 <system__secondary_stack___elabb>
+ b_test_gm.c:33 adainit
+@end smallexample
@noindent
-Flag all local packages declared in package and generic package
-specs.
-Local packages in bodies are not flagged.
+The allocation root #1 of the first example has been split in 2 roots #1
+and #3 thanks to the more precise associated backtrace.
-This rule has no parameters.
+@end ifclear
-@ignore
-@node Improperly_Called_Protected_Entries
-@subsection @code{Improperly_Called_Protected_Entries} (under construction, GLOBAL)
-@cindex @code{Improperly_Called_Protected_Entries} rule (for @command{gnatcheck})
+@node Stack Related Facilities
+@chapter Stack Related Facilities
@noindent
-Flag each protected entry that can be called from more than one task.
+This chapter describes some useful tools associated with stack
+checking and analysis. In
+particular, it deals with dynamic and static stack usage measurements.
-This rule has no parameters.
-@end ignore
+@menu
+* Stack Overflow Checking::
+* Static Stack Usage Analysis::
+* Dynamic Stack Usage Analysis::
+@end menu
-@node Metrics
-@subsection @code{Metrics}
-@cindex @code{Metrics} rule (for @command{gnatcheck})
-
-@noindent
-There is a set of checks based on computing a metric value and comparing the
-result with the specified upper (or lower, depending on a specific metric)
-value specified for a given metric. A construct is flagged if a given metric
-is applicable (can be computed) for it and the computed value is greater
-then (lover then) the specified upper (lower) bound.
-
-The name of any metric-based rule consists of the prefix @code{Metrics_}
-followed by the name of the corresponding metric (see the table below).
-For @option{+R} option, each metric-based rule has a numeric parameter
-specifying the bound (integer or real, depending on a metric), @option{-R}
-option for metric rules does not have a parameter.
-
-The following table shows the metric names for that the corresponding
-metrics-based checks are supported by gnatcheck, including the
-constraint that must be satisfied by the bound that is specified for the check
-and what bound - upper (U) or lower (L) - should be specified.
-
-@multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer}
-@ifnothtml
-@headitem Check Name @tab Description @tab Bounds Value
-@end ifnothtml
-@ifhtml
-@item @b{Check Name} @tab @b{Description} @tab @b{Bounds Value}
-@end ifhtml
-@c Above conditional code is workaround to bug in texi2html (Feb 2008)
-@item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer (U)
-@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer (U)
-@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer (U)
-@end multitable
+@node Stack Overflow Checking
+@section Stack Overflow Checking
+@cindex Stack Overflow Checking
+@cindex -fstack-check
@noindent
-The meaning and the computed values for all these metrics are exactly
-the same as for the corresponding metrics in @command{gnatmetric}.
+For most operating systems, @command{gcc} does not perform stack overflow
+checking by default. This means that if the main environment task or
+some other task exceeds the available stack space, then unpredictable
+behavior will occur. Most native systems offer some level of protection by
+adding a guard page at the end of each task stack. This mechanism is usually
+not enough for dealing properly with stack overflow situations because
+a large local variable could ``jump'' above the guard page.
+Furthermore, when the
+guard page is hit, there may not be any space left on the stack for executing
+the exception propagation code. Enabling stack checking avoids
+such situations.
-@emph{Example:} the rule
-@smallexample
-+RMetrics_Cyclomatic_Complexity : 7
-@end smallexample
-@noindent
-means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
+To activate stack checking, compile all units with the gcc option
+@option{-fstack-check}. For example:
-To turn OFF the check for cyclomatic complexity metric, use the following option:
@smallexample
--RMetrics_Cyclomatic_Complexity
+gcc -c -fstack-check package1.adb
@end smallexample
-@node Misnamed_Identifiers
-@subsection @code{Misnamed_Identifiers}
-@cindex @code{Misnamed_Identifiers} rule (for @command{gnatcheck})
-
@noindent
-Flag the declaration of each identifier that does not have a suffix
-corresponding to the kind of entity being declared.
-The following declarations are checked:
-
-@itemize @bullet
-@item
-type declarations
+Units compiled with this option will generate extra instructions to check
+that any use of the stack (for procedure calls or for declaring local
+variables in declare blocks) does not exceed the available stack space.
+If the space is exceeded, then a @code{Storage_Error} exception is raised.
-@item
-subtype declarations
+For declared tasks, the stack size is controlled by the size
+given in an applicable @code{Storage_Size} pragma or by the value specified
+at bind time with @option{-d} (@pxref{Switches for gnatbind}) or is set to
+the default size as defined in the GNAT runtime otherwise.
-@item
-constant declarations (but not number declarations)
+For the environment task, the stack size depends on
+system defaults and is unknown to the compiler. Stack checking
+may still work correctly if a fixed
+size stack is allocated, but this cannot be guaranteed.
+@ifclear vms
+To ensure that a clean exception is signalled for stack
+overflow, set the environment variable
+@env{GNAT_STACK_LIMIT} to indicate the maximum
+stack area that can be used, as in:
+@cindex GNAT_STACK_LIMIT
-@item
-package renaming declarations (but not generic package renaming
-declarations)
-@end itemize
+@smallexample
+SET GNAT_STACK_LIMIT 1600
+@end smallexample
@noindent
-This rule may have parameters. When used without parameters, the rule enforces
-the following checks:
+The limit is given in kilobytes, so the above declaration would
+set the stack limit of the environment task to 1.6 megabytes.
+Note that the only purpose of this usage is to limit the amount
+of stack used by the environment task. If it is necessary to
+increase the amount of stack for the environment task, then this
+is an operating systems issue, and must be addressed with the
+appropriate operating systems commands.
+@end ifclear
+@ifset vms
+To have a fixed size stack in the environment task, the stack must be put
+in the P0 address space and its size specified. Use these switches to
+create a p0 image:
-@itemize @bullet
-@item
-type-defining names end with @code{_T}, unless the type is an access type,
-in which case the suffix must be @code{_A}
-@item
-constant names end with @code{_C}
-@item
-names defining package renamings end with @code{_R}
-@end itemize
+@smallexample
+gnatmake my_progs -largs "-Wl,--opt=STACK=4000,/p0image"
+@end smallexample
@noindent
-For a private or incomplete type declaration the following checks are
-made for the defining name suffix:
-
-@itemize @bullet
-@item
-For an incomplete type declaration: if the corresponding full type
-declaration is available, the defining identifier from the full type
-declaration is checked, but the defining identifier from the incomplete type
-declaration is not; otherwise the defining identifier from the incomplete
-type declaration is checked against the suffix specified for type
-declarations.
-
-@item
-For a private type declaration (including private extensions), the defining
-identifier from the private type declaration is checked against the type
-suffix (even if the corresponding full declaration is an access type
-declaration), and the defining identifier from the corresponding full type
-declaration is not checked.
-@end itemize
+The quotes are required to keep case. The number after @samp{STACK=} is the
+size of the environmental task stack in pagelets (512 bytes). In this example
+the stack size is about 2 megabytes.
@noindent
-For a deferred constant, the defining name in the corresponding full constant
-declaration is not checked.
+A consequence of the @option{/p0image} qualifier is also to makes RMS buffers
+be placed in P0 space. Refer to @cite{HP OpenVMS Linker Utility Manual} for
+more details about the @option{/p0image} qualifier and the @option{stack}
+option.
+@end ifset
-Defining names of formal types are not checked.
+@node Static Stack Usage Analysis
+@section Static Stack Usage Analysis
+@cindex Static Stack Usage Analysis
+@cindex -fstack-usage
-The rule may have the following parameters:
+@noindent
+A unit compiled with @option{-fstack-usage} will generate an extra file
+that specifies
+the maximum amount of stack used, on a per-function basis.
+The file has the same
+basename as the target object file with a @file{.su} extension.
+Each line of this file is made up of three fields:
-@itemize @bullet
+@itemize
@item
-For the @option{+R} option:
-@table @code
-@item Default
-Sets the default listed above for all the names to be checked.
-
-@item Type_Suffix=@emph{string}
-Specifies the suffix for a type name.
-
-@item Access_Suffix=@emph{string}
-Specifies the suffix for an access type name. If
-this parameter is set, it overrides for access
-types the suffix set by the @code{Type_Suffix} parameter.
-For access types, @emph{string} may have the following format:
-@emph{suffix1(suffix2)}. That means that an access type name
-should have the @emph{suffix1} suffix except for the case when
-the designated type is also an access type, in this case the
-type name should have the @emph{suffix1 & suffix2} suffix.
-
-@item Class_Access_Suffix=@emph{string}
-Specifies the suffix for the name of an access type that points to some class-wide
-type. If this parameter is set, it overrides for such access
-types the suffix set by the @code{Type_Suffix} or @code{Access_Suffix}
-parameter.
-
-@item Class_Subtype_Suffix=@emph{string}
-Specifies the suffix for the name of a subtype that denotes a class-wide type.
-
-@item Constant_Suffix=@emph{string}
-Specifies the suffix for a constant name.
-
-@item Renaming_Suffix=@emph{string}
-Specifies the suffix for a package renaming name.
-@end table
-
+The name of the function.
@item
-For the @option{-R} option:
-@table @code
-@item All_Suffixes
-Remove all the suffixes specified for the
-identifier suffix checks, whether by default or
-as specified by other rule parameters. All the
-checks for this rule are disabled as a result.
-
-@item Type_Suffix
-Removes the suffix specified for types. This
-disables checks for types but does not disable
-any other checks for this rule (including the
-check for access type names if @code{Access_Suffix} is
-set).
-
-@item Access_Suffix
-Removes the suffix specified for access types.
-This disables checks for access type names but
-does not disable any other checks for this rule.
-If @code{Type_Suffix} is set, access type names are
-checked as ordinary type names.
-
-@item Class_Access_Suffix
-Removes the suffix specified for access types pointing to class-wide
-type. This disables specific checks for names of access types pointing to
-class-wide types but does not disable any other checks for this rule.
-If @code{Type_Suffix} is set, access type names are
-checked as ordinary type names. If @code{Access_Suffix} is set, these
-access types are checked as any other access type name.
-
-@item Class_Subtype_Suffix=@emph{string}
-Removes the suffix specified for subtype names.
-This disables checks for subtype names but
-does not disable any other checks for this rule.
-
-@item Constant_Suffix
-Removes the suffix specified for constants. This
-disables checks for constant names but does not
-disable any other checks for this rule.
-
-@item Renaming_Suffix
-Removes the suffix specified for package
-renamings. This disables checks for package
-renamings but does not disable any other checks
-for this rule.
-@end table
+A number of bytes.
+@item
+One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
@end itemize
-@noindent
-If more than one parameter is used, parameters must be separated by commas.
-
-If more than one option is specified for the @command{gnatcheck} invocation,
-a new option overrides the previous one(s).
-
-The @option{+RMisnamed_Identifiers} option (with no parameter) enables
-checks for all the
-name suffixes specified by previous options used for this rule.
-
-The @option{-RMisnamed_Identifiers} option (with no parameter) disables
-all the checks but keeps
-all the suffixes specified by previous options used for this rule.
-
-The @emph{string} value must be a valid suffix for an Ada identifier (after
-trimming all the leading and trailing space characters, if any).
-Parameters are not case sensitive, except the @emph{string} part.
-
-If any error is detected in a rule parameter, the parameter is ignored.
-In such a case the options that are set for the rule are not
-specified.
-
-
-
-@node Multiple_Entries_In_Protected_Definitions
-@subsection @code{Multiple_Entries_In_Protected_Definitions}
-@cindex @code{Multiple_Entries_In_Protected_Definitions} rule (for @command{gnatcheck})
-
-@noindent
-Flag each protected definition (i.e., each protected object/type declaration)
-that defines more than one entry.
-Diagnostic messages are generated for all the entry declarations
-except the first one. An entry family is counted as one entry. Entries from
-the private part of the protected definition are also checked.
-
-This rule has no parameters.
-
-@node Name_Clashes
-@subsection @code{Name_Clashes}
-@cindex @code{Name_Clashes} rule (for @command{gnatcheck})
+The second field corresponds to the size of the known part of the function
+frame.
-@noindent
-Check that certain names are not used as defining identifiers. To activate
-this rule, you need to supply a reference to the dictionary file(s) as a rule
-parameter(s) (more then one dictionary file can be specified). If no
-dictionary file is set, this rule will not cause anything to be flagged.
-Only defining occurrences, not references, are checked.
-The check is not case-sensitive.
+The qualifier @code{static} means that the function frame size
+is purely static.
+It usually means that all local variables have a static size.
+In this case, the second field is a reliable measure of the function stack
+utilization.
-This rule is enabled by default, but without setting any corresponding
-dictionary file(s); thus the default effect is to do no checks.
+The qualifier @code{dynamic} means that the function frame size is not static.
+It happens mainly when some local variables have a dynamic size. When this
+qualifier appears alone, the second field is not a reliable measure
+of the function stack analysis. When it is qualified with @code{bounded}, it
+means that the second field is a reliable maximum of the function stack
+utilization.
-A dictionary file is a plain text file. The maximum line length for this file
-is 1024 characters. If the line is longer then this limit, extra characters
-are ignored.
+@node Dynamic Stack Usage Analysis
+@section Dynamic Stack Usage Analysis
-Each line can be either an empty line, a comment line, or a line containing
-a list of identifiers separated by space or HT characters.
-A comment is an Ada-style comment (from @code{--} to end-of-line).
-Identifiers must follow the Ada syntax for identifiers.
-A line containing one or more identifiers may end with a comment.
+@noindent
+It is possible to measure the maximum amount of stack used by a task, by
+adding a switch to @command{gnatbind}, as:
-@node Non_Qualified_Aggregates
-@subsection @code{Non_Qualified_Aggregates}
-@cindex @code{Non_Qualified_Aggregates} rule (for @command{gnatcheck})
+@smallexample
+$ gnatbind -u0 file
+@end smallexample
@noindent
-Flag each non-qualified aggregate.
-A non-qualified aggregate is an
-aggregate that is not the expression of a qualified expression. A
-string literal is not considered an aggregate, but an array
-aggregate of a string type is considered as a normal aggregate.
-Aggregates of anonymous array types are not flagged.
-
-This rule has no parameters.
+With this option, at each task termination, its stack usage is output on
+@file{stderr}.
+It is not always convenient to output the stack usage when the program
+is still running. Hence, it is possible to delay this output until program
+termination. for a given number of tasks specified as the argument of the
+@option{-u} option. For instance:
+@smallexample
+$ gnatbind -u100 file
+@end smallexample
-@node Non_Short_Circuit_Operators
-@subsection @code{Non_Short_Circuit_Operators}
-@cindex @code{Non_Short_Circuit_Operators} rule (for @command{gnatcheck})
+@noindent
+will buffer the stack usage information of the first 100 tasks to terminate and
+output this info at program termination. Results are displayed in four
+columns:
@noindent
-Flag all calls to predefined @code{and} and @code{or} operators for
-any boolean type. Calls to
-user-defined @code{and} and @code{or} and to operators defined by renaming
-declarations are not flagged. Calls to predefined @code{and} and @code{or}
-operators for modular types or boolean array types are not flagged.
+Index | Task Name | Stack Size | Stack Usage [Value +/- Variation]
-This rule has no parameters.
+@noindent
+where:
+@table @emph
+@item Index
+is a number associated with each task.
+@item Task Name
+is the name of the task analyzed.
-@node Non_SPARK_Attributes
-@subsection @code{Non_SPARK_Attributes}
-@cindex @code{Non_SPARK_Attributes} rule (for @command{gnatcheck})
+@item Stack Size
+is the maximum size for the stack.
-@noindent
-The SPARK language defines the following subset of Ada 95 attribute
-designators as those that can be used in SPARK programs. The use of
-any other attribute is flagged.
+@item Stack Usage
+is the measure done by the stack analyzer. In order to prevent overflow, the stack
+is not entirely analyzed, and it's not possible to know exactly how
+much has actually been used. The report thus contains the theoretical stack usage
+(Value) and the possible variation (Variation) around this value.
-@itemize @bullet
-@item @code{'Adjacent}
-@item @code{'Aft}
-@item @code{'Base}
-@item @code{'Ceiling}
-@item @code{'Component_Size}
-@item @code{'Compose}
-@item @code{'Copy_Sign}
-@item @code{'Delta}
-@item @code{'Denorm}
-@item @code{'Digits}
-@item @code{'Exponent}
-@item @code{'First}
-@item @code{'Floor}
-@item @code{'Fore}
-@item @code{'Fraction}
-@item @code{'Last}
-@item @code{'Leading_Part}
-@item @code{'Length}
-@item @code{'Machine}
-@item @code{'Machine_Emax}
-@item @code{'Machine_Emin}
-@item @code{'Machine_Mantissa}
-@item @code{'Machine_Overflows}
-@item @code{'Machine_Radix}
-@item @code{'Machine_Rounds}
-@item @code{'Max}
-@item @code{'Min}
-@item @code{'Model}
-@item @code{'Model_Emin}
-@item @code{'Model_Epsilon}
-@item @code{'Model_Mantissa}
-@item @code{'Model_Small}
-@item @code{'Modulus}
-@item @code{'Pos}
-@item @code{'Pred}
-@item @code{'Range}
-@item @code{'Remainder}
-@item @code{'Rounding}
-@item @code{'Safe_First}
-@item @code{'Safe_Last}
-@item @code{'Scaling}
-@item @code{'Signed_Zeros}
-@item @code{'Size}
-@item @code{'Small}
-@item @code{'Succ}
-@item @code{'Truncation}
-@item @code{'Unbiased_Rounding}
-@item @code{'Val}
-@item @code{'Valid}
-@end itemize
+@end table
@noindent
-This rule has no parameters.
+The environment task stack, e.g., the stack that contains the main unit, is
+only processed when the environment variable GNAT_STACK_LIMIT is set.
-@node Non_Tagged_Derived_Types
-@subsection @code{Non_Tagged_Derived_Types}
-@cindex @code{Non_Tagged_Derived_Types} rule (for @command{gnatcheck})
+@c *********************************
+@c * GNATCHECK *
+@c *********************************
+@node Verifying Properties Using gnatcheck
+@chapter Verifying Properties Using @command{gnatcheck}
+@findex gnatcheck
+@cindex @command{gnatcheck}
@noindent
-Flag all derived type declarations that do not have a record extension part.
+The @command{gnatcheck} tool is an ASIS-based utility that checks properties
+of Ada source files according to a given set of semantic rules.
+@cindex ASIS
+
+In order to check compliance with a given rule, @command{gnatcheck} has to
+semantically analyze the Ada sources.
+Therefore, checks can only be performed on
+legal Ada units. Moreover, when a unit depends semantically upon units located
+outside the current directory, the source search path has to be provided when
+calling @command{gnatcheck}, either through a specified project file or
+through @command{gnatcheck} switches as described below.
-This rule has no parameters.
+A number of rules are predefined in @command{gnatcheck} and are described
+later in this chapter.
+You can also add new rules, by modifying the @command{gnatcheck} code and
+rebuilding the tool. In order to add a simple rule making some local checks,
+a small amount of straightforward ASIS-based programming is usually needed.
+Project support for @command{gnatcheck} is provided by the GNAT
+driver (see @ref{The GNAT Driver and Project Files}).
+Invoking @command{gnatcheck} on the command line has the form:
-@node Non_Visible_Exceptions
-@subsection @code{Non_Visible_Exceptions}
-@cindex @code{Non_Visible_Exceptions} rule (for @command{gnatcheck})
+@smallexample
+@c $ gnatcheck @ovar{switches} @{@var{filename}@}
+@c @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
+@c @r{[}-cargs @var{gcc_switches}@r{]} -rules @var{rule_options}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatcheck @r{[}@var{switches}@r{]} @{@var{filename}@}
+ @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
+ @r{[}-cargs @var{gcc_switches}@r{]} -rules @var{rule_options}
+@end smallexample
@noindent
-Flag constructs leading to the possibility of propagating an exception
-out of the scope in which the exception is declared.
-Two cases are detected:
-
+where
@itemize @bullet
@item
-An exception declaration in a subprogram body, task body or block
-statement is flagged if the body or statement does not contain a handler for
-that exception or a handler with an @code{others} choice.
+@var{switches} specify the general tool options
@item
-A @code{raise} statement in an exception handler of a subprogram body,
-task body or block statement is flagged if it (re)raises a locally
-declared exception. This may occur under the following circumstances:
-@itemize @minus
-@item
-it explicitly raises a locally declared exception, or
-@item
-it does not specify an exception name (i.e., it is simply @code{raise;})
-and the enclosing handler contains a locally declared exception in its
-exception choices.
-@end itemize
-@end itemize
-
-@noindent
-Renamings of local exceptions are not flagged.
-
-This rule has no parameters.
-
-
-@node Numeric_Literals
-@subsection @code{Numeric_Literals}
-@cindex @code{Numeric_Literals} rule (for @command{gnatcheck})
+Each @var{filename} is the name (including the extension) of a source
+file to process. ``Wildcards'' are allowed, and
+the file name may contain path information.
-@noindent
-Flag each use of a numeric literal in an index expression, and in any
-circumstance except for the following:
+@item
+Each @var{arg_list_filename} is the name (including the extension) of a text
+file containing the names of the source files to process, separated by spaces
+or line breaks.
-@itemize @bullet
@item
-a literal occurring in the initialization expression for a constant
-declaration or a named number declaration, or
+@var{gcc_switches} is a list of switches for
+@command{gcc}. They will be passed on to all compiler invocations made by
+@command{gnatcheck} to generate the ASIS trees. Here you can provide
+@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
+and use the @option{-gnatec} switch to set the configuration file,
+use the @option{-gnat05} switch if sources should be compiled in
+Ada 2005 mode etc.
@item
-an integer literal that is less than or equal to a value
-specified by the @option{N} rule parameter.
+@var{rule_options} is a list of options for controlling a set of
+rules to be checked by @command{gnatcheck} (@pxref{gnatcheck Rule Options}).
@end itemize
@noindent
-This rule may have the following parameters for the @option{+R} option:
-
-@table @asis
-@item @emph{N}
-@emph{N} is an integer literal used as the maximal value that is not flagged
-(i.e., integer literals not exceeding this value are allowed)
-
-@item @code{ALL}
-All integer literals are flagged
-@end table
-
-@noindent
-If no parameters are set, the maximum unflagged value is 1.
-
-The last specified check limit (or the fact that there is no limit at
-all) is used when multiple @option{+R} options appear.
-
-The @option{-R} option for this rule has no parameters.
-It disables the rule but retains the last specified maximum unflagged value.
-If the @option{+R} option subsequently appears, this value is used as the
-threshold for the check.
+Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be
+supplied.
+@menu
+* Format of the Report File::
+* General gnatcheck Switches::
+* gnatcheck Rule Options::
+* Adding the Results of Compiler Checks to gnatcheck Output::
+* Project-Wide Checks::
+* Rule exemption::
+* Predefined Rules::
+* Example of gnatcheck Usage::
+@end menu
-@node OTHERS_In_Aggregates
-@subsection @code{OTHERS_In_Aggregates}
-@cindex @code{OTHERS_In_Aggregates} rule (for @command{gnatcheck})
+@node Format of the Report File
+@section Format of the Report File
+@cindex Report file (for @code{gnatcheck})
@noindent
-Flag each use of an @code{others} choice in extension aggregates.
-In record and array aggregates, an @code{others} choice is flagged unless
-it is used to refer to all components, or to all but one component.
-
-If, in case of a named array aggregate, there are two associations, one
-with an @code{others} choice and another with a discrete range, the
-@code{others} choice is flagged even if the discrete range specifies
-exactly one component; for example, @code{(1..1 => 0, others => 1)}.
+The @command{gnatcheck} tool outputs on @file{stderr} all messages concerning
+rule violations except if running in quiet mode. It also creates a text file
+that contains the complete report of the last gnatcheck run. By default this file
+is named @file{^gnatcheck.out^GNATCHECK.OUT^} and it is located in the
+current directory; the @option{^-o^/OUTPUT^} option can be used to change the
+name and/or location of the report file. This report contains:
-This rule has no parameters.
-
-@node OTHERS_In_CASE_Statements
-@subsection @code{OTHERS_In_CASE_Statements}
-@cindex @code{OTHERS_In_CASE_Statements} rule (for @command{gnatcheck})
-
-@noindent
-Flag any use of an @code{others} choice in a @code{case} statement.
+@itemize @bullet
-This rule has no parameters.
+@item general details of the @command{gnatcheck} run: date and time of the run,
+the version of the tool that has generated this report, full parameters
+of the @command{gnatcheck} invocation, reference to the list of checked
+sources and applied rules (coding standard);
+@item summary of the run (number of checked sources and detected violations);
+@item list of exempted coding standard violations;
+@item list of non-exempted coding standard violations;
+@item list of problems in the definition of exemption sections;
+@item of language violations (compile-time errors) detected in processed sources;
+@end itemize
-@node OTHERS_In_Exception_Handlers
-@subsection @code{OTHERS_In_Exception_Handlers}
-@cindex @code{OTHERS_In_Exception_Handlers} rule (for @command{gnatcheck})
+@node General gnatcheck Switches
+@section General @command{gnatcheck} Switches
@noindent
-Flag any use of an @code{others} choice in an exception handler.
-
-This rule has no parameters.
-
+The following switches control the general @command{gnatcheck} behavior
-@node Outer_Loop_Exits
-@subsection @code{Outer_Loop_Exits}
-@cindex @code{Outer_Loop_Exits} rule (for @command{gnatcheck})
+@table @option
+@c !sort!
+@cindex @option{^-a^/ALL^} (@command{gnatcheck})
+@item ^-a^/ALL^
+Process all units including those with read-only ALI files such as
+those from the GNAT Run-Time library.
-@noindent
-Flag each @code{exit} statement containing a loop name that is not the name
-of the immediately enclosing @code{loop} statement.
+@ifclear vms
+@ignore
+@cindex @option{-d} (@command{gnatcheck})
+@item -d
+Debug mode
+@end ignore
-This rule has no parameters.
+@cindex @option{-dd} (@command{gnatcheck})
+@item -dd
+Progress indicator mode (for use in GPS).
+@end ifclear
+@cindex @option{^-h^/HELP^} (@command{gnatcheck})
+@item ^-h^/HELP^
+List the predefined and user-defined rules. For more details see
+@ref{Predefined Rules}.
-@node Overloaded_Operators
-@subsection @code{Overloaded_Operators}
-@cindex @code{Overloaded_Operators} rule (for @command{gnatcheck})
+@cindex @option{^-l^/LOCS^} (@command{gnatcheck})
+@item ^-l^/LOCS^
+Use full source locations references in the report file. For a construct from
+a generic instantiation a full source location is a chain from the location
+of this construct in the generic unit to the place where this unit is
+instantiated.
-@noindent
-Flag each function declaration that overloads an operator symbol.
-A function body is checked only if the body does not have a
-separate spec. Formal functions are also checked. For a
-renaming declaration, only renaming-as-declaration is checked
+@cindex @option{^-log^/LOG^} (@command{gnatcheck})
+@item ^-log^/LOG^
+Duplicate all the output sent to @file{stderr} into a log file. The log file
+is named @file{gnatcheck.log} and is located in the current directory.
-This rule has no parameters.
+@cindex @option{^-m^/DIAGNOSTIC_LIMIT^} (@command{gnatcheck})
+@item ^-m@i{nnnn}^/DIAGNOSTIC_LIMIT=@i{nnnn}^
+Maximum number of diagnostics to be sent to @file{stdout}, where @i{nnnn} is in
+the range 0@dots{}1000;
+the default value is 500. Zero means that there is no limitation on
+the number of diagnostic messages to be output.
+@cindex @option{^-q^/QUIET^} (@command{gnatcheck})
+@item ^-q^/QUIET^
+Quiet mode. All the diagnostics about rule violations are placed in the
+@command{gnatcheck} report file only, without duplication on @file{stdout}.
-@node Overly_Nested_Control_Structures
-@subsection @code{Overly_Nested_Control_Structures}
-@cindex @code{Overly_Nested_Control_Structures} rule (for @command{gnatcheck})
+@cindex @option{^-s^/SHORT^} (@command{gnatcheck})
+@item ^-s^/SHORT^
+Short format of the report file (no version information, no list of applied
+rules, no list of checked sources is included)
-@noindent
-Flag each control structure whose nesting level exceeds the value provided
-in the rule parameter.
+@cindex @option{^--include-file=@var{file}^/INCLUDE_FILE=@var{file}^} (@command{gnatcheck})
+@item ^--include-file^/INCLUDE_FILE^
+Append the content of the specified text file to the report file
-The control structures checked are the following:
+@cindex @option{^-t^/TIME^} (@command{gnatcheck})
+@item ^-t^/TIME^
+Print out execution time.
-@itemize @bullet
-@item @code{if} statement
-@item @code{case} statement
-@item @code{loop} statement
-@item Selective accept statement
-@item Timed entry call statement
-@item Conditional entry call
-@item Asynchronous select statement
-@end itemize
+@cindex @option{^-v^/VERBOSE^} (@command{gnatcheck})
+@item ^-v^/VERBOSE^
+Verbose mode; @command{gnatcheck} generates version information and then
+a trace of sources being processed.
-@noindent
-The rule has the following parameter for the @option{+R} option:
+@cindex @option{^-o ^/OUTPUT^} (@command{gnatcheck})
+@item ^-o ^/OUTPUT=^@var{report_file}
+Set name of report file file to @var{report_file} .
-@table @emph
-@item N
-Positive integer specifying the maximal control structure nesting
-level that is not flagged
@end table
-@noindent
-If the parameter for the @option{+R} option is not specified or
-if it is not a positive integer, @option{+R} option is ignored.
-
-If more then one option is specified for the gnatcheck call, the later option and
-new parameter override the previous one(s).
-
-
-@node Parameters_Out_Of_Order
-@subsection @code{Parameters_Out_Of_Order}
-@cindex @code{Parameters_Out_Of_Order} rule (for @command{gnatcheck})
-
-@noindent
-Flag each subprogram and entry declaration whose formal parameters are not
-ordered according to the following scheme:
-
-@itemize @bullet
-
-@item @code{in} and @code{access} parameters first,
-then @code{in out} parameters,
-and then @code{out} parameters;
-
-@item for @code{in} mode, parameters with default initialization expressions
-occur last
-@end itemize
-
-@noindent
-Only the first violation of the described order is flagged.
-
-The following constructs are checked:
-
-@itemize @bullet
-@item subprogram declarations (including null procedures);
-@item generic subprogram declarations;
-@item formal subprogram declarations;
-@item entry declarations;
-@item subprogram bodies and subprogram body stubs that do not
-have separate specifications
-@end itemize
+@node gnatcheck Rule Options
+@section @command{gnatcheck} Rule Options
@noindent
-Subprogram renamings are not checked.
+The following options control the processing performed by
+@command{gnatcheck}.
-This rule has no parameters.
+@table @option
+@cindex @option{+ALL} (@command{gnatcheck})
+@item +ALL
+Turn all the rule checks ON.
+@cindex @option{-ALL} (@command{gnatcheck})
+@item -ALL
+Turn all the rule checks OFF.
-@node Positional_Actuals_For_Defaulted_Generic_Parameters
-@subsection @code{Positional_Actuals_For_Defaulted_Generic_Parameters}
-@cindex @code{Positional_Actuals_For_Defaulted_Generic_Parameters} rule (for @command{gnatcheck})
+@cindex @option{+R} (@command{gnatcheck})
+@item +R@var{rule_id}@r{[}:@var{param}@r{]}
+Turn on the check for a specified rule with the specified parameter, if any.
+@var{rule_id} must be the identifier of one of the currently implemented rules
+(use @option{^-h^/HELP^} for the list of implemented rules). Rule identifiers
+are not case-sensitive. The @var{param} item must
+be a string representing a valid parameter(s) for the specified rule.
+If it contains any space characters then this string must be enclosed in
+quotation marks.
-@noindent
-Flag each generic actual parameter corresponding to a generic formal
-parameter with a default initialization, if positional notation is used.
+@cindex @option{-R} (@command{gnatcheck})
+@item -R@var{rule_id}@r{[}:@var{param}@r{]}
+Turn off the check for a specified rule with the specified parameter, if any.
-This rule has no parameters.
+@cindex @option{-from} (@command{gnatcheck})
+@item -from=@var{rule_option_filename}
+Read the rule options from the text file @var{rule_option_filename}, referred
+to as a ``coding standard file'' below.
-@node Positional_Actuals_For_Defaulted_Parameters
-@subsection @code{Positional_Actuals_For_Defaulted_Parameters}
-@cindex @code{Positional_Actuals_For_Defaulted_Parameters} rule (for @command{gnatcheck})
+@end table
@noindent
-Flag each actual parameter to a subprogram or entry call where the
-corresponding formal parameter has a default expression, if positional
-notation is used.
-
-This rule has no parameters.
-
-@node Positional_Components
-@subsection @code{Positional_Components}
-@cindex @code{Positional_Components} rule (for @command{gnatcheck})
+The default behavior is that all the rule checks are disabled.
-@noindent
-Flag each array, record and extension aggregate that includes positional
-notation.
+A coding standard file is a text file that contains a set of rule options
+described above.
+@cindex Coding standard file (for @code{gnatcheck})
+The file may contain empty lines and Ada-style comments (comment
+lines and end-of-line comments). There can be several rule options on a
+single line (separated by a space).
-This rule has no parameters.
+A coding standard file may reference other coding standard files by including
+more @option{-from=@var{rule_option_filename}}
+options, each such option being replaced with the content of the
+corresponding coding standard file during processing. In case a
+cycle is detected (that is, @file{@var{rule_file_1}} reads rule options
+from @file{@var{rule_file_2}}, and @file{@var{rule_file_2}} reads
+(directly or indirectly) rule options from @file{@var{rule_file_1}}),
+processing fails with an error message.
-@node Positional_Generic_Parameters
-@subsection @code{Positional_Generic_Parameters}
-@cindex @code{Positional_Generic_Parameters} rule (for @command{gnatcheck})
+@node Adding the Results of Compiler Checks to gnatcheck Output
+@section Adding the Results of Compiler Checks to @command{gnatcheck} Output
@noindent
-Flag each instantiation using positional parameter notation.
-
-This rule has no parameters.
-
-
-@node Positional_Parameters
-@subsection @code{Positional_Parameters}
-@cindex @code{Positional_Parameters} rule (for @command{gnatcheck})
+The @command{gnatcheck} tool can include in the generated diagnostic messages
+and in
+the report file the results of the checks performed by the compiler. Though
+disabled by default, this effect may be obtained by using @option{+R} with
+the following rule identifiers and parameters:
-@noindent
-Flag each subprogram or entry call using positional parameter notation,
-except for the following:
+@table @option
+@item Restrictions
+To record restrictions violations (which are performed by the compiler if the
+pragma @code{Restrictions} or @code{Restriction_Warnings} are given),
+use the @code{Restrictions} rule
+with the same parameters as pragma
+@code{Restrictions} or @code{Restriction_Warnings}.
-@itemize @bullet
-@item
-Invocations of prefix or infix operators are not flagged
-@item
-If the called subprogram or entry has only one formal parameter,
-the call is not flagged;
-@item
-If a subprogram call uses the @emph{Object.Operation} notation, then
-@itemize @minus
+@item Style_Checks
+To record compiler style checks (@pxref{Style Checking}), use the
+@code{Style_Checks} rule.
+This rule takes a parameter in one of the following forms:
+@itemize
@item
-the first parameter (that is, @emph{Object}) is not flagged;
+@code{All_Checks},
+which enables the standard style checks corresponding to the @option{-gnatyy}
+GNAT style check option, or
+
@item
-if the called subprogram has only two parameters, the second parameter
-of the call is not flagged;
-@end itemize
+a string with the same
+structure and semantics as the @code{string_LITERAL} parameter of the
+GNAT pragma @code{Style_Checks}
+(for further information about this pragma,
+@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
@end itemize
@noindent
-This rule has no parameters.
+For example, the
+@code{+RStyle_Checks:O} rule option activates
+the compiler style check that corresponds to
+@code{-gnatyO} style check option.
+@item Warnings
+To record compiler warnings (@pxref{Warning Message Control}), use the
+@code{Warnings} rule with a parameter that is a valid
+@i{static_string_expression} argument of the GNAT pragma @code{Warnings}
+(for further information about this pragma,
+@pxref{Pragma Warnings,,,gnat_rm, GNAT Reference Manual}).
+Note that in case of gnatcheck
+'s' parameter, that corresponds to the GNAT @option{-gnatws} option, disables
+all the specific warnings, but not suppresses the warning mode,
+and 'e' parameter, corresponding to @option{-gnatwe} that means
+"treat warnings as errors", does not have any effect.
+@end table
+To disable a specific restriction check, use @code{-RStyle_Checks} gnatcheck
+option with the corresponding restriction name as a parameter. @code{-R} is
+not available for @code{Style_Checks} and @code{Warnings} options, to disable
+warnings and style checks, use the corresponding warning and style options.
-@node Predefined_Numeric_Types
-@subsection @code{Predefined_Numeric_Types}
-@cindex @code{Predefined_Numeric_Types} rule (for @command{gnatcheck})
+@node Project-Wide Checks
+@section Project-Wide Checks
+@cindex Project-wide checks (for @command{gnatcheck})
@noindent
-Flag each explicit use of the name of any numeric type or subtype defined
-in package @code{Standard}.
-
-The rationale for this rule is to detect when the
-program may depend on platform-specific characteristics of the implementation
-of the predefined numeric types. Note that this rule is over-pessimistic;
-for example, a program that uses @code{String} indexing
-likely needs a variable of type @code{Integer}.
-Another example is the flagging of predefined numeric types with explicit
-constraints:
-
-@smallexample @c ada
- subtype My_Integer is Integer range Left .. Right;
- Vy_Var : My_Integer;
+In order to perform checks on all units of a given project, you can use
+the GNAT driver along with the @option{-P} option:
+@smallexample
+ gnat check -Pproj -rules -from=my_rules
@end smallexample
@noindent
-This rule detects only numeric types and subtypes defined in
-@code{Standard}. The use of numeric types and subtypes defined in other
-predefined packages (such as @code{System.Any_Priority} or
-@code{Ada.Text_IO.Count}) is not flagged
-
-This rule has no parameters.
-
-
-
-@node Raising_External_Exceptions
-@subsection @code{Raising_External_Exceptions}
-@cindex @code{Raising_External_Exceptions} rule (for @command{gnatcheck})
+If the project @code{proj} depends upon other projects, you can perform
+checks on the project closure using the @option{-U} option:
+@smallexample
+ gnat check -Pproj -U -rules -from=my_rules
+@end smallexample
@noindent
-Flag any @code{raise} statement, in a program unit declared in a library
-package or in a generic library package, for an exception that is
-neither a predefined exception nor an exception that is also declared (or
-renamed) in the visible part of the package.
-
-This rule has no parameters.
-
+Finally, if not all the units are relevant to a particular main
+program in the project closure, you can perform checks for the set
+of units needed to create a given main program (unit closure) using
+the @option{-U} option followed by the name of the main unit:
+@smallexample
+ gnat check -Pproj -U main -rules -from=my_rules
+@end smallexample
-@node Raising_Predefined_Exceptions
-@subsection @code{Raising_Predefined_Exceptions}
-@cindex @code{Raising_Predefined_Exceptions} rule (for @command{gnatcheck})
+@node Rule exemption
+@section Rule exemption
+@cindex Rule exemption (for @command{gnatcheck})
@noindent
-Flag each @code{raise} statement that raises a predefined exception
-(i.e., one of the exceptions @code{Constraint_Error}, @code{Numeric_Error},
-@code{Program_Error}, @code{Storage_Error}, or @code{Tasking_Error}).
+One of the most useful applications of @command{gnatcheck} is to
+automate the enforcement of project-specific coding standards,
+for example in safety-critical systems where particular features
+must be restricted in order to simplify the certification effort.
+However, it may sometimes be appropriate to violate a coding standard rule,
+and in such cases the rationale for the violation should be provided
+in the source program itself so that the individuals
+reviewing or maintaining the program can immediately understand the intent.
-This rule has no parameters.
+The @command{gnatcheck} tool supports this practice with the notion of
+a ``rule exemption'' covering a specific source code section. Normally
+rule violation messages are issued both on @file{stderr}
+and in a report file. In contrast, exempted violations are not listed on
+@file{stderr}; thus users invoking @command{gnatcheck} interactively
+(e.g. in its GPS interface) do not need to pay attention to known and
+justified violations. However, exempted violations along with their
+justification are documented in a special section of the report file that
+@command{gnatcheck} generates.
-@node Separate_Numeric_Error_Handlers
-@subsection @code{Separate_Numeric_Error_Handlers}
-@cindex @code{Separate_Numeric_Error_Handlers} rule (for @command{gnatcheck})
-
-@noindent
-Flags each exception handler that contains a choice for
-the predefined @code{Constraint_Error} exception, but does not contain
-the choice for the predefined @code{Numeric_Error} exception, or
-that contains the choice for @code{Numeric_Error}, but does not contain the
-choice for @code{Constraint_Error}.
-
-This rule has no parameters.
+@menu
+* Using pragma Annotate to Control Rule Exemption::
+* gnatcheck Annotations Rules::
+@end menu
-@ignore
-@node Recursion
-@subsection @code{Recursion} (under construction, GLOBAL)
-@cindex @code{Recursion} rule (for @command{gnatcheck})
+@node Using pragma Annotate to Control Rule Exemption
+@subsection Using pragma @code{Annotate} to Control Rule Exemption
+@cindex Using pragma Annotate to control rule exemption
@noindent
-Flag recursive subprograms (cycles in the call graph). Declarations, and not
-calls, of recursive subprograms are detected.
+Rule exemption is controlled by pragma @code{Annotate} when its first
+argument is ``gnatcheck''. The syntax of @command{gnatcheck}'s
+exemption control annotations is as follows:
-This rule has no parameters.
-@end ignore
+@smallexample @c ada
+@group
+pragma Annotate (gnatcheck, @i{exemption_control}, @i{Rule_Name}, [@i{justification}]);
-@ignore
-@node Side_Effect_Functions
-@subsection @code{Side_Effect_Functions} (under construction, GLOBAL)
-@cindex @code{Side_Effect_Functions} rule (for @command{gnatcheck})
+@i{exemption_control} ::= Exempt_On | Exempt_Off
-@noindent
-Flag functions with side effects.
+@i{Rule_Name} ::= string_literal
-We define a side effect as changing any data object that is not local for the
-body of this function.
+@i{justification} ::= string_literal
+@end group
+@end smallexample
-At the moment, we do NOT consider a side effect any input-output operations
-(changing a state or a content of any file).
+@noindent
+When a @command{gnatcheck} annotation has more then four arguments,
+@command{gnatcheck} issues a warning and ignores the additional arguments.
+If the additional arguments do not follow the syntax above,
+@command{gnatcheck} emits a warning and ignores the annotation.
-We do not consider protected functions for this rule (???)
+The @i{@code{Rule_Name}} argument should be the name of some existing
+@command{gnatcheck} rule.
+Otherwise a warning message is generated and the pragma is
+ignored. If @code{Rule_Name} denotes a rule that is not activated by the given
+@command{gnatcheck} call, the pragma is ignored and no warning is issued.
-There are the following sources of side effect:
+A source code section where an exemption is active for a given rule is
+delimited by an @code{exempt_on} and @code{exempt_off} annotation pair:
-@enumerate
-@item Explicit (or direct) side-effect:
+@smallexample @c ada
+pragma Annotate (gnatcheck, Exempt_On, Rule_Name, "justification");
+-- source code section
+pragma Annotate (gnatcheck, Exempt_Off, Rule_Name);
+@end smallexample
-@itemize @bullet
-@item
-direct assignment to a non-local variable;
-@item
-direct call to an entity that is known to change some data object that is
- not local for the body of this function (Note, that if F1 calls F2 and F2
- does have a side effect, this does not automatically mean that F1 also
- have a side effect, because it may be the case that F2 is declared in
- F1's body and it changes some data object that is global for F2, but
- local for F1);
-@end itemize
+@node gnatcheck Annotations Rules
+@subsection @command{gnatcheck} Annotations Rules
+@cindex @command{gnatcheck} annotations rules
-@item Indirect side-effect:
-@itemize @bullet
-@item
-Subprogram calls implicitly issued by:
@itemize @bullet
-@item
-computing initialization expressions from type declarations as a part
- of object elaboration or allocator evaluation;
-@item
-computing implicit parameters of subprogram or entry calls or generic
- instantiations;
-@end itemize
@item
-activation of a task that change some non-local data object (directly or
- indirectly);
+An ``Exempt_Off'' annotation can only appear after a corresponding
+``Exempt_On'' annotation.
@item
-elaboration code of a package that is a result of a package instantiation;
+Exempted source code sections are only based on the source location of the
+annotations. Any source construct between the two
+annotations is part of the exempted source code section.
@item
-controlled objects;
-@end itemize
+Exempted source code sections for different rules are independent. They can
+be nested or intersect with one another without limitation.
+Creating nested or intersecting source code sections for the same rule is
+not allowed.
-@item Situations when we can suspect a side-effect, but the full static check
-is either impossible or too hard:
-@itemize @bullet
@item
-assignment to access variables or to the objects pointed by access
- variables;
+Malformed exempted source code sections are reported by a warning, and
+the corresponding rule exemptions are ignored.
@item
-call to a subprogram pointed by access-to-subprogram value
+When an exempted source code section does not contain at least one violation
+of the exempted rule, a warning is emitted on @file{stderr}.
@item
-dispatching calls;
+If an ``Exempt_On'' annotation pragma does not have a matching
+``Exempt_Off'' annotation pragma in the same compilation unit, then the
+exemption for the given rule is ignored and a warning is issued.
@end itemize
-@end enumerate
-@noindent
-This rule has no parameters.
-@end ignore
-@node Slices
-@subsection @code{Slices}
-@cindex @code{Slices} rule (for @command{gnatcheck})
+@node Predefined Rules
+@section Predefined Rules
+@cindex Predefined rules (for @command{gnatcheck})
+@ignore
+@c (Jan 2007) Since the global rules are still under development and are not
+@c documented, there is no point in explaining the difference between
+@c global and local rules
@noindent
-Flag all uses of array slicing
-
-This rule has no parameters.
+A rule in @command{gnatcheck} is either local or global.
+A @emph{local rule} is a rule that applies to a well-defined section
+of a program and that can be checked by analyzing only this section.
+A @emph{global rule} requires analysis of some global properties of the
+whole program (mostly related to the program call graph).
+As of @value{NOW}, the implementation of global rules should be
+considered to be at a preliminary stage. You can use the
+@option{+GLOBAL} option to enable all the global rules, and the
+@option{-GLOBAL} rule option to disable all the global rules.
+All the global rules in the list below are
+so indicated by marking them ``GLOBAL''.
+This +GLOBAL and -GLOBAL options are not
+included in the list of gnatcheck options above, because at the moment they
+are considered as a temporary debug options.
-@node Unassigned_OUT_Parameters
-@subsection @code{Unassigned_OUT_Parameters}
-@cindex @code{Unassigned_OUT_Parameters} rule (for @command{gnatcheck})
+@command{gnatcheck} performs rule checks for generic
+instances only for global rules. This limitation may be relaxed in a later
+release.
+@end ignore
@noindent
-Flags procedures' @code{out} parameters that are not assigned, and
-identifies the contexts in which the assignments are missing.
+The predefined rules implemented in @command{gnatcheck}
+are described in a companion document,
+@cite{GNATcheck Reference Manual -- Predefined Rules}.
+The rule identifier is
+used as a parameter of @command{gnatcheck}'s @option{+R} or @option{-R}
+switches.
-An @code{out} parameter is flagged in the statements in the procedure
-body's handled sequence of statements (before the procedure body's
-@code{exception} part, if any) if this sequence of statements contains
-no assignments to the parameter.
-An @code{out} parameter is flagged in an exception handler in the exception
-part of the procedure body's handled sequence of statements if the handler
-contains no assignment to the parameter.
+@node Example of gnatcheck Usage
+@section Example of @command{gnatcheck} Usage
-Bodies of generic procedures are also considered.
+@noindent
+Here is a simple example. Suppose that in the current directory we have a
+project file named @file{gnatcheck_example.gpr} with the following content:
-The following are treated as assignments to an @code{out} parameter:
+@smallexample @c projectfile
+project Gnatcheck_Example is
-@itemize @bullet
-@item
-an assignment statement, with the parameter or some component as the target;
+ for Source_Dirs use ("src");
+ for Object_Dir use "obj";
+ for Main use ("main.adb");
-@item
-passing the parameter (or one of its components) as an @code{out} or
-@code{in out} parameter.
-@end itemize
+ package Check is
+ for Default_Switches ("ada") use ("-rules", "-from=coding_standard");
+ end Check;
+
+end Gnatcheck_Example;
+@end smallexample
@noindent
-This rule does not have any parameters.
+And the file named @file{coding_standard} is also located in the current
+directory and has the following content:
+@smallexample
+-----------------------------------------------------
+-- This is a sample gnatcheck coding standard file --
+-----------------------------------------------------
+-- First, turning on rules, that are directly implemented in gnatcheck
++RAbstract_Type_Declarations
++RAnonymous_Arrays
++RLocal_Packages
++RFloat_Equality_Checks
++REXIT_Statements_With_No_Loop_Name
-@node Uncommented_BEGIN_In_Package_Bodies
-@subsection @code{Uncommented_BEGIN_In_Package_Bodies}
-@cindex @code{Uncommented_BEGIN_In_Package_Bodies} rule (for @command{gnatcheck})
+-- Then, activating compiler checks of interest:
++RStyle_Checks:e
+-- This style check checks if a unit name is present on END keyword that
+-- is the end of the unit declaration
+@end smallexample
@noindent
-Flags each package body with declarations and a statement part that does not
-include a trailing comment on the line containing the @code{begin} keyword;
-this trailing comment needs to specify the package name and nothing else.
-The @code{begin} is not flagged if the package body does not
-contain any declarations.
-
-If the @code{begin} keyword is placed on the
-same line as the last declaration or the first statement, it is flagged
-independently of whether the line contains a trailing comment. The
-diagnostic message is attached to the line containing the first statement.
+And the subdirectory @file{src} contains the following Ada sources:
-This rule has no parameters.
+@file{pack.ads}:
-@node Unconditional_Exits
-@subsection @code{Unconditional_Exits}
-@cindex @code{Unconditional_Exits} rule (for @command{gnatcheck})
+@smallexample @c ada
+package Pack is
+ type T is abstract tagged private;
+ procedure P (X : T) is abstract;
+
+ package Inner is
+ type My_Float is digits 8;
+ function Is_Equal (L, R : My_Float) return Boolean;
+ end Inner;
+private
+ type T is abstract tagged null record;
+end;
+@end smallexample
@noindent
-Flag unconditional @code{exit} statements.
+@file{pack.adb}:
-This rule has no parameters.
-
-@node Unconstrained_Array_Returns
-@subsection @code{Unconstrained_Array_Returns}
-@cindex @code{Unconstrained_Array_Returns} rule (for @command{gnatcheck})
+@smallexample @c ada
+package body Pack is
+ package body Inner is
+ function Is_Equal (L, R : My_Float) return Boolean is
+ begin
+ return L = R;
+ end;
+ end Inner;
+end Pack;
+@end smallexample
@noindent
-Flag each function returning an unconstrained array. Function declarations,
-function bodies (and body stubs) having no separate specifications,
-and generic function instantiations are checked.
-Generic function declarations, function calls and function renamings are
-not checked.
+and @file{main.adb}
-This rule has no parameters.
+@smallexample @c ada
+with Pack; use Pack;
+procedure Main is
-@node Universal_Ranges
-@subsection @code{Universal_Ranges}
-@cindex @code{Universal_Ranges} rule (for @command{gnatcheck})
+ pragma Annotate
+ (gnatcheck, Exempt_On, "Anonymous_Arrays", "this one is fine");
+ Float_Array : array (1 .. 10) of Inner.My_Float;
+ pragma Annotate (gnatcheck, Exempt_Off, "Anonymous_Arrays");
-@noindent
-Flag discrete ranges that are a part of an index constraint, constrained
-array definition, or @code{for}-loop parameter specification, and whose bounds
-are both of type @i{universal_integer}. Ranges that have at least one
-bound of a specific type (such as @code{1 .. N}, where @code{N} is a variable
-or an expression of non-universal type) are not flagged.
+ Another_Float_Array : array (1 .. 10) of Inner.My_Float;
-This rule has no parameters.
+ use Inner;
+ B : Boolean := False;
-@node Unnamed_Blocks_And_Loops
-@subsection @code{Unnamed_Blocks_And_Loops}
-@cindex @code{Unnamed_Blocks_And_Loops} rule (for @command{gnatcheck})
+begin
+ for J in Float_Array'Range loop
+ if Is_Equal (Float_Array (J), Another_Float_Array (J)) then
+ B := True;
+ exit;
+ end if;
+ end loop;
+end Main;
+@end smallexample
@noindent
-Flag each unnamed block statement and loop statement.
+And suppose we call @command{gnatcheck} from the current directory using
+the @command{gnat} driver:
+
+@smallexample
+ gnat check -Pgnatcheck_example.gpr
+@end smallexample
-The rule has no parameters.
+@noindent
+As a result, @command{gnatcheck} is called to check all the files from the
+project @file{gnatcheck_example.gpr} using the coding standard defined by
+the file @file{coding_standard}. As the result, the @command{gnatcheck}
+report file named @file{gnatcheck.out} will be created in the current
+directory, and it will have the following content:
+@smallexample
+RULE CHECKING REPORT
+1. OVERVIEW
-@ignore
-@node Unused_Subprograms
-@subsection @code{Unused_Subprograms} (under construction, GLOBAL)
-@cindex @code{Unused_Subprograms} rule (for @command{gnatcheck})
+Date and time of execution: 2009.10.28 14:17
+Tool version: GNATCHECK (built with ASIS 2.0.R for GNAT Pro 6.3.0w (20091016))
+Command line:
-@noindent
-Flag all unused subprograms.
+gnatcheck -files=.../GNAT-TEMP-000004.TMP -cargs -gnatec=.../GNAT-TEMP-000003.TMP -rules -from=coding_standard
-This rule has no parameters.
-@end ignore
+Coding standard (applied rules):
+ Abstract_Type_Declarations
+ Anonymous_Arrays
+ EXIT_Statements_With_No_Loop_Name
+ Float_Equality_Checks
+ Local_Packages
+ Compiler style checks: -gnatye
+Number of coding standard violations: 6
+Number of exempted coding standard violations: 1
+2. DETECTED RULE VIOLATIONS
-@node USE_PACKAGE_Clauses
-@subsection @code{USE_PACKAGE_Clauses}
-@cindex @code{USE_PACKAGE_Clauses} rule (for @command{gnatcheck})
+2.1. NON-EXEMPTED VIOLATIONS
-@noindent
-Flag all @code{use} clauses for packages; @code{use type} clauses are
-not flagged.
+Source files with non-exempted violations
+ pack.ads
+ pack.adb
+ main.adb
-This rule has no parameters.
+List of violations grouped by files, and ordered by increasing source location:
+pack.ads:2:4: declaration of abstract type
+pack.ads:5:4: declaration of local package
+pack.ads:10:30: declaration of abstract type
+pack.ads:11:1: (style) "end Pack" required
+pack.adb:5:19: use of equality operation for float values
+pack.adb:6:7: (style) "end Is_Equal" required
+main.adb:9:26: anonymous array type
+main.adb:19:10: exit statement with no loop name
+2.2. EXEMPTED VIOLATIONS
-@node Volatile_Objects_Without_Address_Clauses
-@subsection @code{Volatile_Objects_Without_Address_Clauses}
-@cindex @code{Volatile_Objects_Without_Address_Clauses} rule (for @command{gnatcheck})
+Source files with exempted violations
+ main.adb
-@noindent
-Flag each volatile object that does not have an address clause.
+List of violations grouped by files, and ordered by increasing source location:
-The following check is made: if the pragma @code{Volatile} is applied to a
-data object or to its type, then an address clause must
-be supplied for this object.
+main.adb:6:18: anonymous array type
+ (this one is fine)
-This rule does not check the components of data objects,
-array components that are volatile as a result of the pragma
-@code{Volatile_Components}, or objects that are volatile because
-they are atomic as a result of pragmas @code{Atomic} or
-@code{Atomic_Components}.
+2.3. SOURCE FILES WITH NO VIOLATION
-Only variable declarations, and not constant declarations, are checked.
+ No files without violations
-This rule has no parameters.
+END OF REPORT
+@end smallexample
@c *********************************
@command{gnatstub} has the command-line interface of the form
@smallexample
-$ gnatstub @ovar{switches} @var{filename} @ovar{directory}
+@c $ gnatstub @ovar{switches} @var{filename} @ovar{directory}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatstub @r{[}@var{switches}@r{]} @var{filename} @r{[}@var{directory}@r{]} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
is the
current directory)
+@item @samp{@var{gcc_switches}} is a list of switches for
+@command{gcc}. They will be passed on to all compiler invocations made by
+@command{gnatelim} to generate the ASIS trees. Here you can provide
+@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
+use the @option{-gnatec} switch to set the configuration file,
+use the @option{-gnat05} switch if sources should be compiled in
+Ada 2005 mode etc.
+
@item switches
is an optional sequence of switches as described in the next section
@end table
Avoind raising PROGRAM_ERROR in the generated bodies of program unit stubs.
This is not always possible for function stubs.
+@item ^--no-local-header^/NO_LOCAL_HEADER^
+@cindex @option{^--no-local-header^/NO_LOCAL_HEADER^} (@command{gnatstub})
+Do not place local comment header with unit name before body stub for a
+unit.
+
@item ^-o ^/BODY=^@var{body-name}
@cindex @option{^-o^/BODY^} (@command{gnatstub})
Body file name. This should be set if the argument file name does not
@findex binding
@noindent
-GNAT now comes with a new experimental binding generator for C and C++
-headers which is intended to do 95% of the tedious work of generating
-Ada specs from C or C++ header files. Note that this still is a work in
-progress, not designed to generate 100% correct Ada specs.
+GNAT now comes with a binding generator for C and C++ headers which is
+intended to do 95% of the tedious work of generating Ada specs from C
+or C++ header files.
+
+Note that this capability is not intended to generate 100% correct Ada specs,
+and will is some cases require manual adjustments, although it can often
+be used out of the box in practice.
+
+Some of the known limitations include:
+
+@itemize @bullet
+@item only very simple character constant macros are translated into Ada
+constants. Function macros (macros with arguments) are partially translated
+as comments, to be completed manually if needed.
+@item some extensions (e.g. vector types) are not supported
+@item pointers to pointers or complex structures are mapped to System.Address
+@end itemize
The code generated is using the Ada 2005 syntax, which makes it
easier to interface with other languages than previous versions of Ada.
The command line is as follow:
@smallexample
-$ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
+@c $ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ perl gnathtml.pl @r{[}@var{^switches^options^}@r{]} @var{ada-files}
@end smallexample
@noindent
Alternatively, you may run the script using the following command line:
@smallexample
-$ perl gnathtml.pl @ovar{switches} @var{files}
+@c $ perl gnathtml.pl @ovar{switches} @var{files}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ perl gnathtml.pl @r{[}@var{switches}@r{]} @var{files}
@end smallexample
@ifset vms
@end smallexample
@noindent
-Note that only the objects that were compiled with the @samp{-pg} switch will be
-profiled; if you need to profile your whole project, use the
-@samp{-f} gnatmake switch to force full recompilation.
+Note that only the objects that were compiled with the @samp{-pg} switch will
+be profiled; if you need to profile your whole project, use the @samp{-f}
+gnatmake switch to force full recompilation.
@node Program execution
@subsection Program execution
* Ada Exceptions::
* Ada Tasks::
* Debugging Generic Units::
+* Remote Debugging using gdbserver::
* GNAT Abnormal Termination or Failure to Terminate::
* Naming Conventions for GNAT Source Files::
* Getting Internal Debugging Information::
stops and @code{GDB} signals that the breakpoint was encountered by
printing the line of code before which the program is halted.
-@item breakpoint exception @var{name}
-A special form of the breakpoint command which breakpoints whenever
-exception @var{name} is raised.
-If @var{name} is omitted,
-then a breakpoint will occur when any exception is raised.
+@item catch exception @var{name}
+This command causes the program execution to stop whenever exception
+@var{name} is raised. If @var{name} is omitted, then the execution is
+suspended when any exception is raised.
@item print @var{expression}
This will print the value of the given expression. Most simple
that was stepped through.
@node Ada Exceptions
-@section Breaking on Ada Exceptions
+@section Stopping when Ada Exceptions are Raised
@cindex Exceptions
@noindent
-You can set breakpoints that trip when your program raises
-selected exceptions.
+You can set catchpoints that stop the program execution when your program
+raises selected exceptions.
@table @code
-@item break exception
-Set a breakpoint that trips whenever (any task in the) program raises
-any exception.
+@item catch exception
+Set a catchpoint that stops execution whenever (any task in the) program
+raises any exception.
-@item break exception @var{name}
-Set a breakpoint that trips whenever (any task in the) program raises
-the exception @var{name}.
+@item catch exception @var{name}
+Set a catchpoint that stops execution whenever (any task in the) program
+raises the exception @var{name}.
-@item break exception unhandled
-Set a breakpoint that trips whenever (any task in the) program raises an
-exception for which there is no handler.
+@item catch exception unhandled
+Set a catchpoint that stops executino whenever (any task in the) program
+raises an exception for which there is no handler.
@item info exceptions
@itemx info exceptions @var{regexp}
instance in the normal manner and examine the values of local variables, as for
other units.
+@node Remote Debugging using gdbserver
+@section Remote Debugging using gdbserver
+@cindex Remote Debugging using gdbserver
+
+@noindent
+On platforms where gdbserver is supported, it is possible to use this tool
+to debug your application remotely. This can be useful in situations
+where the program needs to be run on a target host that is different
+from the host used for development, particularly when the target has
+a limited amount of resources (either CPU and/or memory).
+
+To do so, start your program using gdbserver on the target machine.
+gdbserver then automatically suspends the execution of your program
+at its entry point, waiting for a debugger to connect to it. The
+following commands starts an application and tells gdbserver to
+wait for a connection with the debugger on localhost port 4444.
+
+@smallexample
+$ gdbserver localhost:4444 program
+Process program created; pid = 5685
+Listening on port 4444
+@end smallexample
+
+Once gdbserver has started listening, we can tell the debugger to establish
+a connection with this gdbserver, and then start the same debugging session
+as if the program was being debugged on the same host, directly under
+the control of GDB.
+
+@smallexample
+$ gdb program
+(gdb) target remote targethost:4444
+Remote debugging using targethost:4444
+0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so.
+(gdb) b foo.adb:3
+Breakpoint 1 at 0x401f0c: file foo.adb, line 3.
+(gdb) continue
+Continuing.
+
+Breakpoint 1, foo () at foo.adb:4
+4 end foo;
+@end smallexample
+
+It is also possible to use gdbserver to attach to an already running
+program, in which case the execution of that program is simply suspended
+until the connection between the debugger and gdbserver is established.
+
+For more information on how to use gdbserver, @ref{Top, Server, Using
+the gdbserver Program, gdb, Debugging with GDB}. GNAT Pro provides support
+for gdbserver on x86-linux, x86-windows and x86_64-linux.
+
@node GNAT Abnormal Termination or Failure to Terminate
@section GNAT Abnormal Termination or Failure to Terminate
@cindex GNAT Abnormal Termination or Failure to Terminate
For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
attributes are recognized, although only a subset of them can sensibly
be implemented. The description of pragmas in
-@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
indicates whether or not they are applicable to non-VMS systems.
@menu
@noindent
The pragma @code{Extend_System} is a configuration pragma that
is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
-Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
+Extend_System,,, gnat_rm, GNAT Reference Manual}, for further details.
HP Ada does not allow the recompilation of the package
@code{SYSTEM}. Instead HP Ada provides several pragmas
@code{TO_ADDRESS}
function for type @code{UNSIGNED_LONGWORD} is changed to
@code{TO_ADDRESS_LONG}.
-@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
+@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual}, for a
discussion of why this change was necessary.
@noindent
a separate subprogram specification which must appear before the
subprogram body.
-GNAT also supplies a number of implementation-defined pragmas as follows:
+GNAT also supplies a number of implementation-defined pragmas including the
+following:
+
@itemize @bullet
@item @code{ABORT_DEFER}
@item @code{ADA_05}
+@item @code{Ada_2005}
+
+@item @code{Ada_12}
+
+@item @code{Ada_2012}
+
@item @code{ANNOTATE}
@item @code{ASSERT}
@end itemize
@noindent
-For full details on these GNAT implementation-defined pragmas,
+For full details on these and other GNAT implementation-defined pragmas,
see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
Manual}.
* AIX-Specific Considerations::
* Irix-Specific Considerations::
* RTX-Specific Considerations::
+* HP-UX-Specific Considerations::
@end menu
@node Summary of Run-Time Configurations
@item
Real-time subsystem (RTSS) executables that run in Ring 0, where
performance can be optimized with RTSS applications taking precedent
-over all Windows applications (@emph{rts-rtx-rtss}).
+over all Windows applications (@emph{rts-rtx-rtss}). This mode requires
+the Microsoft linker to handle RTSS libraries.
+
+@end itemize
+@node HP-UX-Specific Considerations
+@section HP-UX-Specific Considerations
+@cindex HP-UX Scheduling
+
+@noindent
+On HP-UX, appropriate privileges are required to change the scheduling
+parameters of a task. The calling process must have appropriate
+privileges or be a member of a group having @code{PRIV_RTSCHED} access to
+successfully change the scheduling parameters.
+
+By default, GNAT uses the @code{SCHED_HPUX} policy. To have access to the
+priority range 0-31 either the @code{FIFO_Within_Priorities} or the
+@code{Round_Robin_Within_Priorities} scheduling policies need to be set.
+
+To specify the @code{FIFO_Within_Priorities} scheduling policy you can use
+one of the following:
+
+@itemize @bullet
+@item
+@code{pragma Time_Slice (0.0)}
+@cindex pragma Time_Slice
+@item
+the corresponding binder option @option{-T0}
+@cindex @option{-T0} option
+@item
+@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
+@cindex pragma Task_Dispatching_Policy
@end itemize
+@noindent
+To specify the @code{Round_Robin_Within_Priorities}, scheduling policy
+you should use @code{pragma Time_Slice} with a
+value greater than @code{0.0}, or use the corresponding @option{-T}
+binder option, or set the @code{pragma Task_Dispatching_Policy
+(Round_Robin_Within_Priorities)}.
+
@c *******************************
@node Example of Binder Output File
@appendix Example of Binder Output File
@command{gnatmake}) command, or by the use of the configuration pragma:
@smallexample @c ada
-pragma Elaboration_Checks (RM);
+pragma Elaboration_Checks (DYNAMIC);
@end smallexample
@noindent
compiler so this can only be used where both declarations are legal,
even though one of them will not be used.
-Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, or
-Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations
+Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word},
+or Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations
that are parameterized by these constants. For example
@smallexample @c ada
@menu
* Address types::
-* Access types::
+* Access types and 32/64-bit allocation::
* Unchecked conversions::
* Predefined constants::
* Interfacing with C::
+* 32/64-bit descriptors::
* Experience with source compatibility::
@end menu
@itemize @bullet
@item
@code{System.Address} always has a size of 64 bits
+@cindex @code{System.Address} size
+@cindex @code{Address} size
@item
@code{System.Short_Address} is a 32-bit subtype of @code{System.Address}
+@cindex @code{System.Short_Address} size
+@cindex @code{Short_Address} size
@end itemize
@noindent
automatically perform any needed conversions between address
formats.
-@node Access types
-@subsubsection Access types
+@node Access types and 32/64-bit allocation
+@subsubsection Access types and 32/64-bit allocation
+@cindex 32-bit allocation
+@cindex 64-bit allocation
@noindent
-By default, objects designated by access values are always
-allocated in the 32-bit
-address space. Thus legacy code will never contain
-any objects that are not addressable with 32-bit addresses, and
-the compiler will never raise exceptions as result of mixing
-32-bit and 64-bit addresses.
+By default, objects designated by access values are always allocated in
+the 64-bit address space, and access values themselves are represented
+in 64 bits. If these defaults are not appropriate, and 32-bit allocation
+is required (for example if the address of an allocated object is assigned
+to a @code{Short_Address} variable), then several alternatives are available:
-However, the access values themselves are represented in 64 bits, for optimum
-performance and future compatibility with 64-bit code. As was
-the case with @code{System.Address}, the compiler will give an error message
-if an object or record component has a representation clause that
-requires the access value to fit in 32 bits. In such a situation,
-an explicit size clause for the access type, specifying 32 bits,
-will have the desired effect.
+@itemize @bullet
+@item
+A pool-specific access type (ie, an @w{Ada 83} access type, whose
+definition is @code{access T} versus @code{access all T} or
+@code{access constant T}), may be declared with a @code{'Size} representation
+clause that establishes the size as 32 bits.
+In such circumstances allocations for that type will
+be from the 32-bit heap. Such a clause is not permitted
+for a general access type (declared with @code{access all} or
+@code{access constant}) as values of such types must be able to refer
+to any object of the designated type, including objects residing outside
+the 32-bit address range. Existing @w{Ada 83} code will not contain such
+type definitions, however, since general access types were introduced
+in @w{Ada 95}.
+
+@item
+Switches for @command{GNAT BIND} control whether the internal GNAT
+allocation routine @code{__gnat_malloc} uses 64-bit or 32-bit allocations.
+@cindex @code{__gnat_malloc}
+The switches are respectively @option{-H64} (the default) and
+@option{-H32}.
+@cindex @option{-H32} (@command{gnatbind})
+@cindex @option{-H64} (@command{gnatbind})
+
+@item
+The environment variable (logical name) @code{GNAT$NO_MALLOC_64}
+@cindex @code{GNAT$NO_MALLOC_64} environment variable
+may be used to force @code{__gnat_malloc} to use 32-bit allocation.
+If this variable is left
+undefined, or defined as @code{"DISABLE"}, @code{"FALSE"}, or @code{"0"},
+then the default (64-bit) allocation is used.
+If defined as @code{"ENABLE"}, @code{"TRUE"}, or @code{"1"},
+then 32-bit allocation is used. The gnatbind qualifiers described above
+override this logical name.
+
+@item
+A ^gcc switch^gcc switch^ for OpenVMS, @option{-mno-malloc64}, operates
+@cindex @option{-mno-malloc64} (^gcc^gcc^)
+at a low level to convert explicit calls to @code{malloc} and related
+functions from the C run-time library so that they perform allocations
+in the 32-bit heap.
+Since all internal allocations from GNAT use @code{__gnat_malloc},
+this switch is not required unless the program makes explicit calls on
+@code{malloc} (or related functions) from interfaced C code.
+@end itemize
-General access types (declared with @code{access all}) can never be
-32 bits, as values of such types must be able to refer to any object
-of the designated type,
-including objects residing outside the 32-bit address range.
-Existing Ada 83 code will not contain such type definitions,
-however, since general access types were introduced in Ada 95.
@node Unchecked conversions
@subsubsection Unchecked conversions
for int_star'Size use 64; -- Necessary to get 64 and not 32 bits
@end smallexample
+@node 32/64-bit descriptors
+@subsubsection 32/64-bit descriptors
+
+@noindent
+By default, GNAT uses a 64-bit descriptor mechanism. For an imported
+subprogram (i.e., a subprogram identified by pragma @code{Import_Function},
+@code{Import_Procedure}, or @code{Import_Valued_Procedure}) that specifies
+@code{Short_Descriptor} as its mechanism, a 32-bit descriptor is used.
+@cindex @code{Short_Descriptor} mechanism for imported subprograms
+
+If the configuration pragma @code{Short_Descriptors} is supplied, then
+all descriptors will be 32 bits.
+@cindex pragma @code{Short_Descriptors}
+
@node Experience with source compatibility
@subsubsection Experience with source compatibility
* Making code 64 bit clean::
* Allocating memory from the 64 bit storage pool::
* Restrictions on use of 64 bit objects::
-* Using 64 bit storage pools by default::
-* General access types::
* STARLET and other predefined libraries::
@end menu
@subsubsection Allocating memory from the 64-bit storage pool
@noindent
-For any access type @code{T} that potentially requires memory allocations
-beyond the 32-bit address space,
-use the following representation clause:
-
-@smallexample @c ada
- for T'Storage_Pool use System.Pool_64;
-@end smallexample
+By default, all allocations -- for both pool-specific and general
+access types -- use the 64-bit storage pool. To override
+this default, for an individual access type or globally, see
+@ref{Access types and 32/64-bit allocation}.
@node Restrictions on use of 64 bit objects
@subsubsection Restrictions on use of 64-bit objects
no exception is raised and execution
will become erroneous.
-@node Using 64 bit storage pools by default
-@subsubsection Using 64-bit storage pools by default
-
-@noindent
-In some cases it may be desirable to have the compiler allocate
-from 64-bit storage pools by default. This may be the case for
-libraries that are 64-bit clean, but may be used in both 32-bit
-and 64-bit contexts. For these cases the following configuration
-pragma may be specified:
-
-@smallexample @c ada
- pragma Pool_64_Default;
-@end smallexample
-
-@noindent
-Any code compiled in the context of this pragma will by default
-use the @code{System.Pool_64} storage pool. This default may be overridden
-for a specific access type @code{T} by the representation clause:
-
-@smallexample @c ada
- for T'Storage_Pool use System.Pool_32;
-@end smallexample
-
-@noindent
-Any object whose address may be passed to a subprogram with a
-@code{Short_Address} argument, or assigned to a variable of type
-@code{Short_Address}, needs to be allocated from this pool.
-
-@node General access types
-@subsubsection General access types
-
-@noindent
-Objects designated by access values from a
-general access type (declared with @code{access all}) are never allocated
-from a 64-bit storage pool. Code that uses general access types will
-accept objects allocated in either 32-bit or 64-bit address spaces,
-but never allocate objects outside the 32-bit address space.
-Using general access types ensures maximum compatibility with both
-32-bit and 64-bit code.
-
@node STARLET and other predefined libraries
@subsubsection STARLET and other predefined libraries
* Windows Calling Conventions::
* Introduction to Dynamic Link Libraries (DLLs)::
* Using DLLs with GNAT::
-* Building DLLs with GNAT::
* Building DLLs with GNAT Project files::
+* Building DLLs with GNAT::
* Building DLLs with gnatdll::
* GNAT and Windows Resources::
* Debugging a DLL::
@item
It is not possible to link against Microsoft libraries except for
-import libraries. The library must be built to be compatible with
-@file{MSVCRT.LIB} (/MD Microsoft compiler option), @file{LIBC.LIB} and
-@file{LIBCMT.LIB} (/ML or /MT Microsoft compiler options) are known to
-not be compatible with the GNAT runtime. Even if the library is
-compatible with @file{MSVCRT.LIB} it is not guaranteed to work.
+import libraries. Interfacing must be done by the mean of DLLs.
@item
When the compilation environment is located on FAT32 drives, users may
If you use @command{gcc} to compile the non-Ada part of your application,
there are no Windows-specific restrictions that affect the overall
-interoperability with your Ada code. If you plan to use
-Microsoft tools (e.g.@: Microsoft Visual C/C++), you should be aware of
-the following limitations:
-
-@itemize @bullet
-@item
-You cannot link your Ada code with an object or library generated with
-Microsoft tools if these use the @code{.tls} section (Thread Local
-Storage section) since the GNAT linker does not yet support this section.
-
-@item
-You cannot link your Ada code with an object or library generated with
-Microsoft tools if these use I/O routines other than those provided in
-the Microsoft DLL: @code{msvcrt.dll}. This is because the GNAT run time
-uses the services of @code{msvcrt.dll} for its I/Os. Use of other I/O
-libraries can cause a conflict with @code{msvcrt.dll} services. For
-instance Visual C++ I/O stream routines conflict with those in
-@code{msvcrt.dll}.
-@end itemize
-
-@noindent
-If you do want to use the Microsoft tools for your non-Ada code and hit one
-of the above limitations, you have two choices:
+interoperability with your Ada code. If you do want to use the
+Microsoft tools for your non-Ada code, you have two choices:
@enumerate
@item
@item
Or you can encapsulate your Ada code in a DLL to be linked with the
other part of your application. In this case, use GNAT to build the DLL
-(@pxref{Building DLLs with GNAT}) and use the Microsoft or whatever
-environment to build your executable.
+(@pxref{Building DLLs with GNAT Project files}) and use the Microsoft
+or whatever environment to build your executable.
@end enumerate
@node Windows Calling Conventions
@findex Stdcall
@findex APIENTRY
+This section pertain only to Win32. On Win64 there is a single native
+calling convention. All convention specifiers are ignored on this
+platform.
+
@menu
* C Calling Convention::
* Stdcall Calling Convention::
@noindent
The argument @option{-largs -lAPI} at the end of the @command{gnatmake} command
-tells the GNAT linker to look first for a library named @file{API.lib}
-(Microsoft-style name) and if not found for a libraries named
-@file{libAPI.dll.a}, @file{API.dll.a} or @file{libAPI.a}.
-(GNAT-style name). Note that if the Ada package spec for @file{API.dll}
-contains the following pragma
+tells the GNAT linker to look for an import library. The linker will
+look for a library name in this specific order:
+
+@enumerate
+@item @file{libAPI.dll.a}
+@item @file{API.dll.a}
+@item @file{libAPI.a}
+@item @file{API.lib}
+@item @file{libAPI.dll}
+@item @file{API.dll}
+@end enumerate
+
+The first three are the GNU style import libraries. The third is the
+Microsoft style import libraries. The last two are the DLL themself.
+
+Note that if the Ada package spec for @file{API.dll} contains the
+following pragma
@smallexample @c ada
pragma Linker_Options ("-lAPI");
@noindent
Note that a variable is
-@strong{always imported with a Stdcall convention}. A function
+@strong{always imported with a DLL convention}. A function
can have @code{C} or @code{Stdcall} convention.
(@pxref{Windows Calling Conventions}).
@code{lib}.
@end enumerate
+@node Building DLLs with GNAT Project files
+@section Building DLLs with GNAT Project files
+@cindex DLLs, building
+
+@noindent
+There is nothing specific to Windows in the build process.
+@pxref{Library Projects}.
+
+@noindent
+Due to a system limitation, it is not possible under Windows to create threads
+when inside the @code{DllMain} routine which is used for auto-initialization
+of shared libraries, so it is not possible to have library level tasks in SALs.
+
@node Building DLLs with GNAT
@section Building DLLs with GNAT
@cindex DLLs, building
@item building the DLL
-To build the DLL you must use @command{gcc}'s @option{-shared}
-option. It is quite simple to use this method:
+To build the DLL you must use @command{gcc}'s @option{-shared} and
+@option{-shared-libgcc} options. It is quite simple to use this method:
@smallexample
-$ gcc -shared -o api.dll obj1.o obj2.o @dots{}
+$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o @dots{}
@end smallexample
It is important to note that in this case all symbols found in the
file, @pxref{The Definition File}. For example:
@smallexample
-$ gcc -shared -o api.dll api.def obj1.o obj2.o @dots{}
+$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o @dots{}
@end smallexample
If you use a definition file you must export the elaboration procedures
$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
@end smallexample
-@node Building DLLs with GNAT Project files
-@section Building DLLs with GNAT Project files
-@cindex DLLs, building
-
-@noindent
-There is nothing specific to Windows in the build process.
-@pxref{Library Projects}.
-
-@noindent
-Due to a system limitation, it is not possible under Windows to create threads
-when inside the @code{DllMain} routine which is used for auto-initialization
-of shared libraries, so it is not possible to have library level tasks in SALs.
-
@node Building DLLs with gnatdll
@section Building DLLs with gnatdll
@cindex DLLs, building
@end menu
@noindent
-Note that it is preferred to use the built-in GNAT DLL support
-(@pxref{Building DLLs with GNAT}) or GNAT Project files
-(@pxref{Building DLLs with GNAT Project files}) to build DLLs.
+Note that it is preferred to use GNAT Project files
+(@pxref{Building DLLs with GNAT Project files}) or the built-in GNAT
+DLL support (@pxref{Building DLLs with GNAT}) or to build DLLs.
This section explains how to build DLLs containing Ada code using
@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
@smallexample
@cartouche
-$ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
+@c $ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnatdll @r{[}@var{switches}@r{]} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
@end cartouche
@end smallexample
You may specify any of the following switches to @code{gnatdll}:
@table @code
-@item -a@ovar{address}
+@c @item -a@ovar{address}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+@item -a@r{[}@var{address}@r{]}
@cindex @option{-a} (@code{gnatdll})
Build a non-relocatable DLL at @var{address}. If @var{address} is not
specified the default address @var{0x11000000} will be used. By default,
is
@smallexample
-$ dlltool @ovar{switches}
+@c $ dlltool @ovar{switches}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ dlltool @r{[}@var{switches}@r{]}
@end smallexample
@noindent
@item
The program is built with @code{GCC/GNAT} and the DLL is built with
foreign tools.
-@item
@end enumerate
@noindent
OSDN Git Service
