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

gnat_rm.texi, [...]: Now automatically generated from sphinx in the doc directory.

Browse Source 
2015-02-20  Arnaud Charlet  <charlet@adacore.com>                      

        * gnat_rm.texi, gnat_ugn.texi: Now automatically generated from
        sphinx in the doc directory.
        * doc: New directory containing sphinx versions of gnat_rm and gnat_ugn

From-SVN: r220837
This commit is contained in:
Arnaud Charlet 2015-02-20 10:11:44 +01:00
parent 07a64c021a
commit cb2d884d7d
40 changed files with 104137 additions and 35202 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
gcc/ada/doc/Makefile Normal file
View File

@ -0,0 +1,79 @@
# Makefile for Sphinx documentation
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = DOC_NAME=$* sphinx-build
PAPER =
BUILDDIR = build
SOURCEDIR = .
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) \
-c $(SOURCEDIR)/share \
-d $(BUILDDIR)/$*/doctrees \
$(SOURCEDIR)
DOC_LIST=gnat_rm gnat_ugn
FMT_LIST=html pdf txt info
.PHONY: help clean
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " DOC_NAME.html to make standalone HTML files"
@echo " DOC_NAME.pdf to make LaTeX files and run them through pdflatex"
@echo " DOC_NAME.txt to make text files"
@echo " DOC_NAME.texinfo to make Texinfo files"
@echo " DOC_NAME.info to make info files"
@echo " DOC_NAME.all to build DOC_NAME for all previous formats"
@echo " all to build all documentations in all formats"
@echo " html-all same as previous rule but only for HTML format"
@echo " pdf-all same as previous rule but only for PDF format"
@echo " txt-all same as previous rule but only for text format"
@echo " texinfo-all same as previous rule but only for texinfo format"
@echo " info-all same as previous rule but only for info format"
@echo ""
@echo "DOC_NAME should be a documentation name in the following list:"
@echo " $(DOC_LIST)"
@echo ""
@echo "source and location can be overriden using SOURCEDIR and BUILDDIR variables"
clean:
-rm -rf $(BUILDDIR)/*/html \
$(BUILDDIR)/*/pdf \
$(BUILDDIR)/*/txt \
$(BUILDDIR)/*/info
%.html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$*/html
%.pdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/$*/pdf
cp $(SOURCEDIR)/share/sphinx.sty $(BUILDDIR)/$*/pdf
$(MAKE) -C $(BUILDDIR)/$*/pdf all-pdf LATEXOPTS="-interaction=nonstopmode"
%.txt:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/txt
$(MAKE) -C $(BUILDDIR)/$*/txt plaintext
%.info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/info
$(MAKE) -C $(BUILDDIR)/$*/info info
%.texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/texinfo
html-all: $(foreach doc, $(DOC_LIST), $(doc).html)
pdf-all: $(foreach doc, $(DOC_LIST), $(doc).pdf)
txt-all: $(foreach doc, $(DOC_LIST), $(doc).txt)
texinfo-all: $(foreach doc, $(DOC_LIST), $(doc).texinfo)
%.all:
$(MAKE) $(foreach fmt, $(FMT_LIST), $*.$(fmt))
all: $(foreach fmt, $(FMT_LIST), $(fmt).all)

66
gcc/ada/doc/gnat_rm.rst Normal file
View File

@ -0,0 +1,66 @@
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}@*
AdaCore
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being "GNAT Reference
Manual", and with no Back-Cover Texts. A copy of the license is
included in the section entitled :ref:`gnu_fdl`.
.. toctree::
:numbered:
:maxdepth: 3
gnat_rm/about_this_guide
gnat_rm/implementation_defined_pragmas
gnat_rm/implementation_defined_aspects
gnat_rm/implementation_defined_attributes
gnat_rm/standard_and_implementation_defined_restrictions
gnat_rm/implementation_advice
gnat_rm/implementation_defined_characteristics
gnat_rm/intrinsic_subprograms
gnat_rm/representation_clauses_and_pragmas
gnat_rm/standard_library_routines
gnat_rm/the_implementation_of_standard_i_o
gnat_rm/the_gnat_library
gnat_rm/interfacing_to_other_languages
gnat_rm/specialized_needs_annexes
gnat_rm/implementation_of_specific_ada_features
gnat_rm/implementation_of_ada_2012_features
gnat_rm/obsolescent_features
gnat_rm/compatibility_and_porting_guide
.. raw:: latex
\appendix
.. toctree::
:maxdepth: 3
share/gnu_free_documentation_license

185
gcc/ada/doc/gnat_rm/about_this_guide.rst Normal file
View File

@ -0,0 +1,185 @@
.. _About_This_Guide:
****************
About This Guide
****************
.. only:: PRO
For ease of exposition, 'GNAT Pro' will be referred to simply as
'GNAT' in the remainder of this document.
This manual contains useful information in writing programs using the
GNAT compiler. It includes information on implementation dependent
characteristics of GNAT, including all the information required by
Annex M of the Ada language standard.
GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
invoked in Ada 83 compatibility mode.
By default, GNAT assumes Ada 2012,
but you can override with a compiler switch
to explicitly specify the language version.
(Please refer to the *GNAT User's Guide* for details on these switches.)
Throughout this manual, references to 'Ada' without a year suffix
apply to all the Ada versions of the language.
Ada is designed to be highly portable.
In general, a program will have the same effect even when compiled by
different compilers on different platforms.
However, since Ada is designed to be used in a
wide variety of applications, it also contains a number of system
dependent features to be used in interfacing to the external world.
.. index:: Implementation-dependent features
.. index:: Portability
Note: Any program that makes use of implementation-dependent features
may be non-portable. You should follow good programming practice and
isolate and clearly document any sections of your program that make use
of these features in a non-portable manner.
What This Reference Manual Contains
===================================
This reference manual contains the following chapters:
* :ref:`Implementation_Defined_Pragmas`, lists GNAT implementation-dependent
pragmas, which can be used to extend and enhance the functionality of the
compiler.
* :ref:`Implementation_Defined_Attributes`, lists GNAT
implementation-dependent attributes, which can be used to extend and
enhance the functionality of the compiler.
* :ref:`Standard_and_Implementation_Defined_Restrictions`, lists GNAT
implementation-dependent restrictions, which can be used to extend and
enhance the functionality of the compiler.
* :ref:`Implementation_Advice`, provides information on generally
desirable behavior which are not requirements that all compilers must
follow since it cannot be provided on all systems, or which may be
undesirable on some systems.
* :ref:`Implementation_Defined_Characteristics`, provides a guide to
minimizing implementation dependent features.
* :ref:`Intrinsic_Subprograms`, describes the intrinsic subprograms
implemented by GNAT, and how they can be imported into user
application programs.
* :ref:`Representation_Clauses_and_Pragmas`, describes in detail the
way that GNAT represents data, and in particular the exact set
of representation clauses and pragmas that is accepted.
* :ref:`Standard_Library_Routines`, provides a listing of packages and a
brief description of the functionality that is provided by Ada's
extensive set of standard library routines as implemented by GNAT.
* :ref:`The_Implementation_of_Standard_I/O`, details how the GNAT
implementation of the input-output facilities.
* :ref:`The_GNAT_Library`, is a catalog of packages that complement
the Ada predefined library.
* :ref:`Interfacing_to_Other_Languages`, describes how programs
written in Ada using GNAT can be interfaced to other programming
languages.
* :ref:`Specialized_Needs_Annexes`, describes the GNAT implementation of all
of the specialized needs annexes.
* :ref:`Implementation_of_Specific_Ada_Features`, discusses issues related
to GNAT's implementation of machine code insertions, tasking, and several
other features.
* :ref:`Implementation_of_Ada_2012_Features`, describes the status of the
GNAT implementation of the Ada 2012 language standard.
* :ref:`Obsolescent_Features` documents implementation dependent features,
including pragmas and attributes, which are considered obsolescent, since
there are other preferred ways of achieving the same results. These
obsolescent forms are retained for backwards compatibility.
* :ref:`Compatibility_and_Porting_Guide` presents some guidelines for
developing portable Ada code, describes the compatibility issues that
may arise between GNAT and other Ada compilation systems (including those
for Ada 83), and shows how GNAT can expedite porting applications
developed in other Ada environments.
* :ref:`gnu_fdl` contains the license for this document.
.. index:: Ada 95 Language Reference Manual
.. index:: Ada 2005 Language Reference Manual
This reference manual assumes a basic familiarity with the Ada 95 language, as
described in the
:title:`International Standard ANSI/ISO/IEC-8652:1995`.
It does not require knowledge of the new features introduced by Ada 2005,
(officially known as `ISO/IEC 8652:1995 with Technical Corrigendum 1
and Amendment 1`).
Both reference manuals are included in the GNAT documentation
package.
Conventions
===========
.. index:: Conventions, typographical
.. index:: Typographical conventions
Following are examples of the typographical and graphic conventions used
in this guide:
* `Functions`, `utility program names`, `standard names`,
and `classes`.
* `Option flags`
* :file:`File names`
* `Variables`
* *Emphasis*
* [optional information or parameters]
* Examples are described by text
::
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
===================
See the following documents for further information on GNAT:
* :title:`GNAT User's Guide for Native Platforms`,
which provides information on how to use the
GNAT development environment.
* :title:`Ada 95 Reference Manual`, the Ada 95 programming language standard.
* :title:`Ada 95 Annotated Reference Manual`, which is an annotated version
of the Ada 95 standard. The annotations describe
detailed aspects of the design decision, and in particular contain useful
sections on Ada 83 compatibility.
* :title:`Ada 2005 Reference Manual`, the Ada 2005 programming language standard.
* :title:`Ada 2005 Annotated Reference Manual`, which is an annotated version
of the Ada 2005 standard. The annotations describe
detailed aspects of the design decision.
* :title:`Ada 2012 Reference Manual`, the Ada 2012 programming language standard.
* :title:`DEC Ada, Technical Overview and Comparison on DIGITAL Platforms`,
which contains specific information on compatibility between GNAT and
DEC Ada 83 systems.
* :title:`DEC Ada, Language Reference Manual`, part number AA-PYZAB-TK, which
describes in detail the pragmas and attributes provided by the DEC Ada 83
compiler system.

661
gcc/ada/doc/gnat_rm/compatibility_and_porting_guide.rst Normal file
View File

@ -0,0 +1,661 @@
.. _Compatibility_and_Porting_Guide:
*******************************
Compatibility and Porting Guide
*******************************
This chapter presents some guidelines for developing portable Ada code,
describes the compatibility issues that may arise between
GNAT and other Ada compilation systems (including those for Ada 83),
and shows how GNAT can expedite porting
applications developed in other Ada environments.
.. _Writing_Portable_Fixed-Point_Declarations:
Writing Portable Fixed-Point Declarations
=========================================
The Ada Reference Manual gives an implementation freedom to choose bounds
that are narrower by `Small` from the given bounds.
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.
This leads to possible portability problems, so let's have a closer
look at this, and figure out how to avoid these problems.
First, why does this freedom exist, and why would an implementation
take advantage of it? To answer this, take a closer look at the type
declaration for `F1` above. If the compiler uses the given bounds,
it would need 9 bits to hold the largest positive value (and typically
that means 16 bits on all machines). But if the implementation chooses
the +127.0 bound then it can fit values of the type in 8 bits.
Why not make the user write +127.0 if that's what is wanted?
The rationale is that if you are thinking of fixed point
as a kind of 'poor man's floating-point', then you don't want
to be thinking about the scaled integers that are used in its
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
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
dates to Ada 83).
But the important point is that an implementation is not required
to do this narrowing, so we have a potential portability problem.
We could imagine three types of implementation:
(a) those that narrow the range automatically if they can figure
out that the narrower range will allow storage in a smaller machine unit,
(b) those that will narrow only if forced to by a `'Size` clause, and
(c) those that will never narrow.
Now if we are language theoreticians, we can imagine a fourth
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.
So, how do you get the compiler to do what you want? The answer is give the
actual bounds you want, and then use a `'Small` clause and a
`'Size` clause to absolutely pin down what the compiler does.
E.g., for `F2` above, we will write:
.. code-block:: ada
My_Small : constant := 2.0**(-15);
My_First : constant := -1.0;
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
compiler you could add
.. code-block:: ada
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.
If you follow this scheme you will be guaranteed that your fixed-point
types will be portable.
.. _Compatibility_with_Ada_83:
Compatibility with Ada 83
=========================
.. index:: Compatibility (between Ada 83 and Ada 95 / Ada 2005 / Ada 2012)
Ada 95 and the subsequent revisions Ada 2005 and Ada 2012
are highly upwards compatible with Ada 83. In
particular, the design intention was that the difficulties associated
with moving from Ada 83 to later versions of the standard should be no greater
than those that occur when moving from one Ada 83 system to another.
However, there are a number of points at which there are minor
incompatibilities. The :title:`Ada 95 Annotated Reference Manual` contains
full details of these issues as they relate to Ada 95,
and should be consulted for a complete treatment.
In practice the
following subsections treat the most likely issues to be encountered.
.. _Legal_Ada_83_programs_that_are_illegal_in_Ada_95:
Legal Ada 83 programs that are illegal in Ada 95
------------------------------------------------
Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
Ada 95 and later versions of the standard:
* *Character literals*
Some uses of character literals are ambiguous. Since Ada 95 has introduced
`Wide_Character` as a new predefined character type, some uses of
character literals that were legal in Ada 83 are illegal in Ada 95.
For example:
.. code-block:: ada
for Char in 'A' .. 'Z' loop ... end loop;
The problem is that 'A' and 'Z' could be from either
`Character` or `Wide_Character`. The simplest correction
is to make the type explicit; e.g.:
.. code-block:: ada
for Char in Character range 'A' .. 'Z' loop ... end loop;
* *New reserved words*
The identifiers `abstract`, `aliased`, `protected`,
`requeue`, `tagged`, and `until` are reserved in Ada 95.
Existing Ada 83 code using any of these identifiers must be edited to
use some alternative name.
* *Freezing rules*
The rules in Ada 95 are slightly different with regard to the point at
which entities are frozen, and representation pragmas and clauses are
not permitted past the freeze point. This shows up most typically in
the form of an error message complaining that a representation item
appears too late, and the appropriate corrective action is to move
the item nearer to the declaration of the entity to which it refers.
A particular case is that representation pragmas
cannot be applied to a subprogram body. If necessary, a separate subprogram
declaration must be introduced to which the pragma can be applied.
* *Optional bodies for library packages*
In Ada 83, a package that did not require a package body was nevertheless
allowed to have one. This lead to certain surprises in compiling large
systems (situations in which the body could be unexpectedly ignored by the
binder). In Ada 95, if a package does not require a body then it is not
permitted to have a body. To fix this problem, simply remove a redundant
body if it is empty, or, if it is non-empty, introduce a dummy declaration
into the spec that makes the body required. One approach is to add a private
part to the package declaration (if necessary), and define a parameterless
procedure called `Requires_Body`, which must then be given a dummy
procedure body in the package body, which then becomes required.
Another approach (assuming that this does not introduce elaboration
circularities) is to add an `Elaborate_Body` pragma to the package spec,
since one effect of this pragma is to require the presence of a package body.
* *Numeric_Error is the same exception as Constraint_Error*
In Ada 95, the exception `Numeric_Error` is a renaming of `Constraint_Error`.
This means that it is illegal to have separate exception handlers for
the two exceptions. The fix is simply to remove the handler for the
`Numeric_Error` case (since even in Ada 83, a compiler was free to raise
`Constraint_Error` in place of `Numeric_Error` in all cases).
* *Indefinite subtypes in generics*
In Ada 83, it was permissible to pass an indefinite type (e.g, `String`)
as the actual for a generic formal private type, but then the instantiation
would be illegal if there were any instances of declarations of variables
of this type in the generic body. In Ada 95, to avoid this clear violation
of the methodological principle known as the 'contract model',
the generic declaration explicitly indicates whether
or not such instantiations are permitted. If a generic formal parameter
has explicit unknown discriminants, indicated by using `(<>)` after the
subtype name, then it can be instantiated with indefinite types, but no
stand-alone variables can be declared of this type. Any attempt to declare
such a variable will result in an illegality at the time the generic is
declared. If the `(<>)` notation is not used, then it is illegal
to instantiate the generic with an indefinite type.
This is the potential incompatibility issue when porting Ada 83 code to Ada 95.
It will show up as a compile time error, and
the fix is usually simply to add the `(<>)` to the generic declaration.
.. _More_deterministic_semantics:
More deterministic semantics
----------------------------
* *Conversions*
Conversions from real types to integer types round away from 0. In Ada 83
the conversion Integer(2.5) could deliver either 2 or 3 as its value. This
implementation freedom was intended to support unbiased rounding in
statistical applications, but in practice it interfered with portability.
In Ada 95 the conversion semantics are unambiguous, and rounding away from 0
is required. Numeric code may be affected by this change in semantics.
Note, though, that this issue is no worse than already existed in Ada 83
when porting code from one vendor to another.
* *Tasking*
The Real-Time Annex introduces a set of policies that define the behavior of
features that were implementation dependent in Ada 83, such as the order in
which open select branches are executed.
.. _Changed_semantics:
Changed semantics
-----------------
The worst kind of incompatibility is one where a program that is legal in
Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not
possible in Ada 83. Fortunately this is extremely rare, but the one
situation that you should be alert to is the change in the predefined type
`Character` from 7-bit ASCII to 8-bit Latin-1.
.. index:: Latin-1
* *Range of type `Character`*
The range of `Standard.Character` is now the full 256 characters
of Latin-1, whereas in most Ada 83 implementations it was restricted
to 128 characters. Although some of the effects of
this change will be manifest in compile-time rejection of legal
Ada 83 programs it is possible for a working Ada 83 program to have
a different effect in Ada 95, one that was not permitted in Ada 83.
As an example, the expression
`Character'Pos(Character'Last)` returned `127` in Ada 83 and now
delivers `255` as its value.
In general, you should look at the logic of any
character-processing Ada 83 program and see whether it needs to be adapted
to work correctly with Latin-1. Note that the predefined Ada 95 API has a
character handling package that may be relevant if code needs to be adapted
to account for the additional Latin-1 elements.
The desirable fix is to
modify the program to accommodate the full character set, but in some cases
it may be convenient to define a subtype or derived type of Character that
covers only the restricted range.
.. _Other_language_compatibility_issues:
Other language compatibility issues
-----------------------------------
* *-gnat83* switch
All implementations of GNAT provide a switch that causes GNAT to operate
in Ada 83 mode. In this mode, some but not all compatibility problems
of the type described above are handled automatically. For example, the
new reserved words introduced in Ada 95 and Ada 2005 are treated simply
as identifiers as in Ada 83. However,
in practice, it is usually advisable to make the necessary modifications
to the program to remove the need for using this switch.
See the `Compiling Different Versions of Ada` section in
the :title:`GNAT User's Guide`.
* Support for removed Ada 83 pragmas and attributes
A number of pragmas and attributes from Ada 83 were removed from Ada 95,
generally because they were replaced by other mechanisms. Ada 95 and Ada 2005
compilers are allowed, but not required, to implement these missing
elements. In contrast with some other compilers, GNAT implements all
such pragmas and attributes, eliminating this compatibility concern. These
include `pragma Interface` and the floating point type attributes
(`Emax`, `Mantissa`, etc.), among other items.
.. _Compatibility_between_Ada_95_and_Ada_2005:
Compatibility between Ada 95 and Ada 2005
=========================================
.. index:: Compatibility between Ada 95 and Ada 2005
Although Ada 2005 was designed to be upwards compatible with Ada 95, there are
a number of incompatibilities. Several are enumerated below;
for a complete description please see the
:title:`Annotated Ada 2005 Reference Manual`, or section 9.1.1 in
:title:`Rationale for Ada 2005`.
* *New reserved words.*
The words `interface`, `overriding` and `synchronized` are
reserved in Ada 2005.
A pre-Ada 2005 program that uses any of these as an identifier will be
illegal.
* *New declarations in predefined packages.*
A number of packages in the predefined environment contain new declarations:
`Ada.Exceptions`, `Ada.Real_Time`, `Ada.Strings`,
`Ada.Strings.Fixed`, `Ada.Strings.Bounded`,
`Ada.Strings.Unbounded`, `Ada.Strings.Wide_Fixed`,
`Ada.Strings.Wide_Bounded`, `Ada.Strings.Wide_Unbounded`,
`Ada.Tags`, `Ada.Text_IO`, and `Interfaces.C`.
If an Ada 95 program does a `with` and `use` of any of these
packages, the new declarations may cause name clashes.
* *Access parameters.*
A nondispatching subprogram with an access parameter cannot be renamed
as a dispatching operation. This was permitted in Ada 95.
* *Access types, discriminants, and constraints.*
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
possibility of ambiguities in legal Ada 95 programs, since additional types
now need to be considered in expression resolution.
* *Fixed-point multiplication and division.*
Certain expressions involving '*' or '/' for a fixed-point type, which
were legal in Ada 95 and invoked the predefined versions of these operations,
are now ambiguous.
The ambiguity may be resolved either by applying a type conversion to the
expression, or by explicitly invoking the operation from package
`Standard`.
* *Return-by-reference types.*
The Ada 95 return-by-reference mechanism has been removed. Instead, the user
can declare a function returning a value from an anonymous access type.
.. _Implementation-dependent_characteristics:
Implementation-dependent characteristics
========================================
Although the Ada language defines the semantics of each construct as
precisely as practical, in some situations (for example for reasons of
efficiency, or where the effect is heavily dependent on the host or target
platform) the implementation is allowed some freedom. In porting Ada 83
code to GNAT, you need to be aware of whether / how the existing code
exercised such implementation dependencies. Such characteristics fall into
several categories, and GNAT offers specific support in assisting the
transition from certain Ada 83 compilers.
.. _Implementation-defined_pragmas:
Implementation-defined pragmas
------------------------------
Ada compilers are allowed to supplement the language-defined pragmas, and
these are a potential source of non-portability. All GNAT-defined pragmas
are described in the `Implementation Defined Pragmas` chapter of the
:title:`GNAT Reference Manual`, and these include several that are specifically
intended to correspond to other vendors' Ada 83 pragmas.
For migrating from VADS, the pragma `Use_VADS_Size` may be useful.
For compatibility with HP Ada 83, GNAT supplies the pragmas
`Extend_System`, `Ident`, `Inline_Generic`,
`Interface_Name`, `Passive`, `Suppress_All`,
and `Volatile`.
Other relevant pragmas include `External` and `Link_With`.
Some vendor-specific
Ada 83 pragmas (`Share_Generic`, `Subtitle`, and `Title`) are
recognized, thus
avoiding compiler rejection of units that contain such pragmas; they are not
relevant in a GNAT context and hence are not otherwise implemented.
.. _Implementation-defined_attributes:
Implementation-defined attributes
---------------------------------
Analogous to pragmas, the set of attributes may be extended by an
implementation. All GNAT-defined attributes are described in
`Implementation Defined Attributes` section of the
:title:`GNAT Reference Manual`, and these include several that are specifically intended
to correspond to other vendors' Ada 83 attributes. For migrating from VADS,
the attribute `VADS_Size` may be useful. For compatibility with HP
Ada 83, GNAT supplies the attributes `Bit`, `Machine_Size` and
`Type_Class`.
.. _Libraries:
Libraries
---------
Vendors may supply libraries to supplement the standard Ada API. If Ada 83
code uses vendor-specific libraries then there are several ways to manage
this in Ada 95 and later versions of the standard:
* If the source code for the libraries (specs and bodies) are
available, then the libraries can be migrated in the same way as the
application.
* If the source code for the specs but not the bodies are
available, then you can reimplement the bodies.
* Some features introduced by Ada 95 obviate the need for library support. For
example most Ada 83 vendors supplied a package for unsigned integers. The
Ada 95 modular type feature is the preferred way to handle this need, so
instead of migrating or reimplementing the unsigned integer package it may
be preferable to retrofit the application using modular types.
.. _Elaboration_order:
Elaboration order
-----------------
The implementation can choose any elaboration order consistent with the unit
dependency relationship. This freedom means that some orders can result in
Program_Error being raised due to an 'Access Before Elaboration': an attempt
to invoke a subprogram its body has been elaborated, or to instantiate a
generic before the generic body has been elaborated. By default GNAT
attempts to choose a safe order (one that will not encounter access before
elaboration problems) by implicitly inserting `Elaborate` or
`Elaborate_All` pragmas where
needed. However, this can lead to the creation of elaboration circularities
and a resulting rejection of the program by gnatbind. This issue is
thoroughly described in the `Elaboration Order Handling in GNAT` appendix
in the :title:`GNAT User's Guide`.
In brief, there are several
ways to deal with this situation:
* Modify the program to eliminate the circularities, e.g., by moving
elaboration-time code into explicitly-invoked procedures
* Constrain the elaboration order by including explicit `Elaborate_Body` or
`Elaborate` pragmas, and then inhibit the generation of implicit
`Elaborate_All`
pragmas either globally (as an effect of the *-gnatE* switch) or locally
(by selectively suppressing elaboration checks via pragma
`Suppress(Elaboration_Check)` when it is safe to do so).
.. _Target-specific_aspects:
Target-specific aspects
-----------------------
Low-level applications need to deal with machine addresses, data
representations, interfacing with assembler code, and similar issues. If
such an Ada 83 application is being ported to different target hardware (for
example where the byte endianness has changed) then you will need to
carefully examine the program logic; the porting effort will heavily depend
on the robustness of the original design. Moreover, Ada 95 (and thus
Ada 2005 and Ada 2012) are sometimes
incompatible with typical Ada 83 compiler practices regarding implicit
packing, the meaning of the Size attribute, and the size of access values.
GNAT's approach to these issues is described in :ref:`Representation_Clauses`.
.. _Compatibility_with_Other_Ada_Systems:
Compatibility with Other Ada Systems
====================================
If programs avoid the use of implementation dependent and
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
compilers, but do not affect porting code to GNAT.
(As of January 2007, GNAT is the only compiler available for Ada 2005;
the following issues may or may not arise for Ada 2005 programs
when other compilers appear.)
* *Ada 83 Pragmas and Attributes*
Ada 95 compilers are allowed, but not required, to implement the missing
Ada 83 pragmas and attributes that are no longer defined in Ada 95.
GNAT implements all such pragmas and attributes, eliminating this as
a compatibility concern, but some other Ada 95 compilers reject these
pragmas and attributes.
* *Specialized Needs Annexes*
GNAT implements the full set of special needs annexes. At the
current time, it is the only Ada 95 compiler to do so. This means that
programs making use of these features may not be portable to other Ada
95 compilation systems.
* *Representation Clauses*
Some other Ada 95 compilers implement only the minimal set of
representation clauses required by the Ada 95 reference manual. GNAT goes
far beyond this minimal set, as described in the next section.
.. _Representation_Clauses:
Representation Clauses
======================
The Ada 83 reference manual was quite vague in describing both the minimal
required implementation of representation clauses, and also their precise
effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the
minimal set of capabilities required is still quite limited.
GNAT implements the full required set of capabilities in
Ada 95 and Ada 2005, but also goes much further, and in particular
an effort has been made to be compatible with existing Ada 83 usage to the
greatest extent possible.
A few cases exist in which Ada 83 compiler behavior is incompatible with
the requirements in Ada 95 (and thus also Ada 2005). These are instances of
intentional or accidental dependence on specific implementation dependent
characteristics of these Ada 83 compilers. The following is a list of
the cases most likely to arise in existing Ada 83 code.
* *Implicit Packing*
Some Ada 83 compilers allowed a Size specification to cause implicit
packing of an array or record. This could cause expensive implicit
conversions for change of representation in the presence of derived
types, and the Ada design intends to avoid this possibility.
Subsequent AI's were issued to make it clear that such implicit
change of representation in response to a Size clause is inadvisable,
and this recommendation is represented explicitly in the Ada 95 (and Ada 2005)
Reference Manuals as implementation advice that is followed by GNAT.
The problem will show up as an error
message rejecting the size clause. The fix is simply to provide
the explicit pragma `Pack`, or for more fine tuned control, provide
a Component_Size clause.
* *Meaning of Size Attribute*
The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as
the minimal number of bits required to hold values of the type. For example,
on a 32-bit machine, the size of `Natural` will typically be 31 and not
32 (since no sign bit is required). Some Ada 83 compilers gave 31, and
some 32 in this situation. This problem will usually show up as a compile
time error, but not always. It is a good idea to check all uses of the
'Size attribute when porting Ada 83 code. The GNAT specific attribute
Object_Size can provide a useful way of duplicating the behavior of
some Ada 83 compiler systems.
* *Size of Access Types*
A common assumption in Ada 83 code is that an access type is in fact a pointer,
and that therefore it will be the same size as a System.Address value. This
assumption is true for GNAT in most cases with one exception. For the case of
a pointer to an unconstrained array type (where the bounds may vary from one
value of the access type to another), the default is to use a 'fat pointer',
which is represented as two separate pointers, one to the bounds, and one to
the array. This representation has a number of advantages, including improved
efficiency. However, it may cause some difficulties in porting existing Ada 83
code which makes the assumption that, for example, pointers fit in 32 bits on
a machine with 32-bit addressing.
To get around this problem, GNAT also permits the use of 'thin pointers' for
access types in this case (where the designated type is an unconstrained array
type). These thin pointers are indeed the same size as a System.Address value.
To specify a thin pointer, use a size clause for the type, for example:
.. code-block:: ada
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
such flexibility in the use of foreign pointers or in using the
Unrestricted_Access attribute to create pointers to non-aliased objects.
But for any standard portable use of the access type it will work in
a functionally correct manner and allow porting of existing code.
Note that another way of forcing a thin pointer representation
is to use a component size clause for the element size in an array,
or a record representation clause for an access field in a record.
See the documentation of Unrestricted_Access in the GNAT RM for a
full discussion of possible problems using this attribute in conjunction
with thin pointers.
.. _Compatibility_with_HP_Ada_83:
Compatibility with HP Ada 83
============================
All the HP Ada 83 pragmas and attributes are recognized, although only a subset
of them can sensibly be implemented. The description of pragmas in
:ref:`Implementation_Defined_Pragmas` indicates whether or not they are
applicable to GNAT.
* *Default floating-point representation*
In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83,
it is VMS format.
* *System*
the package System in GNAT exactly corresponds to the definition in the
Ada 95 reference manual, which means that it excludes many of the
HP Ada 83 extensions. However, a separate package Aux_DEC is provided
that contains the additional definitions, and a special pragma,
Extend_System allows this package to be treated transparently as an
extension of package System.

1395
gcc/ada/doc/gnat_rm/implementation_advice.rst Normal file
View File

File diff suppressed because it is too large Load Diff

520
gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst Normal file
View File

@ -0,0 +1,520 @@
.. _Implementation_Defined_Aspects:
******************************
Implementation Defined Aspects
******************************
Ada defines (throughout the Ada 2012 reference manual, summarized
in Annex K) a set of aspects that can be specified for certain entities.
These language defined aspects are implemented in GNAT in Ada 2012 mode
and work as described in the Ada 2012 Reference Manual.
In addition, Ada 2012 allows implementations to define additional aspects
whose meaning is defined by the implementation. GNAT provides
a number of these implementation-defined aspects which can be used
to extend and enhance the functionality of the compiler. This section of
the GNAT reference manual describes these additional aspects.
Note that any program using these aspects may not be portable to
other compilers (although GNAT implements this set of aspects on all
platforms). Therefore if portability to other compilers is an important
consideration, you should minimize the use of these aspects.
Note that for many of these aspects, the effect is essentially similar
to the use of a pragma or attribute specification with the same name
applied to the entity. For example, if we write:
.. code-block:: ada
type R is range 1 .. 100
with Value_Size => 10;
then the effect is the same as:
.. code-block:: ada
type R is range 1 .. 100;
for R'Value_Size use 10;
and if we write:
.. code-block:: ada
type R is new Integer
with Shared => True;
then the effect is the same as:
.. code-block:: ada
type R is new Integer;
pragma Shared (R);
In the documentation below, such cases are simply marked
as being boolean aspects equivalent to the corresponding pragma
or attribute definition clause.
Aspect Abstract_State
=====================
.. index:: Abstract_State
This aspect is equivalent to pragma `Abstract_State`.
Annotate
========
.. index:: Annotate
There are three forms of this aspect (where ID is an identifier,
and ARG is a general expression).
*Annotate => ID*
Equivalent to `pragma Annotate (ID, Entity => Name);`
*Annotate => (ID)*
Equivalent to `pragma Annotate (ID, Entity => Name);`
*Annotate => (ID ,ID {, ARG})*
Equivalent to `pragma Annotate (ID, ID {, ARG}, Entity => Name);`
Aspect Async_Readers
====================
.. index:: Async_Readers
This boolean aspect is equivalent to pragma `Async_Readers`.
Aspect Async_Writers
====================
.. index:: Async_Writers
This boolean aspect is equivalent to pragma `Async_Writers`.
Aspect Contract_Cases
=====================
.. index:: Contract_Cases
This aspect is equivalent to pragma `Contract_Cases`, the sequence
of clauses being enclosed in parentheses so that syntactically it is an
aggregate.
Aspect Depends
==============
.. index:: Depends
This aspect is equivalent to pragma `Depends`.
Aspect Dimension
================
.. index:: Dimension
The `Dimension` aspect is used to specify the dimensions of a given
subtype of a dimensioned numeric type. The aspect also specifies a symbol
used when doing formatted output of dimensioned quantities. The syntax is::
with Dimension =>
([Symbol =>] SYMBOL, DIMENSION_VALUE {, DIMENSION_Value})
SYMBOL ::= STRING_LITERAL | CHARACTER_LITERAL
DIMENSION_VALUE ::=
RATIONAL
| others => RATIONAL
| DISCRETE_CHOICE_LIST => RATIONAL
RATIONAL ::= [-] NUMERIC_LITERAL [/ NUMERIC_LITERAL]
This aspect can only be applied to a subtype whose parent type has
a `Dimension_Systen` 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,
the computation of a force must result in dimensions (L => 1, M => 1, T => -2).
For further examples of the usage
of this aspect, see package `System.Dim.Mks`.
Note that when the dimensioned type is an integer type, then any
dimension value must be an integer literal.
Aspect Dimension_System
=======================
.. index:: Dimension_System
The `Dimension_System` aspect is used to define a system of
dimensions that will be used in subsequent subtype declarations with
`Dimension` aspects that reference this system. The syntax is::
with Dimension_System => (DIMENSION {, DIMENSION});
DIMENSION ::= ([Unit_Name =>] IDENTIFIER,
[Unit_Symbol =>] SYMBOL,
[Dim_Symbol =>] SYMBOL)
SYMBOL ::= CHARACTER_LITERAL | STRING_LITERAL
This aspect is applied to a type, which must be a numeric derived type
(typically a floating-point type), that
will represent values within the dimension system. Each `DIMENSION`
corresponds to one particular dimension. A maximum of 7 dimensions may
be specified. `Unit_Name` is the name of the dimension (for example
`Meter`). `Unit_Symbol` is the shorthand used for quantities
of this dimension (for example `m` for `Meter`).
`Dim_Symbol` gives
the identification within the dimension system (typically this is a
single letter, e.g. `L` standing for length for unit name `Meter`).
The `Unit_Symbol` is used in formatted output of dimensioned quantities.
The `Dim_Symbol` is used in error messages when numeric operations have
inconsistent dimensions.
GNAT provides the standard definition of the International MKS system in
the run-time package `System.Dim.Mks`. You can easily define
similar packages for cgs units or British units, and define conversion factors
between values in different systems. The MKS system is characterized by the
following aspect:
.. code-block:: ada
type Mks_Type is new Long_Long_Float with
Dimension_System => (
(Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
(Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
(Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
(Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
(Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => '@'),
(Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
(Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
Note that in the above type definition, we use the `at` symbol (``@``) to
represent a theta character (avoiding the use of extended Latin-1
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 Effective_Reads
======================
.. index:: Effective_Reads
This aspect is equivalent to pragma `Effective_Reads`.
Aspect Effective_Writes
=======================
.. index:: Effective_Writes
This aspect is equivalent to pragma `Effective_Writes`.
Aspect Favor_Top_Level
======================
.. index:: Favor_Top_Level
This boolean aspect is equivalent to pragma `Favor_Top_Level`.
Aspect Global
=============
.. index:: Global
This aspect is equivalent to pragma `Global`.
Aspect Initial_Condition
========================
.. index:: Initial_Condition
This aspect is equivalent to pragma `Initial_Condition`.
Aspect Initializes
==================
.. index:: Initializes
This aspect is equivalent to pragma `Initializes`.
Aspect Inline_Always
====================
.. index:: Inline_Always
This boolean aspect is equivalent to pragma `Inline_Always`.
Aspect Invariant
================
.. index:: Invariant
This aspect is equivalent to pragma `Invariant`. It is a
synonym for the language defined aspect `Type_Invariant` except
that it is separately controllable using pragma `Assertion_Policy`.
Aspect Invariant'Class
======================
.. index:: Invariant'Class
This aspect is equivalent to pragma `Type_Invariant_Class`. It is a
synonym for the language defined aspect `Type_Invariant'Class` except
that it is separately controllable using pragma `Assertion_Policy`.
Aspect Iterable
===============
.. index:: Iterable
This aspect provides a light-weight mechanism for loops and quantified
expressions over container types, without the overhead imposed by the tampering
checks of standard Ada 2012 iterators. The value of the aspect is an aggregate
with four named components: `First`, `Next`, `Has_Element`, and `Element` (the
last one being optional). When only 3 components are specified, only the
`for .. in` form of iteration over cursors is available. When all 4 components
are specified, both this form and the `for .. of` form of iteration over
elements are available. The following is a typical example of use:
.. code-block:: ada
type List is private with
Iterable => (First => First_Cursor,
Next => Advance,
Has_Element => Cursor_Has_Element,
[Element => Get_Element]);
* The value denoted by `First` must denote a primitive operation of the
container type that returns a `Cursor`, which must a be a type declared in
the container package or visible from it. For example:
.. code-block:: ada
function First_Cursor (Cont : Container) return Cursor;
* The value of `Next` is a primitive operation of the container type that takes
both a container and a cursor and yields a cursor. For example:
.. code-block:: ada
function Advance (Cont : Container; Position : Cursor) return Cursor;
* The value of `Has_Element` is a primitive operation of the container type
that takes both a container and a cursor and yields a boolean. For example:
.. code-block:: ada
function Cursor_Has_Element (Cont : Container; Position : Cursor) return Boolean;
* The value of `Element` is a primitive operation of the container type that
takes both a container and a cursor and yields an `Element_Type`, which must
be a type declared in the container package or visible from it. For example:
.. code-block:: ada
function Get_Element (Cont : Container; Position : Cursor) return Element_Type;
This aspect is used in the GNAT-defined formal container packages.
Aspect Linker_Section
=====================
.. index:: Linker_Section
This aspect is equivalent to an `Linker_Section` pragma.
Aspect Lock_Free
================
.. index:: Lock_Free
This boolean aspect is equivalent to pragma `Lock_Free`.
Aspect No_Elaboration_Code_All
==============================
.. index:: No_Elaboration_Code_All
This aspect is equivalent to a `pragma No_Elaboration_Code_All`
statement for a program unit.
Aspect No_Tagged_Streams
========================
.. index:: No_Tagged_Streams
This aspect is equivalent to a `pragma No_Tagged_Streams` with an
argument specifying a root tagged type (thus this aspect can only be
applied to such a type).
Aspect Object_Size
==================
.. index:: Object_Size
This aspect is equivalent to an `Object_Size` attribute definition
clause.
Aspect Obsolescent
==================
.. index:: Obsolsecent
This aspect is equivalent to an `Obsolescent` pragma. Note that the
evaluation of this aspect happens at the point of occurrence, it is not
delayed until the freeze point.
Aspect Part_Of
==============
.. index:: Part_Of
This aspect is equivalent to pragma `Part_Of`.
Aspect Persistent_BSS
=====================
.. index:: Persistent_BSS
This boolean aspect is equivalent to pragma `Persistent_BSS`.
Aspect Predicate
================
.. index:: Predicate
This aspect is equivalent to pragma `Predicate`. It is thus
similar to the language defined aspects `Dynamic_Predicate`
and `Static_Predicate` except that whether the resulting
predicate is static or dynamic is controlled by the form of the
expression. It is also separately controllable using pragma
`Assertion_Policy`.
Aspect Pure_Function
====================
.. index:: Pure_Function
This boolean aspect is equivalent to pragma `Pure_Function`.
Aspect Refined_Depends
======================
.. index:: Refined_Depends
This aspect is equivalent to pragma `Refined_Depends`.
Aspect Refined_Global
=====================
.. index:: Refined_Global
This aspect is equivalent to pragma `Refined_Global`.
Aspect Refined_Post
===================
.. index:: Refined_Post
This aspect is equivalent to pragma `Refined_Post`.
Aspect Refined_State
====================
.. index:: Refined_State
This aspect is equivalent to pragma `Refined_State`.
Aspect Remote_Access_Type
=========================
.. index:: Remote_Access_Type
This aspect is equivalent to pragma `Remote_Access_Type`.
Aspect Scalar_Storage_Order
===========================
.. index:: Scalar_Storage_Order
This aspect is equivalent to a `Scalar_Storage_Order`
attribute definition clause.
Aspect Shared
=============
.. index:: Shared
This boolean aspect is equivalent to pragma `Shared`,
and is thus a synonym for aspect `Atomic`.
Aspect Simple_Storage_Pool
==========================
.. index:: Simple_Storage_Pool
This aspect is equivalent to a `Simple_Storage_Pool`
attribute definition clause.
Aspect Simple_Storage_Pool_Type
===============================
.. index:: Simple_Storage_Pool_Type
This boolean aspect is equivalent to pragma `Simple_Storage_Pool_Type`.
Aspect SPARK_Mode
=================
.. index:: SPARK_Mode
This aspect is equivalent to pragma `SPARK_Mode` and
may be specified for either or both of the specification and body
of a subprogram or package.
Aspect Suppress_Debug_Info
==========================
.. index:: Suppress_Debug_Info
This boolean aspect is equivalent to pragma `Suppress_Debug_Info`.
Aspect Suppress_Initialization
==============================
.. index:: Suppress_Initialization
This boolean aspect is equivalent to pragma `Suppress_Initialization`.
Aspect Test_Case
================
.. index:: Test_Case
This aspect is equivalent to pragma `Test_Case`.
Aspect Thread_Local_Storage
===========================
.. index:: Thread_Local_Storage
This boolean aspect is equivalent to pragma `Thread_Local_Storage`.
Aspect Universal_Aliasing
=========================
.. index:: Universal_Aliasing
This boolean aspect is equivalent to pragma `Universal_Aliasing`.
Aspect Universal_Data
=====================
.. index:: Universal_Data
This aspect is equivalent to pragma `Universal_Data`.
Aspect Unmodified
=================
.. index:: Unmodified
This boolean aspect is equivalent to pragma `Unmodified`.
Aspect Unreferenced
===================
.. index:: Unreferenced
This boolean aspect is equivalent to pragma `Unreferenced`. Note that
in the case of formal parameters, it is not permitted to have aspects for
a formal parameter, so in this case the pragma form must be used.
Aspect Unreferenced_Objects
===========================
.. index:: Unreferenced_Objects
This boolean aspect is equivalent to pragma `Unreferenced_Objects`.
Aspect Value_Size
=================
.. index:: Value_Size
This aspect is equivalent to a `Value_Size`
attribute definition clause.
Aspect Warnings
===============
.. index:: Warnings
This aspect is equivalent to the two argument form of pragma `Warnings`,
where the first argument is `ON` or `OFF` and the second argument
is the entity.

1589
gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1295
gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst Normal file
View File

File diff suppressed because it is too large Load Diff

6887
gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1328
gcc/ada/doc/gnat_rm/implementation_of_ada_2012_features.rst Normal file
View File

File diff suppressed because it is too large Load Diff

671
gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst Normal file
View File

@ -0,0 +1,671 @@
.. _Implementation_of_Specific_Ada_Features:
***************************************
Implementation of Specific Ada Features
***************************************
This chapter describes the GNAT implementation of several Ada language
facilities.
.. _Machine_Code_Insertions:
Machine Code Insertions
=======================
.. index:: Machine Code insertions
Package `Machine_Code` provides machine code support as described
in the Ada Reference Manual in two separate forms:
*
Machine code statements, consisting of qualified expressions that
fit the requirements of RM section 13.8.
*
An intrinsic callable procedure, providing an alternative mechanism of
including machine instructions in a subprogram.
The two features are similar, and both are closely related to the mechanism
provided by the asm instruction in the GNU C compiler. Full understanding
and use of the facilities in this package requires understanding the asm
instruction, see the section on Extended Asm in
:title:`Using_the_GNU_Compiler_Collection_(GCC)`.
Calls to the function `Asm` and the procedure `Asm` have identical
semantic restrictions and effects as described below. Both are provided so
that the procedure call can be used as a statement, and the function call
can be used to form a code_statement.
Consider this C `asm` instruction:
::
asm ("fsinx %1 %0" : "=f" (result) : "f" (angle));
The equivalent can be written for GNAT as:
.. code-block:: ada
Asm ("fsinx %1 %0",
My_Float'Asm_Output ("=f", result),
My_Float'Asm_Input ("f", angle));
The first argument to `Asm` is the assembler template, and is
identical to what is used in GNU C. This string must be a static
expression. The second argument is the output operand list. It is
either a single `Asm_Output` attribute reference, or a list of such
references enclosed in parentheses (technically an array aggregate of
such references).
The `Asm_Output` attribute denotes a function that takes two
parameters. The first is a string, the second is the name of a variable
of the type designated by the attribute prefix. The first (string)
argument is required to be a static expression and designates the
constraint (see the section on Constraints in
:title:`Using_the_GNU_Compiler_Collection_(GCC)`)
for the parameter; e.g., what kind of register is required. The second
argument is the variable to be written or updated with the
result. The possible values for constraint are the same as those used in
the RTL, and are dependent on the configuration file used to build the
GCC back end. If there are no output operands, then this argument may
either be omitted, or explicitly given as `No_Output_Operands`.
No support is provided for GNU C's symbolic names for output parameters.
The second argument of ``my_float'Asm_Output`` functions as
though it were an `out` parameter, which is a little curious, but
all names have the form of expressions, so there is no syntactic
irregularity, even though normally functions would not be permitted
`out` parameters. The third argument is the list of input
operands. It is either a single `Asm_Input` attribute reference, or
a list of such references enclosed in parentheses (technically an array
aggregate of such references).
The `Asm_Input` attribute denotes a function that takes two
parameters. The first is a string, the second is an expression of the
type designated by the prefix. The first (string) argument is required
to be a static expression, and is the constraint for the parameter,
(e.g., what kind of register is required). The second argument is the
value to be used as the input argument. The possible values for the
constraint are the same as those used in the RTL, and are dependent on
the configuration file used to built the GCC back end.
No support is provided for GNU C's symbolic names for input parameters.
If there are no input operands, this argument may either be omitted, or
explicitly given as `No_Input_Operands`. The fourth argument, not
present in the above example, is a list of register names, called the
*clobber* argument. This argument, if given, must be a static string
expression, and is a space or comma separated list of names of registers
that must be considered destroyed as a result of the `Asm` call. If
this argument is the null string (the default value), then the code
generator assumes that no additional registers are destroyed.
In addition to registers, the special clobbers `memory` and
`cc` as described in the GNU C docs are both supported.
The fifth argument, not present in the above example, called the
*volatile* argument, is by default `False`. It can be set to
the literal value `True` to indicate to the code generator that all
optimizations with respect to the instruction specified should be
suppressed, and in particular an instruction that has outputs
will still be generated, even if none of the outputs are
used. See :title:`Using_the_GNU_Compiler_Collection_(GCC)`
for the full description.
Generally it is strongly advisable to use Volatile for any ASM statement
that is missing either input or output operands or to avoid unwanted
optimizations. A warning is generated if this advice is not followed.
No support is provided for GNU C's `asm goto` feature.
The `Asm` subprograms may be used in two ways. First the procedure
forms can be used anywhere a procedure call would be valid, and
correspond to what the RM calls 'intrinsic' routines. Such calls can
be used to intersperse machine instructions with other Ada statements.
Second, the function forms, which return a dummy value of the limited
private type `Asm_Insn`, can be used in code statements, and indeed
this is the only context where such calls are allowed. Code statements
appear as aggregates of the form:
.. code-block:: ada
Asm_Insn'(Asm (...));
Asm_Insn'(Asm_Volatile (...));
In accordance with RM rules, such code statements are allowed only
within subprograms whose entire body consists of such statements. It is
not permissible to intermix such statements with other Ada statements.
Typically the form using intrinsic procedure calls is more convenient
and more flexible. The code statement form is provided to meet the RM
suggestion that such a facility should be made available. The following
is the exact syntax of the call to `Asm`. As usual, if named notation
is used, the arguments may be given in arbitrary order, following the
normal rules for use of positional and named arguments:
::
ASM_CALL ::= Asm (
[Template =>] static_string_EXPRESSION
[,[Outputs =>] OUTPUT_OPERAND_LIST ]
[,[Inputs =>] INPUT_OPERAND_LIST ]
[,[Clobber =>] static_string_EXPRESSION ]
[,[Volatile =>] static_boolean_EXPRESSION] )
OUTPUT_OPERAND_LIST ::=
[PREFIX.]No_Output_Operands
| OUTPUT_OPERAND_ATTRIBUTE
| (OUTPUT_OPERAND_ATTRIBUTE {,OUTPUT_OPERAND_ATTRIBUTE})
OUTPUT_OPERAND_ATTRIBUTE ::=
SUBTYPE_MARK'Asm_Output (static_string_EXPRESSION, NAME)
INPUT_OPERAND_LIST ::=
[PREFIX.]No_Input_Operands
| INPUT_OPERAND_ATTRIBUTE
| (INPUT_OPERAND_ATTRIBUTE {,INPUT_OPERAND_ATTRIBUTE})
INPUT_OPERAND_ATTRIBUTE ::=
SUBTYPE_MARK'Asm_Input (static_string_EXPRESSION, EXPRESSION)
The identifiers `No_Input_Operands` and `No_Output_Operands`
are declared in the package `Machine_Code` and must be referenced
according to normal visibility rules. In particular if there is no
`use` clause for this package, then appropriate package name
qualification is required.
.. _GNAT_Implementation_of_Tasking:
GNAT Implementation of Tasking
==============================
This chapter outlines the basic GNAT approach to tasking (in particular,
a multi-layered library for portability) and discusses issues related
to compliance with the Real-Time Systems Annex.
.. _Mapping_Ada_Tasks_onto_the_Underlying_Kernel_Threads:
Mapping Ada Tasks onto the Underlying Kernel Threads
----------------------------------------------------
GNAT's run-time support comprises two layers:
* GNARL (GNAT Run-time Layer)
* GNULL (GNAT Low-level Library)
In GNAT, Ada's tasking services rely on a platform and OS independent
layer known as GNARL. This code is responsible for implementing the
correct semantics of Ada's task creation, rendezvous, protected
operations etc.
GNARL decomposes Ada's tasking semantics into simpler lower level
operations such as create a thread, set the priority of a thread,
yield, create a lock, lock/unlock, etc. The spec for these low-level
operations constitutes GNULLI, the GNULL Interface. This interface is
directly inspired from the POSIX real-time API.
If the underlying executive or OS implements the POSIX standard
faithfully, the GNULL Interface maps as is to the services offered by
the underlying kernel. Otherwise, some target dependent glue code maps
the services offered by the underlying kernel to the semantics expected
by GNARL.
Whatever the underlying OS (VxWorks, UNIX, Windows, etc.) the
key point is that each Ada task is mapped on a thread in the underlying
kernel. For example, in the case of VxWorks, one Ada task = one VxWorks task.
In addition Ada task priorities map onto the underlying thread priorities.
Mapping Ada tasks onto the underlying kernel threads has several advantages:
*
The underlying scheduler is used to schedule the Ada tasks. This
makes Ada tasks as efficient as kernel threads from a scheduling
standpoint.
*
Interaction with code written in C containing threads is eased
since at the lowest level Ada tasks and C threads map onto the same
underlying kernel concept.
*
When an Ada task is blocked during I/O the remaining Ada tasks are
able to proceed.
*
On multiprocessor systems Ada tasks can execute in parallel.
Some threads libraries offer a mechanism to fork a new process, with the
child process duplicating the threads from the parent.
GNAT does not
support this functionality when the parent contains more than one task.
.. index:: Forking a new process
.. _Ensuring_Compliance_with_the_Real-Time_Annex:
Ensuring Compliance with the Real-Time Annex
--------------------------------------------
.. index:: Real-Time Systems Annex compliance
Although mapping Ada tasks onto
the underlying threads has significant advantages, it does create some
complications when it comes to respecting the scheduling semantics
specified in the real-time annex (Annex D).
For instance the Annex D requirement for the `FIFO_Within_Priorities`
scheduling policy states:
*When the active priority of a ready task that is not running
changes, or the setting of its base priority takes effect, the
task is removed from the ready queue for its old active priority
and is added at the tail of the ready queue for its new active
priority, except in the case where the active priority is lowered
due to the loss of inherited priority, in which case the task is
added at the head of the ready queue for its new active priority.*
While most kernels do put tasks at the end of the priority queue when
a task changes its priority, (which respects the main
FIFO_Within_Priorities requirement), almost none keep a thread at the
beginning of its priority queue when its priority drops from the loss
of inherited priority.
As a result most vendors have provided incomplete Annex D implementations.
The GNAT run-time, has a nice cooperative solution to this problem
which ensures that accurate FIFO_Within_Priorities semantics are
respected.
The principle is as follows. When an Ada task T is about to start
running, it checks whether some other Ada task R with the same
priority as T has been suspended due to the loss of priority
inheritance. If this is the case, T yields and is placed at the end of
its priority queue. When R arrives at the front of the queue it
executes.
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.
.. _GNAT_Implementation_of_Shared_Passive_Packages:
GNAT Implementation of Shared Passive Packages
==============================================
.. index:: Shared passive packages
GNAT fully implements the pragma `Shared_Passive` for
.. index:: pragma `Shared_Passive`
the purpose of designating shared passive packages.
This allows the use of passive partitions in the
context described in the Ada Reference Manual; i.e., for communication
between separate partitions of a distributed application using the
features in Annex E.
.. index:: Annex E
.. index:: Distribution Systems Annex
However, the implementation approach used by GNAT provides for more
extensive usage as follows:
*Communication between separate programs*
This allows separate programs to access the data in passive
partitions, using protected objects for synchronization where
needed. The only requirement is that the two programs have a
common shared file system. It is even possible for programs
running on different machines with different architectures
(e.g., different endianness) to communicate via the data in
a passive partition.
*Persistence between program runs*
The data in a passive package can persist from one run of a
program to another, so that a later program sees the final
values stored by a previous run of the same program.
The implementation approach used is to store the data in files. A
separate stream file is created for each object in the package, and
an access to an object causes the corresponding file to be read or
written.
.. index:: SHARED_MEMORY_DIRECTORY environment variable
The environment variable `SHARED_MEMORY_DIRECTORY` should be
set to the directory to be used for these files.
The files in this directory
have names that correspond to their fully qualified names. For
example, if we have the package
.. code-block:: ada
package X is
pragma Shared_Passive (X);
Y : Integer;
Z : Float;
end X;
and the environment variable is set to `/stemp/`, then the files created
will have the names:
::
/stemp/x.y
/stemp/x.z
These files are created when a value is initially written to the object, and
the files are retained until manually deleted. This provides the persistence
semantics. If no file exists, it means that no partition has assigned a value
to the variable; in this case the initial value declared in the package
will be used. This model ensures that there are no issues in synchronizing
the elaboration process, since elaboration of passive packages elaborates the
initial values, but does not create the files.
The files are written using normal `Stream_IO` access.
If you want to be able
to communicate between programs or partitions running on different
architectures, then you should use the XDR versions of the stream attribute
routines, since these are architecture independent.
If active synchronization is required for access to the variables in the
shared passive package, then as described in the Ada Reference Manual, the
package may contain protected objects used for this purpose. In this case
a lock file (whose name is :file:`___lock` (three underscores)
is created in the shared memory directory.
.. index:: ___lock file (for shared passive packages)
This is used to provide the required locking
semantics for proper protected object synchronization.
GNAT supports shared passive packages on all platforms
except for OpenVMS.
.. _Code_Generation_for_Array_Aggregates:
Code Generation for Array Aggregates
====================================
Aggregates have a rich syntax and allow the user to specify the values of
complex data structures by means of a single construct. As a result, the
code generated for aggregates can be quite complex and involve loops, case
statements and multiple assignments. In the simplest cases, however, the
compiler will recognize aggregates whose components and constraints are
fully static, and in those cases the compiler will generate little or no
executable code. The following is an outline of the code that GNAT generates
for various aggregate constructs. For further details, you will find it
useful to examine the output produced by the -gnatG flag to see the expanded
source that is input to the code generator. You may also want to examine
the assembly code generated at various levels of optimization.
The code generated for aggregates depends on the context, the component values,
and the type. In the context of an object declaration the code generated is
generally simpler than in the case of an assignment. As a general rule, static
component values and static subtypes also lead to simpler code.
.. _Static_constant_aggregates_with_static_bounds:
Static constant aggregates with static bounds
---------------------------------------------
For the declarations:
.. code-block:: ada
type One_Dim is array (1..10) of integer;
ar0 : constant One_Dim := (1, 2, 3, 4, 5, 6, 7, 8, 9, 0);
GNAT generates no executable code: the constant ar0 is placed in static memory.
The same is true for constant aggregates with named associations:
.. code-block:: ada
Cr1 : constant One_Dim := (4 => 16, 2 => 4, 3 => 9, 1 => 1, 5 .. 10 => 0);
Cr3 : constant One_Dim := (others => 7777);
The same is true for multidimensional constant arrays such as:
.. code-block:: ada
type two_dim is array (1..3, 1..3) of integer;
Unit : constant two_dim := ( (1,0,0), (0,1,0), (0,0,1));
The same is true for arrays of one-dimensional arrays: the following are
static:
.. code-block:: ada
type ar1b is array (1..3) of boolean;
type ar_ar is array (1..3) of ar1b;
None : constant ar1b := (others => false); -- fully static
None2 : constant ar_ar := (1..3 => None); -- fully static
However, for multidimensional aggregates with named associations, GNAT will
generate assignments and loops, even if all associations are static. The
following two declarations generate a loop for the first dimension, and
individual component assignments for the second dimension:
.. code-block:: ada
Zero1: constant two_dim := (1..3 => (1..3 => 0));
Zero2: constant two_dim := (others => (others => 0));
.. _Constant_aggregates_with_unconstrained_nominal_types:
Constant aggregates with unconstrained nominal types
----------------------------------------------------
In such cases the aggregate itself establishes the subtype, so that
associations with `others` cannot be used. GNAT determines the
bounds for the actual subtype of the aggregate, and allocates the
aggregate statically as well. No code is generated for the following:
.. code-block:: ada
type One_Unc is array (natural range <>) of integer;
Cr_Unc : constant One_Unc := (12,24,36);
.. _Aggregates_with_static_bounds:
Aggregates with static bounds
-----------------------------
In all previous examples the aggregate was the initial (and immutable) value
of a constant. If the aggregate initializes a variable, then code is generated
for it as a combination of individual assignments and loops over the target
object. The declarations
.. code-block:: ada
Cr_Var1 : One_Dim := (2, 5, 7, 11, 0, 0, 0, 0, 0, 0);
Cr_Var2 : One_Dim := (others > -1);
generate the equivalent of
.. code-block:: ada
Cr_Var1 (1) := 2;
Cr_Var1 (2) := 3;
Cr_Var1 (3) := 5;
Cr_Var1 (4) := 11;
for I in Cr_Var2'range loop
Cr_Var2 (I) := -1;
end loop;
.. _Aggregates_with_non-static_bounds:
Aggregates with non-static bounds
---------------------------------
If the bounds of the aggregate are not statically compatible with the bounds
of the nominal subtype of the target, then constraint checks have to be
generated on the bounds. For a multidimensional array, constraint checks may
have to be applied to sub-arrays individually, if they do not have statically
compatible subtypes.
.. _Aggregates_in_assignment_statements:
Aggregates in assignment statements
-----------------------------------
In general, aggregate assignment requires the construction of a temporary,
and a copy from the temporary to the target of the assignment. This is because
it is not always possible to convert the assignment into a series of individual
component assignments. For example, consider the simple case:
.. code-block:: ada
A := (A(2), A(1));
This cannot be converted into:
.. code-block:: ada
A(1) := A(2);
A(2) := A(1);
So the aggregate has to be built first in a separate location, and then
copied into the target. GNAT recognizes simple cases where this intermediate
step is not required, and the assignments can be performed in place, directly
into the target. The following sufficient criteria are applied:
*
The bounds of the aggregate are static, and the associations are static.
*
The components of the aggregate are static constants, names of
simple variables that are not renamings, or expressions not involving
indexed components whose operands obey these rules.
If any of these conditions are violated, the aggregate will be built in
a temporary (created either by the front-end or the code generator) and then
that temporary will be copied onto the target.
.. _The_Size_of_Discriminated_Records_with_Default_Discriminants:
The Size of Discriminated Records with Default Discriminants
============================================================
If a discriminated type `T` has discriminants with default values, it is
possible to declare an object of this type without providing an explicit
constraint:
.. code-block:: ada
type Size is range 1..100;
type Rec (D : Size := 15) is record
Name : String (1..D);
end T;
Word : Rec;
Such an object is said to be *unconstrained*.
The discriminant of the object
can be modified by a full assignment to the object, as long as it preserves the
relation between the value of the discriminant, and the value of the components
that depend on it:
.. code-block:: ada
Word := (3, "yes");
Word := (5, "maybe");
Word := (5, "no"); -- raises Constraint_Error
In order to support this behavior efficiently, an unconstrained object is
given the maximum size that any value of the type requires. In the case
above, `Word` has storage for the discriminant and for
a `String` of length 100.
It is important to note that unconstrained objects do not require dynamic
allocation. It would be an improper implementation to place on the heap those
components whose size depends on discriminants. (This improper implementation
was used by some Ada83 compilers, where the `Name` component above
would have
been stored as a pointer to a dynamic string). Following the principle that
dynamic storage management should never be introduced implicitly,
an Ada compiler should reserve the full size for an unconstrained declared
object, and place it on the stack.
This maximum size approach
has been a source of surprise to some users, who expect the default
values of the discriminants to determine the size reserved for an
unconstrained object: "If the default is 15, why should the object occupy
a larger size?"
The answer, of course, is that the discriminant may be later modified,
and its full range of values must be taken into account. This is why the
declaration:
.. code-block:: ada
type Rec (D : Positive := 15) is record
Name : String (1..D);
end record;
Too_Large : Rec;
is flagged by the compiler with a warning:
an attempt to create `Too_Large` will raise `Storage_Error`,
because the required size includes `Positive'Last`
bytes. As the first example indicates, the proper approach is to declare an
index type of 'reasonable' range so that unconstrained objects are not too
large.
One final wrinkle: if the object is declared to be `aliased`, or if it is
created in the heap by means of an allocator, then it is *not*
unconstrained:
it is constrained by the default values of the discriminants, and those values
cannot be modified by full assignment. This is because in the presence of
aliasing all views of the object (which may be manipulated by different tasks,
say) must be consistent, so it is imperative that the object, once created,
remain invariant.
.. _Strict_Conformance_to_the_Ada_Reference_Manual:
Strict Conformance to the Ada Reference Manual
==============================================
The dynamic semantics defined by the Ada Reference Manual impose a set of
run-time checks to be generated. By default, the GNAT compiler will insert many
run-time checks into the compiled code, including most of those required by the
Ada Reference Manual. However, there are three checks that are not enabled
in the default mode for efficiency reasons: arithmetic overflow checking for
integer operations (including division by zero), checks for access before
elaboration on subprogram calls, and stack overflow checking (most operating
systems do not perform this check by default).
Strict conformance to the Ada Reference Manual can be achieved by adding
three compiler options for overflow checking for integer operations
(*-gnato*), dynamic checks for access-before-elaboration on subprogram
calls and generic instantiations (*-gnatE*), and stack overflow
checking (*-fstack-check*).
Note that the result of a floating point arithmetic operation in overflow and
invalid situations, when the `Machine_Overflows` attribute of the result
type is `False`, is to generate IEEE NaN and infinite values. This is the
case for machines compliant with the IEEE floating-point standard, but on
machines that are not fully compliant with this standard, such as Alpha, the
*-mieee* compiler flag must be used for achieving IEEE confirming
behavior (although at the cost of a significant performance penalty), so
infinite and NaN values are properly generated.

165
gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst Normal file
View File

@ -0,0 +1,165 @@
.. _Interfacing_to_Other_Languages:
******************************
Interfacing to Other Languages
******************************
The facilities in Annex B of the Ada Reference Manual are fully
implemented in GNAT, and in addition, a full interface to C++ is
provided.
.. _Interfacing_to_C:
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.
Pragma `Convention C` may be applied to Ada types, but mostly has no
effect, since this is the default. The following table shows the
correspondence between Ada scalar types and the corresponding C types.
======================== ==================================================================
Ada Type C Type
======================== ==================================================================
``Integer`` ``int``
``Short_Integer`` ``short``
``Short_Short_Integer`` ``signed char``
``Long_Integer`` ``long``
``Long_Long_Integer`` ``long long``
``Short_Float`` ``float``
``Float`` ``float``
``Long_Float`` ``double``
``Long_Long_Float`` This is the longest floating-point type supported by the hardware.
======================== ==================================================================
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
8, 16, or 32 bits (i.e., C types `signed char`, `short`,
`int`, respectively) depending on the number of values passed.
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.
.. _Interfacing_to_C++:
Interfacing to C++
==================
The interface to C++ makes use of the following pragmas, which are
primarily intended to be constructed automatically using a binding generator
tool, although it is possible to construct them by hand.
Using these pragmas it is possible to achieve complete
inter-operability between Ada tagged types and C++ class definitions.
See :ref:`Implementation_Defined_Pragmas`, for more details.
*pragma CPP_Class ([Entity =>] `LOCAL_NAME`)*
The argument denotes an entity in the current declarative region that is
declared as a tagged or untagged record type. It indicates that the type
corresponds to an externally declared C++ class type, and is to be laid
out the same way that C++ would lay out the type.
Note: Pragma `CPP_Class` is currently obsolete. It is supported
for backward compatibility but its functionality is available
using pragma `Import` with `Convention` = `CPP`.
*pragma CPP_Constructor ([Entity =>] `LOCAL_NAME`)*
This pragma identifies an imported function (imported in the usual way
with pragma `Import`) as corresponding to a C++ constructor.
A few restrictions are placed on the use of the `Access` attribute
in conjunction with subprograms subject to convention `CPP`: the
attribute may be used neither on primitive operations of a tagged
record type with convention `CPP`, imported or not, nor on
subprograms imported with pragma `CPP_Constructor`.
In addition, C++ exceptions are propagated and can be handled in an
`others` choice of an exception handler. The corresponding Ada
occurrence has no message, and the simple name of the exception identity
contains ``Foreign_Exception``. Finalization and awaiting dependent
tasks works properly when such foreign exceptions are propagated.
It is also possible to import a C++ exception using the following syntax:
::
LOCAL_NAME : exception;
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.
.. _Interfacing_to_COBOL:
Interfacing to COBOL
====================
Interfacing to COBOL is achieved as described in section B.4 of
the Ada Reference Manual.
.. _Interfacing_to_Fortran:
Interfacing to Fortran
======================
Interfacing to Fortran is achieved as described in section B.5 of the
Ada Reference Manual. The pragma `Convention Fortran`, applied to a
multi-dimensional array causes the array to be stored in column-major
order as required for convenient interface to Fortran.
.. _Interfacing_to_non-GNAT_Ada_code:
Interfacing to non-GNAT Ada code
================================
It is possible to specify the convention `Ada` in a pragma
`Import` or pragma `Export`. However this refers to
the calling conventions used by GNAT, which may or may not be
similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
compiler to allow interoperation.
If arguments types are kept simple, and if the foreign compiler generally
follows system calling conventions, then it may be possible to integrate
files compiled by other Ada compilers, provided that the elaboration
issues are adequately addressed (for example by eliminating the
need for any load time elaboration).
In particular, GNAT running on VMS is designed to
be highly compatible with the DEC Ada 83 compiler, so this is one
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.

225
gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst Normal file
View File

@ -0,0 +1,225 @@
.. _Intrinsic_Subprograms:
*********************
Intrinsic Subprograms
*********************
.. index:: Intrinsic Subprograms
GNAT allows a user application program to write the declaration:
.. code-block:: ada
pragma Import (Intrinsic, name);
providing that the name corresponds to one of the implemented intrinsic
subprograms in GNAT, and that the parameter profile of the referenced
subprogram meets the requirements. This chapter describes the set of
implemented intrinsic subprograms, and the requirements on parameter profiles.
Note that no body is supplied; as with other uses of pragma Import, the
body is supplied elsewhere (in this case by the compiler itself). Note
that any use of this feature is potentially non-portable, since the
Ada standard does not require Ada compilers to implement this feature.
.. _Intrinsic_Operators:
Intrinsic Operators
===================
.. index:: Intrinsic operator
All the predefined numeric operators in package Standard
in `pragma Import (Intrinsic,..)`
declarations. In the binary operator case, the operands must have the same
size. The operand or operands must also be appropriate for
the operator. For example, for addition, the operands must
both be floating-point or both be fixed-point, and the
right operand for `"**"` must have a root type of
`Standard.Integer'Base`.
You can use an intrinsic operator declaration as in the following example:
.. code-block:: ada
type Int1 is new Integer;
type Int2 is new Integer;
function "+" (X1 : Int1; X2 : Int2) return Int1;
function "+" (X1 : Int1; X2 : Int2) return Int2;
pragma Import (Intrinsic, "+");
This declaration would permit 'mixed mode' arithmetic on items
of the differing types `Int1` and `Int2`.
It is also possible to specify such operators for private types, if the
full views are appropriate arithmetic types.
.. _Compilation_Date:
Compilation_Date
================
.. index:: Compilation_Date
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Source_Info`. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
`GNAT.Source_Info.Compilation_Date` to obtain the date of
the current compilation (in local time format MMM DD YYYY).
.. _Compilation_Time:
Compilation_Time
================
.. index:: Compilation_Time
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Source_Info`. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
`GNAT.Source_Info.Compilation_Time` to obtain the time of
the current compilation (in local time format HH:MM:SS).
.. _Enclosing_Entity:
Enclosing_Entity
================
.. index:: Enclosing_Entity
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Source_Info`. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
`GNAT.Source_Info.Enclosing_Entity` to obtain the name of
the current subprogram, package, task, entry, or protected subprogram.
.. _Exception_Information:
Exception_Information
=====================
.. index:: Exception_Information'
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Current_Exception`. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
`GNAT.Current_Exception.Exception_Information` to obtain
the exception information associated with the current exception.
.. _Exception_Message:
Exception_Message
=================
.. index:: Exception_Message
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Current_Exception`. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
`GNAT.Current_Exception.Exception_Message` to obtain
the message associated with the current exception.
.. _Exception_Name:
Exception_Name
==============
.. index:: Exception_Name
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Current_Exception`. The only useful
use of the intrinsic import in this case is the one in this unit,
so an application program should simply call the function
`GNAT.Current_Exception.Exception_Name` to obtain
the name of the current exception.
.. _File:
File
====
.. index:: File
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Source_Info`. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
`GNAT.Source_Info.File` to obtain the name of the current
file.
.. _Line:
Line
====
.. index:: Line
This intrinsic subprogram is used in the implementation of the
library package `GNAT.Source_Info`. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
`GNAT.Source_Info.Line` to obtain the number of the current
source line.
.. _Shifts_and_Rotates:
Shifts and Rotates
==================
.. index:: Shift_Left
.. index:: Shift_Right
.. index:: Shift_Right_Arithmetic
.. index:: Rotate_Left
.. index:: Rotate_Right
In standard Ada, the shift and rotate functions are available only
for the predefined modular types in package `Interfaces`. However, in
GNAT it is possible to define these functions for any integer
type (signed or modular), as in this example:
.. code-block:: ada
function Shift_Left
(Value : T;
Amount : Natural) return T;
The function name must be one of
Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
Rotate_Right. T must be an integer type. T'Size must be
8, 16, 32 or 64 bits; if T is modular, the modulus
must be 2**8, 2**16, 2**32 or 2**64.
The result type must be the same as the type of `Value`.
The shift amount must be Natural.
The formal parameter names can be anything.
A more convenient way of providing these shift operators is to use
the Provide_Shift_Operators pragma, which provides the function declarations
and corresponding pragma Import's for all five shift functions.
.. _Source_Location:
Source_Location
===============
.. index:: Source_Location
This intrinsic subprogram is used in the implementation of the
library routine `GNAT.Source_Info`. The only useful use of the
intrinsic import in this case is the one in this unit, so an
application program should simply call the function
`GNAT.Source_Info.Source_Location` to obtain the current
source file location.

82
gcc/ada/doc/gnat_rm/obsolescent_features.rst Normal file
View File

@ -0,0 +1,82 @@
.. _Obsolescent_Features:
********************
Obsolescent Features
********************
This chapter describes features that are provided by GNAT, but are
considered obsolescent since there are preferred ways of achieving
the same effect. These features are provided solely for historical
compatibility purposes.
.. _pragma_No_Run_Time:
pragma No_Run_Time
==================
The pragma `No_Run_Time` is used to achieve an affect similar
to the use of the "Zero Foot Print" configurable run time, but without
requiring a specially configured run time. The result of using this
pragma, which must be used for all units in a partition, is to restrict
the use of any language features requiring run-time support code. The
preferred usage is to use an appropriately configured run-time that
includes just those features that are to be made accessible.
.. _pragma_Ravenscar:
pragma Ravenscar
================
The pragma `Ravenscar` has exactly the same effect as pragma
`Profile (Ravenscar)`. The latter usage is preferred since it
is part of the new Ada 2005 standard.
.. _pragma_Restricted_Run_Time:
pragma Restricted_Run_Time
==========================
The pragma `Restricted_Run_Time` has exactly the same effect as
pragma `Profile (Restricted)`. The latter usage is
preferred since the Ada 2005 pragma `Profile` is intended for
this kind of implementation dependent addition.
.. _pragma_Task_Info:
pragma Task_Info
================
The functionality provided by pragma `Task_Info` is now part of the
Ada language. The `CPU` aspect and the package
`System.Multiprocessors` offer a less system-dependent way to specify
task affinity or to query the number of processsors.
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`.
The `Task_Info` pragma provides system dependent control over
aspects of tasking implementation, for example, the ability to map
tasks to specific processors. For details on the facilities available
for the version of GNAT that you are using, see the documentation
in the spec of package System.Task_Info in the runtime
library.
.. _package_System_Task_Info:
package System.Task_Info (:file:`s-tasinf.ads`)
===============================================
This package provides target dependent functionality that is used
to support the `Task_Info` pragma. The predefined Ada package
`System.Multiprocessors` and the `CPU` aspect now provide a
standard replacement for GNAT's `Task_Info` functionality.
.. raw:: latex
\appendix

2138
gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst Normal file
View File

File diff suppressed because it is too large Load Diff

37
gcc/ada/doc/gnat_rm/specialized_needs_annexes.rst Normal file
View File

@ -0,0 +1,37 @@
.. _Specialized_Needs_Annexes:
*************************
Specialized Needs Annexes
*************************
Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not
required in all implementations. However, as described in this chapter,
GNAT implements all of these annexes:
*Systems Programming (Annex C)*
The Systems Programming Annex is fully implemented.
*Real-Time Systems (Annex D)*
The Real-Time Systems Annex is fully implemented.
*Distributed Systems (Annex E)*
Stub generation is fully implemented in the GNAT compiler. In addition,
a complete compatible PCS is available as part of the GLADE system,
a separate product. When the two
products are used in conjunction, this annex is fully implemented.
*Information Systems (Annex F)*
The Information Systems annex is fully implemented.
*Numerics (Annex G)*
The Numerics Annex is fully implemented.
*Safety and Security / High-Integrity Systems (Annex H)*
The Safety and Security Annex (termed the High-Integrity Systems Annex
in Ada 2005) is fully implemented.

1057
gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst Normal file
View File

File diff suppressed because it is too large Load Diff

709
gcc/ada/doc/gnat_rm/standard_library_routines.rst Normal file
View File

@ -0,0 +1,709 @@
.. _Standard_Library_Routines:
*************************
Standard Library Routines
*************************
The Ada Reference Manual contains in Annex A a full description of an
extensive set of standard library routines that can be used in any Ada
program, and which must be provided by all Ada compilers. They are
analogous to the standard C library used by C programs.
GNAT implements all of the facilities described in annex A, and for most
purposes the description in the Ada Reference Manual, or appropriate Ada
text book, will be sufficient for making use of these facilities.
In the case of the input-output facilities,
:ref:`The_Implementation_of_Standard_I/O`,
gives details on exactly how GNAT interfaces to the
file system. For the remaining packages, the Ada Reference Manual
should be sufficient. The following is a list of the packages included,
together with a brief description of the functionality that is provided.
For completeness, references are included to other predefined library
routines defined in other sections of the Ada Reference Manual (these are
cross-indexed from Annex A). For further details see the relevant
package declarations in the run-time library. In particular, a few units
are not implemented, as marked by the presence of pragma Unimplemented_Unit,
and in this case the package declaration contains comments explaining why
the unit is not implemented.
``Ada`` *(A.2)*
This is a parent package for all the standard library packages. It is
usually included implicitly in your program, and itself contains no
useful data or routines.
``Ada.Assertions`` *(11.4.2)*
`Assertions` provides the `Assert` subprograms, and also
the declaration of the `Assertion_Error` exception.
``Ada.Asynchronous_Task_Control`` *(D.11)*
`Asynchronous_Task_Control` provides low level facilities for task
synchronization. It is typically not implemented. See package spec for details.
``Ada.Calendar`` *(9.6)*
`Calendar` provides time of day access, and routines for
manipulating times and durations.
``Ada.Calendar.Arithmetic`` *(9.6.1)*
This package provides additional arithmetic
operations for `Calendar`.
``Ada.Calendar.Formatting`` *(9.6.1)*
This package provides formatting operations for `Calendar`.
``Ada.Calendar.Time_Zones`` *(9.6.1)*
This package provides additional `Calendar` facilities
for handling time zones.
``Ada.Characters`` *(A.3.1)*
This is a dummy parent package that contains no useful entities
``Ada.Characters.Conversions`` *(A.3.2)*
This package provides character conversion functions.
``Ada.Characters.Handling`` *(A.3.2)*
This package provides some basic character handling capabilities,
including classification functions for classes of characters (e.g., test
for letters, or digits).
``Ada.Characters.Latin_1`` *(A.3.3)*
This package includes a complete set of definitions of the characters
that appear in type CHARACTER. It is useful for writing programs that
will run in international environments. For example, if you want an
upper case E with an acute accent in a string, it is often better to use
the definition of `UC_E_Acute` in this package. Then your program
will print in an understandable manner even if your environment does not
support these extended characters.
``Ada.Command_Line`` *(A.15)*
This package provides access to the command line parameters and the name
of the current program (analogous to the use of `argc` and `argv`
in C), and also allows the exit status for the program to be set in a
system-independent manner.
``Ada.Complex_Text_IO`` *(G.1.3)*
This package provides text input and output of complex numbers.
``Ada.Containers`` *(A.18.1)*
A top level package providing a few basic definitions used by all the
following specific child packages that provide specific kinds of
containers.
``Ada.Containers.Bounded_Priority_Queues`` *(A.18.31)*
``Ada.Containers.Bounded_Synchronized_Queues`` *(A.18.29)*
``Ada.Containers.Doubly_Linked_Lists`` *(A.18.3)*
``Ada.Containers.Generic_Array_Sort`` *(A.18.26)*
``Ada.Containers.Generic_Constrained_Array_Sort`` *(A.18.26)*
``Ada.Containers.Generic_Sort`` *(A.18.26)*
``Ada.Containers.Hashed_Maps`` *(A.18.5)*
``Ada.Containers.Hashed_Sets`` *(A.18.8)*
``Ada.Containers.Indefinite_Doubly_Linked_Lists`` *(A.18.12)*
``Ada.Containers.Indefinite_Hashed_Maps`` *(A.18.13)*
``Ada.Containers.Indefinite_Hashed_Sets`` *(A.18.15)*
``Ada.Containers.Indefinite_Holders`` *(A.18.18)*
``Ada.Containers.Indefinite_Multiway_Trees`` *(A.18.17)*
``Ada.Containers.Indefinite_Ordered_Maps`` *(A.18.14)*
``Ada.Containers.Indefinite_Ordered_Sets`` *(A.18.16)*
``Ada.Containers.Indefinite_Vectors`` *(A.18.11)*
``Ada.Containers.Multiway_Trees`` *(A.18.10)*
``Ada.Containers.Ordered_Maps`` *(A.18.6)*
``Ada.Containers.Ordered_Sets`` *(A.18.9)*
``Ada.Containers.Synchronized_Queue_Interfaces`` *(A.18.27)*
``Ada.Containers.Unbounded_Priority_Queues`` *(A.18.30)*
``Ada.Containers.Unbounded_Synchronized_Queues`` *(A.18.28)*
``Ada.Containers.Vectors`` *(A.18.2)*
``Ada.Directories`` *(A.16)*
This package provides operations on directories.
``Ada.Directories.Hierarchical_File_Names`` *(A.16.1)*
This package provides additional directory operations handling
hiearchical file names.
``Ada.Directories.Information`` *(A.16)*
This is an implementation defined package for additional directory
operations, which is not implemented in GNAT.
``Ada.Decimal`` *(F.2)*
This package provides constants describing the range of decimal numbers
implemented, and also a decimal divide routine (analogous to the COBOL
verb DIVIDE ... GIVING ... REMAINDER ...)
``Ada.Direct_IO`` *(A.8.4)*
This package provides input-output using a model of a set of records of
fixed-length, containing an arbitrary definite Ada type, indexed by an
integer record number.
``Ada.Dispatching`` *(D.2.1)*
A parent package containing definitions for task dispatching operations.
``Ada.Dispatching.EDF`` *(D.2.6)*
Not implemented in GNAT.
``Ada.Dispatching.Non_Preemptive`` *(D.2.4)*
Not implemented in GNAT.
``Ada.Dispatching.Round_Robin`` *(D.2.5)*
Not implemented in GNAT.
``Ada.Dynamic_Priorities`` *(D.5)*
This package allows the priorities of a task to be adjusted dynamically
as the task is running.
``Ada.Environment_Variables`` *(A.17)*
This package provides facilities for accessing environment variables.
``Ada.Exceptions`` *(11.4.1)*
This package provides additional information on exceptions, and also
contains facilities for treating exceptions as data objects, and raising
exceptions with associated messages.
``Ada.Execution_Time`` *(D.14)*
Not implemented in GNAT.
``Ada.Execution_Time.Group_Budgets`` *(D.14.2)*
Not implemented in GNAT.
``Ada.Execution_Time.Timers`` *(D.14.1)'*
Not implemented in GNAT.
``Ada.Finalization`` *(7.6)*
This package contains the declarations and subprograms to support the
use of controlled types, providing for automatic initialization and
finalization (analogous to the constructors and destructors of C++).
``Ada.Float_Text_IO`` *(A.10.9)*
A library level instantiation of Text_IO.Float_IO for type Float.
``Ada.Float_Wide_Text_IO`` *(A.10.9)*
A library level instantiation of Wide_Text_IO.Float_IO for type Float.
``Ada.Float_Wide_Wide_Text_IO`` *(A.10.9)*
A library level instantiation of Wide_Wide_Text_IO.Float_IO for type Float.
``Ada.Integer_Text_IO`` *(A.10.9)*
A library level instantiation of Text_IO.Integer_IO for type Integer.
``Ada.Integer_Wide_Text_IO`` *(A.10.9)*
A library level instantiation of Wide_Text_IO.Integer_IO for type Integer.
``Ada.Integer_Wide_Wide_Text_IO`` *(A.10.9)*
A library level instantiation of Wide_Wide_Text_IO.Integer_IO for type Integer.
``Ada.Interrupts`` *(C.3.2)*
This package provides facilities for interfacing to interrupts, which
includes the set of signals or conditions that can be raised and
recognized as interrupts.
``Ada.Interrupts.Names`` *(C.3.2)*
This package provides the set of interrupt names (actually signal
or condition names) that can be handled by GNAT.
``Ada.IO_Exceptions`` *(A.13)*
This package defines the set of exceptions that can be raised by use of
the standard IO packages.
``Ada.Iterator_Interfaces`` *(5.5.1)*
This package provides a generic interface to generalized iterators.
``Ada.Locales`` *(A.19)*
This package provides declarations providing information (Language
and Country) about the current locale.
``Ada.Numerics``
This package contains some standard constants and exceptions used
throughout the numerics packages. Note that the constants pi and e are
defined here, and it is better to use these definitions than rolling
your own.
``Ada.Numerics.Complex_Arrays`` *(G.3.2)*
Provides operations on arrays of complex numbers.
``Ada.Numerics.Complex_Elementary_Functions``
Provides the implementation of standard elementary functions (such as
log and trigonometric functions) operating on complex numbers using the
standard `Float` and the `Complex` and `Imaginary` types
created by the package `Numerics.Complex_Types`.
``Ada.Numerics.Complex_Types``
This is a predefined instantiation of
`Numerics.Generic_Complex_Types` using `Standard.Float` to
build the type `Complex` and `Imaginary`.
``Ada.Numerics.Discrete_Random``
This generic package provides a random number generator suitable for generating
uniformly distributed values of a specified discrete subtype.
``Ada.Numerics.Float_Random``
This package provides a random number generator suitable for generating
uniformly distributed floating point values in the unit interval.
``Ada.Numerics.Generic_Complex_Elementary_Functions``
This is a generic version of the package that provides the
implementation of standard elementary functions (such as log and
trigonometric functions) for an arbitrary complex type.
The following predefined instantiations of this package are provided:
* ``Short_Float``
`Ada.Numerics.Short_Complex_Elementary_Functions`
* ``Float``
`Ada.Numerics.Complex_Elementary_Functions`
* ``Long_Float``
`Ada.Numerics.Long_Complex_Elementary_Functions`
``Ada.Numerics.Generic_Complex_Types``
This is a generic package that allows the creation of complex types,
with associated complex arithmetic operations.
The following predefined instantiations of this package exist
* ``Short_Float``
`Ada.Numerics.Short_Complex_Complex_Types`
* ``Float``
`Ada.Numerics.Complex_Complex_Types`
* ``Long_Float``
`Ada.Numerics.Long_Complex_Complex_Types`
``Ada.Numerics.Generic_Elementary_Functions``
This is a generic package that provides the implementation of standard
elementary functions (such as log an trigonometric functions) for an
arbitrary float type.
The following predefined instantiations of this package exist
* ``Short_Float``
`Ada.Numerics.Short_Elementary_Functions`
* ``Float``
`Ada.Numerics.Elementary_Functions`
* ``Long_Float``
`Ada.Numerics.Long_Elementary_Functions`
``Ada.Numerics.Generic_Real_Arrays`` *(G.3.1)*
Generic operations on arrays of reals
``Ada.Numerics.Real_Arrays`` *(G.3.1)*
Preinstantiation of Ada.Numerics.Generic_Real_Arrays (Float).
``Ada.Real_Time`` *(D.8)*
This package provides facilities similar to those of `Calendar`, but
operating with a finer clock suitable for real time control. Note that
annex D requires that there be no backward clock jumps, and GNAT generally
guarantees this behavior, but of course if the external clock on which
the GNAT runtime depends is deliberately reset by some external event,
then such a backward jump may occur.
``Ada.Real_Time.Timing_Events`` *(D.15)*
Not implemented in GNAT.
``Ada.Sequential_IO`` *(A.8.1)*
This package provides input-output facilities for sequential files,
which can contain a sequence of values of a single type, which can be
any Ada type, including indefinite (unconstrained) types.
``Ada.Storage_IO`` *(A.9)*
This package provides a facility for mapping arbitrary Ada types to and
from a storage buffer. It is primarily intended for the creation of new
IO packages.
``Ada.Streams`` *(13.13.1)*
This is a generic package that provides the basic support for the
concept of streams as used by the stream attributes (`Input`,
`Output`, `Read` and `Write`).
``Ada.Streams.Stream_IO`` *(A.12.1)*
This package is a specialization of the type `Streams` defined in
package `Streams` together with a set of operations providing
Stream_IO capability. The Stream_IO model permits both random and
sequential access to a file which can contain an arbitrary set of values
of one or more Ada types.
``Ada.Strings`` *(A.4.1)*
This package provides some basic constants used by the string handling
packages.
``Ada.Strings.Bounded`` *(A.4.4)*
This package provides facilities for handling variable length
strings. The bounded model requires a maximum length. It is thus
somewhat more limited than the unbounded model, but avoids the use of
dynamic allocation or finalization.
``Ada.Strings.Bounded.Equal_Case_Insensitive`` *(A.4.10)*
Provides case-insensitive comparisons of bounded strings
``Ada.Strings.Bounded.Hash`` *(A.4.9)*
This package provides a generic hash function for bounded strings
``Ada.Strings.Bounded.Hash_Case_Insensitive`` *(A.4.9)*
This package provides a generic hash function for bounded strings that
converts the string to be hashed to lower case.
``Ada.Strings.Bounded.Less_Case_Insensitive`` *(A.4.10)*
This package provides a comparison function for bounded strings that works
in a case insensitive manner by converting to lower case before the comparison.
``Ada.Strings.Fixed`` *(A.4.3)*
This package provides facilities for handling fixed length strings.
``Ada.Strings.Fixed.Equal_Case_Insensitive`` *(A.4.10)*
This package provides an equality function for fixed strings that compares
the strings after converting both to lower case.
``Ada.Strings.Fixed.Hash_Case_Insensitive`` *(A.4.9)*
This package provides a case insensitive hash function for fixed strings that
converts the string to lower case before computing the hash.
``Ada.Strings.Fixed.Less_Case_Insensitive`` *(A.4.10)*
This package provides a comparison function for fixed strings that works
in a case insensitive manner by converting to lower case before the comparison.
``Ada.Strings.Hash`` *(A.4.9)*
This package provides a hash function for strings.
``Ada.Strings.Hash_Case_Insensitive`` *(A.4.9)*
This package provides a hash function for strings that is case insensitive.
The string is converted to lower case before computing the hash.
``Ada.Strings.Less_Case_Insensitive`` *(A.4.10)*
This package provides a comparison function for\\strings that works
in a case insensitive manner by converting to lower case before the comparison.
``Ada.Strings.Maps`` *(A.4.2)*
This package provides facilities for handling character mappings and
arbitrarily defined subsets of characters. For instance it is useful in
defining specialized translation tables.
``Ada.Strings.Maps.Constants`` *(A.4.6)*
This package provides a standard set of predefined mappings and
predefined character sets. For example, the standard upper to lower case
conversion table is found in this package. Note that upper to lower case
conversion is non-trivial if you want to take the entire set of
characters, including extended characters like E with an acute accent,
into account. You should use the mappings in this package (rather than
adding 32 yourself) to do case mappings.
``Ada.Strings.Unbounded`` *(A.4.5)*
This package provides facilities for handling variable length
strings. The unbounded model allows arbitrary length strings, but
requires the use of dynamic allocation and finalization.
``Ada.Strings.Unbounded.Equal_Case_Insensitive`` *(A.4.10)*
Provides case-insensitive comparisons of unbounded strings
``Ada.Strings.Unbounded.Hash`` *(A.4.9)*
This package provides a generic hash function for unbounded strings
``Ada.Strings.Unbounded.Hash_Case_Insensitive`` *(A.4.9)*
This package provides a generic hash function for unbounded strings that
converts the string to be hashed to lower case.
``Ada.Strings.Unbounded.Less_Case_Insensitive`` *(A.4.10)*
This package provides a comparison function for unbounded strings that works
in a case insensitive manner by converting to lower case before the comparison.
``Ada.Strings.UTF_Encoding`` *(A.4.11)*
This package provides basic definitions for dealing with UTF-encoded strings.
``Ada.Strings.UTF_Encoding.Conversions`` *(A.4.11)*
This package provides conversion functions for UTF-encoded strings.
``Ada.Strings.UTF_Encoding.Strings`` *(A.4.11)*
``Ada.Strings.UTF_Encoding.Wide_Strings`` *(A.4.11)*
``Ada.Strings.UTF_Encoding.Wide_Wide_Strings`` *(A.4.11)*
These packages provide facilities for handling UTF encodings for
Strings, Wide_Strings and Wide_Wide_Strings.
``Ada.Strings.Wide_Bounded`` *(A.4.7)*
``Ada.Strings.Wide_Fixed`` *(A.4.7)*
``Ada.Strings.Wide_Maps`` *(A.4.7)*
``Ada.Strings.Wide_Unbounded`` *(A.4.7)*
These packages provide analogous capabilities to the corresponding
packages without ``Wide_`` in the name, but operate with the types
`Wide_String` and `Wide_Character` instead of `String`
and `Character`. Versions of all the child packages are available.
``Ada.Strings.Wide_Wide_Bounded`` *(A.4.7)*
``Ada.Strings.Wide_Wide_Fixed`` *(A.4.7)*
``Ada.Strings.Wide_Wide_Maps`` *(A.4.7)*
``Ada.Strings.Wide_Wide_Unbounded`` *(A.4.7)*
These packages provide analogous capabilities to the corresponding
packages without ``Wide_`` in the name, but operate with the types
`Wide_Wide_String` and `Wide_Wide_Character` instead
of `String` and `Character`.
``Ada.Synchronous_Barriers`` *(D.10.1)*
This package provides facilities for synchronizing tasks at a low level
with barriers.
``Ada.Synchronous_Task_Control`` *(D.10)*
This package provides some standard facilities for controlling task
communication in a synchronous manner.
``Ada.Synchronous_Task_Control.EDF`` *(D.10)*
Not implemented in GNAT.
``Ada.Tags``
This package contains definitions for manipulation of the tags of tagged
values.
``Ada.Tags.Generic_Dispatching_Constructor`` *(3.9)*
This package provides a way of constructing tagged class-wide values given
only the tag value.
``Ada.Task_Attributes`` *(C.7.2)*
This package provides the capability of associating arbitrary
task-specific data with separate tasks.
``Ada.Task_Identifification`` *(C.7.1)*
This package provides capabilities for task identification.
``Ada.Task_Termination`` *(C.7.3)*
This package provides control over task termination.
``Ada.Text_IO``
This package provides basic text input-output capabilities for
character, string and numeric data. The subpackages of this
package are listed next. Note that although these are defined
as subpackages in the RM, they are actually transparently
implemented as child packages in GNAT, meaning that they
are only loaded if needed.
``Ada.Text_IO.Decimal_IO``
Provides input-output facilities for decimal fixed-point types
``Ada.Text_IO.Enumeration_IO``
Provides input-output facilities for enumeration types.
``Ada.Text_IO.Fixed_IO``
Provides input-output facilities for ordinary fixed-point types.
``Ada.Text_IO.Float_IO``
Provides input-output facilities for float types. The following
predefined instantiations of this generic package are available:
* ``Short_Float``
`Short_Float_Text_IO`
* ``Float``
`Float_Text_IO`
* ``Long_Float``
`Long_Float_Text_IO`
``Ada.Text_IO.Integer_IO``
Provides input-output facilities for integer types. The following
predefined instantiations of this generic package are available:
* ``Short_Short_Integer``
`Ada.Short_Short_Integer_Text_IO`
* ``Short_Integer``
`Ada.Short_Integer_Text_IO`
* ``Integer``
`Ada.Integer_Text_IO`
* ``Long_Integer``
`Ada.Long_Integer_Text_IO`
* ``Long_Long_Integer``
`Ada.Long_Long_Integer_Text_IO`
``Ada.Text_IO.Modular_IO``
Provides input-output facilities for modular (unsigned) types.
``Ada.Text_IO.Bounded_IO (A.10.11)``
Provides input-output facilities for bounded strings.
``Ada.Text_IO.Complex_IO (G.1.3)``
This package provides basic text input-output capabilities for complex
data.
``Ada.Text_IO.Editing (F.3.3)``
This package contains routines for edited output, analogous to the use
of pictures in COBOL. The picture formats used by this package are a
close copy of the facility in COBOL.
``Ada.Text_IO.Text_Streams (A.12.2)``
This package provides a facility that allows Text_IO files to be treated
as streams, so that the stream attributes can be used for writing
arbitrary data, including binary data, to Text_IO files.
``Ada.Text_IO.Unbounded_IO (A.10.12)``
This package provides input-output facilities for unbounded strings.
``Ada.Unchecked_Conversion (13.9)``
This generic package allows arbitrary conversion from one type to
another of the same size, providing for breaking the type safety in
special circumstances.
If the types have the same Size (more accurately the same Value_Size),
then the effect is simply to transfer the bits from the source to the
target type without any modification. This usage is well defined, and
for simple types whose representation is typically the same across
all implementations, gives a portable method of performing such
conversions.
If the types do not have the same size, then the result is implementation
defined, and thus may be non-portable. The following describes how GNAT
handles such unchecked conversion cases.
If the types are of different sizes, and are both discrete types, then
the effect is of a normal type conversion without any constraint checking.
In particular if the result type has a larger size, the result will be
zero or sign extended. If the result type has a smaller size, the result
will be truncated by ignoring high order bits.
If the types are of different sizes, and are not both discrete types,
then the conversion works as though pointers were created to the source
and target, and the pointer value is converted. The effect is that bits
are copied from successive low order storage units and bits of the source
up to the length of the target type.
A warning is issued if the lengths differ, since the effect in this
case is implementation dependent, and the above behavior may not match
that of some other compiler.
A pointer to one type may be converted to a pointer to another type using
unchecked conversion. The only case in which the effect is undefined is
when one or both pointers are pointers to unconstrained array types. In
this case, the bounds information may get incorrectly transferred, and in
particular, GNAT uses double size pointers for such types, and it is
meaningless to convert between such pointer types. GNAT will issue a
warning if the alignment of the target designated type is more strict
than the alignment of the source designated type (since the result may
be unaligned in this case).
A pointer other than a pointer to an unconstrained array type may be
converted to and from System.Address. Such usage is common in Ada 83
programs, but note that Ada.Address_To_Access_Conversions is the
preferred method of performing such conversions in Ada 95 and Ada 2005.
Neither
unchecked conversion nor Ada.Address_To_Access_Conversions should be
used in conjunction with pointers to unconstrained objects, since
the bounds information cannot be handled correctly in this case.
``Ada.Unchecked_Deallocation`` *(13.11.2)*
This generic package allows explicit freeing of storage previously
allocated by use of an allocator.
``Ada.Wide_Text_IO`` *(A.11)*
This package is similar to `Ada.Text_IO`, except that the external
file supports wide character representations, and the internal types are
`Wide_Character` and `Wide_String` instead of `Character`
and `String`. The corresponding set of nested packages and child
packages are defined.
``Ada.Wide_Wide_Text_IO`` *(A.11)*
This package is similar to `Ada.Text_IO`, except that the external
file supports wide character representations, and the internal types are
`Wide_Character` and `Wide_String` instead of `Character`
and `String`. The corresponding set of nested packages and child
packages are defined.
For packages in Interfaces and System, all the RM defined packages are
available in GNAT, see the Ada 2012 RM for full details.

2218
gcc/ada/doc/gnat_rm/the_gnat_library.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1252
gcc/ada/doc/gnat_rm/the_implementation_of_standard_i_o.rst Normal file
View File

File diff suppressed because it is too large Load Diff

63
gcc/ada/doc/gnat_ugn.rst Normal file
View File

@ -0,0 +1,63 @@
GNAT User's Guide for Native Platforms
======================================
*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}@*
AdaCore
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover Texts being
"GNAT User's Guide for Native Platforms",
and with no Back-Cover Texts. A copy of the license is
included in the section entitled :ref:`gnu_fdl`.
.. toctree::
:maxdepth: 3
:numbered:
gnat_ugn/about_this_guide
gnat_ugn/getting_started_with_gnat
gnat_ugn/the_gnat_compilation_model
gnat_ugn/building_executable_programs_with_gnat
gnat_ugn/gnat_project_manager
gnat_ugn/tools_supporting_project_files
gnat_ugn/gnat_utility_programs
gnat_ugn/gnat_and_program_execution
.. raw:: latex
\appendix
.. toctree::
:maxdepth: 3
A. Platform-Specific Information <gnat_ugn/platform_specific_information>
B. Example of Binder Output <gnat_ugn/example_of_binder_output>
C. Elaboration Order Handling in GNAT <gnat_ugn/elaboration_order_handling_in_gnat>
D. Inline Assembler <gnat_ugn/inline_assembler>
E. GNU Free Documentation License <share/gnu_free_documentation_license>

223
gcc/ada/doc/gnat_ugn/about_this_guide.rst Normal file
View File

@ -0,0 +1,223 @@
.. _About_This_Guide:
About This Guide
~~~~~~~~~~~~~~~~
.. only:: PRO
For ease of exposition, 'GNAT Pro' will be referred to simply as
'GNAT' in the remainder of this document.
This guide describes the use of GNAT,
a compiler and software development
toolset for the full Ada programming language.
It documents the features of the compiler and tools, and explains
how to use them to build Ada applications.
GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
invoked in Ada 83 compatibility mode.
By default, GNAT assumes Ada 2012, but you can override with a
compiler switch (:ref:`Compiling_Different_Versions_of_Ada`)
to explicitly specify the language version.
Throughout this manual, references to 'Ada' without a year suffix
apply to all Ada 95/2005/2012 versions of the language.
What This Guide Contains
========================
This guide contains the following chapters:
* :ref:`Getting_Started_with_GNAT` describes how to get started compiling
and running Ada programs with the GNAT Ada programming environment.
* :ref:`The_GNAT_Compilation_Model` describes the compilation model used
by GNAT.
* :ref:`Building_Executable_Programs_With_GNAT` describes how to use the
main GNAT tools to build executable programs, and it also gives examples of
using the GNU make utility with GNAT.
* :ref:`GNAT_Project_Manager` describes how to use project files
to organize large projects.
* :ref:`Tools_Supporting_Project_Files` described how to use the project
facility in conjunction with various GNAT tools.
* :ref:`GNAT_Utility_Programs` explains the various utility programs that
are included in the GNAT environment
* :ref:`GNAT_and_Program_Execution` covers a number of topics related to
running, debugging, and tuning the performace of programs developed
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.
* :ref:`Elaboration_Order_Handling_in_GNAT` describes how GNAT helps
you deal with elaboration order issues.
* :ref:`Inline_Assembler` shows how to use the inline assembly facility
in an Ada program.
What You Should Know before Reading This Guide
==============================================
.. index:: Ada 95 Language Reference Manual
.. index:: Ada 2005 Language Reference Manual
This guide assumes a basic familiarity with the Ada 95 language, as
described in the International Standard ANSI/ISO/IEC-8652:1995, January
1995.
It does not require knowledge of the features introduced by Ada 2005
or Ada 2012.
Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in
the GNAT documentation package.
Related Information
===================
For further information about Ada and related tools, please refer to the
following documents:
* :title:`Ada 95 Reference Manual`, :title:`Ada 2005 Reference Manual`, and
:title:`Ada 2012 Reference Manual`, which contain reference
material for the several revisions of the Ada language standard.
* :title:`GNAT Reference_Manual`, which contains all reference material for the GNAT
implementation of Ada.
* :title:`Using the GNAT Programming Studio`, which describes the GPS
Integrated Development Environment.
* :title:`GNAT Programming Studio Tutorial`, which introduces the
main GPS features through examples.
* :title:`Debugging with GDB`,
for all details on the use of the GNU source-level debugger.
* :title:`GNU Emacs Manual`,
for full information on the extensible editor and programming
environment Emacs.
A Note to Readers of Previous Versions of the Manual
====================================================
In early 2015 the GNAT manuals were transitioned to the
reStructuredText (rst) / Sphinx documentation generator technology.
During that process the :title:`GNAT User's Guide` was reorganized
so that related topics would be described together in the same chapter
or appendix. Here's a summary of the major changes realized in
the new document structure.
* :ref:`The_GNAT_Compilation_Model` has been extended so that it now covers
the following material:
- The `gnatname`, `gnatkr`, and `gnatchop` tools
- :ref:`Configuration_Pragmas`
- :ref:`GNAT_and_Libraries`
- :ref:`Conditional_Compilation` including :ref:`Preprocessing_with_gnatprep`
and :ref:`Integrated_Preprocessing`
- :ref:`Generating_Ada_Bindings_for_C_and_C++_headers`
- :ref:`Using_GNAT_Files_with_External_Tools`
* :ref:`Building_Executable_Programs_With_GNAT` is a new chapter consolidating
the following content:
- :ref:`The_GNAT_Make_Program_gnatmake`
- :ref:`Compiling_with_GCC`
- :ref:`Binding_with_gnatbind`
- :ref:`Linking_with_gnatlink`
- :ref:`Using_the_GNU_make_Utility`
* :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`
- :ref:`The_GNAT_Library_Browser_gnatls`
- :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
- :ref:`The_Ada_to_HTML_Converter_gnathtml`
- :ref:`The_Ada-to-XML_Converter_gnat2xml`
- :ref:`The_Program_Property_Verifier_gnatcheck`
- :ref:`The_GNAT_Metrics_Tool_gnatmetric`
- :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`
- :ref:`The_GNAT_Library_Browser_gnatls`
- :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
- :ref:`The_Ada_to_HTML_Converter_gnathtml`
* :ref:`GNAT_and_Program_Execution` is a new chapter consolidating the following:
- :ref:`Running_and_Debugging_Ada_Programs`
- :ref:`Code_Coverage_and_Profiling`
- :ref:`Improving_Performance`
- :ref:`Overflow Check Handling in GNAT <Overflow_Check_Handling_in_GNAT>`
- :ref:`Performing Dimensionality Analysis in GNAT <Performing_Dimensionality_Analysis_in_GNAT>`
- :ref:`Stack_Related_Facilities`
- :ref:`Memory_Management_Issues`
* :ref:`Platform_Specific_Information` is a new appendix consolidating the following:
- :ref:`Run_Time_Libraries`
- :ref:`Microsoft_Windows_Topics`
- :ref:`Mac_OS_Topics`
* The `Compatibility and Porting Guide` appendix has been moved to the
:title:`GNAT Reference Manual`. It now includes a section
`Writing Portable Fixed-Point Declarations` which was previously
a separate chapter in the :title:`GNAT User's Guide`.
Conventions
===========
.. index:: Conventions, typographical
.. index:: Typographical conventions
Following are examples of the typographical and graphic conventions used
in this guide:
* `Functions`, `utility program names`, `standard names`,
and `classes`.
* `Option flags`
* :file:`File names`
* `Variables`
* *Emphasis*
* [optional information or parameters]
* Examples are described by text
::
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.
* Full file names are shown with the '/' character
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.

7381
gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst Normal file
View File

File diff suppressed because it is too large Load Diff

1864
gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst Normal file
View File

File diff suppressed because it is too large Load Diff

750
gcc/ada/doc/gnat_ugn/example_of_binder_output.rst Normal file
View File

@ -0,0 +1,750 @@
.. _Example_of_Binder_Output_File:
*****************************
Example of Binder Output File
*****************************
.. index:: Binder output (example)
This Appendix displays the source code for the output file
generated by *gnatbind* for a simple 'Hello World' program.
Comments have been added for clarification purposes.
.. code-block:: ada
-- The package is called Ada_Main unless this name is actually used
-- as a unit name in the partition, in which case some other unique
-- name is used.
pragma Ada_95;
with System;
package ada_main is
pragma Warnings (Off);
-- The main program saves the parameters (argument count,
-- argument values, environment pointer) in global variables
-- for later access by other units including
-- Ada.Command_Line.
gnat_argc : Integer;
gnat_argv : System.Address;
gnat_envp : System.Address;
-- The actual variables are stored in a library routine. This
-- is useful for some shared library situations, where there
-- are problems if variables are not in the library.
pragma Import (C, gnat_argc);
pragma Import (C, gnat_argv);
pragma Import (C, gnat_envp);
-- The exit status is similarly an external location
gnat_exit_status : Integer;
pragma Import (C, gnat_exit_status);
GNAT_Version : constant String :=
"GNAT Version: Pro 7.4.0w (20141119-49)" & ASCII.NUL;
pragma Export (C, GNAT_Version, "__gnat_version");
Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL;
pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name");
-- This is the generated adainit routine that performs
-- initialization at the start of execution. In the case
-- where Ada is the main program, this main program makes
-- a call to adainit at program startup.
procedure adainit;
pragma Export (C, adainit, "adainit");
-- This is the generated adafinal routine that performs
-- finalization at the end of execution. In the case where
-- Ada is the main program, this main program makes a call
-- to adafinal at program termination.
procedure adafinal;
pragma Export (C, adafinal, "adafinal");
-- This routine is called at the start of execution. It is
-- a dummy routine that is used by the debugger to breakpoint
-- at the start of execution.
-- This is the actual generated main program (it would be
-- suppressed if the no main program switch were used). As
-- required by standard system conventions, this program has
-- the external name main.
function main
(argc : Integer;
argv : System.Address;
envp : System.Address)
return Integer;
pragma Export (C, main, "main");
-- The following set of constants give the version
-- identification values for every unit in the bound
-- partition. This identification is computed from all
-- dependent semantic units, and corresponds to the
-- string that would be returned by use of the
-- Body_Version or Version attributes.
-- The following Export pragmas export the version numbers
-- with symbolic names ending in B (for body) or S
-- (for spec) so that they can be located in a link. The
-- information provided here is sufficient to track down
-- the exact versions of units used in a given build.
type Version_32 is mod 2 ** 32;
u00001 : constant Version_32 := 16#8ad6e54a#;
pragma Export (C, u00001, "helloB");
u00002 : constant Version_32 := 16#fbff4c67#;
pragma Export (C, u00002, "system__standard_libraryB");
u00003 : constant Version_32 := 16#1ec6fd90#;
pragma Export (C, u00003, "system__standard_libraryS");
u00004 : constant Version_32 := 16#3ffc8e18#;
pragma Export (C, u00004, "adaS");
u00005 : constant Version_32 := 16#28f088c2#;
pragma Export (C, u00005, "ada__text_ioB");
u00006 : constant Version_32 := 16#f372c8ac#;
pragma Export (C, u00006, "ada__text_ioS");
u00007 : constant Version_32 := 16#2c143749#;
pragma Export (C, u00007, "ada__exceptionsB");
u00008 : constant Version_32 := 16#f4f0cce8#;
pragma Export (C, u00008, "ada__exceptionsS");
u00009 : constant Version_32 := 16#a46739c0#;
pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB");
u00010 : constant Version_32 := 16#3aac8c92#;
pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS");
u00011 : constant Version_32 := 16#1d274481#;
pragma Export (C, u00011, "systemS");
u00012 : constant Version_32 := 16#a207fefe#;
pragma Export (C, u00012, "system__soft_linksB");
u00013 : constant Version_32 := 16#467d9556#;
pragma Export (C, u00013, "system__soft_linksS");
u00014 : constant Version_32 := 16#b01dad17#;
pragma Export (C, u00014, "system__parametersB");
u00015 : constant Version_32 := 16#630d49fe#;
pragma Export (C, u00015, "system__parametersS");
u00016 : constant Version_32 := 16#b19b6653#;
pragma Export (C, u00016, "system__secondary_stackB");
u00017 : constant Version_32 := 16#b6468be8#;
pragma Export (C, u00017, "system__secondary_stackS");
u00018 : constant Version_32 := 16#39a03df9#;
pragma Export (C, u00018, "system__storage_elementsB");
u00019 : constant Version_32 := 16#30e40e85#;
pragma Export (C, u00019, "system__storage_elementsS");
u00020 : constant Version_32 := 16#41837d1e#;
pragma Export (C, u00020, "system__stack_checkingB");
u00021 : constant Version_32 := 16#93982f69#;
pragma Export (C, u00021, "system__stack_checkingS");
u00022 : constant Version_32 := 16#393398c1#;
pragma Export (C, u00022, "system__exception_tableB");
u00023 : constant Version_32 := 16#b33e2294#;
pragma Export (C, u00023, "system__exception_tableS");
u00024 : constant Version_32 := 16#ce4af020#;
pragma Export (C, u00024, "system__exceptionsB");
u00025 : constant Version_32 := 16#75442977#;
pragma Export (C, u00025, "system__exceptionsS");
u00026 : constant Version_32 := 16#37d758f1#;
pragma Export (C, u00026, "system__exceptions__machineS");
u00027 : constant Version_32 := 16#b895431d#;
pragma Export (C, u00027, "system__exceptions_debugB");
u00028 : constant Version_32 := 16#aec55d3f#;
pragma Export (C, u00028, "system__exceptions_debugS");
u00029 : constant Version_32 := 16#570325c8#;
pragma Export (C, u00029, "system__img_intB");
u00030 : constant Version_32 := 16#1ffca443#;
pragma Export (C, u00030, "system__img_intS");
u00031 : constant Version_32 := 16#b98c3e16#;
pragma Export (C, u00031, "system__tracebackB");
u00032 : constant Version_32 := 16#831a9d5a#;
pragma Export (C, u00032, "system__tracebackS");
u00033 : constant Version_32 := 16#9ed49525#;
pragma Export (C, u00033, "system__traceback_entriesB");
u00034 : constant Version_32 := 16#1d7cb2f1#;
pragma Export (C, u00034, "system__traceback_entriesS");
u00035 : constant Version_32 := 16#8c33a517#;
pragma Export (C, u00035, "system__wch_conB");
u00036 : constant Version_32 := 16#065a6653#;
pragma Export (C, u00036, "system__wch_conS");
u00037 : constant Version_32 := 16#9721e840#;
pragma Export (C, u00037, "system__wch_stwB");
u00038 : constant Version_32 := 16#2b4b4a52#;
pragma Export (C, u00038, "system__wch_stwS");
u00039 : constant Version_32 := 16#92b797cb#;
pragma Export (C, u00039, "system__wch_cnvB");
u00040 : constant Version_32 := 16#09eddca0#;
pragma Export (C, u00040, "system__wch_cnvS");
u00041 : constant Version_32 := 16#6033a23f#;
pragma Export (C, u00041, "interfacesS");
u00042 : constant Version_32 := 16#ece6fdb6#;
pragma Export (C, u00042, "system__wch_jisB");
u00043 : constant Version_32 := 16#899dc581#;
pragma Export (C, u00043, "system__wch_jisS");
u00044 : constant Version_32 := 16#10558b11#;
pragma Export (C, u00044, "ada__streamsB");
u00045 : constant Version_32 := 16#2e6701ab#;
pragma Export (C, u00045, "ada__streamsS");
u00046 : constant Version_32 := 16#db5c917c#;
pragma Export (C, u00046, "ada__io_exceptionsS");
u00047 : constant Version_32 := 16#12c8cd7d#;
pragma Export (C, u00047, "ada__tagsB");
u00048 : constant Version_32 := 16#ce72c228#;
pragma Export (C, u00048, "ada__tagsS");
u00049 : constant Version_32 := 16#c3335bfd#;
pragma Export (C, u00049, "system__htableB");
u00050 : constant Version_32 := 16#99e5f76b#;
pragma Export (C, u00050, "system__htableS");
u00051 : constant Version_32 := 16#089f5cd0#;
pragma Export (C, u00051, "system__string_hashB");
u00052 : constant Version_32 := 16#3bbb9c15#;
pragma Export (C, u00052, "system__string_hashS");
u00053 : constant Version_32 := 16#807fe041#;
pragma Export (C, u00053, "system__unsigned_typesS");
u00054 : constant Version_32 := 16#d27be59e#;
pragma Export (C, u00054, "system__val_lluB");
u00055 : constant Version_32 := 16#fa8db733#;
pragma Export (C, u00055, "system__val_lluS");
u00056 : constant Version_32 := 16#27b600b2#;
pragma Export (C, u00056, "system__val_utilB");
u00057 : constant Version_32 := 16#b187f27f#;
pragma Export (C, u00057, "system__val_utilS");
u00058 : constant Version_32 := 16#d1060688#;
pragma Export (C, u00058, "system__case_utilB");
u00059 : constant Version_32 := 16#392e2d56#;
pragma Export (C, u00059, "system__case_utilS");
u00060 : constant Version_32 := 16#84a27f0d#;
pragma Export (C, u00060, "interfaces__c_streamsB");
u00061 : constant Version_32 := 16#8bb5f2c0#;
pragma Export (C, u00061, "interfaces__c_streamsS");
u00062 : constant Version_32 := 16#6db6928f#;
pragma Export (C, u00062, "system__crtlS");
u00063 : constant Version_32 := 16#4e6a342b#;
pragma Export (C, u00063, "system__file_ioB");
u00064 : constant Version_32 := 16#ba56a5e4#;
pragma Export (C, u00064, "system__file_ioS");
u00065 : constant Version_32 := 16#b7ab275c#;
pragma Export (C, u00065, "ada__finalizationB");
u00066 : constant Version_32 := 16#19f764ca#;
pragma Export (C, u00066, "ada__finalizationS");
u00067 : constant Version_32 := 16#95817ed8#;
pragma Export (C, u00067, "system__finalization_rootB");
u00068 : constant Version_32 := 16#52d53711#;
pragma Export (C, u00068, "system__finalization_rootS");
u00069 : constant Version_32 := 16#769e25e6#;
pragma Export (C, u00069, "interfaces__cB");
u00070 : constant Version_32 := 16#4a38bedb#;
pragma Export (C, u00070, "interfaces__cS");
u00071 : constant Version_32 := 16#07e6ee66#;
pragma Export (C, u00071, "system__os_libB");
u00072 : constant Version_32 := 16#d7b69782#;
pragma Export (C, u00072, "system__os_libS");
u00073 : constant Version_32 := 16#1a817b8e#;
pragma Export (C, u00073, "system__stringsB");
u00074 : constant Version_32 := 16#639855e7#;
pragma Export (C, u00074, "system__stringsS");
u00075 : constant Version_32 := 16#e0b8de29#;
pragma Export (C, u00075, "system__file_control_blockS");
u00076 : constant Version_32 := 16#b5b2aca1#;
pragma Export (C, u00076, "system__finalization_mastersB");
u00077 : constant Version_32 := 16#69316dc1#;
pragma Export (C, u00077, "system__finalization_mastersS");
u00078 : constant Version_32 := 16#57a37a42#;
pragma Export (C, u00078, "system__address_imageB");
u00079 : constant Version_32 := 16#bccbd9bb#;
pragma Export (C, u00079, "system__address_imageS");
u00080 : constant Version_32 := 16#7268f812#;
pragma Export (C, u00080, "system__img_boolB");
u00081 : constant Version_32 := 16#e8fe356a#;
pragma Export (C, u00081, "system__img_boolS");
u00082 : constant Version_32 := 16#d7aac20c#;
pragma Export (C, u00082, "system__ioB");
u00083 : constant Version_32 := 16#8365b3ce#;
pragma Export (C, u00083, "system__ioS");
u00084 : constant Version_32 := 16#6d4d969a#;
pragma Export (C, u00084, "system__storage_poolsB");
u00085 : constant Version_32 := 16#e87cc305#;
pragma Export (C, u00085, "system__storage_poolsS");
u00086 : constant Version_32 := 16#e34550ca#;
pragma Export (C, u00086, "system__pool_globalB");
u00087 : constant Version_32 := 16#c88d2d16#;
pragma Export (C, u00087, "system__pool_globalS");
u00088 : constant Version_32 := 16#9d39c675#;
pragma Export (C, u00088, "system__memoryB");
u00089 : constant Version_32 := 16#445a22b5#;
pragma Export (C, u00089, "system__memoryS");
u00090 : constant Version_32 := 16#6a859064#;
pragma Export (C, u00090, "system__storage_pools__subpoolsB");
u00091 : constant Version_32 := 16#e3b008dc#;
pragma Export (C, u00091, "system__storage_pools__subpoolsS");
u00092 : constant Version_32 := 16#63f11652#;
pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB");
u00093 : constant Version_32 := 16#fe2f4b3a#;
pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS");
-- BEGIN ELABORATION ORDER
-- ada%s
-- interfaces%s
-- system%s
-- system.case_util%s
-- system.case_util%b
-- system.htable%s
-- system.img_bool%s
-- system.img_bool%b
-- system.img_int%s
-- system.img_int%b
-- system.io%s
-- system.io%b
-- system.parameters%s
-- system.parameters%b
-- system.crtl%s
-- interfaces.c_streams%s
-- interfaces.c_streams%b
-- system.standard_library%s
-- system.exceptions_debug%s
-- system.exceptions_debug%b
-- system.storage_elements%s
-- system.storage_elements%b
-- system.stack_checking%s
-- system.stack_checking%b
-- system.string_hash%s
-- system.string_hash%b
-- system.htable%b
-- system.strings%s
-- system.strings%b
-- system.os_lib%s
-- system.traceback_entries%s
-- system.traceback_entries%b
-- ada.exceptions%s
-- system.soft_links%s
-- system.unsigned_types%s
-- system.val_llu%s
-- system.val_util%s
-- system.val_util%b
-- system.val_llu%b
-- system.wch_con%s
-- system.wch_con%b
-- system.wch_cnv%s
-- system.wch_jis%s
-- system.wch_jis%b
-- system.wch_cnv%b
-- system.wch_stw%s
-- system.wch_stw%b
-- ada.exceptions.last_chance_handler%s
-- ada.exceptions.last_chance_handler%b
-- system.address_image%s
-- system.exception_table%s
-- system.exception_table%b
-- ada.io_exceptions%s
-- ada.tags%s
-- ada.streams%s
-- ada.streams%b
-- interfaces.c%s
-- system.exceptions%s
-- system.exceptions%b
-- system.exceptions.machine%s
-- system.finalization_root%s
-- system.finalization_root%b
-- ada.finalization%s
-- ada.finalization%b
-- system.storage_pools%s
-- system.storage_pools%b
-- system.finalization_masters%s
-- system.storage_pools.subpools%s
-- system.storage_pools.subpools.finalization%s
-- system.storage_pools.subpools.finalization%b
-- system.memory%s
-- system.memory%b
-- system.standard_library%b
-- system.pool_global%s
-- system.pool_global%b
-- system.file_control_block%s
-- system.file_io%s
-- system.secondary_stack%s
-- system.file_io%b
-- system.storage_pools.subpools%b
-- system.finalization_masters%b
-- interfaces.c%b
-- ada.tags%b
-- system.soft_links%b
-- system.os_lib%b
-- system.secondary_stack%b
-- system.address_image%b
-- system.traceback%s
-- ada.exceptions%b
-- system.traceback%b
-- ada.text_io%s
-- ada.text_io%b
-- hello%b
-- END ELABORATION ORDER
end ada_main;
.. code-block:: ada
pragma Ada_95;
-- The following source file name pragmas allow the generated file
-- names to be unique for different main programs. They are needed
-- since the package name will always be Ada_Main.
pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads");
pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb");
pragma Suppress (Overflow_Check);
with Ada.Exceptions;
-- Generated package body for Ada_Main starts here
package body ada_main is
pragma Warnings (Off);
-- These values are reference counter associated to units which have
-- been elaborated. It is also used to avoid elaborating the
-- same unit twice.
E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E");
E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E");
E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E");
E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E");
E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E");
E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E");
E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E");
E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E");
E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E");
E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E");
E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E");
E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E");
E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E");
E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E");
E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E");
E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E");
E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E");
E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E");
Local_Priority_Specific_Dispatching : constant String := "";
Local_Interrupt_States : constant String := "";
Is_Elaborated : Boolean := False;
procedure finalize_library is
begin
E06 := E06 - 1;
declare
procedure F1;
pragma Import (Ada, F1, "ada__text_io__finalize_spec");
begin
F1;
end;
E77 := E77 - 1;
E91 := E91 - 1;
declare
procedure F2;
pragma Import (Ada, F2, "system__file_io__finalize_body");
begin
E64 := E64 - 1;
F2;
end;
declare
procedure F3;
pragma Import (Ada, F3, "system__file_control_block__finalize_spec");
begin
E75 := E75 - 1;
F3;
end;
E87 := E87 - 1;
declare
procedure F4;
pragma Import (Ada, F4, "system__pool_global__finalize_spec");
begin
F4;
end;
declare
procedure F5;
pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec");
begin
F5;
end;
declare
procedure F6;
pragma Import (Ada, F6, "system__finalization_masters__finalize_spec");
begin
F6;
end;
declare
procedure Reraise_Library_Exception_If_Any;
pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any");
begin
Reraise_Library_Exception_If_Any;
end;
end finalize_library;
-------------
-- adainit --
-------------
procedure adainit is
Main_Priority : Integer;
pragma Import (C, Main_Priority, "__gl_main_priority");
Time_Slice_Value : Integer;
pragma Import (C, Time_Slice_Value, "__gl_time_slice_val");
WC_Encoding : Character;
pragma Import (C, WC_Encoding, "__gl_wc_encoding");
Locking_Policy : Character;
pragma Import (C, Locking_Policy, "__gl_locking_policy");
Queuing_Policy : Character;
pragma Import (C, Queuing_Policy, "__gl_queuing_policy");
Task_Dispatching_Policy : Character;
pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy");
Priority_Specific_Dispatching : System.Address;
pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching");
Num_Specific_Dispatching : Integer;
pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching");
Main_CPU : Integer;
pragma Import (C, Main_CPU, "__gl_main_cpu");
Interrupt_States : System.Address;
pragma Import (C, Interrupt_States, "__gl_interrupt_states");
Num_Interrupt_States : Integer;
pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states");
Unreserve_All_Interrupts : Integer;
pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts");
Detect_Blocking : Integer;
pragma Import (C, Detect_Blocking, "__gl_detect_blocking");
Default_Stack_Size : Integer;
pragma Import (C, Default_Stack_Size, "__gl_default_stack_size");
Leap_Seconds_Support : Integer;
pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support");
procedure Runtime_Initialize;
pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize");
Finalize_Library_Objects : No_Param_Proc;
pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects");
-- Start of processing for adainit
begin
-- Record various information for this partition. The values
-- are derived by the binder from information stored in the ali
-- files by the compiler.
if Is_Elaborated then
return;
end if;
Is_Elaborated := True;
Main_Priority := -1;
Time_Slice_Value := -1;
WC_Encoding := 'b';
Locking_Policy := ' ';
Queuing_Policy := ' ';
Task_Dispatching_Policy := ' ';
Priority_Specific_Dispatching :=
Local_Priority_Specific_Dispatching'Address;
Num_Specific_Dispatching := 0;
Main_CPU := -1;
Interrupt_States := Local_Interrupt_States'Address;
Num_Interrupt_States := 0;
Unreserve_All_Interrupts := 0;
Detect_Blocking := 0;
Default_Stack_Size := -1;
Leap_Seconds_Support := 0;
Runtime_Initialize;
Finalize_Library_Objects := finalize_library'access;
-- Now we have the elaboration calls for all units in the partition.
-- The Elab_Spec and Elab_Body attributes generate references to the
-- implicit elaboration procedures generated by the compiler for
-- each unit that requires elaboration. Increment a counter of
-- reference for each unit.
System.Soft_Links'Elab_Spec;
System.Exception_Table'Elab_Body;
E23 := E23 + 1;
Ada.Io_Exceptions'Elab_Spec;
E46 := E46 + 1;
Ada.Tags'Elab_Spec;
Ada.Streams'Elab_Spec;
E45 := E45 + 1;
Interfaces.C'Elab_Spec;
System.Exceptions'Elab_Spec;
E25 := E25 + 1;
System.Finalization_Root'Elab_Spec;
E68 := E68 + 1;
Ada.Finalization'Elab_Spec;
E66 := E66 + 1;
System.Storage_Pools'Elab_Spec;
E85 := E85 + 1;
System.Finalization_Masters'Elab_Spec;
System.Storage_Pools.Subpools'Elab_Spec;
System.Pool_Global'Elab_Spec;
E87 := E87 + 1;
System.File_Control_Block'Elab_Spec;
E75 := E75 + 1;
System.File_Io'Elab_Body;
E64 := E64 + 1;
E91 := E91 + 1;
System.Finalization_Masters'Elab_Body;
E77 := E77 + 1;
E70 := E70 + 1;
Ada.Tags'Elab_Body;
E48 := E48 + 1;
System.Soft_Links'Elab_Body;
E13 := E13 + 1;
System.Os_Lib'Elab_Body;
E72 := E72 + 1;
System.Secondary_Stack'Elab_Body;
E17 := E17 + 1;
Ada.Text_Io'Elab_Spec;
Ada.Text_Io'Elab_Body;
E06 := E06 + 1;
end adainit;
--------------
-- adafinal --
--------------
procedure adafinal is
procedure s_stalib_adafinal;
pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal");
procedure Runtime_Finalize;
pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize");
begin
if not Is_Elaborated then
return;
end if;
Is_Elaborated := False;
Runtime_Finalize;
s_stalib_adafinal;
end adafinal;
-- We get to the main program of the partition by using
-- pragma Import because if we try to with the unit and
-- call it Ada style, then not only do we waste time
-- recompiling it, but also, we don't really know the right
-- switches (e.g.@: identifier character set) to be used
-- to compile it.
procedure Ada_Main_Program;
pragma Import (Ada, Ada_Main_Program, "_ada_hello");
----------
-- main --
----------
-- main is actually a function, as in the ANSI C standard,
-- defined to return the exit status. The three parameters
-- are the argument count, argument values and environment
-- pointer.
function main
(argc : Integer;
argv : System.Address;
envp : System.Address)
return Integer
is
-- The initialize routine performs low level system
-- initialization using a standard library routine which
-- sets up signal handling and performs any other
-- required setup. The routine can be found in file
-- a-init.c.
procedure initialize;
pragma Import (C, initialize, "__gnat_initialize");
-- The finalize routine performs low level system
-- finalization using a standard library routine. The
-- routine is found in file a-final.c and in the standard
-- distribution is a dummy routine that does nothing, so
-- really this is a hook for special user finalization.
procedure finalize;
pragma Import (C, finalize, "__gnat_finalize");
-- The following is to initialize the SEH exceptions
SEH : aliased array (1 .. 2) of Integer;
Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address;
pragma Volatile (Ensure_Reference);
-- Start of processing for main
begin
-- Save global variables
gnat_argc := argc;
gnat_argv := argv;
gnat_envp := envp;
-- Call low level system initialization
Initialize (SEH'Address);
-- Call our generated Ada initialization routine
adainit;
-- Now we call the main program of the partition
Ada_Main_Program;
-- Perform Ada finalization
adafinal;
-- Perform low level system finalization
Finalize;
-- Return the proper exit status
return (gnat_exit_status);
end;
-- This section is entirely comments, so it has no effect on the
-- compilation of the Ada_Main package. It provides the list of
-- object files and linker options, as well as some standard
-- libraries needed for the link. The gnatlink utility parses
-- this b~hello.adb file to read these comment lines to generate
-- the appropriate command line arguments for the call to the
-- system linker. The BEGIN/END lines are used for sentinels for
-- this parsing operation.
-- The exact file names will of course depend on the environment,
-- host/target and location of files on the host system.
-- BEGIN Object file/option list
-- ./hello.o
-- -L./
-- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/
-- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a
-- 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
of each part of the generated `Ada_Main` package.
The code is standard Ada in all respects, and can be processed by any
tools that handle Ada. In particular, it is possible to use the debugger
in Ada mode to debug the generated `Ada_Main` package. For example,
suppose that for reasons that you do not understand, your program is crashing
during elaboration of the body of `Ada.Text_IO`. To locate this bug,
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).

276
gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst Normal file
View File

@ -0,0 +1,276 @@
.. _Getting_Started_with_GNAT:
*************************
Getting Started with GNAT
*************************
This chapter describes how to use GNAT's command line interface to build
executable Ada programs.
On most platforms a visually oriented Integrated Development Environment
is also available, the GNAT Programming Studio (GPS).
GPS offers a graphical "look and feel", support for development in
other programming languages, comprehensive browsing features, and
many other capabilities.
For information on GPS please refer to
:title:`Using the GNAT Programming Studio`.
.. _Running_GNAT:
Running GNAT
============
Three steps are needed to create an executable file from an Ada source
file:
* The source file(s) must be compiled.
* The file(s) must be bound using the GNAT binder.
* All appropriate object files must be linked to produce an executable.
All three steps are most commonly handled by using the *gnatmake*
utility program that, given the name of the main program, automatically
performs the necessary compilation, binding and linking steps.
.. _Running_a_Simple_Ada_Program:
Running a Simple Ada Program
============================
Any text editor may be used to prepare an Ada program.
(If Emacs is used, the optional Ada mode may be helpful in laying out the
program.)
The program text is a normal text file. We will assume in our initial
example that you have used your editor to prepare the following
standard format text file:
.. code-block:: ada
with Ada.Text_IO; use Ada.Text_IO;
procedure Hello is
begin
Put_Line ("Hello WORLD!");
end Hello;
This file should be named :file:`hello.adb`.
With the normal default file naming conventions, GNAT requires
that each file
contain a single compilation unit whose file name is the
unit name,
with periods replaced by hyphens; the
extension is :file:`ads` for a
spec and :file:`adb` for a body.
You can override this default file naming convention by use of the
special pragma `Source_File_Name` (for further information please
see :ref:`Using_Other_File_Names`).
Alternatively, if you want to rename your files according to this default
convention, which is probably more convenient if you will be using GNAT
for all your compilations, then the `gnatchop` utility
can be used to generate correctly-named source files
(see :ref:`Renaming_Files_with_gnatchop`).
You can compile the program using the following command (`$` is used
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
C. It assumes that you have given it an Ada program if the file extension is
either :file:`.ads` or :file:`.adb`, and it will then call
the GNAT compiler to compile the specified file.
The :option:`-c` switch is required. It tells *gcc* to only do a
compilation. (For C programs, *gcc* can also do linking, but this
capability is not used directly for Ada programs, so the :option:`-c`
switch must always be present.)
This compile command generates a file
:file:`hello.o`, which is the object
file corresponding to your Ada program. It also generates
an 'Ada Library Information' file :file:`hello.ali`,
which contains additional information used to check
that an Ada program is consistent.
To build an executable file,
use `gnatbind` to bind the program
and *gnatlink* to link it. The
argument to both `gnatbind` and *gnatlink* is the name of the
:file:`ALI` file, but the default extension of :file:`.ali` can
be omitted. This means that in the most common case, the argument
is simply the name of the main program:
.. code-block:: sh
$ gnatbind hello
$ gnatlink hello
A simpler method of carrying out these steps is to use *gnatmake*,
a master program that invokes all the required
compilation, binding and linking tools in the correct order. In particular,
*gnatmake* automatically recompiles any sources that have been
modified since they were last compiled, or sources that depend
on such modified sources, so that 'version skew' is avoided.
.. index:: Version skew (avoided by *gnatmake*)
.. code-block:: sh
$ gnatmake hello.adb
The result is an executable program called :file:`hello`, which can be
run by entering:
.. code-block:: sh
$ hello
assuming that the current directory is on the search path
for executable programs.
and, if all has gone well, you will see::
Hello WORLD!
appear in response to this command.
.. _Running_a_Program_with_Multiple_Units:
Running a Program with Multiple Units
=====================================
Consider a slightly more complicated example that has three files: a
main program, and the spec and body of a package:
.. code-block:: ada
package Greetings is
procedure Hello;
procedure Goodbye;
end Greetings;
with Ada.Text_IO; use Ada.Text_IO;
package body Greetings is
procedure Hello is
begin
Put_Line ("Hello WORLD!");
end Hello;
procedure Goodbye is
begin
Put_Line ("Goodbye WORLD!");
end Goodbye;
end Greetings;
with Greetings;
procedure Gmain is
begin
Greetings.Hello;
Greetings.Goodbye;
end Gmain;
Following the one-unit-per-file rule, place this program in the
following three separate files:
*greetings.ads*
spec of package `Greetings`
*greetings.adb*
body of package `Greetings`
*gmain.adb*
body of main program
To build an executable version of
this program, we could use four separate steps to compile, bind, and link
the program, as follows:
.. code-block:: sh
$ gcc -c gmain.adb
$ gcc -c greetings.adb
$ gnatbind gmain
$ gnatlink gmain
Note that there is no required order of compilation when using GNAT.
In particular it is perfectly fine to compile the main program first.
Also, it is not necessary to compile package specs in the case where
there is an accompanying body; you only need to compile the body. If you want
to submit these files to the compiler for semantic checking and not code
generation, then use the :option:`-gnatc` switch:
.. code-block:: sh
$ gcc -c greetings.ads -gnatc
Although the compilation can be done in separate steps as in the
above example, in practice it is almost always more convenient
to use the *gnatmake* tool. All you need to know in this case
is the name of the main program's source file. The effect of the above four
commands can be achieved with a single one:
.. code-block:: sh
$ gnatmake gmain.adb
In the next section we discuss the advantages of using *gnatmake* in
more detail.
.. _Using_the_gnatmake_Utility:
Using the *gnatmake* Utility
============================
If you work on a program by compiling single components at a time using
*gcc*, you typically keep track of the units you modify. In order to
build a consistent system, you compile not only these units, but also any
units that depend on the units you have modified.
For example, in the preceding case,
if you edit :file:`gmain.adb`, you only need to recompile that file. But if
you edit :file:`greetings.ads`, you must recompile both
:file:`greetings.adb` and :file:`gmain.adb`, because both files contain
units that depend on :file:`greetings.ads`.
*gnatbind* will warn you if you forget one of these compilation
steps, so that it is impossible to generate an inconsistent program as a
result of forgetting to do a compilation. Nevertheless it is tedious and
error-prone to keep track of dependencies among units.
One approach to handle the dependency-bookkeeping is to use a
makefile. However, makefiles present maintenance problems of their own:
if the dependencies change as you change the program, you must make
sure that the makefile is kept up-to-date manually, which is also an
error-prone process.
The *gnatmake* utility takes care of these details automatically.
Invoke it using either one of the following forms:
.. code-block:: sh
$ gnatmake gmain.adb
$ gnatmake gmain
The argument is the name of the file containing the main program;
you may omit the extension. *gnatmake*
examines the environment, automatically recompiles any files that need
recompiling, and binds and links the resulting set of object files,
generating the executable file, :file:`gmain`.
In a large program, it
can be extremely helpful to use *gnatmake*, because working out by hand
what needs to be recompiled can be difficult.
Note that *gnatmake* takes into account all the Ada rules that
establish dependencies among units. These include dependencies that result
from inlining subprogram bodies, and from
generic instantiation. Unlike some other
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.

4190
gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst Normal file
View File

File diff suppressed because it is too large Load Diff

4907
gcc/ada/doc/gnat_ugn/gnat_project_manager.rst Normal file
View File

File diff suppressed because it is too large Load Diff

4997
gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst Normal file
View File

File diff suppressed because it is too large Load Diff

668
gcc/ada/doc/gnat_ugn/inline_assembler.rst Normal file
View File

@ -0,0 +1,668 @@
.. _Inline_Assembler:
****************
Inline Assembler
****************
.. index:: Inline Assembler
If you need to write low-level software that interacts directly
with the hardware, Ada provides two ways to incorporate assembly
language code into your program. First, you can import and invoke
external routines written in assembly language, an Ada feature fully
supported by GNAT. However, for small sections of code it may be simpler
or more efficient to include assembly language statements directly
in your Ada source program, using the facilities of the implementation-defined
package `System.Machine_Code`, which incorporates the gcc
Inline Assembler. The Inline Assembler approach offers a number of advantages,
including the following:
* No need to use non-Ada tools
* Consistent interface over different targets
* Automatic usage of the proper calling conventions
* Access to Ada constants and variables
* Definition of intrinsic routines
* Possibility of inlining a subprogram comprising assembler code
* Code optimizer can take Inline Assembler code into account
This appendix presents a series of examples to show you how to use
the Inline Assembler. Although it focuses on the Intel x86,
the general approach applies also to other processors.
It is assumed that you are familiar with Ada
and with assembly language programming.
.. _Basic_Assembler_Syntax:
Basic Assembler Syntax
======================
The assembler used by GNAT and gcc is based not on the Intel assembly
language, but rather on a language that descends from the AT&T Unix
assembler *as* (and which is often referred to as 'AT&T syntax').
The following table summarizes the main features of *as* syntax
and points out the differences from the Intel conventions.
See the gcc *as* and *gas* (an *as* macro
pre-processor) documentation for further information.
| *Register names*
| gcc / *as*: Prefix with '%'; for example `%eax`
| Intel: No extra punctuation; for example `eax`
| *Immediate operand*
| gcc / *as*: Prefix with '$'; for example `$4`
| Intel: No extra punctuation; for example `4`
| *Address*
| gcc / *as*: Prefix with '$'; for example `$loc`
| Intel: No extra punctuation; for example `loc`
| *Memory contents*
| gcc / *as*: No extra punctuation; for example `loc`
| Intel: Square brackets; for example `[loc]`
| *Register contents*
| gcc / *as*: Parentheses; for example `(%eax)`
| Intel: Square brackets; for example `[eax]`
| *Hexadecimal numbers*
| gcc / *as*: Leading '0x' (C language syntax); for example `0xA0`
| Intel: Trailing 'h'; for example `A0h`
| *Operand size*
| gcc / *as*: Explicit in op code; for example `movw` to move a 16-bit word
| Intel: Implicit, deduced by assembler; for example `mov`
| *Instruction repetition*
| gcc / *as*: Split into two lines; for example
| `rep`
| `stosl`
| Intel: Keep on one line; for example `rep stosl`
| *Order of operands*
| gcc / *as*: Source first; for example `movw $4, %eax`
| Intel: Destination first; for example `mov eax, 4`
.. _A_Simple_Example_of_Inline_Assembler:
A Simple Example of Inline Assembler
====================================
The following example will generate a single assembly language statement,
`nop`, which does nothing. Despite its lack of run-time effect,
the example will be useful in illustrating the basics of
the Inline Assembler facility.
.. code-block:: ada
with System.Machine_Code; use System.Machine_Code;
procedure Nothing is
begin
Asm ("nop");
end Nothing;
`Asm` is a procedure declared in package `System.Machine_Code`;
here it takes one parameter, a *template string* that must be a static
expression and that will form the generated instruction.
`Asm` may be regarded as a compile-time procedure that parses
the template string and additional parameters (none here),
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
:title:`GNAT Reference Manual`.
Under the standard GNAT conventions, the `Nothing` procedure
should be in a file named :file:`nothing.adb`.
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:
::
$ gcc -c -S -fomit-frame-pointer -gnatp nothing.adb
where the options are:
* :samp:`-c`
compile only (no bind or link)
* :samp:`-S`
generate assembler listing
* :samp:`-fomit-frame-pointer`
do not set up separate stack frames
* :samp:`-gnatp`
do not add runtime checks
This gives a human-readable assembler version of the code. The resulting
file will have the same name as the Ada source file, but with a `.s`
extension. In our example, the file :file:`nothing.s` has the following
contents:
::
.file "nothing.adb"
gcc2_compiled.:
___gnu_compiled_ada:
.text
.align 4
.globl __ada_nothing
__ada_nothing:
#APP
nop
#NO_APP
jmp L1
.align 2,0x90
L1:
ret
The assembly code you included is clearly indicated by
the compiler, between the `#APP` and `#NO_APP`
delimiters. The character before the 'APP' and 'NOAPP'
can differ on different targets. For example, GNU/Linux uses '#APP' while
on NT you will see '/APP'.
If you make a mistake in your assembler code (such as using the
wrong size modifier, or using a wrong operand for the instruction) GNAT
will report this error in a temporary file, which will be deleted when
the compilation is finished. Generating an assembler file will help
in such cases, since you can assemble this file separately using the
*as* assembler that comes with gcc.
Assembling the file using the command
::
$ 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.
If there are no errors, *as* will generate an object file
:file:`nothing.out`.
.. _Output_Variables_in_Inline_Assembler:
Output Variables in Inline Assembler
====================================
The examples in this section, showing how to access the processor flags,
illustrate how to specify the destination operands for assembly language
statements.
.. code-block:: ada
with Interfaces; use Interfaces;
with Ada.Text_IO; use Ada.Text_IO;
with System.Machine_Code; use System.Machine_Code;
procedure Get_Flags is
Flags : Unsigned_32;
use ASCII;
begin
Asm ("pushfl" & LF & HT & -- push flags on stack
"popl %%eax" & LF & HT & -- load eax with flags
"movl %%eax, %0", -- store flags in variable
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.
The resulting section of the assembly output file is:
::
#APP
pushfl
popl %eax
movl %eax, -40(%ebp)
#NO_APP
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:
::
#APP
pushfl popl %eax movl %eax, -40(%ebp)
#NO_APP
which is not so convenient for the human reader.
We use Ada comments
at the end of each line to explain what the assembler instructions
actually do. This is a useful convention.
When writing Inline Assembler instructions, you need to precede each register
and variable name with a percent sign. Since the assembler already requires
a percent sign at the beginning of a register name, you need two consecutive
percent signs for such names in the Asm template string, thus `%%eax`.
In the generated assembly code, one of the percent signs will be stripped off.
Names such as `%0`, `%1`, `%2`, etc., denote input or output
variables: operands you later define using `Input` or `Output`
parameters to `Asm`.
An output variable is illustrated in
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
to hold Flags, and the expansion of the `movl` instruction would not be
aware of this optimization. The solution is not to store the result directly
but rather to advise the compiler to choose the correct operand form;
that is the purpose of the `%0` output variable.
Information about the output variable is supplied in the `Outputs`
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,
.. code-block:: ada
Unsigned_32'Asm_Output ("=r", Flags);
uses the `"r"` (register) constraint, telling the compiler to
store the variable in a register.
If the constraint is preceded by the equal character '=', it tells
the compiler that the variable will be used to store data into it.
In the `Get_Flags` example, we used the `"g"` (global) constraint,
allowing the optimizer to choose whatever it deems best.
There are a fairly large number of constraints, but the ones that are
most useful (for the Intel x86 processor) are the following:
====== ==========================================
*=* output constraint
*g* global (i.e., can be stored anywhere)
*m* in memory
*I* a constant
*a* use eax
*b* use ebx
*c* use ecx
*d* use edx
*S* use esi
*D* use edi
*r* use one of eax, ebx, ecx or edx
*q* use one of eax, ebx, ecx, edx, esi or edi
====== ==========================================
The full set of constraints is described in the gcc and *as*
documentation; note that it is possible to combine certain constraints
in one constraint string.
You specify the association of an output variable with an assembler operand
through the :samp:`%{n}` notation, where *n* is a non-negative
integer. Thus in
.. code-block:: ada
Asm ("pushfl" & LF & HT & -- push flags on stack
"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
the compiler decided for the `Flags` variable.
In general, you may have any number of output variables:
* Count the operands starting at 0; thus `%0`, `%1`, etc.
* Specify the `Outputs` parameter as a parenthesized comma-separated list
of `Asm_Output` attributes
For example:
.. code-block:: ada
Asm ("movl %%eax, %0" & LF & HT &
"movl %%ebx, %1" & LF & HT &
"movl %%ecx, %2",
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.
As a variation on the `Get_Flags` example, we can use the constraints
string to direct the compiler to store the eax register into the `Flags`
variable, instead of including the store instruction explicitly in the
`Asm` template string:
.. code-block:: ada
with Interfaces; use Interfaces;
with Ada.Text_IO; use Ada.Text_IO;
with System.Machine_Code; use System.Machine_Code;
procedure Get_Flags_2 is
Flags : Unsigned_32;
use ASCII;
begin
Asm ("pushfl" & LF & HT & -- push flags on stack
"popl %%eax", -- save flags in eax
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:
::
#APP
pushfl
popl %eax
#NO_APP
movl %eax,-40(%ebp)
The compiler generated the store of eax into Flags after
expanding the assembler code.
Actually, there was no need to pop the flags into the eax register;
more simply, we could just pop the flags directly into the program variable:
.. code-block:: ada
with Interfaces; use Interfaces;
with Ada.Text_IO; use Ada.Text_IO;
with System.Machine_Code; use System.Machine_Code;
procedure Get_Flags_3 is
Flags : Unsigned_32;
use ASCII;
begin
Asm ("pushfl" & LF & HT & -- push flags on stack
"pop %0", -- save flags in Flags
Outputs => Unsigned_32'Asm_Output ("=g", Flags));
Put_Line ("Flags register:" & Flags'Img);
end Get_Flags_3;
.. _Input_Variables_in_Inline_Assembler:
Input Variables in Inline Assembler
===================================
The example in this section illustrates how to specify the source operands
for assembly language statements.
The program simply increments its input value by 1:
.. code-block:: ada
with Interfaces; use Interfaces;
with Ada.Text_IO; use Ada.Text_IO;
with System.Machine_Code; use System.Machine_Code;
procedure Increment is
function Incr (Value : Unsigned_32) return Unsigned_32 is
Result : Unsigned_32;
begin
Asm ("incl %0",
Outputs => Unsigned_32'Asm_Output ("=a", Result),
Inputs => Unsigned_32'Asm_Input ("a", Value));
return Result;
end Incr;
Value : Unsigned_32;
begin
Value := 5;
Put_Line ("Value before is" & Value'Img);
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.
The `Inputs` parameter looks much like the `Outputs` parameter,
but with an `Asm_Input` attribute.
The `"="` constraint, indicating an output value, is not present.
You can have multiple input variables, in the same way that you can have more
than one output variable.
The parameter count (%0, %1) etc, still starts at the first output statement,
and continues with the input statements.
Just as the `Outputs` parameter causes the register to be stored into the
target variable after execution of the assembler statements, so does the
`Inputs` parameter cause its variable to be loaded into the register
before execution of the assembler statements.
Thus the effect of the `Asm` invocation is:
* load the 32-bit value of `Value` into eax
* execute the `incl %eax` instruction
* store the contents of eax into the `Result` variable
The resulting assembler file (with *-O2* optimization) contains:
::
_increment__incr.1:
subl $4,%esp
movl 8(%esp),%eax
#APP
incl %eax
#NO_APP
movl %eax,%edx
movl %ecx,(%esp)
addl $4,%esp
ret
.. _Inlining_Inline_Assembler_Code:
Inlining Inline Assembler Code
==============================
For a short subprogram such as the `Incr` function in the previous
section, the overhead of the call and return (creating / deleting the stack
frame) can be significant, compared to the amount of code in the subprogram
body. A solution is to apply Ada's `Inline` pragma to the subprogram,
which directs the compiler to expand invocations of the subprogram at the
point(s) of call, instead of setting up a stack frame for out-of-line calls.
Here is the resulting program:
.. code-block:: ada
with Interfaces; use Interfaces;
with Ada.Text_IO; use Ada.Text_IO;
with System.Machine_Code; use System.Machine_Code;
procedure Increment_2 is
function Incr (Value : Unsigned_32) return Unsigned_32 is
Result : Unsigned_32;
begin
Asm ("incl %0",
Outputs => Unsigned_32'Asm_Output ("=a", Result),
Inputs => Unsigned_32'Asm_Input ("a", Value));
return Result;
end Incr;
pragma Inline (Increment);
Value : Unsigned_32;
begin
Value := 5;
Put_Line ("Value before is" & Value'Img);
Value := Increment (Value);
Put_Line ("Value after is" & Value'Img);
end Increment_2;
Compile the program with both optimization (*-O2*) and inlining
(*-gnatn*) enabled.
The `Incr` function is still compiled as usual, but at the
point in `Increment` where our function used to be called:
::
pushl %edi
call _increment__incr.1
the code for the function body directly appears:
::
movl %esi,%eax
#APP
incl %eax
#NO_APP
movl %eax,%edx
thus saving the overhead of stack frame setup and an out-of-line call.
.. _Other_`Asm`_Functionality:
Other `Asm` Functionality
=========================
This section describes two important parameters to the `Asm`
procedure: `Clobber`, which identifies register usage;
and `Volatile`, which inhibits unwanted optimizations.
.. _The_`Clobber`_Parameter:
The `Clobber` Parameter
-----------------------
One of the dangers of intermixing assembly language and a compiled language
such as Ada is that the compiler needs to be aware of which registers are
being used by the assembly code. In some cases, such as the earlier examples,
the constraint string is sufficient to indicate register usage (e.g.,
`"a"` for
the eax register). But more generally, the compiler needs an explicit
identification of the registers that are used by the Inline Assembly
statements.
Using a register that the compiler doesn't know about
could be a side effect of an instruction (like `mull`
storing its result in both eax and edx).
It can also arise from explicit register usage in your
assembly code; for example:
.. code-block:: ada
Asm ("movl %0, %%ebx" & LF & HT &
"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.
In such cases you need to supply the `Clobber` parameter to `Asm`,
to identify the registers that will be used by your assembly code:
.. code-block:: ada
Asm ("movl %0, %%ebx" & LF & HT &
"movl %%ebx, %1",
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
are separated by commas; e.g., `"eax, ebx"`
The `Clobber` parameter has several additional uses:
* Use 'register' name `cc` to indicate that flags might have changed
* Use 'register' name `memory` if you changed a memory location
.. _The_`Volatile`_Parameter:
The `Volatile` Parameter
------------------------
.. index:: Volatile parameter
Compiler optimizations in the presence of Inline Assembler may sometimes have
unwanted effects. For example, when an `Asm` invocation with an input
variable is inside a loop, the compiler might move the loading of the input
variable outside the loop, regarding it as a one-time initialization.
If this effect is not desired, you can disable such optimizations by setting
the `Volatile` parameter to `True`; for example:
.. code-block:: ada
Asm ("movl %0, %%ebx" & LF & HT &
"movl %%ebx, %1",
Outputs => Unsigned_32'Asm_Output ("=g", Var_Out),
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.
Although setting `Volatile` to `True` prevents unwanted
optimizations, it will also disable other optimizations that might be
important for efficiency. In general, you should set `Volatile`
to `True` only if the compiler's optimizations have created
problems.

2191
gcc/ada/doc/gnat_ugn/platform_specific_information.rst Normal file
View File

File diff suppressed because it is too large Load Diff

4846
gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst Normal file
View File

File diff suppressed because it is too large Load Diff

745
gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst Normal file
View File

@ -0,0 +1,745 @@
.. _Tools_Supporting_Project_Files:
Tools Supporting Project Files
==============================
This section describes how project files can be used in conjunction with a number of
GNAT tools.
.. _gnatmake_and_Project_Files:
gnatmake and Project Files
--------------------------
This section covers several topics related to *gnatmake* and
project files: defining switches for *gnatmake*
and for the tools that it invokes; specifying configuration pragmas;
the use of the `Main` attribute; building and rebuilding library project
files.
.. _Switches_Related_to_Project_Files:
Switches Related to Project Files
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
The following switches are used by GNAT tools that support project files:
.. index:: -P (any project-aware tool)
:samp:`-P{project}`
Indicates the name of a project file. This project file will be parsed with
the verbosity indicated by *-vP*x**,
if any, and using the external references indicated
by *-X* switches, if any.
There may zero, one or more spaces between *-P* and `project`.
There must be only one *-P* switch on the command line.
Since the Project Manager parses the project file only after all the switches
on the command line are checked, the order of the switches
*-P*,
*-vP*x**
or *-X* is not significant.
.. index:: -X (any project-aware tool)
:samp:`-X{name}={value}`
Indicates that external variable `name` has the value `value`.
The Project Manager will use this value for occurrences of
`external(name)` when parsing the project file.
If `name` or `value` includes a space, then `name=value` should be
put between quotes.
::
-XOS=NT
-X"user=John Doe"
Several *-X* switches can be used simultaneously.
If several *-X* switches specify the same
`name`, only the last one is used.
An external variable specified with a *-X* switch
takes precedence over the value of the same name in the environment.
.. index:: -vP (any project-aware tool)
:samp:`-vP{x}`
Indicates the verbosity of the parsing of GNAT project files.
*-vP0* means Default;
*-vP1* means Medium;
*-vP2* means High.
The default is Default: no output for syntactically correct
project files.
If several *-vP*x** switches are present,
only the last one is used.
.. index:: -aP (any project-aware tool)
:samp:`-aP{dir}`
Add directory `dir` at the beginning of the project search path, in order,
after the current working directory.
.. index:: -eL (any project-aware tool)
:samp:`-eL`
Follow all symbolic links when processing project files.
.. index:: --subdirs= (gnatmake and gnatclean)
:samp:`--subdirs={subdir}`
This switch is recognized by *gnatmake* and *gnatclean*. It
indicate that the real directories (except the source directories) are the
subdirectories `subdir` of the directories specified in the project files.
This applies in particular to object directories, library directories and
exec directories. If the subdirectories do not exist, they are created
automatically.
.. _Switches_and_Project_Files:
Switches and Project Files
^^^^^^^^^^^^^^^^^^^^^^^^^^
For each of the packages `Builder`, `Compiler`, `Binder`, and
`Linker`, you can specify a `Default_Switches`
attribute, a `Switches` attribute, or both;
as their names imply, these switch-related
attributes affect the switches that are used for each of these GNAT
components when
*gnatmake* is invoked. As will be explained below, these
component-specific switches precede
the switches provided on the *gnatmake* command line.
The `Default_Switches` attribute is an attribute
indexed by language name (case insensitive) whose value is a string list.
For example:
.. code-block:: gpr
package Compiler is
for Default_Switches ("Ada")
use ("-gnaty",
"-v");
end Compiler;
The `Switches` attribute is indexed on a file name (which may or may
not be case sensitive, depending
on the operating system) whose value is a string list. For example:
.. code-block:: gpr
package Builder is
for Switches ("main1.adb")
use ("-O2");
for Switches ("main2.adb")
use ("-g");
end Builder;
For the `Builder` package, the file names must designate source files
for main subprograms. For the `Binder` and `Linker` packages, the
file names must designate :file:`ALI` or source files for main subprograms.
In each case just the file name without an explicit extension is acceptable.
For each tool used in a program build (*gnatmake*, the compiler, the
binder, and the linker), the corresponding package @dfn{contributes} a set of
switches for each file on which the tool is invoked, based on the
switch-related attributes defined in the package.
In particular, the switches
that each of these packages contributes for a given file `f` comprise:
* the value of attribute `Switches (`f`)`,
if it is specified in the package for the given file,
* otherwise, the value of `Default_Switches ("Ada")`,
if it is specified in the package.
If neither of these attributes is defined in the package, then the package does
not contribute any switches for the given file.
When *gnatmake* is invoked on a file, the switches comprise
two sets, in the following order: those contributed for the file
by the `Builder` package;
and the switches passed on the command line.
When *gnatmake* invokes a tool (compiler, binder, linker) on a file,
the switches passed to the tool comprise three sets,
in the following order:
* the applicable switches contributed for the file
by the `Builder` package in the project file supplied on the command line;
* those contributed for the file by the package (in the relevant project file --
see below) corresponding to the tool; and
* the applicable switches passed on the command line.
The term *applicable switches* reflects the fact that
*gnatmake* switches may or may not be passed to individual
tools, depending on the individual switch.
*gnatmake* may invoke the compiler on source files from different
projects. The Project Manager will use the appropriate project file to
determine the `Compiler` package for each source file being compiled.
Likewise for the `Binder` and `Linker` packages.
As an example, consider the following package in a project file:
.. code-block:: gpr
project Proj1 is
package Compiler is
for Default_Switches ("Ada")
use ("-g");
for Switches ("a.adb")
use ("-O1");
for Switches ("b.adb")
use ("-O2",
"-gnaty");
end Compiler;
end Proj1;
If *gnatmake* is invoked with this project file, and it needs to
compile, say, the files :file:`a.adb`, :file:`b.adb`, and :file:`c.adb`, then
:file:`a.adb` will be compiled with the switch *-O1*,
:file:`b.adb` with switches *-O2* and *-gnaty*,
and :file:`c.adb` with *-g*.
The following example illustrates the ordering of the switches
contributed by different packages:
.. code-block:: gpr
project Proj2 is
package Builder is
for Switches ("main.adb")
use ("-g",
"-O1",
"-f");
end Builder;
package Compiler is
for Switches ("main.adb")
use ("-O2");
end Compiler;
end Proj2;
If you issue the command:
::
$ gnatmake -Pproj2 -O0 main
then the compiler will be invoked on :file:`main.adb` with the following
sequence of switches
::
-g -O1 -O2 -O0
with the last *-O*
switch having precedence over the earlier ones;
several other switches
(such as *-c*) are added implicitly.
The switches *-g*
and *-O1* are contributed by package
`Builder`, *-O2* is contributed
by the package `Compiler`
and *-O0* comes from the command line.
The *-g* switch will also be passed in the invocation of
*Gnatlink.*
A final example illustrates switch contributions from packages in different
project files:
.. code-block:: gpr
project Proj3 is
for Source_Files use ("pack.ads", "pack.adb");
package Compiler is
for Default_Switches ("Ada")
use ("-gnata");
end Compiler;
end Proj3;
with "Proj3";
project Proj4 is
for Source_Files use ("foo_main.adb", "bar_main.adb");
package Builder is
for Switches ("foo_main.adb")
use ("-s",
"-g");
end Builder;
end Proj4;
.. code-block:: ada
-- Ada source file:
with Pack;
procedure Foo_Main is
...
end Foo_Main;
If the command is
::
$ gnatmake -PProj4 foo_main.adb -cargs -gnato
then the switches passed to the compiler for :file:`foo_main.adb` are
*-g* (contributed by the package `Proj4.Builder`) and
*-gnato* (passed on the command line).
When the imported package `Pack` is compiled, the switches used
are *-g* from `Proj4.Builder`,
*-gnata* (contributed from package `Proj3.Compiler`,
and *-gnato* from the command line.
When using *gnatmake* with project files, some switches or
arguments may be expressed as relative paths. As the working directory where
compilation occurs may change, these relative paths are converted to absolute
paths. For the switches found in a project file, the relative paths
are relative to the project file directory, for the switches on the command
line, they are relative to the directory where *gnatmake* is invoked.
The switches for which this occurs are:
-I,
-A,
-L,
-aO,
-aL,
-aI, as well as all arguments that are not switches (arguments to
switch
-o, object files specified in package `Linker` or after
-largs on the command line). The exception to this rule is the switch
--RTS= for which a relative path argument is never converted.
.. _Specifying_Configuration_Pragmas:
Specifying Configuration Pragmas
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When using *gnatmake* with project files, if there exists a file
:file:`gnat.adc` that contains configuration pragmas, this file will be
ignored.
Configuration pragmas can be defined by means of the following attributes in
project files: `Global_Configuration_Pragmas` in package `Builder`
and `Local_Configuration_Pragmas` in package `Compiler`.
Both these attributes are single string attributes. Their values is the path
name of a file containing configuration pragmas. If a path name is relative,
then it is relative to the project directory of the project file where the
attribute is defined.
When compiling a source, the configuration pragmas used are, in order,
those listed in the file designated by attribute
`Global_Configuration_Pragmas` in package `Builder` of the main
project file, if it is specified, and those listed in the file designated by
attribute `Local_Configuration_Pragmas` in package `Compiler` of
the project file of the source, if it exists.
.. _Project_Files_and_Main_Subprograms:
Project Files and Main Subprograms
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
When using a project file, you can invoke *gnatmake*
with one or several main subprograms, by specifying their source files on the
command line.
::
$ gnatmake -Pprj main1.adb main2.adb main3.adb
Each of these needs to be a source file of the same project, except
when the switch `-u` is used.
When `-u` is not used, all the mains need to be sources of the
same project, one of the project in the tree rooted at the project specified
on the command line. The package `Builder` of this common project, the
"main project" is the one that is considered by *gnatmake*.
When `-u` is used, the specified source files may be in projects
imported directly or indirectly by the project specified on the command line.
Note that if such a source file is not part of the project specified on the
command line, the switches found in package `Builder` of the
project specified on the command line, if any, that are transmitted
to the compiler will still be used, not those found in the project file of
the source file.
When using a project file, you can also invoke *gnatmake* without
explicitly specifying any main, and the effect depends on whether you have
defined the `Main` attribute. This attribute has a string list value,
where each element in the list is the name of a source file (the file
extension is optional) that contains a unit that can be a main subprogram.
If the `Main` attribute is defined in a project file as a non-empty
string list and the switch *-u* is not used on the command
line, then invoking *gnatmake* with this project file but without any
main on the command line is equivalent to invoking *gnatmake* with all
the file names in the `Main` attribute on the command line.
Example:
.. code-block:: gpr
project Prj is
for Main use ("main1.adb", "main2.adb", "main3.adb");
end Prj;
With this project file, `"gnatmake -Pprj"`
is equivalent to
`"gnatmake -Pprj main1.adb main2.adb main3.adb"`.
When the project attribute `Main` is not specified, or is specified
as an empty string list, or when the switch *-u* is used on the command
line, then invoking *gnatmake* with no main on the command line will
result in all immediate sources of the project file being checked, and
potentially recompiled. Depending on the presence of the switch *-u*,
sources from other project files on which the immediate sources of the main
project file depend are also checked and potentially recompiled. In other
words, the *-u* switch is applied to all of the immediate sources of the
main project file.
When no main is specified on the command line and attribute `Main` exists
and includes several mains, or when several mains are specified on the
command line, the default switches in package `Builder` will
be used for all mains, even if there are specific switches
specified for one or several mains.
But the switches from package `Binder` or `Linker` will be
the specific switches for each main, if they are specified.
.. _Library_Project_Files:
Library Project Files
^^^^^^^^^^^^^^^^^^^^^
When *gnatmake* is invoked with a main project file that is a library
project file, it is not allowed to specify one or more mains on the command
line.
When a library project file is specified, switches `-b` and
`-l` have special meanings.
* `-b` is only allowed for stand-alone libraries. It indicates
to *gnatmake* that *gnatbind* should be invoked for the
library.
* `-l` may be used for all library projects. It indicates
to *gnatmake* that the binder generated file should be compiled
(in the case of a stand-alone library) and that the library should be built.
.. _The_GNAT_Driver_and_Project_Files:
The GNAT Driver and Project Files
---------------------------------
A number of GNAT tools beyond *gnatmake*
can benefit from project files:
.. only:: PRO or GPL
* *gnatbind*
* *gnatcheck*
* *gnatclean*
* *gnatelim*
* *gnatfind*
* *gnatlink*
* *gnatls*
* *gnatmetric*
* *gnatpp*
* *gnatstub*
* *gnatxref*
.. only:: FSF
* *gnatbind*
* *gnatclean*
* *gnatfind*
* *gnatlink*
* *gnatls*
* *gnatxref*
However, none of these tools can be invoked
directly with a project file switch (*-P*).
They must be invoked through the *gnat* driver.
The *gnat* driver is a wrapper that accepts a number of commands and
calls the corresponding tool. It was designed initially for VMS platforms (to
convert VMS qualifiers to Unix-style switches), but it is now available on all
GNAT platforms.
On non-VMS platforms, the *gnat* driver accepts the following commands
(case insensitive):
.. only:: PRO or GPL
* BIND to invoke *gnatbind*
* CHOP to invoke *gnatchop*
* CLEAN to invoke *gnatclean*
* COMP or COMPILE to invoke the compiler
* ELIM to invoke *gnatelim*
* FIND to invoke *gnatfind*
* KR or KRUNCH to invoke *gnatkr*
* LINK to invoke *gnatlink*
* LS or LIST to invoke *gnatls*
* MAKE to invoke *gnatmake*
* METRIC to invoke *gnatmetric*
* NAME to invoke *gnatname*
* PP or PRETTY to invoke *gnatpp*
* PREP or PREPROCESS to invoke *gnatprep*
* STUB to invoke *gnatstub*
* XREF to invoke *gnatxref*
.. only:: FSF
* BIND to invoke *gnatbind*
* CHOP to invoke *gnatchop*
* CLEAN to invoke *gnatclean*
* COMP or COMPILE to invoke the compiler
* FIND to invoke *gnatfind*
* KR or KRUNCH to invoke *gnatkr*
* LINK to invoke *gnatlink*
* LS or LIST to invoke *gnatls*
* MAKE to invoke *gnatmake*
* NAME to invoke *gnatname*
* PREP or PREPROCESS to invoke *gnatprep*
* XREF to invoke *gnatxref*
Note that the command
*gnatmake -c -f -u* is used to invoke the compiler.
On non-VMS platforms, between *gnat* and the command, two
special switches may be used:
* *-v* to display the invocation of the tool.
* *-dn* to prevent the *gnat* driver from removing
the temporary files it has created. These temporary files are
configuration files and temporary file list files.
The command may be followed by switches and arguments for the invoked
tool.
::
$ gnat bind -C main.ali
$ gnat ls -a main
$ gnat chop foo.txt
Switches may also be put in text files, one switch per line, and the text
files may be specified with their path name preceded by '@'.
::
$ gnat bind @args.txt main.ali
In addition, for the following commands the project file related switches
(*-P*, *-X* and *-vPx*) may be used in addition to
the switches of the invoking tool:
.. only:: PRO or GPL
* BIND
* COMP or COMPILE
* FIND
* ELIM
* LS or LIST
* LINK
* METRIC
* PP or PRETTY
* STUB
* XREF
.. only:: FSF
* BIND
* COMP or COMPILE
* FIND
* LS or LIST
* LINK
* XREF
.. only:: PRO or GPL
When GNAT PP or GNAT PRETTY is used with a project file, but with no source
specified on the command line, it invokes *gnatpp* with all
the immediate sources of the specified project file.
When GNAT METRIC is used with a project file, but with no source
specified on the command line, it invokes *gnatmetric*
with all the immediate sources of the specified project file and with
*-d* with the parameter pointing to the object directory
of the project.
In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with
a project file, no source is specified on the command line and
switch -U is specified on the command line, then
the underlying tool (gnatpp or
gnatmetric) is invoked for all sources of all projects,
not only for the immediate sources of the main project.
(-U stands for Universal or Union of the project files of the project tree)
For each of the following commands, there is optionally a corresponding
package in the main project.
.. only:: PRO or GPL
* package `Binder` for command BIND (invoking `gnatbind`)
* package `Check` for command CHECK (invoking `gnatcheck`)
* package `Compiler` for command COMP or COMPILE (invoking the compiler)
* package `Cross_Reference` for command XREF (invoking `gnatxref`)
* package `Eliminate` for command ELIM (invoking `gnatelim`)
* package `Finder` for command FIND (invoking `gnatfind`)
* package `Gnatls` for command LS or LIST (invoking `gnatls`)
* package `Gnatstub` for command STUB (invoking `gnatstub`)
* package `Linker` for command LINK (invoking `gnatlink`)
* package `Metrics` for command METRIC (invoking `gnatmetric`)
* package `Pretty_Printer` for command PP or PRETTY (invoking `gnatpp`)
.. only:: FSF
* package `Binder` for command BIND (invoking `gnatbind`)
* package `Compiler` for command COMP or COMPILE (invoking the compiler)
* package `Cross_Reference` for command XREF (invoking `gnatxref`)
* package `Finder` for command FIND (invoking `gnatfind`)
* package `Gnatls` for command LS or LIST (invoking `gnatls`)
* package `Linker` for command LINK (invoking `gnatlink`)
Package `Gnatls` has a unique attribute `Switches`,
a simple variable with a string list value. It contains switches
for the invocation of `gnatls`.
.. code-block:: gpr
project Proj1 is
package gnatls is
for Switches
use ("-a",
"-v");
end gnatls;
end Proj1;
All other packages have two attribute `Switches` and
`Default_Switches`.
`Switches` is an indexed attribute, indexed by the
source file name, that has a string list value: the switches to be
used when the tool corresponding to the package is invoked for the specific
source file.
`Default_Switches` is an attribute,
indexed by the programming language that has a string list value.
`Default_Switches ("Ada")` contains the
switches for the invocation of the tool corresponding
to the package, except if a specific `Switches` attribute
is specified for the source file.
.. code-block:: gpr
project Proj is
for Source_Dirs use ("");
package gnatls is
for Switches use
("-a",
"-v");
end gnatls;
package Compiler is
for Default_Switches ("Ada")
use ("-gnatv",
"-gnatwa");
end Binder;
package Binder is
for Default_Switches ("Ada")
use ("-C",
"-e");
end Binder;
package Linker is
for Default_Switches ("Ada")
use ("-C");
for Switches ("main.adb")
use ("-C",
"-v",
"-v");
end Linker;
package Finder is
for Default_Switches ("Ada")
use ("-a",
"-f");
end Finder;
package Cross_Reference is
for Default_Switches ("Ada")
use ("-a",
"-f",
"-d",
"-u");
end Cross_Reference;
end Proj;
With the above project file, commands such as
::
$ gnat comp -Pproj main
$ gnat ls -Pproj main
$ gnat xref -Pproj main
$ gnat bind -Pproj main.ali
$ gnat link -Pproj main.ali
will set up the environment properly and invoke the tool with the switches
found in the package corresponding to the tool:
`Default_Switches ("Ada")` for all tools,
except `Switches ("main.adb")`
for `gnatlink`.
.. only:: PRO or GPL
It is also possible to invoke some of the tools,
(`gnatcheck`,
`gnatmetric`,
and `gnatpp`)
on a set of project units thanks to the combination of the switches
*-P*, *-U* and possibly the main unit when one is interested
in its closure. For instance,
::
$ gnat metric -Pproj
will compute the metrics for all the immediate units of project `proj`.
::
$ gnat metric -Pproj -U
will compute the metrics for all the units of the closure of projects
rooted at `proj`.
::
$ gnat metric -Pproj -U main_unit
will compute the metrics for the closure of units rooted at
`main_unit`. This last possibility relies implicitly
on *gnatbind*'s option *-R*. But if the argument files for the
tool invoked by the *gnat* driver are explicitly specified
either directly or through the tool *-files* option, then the tool
is called only for these explicitly specified files.

180
gcc/ada/doc/share/ada_pygments.py Normal file
View File

@ -0,0 +1,180 @@
"""Alternate Ada and Project Files parsers for Sphinx/Rest"""
import re
from pygments.lexer import RegexLexer, bygroups
from pygments.token import Text, Comment, Operator, Keyword, Name, String, \
Number, Punctuation
def get_lexer_tokens(tag_highlighting=False, project_support=False):
"""Return the tokens needed for RegexLexer
:param tag_highlighting: if True we support tag highlighting. See
AdaLexerWithTags documentation
:type tag_highlighting: bool
:param project_support: if True support additional keywors associated
with project files.
:type project_support: bool
:return: a dictionary following the structure required by RegexLexer
:rtype: dict
"""
if project_support:
project_pattern = r'project\s+|'
project_pattern2 = r'project|'
else:
project_pattern = r''
project_pattern2 = r''
result = {
'root': [
# Comments
(r'--.*$', Comment),
# Character literal
(r"'.'", String.Char),
# Strings
(r'"[^"]*"', String),
# Numeric
# Based literal
(r'[0-9][0-9_]*#[0-9a-f][0-9a-f_]*#(E[\+-]?[0-9][0-9_]*)?',
Number.Integer),
(r'[0-9][0-9_]*#[0-9a-f][0-9a-f_]*'
r'\.[0-9a-f][0-9a-f_]*#(E[\+-]?[0-9][0-9_]*)?', Number.Float),
# Decimal literal
(r'[0-9][0-9_]*\.[0-9][0-9_](E[\+-]?[0-9][0-9_]*)?', Number.Float),
(r'[0-9][0-9_]*(E[\+-]?[0-9][0-9_]*)?', Number.Integer),
# Match use and with statements
# The first part of the pattern is be sure we don't match
# for/use constructs.
(r'(\n\s*|;\s*)(with|use)(\s+[\w\.]+)',
bygroups(Punctuation, Keyword.Reserved, Name.Namespace)),
# Match procedure, package and function declarations
(r'end\s+(if|loop|record)', Keyword),
(r'(package(?:\s+body)?\s+|' + project_pattern +
r'function\s+|end\s+|procedure\s+)([\w\.]+)',
bygroups(Keyword, Name.Function)),
# Ada 2012 standard attributes, GNAT specific ones and
# Spark 2014 ones ('Update and 'Loop_Entry)
# (reversed order to avoid having for
# example Max before Max_Alignment_For_Allocation).
(r'\'(Write|Width|Wide_Width|Wide_Wide_Width|Wide_Wide_Value|'
r'Wide_Wide_Image|Wide_Value|Wide_Image|Word_Size|Wchar_T_Size|'
r'Version|Value_Size|Value|Valid_Scalars|VADS_Size|Valid|Val|'
r'Update|Unrestricted_Access|Universal_Literal_String|'
r'Unconstrained_Array|Unchecked_Access|Unbiased_Rounding|'
r'UET_Address|Truncation|Type_Class|To_Address|Tick|Terminated|'
r'Target_Name|Tag|System_Allocator_Alignment|Succ|Stub_Type|'
r'Stream_Size|Storage_Unit|Storage_Size|Storage_Pool|Small|Size|'
r'Simple_Storage_Pool|Signed_Zeros|Scaling|Scale|'
r'Scalar_Storage_Order|Safe_Last|Safe_Large|Safe_First|'
r'Safe_Emax|Rounding|Round|Result|Remainder|Ref|Read|'
r'Range_Length|Range|Priority|Pred|'
r'Position|Pos|Pool_Address|Passed_By_Reference|Partition_Id|'
r'Overlaps_Storage|Output|Old|Object_Size|Null_Parameter|Modulus|'
r'Model_Small|Model_Mantissa|Model_Epsilon|Model_Emin|Model|Mod|'
r'Min|Mechanism_Code|Maximum_Alignment|'
r'Max_Size_In_Storage_Elements|Max_Priority|'
r'Max_Interrupt_Priority|Max_Alignment_For_Allocation|'
r'Max|Mantissa|Machine_Size|Machine_Rounds|Machine_Rounding|'
r'Machine_Radix|Machine_Overflows|Machine_Mantissa|Machine_Emin|'
r'Machine_Emax|Machine|Loop_Entry|Length|Length|Leading_Part|'
r'Last_Valid|Last_Bit|Last|Large|Invalid_Value|Integer_Value|'
r'Input|Image|Img|Identity|Has_Same_Storage|Has_Discriminants|'
r'Has_Access_Values|Fraction|Fore|Floor|Fixed_Value|First_Valid|'
r'First_Bit|First|External_Tag|Exponent|Epsilon|Enum_Val|'
r'Enum_Rep|Enabled|Emax|Elaborated|Elab_Subp_Body|Elab_Spec|'
r'Elab_Body|Descriptor_Size|Digits|Denorm|Delta|Definite|'
r'Default_Bit_Order|Count|Copy_Sign|Constrained|'
r'Compose|Component_Size|Compiler_Version|Code_Address|Class|'
r'Ceiling|Caller|Callable|Body_Version|Bit_Order|Bit_Position|'
r'Bit|Base|Asm_Output|Asm_Input|Alignment|Aft|Adjacent|'
r'Address_Size|Address|Access|Abort_Signal|AST_Entry)',
Name.Attribute),
# All Ada2012 reserved words
(r'(abort|abstract|abs|accept|access|aliased|all|and|array|at|'
r'begin|body|case|constant|declare|delay|delta|digits|do|'
r'else|elsif|end|entry|exception|exit|for|function|generic|goto|'
r'if|interface|in|is|limited|loop|mod|new|not|null|'
r'of|or|others|out|overriding|' + project_pattern2 +
r'package|pragma|private|procedure|protected|'
r'raise|range|record|rem|renames|requeue|return|reverse|'
r'select|separate|some|subtype|synchronized|'
r'tagged|task|terminate|then|type|until|use|when|while|with|xor'
r')([\s;,])',
bygroups(Keyword.Reserved, Punctuation)),
# Two characters operators
(r'=>|\.\.|\*\*|:=|/=|>=|<=|<<|>>|<>', Operator),
# One character operators
(r'&|\'|\(|\)|\*|\+|-|\.|/|:|<|=|>|\|', Operator),
(r',|;', Punctuation),
# Spaces
(r'\s+', Text),
# Builtin values
(r'False|True', Keyword.Constant),
# Identifiers
(r'[\w\.]+', Name)], }
# Insert tag highlighting before identifiers
if tag_highlighting:
result['root'].insert(-1, (r'\[[\w ]*\]', Name.Tag))
return result
class AdaLexer(RegexLexer):
"""Alternate Pygments lexer for Ada source code and project files
The default pygments lexer always fails causing disabling of syntax
highlighting in Sphinx. This lexer is simpler but safer.
In order to use this lexer in your Sphinx project add the following
code at the end of your conf.py
.. code-block:: python
import gnatpython.ada_pygments
def setup(app):
app.add_lexer('ada', gnatpython.ada_pygments.AdaLexer())
"""
name = 'Ada'
aliases = ['ada', 'ada83', 'ada95', 'ada2005', 'ada2012']
filenames = ['*.adb', '*.ads', '*.ada']
mimetypes = ['text/x-ada']
flags = re.MULTILINE | re.I # Ignore case
tokens = get_lexer_tokens()
class TaggedAdaLexer(AdaLexer):
"""Alternate Pygments lexer for Ada source code with tags
A tag is a string of the form::
[MY STRING]
Only alphanumerical characters and spaces are considered inside the
brackets.
"""
name = 'TaggedAda'
aliases = ['tagged_ada']
tokens = get_lexer_tokens(True)
class GNATProjectLexer(RegexLexer):
"""Pygment lexer for project files
This is the same as the AdaLexer but with support of ``project``
keyword.
"""
name = 'GPR'
aliases = ['gpr']
filenames = ['*.gpr']
mimetypes = ['text/x-gpr']
flags = re.MULTILINE | re.I # Ignore case
tokens = get_lexer_tokens(project_support=True)

134
gcc/ada/doc/share/conf.py Normal file
View File

@ -0,0 +1,134 @@
# -*- coding: utf-8 -*-
#
# GNAT build configuration file
import sys
import os
import time
import re
sys.path.append('.')
import ada_pygments
import latex_elements
# Some configuration values for the various documentation handled by
# this conf.py
DOCS = {
'gnat_rm': {
'title': u'GNAT Reference Manual'},
'gnat_ugn': {
'title': u'GNAT User\'s Guide for Native Platforms'}}
# Then retrieve the source directory
root_source_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
gnatvsn_spec = os.path.join(root_source_dir, '..', 'gnatvsn.ads')
basever = os.path.join(root_source_dir, '..', '..', 'BASE-VER')
texi_fsf = True # Set to False when FSF doc is switched to sphinx by default
with open(gnatvsn_spec, 'rb') as fd:
gnatvsn_content = fd.read()
def get_copyright():
return u'2008-%s, Free Software Foundation' % time.strftime('%Y')
def get_gnat_version():
m = re.search(r'Gnat_Static_Version_String : ' +
r'constant String := "([^\(\)]+)\(.*\)?";',
gnatvsn_content)
if m:
return m.group(1).strip()
else:
if texi_fsf and os.path.exists(basever):
return ''
try:
with open(basever, 'rb') as fd:
return fd.read()
except:
pass
print 'cannot find GNAT version in gnatvsn.ads or in ' + basever
sys.exit(1)
def get_gnat_build_type():
m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);',
gnatvsn_content)
if m:
return {'Gnatpro': 'PRO',
'FSF': 'FSF',
'GPL': 'GPL'}[m.group(1).strip()]
else:
print 'cannot compute GNAT build type'
sys.exit(1)
# First retrieve the name of the documentation we are building
doc_name = os.environ.get('DOC_NAME', None)
if doc_name is None:
print 'DOC_NAME environment variable should be set'
sys.exit(1)
if doc_name not in DOCS:
print '%s is not a valid documentation name' % doc_name
sys.exit(1)
# Exclude sources that are not part of the current documentation
exclude_patterns = []
for d in os.listdir(root_source_dir):
if d not in ('share', doc_name, doc_name + '.rst'):
exclude_patterns.append(d)
print 'ignoring %s' % d
if doc_name == 'gnat_rm':
exclude_patterns.append('share/gnat_project_manager.rst')
print 'ignoring share/gnat_project_manager.rst'
extensions = []
templates_path = ['_templates']
source_suffix = '.rst'
master_doc = doc_name
# General information about the project.
project = DOCS[doc_name]['title']
copyright = get_copyright()
version = get_gnat_version()
release = get_gnat_version()
pygments_style = 'sphinx'
tags.add(get_gnat_build_type())
html_theme = 'sphinxdoc'
if os.path.isfile('adacore_transparent.png'):
html_logo = 'adacore_transparent.png'
if os.path.isfile('favicon.ico'):
html_favicon = 'favicon.ico'
html_static_path = ['_static']
latex_elements = {
'preamble': latex_elements.TOC_DEPTH +
latex_elements.PAGE_BLANK +
latex_elements.TOC_CMD +
latex_elements.LATEX_HYPHEN +
latex_elements.doc_settings(DOCS[doc_name]['title'],
get_gnat_version()),
'tableofcontents': latex_elements.TOC}
latex_documents = [
(master_doc, '%s.tex' % doc_name, project, u'AdaCore', 'manual')]
texinfo_documents = [
(master_doc, doc_name, project,
u'AdaCore', doc_name, doc_name, '')]
def setup(app):
app.add_lexer('ada', ada_pygments.AdaLexer())
app.add_lexer('gpr', ada_pygments.GNATProjectLexer())

458
gcc/ada/doc/share/gnu_free_documentation_license.rst Normal file
View File

@ -0,0 +1,458 @@
.. _gnu_fdl:
******************************
GNU Free Documentation License
******************************
Version 1.3, 3 November 2008
Copyright 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc
http://fsf.org/
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
**Preamble**
The purpose of this License is to make a manual, textbook, or other
functional and useful document "free" in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of "copyleft", which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
**1. APPLICABILITY AND DEFINITIONS**
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The **Document**, below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as "**you**". You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A "**Modified Version**" of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A "**Secondary Section**" is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The "**Invariant Sections**" are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The "**Cover Texts**" are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A "**Transparent**" copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not "Transparent" is called **Opaque**.
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The "**Title Page**" means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, "Title Page" means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
The "**publisher**" means any person or entity that distributes
copies of the Document to the public.
A section "**Entitled XYZ**" means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as "**Acknowledgements**",
"**Dedications**", "**Endorsements**", or "**History**".)
To "**Preserve the Title**"
of such a section when you modify the Document means that it remains a
section "Entitled XYZ" according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
**2. VERBATIM COPYING**
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
**3. COPYING IN QUANTITY**
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
**4. MODIFICATIONS**
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.
D. Preserve all the copyright notices of the Document.
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.
H. Include an unaltered copy of this License.
I. Preserve the section Entitled "History", Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled "History" in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the "History" section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.
K. For any section Entitled "Acknowledgements" or "Dedications",
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.
M. Delete any section Entitled "Endorsements". Such a section
may not be included in the Modified Version.
N. Do not retitle any existing section to be Entitled "Endorsements"
or to conflict in title with any Invariant Section.
O. Preserve any Warranty Disclaimers.
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled "Endorsements", provided it contains
nothing but endorsements of your Modified Version by various
parties---for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
**5. COMBINING DOCUMENTS**
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled "History"
in the various original documents, forming one section Entitled
"History"; likewise combine any sections Entitled "Acknowledgements",
and any sections Entitled "Dedications". You must delete all sections
Entitled "Endorsements".
**6. COLLECTIONS OF DOCUMENTS**
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
**7. AGGREGATION WITH INDEPENDENT WORKS**
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an "aggregate" if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
**8. TRANSLATION**
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled "Acknowledgements",
"Dedications", or "History", the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
**9. TERMINATION**
You may not copy, modify, sublicense, or distribute the Document
except as expressly provided under this License. Any attempt
otherwise to copy, modify, sublicense, or distribute it is void, and
will automatically terminate your rights under this License.
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, receipt of a copy of some or all of the same material does
not give you any rights to use it.
**10. FUTURE REVISIONS OF THIS LICENSE**
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License "or any later version" applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation. If the Document
specifies that a proxy can decide which future versions of this
License can be used, that proxy's public statement of acceptance of a
version permanently authorizes you to choose that version for the
Document.
**11. RELICENSING**
"Massive Multiauthor Collaboration Site" (or "MMC Site") means any
World Wide Web server that publishes copyrightable works and also
provides prominent facilities for anybody to edit those works. A
public wiki that anybody can edit is an example of such a server. A
"Massive Multiauthor Collaboration" (or "MMC") contained in the
site means any set of copyrightable works thus published on the MMC
site.
"CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
license published by Creative Commons Corporation, a not-for-profit
corporation with a principal place of business in San Francisco,
California, as well as future copyleft versions of that license
published by that same organization.
"Incorporate" means to publish or republish a Document, in whole or
in part, as part of another Document.
An MMC is "eligible for relicensing" if it is licensed under this
License, and if all works that were first published under this License
somewhere other than this MMC, and subsequently incorporated in whole
or in part into the MMC, (1) had no cover texts or invariant sections,
and (2) were thus incorporated prior to November 1, 2008.
The operator of an MMC Site may republish an MMC contained in the site
under CC-BY-SA on the same site at any time before August 1, 2009,
provided the MMC is eligible for relicensing.
**ADDENDUM: How to use this License for your documents**
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
Copyright © YEAR YOUR NAME.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled "GNU
Free Documentation License".
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the "with ... Texts." line with this:
with the Invariant Sections being LIST THEIR TITLES, with the
Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.

64
gcc/ada/doc/share/latex_elements.py Normal file
View File

@ -0,0 +1,64 @@
# define some latex elements to be used for PDF output
PAGE_BLANK = r'''
\makeatletter
\def\cleartooddpage{%%
\cleardoublepage%%
}
\def\cleardoublepage{%%
\clearpage%%
\if@twoside%%
\ifodd\c@page%%
%% nothing to do
\else%%
\hbox{}%%
\thispagestyle{plain}%%
\vspace*{\fill}%%
\begin{center}%%
\textbf{\em This page is intentionally left blank.}%%
\end{center}%%
\vspace{\fill}%%
\newpage%%
\if@twocolumn%%
\hbox{}%%
\newpage%%
\fi%%
\fi%%
\fi%%
}
\makeatother
'''
TOC_DEPTH = r'''
\pagenumbering{arabic}
\setcounter{tocdepth}{3}
'''
TOC_CMD = r'''
\makeatletter
\def\tableofcontents{%%
\pagestyle{plain}%%
\chapter*{\contentsname}%%
\@mkboth{\MakeUppercase{\contentsname}}%%
{\MakeUppercase{\contentsname}}%%
\@starttoc{toc}%%
}
\makeatother
'''
TOC = r'''
\cleardoublepage
\tableofcontents
\cleardoublepage\pagestyle{plain}
'''
LATEX_HYPHEN = r'''
\hyphenpenalty=5000
\tolerance=1000
'''
def doc_settings(full_document_name, version):
return '\n'.join([
r'\newcommand*{\GNATFullDocumentName}[0]{' + full_document_name + r'}',
r'\newcommand*{\GNATVersion}[0]{' + version + r'}'])

570
gcc/ada/doc/share/sphinx.sty Normal file
View File

@ -0,0 +1,570 @@
%
% sphinx.sty
%
% Adapted from the old python.sty, mostly written by Fred Drake,
% by Georg Brandl.
%
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\ProvidesPackage{sphinx}[2010/01/15 LaTeX package (Sphinx markup)]
\@ifclassloaded{memoir}{}{\RequirePackage{fancyhdr}}
\RequirePackage{textcomp}
\RequirePackage{fancybox}
\RequirePackage{titlesec}
\RequirePackage{tabulary}
\RequirePackage{amsmath} % for \text
\RequirePackage{makeidx}
\RequirePackage{framed}
\RequirePackage{ifthen}
\RequirePackage{color}
% For highlighted code.
\RequirePackage{fancyvrb}
% For table captions.
\RequirePackage{threeparttable}
% Handle footnotes in tables.
\RequirePackage{footnote}
\makesavenoteenv{tabulary}
% For floating figures in the text.
\RequirePackage{wrapfig}
% Separate paragraphs by space by default.
\RequirePackage{parskip}
\RequirePackage{lastpage}
% Redefine these colors to your liking in the preamble.
\definecolor{TitleColor}{rgb}{0.126,0.263,0.361}
\definecolor{InnerLinkColor}{rgb}{0.208,0.374,0.486}
\definecolor{OuterLinkColor}{rgb}{0.216,0.439,0.388}
% Required to preserve indentation settings in minipage constructs
% (otherwise parskip is set to 0 by default. minipagerestore is called
% each time we enter a minipage environment)
\newcommand{\@minipagerestore}{\setlength{\parskip}{\medskipamount}}
% Redefine these colors to something not white if you want to have colored
% background and border for code examples.
\definecolor{VerbatimColor}{rgb}{1,1,1}
\definecolor{VerbatimBorderColor}{rgb}{1,1,1}
% Uncomment these two lines to ignore the paper size and make the page
% size more like a typical published manual.
%\renewcommand{\paperheight}{9in}
%\renewcommand{\paperwidth}{8.5in} % typical squarish manual
%\renewcommand{\paperwidth}{7in} % O'Reilly ``Programmming Python''
% use pdfoutput for pTeX and dvipdfmx
\ifx\kanjiskip\undefined\else
\ifx\Gin@driver{dvipdfmx.def}\undefined\else
\newcount\pdfoutput\pdfoutput=0
\fi
\fi
% For graphicx, check if we are compiling under latex or pdflatex.
\ifx\pdftexversion\undefined
\usepackage{graphicx}
\else
\usepackage[pdftex]{graphicx}
\fi
% for PDF output, use colors and maximal compression
\newif\ifsphinxpdfoutput\sphinxpdfoutputfalse
\ifx\pdfoutput\undefined\else\ifcase\pdfoutput
\let\py@NormalColor\relax
\let\py@TitleColor\relax
\else
\sphinxpdfoutputtrue
\input{pdfcolor}
\def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
\def\py@TitleColor{\color{TitleColor}}
\pdfcompresslevel=9
\fi\fi
% XeLaTeX can do colors, too
\ifx\XeTeXrevision\undefined\else
\def\py@NormalColor{\color[rgb]{0.0,0.0,0.0}}
\def\py@TitleColor{\color{TitleColor}}
\fi
% Increase printable page size (copied from fullpage.sty)
\topmargin 0pt
\advance \topmargin by -\headheight
\advance \topmargin by -\headsep
% attempt to work a little better for A4 users
\textheight \paperheight
\advance\textheight by -2in
\oddsidemargin 0pt
\evensidemargin 0pt
%\evensidemargin -.25in % for ``manual size'' documents
\marginparwidth 0.5in
\textwidth \paperwidth
\advance\textwidth by -2in
% Style parameters and macros used by most documents here
\raggedbottom
\sloppy
\hbadness = 5000 % don't print trivial gripes
\pagestyle{empty} % start this way
\renewcommand{\maketitle}{%
\begin{titlepage}%
\let\footnotesize\small
\let\footnoterule\relax
\rule{\textwidth}{1pt}%
\ifsphinxpdfoutput
\begingroup
% These \defs are required to deal with multi-line authors; it
% changes \\ to ', ' (comma-space), making it pass muster for
% generating document info in the PDF file.
\def\\{, }
\def\and{and }
\pdfinfo{
/Author (\@author)
/Title (\@title)
}
\endgroup
\fi
\begin{flushright}%
\sphinxlogo%
{\rm\Huge \@title \par}%
{\em\LARGE\py@HeaderFamily \py@release\releaseinfo \par}
\vfill
{\LARGE\py@HeaderFamily
\par}
\vfill\vfill
{\large
\@date \par
\vfill
\py@authoraddress \par
}%
\end{flushright}%\par
\@thanks
\end{titlepage}%
\cleardoublepage%
\setcounter{footnote}{0}%
\let\thanks\relax\let\maketitle\relax
}
% Use this to set the font family for headers and other decor:
\newcommand{\py@HeaderFamily}{\sffamily\bfseries}
% Redefine the 'normal' header/footer style when using "fancyhdr" package:
\@ifundefined{fancyhf}{}{
% Use \pagestyle{normal} as the primary pagestyle for text.
\fancypagestyle{normal}{
\fancyhf{}
\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage\ of \pageref*{LastPage}}}
\fancyfoot[LO]{{\py@HeaderFamily\nouppercase{\rightmark}}}
\fancyfoot[RE]{{\py@HeaderFamily\nouppercase{\leftmark}}}
\fancyhead[LE,RO]{{\py@HeaderFamily \@title, \py@release}}
\renewcommand{\headrulewidth}{0.4pt}
\renewcommand{\footrulewidth}{0.4pt}
% define chaptermark with \@chappos when \@chappos is available for Japanese
\ifx\@chappos\undefined\else
\def\chaptermark##1{\markboth{\@chapapp\space\thechapter\space\@chappos\space ##1}{}}
\fi
}
% Update the plain style so we get the page number & footer line,
% but not a chapter or section title. This is to keep the first
% page of a chapter and the blank page between chapters `clean.'
\fancypagestyle{plain}{
\fancyhf{}
\fancyfoot[LE,RO]{{\py@HeaderFamily\thepage\ of \pageref*{LastPage}}}
\fancyfoot[LO,RE]{{\py@HeaderFamily \GNATFullDocumentName}}
\fancyhead[LE,RO]{{\py@HeaderFamily \@title\ \GNATVersion}}
\renewcommand{\headrulewidth}{0.0pt}
\renewcommand{\footrulewidth}{0.4pt}
}
}
% Some custom font markup commands.
%
\newcommand{\strong}[1]{{\textbf{#1}}}
\newcommand{\code}[1]{\texttt{#1}}
\newcommand{\bfcode}[1]{\code{\bfseries#1}}
\newcommand{\email}[1]{\textsf{#1}}
% Redefine the Verbatim environment to allow border and background colors.
% The original environment is still used for verbatims within tables.
\let\OriginalVerbatim=\Verbatim
\let\endOriginalVerbatim=\endVerbatim
% Play with vspace to be able to keep the indentation.
\newlength\distancetoright
\def\mycolorbox#1{%
\setlength\distancetoright{\linewidth}%
\advance\distancetoright -\@totalleftmargin %
\fcolorbox{VerbatimBorderColor}{VerbatimColor}{%
\begin{minipage}{\distancetoright}%
#1
\end{minipage}%
}%
}
\def\FrameCommand{\mycolorbox}
\renewcommand{\Verbatim}[1][1]{%
% list starts new par, but we don't want it to be set apart vertically
\bgroup\parskip=0pt%
\smallskip%
% The list environement is needed to control perfectly the vertical
% space.
\list{}{%
\setlength\parskip{0pt}%
\setlength\itemsep{0ex}%
\setlength\topsep{0ex}%
\setlength\partopsep{0pt}%
\setlength\leftmargin{0pt}%
}%
\item\MakeFramed {\FrameRestore}%
\small%
\OriginalVerbatim[#1]%
}
\renewcommand{\endVerbatim}{%
\endOriginalVerbatim%
\endMakeFramed%
\endlist%
% close group to restore \parskip
\egroup%
}
% \moduleauthor{name}{email}
\newcommand{\moduleauthor}[2]{}
% \sectionauthor{name}{email}
\newcommand{\sectionauthor}[2]{}
% Augment the sectioning commands used to get our own font family in place,
% and reset some internal data items:
\titleformat{\section}{\Large\py@HeaderFamily}%
{\py@TitleColor\thesection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsection}{\large\py@HeaderFamily}%
{\py@TitleColor\thesubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\subsubsection}{\py@HeaderFamily}%
{\py@TitleColor\thesubsubsection}{0.5em}{\py@TitleColor}{\py@NormalColor}
\titleformat{\paragraph}{\small\py@HeaderFamily}%
{\py@TitleColor}{0em}{\py@TitleColor}{\py@NormalColor}
% {fulllineitems} is the main environment for object descriptions.
%
\newcommand{\py@itemnewline}[1]{%
\@tempdima\linewidth%
\advance\@tempdima \leftmargin\makebox[\@tempdima][l]{#1}%
}
\newenvironment{fulllineitems}{
\begin{list}{}{\labelwidth \leftmargin \labelsep 0pt
\rightmargin 0pt \topsep -\parskip \partopsep \parskip
\itemsep -\parsep
\let\makelabel=\py@itemnewline}
}{\end{list}}
% \optional is used for ``[, arg]``, i.e. desc_optional nodes.
\newcommand{\optional}[1]{%
{\textnormal{\Large[}}{#1}\hspace{0.5mm}{\textnormal{\Large]}}}
\newlength{\py@argswidth}
\newcommand{\py@sigparams}[2]{%
\parbox[t]{\py@argswidth}{#1\code{)}#2}}
\newcommand{\pysigline}[1]{\item[#1]\nopagebreak}
\newcommand{\pysiglinewithargsret}[3]{%
\settowidth{\py@argswidth}{#1\code{(}}%
\addtolength{\py@argswidth}{-2\py@argswidth}%
\addtolength{\py@argswidth}{\linewidth}%
\item[#1\code{(}\py@sigparams{#2}{#3}]}
% Production lists
%
\newenvironment{productionlist}{
% \def\optional##1{{\Large[}##1{\Large]}}
\def\production##1##2{\\\code{##1}&::=&\code{##2}}
\def\productioncont##1{\\& &\code{##1}}
\parindent=2em
\indent
\begin{tabular}{lcl}
}{%
\end{tabular}
}
% Notices / Admonitions
%
\newlength{\py@noticelength}
\newcommand{\py@heavybox}{
\setlength{\fboxrule}{1pt}
\setlength{\fboxsep}{6pt}
\setlength{\py@noticelength}{\linewidth}
\addtolength{\py@noticelength}{-2\fboxsep}
\addtolength{\py@noticelength}{-2\fboxrule}
%\setlength{\shadowsize}{3pt}
\noindent\Sbox
\minipage{\py@noticelength}
}
\newcommand{\py@endheavybox}{
\endminipage
\endSbox
\fbox{\TheSbox}
}
\newcommand{\py@lightbox}{{%
\setlength\parskip{0pt}\par
\noindent\rule[0ex]{\linewidth}{0.5pt}%
\par\noindent\vspace{-0.5ex}%
}}
\newcommand{\py@endlightbox}{{%
\setlength{\parskip}{0pt}%
\par\noindent\rule[0.5ex]{\linewidth}{0.5pt}%
\par\vspace{-0.5ex}%
}}
% Some are quite plain:
\newcommand{\py@noticestart@note}{\py@lightbox}
\newcommand{\py@noticeend@note}{\py@endlightbox}
\newcommand{\py@noticestart@hint}{\py@lightbox}
\newcommand{\py@noticeend@hint}{\py@endlightbox}
\newcommand{\py@noticestart@important}{\py@lightbox}
\newcommand{\py@noticeend@important}{\py@endlightbox}
\newcommand{\py@noticestart@tip}{\py@lightbox}
\newcommand{\py@noticeend@tip}{\py@endlightbox}
% Others gets more visible distinction:
\newcommand{\py@noticestart@warning}{\py@heavybox}
\newcommand{\py@noticeend@warning}{\py@endheavybox}
\newcommand{\py@noticestart@caution}{\py@heavybox}
\newcommand{\py@noticeend@caution}{\py@endheavybox}
\newcommand{\py@noticestart@attention}{\py@heavybox}
\newcommand{\py@noticeend@attention}{\py@endheavybox}
\newcommand{\py@noticestart@danger}{\py@heavybox}
\newcommand{\py@noticeend@danger}{\py@endheavybox}
\newcommand{\py@noticestart@error}{\py@heavybox}
\newcommand{\py@noticeend@error}{\py@endheavybox}
\newenvironment{notice}[2]{
\def\py@noticetype{#1}
\csname py@noticestart@#1\endcsname
\strong{#2}
}{\csname py@noticeend@\py@noticetype\endcsname}
% Allow the release number to be specified independently of the
% \date{}. This allows the date to reflect the document's date and
% release to specify the release that is documented.
%
\newcommand{\py@release}{}
\newcommand{\version}{}
\newcommand{\shortversion}{}
\newcommand{\releaseinfo}{}
\newcommand{\releasename}{GNAT}
\newcommand{\release}[1]{%
\renewcommand{\py@release}{\releasename\space\version}%
\renewcommand{\version}{#1}}
\newcommand{\setshortversion}[1]{%
\renewcommand{\shortversion}{#1}}
\newcommand{\setreleaseinfo}[1]{%
\renewcommand{\releaseinfo}{#1}}
% Allow specification of the author's address separately from the
% author's name. This can be used to format them differently, which
% is a good thing.
%
\newcommand{\py@authoraddress}{}
\newcommand{\authoraddress}[1]{\renewcommand{\py@authoraddress}{#1}}
% This sets up the fancy chapter headings that make the documents look
% at least a little better than the usual LaTeX output.
%
\@ifundefined{ChTitleVar}{}{
\ChNameVar{\raggedleft\normalsize\py@HeaderFamily}
\ChNumVar{\raggedleft \bfseries\Large\py@HeaderFamily}
\ChTitleVar{\raggedleft \textrm{\Huge\py@HeaderFamily}}
% This creates chapter heads without the leading \vspace*{}:
\def\@makechapterhead#1{%
{\parindent \z@ \raggedright \normalfont
\ifnum \c@secnumdepth >\m@ne
\DOCH
\fi
\interlinepenalty\@M
\DOTI{#1}
}
}
}
% Redefine description environment so that it is usable inside fulllineitems.
%
\renewcommand{\description}{%
\list{}{\labelwidth\z@%
\itemindent-\leftmargin%
\labelsep5pt%
\let\makelabel=\descriptionlabel}}
% Definition lists; requested by AMK for HOWTO documents. Probably useful
% elsewhere as well, so keep in in the general style support.
%
\newenvironment{definitions}{%
\begin{description}%
\def\term##1{\item[##1]\mbox{}\\*[0mm]}
}{%
\end{description}%
}
% Tell TeX about pathological hyphenation cases:
\hyphenation{Base-HTTP-Re-quest-Hand-ler}
% The following is stuff copied from docutils' latex writer.
%
\newcommand{\optionlistlabel}[1]{\bf #1 \hfill}
\newenvironment{optionlist}[1]
{\begin{list}{}
{\setlength{\labelwidth}{#1}
\setlength{\rightmargin}{1cm}
\setlength{\leftmargin}{\rightmargin}
\addtolength{\leftmargin}{\labelwidth}
\addtolength{\leftmargin}{\labelsep}
\renewcommand{\makelabel}{\optionlistlabel}}
}{\end{list}}
\newlength{\lineblockindentation}
\setlength{\lineblockindentation}{2.5em}
\newenvironment{lineblock}[1]
{\begin{list}{}
{\setlength{\partopsep}{\parskip}
\addtolength{\partopsep}{\baselineskip}
\topsep0pt\itemsep0.15\baselineskip\parsep0pt
\leftmargin#1}
\raggedright}
{\end{list}}
% Redefine includgraphics for avoiding images larger than the screen size
% If the size is not specified.
\let\py@Oldincludegraphics\includegraphics
\newbox\image@box%
\newdimen\image@width%
\renewcommand\includegraphics[2][\@empty]{%
\ifx#1\@empty%
\setbox\image@box=\hbox{\py@Oldincludegraphics{#2}}%
\image@width\wd\image@box%
\ifdim \image@width>\linewidth%
\setbox\image@box=\hbox{\py@Oldincludegraphics[width=\linewidth]{#2}}%
\box\image@box%
\else%
\py@Oldincludegraphics{#2}%
\fi%
\else%
\py@Oldincludegraphics[#1]{#2}%
\fi%
}
% to make pdf with correct encoded bookmarks in Japanese
% this should precede the hyperref package
\ifx\kanjiskip\undefined\else
\usepackage{atbegshi}
\ifx\ucs\undefined
\ifnum 42146=\euc"A4A2
\AtBeginShipoutFirst{\special{pdf:tounicode EUC-UCS2}}
\else
\AtBeginShipoutFirst{\special{pdf:tounicode 90ms-RKSJ-UCS2}}
\fi
\else
\AtBeginShipoutFirst{\special{pdf:tounicode UTF8-UCS2}}
\fi
\fi
% Include hyperref last.
\RequirePackage[colorlinks,breaklinks,destlabel,
linkcolor=InnerLinkColor,filecolor=OuterLinkColor,
menucolor=OuterLinkColor,urlcolor=OuterLinkColor,
citecolor=InnerLinkColor]{hyperref}
% Fix anchor placement for figures with captions.
% (Note: we don't use a package option here; instead, we give an explicit
% \capstart for figures that actually have a caption.)
\RequirePackage{hypcap}
% From docutils.writers.latex2e
\providecommand{\DUspan}[2]{%
{% group ("span") to limit the scope of styling commands
\@for\node@class@name:=#1\do{%
\ifcsname docutilsrole\node@class@name\endcsname%
\csname docutilsrole\node@class@name\endcsname%
\fi%
}%
{#2}% node content
}% close "span"
}
\providecommand*{\DUprovidelength}[2]{
\ifthenelse{\isundefined{#1}}{\newlength{#1}\setlength{#1}{#2}}{}
}
\DUprovidelength{\DUlineblockindent}{2.5em}
\ifthenelse{\isundefined{\DUlineblock}}{
\newenvironment{DUlineblock}[1]{%
\list{}{\setlength{\partopsep}{\parskip}
\addtolength{\partopsep}{\baselineskip}
\setlength{\topsep}{0pt}
\setlength{\itemsep}{0.15\baselineskip}
\setlength{\parsep}{0pt}
\setlength{\leftmargin}{#1}}
\raggedright
}
{\endlist}
}{}
% From footmisc.sty: allows footnotes in titles
\let\FN@sf@@footnote\footnote
\def\footnote{\ifx\protect\@typeset@protect
\expandafter\FN@sf@@footnote
\else
\expandafter\FN@sf@gobble@opt
\fi
}
\edef\FN@sf@gobble@opt{\noexpand\protect
\expandafter\noexpand\csname FN@sf@gobble@opt \endcsname}
\expandafter\def\csname FN@sf@gobble@opt \endcsname{%
\@ifnextchar[%]
\FN@sf@gobble@twobracket
\@gobble
}
\def\FN@sf@gobble@twobracket[#1]#2{}
% adjust the margins for footer,
% this works with the jsclasses only (Japanese standard document classes)
\ifx\@jsc@uplatextrue\undefined\else
\hypersetup{setpagesize=false}
\setlength\footskip{2\baselineskip}
\addtolength{\textheight}{-2\baselineskip}
\fi
% fix the double index and bibliography on the table of contents
% in jsclasses (Japanese standard document classes)
\ifx\@jsc@uplatextrue\undefined\else
\renewcommand{\theindex}{
\cleardoublepage
\phantomsection
\py@OldTheindex
}
\renewcommand{\thebibliography}[1]{
\cleardoublepage
\phantomsection
\py@OldThebibliography{1}
}
\fi
% do not use \@chappos in Appendix in pTeX
\ifx\kanjiskip\undefined\else
\renewcommand{\appendix}{\par
\setcounter{chapter}{0}
\setcounter{section}{0}
\gdef\@chapapp{\appendixname}
\gdef\@chappos{}
\gdef\thechapter{\@Alph\c@chapter}
}
\fi

29917
gcc/ada/gnat_rm.texi
View File

File diff suppressed because it is too large Load Diff

52356
gcc/ada/gnat_ugn.texi
View File

File diff suppressed because it is too large Load Diff