OpenE2K
/
gcc
2
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

gnat_rm.texi, [...]: Add -gnatyl documentation Update 'Exception Handling Control' chapter which was... 

2007-04-06  Robert Dewar  <dewar@adacore.com>
	    Arnaud Charlet  <charlet@adacore.com>
	    Vincent Celier  <celier@adacore.com>

	* gnat_rm.texi, gnat_ugn.texi: Add -gnatyl documentation
	Update 'Exception Handling Control' chapter which was outdated.
	Minor fix to documentation of -gnatwq
	Remove section "Adapting the Run Time to a New C++ Compiler" because
	it is now obsolete.
	Add passage on need of -nostart-files in some non-ada-main cases.
	Document new switch -eS (/STANDARD_OUTPUT_FOR_COMMANDS) for gnatmake
	Update documentation about Interfacing with C++
	Add documentation for new gnatmake switch -p
	Add missing protocol part in URLs.
	Document -gnatyA
	Document pragma Compile_Time_Error
	Add documentation for Object_Size indicating that stand alone
	objects can have a larger size in some cases.
	Add node for GNAT.Byte_Swapping, GNAT.SHA1
	Update reference to the Ravenscar profile.
	Document pragma Unreferenced_Objects

	* gnat-style.texi: Fix typo

From-SVN: r123584
This commit is contained in:
Robert Dewar 2007-04-06 11:24:18 +02:00 committed by Arnaud Charlet
parent ecf8118f79
commit 0916df6a3e
3 changed files with 493 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
gcc/ada/gnat-style.texi
View File

@ -243,7 +243,7 @@ capitalized when used as @syntax{attribute_designator}.
@itemize @bullet
@item
A comment starts with @code{--} followed by two spaces).
A comment starts with @code{--} followed by two spaces.
The only exception to this rule (i.e.@: one space is tolerated) is when the
comment ends with a single space followed by @code{--}.
It is also acceptable to have only one space between @code{--} and the start

256
gcc/ada/gnat_rm.texi
View File

@ -107,6 +107,7 @@ Implementation Defined Pragmas
* Pragma C_Pass_By_Copy::
* Pragma Comment::
* Pragma Common_Object::
* Pragma Compile_Time_Error::
* Pragma Compile_Time_Warning::
* Pragma Complete_Representation::
* Pragma Complex_Representation::
@ -187,6 +188,7 @@ Implementation Defined Pragmas
* Pragma Unimplemented_Unit::
* Pragma Universal_Data::
* Pragma Unreferenced::
* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
* Pragma Unsuppress::
* Pragma Use_VADS_Size::
@ -258,6 +260,7 @@ The Implementation of Standard I/O
* Wide_Wide_Text_IO::
* Stream_IO::
* Shared Files::
* Filenames encoding::
* Open Modes::
* Operations on C Streams::
* Interfacing to C Streams::
@ -294,6 +297,7 @@ The GNAT Library
* GNAT.Bubble_Sort (g-bubsor.ads)::
* GNAT.Bubble_Sort_A (g-busora.ads)::
* GNAT.Bubble_Sort_G (g-busorg.ads)::
* GNAT.Byte_Swapping (g-bytswa.ads)::
* GNAT.Calendar (g-calend.ads)::
* GNAT.Calendar.Time_IO (g-catiio.ads)::
* GNAT.Case_Util (g-casuti.ads)::
@ -332,6 +336,7 @@ The GNAT Library
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
* GNAT.SHA1 (g-sha1.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* GNAT.Source_Info (g-souinf.ads)::
@ -650,6 +655,7 @@ consideration, the use of these pragmas should be minimized.
* Pragma C_Pass_By_Copy::
* Pragma Comment::
* Pragma Common_Object::
* Pragma Compile_Time_Error::
* Pragma Compile_Time_Warning::
* Pragma Complete_Representation::
* Pragma Complex_Representation::
@ -730,6 +736,7 @@ consideration, the use of these pragmas should be minimized.
* Pragma Unimplemented_Unit::
* Pragma Universal_Data::
* Pragma Unreferenced::
* Pragma Unreferenced_Objects::
* Pragma Unreserve_All_Interrupts::
* Pragma Unsuppress::
* Pragma Use_VADS_Size::
@ -1035,6 +1042,33 @@ support is available, then the code generator will issue a message
indicating that the necessary attribute for implementation of this
pragma is not available.
@node Pragma Compile_Time_Error
@unnumberedsec Pragma Compile_Time_Error
@findex Compile_Time_Error
@noindent
Syntax:
@smallexample @c ada
pragma Compile_Time_Error
(boolean_EXPRESSION, static_string_EXPRESSION);
@end smallexample
@noindent
This pragma can be used to generate additional compile time
error messages. It
is particularly useful in generics, where errrs can be issued for
specific problematic instantiations. The first parameter is a boolean
expression. The pragma is effective only if the value of this expression
is known at compile time, and has the value True. The set of expressions
whose values are known at compile time includes all static boolean
expressions, and also other values which the compiler can determine
at compile time (e.g. the size of a record type set by an explicit
size representation clause, or the value of a variable which was
initialized to a constant and is known not to have been modified).
If these conditions are met, an error message is generated using
the value given as the second argument. This string value may contain
embedded ASCII.LF characters to break the message into multiple lines.
@node Pragma Compile_Time_Warning
@unnumberedsec Pragma Compile_Time_Warning
@findex Compile_Time_Warning
@ -1227,25 +1261,24 @@ pragma CPP_Class ([Entity =>] local_NAME);
@end smallexample
@noindent
The argument denotes an entity in the current declarative region
that is declared as a tagged or untagged record type. It indicates that
the type corresponds to an externally declared C++ class type, and is to
be laid out the same way that C++ would lay out the type.
If (and only if) the type is tagged, at least one component in the
record must be of type @code{Interfaces.CPP.Vtable_Ptr}, corresponding
to the C++ Vtable (or Vtables in the case of multiple inheritance) used
for dispatching.
The argument denotes an entity in the current declarative region that is
declared as a tagged record type. It indicates that the type corresponds
to an externally declared C++ class type, and is to be laid out the same
way that C++ would lay out the type.
Types for which @code{CPP_Class} is specified do not have assignment or
equality operators defined (such operations can be imported or declared
as subprograms as required). Initialization is allowed only by
constructor functions (see pragma @code{CPP_Constructor}).
as subprograms as required). Initialization is allowed only by constructor
functions (see pragma @code{CPP_Constructor}).
Pragma @code{CPP_Class} is intended primarily for automatic generation
using an automatic binding generator tool.
See @ref{Interfacing to C++} for related information.
Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
for backward compatibility but its functionality is available
using pragma @code{Import} with @code{Convention} = @code{CPP}.
@node Pragma CPP_Constructor
@unnumberedsec Pragma CPP_Constructor
@cindex Interfacing with C++
@ -1254,16 +1287,18 @@ See @ref{Interfacing to C++} for related information.
Syntax:
@smallexample @c ada
pragma CPP_Constructor ([Entity =>] local_NAME);
pragma CPP_Constructor ([Entity =>] local_NAME
[, [External_Name =>] static_string_EXPRESSION ]
[, [Link_Name =>] static_string_EXPRESSION ]);
@end smallexample
@noindent
This pragma identifies an imported function (imported in the usual way
with pragma @code{Import}) as corresponding to a C++
constructor. The argument is a name that must have been
previously mentioned in a pragma @code{Import}
with @code{Convention} = @code{CPP}, and must be of one of the following
forms:
with pragma @code{Import}) as corresponding to a C++ constructor. If
@code{External_Name} and @code{Link_Name} are not specified then the
@code{Entity} argument is a name that must have been previously mentioned
in a pragma @code{Import} with @code{Convention} = @code{CPP}. Such name
must be of one of the following forms:
@itemize @bullet
@item
@ -1325,37 +1360,9 @@ See @ref{Interfacing to C++} for more related information.
@cindex Interfacing to C++
@findex CPP_Virtual
@noindent
Syntax:
This pragma is now obsolete has has no effect because GNAT generates
the same object layout than the G++ compiler.
@smallexample @c ada
pragma CPP_Virtual
[Entity =>] ENTITY,
[, [Vtable_Ptr =>] vtable_ENTITY,]
[, [Position =>] static_integer_EXPRESSION]);
@end smallexample
@noindent
This pragma serves the same function as pragma @code{Import} in that
case of a virtual function imported from C++. The @var{Entity} argument
must be a
primitive subprogram of a tagged type to which pragma @code{CPP_Class}
applies. The @var{Vtable_Ptr} argument specifies
the Vtable_Ptr component which contains the
entry for this virtual function. The @var{Position} argument
is the sequential number
counting virtual functions for this Vtable starting at 1.
The @code{Vtable_Ptr} and @code{Position} arguments may be omitted if
there is one Vtable_Ptr present (single inheritance case) and all
virtual functions are imported. In that case the compiler can deduce both
these values.
No @code{External_Name} or @code{Link_Name} arguments are required for a
virtual function, since it is always accessed indirectly via the
appropriate Vtable entry.
Pragma @code{CPP_Virtual} is intended primarily for automatic generation
using an automatic binding generator tool.
See @ref{Interfacing to C++} for related information.
@node Pragma CPP_Vtable
@ -1363,31 +1370,9 @@ See @ref{Interfacing to C++} for related information.
@cindex Interfacing with C++
@findex CPP_Vtable
@noindent
Syntax:
This pragma is now obsolete has has no effect because GNAT generates
the same object layout than the G++ compiler.
@smallexample @c ada
pragma CPP_Vtable (
[Entity =>] ENTITY,
[Vtable_Ptr =>] vtable_ENTITY,
[Entry_Count =>] static_integer_EXPRESSION);
@end smallexample
@noindent
Given a record to which the pragma @code{CPP_Class} applies,
this pragma can be specified for each component of type
@code{CPP.Interfaces.Vtable_Ptr}.
@var{Entity} is the tagged type, @var{Vtable_Ptr}
is the record field of type @code{Vtable_Ptr}, and @var{Entry_Count} is
the number of virtual functions on the C++ side. Not all of these
functions need to be imported on the Ada side.
You may omit the @code{CPP_Vtable} pragma if there is only one
@code{Vtable_Ptr} component in the record and all virtual functions are
imported on the Ada side (the default value for the entry count in this
case is simply the total number of virtual functions).
Pragma @code{CPP_Vtable} is intended primarily for automatic generation
using an automatic binding generator tool.
See @ref{Interfacing to C++} for related information.
@node Pragma Debug
@ -3350,7 +3335,7 @@ This set of configuration pragmas and restrictions correspond to the
definition of the ``Ravenscar Profile'' for limited tasking, devised and
published by the @cite{International Real-Time Ada Workshop}, 1997,
and whose most recent description is available at
@url{ftp://ftp.openravenscar.org/openravenscar/ravenscar00.pdf}.
@url{http://www-users.cs.york.ac.uk/~burns/ravenscar.ps}.
The original definition of the profile was revised at subsequent IRTAW
meetings. It has been included in the ISO
@ -4041,7 +4026,7 @@ equivalent to a C union. It was introduced as a GNAT implementation defined
pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this
pragma, making it language defined, and GNAT fully implements this extended
version in all language modes (Ada 83, Ada 95, and Ada 2005). For full
details, consult the Ada 2005 RM, section 8.3.3.
details, consult the Ada 2005 RM, section B.3.3.
@node Pragma Unimplemented_Unit
@unnumberedsec Pragma Unimplemented_Unit
@ -4137,6 +4122,29 @@ mentioned in @code{with} clauses (similar to the usage of pragma
@code{Elaborate_All}. The effect is to suppress warnings about unreferenced
units.
@node Pragma Unreferenced_Objects
@unnumberedsec Pragma Unreferenced_Objects
@findex Unreferenced_Objects
@cindex Warnings, unreferenced
@noindent
Syntax:
@smallexample @c ada
pragma Unreferenced_Objects (local_subtype_NAME @{, local_subtype_NAME@});
@end smallexample
@noindent
This pragma signals that for the types or subtypes whose names are
listed, objects which are declared with one of these types or subtypes may
not be referenced, and if no references appear, no warnings are given.
This is particularly useful for objects which are declared solely for their
initialization and finalization effect. Such variables are sometimes referred
to as RAII variables (Resource Acquisition Is Initialization). Using this
pragma on the relevant type (most typically a limited controlled type), the
compiler will automatically suppress unwanted warnings about these variables
not being referenced.
@node Pragma Unreserve_All_Interrupts
@unnumberedsec Pragma Unreserve_All_Interrupts
@findex Unreserve_All_Interrupts
@ -4358,9 +4366,13 @@ o turn on warnings for address clause overlay
O turn off warnings for address clause overlay
p turn on warnings for ineffective pragma Inline
P turn off warnings for ineffective pragma Inline
q turn on warnings for questionable missing parentheses
Q turn off warnings for questionable missing parentheses
r turn on warnings for redundant construct
R turn off warnings for redundant construct
s suppress all warnings
t turn on warnings for tracking deleted code
T turn off warnings for tracking deleted code
u turn on warnings for unused entity
U turn off warnings for unused entity
v turn on warnings for unassigned variable
@ -5072,6 +5084,14 @@ by default be 32 bits (four bytes). But objects of type
@code{R2} will be only
8 bits (one byte), since @code{R2'Object_Size} has been set to 8.
Although @code{Object_Size} does properly reflect the default object size
value, it is not necessarily the case that all objects will be of this size
in a case where it is not specified explicitly. The compiler is free to
increase the size and alignment of stand alone objects to improve efficiency
of the generated code and sometimes does so in the case of large composite
objects. If the size of a stand alone object is critical to the
application, it should be specified explicitly.
@node Passed_By_Reference
@unnumberedsec Passed_By_Reference
@cindex Parameters, when passed by reference
@ -5401,10 +5421,6 @@ Affects semantics
Affects semantics
@item CPP_Constructor
Affects semantics
@item CPP_Virtual
Affects semantics
@item CPP_Vtable
Affects semantics
@item Debug
Affects semantics
@item Interface_Name
@ -6216,7 +6232,7 @@ convention. Any declarations useful for interfacing to any language on
the given hardware architecture should be provided directly in
@code{Interfaces}.
@end cartouche
Followed. An additional package not defined
Followed. An additional package not defined
in the Ada 95 Reference Manual is @code{Interfaces.CPP}, used
for interfacing to C++.
@ -7970,7 +7986,7 @@ Allowed only for record types, like C, but also notes that record
is to be passed by copy rather than reference.
@item COBOL
COBOL
@item CPP
@item C_Plus_Plus (or CPP)
C++
@item Default
Treated the same as C
@ -8148,9 +8164,27 @@ Pos values.
attribute. See C.7.1(7).
@end cartouche
@noindent
The result of this attribute is an 8-digit hexadecimal string
representing the virtual address of the task control block.
The result of this attribute is a string that identifies
the object or component that denotes a given task. If a variable Var has a task
type, the image for this task will have the form Var_XXXXXXXX, where the sufffix
is the hexadecimal representation of the virtual address of the corresponding
task control block. If the variable is an array of tasks, the image of each
task will have the form of an indexed component indicating the position of a
given task in the array, eg. Group(5)_XXXXXXX. If the task is a
component of a record, the image of the task will have the form of a selected
component. These rules are fully recursive, so that the image of a task that
is a subcomponent of a composite object corresponds to the expression that
designates this task.
@noindent
If a task is created by an allocator, its image depends on the context. If the
allocator is part of an object declaration, the rules described above are used
to construct its image, and this image is not affected by subsequent assignments. If the allocator appears within an expression, the image
includes only the name of the task type.
@noindent
If the configuration pragma Discard_Names is present, or if the restriction
No_Implicit_Heap_Allocation is in effect, the image reduces to
the numeric suffix, that is to say the hexadecimal representation of the
virtual address of the control block of the task.
@sp 1
@cartouche
@noindent
@ -11221,6 +11255,7 @@ these additional facilities are also described in this chapter.
* Wide_Wide_Text_IO::
* Stream_IO::
* Shared Files::
* Filenames encoding::
* Open Modes::
* Operations on C Streams::
* Interfacing to C Streams::
@ -11299,7 +11334,7 @@ there are two keywords defined.
@smallexample
SHARED=[YES|NO]
WCEM=[n|h|u|s\e]
WCEM=[n|h|u|s|e|8|b]
@end smallexample
@noindent
@ -12060,6 +12095,28 @@ heterogeneous input-output. Although this approach will work in GNAT if
@samp{shared=yes} is specified, it is preferable in Ada 95 to use Stream_IO
for this purpose (using the stream attributes)
@node Filenames encoding
@section Filenames encoding
@noindent
An encoding form parameter can be used to specify the filename
encoding @samp{encoding=@var{xxx}}.
@itemize @bullet
@item
If the form parameter @samp{encoding=utf8} appears in the form string, the
filename must be encoded in UTF-8.
@item
If the form parameter @samp{encoding=8bits} appears in the form
string, the filename must be a standard 8bits string.
@end itemize
In the absence of a @samp{encoding=@var{xxx}} form parameter, the
value UTF-8 is used. This encoding form parameter is only supported on
the Windows platform. On the other Operating Systems the runtime is
supporting UTF-8 natively.
@node Open Modes
@section Open Modes
@ -12405,6 +12462,7 @@ of GNAT, and will generate a warning message.
* GNAT.Bubble_Sort (g-bubsor.ads)::
* GNAT.Bubble_Sort_A (g-busora.ads)::
* GNAT.Bubble_Sort_G (g-busorg.ads)::
* GNAT.Byte_Swapping (g-bytswa.ads)::
* GNAT.Calendar (g-calend.ads)::
* GNAT.Calendar.Time_IO (g-catiio.ads)::
* GNAT.CRC32 (g-crc32.ads)::
@ -12443,6 +12501,7 @@ of GNAT, and will generate a warning message.
* GNAT.Regpat (g-regpat.ads)::
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
* GNAT.Semaphores (g-semaph.ads)::
* GNAT.SHA1 (g-sha1.ads)::
* GNAT.Signals (g-signal.ads)::
* GNAT.Sockets (g-socket.ads)::
* GNAT.Source_Info (g-souinf.ads)::
@ -12821,6 +12880,16 @@ are provided as generic parameters, this improves efficiency, especially
if the procedures can be inlined, at the expense of duplicating code for
multiple instantiations.
@node GNAT.Byte_Swapping (g-bytswa.ads)
@section @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
@cindex @code{GNAT.Byte_Swapping} (@file{g-bytswa.ads})
@cindex Byte swapping
@cindex Endian
@noindent
General routines for swapping the bytes in 2-, 4-, and 8-byte quantities.
Machine-specific implementations are available in some cases.
@node GNAT.Calendar (g-calend.ads)
@section @code{GNAT.Calendar} (@file{g-calend.ads})
@cindex @code{GNAT.Calendar} (@file{g-calend.ads})
@ -13247,6 +13316,14 @@ secondary stack.
@noindent
Provides classic counting and binary semaphores using protected types.
@node GNAT.SHA1 (g-sha1.ads)
@section @code{GNAT.SHA1} (@file{g-sha1.ads})
@cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
@cindex Secure Hash Algorithm SHA-1
@noindent
Implements the SHA-1 Secure Hash Algorithm as described in RFC 3174.
@node GNAT.Signals (g-signal.ads)
@section @code{GNAT.Signals} (@file{g-signal.ads})
@cindex @code{GNAT.Signals} (@file{g-signal.ads})
@ -13769,24 +13846,23 @@ tool, although it is possible to construct them by hand. No suitable binding
generator tool is supplied with GNAT though.
Using these pragmas it is possible to achieve complete
inter-operability between Ada tagged types and C class definitions.
inter-operability between Ada tagged types and C++ class definitions.
See @ref{Implementation Defined Pragmas}, for more details.
@table @code
@item pragma CPP_Class ([Entity =>] @var{local_NAME})
The argument denotes an entity in the current declarative region that is
declared as a tagged or untagged record type. It indicates that the type
declared as a tagged or untagged record type. It indicates that the type
corresponds to an externally declared C++ class type, and is to be laid
out the same way that C++ would lay out the type.
Note: Pragma @code{CPP_Class} is currently obsolete. It is supported
for backward compatibility but its functionality is available
using pragma @code{Import} with @code{Convention} = @code{CPP}.
@item pragma CPP_Constructor ([Entity =>] @var{local_NAME})
This pragma identifies an imported function (imported in the usual way
with pragma @code{Import}) as corresponding to a C++ constructor.
@item pragma CPP_Vtable @dots{}
One @code{CPP_Vtable} pragma can be present for each component of type
@code{CPP.Interfaces.Vtable_Ptr} in a record to which pragma @code{CPP_Class}
applies.
@end table
@node Interfacing to COBOL

392
gcc/ada/gnat_ugn.texi
View File

@ -2920,6 +2920,12 @@ gnatlink unit2.ali main.o -o exec_file
This procedure yields a binary executable called @file{exec_file}.
@end enumerate
@noindent
Depending on the circumstances (for example when your non-Ada main object
does not provide symbol @code{main}), you may also need to instruct the
GNAT linker not to include the standard startup objects by passing the
@option{^-nostartfiles^/NOSTART_FILES^} switch to @command{gnatlink}.
@node Calling Conventions
@subsection Calling Conventions
@cindex Foreign Languages
@ -3028,7 +3034,7 @@ Equivalent to C.
@findex C++
@cindex Interfacing to C++
@cindex Convention C++
@item CPP
@item C_Plus_Plus (or CPP)
This stands for C++. For most purposes this is identical to C.
See the separate description of the specialized GNAT pragmas relating to
C++ interfacing for further details.
@ -3147,24 +3153,24 @@ with a new C++ compiler.
* Interfacing to C++::
* Linking a Mixed C++ & Ada Program::
* A Simple Example::
* Adapting the Run Time to a New C++ Compiler::
* Interfacing with C++ at the Class Level::
@end menu
@node Interfacing to C++
@subsection Interfacing to C++
@noindent
GNAT supports interfacing with C++ compilers generating code that is
compatible with the standard Application Binary Interface of the given
platform.
GNAT supports interfacing with the G++ compiler (or any C++ compiler
generating code that is compatible with the G++ Application Binary
Interface ---see http://www.codesourcery.com/archives/cxx-abi).
@noindent
Interfacing can be done at 3 levels: simple data, subprograms, and
classes. In the first two cases, GNAT offers a specific @var{Convention
CPP} that behaves exactly like @var{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:
C_Plus_Plus} (or @var{CPP}) that behaves exactly like @var{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:
@itemize @bullet
@item
by modifying the C++ code in order to force a C convention using
@ -3177,8 +3183,8 @@ the pragma import.
@noindent
Interfacing at the class level can be achieved by using the GNAT specific
pragmas such as @code{CPP_Class} and @code{CPP_Virtual}. See the GNAT
Reference Manual for additional information.
pragmas such as @code{CPP_Constructor}. See the GNAT Reference Manual for
additional information.
@node Linking a Mixed C++ & Ada Program
@subsection Linking a Mixed C++ & Ada Program
@ -3377,9 +3383,11 @@ A::A(void)
@b{end} Simple_Cpp_Interface;
@b{with} System;
@b{package} Simple_Cpp_Interface @b{is}
@b{type} A @b{is} @b{limited}
@b{record}
Vptr : System.Address;
O_Value : Integer;
A_Value : Integer;
@b{end} @b{record};
@ -3394,22 +3402,240 @@ A::A(void)
@b{end} Simple_Cpp_Interface;
@end smallexample
@node Adapting the Run Time to a New C++ Compiler
@subsection Adapting the Run Time to a New C++ Compiler
@node Interfacing with C++ at the Class Level
@subsection Interfacing with C++ at the Class Level
@noindent
GNAT offers the capability to derive Ada 95 tagged types directly from
preexisting C++ classes and . See ``Interfacing with C++'' in the
@cite{GNAT Reference Manual}. The mechanism used by GNAT for achieving
such a goal
has been made user configurable through a GNAT library unit
@code{Interfaces.CPP}. The default version of this file is adapted to
the GNU C++ compiler. Internal knowledge of the virtual
table layout used by the new C++ compiler is needed to configure
properly this unit. The Interface of this unit is known by the compiler
and cannot be changed except for the value of the constants defining the
characteristics of the virtual table: CPP_DT_Prologue_Size, CPP_DT_Entry_Size,
CPP_TSD_Prologue_Size, CPP_TSD_Entry_Size. Read comments in the source
of this unit for more details.
In this section we demonstrate the GNAT features for interfacing with
C++ by means of an example making use of Ada 2005 abstract interface
types. This example consists of a classification of animals; classes
have been used to model our main classification of animals, and
interfaces provide support for the management of secondary
classifications. We first demonstrate a case in which the types and
constructors are defined on the C++ side and imported from the Ada
side, and latter the reverse case.
The root of our derivation will be the @code{Animal} class, with a
single private attribute (the @code{Age} of the animal) and two public
primitives to set and get the value of this attribute.
@smallexample
@b{class} Animal @{
@b{public}:
@b{virtual} void Set_Age (int New_Age);
@b{virtual} int Age ();
@b{private}:
int Age_Count;
@};
@end smallexample
Abstract interface types are defined in C++ by means of classes with pure
virtual functions and no data members. In our example we will use two
interfaces that provide support for the common management of @code{Carnivore}
and @code{Domestic} animals:
@smallexample
@b{class} Carnivore @{
@b{public}:
@b{virtual} int Number_Of_Teeth () = 0;
@};
@b{class} Domestic @{
@b{public}:
@b{virtual void} Set_Owner (char* Name) = 0;
@};
@end smallexample
Using these declarations, we can now say that a @code{Dog} is an animal that is
both Carnivore and Domestic, that is:
@smallexample
@b{class} Dog : Animal, Carnivore, Domestic @{
@b{public}:
@b{virtual} int Number_Of_Teeth ();
@b{virtual} void Set_Owner (char* Name);
Dog(); // Constructor
@b{private}:
int Tooth_Count;
char *Owner;
@};
@end smallexample
In the following examples we will assume that the previous declarations are
located in a file named @code{animals.h}. The following package demonstrates
how to import these C++ declarations from the Ada side:
@smallexample
@b{with} Interfaces.C.Strings; @b{use} Interfaces.C.Strings;
@b{package} Animals @b{is}
@b{type} Carnivore @b{is interface};
@b{pragma} Convention (C_Plus_Plus, Carnivore);
@b{function} Number_Of_Teeth (X : Carnivore)
@b{return} Natural @b{is abstract};
@b{type} Domestic @b{is interface};
@b{pragma} Convention (C_Plus_Plus, Set_Owner);
@b{procedure} Set_Owner
(X : @b{in out} Domestic;
Name : Chars_Ptr) @b{is abstract};
@b{type} Animal @b{is tagged record}
Age : Natural := 0;
@b{end record};
@b{pragma} Import (C_Plus_Plus, Animal);
@b{procedure} Set_Age (X : @b{in out} Animal; Age : Integer);
@b{pragma} Import (C_Plus_Plus, Set_Age);
@b{function} Age (X : Animal) @b{return} Integer;
@b{pragma} Import (C_Plus_Plus, Age);
@b{type} Dog @b{is new} Animal @b{and} Carnivore @b{and} Domestic @b{with record}
Tooth_Count : Natural;
Owner : String (1 .. 30);
@b{end record};
@b{pragma} Import (C_Plus_Plus, Dog);
@b{function} Number_Of_Teeth (A : Dog) @b{return} Integer;
@b{pragma} Import (C_Plus_Plus, Number_Of_Teeth);
@b{procedure} Set_Owner (A : @b{in out} Dog; Name : Chars_Ptr);
@b{pragma} Import (C_Plus_Plus, Set_Owner);
@b{function} New_Dog @b{return} Dog'Class;
@b{pragma} CPP_Constructor (New_Dog);
@b{pragma} Import (CPP, New_Dog, "_ZN3DogC2Ev");
@b{end} Animals;
@end smallexample
Thanks to the compatibility between GNAT run-time structures and the C++ ABI,
interfacing with these C++ classes is easy. The only requirement is that all
the primitives and components must be declared exactly in the same order in
the two languages.
Regarding the abstract interfaces, we must indicate to the GNAT compiler by
means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass
the arguments to the called primitives will be the same as for C++. For the
imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus}
to indicate that they have been defined on the C++ side; this is required
because the dispatch table associated with these tagged types will be built
in the C++ side and therefore will not contain the predefined Ada primitives
which Ada would otherwise expect.
As the reader can see there is no need to indicate the C++ mangled names
associated with each subprogram because it is assumed that all the calls to
these primitives will be dispatching calls. The only exception is the
constructor, which must be registered with the compiler by means of
@code{pragma CPP_Constructor} and needs to provide its associated C++
mangled name because the Ada compiler generates direct calls to it.
With the above packages we can now declare objects of type Dog on the Ada side
and dispatch calls to the corresponding subprograms on the C++ side. We can
also extend the tagged type Dog with further fields and primitives, and
override some of its C++ primitives on the Ada side. For example, here we have
a type derivation defined on the Ada side that inherits all the dispatching
primitives of the ancestor from the C++ side.
@smallexample
@b{with} Animals; @b{use} Animals;
@b{package} Vaccinated_Animals @b{is}
@b{type} Vaccinated_Dog @b{is new} Dog @b{with null record};
@b{function} Vaccination_Expired (A : Vaccinated_Dog) @b{return} Boolean;
@b{end} Vaccinated_Animals;
@end smallexample
It is important to note that, because of the ABI compatibility, the programmer
does not need to add any further information to indicate either the object
layout or the dispatch table entry associated with each dispatching operation.
Now let us define all the types and constructors on the Ada side and export
them to C++, using the same hierarchy of our previous example:
@smallexample
@b{with} Interfaces.C.Strings;
@b{use} Interfaces.C.Strings;
@b{package} Animals @b{is}
@b{type} Carnivore @b{is interface};
@b{pragma} Convention (C_Plus_Plus, Carnivore);
@b{function} Number_Of_Teeth (X : Carnivore)
@b{return} Natural @b{is abstract};
@b{type} Domestic @b{is interface};
@b{pragma} Convention (C_Plus_Plus, Set_Owner);
@b{procedure} Set_Owner
(X : @b{in out} Domestic;
Name : Chars_Ptr) @b{is abstract};
@b{type} Animal @b{is tagged record}
Age : Natural := 0;
@b{end record};
@b{pragma} Convention (C_Plus_Plus, Animal);
@b{procedure} Set_Age (X : @b{in out} Animal; Age : Integer);
@b{pragma} Export (C_Plus_Plus, Set_Age);
@b{function} Age (X : Animal) @b{return} Integer;
@b{pragma} Export (C_Plus_Plus, Age);
@b{type} Dog @b{is new} Animal @b{and} Carnivore @b{and} Domestic @b{with record}
Tooth_Count : Natural;
Owner : String (1 .. 30);
@b{end record};
@b{pragma} Convention (C_Plus_Plus, Dog);
@b{function} Number_Of_Teeth (A : Dog) @b{return} Integer;
@b{pragma} Export (C_Plus_Plus, Number_Of_Teeth);
@b{procedure} Set_Owner (A : @b{in out} Dog; Name : Chars_Ptr);
@b{pragma} Export (C_Plus_Plus, Set_Owner);
@b{function} New_Dog @b{return} Dog'Class;
@b{pragma} Export (C_Plus_Plus, New_Dog);
@b{end} Animals;
@end smallexample
Compared with our previous example the only difference is the use of
@code{pragma Export} to indicate to the GNAT compiler that the primitives will
be available to C++. Thanks to the ABI compatibility, on the C++ side there is
nothing else to be done; as explained above, the only requirement is that all
the primitives and components are declared in exactly the same order.
For completeness, let us see a brief C++ main program that uses the
declarations available in @code{animals.h} (presented in our first example) to
import and use the declarations from the Ada side, properly initializing and
finalizing the Ada run-time system along the way:
@smallexample
@b{#include} "animals.h"
@b{#include} <iostream>
@b{using namespace} std;
void Check_Carnivore (Carnivore *obj) @{ ... @}
void Check_Domestic (Domestic *obj) @{ ... @}
void Check_Animal (Animal *obj) @{ ... @}
void Check_Dog (Dog *obj) @{ ... @}
@b{extern} "C" @{
void adainit (void);
void adafinal (void);
Dog* new_dog ();
@}
void test ()
@{
Dog *obj = new_dog(); // Ada constructor
Check_Carnivore (obj); // Check secondary DT
Check_Domestic (obj); // Check secondary DT
Check_Animal (obj); // Check primary DT
Check_Dog (obj); // Check primary DT
@}
int main ()
@{
adainit (); test(); adafinal ();
return 0;
@}
@end smallexample
@node Comparison between GNAT and C/C++ Compilation Models
@section Comparison between GNAT and C/C++ Compilation Models
@ -3872,9 +4098,10 @@ Externals names are folded to all uppercase.
Internal GNAT implementation mode. This should not be used for
applications programs, it is intended only for use by the compiler
and its run-time library. For documentation, see the GNAT sources.
Note that @option{-gnatg} implies @option{-gnatwu} so that warnings
are generated on unreferenced entities, and all warnings are treated
as errors.
Note that @option{-gnatg} implies @option{-gnatwae} so that all
standard warnings are turned on, and @option{-gnaty} so that all
standard style options are turned on. All warnings and style error
messages are treated as errors.
@item -gnatG
@cindex @option{-gnatG} (@command{gcc})
@ -4972,12 +5199,12 @@ request silently.
@cindex Parentheses, warnings
This switch activates warnings for cases where parentheses are not used and
the result is potential ambiguity from a readers point of view. For example
(not a > b) when a and b are modular means (not (a) > b) and very likely the
(not a > b) when a and b are modular means ((not a) > b) and very likely the
programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and
quite likely ((-x) mod 5) was intended. In such situations it seems best to
follow the rule of always parenthesizing to make the association clear, and
this warning switch warns if such parentheses are not present. The default
is that these warnings are not given.
is that these warnings are given.
This warning can also be turned on using @option{-gnatwa}.
@item -gnatwQ
@ -5099,7 +5326,6 @@ with a literal or S'Length. This is a case where the code is assuming that the
low bound is one, which is in general not true (for example when a slice is
passed). The default is that such warnings are generated.
This warning can also be turned on using @option{-gnatwa}.
F
@item -gnatwW
@emph{Suppress warnings on wrong low bound assumption.}
@ -5542,6 +5768,13 @@ used as attributes names, must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
@item ^A^ARRAY_INDEXES^
@emph{Use of array index numbers in array attributes.}
If the ^letter A^word ARRAY_INDEXES^ appears in the string after
@option{-gnaty} then when using the array attributes First, Last, Range,
or Length, the index number must be omitted for one-dimensional arrays
and is required for multi-dimensional arrays.
@item ^b^BLANKS^
@emph{Blanks not allowed at statement end.}
If the ^letter b^word BLANKS^ appears in the string after @option{-gnaty} then
@ -5664,7 +5897,8 @@ option are more liberal than those in the Ada Reference Manual. First
in the case of record declarations, it is permissible to put the
@code{record} keyword on the same line as the @code{type} keyword, and
then the @code{end} in @code{end record} must line up under @code{type}.
For example, either of the following two layouts is acceptable:
This is also permitted when the type declaration is split on two lines.
For example, any of the following three layouts is acceptable:
@smallexample @c ada
@cartouche
@ -5678,6 +5912,13 @@ type q is
a : integer;
b : integer;
end record;
type q is
record
a : integer;
b : integer;
end record;
@end cartouche
@end smallexample
@ -5872,7 +6113,7 @@ The switch
@ifclear vms
@option{-gnaty} on its own (that is not
followed by any letters or digits),
is equivalent to @code{gnaty3abcefhiklmnprst}, that is all checking
is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
options enabled with the exception of @option{-gnatyo},
@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
@end ifclear
@ -6197,7 +6438,7 @@ Although GNAT is primarily an Ada 95 compiler, it can be set to operate
in Ada 2005 mode using this option. Although the new standard has not
yet been issued (as of early 2005), many features have been discussed and
approved in ``Ada Issues'' (AI's). For the text of these AI's, see
@url{www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}. Included with GNAT
@url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}. Included with GNAT
releases is a file @file{features-ada0y} that describes the current set
of implemented Ada 2005 features.
@ -6642,7 +6883,7 @@ to propagate an exception through a C/C++ code, the C/C++ code
must be compiled with the @option{-funwind-tables} GCC's
option.
The following switches can be used to control which of the
The following switches may be used to control which of the
two exception handling methods is used.
@table @option
@ -6650,9 +6891,8 @@ two exception handling methods is used.
@item --RTS=sjlj
@cindex @option{--RTS=sjlj} (@command{gnatmake})
This switch causes the setjmp/longjmp run-time to be used
for exception handling. If this is the default mechanism for the
target (see below), then this has no effect. If the default
This switch causes the setjmp/longjmp run-time (when available) to be used
for exception handling. If the default
mechanism for the target is zero cost exceptions, then
this switch can be used to modify this default, and must be
used for all units in the partition.
@ -6666,12 +6906,12 @@ application is improved by favoring exception propagation.
@cindex Zero Cost Exceptions
This switch causes the zero cost approach to be used
for exception handling. If this is the default mechanism for the
target (see below), then this has no effect. If the default
target (see below), then this switch is unneeded. If the default
mechanism for the target is setjmp/longjmp exceptions, then
this switch can be used to modify this default, and must be
used for all units in the partition.
This option can only be used if the zero cost approach
is available for the target in use (see below).
is available for the target in use, otherwise it will generate an error.
@end table
@noindent
@ -6680,18 +6920,6 @@ and @command{gnatbind}. Passing this option to @command{gnatmake}
(@pxref{Switches for gnatmake}) will ensure the required consistency
through the compilation and binding steps.
The @code{setjmp/longjmp} approach is available on all targets, while
the @code{zero cost} approach is available on selected targets.
To determine whether zero cost exceptions can be used for a
particular target, look at the private part of the file system.ads.
Either @code{GCC_ZCX_Support} or @code{Front_End_ZCX_Support} must
be True to use the zero cost approach. If both of these switches
are set to False, this means that zero cost exception handling
is not yet available for that target. The switch
@code{ZCX_By_Default} indicates the default approach. If this
switch is set to True, then the @code{zero cost} approach is
used by default.
@node Units to Sources Mapping Files
@subsection Units to Sources Mapping Files
@ -8514,6 +8742,12 @@ This switch cannot be used when using a project file.
Follow all symbolic links when processing project files.
@end ifclear
@item ^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^
@cindex @option{^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^} (@command{gnatmake})
Output the commands for the compiler, the binder and the linker
on ^standard output^SYS$OUTPUT^,
instead of ^standard error^SYS$ERROR^.
@item ^-f^/FORCE_COMPILE^
@cindex @option{^-f^/FORCE_COMPILE^} (@command{gnatmake})
Force recompilations. Recompile all sources, even though some object
@ -8634,6 +8868,12 @@ for an executable file on the host system.
This switch cannot be used when invoking @command{gnatmake} with several
@file{file_names}.
@item ^-p or --create-missing-dirs^/CREATE_MISSING_DIRS^
@cindex @option{^-p^/CREATE_MISSING_DIRS^} (@command{gnatmake})
When using project files (^-P^/PROJECT_FILE=^@var{project}), create
automatically missing object directories, library directories and exec
directories.
@item ^-P^/PROJECT_FILE=^@var{project}
@cindex @option{^-P^/PROJECT_FILE^} (@command{gnatmake})
Use project file @var{project}. Only one such switch can be used.
@ -14965,6 +15205,13 @@ semantically legal.
If this condition is not met, @command{gnatpp} will terminate with an
error message; no output file will be generated.
If the source files presented to @command{gnatpp} contain
preprocessing directives, then the output file will
correspond to the generated source after all
preprocessing is carried out. There is no way
using @command{gnatpp} to obtain pretty printed files that
include the preprocessing directives.
If the compilation unit
contained in the input source depends semantically upon units located
outside the current directory, you have to provide the source search path
@ -16379,7 +16626,7 @@ maximal loop nesting level
@noindent
The McCabe complexity metrics are defined
in @url{www.mccabe.com/pdf/nist235r.pdf}
in @url{http://www.mccabe.com/pdf/nist235r.pdf}
According to McCabe, both control statements and short-circuit control forms
should be taken into account when computing cyclomatic complexity. For each
@ -19286,8 +19533,27 @@ quotation marks.
@item -R@i{rule_id}
Turn off the check for a specified rule
@cindex @option{-from} (@command{gnatcheck})
@item -from=@i{rule_option_filename}
Read the rule options from the text file @i{rule_option_filename}, referred as
``rule file'' below.
@end table
@noindent
A rule file is supposed to be a text file containing an arbitrary set of
rule options. The file may contain empty lines and Ada-style comments (comment
lines and end-of-line comments). The rule file have free format, that is,
you do not have to start a new rule option from the new line.
A rule file may contain another @option{-from=@i{rule_option_filename}}
options, each of such options is replaced with the content of the
corresponding rule file during the rule files processing. In case if a
cycling is detected (that is, @i{rule_file_1} reads rule options from
@i{rule_file_2}, and @i{rule_file_2} reads (directly or indirectly)
rule options from @i{rule_file_1}), the process of macro-expansions
of rule files is interrupted and a part of their content is ignored.
@node Add the Results of Compiler Checks to gnatcheck Output
@section Add the Results of Compiler Checks to @command{gnatcheck} Output
@ -21717,10 +21983,6 @@ GNAT also supplies a number of implementation-defined pragmas as follows:
@item @code{CPP_DESTRUCTOR}
@item @code{CPP_VIRTUAL}
@item @code{CPP_VTABLE}
@item @code{DEBUG}
@item @code{EXTEND_SYSTEM}
@ -27615,16 +27877,14 @@ pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
@end smallexample
@noindent
then the imported routine is @code{retrieve_val@@4}, that is, there is no
trailing underscore but the appropriate @code{@@}@code{@i{nn}} is always
added at the end of the @code{Link_Name} by the compiler.
then the imported routine is @code{retrieve_val}, that is, there is no
decoration at all. No leading underscore and no Stdcall suffix
@code{@@}@code{@i{nn}}.
@noindent
Note, that in some special cases a DLL's entry point name lacks a trailing
@code{@@}@code{@i{nn}} while the exported name generated for a call has it.
The @code{gnatdll} tool, which creates the import library for the DLL, is able
to handle those cases (@pxref{Using gnatdll} for the description of
the switches).
This is especially important as in some special cases a DLL's entry
point name lacks a trailing @code{@@}@code{@i{nn}} while the exported
name generated for a call has it.
@noindent
It is also possible to import variables defined in a DLL by using an