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

* gnat_rm.texi, gnat_ugn.texi, doc: Documentation updates and clean ups 

From-SVN: r223079
This commit is contained in:
Arnaud Charlet 2015-05-12 17:19:25 +02:00
parent 69031b4545
commit 74e9ae980d
8 changed files with 743 additions and 702 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -201,6 +201,16 @@ characters in this context).
See section 'Performing Dimensionality Analysis in GNAT' in the GNAT Users
Guide for detailed examples of use of the dimension system.
Aspect Disable_Controlled
=========================
.. index:: Disable_Controlled
The aspect `Disable_Controlled` is defined for controlled record types. If
active, this aspect causes suppression of all related calls to `Initialize`,
`Adjust`, and `Finalize`. The intended use is for conditional compilation,
where for example you might want a record to be controlled or not depending on
whether some run-time check is enabled or suppressed.
Aspect Effective_Reads
======================
.. index:: Effective_Reads
@ -511,6 +521,12 @@ Aspect Value_Size
This aspect is equivalent to a `Value_Size`
attribute definition clause.
Aspect Volatile_Full_Access
===========================
.. index:: Volatile_Full_Access
This boolean aspect is equivalent to pragma `Volatile_Full_Access`.
Aspect Warnings
===============
.. index:: Warnings

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

@ -793,10 +793,6 @@ range). The result is static for static subtypes. `Range_Length`
applied to the index subtype of a one dimensional array always gives the
same result as `Length` applied to the array itself.
Attribute Ref
=============
.. index:: Ref
Attribute Restriction_Set
=========================
.. index:: Restriction_Set

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

@ -6583,6 +6583,38 @@ in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005
implementation of pragma Volatile is upwards compatible with the
implementation in DEC Ada 83.
Pragma Volatile_Full_Access
===========================
Syntax:
.. code-block:: ada
pragma Volatile_Full_Access (LOCAL_NAME);
This is similar in effect to pragma Volatile, except that any reference to the
object is guaranteed to be done only with instructions that read or write all
the bits of the object. Furthermore, if the object is of a composite type,
then any reference to a component of the object is guaranteed to read and/or
write all the bits of the object.
The intention is that this be suitable for use with memory-mapped I/O devices
on some machines. Note that there are two important respects in which this is
different from `pragma Atomic`. First a reference to a `Volatile_Full_Access`
object is not a sequential action in the RM 9.10 sense and, therefore, does
not create a synchronization point. Second, in the case of `pragma Atomic`,
there is no guarantee that all the bits will be accessed if the reference
is not to the whole object; the compiler is allowed (and generally will)
access only part of the object in this case.
It is not permissible to specify `Atomic` and `Volatile_Full_Access` for
the same object.
It is not permissible to specify `Volatile_Full_Access` for a composite
(record or array) type or object that has at least one `Aliased` component.
Pragma Warning_As_Error
=======================

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

@ -371,10 +371,10 @@ Consider the following modified version of the above program:
begin
Put_Line (Integer'Image (V2'Size));
Put_Line (Integer'IMage (Size (V2)));
Put_Line (Integer'Image (Size (V2)));
V2 := (True, 'x');
Put_Line (Integer'Image (V2'Size));
Put_Line (Integer'IMage (Size (V2)));
Put_Line (Integer'Image (Size (V2)));
end q;
The output from this program is
@ -553,11 +553,6 @@ is illegal to convert from one access subtype to the other. For a more
complete description of this additional legality rule, see the
description of the `Object_Size` attribute.
At the implementation level, Esize stores the Object_Size and the
RM_Size field stores the `Value_Size` (and hence the value of the
`Size` attribute,
which, as noted above, is equivalent to `Value_Size`).
To get a feel for the difference, consider the following examples (note
that in each case the base is `Short_Short_Integer` with a size of 8):
@ -573,15 +568,17 @@ that in each case the base is `Short_Short_Integer` with a size of 8):
+---------------------------------------------+-------------+-------------+
|``subtype x4 is x2'base range 0 .. 10;`` | 8 | 4 |
+---------------------------------------------+-------------+-------------+
|``dynamic : x2'Base range -64 .. +63;`` | | |
+---------------------------------------------+-------------+-------------+
|``subtype x5 is x2 range 0 .. dynamic;`` | 16 | 3* |
+---------------------------------------------+-------------+-------------+
|``subtype x6 is x2'base range 0 .. dynamic;``| 8 | 3* |
|``subtype x6 is x2'base range 0 .. dynamic;``| 8 | 7* |
+---------------------------------------------+-------------+-------------+
Note: the entries marked '3*' are not actually specified by the Ada
Reference Manual, but it seems in the spirit of the RM rules to allocate
the minimum number of bits (here 3, given the range for `x2`)
known to be large enough to hold the given range of values.
Note: the entries marked '*' are not actually specified by the Ada
Reference Manual, which has nothing to say about size in the dynamic
case. What GNAT does is to allocate sufficient bits to accomodate any
possible dynamic values for the bounds at run-time.
So far, so good, but GNAT has to obey the RM rules, so the question is
under what conditions must the RM `Size` be used.
@ -620,7 +617,7 @@ since it must be rounded up so that this value is a multiple of the
alignment (4 bytes = 32 bits).
For all other types, the `Object_Size`
and Value_Size are the same (and equivalent to the RM attribute `Size`).
and `Value_Size` are the same (and equivalent to the RM attribute `Size`).
Only `Size` may be specified for such types.
Note that `Value_Size` can be used to force biased representation
@ -822,7 +819,7 @@ definition clause on byte ordering. Briefly, it has no effect at all, but
a detailed example will be helpful. Before giving this
example, let us review the precise
definition of the effect of defining `Bit_Order`. The effect of a
non-standard bit order is described in section 15.5.3 of the Ada
non-standard bit order is described in section 13.5.3 of the Ada
Reference Manual:
"2 A bit ordering is a method of interpreting the meaning of
@ -840,7 +837,7 @@ this context, we visit section 13.5.1 of the manual:
The critical point here is that storage places are taken from
the values after normalization, not before. So the `Bit_Order`
interpretation applies to normalized values. The interpretation
is described in the later part of the 15.5.3 paragraph:
is described in the later part of the 13.5.3 paragraph:
"2 A bit ordering is a method of interpreting the meaning of
the storage place attributes. High_Order_First (known in the

82
gcc/ada/doc/gnat_ugn/gnat_project_manager.rst
View File

@ -300,10 +300,7 @@ locating the specified source files in the specified source directories.
However, when compiling a multi-language application, or a pure C
application, the project manager must be told which languages are of
interest, which is done by setting the **Languages** attribute to a list of
strings, each of which is the name of a language. Tools like
*gnatmake* only know about Ada, while other tools like
*gprbuild* know about many more languages such as C, C++, Fortran,
assembly and others can be added dynamically.
strings, each of which is the name of a language.
.. index:: Naming scheme (GNAT Project Manager)
@ -416,8 +413,7 @@ Its value is the path to the object directory, either absolute or
relative to the directory containing the project file. This
directory must already exist and be readable and writable, although
some tools have a switch to create the directory if needed (See
the switch `-p` for *gnatmake*
and *gprbuild*).
the switch `-p` for *gprbuild*).
If the attribute `Object_Dir` is not specified, it defaults to
the project directory, that is the directory containing the project file.
@ -569,7 +565,7 @@ packages would be involved in the build process.
for Exec_Dir use ".";
for Main use ("proc.adb");
package Builder is --<<< for gnatmake and gprbuild
package Builder is --<<< for gprbuild
end Builder;
package Compiler is --<<< for the compiler
@ -667,7 +663,7 @@ Several attributes can be used to specify the switches:
The switches for the other tools are defined in a similar manner through the
**Default_Switches** and **Switches** attributes, respectively in the
*Builder* package (for *gnatmake* and *gprbuild*),
*Builder* package (for *gprbuild*),
the *Binder* package (binding Ada executables) and the *Linker*
package (for linking executables).
@ -682,7 +678,7 @@ Here is the command we would use from the command line:
.. code-block:: sh
gnatmake -Pbuild
gprbuild -Pbuild
This will automatically build the executables specified through the
*Main* attribute: for each, it will compile or recompile the
@ -690,10 +686,9 @@ sources for which the object file does not exist or is not up-to-date; it
will then run the binder; and finally run the linker to create the
executable itself.
*gnatmake* only knows how to handle Ada files. By using
*gprbuild* as a builder, you could automatically manage C files the
The *gprbuild* builder, can automatically manage C files the
same way: create the file :file:`utils.c` in the :file:`common` directory,
set the attribute *Languages* to `"(Ada, C)"`, and run
set the attribute *Languages* to `"(Ada, C)"`, and re-run
.. code-block:: sh
@ -1226,16 +1221,10 @@ following algorithm, in this order; the first matching file is used:
Such directories depend on the tool used. The locations searched in the
specified order are:
* :file:`<prefix>/<target>/lib/gnat`
(for *gnatmake* in all cases, and for *gprbuild* if option
*--target* is specified)
* :file:`<prefix>/<target>/share/gpr`
(for *gnatmake* in all cases, and for *gprbuild* if option
*--target* is specified)
* :file:`<prefix>/<target>/lib/gnat` if option *--target* is specified
* :file:`<prefix>/<target>/share/gpr` if option *--target* is specified
* :file:`<prefix>/share/gpr/`
(for *gnatmake* and *gprbuild*)
* :file:`<prefix>/lib/gnat/`
(for *gnatmake* and *gprbuild*)
In our example, :file:`gtkada.gpr` is found in the predefined directory if
it was installed at the same root as GNAT.
@ -1486,19 +1475,13 @@ order of priority):
.. index:: -X (usage with GNAT Project Manager)
**Command line**:
When launching *gnatmake* or *gprbuild*, the user can pass
When launching *gprbuild*, the user can pass
extra *-X* switches to define the external value. In
our case, the command line might look like
::
.. code-block:: sh
gnatmake -Pbuild.gpr -Xmode=debug
or
::
gnatmake -Pbuild.gpr -Xmode=release
gprbuild -Pbuild.gpr -Xmode=release
**Environment variables**:
@ -1776,14 +1759,8 @@ of shard libraries reduces the size of the final executable and can also reduce
the memory footprint at execution time when the library is shared among several
executables.
It is also possible to build **multi-language libraries**. When using
*gprbuild* as a builder, multi-language library projects allow naturally
the creation of multi-language libraries . *gnatmake*, does not try to
compile non Ada sources. However, when the project is multi-language, it will
automatically link all object files found in the object directory, whether or
not they were compiled from an Ada source file. This specific behavior does not
apply to Ada-only projects which only take into account the objects
corresponding to the sources of the project.
*gprbuild also allows to build **multi-language libraries** when specifying
sources from multiple languages.
A non-library project can import a library project. When the builder is invoked
on the former, the library of the latter is only rebuilt when absolutely
@ -1802,11 +1779,11 @@ the following two commands need to be used:
.. code-block:: sh
gnatmake -Plogging.gpr
gnatmake -Pbuild.gpr
gprbuild -Plogging.gpr
gprbuild -Pbuild.gpr
All :file:`ALI` files will also be copied from the object directory to the
library directory. To build executables, *gnatmake* will use the
library directory. To build executables, *gprbuild* will use the
library rather than the individual object files.
Library projects can also be useful to describe a library that needs to be used
@ -2307,8 +2284,7 @@ Very often, modules will build their own executables (for testing
purposes for instance), or libraries (for easier reuse in various
contexts).
However, if you build your project through *gnatmake* or
*gprbuild*, using a syntax similar to
However, if you build your project through *gprbuild*, using a syntax similar to
::
@ -2316,9 +2292,9 @@ However, if you build your project through *gnatmake* or
this will only rebuild the main programs of project A, not those of the
imported projects B and C. Therefore you have to spawn several
*gnatmake* commands, one per project, to build all executables.
*gprbuild* commands, one per project, to build all executables.
This is a little inconvenient, but more importantly is inefficient
because *gnatmake* needs to do duplicate work to ensure that sources are
because *gprbuild* needs to do duplicate work to ensure that sources are
up-to-date, and cannot easily compile things in parallel when using
the -j switch.
@ -2349,10 +2325,6 @@ aggregate project, you will need to add "p.gpr" in the list of project
files for the aggregate project, or the main will not be built when
building the aggregate project.
Aggregate projects are supported only with *gprbuild*, not with
*gnatmake*.
.. _Building_a_set_of_projects_with_a_single_command:
Building a set of projects with a single command
@ -2463,7 +2435,7 @@ once.
Since there is no ambiguity as to which switches should be used, files
can be compiled in parallel (through the usual -j switch) and this can
be done while maximizing the use of CPUs (compared to launching
multiple *gprbuild* and *gnatmake* commands in parallel).
multiple *gprbuild* commands in parallel).
.. _Syntax_of_aggregate_projects:
@ -3118,8 +3090,8 @@ The following packages are currently supported in project files
*Binder*
This package specifies characteristics useful when invoking the binder either
directly via the *gnat* driver or when using a builder such as
*gnatmake* or *gprbuild*. See :ref:`Main_Subprograms`.
directly via the *gnat* driver or when using *gprbuild*.
See :ref:`Main_Subprograms`.
*Builder*
This package specifies the compilation options used when building an
@ -3353,7 +3325,7 @@ External Values
An external value is an expression whose value is obtained from the command
that invoked the processing of the current project file (typically a
*gnatmake* or *gprbuild* command).
*gprbuild* command).
There are two kinds of external values, one that returns a single string, and
one that returns a string list.
@ -4576,9 +4548,9 @@ Package IDE Attributes
* **Compiler_Command**: single, indexed, case-insensitive index
Index is a language Name. Value is a string that denotes the command to be
used to invoke the compiler. The value of `Compiler_Command ("Ada")` is
expected to be compatible with *gnatmake*, in particular in
the handling of switches.
used to invoke the compiler. For historical reasons, the value of
`Compiler_Command ("Ada")` is expected to be a reference to *gnatmake* or
*cross-gnatmake*.
* **Debugger_Command**: single

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

@ -4983,5 +4983,6 @@ Alternatively, you may run the script using the following command line:
* generic tests for nested generic packages and their instantiations
* tests for protected subprograms and entries
* pragma No_Run_Time
* if pragmas for C and C++ interaction are used, manual adjustments might be
necessary to make the test driver compilable

1202
gcc/ada/gnat_rm.texi
View File

File diff suppressed because it is too large Load Diff

81
gcc/ada/gnat_ugn.texi
View File

@ -21,7 +21,7 @@
@copying
@quotation
GNAT User's Guide for Native Platforms , March 24, 2015
GNAT User's Guide for Native Platforms , May 12, 2015
AdaCore
@ -17021,10 +17021,7 @@ the default naming convention.
However, when compiling a multi-language application, or a pure C
application, the project manager must be told which languages are of
interest, which is done by setting the @strong{Languages} attribute to a list of
strings, each of which is the name of a language. Tools like
@emph{gnatmake} only know about Ada, while other tools like
@emph{gprbuild} know about many more languages such as C, C++, Fortran,
assembly and others can be added dynamically.
strings, each of which is the name of a language.
@geindex Naming scheme (GNAT Project Manager)
@ -17143,8 +17140,7 @@ Its value is the path to the object directory, either absolute or
relative to the directory containing the project file. This
directory must already exist and be readable and writable, although
some tools have a switch to create the directory if needed (See
the switch @cite{-p} for @emph{gnatmake}
and @emph{gprbuild}).
the switch @cite{-p} for @emph{gprbuild}).
If the attribute @cite{Object_Dir} is not specified, it defaults to
the project directory, that is the directory containing the project file.
@ -17293,7 +17289,7 @@ packages would be involved in the build process.
@c for Exec_Dir use ".";
@c for Main use ("proc.adb");
@c
@c package Builder is --<<< for gnatmake and gprbuild
@c package Builder is --<<< for gprbuild
@c end Builder;
@c
@c package Compiler is --<<< for the compiler
@ -17397,7 +17393,7 @@ used for all the sources of the project.
The switches for the other tools are defined in a similar manner through the
@strong{Default_Switches} and @strong{Switches} attributes, respectively in the
@emph{Builder} package (for @emph{gnatmake} and @emph{gprbuild}),
@emph{Builder} package (for @emph{gprbuild}),
the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
package (for linking executables).
@ -17410,7 +17406,7 @@ Now that our project files are written, let's build our executable.
Here is the command we would use from the command line:
@example
gnatmake -Pbuild
gprbuild -Pbuild
@end example
This will automatically build the executables specified through the
@ -17419,10 +17415,9 @@ sources for which the object file does not exist or is not up-to-date; it
will then run the binder; and finally run the linker to create the
executable itself.
@emph{gnatmake} only knows how to handle Ada files. By using
@emph{gprbuild} as a builder, you could automatically manage C files the
The @emph{gprbuild} builder, can automatically manage C files the
same way: create the file @code{utils.c} in the @code{common} directory,
set the attribute @emph{Languages} to @cite{"(Ada@comma{} C)"}, and run
set the attribute @emph{Languages} to @cite{"(Ada@comma{} C)"}, and re-run
@example
gprbuild -Pbuild
@ -18034,22 +18029,16 @@ specified order are:
@itemize *
@item
@code{<prefix>/<target>/lib/gnat}
(for @emph{gnatmake} in all cases, and for @emph{gprbuild} if option
@emph{--target} is specified)
@code{<prefix>/<target>/lib/gnat} if option @emph{--target} is specified
@item
@code{<prefix>/<target>/share/gpr}
(for @emph{gnatmake} in all cases, and for @emph{gprbuild} if option
@emph{--target} is specified)
@code{<prefix>/<target>/share/gpr} if option @emph{--target} is specified
@item
@code{<prefix>/share/gpr/}
(for @emph{gnatmake} and @emph{gprbuild})
@item
@code{<prefix>/lib/gnat/}
(for @emph{gnatmake} and @emph{gprbuild})
@end itemize
In our example, @code{gtkada.gpr} is found in the predefined directory if
@ -18318,18 +18307,12 @@ order of priority):
@item @strong{Command line}:
When launching @emph{gnatmake} or @emph{gprbuild}, the user can pass
When launching @emph{gprbuild}, the user can pass
extra @emph{-X} switches to define the external value. In
our case, the command line might look like
@example
gnatmake -Pbuild.gpr -Xmode=debug
@end example
or
@example
gnatmake -Pbuild.gpr -Xmode=release
gprbuild -Pbuild.gpr -Xmode=release
@end example
@item @strong{Environment variables}:
@ -18639,14 +18622,8 @@ of shard libraries reduces the size of the final executable and can also reduce
the memory footprint at execution time when the library is shared among several
executables.
It is also possible to build @strong{multi-language libraries}. When using
@emph{gprbuild} as a builder, multi-language library projects allow naturally
the creation of multi-language libraries . @emph{gnatmake}, does not try to
compile non Ada sources. However, when the project is multi-language, it will
automatically link all object files found in the object directory, whether or
not they were compiled from an Ada source file. This specific behavior does not
apply to Ada-only projects which only take into account the objects
corresponding to the sources of the project.
@emph{gprbuild also allows to build **multi-language libraries*} when specifying
sources from multiple languages.
A non-library project can import a library project. When the builder is invoked
on the former, the library of the latter is only rebuilt when absolutely
@ -18664,12 +18641,12 @@ up to date, and that all the sources of @cite{Build} are also up to date,
the following two commands need to be used:
@example
gnatmake -Plogging.gpr
gnatmake -Pbuild.gpr
gprbuild -Plogging.gpr
gprbuild -Pbuild.gpr
@end example
All @code{ALI} files will also be copied from the object directory to the
library directory. To build executables, @emph{gnatmake} will use the
library directory. To build executables, @emph{gprbuild} will use the
library rather than the individual object files.
Library projects can also be useful to describe a library that needs to be used
@ -19210,8 +19187,7 @@ Very often, modules will build their own executables (for testing
purposes for instance), or libraries (for easier reuse in various
contexts).
However, if you build your project through @emph{gnatmake} or
@emph{gprbuild}, using a syntax similar to
However, if you build your project through @emph{gprbuild}, using a syntax similar to
@example
gprbuild -PA.gpr
@ -19219,9 +19195,9 @@ gprbuild -PA.gpr
this will only rebuild the main programs of project A, not those of the
imported projects B and C. Therefore you have to spawn several
@emph{gnatmake} commands, one per project, to build all executables.
@emph{gprbuild} commands, one per project, to build all executables.
This is a little inconvenient, but more importantly is inefficient
because @emph{gnatmake} needs to do duplicate work to ensure that sources are
because @emph{gprbuild} needs to do duplicate work to ensure that sources are
up-to-date, and cannot easily compile things in parallel when using
the -j switch.
@ -19252,9 +19228,6 @@ aggregate project, you will need to add "p.gpr" in the list of project
files for the aggregate project, or the main will not be built when
building the aggregate project.
Aggregate projects are supported only with @emph{gprbuild}, not with
@emph{gnatmake}.
@node Building a set of projects with a single command,Define a build environment,Building all main programs from a single project tree,Aggregate Projects
@anchor{gnat_ugn/gnat_project_manager building-a-set-of-projects-with-a-single-command}@anchor{184}@anchor{gnat_ugn/gnat_project_manager id29}@anchor{185}
@subsection Building a set of projects with a single command
@ -19363,7 +19336,7 @@ once.
Since there is no ambiguity as to which switches should be used, files
can be compiled in parallel (through the usual -j switch) and this can
be done while maximizing the use of CPUs (compared to launching
multiple @emph{gprbuild} and @emph{gnatmake} commands in parallel).
multiple @emph{gprbuild} commands in parallel).
@node Syntax of aggregate projects,package Builder in aggregate projects,Performance improvements in builder,Aggregate Projects
@anchor{gnat_ugn/gnat_project_manager id32}@anchor{18a}@anchor{gnat_ugn/gnat_project_manager syntax-of-aggregate-projects}@anchor{18b}
@ -20141,8 +20114,8 @@ The following packages are currently supported in project files
@item @emph{Binder}
This package specifies characteristics useful when invoking the binder either
directly via the @emph{gnat} driver or when using a builder such as
@emph{gnatmake} or @emph{gprbuild}. See @ref{15d,,Main Subprograms}.
directly via the @emph{gnat} driver or when using @emph{gprbuild}.
See @ref{15d,,Main Subprograms}.
@item @emph{Builder}
@ -20402,7 +20375,7 @@ Illegal := "gnat.adc" & List2; -- Illegal, must start with list
An external value is an expression whose value is obtained from the command
that invoked the processing of the current project file (typically a
@emph{gnatmake} or @emph{gprbuild} command).
@emph{gprbuild} command).
There are two kinds of external values, one that returns a single string, and
one that returns a string list.
@ -21882,9 +21855,9 @@ in a cross-compilation environment, for example @cite{"wtx"} or
@strong{Compiler_Command}: single, indexed, case-insensitive index
Index is a language Name. Value is a string that denotes the command to be
used to invoke the compiler. The value of @cite{Compiler_Command ("Ada")} is
expected to be compatible with @emph{gnatmake}, in particular in
the handling of switches.
used to invoke the compiler. For historical reasons, the value of
@cite{Compiler_Command ("Ada")} is expected to be a reference to @emph{gnatmake} or
@emph{cross-gnatmake}.
@item
@strong{Debugger_Command}: single