mirror/gcc
2
0
Fork 0
mirror of git://gcc.gnu.org/git/gcc.git synced 2025-03-24 04:10:29 +08:00
Code Issues Packages Projects Releases Wiki Activity

getting_started_with_gnat.rst, [...]: Update documentation.

Browse Source 
* doc/gnat_ugn/getting_started_with_gnat.rst,
	doc/gnat_ugn/inline_assembler.rst,
	doc/gnat_ugn/building_executable_programs_with_gnat.rst,
	doc/gnat_ugn/elaboration_order_handling_in_gnat.rst,
	doc/gnat_ugn/about_this_guide.rst,
	doc/gnat_ugn/platform_specific_information.rst,
	doc/gnat_ugn/example_of_binder_output.rst,
	doc/gnat_ugn/gnat_and_program_execution.rst,
	doc/gnat_ugn/gnat_utility_programs.rst,
	doc/gnat_ugn/the_gnat_compilation_model.rst,
	doc/gnat_rm/implementation_defined_attributes.rst,
	doc/gnat_rm/compatibility_and_porting_guide.rst,
	doc/gnat_rm/standard_library_routines.rst,
	doc/gnat_rm/standard_and_implementation_defined_restrictions.rst,
	doc/gnat_rm/implementation_defined_pragmas.rst,
	doc/gnat_rm/the_gnat_library.rst,
	doc/gnat_rm/obsolescent_features.rst,
	doc/gnat_rm/about_this_guide.rst,
	doc/gnat_rm/the_implementation_of_standard_i_o.rst,
	doc/gnat_rm/implementation_of_ada_2012_features.rst,
	doc/gnat_rm/interfacing_to_other_languages.rst,
	doc/gnat_rm/implementation_defined_aspects.rst,
	doc/gnat_rm.rst: Update documentation.
	* gnat_rm.texi, gnat_ugn.texi: Regenerated.

From-SVN: r244426
This commit is contained in:
Arnaud Charlet 2017-01-13 11:23:42 +00:00 committed by Arnaud Charlet
parent b5f3c91301
commit 33c51287cd
26 changed files with 1724 additions and 1300 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
gcc/ada/ChangeLog
View File

@ -1,3 +1,30 @@
2017-01-13 Arnaud Charlet <charlet@adacore.com>
* doc/gnat_ugn/getting_started_with_gnat.rst,
doc/gnat_ugn/inline_assembler.rst,
doc/gnat_ugn/building_executable_programs_with_gnat.rst,
doc/gnat_ugn/elaboration_order_handling_in_gnat.rst,
doc/gnat_ugn/about_this_guide.rst,
doc/gnat_ugn/platform_specific_information.rst,
doc/gnat_ugn/example_of_binder_output.rst,
doc/gnat_ugn/gnat_and_program_execution.rst,
doc/gnat_ugn/gnat_utility_programs.rst,
doc/gnat_ugn/the_gnat_compilation_model.rst,
doc/gnat_rm/implementation_defined_attributes.rst,
doc/gnat_rm/compatibility_and_porting_guide.rst,
doc/gnat_rm/standard_library_routines.rst,
doc/gnat_rm/standard_and_implementation_defined_restrictions.rst,
doc/gnat_rm/implementation_defined_pragmas.rst,
doc/gnat_rm/the_gnat_library.rst,
doc/gnat_rm/obsolescent_features.rst,
doc/gnat_rm/about_this_guide.rst,
doc/gnat_rm/the_implementation_of_standard_i_o.rst,
doc/gnat_rm/implementation_of_ada_2012_features.rst,
doc/gnat_rm/interfacing_to_other_languages.rst,
doc/gnat_rm/implementation_defined_aspects.rst,
doc/gnat_rm.rst: Update documentation.
* gnat_rm.texi, gnat_ugn.texi: Regenerated.
2017-01-13 Ed Schonberg <schonberg@adacore.com>
* einfo.ads: minor grammar fixes in comment of Normalized_Position_Max.

12
gcc/ada/doc/gnat_rm.rst
View File

@ -4,23 +4,23 @@ GNAT Reference Manual
*GNAT, The GNU Ada Development Environment*
.. only:: PRO
*GNAT Pro Edition*
| Version |version|
| Date: |today|
.. only:: GPL
*GNAT GPL Edition*
| Version |version|
| Date: |today|
.. only:: FSF
.. raw:: texinfo
@include gcc-common.texi
GCC version @value{version-GCC}@*

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

@ -114,7 +114,7 @@ This reference manual contains the following chapters:
.. index:: Ada 2005 Language Reference Manual
This reference manual assumes a basic familiarity with the Ada 95 language, as
described in the
described in the
:title:`International Standard ANSI/ISO/IEC-8652:1995`.
It does not require knowledge of the new features introduced by Ada 2005 or
Ada 2012.
@ -148,10 +148,10 @@ in this guide:
::
and then shown this way.
* Commands that are entered by the user are shown as preceded by a prompt string
comprising the ``$`` character followed by a space.
Related Information
===================

25
gcc/ada/doc/gnat_rm/compatibility_and_porting_guide.rst
View File

@ -22,7 +22,7 @@ For example, if we write
.. code-block:: ada
type F1 is delta 1.0 range -128.0 .. +128.0;
then the implementation is allowed to choose -128.0 .. +127.0 if it
likes, but is not required to do so.
@ -45,7 +45,7 @@ representation. Let's take another example:
.. code-block:: ada
type F2 is delta 2.0**(-15) range -1.0 .. +1.0;
Looking at this declaration, it seems casually as though
it should fit in 16 bits, but again that extra positive value
+1.0 has the scaled integer equivalent of 2**15 which is one too
@ -54,7 +54,7 @@ big for signed 16 bits. The implementation can treat this as:
.. code-block:: ada
type F2 is delta 2.0**(-15) range -1.0 .. +1.0-(2.0**(-15));
and the Ada language design team felt that this was too annoying
to require. We don't need to debate this decision at this point,
since it is well established (the rule about narrowing the ranges
@ -77,14 +77,14 @@ approach: to narrow all the time, e.g. to treat
.. code-block:: ada
type F3 is delta 1.0 range -10.0 .. +23.0;
as though it had been written:
.. code-block:: ada
type F3 is delta 1.0 range -9.0 .. +22.0;
But although technically allowed, such a behavior would be hostile and silly,
and no real compiler would do this. All real compilers will fall into one of
the categories (a), (b) or (c) above.
@ -101,14 +101,14 @@ E.g., for `F2` above, we will write:
My_Last : constant := +1.0 - My_Small;
type F2 is delta My_Small range My_First .. My_Last;
and then add
.. code-block:: ada
for F2'Small use my_Small;
for F2'Size use 16;
In practice all compilers will do the same thing here and will give you
what you want, so the above declarations are fully portable. If you really
want to play language lawyer and guard against ludicrous behavior by the
@ -118,7 +118,7 @@ compiler you could add
Test1 : constant := 1 / Boolean'Pos (F2'First = My_First);
Test2 : constant := 1 / Boolean'Pos (F2'Last = My_Last);
One or other or both are allowed to be illegal if the compiler is
behaving in a silly manner, but at least the silly compiler will not
get away with silently messing with your (very clear) intentions.
@ -176,7 +176,7 @@ Ada 95 and later versions of the standard:
.. code-block:: ada
for Char in Character range 'A' .. 'Z' loop ... end loop;
* *New reserved words*
The identifiers `abstract`, `aliased`, `protected`,
@ -368,7 +368,7 @@ for a complete description please see the
Rule changes in this area have led to some incompatibilities; for example,
constrained subtypes of some access types are not permitted in Ada 2005.
* *Aggregates for limited types.*
The allowance of aggregates for limited types in Ada 2005 raises the
@ -517,7 +517,7 @@ Compatibility with Other Ada Systems
====================================
If programs avoid the use of implementation dependent and
implementation defined features, as documented in the
implementation defined features, as documented in the
:title:`Ada Reference Manual`, there should be a high degree of portability between
GNAT and other Ada systems. The following are specific items which
have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95
@ -618,7 +618,7 @@ the cases most likely to arise in existing Ada 83 code.
type X is access all String;
for X'Size use Standard'Address_Size;
which will cause the type X to be represented using a single pointer.
When using this representation, the bounds are right behind the array.
This representation is slightly less efficient, and does not allow quite
@ -658,4 +658,3 @@ applicable to GNAT.
that contains the additional definitions, and a special pragma,
Extend_System allows this package to be treated transparently as an
extension of package System.

15
gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst
View File

@ -359,6 +359,13 @@ Aspect Lock_Free
This boolean aspect is equivalent to :ref:`pragma Lock_Free<Pragma-Lock_Free>`.
Aspect Max_Queue_Length
=======================
.. index:: Max_Queue_Length
This aspect is equivalent to :ref:`pragma Max_Queue_Length<Pragma-Max_Queue_Length>`.
Aspect No_Elaboration_Code_All
==============================
.. index:: No_Elaboration_Code_All
@ -447,6 +454,14 @@ Aspect Remote_Access_Type
This aspect is equivalent to :ref:`pragma Remote_Access_Type<Pragma-Remote_Access_Type>`.
Aspect Secondary_Stack_Size
===========================
.. index:: Secondary_Stack_Size
This aspect is equivalent to :ref:`pragma Secondary_Stack_Size<Pragma-Secondary_Stack_Size>`.
Aspect Scalar_Storage_Order
===========================
.. index:: Scalar_Storage_Order

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

@ -404,6 +404,21 @@ Attribute Fast_Math
prefix) yields a static Boolean value that is True if pragma
`Fast_Math` is active, and False otherwise.
Attribute Finalization_Size
===========================
.. index:: Finalization_Size
The prefix of attribute `Finalization_Size` must be an object or
a non-class-wide type. This attribute returns the size of any hidden data
reserved by the compiler to handle finalization-related actions. The type of
the attribute is `universal_integer`.
`Finalization_Size` yields a value of zero for a type with no controlled
parts, an object whose type has no controlled parts, or an object of a
class-wide type whose tag denotes a type with no controlled parts.
Note that only heap-allocated objects contain finalization data.
Attribute Fixed_Value
=====================
.. index:: Fixed_Value

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

@ -427,7 +427,7 @@ Syntax::
Refined_Post |
Statement_Assertions
POLICY_IDENTIFIER ::= Check | Disable | Ignore
POLICY_IDENTIFIER ::= Check | Disable | Ignore | Suppressible
This is a standard Ada 2012 pragma that is available as an
@ -450,6 +450,8 @@ If the policy is `IGNORE`, then assertions are ignored, i.e.
the corresponding pragma or aspect is deactivated.
This pragma overrides the effect of the *-gnata* switch on the
command line.
If the policy is `SUPPRESSIBLE`, then assertions are enabled by default,
however, if the *-gnatp* switch is specified all assertions are ignored.
The implementation defined policy `DISABLE` is like
`IGNORE` except that it completely disables semantic
@ -2381,7 +2383,7 @@ Syntax:
pragma Implementation_Defined (local_NAME);
This pragma marks a previously declared entioty as implementation-defined.
This pragma marks a previously declared entity as implementation-defined.
For an overloaded entity, applies to the most recent homonym.
@ -3561,6 +3563,19 @@ Syntax::
This pragma is provided for compatibility with OpenVMS VAX Systems. It has
no effect in GNAT, other than being syntax checked.
Pragma Max_Queue_Length
=======================
Syntax::
pragma Max_Entry_Queue (static_integer_EXPRESSION);
This pragma is used to specify the maximum callers per entry queue for
individual protected entries and entry families. It accepts a single
positive integer as a parameter and must appear after the declaration
of an entry.
Pragma No_Body
==============
@ -4530,6 +4545,43 @@ aspects, but is prepared to ignore the pragmas. The assertion
policy that controls this pragma is `Post'Class`, not
`Post_Class`.
Pragma Rename_Pragma
============================
.. index:: Pragmas, synonyms
Syntax:
::
pragma Rename_Pragma (
[New_Name =>] IDENTIFIER,
[Renamed =>] pragma_IDENTIFIER);
This pragma provides a mechanism for supplying new names for existing
pragmas. The `New_Name` identifier can subsequently be used as a synonym for
the Renamed pragma. For example, suppose you have code that was originally
developed on a compiler that supports Inline_Only as an implementation defined
pragma. And suppose the semantics of pragma Inline_Only are identical to (or at
least very similar to) the GNAT implementation defined pragma
Inline_Always. You could globally replace Inline_Only with Inline_Always.
However, to avoid that source modification, you could instead add a
configuration pragma:
.. code-block:: ada
pragma Rename_Pragma (
New_Name => Inline_Only,
Renamed => Inline_Always);
Then GNAT will treat "pragma Inline_Only ..." as if you had written
"pragma Inline_Always ...".
Pragma Inline_Only will not necessarily mean the same thing as the other Ada
compiler; it's up to you to make sure the semantics are close enough.
Pragma Pre
==========
.. index:: Pre
@ -4937,6 +4989,9 @@ is defined in the following sections.
The ``Simple_Barriers`` restriction has been replaced by
``Pure_Barriers``.
The ``Max_Protected_Entries``, ``Max_Entry_Queue_Length``, and
``No_Relative_Delay`` restrictions have been removed.
* Pragma Profile (Restricted)
This profile corresponds to the GNAT restricted run time. It
@ -5470,6 +5525,41 @@ run with various special switches as follows:
comprehensive messages identifying possible problems based on this
information.
.. _Pragma-Secondary_Stack_Size:
Pragma Secondary_Stack_Size
===========================
Syntax:
.. code-block:: ada
pragma Secondary_Stack_Size (integer_EXPRESSION);
This pragma appears within the task definition of a single task declaration
or a task type declaration (like pragma `Storage_Size`) and applies to all
task objects of that type. The argument specifies the size of the secondary
stack to be used by these task objects, and must be of an integer type. The
secondary stack is used to handle functions that return a variable-sized
result, for example a function returning an unconstrained String.
Note this pragma only applies to targets using fixed secondary stacks, like
VxWorks 653 and bare board targets, where a fixed block for the
secondary stack is allocated from the primary stack of the task. By default,
these targets assign a percentage of the primary stack for the secondary stack,
as defined by `System.Parameter.Sec_Stack_Percentage`. With this pragma,
an `integer_EXPRESSION` of bytes is assigned from the primary stack instead.
For most targets, the pragma does not apply as the secondary stack grows on
demand: allocated as a chain of blocks in the heap. The default size of these
blocks can be modified via the `-D` binder option as described in
:title:`GNAT User's Guide`.
Note that no check is made to see if the secondary stack can fit inside the
primary stack.
Note the pragma cannot appear when the restriction `No_Secondary_Stack`
is in effect.
Pragma Share_Generic
====================
@ -6853,7 +6943,7 @@ variables whose name contains one of the substrings
`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names
are typically to be used in cases where such warnings are expected.
Thus it is never necessary to use `pragma Unmodified` for such
variables, though it is harmless to do so.
variables, though it is harmless to do so.
Pragma Validity_Checks
======================

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

@ -114,48 +114,48 @@ Supported Aspect Source
================================== ===========
`Ada_2005` -- GNAT
`Ada_2012` -- GNAT
`Address`
`Alignment`
`Atomic`
`Atomic_Components`
`Bit_Order`
`Component_Size`
`Address`
`Alignment`
`Atomic`
`Atomic_Components`
`Bit_Order`
`Component_Size`
`Contract_Cases` -- GNAT
`Discard_Names`
`External_Tag`
`Discard_Names`
`External_Tag`
`Favor_Top_Level` -- GNAT
`Inline`
`Inline`
`Inline_Always` -- GNAT
`Invariant` -- GNAT
`Machine_Radix`
`No_Return`
`Machine_Radix`
`No_Return`
`Object_Size` -- GNAT
`Pack`
`Pack`
`Persistent_BSS` -- GNAT
`Post`
`Pre`
`Predicate`
`Preelaborable_Initialization`
`Post`
`Pre`
`Predicate`
`Preelaborable_Initialization`
`Pure_Function` -- GNAT
`Remote_Access_Type` -- GNAT
`Shared` -- GNAT
`Size`
`Storage_Pool`
`Storage_Size`
`Stream_Size`
`Suppress`
`Size`
`Storage_Pool`
`Storage_Size`
`Stream_Size`
`Suppress`
`Suppress_Debug_Info` -- GNAT
`Test_Case` -- GNAT
`Thread_Local_Storage` -- GNAT
`Type_Invariant`
`Unchecked_Union`
`Type_Invariant`
`Unchecked_Union`
`Universal_Aliasing` -- GNAT
`Unmodified` -- GNAT
`Unreferenced` -- GNAT
`Unreferenced_Objects` -- GNAT
`Unsuppress`
`Unsuppress`
`Value_Size` -- GNAT
`Volatile`
`Volatile`
`Volatile_Components`
`Warnings` -- GNAT
================================== ===========
@ -436,7 +436,7 @@ Supported Aspect Source
::
(if expr then expr {elsif expr then expr} [else expr])
The parentheses can be omitted in contexts where parentheses are present
anyway, such as subprogram arguments and pragma arguments. If the **else**
clause is omitted, **else** *True* is assumed;
@ -500,7 +500,7 @@ Supported Aspect Source
.. code-block:: ada
X := (case Y is when 1 => 2, when 2 => 3, when others => 31)
RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33)
.. index:: AI-0104 (Ada 2012 feature)

17
gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst
View File

@ -15,9 +15,9 @@ Interfacing to C
Interfacing to C with GNAT can use one of two approaches:
*
*
The types in the package `Interfaces.C` may be used.
*
*
Standard Ada types may be used directly. This may be less portable to
other compilers, but will work on all GNAT compilers, which guarantee
correspondence between the C and Ada types.
@ -44,7 +44,7 @@ Ada Type C Type
Additionally, there are the following general correspondences between Ada
and C types:
*
*
Ada enumeration types map to C enumeration types directly if pragma
`Convention C` is specified, which causes them to have int
length. Without pragma `Convention C`, Ada enumeration types map to
@ -53,17 +53,17 @@ and C types:
This is the only case in which pragma `Convention C` affects the
representation of an Ada type.
*
*
Ada access types map to C pointers, except for the case of pointers to
unconstrained types in Ada, which have no direct C equivalent.
*
*
Ada arrays map directly to C arrays.
*
*
Ada records map directly to C structures.
*
*
Packed Ada records map to C structures where all members are bit fields
of the length corresponding to the ``type'Size`` value in Ada.
@ -116,7 +116,7 @@ It is also possible to import a C++ exception using the following syntax:
pragma Import (Cpp,
[Entity =>] LOCAL_NAME,
[External_Name =>] static_string_EXPRESSION);
The `External_Name` is the name of the C++ RTTI symbol. You can then
cover a specific C++ exception in an exception handler.
@ -162,4 +162,3 @@ case in which it is possible to import foreign units of this type,
provided that the data items passed are restricted to simple scalar
values or simple record types without variants, or simple array
types with fixed bounds.

2
gcc/ada/doc/gnat_rm/obsolescent_features.rst
View File

@ -56,7 +56,7 @@ Syntax
.. code-block:: ada
pragma Task_Info (EXPRESSION);
This pragma appears within a task definition (like pragma
`Priority`) and applies to the task in which it appears. The
argument must be of type `System.Task_Info.Task_Info_Type`.

3
gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst
View File

@ -584,7 +584,8 @@ No_Secondary_Stack
[GNAT] This restriction ensures at compile time that the generated code
does not contain any reference to the secondary stack. The secondary
stack is used to implement functions returning unconstrained objects
(arrays or records) on some targets.
(arrays or records) on some targets. Suppresses the allocation of
secondary stacks for tasks (excluding the environment task) at run time.
No_Select_Statements
--------------------

3
gcc/ada/doc/gnat_rm/standard_library_routines.rst
View File

@ -317,7 +317,7 @@ the unit is not implemented.
The following predefined instantiations of this package are provided:
* ``Short_Float``
`Ada.Numerics.Short_Complex_Elementary_Functions`
* ``Float``
@ -706,4 +706,3 @@ the unit is not implemented.
For packages in Interfaces and System, all the RM defined packages are
available in GNAT, see the Ada 2012 RM for full details.

15
gcc/ada/doc/gnat_rm/the_gnat_library.rst
View File

@ -1996,6 +1996,21 @@ This package provides a limited binding to the VxWorks API.
In particular, it interfaces with the
VxWorks hardware interrupt facilities.
.. _`Interfaces.VxWorks.Int_Connection_(i-vxinco.ads)`:
`Interfaces.VxWorks.Int_Connection` (:file:`i-vxinco.ads`)
==========================================================
.. index:: Interfaces.VxWorks.Int_Connection (i-vxinco.ads)
.. index:: Interfacing to VxWorks
.. index:: VxWorks, interfacing
This package provides a way for users to replace the use of
intConnect() with a custom routine for installing interrupt
handlers.
.. _`Interfaces.VxWorks.IO_(i-vxwoio.ads)`:
`Interfaces.VxWorks.IO` (:file:`i-vxwoio.ads`)

111
gcc/ada/doc/gnat_rm/the_implementation_of_standard_i_o.rst
View File

@ -39,37 +39,37 @@ Standard I/O Packages
The Standard I/O packages described in Annex A for
*
*
Ada.Text_IO
*
*
Ada.Text_IO.Complex_IO
*
*
Ada.Text_IO.Text_Streams
*
*
Ada.Wide_Text_IO
*
*
Ada.Wide_Text_IO.Complex_IO
*
*
Ada.Wide_Text_IO.Text_Streams
*
*
Ada.Wide_Wide_Text_IO
*
*
Ada.Wide_Wide_Text_IO.Complex_IO
*
*
Ada.Wide_Wide_Text_IO.Text_Streams
*
*
Ada.Stream_IO
*
*
Ada.Sequential_IO
*
*
Ada.Direct_IO
are implemented using the C
library streams facility; where
*
*
All files are opened using `fopen`.
*
*
All input/output operations use `fread`/`fwrite`.
There is no internal buffering of any kind at the Ada library level. The only
@ -94,7 +94,7 @@ The format of a FORM string in GNAT is:
::
"keyword=value,keyword=value,...,keyword=value"
where letters may be in upper or lower case, and there are no spaces
between values. The order of the entries is not important. Currently
@ -107,7 +107,7 @@ the following keywords defined.
SHARED=[YES|NO]
WCEM=[n|h|u|s|e|8|b]
ENCODING=[UTF8|8BITS]
The use of these parameters is described later in this section. If an
unrecognized keyword appears in a form string, it is silently ignored
@ -173,7 +173,7 @@ arrays. For example, the following will raise `Data_Error`:
IO.Read (F, S);
Put_Line (S);
On some Ada implementations, this will print `hell`, but the program is
clearly incorrect, since there is only one element in the file, and that
@ -196,21 +196,21 @@ special control characters:
LF (line feed, 16#0A#) Line Mark
FF (form feed, 16#0C#) Page Mark
A canonical Text_IO file is defined as one in which the following
conditions are met:
*
*
The character `LF` is used only as a line mark, i.e., to mark the end
of the line.
*
*
The character `FF` is used only as a page mark, i.e., to mark the
end of a page and consequently can appear only immediately following a
`LF` (line mark) character.
*
*
The file ends with either `LF` (line mark) or `LF`-`FF`
(line mark, page mark). In the former case, the page mark is implicitly
assumed to be present.
@ -229,16 +229,16 @@ Manual, and all the routines in Text_IO are fully implemented.
A text file that does not meet the requirements for a canonical Text_IO
file has one of the following:
*
*
The file contains `FF` characters not immediately following a
`LF` character.
*
*
The file contains `LF` or `FF` characters written by
`Put` or `Put_Line`, which are not logically considered to be
line marks or page marks.
*
*
The file ends in a character other than `LF` or `FF`,
i.e., there is no explicit line mark or page mark at the end of the file.
@ -260,14 +260,14 @@ is being read. No internal buffering occurs in Text_IO, and usually the
physical position in the stream used to implement the file corresponds
to this logical position defined by Text_IO. There are two exceptions:
*
*
After a call to `End_Of_Page` that returns `True`, the stream
is positioned past the `LF` (line mark) that precedes the page
mark. Text_IO maintains an internal flag so that subsequent read
operations properly handle the logical position which is unchanged by
the `End_Of_Page` call.
*
*
After a call to `End_Of_File` that returns `True`, if the
Text_IO file was positioned before the line mark at the end of file
before the call, then the logical position is unchanged, but the stream
@ -298,19 +298,19 @@ marks. Any `Ascii.FF` characters (the character normally used for a
page mark) appearing in the file are considered to be data
characters. In particular:
*
*
`Get_Line` and `Skip_Line` do not test for a page mark
following a line mark. If a page mark appears, it will be treated as a
data character.
*
*
This avoids the need to wait for an extra character to be typed or
entered from the pipe to complete one of these operations.
*
*
`End_Of_Page` always returns `False`
*
*
`End_Of_File` will return `False` if there is a page mark at
the end of the file.
@ -440,7 +440,7 @@ specified using a FORM parameter:
::
WCEM=`x`
as part of the FORM string (WCEM = wide character encoding method),
where `x` is one of the following characters
@ -477,7 +477,7 @@ being brackets encoding if no coding method was specified with -gnatW).
::
ESC a b c d
..
where `a`, `b`, `c`, `d` are the four hexadecimal
@ -524,7 +524,7 @@ being brackets encoding if no coding method was specified with -gnatW).
16#0000#-16#007f#: 2#0xxxxxxx#
16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
..
where the `xxx` bits correspond to the left-padded bits of the
@ -545,7 +545,7 @@ being brackets encoding if no coding method was specified with -gnatW).
::
[ " a b c d " ]
..
where `a`, `b`, `c`, `d` are the four hexadecimal
@ -590,7 +590,7 @@ being brackets encoding if no coding method was specified with -gnatW).
::
Start of output ["5B"]first run]
..
In practice brackets encoding is reasonably useful for normal Put_Line use
@ -623,7 +623,7 @@ normal lower ASCII set (i.e., a character in the range:
.. code-block:: ada
Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#)
then although the logical position of the file pointer is unchanged by
the `Look_Ahead` call, the stream is physically positioned past the
@ -658,7 +658,7 @@ specified using a FORM parameter:
::
WCEM=`x`
as part of the FORM string (WCEM = wide character encoding method),
where `x` is one of the following characters
@ -701,7 +701,7 @@ being brackets encoding if no coding method was specified with -gnatW).
16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx#
16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx#
..
where the `xxx` bits correspond to the left-padded bits of the
@ -719,7 +719,7 @@ being brackets encoding if no coding method was specified with -gnatW).
::
[ " a b c d " ]
..
and by the following ten character sequence if not
@ -728,7 +728,7 @@ being brackets encoding if no coding method was specified with -gnatW).
::
[ " a b c d e f " ]
..
where `a`, `b`, `c`, `d`, `e`, and `f`
@ -767,7 +767,7 @@ normal lower ASCII set (i.e., a character in the range:
.. code-block:: ada
Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#)
then although the logical position of the file pointer is unchanged by
the `Look_Ahead` call, the stream is physically positioned past the
@ -798,11 +798,11 @@ written to the file as described in the Ada Reference Manual. The type
`Stream_Element` is simply a byte. There are two ways to read or
write a stream file.
*
*
The operations `Read` and `Write` directly read or write a
sequence of stream elements with no control information.
*
*
The stream attributes applied to a stream file transfer data in the
manner described for stream attributes.
@ -816,7 +816,7 @@ passed to Text_IO.Create and Text_IO.Open. ``Text_Translation=xxx``
has no effect on Unix systems. Possible values are:
*
*
``Yes`` or ``Text`` is the default, which means to
translate LF to/from CR/LF on Windows systems.
@ -825,15 +825,15 @@ has no effect on Unix systems. Possible values are:
may be used to create Unix-style files on
Windows.
*
*
``wtext`` translation enabled in Unicode mode.
(corresponds to _O_WTEXT).
*
*
``u8text`` translation enabled in Unicode UTF-8 mode.
(corresponds to O_U8TEXT).
*
*
``u16text`` translation enabled in Unicode UTF-16
mode. (corresponds to_O_U16TEXT).
@ -851,21 +851,21 @@ To provide a full range of functionality, while at the same time
minimizing the problems of portability caused by this implementation
dependence, GNAT handles file sharing as follows:
*
*
In the absence of a ``shared=xxx`` form parameter, an attempt
to open two or more files with the same full name is considered an error
and is not supported. The exception `Use_Error` will be
raised. Note that a file that is not explicitly closed by the program
remains open until the program terminates.
*
*
If the form parameter ``shared=no`` appears in the form string, the
file can be opened or created with its own separate stream identifier,
regardless of whether other files sharing the same external file are
opened. The exact effect depends on how the C stream routines handle
multiple accesses to the same external files using separate streams.
*
*
If the form parameter ``shared=yes`` appears in the form string for
each of two or more files opened using the same full name, the same
stream is shared between these files, and the semantics are as described
@ -905,11 +905,11 @@ Filenames encoding
An encoding form parameter can be used to specify the filename
encoding ``encoding=xxx``.
*
*
If the form parameter ``encoding=utf8`` appears in the form string, the
filename must be encoded in UTF-8.
*
*
If the form parameter ``encoding=8bits`` appears in the form
string, the filename must be a standard 8bits string.
@ -979,7 +979,7 @@ using the mode shown in the following table:
+----------------------------+---------------+------------------+
| Inout_File | "r+" | "w+" |
+----------------------------+---------------+------------------+
If text file translation is required, then either ``b`` or ``t``
is added to the mode, depending on the setting of Text. Text file
@ -1153,7 +1153,7 @@ access to the C library functions for operations on C streams:
-- Maximum length of an allowable full path name on the
-- system, including a terminating NUL character.
end Interfaces.C_Streams;
.. _Interfacing_to_C_Streams:
@ -1231,7 +1231,7 @@ operations.
C_Stream : in Interfaces.C_Streams.FILEs;
Form : in String := "");
end Ada.Stream_IO.C_Streams;
In each of these six packages, the `C_Stream` function obtains the
`FILE` pointer from a currently opened Ada file. It is then
@ -1249,4 +1249,3 @@ The `Open` procedures in these packages open a file giving an
existing C Stream instead of a file name. Typically this stream is
imported from a C program, allowing an Ada file to operate on an
existing C file.

11
gcc/ada/doc/gnat_ugn/about_this_guide.rst
View File

@ -45,11 +45,11 @@ This guide contains the following chapters:
with GNAT
Appendices cover several additional topics:
* :ref:`Platform_Specific_Information` describes the different run-time
library implementations and also presents information on how to use
GNAT on several specific platforms
* :ref:`Example_of_Binder_Output_File` shows the source code for the binder
output file for a sample program.
@ -136,7 +136,7 @@ the new document structure.
* :ref:`GNAT_Utility_Programs` is a new chapter consolidating the information about several
GNAT tools:
.. only:: PRO or GPL
- :ref:`The_File_Cleanup_Utility_gnatclean`
@ -149,7 +149,7 @@ the new document structure.
- :ref:`The_GNAT_Pretty-Printer_gnatpp`
- :ref:`The_Body_Stub_Generator_gnatstub`
- :ref:`The_Unit_Test_Generator_gnattest`
.. only:: FSF
- :ref:`The_File_Cleanup_Utility_gnatclean`
@ -206,7 +206,7 @@ in this guide:
::
and then shown this way.
* Commands that are entered by the user are shown as preceded by a prompt string
comprising the ``$`` character followed by a space.
@ -214,4 +214,3 @@ in this guide:
as the directory separator; e.g., :file:`parent-dir/subdir/myfile.adb`.
If you are using GNAT on a Windows platform, please note that
the '\\' character should be used instead.

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

@ -28,14 +28,14 @@ how to make use of the general GNU make mechanism
in a GNAT context (see :ref:`Using_the_GNU_make_Utility`).
.. only:: PRO or GPL
For building large systems with components possibly written
in different languages (such as Ada, C, C++ and Fortran)
and organized into subsystems and libraries, the GPRbuild
tool can be used. This tool, and the Project Manager
facility that it is based upon, is described in
*GPRbuild and GPR Companion Tools User's Guide*.
.. _The_GNAT_Make_Program_gnatmake:
@ -527,7 +527,7 @@ You may specify any of the following switches to *gnatmake*:
:samp:`-P{project}`
Use project file `project`. Only one such switch can be used.
.. -- Comment:
.. -- Comment:
:ref:`gnatmake_and_Project_Files`.
@ -1445,9 +1445,7 @@ Alphabetical List of All Switches
*-gnatc* as a builder switch (before *-cargs* or in package
Builder of the project file) then *gnatmake* will not fail because
it will not look for the object files after compilation, and it will not try
to build and link. This switch may not be given if a previous `-gnatR`
switch has been given, since `-gnatR` requires that the code generator
be called to complete determination of representation information.
to build and link.
.. index:: -gnatC (gcc)
@ -1476,7 +1474,7 @@ Alphabetical List of All Switches
:samp:`-gnatD`
Create expanded source files for source level debugging. This switch
also suppress generation of cross-reference information
also suppresses generation of cross-reference information
(see *-gnatx*). Note that this switch is not allowed if a previous
-gnatR switch has been given, since these two switches are not compatible.
@ -1917,8 +1915,8 @@ Alphabetical List of All Switches
.. index:: -gnatn (gcc)
:samp:`-gnatn[12]`
Activate inlining for subprograms for which pragma `Inline` is
specified. This inlining is performed by the GCC back-end. An optional
Activate inlining across modules for subprograms for which pragma `Inline`
is specified. This inlining is performed by the GCC back-end. An optional
digit sets the inlining level: 1 for moderate inlining across modules
or 2 for full inlining across modules. If no inlining level is specified,
the compiler will pick it based on the optimization level.
@ -5417,16 +5415,16 @@ Subprogram Inlining Control
.. index:: -gnatn (gcc)
:samp:`-gnatn[12]`
The `n` here is intended to suggest the first syllable of the
word 'inline'.
GNAT recognizes and processes `Inline` pragmas. However, for the
inlining to actually occur, optimization must be enabled and, in order
to enable inlining of subprograms specified by pragma `Inline`,
The `n` here is intended to suggest the first syllable of the word 'inline'.
GNAT recognizes and processes `Inline` pragmas. However, for inlining to
actually occur, optimization must be enabled and, by default, inlining of
subprograms across modules is not performed. If you want to additionally
enable inlining of subprograms specified by pragma `Inline` across modules,
you must also specify this switch.
In the absence of this switch, GNAT does not attempt
inlining and does not need to access the bodies of
subprograms for which `pragma Inline` is specified if they are not
in the current unit.
In the absence of this switch, GNAT does not attempt inlining across modules
and does not access the bodies of subprograms for which `pragma Inline` is
specified if they are not in the current unit.
You can optionally specify the inlining level: 1 for moderate inlining across
modules, which is a good compromise between compilation times and performances
@ -5659,7 +5657,7 @@ Debugging Control
you to do source level debugging using the generated code which is
sometimes useful for complex code, for example to find out exactly
which part of a complex construction raised an exception. This switch
also suppress generation of cross-reference information (see
also suppresses generation of cross-reference information (see
*-gnatx*) since otherwise the cross-reference information
would refer to the :file:`.dg` file, which would cause
confusion since this is not the original source file.
@ -5727,12 +5725,6 @@ Debugging Control
this case, the component clause uses an obvious extension of permitted
Ada syntax, for example `at 0 range 0 .. -1`.
Representation information requires that code be generated (since it is the
code generator that lays out complex data structures). If an attempt is made
to output representation information when no code is generated, for example
when a subunit is compiled on its own, then no information can be generated
and the compiler outputs a message to this effect.
.. index:: -gnatS (gcc)
@ -5901,6 +5893,21 @@ there is no point in using *-m* switches to improve performance
unless you actually see a performance improvement.
.. _Linker_Switches:
Linker Switches
===============
Linker switches can be specified after :samp:`-largs` builder switch.
.. index:: -fuse-ld=name
:samp:`-fuse-ld={name}`
Linker to be used. The default is ``bfd`` for :file:`ld.bfd`,
the alternative being ``gold`` for :file:`ld.gold`. The later is
a more recent and faster linker, but only available on GNU/Linux
platforms.
.. _Binding_with_gnatbind:
Binding with `gnatbind`
@ -6113,10 +6120,12 @@ be presented in subsequent sections.
blocks (whose size is the minimum of the default secondary stack size value,
and the actual size needed for the current allocation request).
For certain targets, notably VxWorks 653,
the secondary stack is allocated by carving off a fixed ratio chunk of the
primary task stack. The -D option is used to define the
size of the environment task's secondary stack.
For certain targets, notably VxWorks 653 and bare board targets,
the secondary stack is allocated by carving off a chunk of the primary task
stack. By default this is a fixed percentage of the primary task stack as
defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per
task using the Secondary_Stack_Size pragma/aspect. The -D option is used to
define the size of the environment task's secondary stack.
.. index:: -e (gnatbind)
@ -6151,6 +6160,11 @@ be presented in subsequent sections.
Currently the same as `-Ea`.
.. index:: -f (gnatbind)
:samp:`-f{elab-order}`
Force elaboration order.
.. index:: -F (gnatbind)
:samp:`-F`
@ -6600,6 +6614,47 @@ The following switches provide additional control over the elaboration
order. For full details see :ref:`Elaboration_Order_Handling_in_GNAT`.
.. index:: -f (gnatbind)
:samp:`-f{elab-order}`
Force elaboration order.
`elab-order` should be the name of a "forced elaboration order file", that
is, a text file containing library item names, one per line. A name of the
form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
name of the form "some.unit%b" or "some.unit (body)" denotes the body of
Some.Unit. Each pair of lines is taken to mean that there is an elaboration
dependence of the second line on the first. For example, if the file
contains:
.. code-block:: ada
this (spec)
this (body)
that (spec)
that (body)
then the spec of This will be elaborated before the body of This, and the
body of This will be elaborated before the spec of That, and the spec of That
will be elaborated before the body of That. The first and last of these three
dependences are already required by Ada rules, so this file is really just
forcing the body of This to be elaborated before the spec of That.
The given order must be consistent with Ada rules, or else `gnatbind` will
give elaboration cycle errors. For example, if you say x (body) should be
elaborated before x (spec), there will be a cycle, because Ada rules require
x (spec) to be elaborated before x (body); you can't have the spec and body
both elaborated before each other.
If you later add "with That;" to the body of This, there will be a cycle, in
which case you should erase either "this (body)" or "that (spec)" from the
above forced elaboration order file.
Blank lines and Ada-style comments are ignored. Unit names that do not exist
in the program are ignored. Units in the GNAT predefined library are also
ignored.
.. index:: -p (gnatbind)
:samp:`-p`

4
gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst
View File

@ -1661,8 +1661,8 @@ and
::
Init_Constants spec
Init_Constants body
Constants spec
Init_Constants body
Calc spec
Main body
@ -1703,7 +1703,7 @@ compilers can choose different orders.
However, GNAT does attempt to diagnose the common situation where there
are uninitialized variables in the visible part of a package spec, and the
corresponding package body has an elaboration block that directly or
indirectly initialized one or more of these variables. This is the situation
indirectly initializes one or more of these variables. This is the situation
in which a pragma Elaborate_Body is usually desirable, and GNAT will generate
a warning that suggests this addition if it detects this situation.

5
gcc/ada/doc/gnat_ugn/example_of_binder_output.rst
View File

@ -727,7 +727,7 @@ Comments have been added for clarification purposes.
-- END Object file/option list
end ada_main;
The Ada code in the above example is exactly what is generated by the
binder. We have added comments to more clearly indicate the function
@ -743,8 +743,7 @@ you can place a breakpoint on the call:
.. code-block:: ada
Ada.Text_Io'Elab_Body;
and trace the elaboration routine for this package to find out where
the problem might be (more usually of course you would be debugging
elaboration code in your own application).

3
gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst
View File

@ -75,7 +75,7 @@ as the command prompt in the examples in this document):
.. code-block:: sh
$ gcc -c hello.adb
*gcc* is the command used to run the compiler. This compiler is
capable of compiling programs in several languages, including Ada and
@ -273,4 +273,3 @@ Ada make tools, *gnatmake* does not rely on the dependencies that were
found by the compiler on a previous compilation, which may possibly
be wrong when sources change. *gnatmake* determines the exact set of
dependencies from scratch each time it is run.

11
gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
View File

@ -1740,10 +1740,9 @@ following conditions are met:
.. index:: Inline
* Any one of the following applies: `pragma Inline` is applied to the
subprogram and the *-gnatn* switch is specified; the
subprogram is local to the unit and called once from within it; the
subprogram is small and optimization level *-O2* is specified;
optimization level *-O3* is specified.
subprogram; the subprogram is local to the unit and called once from
within it; the subprogram is small and optimization level *-O2* is
specified; optimization level *-O3* is specified.
Calls to subprograms in |withed| units are normally not inlined.
To achieve actual inlining (that is, replacement of the call by the code
@ -1755,8 +1754,6 @@ in the body of the subprogram), the following conditions must all be true:
and not contain something that *gcc* cannot support in inlined
subprograms.
* The call appears in a body (not in a package spec).
* There is a `pragma Inline` for the subprogram.
* The *-gnatn* switch is used on the command line.
@ -1806,7 +1803,7 @@ additional dependencies.
.. index:: -fno-inline (gcc)
Note: The *-fno-inline* switch overrides all other conditions and ensures that
no inlining occurs, unless requested with pragma Inline_Always for gcc
no inlining occurs, unless requested with pragma Inline_Always for *gcc*
back-ends. The extra dependences resulting from *-gnatn* will still be active,
even if this switch is used to suppress the resulting inlining actions.

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

@ -632,11 +632,7 @@ The following switches are available for *gnatxref*:
.. index:: -pFILE (gnatxref)
:samp:`p{FILE}`
Specify a project file to use (see the *GNAT_Project_Manager*
chapter in the *GPRbuild User's Guide*).
If you need to use the :file:`.gpr`
project files, you should use gnatxref through the GNAT driver
(*gnat xref -Pproject*).
Specify a project file to use.
By default, `gnatxref` and `gnatfind` will try to locate a
project file in the current directory.
@ -836,8 +832,7 @@ The following switches are available:
.. index:: -pFILE (gnatfind)
:samp:`p{FILE}`
Specify a project file (see the *GNAT_Project_Manager* chapter in the
*GPRbuild User's Guide*).
Specify a project file.
By default, `gnatxref` and `gnatfind` will try to locate a
project file in the current directory.
@ -3060,7 +3055,7 @@ Alternatively, you may run the script using the following command line:
.. index:: -nt (gnatpp)
:samp:`-neD`
:samp:`-ntD`
Names introduced by type and subtype declarations are always
cased as they appear in the declaration in the source file.
Overrides -n casing setting.
@ -4206,6 +4201,14 @@ Alternatively, you may run the script using the following command line:
a skeleton for each visible subprogram in the packages under consideration when
they do not exist already.
*gnattest* is a project-aware tool.
(See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
the project-related switches but note that *gnattest* does not support
the :samp:`-U`, :samp:`-eL`, :samp:`--subdirs={dir}`, or
:samp:`--no_objects_dir` switches.)
The project file package that can specify
*gnattest* switches is named ``gnattest``.
The user can choose to generate a single test driver
that will run all individual tests, or separate test drivers for each test. The
second option allows much greater flexibility in test execution environment,
@ -4354,12 +4357,6 @@ Alternatively, you may run the script using the following command line:
Recursively considers all sources from all projects.
.. index:: -X (gnattest)
:samp:`-X{name}={value}`
Indicate that external variable `name` has the value `value`.
.. index:: --RTS (gnattest)
:samp:`--RTS={rts-path}`
@ -5050,7 +5047,7 @@ Alternatively, you may run the script using the following command line:
with a number of GNAT tools.
For a comprehensive description of project files and the overall
GNAT Project Manager facility, please refer to the
*GNAT Project Manager* chapter in the
*GNAT Project Manager* chapter in the
*GPRbuild and GPR Companion Tools User's Guide*.
.. index:: Project-aware tool
@ -5072,7 +5069,7 @@ Alternatively, you may run the script using the following command line:
:samp:`-U`
If a project file is supplied, say for project ``proj``,
but no sources are specified for ``proj`` (either by a
but no sources are specified for ``proj`` (either by a
project attribute or through a tool option that provides a list
of the files to be used), process all the source files
from projects imported either directly or indirectly by ``proj``.
@ -5108,7 +5105,7 @@ Alternatively, you may run the script using the following command line:
defined by that project, either implicitly by residing in the project
source directories, or explicitly through any of the source-related
attributes).
.. _Tool-specific_packages_in_project files:
Tool-specific packages in project files
@ -5121,4 +5118,4 @@ Alternatively, you may run the script using the following command line:
A tool-specific package in a project file may define the ``Default_Switches``
attribute indexed by "ada" (as language name). The value of this attribute
is a list of switches that will be supplied at tool invocation.
Project-specific switches cannot be specified through this attribute.
Project-specific switches cannot be specified through this attribute.

48
gcc/ada/doc/gnat_ugn/inline_assembler.rst
View File

@ -119,7 +119,7 @@ from which it generates a sequence of assembly language instructions.
The examples in this chapter will illustrate several of the forms
for invoking `Asm`; a complete specification of the syntax
is found in the `Machine_Code_Insertions` section of the
is found in the `Machine_Code_Insertions` section of the
:title:`GNAT Reference Manual`.
Under the standard GNAT conventions, the `Nothing` procedure
@ -129,7 +129,7 @@ You can build the executable in the usual way:
::
$ gnatmake nothing
However, the interesting aspect of this example is not its run-time behavior
but rather the generated assembly code.
To see this output, invoke the compiler as follows:
@ -137,7 +137,7 @@ To see this output, invoke the compiler as follows:
::
$ gcc -c -S -fomit-frame-pointer -gnatp nothing.adb
where the options are:
* :samp:`-c`
@ -191,7 +191,7 @@ Assembling the file using the command
::
$ as nothing.s
$ as nothing.s
will give you error messages whose lines correspond to the assembler
input file, so you can easily find and correct any mistakes you made.
@ -224,7 +224,7 @@ statements.
Outputs => Unsigned_32'Asm_Output ("=g", Flags));
Put_Line ("Flags register:" & Flags'Img);
end Get_Flags;
In order to have a nicely aligned assembly listing, we have separated
multiple assembler statements in the Asm template string with linefeed
(ASCII.LF) and horizontal tab (ASCII.HT) characters.
@ -243,7 +243,7 @@ It would have been legal to write the Asm invocation as:
.. code-block:: ada
Asm ("pushfl popl %%eax movl %%eax, %0")
but in the generated assembler file, this would come out as:
::
@ -251,7 +251,7 @@ but in the generated assembler file, this would come out as:
#APP
pushfl popl %eax movl %eax, -40(%ebp)
#NO_APP
which is not so convenient for the human reader.
We use Ada comments
@ -273,7 +273,7 @@ the third statement in the Asm template string:
::
movl %%eax, %0
The intent is to store the contents of the eax register in a variable that can
be accessed in Ada. Simply writing `movl %%eax, Flags` would not
necessarily work, since the compiler might optimize by using a register
@ -288,21 +288,21 @@ parameter to `Asm`:
.. code-block:: ada
Outputs => Unsigned_32'Asm_Output ("=g", Flags));
The output is defined by the `Asm_Output` attribute of the target type;
the general format is
.. code-block:: ada
Type'Asm_Output (constraint_string, variable_name)
The constraint string directs the compiler how
to store/access the associated variable. In the example
.. code-block:: ada
Unsigned_32'Asm_Output ("=m", Flags);
the `"m"` (memory) constraint tells the compiler that the variable
`Flags` should be stored in a memory variable, thus preventing
the optimizer from keeping it in a register. In contrast,
@ -310,7 +310,7 @@ the optimizer from keeping it in a register. In contrast,
.. code-block:: ada
Unsigned_32'Asm_Output ("=r", Flags);
uses the `"r"` (register) constraint, telling the compiler to
store the variable in a register.
@ -352,7 +352,7 @@ integer. Thus in
"popl %%eax" & LF & HT & -- load eax with flags
"movl %%eax, %0", -- store flags in variable
Outputs => Unsigned_32'Asm_Output ("=g", Flags));
`%0` will be replaced in the expanded code by the appropriate operand,
whatever
@ -375,7 +375,7 @@ For example:
Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A
Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B
Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C
where `Var_A`, `Var_B`, and `Var_C` are variables
in the Ada program.
@ -398,7 +398,7 @@ variable, instead of including the store instruction explicitly in the
Outputs => Unsigned_32'Asm_Output ("=a", Flags));
Put_Line ("Flags register:" & Flags'Img);
end Get_Flags_2;
The `"a"` constraint tells the compiler that the `Flags`
variable will come from the eax register. Here is the resulting code:
@ -409,7 +409,7 @@ variable will come from the eax register. Here is the resulting code:
popl %eax
#NO_APP
movl %eax,-40(%ebp)
The compiler generated the store of eax into Flags after
expanding the assembler code.
@ -430,7 +430,7 @@ more simply, we could just pop the flags directly into the program variable:
Outputs => Unsigned_32'Asm_Output ("=g", Flags));
Put_Line ("Flags register:" & Flags'Img);
end Get_Flags_3;
.. _Input_Variables_in_Inline_Assembler:
@ -465,7 +465,7 @@ The program simply increments its input value by 1:
Value := Incr (Value);
Put_Line ("Value after is" & Value'Img);
end Increment;
The `Outputs` parameter to `Asm` specifies
that the result will be in the eax register and that it is to be stored
in the `Result` variable.
@ -505,7 +505,7 @@ The resulting assembler file (with *-O2* optimization) contains:
movl %ecx,(%esp)
addl $4,%esp
ret
.. _Inlining_Inline_Assembler_Code:
@ -545,7 +545,7 @@ Here is the resulting program:
Value := Increment (Value);
Put_Line ("Value after is" & Value'Img);
end Increment_2;
Compile the program with both optimization (*-O2*) and inlining
(*-gnatn*) enabled.
@ -557,7 +557,7 @@ point in `Increment` where our function used to be called:
pushl %edi
call _increment__incr.1
the code for the function body directly appears:
@ -607,7 +607,7 @@ assembly code; for example:
"movl %%ebx, %1",
Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
Inputs => Unsigned_32'Asm_Input ("g", Var_In));
where the compiler (since it does not analyze the `Asm` template string)
does not know you are using the ebx register.
@ -622,7 +622,7 @@ to identify the registers that will be used by your assembly code:
Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
Inputs => Unsigned_32'Asm_Input ("g", Var_In),
Clobber => "ebx");
The Clobber parameter is a static string expression specifying the
register(s) you are using. Note that register names are *not* prefixed
by a percent sign. Also, if more than one register is used then their names
@ -657,7 +657,7 @@ the `Volatile` parameter to `True`; for example:
Inputs => Unsigned_32'Asm_Input ("g", Var_In),
Clobber => "ebx",
Volatile => True);
By default, `Volatile` is set to `False` unless there is no
`Outputs` parameter.

6
gcc/ada/doc/gnat_ugn/platform_specific_information.rst
View File

@ -160,7 +160,7 @@ For example on x86-linux::
.. image:: rtlibrary-structure.png
.. only:: not (html or latex)
.. only:: not (html or latex)
::
@ -562,7 +562,7 @@ and::
Ada.Command_Line.Argument (1) -> "'*.txt'"
.. _Mixed-Language_Programming_on_Windows:
Mixed-Language Programming on Windows
@ -1944,7 +1944,7 @@ cookbook-style sequence of steps to follow:
$ gprbuild -p mylib.gpr
2. Produce a .def file for the symbols you need to interface with, either by
hand or automatically with possibly some manual adjustments
hand or automatically with possibly some manual adjustments
(see :ref:`Creating Definition File Automatically <Create_Def_File_Automatically>`):
::

204
gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst
View File

@ -27,7 +27,7 @@ the following material:
* :ref:`Source_Representation`
* :ref:`Foreign_Language_Representation`
* :ref:`File_Naming_Topics_and_Utilities`
* :ref:`Configuration_Pragmas`
* :ref:`Generating_Object_Files`
* :ref:`Source_Dependencies`
@ -217,7 +217,7 @@ possible encoding schemes:
character sequence::
ESC a b c d
where `a`, `b`, `c`, `d` are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ESC A345 is used to represent the wide character with code
@ -281,7 +281,7 @@ possible encoding schemes:
character sequence::
[ " a b c d " ]
where `a`, `b`, `c`, `d` are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ['A345'] is used to represent the wide character with code
@ -293,7 +293,7 @@ possible encoding schemes:
and is also the method used for wide character encoding in some standard
ACATS (Ada Conformity Assessment Test Suite) test suite distributions.
.. note::
.. note::
Some of these coding schemes do not permit the full use of the
Ada character set. For example, neither Shift JIS nor EUC allow the
@ -321,7 +321,7 @@ possible encoding schemes:
10xxxxxx 10xxxxxx
16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx
10xxxxxx 10xxxxxx 10xxxxxx
where the `xxx` bits correspond to the left-padded bits of the
32-bit character value.
@ -332,7 +332,7 @@ possible encoding schemes:
[ " a b c d e f " ]
[ " a b c d e f g h " ]
where `a-h` are the six or eight hexadecimal
characters (using uppercase letters) of the wide wide character code. For
example, ["1F4567"] is used to represent the wide wide character with code
@ -441,7 +441,7 @@ The form of this pragma is as shown in the following examples:
Spec_File_Name => "myutilst_a.ada");
pragma Source_File_name (My_Utilities.Stacks,
Body_File_Name => "myutilst.ada");
As shown in this example, the first argument for the pragma is the unit
name (in this example a child unit). The second argument has the form
of a named association. The identifier
@ -467,7 +467,7 @@ of the language, here `ada`, as in:
.. code-block:: sh
$ gcc -c -x ada peculiar_file_name.sim
`gnatmake` handles non-standard file names in the usual manner (the
non-standard file name for the main program is simply used as the
argument to gnatmake). Note that if the extension is also non-standard,
@ -573,7 +573,7 @@ two pragmas appear:
(Spec_File_Name => ".1.ada");
pragma Source_File_Name
(Body_File_Name => ".2.ada");
The default GNAT scheme is actually implemented by providing the following
default pragmas internally:
@ -583,7 +583,7 @@ default pragmas internally:
(Spec_File_Name => ".ads", Dot_Replacement => "-");
pragma Source_File_Name
(Body_File_Name => ".adb", Dot_Replacement => "-");
Our final example implements a scheme typically used with one of the
Ada 83 compilers, where the separator character for subunits was '__'
(two underscores), specs were identified by adding :file:`_.ADA`, bodies
@ -609,7 +609,7 @@ the same double underscore separator for child units.
Casing = Uppercase);
.. index:: ! gnatname
.. index:: ! gnatname
.. _Handling_Arbitrary_File_Naming_Conventions_with_gnatname:
@ -654,7 +654,7 @@ The usual form of the `gnatname` command is:
$ gnatname [`switches`] `naming_pattern` [`naming_patterns`]
[--and [`switches`] `naming_pattern` [`naming_patterns`]]
All of the arguments are optional. If invoked without any argument,
`gnatname` will display its usage.
@ -683,7 +683,7 @@ Examples of Naming Patterns are::
"*.[12].ada"
"*.ad[sb]*"
"body_*" "spec_*"
For a more complete description of the syntax of Naming Patterns,
see the second kind of regular expressions described in :file:`g-regexp.ads`
(the 'Glob' regular expressions).
@ -784,7 +784,7 @@ You may specify any of the following switches to `gnatname`:
.. code-block:: sh
gnatname -Pprj -f"*.c" "*.ada"
will look for Ada units in all files with the :file:`.ada` extension,
and will add to the list of file for project :file:`prj.gpr` the C files
with extension :file:`.c`.
@ -833,7 +833,7 @@ You may specify any of the following switches to `gnatname`:
.. code-block:: sh
gnatname -x "*_nt.ada" "*.ada"
will look for Ada units in all files with the :file:`.ada` extension,
except those whose names end with :file:`_nt.ada`.
@ -846,7 +846,7 @@ Examples of `gnatname` Usage
.. code-block:: sh
$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*"
In this example, the directory :file:`/home/me` must already exist
and be writable. In addition, the directory
:file:`/home/me/sources` (specified by
@ -858,7 +858,7 @@ Note the optional spaces after *-c* and *-d*.
$ gnatname -P/home/me/proj -x "*_nt_body.ada"
-dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
Note that several switches *-d* may be used,
even in conjunction with one or several switches
*-D*. Several Naming Patterns and one excluded pattern
@ -920,7 +920,7 @@ The `gnatkr` command has the form:
.. code-block:: sh
$ gnatkr `name` [`length`]
`name` is the uncrunched file name, derived from the name of the unit
in the standard manner described in the previous section (i.e., in particular
all dots are replaced by hyphens). The file name may or may not have an
@ -989,7 +989,7 @@ the specified length by following these rules:
ou st wi fix 9
ou st wi fi 8
Final file name: oustwifi.adb
* The file names for all predefined units are always krunched to eight
characters. The krunching of these predefined units uses the following
special prefix replacements:
@ -1023,7 +1023,7 @@ the specified length by following these rules:
a- st wi fix 9
a- st wi fi 8
Final file name: a-stwifi.adb
Of course no file shortening algorithm can guarantee uniqueness over all
possible unit names, and if file name krunching is used then it is your
responsibility to ensure that no name clashes occur. The utility
@ -1043,7 +1043,7 @@ Examples of `gnatkr` Usage
$ gnatkr grandparent-parent-child --> grparchi
$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads
$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads
.. _Renaming_Files_with_gnatchop:
@ -1160,7 +1160,7 @@ The `gnatchop` command has the form:
$ gnatchop switches file_name [file_name ...]
[directory]
The only required argument is the file name of the file to be chopped.
There are no restrictions on the form of this file name. The file itself
contains one or more Ada units, in normal GNAT format, concatenated
@ -1179,19 +1179,19 @@ file called :file:`hellofiles` containing
.. code-block:: ada
procedure Hello;
with Ada.Text_IO; use Ada.Text_IO;
procedure Hello is
begin
Put_Line ("Hello");
end Hello;
the command
.. code-block:: sh
$ gnatchop hellofiles
generates two files in the current directory, one called
:file:`hello.ads` containing the single line that is the procedure spec,
and the other called :file:`hello.adb` containing the remaining text. The
@ -1214,13 +1214,13 @@ the command
.. code-block:: sh
$ gnatchop toto.txt
will not produce any new file and will result in the following warnings::
toto.txt:1:01: warning: empty file, contains no compilation units
no compilation units found
no source files written
.. _Switches_for_gnatchop:
@ -1355,7 +1355,7 @@ directory are modified).
.. code-block:: sh
$ gnatchop archive
Chops the source file :file:`archive`
into the current directory. One
useful application of `gnatchop` is in sending sets of sources
@ -1368,7 +1368,7 @@ file names.
.. code-block:: sh
$ gnatchop file1 file2 file3 direc
Chops all units in files :file:`file1`, :file:`file2`, :file:`file3`, placing
the resulting files in the directory :file:`direc`. Note that if any units
occur more than once anywhere within this set of files, an error message
@ -1390,7 +1390,7 @@ Configuration Pragmas
Configuration pragmas include those pragmas described as
such in the Ada Reference Manual, as well as
implementation-dependent pragmas that are configuration pragmas.
See the `Implementation_Defined_Pragmas` chapter in the
See the `Implementation_Defined_Pragmas` chapter in the
:title:`GNAT_Reference_Manual` for details on these
additional GNAT-specific configuration pragmas.
Most notably, the pragma `Source_File_Name`, which allows
@ -1446,6 +1446,7 @@ recognized by GNAT::
Propagate_Exceptions
Queuing_Policy
Ravenscar
Rename_Pragma
Restricted_Run_Time
Restrictions
Restrictions_Warnings
@ -1464,7 +1465,7 @@ recognized by GNAT::
Validity_Checks
Warnings
Wide_Character_Encoding
.. _Handling_of_Configuration_Pragmas:
@ -1892,13 +1893,13 @@ Here is a simple library project file:
for Library_Dir use "lib";
for Library_Kind use "dynamic";
end My_lib;
and the compilation command to build and install the library:
.. code-block:: sh
$ gnatmake -Pmy_lib
It is not entirely trivial to perform manually all the steps required to
produce a library. We recommend that you use the GNAT Project Manager
for this task. In special cases where this is not desired, the necessary
@ -1925,7 +1926,7 @@ Here is an example of such a dummy program:
begin
null;
end;
Here are the generic commands that will build an archive or a shared library.
.. code-block:: sh
@ -1950,7 +1951,7 @@ Here are the generic commands that will build an archive or a shared library.
# Make the ALI files read-only so that gnatmake will not try to
# regenerate the objects that are in the library
$ chmod -w *.ali
Please note that the library must have a name of the form :file:`lib{xxx}.a`
or :file:`lib{xxx}.so` (or :file:`lib{xxx}.dll` on Windows) in order to
be accessed by the directive :samp:`-l{xxx}` at link time.
@ -1980,7 +1981,7 @@ file. The location of the gcc spec file can be determined as follows:
.. code-block:: sh
$ gcc -v
The configuration files mentioned above have a simple format: each line
must contain one unique directory name.
@ -2029,7 +2030,7 @@ write:
project My_Proj is
...
end My_Proj;
Even if you have a third-party, non-Ada library, you can still use GNAT's
Project Manager facility to provide a wrapper for it. For example, the
following project, when |withed| by your main project, will link with the
@ -2044,7 +2045,7 @@ third-party library :file:`liba.a`:
for Library_Name use "a";
for Library_Kind use "static";
end Liba;
This is an alternative to the use of `pragma Linker_Options`. It is
especially interesting in the context of systems with several interdependent
static libraries where finding a proper linker order is not easy and best be
@ -2064,7 +2065,7 @@ For example, you can use the library :file:`mylib` installed in
$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\
-largs -lmy_lib
This can be expressed more simply:
.. code-block:: sh
@ -2087,7 +2088,7 @@ when the following conditions are met:
.. code-block:: ada
pragma Linker_Options ("-lmy_lib");
Note that you may also load a library dynamically at
run time given its filename, as illustrated in the GNAT :file:`plugins` example
in the directory :file:`share/examples/gnat/plugins` within the GNAT
@ -2150,11 +2151,11 @@ that make a project a Library Project (`Library_Name` and
the attribute `Library_Interface` must be defined. For example:
.. code-block:: gpr
for Library_Dir use "lib_dir";
for Library_Name use "dummy";
for Library_Interface use ("int1", "int1.child");
Attribute `Library_Interface` has a non-empty string list value,
each string in the list designating a unit contained in an immediate source
of the project file.
@ -2195,7 +2196,7 @@ build an encapsulated library the attribute
for Library_Kind use "dynamic";
for Library_Interface use ("int1", "int1.child");
for Library_Standalone use "encapsulated";
The default value for this attribute is `standard` in which case
a stand-alone library is built.
@ -2226,13 +2227,13 @@ occasions when it is necessary here are the steps that you need to perform:
.. code-block:: sh
$ gnatbind -n int1.ali int2.ali -Lsal1
* Compile the binder generated file:
.. code-block:: sh
$ gcc -c b~int2.adb
* Link the dynamic library with all the necessary object files,
indicating to the linker the names of the `init` (and possibly
`final`) procedures for automatic initialization (and finalization).
@ -2273,7 +2274,7 @@ Here is an example of simple library interface for use with C main program:
pragma Export (C, Do_Something_Else, "do_something_else");
end My_Package;
On the foreign language side, you must provide a 'foreign' view of the
library interface; remember that it should contain elaboration routines in
addition to interface subprograms.
@ -2292,7 +2293,7 @@ that there is no rule for the naming of this file, any name can be used)
/* the interface exported by the library */
extern void do_something (void);
extern void do_something_else (void);
Libraries built as explained above can be used from any program, provided
that the elaboration procedures (named `mylibinit` in the previous
example) are called before the library services are used. Any number of
@ -2310,7 +2311,7 @@ Below is an example of a C program that uses the `mylib` library.
{
/* First, elaborate the library before using it */
mylibinit ();
/* Main program, using the library exported entities */
do_something ();
do_something_else ();
@ -2387,7 +2388,7 @@ be determined by means of the command:
.. code-block:: sh
$ gnatls -v
The last entry in the object search path usually contains the
gnat library. This Makefile contains its own documentation and in
particular the set of instructions needed to rebuild a new library and
@ -2453,7 +2454,7 @@ constants to control which code is executed.
if FP_Initialize_Required then
...
end if;
Not only will the code inside the `if` statement not be executed if
the constant Boolean is `False`, but it will also be completely
deleted from the program.
@ -2475,7 +2476,7 @@ something like:
Reset_Available : constant Boolean := False;
...
end Config;
The `Config` package exists in multiple forms for the various targets,
with an appropriate script selecting the version of `Config` needed.
Then any other unit requiring conditional compilation can do a |with|
@ -2520,13 +2521,13 @@ example, the last test could be written:
.. code-block:: ada
pragma Assert (Temperature <= 999.0, "Temperature Crazy");
or simply
.. code-block:: ada
pragma Assert (Temperature <= 999.0);
In both cases, if assertions are active and the temperature is excessive,
the exception `Assert_Failure` will be raised, with the given string in
the first case or a string indicating the location of the pragma in the second
@ -2552,7 +2553,7 @@ For the example above with the `Put_Line`, the GNAT-specific pragma
.. code-block:: ada
pragma Debug (Put_Line ("got to the first stage!"));
If debug pragmas are enabled, the argument, which must be of the form of
a procedure call, is executed (in this case, `Put_Line` will be called).
Only one call can be present, but of course a special debugging procedure
@ -2593,7 +2594,7 @@ to add a `null` statement.
pragma Assert (Num_Cases < 10);
null;
end if;
.. _Conditionalizing_Declarations:
Conditionalizing Declarations
@ -2691,7 +2692,7 @@ to compile with an Ada 95 compiler. Conceptually you want to say:
else
... not quite as neat Ada 95 code
end if;
where `Ada_2005` is a Boolean constant.
But this won't work when `Ada_2005` is set to `False`,
@ -2721,7 +2722,7 @@ This can also be done with project files' naming schemes. For example:
.. code-block:: gpr
for body ("File_Queries.Insert") use "file_queries-insert-2005.ada";
Note also that with project files it is desirable to use a different extension
than :file:`ads` / :file:`adb` for alternative versions. Otherwise a naming
conflict may arise through another commonly used feature: to declare as part
@ -3024,7 +3025,7 @@ In this example, <expression> is defined by the following grammar::
<expression> ::= <expression> and then <expression>
<expression> ::= <expression> or else <expression>
<expression> ::= ( <expression> )
Note the following restriction: it is not allowed to have "and" or "or"
following "not" in the same expression without parentheses. For example, this
is not allowed:
@ -3032,14 +3033,14 @@ is not allowed:
.. code-block:: ada
not X or Y
This can be expressed instead as one of the following forms:
.. code-block:: ada
(not X) or Y
not (X or Y)
For the first test (<expression> ::= <symbol>) the symbol must have
either the value true or false, that is to say the right-hand of the
symbol definition must be one of the (case-insensitive) literals
@ -3089,7 +3090,7 @@ Symbol substitution outside of preprocessor lines is obtained by using
the sequence::
$symbol
anywhere within a source line, except in a comment or within a
string literal. The identifier
following the `$` must match one of the symbols defined in the symbol
@ -3303,7 +3304,7 @@ the main subprogram in Ada:
/* file1.c */
#include <stdio.h>
void print_num (int num)
{
printf ("num is %d.\\n", num);
@ -3313,15 +3314,15 @@ the main subprogram in Ada:
.. code-block:: c
/* file2.c */
/* num_from_Ada is declared in my_main.adb */
extern int num_from_Ada;
int get_num (void)
{
return num_from_Ada;
}
.. code-block:: ada
-- my_main.adb
@ -3344,7 +3345,7 @@ the main subprogram in Ada:
begin
Print_Num (Get_Num);
end My_Main;
To build this example:
* First compile the foreign language files to
@ -3354,7 +3355,7 @@ To build this example:
$ gcc -c file1.c
$ gcc -c file2.c
* Then, compile the Ada units to produce a set of object files and ALI
files:
@ -3374,13 +3375,13 @@ To build this example:
.. code-block:: sh
$ gnatlink my_main.ali file1.o file2.o
The last three steps can be grouped in a single command:
.. code-block:: sh
$ gnatmake my_main.adb -largs file1.o file2.o
.. index:: Binder output file
@ -3419,7 +3420,7 @@ sources. To illustrate, we have the following example:
adafinal();
}
.. code-block:: ada
-- unit1.ads
@ -3455,7 +3456,7 @@ sources. To illustrate, we have the following example:
return A - B;
end Sub;
end Unit2;
The build procedure for this application is similar to the last
example's:
@ -3464,7 +3465,7 @@ example's:
.. code-block:: sh
$ gcc -c main.c
* Next, compile the Ada units to produce a set of object files and ALI
files:
@ -3473,21 +3474,21 @@ example's:
$ gnatmake -c unit1.adb
$ gnatmake -c unit2.adb
* Run the Ada binder on every generated ALI file. Make sure to use the
:option:`-n` option to specify a foreign main program:
.. code-block:: sh
$ gnatbind -n unit1.ali unit2.ali
* Link the Ada main program, the Ada objects and the foreign language
objects. You need only list the last ALI file here:
.. code-block:: sh
$ gnatlink unit2.ali main.o -o exec_file
This procedure yields a binary executable called :file:`exec_file`.
Depending on the circumstances (for example when your non-Ada main object
@ -3673,7 +3674,7 @@ Convention identifiers are recognized by GNAT:
function "/" (D : Distance; T : Time)
return Velocity;
pragma Import (Intrinsic, "/");
This common idiom is often programmed with a generic definition and an
explicit body. The pragma makes it simpler to introduce such declarations.
It incurs no overhead in compilation time or code size, because it is
@ -3691,7 +3692,7 @@ Convention identifiers are recognized by GNAT:
function builtin_sqrt (F : Float) return Float;
pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf");
Most of the GCC builtins are accessible this way, and as for other
import conventions (e.g. C), it is the user's responsibility to ensure
that the Ada subprogram profile matches the underlying builtin
@ -3738,7 +3739,7 @@ pragma:
.. code-block:: ada
pragma Convention_Identifier (Fortran77, Fortran);
And from now on the identifier Fortran77 may be used as a convention
identifier (for example in an `Import` pragma) with the same
meaning as Fortran.
@ -3805,7 +3806,7 @@ considered:
$ g++ -c -fkeep-inline-functions file1.C
$ g++ -c -fkeep-inline-functions file2.C
$ gnatmake ada_unit -largs file1.o file2.o --LINK=g++
* Using GNAT and G++ from two different GCC installations: If both
compilers are on the :envvar`PATH`, the previous method may be used. It is
@ -3825,7 +3826,7 @@ considered:
$ gnatbind ada_unit
$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
If there is a problem due to interfering environment variables, it can
be worked around by using an intermediate script. The following example
shows the proper script to use when GNAT has not been installed at its
@ -3839,7 +3840,7 @@ considered:
unset GCC_ROOT
c++ $*
$ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script
* Using a non-GNU C++ compiler: The commands previously described can be
used to insure that the C++ linker is used. Nonetheless, you need to add
@ -3855,7 +3856,7 @@ considered:
#!/bin/sh
CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a`
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
where CC is the name of the non-GNU C++ compiler.
@ -3871,7 +3872,7 @@ considered:
`gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \\
`gcc -print-file-name=crtend.o`
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
If the "zero cost exception" mechanism is used, and the platform
doesn't support automatic registration of exception tables (e.g., HP-UX
@ -3907,7 +3908,7 @@ Here are the compilation commands:
$ g++ -c ex7.C
$ gnatbind -n simple_cpp_interface
$ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o
Here are the corresponding sources:
.. code-block:: cpp
@ -3977,7 +3978,7 @@ Here are the corresponding sources:
a_value = 1010;
printf ("in A::A, a_value = %d \\n",a_value);
}
.. code-block:: ada
-- simple_cpp_interface.ads
@ -3998,7 +3999,7 @@ Here are the corresponding sources:
pragma Export (C, Ada_Method2);
end Simple_Cpp_Interface;
.. code-block:: ada
-- simple_cpp_interface.adb
@ -4038,7 +4039,7 @@ C++ class:
Root(int v); // 1st non-default constructor
Root(int v, int w); // 2nd non-default constructor
};
For this purpose we can write the following package spec (further
information on how to build this spec is available in
:ref:`Interfacing_with_C++_at_the_Class_Level` and
@ -4059,14 +4060,14 @@ information on how to build this spec is available in
function Constructor return Root;
pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev");
function Constructor (v : Integer) return Root;
pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei");
function Constructor (v, w : Integer) return Root;
pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii");
end Pkg_Root;
On the Ada side the constructor is represented by a function (whose
name is arbitrary) that returns the classwide type corresponding to
the imported C++ class. Although the constructor is described as a
@ -4095,7 +4096,7 @@ expression that initializes the object. For example:
Obj2 : Root := Constructor;
Obj3 : Root := Constructor (v => 10);
Obj4 : Root := Constructor (30, 40);
The first two declarations are equivalent: in both cases the default C++
constructor is invoked (in the former case the call to the constructor is
implicit, and in the latter case the call is explicit in the object
@ -4242,7 +4243,7 @@ and `Domestic` animals:
public:
virtual void Set_Owner (char* Name) = 0;
};
Using these declarations, we can now say that a `Dog` is an animal that is
both Carnivore and Domestic, that is:
@ -4309,7 +4310,7 @@ how to import these C++ declarations from the Ada side:
pragma CPP_Constructor (New_Dog);
pragma Import (CPP, New_Dog, "_ZN3DogC2Ev");
end Animals;
Thanks to the compatibility between GNAT run-time structures and the C++ ABI,
interfacing with these C++ classes is easy. The only requirement is that all
the primitives and components must be declared exactly in the same order in
@ -4398,7 +4399,7 @@ them to C++, using the same hierarchy of our previous example:
function New_Dog return Dog'Class;
pragma Export (C_Plus_Plus, New_Dog);
end Animals;
Compared with our previous example the only differences are the use of
`pragma Convention` (instead of `pragma Import`), and the use of
`pragma Export` to indicate to the GNAT compiler that the primitives will
@ -4442,7 +4443,7 @@ finalizing the Ada run-time system along the way:
adainit (); test(); adafinal ();
return 0;
}
.. _Generating_Ada_Bindings_for_C_and_C++_headers:
Generating Ada Bindings for C and C++ headers
@ -4487,7 +4488,7 @@ header files needed by these files transitively. For example:
$ g++ -c -fdump-ada-spec -C /usr/include/time.h
$ gcc -c -gnat05 *.ads
will generate, under GNU/Linux, the following files: :file:`time_h.ads`,
:file:`bits_time_h.ads`, :file:`stddef_h.ads`, :file:`bits_types_h.ads` which
correspond to the files :file:`/usr/include/time.h`,
@ -4530,7 +4531,7 @@ generating a generic:
.. code-block:: ada
procedure foo (param1 : int);
with the C++ front-end, the name is available, and we generate:
.. code-block:: ada
@ -4615,7 +4616,7 @@ For example, given the following C++ header file:
Dog();
};
The corresponding Ada code is generated:
.. code-block:: ada
@ -4668,7 +4669,7 @@ The corresponding Ada code is generated:
pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
end;
use Class_Dog;
.. _Switches_for_Ada_Binding_Generation:
@ -4928,7 +4929,7 @@ we have the following package spec:
package QRS is
MN : Integer;
end QRS;
.. index:: pragma Export
The variable `MN` has a full expanded Ada name of `QRS.MN`, so
@ -4943,7 +4944,7 @@ Of course if a `pragma Export` is used this may be overridden:
Var2 : Integer;
pragma Export (Var2, C, Link_Name => "var2_link_name");
end Exports;
In this case, the link name for `Var1` is whatever link name the
C compiler would assign for the C function `var1_name`. This typically
would be either `var1_name` or `_var1_name`, depending on operating
@ -4964,4 +4965,3 @@ names. So if we have a library level procedure such as:
procedure Hello (S : String);
the external name of this procedure will be `_ada_hello`.

1563
gcc/ada/gnat_rm.texi
View File

File diff suppressed because it is too large Load Diff

622
gcc/ada/gnat_ugn.texi
View File

File diff suppressed because it is too large Load Diff