gnat_rm.texi, [...]: Now automatically generated from sphinx in the doc directory.
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:
parent
07a64c021a
commit
cb2d884d7d
|
@ -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)
|
||||
|
|
@ -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
|
|
@ -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.
|
|
@ -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.
|
||||
|
File diff suppressed because it is too large
Load Diff
|
@ -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.
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
File diff suppressed because it is too large
Load Diff
|
@ -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.
|
||||
|
File diff suppressed because it is too large
Load Diff
|
@ -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.
|
||||
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -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>
|
||||
|
||||
|
|
@ -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.
|
||||
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -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).
|
||||
|
|
@ -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.
|
||||
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -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.
|
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
|
@ -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.
|
|
@ -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)
|
|
@ -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())
|
|
@ -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.
|
|
@ -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'}'])
|
|
@ -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
29917
gcc/ada/gnat_rm.texi
File diff suppressed because it is too large
Load Diff
52356
gcc/ada/gnat_ugn.texi
52356
gcc/ada/gnat_ugn.texi
File diff suppressed because it is too large
Load Diff
Loading…
Reference in New Issue