Skip to content

R
riscv-gcc-1
Commit 33c51287 by Arnaud Charlet Committed by Arnaud Charlet
Options

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

	* 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
parent b5f3c913
Showing with 420 additions and 215 deletions
gcc/ada/ChangeLog
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.
......
gcc/ada/doc/gnat_rm.rst
......@@ -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}@*
......
gcc/ada/doc/gnat_rm/about_this_guide.rst
......@@ -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
===================
......
gcc/ada/doc/gnat_rm/compatibility_and_porting_guide.rst
......@@ -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.
gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst
......@@ -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
......
gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst
......@@ -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
......
gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst
......@@ -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
======================
......
gcc/ada/doc/gnat_rm/implementation_of_ada_2012_features.rst
......@@ -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)
......
gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst
......@@ -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.
gcc/ada/doc/gnat_rm/obsolescent_features.rst
......@@ -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`.
......
gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst
......@@ -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
--------------------
......
gcc/ada/doc/gnat_rm/standard_library_routines.rst
......@@ -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.
gcc/ada/doc/gnat_rm/the_gnat_library.rst
......@@ -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`)
......
gcc/ada/doc/gnat_ugn/about_this_guide.rst
......@@ -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.
gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
......@@ -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`
......
gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst
......@@ -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.
......
gcc/ada/doc/gnat_ugn/example_of_binder_output.rst
......@@ -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).
gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst
......@@ -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.
gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst
......@@ -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.
......
gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
......@@ -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.
gcc/ada/doc/gnat_ugn/inline_assembler.rst
......@@ -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.
......
gcc/ada/doc/gnat_ugn/platform_specific_information.rst
......@@ -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>`):
::
......
gcc/ada/gnat_rm.texi
This source diff could not be displayed because it is too large. You can view the blob instead.
gcc/ada/gnat_ugn.texi
This source diff could not be displayed because it is too large. You can view the blob instead.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment