gnat_ugn.texi: Add documentation for -gnatw.w/-gnatw.W Add description for the new gnatstub...
2008-03-26 Robert Dewar <dewar@adacore.com> * gnat_ugn.texi: Add documentation for -gnatw.w/-gnatw.W Add description for the new gnatstub option '--header-file' clarification of -gnatwz/-gnatwZ Add a "Irix-Specific Considerations" section to document the need to set LD_LIBRARY_PATH when using the default shared runtime library. Added documentation for both gcov and gprof. * gnat_rm.texi: Document that pragma Compile_Time_Warning generates messages that are not suppressed when clients are compiled. Add documentation of s-pooglo s-pooloc Document the new GNAT.Serial_Communications API. Add documentation for 'Old attribute Add description of pragma Optimize_Alignment * ug_words: Add entries for -gnatw.w -gnatw.W * usage.adb: Add line for -gnatw.w (warn on warnings off) From-SVN: r133588
This commit is contained in:
Robert Dewar
Arnaud Charlet
parent
7e5e5cc7c4
commit
da50876659
@ -170,6 +170,7 @@ Implementation Defined Pragmas
|
||||
* Pragma No_Strict_Aliasing ::
|
||||
* Pragma Normalize_Scalars::
|
||||
* Pragma Obsolescent::
|
||||
* Pragma Optimize_Alignment::
|
||||
* Pragma Passive::
|
||||
* Pragma Persistent_BSS::
|
||||
* Pragma Polling::
|
||||
@ -198,6 +199,7 @@ Implementation Defined Pragmas
|
||||
* Pragma Unimplemented_Unit::
|
||||
* Pragma Universal_Aliasing ::
|
||||
* Pragma Universal_Data::
|
||||
* Pragma Unmodified::
|
||||
* Pragma Unreferenced::
|
||||
* Pragma Unreferenced_Objects::
|
||||
* Pragma Unreserve_All_Interrupts::
|
||||
@ -241,6 +243,7 @@ Implementation Defined Attributes
|
||||
* Mechanism_Code::
|
||||
* Null_Parameter::
|
||||
* Object_Size::
|
||||
* Old::
|
||||
* Passed_By_Reference::
|
||||
* Pool_Address::
|
||||
* Range_Length::
|
||||
@ -283,12 +286,14 @@ The GNAT Library
|
||||
* Ada.Characters.Latin_9 (a-chlat9.ads)::
|
||||
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
|
||||
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
|
||||
* Ada.Command_Line.Remove (a-colire.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
|
||||
* Ada.Command_Line.Environment (a-colien.ads)::
|
||||
* Ada.Command_Line.Remove (a-colire.ads)::
|
||||
* Ada.Command_Line.Response_File (a-clrefi.ads)::
|
||||
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
|
||||
* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
|
||||
* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
|
||||
* Ada.Exceptions.Traceback (a-exctra.ads)::
|
||||
* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
|
||||
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
|
||||
@ -296,7 +301,9 @@ The GNAT Library
|
||||
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
|
||||
* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
|
||||
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
|
||||
* Ada.Wide_Characters.Unicode (a-wichun.ads)::
|
||||
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
|
||||
* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
|
||||
* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
|
||||
* GNAT.Altivec (g-altive.ads)::
|
||||
* GNAT.Altivec.Conversions (g-altcon.ads)::
|
||||
@ -350,12 +357,13 @@ The GNAT Library
|
||||
* GNAT.Most_Recent_Exception (g-moreex.ads)::
|
||||
* GNAT.OS_Lib (g-os_lib.ads)::
|
||||
* GNAT.Perfect_Hash_Generators (g-pehage.ads)::
|
||||
* GNAT.Random_Numbers (g-rannum.ads)
|
||||
* GNAT.Random_Numbers (g-rannum.ads)::
|
||||
* GNAT.Regexp (g-regexp.ads)::
|
||||
* GNAT.Registry (g-regist.ads)::
|
||||
* GNAT.Regpat (g-regpat.ads)::
|
||||
* GNAT.Secondary_Stack_Info (g-sestin.ads)::
|
||||
* GNAT.Semaphores (g-semaph.ads)::
|
||||
* GNAT.Serial_Communications (g-sercom.ads)::
|
||||
* GNAT.SHA1 (g-sha1.ads)::
|
||||
* GNAT.Signals (g-signal.ads)::
|
||||
* GNAT.Sockets (g-socket.ads)::
|
||||
@ -383,10 +391,6 @@ The GNAT Library
|
||||
* Interfaces.C.Extensions (i-cexten.ads)::
|
||||
* Interfaces.C.Streams (i-cstrea.ads)::
|
||||
* Interfaces.CPP (i-cpp.ads)::
|
||||
* Interfaces.Os2lib (i-os2lib.ads)::
|
||||
* Interfaces.Os2lib.Errors (i-os2err.ads)::
|
||||
* Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
|
||||
* Interfaces.Os2lib.Threads (i-os2thr.ads)::
|
||||
* Interfaces.Packed_Decimal (i-pacdec.ads)::
|
||||
* Interfaces.VxWorks (i-vxwork.ads)::
|
||||
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
|
||||
@ -394,6 +398,8 @@ The GNAT Library
|
||||
* System.Assertions (s-assert.ads)::
|
||||
* System.Memory (s-memory.ads)::
|
||||
* System.Partition_Interface (s-parint.ads)::
|
||||
* System.Pool_Global (s-pooglo.ads)::
|
||||
* System.Pool_Local (s-pooloc.ads)::
|
||||
* System.Restrictions (s-restri.ads)::
|
||||
* System.Rident (s-rident.ads)::
|
||||
* System.Task_Info (s-tasinf.ads)::
|
||||
@ -758,6 +764,7 @@ consideration, the use of these pragmas should be minimized.
|
||||
* Pragma No_Strict_Aliasing::
|
||||
* Pragma Normalize_Scalars::
|
||||
* Pragma Obsolescent::
|
||||
* Pragma Optimize_Alignment::
|
||||
* Pragma Passive::
|
||||
* Pragma Persistent_BSS::
|
||||
* Pragma Polling::
|
||||
@ -786,6 +793,7 @@ consideration, the use of these pragmas should be minimized.
|
||||
* Pragma Unimplemented_Unit::
|
||||
* Pragma Universal_Aliasing ::
|
||||
* Pragma Universal_Data::
|
||||
* Pragma Unmodified::
|
||||
* Pragma Unreferenced::
|
||||
* Pragma Unreferenced_Objects::
|
||||
* Pragma Unreserve_All_Interrupts::
|
||||
@ -1162,7 +1170,15 @@ pragma Compile_Time_Warning
|
||||
|
||||
@noindent
|
||||
Same as pragma Compile_Time_Error, except a warning is issued instead
|
||||
of an error message.
|
||||
of an error message. Note that if this pragma is used in a package that
|
||||
is with'ed by a client, the client will get the warning even though it
|
||||
is issued by a with'ed package (normally warnings in with'ed units are
|
||||
suppressed, but this is a special exception to that rule).
|
||||
|
||||
One typical use is within a generic where compile time known characteristics
|
||||
of formal parameters are tested, and warnings given appropriately. Another use
|
||||
with a first parameter of True is to warn a client about use of a package,
|
||||
for example that it is not fully implemented.
|
||||
|
||||
@node Pragma Complete_Representation
|
||||
@unnumberedsec Pragma Complete_Representation
|
||||
@ -3373,6 +3389,77 @@ Entity parameter is omitted, then the pragma applies to the declaration
|
||||
immediately preceding the pragma (this form cannot be used for the
|
||||
enumeration literal case).
|
||||
|
||||
@node Pragma Optimize_Alignment
|
||||
@unnumberedsec Pragma Optimize_Alignment
|
||||
@findex Optimize_Alignment
|
||||
@cindex Alignment, default settings
|
||||
@noindent
|
||||
Syntax:
|
||||
|
||||
@smallexample @c ada
|
||||
pragma Optimize_Alignment (TIME | SPACE | OFF);
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
This is a configuration pragma which affects the choice of default alignments
|
||||
for types where no alignment is explicitly specified. There is a time/space
|
||||
trade-off in the selection of these values. Large alignments result in more
|
||||
efficient code, at the expense of larger data space, since sizes have to be
|
||||
increased to match these alignments. Smaller alignments save space, but the
|
||||
access code is slower. The normal choice of default alignments (which is what
|
||||
you get if you do not use this pragma, or if you use an argument of OFF),
|
||||
tries to balance these two requirements.
|
||||
|
||||
Specifying SPACE causes smaller default alignments to be chosen in two cases.
|
||||
First any packed record is given an alignment of 1. Second, if a size is given
|
||||
for the type, then the alignment is chosen to avoid increasing this size. For
|
||||
example, consider:
|
||||
|
||||
@smallexample @c ada
|
||||
type R is record
|
||||
X : Integer;
|
||||
Y : Character;
|
||||
end record;
|
||||
|
||||
for R'Size use 5*8;
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
In the default mode, this type gets an alignment of 4, so that access to the
|
||||
Integer field X are efficient. But this means that objects of the type end up
|
||||
with a size of 8 bytes. This is a valid choice, since sizes of objects are
|
||||
allowed to be bigger than the size of the type, but it can waste space if for
|
||||
example fields of type R appear in an enclosing record. If the above type is
|
||||
compiled in @code{Optimize_Alignment (Space)} mode, the alignment is set to 1.
|
||||
|
||||
Specifying TIME causes larger default alignments to be chosen in the case of
|
||||
small types with sizes that are not a power of 2. For example, consider:
|
||||
|
||||
@smallexample @c ada
|
||||
type R is record
|
||||
A : Character;
|
||||
B : Character;
|
||||
C : Boolean;
|
||||
end record;
|
||||
|
||||
pragma Pack (R);
|
||||
for R'Size use 17;
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
The default alignment for this record is normally 1, but if this type is
|
||||
compiled in @code{Optimize_Alignment (Time)} mode, then the alignment is set
|
||||
to 4, which wastes space for objects of the type, since they are now 4 bytes
|
||||
long, but results in more efficient access when the whole record is referenced.
|
||||
|
||||
As noted above, this is a configuration pragma, and there is a requirement
|
||||
that all units in a partition be compiled with a consistent setting of the
|
||||
optimization setting. This would normally be achieved by use of a configuration
|
||||
pragma file containing the appropriate setting. The exception to this rule is
|
||||
that predefined units in the GNAT library (that is, members of the Ada, System,
|
||||
Interfaces, GNAT hierarchies) ignore the setting of this pragma, and thus the
|
||||
consistency requirement does not apply to them.
|
||||
|
||||
@node Pragma Passive
|
||||
@unnumberedsec Pragma Passive
|
||||
@findex Passive
|
||||
@ -4313,6 +4400,31 @@ a library unit pragma, but can also be used as a configuration pragma
|
||||
of this pragma is also available by applying the -univ switch on the
|
||||
compilations of units where universal addressing of the data is desired.
|
||||
|
||||
@node Pragma Unmodified
|
||||
@unnumberedsec Pragma Unmodified
|
||||
@findex Unmodified
|
||||
@cindex Warnings, unmodified
|
||||
@noindent
|
||||
Syntax:
|
||||
|
||||
@smallexample @c ada
|
||||
pragma Unmodified (LOCAL_NAME @{, LOCAL_NAME@});
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
This pragma signals that the assignable entities (variables,
|
||||
@code{out} parameters, @code{in out} parameters) whose names are listed are
|
||||
deliberately not assigned in the current source unit. This
|
||||
suppresses warnings about the
|
||||
entities being referenced but not assigned, and in addition a warning will be
|
||||
generated if one of these entities is in fact assigned in the
|
||||
same unit as the pragma (or in the corresponding body, or one
|
||||
of its subunits).
|
||||
|
||||
This is particularly useful for clearly signaling that a particular
|
||||
parameter is not modified, even though the spec suggests that it might
|
||||
be.
|
||||
|
||||
@node Pragma Unreferenced
|
||||
@unnumberedsec Pragma Unreferenced
|
||||
@findex Unreferenced
|
||||
@ -4578,55 +4690,66 @@ full details see @ref{Warning Message Control,,, gnat_ugn, @value{EDITION}
|
||||
User's Guide}.
|
||||
|
||||
@smallexample
|
||||
a turn on all optional warnings (except d,h,l)
|
||||
A turn off all optional warnings
|
||||
b turn on warnings for bad fixed value (not multiple of small)
|
||||
B turn off warnings for bad fixed value (not multiple of small)
|
||||
c turn on warnings for constant conditional
|
||||
C turn off warnings for constant conditional
|
||||
d turn on warnings for implicit dereference
|
||||
D turn off warnings for implicit dereference
|
||||
e treat all warnings as errors
|
||||
f turn on warnings for unreferenced formal
|
||||
F turn off warnings for unreferenced formal
|
||||
g turn on warnings for unrecognized pragma
|
||||
G turn off warnings for unrecognized pragma
|
||||
h turn on warnings for hiding variable
|
||||
H turn off warnings for hiding variable
|
||||
i turn on warnings for implementation unit
|
||||
I turn off warnings for implementation unit
|
||||
j turn on warnings for obsolescent (annex J) feature
|
||||
J turn off warnings for obsolescent (annex J) feature
|
||||
k turn on warnings on constant variable
|
||||
K turn off warnings on constant variable
|
||||
l turn on warnings for missing elaboration pragma
|
||||
L turn off warnings for missing elaboration pragma
|
||||
m turn on warnings for variable assigned but not read
|
||||
M turn off warnings for variable assigned but not read
|
||||
n normal warning mode (cancels -gnatws/-gnatwe)
|
||||
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
|
||||
V turn off warnings for unassigned variable
|
||||
w turn on warnings for wrong low bound assumption
|
||||
W turn off warnings for wrong low bound assumption
|
||||
x turn on warnings for export/import
|
||||
X turn off warnings for export/import
|
||||
y turn on warnings for Ada 2005 incompatibility
|
||||
Y turn off warnings for Ada 2005 incompatibility
|
||||
z turn on size/align warnings for unchecked conversion
|
||||
Z turn off size/align warnings for unchecked conversion
|
||||
a turn on all optional warnings (except d h l .o)
|
||||
A turn off all optional warnings
|
||||
.a* turn on warnings for failing assertions
|
||||
.A turn off warnings for failing assertions
|
||||
b turn on warnings for bad fixed value (not multiple of small)
|
||||
B* turn off warnings for bad fixed value (not multiple of small)
|
||||
c turn on warnings for constant conditional
|
||||
C* turn off warnings for constant conditional
|
||||
.c turn on warnings for unrepped components
|
||||
.C* turn off warnings for unrepped components
|
||||
d turn on warnings for implicit dereference
|
||||
D* turn off warnings for implicit dereference
|
||||
e treat all warnings as errors
|
||||
f turn on warnings for unreferenced formal
|
||||
F* turn off warnings for unreferenced formal
|
||||
g* turn on warnings for unrecognized pragma
|
||||
G turn off warnings for unrecognized pragma
|
||||
h turn on warnings for hiding variable
|
||||
H* turn off warnings for hiding variable
|
||||
i* turn on warnings for implementation unit
|
||||
I turn off warnings for implementation unit
|
||||
j turn on warnings for obsolescent (annex J) feature
|
||||
J* turn off warnings for obsolescent (annex J) feature
|
||||
k turn on warnings on constant variable
|
||||
K* turn off warnings on constant variable
|
||||
l turn on warnings for missing elaboration pragma
|
||||
L* turn off warnings for missing elaboration pragma
|
||||
m turn on warnings for variable assigned but not read
|
||||
M* turn off warnings for variable assigned but not read
|
||||
n* normal warning mode (cancels -gnatws/-gnatwe)
|
||||
o* turn on warnings for address clause overlay
|
||||
O turn off warnings for address clause overlay
|
||||
.o turn on warnings for out parameters assigned but not read
|
||||
.O* turn off warnings for out parameters assigned but not read
|
||||
p turn on warnings for ineffective pragma Inline in frontend
|
||||
P* turn off warnings for ineffective pragma Inline in frontend
|
||||
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
|
||||
.r turn on warnings for object renaming function
|
||||
.R* turn off warnings for object renaming function
|
||||
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
|
||||
V turn off warnings for unassigned variable
|
||||
w* turn on warnings for wrong low bound assumption
|
||||
W turn off warnings for wrong low bound assumption
|
||||
x* turn on warnings for export/import
|
||||
X turn off warnings for export/import
|
||||
.x turn on warnings for non-local exceptions
|
||||
.X* turn off warnings for non-local exceptions
|
||||
y* turn on warnings for Ada 2005 incompatibility
|
||||
Y turn off warnings for Ada 2005 incompatibility
|
||||
z* turn on convention/size/align warnings for unchecked conversion
|
||||
Z turn off convention/size/align warnings for unchecked conversion
|
||||
* indicates default in above list
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
@ -4796,6 +4919,7 @@ consideration, you should minimize the use of these attributes.
|
||||
* Mechanism_Code::
|
||||
* Null_Parameter::
|
||||
* Object_Size::
|
||||
* Old::
|
||||
* Passed_By_Reference::
|
||||
* Pool_Address::
|
||||
* Range_Length::
|
||||
@ -5324,40 +5448,46 @@ alignment will be 4, because of the
|
||||
integer field, and so the default size of record objects for this type
|
||||
will be 64 (8 bytes).
|
||||
|
||||
The @code{@var{type}'Object_Size} attribute
|
||||
has been added to GNAT to allow the
|
||||
default object size of a type to be easily determined. For example,
|
||||
@code{Natural'Object_Size} is 32, and
|
||||
@code{Rec'Object_Size} (for the record type in the above example) will be
|
||||
64. Note also that, unlike the situation with the
|
||||
@code{Size} attribute as defined in the Ada RM, the
|
||||
@code{Object_Size} attribute can be specified individually
|
||||
for different subtypes. For example:
|
||||
@node Old
|
||||
@unnumberedsec Old
|
||||
@cindex Capturing Old values
|
||||
@cindex Postconditions
|
||||
@noindent
|
||||
The attribute Prefix'Old can be used within a
|
||||
subprogram to refer to the value of the prefix on entry. So for
|
||||
example if you have an argument of a record type X called Arg1,
|
||||
you can refer to Arg1.Field'Old which yields the value of
|
||||
Arg1.Field on entry. The implementation simply involves generating
|
||||
an object declaration which captures the value on entry. Any
|
||||
prefix is allowed except one of a limited type (since limited
|
||||
types cannot be copied to capture their values).
|
||||
|
||||
The following example shows the use of 'Old to implement
|
||||
a test of a postcondition:
|
||||
|
||||
@smallexample @c ada
|
||||
type R is new Integer;
|
||||
subtype R1 is R range 1 .. 10;
|
||||
subtype R2 is R range 1 .. 10;
|
||||
for R2'Object_Size use 8;
|
||||
with Old_Pkg;
|
||||
procedure Old is
|
||||
begin
|
||||
Old_Pkg.Incr;
|
||||
end Old;
|
||||
|
||||
package Old_Pkg is
|
||||
procedure Incr;
|
||||
end Old_Pkg;
|
||||
|
||||
package body Old_Pkg is
|
||||
Count : Natural := 0;
|
||||
|
||||
procedure Incr is
|
||||
begin
|
||||
... code manipulating the value of Count
|
||||
|
||||
pragma Assert (Count = Count'Old + 1);
|
||||
end Incr;
|
||||
end Old_Pkg;
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
In this example, @code{R'Object_Size} and @code{R1'Object_Size} are both
|
||||
32 since the default object size for a subtype is the same as the object size
|
||||
for the parent subtype. This means that objects of type @code{R}
|
||||
or @code{R1} will
|
||||
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
|
||||
@ -12749,12 +12879,14 @@ of GNAT, and will generate a warning message.
|
||||
* Ada.Characters.Latin_9 (a-chlat9.ads)::
|
||||
* Ada.Characters.Wide_Latin_1 (a-cwila1.ads)::
|
||||
* Ada.Characters.Wide_Latin_9 (a-cwila9.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)::
|
||||
* Ada.Command_Line.Remove (a-colire.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)::
|
||||
* Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)::
|
||||
* Ada.Command_Line.Environment (a-colien.ads)::
|
||||
* Ada.Command_Line.Remove (a-colire.ads)::
|
||||
* Ada.Command_Line.Response_File (a-clrefi.ads)::
|
||||
* Ada.Direct_IO.C_Streams (a-diocst.ads)::
|
||||
* Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads)::
|
||||
* Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)::
|
||||
* Ada.Exceptions.Traceback (a-exctra.ads)::
|
||||
* Ada.Sequential_IO.C_Streams (a-siocst.ads)::
|
||||
* Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads)::
|
||||
@ -12762,7 +12894,9 @@ of GNAT, and will generate a warning message.
|
||||
* Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads)::
|
||||
* Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads)::
|
||||
* Ada.Text_IO.C_Streams (a-tiocst.ads)::
|
||||
* Ada.Wide_Characters.Unicode (a-wichun.ads)::
|
||||
* Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)::
|
||||
* Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)::
|
||||
* Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)::
|
||||
* GNAT.Altivec (g-altive.ads)::
|
||||
* GNAT.Altivec.Conversions (g-altcon.ads)::
|
||||
@ -12780,7 +12914,6 @@ of GNAT, and will generate a warning message.
|
||||
* GNAT.Byte_Swapping (g-bytswa.ads)::
|
||||
* GNAT.Calendar (g-calend.ads)::
|
||||
* GNAT.Calendar.Time_IO (g-catiio.ads)::
|
||||
* GNAT.CRC32 (g-crc32.ads)::
|
||||
* GNAT.Case_Util (g-casuti.ads)::
|
||||
* GNAT.CGI (g-cgi.ads)::
|
||||
* GNAT.CGI.Cookie (g-cgicoo.ads)::
|
||||
@ -12788,6 +12921,7 @@ of GNAT, and will generate a warning message.
|
||||
* GNAT.Command_Line (g-comlin.ads)::
|
||||
* GNAT.Compiler_Version (g-comver.ads)::
|
||||
* GNAT.Ctrl_C (g-ctrl_c.ads)::
|
||||
* GNAT.CRC32 (g-crc32.ads)::
|
||||
* GNAT.Current_Exception (g-curexc.ads)::
|
||||
* GNAT.Debug_Pools (g-debpoo.ads)::
|
||||
* GNAT.Debug_Utilities (g-debuti.ads)::
|
||||
@ -12822,6 +12956,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.Serial_Communications (g-sercom.ads)::
|
||||
* GNAT.SHA1 (g-sha1.ads)::
|
||||
* GNAT.Signals (g-signal.ads)::
|
||||
* GNAT.Sockets (g-socket.ads)::
|
||||
@ -12849,10 +12984,6 @@ of GNAT, and will generate a warning message.
|
||||
* Interfaces.C.Extensions (i-cexten.ads)::
|
||||
* Interfaces.C.Streams (i-cstrea.ads)::
|
||||
* Interfaces.CPP (i-cpp.ads)::
|
||||
* Interfaces.Os2lib (i-os2lib.ads)::
|
||||
* Interfaces.Os2lib.Errors (i-os2err.ads)::
|
||||
* Interfaces.Os2lib.Synchronization (i-os2syn.ads)::
|
||||
* Interfaces.Os2lib.Threads (i-os2thr.ads)::
|
||||
* Interfaces.Packed_Decimal (i-pacdec.ads)::
|
||||
* Interfaces.VxWorks (i-vxwork.ads)::
|
||||
* Interfaces.VxWorks.IO (i-vxwoio.ads)::
|
||||
@ -12860,6 +12991,8 @@ of GNAT, and will generate a warning message.
|
||||
* System.Assertions (s-assert.ads)::
|
||||
* System.Memory (s-memory.ads)::
|
||||
* System.Partition_Interface (s-parint.ads)::
|
||||
* System.Pool_Global (s-pooglo.ads)::
|
||||
* System.Pool_Local (s-pooloc.ads)::
|
||||
* System.Restrictions (s-restri.ads)::
|
||||
* System.Rident (s-rident.ads)::
|
||||
* System.Task_Info (s-tasinf.ads)::
|
||||
@ -12909,9 +13042,9 @@ instead of @code{Character}. The provision of such a package
|
||||
is specifically authorized by the Ada Reference Manual
|
||||
(RM A.3.3(27)).
|
||||
|
||||
@node Ada.Characters.Wide_Wide_Latin_1 (a-czila1.ads)
|
||||
@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
|
||||
@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-czila1.ads})
|
||||
@node Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads)
|
||||
@section @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
|
||||
@cindex @code{Ada.Characters.Wide_Wide_Latin_1} (@file{a-chzla1.ads})
|
||||
@cindex Latin_1 constants for Wide_Wide_Character
|
||||
|
||||
@noindent
|
||||
@ -12923,9 +13056,9 @@ instead of @code{Character}. The provision of such a package
|
||||
is specifically authorized by the Ada Reference Manual
|
||||
(RM A.3.3(27)).
|
||||
|
||||
@node Ada.Characters.Wide_Wide_Latin_9 (a-czila9.ads)
|
||||
@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
|
||||
@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-czila9.ads})
|
||||
@node Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads)
|
||||
@section @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
|
||||
@cindex @code{Ada.Characters.Wide_Wide_Latin_9} (@file{a-chzla9.ads})
|
||||
@cindex Latin_9 constants for Wide_Wide_Character
|
||||
|
||||
@noindent
|
||||
@ -12937,6 +13070,16 @@ instead of @code{Character}. The provision of such a package
|
||||
is specifically authorized by the Ada Reference Manual
|
||||
(RM A.3.3(27)).
|
||||
|
||||
@node Ada.Command_Line.Environment (a-colien.ads)
|
||||
@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
|
||||
@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
|
||||
@cindex Environment entries
|
||||
|
||||
@noindent
|
||||
This child of @code{Ada.Command_Line}
|
||||
provides a mechanism for obtaining environment values on systems
|
||||
where this concept makes sense.
|
||||
|
||||
@node Ada.Command_Line.Remove (a-colire.ads)
|
||||
@section @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
|
||||
@cindex @code{Ada.Command_Line.Remove} (@file{a-colire.ads})
|
||||
@ -12950,15 +13093,18 @@ arguments from the argument list. Once removed, an argument is not visible
|
||||
to further calls on the subprograms in @code{Ada.Command_Line} will not
|
||||
see the removed argument.
|
||||
|
||||
@node Ada.Command_Line.Environment (a-colien.ads)
|
||||
@section @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
|
||||
@cindex @code{Ada.Command_Line.Environment} (@file{a-colien.ads})
|
||||
@cindex Environment entries
|
||||
@node Ada.Command_Line.Response_File (a-clrefi.ads)
|
||||
@section @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
|
||||
@cindex @code{Ada.Command_Line.Response_File} (@file{a-clrefi.ads})
|
||||
@cindex Response file for command line
|
||||
@cindex Command line, response file
|
||||
@cindex Command line, handling long command lines
|
||||
|
||||
@noindent
|
||||
This child of @code{Ada.Command_Line}
|
||||
provides a mechanism for obtaining environment values on systems
|
||||
where this concept makes sense.
|
||||
This child of @code{Ada.Command_Line} provides a mechanism facilities for
|
||||
getting command line arguments from a text file, called a "response file".
|
||||
Using a response file allow passing a set of arguments to an executable longer
|
||||
than the maximum allowed by the system on the command line.
|
||||
|
||||
@node Ada.Direct_IO.C_Streams (a-diocst.ads)
|
||||
@section @code{Ada.Direct_IO.C_Streams} (@file{a-diocst.ads})
|
||||
@ -12981,6 +13127,16 @@ This child subprogram provides a way of testing for the null
|
||||
exception occurrence (@code{Null_Occurrence}) without raising
|
||||
an exception.
|
||||
|
||||
@node Ada.Exceptions.Last_Chance_Handler (a-elchha.ads)
|
||||
@section @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
|
||||
@cindex @code{Ada.Exceptions.Last_Chance_Handler} (@file{a-elchha.ads})
|
||||
@cindex Null_Occurrence, testing for
|
||||
|
||||
@noindent
|
||||
This child subprogram is used for handling otherwise unhandled
|
||||
exceptions (hence the name last chance), and perform clean ups before
|
||||
terminating the program. Note that this subprogram never returns.
|
||||
|
||||
@node Ada.Exceptions.Traceback (a-exctra.ads)
|
||||
@section @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
|
||||
@cindex @code{Ada.Exceptions.Traceback} (@file{a-exctra.ads})
|
||||
@ -13057,6 +13213,15 @@ C streams and @code{Text_IO}. The stream identifier can be
|
||||
extracted from a file opened on the Ada side, and an Ada file
|
||||
can be constructed from a stream opened on the C side.
|
||||
|
||||
@node Ada.Wide_Characters.Unicode (a-wichun.ads)
|
||||
@section @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
|
||||
@cindex @code{Ada.Wide_Characters.Unicode} (@file{a-wichun.ads})
|
||||
@cindex Unicode categorization, Wide_Character
|
||||
|
||||
@noindent
|
||||
This package provides subprograms that allow categorization of
|
||||
Wide_Character values according to Unicode categories.
|
||||
|
||||
@node Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads)
|
||||
@section @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
|
||||
@cindex @code{Ada.Wide_Text_IO.C_Streams} (@file{a-wtcstr.ads})
|
||||
@ -13068,6 +13233,15 @@ C streams and @code{Wide_Text_IO}. The stream identifier can be
|
||||
extracted from a file opened on the Ada side, and an Ada file
|
||||
can be constructed from a stream opened on the C side.
|
||||
|
||||
@node Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads)
|
||||
@section @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
|
||||
@cindex @code{Ada.Wide_Wide_Characters.Unicode} (@file{a-zchuni.ads})
|
||||
@cindex Unicode categorization, Wide_Wide_Character
|
||||
|
||||
@noindent
|
||||
This package provides subprograms that allow categorization of
|
||||
Wide_Wide_Character values according to Unicode categories.
|
||||
|
||||
@node Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads)
|
||||
@section @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
|
||||
@cindex @code{Ada.Wide_Wide_Text_IO.C_Streams} (@file{a-ztcstr.ads})
|
||||
@ -13726,6 +13900,15 @@ secondary stack.
|
||||
@noindent
|
||||
Provides classic counting and binary semaphores using protected types.
|
||||
|
||||
@node GNAT.Serial_Communications (g-sercom.ads)
|
||||
@section @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
|
||||
@cindex @code{GNAT.Serial_Communications} (@file{g-sercom.ads})
|
||||
@cindex Serial_Communications
|
||||
|
||||
@noindent
|
||||
Provides a simple interface to send and receive data over a serial
|
||||
port. This is only supported on GNU/Linux and Windows.
|
||||
|
||||
@node GNAT.SHA1 (g-sha1.ads)
|
||||
@section @code{GNAT.SHA1} (@file{g-sha1.ads})
|
||||
@cindex @code{GNAT.SHA1} (@file{g-sha1.ads})
|
||||
@ -14010,49 +14193,6 @@ This package provides facilities for use in interfacing to C++. It
|
||||
is primarily intended to be used in connection with automated tools
|
||||
for the generation of C++ interfaces.
|
||||
|
||||
@node Interfaces.Os2lib (i-os2lib.ads)
|
||||
@section @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
|
||||
@cindex @code{Interfaces.Os2lib} (@file{i-os2lib.ads})
|
||||
@cindex Interfacing, to OS/2
|
||||
@cindex OS/2 interfacing
|
||||
|
||||
@noindent
|
||||
This package provides interface definitions to the OS/2 library.
|
||||
It is a thin binding which is a direct translation of the
|
||||
various @file{<bse@.h>} files.
|
||||
|
||||
@node Interfaces.Os2lib.Errors (i-os2err.ads)
|
||||
@section @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
|
||||
@cindex @code{Interfaces.Os2lib.Errors} (@file{i-os2err.ads})
|
||||
@cindex OS/2 Error codes
|
||||
@cindex Interfacing, to OS/2
|
||||
@cindex OS/2 interfacing
|
||||
|
||||
@noindent
|
||||
This package provides definitions of the OS/2 error codes.
|
||||
|
||||
@node Interfaces.Os2lib.Synchronization (i-os2syn.ads)
|
||||
@section @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
|
||||
@cindex @code{Interfaces.Os2lib.Synchronization} (@file{i-os2syn.ads})
|
||||
@cindex Interfacing, to OS/2
|
||||
@cindex Synchronization, OS/2
|
||||
@cindex OS/2 synchronization primitives
|
||||
|
||||
@noindent
|
||||
This is a child package that provides definitions for interfacing
|
||||
to the @code{OS/2} synchronization primitives.
|
||||
|
||||
@node Interfaces.Os2lib.Threads (i-os2thr.ads)
|
||||
@section @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
|
||||
@cindex @code{Interfaces.Os2lib.Threads} (@file{i-os2thr.ads})
|
||||
@cindex Interfacing, to OS/2
|
||||
@cindex Thread control, OS/2
|
||||
@cindex OS/2 thread interfacing
|
||||
|
||||
@noindent
|
||||
This is a child package that provides definitions for interfacing
|
||||
to the @code{OS/2} thread primitives.
|
||||
|
||||
@node Interfaces.Packed_Decimal (i-pacdec.ads)
|
||||
@section @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
|
||||
@cindex @code{Interfaces.Packed_Decimal} (@file{i-pacdec.ads})
|
||||
@ -14136,6 +14276,30 @@ This package provides facilities for partition interfacing. It
|
||||
is used primarily in a distribution context when using Annex E
|
||||
with @code{GLADE}.
|
||||
|
||||
@node System.Pool_Global (s-pooglo.ads)
|
||||
@section @code{System.Pool_Global} (@file{s-pooglo.ads})
|
||||
@cindex @code{System.Pool_Global} (@file{s-pooglo.ads})
|
||||
@cindex Storage pool, global
|
||||
@cindex Global storage pool
|
||||
|
||||
@noindent
|
||||
This package provides a storage pool that is equivalent to the default
|
||||
storage pool used for access types for which no pool is specifically
|
||||
declared. It uses malloc/free to allocate/free and does not attempt to
|
||||
do any automatic reclamation.
|
||||
|
||||
@node System.Pool_Local (s-pooloc.ads)
|
||||
@section @code{System.Pool_Local} (@file{s-pooloc.ads})
|
||||
@cindex @code{System.Pool_Local} (@file{s-pooloc.ads})
|
||||
@cindex Storage pool, local
|
||||
@cindex Local storage pool
|
||||
|
||||
@noindent
|
||||
This package provides a storage pool that is intended for use with locally
|
||||
defined access types. It uses malloc/free for allocate/free, and maintains
|
||||
a list of allocated blocks, so that all storage allocated for the pool can
|
||||
be freed automatically when the pool is finalized.
|
||||
|
||||
@node System.Restrictions (s-restri.ads)
|
||||
@section @code{System.Restrictions} (@file{s-restri.ads})
|
||||
@cindex @code{System.Restrictions} (@file{s-restri.ads})
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
@c o
|
||||
@c G N A T _ U G N o
|
||||
@c o
|
||||
@c Copyright (C) 1992-2007, AdaCore o
|
||||
@c Copyright (C) 1992-2008, AdaCore o
|
||||
@c o
|
||||
@c GNAT is free software; you can redistribute it and/or modify it under o
|
||||
@c terms of the GNU General Public License as published by the Free Soft- o
|
||||
@ -89,7 +89,6 @@
|
||||
@set EDITION GNAT
|
||||
@set DEFAULTLANGUAGEVERSION Ada 2005
|
||||
@set NONDEFAULTLANGUAGEVERSION Ada 95
|
||||
@set FILE gnat_ugn
|
||||
|
||||
@ifset unw
|
||||
@set PLATFORM
|
||||
@ -102,7 +101,7 @@
|
||||
@settitle @value{EDITION} User's Guide @value{PLATFORM}
|
||||
@dircategory GNU Ada tools
|
||||
@direntry
|
||||
* @value{EDITION} User's Guide (@value{FILE}) @value{PLATFORM}
|
||||
* @value{EDITION} User's Guide (gnat_ugn) @value{PLATFORM}
|
||||
@end direntry
|
||||
|
||||
@include gcc-common.texi
|
||||
@ -195,6 +194,9 @@ AdaCore@*
|
||||
* Creating Sample Bodies Using gnatstub::
|
||||
* Other Utility Programs::
|
||||
* Running and Debugging Ada Programs::
|
||||
@ifclear vms
|
||||
* Code Coverage and Profiling::
|
||||
@end ifclear
|
||||
@ifset vms
|
||||
* Compatibility with HP Ada::
|
||||
@end ifset
|
||||
@ -503,6 +505,13 @@ Other Utility Programs
|
||||
* The External Symbol Naming Scheme of GNAT::
|
||||
* Converting Ada Files to html with gnathtml::
|
||||
|
||||
@ifclear vms
|
||||
Code Coverage and Profiling
|
||||
|
||||
* Code Coverage of Ada Programs using gcov::
|
||||
* Profiling an Ada Program using gprof::
|
||||
@end ifclear
|
||||
|
||||
Running and Debugging Ada Programs
|
||||
|
||||
* The GNAT Debugger GDB::
|
||||
@ -587,6 +596,7 @@ Platform-Specific Information for the Run-Time Libraries
|
||||
* Solaris-Specific Considerations::
|
||||
* Linux-Specific Considerations::
|
||||
* AIX-Specific Considerations::
|
||||
* Irix-Specific Considerations::
|
||||
|
||||
Example of Binder Output File
|
||||
|
||||
@ -842,6 +852,12 @@ a utility that generates empty but compilable bodies for library units.
|
||||
@ref{Other Utility Programs}, discusses several other GNAT utilities,
|
||||
including @code{gnathtml}.
|
||||
|
||||
@ifclear vms
|
||||
@item
|
||||
@ref{Code Coverage and Profiling}, describes how to perform a structural
|
||||
coverage and profile the execution of Ada programs.
|
||||
@end ifclear
|
||||
|
||||
@item
|
||||
@ref{Running and Debugging Ada Programs}, describes how to run and debug
|
||||
Ada programs.
|
||||
@ -5225,9 +5241,11 @@ This warning can also be turned on using @option{-gnatwa}.
|
||||
@item -gnatwW
|
||||
@emph{Suppress warnings on wrong low bound assumption.}
|
||||
@cindex @option{-gnatwW} (@command{gcc})
|
||||
This switch activates warnings for indexing an unconstrained string parameter
|
||||
with a literal or S'Length. This warning can also be suppressed by providing
|
||||
an Assert pragma that checks the low bound, for example:
|
||||
This switch suppresses warnings for indexing an unconstrained string parameter
|
||||
with a literal or S'Length. Note that this warning can also be suppressed
|
||||
in a particular case by adding an
|
||||
assertion that the lower bound is 1,
|
||||
as shown in the following example.
|
||||
|
||||
@smallexample @c ada
|
||||
procedure K (S : String) is
|
||||
@ -5235,6 +5253,22 @@ an Assert pragma that checks the low bound, for example:
|
||||
@dots{}
|
||||
@end smallexample
|
||||
|
||||
@item -gnatw.w
|
||||
@emph{Activate warnings on unnecessary Warnings Off pragmas}
|
||||
@cindex @option{-gnatw.w} (@command{gcc})
|
||||
@cindex Warnings Off control
|
||||
This switch activates warnings for use of @code{pragma Warnings (Off, entity}
|
||||
where either the pragma is entirely useless (because it suppresses no
|
||||
warnings), or it could be replaced by @code{pragma Unreferenced} or
|
||||
@code{pragma Unmodified}.The default is that these warnings are not given.
|
||||
Note that this warning is not included in -gnatwa, it must be
|
||||
activated explicitly.
|
||||
|
||||
@item -gnatw.W
|
||||
@emph{Suppress warnings on unnecessary Warnings Off pragmas}
|
||||
@cindex @option{-gnatw.W} (@command{gcc})
|
||||
This switch suppresses warnings for use of @code{pragma Warnings (Off, entity}.
|
||||
|
||||
@item -gnatwx
|
||||
@emph{Activate warnings on Export/Import pragmas.}
|
||||
@cindex @option{-gnatwx} (@command{gcc})
|
||||
@ -5297,7 +5331,9 @@ incompatibilities between Ada 95 and Ada 2005.
|
||||
This switch activates warnings for unchecked conversions
|
||||
where the types are known at compile time to have different
|
||||
sizes. The default
|
||||
is that such warnings are generated.
|
||||
is that such warnings are generated. Warnings are also
|
||||
generated for subprogram pointers with different conventions,
|
||||
and, on VMS only, for data pointers with different conventions.
|
||||
This warning can also be turned on using @option{-gnatwa}.
|
||||
|
||||
@item -gnatwZ
|
||||
@ -5305,7 +5341,7 @@ This warning can also be turned on using @option{-gnatwa}.
|
||||
@cindex @option{-gnatwZ} (@command{gcc})
|
||||
This switch suppresses warnings for unchecked conversions
|
||||
where the types are known at compile time to have different
|
||||
sizes.
|
||||
sizes or conventions.
|
||||
|
||||
@item ^-Wuninitialized^WARNINGS=UNINITIALIZED^
|
||||
@cindex @option{-Wuninitialized}
|
||||
@ -21535,6 +21571,10 @@ into the body stub.
|
||||
@cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub})
|
||||
Put a sample comment header into the body stub.
|
||||
|
||||
@item ^--header-file=@var{filename}^/FROM_HEADER_FILE=@var{filename}^
|
||||
@cindex @option{^--header-file^/FROM_HEADER_FILE=^} (@command{gnatstub})
|
||||
Use the content of the file as the comment header for a generated body stub.
|
||||
|
||||
@ifclear vms
|
||||
@item -IDIR
|
||||
@cindex @option{-IDIR} (@command{gnatstub})
|
||||
@ -21888,6 +21928,291 @@ $ RUN/DEBUG <PROGRAM_NAME>
|
||||
@noindent
|
||||
@end ifset
|
||||
|
||||
@ifclear vms
|
||||
@c ******************************
|
||||
@node Code Coverage and Profiling
|
||||
@chapter Code Coverage and Profiling
|
||||
@cindex Code Coverage
|
||||
@cindex Profiling
|
||||
|
||||
@noindent
|
||||
This chapter describes how to use @code{gcov} - coverage testing tool - and
|
||||
@code{gprof} - profiler tool - on your Ada programs.
|
||||
|
||||
@menu
|
||||
* Code Coverage of Ada Programs using gcov::
|
||||
* Profiling an Ada Program using gprof::
|
||||
@end menu
|
||||
|
||||
@node Code Coverage of Ada Programs using gcov
|
||||
@section Code Coverage of Ada Programs using gcov
|
||||
@cindex gcov
|
||||
@cindex -fprofile-arcs
|
||||
@cindex -ftest-coverage
|
||||
@cindex -coverage
|
||||
@cindex Code Coverage
|
||||
|
||||
@noindent
|
||||
@code{gcov} is a test coverage program: it analyzes the execution of a given
|
||||
program on selected tests, to help you determine the portions of the program
|
||||
that are still untested.
|
||||
|
||||
@code{gcov} is part of the GCC suite, and is described in detail in the GCC
|
||||
User's Guide. You can refer to this documentation for a more complete
|
||||
description.
|
||||
|
||||
This chapter provides a quick startup guide, and
|
||||
details some Gnat-specific features.
|
||||
|
||||
@menu
|
||||
* Quick startup guide::
|
||||
* Gnat specifics::
|
||||
@end menu
|
||||
|
||||
@node Quick startup guide
|
||||
@subsection Quick startup guide
|
||||
|
||||
In order to perform coverage analysis of a program using @code{gcov}, 3
|
||||
steps are needed:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Code instrumentation during the compilation process
|
||||
@item
|
||||
Execution of the instrumented program
|
||||
@item
|
||||
Execution of the @code{gcov} tool to generate the result.
|
||||
@end itemize
|
||||
|
||||
The code instrumentation needed by gcov is created at the object level:
|
||||
The source code is not modified in any way, because the instrumentation code is
|
||||
inserted by gcc during the compilation process. To compile your code with code
|
||||
coverage activated, you need to recompile your whole project using the
|
||||
switches
|
||||
@code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using
|
||||
@code{-fprofile-arcs}.
|
||||
|
||||
@smallexample
|
||||
$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \
|
||||
-largs -fprofile-arcs
|
||||
@end smallexample
|
||||
|
||||
This compilation process will create @file{.gcno} files together with
|
||||
the usual object files.
|
||||
|
||||
Once the program is compiled with coverage instrumentation, you can
|
||||
run it as many times as needed - on portions of a test suite for
|
||||
example. The first execution will produce @file{.gcda} files at the
|
||||
same location as the @file{.gcno} files. The following executions
|
||||
will update those files, so that a cumulative result of the covered
|
||||
portions of the program is generated.
|
||||
|
||||
Finaly, you need to call the @code{gcov} tool. The different options of
|
||||
@code{gcov} are available in the GCC User's Guide, section 'Invoking gcov'.
|
||||
|
||||
This will create anotated source files with a @file{.gcov} extension:
|
||||
@file{my_main.adb} file will be analysed in @file{my_main.adb.gcov}.
|
||||
|
||||
@node Gnat specifics
|
||||
@subsection Gnat specifics
|
||||
|
||||
Because Ada semantics, portions of the source code may be shared among
|
||||
several object files. This is the case for example when generics are
|
||||
involved, when inlining is active or when declarations generate initialisation
|
||||
calls. In order to take
|
||||
into account this shared code, you need to call @code{gcov} on all
|
||||
source files of the tested program at once.
|
||||
|
||||
The list of source files might exceed the system's maximum command line
|
||||
length. In order to bypass this limitation, a new mechanism has been
|
||||
implemented in @code{gcov}: you can now list all your project's files into a
|
||||
text file, and provide this file to gcov as a parameter, preceded by a @@
|
||||
(e.g. @samp{gcov @@mysrclist.txt}).
|
||||
|
||||
@node Profiling an Ada Program using gprof
|
||||
@section Profiling an Ada Program using gprof
|
||||
@cindex gprof
|
||||
@cindex -pg
|
||||
@cindex Profiling
|
||||
|
||||
@noindent
|
||||
This section is not meant to be an exhaustive documentation of @code{gprof}.
|
||||
Full documentation for it can be found in the GNU Profiler User's Guide
|
||||
documentation that is part of this GNAT distribution.
|
||||
|
||||
Profiling a program helps determine the parts of a program that are executed
|
||||
most often, and are therefore the most time-consuming.
|
||||
|
||||
@code{gprof} is the standard GNU profiling tool; it has been enhanced to
|
||||
better handle Ada programs and multitasking.
|
||||
It is currently supported on the following platoforms
|
||||
@itemize @bullet
|
||||
@item
|
||||
linux x86/x86_64
|
||||
@item
|
||||
solaris sparc/sparc64/x86
|
||||
@item
|
||||
windows x86
|
||||
@end itemize
|
||||
|
||||
@noindent
|
||||
In order to profile a program using @code{gprof}, 3 steps are needed:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
Code instrumentation, requiring a full recompilation of the project with the
|
||||
proper switches.
|
||||
@item
|
||||
Execution of the program under the analysis conditions, i.e. with the desired
|
||||
input.
|
||||
@item
|
||||
Analysis of the results using the @code{gprof} tool.
|
||||
@end itemize
|
||||
|
||||
@noindent
|
||||
The following sections detail the different steps, and indicate how
|
||||
to interpret the results:
|
||||
@menu
|
||||
* Compilation for profiling::
|
||||
* Program execution::
|
||||
* Running gprof::
|
||||
* Interpretation of profiling results::
|
||||
@end menu
|
||||
|
||||
@node Compilation for profiling
|
||||
@subsection Compilation for profiling
|
||||
@cindex -pg
|
||||
@cindex Profiling
|
||||
|
||||
In order to profile a program the first step is to tell the compiler
|
||||
to generate the necessary profiling information. The compiler switch to be used
|
||||
is @code{-pg}, which must be added to other compilation switches. This
|
||||
switch needs to be specified both during compilation and link stages, and can
|
||||
be specified once when using gnatmake:
|
||||
|
||||
@smallexample
|
||||
gnatmake -f -pg -P my_project
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
Note that only the objects that were compiled with the @samp{-pg} switch will be
|
||||
profiled; if you need to profile your whole project, use the
|
||||
@samp{-f} gnatmake switch to force full recompilation.
|
||||
|
||||
@node Program execution
|
||||
@subsection Program execution
|
||||
|
||||
@noindent
|
||||
Once the program has been compiled for profiling, you can run it as usual.
|
||||
|
||||
The only constraint imposed by profiling is that the program must terminate
|
||||
normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
|
||||
properly analyzed.
|
||||
|
||||
Once the program completes execution, a data file called @file{gmon.out} is
|
||||
generated in the directory where the program was launched from. If this file
|
||||
already exists, it will be overwritten.
|
||||
|
||||
@node Running gprof
|
||||
@subsection Running gprof
|
||||
|
||||
@noindent
|
||||
The @code{gprof} tool is called as follow:
|
||||
|
||||
@smallexample
|
||||
gprof my_prog gmon.out
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
or simpler:
|
||||
|
||||
@smallexample
|
||||
gprof my_prog
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
The complete form of the gprof command line is the following:
|
||||
|
||||
@smallexample
|
||||
gprof [^switches^options^] [executable [data-file]]
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
@code{gprof} supports numerous ^switch^options^. The order of these
|
||||
^switch^options^ does not matter. The full list of options can be found in
|
||||
the GNU Profiler User's Guide documentation that comes with this documentation.
|
||||
|
||||
The following is the subset of those switches that is most relevant:
|
||||
|
||||
@table @option
|
||||
|
||||
@item --demangle[=@var{style}]
|
||||
@itemx --no-demangle
|
||||
@cindex @option{--demangle} (@code{gprof})
|
||||
These options control whether symbol names should be demangled when
|
||||
printing output. The default is to demangle C++ symbols. The
|
||||
@code{--no-demangle} option may be used to turn off demangling. Different
|
||||
compilers have different mangling styles. The optional demangling style
|
||||
argument can be used to choose an appropriate demangling style for your
|
||||
compiler, in particular Ada symbols generated by GNAT can be demangled using
|
||||
@code{--demangle=gnat}.
|
||||
|
||||
@item -e @var{function_name}
|
||||
@cindex @option{-e} (@code{gprof})
|
||||
The @samp{-e @var{function}} option tells @code{gprof} not to print
|
||||
information about the function @var{function_name} (and its
|
||||
children@dots{}) in the call graph. The function will still be listed
|
||||
as a child of any functions that call it, but its index number will be
|
||||
shown as @samp{[not printed]}. More than one @samp{-e} option may be
|
||||
given; only one @var{function_name} may be indicated with each @samp{-e}
|
||||
option.
|
||||
|
||||
@item -E @var{function_name}
|
||||
@cindex @option{-E} (@code{gprof})
|
||||
The @code{-E @var{function}} option works like the @code{-e} option, but
|
||||
execution time spent in the function (and children who were not called from
|
||||
anywhere else), will not be used to compute the percentages-of-time for
|
||||
the call graph. More than one @samp{-E} option may be given; only one
|
||||
@var{function_name} may be indicated with each @samp{-E} option.
|
||||
|
||||
@item -f @var{function_name}
|
||||
@cindex @option{-f} (@code{gprof})
|
||||
The @samp{-f @var{function}} option causes @code{gprof} to limit the
|
||||
call graph to the function @var{function_name} and its children (and
|
||||
their children@dots{}). More than one @samp{-f} option may be given;
|
||||
only one @var{function_name} may be indicated with each @samp{-f}
|
||||
option.
|
||||
|
||||
@item -F @var{function_name}
|
||||
@cindex @option{-F} (@code{gprof})
|
||||
The @samp{-F @var{function}} option works like the @code{-f} option, but
|
||||
only time spent in the function and its children (and their
|
||||
children@dots{}) will be used to determine total-time and
|
||||
percentages-of-time for the call graph. More than one @samp{-F} option
|
||||
may be given; only one @var{function_name} may be indicated with each
|
||||
@samp{-F} option. The @samp{-F} option overrides the @samp{-E} option.
|
||||
|
||||
@end table
|
||||
|
||||
@node Interpretation of profiling results
|
||||
@subsection Interpretation of profiling results
|
||||
|
||||
@noindent
|
||||
|
||||
The results of the profiling analysis are represented by two arrays: the
|
||||
'flat profile' and the 'call graph'. Full documentation of those outputs
|
||||
can be found in the GNU Profiler User's Guide.
|
||||
|
||||
The flat profile shows the time spent in each function of the program, and how
|
||||
many time it has been called. This allows you to locate easily the most
|
||||
time-consuming functions.
|
||||
|
||||
The call graph shows, for each subprogram, the subprograms that call it,
|
||||
and the subprograms that it calls. It also provides an estimate of the time
|
||||
spent in each of those callers/called subprograms.
|
||||
@end ifclear
|
||||
|
||||
@c ******************************
|
||||
@node Running and Debugging Ada Programs
|
||||
@chapter Running and Debugging Ada Programs
|
||||
@cindex Debugging
|
||||
@ -24694,6 +25019,7 @@ information about several specific platforms.
|
||||
* Solaris-Specific Considerations::
|
||||
* Linux-Specific Considerations::
|
||||
* AIX-Specific Considerations::
|
||||
* Irix-Specific Considerations::
|
||||
@end menu
|
||||
|
||||
@node Summary of Run-Time Configurations
|
||||
@ -25010,6 +25336,24 @@ occurs in the environment task, or use @code{pragma Storage_Size} to
|
||||
specify a sufficiently large size for the stack of the task that contains
|
||||
this call.
|
||||
|
||||
@node Irix-Specific Considerations
|
||||
@section Irix-Specific Considerations
|
||||
@cindex Irix libraries
|
||||
|
||||
@noindent
|
||||
The GCC support libraries coming with the Irix compiler have moved to
|
||||
their canonical place with respect to the general Irix ABI related
|
||||
conventions. Running applications built with the default shared GNAT
|
||||
run-time now requires the LD_LIBRARY_PATH environment variable to
|
||||
include this location. A possible way to achieve this is to issue the
|
||||
following command line on a bash prompt:
|
||||
|
||||
@smallexample
|
||||
@group
|
||||
$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`dirname \`gcc --print-file-name=libgcc_s.so\``
|
||||
@end group
|
||||
@end smallexample
|
||||
|
||||
@c *******************************
|
||||
@node Example of Binder Output File
|
||||
@appendix Example of Binder Output File
|
||||
|
||||
@ -159,6 +159,8 @@ gcc -c ^ GNAT COMPILE
|
||||
-gnatwV ^ /WARNINGS=NOVARIABLES_UNINITIALIZED
|
||||
-gnatww ^ /WARNINGS=LOWBOUND_ASSUMED
|
||||
-gnatwW ^ /WARNINGS=NOLOWBOUND_ASSUMED
|
||||
-gnatw.w ^ /WARNINGS=WARNINGS_OFF_PRAGMAS
|
||||
-gnatw.W ^ /WARNINGS=NOWARNINGS_OFF_PRAGMAS
|
||||
-gnatwx ^ /WARNINGS=IMPORT_EXPORT_PRAGMAS
|
||||
-gnatwX ^ /WARNINGS=NOIMPORT_EXPORT_PRAGMAS
|
||||
-gnatw.x ^ /WARNINGS=LOCAL_RAISE_HANDLING
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
-- --
|
||||
-- B o d y --
|
||||
-- --
|
||||
-- Copyright (C) 1992-2007, Free Software Foundation, Inc. --
|
||||
-- Copyright (C) 1992-2008, Free Software Foundation, Inc. --
|
||||
-- --
|
||||
-- GNAT is free software; you can redistribute it and/or modify it under --
|
||||
-- terms of the GNU General Public License as published by the Free Soft- --
|
||||
@ -362,7 +362,7 @@ begin
|
||||
|
||||
Write_Switch_Char ("wxx");
|
||||
Write_Line ("Enable selected warning modes, xx = list of parameters:");
|
||||
Write_Line (" a turn on all optional warnings (except d h l .o)");
|
||||
Write_Line (" a turn on all optional warnings (except dhl.o.w)");
|
||||
Write_Line (" A turn off all optional warnings");
|
||||
Write_Line (" .a* turn on warnings for failing assertions");
|
||||
Write_Line (" .A turn off warnings for failing assertions");
|
||||
@ -428,6 +428,8 @@ begin
|
||||
Write_Line (" w* turn on warnings for wrong low bound assumption");
|
||||
Write_Line (" W turn off warnings for wrong low bound " &
|
||||
"assumption");
|
||||
Write_Line (" .w turn on warnings on pragma Warnings Off");
|
||||
Write_Line (" .w* turn off warnings on pragma Warnings Off");
|
||||
Write_Line (" x* turn on warnings for export/import");
|
||||
Write_Line (" X turn off warnings for export/import");
|
||||
Write_Line (" .x turn on warnings for non-local exceptions");
|
||||
|
||||
Loading…
Reference in New Issue
Block a user