\input texinfo @c -*-texinfo-*-
@c %**start of header
+
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c o
@c GNAT DOCUMENTATION o
@c o
@c G N A T _ U G N o
@c o
-@c Copyright (C) 1992-2008, AdaCore o
-@c o
-@c GNAT is free software; you can redistribute it and/or modify it under o
-@c terms of the GNU General Public License as published by the Free Soft- o
-@c ware Foundation; either version 2, or (at your option) any later ver- o
-@c sion. GNAT is distributed in the hope that it will be useful, but WITH- o
-@c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY o
-@c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o
-@c for more details. You should have received a copy of the GNU General o
-@c Public License distributed with GNAT; see file COPYING. If not, write o
-@c to the Free Software Foundation, 51 Franklin Street, Fifth Floor, o
-@c Boston, MA 02110-1301, USA. o
+@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
+@setfilename gnat_ugn.info
+
+@copying
+Copyright @copyright{} 1995-2009 Free Software Foundation,
+Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end copying
+
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c
@c GNAT_UGN Style Guide
@c
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
-@setfilename gnat_ugn.info
-
@set NOW January 2007
@c This flag is used where the text refers to conditions that exist when the
@c text was entered into the document but which may change over time.
@settitle @value{EDITION} User's Guide @value{PLATFORM}
@dircategory GNU Ada tools
@direntry
-* @value{EDITION} User's Guide (gnat_ugn) @value{PLATFORM}
+* @value{EDITION} User's Guide: (gnat_ugn). @value{PLATFORM}
@end direntry
@include gcc-common.texi
@syncodeindex fn cp
@c %**end of header
-@copying
-Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
-Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being ``GNU Free Documentation License'', with the
-Front-Cover Texts being
-``@value{EDITION} User's Guide'',
-and with no Back-Cover Texts.
-A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-@end copying
-
@titlepage
@title @value{EDITION} User's Guide
@ifset vms
* Stack Related Facilities::
* Verifying Properties Using gnatcheck::
* Creating Sample Bodies Using gnatstub::
+* Generating Ada Bindings for C and C++ headers::
* Other Utility Programs::
* Running and Debugging Ada Programs::
@ifclear vms
The Cross-Referencing Tools gnatxref and gnatfind
-* gnatxref Switches::
-* gnatfind Switches::
+* Switches for gnatxref::
+* Switches for gnatfind::
* Project Files for gnatxref and gnatfind::
* Regular Expressions in gnatfind and gnatxref::
* Examples of gnatxref Usage::
* 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
a utility that generates empty but compilable bodies 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.
+
+@item
@ref{Other Utility Programs}, discusses several other GNAT utilities,
including @code{gnathtml}.
it is necessary to compile in optimizing mode.
@cindex @option{-gnatN} switch
-The use of @option{-gnatN} activates a more extensive inlining optimization
+The use of @option{-gnatN} activates inlining optimization
that is performed by the front end of the compiler. This inlining does
not require that the code generation be optimized. Like @option{-gnatn},
the use of this switch generates additional dependencies.
-Note that
-@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
-to specify both options.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@item
If an object file @file{O} depends on the proper body of a subunit through
* Interfacing to C++::
* Linking a Mixed C++ & Ada Program::
* A Simple Example::
+* Interfacing with C++ constructors::
* Interfacing with C++ at the Class Level::
@end menu
Interfacing can be done at 3 levels: simple data, subprograms, and
classes. In the first two cases, GNAT offers a specific @code{Convention
C_Plus_Plus} (or @code{CPP}) that behaves exactly like @code{Convention C}.
-Usually, C++ mangles the names of subprograms, and currently, GNAT does
-not provide any help to solve the demangling problem. This problem can be
-addressed in two ways:
+Usually, C++ mangles the names of subprograms. To generate proper mangled
+names automatically, see @ref{Generating Ada Bindings for C and C++ headers}).
+This problem can also be addressed manually in two ways:
+
@itemize @bullet
@item
by modifying the C++ code in order to force a C convention using
the @code{extern "C"} syntax.
@item
-by figuring out the mangled name and use it as the Link_Name argument of
-the pragma import.
+by figuring out the mangled name (using e.g. @command{nm}) and using it as the
+Link_Name argument of the pragma import.
@end itemize
@noindent
@item
Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
The C++ linker can simply be called by using the C++ specific driver
-called @code{c++}. Note that this setup is not very common because it
-may involve recompiling the whole GCC tree from sources, which makes it
-harder to upgrade the compilation system for one language without
-destabilizing the other.
+called @code{g++}.
+
+Note that if the C++ code uses inline functions, you will need to
+compile your C++ code with the @code{-fkeep-inline-functions} switch in
+order to provide an existing function implementation that the Ada code can
+link with.
@smallexample
-$ c++ -c file1.C
-$ c++ -c file2.C
-$ gnatmake ada_unit -largs file1.o file2.o --LINK=c++
+$ g++ -c -fkeep-inline-functions file1.C
+$ g++ -c -fkeep-inline-functions file2.C
+$ gnatmake ada_unit -largs file1.o file2.o --LINK=g++
@end smallexample
@item
@end enumerate
+Another alternative is to use the @command{gprbuild} multi-language builder
+which has a large knowledge base and knows how to link Ada and C++ code
+together automatically in most cases.
+
@node A Simple Example
@subsection A Simple Example
@noindent
Here are the compilation commands:
@smallexample
$ gnatmake -c simple_cpp_interface
-$ c++ -c cpp_main.C
-$ c++ -c ex7.C
+$ g++ -c cpp_main.C
+$ g++ -c ex7.C
$ gnatbind -n simple_cpp_interface
-$ gnatlink simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS)
+$ gnatlink simple_cpp_interface -o cpp_main --LINK=g++
-lstdc++ ex7.o cpp_main.o
@end smallexample
end Simple_Cpp_Interface;
@end smallexample
+@node Interfacing with C++ constructors
+@subsection Interfacing with C++ constructors
+@noindent
+
+In order to interface with C++ constructors GNAT provides the
+@code{pragma CPP_Constructor} (@xref{Interfacing to C++,,,
+gnat_rm, GNAT Reference Manual}, for additional information).
+In this section we present some common uses of C++ constructors
+in mixed-languages programs in GNAT.
+
+Let us assume that we need to interface with the following
+C++ class:
+
+@smallexample
+@b{class} Root @{
+@b{public}:
+ int a_value;
+ int b_value;
+ @b{virtual} int Get_Value ();
+ Root(); // Default constructor
+ Root(int v); // 1st non-default constructor
+ Root(int v, int w); // 2nd non-default constructor
+@};
+@end smallexample
+
+For this purpose we can write the following package spec (further
+information on how to build this spec is available in
+@ref{Interfacing with C++ at the Class Level} and
+@ref{Generating Ada Bindings for C and C++ headers}).
+
+@smallexample @c ada
+with Interfaces.C; use Interfaces.C;
+package Pkg_Root is
+ type Root is tagged limited record
+ A_Value : int;
+ B_Value : int;
+ end record;
+ pragma Import (CPP, Root);
+
+ function Get_Value (Obj : Root) return int;
+ pragma Import (CPP, Get_Value);
+
+ function Constructor return Root;
+ pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev");
+
+ function Constructor (v : Integer) return Root;
+ pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei");
+
+ function Constructor (v, w : Integer) return Root;
+ pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii");
+end Pkg_Root;
+@end smallexample
+
+On the Ada side the constructor is represented by a function (whose
+name is arbitrary) that returns the classwide type corresponding to
+the imported C++ class. Although the constructor is described as a
+function, it is typically a procedure with an extra implicit argument
+(the object being initialized) at the implementation level. GNAT
+issues the appropriate call, whatever it is, to get the object
+properly initialized.
+
+Constructors can only appear in the following contexts:
+
+@itemize @bullet
+@item
+On the right side of an initialization of an object of type @var{T}.
+@item
+On the right side of an initialization of a record component of type @var{T}.
+@item
+In an Ada 2005 limited aggregate.
+@item
+In an Ada 2005 nested limited aggregate.
+@item
+In an Ada 2005 limited aggregate that initializes an object built in
+place by an extended return statement.
+@end itemize
+
+@noindent
+In a declaration of an object whose type is a class imported from C++,
+either the default C++ constructor is implicitly called by GNAT, or
+else the required C++ constructor must be explicitly called in the
+expression that initializes the object. For example:
+
+@smallexample @c ada
+ Obj1 : Root;
+ Obj2 : Root := Constructor;
+ Obj3 : Root := Constructor (v => 10);
+ Obj4 : Root := Constructor (30, 40);
+@end smallexample
+
+The first two declarations are equivalent: in both cases the default C++
+constructor is invoked (in the former case the call to the constructor is
+implicit, and in the latter case the call is explicit in the object
+declaration). @code{Obj3} is initialized by the C++ non-default constructor
+that takes an integer argument, and @code{Obj4} is initialized by the
+non-default C++ constructor that takes two integers.
+
+Let us derive the imported C++ class in the Ada side. For example:
+
+@smallexample @c ada
+ type DT is new Root with record
+ C_Value : Natural := 2009;
+ end record;
+@end smallexample
+
+In this case the components DT inherited from the C++ side must be
+initialized by a C++ constructor, and the additional Ada components
+of type DT are initialized by GNAT. The initialization of such an
+object is done either by default, or by means of a function returning
+an aggregate of type DT, or by means of an extension aggregate.
+
+@smallexample @c ada
+ Obj5 : DT;
+ Obj6 : DT := Function_Returning_DT (50);
+ Obj7 : DT := (Constructor (30,40) with C_Value => 50);
+@end smallexample
+
+The declaration of @code{Obj5} invokes the default constructors: the
+C++ default constructor of the parent type takes care of the initialization
+of the components inherited from Root, and GNAT takes care of the default
+initialization of the additional Ada components of type DT (that is,
+@code{C_Value} is initialized to value 2009). The order of invocation of
+the constructors is consistent with the order of elaboration required by
+Ada and C++. That is, the constructor of the parent type is always called
+before the constructor of the derived type.
+
+Let us now consider a record that has components whose type is imported
+from C++. For example:
+
+@smallexample @c ada
+ type Rec1 is limited record
+ Data1 : Root := Constructor (10);
+ Value : Natural := 1000;
+ end record;
+
+ type Rec2 (D : Integer := 20) is limited record
+ Rec : Rec1;
+ Data2 : Root := Constructor (D, 30);
+ end record;
+@end smallexample
+
+The initialization of an object of type @code{Rec2} will call the
+non-default C++ constructors specified for the imported components.
+For example:
+
+@smallexample @c ada
+ Obj8 : Rec2 (40);
+@end smallexample
+
+Using Ada 2005 we can use limited aggregates to initialize an object
+invoking C++ constructors that differ from those specified in the type
+declarations. For example:
+
+@smallexample @c ada
+ Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16),
+ others => <>),
+ others => <>);
+@end smallexample
+
+The above declaration uses an Ada 2005 limited aggregate to
+initialize @code{Obj9}, and the C++ constructor that has two integer
+arguments is invoked to initialize the @code{Data1} component instead
+of the constructor specified in the declaration of type @code{Rec1}. In
+Ada 2005 the box in the aggregate indicates that unspecified components
+are initialized using the expression (if any) available in the component
+declaration. That is, in this case discriminant @code{D} is initialized
+to value @code{20}, @code{Value} is initialized to value 1000, and the
+non-default C++ constructor that handles two integers takes care of
+initializing component @code{Data2} with values @code{20,30}.
+
+In Ada 2005 we can use the extended return statement to build the Ada
+equivalent to C++ non-default constructors. For example:
+
+@smallexample @c ada
+ function Constructor (V : Integer) return Rec2 is
+ begin
+ return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20),
+ others => <>),
+ others => <>) do
+ -- Further actions required for construction of
+ -- objects of type Rec2
+ ...
+ end record;
+ end Constructor;
+@end smallexample
+
+In this example the extended return statement construct is used to
+build in place the returned object whose components are initialized
+by means of a limited aggregate. Any further action associated with
+the constructor can be placed inside the construct.
+
@node Interfacing with C++ at the Class Level
@subsection Interfacing with C++ at the Class Level
@noindent
procedure Set_Owner (A : in out Dog; Name : Chars_Ptr);
pragma Import (C_Plus_Plus, Set_Owner);
- function New_Dog return Dog'Class;
+ function New_Dog return Dog;
pragma CPP_Constructor (New_Dog);
pragma Import (CPP, New_Dog, "_ZN3DogC2Ev");
end Animals;
@item -fno-inline-functions
@cindex @option{-fno-inline-functions} (@command{gcc})
-Suppresses automatic inlining of small subprograms, which is enabled
+Suppresses automatic inlining of simple subprograms, which is enabled
if @option{-O3} is used.
+@item -fno-inline-small-functions
+@cindex @option{-fno-inline-small-functions} (@command{gcc})
+Suppresses automatic inlining of small subprograms, which is enabled
+if @option{-O2} is used.
+
@item -fno-inline-functions-called-once
@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
Suppresses inlining of subprograms local to the unit and called once
from within it, which is enabled if @option{-O1} is used.
+@item -fno-ivopts
+@cindex @option{-fno-ivopts} (@command{gcc})
+Suppresses high-level loop induction variable optimizations, which are
+enabled if @option{-O1} is used. These optimizations are generally
+profitable but, for some specific cases of loops with numerous uses
+of the iteration variable that follow a common pattern, they may end
+up destroying the regularity that could be exploited at a lower level
+and thus producing inferior code.
+
@item -fno-strict-aliasing
@cindex @option{-fno-strict-aliasing} (@command{gcc})
Causes the compiler to avoid assumptions regarding non-aliasing
@cindex @option{-gnatb} (@command{gcc})
Generate brief messages to @file{stderr} even if verbose mode set.
+@item -gnatB
+@cindex @option{-gnatB} (@command{gcc})
+Assume no invalid (bad) values except for 'Valid attribute use
+(@pxref{Validity Checking}).
+
@item -gnatc
@cindex @option{-gnatc} (@command{gcc})
Check syntax and semantics only (no code generation attempted).
+@item -gnatC
+@cindex @option{-gnatC} (@command{gcc})
+Generate CodePeer information (no code generation attempted).
+This switch will generate an intermediate representation suitable for
+use by CodePeer (@file{.scil} files). This switch is not compatible with
+code generation (it will, among other things, disable some switches such
+as -gnatn, and enable others such as -gnata).
+
@item -gnatd
@cindex @option{-gnatd} (@command{gcc})
Specify debug options for the compiler. The string of characters after
programmers, and these are documented at appropriate points in this
users guide.
+@ifclear vms
@item -gnatD
-@cindex @option{-gnatD} (@command{gcc})
+@cindex @option{-gnatD[nn]} (@command{gcc})
+@end ifclear
+@ifset vms
+@item /XDEBUG /LXDEBUG=nnn
+@end ifset
Create expanded source files for source level debugging. This switch
also suppress generation of cross-reference information
(see @option{-gnatx}).
@cindex @option{-gnatef} (@command{gcc})
Display full source path name in brief error messages.
+@item -gnateG
+@cindex @option{-gnateG} (@command{gcc})
+Save result of preprocessing in a text file.
+
@item -gnatem=@var{path}
@cindex @option{-gnatem} (@command{gcc})
Specify a mapping file
@end ifclear
(@pxref{Integrated Preprocessing}).
+@item -gnateS
+@cindex @option{-gnateS} (@command{gcc})
+Generate SCO (Source Coverage Obligation) information in the ALI
+file. This information is used by advanced coverage tools. See
+unit @file{SCOs} in the compiler sources for details in files
+@file{scos.ads} and @file{scos.adb}.
+
@item -gnatE
@cindex @option{-gnatE} (@command{gcc})
Full dynamic elaboration checks.
so that all standard warnings and all standard style options are turned on.
All warnings and style error messages are treated as errors.
-@item -gnatG
-@cindex @option{-gnatG} (@command{gcc})
+@ifclear vms
+@item -gnatG=nn
+@cindex @option{-gnatG[nn]} (@command{gcc})
+@end ifclear
+@ifset vms
+@item /EXPAND_SOURCE, /LEXPAND_SOURCE=nnn
+@end ifset
List generated expanded code in source form.
@item ^-gnath^/HELP^
@item ^-gnatI^/IGNORE_REP_CLAUSES^
@cindex @option{^-gnatI^IGNORE_REP_CLAUSES^} (@command{gcc})
-Ignore representation clauses. When this switch is used, all
+Ignore representation clauses. When this switch is used,
representation clauses are treated as comments. This is useful
when initially porting code where you want to ignore rep clause
problems, and also for compiling foreign code (particularly
-for use with ASIS).
+for use with ASIS). The representation clauses that are ignored
+are: enumeration_representation_clause, record_representation_clause,
+and attribute_definition_clause for the following attributes:
+Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
+Object_Size, Size, Small, Stream_Size, and Value_Size.
+Note that this option should be used only for compiling -- the
+code is likely to malfunction at run time.
@item -gnatjnn
@cindex @option{-gnatjnn} (@command{gcc})
@item -gnatm=@var{n}
@cindex @option{-gnatm} (@command{gcc})
Limit number of detected error or warning messages to @var{n}
-where @var{n} is in the range 1..999_999. The default setting if
-no switch is given is 9999. Compilation is terminated if this
-limit is exceeded. The equal sign here is optional.
+where @var{n} is in the range 1..999999. The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. The equal sign here is optional. A value of zero
+means that no limit applies.
@item -gnatn
@cindex @option{-gnatn} (@command{gcc})
pragma @code{Inline} is specified. This inlining is performed
by the front end and will be visible in the
@option{-gnatG} output.
-In some cases, this has proved more effective than the back end
-inlining resulting from the use of
-@option{-gnatn}.
-Note that
-@option{-gnatN} automatically implies
-@option{-gnatn} so it is not necessary
-to specify both options. There are a few cases that the back-end inlining
-catches that cannot be dealt with in the front-end.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@item -gnato
@cindex @option{-gnato} (@command{gcc})
Enable numeric overflow checking (which is not normally enabled by
-default). Not that division by zero is a separate check that is not
+default). Note that division by zero is a separate check that is not
controlled by this switch (division by zero checking is on by default).
@item -gnatp
@cindex @option{-gnatp} (@command{gcc})
-Suppress all checks.
+Suppress all checks. See @ref{Run-Time Checks} for details.
@item -gnatP
@cindex @option{-gnatP} (@command{gcc})
@item -gnatq
@cindex @option{-gnatq} (@command{gcc})
-Don't quit; try semantics, even if parse errors.
+Don't quit. Try semantics, even if parse errors.
@item -gnatQ
@cindex @option{-gnatQ} (@command{gcc})
-Don't quit; generate @file{ALI} and tree files even if illegalities.
+Don't quit. Generate @file{ALI} and tree files even if illegalities.
@item -gnatr
@cindex @option{-gnatr} (@command{gcc})
@item -gnatV
@cindex @option{-gnatV} (@command{gcc})
-Control level of validity checking. See separate section describing
-this feature.
+Control level of validity checking (@pxref{Validity Checking}).
@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^
@cindex @option{^-gnatw^/WARNINGS^} (@command{gcc})
@item
The switches
-@option{^-gnatz^/DISTRIBUTION_STUBS^}, @option{-gnatzc}, and @option{-gnatzr}
-may not be combined with any other switches.
+^^@option{/DISTRIBUTION_STUBS=},^
+@option{-gnatzc} and @option{-gnatzr} may not be combined with any other
+switches, and only one of them may appear in the command line.
@ifclear vms
@item
@item
Once a ``V'' appears in the string (that is a use of the @option{-gnatV}
switch), then all further characters in the switch are interpreted
-as validity checking options (see description of @option{-gnatV}).
+as validity checking options (@pxref{Validity Checking}).
+
+@item
+Option ``em'', ``ec'', ``ep'', ``l='' and ``R'' must be the last options in
+a combined list of options.
@end ifclear
@end itemize
The @code{m} stands for maximum.
@end ifclear
@var{n} is a decimal integer in the
-range of 1 to 999 and limits the number of error messages to be
-generated. For example, using @option{-gnatm2} might yield
+range of 1 to 999999 and limits the number of error or warning
+messages to be generated. For example, using
+@option{-gnatm2} might yield
@smallexample
e.adb:3:04: Incorrect spelling of keyword "function"
e.adb:5:35: missing ".."
-fatal error: maximum errors reached
+fatal error: maximum number of errors detected
compilation abandoned
@end smallexample
@noindent
+The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. A value of zero means that no limit applies.
+
+@noindent
Note that the equal sign is optional, so the switches
@option{-gnatm2} and @option{-gnatm=2} are equivalent.
@itemize @bullet
@item
-Full details on entities not available in high integrity mode
-@item
Details on possibly non-portable unchecked conversion
@item
List possible interpretations for ambiguous calls
This switch suppresses warnings for static fixed-point expressions whose
value is not an exact multiple of Small.
+@item -gnatw.b
+@emph{Activate warnings on biased representation.}
+@cindex @option{-gnatw.b} (@command{gcc})
+@cindex Biased representation
+This switch activates warnings when a size clause, value size clause, component
+clause, or component size clause forces the use of biased representation for an
+integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
+to represent 10/11). The default is that such warnings are generated.
+
+@item -gnatw.B
+@emph{Suppress warnings on biased representation.}
+@cindex @option{-gnatwB} (@command{gcc})
+This switch suppresses warnings for representation clauses that force the use
+of biased representation.
+
@item -gnatwc
@emph{Activate warnings on conditionals.}
@cindex @option{-gnatwc} (@command{gcc})
This switch disables warnings for a @code{with} of an internal GNAT
implementation unit.
+@item -gnatw.i
+@emph{Activate warnings on overlapping actuals.}
+@cindex @option{-gnatw.i} (@command{gcc})
+This switch enables a warning on statically detectable overlapping actuals in
+a subprogram call, when one of the actuals is an in-out parameter, and the
+types of the actuals are not by-copy types. The warning is off by default,
+and is not included under -gnatwa.
+
+@item -gnatw.I
+@emph{Disable warnings on overlapping actuals.}
+@cindex @option{-gnatw.I} (@command{gcc})
+This switch disables warnings on overlapping actuals in a call..
+
@item -gnatwj
@emph{Activate warnings on obsolescent features (Annex J).}
@cindex @option{-gnatwj} (@command{gcc})
This switch disables warnings for variables that are assigned or
initialized, but never read.
+@item -gnatw.m
+@emph{Activate warnings on suspicious modulus values.}
+@cindex @option{-gnatw.m} (@command{gcc})
+This switch activates warnings for modulus values that seem suspicious.
+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.
+
+@item -gnatw.M
+@emph{Disable warnings on suspicious modulus values.}
+@cindex @option{-gnatw.M} (@command{gcc})
+This switch disables warnings for suspicious modulus values.
+
@item -gnatwn
@emph{Set normal warnings mode.}
@cindex @option{-gnatwn} (@command{gcc})
@cindex @option{-gnatwR} (@command{gcc})
This switch suppresses warnings for redundant constructs.
+@item -gnatw.r
+@emph{Activate warnings for object renaming function.}
+@cindex @option{-gnatw.r} (@command{gcc})
+This switch activates warnings for an object renaming that renames a
+function call, which is equivalent to a constant declaration (as
+opposed to renaming the function itself). The default is that these
+warnings are given. This warning can also be turned on using
+@option{-gnatwa}.
+
+@item -gnatw.R
+@emph{Suppress warnings for object renaming function.}
+@cindex @option{-gnatwT} (@command{gcc})
+This switch suppresses warnings for object renaming function.
+
@item -gnatws
@emph{Suppress all warnings.}
@cindex @option{-gnatws} (@command{gcc})
@findex Validity Checking
@noindent
-The Ada Reference Manual has specific requirements for checking
-for invalid values. In particular, RM 13.9.1 requires that the
-evaluation of invalid values (for example from unchecked conversions),
-not result in erroneous execution. In GNAT, the result of such an
-evaluation in normal default mode is to either use the value
-unmodified, or to raise Constraint_Error in those cases where use
-of the unmodified value would cause erroneous execution. The cases
-where unmodified values might lead to erroneous execution are case
-statements (where a wild jump might result from an invalid value),
-and subscripts on the left hand side (where memory corruption could
-occur as a result of an invalid value).
-
-The @option{-gnatV^@var{x}^^} switch allows more control over the validity
-checking mode.
+The Ada Reference Manual defines the concept of invalid values (see
+RM 13.9.1). The primary source of invalid values is uninitialized
+variables. A scalar variable that is left uninitialized may contain
+an invalid value; the concept of invalid does not apply to access or
+composite types.
+
+It is an error to read an invalid value, but the RM does not require
+run-time checks to detect such errors, except for some minimal
+checking to prevent erroneous execution (i.e. unpredictable
+behavior). This corresponds to the @option{-gnatVd} switch below,
+which is the default. For example, by default, if the expression of a
+case statement is invalid, it will raise Constraint_Error rather than
+causing a wild jump, and if an array index on the left-hand side of an
+assignment is invalid, it will raise Constraint_Error rather than
+overwriting an arbitrary memory location.
+
+The @option{-gnatVa} may be used to enable additional validity checks,
+which are not required by the RM. These checks are often very
+expensive (which is why the RM does not require them). These checks
+are useful in tracking down uninitialized variables, but they are
+not usually recommended for production builds.
+
+The other @option{-gnatV^@var{x}^^} switches below allow finer-grained
+control; you can enable whichever validity checks you desire. However,
+for most debugging purposes, @option{-gnatVa} is sufficient, and the
+default @option{-gnatVd} (i.e. standard Ada behavior) is usually
+sufficient for non-debugging use.
+
+The @option{-gnatB} switch tells the compiler to assume that all
+values are valid (that is, within their declared subtype range)
+except in the context of a use of the Valid attribute. This means
+the compiler can generate more efficient code, since the range
+of values is better known at compile time. However, an uninitialized
+variable can cause wild jumps and memory corruption in this mode.
+
+The @option{-gnatV^@var{x}^^} switch allows control over the validity
+checking mode as described below.
@ifclear vms
The @code{x} argument is a string of letters that
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifclear
@ifset vms
The options allowed for this qualifier
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifset
@table @option
rule, together with h (no horizontal tabs), is to enforce a canonical format
for the use of blanks to separate source tokens.
+@item ^B^BOOLEAN_OPERATORS^
+@emph{Check Boolean operators.}
+The use of AND/OR operators is not permitted except in the cases of modular
+operands, array operands, and simple stand-alone boolean variables or
+boolean constants. In all other cases AND THEN/OR ELSE are required.
+
@item ^c^COMMENTS^
@emph{Check comments.}
Comments must meet the following set of rules:
the value of this suffix is used in the ordering (e.g.@: Junk2 comes
before Junk10).
+@item ^O^OVERRIDING_INDICATORS^
+@emph{Check that overriding subprograms are explicitly marked as such.}
+The declaration of a primitive operation of a type extension that overrides
+an inherited operation must carry an overriding indicator.
+
@item ^p^PRAGMA^
@emph{Check pragma casing.}
Pragma names must be written in mixed case, that is, the
a space must separate the two tokens.
@item
+if the token following a right parenthesis starts with a letter or digit, then
+a space must separate the two tokens.
+
+@item
A right parenthesis must either be the first non-blank character on
a line, or it must be preceded by a non-blank character.
XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
@end ifset
-
-
The switch
@ifclear vms
@option{-gnatyN}
@cindex Checks, stack overflow checking
@noindent
-If you compile with the default options, GNAT will insert many run-time
-checks into the compiled code, including code that performs range
-checking against constraints, but not arithmetic overflow checking for
-integer operations (including division by zero), checks for access
-before elaboration on subprogram calls, or stack overflow checking. All
-other run-time checks, as required by the Ada Reference Manual, are
-generated by default. The following @command{gcc} switches refine this
-default behavior:
+By default, the following checks are suppressed: integer overflow
+checks, stack overflow checks, and checks for access before
+elaboration on subprogram calls. All other checks, including range
+checks and array bounds checks, are turned on by default. The
+following @command{gcc} switches refine this default behavior.
@table @option
@c !sort!
@cindex Suppressing checks
@cindex Checks, suppressing
@findex Suppress
-Suppress all run-time checks as though @code{pragma Suppress (all_checks})
-had been present in the source. Validity checks are also suppressed (in
+This switch causes the unit to be compiled
+as though @code{pragma Suppress (All_checks)}
+had been present in the source. Validity checks are also eliminated (in
other words @option{-gnatp} also implies @option{-gnatVn}.
Use this switch to improve the performance
of the code at the expense of safety in the presence of invalid data or
program bugs.
+Note that when checks are suppressed, the compiler is allowed, but not
+required, to omit the checking code. If the run-time cost of the
+checking code is zero or near-zero, the compiler will generate it even
+if checks are suppressed. In particular, if the compiler can prove
+that a certain check will necessarily fail, it will generate code to
+do an unconditional ``raise'', even if checks are suppressed. The
+compiler warns in this case. Another case in which checks may not be
+eliminated is when they are embedded in certain run time routines such
+as math library routines.
+
+Of course, run-time checks are omitted whenever the compiler can prove
+that they will not fail, whether or not checks are suppressed.
+
+Note that if you suppress a check that would have failed, program
+execution is erroneous, which means the behavior is totally
+unpredictable. The program might crash, or print wrong answers, or
+do anything else. It might even do exactly what you wanted it to do
+(and then it might start failing mysteriously next week or next
+year). The compiler will generate code based on the assumption that
+the condition being checked is true, which can result in disaster if
+that assumption is wrong.
+
@item -gnato
@cindex @option{-gnato} (@command{gcc})
@cindex Overflow checks
range of the result type. The following example shows the distinction:
@smallexample @c ada
-X1 : Integer := Integer'Last;
-X2 : Integer range 1 .. 5 := 5;
-X3 : Integer := Integer'Last;
-X4 : Integer range 1 .. 5 := 5;
-F : Float := 2.0E+20;
+X1 : Integer := "Integer'Last";
+X2 : Integer range 1 .. 5 := "5";
+X3 : Integer := "Integer'Last";
+X4 : Integer range 1 .. 5 := "5";
+F : Float := "2.0E+20";
@dots{}
X1 := X1 + 1;
X2 := X2 + 1;
@end smallexample
@noindent
+Note that if explicit values are assigned at compile time, the
+compiler may be able to detect overflow at compile time, in which case
+no actual run-time checking code is required, and Constraint_Error
+will be raised unconditionally, with or without
+@option{-gnato}. That's why the assigned values in the above fragment
+are in quotes, the meaning is "assign a value not known to the
+compiler that happens to be equal to ...". The remaining discussion
+assumes that the compiler cannot detect the values at compile time.
+
Here the first addition results in a value that is outside the base range
of Integer, and hence requires an overflow check for detection of the
constraint error. Thus the first assignment to @code{X1} raises a
@code{Constraint_Error} exception only if @option{-gnato} is set.
-The second increment operation results in a violation
-of the explicit range constraint, and such range checks are always
-performed (unless specifically suppressed with a pragma @code{suppress}
-or the use of @option{-gnatp}).
+The second increment operation results in a violation of the explicit
+range constraint; such range checks are performed by default, and are
+unaffected by @option{-gnato}.
The two conversions of @code{F} both result in values that are outside
the base range of type @code{Integer} and thus will raise
@cindex Check, elaboration
Enables dynamic checks for access-before-elaboration
on subprogram calls and generic instantiations.
+Note that @option{-gnatE} is not necessary for safety, because in the
+default mode, GNAT ensures statically that the checks would not fail.
For full details of the effect and use of this switch,
@xref{Compiling Using gcc}.
@item -gnatN
@cindex @option{-gnatN} (@command{gcc})
-The front end inlining activated by this switch is generally more extensive,
-and quite often more effective than the standard @option{-gnatn} inlining mode.
-It will also generate additional dependencies.
-Note that
-@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
-to specify both options.
+This switch activates front-end inlining which also
+generates additional dependencies.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@end table
@node Auxiliary Output Control
Typically
these tools do the necessary compilations automatically, so you should
not have to specify this switch in normal operation.
+Note that the combination of switches @option{-gnatct}
+generates a tree in the form required by ASIS applications.
@item -gnatu
@cindex @option{-gnatu} (@command{gcc})
file @file{debug.adb}.
@end ifclear
-@item -gnatG
+@item -gnatG[=nn]
@cindex @option{-gnatG} (@command{gcc})
This switch causes the compiler to generate auxiliary output containing
a pseudo-source listing of the generated expanded code. Like most Ada
these cases, and consider whether it may be desirable to modify the coding
approach to improve efficiency.
+The optional parameter @code{nn} if present after -gnatG specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+
The format of the output is very similar to standard Ada source, and is
easily understood by an Ada programmer. The following special syntactic
additions correspond to low level features used in the generated code that
evaluation of the expression 1.0/27.0).
@end table
-@item -gnatD
+@item -gnatD[=nn]
@cindex @option{-gnatD} (@command{gcc})
When used in conjunction with @option{-gnatG}, this switch causes
the expanded source, as described above for
@option{-gnatDG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
+The optional parameter @code{nn} if present after -gnatD specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+
@item -gnatr
@cindex @option{-gnatr} (@command{gcc})
@cindex pragma Restrictions
@table @option
-@item -gnatem^^=^@var{path}
+@item -gnatem=@var{path}
@cindex @option{-gnatem} (@command{gcc})
A mapping file is a way to communicate to the compiler two mappings:
from unit names to file names (without any directory information) and from
sources are read over a slow network connection. In normal operation,
you need not be concerned with the format or use of mapping files,
and the @option{-gnatem} switch is not a switch that you would use
-explicitly. it is intended only for use by automatic tools such as
+explicitly. It is intended primarily for use by automatic tools such as
@command{gnatmake} running under the project file facility. The
description here of the format of mapping files is provided
for completeness and for possible use by other tools.
-A mapping file is a sequence of sets of three lines. In each set,
-the first line is the unit name, in lower case, with ``@code{%s}''
-appended for
-specs and ``@code{%b}'' appended for bodies; the second line is the
+A mapping file is a sequence of sets of three lines. In each set, the
+first line is the unit name, in lower case, with @code{%s} appended
+for specs and @code{%b} appended for bodies; the second line is the
file name; and the third line is the path name.
Example:
/gnat/project1/sources/main.2.ada
@end smallexample
-When the switch @option{-gnatem} is specified, the compiler will create
-in memory the two mappings from the specified file. If there is any problem
-(nonexistent file, truncated file or duplicate entries), no mapping will
-be created.
+When the switch @option{-gnatem} is specified, the compiler will
+create in memory the two mappings from the specified file. If there is
+any problem (nonexistent file, truncated file or duplicate entries),
+no mapping will be created.
-Several @option{-gnatem} switches may be specified; however, only the last
-one on the command line will be taken into account.
+Several @option{-gnatem} switches may be specified; however, only the
+last one on the command line will be taken into account.
-When using a project file, @command{gnatmake} create a temporary mapping file
-and communicates it to the compiler using this switch.
+When using a project file, @command{gnatmake} creates a temporary
+mapping file and communicates it to the compiler using this switch.
@end table
@noindent
This switch is similar to switch @option{^-D^/ASSOCIATE^} of @code{gnatprep}.
+@item -gnateG
+When integrated preprocessing is performed and the preprocessor modifies
+the source text, write the result of this preprocessing into a file
+<source>^.prep^_prep^.
+
@end table
@node Code Generation Control
@item ^-m^/ERROR_LIMIT=^@var{n}
@cindex @option{^-m^/ERROR_LIMIT^} (@command{gnatbind})
-Limit number of detected errors to @var{n}, where @var{n} is
-in the range 1..999_999. The default value if no switch is
-given is 9999. Binding is terminated if the limit is exceeded.
+Limit number of detected errors or warnings to @var{n}, where @var{n} is
+in the range 1..999999. The default value if no switch is
+given is 9999. If the number of warnings reaches this limit, then a
+message is output and further warnings are suppressed, the bind
+continues in this case. If the number of errors reaches this
+limit, then a message is output and the bind is abandoned.
+A value of zero means that no limit is enforced. The equal
+sign is optional.
+
@ifset unw
Furthermore, under Windows, the sources pointed to by the libraries path
set in the registry are not searched for.
@item ^-C^/MAPPING^
@cindex @option{^-C^/MAPPING^} (@command{gnatmake})
-Use a temporary mapping file. A mapping file is a way to communicate to the
-compiler two mappings: from unit names to file names (without any directory
-information) and from file names to path names (with full directory
-information). These mappings are used by the compiler to short-circuit the path
-search. When @command{gnatmake} is invoked with this switch, it will create
-a temporary mapping file, initially populated by the project manager,
-if @option{^-P^/PROJECT_FILE^} is used, otherwise initially empty.
-Each invocation of the compiler will add the newly accessed sources to the
-mapping file. This will improve the source search during the next invocation
-of the compiler.
+Use a temporary mapping file. A mapping file is a way to communicate
+to the compiler two mappings: from unit names to file names (without
+any directory information) and from file names to path names (with
+full directory information). A mapping file can make the compiler's
+file searches faster, especially if there are many source directories,
+or the sources are read over a slow network connection. If
+@option{^-P^/PROJECT_FILE^} is used, a mapping file is always used, so
+@option{^-C^/MAPPING^} is unnecessary; in this case the mapping file
+is initially populated based on the project file. If
+@option{^-C^/MAPPING^} is used without
+@option{^-P^/PROJECT_FILE^},
+the mapping file is initially empty. Each invocation of the compiler
+will add any newly accessed sources to the mapping file.
@item ^-C=^/USE_MAPPING_FILE=^@var{file}
@cindex @option{^-C=^/USE_MAPPING^} (@command{gnatmake})
@ifclear vms
@item -eL
@cindex @option{-eL} (@command{gnatmake})
+@cindex symbolic links
Follow all symbolic links when processing project files.
+This should be used if your project uses symbolic links for files or
+directories, but is not needed in other cases.
+
+@cindex naming scheme
+This also assumes that no directory matches the naming scheme for files (for
+instance that you do not have a directory called "sources.ads" when using the
+default GNAT naming scheme).
+
+When you do not have to use this switch (ie by default), gnatmake is able to
+save a lot of system calls (several per source file and object file), which
+can result in a significant speed up to load and manipulate a project file,
+especially when using source files from a remote system.
+
@end ifclear
@item ^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^
@subsection Controlling Run-Time Checks
@noindent
-By default, GNAT generates all run-time checks, except arithmetic overflow
-checking for integer operations and checks for access before elaboration on
+By default, GNAT generates all run-time checks, except integer overflow
+checks, stack overflow checks, and checks for access before elaboration on
subprogram calls. The latter are not required in default mode, because all
necessary checking is done at compile time.
@cindex @option{-gnatp} (@command{gcc})
This kind of optimization, called strict aliasing analysis, is
triggered by specifying an optimization level of @option{-O2} or
-higher and allows @code{GNAT} to generate more efficient code
+higher or @option{-Os} and allows @code{GNAT} to generate more efficient code
when access values are involved.
However, although this optimization is always correct in terms of
restriction since any possible desired effect can be achieved by
unchecked conversion of access values.
+The aliasing analysis done in strict aliasing mode can certainly
+have significant benefits. We have seen cases of large scale
+application code where the time is increased by up to 5% by turning
+this optimization off. If you have code that includes significant
+usage of unchecked conversion, you might want to just stick with
+@option{-O1} and avoid the entire issue. If you get adequate
+performance at this level of optimization level, that's probably
+the safest approach. If tests show that you really need higher
+levels of optimization, then you can experiment with @option{-O2}
+and @option{-O2 -fno-strict-aliasing} to see how much effect this
+has on size and speed of the code. If you really need to use
+@option{-O2} with strict aliasing in effect, then you should
+review any uses of unchecked conversion of access types,
+particularly if you are getting the warnings described above.
+
@ifset vms
@node Coverage Analysis
@subsection Coverage Analysis
time you compile, regarding the source files that it writes as temporary
files that you throw away.
+Note that if your file containing multiple units starts with a byte order
+mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
+will each start with a copy of this BOM, meaning that they can be compiled
+automatically in UTF-8 mode without needing to specify an explicit encoding.
+
@node Operating gnatchop in Compilation Mode
@section Operating gnatchop in Compilation Mode
Ada_05
Ada_2005
Assertion_Policy
+ Assume_No_Invalid_Values
C_Pass_By_Copy
Check_Name
Check_Policy
Compile_Time_Warning
Compiler_Unit
Component_Alignment
+ Convention_Identifier
Debug_Policy
Detect_Blocking
Discard_Names
Elaboration_Checks
Eliminate
Extend_System
+ Extensions_Allowed
External_Name_Casing
Fast_Math
Favor_Top_Level
@node Importing Other Projects
@subsection Importing Other Projects
@cindex @code{ADA_PROJECT_PATH}
+@cindex @code{GPR_PROJECT_PATH}
@noindent
A compilation unit in a source file in one project may depend on compilation
The imported project file is in the same directory as the importing project
file, or
@item
-You have defined ^an environment variable^a logical name^
+You have defined one or two ^environment variables^logical names^
that includes the directory containing
-the needed project file. The syntax of @code{ADA_PROJECT_PATH} is the same as
+the needed project file. The syntax of @code{GPR_PROJECT_PATH} and
+@code{ADA_PROJECT_PATH} is the same as
the syntax of @code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH}: a list of
directory names separated by colons (semicolons on Windows).
@end itemize
@noindent
-Thus, if we define @code{ADA_PROJECT_PATH} to include @file{^/gui^[GUI]^} and
+Thus, if we define @code{ADA_PROJECT_PATH} or @code{GPR_PROJECT_PATH}
+to include @file{^/gui^[GUI]^} and
@file{^/comm^[COMM]^}, then our project file @file{app_proj.gpr} can be written
as follows:
@itemize @bullet
@item
-@code{abstract}: qualify a project with no sources. An abstract project must
-have a declaration specifying that there are no sources in the project, and,
-if it extends another project, the project it extends must also be a qualified
-abstract project.
+@code{abstract}: qualify a project with no sources. A qualified abstract
+project must either have no declaration of attributes @code{Source_Dirs},
+@code{Source_Files}, @code{Languages} or @code{Source_List_File}, or one of
+@code{Source_Dirs}, @code{Source_Files}, or @code{Languages} must be declared
+as empty. If it extends another project, the project it extends must also be a
+qualified abstract project.
@item
@code{standard}: a standard project is a non library project with sources.
@item
@code{Cross_Reference}
@item
+@code{Check}
+@item
@code{Eliminate}
@item
@code{Pretty_Printer}
an error to have several files with the same source file name.
Projects can be specified to have no Ada source
-files: the value of (@code{Source_Dirs} or @code{Source_Files} may be an empty
+files: the value of @code{Source_Dirs} or @code{Source_Files} may be an empty
list, or the @code{"Ada"} may be absent from @code{Languages}:
@smallexample @c projectfile
@node Importing Projects
@section Importing Projects
@cindex @code{ADA_PROJECT_PATH}
+@cindex @code{GPR_PROJECT_PATH}
@noindent
An immediate source of a project P may depend on source files that
@item
In between, all the directories referenced in the
-^environment variable^logical name^ @env{ADA_PROJECT_PATH} if it exists.
+^environment variables^logical names^ @env{GPR_PROJECT_PATH}
+and @env{ADA_PROJECT_PATH} if they exist, and in that order.
@end itemize
@noindent
will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec
if the longest suffix is @code{Spec_Suffix ("Ada")}.
+If the suffix does not start with a '.', a file with a name exactly equal
+to the suffix will also be part of the project (for instance if you define
+the suffix as @code{Makefile}, a file called @file{Makefile} will be part
+of the project. This is not interesting in general when using projects to
+compile. However, it might become useful when a project is also used to
+find the list of source files in an editor, like the GNAT Programming System
+(GPS).
+
If @code{Body_Suffix ("Ada")} is not specified, then the default is
@code{"^.adb^.ADB^"}.
for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
@end smallexample
+When the source file contains several units, you can indicate at what
+position the unit occurs in the file, with the following. The first unit
+in the file has index 1
+
+@smallexample @c projectfile
+ for Body ("top") use "foo.a" at 1;
+ for Body ("foo") use "foo.a" at 2;
+@end smallexample
+
@item @code{Body}
You can use the associative array attribute @code{Body} to
@noindent
@emph{Library projects} are projects whose object code is placed in a library.
-(Note that this facility is not yet supported on all platforms)
+(Note that this facility is not yet supported on all platforms).
+
+@code{gnatmake} or @code{gprbuild} will collect all object files into a
+single archive, which might either be a shared or a static library. This
+library can later on be linked with multiple executables, potentially
+reducing their sizes.
+
+If your project file specifies languages other than Ada, but you are still
+using @code{gnatmake} to compile and link, the latter will not try to
+compile your sources other than Ada (you should use @code{gprbuild} if that
+is your intent). However, @code{gnatmake} will automatically link all object
+files found in the object directory, whether or not they were compiled from
+an Ada source file. This specific behavior only applies when multiple
+languages are specified.
To create a library project, you need to define in its project file
two project-level attributes: @code{Library_Name} and @code{Library_Dir}.
package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^})
@item
+package @code{Check} for command CHECK
+(invoking @code{^gnatcheck^gnatcheck^})
+
+@item
package @code{Metrics} for command METRIC
(invoking @code{^gnatmetric^gnatmetric^})
use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}).
@menu
-* gnatxref Switches::
-* gnatfind Switches::
+* Switches for gnatxref::
+* Switches for gnatfind::
* Project Files for gnatxref and gnatfind::
* Regular Expressions in gnatfind and gnatxref::
* Examples of gnatxref Usage::
* Examples of gnatfind Usage::
@end menu
-@node gnatxref Switches
+@node Switches for gnatxref
@section @code{gnatxref} Switches
@noindent
you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of
@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}.
-@node gnatfind Switches
+@node Switches for gnatfind
@section @code{gnatfind} Switches
@noindent
@cindex @option{-nostdlib} (@command{gnatfind})
Do not look for library files in the system default directory.
+@item --ext=@var{extension}
+@cindex @option{--ext} (@command{gnatfind})
+Specify an alternate ali file extension. The default is @code{ali} and other
+extensions (e.g. @code{sli} for SPARK library files) may be specified via this
+switch. Note that if this switch overrides the default, which means that only
+the new extension will be considered.
+
@item --RTS=@var{rts-path}
@cindex @option{--RTS} (@command{gnatfind})
Specifies the default location of the runtime library. Same meaning as the
Do not place the keyword @code{is} on a separate line in a subprogram body in
case if the spec occupies more then one line.
+@cindex @option{^--separate-label^/SEPARATE_LABEL^} (@command{gnatpp})
+@item ^--separate-label^/SEPARATE_LABEL^
+Place statement label(s) on a separate line, with the following statement
+on the next line.
+
@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
Place the keyword @code{loop} in FOR and WHILE loop statements and the
@item ^-x^/XML^
Generate the XML output
+@cindex @option{^-xs^/XSD^} (@command{gnatmetric})
+@item ^-xs^/XSD^
+Generate the XML output and the XML schema file that describes the structure
+of the XML metric report, this schema is assigned to the XML file. The schema
+file has the same name as the XML output file with @file{.xml} suffix replaced
+with @file{.xsd}
+
@cindex @option{^-nt^/NO_TEXT^} (@command{gnatmetric})
@item ^-nt^/NO_TEXT^
Do not generate the output in text form (implies @option{^-x^/XML^})
@cindex @option{--no-lines@var{x}}
@end ifclear
-@item ^--lines-all^/LINE_COUNT_METRICS=ALL_ON^
+@item ^--lines-all^/LINE_COUNT_METRICS=ALL^
Report all the line metrics
-@item ^--no-lines-all^/LINE_COUNT_METRICS=ALL_OFF^
+@item ^--no-lines-all^/LINE_COUNT_METRICS=NONE^
Do not report any of line metrics
-@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES_ON^
+@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES^
Report the number of all lines
-@item ^--no-lines^/LINE_COUNT_METRICS=ALL_LINES_OFF^
+@item ^--no-lines^/LINE_COUNT_METRICS=NOALL_LINES^
Do not report the number of all lines
-@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES_ON^
+@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES^
Report the number of code lines
-@item ^--no-lines-code^/LINE_COUNT_METRICS=CODE_LINES_OFF^
+@item ^--no-lines-code^/LINE_COUNT_METRICS=NOCODE_LINES^
Do not report the number of code lines
-@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_ON^
+@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES^
Report the number of comment lines
-@item ^--no-lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_OFF^
+@item ^--no-lines-comment^/LINE_COUNT_METRICS=NOCOMMENT_LINES^
Do not report the number of comment lines
-@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_ON^
+@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES^
Report the number of code lines containing
end-of-line comments
-@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_OFF^
+@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=NOCODE_COMMENT_LINES^
Do not report the number of code lines containing
end-of-line comments
-@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_ON^
+@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE^
Report the comment percentage in the program text
-@item ^--no-lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_OFF^
+@item ^--no-lines-ratio^/LINE_COUNT_METRICS=NOCOMMENT_PERCENTAGE^
Do not report the comment percentage in the program text
-@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_ON^
+@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES^
Report the number of blank lines
-@item ^--no-lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_OFF^
+@item ^--no-lines-blank^/LINE_COUNT_METRICS=NOBLANK_LINES^
Do not report the number of blank lines
-@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_ON^
+@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES^
Report the average number of code lines in subprogram bodies, task bodies,
entry bodies and statement sequences in package bodies. The metric is computed
and reported for the whole set of processed Ada sources only.
-@item ^--no-lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_OFF^
+@item ^--no-lines-average^/LINE_COUNT_METRICS=NOAVERAGE_BODY_LINES^
Do not report the average number of code lines in subprogram bodies,
task bodies, entry bodies and statement sequences in package bodies.
@cindex @option{--no-syntax@var{x}} (@command{gnatmetric})
@end ifclear
-@item ^--syntax-all^/SYNTAX_METRICS=ALL_ON^
+@item ^--syntax-all^/SYNTAX_METRICS=ALL^
Report all the syntax metrics
-@item ^--no-syntax-all^/ALL_OFF^
+@item ^--no-syntax-all^/SYNTAX_METRICS=NONE^
Do not report any of syntax metrics
-@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS_ON^
+@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS^
Report the total number of declarations
-@item ^--no-declarations^/SYNTAX_METRICS=DECLARATIONS_OFF^
+@item ^--no-declarations^/SYNTAX_METRICS=NODECLARATIONS^
Do not report the total number of declarations
-@item ^--statements^/SYNTAX_METRICS=STATEMENTS_ON^
+@item ^--statements^/SYNTAX_METRICS=STATEMENTS^
Report the total number of statements
-@item ^--no-statements^/SYNTAX_METRICS=STATEMENTS_OFF^
+@item ^--no-statements^/SYNTAX_METRICS=NOSTATEMENTS^
Do not report the total number of statements
-@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_ON^
+@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS^
Report the number of public subprograms in a compilation unit
-@item ^--no-public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_OFF^
+@item ^--no-public-subprograms^/SYNTAX_METRICS=NOPUBLIC_SUBPROGRAMS^
Do not report the number of public subprograms in a compilation unit
-@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_ON^
+@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS^
Report the number of all the subprograms in a compilation unit
-@item ^--no-all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_OFF^
+@item ^--no-all-subprograms^/SYNTAX_METRICS=NOALL_SUBPROGRAMS^
Do not report the number of all the subprograms in a compilation unit
-@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES_ON^
+@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES^
Report the number of public types in a compilation unit
-@item ^--no-public-types^/SYNTAX_METRICS=PUBLIC_TYPES_OFF^
+@item ^--no-public-types^/SYNTAX_METRICS=NOPUBLIC_TYPES^
Do not report the number of public types in a compilation unit
-@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES_ON^
+@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES^
Report the number of all the types in a compilation unit
-@item ^--no-all-types^/SYNTAX_METRICS=ALL_TYPES_OFF^
+@item ^--no-all-types^/SYNTAX_METRICS=NOALL_TYPES^
Do not report the number of all the types in a compilation unit
-@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_ON^
+@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING^
Report the maximal program unit nesting level
@item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^
Do not report the maximal program unit nesting level
-@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_ON^
+@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING^
Report the maximal construct nesting level
-@item ^--no-construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_OFF^
+@item ^--no-construct-nesting^/SYNTAX_METRICS=NOCONSTRUCT_NESTING^
Do not report the maximal construct nesting level
@end table
@cindex @option{--no-complexity@var{x}}
@end ifclear
-@item ^--complexity-all^/COMPLEXITY_METRICS=ALL_ON^
+@item ^--complexity-all^/COMPLEXITY_METRICS=ALL^
Report all the complexity metrics
-@item ^--no-complexity-all^/COMPLEXITY_METRICS=ALL_OFF^
+@item ^--no-complexity-all^/COMPLEXITY_METRICS=NONE^
Do not report any of complexity metrics
-@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_ON^
+@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC^
Report the McCabe Cyclomatic Complexity
-@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_OFF^
+@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=NOCYCLOMATIC^
Do not report the McCabe Cyclomatic Complexity
-@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_ON^
+@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL^
Report the Essential Complexity
-@item ^--no-complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_OFF^
+@item ^--no-complexity-essential^/COMPLEXITY_METRICS=NOESSENTIAL^
Do not report the Essential Complexity
@item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^
Report maximal loop nesting level
-@item ^--no-loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_OFF^
+@item ^--no-loop-nesting^/COMPLEXITY_METRICS=NOLOOP_NESTING^
Do not report maximal loop nesting level
-@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_ON^
+@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY^
Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
task bodies, entry bodies and statement sequences in package bodies.
The metric is computed and reported for whole set of processed Ada sources
only.
-@item ^--no-complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_OFF^
+@item ^--no-complexity-average^/COMPLEXITY_METRICS=NOAVERAGE_COMPLEXITY^
Do not report the average McCabe Cyclomatic Complexity for all the subprogram
bodies, task bodies, entry bodies and statement sequences in package bodies
Do not consider @code{exit} statements as @code{goto}s when
computing Essential Complexity
+@item ^--extra-exit-points^/EXTRA_EXIT_POINTS^
+Report the extra exit points for subprogram bodies. As an exit point, this
+metric counts @code{return} statements and raise statements in case when the
+raised exception is not handled in the same body. In case of a function this
+metric subtracts 1 from the number of exit points, because a function body
+must contain at least one @code{return} statement.
+
+@item ^--no-extra-exit-points^/NOEXTRA_EXIT_POINTS^
+Do not report the extra exit points for subprogram bodies
@end table
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 (if any) is considered
-together with its spec when counting the dependencies. For dependencies
+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.
@cindex @option{/COUPLING_METRICS} (@command{gnatmetric})
@end ifset
-@item ^--coupling-all^/COUPLING_METRICS=ALL_ON^
+@item ^--coupling-all^/COUPLING_METRICS=ALL^
Report all the coupling metrics
-@item ^--no-coupling-all^/COUPLING_METRICS=ALL_OFF^
+@item ^--no-coupling-all^/COUPLING_METRICS=NONE^
Do not report any of metrics
-@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_ON^
+@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT^
Report package efferent coupling
-@item ^--no-package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_OFF^
+@item ^--no-package-efferent-coupling^/COUPLING_METRICS=NOPACKAGE_EFFERENT^
Do not report package efferent coupling
-@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_ON^
+@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT^
Report package afferent coupling
-@item ^--no-package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_OFF^
+@item ^--no-package-afferent-coupling^/COUPLING_METRICS=NOPACKAGE_AFFERENT^
Do not report package afferent coupling
-@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_ON^
+@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT^
Report category efferent coupling
-@item ^--no-category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_OFF^
+@item ^--no-category-efferent-coupling^/COUPLING_METRICS=NOCATEGORY_EFFERENT^
Do not report category efferent coupling
-@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_ON^
+@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT^
Report category afferent coupling
-@item ^--no-category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_OFF^
+@item ^--no-category-afferent-coupling^/COUPLING_METRICS=NOCATEGORY_AFFERENT^
Do not report category afferent coupling
@end table
All compilation units comprising an application, including those in a library,
need to be elaborated in an order partially defined by Ada's semantics. GNAT
computes the elaboration order from the @file{ALI} files and this is why they
-constitute a mandatory part of GNAT libraries. Except in the case of
-@emph{stand-alone libraries}, where a specific library elaboration routine is
-produced independently of the application(s) using the library.
+constitute a mandatory part of GNAT libraries.
+@emph{Stand-alone libraries} are the exception to this rule because a specific
+library elaboration routine is produced independently of the application(s)
+using the library.
@node General Ada Libraries
@section General Ada Libraries
@node Installing a library
@subsection Installing a library
@cindex @code{ADA_PROJECT_PATH}
+@cindex @code{GPR_PROJECT_PATH}
@noindent
If you use project files, library installation is part of the library build
files and libraries in the directories mentioned in the project file. For
convenience, the user's library project file should be installed in a location
that will be searched automatically by the GNAT
-builder. These are the directories referenced in the @env{ADA_PROJECT_PATH}
+builder. These are the directories referenced in the @env{GPR_PROJECT_PATH}
environment variable (@pxref{Importing Projects}), and also the default GNAT
library location that can be queried with @command{gnatls -v} and is usually of
the form $gnat_install_root/lib/gnat.
Here is an example of simple library interface for use with C main program:
@smallexample @c ada
-package Interface is
+package My_Package is
procedure Do_Something;
pragma Export (C, Do_Something, "do_something");
procedure Do_Something_Else;
pragma Export (C, Do_Something_Else, "do_something_else");
-end Interface;
+end My_Package;
@end smallexample
@noindent
The @code{gnatmem} utility monitors dynamic allocation and
deallocation activity in a program, and displays information about
incorrect deallocations and possible sources of memory leaks.
-It provides three type of information:
+It is designed to work in association with a static runtime library
+only and in this context provides three types of information:
@itemize @bullet
@item
General information concerning memory management, such as the total
columns:
@noindent
-Index | Task Name | Stack Size | Actual Use [min - max]
+Index | Task Name | Stack Size | Stack Usage [Value +/- Variation]
@noindent
where:
@item Stack Size
is the maximum size for the stack.
-@item Actual Use
-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 real amount of stack used is between the min
-and max values.
+@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.
@end table
@smallexample
$ gnatcheck @ovar{switches} @{@var{filename}@}
@r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
- @r{[}-cargs @var{gcc_switches}@r{]} @r{[}-rules @var{rule_options}@r{]}
+ @r{[}-cargs @var{gcc_switches}@r{]} -rules @var{rule_options}
@end smallexample
@noindent
@end itemize
@noindent
-Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be supplied.
+Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be
+supplied.
@menu
* Format of the Report File::
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
+* Example of gnatcheck Usage::
@end menu
@node Format of the Report File
@noindent
The @command{gnatcheck} tool outputs on @file{stdout} all messages concerning
rule violations.
-It also creates, in the current
-directory, a text file named @file{^gnatcheck.out^GNATCHECK.OUT^} that
-contains the complete report of the last gnatcheck run. This report contains:
+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 a list of the Ada source files being checked,
-@item a list of enabled and disabled rules,
-@item a list of the diagnostic messages, ordered in three different ways
-and collected in three separate
-sections. Section 1 contains the raw list of diagnostic messages. It
-corresponds to the output going to @file{stdout}. Section 2 contains
-messages ordered by rules.
-Section 3 contains messages ordered by source files.
+@item 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
@node General gnatcheck Switches
@cindex @option{^-a^/ALL^} (@command{gnatcheck})
@item ^-a^/ALL^
Process all units including those with read-only ALI files such as
-those from GNAT Run-Time library.
+those from the GNAT Run-Time library.
@ifclear vms
@ignore
@cindex @option{-dd} (@command{gnatcheck})
@item -dd
-Progress indicator mode (for use in GPS)
+Progress indicator mode (for use in GPS).
@end ifclear
@cindex @option{^-h^/HELP^} (@command{gnatcheck})
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 diagnoses about rule violations are placed in the
-@command{gnatcheck} report file only, without duplicating in @file{stdout}.
+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{^-s1^/COMPILER_STYLE^} (@command{gnatcheck})
-@item ^-s1^/COMPILER_STYLE^
-Include the compiler-style section in the report file
-
-@cindex @option{^-s2^/BY_RULES^} (@command{gnatcheck})
-@item ^-s2^/BY_RULES^
-Include the section containing diagnoses ordered by rules in the report file
+@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{^-s3^/BY_FILES_BY_RULES^} (@command{gnatcheck})
-@item ^-s3^/BY_FILES_BY_RULES^
-Include the section containing diagnoses ordered by files and then by rules
-in the report file
+@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
@noindent
@cindex @option{-from} (@command{gnatcheck})
@item -from=@var{rule_option_filename}
-Read the rule options from the text file @var{rule_option_filename}, referred as
-``rule file'' below.
+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 enabled, except for
-the checks performed by the compiler.
-@ignore
-and the checks associated with the
-global rules.
-@end ignore
+The default behavior is that all the rule checks are disabled.
-A rule file is a text file containing a set of rule options.
-@cindex Rule file (for @code{gnatcheck})
+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). The rule file has free format; that is,
-you do not have to start a new rule option on a new line.
+lines and end-of-line comments). There can be several rule options on a
+single line (separated by a space).
-A rule file may contain other @option{-from=@var{rule_option_filename}}
+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 rule file during the rule files processing. In case a
+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}}),
-the processing of rule files is interrupted and a part of their content
-is ignored.
+processing fails with an error message.
@node Adding the Results of Compiler Checks to gnatcheck Output
@table @option
@item Restrictions
-To record restrictions violations (that are performed by the compiler if the
+To record restrictions violations (which are performed by the compiler if the
pragma @code{Restrictions} or @code{Restriction_Warnings} are given),
-use the rule named
-@code{Restrictions} with the same parameters as pragma
+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 rule named
-@code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
-which enables all the standard style checks that corresponds to @option{-gnatyy}
-GNAT style check option, or a string that has exactly the same
-structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
-@code{Style_Checks} (for further information about this pragma,
+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 rule
-named @code{Warnings} with a parameter that is a valid
-@i{static_string_expression} argument of GNAT pragma @code{Warnings}
-(for further information about this pragma, @pxref{Pragma Warnings,,,
-gnat_rm, GNAT Reference Manual}). Note, that in case of gnatcheck
+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
@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
* Ceiling_Violations::
@end ignore
+* Complex_Inlined_Subprograms::
* Controlled_Type_Declarations::
* Declarations_In_Blocks::
+* Deep_Inheritance_Hierarchies::
+* Deeply_Nested_Generics::
+* Deeply_Nested_Inlining::
+@ignore
+* Deeply_Nested_Local_Inlining::
+@end ignore
* Default_Parameters::
+* Direct_Calls_To_Primitives::
* Discriminated_Records::
* Enumeration_Ranges_In_CASE_Statements::
* Exceptions_As_Control_Flow::
+* Exits_From_Conditional_Loops::
* EXIT_Statements_With_No_Loop_Name::
* Expanded_Loop_Exit_Names::
* Explicit_Full_Discrete_Ranges::
* Float_Equality_Checks::
+* Forbidden_Attributes::
* Forbidden_Pragmas::
* Function_Style_Procedures::
* Generics_In_Subprograms::
@ignore
* Improperly_Called_Protected_Entries::
@end ignore
-* Metrics_Violation::
+* Metrics::
+* Misnamed_Controlling_Parameters::
* Misnamed_Identifiers::
* Multiple_Entries_In_Protected_Definitions::
* Name_Clashes::
* Side_Effect_Functions::
@end ignore
* Slices::
+* Too_Many_Parents::
* Unassigned_OUT_Parameters::
* Uncommented_BEGIN_In_Package_Bodies::
+* Unconditional_Exits::
* Unconstrained_Array_Returns::
* Universal_Ranges::
* Unnamed_Blocks_And_Loops::
* Unused_Subprograms::
@end ignore
* USE_PACKAGE_Clauses::
+* Visible_Components::
* Volatile_Objects_Without_Address_Clauses::
@end menu
@cindex @code{Anonymous_Subtypes} rule (for @command{gnatcheck})
@noindent
-Flag all uses of anonymous subtypes. A use of an anonymous subtype is
+Flag all uses of anonymous subtypes (except cases when subtype indication
+is a part of a record component definition, and this subtype indication
+depends on a discriminant). A use of an anonymous subtype is
any instance of a subtype indication with a constraint, other than one
that occurs immediately within a subtype declaration. Any use of a range
other than as a constraint used immediately within a subtype declaration
@ignore
@node Ceiling_Violations
-@subsection @code{Ceiling_Violations} (under construction, GLOBAL)
+@subsection @code{Ceiling5_Violations} (under construction, GLOBAL)
@cindex @code{Ceiling_Violations} rule (for @command{gnatcheck})
@noindent
This rule has no parameters.
+@node Complex_Inlined_Subprograms
+@subsection @code{Complex_Inlined_Subprograms}
+@cindex @code{Complex_Inlined_Subprograms} rule (for @command{gnatcheck})
+
+@noindent
+Flags a subprogram (or generic subprogram) if
+pragma Inline is applied to the subprogram and at least one of the following
+conditions is met:
+
+@itemize @bullet
+@item
+it contains at least one complex declaration such as a subprogram body,
+package, task, protected declaration, or a generic instantiation
+(except instantiation of @code{Ada.Unchecked_Conversion});
+
+@item
+it contains at least one complex statement such as a loop, a case
+or a if statement, or a short circuit control form;
+
+@item
+the number of statements exceeds
+a value specified by the @option{N} rule parameter;
+@end itemize
+
+@noindent
+This rule has the following (mandatory) parameter for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximum allowed total number of statements
+in the subprogram body.
+@end table
+
@node Declarations_In_Blocks
@subsection @code{Declarations_In_Blocks}
This rule has no parameters.
-@node Default_Parameters
-@subsection @code{Default_Parameters}
-@cindex @code{Default_Parameters} rule (for @command{gnatcheck})
+@node Deep_Inheritance_Hierarchies
+@subsection @code{Deep_Inheritance_Hierarchies}
+@cindex @code{Deep_Inheritance_Hierarchies} rule (for @command{gnatcheck})
@noindent
-Flag all default expressions for subprogram parameters. Parameter
-declarations of formal and generic subprograms are also checked.
+Flags a tagged derived type declaration or an interface type declaration if
+its depth (in its inheritance
+hierarchy) exceeds the value specified by the @option{N} rule parameter.
-This rule has no parameters.
+The inheritance depth of a tagged type or interface type is defined as 0 for
+a type with no parent and no progenitor, and otherwise as 1 + max of the
+depths of the immediate parent and immediate progenitors.
+This rule does not flag private extension
+declarations. In the case of a private extension, the corresponding full
+declaration is checked.
-@node Discriminated_Records
-@subsection @code{Discriminated_Records}
-@cindex @code{Discriminated_Records} rule (for @command{gnatcheck})
+This rule has the following (mandatory) parameter for the @option{+R} option:
-@noindent
-Flag all declarations of record types with discriminants. Only the
-declarations of record and record extension types are checked. Incomplete,
-formal, private, derived and private extension type declarations are not
-checked. Task and protected type declarations also are not checked.
+@table @emph
+@item N
+Integer not less than -1 specifying the maximal allowed depth of any inheritance
+hierarchy. If the rule parameter is set to -1, the rule flags all the declarations
+of tagged and interface types.
+@end table
-This rule has no parameters.
+@node Deeply_Nested_Generics
+@subsection @code{Deeply_Nested_Generics}
+@cindex @code{Deeply_Nested_Generics} rule (for @command{gnatcheck})
-@node Enumeration_Ranges_In_CASE_Statements
-@subsection @code{Enumeration_Ranges_In_CASE_Statements}
+@noindent
+Flags a generic declaration nested in another generic declaration if
+the nesting level of the inner generic exceeds
+a value specified by the @option{N} rule parameter.
+The nesting level is the number of generic declaratons that enclose the given
+(generic) declaration. Formal packages are not flagged by this rule.
+
+This rule has the following (mandatory) parameters for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed nesting level
+for a generic declaration.
+@end table
+
+@node Deeply_Nested_Inlining
+@subsection @code{Deeply_Nested_Inlining}
+@cindex @code{Deeply_Nested_Inlining} rule (for @command{gnatcheck})
+
+@noindent
+Flags a subprogram (or generic subprogram) if
+pragma Inline has been applied to the subprogram but the subprogram
+calls to another inlined subprogram that results in nested inlining
+with nesting depth exceeding the value specified by the
+@option{N} rule parameter.
+
+This rule requires the global analysis of all the compilation units that
+are @command{gnatcheck} arguments; such analysis may affect the tool's
+performance.
+
+This rule has the following (mandatory) parameter for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed level of nested inlining.
+@end table
+
+
+@ignore
+@node Deeply_Nested_Local_Inlining
+@subsection @code{Deeply_Nested_Local_Inlining}
+@cindex @code{Deeply_Nested_Local_Inlining} rule (for @command{gnatcheck})
+
+@noindent
+Flags a subprogram body if a pragma @code{Inline} is applied to the
+corresponding subprogram (or generic subprogram) and the body contains a call
+to another inlined subprogram that results in nested inlining with nesting
+depth more then a value specified by the @option{N} rule parameter.
+This rule is similar to @code{Deeply_Nested_Inlining} rule, but it
+assumes that calls to subprograms in
+with'ed units are not inlided, so all the analysis of the depth of inlining is
+limited by the compilation unit where the subprogram body is located and the
+units it depends semantically upon. Such analysis may be usefull for the case
+when neiter @option{-gnatn} nor @option{-gnatN} option is used when building
+the executable.
+
+This rule has the following (mandatory) parameters for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed level of nested inlining.
+@end table
+
+@end ignore
+
+@node Default_Parameters
+@subsection @code{Default_Parameters}
+@cindex @code{Default_Parameters} rule (for @command{gnatcheck})
+
+@noindent
+Flag all default expressions for subprogram parameters. Parameter
+declarations of formal and generic subprograms are also checked.
+
+This rule has no parameters.
+
+
+@node Direct_Calls_To_Primitives
+@subsection @code{Direct_Calls_To_Primitives}
+@cindex @code{Direct_Calls_To_Primitives} rule (for @command{gnatcheck})
+
+@noindent
+Flags any non-dispatching call to a dispatching primitive operation, except
+for the common idiom where a primitive subprogram for a tagged type
+directly calls the same primitive subprogram of the type's immediate ancestor.
+
+This rule has no parameters.
+
+
+@node Discriminated_Records
+@subsection @code{Discriminated_Records}
+@cindex @code{Discriminated_Records} rule (for @command{gnatcheck})
+
+@noindent
+Flag all declarations of record types with discriminants. Only the
+declarations of record and record extension types are checked. Incomplete,
+formal, private, derived and private extension type declarations are not
+checked. Task and protected type declarations also are not checked.
+
+This rule has no parameters.
+
+
+@node Enumeration_Ranges_In_CASE_Statements
+@subsection @code{Enumeration_Ranges_In_CASE_Statements}
@cindex @code{Enumeration_Ranges_In_CASE_Statements} (for @command{gnatcheck})
@noindent
The rule has no parameters.
+@node Exits_From_Conditional_Loops
+@subsection @code{Exits_From_Conditional_Loops}
+@cindex @code{Exits_From_Conditional_Loops} (for @command{gnatcheck})
+
+@noindent
+Flag any exit statement if it transfers the control out of a @code{for} loop
+or a @code{while} loop. This includes cases when the @code{exit} statement
+applies to a @code{FOR} or @code{while} loop, and cases when it is enclosed
+in some @code{for} or @code{while} loop, but transfers the control from some
+outer (inconditional) @code{loop} statement.
+
+The rule has no parameters.
+
+
@node EXIT_Statements_With_No_Loop_Name
@subsection @code{EXIT_Statements_With_No_Loop_Name}
@cindex @code{EXIT_Statements_With_No_Loop_Name} (for @command{gnatcheck})
This rule has no parameters.
+@node Forbidden_Attributes
+@subsection @code{Forbidden_Attributes}
+@cindex @code{Forbidden_Attributes} rule (for @command{gnatcheck})
+
+@noindent
+Flag each use of the specified attributes. The attributes to be detected are
+named in the rule's parameters.
+
+This rule has the following parameters:
+
+@itemize @bullet
+@item For the @option{+R} option
+
+@table @asis
+@item @emph{Attribute_Designator}
+Adds the specified attribute to the set of attributes to be detected and sets
+the detection checks for all the specified attributes ON.
+If @emph{Attribute_Designator}
+does not denote any attribute defined in the Ada standard
+or in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference
+Manual}, it is treated as the name of unknown attribute.
+
+@item @code{GNAT}
+All the GNAT-specific attributes are detected; this sets
+the detection checks for all the specified attributes ON.
+
+@item @code{ALL}
+All attributes are detected; this sets the rule ON.
+@end table
+
+@item For the @option{-R} option
+@table @asis
+@item @emph{Attribute_Designator}
+Removes the specified attribute from the set of attributes to be
+detected without affecting detection checks for
+other attributes. If @emph{Attribute_Designator} does not correspond to any
+attribute defined in the Ada standard or in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference Manual},
+this option is treated as turning OFF detection of all unknown attributes.
+
+@item GNAT
+Turn OFF detection of all GNAT-specific attributes
+
+@item ALL
+Clear the list of the attributes to be detected and
+turn the rule OFF.
+@end table
+@end itemize
+
+@noindent
+Parameters are not case sensitive. If @emph{Attribute_Designator} does not
+have the syntax of an Ada identifier and therefore can not be considered as a
+(part of an) attribute designator, a diagnostic message is generated and the
+corresponding parameter is ignored. (If an attribute allows a static
+expression to be a part of the attribute designator, this expression is
+ignored by this rule.)
+
+When more then one parameter is given in the same rule option, the parameters
+must be separated by commas.
+
+If more then one option for this rule is specified for the gnatcheck call, a
+new option overrides the previous one(s).
+
+The @option{+R} option with no parameters turns the rule ON, with the set of
+attributes to be detected defined by the previous rule options.
+(By default this set is empty, so if the only option specified for the rule is
+@option{+RForbidden_Attributes} (with
+no parameter), then the rule is enabled, but it does not detect anything).
+The @option{-R} option with no parameter turns the rule OFF, but it does not
+affect the set of attributes to be detected.
+
+
@node Forbidden_Pragmas
@subsection @code{Forbidden_Pragmas}
@cindex @code{Forbidden_Pragmas} rule (for @command{gnatcheck})
This rule has no parameters.
@end ignore
-@node Metrics_Violation
-@subsection @code{Metrics_Violation}
+@node Metrics
+@subsection @code{Metrics}
@cindex @code{Metrics} rule (for @command{gnatcheck})
@noindent
-This is an umbrella rule for a set of metrics-based checks. The parameters of
-the rule specify which metrics should be checked, and a bound (upper or lower,
-depending on the metric) for each specified metric. A construct is
-flagged if a specified metric can be computed for it, and the resulting value
-is higher then the upper bound (or less than the lower bound) specified.
+There is a set of checks based on computing a metric value and comparing the
+result with the specified upper (or lower, depending on a specific metric)
+value specified for a given metric. A construct is flagged if a given metric
+is applicable (can be computed) for it and the computed value is greater
+then (lover then) the specified upper (lower) bound.
-This rule has the following parameters:
-
-@itemize @bullet
-@item
-For the @option{+R} option:
-@table @code
-@item @i{Metric_Check_Name} < @i{LowerBound}
-Turns the check for the specified metric ON and specifies the lower bound
-for a given metric check
+The name of any metric-based rule consists of the prefix @code{Metrics_}
+followed by the name of the corresponding metric (see the table below).
+For @option{+R} option, each metric-based rule has a numeric parameter
+specifying the bound (integer or real, depending on a metric), @option{-R}
+option for metric rules does not have a parameter.
-@item @i{Metric_Check_Name} > @i{UpperBound}
-
-Turns the check for the specified metric ON and specifies the upper bound
-for a given metric check
-@end table
-
-@item
-For the @option{-R} option:
-@table @code
-@item @i{Metric_Check_Name}
-Turns the check for the specified metric OFF
-@end table
-@end itemize
-
-@noindent
-Parameters are not case-sensitive. @i{Metric_Check_Name} must be
-the name of a metric supported by the @code{Metrics_Violation} rule
-(see the table below),
-otherwise the parameter is ignored. Whether the upper or lower bound
-is specified for a given check, depends on the metric. If a
-parameter for the @option{+R} option specifies an invalid limit, a
-warning is issued and the parameter is ignored.
-
-The @option{-R} option without parameters turns OFF all the previously enabled
-metric checks. the @option{+R} option without parameters turns ON all the
-metric checks that have been defined by previous @option{+R} options with
-valid parameters. @option{+R} option with a valid
-parameter also turns ON all the other metric checks that have been defined
-by previous @option{+R} options with valid parameters if they have been
-disabled by @option{-R} option without parameters.
-
-By default no metrics checks are ON, so the @option{+R} option without
-parameters actually does not specify any check.
-
-The following table shows the available metrics-based checks,
-including the constraint that must be satisfied by the bound that
-is specified for the check.
+The following table shows the metric names for that the corresponding
+metrics-based checks are supported by gnatcheck, including the
+constraint that must be satisfied by the bound that is specified for the check
+and what bound - upper (U) or lower (L) - should be specified.
@multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer}
@ifnothtml
@item @b{Check Name} @tab @b{Description} @tab @b{Bounds Value}
@end ifhtml
@c Above conditional code is workaround to bug in texi2html (Feb 2008)
-@item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer
-@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer
-@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer
+@item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer (U)
+@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer (U)
+@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer (U)
@end multitable
@noindent
@emph{Example:} the rule
@smallexample
-+RMetrics_Violation: Cyclomatic_Complexity > 7
++RMetrics_Cyclomatic_Complexity : 7
@end smallexample
@noindent
means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
+To turn OFF the check for cyclomatic complexity metric, use the following option:
+@smallexample
+-RMetrics_Cyclomatic_Complexity
+@end smallexample
+
+
+@node Misnamed_Controlling_Parameters
+@subsection @code{Misnamed_Controlling_Parameters}
+@cindex @code{Misnamed_Controlling_Parameters} rule (for @command{gnatcheck})
+
+@noindent
+Flags a declaration of a dispatching operation, if the first parameter is
+not a controlling one and its name is not @code{This} (the check for
+parameter name is not case-sensitive). Declarations of dispatching functions
+with controlling result and no controlling parameter are never flagged.
+
+A subprogram body declaration, subprogram renaming declaration or subprogram
+body stub is flagged only if it is not a completion of a prior subprogram
+declaration.
+
+This rule has no parameters.
+
+
+
@node Misnamed_Identifiers
@subsection @code{Misnamed_Identifiers}
@cindex @code{Misnamed_Identifiers} rule (for @command{gnatcheck})
type declarations
@item
+subtype declarations
+
+@item
constant declarations (but not number declarations)
@item
@end itemize
@noindent
-For a private or incomplete type declaration the following checks are
-made for the defining name suffix:
+Defining identifiers from incomplete type declarations are never flagged.
-@itemize @bullet
-@item
-For an incomplete type declaration: if the corresponding full type
-declaration is available, the defining identifier from the full type
-declaration is checked, but the defining identifier from the incomplete type
-declaration is not; otherwise the defining identifier from the incomplete
-type declaration is checked against the suffix specified for type
-declarations.
-
-@item
-For a private type declaration (including private extensions), the defining
+For a private type declaration (including private extensions), the defining
identifier from the private type declaration is checked against the type
suffix (even if the corresponding full declaration is an access type
declaration), and the defining identifier from the corresponding full type
declaration is not checked.
-@end itemize
@noindent
For a deferred constant, the defining name in the corresponding full constant
Specifies the suffix for an access type name. If
this parameter is set, it overrides for access
types the suffix set by the @code{Type_Suffix} parameter.
+For access types, @emph{string} may have the following format:
+@emph{suffix1(suffix2)}. That means that an access type name
+should have the @emph{suffix1} suffix except for the case when
+the designated type is also an access type, in this case the
+type name should have the @emph{suffix1 & suffix2} suffix.
+
+@item Class_Access_Suffix=@emph{string}
+Specifies the suffix for the name of an access type that points to some class-wide
+type. If this parameter is set, it overrides for such access
+types the suffix set by the @code{Type_Suffix} or @code{Access_Suffix}
+parameter.
+
+@item Class_Subtype_Suffix=@emph{string}
+Specifies the suffix for the name of a subtype that denotes a class-wide type.
@item Constant_Suffix=@emph{string}
Specifies the suffix for a constant name.
If @code{Type_Suffix} is set, access type names are
checked as ordinary type names.
+@item Class_Access_Suffix
+Removes the suffix specified for access types pointing to class-wide
+type. This disables specific checks for names of access types pointing to
+class-wide types but does not disable any other checks for this rule.
+If @code{Type_Suffix} is set, access type names are
+checked as ordinary type names. If @code{Access_Suffix} is set, these
+access types are checked as any other access type name.
+
+@item Class_Subtype_Suffix=@emph{string}
+Removes the suffix specified for subtype names.
+This disables checks for subtype names but
+does not disable any other checks for this rule.
+
@item Constant_Suffix
Removes the suffix specified for constants. This
disables checks for constant names but does not
@end itemize
@noindent
-The rule may have the following parameter for the @option{+R} option:
+The rule has the following parameter for the @option{+R} option:
@table @emph
@item N
@end table
@noindent
-If the parameter for the @option{+R} option is not a positive integer,
-the parameter is ignored and the rule is turned ON with the most recently
-specified maximal non-flagged nesting level.
+If the parameter for the @option{+R} option is not specified or
+if it is not a positive integer, @option{+R} option is ignored.
If more then one option is specified for the gnatcheck call, the later option and
new parameter override the previous one(s).
-A @option{+R} option with no parameter turns the rule ON using the maximal
-non-flagged nesting level specified by the most recent @option{+R} option with
-a parameter, or the value 4 if there is no such previous @option{+R} option.
-
-
@node Parameters_Out_Of_Order
@subsection @code{Parameters_Out_Of_Order}
@cindex @code{Positional_Generic_Parameters} rule (for @command{gnatcheck})
@noindent
-Flag each instantiation using positional parameter notation.
+Flag each positional actual generic parameter except for the case when
+the generic unit being iinstantiated has exactly one generic formal
+parameter.
This rule has no parameters.
@cindex @code{Positional_Parameters} rule (for @command{gnatcheck})
@noindent
-Flag each subprogram or entry call using positional parameter notation,
+Flag each positional parameter notation in a subprogram or entry call,
except for the following:
@itemize @bullet
@item
-Invocations of prefix or infix operators are not flagged
+Parameters of calls to of prefix or infix operators are not flagged
@item
If the called subprogram or entry has only one formal parameter,
-the call is not flagged;
+the parameter of the call is not flagged;
@item
If a subprogram call uses the @emph{Object.Operation} notation, then
@itemize @minus
This rule has no parameters.
+@node Too_Many_Parents
+@subsection @code{Too_Many_Parents}
+@cindex @code{Too_Many_Parents} rule (for @command{gnatcheck})
+
+@noindent
+Flags any type declaration, single task declaration or single protected
+declaration that has more then @option{N} parents, @option{N} is a parameter
+of the rule.
+A parent here is either a (sub)type denoted by the subtype mark from the
+parent_subtype_indication (in case of a derived type declaration), or
+any of the progenitors from the interface list, if any.
+
+This rule has the following (mandatory) parameters for the @option{+R} option:
+
+@table @emph
+@item N
+Positive integer specifying the maximal allowed number of parents.
+@end table
+
+
@node Unassigned_OUT_Parameters
@subsection @code{Unassigned_OUT_Parameters}
@cindex @code{Unassigned_OUT_Parameters} rule (for @command{gnatcheck})
This rule has no parameters.
+@node Unconditional_Exits
+@subsection @code{Unconditional_Exits}
+@cindex @code{Unconditional_Exits} rule (for @command{gnatcheck})
+
+@noindent
+Flag unconditional @code{exit} statements.
+
+This rule has no parameters.
@node Unconstrained_Array_Returns
@subsection @code{Unconstrained_Array_Returns}
Flag each function returning an unconstrained array. Function declarations,
function bodies (and body stubs) having no separate specifications,
and generic function instantiations are checked.
-Generic function declarations, function calls and function renamings are
+Function calls and function renamings are
not checked.
+Generic function declarations, and function declarations in generic
+packages are not checked, instead this rule checks the results of
+generic instantiations (that is, expanded specification and expanded
+body corresponding to an instantiation).
+
This rule has no parameters.
@node Universal_Ranges
This rule has no parameters.
+@node Visible_Components
+@subsection @code{Visible_Components}
+@cindex @code{Visible_Components} rule (for @command{gnatcheck})
+
+@noindent
+Flags all the type declarations located in the visible part of a library
+package or a library generic package that can declare a visible component. A
+type is considered as declaring a visible component if it contains a record
+definition by its own or as a part of a record extension. Type declaration is
+flagged even if it contains a record definition that defines no components.
+
+Declarations located in private parts of local (generic) packages are not
+flagged. Declarations in private packages are not flagged.
+
+This rule has no parameters.
+
@node Volatile_Objects_Without_Address_Clauses
@subsection @code{Volatile_Objects_Without_Address_Clauses}
This rule has no parameters.
+@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
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::
@cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub})
Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}}
-@item ^-o^/BODY=^@var{body-name}
+@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.
+This is not always possible for function stubs.
+
+@item ^--no-local-header^/NO_LOCAL_HEADER^
+@cindex @option{^--no-local-header^/NO_LOCAL_HEADER^} (@command{gnatstub})
+Do not place local comment header with unit name before body stub for a
+unit.
+
+@item ^-o ^/BODY=^@var{body-name}
@cindex @option{^-o^/BODY^} (@command{gnatstub})
Body file name. This should be set if the argument file name does not
follow
@end table
+@c *********************************
+@node Generating Ada Bindings for C and C++ headers
+@chapter Generating Ada Bindings for C and C++ headers
+@findex binding
+
+@noindent
+GNAT now comes with a new experimental binding generator for C and C++
+headers which is intended to do 95% of the tedious work of generating
+Ada specs from C or C++ header files. Note that this still is a work in
+progress, not designed to generate 100% correct Ada specs.
+
+The code generated is using the Ada 2005 syntax, which makes it
+easier to interface with other languages than previous versions of Ada.
+
+@menu
+* Running the binding generator::
+* Generating bindings for C++ headers::
+* Switches::
+@end menu
+
+@node Running the binding generator
+@section Running the binding generator
+
+@noindent
+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:
+
+@smallexample
+$ g++ -c -fdump-ada-spec -C /usr/include/time.h
+$ gcc -c -gnat05 *.ads
+@end smallexample
+
+will generate, under GNU/Linux, the following files: @file{time_h.ads},
+@file{bits_time_h.ads}, @file{stddef_h.ads}, @file{bits_types_h.ads} which
+correspond to the files @file{/usr/include/time.h},
+@file{/usr/include/bits/time.h}, etc@dots{}, and will then compile in Ada 2005
+mode these Ada specs.
+
+The @code{-C} switch tells @command{gcc} to extract comments from headers,
+and will attempt to generate corresponding Ada comments.
+
+If you want to generate a single Ada file and not the transitive closure, you
+can use instead the @option{-fdump-ada-spec-slim} switch.
+
+Note that we recommend when possible to use the @command{g++} driver to
+generate bindings, even for most C headers, since this will in general
+generate better Ada specs. For generating bindings for C++ headers, it is
+mandatory to use the @command{g++} command, or @command{gcc -x c++} which
+is equivalent in this case. If @command{g++} cannot work on your C headers
+because of incompatibilities between C and C++, then you can fallback to
+@command{gcc} instead.
+
+For an example of better bindings generated from the C++ front-end,
+the name of the parameters (when available) are actually ignored by the C
+front-end. Consider the following C header:
+
+@smallexample
+extern void foo (int variable);
+@end smallexample
+
+with the C front-end, @code{variable} is ignored, and the above is handled as:
+
+@smallexample
+extern void foo (int);
+@end smallexample
+
+generating a generic:
+
+@smallexample
+procedure foo (param1 : int);
+@end smallexample
+
+with the C++ front-end, the name is available, and we generate:
+
+@smallexample
+procedure foo (variable : int);
+@end smallexample
+
+In some cases, the generated bindings will be more complete or more meaningful
+when defining some macros, which you can do via the @option{-D} switch. This
+is for example the case with @file{Xlib.h} under GNU/Linux:
+
+@smallexample
+g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
+@end smallexample
+
+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
+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
+generate Ada bindings for @file{readline/readline.h}, you need to first
+include @file{stdio.h}, so you can create a file with the following two
+lines in e.g. @file{readline1.h}:
+
+@smallexample
+#include <stdio.h>
+#include <readline/readline.h>
+@end smallexample
+
+and then generate Ada bindings from this file:
+
+@smallexample
+$ g++ -c -fdump-ada-spec readline1.h
+@end smallexample
+
+@node Generating bindings for C++ headers
+@section Generating bindings for C++ headers
+
+@noindent
+Generating bindings for C++ headers is done using the same options, always
+with the @command{g++} compiler.
+
+In this mode, C++ classes will be mapped to Ada tagged types, constructors
+will be mapped using the @code{CPP_Constructor} pragma, and when possible,
+multiple inheritance of abstract classes will be mapped to Ada interfaces
+(@xref{Interfacing to C++,,,gnat_rm, GNAT Reference Manual}, for additional
+information on interfacing to C++).
+
+For example, given the following C++ header file:
+
+@smallexample
+@group
+@cartouche
+class Carnivore @{
+public:
+ virtual int Number_Of_Teeth () = 0;
+@};
+
+class Domestic @{
+public:
+ virtual void Set_Owner (char* Name) = 0;
+@};
+
+class Animal @{
+public:
+ int Age_Count;
+ virtual void Set_Age (int New_Age);
+@};
+
+class Dog : Animal, Carnivore, Domestic @{
+ public:
+ int Tooth_Count;
+ char *Owner;
+
+ virtual int Number_Of_Teeth ();
+ virtual void Set_Owner (char* Name);
+
+ Dog();
+@};
+@end cartouche
+@end group
+@end smallexample
+
+The corresponding Ada code is generated:
+
+@smallexample @c ada
+@group
+@cartouche
+ package Class_Carnivore is
+ type Carnivore is limited interface;
+ pragma Import (CPP, Carnivore);
+
+ function Number_Of_Teeth (this : access Carnivore) return int is abstract;
+ end;
+ use Class_Carnivore;
+
+ package Class_Domestic is
+ type Domestic is limited interface;
+ pragma Import (CPP, Domestic);
+
+ procedure Set_Owner
+ (this : access Domestic;
+ Name : Interfaces.C.Strings.chars_ptr) is abstract;
+ end;
+ use Class_Domestic;
+
+ package Class_Animal is
+ type Animal is tagged limited record
+ Age_Count : aliased int;
+ end record;
+ pragma Import (CPP, Animal);
+
+ procedure Set_Age (this : access Animal; New_Age : int);
+ pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
+ end;
+ use Class_Animal;
+
+ package Class_Dog is
+ type Dog is new Animal and Carnivore and Domestic with record
+ Tooth_Count : aliased int;
+ Owner : Interfaces.C.Strings.chars_ptr;
+ end record;
+ pragma Import (CPP, Dog);
+
+ function Number_Of_Teeth (this : access Dog) return int;
+ pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");
+
+ procedure Set_Owner
+ (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
+ pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
+
+ function New_Dog return Dog;
+ pragma CPP_Constructor (New_Dog);
+ pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
+ end;
+ use Class_Dog;
+@end cartouche
+@end group
+@end smallexample
+
+@node Switches
+@section Switches
+
+@table @option
+@item -fdump-ada-spec
+@cindex @option{-fdump-ada-spec} (@command{gcc})
+Generate Ada spec files for the given header files transitively (including
+all header files that these headers depend upon).
+
+@item -fdump-ada-spec-slim
+@cindex @option{-fdump-ada-spec-slim} (@command{gcc})
+Generate Ada spec files for the header files specified on the command line
+only.
+
+@item -C
+@cindex @option{-C} (@command{gcc})
+Extract comments from headers and generate Ada comments in the Ada spec files.
+@end table
+
@node Other Utility Programs
@chapter Other Utility Programs
text file, and provide this file to gcov as a parameter, preceded by a @@
(e.g. @samp{gcov @@mysrclist.txt}).
+Note that on AIX compiling a static library with @code{-fprofile-arcs} is
+not supported as there can be unresolved symbols during the final link.
+
@node Profiling an Ada Program using gprof
@section Profiling an Ada Program using gprof
@cindex gprof
For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
attributes are recognized, although only a subset of them can sensibly
be implemented. The description of pragmas in
-@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
indicates whether or not they are applicable to non-VMS systems.
@menu
@noindent
The pragma @code{Extend_System} is a configuration pragma that
is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
-Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
+Extend_System,,, gnat_rm, GNAT Reference Manual}, for further details.
HP Ada does not allow the recompilation of the package
@code{SYSTEM}. Instead HP Ada provides several pragmas
@code{TO_ADDRESS}
function for type @code{UNSIGNED_LONGWORD} is changed to
@code{TO_ADDRESS_LONG}.
-@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
+@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual}, for a
discussion of why this change was necessary.
@noindent
* Linux-Specific Considerations::
* AIX-Specific Considerations::
* Irix-Specific Considerations::
+* RTX-Specific Considerations::
@end menu
@node Summary of Run-Time Configurations
@item @code{@ @ @ @ }Tasking @tab native Win32 threads
@item @code{@ @ @ @ }Exceptions @tab SJLJ
@*
+@item @b{x86-windows-rtx}
+@item @code{@ @ }@i{rts-rtx-rtss (default)}
+@item @code{@ @ @ @ }Tasking @tab RTX real-time subsystem RTSS threads (kernel mode)
+@item @code{@ @ @ @ }Exceptions @tab SJLJ
+@*
+@item @code{@ @ }@i{rts-rtx-w32}
+@item @code{@ @ @ @ }Tasking @tab RTX Win32 threads (user mode)
+@item @code{@ @ @ @ }Exceptions @tab ZCX
+@*
@item @b{x86_64-linux}
@item @code{@ @ }@i{rts-native (default)}
@item @code{@ @ @ @ }Tasking @tab pthread library
@end group
@end smallexample
+@node RTX-Specific Considerations
+@section RTX-Specific Considerations
+@cindex RTX libraries
+
+@noindent
+The Real-time Extension (RTX) to Windows is based on the Windows Win32
+API. Applications can be built to work in two different modes:
+
+@itemize @bullet
+@item
+Windows executables that run in Ring 3 to utilize memory protection
+(@emph{rts-rtx-w32}).
+
+@item
+Real-time subsystem (RTSS) executables that run in Ring 0, where
+performance can be optimized with RTSS applications taking precedent
+over all Windows applications (@emph{rts-rtx-rtss}).
+
+@end itemize
+
@c *******************************
@node Example of Binder Output File
@appendix Example of Binder Output File
@command{gnatmake}) command, or by the use of the configuration pragma:
@smallexample @c ada
-pragma Elaboration_Checks (RM);
+pragma Elaboration_Checks (DYNAMIC);
@end smallexample
@noindent
OSDN Git Service
