mirror/gcc
2
0
Fork 0
mirror of git://gcc.gnu.org/git/gcc.git synced 2025-04-04 23:01:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

gnat_rm.texi, [...]: Update documentation.

Browse Source 
* gnat_rm.texi, gnat_ugn.texi,
	doc/gnat_ugn/building_executable_programs_with_gnat.rst,
	doc/gnat_ugn/platform_specific_information.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/the_gnat_library.rst,
	doc/gnat_rm/implementation_defined_pragmas.rst,
	doc/gnat_rm/representation_clauses_and_pragmas.rst,
	doc/gnat_rm/implementation_of_specific_ada_features.rst,
	doc/gnat_rm/implementation_defined_aspects.rst,
	doc/gnat_rm/implementation_defined_characteristics.rst: Update
	documentation.

From-SVN: r247253
This commit is contained in:
Arnaud Charlet 2017-04-25 15:59:28 +00:00 committed by Arnaud Charlet
parent 211e7410b3
commit 9c533e7dfb
14 changed files with 1623 additions and 1372 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

17
gcc/ada/ChangeLog
View File

@ -1,3 +1,20 @@
2017-04-25 Arnaud Charlet <charlet@adacore.com>
* gnat_rm.texi, gnat_ugn.texi,
doc/gnat_ugn/building_executable_programs_with_gnat.rst,
doc/gnat_ugn/platform_specific_information.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/the_gnat_library.rst,
doc/gnat_rm/implementation_defined_pragmas.rst,
doc/gnat_rm/representation_clauses_and_pragmas.rst,
doc/gnat_rm/implementation_of_specific_ada_features.rst,
doc/gnat_rm/implementation_defined_aspects.rst,
doc/gnat_rm/implementation_defined_characteristics.rst: Update
documentation.
2017-04-25 Arnaud Charlet <charlet@adacore.com>
* exp_ch4.adb (Expand_N_Case_Expression): Emit error message when

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

@ -66,8 +66,9 @@ Aspect Abstract_State
This aspect is equivalent to :ref:`pragma Abstract_State<Pragma-Abstract_State>`.
Annotate
========
Aspect Annotate
===============
.. index:: Annotate
There are three forms of this aspect (where ID is an identifier,
@ -147,7 +148,7 @@ used when doing formatted output of dimensioned quantities. The syntax is::
This aspect can only be applied to a subtype whose parent type has
a `Dimension_Systen` aspect. The aspect must specify values for
a `Dimension_System` aspect. The aspect must specify values for
all dimensions of the system. The rational values are the powers of the
corresponding dimensions that are used by the compiler to verify that
physical (numeric) computations are dimensionally consistent. For example,
@ -361,7 +362,6 @@ 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>`.

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

@ -1168,7 +1168,7 @@ used in contexts (e.g., preelaborable packages) which require a
static expression and where the function call could not be used
(since the function call is always nonstatic, even if its
argument is static). The argument must be in the range
-(2**(m-1) .. 2**m-1, where m is the memory size
-(2**(m-1)) .. 2**m-1, where m is the memory size
(typically 32 or 64). Negative values are intepreted in a
modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on
a 32 bits machine).

8
gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst
View File

@ -986,13 +986,13 @@ The policy is the same as that of the underlying threads implementation.
in a pragma `Locking_Policy`. See D.3(4)."
The two implementation defined policies permitted in GNAT are
`Inheritance_Locking` and `Conccurent_Readers_Locking`. On
`Inheritance_Locking` and `Concurrent_Readers_Locking`. On
targets that support the `Inheritance_Locking` policy, locking is
implemented by inheritance, i.e., the task owning the lock operates
at a priority equal to the highest priority of any task currently
requesting the lock. On targets that support the
`Conccurent_Readers_Locking` policy, locking is implemented with a
read/write lock allowing multiple propected object functions to enter
requesting the lock. On targets that support the
`Concurrent_Readers_Locking` policy, locking is implemented with a
read/write lock allowing multiple protected object functions to enter
concurrently.
*

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

@ -564,7 +564,7 @@ Syntax:
.. code-block:: ada
pragma Asynch_Readers [ (boolean_EXPRESSION) ];
pragma Asynch_Readers [ (boolean_EXPRESSION) ];
For the semantics of this pragma, see the entry for aspect `Async_Readers` in
the SPARK 2014 Reference Manual, section 7.1.2.
@ -578,7 +578,7 @@ Syntax:
.. code-block:: ada
pragma Asynch_Writers [ (boolean_EXPRESSION) ];
pragma Asynch_Writers [ (boolean_EXPRESSION) ];
For the semantics of this pragma, see the entry for aspect `Async_Writers` in
the SPARK 2014 Reference Manual, section 7.1.2.
@ -1203,9 +1203,9 @@ following is an example of use within a package spec:
package Math_Functions is
...
function Sqrt (Arg : Float) return Float;
pragma Contract_Cases ((Arg in 0 .. 99) => Sqrt'Result < 10,
Arg >= 100 => Sqrt'Result >= 10,
others => Sqrt'Result = 0);
pragma Contract_Cases (((Arg in 0.0 .. 99.0) => Sqrt'Result < 10.0,
Arg >= 100.0 => Sqrt'Result >= 10.0,
others => Sqrt'Result = 0.0));
...
end Math_Functions;
@ -1380,6 +1380,21 @@ This pragma is standard in Ada 2012, but is available in all earlier
versions of Ada as an implementation-defined pragma.
See Ada 2012 Reference Manual for details.
Pragma Deadline_Floor
=====================
Syntax:
.. code-block:: ada
pragma Deadline_Floor (time_span_EXPRESSION);
This pragma applies only to protected types and specifies the floor
deadline inherited by a task when the task enters a protected object.
It is effective only when the EDF scheduling policy is used.
.. _Pragma-Default_Initial_Condition:
Pragma Default_Initial_Condition
@ -1628,7 +1643,7 @@ Syntax:
.. code-block:: ada
pragma Effective_Reads [ (boolean_EXPRESSION) ];
pragma Effective_Reads [ (boolean_EXPRESSION) ];
For the semantics of this pragma, see the entry for aspect `Effective_Reads` in
the SPARK 2014 Reference Manual, section 7.1.2.
@ -2248,14 +2263,13 @@ Syntax:
pragma Favor_Top_Level (type_NAME);
The named type must be an access-to-subprogram type. This pragma is an
efficiency hint to the compiler, regarding the use of 'Access or
'Unrestricted_Access on nested (non-library-level) subprograms. The
pragma means that nested subprograms are not used with this type, or
are rare, so that the generated code should be efficient in the
top-level case. When this pragma is used, dynamically generated
trampolines may be used on some targets for nested subprograms.
See also the No_Implicit_Dynamic_Code restriction.
The argument of pragma `Favor_Top_Level` must be a named access-to-subprogram
type. This pragma is an efficiency hint to the compiler, regarding the use of
`'Access` or `'Unrestricted_Access` on nested (non-library-level) subprograms.
The pragma means that nested subprograms are not used with this type, or are
rare, so that the generated code should be efficient in the top-level case.
When this pragma is used, dynamically generated trampolines may be used on some
targets for nested subprograms. See restriction `No_Implicit_Dynamic_Code`.
Pragma Finalize_Storage_Only
============================
@ -2268,11 +2282,14 @@ Syntax:
pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME);
This pragma allows the compiler not to emit a Finalize call for objects
defined at the library level. This is mostly useful for types where
finalization is only used to deal with storage reclamation since in most
environments it is not necessary to reclaim memory just before terminating
execution, hence the name.
The argument of pragma `Finalize_Storage_Only` must denote a local type which
is derived from `Ada.Finalization.Controlled` or `Limited_Controlled`. The
pragma suppresses the call to `Finalize` for declared library-level objects
of the argument type. This is mostly useful for types where finalization is
only used to deal with storage reclamation since in most environments it is
not necessary to reclaim memory just before terminating execution, hence the
name. Note that this pragma does not suppress Finalize calls for library-level
heap-allocated objects (see pragma `No_Heap_Finalization`).
Pragma Float_Representation
===========================
@ -2849,9 +2866,13 @@ Syntax:
pragma Inline_Always (NAME [, NAME]);
Similar to pragma `Inline` except that inlining is not subject to
the use of option *-gnatn* or *-gnatN* and the inlining
happens regardless of whether these options are used.
Similar to pragma `Inline` except that inlining is unconditional.
Inline_Always instructs the compiler to inline every direct call to the
subprogram or else to emit a compilation error, independently of any
option, in particular *-gnatn* or *-gnatN* or the optimization level.
It is an error to take the address or access of `NAME`. It is also an error to
apply this pragma to a primitive operation of a tagged type. Thanks to such
restrictions, the compiler is allowed to remove the out-of-line body of `NAME`.
Pragma Inline_Generic
=====================
@ -2974,7 +2995,9 @@ Interrupts can be in one of three states:
The interrupt is reserved (no Ada handler can be installed), and the
Ada run-time may not install a handler. As a result you are guaranteed
standard system default action if this interrupt is raised.
standard system default action if this interrupt is raised. This also allows
installing a low level handler via C APIs such as sigaction(), outside
of Ada control.
* Runtime
@ -2984,7 +3007,8 @@ Interrupts can be in one of three states:
* User
The interrupt is unreserved. The user may install a handler to provide
The interrupt is unreserved. The user may install an Ada handler via
Ada.Interrupts and pragma Interrupt_Handler or Attach_Handler to provide
some other action.
These states are the allowed values of the `State` parameter of the
@ -3614,12 +3638,44 @@ Syntax:
This is a program unit pragma (there is also an equivalent aspect of the
same name) that establishes the restriction `No_Elaboration_Code` for
the current unit and any extended main source units (body and subunits.
It also has has the effect of enforcing a transitive application of this
aspect, so that if any unit is implicitly or explicitly WITH'ed by the
the current unit and any extended main source units (body and subunits).
It also has the effect of enforcing a transitive application of this
aspect, so that if any unit is implicitly or explicitly with'ed by the
current unit, it must also have the No_Elaboration_Code_All aspect set.
It may be applied to package or subprogram specs or their generic versions.
Pragma No_Heap_Finalization
===========================
Syntax:
::
pragma No_Heap_Finalization [ (first_subtype_LOCAL_NAME) ];
Pragma `No_Heap_Finalization` may be used as a configuration pragma or as a
type-specific pragma.
In its configuration form, the pragma must appear within a configuration file
such as gnat.adc, without an argument. The pragma suppresses the call to
`Finalize` for heap-allocated objects created through library-level named
access-to-object types in cases where the designated type requires finalization
actions.
In its type-specific form, the argument of the pragma must denote a
library-level named access-to-object type. The pragma suppresses the call to
`Finalize` for heap-allocated objects created through the specific access type
in cases where the designated type requires finalization actions.
It is still possible to finalize such heap-allocated objects by explicitly
deallocating them.
A library-level named access-to-object type declared within a generic unit will
lose its `No_Heap_Finalization` pragma when the corresponding instance does not
appear at the library level.
Pragma No_Inline
================
@ -4855,14 +4911,16 @@ Syntax:
.. code-block:: ada
pragma Profile (Ravenscar | Restricted | Rational | GNAT_Extended_Ravenscar);
pragma Profile (Ravenscar | Restricted | Rational |
GNAT_Extended_Ravenscar | GNAT_Ravenscar_EDF );
This pragma is standard in Ada 2005, but is available in all earlier
versions of Ada as an implementation-defined pragma. This is a
configuration pragma that establishes a set of configuration pragmas
that depend on the argument. `Ravenscar` is standard in Ada 2005.
The other possibilities (`Restricted`, `Rational`, `GNAT_Extended_Ravenscar`)
The other possibilities (`Restricted`, `Rational`,
`GNAT_Extended_Ravenscar`, `GNAT_Ravenscar_EDF`)
are implementation-defined. The set of configuration pragmas
is defined in the following sections.
@ -4992,6 +5050,11 @@ is defined in the following sections.
The ``Max_Protected_Entries``, ``Max_Entry_Queue_Length``, and
``No_Relative_Delay`` restrictions have been removed.
* Pragma Profile (GNAT_Ravenscar_EDF)
This profile corresponds to the Ravenscar profile but using
EDF_Across_Priority as the Task_Scheduling_Policy.
* Pragma Profile (Restricted)
This profile corresponds to the GNAT restricted run time. It
@ -5536,26 +5599,26 @@ Syntax:
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
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
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
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,
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
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
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`
@ -7384,6 +7447,10 @@ also be used at any point that a pragma is allowed, and it is permissible
to have more than one such pragma in a file, allowing multiple encodings
to appear within the same file.
However, note that the pragma cannot immediately precede the relevant
wide character, because then the previous encoding will still be in
effect, causing "illegal character" errors.
The argument can be an identifier or a character literal. In the identifier
case, it is one of `HEX`, `UPPER`, `SHIFT_JIS`,
`EUC`, `UTF8`, or `BRACKETS`. In the character literal

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

@ -285,6 +285,31 @@ Note that this simple scheme preserves the relative order of the tasks
that were ready to execute in the priority queue where R has been
placed at the end.
.. Support_for_Locking_Policies
Support for Locking Policies
----------------------------
This section specifies which policies specified by pragma Locking_Policy
are supported on which platforms.
GNAT supports the standard `Ceiling_Locking` policy, and the
implementation defined `Inheritance_Locking` and
`Concurrent_Readers_Locking` policies.
`Ceiling_Locking` is supported on all platforms if the operating system
supports it. In particular, `Ceiling_Locking` is not supported on
VxWorks.
`Inheritance_Locking` is supported on
Linux,
Darwin (Mac OS X),
LynxOS 178,
and VxWorks.
`Concurrent_Readers_Locking` is supported on Linux.
Note that on Linux, `Ceiling_Locking` requires the program to be running
with root privileges. Otherwise, the policy is ignored.
.. _GNAT_Implementation_of_Shared_Passive_Packages:
GNAT Implementation of Shared Passive Packages

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

@ -1576,10 +1576,9 @@ check Alignment_Check is suppressed, or if
`pragma Restrictions (No_Elaboration_Code)` is in effect. It is also
suppressed by default on non-strict alignment machines (such as the x86).
Finally, GNAT does not permit overlaying of objects of controlled types or
composite types containing a controlled component. In most cases, the compiler
can detect an attempt at such overlays and will generate a warning at compile
time and a Program_Error exception at run time.
Finally, GNAT does not permit overlaying of objects of class-wide types. In
most cases, the compiler can detect an attempt at such overlays and will
generate a warning at compile time and a Program_Error exception at run time.
.. index:: Export

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

@ -2713,6 +2713,8 @@ of the pragma in the :title:`GNAT_Reference_manual`).
* :samp:`-gnatw.h` (holes in record layouts)
* :samp:`-gnatw.j` (late primitives of tagged types)
* :samp:`-gnatw.k` (redefinition of names in standard)
* :samp:`-gnatwl` (elaboration warnings)
@ -3186,6 +3188,24 @@ of the pragma in the :title:`GNAT_Reference_manual`).
This switch disables warnings on use of obsolescent features.
.. index:: -gnatw.j (gcc)
:samp:`-gnatw.j`
*Activate warnings on late declarations of tagged type primitives.*
This switch activates warnings on visible primitives added to a
tagged type after deriving a private extension from it.
.. index:: -gnatw.J (gcc)
:samp:`-gnatw.J`
*Suppress warnings on late declarations of tagged type primitives.*
This switch suppresses warnings on visible primitives added to a
tagged type after deriving a private extension from it.
.. index:: -gnatwk (gcc)
:samp:`-gnatwk`
@ -6114,7 +6134,7 @@ be presented in subsequent sections.
sized result, for example a function returning an unconstrained
String. There are two ways in which this secondary stack is allocated.
For most targets, the secondary stack is growing on demand and is allocated
For most targets, the secondary stack grows on demand and is allocated
as a chain of blocks in the heap. The -D option is not very
relevant. It only give some control over the size of the allocated
blocks (whose size is the minimum of the default secondary stack size value,

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

@ -3354,7 +3354,7 @@ and similarly for `Mass`, `Time`, `Electric_Current`,
The package also defines conventional names for values of each unit, for
example:
.. code-block":: ada
.. code-block:: ada
m : constant Length := 1.0;
kg : constant Mass := 1.0;

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

@ -535,20 +535,20 @@ The following switches are available for *gnatxref*:
.. index:: --version (gnatxref)
:samp:`-version`
:samp:`--version`
Display Copyright and version, then exit disregarding all other options.
.. index:: --help (gnatxref)
:samp:`-help`
:samp:`--help`
If *--version* was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatxref)
:samp:`a`
:samp:`-a`
If this switch is present, `gnatfind` and `gnatxref` will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
@ -559,7 +559,7 @@ The following switches are available for *gnatxref*:
.. index:: -aIDIR (gnatxref)
:samp:`aI{DIR}`
:samp:`-aI{DIR}`
When looking for source files also look in directory DIR. The order in which
source file search is undertaken is the same as for *gnatmake*.
@ -567,26 +567,26 @@ The following switches are available for *gnatxref*:
.. index:: -aODIR (gnatxref)
:samp:`aO{DIR}`
When searching for library and object files, look in directory
When -searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
*gnatmake*.
.. index:: -nostdinc (gnatxref)
:samp:`nostdinc`
:samp:`-nostdinc`
Do not look for sources in the system default directory.
.. index:: -nostdlib (gnatxref)
:samp:`nostdlib`
:samp:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --ext (gnatxref)
:samp:`-ext={extension}`
:samp:`--ext={extension}`
Specify an alternate ali file extension. The default is `ali` and other
extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*)
may be specified via this switch. Note that if this switch overrides the
@ -595,21 +595,21 @@ The following switches are available for *gnatxref*:
.. index:: --RTS (gnatxref)
:samp:`-RTS={rts-path}`
:samp:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
.. index:: -d (gnatxref)
:samp:`d`
:samp:`-d`
If this switch is set `gnatxref` will output the parent type
reference for each matching derived types.
.. index:: -f (gnatxref)
:samp:`f`
:samp:`-f`
If this switch is set, the output file names will be preceded by their
directory (if the file was found in the search path). If this switch is
not set, the directory will not be printed.
@ -617,7 +617,7 @@ The following switches are available for *gnatxref*:
.. index:: -g (gnatxref)
:samp:`g`
:samp:`-g`
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
`gnatfind` and `gnatxref`.
@ -625,30 +625,28 @@ The following switches are available for *gnatxref*:
.. index:: -IDIR (gnatxref)
:samp:`I{DIR}`
:samp:`-I{DIR}`
Equivalent to :samp:`-aODIR -aIDIR`.
.. index:: -pFILE (gnatxref)
:samp:`p{FILE}`
Specify a project file to use.
:samp:`-p{FILE}`
Specify a configuration file to use to list the source and object directories.
By default, `gnatxref` and `gnatfind` will try to locate a
project file in the current directory.
If a file is specified, then the content of the source directory and object
directory lines are added as if they had been specified respectively
by :samp:`-aI` and :samp:`-aO`.
If a project file is either specified or found by the tools, then the content
of the source directory and object directory lines are added as if they
had been specified respectively by :samp:`-aI`
and :samp:`-aO`.
See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
of this configuration file.
:samp:`u`
:samp:`-u`
Output only unused symbols. This may be really useful if you give your
main compilation unit on the command line, as `gnatxref` will then
display every unused entity and 'with'ed package.
:samp:`v`
:samp:`-v`
Instead of producing the default output, `gnatxref` will generate a
:file:`tags` file that can be used by vi. For examples how to use this
feature, see :ref:`Examples_of_gnatxref_Usage`. The tags file is output
@ -719,7 +717,6 @@ with the following iterpretation of the command arguments:
Note that if you specify at least one file in this part, `gnatfind` may
sometimes not be able to find the body of the subprograms.
At least one of 'sourcefile' or 'pattern' has to be present on
the command line.
@ -733,14 +730,14 @@ The following switches are available:
.. index:: --help (gnatfind)
:samp:`-help`
:samp:`--help`
If *--version* was not used, display usage, then exit disregarding
all other options.
.. index:: -a (gnatfind)
:samp:`a`
:samp:`-a`
If this switch is present, `gnatfind` and `gnatxref` will parse
the read-only files found in the library search path. Otherwise, these files
will be ignored. This option can be used to protect Gnat sources or your own
@ -751,14 +748,14 @@ The following switches are available:
.. index:: -aIDIR (gnatfind)
:samp:`aI{DIR}`
:samp:`-aI{DIR}`
When looking for source files also look in directory DIR. The order in which
source file search is undertaken is the same as for *gnatmake*.
.. index:: -aODIR (gnatfind)
:samp:`aO{DIR}`
:samp:`-aO{DIR}`
When searching for library and object files, look in directory
DIR. The order in which library files are searched is the same as for
*gnatmake*.
@ -766,19 +763,19 @@ The following switches are available:
.. index:: -nostdinc (gnatfind)
:samp:`nostdinc`
:samp:`-nostdinc`
Do not look for sources in the system default directory.
.. index:: -nostdlib (gnatfind)
:samp:`nostdlib`
:samp:`-nostdlib`
Do not look for library files in the system default directory.
.. index:: --ext (gnatfind)
:samp:`-ext={extension}`
:samp:`--ext={extension}`
Specify an alternate ali file extension. The default is `ali` and other
extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*)
may be specified via this switch. Note that if this switch overrides the
@ -787,21 +784,21 @@ The following switches are available:
.. index:: --RTS (gnatfind)
:samp:`-RTS={rts-path}`
:samp:`--RTS={rts-path}`
Specifies the default location of the runtime library. Same meaning as the
equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`).
.. index:: -d (gnatfind)
:samp:`d`
:samp:`-d`
If this switch is set, then `gnatfind` will output the parent type
reference for each matching derived types.
.. index:: -e (gnatfind)
:samp:`e`
:samp:`-e`
By default, `gnatfind` accept the simple regular expression set for
`pattern`. If this switch is set, then the pattern will be
considered as full Unix-style regular expression.
@ -809,7 +806,7 @@ The following switches are available:
.. index:: -f (gnatfind)
:samp:`f`
:samp:`-f`
If this switch is set, the output file names will be preceded by their
directory (if the file was found in the search path). If this switch is
not set, the directory will not be printed.
@ -817,7 +814,7 @@ The following switches are available:
.. index:: -g (gnatfind)
:samp:`g`
:samp:`-g`
If this switch is set, information is output only for library-level
entities, ignoring local entities. The use of this switch may accelerate
`gnatfind` and `gnatxref`.
@ -825,26 +822,25 @@ The following switches are available:
.. index:: -IDIR (gnatfind)
:samp:`I{DIR}`
:samp:`-I{DIR}`
Equivalent to :samp:`-aODIR -aIDIR`.
.. index:: -pFILE (gnatfind)
:samp:`p{FILE}`
Specify a project file.
By default, `gnatxref` and `gnatfind` will try to locate a
project file in the current directory.
:samp:`-p{FILE}`
Specify a configuration file to use to list the source and object directories.
If a project file is either specified or found by the tools, then the content
of the source directory and object directory lines are added as if they
had been specified respectively by :samp:`-aI` and
:samp:`-aO`.
If a file is specified, then the content of the source directory and object
directory lines are added as if they had been specified respectively
by :samp:`-aI` and :samp:`-aO`.
See :ref:`Configuration_Files_for_gnatxref_and_gnatfind` for the syntax
of this configuration file.
.. index:: -r (gnatfind)
:samp:`r`
:samp:`-r`
By default, `gnatfind` will output only the information about the
declaration, body or type completion of the entities. If this switch is
set, the `gnatfind` will locate every reference to the entities in
@ -854,14 +850,14 @@ The following switches are available:
.. index:: -s (gnatfind)
:samp:`s`
:samp:`-s`
If this switch is set, then `gnatfind` will output the content
of the Ada source file lines were the entity was found.
.. index:: -t (gnatfind)
:samp:`t`
:samp:`-t`
If this switch is set, then `gnatfind` will output the type hierarchy for
the specified type. It act like -d option but recursively from parent
type to parent type. When this switch is set it is not possible to
@ -877,28 +873,16 @@ As stated previously, gnatfind will search in every directory in the
search path. You can force it to look only in the current directory if
you specify `*` at the end of the command line.
.. _Project_Files_for_gnatxref_and_gnatfind:
.. _Configuration_Files_for_gnatxref_and_gnatfind:
Project Files for *gnatxref* and *gnatfind*
-------------------------------------------
Configuration Files for *gnatxref* and *gnatfind*
-------------------------------------------------
Project files allow a programmer to specify how to compile its
application, where to find sources, etc. These files are used
primarily by GPS, but they can also be used
by the two tools `gnatxref` and `gnatfind`.
Configuration files are used by `gnatxref` and `gnatfind` to specify
the list of source and object directories to consider. They can be
specified via the :samp:`-p` switch.
A project file name must end with :file:`.gpr`. If a single one is
present in the current directory, then `gnatxref` and `gnatfind` will
extract the information from it. If multiple project files are found, none of
them is read, and you have to use the :samp:`-p` switch to specify the one
you want to use.
The following lines can be included, even though most of them have default
values which can be used in most cases.
The lines can be entered in any order in the file.
Except for :file:`src_dir` and :file:`obj_dir`, you can only have one instance of
each line. If you have multiple instances, only the last one is taken into
account.
The following lines can be included, in any order in the file:
* *src_dir=DIR*
[default: `"./"`].
@ -906,66 +890,13 @@ account.
lines can be specified and they will be searched in the order they
are specified.
* *obj_dir=DIR*
[default: `"./"`].
Specifies a directory where to look for object and library files. Multiple
`obj_dir` lines can be specified, and they will be searched in the order
they are specified
* *comp_opt=SWITCHES*
[default: `""`].
Creates a variable which can be referred to subsequently by using
the `${comp_opt}` notation. This is intended to store the default
switches given to *gnatmake* and *gcc*.
* *bind_opt=SWITCHES*
[default: `""`].
Creates a variable which can be referred to subsequently by using
the :samp:`${bind_opt}` notation. This is intended to store the default
switches given to *gnatbind*.
* *link_opt=SWITCHES*
[default: `""`].
Creates a variable which can be referred to subsequently by using
the :samp:`${link_opt}` notation. This is intended to store the default
switches given to *gnatlink*.
* *main=EXECUTABLE*
[default: `""`].
Specifies the name of the executable for the application. This variable can
be referred to in the following lines by using the :samp:`{${main}` notation.
* *comp_cmd=COMMAND*
[default: `"gcc -c -I${src_dir} -g -gnatq"`].
Specifies the command used to compile a single file in the application.
* *make_cmd=COMMAND*
[default: `"gnatmake ${main} -aI${src_dir}
-aO${obj_dir} -g -gnatq -cargs ${comp_opt}
-bargs ${bind_opt} -largs ${link_opt}"`].
Specifies the command used to recompile the whole application.
* *run_cmd=COMMAND*
[default: `"${main}"`].
Specifies the command used to run the application.
* *debug_cmd=COMMAND*
[default: `"gdb ${main}"`].
Specifies the command used to debug the application
*gnatxref* and *gnatfind* only take into account the
`src_dir` and `obj_dir` lines, and ignore the others.
Any other line will be silently ignored.
.. _Regular_Expressions_in_gnatfind_and_gnatxref:
@ -3316,7 +3247,8 @@ Alternatively, you may run the script using the following command line:
:samp:`--par_threshold={nnn}`
If the number of parameter specifications is greater than `nnn`
(or equal to `nnn` in case of a function), start each specification from
a new line. This feature is disabled by default.
a new line. If `nnn` is 0, and `--no-separate-is` was not specified, then
the "is" is placed on a separate line. This feature is disabled by default.
.. _Setting_the_Source_Search_Path:
@ -4356,6 +4288,10 @@ Alternatively, you may run the script using the following command line:
:samp:`-r`
Recursively considers all sources from all projects.
.. index:: -files (gnattest)
:samp:`-files={filename}`
The name of a text file containing a list of Ada source files to process.
.. index:: --RTS (gnattest)
@ -4625,7 +4561,7 @@ Alternatively, you may run the script using the following command line:
::
$ cd obj/driver
$ gnatmake -Ptest_driver
$ gprbuild -Ptest_driver
$ test_runner
One failed test with the diagnosis "test not implemented" is reported.
@ -4852,7 +4788,7 @@ Alternatively, you may run the script using the following command line:
Testing with Contracts
----------------------
*gnattest* supports pragmas *Precondition*, *Postcondition*, and *Test_Case*,
*gnattest* supports pragmas *Pre*, *Post*, and *Test_Case*,
as well as the corresponding Ada 2012 aspects.
Test routines are generated, one per each *Test_Case* associated with a tested
subprogram. Those test routines have special wrappers for tested functions
@ -5002,6 +4938,29 @@ Alternatively, you may run the script using the following command line:
attempting to use this powerful feature.
.. _Gnatcov_Integration:
Integration with GNATcoverage
-----------------------------
In addition to the harness, *gnattest* generates a Makefile. This Makefile
provides targets for building the test drivers and also the targets for
computing the coverage information using GNATcoverage framework when this
coverage analysis tool is available. The target ``coverage`` fully automates
the process: it will first build all test drivers, then run them under
GNATcoverage, analyze individual trace files, and finally aggregate them:
::
make coverage
GNATcoverage options, such as coverage criteria and generated report format,
can be adjusted using Makefile variables provided for this purpose.
Note that coverage targets are not generated in the Makefile when
--separate-drivers=test is passed to gnattest.
.. _Putting_Tests_under_Version_Control:
Putting Tests under Version Control
@ -5075,10 +5034,12 @@ Alternatively, you may run the script using the following command line:
from projects imported either directly or indirectly by ``proj``.
Otherwise this option has no effect.
:samp:`-U {main_unit}`
:samp:`-U {source_file}`
Similar to :samp:`-U`, but if no sources are specified then
process only those source files for units in the closure of
`main_unit`.
the Ada source contained in `source_file`. Note that this option
expects the source file name but not the Ada unit name as its
parameter.
:samp:`-X{name}={val}`
Indicates that the external variable ``name`` in the project has the

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

@ -237,6 +237,20 @@ value greater than 0.0, or else use the corresponding *-T*
binder option.
To make sure a program is running as root, you can put something like
this in a library package body in your application:
.. code-block:: ada
function geteuid return Integer;
pragma Import (C, geteuid, "geteuid");
Ignore : constant Boolean :=
(if geteuid = 0 then True else raise Program_Error with "must be root");
It gets the effective user id, and if it's not 0 (i.e. root), it raises
Program_Error.
.. index:: Solaris Sparc threads libraries
.. _Solaris-Specific_Considerations:
@ -2215,7 +2229,7 @@ This setting can be done with *gnatlink* using either of the following:
This sets the stack reserve size to 0x1000000 bytes. Note that with
*-Wl* option it is not possible to set the stack commit size
because the coma is a separator for this option.
because the comma is a separator for this option.
.. _Setting_Heap_Size_from_gnatlink:
@ -2244,7 +2258,7 @@ Under Windows systems, it is possible to specify the program heap size from
This sets the heap reserve size to 0x1000000 bytes. Note that with
*-Wl* option it is not possible to set the heap commit size
because the coma is a separator for this option.
because the comma is a separator for this option.
.. _Win32_Specific_Addons:

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

@ -2796,9 +2796,9 @@ The preprocessing language allows such constructs as
.. code-block:: c
#if DEBUG or else (PRIORITY > 4) then
bunch of declarations
sequence of declarations
#else
completely different bunch of declarations
completely different sequence of declarations
#end if;
The values of the symbols `DEBUG` and `PRIORITY` can be
@ -2806,7 +2806,7 @@ defined either on the command line or in a separate file.
The other way of running the preprocessor is even closer to the C style and
often more convenient. In this approach the preprocessing is integrated into
the compilation process. The compiler is fed the preprocessor input which
the compilation process. The compiler is given the preprocessor input which
includes `#if` lines etc, and then the compiler carries out the
preprocessing internally and processes the resulting output.
For more details on this approach, see :ref:`Integrated_Preprocessing`.
@ -2831,8 +2831,8 @@ For further discussion of conditional compilation in general, see
Preprocessing Symbols
^^^^^^^^^^^^^^^^^^^^^
Preprocessing symbols are defined in definition files and referred to in
sources to be preprocessed. A Preprocessing symbol is an identifier, following
Preprocessing symbols are defined in *definition files* and referenced in the
sources to be preprocessed. A preprocessing symbol is an identifier, following
normal Ada (case-insensitive) rules for its syntax, with the restriction that
all characters need to be in the ASCII set (no accented letters).
@ -2859,7 +2859,7 @@ where
* *outfile*
is the full name of the output file, which is an Ada source
in standard Ada form. When used with GNAT, this file name will
normally have an ads or adb suffix.
normally have an *ads* or *adb* suffix.
* *deffile*
is the full name of a text file containing definitions of
@ -2880,7 +2880,7 @@ Switches for `gnatprep`
.. index:: --help (gnatprep)
:samp:`--help`
If *--version* was not used, display usage, then exit disregarding
If :option:`--version` was not used, display usage and then exit disregarding
all other options.
.. index:: -b (gnatprep)
@ -2904,15 +2904,15 @@ Switches for `gnatprep`
Causes comments to be scanned. Normally comments are ignored by gnatprep.
If this option is specified, then comments are scanned and any $symbol
substitutions performed as in program text. This is particularly useful
when structured comments are used (e.g., when writing programs in the
SPARK dialect of Ada). Note that this switch is not available when
doing integrated preprocessing (it would be useless in this context
since comments are ignored by the compiler in any case).
when structured comments are used (e.g., for programs written in a
pre-2014 version of the SPARK Ada subset). Note that this switch is not
available when doing integrated preprocessing (it would be useless in
this context since comments are ignored by the compiler in any case).
.. index:: -D (gnatprep)
:samp:`-D{symbol}={value}`
Defines a new preprocessing symbol, associated with value. If no value is given
:samp:`-D{symbol}[={value}]`
Defines a new preprocessing symbol with the specified value. If no value is given
on the command line, then symbol is considered to be `True`. This switch
can be used in place of a definition file.
@ -3119,84 +3119,134 @@ and then the substitution will occur as desired.
Integrated Preprocessing
------------------------
GNAT sources may be preprocessed immediately before compilation.
In this case, the actual
text of the source is not the text of the source file, but is derived from it
through a process called preprocessing. Integrated preprocessing is specified
through switches *-gnatep* and/or *-gnateD*. *-gnatep*
indicates, through a text file, the preprocessing data to be used.
:samp:`-gnateD` specifies or modifies the values of preprocessing symbol.
Note that integrated preprocessing applies only to Ada source files, it is
As noted above, a file to be preprocessed consists of Ada source code
in which preprocessing lines have been inserted. However,
instead of using *gnatprep* to explicitly preprocess a file as a separate
step before compilation, you can carry out the preprocessing implicitly
as part of compilation. Such *integrated preprocessing*, which is the common
style with C, is performed when either or both of the following switches
are passed to the compiler:
* :option:`-gnatep`, which specifies the *preprocessor data file*.
This file dictates how the source files will be preprocessed (e.g., which
symbol definition files apply to which sources).
* :option:`-gnateD`, which defines values for preprocessing symbols.
Integrated preprocessing applies only to Ada source files, it is
not available for configuration pragma files.
Note that when integrated preprocessing is used, the output from the
preprocessor is not written to any external file. Instead it is passed
internally to the compiler. If you need to preserve the result of
preprocessing in a file, then you should use *gnatprep*
to perform the desired preprocessing in stand-alone mode.
With integrated preprocessing, the output from the preprocessor is not,
by default, written to any external file. Instead it is passed
internally to the compiler. To preserve the result of
preprocessing in a file, either run *gnatprep*
in standalone mode or else supply the :option:`-gnateG` switch
(described below) to the compiler.
It is recommended that *gnatmake* switch -s should be
used when Integrated Preprocessing is used. The reason is that preprocessing
with another Preprocessing Data file without changing the sources will
not trigger recompilation without this switch.
The *gnatmake* switch :option:`-s` should be used with integrated
preprocessing; otherwise the use of a different preprocessor data file
without changing the sources will not cause recompilation.
Note that *gnatmake* switch -m will almost
Note that the *gnatmake* switch :option:`-m` will almost
always trigger recompilation for sources that are preprocessed,
because *gnatmake* cannot compute the checksum of the source after
preprocessing.
The actual preprocessing function is described in detail in section
:ref:`Preprocessing_with_gnatprep`. This section only describes how integrated
preprocessing is triggered and parameterized.
The actual preprocessing function is described in detail in
:ref:`Preprocessing_with_gnatprep`. This section explains the switches
that relate to integrated preprocessing.
.. index:: -gnatep (gcc)
:samp:`-gnatep={file}`
This switch indicates to the compiler the file name (without directory
information) of the preprocessor data file to use. The preprocessor data file
should be found in the source directories. Alternatively when using project
files, you can reference to the project file's directory via the
``project name'Project_Dir`` project attribute, e.g:
:samp:`-gnatep={preprocessor_data_file}`
This switch specifies the file name (without directory
information) of the preprocessor data file. Either place this file
in one of the source directories, or, when using project
files, reference the project file's directory via the
``project_name'Project_Dir`` project attribute; e.g:
.. code-block:: gpr
.. code-block:: gpr
project Prj is
package Compiler is
for Switches ("Ada") use
("-gnatep=" & Prj'Project_Dir & "prep.def");
end Compiler;
end Prj;
project Prj is
package Compiler is
for Switches ("Ada") use
("-gnatep=" & Prj'Project_Dir & "prep.def");
end Compiler;
end Prj;
A preprocessing data file is a text file with significant lines indicating
how should be preprocessed either a specific source or all sources not
mentioned in other lines. A significant line is a nonempty, non-comment line.
Comments are similar to Ada comments.
A preprocessor data file is a text file that contains *preprocessor
control lines*. A preprocessor control line directs the preprocessing of
either a particular source file, or, analogous to *others* in Ada,
all sources not specified elsewhere in the preprocessor data file.
A preprocessor control line
can optionally identify a *definition file* that assigns values to
preprocessor symbols, as well as a list of switches that relate to
preprocessing.
Empty lines and comments (using Ada syntax) are also permitted, with no
semantic effect.
Each significant line starts with either a literal string or the character '*'.
A literal string is the file name (without directory information) of the source
to preprocess. A character '*' indicates the preprocessing for all the sources
that are not specified explicitly on other lines (order of the lines is not
significant). It is an error to have two lines with the same file name or two
Here's an example of a preprocessor data file:
.. code-block:: ada
"toto.adb" "prep.def" -u
-- Preprocess toto.adb, using definition file prep.def
-- Undefined symbols are treated as False
* -c -DVERSION=V101
-- Preprocess all other sources without using a definition file
-- Suppressed lined are commented
-- Symbol VERSION has the value V101
"tata.adb" "prep2.def" -s
-- Preprocess tata.adb, using definition file prep2.def
-- List all symbols with their values
A preprocessor control line has the following syntax:
::
<preprocessor_control_line> ::=
<preprocessor_input> [ <definition_file_name> ] { <switch> }
<preprocessor_input> ::= <source_file_name> | '*'
<definition_file_name> ::= <string_literal>
<source_file_name> := <string_literal>
<switch> := (See below for list)
Thus each preprocessor control line starts with either a literal string or
the character '*':
* A literal string is the file name (without directory information) of the source
file that will be input to the preprocessor.
* The character '*' is a wild-card indicator; the additional parameters on the line
indicate the preprocessing for all the sources
that are not specified explicitly on other lines (the order of the lines is not
significant).
It is an error to have two lines with the same file name or two
lines starting with the character '*'.
After the file name or the character '*', another optional literal string
indicating the file name of the definition file to be used for preprocessing
After the file name or '*', an optional literal string specifies the name of
the definition file to be used for preprocessing
(:ref:`Form_of_Definitions_File`). The definition files are found by the
compiler in one of the source directories. In some cases, when compiling
a source in a directory other than the current directory, if the definition
file is in the current directory, it may be necessary to add the current
directory as a source directory through switch -I., otherwise
directory as a source directory through the :option:`-I` switch; otherwise
the compiler would not find the definition file.
Then, optionally, switches similar to those of `gnatprep` may
be found. Those switches are:
Finally, switches similar to those of *gnatprep* may optionally appear:
:samp:`-b`
Causes both preprocessor lines and the lines deleted by
preprocessing to be replaced by blank lines, preserving the line number.
This switch is always implied; however, if specified after *-c*
it cancels the effect of *-c*.
This switch is always implied; however, if specified after :option:`-c`
it cancels the effect of :option:`-c`.
:samp:`-c`
@ -3205,11 +3255,12 @@ preprocessing is triggered and parameterized.
with the special string '`--!`'.
:samp:`-Dsymbol={value}`
Define or redefine a symbol, associated with value. A symbol is an Ada
identifier, or an Ada reserved word, with the exception of `if`,
:samp:`-D{symbol}={new_value}`
Define or redefine *symbol* to have *new_value* as its value.
The permitted form for *symbol* is either an Ada identifier, or any Ada reserved word
aside from `if`,
`else`, `elsif`, `end`, `and`, `or` and `then`.
`value` is either a literal string, an Ada identifier or any Ada reserved
The permitted form for `new_value` is a literal string, an Ada identifier or any Ada reserved
word. A symbol declared with this switch replaces a symbol with the
same name defined in a definition file.
@ -3226,51 +3277,39 @@ preprocessing is triggered and parameterized.
a `#if` or `#elsif` test will be treated as an error.
Examples of valid lines in a preprocessor data file:
.. code-block:: ada
"toto.adb" "prep.def" -u
-- preprocess "toto.adb", using definition file "prep.def",
-- undefined symbol are False.
* -c -DVERSION=V101
-- preprocess all other sources without a definition file;
-- suppressed lined are commented; symbol VERSION has the value V101.
"titi.adb" "prep2.def" -s
-- preprocess "titi.adb", using definition file "prep2.def";
-- list all symbols with their values.
.. index:: -gnateD (gcc)
:samp:`-gnateDsymbol[=value]`
Define or redefine a preprocessing symbol, associated with value. If no value
is given on the command line, then the value of the symbol is `True`.
A symbol is an identifier, following normal Ada (case-insensitive)
rules for its syntax, and value is either an arbitrary string between double
:samp:`-gnateD{symbol}[={new_value}]`
Define or redefine *symbol* to have *new_value* as its value. If no value
is supplied, then the value of *symbol* is `True`.
The form of *symbol* is an identifier, following normal Ada (case-insensitive)
rules for its syntax, and *new_value* is either an arbitrary string between double
quotes or any sequence (including an empty sequence) of characters from the
set (letters, digits, period, underline).
Ada reserved words may be used as symbols, with the exceptions of `if`,
`else`, `elsif`, `end`, `and`, `or` and `then`.
Examples::
Examples:
-gnateDToto=Titi
-gnateDFoo
-gnateDFoo=\"Foo-Bar\"
::
-gnateDToto=Tata
-gnateDFoo
-gnateDFoo=\"Foo-Bar\"
A symbol declared with this switch on the command line replaces a
symbol with the same name either in a definition file or specified with a
switch -D in the preprocessor data file.
switch :option:`-D` in the preprocessor data file.
This switch is similar to switch *-D* of `gnatprep`.
This switch is similar to switch :option:`-D` of `gnatprep`.
:samp:`-gnateG`
When integrated preprocessing is performed and the preprocessor modifies
the source text, write the result of this preprocessing into a file
<source>.prep.
When integrated preprocessing is performed on source file :file:`filename.extension`,
create or overwrite :file:`filename.extension.prep` to contain
the result of the preprocessing.
For example if the source file is :file:`foo.adb` then
the output file will be :file:`foo.adb.prep`.
.. _Mixed_Language_Programming:
@ -3340,7 +3379,7 @@ the main subprogram in Ada:
-- Declare an Ada procedure spec for Print_Num, then use
-- C function print_num for the implementation.
procedure Print_Num (Num : Integer);
pragma Import (C, Print_Num, "print_num";
pragma Import (C, Print_Num, "print_num");
begin
Print_Num (Get_Num);

1744
gcc/ada/gnat_rm.texi
View File

File diff suppressed because it is too large Load Diff

545
gcc/ada/gnat_ugn.texi
View File

File diff suppressed because it is too large Load Diff