* 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
* 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.
@cindex @option{-gnateG} (@command{gcc})
Save result of preprocessing in a text file.
-@item -gnateInnn
+@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 nnn. nnn needs to be a positive number and need to
-be a valid index in the multi-unit source.
+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})
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.
@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.}
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
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
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::
@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)}.
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
@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}
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
@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
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
@section Running @command{gnatstub}
@noindent
-@command{gnatstub} has the command-line interface of the form
+@command{gnatstub} has a command-line interface of the form:
@smallexample
@c $ gnatstub @ovar{switches} @var{filename} @ovar{directory}
@item @samp{@var{gcc_switches}} is a list of switches for
@command{gcc}. They will be passed on to all compiler invocations made by
-@command{gnatelim} to generate the ASIS trees. Here you can provide
+@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})
-void 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 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 cases of overloading.
+
+Note that if the project already has both my_unit.ads and my_unit-tests.ads this
+will cause name a conflict with 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
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}.
@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