@c o
@c G N A T _ U G N o
@c o
-@c Copyright (C) 1992-2010, AdaCore o
+@c Copyright (C) 1992-2012, Free Software Foundation, Inc. o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
* Stack Related Facilities::
* Verifying Properties Using gnatcheck::
* Creating Sample Bodies Using gnatstub::
+* Creating Unit Tests Using gnattest::
* Generating Ada Bindings for C and C++ headers::
* Other Utility Programs::
* Running and Debugging Ada Programs::
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
+* Vectorization of loops::
* Other Optimization Switches::
* Optimization and Strict Aliasing::
@ifset vms
Verifying Properties Using gnatcheck
-* 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::
-
Sample Bodies Using gnatstub
* Running gnatstub::
* Switches for gnatstub::
+Creating Unit Tests Using gnattest
+
+* Running gnattest::
+* Switches for gnattest::
+* Project Attributes for gnattest::
+* Simple Example::
+* Setting Up and Tearing Down the Testing Environment::
+* Regenerating Tests::
+* Default Test Behavior::
+* Testing Primitive Operations of Tagged Types::
+* Testing Inheritance::
+* Tagged Types Substitutability Testing::
+* Testing with Contracts::
+* Additional Tests::
+* Current Limitations::
+
Other Utility Programs
* Using Other Utility Programs with GNAT::
a utility that generates empty but compilable bodies for library units.
@item
+@ref{Creating Unit Tests Using gnattest}, discusses @code{gnattest},
+a utility that generates unit testing templates for library units.
+
+@item
@ref{Generating Ada Bindings for C and C++ headers}, describes how to
generate automatically Ada bindings from C and C++ headers.
@noindent
GNAT additionally provides a useful pragma @code{Convention_Identifier}
-that can be used to parametrize conventions and allow additional synonyms
+that can be used to parameterize conventions and allow additional synonyms
to be specified. For example if you have legacy code in which the convention
identifier Fortran77 was used for Fortran, you can use the configuration
pragma:
@item -fno-inline
@cindex @option{-fno-inline} (@command{gcc})
-Suppresses all back-end inlining, even if other optimization or inlining
-switches are set.
-This includes suppression of inlining that results
-from the use of the pragma @code{Inline_Always}.
+Suppresses all inlining, even if other optimization or inlining
+switches are set. This includes suppression of inlining that
+results from the use of the pragma @code{Inline_Always}.
Any occurrences of pragma @code{Inline} or @code{Inline_Always}
are ignored, and @option{-gnatn} and @option{-gnatN} have no
effect if this switch is present.
@item -fstack-usage
@cindex @option{-fstack-usage} (@command{gcc})
Makes the compiler output stack usage information for the program, on a
-per-function basis. See @ref{Static Stack Usage Analysis} for details.
+per-subprogram basis. See @ref{Static Stack Usage Analysis} for details.
@item -fcallgraph-info@r{[}=su@r{]}
@cindex @option{-fcallgraph-info} (@command{gcc})
@item -gnat2005
@cindex @option{-gnat2005} (@command{gcc})
-Allow full Ada 2005 features (same as @option{-gnat05}
+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}
+Allow full Ada 2012 features (same as @option{-gnat12})
@item -gnata
@cindex @option{-gnata} (@command{gcc})
Defines a symbol, associated with @var{value}, for preprocessing.
(@pxref{Integrated Preprocessing}).
+@item -gnateE
+@cindex @option{-gnateE} (@command{gcc})
+Generate extra information in exception messages. In particular, display
+extra column information and the value and range associated with index and
+range check failures, and extra column information for access checks.
+In cases where the compiler is able to determine at compile time that
+a check will fail, it gives a warning, and the extra information is not
+produced at run time.
+
@item -gnatef
@cindex @option{-gnatef} (@command{gcc})
Display full source path name in brief error messages.
@cindex @option{-gnateG} (@command{gcc})
Save result of preprocessing in a text file.
+@item ^-gnateI^/MULTI_UNIT_INDEX=^@var{nnn}
+@cindex @option{-gnateI} (@command{gcc})
+Indicates that the source is a multi-unit source and that the index of the
+unit to compile is @var{nnn}. @var{nnn} needs to be a positive number and need
+to be a valid index in the multi-unit source.
+
@item -gnatem=@var{path}
@cindex @option{-gnatem} (@command{gcc})
Specify a mapping file
@end ifclear
(@pxref{Integrated Preprocessing}).
+@item -gnateP
+@cindex @option{-gnateP} (@command{gcc})
+Turn categorization dependency errors into warnings.
+Ada requires that units that WITH one another have compatible categories, for
+example a Pure unit cannot WITH a Preelaborate unit. If this switch is used,
+these errors become warnings (which can be ignored, or suppressed in the usual
+manner). This can be useful in some specialized circumstances such as the
+temporary use of special test software.
@item -gnateS
@cindex @option{-gnateS} (@command{gcc})
Generate SCO (Source Coverage Obligation) information in the ALI
@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
@file{stderr} (standard error) giving the number of error messages and
warning messages generated.
-@item -^gnatl^OUTPUT_FILE^=file
-@cindex @option{^-gnatl^OUTPUT_FILE^=fname} (@command{gcc})
+@item ^-gnatl^/OUTPUT_FILE^=file
+@cindex @option{^-gnatl^/OUTPUT_FILE^=fname} (@command{gcc})
This has the same effect as @option{-gnatl} except that the output is
written to a file instead of to standard output. If the given name
@file{fname} does not start with a period, then it is the full name
of the file to be written. If @file{fname} is an extension, it is
appended to the name of the file being compiled. For example, if
-file @file{xyz.adb} is compiled with @option{^-gnatl^OUTPUT_FILE^=.lst},
+file @file{xyz.adb} is compiled with @option{^-gnatl^/OUTPUT_FILE^=.lst},
then the output is written to file ^xyz.adb.lst^xyz.adb_lst^.
@item -gnatU
@table @option
@c !sort!
@item -gnatwa
-@emph{Activate all optional errors.}
+@emph{Activate most optional warnings.}
@cindex @option{-gnatwa} (@command{gcc})
-This switch activates most optional warning messages, see remaining list
+This switch activates most optional warning messages. See the remaining list
in this section for details on optional warning messages that can be
individually controlled. The warnings that are not turned on by this
switch are
@option{-gnatwd} (implicit dereferencing),
@option{-gnatwh} (hiding),
+@option{-gnatw.h} (holes (gaps) in record layouts)
+@option{-gnatw.i} (overlapping actuals),
@option{-gnatwl} (elaboration warnings),
-@option{-gnatw.o} (warn on values set by out parameters ignored)
-and @option{-gnatwt} (tracking of deleted conditional code).
+@option{-gnatw.l} (inherited aspects),
+@option{-gnatw.o} (warn on values set by out parameters ignored),
+@option{-gnatwt} (tracking of deleted conditional code)
+and @option{-gnatw.u} (unordered enumeration),
All other optional warnings are turned on.
@item -gnatwA
@cindex @option{-gnatwA} (@command{gcc})
This switch suppresses all optional warning messages, see remaining list
in this section for details on optional warning messages that can be
-individually controlled.
+individually controlled. Note that unlike switch @option{-gnatws}, the
+use of switch @option{-gnatwA} does not suppress warnings that are
+normally given unconditionally and cannot be individually controlled
+(for example, the warning about a missing exit path in a function).
+Also, again unlike switch @option{-gnatws}, warnings suppressed by
+the use of switch @option{-gnatwA} can be individually turned back
+on. For example the use of switch @option{-gnatwA} followed by
+switch @option{-gnatwd} will suppress all optional warnings except
+the warnings for implicit dereferencing.
@item -gnatw.a
@emph{Activate warnings on failing assertions.}
@cindex @option{-gnatw.e} (@command{gcc})
@cindex Warnings, activate every optional warning
This switch activates all optional warnings, including those which
-are not activated by @code{-gnatwa}.
+are not activated by @code{-gnatwa}. The use of this switch is not
+recommended for normal use. If you turn this switch on, it is almost
+certain that you will get large numbers of useless warnings. The
+warnings that are excluded from @code{-gnatwa} are typically highly
+specialized warnings that are suitable for use only in code that has
+been specifically designed according to specialized coding rules.
@item -gnatwf
@emph{Activate warnings on unreferenced formals.}
@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})
See the section in this guide on elaboration checking for details on
when such pragmas should be used.
+@item -gnatw.l
+@emph{List inherited aspects.}
+@cindex @option{-gnatw.l} (@command{gcc})
+This switch causes the compiler to list inherited invariants,
+preconditions, and postconditions from Invariant'Class, Pre'Class, and
+Post'Class aspects. Also list inherited subtype predicates.
+These messages are not automatically turned on by the use of @option{-gnatwa}.
+
+@item -gnatw.L
+@emph{Suppress listing of inherited aspects.}
+@cindex @option{-gnatw.L} (@command{gcc})
+This switch suppresses listing of inherited aspects.
+
@item -gnatwm
@emph{Activate warnings on modified but unreferenced variables.}
@cindex @option{-gnatwm} (@command{gcc})
The cases caught are where the size is the same as the modulus (e.g.
a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64
with no size clause. The guess in both cases is that 2**x was intended
-rather than x. The default is that these warnings are given.
+rather than x. In addition expressions of the form 2*x for small x
+generate a warning (the almost certainly accurate guess being that
+2**x was intended). The default is that these warnings are given.
@item -gnatw.M
@emph{Disable warnings on suspicious modulus values.}
@emph{Suppress all warnings.}
@cindex @option{-gnatws} (@command{gcc})
This switch completely suppresses the
-output of all warning messages from the GNAT front end.
-Note that it does not suppress warnings from the @command{gcc} back end.
+output of all warning messages from the GNAT front end, including
+both warnings that can be controlled by switches described in this
+section, and those that are normally given unconditionally. The
+effect of this suppress action can only be cancelled by a subsequent
+use of the switch @option{-gnatwn}.
+
+Note that switch @option{-gnatws} 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}. 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 overridden 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.}
@cindex @option{-gnatwt} (@command{gcc})
@cindex @option{-gnatwT} (@command{gcc})
This switch suppresses warnings for tracking of deleted conditional code.
+@item -gnatw.t
+@emph{Activate warnings on suspicious contracts.}
+@cindex @option{-gnatw.t} (@command{gcc})
+This switch activates warnings on suspicious postconditions (whether a
+pragma @code{Postcondition} or a @code{Post} aspect in Ada 2012). A
+function postcondition is suspicious when it does not mention the result
+of the function. A procedure postcondition is suspicious when it only
+refers to the pre-state of the procedure, because in that case it should
+rather be expressed as a precondition. The default is that such warnings
+are not generated. This warning can also be turned on using @option{-gnatwa}.
+
+@item -gnatw.T
+@emph{Suppress warnings on suspicious contracts.}
+@cindex @option{-gnatw.T} (@command{gcc})
+This switch suppresses warnings on suspicious postconditions.
+
@item -gnatwu
@emph{Activate warnings on unused entities.}
@cindex @option{-gnatwu} (@command{gcc})
are declared but not referenced, and for units that are @code{with}'ed
and not
referenced. In the case of packages, a warning is also generated if
-no entities in the package are referenced. This means that if the package
-is referenced but the only references are in @code{use}
+no entities in the package are referenced. This means that if a with'ed
+package is referenced but the only references are in @code{use}
clauses or @code{renames}
declarations, a warning is still generated. A warning is also generated
for a generic package that is @code{with}'ed but never instantiated.
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.
+The default is that such warnings are not generated.
+This warning is not automatically turned on by the use of @option{-gnatwa}.
@item -gnatw.U
@emph{Deactivate warnings on unordered enumeration types.}
@emph{Activate warnings on unnecessary Warnings Off pragmas}
@cindex @option{-gnatw.w} (@command{gcc})
@cindex Warnings Off control
-This switch activates warnings for use of @code{pragma Warnings (Off, entity}
+This switch activates warnings for use of @code{pragma Warnings (Off, entity)}
where either the pragma is entirely useless (because it suppresses no
warnings), or it could be replaced by @code{pragma Unreferenced} or
-@code{pragma Unmodified}.The default is that these warnings are not given.
+@code{pragma Unmodified}. The default is that these warnings are not given.
Note that this warning is not included in -gnatwa, it must be
activated explicitly.
@item -gnatw.W
@emph{Suppress warnings on unnecessary Warnings Off pragmas}
@cindex @option{-gnatw.W} (@command{gcc})
-This switch suppresses warnings for use of @code{pragma Warnings (Off, entity}.
+This switch suppresses warnings for use of @code{pragma Warnings (Off, entity)}.
@item -gnatwx
@emph{Activate warnings on Export/Import pragmas.}
(No_Exception_Propagation) is in effect.
@item -gnatwy
-@emph{Activate warnings for Ada 2005 compatibility issues.}
+@emph{Activate warnings for Ada compatibility issues.}
@cindex @option{-gnatwy} (@command{gcc})
-@cindex Ada 2005 compatibility issues warnings
-For the most part Ada 2005 is upwards compatible with Ada 95,
-but there are some exceptions (for example the fact that
-@code{interface} is now a reserved word in Ada 2005). This
+@cindex Ada compatibility issues warnings
+For the most part, newer versions of Ada are upwards compatible
+with older versions. For example, Ada 2005 programs will almost
+always work when compiled as Ada 2012.
+However there are some exceptions (for example the fact that
+@code{some} is now a reserved word in Ada 2012). This
switch activates several warnings to help in identifying
and correcting such incompatibilities. The default is that
these warnings are generated. Note that at one point Ada 2005
This warning can also be turned on using @option{-gnatwa}.
@item -gnatwY
-@emph{Disable warnings for Ada 2005 compatibility issues.}
+@emph{Disable warnings for Ada compatibility issues.}
@cindex @option{-gnatwY} (@command{gcc})
-@cindex Ada 2005 compatibility issues warnings
-This switch suppresses several warnings intended to help in identifying
-incompatibilities between Ada 95 and Ada 2005.
+@cindex Ada compatibility issues warnings
+This switch suppresses the warnings intended to help in identifying
+incompatibilities between Ada language versions.
@item -gnatwz
@emph{Activate warnings on unchecked conversions.}
the back end warning for uninitialized variables. This switch must be
used in conjunction with an optimization level greater than zero.
+@item -Wstack-usage=@var{len}
+@cindex @option{-Wstack-usage}
+Warn if the stack usage of a subprogram might be larger than @var{len} bytes.
+See @ref{Static Stack Usage Analysis} for details.
+
@item ^-Wall^/ALL_BACK_END_WARNINGS^
@cindex @option{-Wall}
-This switch enables all the above warnings from the @option{GCC} back end.
+This switch enables most warnings from the @option{GCC} back end.
The code generator detects a number of warning situations that are missed
by the @option{GNAT} front end, and this switch can be used to activate them.
The use of this switch also sets the default front end warning mode to
A string of warning parameters can be used in the same parameter. For example:
@smallexample
--gnatwaLe
+-gnatwaGe
@end smallexample
@noindent
-will turn on all optional warnings except for elaboration pragma warnings,
+will turn on all optional warnings except for unrecognized pragma warnings,
and also specify that warnings should be treated as errors.
@end ifclear
+
When no switch @option{^-gnatw^/WARNINGS^} is used, this is equivalent to:
@table @option
@c !sort!
+@item -gnatwB
+@item -gnatw.b
@item -gnatwC
+@item -gnatw.C
@item -gnatwD
@item -gnatwF
@item -gnatwg
@item -gnatwH
@item -gnatwi
+@item -gnatw.I
@item -gnatwJ
@item -gnatwK
@item -gnatwL
+@item -gnatw.L
@item -gnatwM
+@item -gnatw.m
@item -gnatwn
@item -gnatwo
+@item -gnatw.O
@item -gnatwP
+@item -gnatw.P
+@item -gnatwq
@item -gnatwR
+@item -gnatw.R
+@item -gnatw.S
+@item -gnatwT
+@item -gnatw.T
@item -gnatwU
@item -gnatwv
-@item -gnatwz
+@item -gnatww
+@item -gnatw.W
@item -gnatwx
+@item -gnatw.X
+@item -gnatwy
+@item -gnatwz
@end table
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
@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.
+boolean constants. In all other cases @code{and then}/@code{or else} are
+required.
@item ^c^COMMENTS^
-@emph{Check comments.}
+@emph{Check comments, double space.}
Comments must meet the following set of rules:
@itemize @bullet
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
@end smallexample
@end itemize
+@item ^C^COMMENTS1^
+@emph{Check comments, single space.}
+This is identical to @code{^c^COMMENTS^} except that only one space
+is required following the @code{--} of a comment instead of two.
+
@item ^d^DOS_LINE_ENDINGS^
@emph{Check no DOS line terminators present.}
All lines must be terminated by a single ASCII.LF
in the source text.
@item ^g^GNAT^
-@emph{GNAT style mode}
+@emph{GNAT style mode.}
The set of style check switches is set to match that used by the GNAT sources.
This may be useful when developing code that is eventually intended to be
incorporated into GNAT. For further details, see GNAT sources.
containing all or part of the condition to be tested.
@item ^I^IN_MODE^
-@emph{check mode IN keywords}
+@emph{check mode IN keywords.}
Mode @code{in} (the default mode) is not
allowed to be given explicitly. @code{in out} is fine,
but not @code{in} on its own.
@end smallexample
@item ^Lnnn^MAX_NESTING=nnn^
-@emph{Set maximum nesting level}
+@emph{Set maximum nesting level.}
The maximum level of nesting of constructs (including subprograms, loops,
blocks, packages, and conditionals) may not exceed the given value
@option{nnn}. A value of zero disconnects this style check.
@code{Integer} and @code{ASCII.NUL}).
@item ^N^NONE^
-@emph{Turn off all style checks}
+@emph{Turn off all style checks.}
All style check options are turned off.
@item ^o^ORDERED_SUBPROGRAMS^
identifiers. The only requirement is for consistency of references
with declarations.
-@item ^S^STATEMENTS_AFTER_THEN_ELSE^
-@emph{Check no statements after THEN/ELSE.}
-No statements are allowed
-on the same line as a THEN or ELSE keyword following the
-keyword in an IF statement. OR ELSE and AND THEN are not affected,
-and a special exception allows a pragma to appear after ELSE.
-
@item ^s^SPECS^
@emph{Check separate specs.}
Separate declarations (``specs'') are required for subprograms (a
not required to have a separate declaration. This exception covers
the most frequent form of main program procedures.
+@item ^S^STATEMENTS_AFTER_THEN_ELSE^
+@emph{Check no statements after @code{then}/@code{else}.}
+No statements are allowed
+on the same line as a @code{then} or @code{else} keyword following the
+keyword in an @code{if} statement. @code{or else} and @code{and then} are not
+affected, and a special exception allows a pragma to appear after @code{else}.
+
@item ^t^TOKEN^
@emph{Check token spacing.}
The following token spacing rules are enforced:
@itemize @bullet
@item
-The keywords @code{@b{abs}} and @code{@b{not}} must be followed by a space.
+The keywords @code{abs} and @code{not} must be followed by a space.
@item
The token @code{=>} must be surrounded by spaces.
@item ^y^ALL_BUILTIN^
@emph{Set all standard style check options}
This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
-options enabled with the exception of @option{-gnatyo}, @option{-gnatyI},
-@option{-gnatyS}, @option{-gnatyLnnn},
-@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
+options enabled with the exception of @option{-gnatyB}, @option{-gnatyd},
+@option{-gnatyI}, @option{-gnatyLnnn}, @option{-gnatyo}, @option{-gnatyO},
+@option{-gnatyS}, @option{-gnatyu}, and @option{-gnatyx}.
@ifclear vms
@item -
The switch
@ifclear vms
@option{-gnaty} on its own (that is not
-followed by any letters or digits), then the effect is equivalent
-to the use of @option{-gnatyy}, as described above, that is all
+followed by any letters or digits) is equivalent
+to the use of @option{-gnatyy} as described above, that is all
built-in standard style check options are enabled.
@end ifclear
@option{-gnat83} and @option{-gnat95} switches for further
information).
+@ifset PROEDITION
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).
+@end ifset
@item -gnat12 or -gnat2012 (Ada 2012 mode)
@cindex @option{-gnat12} (@command{gcc})
for further information).
For information about the approved ``Ada Issues'' that have been incorporated
-into Ada 2012, see @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}.
+into Ada 2012, see @url{http://www.ada-auth.org/ais.html}.
Included with GNAT releases is a file @file{features-ada12} that describes
the set of implemented Ada 2012 features.
since brackets encoding is always recognized, it may be conveniently
used in standard libraries, allowing these libraries to be used with
any of the available coding schemes.
-scheme.
+
+Note that brackets encoding only applies to program text. Within comments,
+brackets are considered to be normal graphic characters, and bracket sequences
+are never recognized as wide characters.
If no @option{-gnatW?} parameter is present, then the default
representation is normally Brackets encoding only. However, if the
parameter.
@end table
+
+When no @option{-gnatW?} is specified, then characters (other than wide
+characters represented using brackets notation) are treated as 8-bit
+Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
+and ASCII format effectors (CR, LF, HT, VT). Other lower half control
+characters in the range 16#00#..16#1F# are not accepted in program text
+or in comments. Upper half control characters (16#80#..16#9F#) are rejected
+in program text, but allowed and ignored in comments. Note in particular
+that the Next Line (NEL) character whose encoding is 16#85# is not recognized
+as an end of line in this default mode. If your source program contains
+instances of the NEL character used as a line terminator,
+you must use UTF-8 encoding for the whole
+source program. In default mode, all lines must be ended by a standard
+end of line sequence (CR, CR/LF, or LF).
+
+Note that the convention of simply accepting all upper half characters in
+comments means that programs that use standard ASCII for program text, but
+UTF-8 encoding for comments are accepted in default mode, providing that the
+comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator.
+This is a common mode for many programs with foreign language comments.
+
@node File Naming Control
@subsection File Naming Control
@cindex @option{-gnatep} (@command{gcc})
This switch indicates to the compiler the file name (without directory
information) of the preprocessor data file to use. The preprocessor data file
-should be found in the source directories.
+should be found in the source directories. Note that when the compiler is
+called by a builder (@command{gnatmake} or @command{gprbuild}) with a project
+file, if the object directory is not also a source directory, the builder needs
+to be called with @option{-x}.
@noindent
A preprocessing data file is a text file with significant lines indicating
Use of these @option{-m} switches may in some cases result in improved
code performance.
-The GNAT Pro technology is tested and qualified without any
+The @value{EDITION} technology is tested and qualified without any
@option{-m} switches,
so generally the most reliable approach is to avoid the use of these
switches. However, we generally expect most of these switches to work
-successfully with GNAT Pro, and many customers have reported successful
+successfully with @value{EDITION}, and many customers have reported successful
use of these options.
Our general advice is to avoid the use of @option{-m} switches unless
* 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{^-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{^-H64^/64_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.
@cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@command{gnatbind})
Pessimistic (worst-case) elaboration order
+@item ^-P^-P^
+@cindex @option{^-P^/CODEPEER^} (@command{gnatbind})
+Generate binder file suitable for CodePeer.
+
@item ^-R^-R^
@cindex @option{^-R^-R^} (@command{gnatbind})
Output closure source list.
These implicit pragmas are still respected by the binder in
@option{^-p^/PESSIMISTIC_ELABORATION^} mode, so a
safe elaboration order is assured.
+
+Note that @option{^-p^/PESSIMISTIC_ELABORATION^} is not intended for
+production use; it is more for debugging/experimental use.
@end table
@node Output Control
@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
switches.
The default linker called by gnatlink is @command{gcc} which in
turn calls the appropriate system linker.
+
+One useful option for the linker is @option{-s}: it reduces the size of the
+executable by removing all symbol table and relocation information from the
+executable.
+
Standard options for the linker such as @option{-lmy_lib} or
@option{-Ldir} can be added as is.
For options that are not recognized by
@command{gcc} as linker options, use the @command{gcc} switches
@option{-Xlinker} or @option{-Wl,}.
+
Refer to the GCC documentation for
-details. Here is an example showing how to generate a linker map:
+details.
+
+Here is an example showing how to generate a linker map:
@smallexample
$ ^gnatlink my_prog -Wl,-Map,MAPFILE^GNAT LINK my_prog.ali /MAP^
for further details. You would normally use the @option{-b} or
@option{-V} switch instead.
+@item -M
+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 -M=mapfile
+When linking an executable, create a map file. The name of the map file is
+"mapfile".
+
@item --GCC=@var{compiler_name}
@cindex @option{--GCC=compiler_name} (@command{gnatlink})
Program used for compiling the binder file. The default is
projects. When this switch is used on the command line, this restriction is
relaxed.
+@item ^--source-info=<source info file>^/SRC_INFO=source-info-file^
+Specify a source info file. This switch is active only when project files
+are used. If the source info file is specified as a relative path, then it is
+relative to the object directory of the main project. If the source info file
+does not exist, then after the Project Manager has successfully parsed and
+processed the project files and found the sources, it creates the source info
+file. If the source info file already exists and can be read successfully,
+then the Project Manager will get all the needed information about the sources
+from the source info file and will not look for them. This reduces the time
+to process the project files, especially when looking for sources that take a
+long time. If the source info file exists but cannot be parsed successfully,
+the Project Manager will attempt to recreate it. If the Project Manager fails
+to create the source info file, a message is issued, but gnatmake does not
+fail. @command{gnatmake} "trusts" the source info file. This means that
+if the source files have changed (addition, deletion, moving to a different
+source directory), then the source info file need to be deleted and recreated.
+
@ifclear vms
@item --create-map-file
When linking an executable, create a map file. The name of the map file
This switch cannot be used when using a project file.
+@item -eInnn
+@cindex @option{-eI} (@command{gnatmake})
+Indicates that the main source is a multi-unit source and the rank of the unit
+in the source file is nnn. nnn needs to be a positive number and a valid
+index in the source. This switch cannot be used when @command{gnatmake} is
+invoked for several mains.
+
@ifclear vms
@item -eL
@cindex @option{-eL} (@command{gnatmake})
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
+When you do not have to use this switch (i.e.@: 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.
It then documents the @command{gnatelim} tool and unused subprogram/data
elimination feature, which can reduce the size of program executables.
-Note: to invoke @command{gnatelim} with a project file, use the @code{gnat}
-driver (see @ref{The GNAT Driver and Project Files}).
-
@ifnottex
@menu
* Performance Considerations::
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
+* Vectorization of loops::
* Other Optimization Switches::
* Optimization and Strict Aliasing::
@item ^-O3^/OPTIMIZE=INLINING^
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.
+(@pxref{Inlining of Subprograms}) and attempts to vectorize loops.
@item ^-Os^/OPTIMIZE=SPACE^
Optimize space usage (code and data) of resulting program.
@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 optimization
-level @option{-O2} is specified, or automatic inlining (optimization level
-@option{-O3}) is specified.
+Any one of the following applies: @code{pragma Inline} is applied to the
+subprogram and the @option{^-gnatn^/INLINE^} switch is specified; the
+subprogram is local to the unit and called once from within it; the
+subprogram is small and optimization level @option{-O2} is specified;
+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
@option{-O2}, and indeed you should use @option{-O3} only if tests show that
it actually improves performance.
+@node Vectorization of loops
+@subsection Vectorization of loops
+@cindex Optimization Switches
+
+You can take advantage of the auto-vectorizer present in the @command{gcc}
+back end to vectorize loops with GNAT. The corresponding command line switch
+is @option{-ftree-vectorize} but, as it is enabled by default at @option{-O3}
+and other aggressive optimizations helpful for vectorization also are enabled
+by default at this level, using @option{-O3} directly is recommended.
+
+You also need to make sure that the target architecture features a supported
+SIMD instruction set. For example, for the x86 architecture, you should at
+least specify @option{-msse2} to get significant vectorization (but you don't
+need to specify it for x86-64 as it is part of the base 64-bit architecture).
+Similarly, for the PowerPC architecture, you should specify @option{-maltivec}.
+
+The preferred loop form for vectorization is the @code{for} iteration scheme.
+Loops with a @code{while} iteration scheme can also be vectorized if they are
+very simple, but the vectorizer will quickly give up otherwise. With either
+iteration scheme, the flow of control must be straight, in particular no
+@code{exit} statement may appear in the loop body. The loop may however
+contain a single nested loop, if it can be vectorized when considered alone:
+
+@smallexample @c ada
+@cartouche
+ A : array (1..4, 1..4) of Long_Float;
+ S : array (1..4) of Long_Float;
+
+ procedure Sum is
+ begin
+ for I in A'Range(1) loop
+ for J in A'Range(2) loop
+ S (I) := S (I) + A (I, J);
+ end loop;
+ end loop;
+ end Sum;
+@end cartouche
+@end smallexample
+
+The vectorizable operations depend on the targeted SIMD instruction set, but
+the adding and some of the multiplying operators are generally supported, as
+well as the logical operators for modular types. Note that, in the former
+case, enabling overflow checks, for example with @option{-gnato}, totally
+disables vectorization. The other checks are not supposed to have the same
+definitive effect, although compiling with @option{-gnatp} might well reveal
+cases where some checks do thwart vectorization.
+
+Type conversions may also prevent vectorization if they involve semantics that
+are not directly supported by the code generator or the SIMD instruction set.
+A typical example is direct conversion from floating-point to integer types.
+The solution in this case is to use the following idiom:
+
+@smallexample @c ada
+ Integer (S'Truncation (F))
+@end smallexample
+
+@noindent
+if @code{S} is the subtype of floating-point object @code{F}.
+
+In most cases, the vectorizable loops are loops that iterate over arrays.
+All kinds of array types are supported, i.e. constrained array types with
+static bounds:
+
+@smallexample @c ada
+ type Array_Type is array (1 .. 4) of Long_Float;
+@end smallexample
+
+@noindent
+constrained array types with dynamic bounds:
+
+@smallexample @c ada
+ type Array_Type is array (1 .. Q.N) of Long_Float;
+
+ type Array_Type is array (Q.K .. 4) of Long_Float;
+
+ type Array_Type is array (Q.K .. Q.N) of Long_Float;
+@end smallexample
+
+@noindent
+or unconstrained array types:
+
+@smallexample @c ada
+ type Array_Type is array (Positive range <>) of Long_Float;
+@end smallexample
+
+@noindent
+The quality of the generated code decreases when the dynamic aspect of the
+array type increases, the worst code being generated for unconstrained array
+types. This is so because, the less information the compiler has about the
+bounds of the array, the more fallback code it needs to generate in order to
+fix things up at run time.
+
+You can obtain information about the vectorization performed by the compiler
+by specifying @option{-ftree-vectorizer-verbose=N}. For more details of
+this switch, see @ref{Debugging Options,,Options for Debugging Your Program
+or GCC, gcc, Using the GNU Compiler Collection (GCC)}.
+
@node Other Optimization Switches
@subsection Other Optimization Switches
@cindex Optimization Switches
Since @code{GNAT} uses the @command{gcc} back end, all the specialized
@command{gcc} optimization switches are potentially usable. These switches
have not been extensively tested with GNAT but can generally be expected
-to work. Examples of switches in this category are
-@option{-funroll-loops} and
-the various target-specific @option{-m} options (in particular, it has been
-observed that @option{-march=pentium4} can significantly improve performance
+to work. Examples of switches in this category are @option{-funroll-loops}
+and the various target-specific @option{-m} options (in particular, it has
+been observed that @option{-march=xxx} can significantly improve performance
on appropriate machines). For full details of these switches, see
@ref{Submodel Options,, Hardware Models and Configurations, gcc, Using
the GNU Compiler Collection (GCC)}.
@item ^--no-elim-dispatch^/NO_DISPATCH^
Do not generate pragmas for dispatching operations.
+@item ^--ignore^/IGNORE^=@var{filename}
+@cindex @option{^--ignore^/IGNORE^} (@command{gnatelim})
+Do not generate pragmas for subprograms declared in the sources
+listed in a specified file
+
@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,
@item ^-wq^/WARNINGS=QUIET^
@cindex @option{^-wq^/WARNINGS=QUIET^} (@command{gnatelim})
-Quet warning mode - some warnings are suppressed. In particular warnings that
+Quiet 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
+Note: to invoke @command{gnatelim} with a project file, use the @code{gnat}
+driver (see @ref{The GNAT Driver and Project Files}).
+
@node Processing Precompiled Libraries
@subsection Processing Precompiled Libraries
Ada_2005
Ada_12
Ada_2012
+ Annotate
Assertion_Policy
Assume_No_Invalid_Values
C_Pass_By_Copy
Convention_Identifier
Debug_Policy
Detect_Blocking
+ Default_Storage_Pool
Discard_Names
Elaboration_Checks
Eliminate
@section Handling of Configuration Pragmas
Configuration pragmas may either appear at the start of a compilation
-unit, in which case they apply only to that unit, or they may apply to
+unit, or they can appear in a configuration pragma file to apply to
all compilations performed in a given compilation environment.
GNAT also provides the @code{gnatchop} utility to provide an automatic
@file{gnat.adc} file that contains configuration pragmas directly,
as described in the following section.
+In the case of @code{Restrictions} pragmas appearing as configuration
+pragmas in individual compilation units, the exact handling depends on
+the type of restriction.
+
+Restrictions that require partition-wide consistency (like
+@code{No_Tasking}) are
+recognized wherever they appear
+and can be freely inherited, e.g. from a with'ed unit to the with'ing
+unit. This makes sense since the binder will in any case insist on seeing
+consistent use, so any unit not conforming to any restrictions that are
+anywhere in the partition will be rejected, and you might as well find
+that out at compile time rather than at bind time.
+
+For restrictions that do not require partition-wide consistency, e.g.
+SPARK or No_Implementation_Attributes, in general the restriction applies
+only to the unit in which the pragma appears, and not to any other units.
+
+The exception is No_Elaboration_Code which always applies to the entire
+object file from a compilation, i.e. to the body, spec, and all subunits.
+This restriction can be specified in a configuration pragma file, or it
+can be on the body and/or the spec (in eithe case it applies to all the
+relevant units). It can appear on a subunit only if it has previously
+appeared in the body of spec.
+
@node The Configuration Pragmas Files
@section The Configuration Pragmas Files
@cindex @file{gnat.adc}
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.
+is 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
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
+(see @ref{The GNAT Driver and Project Files}).
The @command{gnatpp} command has the form
@item ^-nM^/NAME_CASING=MIXED_CASE^
Names are in mixed case
+@cindex @option{^-ne@var{x}^/ENUM_CASING^} (@command{gnatpp})
+@item ^-neD^/ENUM_CASING=AS_DECLARED^
+Enumeration literal casing for defining occurrences are as they appear in the
+source file. Overrides ^-n^/NAME_CASING^ casing setting.
+
+@item ^-neU^/ENUM_CASING=UPPER_CASE^
+Enumeration literals are in upper case. Overrides ^-n^/NAME_CASING^ casing
+setting.
+
+@item ^-neL^/ENUM_CASING=LOWER_CASE^
+Enumeration literals are in lower case. Overrides ^-n^/NAME_CASING^ casing
+setting.
+
+@item ^-neM^/ENUM_CASING=MIXED_CASE^
+Enumeration literals are in mixed case. Overrides ^-n^/NAME_CASING^ casing
+setting.
+
+@cindex @option{^-nt@var{x}^/TYPE_CASING^} (@command{gnatpp})
+@item ^-neD^/TYPE_CASING=AS_DECLARED^
+Names introduced by type and subtype declarations are always
+cased as they appear in the declaration in the source file.
+Overrides ^-n^/NAME_CASING^ casing setting.
+
+@item ^-ntU^/TYPE_CASING=UPPER_CASE^
+Names introduced by type and subtype declarations are always in
+upper case. Overrides ^-n^/NAME_CASING^ casing setting.
+
+@item ^-ntL^/TYPE_CASING=LOWER_CASE^
+Names introduced by type and subtype declarations are always in
+lower case. Overrides ^-n^/NAME_CASING^ casing setting.
+
+@item ^-ntM^/TYPE_CASING=MIXED_CASE^
+Names introduced by type and subtype declarations are always in
+mixed case. Overrides ^-n^/NAME_CASING^ casing setting.
+
@cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp})
@item ^-pL^/PRAGMA_CASING=LOWER_CASE^
Pragma names are lower case
@item ^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^
Keep unchanged special form comments
-Reformat comment blocks
-
@cindex @option{^-l@var{n}^/CONSTRUCT_LAYOUT^} (@command{gnatpp})
@item ^-l1^/CONSTRUCT_LAYOUT=GNAT^
GNAT-style layout (this is 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.
+
+@item ^--call_threshold=@var{nnn}^/MAX_ACT=@var{nnn}^
+@cindex @option{^--call_threshold^/MAX_ACT^} (@command{gnatpp})
+If the number of parameter associations is greater than @var{nnn} and if at
+least one association uses named notation, start each association from
+a new line. If @var{nnn} is 0, no check for the number of associations
+is made, this is the default.
+
+@item ^--par_threshold=@var{nnn}^/MAX_PAR=@var{nnn}^
+@cindex @option{^--par_threshold^/MAX_PAR^} (@command{gnatpp})
+If the number of parameter specifications is greater than @var{nnn}
+(or equal to @var{nnn} in case of a function), start each specification from
+a new line. The default for @var{nnn} is 3.
@end table
@node Setting the Source Search Path
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.
+through the @command{gnat} driver (see @ref{The GNAT Driver and Project Files}).
The @command{gnatmetric} command has the form
* Line Metrics Control::
* Syntax Metrics Control::
* Complexity Metrics Control::
-* Object-Oriented Metrics Control::
+* Coupling Metrics Control::
@end menu
@node Line Metrics Control
@table @emph
@item LSLOC (``Logical Source Lines Of Code'')
-The total number of declarations and the total number of statements
+The total number of declarations and the total number of statements. Note
+that the definition of declarations is the one given in the reference
+manual:
+
+@noindent
+``Each of the following is defined to be a declaration: any basic_declaration;
+an enumeration_literal_specification; a discriminant_specification;
+a component_declaration; a loop_parameter_specification; a
+parameter_specification; a subprogram_body; an entry_declaration;
+an entry_index_specification; a choice_parameter_specification;
+a generic_formal_parameter_declaration.''
+
+This means for example that each enumeration literal adds one to the count,
+as well as each subprogram parameter.
+
+Thus the results from this metric will be significantly greater than might
+be expected from a naive view of counting semicolons.
@item Maximal static nesting level of inner program units
According to
McCabe essential complexity;
@item
-maximal loop nesting level
+maximal loop nesting level;
+@item
+extra exit points (for subprograms);
@end itemize
@noindent
-The McCabe complexity metrics are defined
-in @url{http://www.mccabe.com/pdf/nist235r.pdf}
+The McCabe cyclomatic complexity metric is defined
+in @url{http://www.mccabe.com/pdf/mccabe-nist235r.pdf}
According to McCabe, both control statements and short-circuit control forms
should be taken into account when computing cyclomatic complexity. For each
@end itemize
@noindent
+
+The origin of cyclomatic complexity metric is the need to estimate the number
+of independent paths in the control flow graph that in turn gives the number
+of tests needed to satisfy paths coverage testing completeness criterion.
+Considered from the testing point of view, a static Ada @code{loop} (that is,
+the @code{loop} statement having static subtype in loop parameter
+specification) does not add to cyclomatic complexity. By providing
+@option{^--no-static-loop^NO_STATIC_LOOP^} option a user
+may specify that such loops should not be counted when computing the
+cyclomatic complexity metric
+
+The Ada essential complexity metric is a McCabe cyclomatic complexity metric
+counted for the code that is reduced by excluding all the pure structural Ada
+control statements. An compound statement is considered as a non-structural
+if it contains a @code{raise} or @code{return} statement as it subcomponent,
+or if it contains a @code{goto} statement that transfers the control outside
+the operator. A selective accept statement with @code{terminate} alternative
+is considered as non-structural statement. When computing this metric,
+@code{exit} statements are treated in the same way as @code{goto}
+statements unless @option{^-ne^NO_EXITS_AS_GOTOS^} option is specified.
+
+The Ada essential complexity metric defined here is intended to quantify
+the extent to which the software is unstructured. It is adapted from
+the McCabe essential complexity metric defined in
+http://www.mccabe.com/pdf/nist235r.pdf but is modified to be more
+suitable for typical Ada usage. For example, short circuit forms
+are not penalized as unstructured in the Ada essential complexity metric.
+
When computing cyclomatic and essential complexity, @command{gnatmetric} skips
the code in the exception handlers and in all the nested program units.
Do not consider @code{exit} statements as @code{goto}s when
computing Essential Complexity
+@cindex @option{^--no-static-loop^/NO_STATIC_LOOP^} (@command{gnatmetric})
+@item ^--no-static-loop^/NO_STATIC_LOOP^
+Do not consider static loops when computing cyclomatic 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
@end table
-@node Object-Oriented Metrics Control
-@subsubsection Object-Oriented Metrics Control
-@cindex Object-Oriented metrics control in @command{gnatmetric}
+@node Coupling Metrics Control
+@subsubsection Coupling Metrics Control
+@cindex Coupling 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
+Coupling metrics measure the dependencies between a given entity and other
+entities the program consists of. The goal of these metrics is to estimate the
+stability of the whole program considered as the collection of entities
+(modules, classes etc.).
+
+Gnatmetric computes the following coupling metrics:
+
+@itemize @bullet
+
+@item
+@emph{object-oriented coupling} - for classes in traditional object-oriented
+sense;
+
+@item
+@emph{unit coupling} - for all the program units making up a program;
+
+@item
+@emph{control coupling} - this metric counts dependencies between a unit and
+only those units that define subprograms;
+@end itemize
+
+@noindent
+Two kinds of coupling metrics are computed:
+
+@table @asis
+@item fan-out coupling (efferent coupling)
+@cindex fan-out coupling
+@cindex efferent coupling
+the number of entities the given entity depends upon. It
+estimates in what extent the given entity depends on the changes in
+``external world''
+
+@item fan-in coupling (afferent coupling)
+@cindex fan-in coupling
+@cindex afferent coupling
+the number of entities that depend on a given entity.
+It estimates in what extent the ``external world'' depends on the changes in a
+given entity
+@end table
+
+@noindent
+
+Object-oriented coupling metrics are metrics that measure the dependencies
+between a given class (or a group of classes) and the other classes in the
+program. In this subsection the term ``class'' is used in its traditional
+object-oriented programming sense (an instantiable module that contains data
+and/or method members). A @emph{category} (of classes) is a group of closely
+related classes that are reused and/or modified together.
+
+A class @code{K}'s fan-out coupling is the number of classes
that @code{K} depends upon.
-A category's efferent coupling is the number of classes outside the
+A category's fan-out 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
+A class @code{K}'s fan-in coupling is the number of classes
that depend upon @code{K}.
-A category's afferent coupling is the number of classes outside the
+A category's fan-in 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
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.
+or interface types. That is a
+category is an Ada hierarchy of library-level program units. So class coupling
+in case of Ada is called as tagged coupling, and category coupling - as
+hierarchy coupling.
+
+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 object-oriented coupling
+metrics, only dependencies on units that are considered as classes, are
+considered.
+
+For unit and control coupling also not compilation units but program units are
+counted. That is, for a package, its spec, its body and its subunits (if any)
+are considered as making up one unit, and the dependencies that are counted
+are the dependencies of all these compilation units collected together as
+the dependencies as a (whole) unit. And metrics are reported for spec
+compilation units only (or for a subprogram body unit in case if there is no
+separate spec for the given subprogram).
+
+For unit coupling, dependencies between all kinds of program units are
+considered. For control coupling, for each unit the dependencies of this unit
+upon units that define subprograms are counted, so control fan-out coupling
+is reported for all units, but control fan-in coupling - only for the units
+that define subprograms.
+
+
+
+
+
When computing coupling metrics, @command{gnatmetric} counts only
dependencies between units that are arguments of the gnatmetric call.
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.
+option (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})
+@cindex @option{--tagged-coupling@var{x}} (@command{gnatmetric})
+@cindex @option{--hierarchy-coupling@var{x}} (@command{gnatmetric})
+@cindex @option{--unit-coupling@var{x}} (@command{gnatmetric})
+@cindex @option{--control-coupling@var{x}} (@command{gnatmetric})
@end ifclear
@ifset vms
@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 ^--tagged-coupling-out^/COUPLING_METRICS=TAGGED_OUT^
+Report tagged (class) fan-out coupling
-@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT^
-Report package efferent coupling
+@item ^--tagged-coupling-in^/COUPLING_METRICS=TAGGED_IN^
+Report tagged (class) fan-in coupling
-@item ^--no-package-efferent-coupling^/COUPLING_METRICS=NOPACKAGE_EFFERENT^
-Do not report package efferent coupling
+@item ^--hierarchy-coupling-out^/COUPLING_METRICS=HIERARCHY_OUT^
+Report hierarchy (category) fan-out coupling
-@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT^
-Report package afferent coupling
+@item ^--hierarchy-coupling-in^/COUPLING_METRICS=HIERARCHY_IN^
+Report hierarchy (category) fan-in coupling
-@item ^--no-package-afferent-coupling^/COUPLING_METRICS=NOPACKAGE_AFFERENT^
-Do not report package afferent coupling
+@item ^--unit-coupling-out^/COUPLING_METRICS=UNIT_OUT^
+Report unit fan-out coupling
-@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT^
-Report category efferent coupling
+@item ^--unit-coupling-in^/COUPLING_METRICS=UNIT_IN^
+Report unit fan-in 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
+@item ^--control-coupling-out^/COUPLING_METRICS=CONTROL_OUT^
+Report control fan-out coupling
+@item ^--control-coupling-in^/COUPLING_METRICS=CONTROL_IN^
+Report control fan-in coupling
@end table
@node Other gnatmetric Switches
@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.
@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.
+object directory specified or defaulted in the project file.
@item ^--unchecked-shared-lib-imports^/UNCHECKED_SHARED_LIB_IMPORTS^
By default, shared library projects are not allowed to import static library
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
+@noindent
+It is also possible to build an encapsulated library where not only
+the code to elaborate and finalize the library is embedded but also
+ensuring that the library is linked only against static
+libraries. So an encapsulated library only depends on system
+libraries, all other code, including the GNAT runtime, is embedded. To
+build an encapsulated library the attribute
+@code{Library_Standalone} must be set to @code{encapsulated}:
+
+@smallexample @c projectfile
+@group
+ for Library_Dir use "lib_dir";
+ for Library_Name use "dummy";
+ for Library_Interface use ("int1", "int1.child");
+ for Library_Standalone use "encapsulated";
+@end group
+@end smallexample
+
+@noindent
+The default value for this attribute is @code{standard} in which case
+a stand-alone library is built.
+
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
@font@heightrm=cmr8
@heightrm
@end iftex
-# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH.
+# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_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).
+# only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_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
SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@}
OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@}
ADA_INCLUDE_PATH += $@{SOURCE_LIST@}
-ADA_OBJECT_PATH += $@{OBJECT_LIST@}
+ADA_OBJECTS_PATH += $@{OBJECT_LIST@}
export ADA_INCLUDE_PATH
-export ADA_OBJECT_PATH
+export ADA_OBJECTS_PATH
all:
gnatmake main_unit
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.
+
+@noindent
+On Itanium platforms, you can instead assign the @samp{GNAT_STACK_SIZE} and
+@samp{GNAT_RBS_SIZE} logicals to the size of the primary and register
+stack in kilobytes. For example:
+
+@smallexample
+$ define GNAT_RBS_SIZE 1024 ! Limit the RBS size to 1MB.
+@end smallexample
@end ifset
@node Static Stack Usage Analysis
means that the second field is a reliable maximum of the function stack
utilization.
+A unit compiled with @option{-Wstack-usage} will issue a warning for each
+subprogram whose stack usage might be larger than the specified amount of
+bytes. The wording is in keeping with the qualifier documented above.
+
@node Dynamic Stack Usage Analysis
@section Dynamic Stack Usage Analysis
columns:
@noindent
-Index | Task Name | Stack Size | Stack Usage [Value +/- Variation]
+Index | Task Name | Stack Size | Stack Usage
@noindent
where:
@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.
+much has actually been used.
@end table
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.
+@noindent
+The package @code{GNAT.Task_Stack_Usage} provides facilities to get
+stack usage reports at run-time. See its body for the details.
@c *********************************
@c * GNATCHECK *
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.
+through @command{gnatcheck} switches.
-Project support for @command{gnatcheck} is provided by the GNAT
-driver (see @ref{The GNAT Driver and Project Files}).
+For full details, refer to @cite{GNATcheck Reference Manual} document.
-Invoking @command{gnatcheck} on the command line has the form:
-@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
+@c *********************************
+@node Creating Sample Bodies Using gnatstub
+@chapter Creating Sample Bodies Using @command{gnatstub}
+@findex gnatstub
@noindent
-where
-@itemize @bullet
-@item
-@var{switches} specify the general tool options
-
-@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.
-
-@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.
+@command{gnatstub} creates body stubs, that is, empty but compilable bodies
+for library unit declarations.
-@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,
-use the @option{-gnat05} switch if sources should be compiled in
-Ada 2005 mode etc.
+Note: to invoke @code{gnatstub} with a project file, use the @code{gnat}
+driver (see @ref{The GNAT Driver and Project Files}).
-@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
+To create a body stub, @command{gnatstub} has to compile the library
+unit declaration. Therefore, bodies can be created only for legal
+library units. Moreover, if a library unit depends semantically upon
+units located outside the current directory, you have to provide
+the source search path when calling @command{gnatstub}, see the description
+of @command{gnatstub} switches below.
-@noindent
-Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be
-supplied.
+By default, all the program unit body stubs generated by @code{gnatstub}
+raise the predefined @code{Program_Error} exception, which will catch
+accidental calls of generated stubs. This behavior can be changed with
+option @option{^--no-exception^/NO_EXCEPTION^} (see below).
@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::
+* Running gnatstub::
+* Switches for gnatstub::
@end menu
-@node Format of the Report File
-@section Format of the Report File
-@cindex Report file (for @code{gnatcheck})
+@node Running gnatstub
+@section Running @command{gnatstub}
@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; the @option{^-o^/OUTPUT^} option can be used to change the
-name and/or location of the report file. This report contains:
-@itemize @bullet
-@item date and time of @command{gnatcheck} run, the version of
-the tool that has generated this report and the full parameters
-of the @command{gnatcheck} invocation;
-@item list of enabled rules;
-@item total number of detected violations;
-@item list of source files where rule violations have been detected;
-@item list of source files where no violations have been detected.
-@end itemize
+@command{gnatstub} has a command-line interface of the form:
-@node General gnatcheck Switches
-@section General @command{gnatcheck} Switches
-
-@noindent
-The following switches control the general @command{gnatcheck} behavior
-
-@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.
-
-@ifclear vms
-@ignore
-@cindex @option{-d} (@command{gnatcheck})
-@item -d
-Debug mode
-@end ignore
-
-@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}.
-
-@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.
-
-@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.
-
-@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}.
-
-@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)
-
-@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
-
-@cindex @option{^-t^/TIME^} (@command{gnatcheck})
-@item ^-t^/TIME^
-Print out execution time.
-
-@cindex @option{^-v^/VERBOSE^} (@command{gnatcheck})
-@item ^-v^/VERBOSE^
-Verbose mode; @command{gnatcheck} generates version information and then
-a trace of sources being processed.
-
-@cindex @option{^-o ^/OUTPUT^} (@command{gnatcheck})
-@item ^-o ^/OUTPUT=^@var{report_file}
-Set name of report file file to @var{report_file} .
-
-@end table
-
-@node gnatcheck Rule Options
-@section @command{gnatcheck} Rule Options
-
-@noindent
-The following options control the processing performed by
-@command{gnatcheck}.
-
-@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.
-
-@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.
-
-@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.
-
-@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.
-
-@end table
-
-@noindent
-The default behavior is that all the rule checks are disabled.
-
-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).
-
-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 Adding the Results of Compiler Checks to gnatcheck Output
-@section Adding the Results of Compiler Checks to @command{gnatcheck} Output
-
-@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:
-
-@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}.
-
-@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
-@code{All_Checks},
-which enables the standard style checks corresponding to the @option{-gnatyy}
-GNAT style check option, or
-
-@item
-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
-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 Project-Wide Checks
-@section Project-Wide Checks
-@cindex Project-wide checks (for @command{gnatcheck})
-
-@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
-
-@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
-
-
-@node Rule exemption
-@section Rule exemption
-@cindex Rule exemption (for @command{gnatcheck})
-
-@noindent
-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.
-
-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.
-
-@menu
-* Using pragma Annotate to Control Rule Exemption::
-* gnatcheck Annotations Rules::
-@end menu
-
-@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
-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:
-
-@smallexample @c ada
-@group
-pragma Annotate (gnatcheck, @i{exemption_control}, @i{Rule_Name}, [@i{justification}]);
-
-@i{exemption_control} ::= Exempt_On | Exempt_Off
-
-@i{Rule_Name} ::= string_literal
-
-@i{justification} ::= string_literal
-@end group
-@end smallexample
-
-@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.
-
-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.
-
-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:
-
-@smallexample @c ada
-pragma Annotate (gnatcheck, Exempt_On, Rule_Name, "justification");
--- source code section
-pragma Annotate (gnatcheck, Exempt_Off, Rule_Name);
-@end smallexample
-
-
-@node gnatcheck Annotations Rules
-@subsection @command{gnatcheck} Annotations Rules
-@cindex @command{gnatcheck} annotations rules
-
-@itemize @bullet
-
-@item
-An ``Exempt_Off'' annotation can only appear after a corresponding
-``Exempt_On'' annotation.
-
-@item
-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
-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
-Malformed exempted source code sections are reported by a warning, and
-the corresponding rule exemptions are ignored.
-
-@item
-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
-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
-
-
-@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
-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.
-
-@command{gnatcheck} performs rule checks for generic
-instances only for global rules. This limitation may be relaxed in a later
-release.
-@end ignore
-
-@noindent
-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.
-
-
-@node Example of gnatcheck Usage
-@section Example of @command{gnatcheck} Usage
-
-@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:
-
-@smallexample @c projectfile
-project Gnatcheck_Example is
-
- for Source_Dirs use ("src");
- for Object_Dir use "obj";
- for Main use ("main.adb");
-
- package Check is
- for Default_Switches ("ada") use ("-rules", "-from=coding_standard");
- end Check;
-
-end Gnatcheck_Example;
-@end smallexample
-
-@noindent
-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
-
--- 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
-And the subdirectory @file{src} contains the following Ada sources:
-
-@file{pack.ads}:
-
-@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
-@file{pack.adb}:
-
-@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
-and @file{main.adb}
-
-@smallexample @c ada
-with Pack; use Pack;
-procedure Main is
-
- 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");
-
- Another_Float_Array : array (1 .. 10) of Inner.My_Float;
-
- use Inner;
-
- B : Boolean := False;
-
-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
-And suppose we call @command{gnatcheck} from the current directory using
-the @command{gnat} driver:
-
-@smallexample
- gnat check -Pgnatcheck_example.gpr
-@end smallexample
-
-@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
-
-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:
-
-gnatcheck -files=.../GNAT-TEMP-000004.TMP -cargs -gnatec=.../GNAT-TEMP-000003.TMP -rules -from=coding_standard
-
-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
-
-2.1. NON-EXEMPTED VIOLATIONS
-
-Source files with non-exempted violations
- pack.ads
- pack.adb
- main.adb
-
-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
-
-Source files with exempted violations
- main.adb
-
-List of violations grouped by files, and ordered by increasing source location:
-
-main.adb:6:18: anonymous array type
- (this one is fine)
-
-2.3. SOURCE FILES WITH NO VIOLATION
-
- No files without violations
-
-END OF REPORT
-@end smallexample
-
-
-@c *********************************
-@node Creating Sample Bodies Using gnatstub
-@chapter Creating Sample Bodies Using @command{gnatstub}
-@findex gnatstub
-
-@noindent
-@command{gnatstub} creates body stubs, that is, empty but compilable bodies
-for library unit declarations.
-
-Note: to invoke @code{gnatstub} with a project file, use the @code{gnat}
-driver (see @ref{The GNAT Driver and Project Files}).
-
-To create a body stub, @command{gnatstub} has to compile the library
-unit declaration. Therefore, bodies can be created only for legal
-library units. Moreover, if a library unit depends semantically upon
-units located outside the current directory, you have to provide
-the source search path when calling @command{gnatstub}, see the description
-of @command{gnatstub} switches below.
-
-By default, all the program unit body stubs generated by @code{gnatstub}
-raise the predefined @code{Program_Error} exception, which will catch
-accidental calls of generated stubs. This behavior can be changed with
-option @option{^--no-exception^/NO_EXCEPTION^} (see below).
-
-@menu
-* Running gnatstub::
-* Switches for gnatstub::
-@end menu
-
-@node Running gnatstub
-@section Running @command{gnatstub}
-
-@noindent
-@command{gnatstub} has the command-line interface of the form
-
-@smallexample
-@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
+@smallexample
+@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
where
@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
+@command{gnatstub} 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
@item ^--no-exception^/NO_EXCEPTION^
@cindex @option{^--no-exception^/NO_EXCEPTION^} (@command{gnatstub})
-Avoind raising PROGRAM_ERROR in the generated bodies of program unit stubs.
+Avoid 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^
@end table
@c *********************************
+@node Creating Unit Tests Using gnattest
+@chapter Creating Unit Tests Using @command{gnattest}
+@findex gnattest
+
+@noindent
+@command{gnattest} is an ASIS-based utility that creates unit-test stubs
+as well as a test driver infrastructure (harness). @command{gnattest} creates
+a stub for each visible subprogram in the packages under consideration when
+they do not exist already.
+
+In order to process source files from a project, @command{gnattest} has to
+semantically analyze the sources. Therefore, test stubs can only be
+generated for legal Ada units. If a unit is dependent on other units,
+those units should be among the source files of the project or of other projects
+imported by this one.
+
+Generated stubs and harnesses are based on the AUnit testing framework. AUnit is
+an Ada adaptation of the xxxUnit testing frameworks, similar to JUnit for Java
+or CppUnit for C++. While it is advised that gnattest users read the AUnit
+manual, deep knowledge of AUnit is not necessary for using gnattest. For correct
+operation of @command{gnattest}, AUnit should be installed and aunit.gpr must be
+on the project path. This happens automatically when Aunit is installed at its
+default location.
+@menu
+* Running gnattest::
+* Switches for gnattest::
+* Project Attributes for gnattest::
+* Simple Example::
+* Setting Up and Tearing Down the Testing Environment::
+* Regenerating Tests::
+* Default Test Behavior::
+* Testing Primitive Operations of Tagged Types::
+* Testing Inheritance::
+* Tagged Types Substitutability Testing::
+* Testing with Contracts::
+* Additional Tests::
+* Current Limitations::
+@end menu
+
+@node Running gnattest
+@section Running @command{gnattest}
+
+@noindent
+@command{gnattest} has a command-line interface of the form
+
+@smallexample
+@c $ gnattest @var{-Pprojname} @ovar{switches} @ovar{filename} @ovar{directory}
+@c Expanding @ovar macro inline (explanation in macro def comments)
+$ gnattest @var{-Pprojname} @r{[}@var{--harness-dir=dirname}@r{]} @r{[}@var{switches}@r{]} @r{[}@var{filename}@r{]} @r{[}-cargs @var{gcc_switches}@r{]}
+@end smallexample
+
+@noindent
+where
+@table @var
+
+@item -Pprojname
+specifies the project defining the location of source files. When no
+file names are provided on the command line, all sources in the project
+are used as input. This switch is required.
+
+@item --harness-dir=dirname
+specifies the directory that will hold the harness packages and project file
+for the test driver. The harness directory should be specified either by that
+switch or by the corresponding attribute in the project file.
+
+@item filename
+is the name of the source file containing the library unit package declaration
+for which a test package will be created. The file name may be given with a
+path.
+
+@item @samp{@var{gcc_switches}}
+is a list of switches for
+@command{gcc}. These switches will be passed on to all compiler invocations
+made by @command{gnatstub} to generate a set of 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
+
+@command{gnattest} results can be found in two different places.
+
+@itemize @bullet
+@item automatic harness:
+the harness code, which is located either in the harness-dir as specified on
+the command line or in the project file. All of this code is generated
+completely automatically and can be destroyed and regenerated at will. It is not
+recommended to modify this code manually, since it could easily be overridden
+by mistake. The entry point in the harness code is the project file named
+@command{test_driver.gpr}. Tests can be compiled and run using a command
+such as:
+
+@smallexample
+gnatmake -P<harness-dir>/test_driver
+test_runner
+@end smallexample
+
+Note that you might need to specify the necessary values of scenario variables
+when you are not using the AUnit defaults.
+
+@item actual unit test stubs:
+a test stub for each visible subprogram is created in a separate file, if it
+doesn't exist already. By default, those separate test files are located in a
+"tests" directory that is created in the directory containing the source file
+itself. If it is not appropriate to create the tests in subdirectories of the
+source, option @option{--separate-root} can be used. For example, if a source
+file my_unit.ads in directory src contains a visible subprogram Proc, then
+the corresponding unit test will be found in file
+src/tests/my_unit-tests-proc_<code>.adb. <code> is a signature encoding used to
+differentiate test names in case of overloading.
+
+Note that if the project already has both my_unit.ads and my_unit-tests.ads,
+this will cause a name conflict with the generated test package.
+@end itemize
+
+@node Switches for gnattest
+@section Switches for @command{gnattest}
+
+@table @option
+@c !sort!
+
+@item --harness-only
+@cindex @option{--harness-only} (@command{gnattest})
+When this option is given, @command{gnattest} creates a harness for all
+sources, treating them as test packages.
+
+@item --additional-tests=@var{projname}
+@cindex @option{--additional-tests} (@command{gnattest})
+Sources described in @var{projname} are considered potential additional
+manual tests to be added to the test suite.
+
+@item -r
+@cindex @option{-r} (@command{gnattest})
+Recursively consider all sources from all projects.
+
+@item -X@var{name=value}
+@cindex @option{-X} (@command{gnattest})
+Indicate that external variable @var{name} has the value @var{value}.
+
+@item -q
+@cindex @option{-q} (@command{gnattest})
+Suppresses noncritical output messages.
+
+@item -v
+@cindex @option{-v} (@command{gnattest})
+Verbose mode: generates version information.
+
+@item --liskov
+@cindex @option{--liskov} (@command{gnattest})
+Enables Liskov verification: run all tests from all parents in order
+to check substitutability.
+
+@item --stub-default=@var{val}
+@cindex @option{--stub-default} (@command{gnattest})
+Specifies the default behavior of generated stubs. @var{val} can be either
+"fail" or "pass", "fail" being the default.
+
+@item --separate-root=@var{dirname}
+@cindex @option{--separate-root} (@command{gnattest})
+The directory hierarchy of tested sources is recreated in the @var{dirname}
+directory, and test packages are placed in corresponding directories.
+
+@item --subdir=@var{dirname}
+@cindex @option{--subdir} (@command{gnattest})
+Test packages are placed in subdirectories. This is the default output mode
+since it does not require any additional input from the user. Subdirectories
+named "tests" will be created by default.
+
+@end table
+
+@option{--separate_root} and @option{--subdir} switches are mutually exclusive.
+
+@node Project Attributes for gnattest
+@section Project Attributes for @command{gnattest}
+
+@noindent
+
+Most of the command-line options can also be passed to the tool by adding
+special attributes to the project file. Those attributes should be put in
+package gnattest. Here is the list of attributes:
+
+@itemize @bullet
+
+@item Separate_Stub_Root
+is used to select the same output mode as with the --separate-root option.
+This attribute cannot be used together with Stub_Subdir.
+
+@item Stub_Subdir
+is used to select the same output mode as with the --subdir option.
+This attribute cannot be used together with Separate_Stub_Root.
+
+@item Harness_Dir
+is used to specify the directory in which to place harness packages and project
+file for the test driver, otherwise specified by --harness-dir.
+
+@item Additional_Tests
+is used to specify the project file, otherwise given by
+--additional-tests switch.
+
+@item Stubs_Default
+is used to specify the default behaviour of test stubs, otherwise
+specified by --stub-default option. The value of this attribute
+should be either "pass" or "fail".
+
+@end itemize
+
+Each of those attributes can be overridden from the command line if needed.
+Other @command{gnattest} switches can also be passed via the project
+file as an attribute list called GNATtest_Switches.
+
+@node Simple Example
+@section Simple Example
+
+@noindent
+
+Let's take a very simple example using the first @command{gnattest} example
+located in:
+
+@smallexample
+<install_prefix>/share/examples/gnattest/simple
+@end smallexample
+
+This project contains a simple package containing one subprogram. By running gnattest:
+
+@smallexample
+$ gnattest --harness-dir=driver -Psimple.gpr
+@end smallexample
+
+a test driver is created in directory "driver". It can be compiled and run:
+
+@smallexample
+$ cd driver
+$ gprbuild -Ptest_driver
+$ test_runner
+@end smallexample
+
+One failed test with diagnosis "test not implemented" is reported.
+Since no special output option was specified, the test package Simple.Tests
+is located in:
+
+@smallexample
+<install_prefix>/share/examples/gnattest/simple/src/tests
+@end smallexample
+
+For each package containing visible subprograms, a child test package is
+generated. It contains one test routine per tested subprogram. Each
+declaration of a test subprogram has a comment specifying which tested
+subprogram it corresponds to. All of the test routines have separate bodies.
+The test routine located at simple-tests-test_inc_5eaee3.adb contains a single
+statement: a call to procedure Assert. It has two arguments: the Boolean
+expression we want to check and the diagnosis message to display if
+the condition is false.
+
+That is where actual testing code should be written after a proper setup.
+An actual check can be performed by replacing the Assert call with:
+
+@smallexample @c ada
+Assert (Inc (1) = 2, "wrong incrementation");
+@end smallexample
+
+After recompiling and running the test driver, one successfully passed test
+is reported.
+
+@node Setting Up and Tearing Down the Testing Environment
+@section Setting Up and Tearing Down the Testing Environment
+
+@noindent
+
+Besides test routines themselves, each test package has an inner package
+Env_Mgmt that has two procedures: User_Set_Up and User_Tear_Down.
+User_Set_Up is called before each test routine of the package and
+User_Tear_Down is called after each test routine. Those two procedures can
+be used to perform necessary initialization and finalization,
+memory allocation, etc.
+
+@node Regenerating Tests
+@section Regenerating Tests
+
+@noindent
+
+Bodies of test routines and env_mgmt packages are never overridden after they
+have been created once. As long as the name of the subprogram, full expanded Ada
+names, and the order of its parameters is the same, the old test routine will
+fit in its place and no test stub will be generated for the subprogram.
+
+This can be demonstrated with the previous example. By uncommenting declaration
+and body of function Dec in simple.ads and simple.adb, running
+@command{gnattest} on the project, and then running the test driver:
+
+@smallexample
+gnattest --harness-dir=driver -Psimple.gpr
+cd driver
+gprbuild -Ptest_driver
+test_runner
+@end smallexample
+
+the old test is not replaced with a stub, nor is it lost, but a new test stub is
+created for function Dec.
+
+The only way of regenerating tests stubs is to remove the previously created
+tests.
+
+@node Default Test Behavior
+@section Default Test Behavior
+
+@noindent
+
+The generated test driver can treat unimplemented tests in two ways:
+either count them all as failed (this is useful to see which tests are still
+left to implement) or as passed (to sort out unimplemented ones from those
+actually failing).
+
+The test driver accepts a switch to specify this behavior: --stub-default=val,
+where val is either "pass" or "fail" (exactly as for @command{gnattest}).
+
+The default behavior of the test driver is set with the same switch
+as passed to gnattest when generating the test driver.
+
+Passing it to the driver generated on the first example:
+
+@smallexample
+test_runner --stub-default=pass
+@end smallexample
+
+makes both tests pass, even the unimplemented one.
+
+@node Testing Primitive Operations of Tagged Types
+@section Testing Primitive Operations of Tagged Types
+
+@noindent
+
+Creation of test stubs for primitive operations of tagged types entails a number
+of features. Test routines for all primitives of a given tagged type are
+placed in a separate child package named according to the tagged type. For
+example, if you have tagged type T in package P, all tests for primitives
+of T will be in P.T_Tests.
+
+Consider running gnattest on the second example (note: actual tests for this
+example already exist, so there's no need to worry if the tool reports that
+no new stubs were generated):
+
+@smallexample
+cd <install_prefix>/share/examples/gnattest/tagged_rec
+gnattest --harness-dir=driver -Ptagged_rec.gpr
+@end smallexample
+
+Taking a closer look at the test type declared in the test package
+Speed1.Controller_Tests is necessary. It is declared in:
+
+@smallexample
+<install_prefix>/share/examples/gnattest/tagged_rec/src/tests
+@end smallexample
+
+Test types are direct or indirect descendants of
+AUnit.Test_Fixtures.Test_Fixture type. In the case of nonprimitive tested
+subprograms, the user doesn't need to be concerned with them. However,
+when generating test packages for primitive operations, there are some things
+the user needs to know.
+
+Type Test_Controller has components that allow assignment of various
+derivations of type Controller. And if you look at the specification of
+package Speed2.Auto_Controller, you will see that Test_Auto_Controller
+actually derives from Test_Controller rather than AUnit type Test_Fixture.
+Thus, test types mirror the hierarchy of tested types.
+
+The User_Set_Up procedure of Env_Mgmt package corresponding to a test package
+of primitive operations of type T assigns to Fixture a reference to an
+object of that exact type T. Notice, however, that if the tagged type has
+discriminants, the User_Set_Up only has a commented template for setting
+up the fixture, since filling the discriminant with actual value is up
+to the user.
+
+The knowledge of the structure of test types allows additional testing
+without additional effort. Those possibilities are described below.
+
+@node Testing Inheritance
+@section Testing Inheritance
+
+@noindent
+
+Since the test type hierarchy mimics the hierarchy of tested types, the
+inheritance of tests takes place. An example of such inheritance can be
+seen by running the test driver generated for the second example. As previously
+mentioned, actual tests are already written for this example.
+
+@smallexample
+cd driver
+gprbuild -Ptest_driver
+test_runner
+@end smallexample
+
+There are 6 passed tests while there are only 5 testable subprograms. The test
+routine for function Speed has been inherited and run against objects of the
+derived type.
+
+@node Tagged Types Substitutability Testing
+@section Tagged Types Substitutability Testing
+
+@noindent
+
+Tagged Types Substitutability Testing is a way of verifying the Liskov
+substitution principle (LSP) by testing. LSP is a principle stating that if
+S is a subtype of T (in Ada, S is a derived type of tagged type T),
+then objects of type T may be replaced with objects of type S (that is,
+objects of type S may be substituted for objects of type T), without
+altering any of the desirable properties of the program. When the properties
+of the program are expressed in the form of subprogram preconditions and
+postconditions (let's call them pre and post), LSP is formulated as relations
+between the pre and post of primitive operations and the pre and post of their
+derived operations. The pre of a derived operation should not be stronger than
+the original pre, and the post of the derived operation should not be weaker
+than the original post. Those relations ensure that verifying if a dispatching
+call is safe can be done just by using the pre and post of the root operation.
+
+Verifying LSP by testing consists of running all the unit tests associated with
+the primitives of a given tagged type with objects of its derived types.
+
+In the example used in the previous section, there was clearly a violation of
+LSP. The overriding primitive Adjust_Speed in package Speed2 removes the
+functionality of the overridden primitive and thus doesn't respect LSP.
+Gnattest has a special option to run overridden parent tests against objects
+of the type which have overriding primitives:
+
+@smallexample
+gnattest --harness-dir=driver --liskov -Ptagged_rec.gpr
+cd driver
+gprbuild -Ptest_driver
+test_runner
+@end smallexample
+
+While all the tests pass by themselves, the parent test for Adjust_Speed fails
+against objects of the derived type.
+
+@node Testing with Contracts
+@section Testing with Contracts
+
+@noindent
+
+@command{gnattest} supports pragmas Precondition, Postcondition, and Test_Case.
+Test routines are generated, one per each Test_Case associated with a tested
+subprogram. Those test routines have special wrappers for tested functions
+that have composition of pre- and postcondition of the subprogram with
+"requires" and "ensures" of the Test_Case (depending on the mode, pre and post
+either count for Nominal mode or do not count for Robustness mode).
+
+The third example demonstrates how this works:
+
+@smallexample
+cd <install_prefix>/share/examples/gnattest/contracts
+gnattest --harness-dir=driver -Pcontracts.gpr
+@end smallexample
+
+Putting actual checks within the range of the contract does not cause any
+error reports. For example, for the test routine which corresponds to
+test case 1:
+
+@smallexample @c ada
+Assert (Sqrt (9.0) = 3.0, "wrong sqrt");
+@end smallexample
+
+and for the test routine corresponding to test case 2:
+
+@smallexample @c ada
+Assert (Sqrt (-5.0) = -1.0, "wrong error indication");
+@end smallexample
+
+are acceptable:
+
+@smallexample
+cd driver
+gprbuild -Ptest_driver
+test_runner
+@end smallexample
+
+However, by changing 9.0 to 25.0 and 3.0 to 5.0, for example, you can get
+a precondition violation for test case one. Also, by using any otherwise
+correct but positive pair of numbers in the second test routine, you can also
+get a precondition violation. Postconditions are checked and reported
+the same way.
+
+@node Additional Tests
+@section Additional Tests
+
+@noindent
+@command{gnattest} can add user-written tests to the main suite of the test
+driver. @command{gnattest} traverses the given packages and searches for test
+routines. All procedures with a single in out parameter of a type which is
+derived from AUnit.Test_Fixtures.Test_Fixture and that are declared in package
+specifications are added to the suites and are then executed by the test driver.
+(Set_Up and Tear_Down are filtered out.)
+
+An example illustrates two ways of creating test harnesses for user-written
+tests. Directory additional_tests contains an AUnit-based test driver written
+by hand.
+
+@smallexample
+<install_prefix>/share/examples/gnattest/additional_tests/
+@end smallexample
+
+To create a test driver for already-written tests, use the --harness-only
+option:
+
+@smallexample
+gnattest -Padditional/harness/harness.gpr --harness-dir=harness_only \
+ --harness-only
+gnatmake -Pharness_only/test_driver.gpr
+harness_only/test_runner
+@end smallexample
+
+Additional tests can also be executed together with generated tests:
+
+@smallexample
+gnattest -Psimple.gpr --additional-tests=additional/harness/harness.gpr \
+ --harness-dir=mixing
+gnatmake -Pmixing/test_driver.gpr
+mixing/test_runner
+@end smallexample
+
+@node Current Limitations
+@section Current Limitations
+
+@noindent
+
+The tool currently does not support following features:
+
+@itemize @bullet
+@item generic tests for generic packages and package instantiations
+@item tests for protected subprograms and entries
+@item aspects Precondition, Postcondition, and Test_Case
+@item generating test packages for code that is not conformant with ada 2005
+
+@end itemize
+
+@c *********************************
@node Generating Ada Bindings for C and C++ headers
@chapter Generating Ada Bindings for C and C++ headers
@findex binding
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
+@item identifiers with identical name (except casing) will generate compilation
+ errors (e.g. @code{shm_get} vs @code{SHM_GET}).
@end itemize
The code generated is using the Ada 2005 syntax, which makes it
The binding generator is part of the @command{gcc} compiler and can be
invoked via the @option{-fdump-ada-spec} switch, which will generate Ada
spec files for the header files specified on the command line, and all
-header files needed by these files transitivitely. For example:
+header files needed by these files transitively. For example:
@smallexample
$ g++ -c -fdump-ada-spec -C /usr/include/time.h
The above will generate more complete bindings than a straight call without
the @option{-DXLIB_ILLEGAL_ACCESS} switch.
-In other cases, it is not possible to parse a header file in a stand alone
+In other cases, it is not possible to parse a header file in a stand-alone
manner, because other include files need to be included first. In this
case, the solution is to create a small header file including the needed
@code{#include} and possible @code{#define} directives. For example, to
raises the exception @var{name}.
@item catch exception unhandled
-Set a catchpoint that stops executino whenever (any task in the) program
+Set a catchpoint that stops executing whenever (any task in the) program
raises an exception for which there is no handler.
@item info exceptions
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
+the gdbserver Program, gdb, Debugging with GDB}. @value{EDITION} provides support
for gdbserver on x86-linux, x86-windows and x86_64-linux.
@node GNAT Abnormal Termination or Failure to Terminate
GNAT provides implementations of these HP bindings in the @code{DECLIB}
directory, on both the Alpha and I64 OpenVMS platforms.
+The X components of DECLIB compatibility package are located in a separate
+library, called XDECGNAT, which is not linked with by default; this library
+must be explicitly linked with any application that makes use of any X facilities,
+with a command similar to
+
+@code{GNAT MAKE USE_X /LINK /LIBRARY=XDECGNAT}
+
The X/Motif bindings used to build @code{DECLIB} are whatever versions are
in the
HP Ada @file{ADA$PREDEFINED} directory with extension @file{.ADC}.
&\cr
\+\it Tool
&\it Product with HP Ada
- & \it Product with GNAT Pro\cr
+ & \it Product with @value{EDITION}\cr
\smallskip
\+Code Management System
&HP CMS
@c the TeX version above for the printed version
@flushleft
@c @multitable @columnfractions .3 .4 .4
-@multitable {Source Code Analyzer /}{Tool with HP Ada}{Tool with GNAT Pro}
+@multitable {Source Code Analyzer /}{Tool with HP Ada}{Tool with @value{EDITION}}
@item @i{Tool}
@tab @i{Tool with HP Ada}
@tab @i{Tool with @value{EDITION}}
@item @b{ppc-aix}
@item @code{@ @ }@i{rts-native (default)}
@item @code{@ @ @ @ }Tasking @tab native AIX threads
+@item @code{@ @ @ @ }Exceptions @tab ZCX
+@*
+@item @code{@ @ }@i{rts-sjlj}
+@item @code{@ @ @ @ }Tasking @tab native AIX threads
@item @code{@ @ @ @ }Exceptions @tab SJLJ
@*
@item @b{ppc-darwin}
@item @b{x86-solaris}
@item @code{@ @ }@i{rts-native (default)}
@item @code{@ @ @ @ }Tasking @tab native Solaris threads
+@item @code{@ @ @ @ }Exceptions @tab ZCX
+@*
+@item @code{@ @ }@i{rts-sjlj}
+@item @code{@ @ @ @ }Tasking @tab native Solaris threads library
@item @code{@ @ @ @ }Exceptions @tab SJLJ
@*
@item @b{x86-windows}
@item @code{@ @ @ @ }Tasking @tab native Win32 threads
@item @code{@ @ @ @ }Exceptions @tab ZCX
@*
-@item @code{@ @ }@i{rts-sjlj (default)}
+@item @code{@ @ }@i{rts-sjlj}
@item @code{@ @ @ @ }Tasking @tab native Win32 threads
@item @code{@ @ @ @ }Exceptions @tab SJLJ
@*
the generic declaration explicitly indicates whether
or not such instantiations are permitted. If a generic formal parameter
has explicit unknown discriminants, indicated by using @code{(<>)} after the
-type name, then it can be instantiated with indefinite types, but no
+subtype name, then it can be instantiated with indefinite types, but no
stand-alone variables can be declared of this type. Any attempt to declare
such a variable will result in an illegality at the time the generic is
declared. If the @code{(<>)} notation is not used, then it is illegal
@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
@noindent
64-bit @value{EDITION} for Open VMS takes advantage of the freedom given in the
Ada standard with respect to the type of @code{System.Address}. Previous
-versions of GNAT Pro have defined this type as private and implemented it as a
+versions of @value{EDITION} have defined this type as private and implemented it as a
modular type.
In order to allow defining @code{System.Short_Address} as a proper subtype,
@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.
+Microsoft style import libraries. The last two are the actual DLL names.
Note that if the Ada package spec for @file{API.dll} contains the
following pragma
@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
application. The objects that can be added as resources include:
@itemize @bullet
-@item
-menus
+@item menus
-@item
-accelerators
+@item accelerators
-@item
-dialog boxes
+@item dialog boxes
-@item
-string tables
+@item string tables
-@item
-bitmaps
+@item bitmaps
-@item
-cursors
+@item cursors
-@item
-icons
+@item icons
-@item
-fonts
+@item fonts
+
+@item version information
@end itemize
+For example, a version information resource can be defined as follow and
+embedded into an executable or DLL:
+
+A version information resource can be used to embed information into an
+executable or a DLL. These information can be viewed using the file properties
+from the Windows Explorer. Here is an example of a version information
+resource:
+
+@smallexample
+@group
+1 VERSIONINFO
+FILEVERSION 1,0,0,0
+PRODUCTVERSION 1,0,0,0
+BEGIN
+ BLOCK "StringFileInfo"
+ BEGIN
+ BLOCK "080904E4"
+ BEGIN
+ VALUE "CompanyName", "My Company Name"
+ VALUE "FileDescription", "My application"
+ VALUE "FileVersion", "1.0"
+ VALUE "InternalName", "my_app"
+ VALUE "LegalCopyright", "My Name"
+ VALUE "OriginalFilename", "my_app.exe"
+ VALUE "ProductName", "My App"
+ VALUE "ProductVersion", "1.0"
+ END
+ END
+
+ BLOCK "VarFileInfo"
+ BEGIN
+ VALUE "Translation", 0x809, 1252
+ END
+END
+@end group
+@end smallexample
+
+The value @code{0809} (langID) is for the U.K English language and
+@code{04E4} (charsetID), which is equal to @code{1252} decimal, for
+multilingual.
+
@noindent
-This section explains how to build, compile and use resources.
+This section explains how to build, compile and use resources. Note that this
+section does not cover all resource objects, for a complete description see
+the corresponding Microsoft documentation.
@node Building Resources
@subsection Building Resources
OSDN Git Service
