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

building_executable_programs_with_gnat.rst, [...]: Doc improvements. 

* doc/gnat_ugn/building_executable_programs_with_gnat.rst,
	doc/gnat_ugn/gnat_utility_programs.rst
	doc/gnat_rm/implementation_defined_attributes.rst
	doc/gnat_rm/implementation_defined_pragmas.rst
	doc/gnat_rm/representation_clauses_and_pragmas.rst
	doc/gnat_rm/about_this_guide.rst
	doc/gnat_rm/implementation_of_ada_2012_features.rst: Doc improvements.
	* gnat_rm.texi, gnat_ugn.texi: Regenerate.

From-SVN: r221628
This commit is contained in:
Arnaud Charlet 2015-03-24 11:49:20 +00:00 committed by Arnaud Charlet
parent a258100585
commit a62638a348
10 changed files with 959 additions and 872 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
gcc/ada/ChangeLog
View File

@ -1,3 +1,14 @@
2015-03-24 Arnaud Charlet <charlet@adacore.com>
* doc/gnat_ugn/building_executable_programs_with_gnat.rst,
doc/gnat_ugn/gnat_utility_programs.rst
doc/gnat_rm/implementation_defined_attributes.rst
doc/gnat_rm/implementation_defined_pragmas.rst
doc/gnat_rm/representation_clauses_and_pragmas.rst
doc/gnat_rm/about_this_guide.rst
doc/gnat_rm/implementation_of_ada_2012_features.rst: Doc improvements.
* gnat_rm.texi, gnat_ugn.texi: Regenerate.
2015-03-23 Jakub Jelinek <jakub@redhat.com>
PR bootstrap/65522

7
gcc/ada/doc/gnat_rm/about_this_guide.rst
View File

@ -115,10 +115,9 @@ This reference manual contains the following chapters:
This reference manual assumes a basic familiarity with the Ada 95 language, as
described in the
:title:`International Standard ANSI/ISO/IEC-8652:1995`.
It does not require knowledge of the new features introduced by Ada 2005,
(officially known as `ISO/IEC 8652:1995 with Technical Corrigendum 1
and Amendment 1`).
Both reference manuals are included in the GNAT documentation
It does not require knowledge of the new features introduced by Ada 2005 or
Ada 2012.
All three reference manuals are included in the GNAT documentation
package.
Conventions

73
gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst
View File

@ -146,7 +146,7 @@ an address clause as in the following example:
procedure L;
for L'Address use K'Address;
pragma Import (Ada, L);
A call to `L` is then expected to result in a call to `K`.
In Ada 83, where there were no access-to-subprogram values, this was
@ -186,6 +186,7 @@ attribute in the generic instance when applied to a scalar type or a
record type without discriminants is always `True`. This usage is
compatible with older Ada compilers, including notably DEC Ada.
Attribute Default_Bit_Order
===========================
.. index:: Big endian
@ -214,6 +215,16 @@ order (as specified using pragma `Default_Scalar_Storage_Order`, or
equal to `Default_Bit_Order` if unspecified) as a
`System.Bit_Order` value. This is a static attribute.
Attribute Deref
===============
.. index:: Deref
The attribute `typ'Deref(expr)` where `expr` is of type `System.Address` yields
the variable of type `typ` that is located at the given address. It is similar
to `(totyp (expr).all)`, where `totyp` is an unchecked conversion from address to
a named access-to-`typ` type, except that it yields a variable, so it can be
used on the left side of an assignment.
Attribute Descriptor_Size
=========================
.. index:: Descriptor
@ -232,7 +243,7 @@ the first element of the array.
type Unconstr_Array is array (Positive range <>) of Boolean;
Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img);
The attribute takes into account any additional padding due to type alignment.
In the example above, the descriptor contains two values of type
@ -331,7 +342,7 @@ function with the following spec:
.. code-block:: ada
function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>;
It is also allowable to apply `Enum_Rep` directly to an object of an
enumeration type or to a non-overloaded enumeration
@ -366,7 +377,7 @@ function with the following spec:
.. code-block:: ada
function S'Enum_Val (Arg : <Universal_Integer>) return S'Base;
The function returns the enumeration value whose representation matches the
argument, or raises Constraint_Error if no enumeration literal of the type
@ -403,11 +414,11 @@ function with the following specification:
.. code-block:: ada
function S'Fixed_Value (Arg : <Universal_Integer>) return S;
The value returned is the fixed-point value `V` such that::
V = Arg * S'Small
The effect is thus similar to first converting the argument to the
integer type used to represent `S`, and then doing an unchecked
@ -461,14 +472,14 @@ debugging:
.. code-block:: ada
Put_Line ("X = " & X'Img);
has the same meaning as the more verbose:
.. code-block:: ada
Put_Line ("X = " & T'Image (X));
where `T` is the (sub)type of the object `X`.
Note that technically, in analogy to `Image`,
@ -491,7 +502,7 @@ function with the following spec:
The value returned is the integer value `V`, such that::
Arg = V * T'Small
where `T` is the type of `Arg`.
The effect is thus similar to first doing an unchecked conversion from
@ -550,7 +561,7 @@ in this example:
"Gen can only be instantiated at library level");
...
end Gen;
Attribute Lock_Free
===================
@ -566,7 +577,7 @@ Attribute Loop_Entry
Syntax::
X'Loop_Entry [(loop_name)]
The `Loop_Entry` attribute is used to refer to the value that an
expression had upon entry to a given loop in much the same way that the
@ -678,7 +689,7 @@ Similarly, a record containing an integer and a character:
I : Integer;
C : Character;
end record;
will have a size of 40 (that is `Rec'Size` will be 40). The
alignment will be 4, because of the
@ -715,7 +726,7 @@ Consider this example:
type "R1" defined at line 3
13. end;
In the absence of lines 5 and 6,
types `R1` and `R2` statically match and
@ -765,8 +776,8 @@ bounds are allocated just before the first component,
whereas ``X'Address`` returns the address of the first
component.
Here, we are interpreting 'storage pool' broadly to mean
``wherever the object is allocated``, which could be a
Here, we are interpreting 'storage pool' broadly to mean
``wherever the object is allocated``, which could be a
user-defined storage pool,
the global heap, on the stack, or in a static memory area.
For an object created by `new`, ``Ptr.all'Pool_Address`` is
@ -803,7 +814,7 @@ There are two forms:
System'Restriction_Set (partition_boolean_restriction_NAME)
System'Restriction_Set (No_Dependence => library_unit_NAME);
In the case of the first form, the only restriction names
allowed are parameterless restrictions that are checked
@ -839,7 +850,7 @@ So for example if you write
else
...
end if;
And the result is False, so that the else branch is executed,
you can assume that this restriction is not set for any unit
@ -939,7 +950,7 @@ of the use of this feature:
-- If Scalar_Storage_Order is specified, it must be consistent with
-- Bit_Order, so it's best to always define the latter explicitly if
-- the former is used.
Other properties are as for standard representation attribute `Bit_Order`,
as defined by Ada RM 13.5.3(4). The default is `System.Default_Bit_Order`.
@ -1020,7 +1031,7 @@ via an attribute_definition_clause (or by specifying the equivalent aspect):
for Acc'Simple_Storage_Pool use My_Pool;
The name given in an attribute_definition_clause for the
`Simple_Storage_Pool` attribute shall denote a variable of
@ -1174,7 +1185,7 @@ corresponding actual subtype. The value of this attribute is of type
Type_Class_Access,
Type_Class_Task,
Type_Class_Address);
Protected types yield the value `Type_Class_Task`, which thus
applies to all concurrent types. This attribute is designed to
@ -1241,7 +1252,7 @@ For example, the following program prints the first 50 digits of pi:
begin
Put (Ada.Numerics.Pi'Universal_Literal_String);
end;
Attribute Unrestricted_Access
=============================
@ -1291,7 +1302,7 @@ has returned, such calls are erroneous. For example:
end P2;
end P;
When P1 is called from P2, the call via Global is OK, but if P1 were
called after P2 returns, it would be an erroneous use of a dangling
@ -1348,7 +1359,7 @@ reject the use as illegal, as shown in the following example:
P (X2'Unrestricted_Access); -- OK
end;
but other cases cannot be detected by the compiler, and are
considered to be erroneous. Consider the following example:
@ -1376,7 +1387,7 @@ considered to be erroneous. Consider the following example:
begin
P (A (Y));
end;
A normal unconstrained array value
or a constrained array object marked as aliased has the bounds in memory
@ -1408,7 +1419,7 @@ is not well-defined. Consider this example:
RV : R := P'Unrestricted_Access;
..
RV.all := 3;
Here we attempt to modify the constant P from 4 to 3, but the compiler may
or may not notice this attempt, and subsequent references to P may yield
@ -1425,7 +1436,7 @@ value of an `IN` parameter:
begin
RV.all := 'a';
end;
In general this is a risky approach. It may appear to "work" but such uses of
`Unrestricted_Access` are potentially non-portable, even from one version
@ -1446,7 +1457,7 @@ with one or more modified components. The syntax is::
MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION
INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST {| INDEX_EXPRESSION_LIST }
INDEX_EXPRESSION_LIST ::= ( EXPRESSION {, EXPRESSION } )
where `PREFIX` is the name of an array or record object, the
association list in parentheses does not contain an `others`
@ -1463,7 +1474,7 @@ example:
...
Avar1 : Arr := (1,2,3,4,5);
Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20);
yields a value for `Avar2` of 1,10,20,20,5 with `Avar1`
begin unmodified. Similarly:
@ -1474,7 +1485,7 @@ begin unmodified. Similarly:
...
Rvar1 : Rec := (A => 1, B => 2, C => 3);
Rvar2 : Rec := Rvar1'Update (B => 20);
yields a value for `Rvar2` of (A => 1, B => 20, C => 3),
with `Rvar1` being unmodifed.
@ -1484,7 +1495,7 @@ completely before it is used. This means that if you write:
.. code-block:: ada
Avar1 := Avar1'Update (1 => 10, 2 => Function_Call);
then the value of `Avar1` is not modified if `Function_Call`
raises an exception, unlike the effect of a series of direct assignments
@ -1508,7 +1519,7 @@ Multi-dimensional arrays can be modified, as shown by this example:
A : array (1 .. 10, 1 .. 10) of Integer;
..
A := A'Update ((1, 2) => 20, (3, 4) => 30);
which changes element (1,2) to 20 and (3,4) to 30.

21
gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst
View File

@ -2196,6 +2196,25 @@ Syntax:
This pragma is identical in effect to pragma `Comment`. It is provided
for compatibility with other Ada compilers providing this pragma.
Pragma Ignore_Pragma
====================
Syntax:
.. code-block:: ada
pragma Ignore_Pragma (pragma_IDENTIFIER);
This is a configuration pragma
that takes a single argument that is a simple identifier. Any subsequent
use of a pragma whose pragma identifier matches this argument will be
silently ignored. This may be useful when legacy code or code intended
for compilation with some other compiler contains pragmas that match the
name, but not the exact implementation, of a `GNAT` pragma. The use of this
pragma allows such pragmas to be ignored, which may be useful in `CodePeer`
mode, or during porting of legacy code.
Pragma Implementation_Defined
=============================
@ -5737,6 +5756,8 @@ names that are implementation defined (as permitted by the RM):
on addresses used in address clauses. Such checks can also be suppressed
by suppressing range checks, but the specific use of `Alignment_Check`
allows suppression of alignment checks without suppressing other range checks.
Note that `Alignment_Check` is suppressed by default on machines (such as
the x86) with non-strict alignment.
*
`Atomic_Synchronization` can be used to suppress the special memory

6
gcc/ada/doc/gnat_rm/implementation_of_ada_2012_features.rst
View File

@ -15,8 +15,10 @@ Implementation of Ada 2012 Features
.. index:: Ada_2012 configuration pragma
This chapter contains a complete list of Ada 2012 features that have been
implemented as of GNAT version 6.4. Generally, these features are only
available if the *-gnat12* (Ada 2012 features enabled) flag is set
implemented.
Generally, these features are only
available if the *-gnat12* (Ada 2012 features enabled) option is set,
which is the default behavior,
or if the configuration pragma `Ada_2012` is used.
However, new pragmas, attributes, and restrictions are

158
gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst
View File

@ -84,7 +84,7 @@ values are as follows:
A, B : Character;
end record;
for Small'Size use 16;
then the default alignment of the record type `Small` is 2, not 1. This
leads to more efficient code when the record is treated as a unit, and also
allows the type to specified as `Atomic` on architectures requiring
@ -122,7 +122,7 @@ to control this choice. Consider:
type R is range 1 .. 10_000;
for R'Alignment use 1;
subtype RS is R range 1 .. 1000;
The alignment clause specifies an alignment of 1 for the first named subtype
`R` but this does not necessarily apply to `RS`. When writing
portable Ada code, you should avoid writing code that explicitly or
@ -159,7 +159,7 @@ For example:
Y1 : integer;
Y2 : boolean;
end record;
In this example, `Smallint'Size` = `Smallint'Value_Size` = 3,
as specified by the RM rules,
but objects of this type will have a size of 8
@ -189,7 +189,7 @@ increasing it. For example, if we have:
type My_Boolean is new Boolean;
for My_Boolean'Size use 32;
then values of this type will always be 32 bits long. In the case of
discrete types, the size can be increased up to 64 bits, with the effect
that the entire specified field is used to hold the value, sign- or
@ -227,7 +227,7 @@ task definition a pragma of the form:
.. code-block:: ada
pragma Storage_Size (Default_Stack_Size);
Then `Default_Stack_Size` can be defined in a global package, and
modified as required. Any tasks requiring stack sizes different from the
default can have an appropriate alternative reference in the pragma.
@ -269,7 +269,7 @@ size storage pool is eliminated. Consider the following example:
-- ...
y := new R;
end;
As indicated in this example, these dummy storage pools are often useful in
connection with interfacing where no object will ever be allocated. If you
compile the above example, you get the warning:
@ -278,7 +278,7 @@ compile the above example, you get the warning:
p.adb:16:09: warning: allocation from empty storage pool
p.adb:16:09: warning: Storage_Error will be raised at run time
Of course in practice, there will not be any explicit allocators in the
case of such an access declaration.
@ -314,7 +314,7 @@ for any variant. Consider the following program
Put_Line (Integer'Image (V1'Size));
Put_Line (Integer'Image (V2'Size));
end q;
Here we are dealing with a variant record, where the True variant
requires 16 bits, and the False variant requires 8 bits.
In the above example, both V1 and V2 contain the False variant,
@ -325,7 +325,7 @@ program is:
8
16
The reason for the difference here is that the discriminant value of
V1 is fixed, and will always be False. It is not possible to assign
a True variant value to V1, therefore 8 bits is sufficient. On the
@ -376,7 +376,7 @@ Consider the following modified version of the above program:
Put_Line (Integer'Image (V2'Size));
Put_Line (Integer'IMage (Size (V2)));
end q;
The output from this program is
::
@ -385,7 +385,7 @@ The output from this program is
8
16
16
Here we see that while the `'Size` attribute always returns
the maximum size, regardless of the current variant value, the
`Size` function does indeed return the size of the current
@ -413,7 +413,7 @@ For example, suppose we have the declaration:
type Small is range -7 .. -4;
for Small'Size use 2;
Although the default size of type `Small` is 4, the `Size`
clause is accepted by GNAT and results in the following representation
scheme:
@ -424,7 +424,7 @@ scheme:
-6 is represented as 2#01#
-5 is represented as 2#10#
-4 is represented as 2#11#
Biased representation is only used if the specified `Size` clause
cannot be accepted in any other manner. These reduced sizes that force
biased representation can be used for all discrete types except for
@ -461,7 +461,7 @@ from Ada 83 to Ada 95 or Ada 2005. For example, consider:
at 0 range 0 .. Natural'Size - 1;
at 0 range Natural'Size .. 2 * Natural'Size - 1;
end record;
In the above code, since the typical size of `Natural` objects
is 32 bits and `Natural'Size` is 31, the above code can cause
unexpected inefficient packing in Ada 95 and Ada 2005, and in general
@ -485,19 +485,19 @@ byte access instructions such as the Alpha.
The default rules for the value of `Object_Size` for
discrete types are as follows:
*
*
The `Object_Size` for base subtypes reflect the natural hardware
size in bits (run the compiler with *-gnatS* to find those values
for numeric types). Enumeration types and fixed-point base subtypes have
8, 16, 32 or 64 bits for this size, depending on the range of values
to be stored.
*
*
The `Object_Size` of a subtype is the same as the
`Object_Size` of
the type from which it is obtained.
*
*
The `Object_Size` of a derived base type is copied from the parent
base type, and the `Object_Size` of a derived first subtype is copied
from the parent first subtype.
@ -513,18 +513,18 @@ target dependent).
The default rules for the value of `Value_Size` are as follows:
*
*
The `Value_Size` for a base subtype is the minimum number of bits
required to store all values of the type (including the sign bit
only if negative values are possible).
*
*
If a subtype statically matches the first subtype of a given type, then it has
by default the same `Value_Size` as the first subtype. This is a
consequence of RM 13.1(14): "if two subtypes statically match,
then their subtype-specific aspects are the same".)
*
*
All other subtypes have a `Value_Size` corresponding to the minimum
number of bits required to store all values of the subtype. For
dynamic bounds, it is assumed that the value can range down or up
@ -588,13 +588,13 @@ under what conditions must the RM `Size` be used.
The following is a list
of the occasions on which the RM `Size` must be used:
*
*
Component size for packed arrays or records
*
*
Value of the attribute `Size` for a type
*
*
Warning about sizes not matching for unchecked conversion
For record types, the `Object_Size` is always a multiple of the
@ -608,7 +608,7 @@ alignment of the type (this is true for all types). In some cases the
X : Integer;
Y : Character;
end record;
On a typical 32-bit architecture, the X component will be four bytes, and
require four-byte alignment, and the Y component will be one byte. In this
@ -632,7 +632,7 @@ for a particular subtype. Consider this example:
type R is (A, B, C, D, E, F);
subtype RAB is R range A .. B;
subtype REF is R range E .. F;
By default, `RAB`
has a size of 1 (sufficient to accommodate the representation
@ -645,7 +645,7 @@ following `Value_Size` attribute definition clause:
.. code-block:: ada
for REF'Value_Size use 1;
then biased representation is forced for `REF`,
and 0 will represent `E` and 1 will represent `F`.
@ -676,7 +676,7 @@ honor all packing requests in this range. For example, if we have:
type r is array (1 .. 8) of Natural;
for r'Component_Size use 31;
then the resulting array has a length of 31 bytes (248 bits = 8 * 31).
Of course access to the components of such an array is considerably
@ -695,7 +695,7 @@ padded because of its default alignment. For example, if we have:
type a is array (1 .. 8) of r;
for a'Component_Size use 72;
then the resulting array has a length of 72 bytes, instead of 96 bytes
if the alignment of the record (4) was obeyed.
@ -758,7 +758,7 @@ restrictions placed on component clauses as follows:
A at 0 range 7 .. 7;
B at 0 range 0 .. 6;
end record;
The useful application here is to write the second declaration with the
`Bit_Order` attribute definition clause, and know that it will be treated
@ -784,7 +784,7 @@ restrictions placed on component clauses as follows:
for R2 use record
A at 0 range 0 .. 31;
end record;
This declaration will result in a little-endian integer on a
little-endian machine, and a big-endian integer on a big-endian machine.
@ -804,7 +804,7 @@ restrictions placed on component clauses as follows:
Since the misconception that Bit_Order automatically deals with all
endian-related incompatibilities is a common one, the specification of
a component field that is an integral number of bytes will always
generate a warning. This warning may be suppressed using `pragma Warnings (Off)`
generate a warning. This warning may be suppressed using `pragma Warnings (Off)`
if desired. The following section contains additional
details regarding the issue of byte ordering.
@ -907,7 +907,7 @@ On a big-endian machine, we can write the following representation clause
Slave_V6 at 1 range 6 .. 6;
Slave_V7 at 1 range 7 .. 7;
end record;
Now if we move this to a little endian machine, then the bit ordering within
the byte is backwards, so we have to rewrite the record rep clause as:
@ -933,7 +933,7 @@ the byte is backwards, so we have to rewrite the record rep clause as:
Slave_V6 at 1 range 1 .. 1;
Slave_V7 at 1 range 0 .. 0;
end record;
It is a nuisance to have to rewrite the clause, especially if
the code has to be maintained on both machines. However,
@ -948,7 +948,7 @@ first record clause, together with the declaration
.. code-block:: ada
for Data'Bit_Order use High_Order_First;
and the effect is what is desired, namely the layout is exactly the same,
independent of whether the code is compiled on a big-endian or little-endian
@ -982,7 +982,7 @@ example as:
Slave_V6 at 0 range 14 .. 14;
Slave_V7 at 0 range 15 .. 15;
end record;
This is exactly equivalent to saying (a repeat of the first example):
@ -1008,7 +1008,7 @@ This is exactly equivalent to saying (a repeat of the first example):
Slave_V6 at 1 range 6 .. 6;
Slave_V7 at 1 range 7 .. 7;
end record;
Why are they equivalent? Well take a specific field, the `Slave_V2`
field. The storage place attributes are obtained by normalizing the
@ -1060,7 +1060,7 @@ some machines we might write:
Slave_V6 at Slave_Byte range 6 .. 6;
Slave_V7 at Slave_Byte range 7 .. 7;
end record;
Now to switch between machines, all that is necessary is
to set the boolean constant `Master_Byte_First` in
an appropriate manner.
@ -1076,13 +1076,13 @@ Pragma `Pack` applied to an array has no effect unless the component type
is packable. For a component type to be packable, it must be one of the
following cases:
*
*
Any scalar type
*
*
Any type whose size is specified with a size clause
*
*
Any packed array type with a static size
*
*
Any record type padded because of its default alignment
For all these cases, if the component subtype size is in the range
@ -1096,7 +1096,7 @@ For example if we have:
type ar is array (1 .. 8) of r;
pragma Pack (ar);
Then the component size of `ar` will be set to 5 (i.e., to `r'size`,
and the size of the array `ar` will be exactly 40 bits.
@ -1154,7 +1154,7 @@ occurs with subtype `Natural`. Consider:
type Arr is array (1 .. 32) of Natural;
pragma Pack (Arr);
In all commonly used Ada 83 compilers, this pragma Pack would be ignored,
since typically `Natural'Size` is 32 in Ada 83, and in any case most
Ada 83 compilers did not attempt 31 bit packing.
@ -1170,7 +1170,7 @@ explicitly:
type Arr is array (1 .. 32) of Natural;
for Arr'Component_Size use 31;
Here 31-bit packing is achieved as required, and no warning is generated,
since in this case the programmer intention is clear.
@ -1187,11 +1187,11 @@ taken by components. We distinguish between *packable* components and
*non-packable* components.
Components of the following types are considered packable:
*
*
Components of a primitive type are packable unless they are aliased
or of an atomic type.
*
*
Small packed arrays, whose size does not exceed 64 bits, and where the
size is statically known at compile time, are represented internally
as modular integers, and so they are also packable.
@ -1226,7 +1226,7 @@ For example, consider the record
L6 : Rb2;
end record;
pragma Pack (X2);
The representation for the record X2 is as follows:
.. code-block:: ada
@ -1282,7 +1282,7 @@ thus the same lack of restriction applies. For example, if you declare:
type R is array (1 .. 49) of Boolean;
pragma Pack (R);
for R'Size use 49;
then a component clause for a component of type R may start on any
specified bit boundary, and may specify a value of 49 bits or greater.
@ -1331,7 +1331,7 @@ so for example, the following is permitted:
L at 0 range 2 .. 81;
R at 0 range 82 .. 161;
end record;
Note: the above rules apply to recent releases of GNAT 5.
In GNAT 3, there are more severe restrictions on larger components.
For non-primitive types, including packed arrays with a size greater than
@ -1371,7 +1371,7 @@ or address overlays. For example
C : Character;
I : Integer;
end record;
On typical machines, integers need to be aligned on a four-byte
boundary, resulting in three bytes of undefined rubbish following
the 8-bit field for C. To ensure that the hole in a variable of
@ -1387,7 +1387,7 @@ you could for example do:
BaseVar : Base;
RealVar : Hrec;
for RealVar'Address use BaseVar'Address;
Now the 8-bytes of the value of RealVar start out containing all zero
bits. A safer approach is to just define dummy fields, avoiding the
@ -1402,7 +1402,7 @@ holes, as in:
Dummy3 : Short_Short_Integer := 0;
I : Integer;
end record;
And to make absolutely sure that the intent of this is followed, you
can use representation clauses:
@ -1416,7 +1416,7 @@ can use representation clauses:
I at 4 range 0 .. 31;
end record;
for Hrec'Size use 64;
.. _Enumeration_Clauses:
@ -1437,7 +1437,7 @@ be in the range:
.. code-block:: ada
0 .. System.Max_Binary_Modulus;
A *confirming* representation clause is one in which the values range
from 0 in sequence, i.e., a clause that confirms the default representation
@ -1455,7 +1455,7 @@ manner. Consider the declarations:
type r is (A, B, C);
for r use (A => 1, B => 5, C => 10);
type t is array (r) of Character;
The array type t corresponds to a vector with exactly three elements and
has a default size equal to `3*Character'Size`. This ensures efficient
use of space, but means that accesses to elements of the array will incur
@ -1519,14 +1519,14 @@ if one is present, is inexpensive). In addition, if there is no implicit or
explicit initialization, then there are no restrictions. GNAT will reject
only the case where all three of these conditions hold:
*
*
The type of the item is non-elementary (e.g., a record or array).
*
*
There is explicit or implicit initialization required for the object.
Note that access values are always implicitly initialized.
*
*
The address value is non-static. Here GNAT is more permissive than the
RM, and allows the address value to be the address of a previously declared
stand-alone variable, as long as it does not itself have an address clause.
@ -1536,7 +1536,7 @@ only the case where all three of these conditions hold:
Anchor : Some_Initialized_Type;
Overlay : Some_Initialized_Type;
for Overlay'Address use Anchor'Address;
However, the prefix of the address clause cannot be an array component, or
a component of a discriminated record.
@ -1553,7 +1553,7 @@ expressions have identical values:
To_Address (16#1234_0000#)
System'To_Address (16#1234_0000#);
except that the second form is considered to be a static expression, and
thus when used as an address clause value is always permitted.
@ -1569,13 +1569,15 @@ the same as the alignment of the type of the object). If an address clause
is given that specifies an inappropriately aligned address value, then the
program execution is erroneous.
Since this source of erroneous behavior can have unfortunate effects, GNAT
Since this source of erroneous behavior can have unfortunate effects on
machines with strict alignment requirements, GNAT
checks (at compile time if possible, generating a warning, or at execution
time with a run-time check) that the alignment is appropriate. If the
run-time check fails, then `Program_Error` is raised. This run-time
check is suppressed if range checks are suppressed, or if the special GNAT
check Alignment_Check is suppressed, or if
`pragma Restrictions (No_Elaboration_Code)` is in effect.
`pragma Restrictions (No_Elaboration_Code)` is in effect. It is also
suppressed by default on non-strict alignment machines (such as the x86).
Finally, GNAT does not permit overlaying of objects of controlled types or
composite types containing a controlled component. In most cases, the compiler
@ -1621,7 +1623,7 @@ programmer wants, so GNAT will output a warning:
initialization (RM B(24))
end G;
As indicated by the warning message, the solution is to use a (dummy) pragma
Import to suppress this initialization. The pragma tell the compiler that the
object is declared and initialized elsewhere. The following package compiles
@ -1639,7 +1641,7 @@ without warnings (and the initialization is suppressed):
for Ext'Address use System'To_Address (16#1234_1234#);
pragma Import (Ada, Ext);
end G;
A final issue with address clauses involves their use for overlaying
variables, as in the following example:
@ -1651,7 +1653,7 @@ variables, as in the following example:
A : Integer;
B : Integer;
for B'Address use A'Address;
or alternatively, using the form recommended by the RM:
@ -1661,7 +1663,7 @@ or alternatively, using the form recommended by the RM:
Addr : constant Address := A'Address;
B : Integer;
for B'Address use Addr;
In both of these cases, `A`
and `B` become aliased to one another via the
@ -1702,7 +1704,7 @@ issue of unintentional initialization, as shown by this example:
suppress initialization (RM B.1(24))
end Overwrite_Record;
Here the default initialization of `Y` will clobber the value
of `X`, which justifies the warning. The warning notes that
this effect can be eliminated by adding a `pragma Import`
@ -1720,7 +1722,7 @@ which suppresses the initialization:
for Y'Address use X'Address;
pragma Import (Ada, Y);
end Overwrite_Record;
Note that the use of `pragma Initialize_Scalars` may cause variables to
be initialized when they would not otherwise have been in the absence
@ -1751,7 +1753,7 @@ for the composite object:
Put_Line ("X was not clobbered");
end if;
end Overwrite_Array;
The above program generates the warning as shown, and at execution
time, prints `X was clobbered`. If the `pragma Import` is
added as suggested:
@ -1773,7 +1775,7 @@ added as suggested:
Put_Line ("X was not clobbered");
end if;
end Overwrite_Array;
then the program compiles without the warning and when run will generate
the output `X was not clobbered`.
@ -1803,7 +1805,7 @@ operations, for example:
Temp := Mem;
Temp.A := 32;
Mem := Temp;
For a full access (reference or modification) of the variable (Mem) in
this case, as in the above examples, GNAT guarantees that the entire atomic
word will be accessed. It is not clear whether the RM requires this. For
@ -1816,7 +1818,7 @@ A problem arises with a component access such as:
.. code-block:: ada
Mem.A := 32;
Note that the component A is not declared as atomic. This means that it is
not clear what this assignment means. It could correspond to full word read
and write as given in the first example, or on architectures that supported
@ -1831,7 +1833,7 @@ a warning in such a case:
|
>>> warning: access to non-atomic component of atomic array,
may cause unexpected accesses to atomic object
It is best to be explicit in this situation, by either declaring the
components to be atomic if you want the byte store, or explicitly writing
the full word access sequence if that is what the hardware requires.
@ -1869,7 +1871,7 @@ There are four exceptions to this general rule:
::
type Color is (Red, Green, Blue);
8 bits is sufficient to store all values of the type, so by default, objects
of type `Color` will be represented using 8 bits. However, normal C
convention is to use 32 bits for all enum values in C, since enum values
@ -1902,7 +1904,7 @@ There are four exceptions to this general rule:
type C_Switch is new Boolean;
pragma Convention (C, C_Switch);
then the GNAT generated code will treat any nonzero value as true. For truth
values generated by GNAT, the conventional value 1 will be used for True, but
@ -1984,7 +1986,7 @@ The following program shows these conventions in action:
>>> subprogram "F" has wrong convention
>>> does not match access to subprogram declared at line 24
39. end ConvComp;
.. _Determining_the_Representations_chosen_by_GNAT:
@ -2058,7 +2060,7 @@ clauses. For example, if we compile the package:
end record;
pragma Pack (x2);
end q;
using the switch *-gnatR* we obtain the following output:
.. code-block:: ada
@ -2111,7 +2113,7 @@ using the switch *-gnatR* we obtain the following output:
l5 at 16 range 1 .. 13;
l6 at 18 range 0 .. 71;
end record;
The Size values are actually the Object_Size, i.e., the default size that
will be allocated for objects of the type.
The ``??`` size for type r indicates that we have a variant record, and the

8
gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
View File

@ -4676,8 +4676,12 @@ checks to be performed. The following checks are defined:
:samp:`-gnatyO`
*Check that overriding subprograms are explicitly marked as such.*
The declaration of a primitive operation of a type extension that overrides
an inherited operation must carry an overriding indicator.
This applies to all subprograms of a derived type that override a primitive
operation of the type, for both tagged and untagged types. In particular,
the declaration of a primitive operation of a type extension that overrides
an inherited operation must carry an overriding indicator. Another case is
the declaration of a function that overrides a predefined operator (such
as an equality operator).
.. index:: -gnatyp (gcc)

140
gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
View File

@ -57,7 +57,7 @@ The `gnatclean` command has the form:
::
$ gnatclean switches `names`
where `names` is a list of source file names. Suffixes :file:`.ads` and
:file:`adb` may be omitted. If a project file is specified using switch
:samp:`-P`, then `names` may be completely omitted.
@ -465,7 +465,7 @@ building specialized scripts.
/home/comar/local/adainclude/s-tasoli.ads
/home/comar/local/adainclude/s-unstyp.ads
/home/comar/local/adainclude/unchconv.ads
.. _The_Cross-Referencing_Tools_gnatxref_and_gnatfind:
@ -511,7 +511,7 @@ The command invocation for `gnatxref` is:
::
$ gnatxref [`switches`] `sourcefile1` [`sourcefile2` ...]
where
*sourcefile1* [, *sourcefile2* ...]
@ -939,7 +939,7 @@ account.
[default: `""`].
Specifies the name of the executable for the application. This variable can
be referred to in the following lines by using the :samp:`{${main}` notation.
* *comp_cmd=COMMAND*
[default: `"gcc -c -I${src_dir} -g -gnatq"`].
@ -1002,14 +1002,14 @@ are recognized:
::
regexp ::= term {| term} -- alternation (term or term ...)
term ::= item {item} -- concatenation (item then item)
item ::= elmt -- match elmt
item ::= elmt * -- zero or more elmt's
item ::= elmt + -- one or more elmt's
item ::= elmt ? -- matches elmt or nothing
elmt ::= nschar -- matches given character
elmt ::= [nschar {nschar}] -- matches any character listed
elmt ::= [^ nschar {nschar}] -- matches any character not listed
@ -1020,7 +1020,7 @@ are recognized:
char ::= any character, including special characters
nschar ::= any character except ()[].*+?^
Here are a few examples:
``abcde|fghi``
@ -1111,7 +1111,7 @@ You can then issue any of the following commands:
Print Type: Unit
Decl: bar.ads 2:15
Ref: main.adb 6:12 7:12
This shows that the entity `Main` is declared in main.ads, line 2, column 9,
its body is in main.adb, line 1, column 14 and is not referenced any where.
@ -1137,7 +1137,7 @@ free implementation of *vi*, such as *vim*.
::
$ gnatxref -v gnatfind.adb > tags
The following command will generate the tags file for `gnatfind` itself
(if the sources are in the search path!):
@ -1145,7 +1145,7 @@ The following command will generate the tags file for `gnatfind` itself
::
$ gnatxref -v gnatfind.adb > tags
From *vi*, you can then use the command :samp:`:tag {entity}`
(replacing `entity` by whatever you are looking for), and vi will
display a new file with the corresponding declaration of entity.
@ -1171,7 +1171,7 @@ Examples of `gnatfind` Usage
directory/main.ads:106:14: xyz <= declaration
directory/main.adb:24:10: xyz <= body
directory/foo.ads:45:23: xyz <= declaration
I.e., one of the entities xyz found in main.adb is declared at
line 12 of main.ads (and its body is in main.adb), and another one is
declared at line 45 of foo.ads
@ -1190,7 +1190,7 @@ Examples of `gnatfind` Usage
procedure xyz is
directory/foo.ads:45:23: xyz <= declaration
xyz : Integer;
This can make it easier to find exactly the location your are looking
for.
@ -1352,13 +1352,13 @@ is located. The syntax of this line is:
::
#!full_path_name_to_perl
Alternatively, you may run the script using the following command line:
::
$ perl gnathtml.pl [`switches`] `files`
@ -1392,7 +1392,7 @@ Alternatively, you may run the script using the following command line:
::
$ gnat2xml [options] filenames [-files filename] [-cargs gcc_switches]
Options:
:samp:`--help`
@ -1409,7 +1409,7 @@ Alternatively, you may run the script using the following command line:
the set of sources to be processed. The exact set of argument
sources depends on other options specified, see below.
:samp:`-U`
:samp:`-U`
If a project file is specified and no argument source is explicitly
specified, process all the units of the closure of the argument project.
Otherwise this option has no effect.
@ -1420,7 +1420,7 @@ Alternatively, you may run the script using the following command line:
option), process the closure of units rooted at `main_unit`.
Otherwise this option has no effect.
:samp:`-X{name}={value}`
:samp:`-X{name}={value}`
Indicates that external variable `name` in
the argument project has the value `value`. Has no effect if no
project is specified as tool argument.
@ -1437,7 +1437,7 @@ Alternatively, you may run the script using the following command line:
only compiles files that need to be recompiled. A project file
is required in this mode.
:samp:`-j{n}`
:samp:`-j{n}`
In *--incremental* mode, use `n` *gnat2xml*
processes to perform XML generation in parallel. If `n` is 0, then
the maximum number of parallel tree creations is the number of core
@ -1452,7 +1452,7 @@ Alternatively, you may run the script using the following command line:
Directories to search for dependencies.
You can also set the ADA_INCLUDE_PATH environment variable for this.
:samp:`--compact`
:samp:`--compact`
Debugging version, with interspersed source, and a more
compact representation of "sloc". This version does not conform
to any schema.
@ -1463,15 +1463,15 @@ Alternatively, you may run the script using the following command line:
:samp:`-files={filename}`
The name of a text file containing a list of Ada source files to process
:samp:`-q`
:samp:`-q`
Quiet
:samp:`-v`
:samp:`-v`
Verbose
:samp:`-cargs` ...
:samp:`-cargs` ...
Options to pass to gcc
If a project file is specified and no argument source is explicitly
specified, and no *-U* is specified, then the set of processed
sources is all the immediate units of the argument project.
@ -1481,7 +1481,7 @@ Alternatively, you may run the script using the following command line:
::
$ gnat2xml -v -output-dir=xml-files *.ad[sb]
The above will create \*.xml files in the :file:`xml-files` subdirectory.
For example, if there is an Ada package Mumble.Dumble, whose spec and
body source code lives in mumble-dumble.ads and mumble-dumble.adb,
@ -1505,7 +1505,7 @@ Alternatively, you may run the script using the following command line:
::
$ gnat2xsd > ada-schema.xsd
*gnat2xml* generates XML files that will validate against
:file:`ada-schema.xsd`.
@ -1549,7 +1549,7 @@ Alternatively, you may run the script using the following command line:
type T is range 1..10;
X, Y : constant T := 1;
The first 'T' is the defining occurrence of a type. The 'X' is the
defining occurrence of a constant, as is the 'Y', and the second 'T' is
@ -1577,14 +1577,14 @@ Alternatively, you may run the script using the following command line:
...
-- Returns Element_Kinds:
-- An_Expression
The corresponding sub-element of type Assignment_Statement is:
::
<xsd:element name="assignment_expression_q" type="Expression_Class"/>
where Expression_Class is defined by an xsd:choice of all the
various kinds of expression.
@ -1774,7 +1774,7 @@ Alternatively, you may run the script using the following command line:
formal_function
formal_package
formal_package_declaration_with_box
.. _Generating_Representation_Clauses:
Generating Representation Clauses
@ -1808,7 +1808,7 @@ Alternatively, you may run the script using the following command line:
...
<comment text="--gen-">
...
.. only:: PRO or GPL
@ -2194,7 +2194,7 @@ Alternatively, you may run the script using the following command line:
* *Maximal static nesting level of inner program units*
According to :title:`Ada Reference Manual`, 10.1(1):
"A program unit is either a package, a task unit, a protected unit, a
protected entry, a generic unit, or an explicitly declared subprogram other
than an enumeration literal."
@ -2619,7 +2619,7 @@ Alternatively, you may run the script using the following command line:
return F_1 (I);
end Fun;
end Pack;
If we apply *gnatmetric* with the *--coupling-all* option to
these units, the result will be:
@ -2852,11 +2852,6 @@ Alternatively, you may run the script using the following command line:
You can specify various style directives via switches; e.g.,
identifier case conventions, rules of indentation, and comment layout.
Note: A newly-redesigned set of formatting algorithms used by gnatpp
is now available.
To invoke the old formatting algorithms, use the ``--pp-old`` switch.
Support for ``--pp-old`` will be removed in some future version.
To produce a reformatted file, *gnatpp* invokes the Ada
compiler and generates and uses the ASIS tree for the input source;
thus the input must be legal Ada code, and the tool should have all the
@ -2875,7 +2870,7 @@ Alternatively, you may run the script using the following command line:
::
$ gnatpp [`switches`] `filename` [-cargs `gcc_switches`]
where
* `switches` is an optional sequence of switches defining such properties as
@ -3499,12 +3494,6 @@ Alternatively, you may run the script using the following command line:
of the default `--!pp on`.
.. index:: --pp-old (gnatpp)
:samp:`--pp-old`
Use the old formatting algorithms.
.. index:: -files (gnatpp)
:samp:`-files {filename}`
@ -3597,12 +3586,12 @@ Alternatively, you may run the script using the following command line:
Green_Interrupt_Kind);
--!pp on -- reenable pretty printing
...
You can specify different comment strings using the ``--pp-off``
and ``--pp-on`` switches. For example, if you say:
::
$ gnatpp --pp-off=' pp-' *.ad?
then gnatpp will recognize comments of the form
@ -3765,7 +3754,7 @@ Alternatively, you may run the script using the following command line:
`casing_schema` ::= `identifier` | `simple_identifier`
`simple_identifier` ::= `letter`{`letter_or_digit`}
(See :title:`Ada Reference Manual`, Section 2.3) for the definition of the
`identifier` lexical element and the `letter_or_digit` category.)
@ -3804,7 +3793,7 @@ Alternatively, you may run the script using the following command line:
For example, suppose we have the following source to reformat:
.. code-block:: ada
procedure test is
name1 : integer := 1;
name4_name3_name2 : integer := 2;
@ -3813,7 +3802,7 @@ Alternatively, you may run the script using the following command line:
begin
name2_name3_name4 := name4_name3_name2 > name1;
end;
And suppose we have two dictionaries:
::
@ -3825,13 +3814,13 @@ Alternatively, you may run the script using the following command line:
*dict2:*
*NAME3*
If *gnatpp* is called with the following switches:
::
$ gnatpp -nM -D dict1 -D dict2 test.adb
then we will get the following name casing in the *gnatpp* output:
@ -3885,13 +3874,13 @@ Alternatively, you may run the script using the following command line:
Running *gnatstub*
------------------
*gnatstub* invocation has the following form:
::
$ gnatstub [`switches`] `filename` [-cargs `gcc_switches`]
where
* *filename*
@ -3912,7 +3901,7 @@ Alternatively, you may run the script using the following command line:
or creates the name file to generate using the standard GNAT
naming conventions.
* *gcc_switches* is a list of switches for *gcc*.
* *gcc_switches* is a list of switches for *gcc*.
They will be passed on to all compiler invocations made by
*gnatstub* to generate the ASIS trees. Here you can provide
``-I`` switches to form the source search path,
@ -4212,7 +4201,7 @@ Alternatively, you may run the script using the following command line:
::
$ gnattest `-Pprojname` [`--harness-dir=dirname`] [`switches`] [`filename`] [-cargs `gcc_switches`]
where
* :samp:`-P{projname}`
@ -4281,7 +4270,7 @@ Alternatively, you may run the script using the following command line:
::
$ gnattest `test_drivers.list` [`switches`]
where
* :samp:`{test_drivers.list}`
@ -4557,15 +4546,15 @@ Alternatively, you may run the script using the following command line:
located in:
::
<install_prefix>/share/examples/gnattest/simple
This project contains a simple package containing one subprogram. By running gnattest:
::
$ gnattest --harness-dir=driver -Psimple.gpr
a test driver is created in directory ``driver``. It can be compiled and run:
::
@ -4573,7 +4562,7 @@ Alternatively, you may run the script using the following command line:
$ cd obj/driver
$ gnatmake -Ptest_driver
$ test_runner
One failed test with diagnosis ``test not implemented`` is reported.
Since no special output option was specified, the test package ``Simple.Tests``
is located in:
@ -4581,7 +4570,7 @@ Alternatively, you may run the script using the following command line:
::
<install_prefix>/share/examples/gnattest/simple/obj/gnattest/tests
For each package containing visible subprograms, a child test package is
generated. It contains one test routine per tested subprogram. Each
@ -4601,7 +4590,7 @@ Alternatively, you may run the script using the following command line:
::
Assert (Inc (1) = 2, "wrong incrementation");
After recompiling and running the test driver, one successfully passed test
is reported.
@ -4642,7 +4631,7 @@ Alternatively, you may run the script using the following command line:
$ cd obj/driver
$ gnatmake -Ptest_driver
$ test_runner
The old test is not replaced with a stub, nor is it lost, but a new test
skeleton is created for function Dec.
@ -4668,11 +4657,11 @@ Alternatively, you may run the script using the following command line:
as passed to gnattest when generating the test driver.
Passing it to the driver generated on the first example:
::
$ test_runner --skeleton-default=pass
makes both tests pass, even the unimplemented one.
@ -4695,7 +4684,7 @@ Alternatively, you may run the script using the following command line:
$ cd <install_prefix>/share/examples/gnattest/tagged_rec
$ gnattest --harness-dir=driver -Ptagged_rec.gpr
Taking a closer look at the test type declared in the test package
Speed1.Controller_Test_Data is necessary. It is declared in:
@ -4741,7 +4730,7 @@ Alternatively, you may run the script using the following command line:
$ cd obj/driver
$ gnatmake -Ptest_driver
$ test_runner
There are 6 passed tests while there are only 5 testable subprograms. The test
routine for function Speed has been inherited and run against objects of the
derived type.
@ -4784,7 +4773,7 @@ Alternatively, you may run the script using the following command line:
$ cd obj/driver
$ gnatmake -Ptest_driver
$ test_runner
While all the tests pass by themselves, the parent test for Adjust_Speed fails
against objects of the derived type.
@ -4812,7 +4801,7 @@ Alternatively, you may run the script using the following command line:
$ cd <install_prefix>/share/examples/gnattest/contracts
$ gnattest --harness-dir=driver -Pcontracts.gpr
Putting actual checks within the range of the contract does not cause any
error reports. For example, for the test routine which corresponds to
test case 1:
@ -4820,7 +4809,7 @@ Alternatively, you may run the script using the following command line:
::
Assert (Sqrt (9.0) = 3.0, "wrong sqrt");
and for the test routine corresponding to test case 2:
::
@ -4834,7 +4823,7 @@ Alternatively, you may run the script using the following command line:
$ cd obj/driver
$ gnatmake -Ptest_driver
$ test_runner
However, by changing 9.0 to 25.0 and 3.0 to 5.0, for example, you can get
a precondition violation for test case one. Also, by using any otherwise
correct but positive pair of numbers in the second test routine, you can also
@ -4861,7 +4850,7 @@ Alternatively, you may run the script using the following command line:
::
<install_prefix>/share/examples/gnattest/additional_tests/
To create a test driver for already-written tests, use the ``--harness-only``
option:
@ -4871,7 +4860,7 @@ Alternatively, you may run the script using the following command line:
--harness-only
gnatmake -Pharness_only/test_driver.gpr
harness_only/test_runner
Additional tests can also be executed together with generated tests:
::
@ -4983,7 +4972,7 @@ Alternatively, you may run the script using the following command line:
::
$ powerpc-elf-gnattest -Psimple.gpr -XPLATFORM=powerpc-elf -XRUNTIME=zfp
.. _Current_Limitations:
@ -4994,4 +4983,5 @@ Alternatively, you may run the script using the following command line:
* generic tests for nested generic packages and their instantiations
* tests for protected subprograms and entries
* if pragmas for C and C++ interaction are used, manual adjustments might be
necessary to make the test driver compilable

1397
gcc/ada/gnat_rm.texi
View File

File diff suppressed because it is too large Load Diff

10
gcc/ada/gnat_ugn.texi
View File

@ -21,7 +21,7 @@
@copying
@quotation
GNAT User's Guide for Native Platforms , March 01, 2015
GNAT User's Guide for Native Platforms , March 24, 2015
AdaCore
@ -13300,8 +13300,12 @@ before Junk10).
@emph{Check that overriding subprograms are explicitly marked as such.}
The declaration of a primitive operation of a type extension that overrides
an inherited operation must carry an overriding indicator.
This applies to all subprograms of a derived type that override a primitive
operation of the type, for both tagged and untagged types. In particular,
the declaration of a primitive operation of a type extension that overrides
an inherited operation must carry an overriding indicator. Another case is
the declaration of a function that overrides a predefined operator (such
as an equality operator).
@end table
@geindex -gnatyp (gcc)