-\input texinfo @c -*-texinfo-*-
+f\input texinfo @c -*-texinfo-*-
@c %**start of header
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@setfilename gnat_ugn.info
@copying
-Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
+Copyright @copyright{} 1995-2009 Free Software Foundation,
Inc.
Permission is granted to copy, distribute and/or modify this document
* 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
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
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}.
* 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
@item -gnatB
@cindex @option{-gnatB} (@command{gcc})
-Assume no invalid (bad) values except for 'Valid attribute use.
+Assume no invalid (bad) values except for 'Valid attribute use
+(@pxref{Validity Checking}).
@item -gnatc
@cindex @option{-gnatc} (@command{gcc})
Check syntax and semantics only (no code generation attempted).
+@item -gnatC
+@cindex @option{-gnatC} (@command{gcc})
+Generate CodePeer information (no code generation attempted).
+This switch will generate an intermediate representation suitable for
+use by CodePeer (@file{.scil} files). This switch is not compatible with
+code generation (it will, among other things, disable some switches such
+as -gnatn, and enable others such as -gnata).
+
@item -gnatd
@cindex @option{-gnatd} (@command{gcc})
Specify debug options for the compiler. The string of characters after
programmers, and these are documented at appropriate points in this
users guide.
+@ifclear vms
@item -gnatD
@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}).
@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 -gnatGnn
+@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})
@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
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}).
@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 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 Ada Reference Manual defines the concept of invalid values (see
+RM 13.9.1). The primary source of invalid values is uninitialized
+variables. A scalar variable that is left uninitialized may contain
+an invalid value; the concept of invalid does not apply to access or
+composite types.
+
+It is an error to read an invalid value, but the RM does not require
+run-time checks to detect such errors, except for some minimal
+checking to prevent erroneous execution (i.e. unpredictable
+behavior). This corresponds to the @option{-gnatVd} switch below,
+which is the default. For example, by default, if the expression of a
+case statement is invalid, it will raise Constraint_Error rather than
+causing a wild jump, and if an array index on the left-hand side of an
+assignment is invalid, it will raise Constraint_Error rather than
+overwriting an arbitrary memory location.
+
+The @option{-gnatVa} may be used to enable additional validity checks,
+which are not required by the RM. These checks are often very
+expensive (which is why the RM does not require them). These checks
+are useful in tracking down uninitialized variables, but they are
+not usually recommended for production builds.
+
+The other @option{-gnatV^@var{x}^^} switches below allow finer-grained
+control; you can enable whichever validity checks you desire. However,
+for most debugging purposes, @option{-gnatVa} is sufficient, and the
+default @option{-gnatVd} (i.e. standard Ada behavior) is usually
+sufficient for non-debugging use.
The @option{-gnatB} switch tells the compiler to assume that all
values are valid (that is, within their declared subtype range)
except in the context of a use of the Valid attribute. This means
the compiler can generate more efficient code, since the range
-of values is better known at compile time.
+of values is better known at compile time. However, an uninitialized
+variable can cause wild jumps and memory corruption in this mode.
-The @option{-gnatV^@var{x}^^} switch allows more control over the validity
-checking mode.
+The @option{-gnatV^@var{x}^^} switch allows control over the validity
+checking mode as described below.
@ifclear vms
The @code{x} argument is a string of letters that
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifclear
@ifset vms
The options allowed for this qualifier
indicate validity checks that are performed or not performed in addition
-to the default checks described above.
+to the default checks required by Ada as described above.
@end ifset
@table @option
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:
@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
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.
+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.
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[nn]
+@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
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.
+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
evaluation of the expression 1.0/27.0).
@end table
-@item -gnatD[nn]
+@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
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.
+reset to 40. The equal sign is optional.
@item -gnatr
@cindex @option{-gnatr} (@command{gcc})
@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.
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.
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}.
@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.
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
* gnatcheck Rule Options::
* Adding the Results of Compiler Checks to gnatcheck Output::
* Project-Wide Checks::
+* Rule exemption::
* Predefined Rules::
@end menu
@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, @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 paarmeters
+of the @command{gnatcheck} invocation;
+@item the list of enabled rules;
+@item the total number of detected violations;
+@item list of source files for that rule violations have been detected;
+@item list of source files with no violations detected;
@end itemize
@node General gnatcheck Switches
of this construct in the generic unit to the place where this unit is
instantiated.
-@cindex @option{^-m^/DIAGNOSIS_LIMIT^} (@command{gnatcheck})
-@item ^-m@i{nnn}^/DIAGNOSIS_LIMIT=@i{nnn}^
+@cindex @option{^-log^/LOG^} (@command{gnatcheck})
+@item ^-log^/LOG^
+Duplicate all the output sent to Stderr into a log file. The log file is
+named @var{gnatcheck.log} and is located in the current directory.
+
+@cindex @option{^-m^/DIAGNOSTIC_LIMIT^} (@command{gnatcheck})
+@item ^-m@i{nnn}^/DIAGNOSTIC_LIMIT=@i{nnn}^
Maximum number of diagnoses to be sent to Stdout, @i{nnn} from o@dots{}1000,
the default value is 500. Zero means that there is no limitation on
the number of diagnostic messages to be printed into Stdout.
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
GNAT style check option, or a string that has exactly the same
structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
@code{Style_Checks} (for further information about this pragma,
-@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
+@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}). For example,
+@code{+RStyle_Checks:O} rule option activates and adds to @command{gnatcheck}
+output the compiler style check that corresponds to
+@code{-gnatyO} style check option.
@item Warnings
To record compiler warnings (@pxref{Warning Message Control}), use the rule
@end smallexample
+@node Rule exemption
+@section Rule exemption
+@cindex Rule exemption (for @command{gnatcheck})
+
+@noindent
+@command{gnatcheck} can be used to inforce a coding standard. It may be
+appropriate, in some circumstances, to accept violations of the coding
+standard. In such a case, it is a good idea to justify the violation within
+the sources themselves. It makes it possible to maintain the justification
+for such violations along with the sources containing them.
+@command{gnatcheck} supports such justified violations with the notion of
+``exemption'' covering a specific source code section. Usually,
+@command{gnatcheck} issues rule violation messages both on @file{stderr}
+and in a report file. Exempted violations are not reported at all on
+@file{stderr} so that users using @command{gnatcheck} in interactive mode
+(e.g. in its GPS interface) do not need to pay attention to known and
+justified violations. The @command{gnatcheck} report includes exempted
+violations in a special section along with their justification.
+
+@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 parameter is
+``gnatcheck''. Here is the syntax of @command{gnatcheck} annotations:
+
+@smallexample @c ada
+pragma Annotate (gnatcheck, exemption_control, Rule_Name, [justification]);
+
+exemption_control ::= "Exempt_On" | "Exempt_Off"
+
+Rule_Name ::= string_literal
+
+justification ::= string_literal
+
+@end smallexample
+
+@noindent
+When a @command{gnatcheck} annotatation has more then four parameters,
+@command{gnatcheck} issues a warning and ignore additional parameters.
+If the additional parameters do not follow the syntax above,
+@command{gnatcheck} emits a warning and ignores the annotation.
+
+@code{Rule_Name} should be the name of some existing @command{gnatcheck} rule.
+If this is not the case, the 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 silently.
+
+A source code section where an exemption is active for a given rule starts with
+an extempt_on annotation and terminates with an exempt_off one:
+
+@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 in order to create a properly formed exempted source
+code section;
+
+@item
+exempted source code sections are only based on the source location of the
+annotations. Any source construct having a source location in 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. It is not allowed
+to create nested or intersecting source code sections for the same rule;
+
+@item
+malformed exempted source code sections are reported by a warning and
+the corresponding rule exemption is 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}. This allow proper
+maintenance of exempted source code sections;
+
+@item
+if an exempted source code section reaches the end of the compilation unit
+source and there is no @code{Annotate} pragma closing this section, then the
+exemption for the given rule is turned off 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::
* Improperly_Called_Protected_Entries::
@end ignore
* 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
@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 Deep_Inheritance_Hierarchies
+@subsection @code{Deep_Inheritance_Hierarchies}
+@cindex @code{Deep_Inheritance_Hierarchies} rule (for @command{gnatcheck})
+
+@noindent
+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.
+
+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 correspondong full
+declaration is checked.
+
+This rule has the following (mandatory) parameter for the @option{+R} option:
+
+@table @emph
+@item N
+Integer not less then -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
+
+
+@node Deeply_Nested_Generics
+@subsection @code{Deeply_Nested_Generics}
+@cindex @code{Deeply_Nested_Generics} rule (for @command{gnatcheck})
+
+@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})
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})
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})
-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:
-
-@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.
+Defining identifiers from incomplete type declarations are never flagged.
-@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
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}
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
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
@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
