diff options
| author | charlet <charlet@138bc75d-0d04-0410-961f-82ee72b054a4> | 2015-02-20 09:11:44 +0000 |
|---|---|---|
| committer | charlet <charlet@138bc75d-0d04-0410-961f-82ee72b054a4> | 2015-02-20 09:11:44 +0000 |
| commit | bf5dffd3a47fe12ace71fe48e87cfb1b9ada1344 (patch) | |
| tree | 8595086bf6f09398ca79a336e320d885e52b2c66 /gcc/ada/doc | |
| parent | e43fc5c526012253ec5c1c243552b514ab4ff7c9 (diff) | |
| download | gcc-bf5dffd3a47fe12ace71fe48e87cfb1b9ada1344.tar.gz | |
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
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@220837 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'gcc/ada/doc')
38 files changed, 57066 insertions, 0 deletions
diff --git a/gcc/ada/doc/Makefile b/gcc/ada/doc/Makefile new file mode 100644 index 00000000000..9a8070ce612 --- /dev/null +++ b/gcc/ada/doc/Makefile @@ -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) + diff --git a/gcc/ada/doc/gnat_rm.rst b/gcc/ada/doc/gnat_rm.rst new file mode 100644 index 00000000000..a9ea40d679e --- /dev/null +++ b/gcc/ada/doc/gnat_rm.rst @@ -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 diff --git a/gcc/ada/doc/gnat_rm/about_this_guide.rst b/gcc/ada/doc/gnat_rm/about_this_guide.rst new file mode 100644 index 00000000000..ad3ca5f460a --- /dev/null +++ b/gcc/ada/doc/gnat_rm/about_this_guide.rst @@ -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. diff --git a/gcc/ada/doc/gnat_rm/compatibility_and_porting_guide.rst b/gcc/ada/doc/gnat_rm/compatibility_and_porting_guide.rst new file mode 100644 index 00000000000..153d585b547 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/compatibility_and_porting_guide.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_rm/implementation_advice.rst b/gcc/ada/doc/gnat_rm/implementation_advice.rst new file mode 100644 index 00000000000..2ccb4e40172 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/implementation_advice.rst @@ -0,0 +1,1395 @@ +.. _Implementation_Advice: + +********************* +Implementation Advice +********************* + +The main text of the Ada Reference Manual describes the required +behavior of all Ada compilers, and the GNAT compiler conforms to +these requirements. + +In addition, there are sections throughout the Ada Reference Manual headed +by the phrase 'Implementation advice'. These sections are not normative, +i.e., they do not specify requirements that all compilers must +follow. Rather they provide advice on generally desirable behavior. +They are not requirements, because they describe behavior that cannot +be provided on all systems, or may be undesirable on some systems. + +As far as practical, GNAT follows the implementation advice in +the Ada Reference Manual. Each such RM section corresponds to a section +in this chapter whose title specifies the +RM section number and paragraph number and the subject of +the advice. The contents of each section consists of the RM text within +quotation marks, +followed by the GNAT interpretation of the advice. Most often, this simply says +'followed', which means that GNAT follows the advice. However, in a +number of cases, GNAT deliberately deviates from this advice, in which +case the text describes what GNAT does and why. + +.. index:: Error detection + +RM 1.1.3(20): Error Detection +============================= + + "If an implementation detects the use of an unsupported Specialized Needs + Annex feature at run time, it should raise `Program_Error` if + feasible." + +Not relevant. All specialized needs annex features are either supported, +or diagnosed at compile time. + +.. index:: Child Units + +RM 1.1.3(31): Child Units +========================= + + + "If an implementation wishes to provide implementation-defined + extensions to the functionality of a language-defined library unit, it + should normally do so by adding children to the library unit." + +Followed. + +.. index:: Bounded errors + +RM 1.1.5(12): Bounded Errors +============================ + + "If an implementation detects a bounded error or erroneous + execution, it should raise `Program_Error`." + +Followed in all cases in which the implementation detects a bounded +error or erroneous execution. Not all such situations are detected at +runtime. + +.. index:: Pragmas + +.. _RM_2_8_16_Pragmas: + +RM 2.8(16): Pragmas +=================== + + "Normally, implementation-defined pragmas should have no semantic effect + for error-free programs; that is, if the implementation-defined pragmas + are removed from a working program, the program should still be legal, + and should still have the same semantics." + +The following implementation defined pragmas are exceptions to this +rule: + ++--------------------+-------------------+ +| Pragma | Explanation | ++====================+===================+ +| *Abort_Defer* | Affects semantics | ++--------------------+-------------------+ +|*Ada_83* | Affects legality | ++--------------------+-------------------+ +|*Assert* | Affects semantics | ++--------------------+-------------------+ +|*CPP_Class* | Affects semantics | ++--------------------+-------------------+ +|*CPP_Constructor* | Affects semantics | ++--------------------+-------------------+ +|*Debug* | Affects semantics | ++--------------------+-------------------+ +|*Interface_Name* | Affects semantics | ++--------------------+-------------------+ +|*Machine_Attribute* | Affects semantics | ++--------------------+-------------------+ +|*Unimplemented_Unit*| Affects legality | ++--------------------+-------------------+ +|*Unchecked_Union* | Affects semantics | ++--------------------+-------------------+ + +In each of the above cases, it is essential to the purpose of the pragma +that this advice not be followed. For details see +:ref:`Implementation_Defined_Pragmas`. + +RM 2.8(17-19): Pragmas +====================== + + "Normally, an implementation should not define pragmas that can + make an illegal program legal, except as follows: + + * A pragma used to complete a declaration, such as a pragma `Import`; + + * A pragma used to configure the environment by adding, removing, or + replacing `library_items`." + +See :ref:`RM_2_8_16_Pragmas`. + +.. index:: Character Sets + +.. index:: Alternative Character Sets + +RM 3.5.2(5): Alternative Character Sets +======================================= + + "If an implementation supports a mode with alternative interpretations + for `Character` and `Wide_Character`, the set of graphic + characters of `Character` should nevertheless remain a proper + subset of the set of graphic characters of `Wide_Character`. Any + character set 'localizations' should be reflected in the results of + the subprograms defined in the language-defined package + `Characters.Handling` (see A.3) available in such a mode. In a mode with + an alternative interpretation of `Character`, the implementation should + also support a corresponding change in what is a legal + `identifier_letter`." + +Not all wide character modes follow this advice, in particular the JIS +and IEC modes reflect standard usage in Japan, and in these encoding, +the upper half of the Latin-1 set is not part of the wide-character +subset, since the most significant bit is used for wide character +encoding. However, this only applies to the external forms. Internally +there is no such restriction. + +.. index:: Integer types + +RM 3.5.4(28): Integer Types +=========================== + + "An implementation should support `Long_Integer` in addition to + `Integer` if the target machine supports 32-bit (or longer) + arithmetic. No other named integer subtypes are recommended for package + `Standard`. Instead, appropriate named integer subtypes should be + provided in the library package `Interfaces` (see B.2)." + +`Long_Integer` is supported. Other standard integer types are supported +so this advice is not fully followed. These types +are supported for convenient interface to C, and so that all hardware +types of the machine are easily available. + +RM 3.5.4(29): Integer Types +=========================== + + "An implementation for a two's complement machine should support + modular types with a binary modulus up to ``System.Max_Int*2+2``. An + implementation should support a non-binary modules up to `Integer'Last`." + +Followed. + +.. index:: Enumeration values + +RM 3.5.5(8): Enumeration Values +=============================== + + "For the evaluation of a call on ``S'Pos`` for an enumeration + subtype, if the value of the operand does not correspond to the internal + code for any enumeration literal of its type (perhaps due to an + un-initialized variable), then the implementation should raise + `Program_Error`. This is particularly important for enumeration + types with noncontiguous internal codes specified by an + enumeration_representation_clause." + +Followed. + +.. index:: Float types + +RM 3.5.7(17): Float Types +========================= + + "An implementation should support `Long_Float` in addition to + `Float` if the target machine supports 11 or more digits of + precision. No other named floating point subtypes are recommended for + package `Standard`. Instead, appropriate named floating point subtypes + should be provided in the library package `Interfaces` (see B.2)." + +`Short_Float` and `Long_Long_Float` are also provided. The +former provides improved compatibility with other implementations +supporting this type. The latter corresponds to the highest precision +floating-point type supported by the hardware. On most machines, this +will be the same as `Long_Float`, but on some machines, it will +correspond to the IEEE extended form. The notable case is all ia32 +(x86) implementations, where `Long_Long_Float` corresponds to +the 80-bit extended precision format supported in hardware on this +processor. Note that the 128-bit format on SPARC is not supported, +since this is a software rather than a hardware format. + +.. index:: Multidimensional arrays + +.. index:: Arrays, multidimensional + +RM 3.6.2(11): Multidimensional Arrays +===================================== + + "An implementation should normally represent multidimensional arrays in + row-major order, consistent with the notation used for multidimensional + array aggregates (see 4.3.3). However, if a pragma `Convention` + (`Fortran`, ...) applies to a multidimensional array type, then + column-major order should be used instead (see B.5, `Interfacing with Fortran`)." + +Followed. + +.. index:: Duration'Small + +RM 9.6(30-31): Duration'Small +============================= + + "Whenever possible in an implementation, the value of `Duration'Small` + should be no greater than 100 microseconds." + +Followed. (`Duration'Small` = 10**(-9)). + + "The time base for `delay_relative_statements` should be monotonic; + it need not be the same time base as used for `Calendar.Clock`." + +Followed. + +RM 10.2.1(12): Consistent Representation +======================================== + + "In an implementation, a type declared in a pre-elaborated package should + have the same representation in every elaboration of a given version of + the package, whether the elaborations occur in distinct executions of + the same program, or in executions of distinct programs or partitions + that include the given version." + +Followed, except in the case of tagged types. Tagged types involve +implicit pointers to a local copy of a dispatch table, and these pointers +have representations which thus depend on a particular elaboration of the +package. It is not easy to see how it would be possible to follow this +advice without severely impacting efficiency of execution. + +.. index:: Exception information + +RM 11.4.1(19): Exception Information +==================================== + + "`Exception_Message` by default and `Exception_Information` + should produce information useful for + debugging. `Exception_Message` should be short, about one + line. `Exception_Information` can be long. `Exception_Message` + should not include the + `Exception_Name`. `Exception_Information` should include both + the `Exception_Name` and the `Exception_Message`." + +Followed. For each exception that doesn't have a specified +`Exception_Message`, the compiler generates one containing the location +of the raise statement. This location has the form 'file_name:line', where +file_name is the short file name (without path information) and line is the line +number in the file. Note that in the case of the Zero Cost Exception +mechanism, these messages become redundant with the Exception_Information that +contains a full backtrace of the calling sequence, so they are disabled. +To disable explicitly the generation of the source location message, use the +Pragma `Discard_Names`. + +.. index:: Suppression of checks + +.. index:: Checks, suppression of + +RM 11.5(28): Suppression of Checks +================================== + + "The implementation should minimize the code executed for checks that + have been suppressed." + +Followed. + +.. index:: Representation clauses + +RM 13.1 (21-24): Representation Clauses +======================================= + + "The recommended level of support for all representation items is + qualified as follows: + + An implementation need not support representation items containing + non-static expressions, except that an implementation should support a + representation item for a given entity if each non-static expression in + the representation item is a name that statically denotes a constant + declared before the entity." + +Followed. In fact, GNAT goes beyond the recommended level of support +by allowing nonstatic expressions in some representation clauses even +without the need to declare constants initialized with the values of +such expressions. +For example: + +.. code-block:: ada + + X : Integer; + Y : Float; + for Y'Address use X'Address;>> + + + "An implementation need not support a specification for the `Size` + for a given composite subtype, nor the size or storage place for an + object (including a component) of a given composite subtype, unless the + constraints on the subtype and its composite subcomponents (if any) are + all static constraints." + +Followed. Size Clauses are not permitted on non-static components, as +described above. + + + "An aliased component, or a component whose type is by-reference, should + always be allocated at an addressable location." + +Followed. + +.. index:: Packed types + +RM 13.2(6-8): Packed Types +========================== + + "If a type is packed, then the implementation should try to minimize + storage allocated to objects of the type, possibly at the expense of + speed of accessing components, subject to reasonable complexity in + addressing calculations. + + The recommended level of support pragma `Pack` is: + + For a packed record type, the components should be packed as tightly as + possible subject to the Sizes of the component subtypes, and subject to + any `record_representation_clause` that applies to the type; the + implementation may, but need not, reorder components or cross aligned + word boundaries to improve the packing. A component whose `Size` is + greater than the word size may be allocated an integral number of words." + +Followed. Tight packing of arrays is supported for all component sizes +up to 64-bits. If the array component size is 1 (that is to say, if +the component is a boolean type or an enumeration type with two values) +then values of the type are implicitly initialized to zero. This +happens both for objects of the packed type, and for objects that have a +subcomponent of the packed type. + + + "An implementation should support Address clauses for imported + subprograms." + +Followed. + +.. index:: Address clauses + +RM 13.3(14-19): Address Clauses +=============================== + + "For an array `X`, ``X'Address`` should point at the first + component of the array, and not at the array bounds." + +Followed. + + "The recommended level of support for the `Address` attribute is: + + ``X'Address`` should produce a useful result if `X` is an + object that is aliased or of a by-reference type, or is an entity whose + `Address` has been specified." + +Followed. A valid address will be produced even if none of those +conditions have been met. If necessary, the object is forced into +memory to ensure the address is valid. + + "An implementation should support `Address` clauses for imported + subprograms." + +Followed. + + "Objects (including subcomponents) that are aliased or of a by-reference + type should be allocated on storage element boundaries." + +Followed. + + "If the `Address` of an object is specified, or it is imported or exported, + then the implementation should not perform optimizations based on + assumptions of no aliases." + +Followed. + +.. index:: Alignment clauses + +RM 13.3(29-35): Alignment Clauses +================================= + + "The recommended level of support for the `Alignment` attribute for + subtypes is: + + An implementation should support specified Alignments that are factors + and multiples of the number of storage elements per word, subject to the + following:" + +Followed. + + "An implementation need not support specified Alignments for + combinations of Sizes and Alignments that cannot be easily + loaded and stored by available machine instructions." + +Followed. + + "An implementation need not support specified Alignments that are + greater than the maximum `Alignment` the implementation ever returns by + default." + +Followed. + + "The recommended level of support for the `Alignment` attribute for + objects is: + + Same as above, for subtypes, but in addition:" + +Followed. + + "For stand-alone library-level objects of statically constrained + subtypes, the implementation should support all alignments + supported by the target linker. For example, page alignment is likely to + be supported for such objects, but not for subtypes." + +Followed. + +.. index:: Size clauses + +RM 13.3(42-43): Size Clauses +============================ + + "The recommended level of support for the `Size` attribute of + objects is: + + A `Size` clause should be supported for an object if the specified + `Size` is at least as large as its subtype's `Size`, and + corresponds to a size in storage elements that is a multiple of the + object's `Alignment` (if the `Alignment` is nonzero)." + +Followed. + +RM 13.3(50-56): Size Clauses +============================ + + "If the `Size` of a subtype is specified, and allows for efficient + independent addressability (see 9.10) on the target architecture, then + the `Size` of the following objects of the subtype should equal the + `Size` of the subtype: + + Aliased objects (including components)." + +Followed. + + "`Size` clause on a composite subtype should not affect the + internal layout of components." + +Followed. But note that this can be overridden by use of the implementation +pragma Implicit_Packing in the case of packed arrays. + + "The recommended level of support for the `Size` attribute of subtypes is: + + The `Size` (if not specified) of a static discrete or fixed point + subtype should be the number of bits needed to represent each value + belonging to the subtype using an unbiased representation, leaving space + for a sign bit only if the subtype contains negative values. If such a + subtype is a first subtype, then an implementation should support a + specified `Size` for it that reflects this representation." + +Followed. + + "For a subtype implemented with levels of indirection, the `Size` + should include the size of the pointers, but not the size of what they + point at." + +Followed. + +.. index:: Component_Size clauses + +RM 13.3(71-73): Component Size Clauses +====================================== + + "The recommended level of support for the `Component_Size` + attribute is: + + An implementation need not support specified `Component_Sizes` that are + less than the `Size` of the component subtype." + +Followed. + + "An implementation should support specified Component_Sizes that + are factors and multiples of the word size. For such + Component_Sizes, the array should contain no gaps between + components. For other Component_Sizes (if supported), the array + should contain no gaps between components when packing is also + specified; the implementation should forbid this combination in cases + where it cannot support a no-gaps representation." + +Followed. + +.. index:: Enumeration representation clauses + +.. index:: Representation clauses, enumeration + +RM 13.4(9-10): Enumeration Representation Clauses +================================================= + + "The recommended level of support for enumeration representation clauses + is: + + An implementation need not support enumeration representation clauses + for boolean types, but should at minimum support the internal codes in + the range `System.Min_Int .. System.Max_Int`." + +Followed. + +.. index:: Record representation clauses + +.. index:: Representation clauses, records + +RM 13.5.1(17-22): Record Representation Clauses +=============================================== + + "The recommended level of support for + `record_representation_clauses` is: + + An implementation should support storage places that can be extracted + with a load, mask, shift sequence of machine code, and set with a load, + shift, mask, store sequence, given the available machine instructions + and run-time model." + +Followed. + + "A storage place should be supported if its size is equal to the + `Size` of the component subtype, and it starts and ends on a + boundary that obeys the `Alignment` of the component subtype." + +Followed. + + "If the default bit ordering applies to the declaration of a given type, + then for a component whose subtype's `Size` is less than the word + size, any storage place that does not cross an aligned word boundary + should be supported." + +Followed. + + "An implementation may reserve a storage place for the tag field of a + tagged type, and disallow other components from overlapping that place." + +Followed. The storage place for the tag field is the beginning of the tagged +record, and its size is Address'Size. GNAT will reject an explicit component +clause for the tag field. + + "An implementation need not support a `component_clause` for a + component of an extension part if the storage place is not after the + storage places of all components of the parent type, whether or not + those storage places had been specified." + +Followed. The above advice on record representation clauses is followed, +and all mentioned features are implemented. + +.. index:: Storage place attributes + +RM 13.5.2(5): Storage Place Attributes +====================================== + + "If a component is represented using some form of pointer (such as an + offset) to the actual data of the component, and this data is contiguous + with the rest of the object, then the storage place attributes should + reflect the place of the actual data, not the pointer. If a component is + allocated discontinuously from the rest of the object, then a warning + should be generated upon reference to one of its storage place + attributes." + +Followed. There are no such components in GNAT. + +.. index:: Bit ordering + +RM 13.5.3(7-8): Bit Ordering +============================ + + "The recommended level of support for the non-default bit ordering is: + + If `Word_Size` = `Storage_Unit`, then the implementation + should support the non-default bit ordering in addition to the default + bit ordering." + +Followed. Word size does not equal storage size in this implementation. +Thus non-default bit ordering is not supported. + +.. index:: Address, as private type + +RM 13.7(37): Address as Private +=============================== + + "`Address` should be of a private type." + +Followed. + +.. index:: Operations, on `Address` + +.. index:: Address, operations of + +RM 13.7.1(16): Address Operations +================================= + + "Operations in `System` and its children should reflect the target + environment semantics as closely as is reasonable. For example, on most + machines, it makes sense for address arithmetic to 'wrap around'. + Operations that do not make sense should raise `Program_Error`." + +Followed. Address arithmetic is modular arithmetic that wraps around. No +operation raises `Program_Error`, since all operations make sense. + +.. index:: Unchecked conversion + +RM 13.9(14-17): Unchecked Conversion +==================================== + + "The `Size` of an array object should not include its bounds; hence, + the bounds should not be part of the converted data." + +Followed. + + "The implementation should not generate unnecessary run-time checks to + ensure that the representation of `S` is a representation of the + target type. It should take advantage of the permission to return by + reference when possible. Restrictions on unchecked conversions should be + avoided unless required by the target environment." + +Followed. There are no restrictions on unchecked conversion. A warning is +generated if the source and target types do not have the same size since +the semantics in this case may be target dependent. + + "The recommended level of support for unchecked conversions is: + + Unchecked conversions should be supported and should be reversible in + the cases where this clause defines the result. To enable meaningful use + of unchecked conversion, a contiguous representation should be used for + elementary subtypes, for statically constrained array subtypes whose + component subtype is one of the subtypes described in this paragraph, + and for record subtypes without discriminants whose component subtypes + are described in this paragraph." + +Followed. + +.. index:: Heap usage, implicit + +RM 13.11(23-25): Implicit Heap Usage +==================================== + + "An implementation should document any cases in which it dynamically + allocates heap storage for a purpose other than the evaluation of an + allocator." + +Followed, the only other points at which heap storage is dynamically +allocated are as follows: + +* + At initial elaboration time, to allocate dynamically sized global + objects. + +* + To allocate space for a task when a task is created. + +* + To extend the secondary stack dynamically when needed. The secondary + stack is used for returning variable length results. + +.. + + "A default (implementation-provided) storage pool for an + access-to-constant type should not have overhead to support deallocation of + individual objects." + +Followed. + + "A storage pool for an anonymous access type should be created at the + point of an allocator for the type, and be reclaimed when the designated + object becomes inaccessible." + +Followed. + +.. index:: Unchecked deallocation + +RM 13.11.2(17): Unchecked Deallocation +====================================== + + "For a standard storage pool, `Free` should actually reclaim the + storage." + +Followed. + +.. index:: Stream oriented attributes + +RM 13.13.2(17): Stream Oriented Attributes +========================================== + + "If a stream element is the same size as a storage element, then the + normal in-memory representation should be used by `Read` and + `Write` for scalar objects. Otherwise, `Read` and `Write` + should use the smallest number of stream elements needed to represent + all values in the base range of the scalar type." + +Followed. By default, GNAT uses the interpretation suggested by AI-195, +which specifies using the size of the first subtype. +However, such an implementation is based on direct binary +representations and is therefore target- and endianness-dependent. +To address this issue, GNAT also supplies an alternate implementation +of the stream attributes `Read` and `Write`, +which uses the target-independent XDR standard representation +for scalar types. + +.. index:: XDR representation + +.. index:: Read attribute + +.. index:: Write attribute + +.. index:: Stream oriented attributes + +The XDR implementation is provided as an alternative body of the +`System.Stream_Attributes` package, in the file +:file:`s-stratt-xdr.adb` in the GNAT library. +There is no :file:`s-stratt-xdr.ads` file. +In order to install the XDR implementation, do the following: + +* Replace the default implementation of the + `System.Stream_Attributes` package with the XDR implementation. + For example on a Unix platform issue the commands: + + .. code-block:: sh + + $ mv s-stratt.adb s-stratt-default.adb + $ mv s-stratt-xdr.adb s-stratt.adb + + +* + Rebuild the GNAT run-time library as documented in + the `GNAT and Libraries` section of the :title:`GNAT User's Guide`. + +RM A.1(52): Names of Predefined Numeric Types +============================================= + + "If an implementation provides additional named predefined integer types, + then the names should end with ``Integer`` as in + ``Long_Integer``. If an implementation provides additional named + predefined floating point types, then the names should end with + ``Float`` as in ``Long_Float``." + +Followed. + +.. index:: Ada.Characters.Handling + +RM A.3.2(49): `Ada.Characters.Handling` +======================================= + + "If an implementation provides a localized definition of `Character` + or `Wide_Character`, then the effects of the subprograms in + `Characters.Handling` should reflect the localizations. + See also 3.5.2." + +Followed. GNAT provides no such localized definitions. + +.. index:: Bounded-length strings + +RM A.4.4(106): Bounded-Length String Handling +============================================= + + "Bounded string objects should not be implemented by implicit pointers + and dynamic allocation." + +Followed. No implicit pointers or dynamic allocation are used. + +.. index:: Random number generation + +RM A.5.2(46-47): Random Number Generation +========================================= + + "Any storage associated with an object of type `Generator` should be + reclaimed on exit from the scope of the object." + +Followed. + + "If the generator period is sufficiently long in relation to the number + of distinct initiator values, then each possible value of + `Initiator` passed to `Reset` should initiate a sequence of + random numbers that does not, in a practical sense, overlap the sequence + initiated by any other value. If this is not possible, then the mapping + between initiator values and generator states should be a rapidly + varying function of the initiator value." + +Followed. The generator period is sufficiently long for the first +condition here to hold true. + +.. index:: Get_Immediate + +RM A.10.7(23): `Get_Immediate` +============================== + + "The `Get_Immediate` procedures should be implemented with + unbuffered input. For a device such as a keyboard, input should be + available if a key has already been typed, whereas for a disk + file, input should always be available except at end of file. For a file + associated with a keyboard-like device, any line-editing features of the + underlying operating system should be disabled during the execution of + `Get_Immediate`." + +Followed on all targets except VxWorks. For VxWorks, there is no way to +provide this functionality that does not result in the input buffer being +flushed before the `Get_Immediate` call. A special unit +`Interfaces.Vxworks.IO` is provided that contains routines to enable +this functionality. + +.. index:: Export + +RM B.1(39-41): Pragma `Export` +============================== + + "If an implementation supports pragma `Export` to a given language, + then it should also allow the main subprogram to be written in that + language. It should support some mechanism for invoking the elaboration + of the Ada library units included in the system, and for invoking the + finalization of the environment task. On typical systems, the + recommended mechanism is to provide two subprograms whose link names are + `adainit` and `adafinal`. `adainit` should contain the + elaboration code for library units. `adafinal` should contain the + finalization code. These subprograms should have no effect the second + and subsequent time they are called." + +Followed. + + "Automatic elaboration of pre-elaborated packages should be + provided when pragma `Export` is supported." + +Followed when the main program is in Ada. If the main program is in a +foreign language, then +`adainit` must be called to elaborate pre-elaborated +packages. + + "For each supported convention `L` other than `Intrinsic`, an + implementation should support `Import` and `Export` pragmas + for objects of `L`-compatible types and for subprograms, and pragma + `Convention` for `L`-eligible types and for subprograms, + presuming the other language has corresponding features. Pragma + `Convention` need not be supported for scalar types." + +Followed. + +.. index:: Package Interfaces + +.. index:: Interfaces + +RM B.2(12-13): Package `Interfaces` +=================================== + + "For each implementation-defined convention identifier, there should be a + child package of package Interfaces with the corresponding name. This + package should contain any declarations that would be useful for + interfacing to the language (implementation) represented by the + convention. Any declarations useful for interfacing to any language on + the given hardware architecture should be provided directly in + `Interfaces`." + +Followed. + + "An implementation supporting an interface to C, COBOL, or Fortran should + provide the corresponding package or packages described in the following + clauses." + +Followed. GNAT provides all the packages described in this section. + +.. index:: C, interfacing with + +RM B.3(63-71): Interfacing with C +================================= + + "An implementation should support the following interface correspondences + between Ada and C." + +Followed. + + "An Ada procedure corresponds to a void-returning C function." + +Followed. + + "An Ada function corresponds to a non-void C function." + +Followed. + + "An Ada `in` scalar parameter is passed as a scalar argument to a C + function." + +Followed. + + "An Ada `in` parameter of an access-to-object type with designated + type `T` is passed as a ``t*`` argument to a C function, + where ``t`` is the C type corresponding to the Ada type `T`." + +Followed. + + "An Ada access `T` parameter, or an Ada `out` or `in out` + parameter of an elementary type `T`, is passed as a ``t*`` + argument to a C function, where ``t`` is the C type corresponding to + the Ada type `T`. In the case of an elementary `out` or + `in out` parameter, a pointer to a temporary copy is used to + preserve by-copy semantics." + +Followed. + + "An Ada parameter of a record type `T`, of any mode, is passed as a + ``t*`` argument to a C function, where ``t`` is the C + structure corresponding to the Ada type `T`." + +Followed. This convention may be overridden by the use of the C_Pass_By_Copy +pragma, or Convention, or by explicitly specifying the mechanism for a given +call using an extended import or export pragma. + + "An Ada parameter of an array type with component type `T`, of any + mode, is passed as a ``t*`` argument to a C function, where + ``t`` is the C type corresponding to the Ada type `T`." + +Followed. + + "An Ada parameter of an access-to-subprogram type is passed as a pointer + to a C function whose prototype corresponds to the designated + subprogram's specification." + +Followed. + +.. index:: COBOL, interfacing with + +RM B.4(95-98): Interfacing with COBOL +===================================== + + "An Ada implementation should support the following interface + correspondences between Ada and COBOL." + +Followed. + + "An Ada access `T` parameter is passed as a ``BY REFERENCE`` data item of + the COBOL type corresponding to `T`." + +Followed. + + "An Ada in scalar parameter is passed as a ``BY CONTENT`` data item of + the corresponding COBOL type." + +Followed. + + "Any other Ada parameter is passed as a ``BY REFERENCE`` data item of the + COBOL type corresponding to the Ada parameter type; for scalars, a local + copy is used if necessary to ensure by-copy semantics." + +Followed. + +.. index:: Fortran, interfacing with + +RM B.5(22-26): Interfacing with Fortran +======================================= + + "An Ada implementation should support the following interface + correspondences between Ada and Fortran:" + +Followed. + + "An Ada procedure corresponds to a Fortran subroutine." + +Followed. + + "An Ada function corresponds to a Fortran function." + +Followed. + + "An Ada parameter of an elementary, array, or record type `T` is + passed as a `T` argument to a Fortran procedure, where `T` is + the Fortran type corresponding to the Ada type `T`, and where the + INTENT attribute of the corresponding dummy argument matches the Ada + formal parameter mode; the Fortran implementation's parameter passing + conventions are used. For elementary types, a local copy is used if + necessary to ensure by-copy semantics." + +Followed. + + "An Ada parameter of an access-to-subprogram type is passed as a + reference to a Fortran procedure whose interface corresponds to the + designated subprogram's specification." + +Followed. + +.. index:: Machine operations + +RM C.1(3-5): Access to Machine Operations +========================================= + + "The machine code or intrinsic support should allow access to all + operations normally available to assembly language programmers for the + target environment, including privileged instructions, if any." + +Followed. + + "The interfacing pragmas (see Annex B) should support interface to + assembler; the default assembler should be associated with the + convention identifier `Assembler`." + +Followed. + + "If an entity is exported to assembly language, then the implementation + should allocate it at an addressable location, and should ensure that it + is retained by the linking process, even if not otherwise referenced + from the Ada code. The implementation should assume that any call to a + machine code or assembler subprogram is allowed to read or update every + object that is specified as exported." + +Followed. + +RM C.1(10-16): Access to Machine Operations +=========================================== + + "The implementation should ensure that little or no overhead is + associated with calling intrinsic and machine-code subprograms." + +Followed for both intrinsics and machine-code subprograms. + + "It is recommended that intrinsic subprograms be provided for convenient + access to any machine operations that provide special capabilities or + efficiency and that are not otherwise available through the language + constructs." + +Followed. A full set of machine operation intrinsic subprograms is provided. + + "Atomic read-modify-write operations---e.g., test and set, compare and + swap, decrement and test, enqueue/dequeue." + +Followed on any target supporting such operations. + + "Standard numeric functions---e.g.:, sin, log." + +Followed on any target supporting such operations. + + "String manipulation operations---e.g.:, translate and test." + +Followed on any target supporting such operations. + + "Vector operations---e.g.:, compare vector against thresholds." + +Followed on any target supporting such operations. + + "Direct operations on I/O ports." + +Followed on any target supporting such operations. + +.. index:: Interrupt support + +RM C.3(28): Interrupt Support +============================= + + "If the `Ceiling_Locking` policy is not in effect, the + implementation should provide means for the application to specify which + interrupts are to be blocked during protected actions, if the underlying + system allows for a finer-grain control of interrupt blocking." + +Followed. The underlying system does not allow for finer-grain control +of interrupt blocking. + +.. index:: Protected procedure handlers + +RM C.3.1(20-21): Protected Procedure Handlers +============================================= + + "Whenever possible, the implementation should allow interrupt handlers to + be called directly by the hardware." + +Followed on any target where the underlying operating system permits +such direct calls. + + "Whenever practical, violations of any + implementation-defined restrictions should be detected before run time." + +Followed. Compile time warnings are given when possible. + +.. index:: Package `Interrupts` + +.. index:: Interrupts + +RM C.3.2(25): Package `Interrupts` +================================== + + "If implementation-defined forms of interrupt handler procedures are + supported, such as protected procedures with parameters, then for each + such form of a handler, a type analogous to `Parameterless_Handler` + should be specified in a child package of `Interrupts`, with the + same operations as in the predefined package Interrupts." + +Followed. + +.. index:: Pre-elaboration requirements + +RM C.4(14): Pre-elaboration Requirements +======================================== + + "It is recommended that pre-elaborated packages be implemented in such a + way that there should be little or no code executed at run time for the + elaboration of entities not already covered by the Implementation + Requirements." + +Followed. Executable code is generated in some cases, e.g., loops +to initialize large arrays. + +RM C.5(8): Pragma `Discard_Names` +================================= + + "If the pragma applies to an entity, then the implementation should + reduce the amount of storage used for storing names associated with that + entity." + +Followed. + +.. index:: Package Task_Attributes + +.. index:: Task_Attributes + +RM C.7.2(30): The Package Task_Attributes +========================================= + + "Some implementations are targeted to domains in which memory use at run + time must be completely deterministic. For such implementations, it is + recommended that the storage for task attributes will be pre-allocated + statically and not from the heap. This can be accomplished by either + placing restrictions on the number and the size of the task's + attributes, or by using the pre-allocated storage for the first `N` + attribute objects, and the heap for the others. In the latter case, + `N` should be documented." + +Not followed. This implementation is not targeted to such a domain. + +.. index:: Locking Policies + +RM D.3(17): Locking Policies +============================ + + "The implementation should use names that end with ``_Locking`` for + locking policies defined by the implementation." + +Followed. Two implementation-defined locking policies are defined, +whose names (`Inheritance_Locking` and +`Concurrent_Readers_Locking`) follow this suggestion. + +.. index:: Entry queuing policies + +RM D.4(16): Entry Queuing Policies +================================== + + "Names that end with ``_Queuing`` should be used + for all implementation-defined queuing policies." + +Followed. No such implementation-defined queuing policies exist. + +.. index:: Preemptive abort + +RM D.6(9-10): Preemptive Abort +============================== + + "Even though the `abort_statement` is included in the list of + potentially blocking operations (see 9.5.1), it is recommended that this + statement be implemented in a way that never requires the task executing + the `abort_statement` to block." + +Followed. + + "On a multi-processor, the delay associated with aborting a task on + another processor should be bounded; the implementation should use + periodic polling, if necessary, to achieve this." + +Followed. + +.. index:: Tasking restrictions + +RM D.7(21): Tasking Restrictions +================================ + + "When feasible, the implementation should take advantage of the specified + restrictions to produce a more efficient implementation." + +GNAT currently takes advantage of these restrictions by providing an optimized +run time when the Ravenscar profile and the GNAT restricted run time set +of restrictions are specified. See pragma `Profile (Ravenscar)` and +pragma `Profile (Restricted)` for more details. + +.. index:: Time, monotonic + +RM D.8(47-49): Monotonic Time +============================= + + "When appropriate, implementations should provide configuration + mechanisms to change the value of `Tick`." + +Such configuration mechanisms are not appropriate to this implementation +and are thus not supported. + + "It is recommended that `Calendar.Clock` and `Real_Time.Clock` + be implemented as transformations of the same time base." + +Followed. + + + "It is recommended that the best time base which exists in + the underlying system be available to the application through + `Clock`. `Best` may mean highest accuracy or largest range." + +Followed. + +.. index:: Partition communication subsystem + +.. index:: PCS + +RM E.5(28-29): Partition Communication Subsystem +================================================ + + "Whenever possible, the PCS on the called partition should allow for + multiple tasks to call the RPC-receiver with different messages and + should allow them to block until the corresponding subprogram body + returns." + +Followed by GLADE, a separately supplied PCS that can be used with +GNAT. + + "The `Write` operation on a stream of type `Params_Stream_Type` + should raise `Storage_Error` if it runs out of space trying to + write the `Item` into the stream." + +Followed by GLADE, a separately supplied PCS that can be used with +GNAT. + +.. index:: COBOL support + +RM F(7): COBOL Support +====================== + + "If COBOL (respectively, C) is widely supported in the target + environment, implementations supporting the Information Systems Annex + should provide the child package `Interfaces.COBOL` (respectively, + `Interfaces.C`) specified in Annex B and should support a + `convention_identifier` of COBOL (respectively, C) in the interfacing + pragmas (see Annex B), thus allowing Ada programs to interface with + programs written in that language." + +Followed. + +.. index:: Decimal radix support + +RM F.1(2): Decimal Radix Support +================================ + + "Packed decimal should be used as the internal representation for objects + of subtype `S` when `S`'Machine_Radix = 10." + +Not followed. GNAT ignores `S`'Machine_Radix and always uses binary +representations. + +.. index:: Numerics + +RM G: Numerics +============== + + "If Fortran (respectively, C) is widely supported in the target + environment, implementations supporting the Numerics Annex + should provide the child package `Interfaces.Fortran` (respectively, + `Interfaces.C`) specified in Annex B and should support a + `convention_identifier` of Fortran (respectively, C) in the interfacing + pragmas (see Annex B), thus allowing Ada programs to interface with + programs written in that language." + +Followed. + +.. index:: Complex types + +RM G.1.1(56-58): Complex Types +============================== + + "Because the usual mathematical meaning of multiplication of a complex + operand and a real operand is that of the scaling of both components of + the former by the latter, an implementation should not perform this + operation by first promoting the real operand to complex type and then + performing a full complex multiplication. In systems that, in the + future, support an Ada binding to IEC 559:1989, the latter technique + will not generate the required result when one of the components of the + complex operand is infinite. (Explicit multiplication of the infinite + component by the zero component obtained during promotion yields a NaN + that propagates into the final result.) Analogous advice applies in the + case of multiplication of a complex operand and a pure-imaginary + operand, and in the case of division of a complex operand by a real or + pure-imaginary operand." + +Not followed. + + "Similarly, because the usual mathematical meaning of addition of a + complex operand and a real operand is that the imaginary operand remains + unchanged, an implementation should not perform this operation by first + promoting the real operand to complex type and then performing a full + complex addition. In implementations in which the `Signed_Zeros` + attribute of the component type is `True` (and which therefore + conform to IEC 559:1989 in regard to the handling of the sign of zero in + predefined arithmetic operations), the latter technique will not + generate the required result when the imaginary component of the complex + operand is a negatively signed zero. (Explicit addition of the negative + zero to the zero obtained during promotion yields a positive zero.) + Analogous advice applies in the case of addition of a complex operand + and a pure-imaginary operand, and in the case of subtraction of a + complex operand and a real or pure-imaginary operand." + +Not followed. + + "Implementations in which `Real'Signed_Zeros` is `True` should + attempt to provide a rational treatment of the signs of zero results and + result components. As one example, the result of the `Argument` + function should have the sign of the imaginary component of the + parameter `X` when the point represented by that parameter lies on + the positive real axis; as another, the sign of the imaginary component + of the `Compose_From_Polar` function should be the same as + (respectively, the opposite of) that of the `Argument` parameter when that + parameter has a value of zero and the `Modulus` parameter has a + nonnegative (respectively, negative) value." + +Followed. + +.. index:: Complex elementary functions + +RM G.1.2(49): Complex Elementary Functions +========================================== + + "Implementations in which `Complex_Types.Real'Signed_Zeros` is + `True` should attempt to provide a rational treatment of the signs + of zero results and result components. For example, many of the complex + elementary functions have components that are odd functions of one of + the parameter components; in these cases, the result component should + have the sign of the parameter component at the origin. Other complex + elementary functions have zero components whose sign is opposite that of + a parameter component at the origin, or is always positive or always + negative." + +Followed. + +.. index:: Accuracy requirements + +RM G.2.4(19): Accuracy Requirements +=================================== + + "The versions of the forward trigonometric functions without a + `Cycle` parameter should not be implemented by calling the + corresponding version with a `Cycle` parameter of + `2.0*Numerics.Pi`, since this will not provide the required + accuracy in some portions of the domain. For the same reason, the + version of `Log` without a `Base` parameter should not be + implemented by calling the corresponding version with a `Base` + parameter of `Numerics.e`." + +Followed. + +.. index:: Complex arithmetic accuracy + +.. index:: Accuracy, complex arithmetic + +RM G.2.6(15): Complex Arithmetic Accuracy +========================================= + + "The version of the `Compose_From_Polar` function without a + `Cycle` parameter should not be implemented by calling the + corresponding version with a `Cycle` parameter of + `2.0*Numerics.Pi`, since this will not provide the required + accuracy in some portions of the domain." + +Followed. + +.. index:: Sequential elaboration policy + +RM H.6(15/2): Pragma Partition_Elaboration_Policy +================================================= + + "If the partition elaboration policy is `Sequential` and the + Environment task becomes permanently blocked during elaboration then the + partition is deadlocked and it is recommended that the partition be + immediately terminated." + +Not followed. diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst b/gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst new file mode 100644 index 00000000000..9b9fd11442a --- /dev/null +++ b/gcc/ada/doc/gnat_rm/implementation_defined_aspects.rst @@ -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. diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst new file mode 100644 index 00000000000..b25f9c996a6 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst @@ -0,0 +1,1589 @@ +.. _Implementation_Defined_Attributes: + +********************************* +Implementation Defined Attributes +********************************* + +Ada defines (throughout the Ada reference manual, +summarized in Annex K), +a set of attributes that provide useful additional functionality in all +areas of the language. These language defined attributes are implemented +in GNAT and work as described in the Ada Reference Manual. + +In addition, Ada allows implementations to define additional +attributes whose meaning is defined by the implementation. GNAT provides +a number of these implementation-dependent attributes which can be used +to extend and enhance the functionality of the compiler. This section of +the GNAT reference manual describes these additional attributes. It also +describes additional implementation-dependent features of standard +language-defined attributes. + +Note that any program using these attributes may not be portable to +other compilers (although GNAT implements this set of attributes on all +platforms). Therefore if portability to other compilers is an important +consideration, you should minimize the use of these attributes. + +Attribute Abort_Signal +====================== +.. index:: Abort_Signal + +`Standard'Abort_Signal` (`Standard` is the only allowed +prefix) provides the entity for the special exception used to signal +task abort or asynchronous transfer of control. Normally this attribute +should only be used in the tasking runtime (it is highly peculiar, and +completely outside the normal semantics of Ada, for a user program to +intercept the abort exception). + +Attribute Address_Size +====================== +.. index:: Size of `Address` + +.. index:: Address_Size + +`Standard'Address_Size` (`Standard` is the only allowed +prefix) is a static constant giving the number of bits in an +`Address`. It is the same value as System.Address'Size, +but has the advantage of being static, while a direct +reference to System.Address'Size is non-static because Address +is a private type. + +Attribute Asm_Input +=================== +.. index:: Asm_Input + +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 +constant are the same as those used in the RTL, and are dependent on +the configuration file used to built the GCC back end. +:ref:`Machine_Code_Insertions` + +Attribute Asm_Output +==================== +.. index:: Asm_Output + +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 for the parameter (e.g., what kind of register is +required). The second argument is the variable to be 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`. +:ref:`Machine_Code_Insertions` + +Attribute Atomic_Always_Lock_Free +================================= +.. index:: Atomic_Always_Lock_Free + +The prefix of the `Atomic_Always_Lock_Free` attribute is a type. +The result is a Boolean value which is True if the type has discriminants, +and False otherwise. The result indicate whether atomic operations are +supported by the target for the given type. + +Attribute Bit +============= +.. index:: Bit + +``obj'Bit``, where `obj` is any object, yields the bit +offset within the storage unit (byte) that contains the first bit of +storage allocated for the object. The value of this attribute is of the +type `Universal_Integer`, and is always a non-negative number not +exceeding the value of `System.Storage_Unit`. + +For an object that is a variable or a constant allocated in a register, +the value is zero. (The use of this attribute does not force the +allocation of a variable to memory). + +For an object that is a formal parameter, this attribute applies +to either the matching actual parameter or to a copy of the +matching actual parameter. + +For an access object the value is zero. Note that +``obj.all'Bit`` is subject to an `Access_Check` for the +designated object. Similarly for a record component +``X.C'Bit`` is subject to a discriminant check and +``X(I).Bit`` and ``X(I1..I2)'Bit`` +are subject to index checks. + +This attribute is designed to be compatible with the DEC Ada 83 definition +and implementation of the `Bit` attribute. + +Attribute Bit_Position +====================== +.. index:: Bit_Position + +``R.C'Bit_Position``, where `R` is a record object and `C` is one +of the fields of the record type, yields the bit +offset within the record contains the first bit of +storage allocated for the object. The value of this attribute is of the +type `Universal_Integer`. The value depends only on the field +`C` and is independent of the alignment of +the containing record `R`. + +Attribute Code_Address +====================== +.. index:: Code_Address +.. index:: Subprogram address + +.. index:: Address of subprogram code + +The `'Address` +attribute may be applied to subprograms in Ada 95 and Ada 2005, but the +intended effect seems to be to provide +an address value which can be used to call the subprogram by means of +an address clause as in the following example: + +.. code-block:: ada + + procedure K is ... + + procedure L; + for L'Address use K'Address; + pragma Import (Ada, L); + + +A call to `L` is then expected to result in a call to `K`. +In Ada 83, where there were no access-to-subprogram values, this was +a common work-around for getting the effect of an indirect call. +GNAT implements the above use of `Address` and the technique +illustrated by the example code works correctly. + +However, for some purposes, it is useful to have the address of the start +of the generated code for the subprogram. On some architectures, this is +not necessarily the same as the `Address` value described above. +For example, the `Address` value may reference a subprogram +descriptor rather than the subprogram itself. + +The `'Code_Address` attribute, which can only be applied to +subprogram entities, always returns the address of the start of the +generated code of the specified subprogram, which may or may not be +the same value as is returned by the corresponding `'Address` +attribute. + +Attribute Compiler_Version +========================== +.. index:: Compiler_Version + +`Standard'Compiler_Version` (`Standard` is the only allowed +prefix) yields a static string identifying the version of the compiler +being used to compile the unit containing the attribute reference. + +Attribute Constrained +===================== +.. index:: Constrained + +In addition to the usage of this attribute in the Ada RM, `GNAT` +also permits the use of the `'Constrained` attribute +in a generic template +for any type, including types without discriminants. The value of this +attribute in the generic instance when applied to a scalar type or a +record type without discriminants is always `True`. This usage is +compatible with older Ada compilers, including notably DEC Ada. + +Attribute Default_Bit_Order +=========================== +.. index:: Big endian + +.. index:: Little endian + +.. index:: Default_Bit_Order + +`Standard'Default_Bit_Order` (`Standard` is the only +permissible prefix), provides the value `System.Default_Bit_Order` +as a `Pos` value (0 for `High_Order_First`, 1 for +`Low_Order_First`). This is used to construct the definition of +`Default_Bit_Order` in package `System`. + +Attribute Default_Scalar_Storage_Order +====================================== +.. index:: Big endian + +.. index:: Little endian + +.. index:: Default_Scalar_Storage_Order + +`Standard'Default_Scalar_Storage_Order` (`Standard` is the only +permissible prefix), provides the current value of the default scalar storage +order (as specified using pragma `Default_Scalar_Storage_Order`, or +equal to `Default_Bit_Order` if unspecified) as a +`System.Bit_Order` value. This is a static attribute. + +Attribute Descriptor_Size +========================= +.. index:: Descriptor + +.. index:: Dope vector + +.. index:: Descriptor_Size + +Non-static attribute `Descriptor_Size` returns the size in bits of the +descriptor allocated for a type. The result is non-zero only for unconstrained +array types and the returned value is of type universal integer. In GNAT, an +array descriptor contains bounds information and is located immediately before +the first element of the array. + +.. code-block:: ada + + type Unconstr_Array is array (Positive range <>) of Boolean; + Put_Line ("Descriptor size = " & Unconstr_Array'Descriptor_Size'Img); + + +The attribute takes into account any additional padding due to type alignment. +In the example above, the descriptor contains two values of type +`Positive` representing the low and high bound. Since `Positive` has +a size of 31 bits and an alignment of 4, the descriptor size is `2 * Positive'Size + 2` or 64 bits. + +Attribute Elaborated +==================== +.. index:: Elaborated + +The prefix of the `'Elaborated` attribute must be a unit name. The +value is a Boolean which indicates whether or not the given unit has been +elaborated. This attribute is primarily intended for internal use by the +generated code for dynamic elaboration checking, but it can also be used +in user programs. The value will always be True once elaboration of all +units has been completed. An exception is for units which need no +elaboration, the value is always False for such units. + +Attribute Elab_Body +=================== +.. index:: Elab_Body + +This attribute can only be applied to a program unit name. It returns +the entity for the corresponding elaboration procedure for elaborating +the body of the referenced unit. This is used in the main generated +elaboration procedure by the binder and is not normally used in any +other context. However, there may be specialized situations in which it +is useful to be able to call this elaboration procedure from Ada code, +e.g., if it is necessary to do selective re-elaboration to fix some +error. + +Attribute Elab_Spec +=================== +.. index:: Elab_Spec + +This attribute can only be applied to a program unit name. It returns +the entity for the corresponding elaboration procedure for elaborating +the spec of the referenced unit. This is used in the main +generated elaboration procedure by the binder and is not normally used +in any other context. However, there may be specialized situations in +which it is useful to be able to call this elaboration procedure from +Ada code, e.g., if it is necessary to do selective re-elaboration to fix +some error. + +Attribute Elab_Subp_Body +======================== +.. index:: Elab_Subp_Body + +This attribute can only be applied to a library level subprogram +name and is only allowed in CodePeer mode. It returns the entity +for the corresponding elaboration procedure for elaborating the body +of the referenced subprogram unit. This is used in the main generated +elaboration procedure by the binder in CodePeer mode only and is unrecognized +otherwise. + +Attribute Emax +============== +.. index:: Ada 83 attributes + +.. index:: Emax + +The `Emax` attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +Attribute Enabled +================= +.. index:: Enabled + +The `Enabled` attribute allows an application program to check at compile +time to see if the designated check is currently enabled. The prefix is a +simple identifier, referencing any predefined check name (other than +`All_Checks`) or a check name introduced by pragma Check_Name. If +no argument is given for the attribute, the check is for the general state +of the check, if an argument is given, then it is an entity name, and the +check indicates whether an `Suppress` or `Unsuppress` has been +given naming the entity (if not, then the argument is ignored). + +Note that instantiations inherit the check status at the point of the +instantiation, so a useful idiom is to have a library package that +introduces a check name with `pragma Check_Name`, and then contains +generic packages or subprograms which use the `Enabled` attribute +to see if the check is enabled. A user of this package can then issue +a `pragma Suppress` or `pragma Unsuppress` before instantiating +the package or subprogram, controlling whether the check will be present. + +Attribute Enum_Rep +================== +.. index:: Representation of enums + +.. index:: Enum_Rep + +For every enumeration subtype `S`, ``S'Enum_Rep`` denotes a +function with the following spec: + +.. code-block:: ada + + function S'Enum_Rep (Arg : S'Base) return <Universal_Integer>; + + +It is also allowable to apply `Enum_Rep` directly to an object of an +enumeration type or to a non-overloaded enumeration +literal. In this case ``S'Enum_Rep`` is equivalent to +``typ'Enum_Rep(S)`` where `typ` is the type of the +enumeration literal or object. + +The function returns the representation value for the given enumeration +value. This will be equal to value of the `Pos` attribute in the +absence of an enumeration representation clause. This is a static +attribute (i.e.,:the result is static if the argument is static). + +``S'Enum_Rep`` can also be used with integer types and objects, +in which case it simply returns the integer value. The reason for this +is to allow it to be used for `(<>)` discrete formal arguments in +a generic unit that can be instantiated with either enumeration types +or integer types. Note that if `Enum_Rep` is used on a modular +type whose upper bound exceeds the upper bound of the largest signed +integer type, and the argument is a variable, so that the universal +integer calculation is done at run time, then the call to `Enum_Rep` +may raise `Constraint_Error`. + +Attribute Enum_Val +================== +.. index:: Representation of enums + +.. index:: Enum_Val + +For every enumeration subtype `S`, ``S'Enum_Val`` denotes a +function with the following spec: + +.. code-block:: ada + + function S'Enum_Val (Arg : <Universal_Integer>) return S'Base; + + +The function returns the enumeration value whose representation matches the +argument, or raises Constraint_Error if no enumeration literal of the type +has the matching value. +This will be equal to value of the `Val` attribute in the +absence of an enumeration representation clause. This is a static +attribute (i.e., the result is static if the argument is static). + +Attribute Epsilon +================= +.. index:: Ada 83 attributes + +.. index:: Epsilon + +The `Epsilon` attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +Attribute Fast_Math +=================== +.. index:: Fast_Math + +`Standard'Fast_Math` (`Standard` is the only allowed +prefix) yields a static Boolean value that is True if pragma +`Fast_Math` is active, and False otherwise. + +Attribute Fixed_Value +===================== +.. index:: Fixed_Value + +For every fixed-point type `S`, ``S'Fixed_Value`` denotes a +function with the following specification: + +.. code-block:: ada + + function S'Fixed_Value (Arg : <Universal_Integer>) return S; + +The value returned is the fixed-point value `V` such that:: + + V = Arg * S'Small + + +The effect is thus similar to first converting the argument to the +integer type used to represent `S`, and then doing an unchecked +conversion to the fixed-point type. The difference is +that there are full range checks, to ensure that the result is in range. +This attribute is primarily intended for use in implementation of the +input-output functions for fixed-point values. + +Attribute From_Any +================== +.. index:: From_Any + +This internal attribute is used for the generation of remote subprogram +stubs in the context of the Distributed Systems Annex. + +Attribute Has_Access_Values +=========================== +.. index:: Access values, testing for + +.. index:: Has_Access_Values + +The prefix of the `Has_Access_Values` attribute is a type. The result +is a Boolean value which is True if the is an access type, or is a composite +type with a component (at any nesting depth) that is an access type, and is +False otherwise. +The intended use of this attribute is in conjunction with generic +definitions. If the attribute is applied to a generic private type, it +indicates whether or not the corresponding actual type has access values. + +Attribute Has_Discriminants +=========================== +.. index:: Discriminants, testing for + +.. index:: Has_Discriminants + +The prefix of the `Has_Discriminants` attribute is a type. The result +is a Boolean value which is True if the type has discriminants, and False +otherwise. The intended use of this attribute is in conjunction with generic +definitions. If the attribute is applied to a generic private type, it +indicates whether or not the corresponding actual type has discriminants. + +Attribute Img +============= +.. index:: Img + +The `Img` attribute differs from `Image` in that it is applied +directly to an object, and yields the same result as +`Image` for the subtype of the object. This is convenient for +debugging: + +.. code-block:: ada + + Put_Line ("X = " & X'Img); + + +has the same meaning as the more verbose: + +.. code-block:: ada + + Put_Line ("X = " & T'Image (X)); + +where `T` is the (sub)type of the object `X`. + +Note that technically, in analogy to `Image`, +`X'Img` returns a parameterless function +that returns the appropriate string when called. This means that +`X'Img` can be renamed as a function-returning-string, or used +in an instantiation as a function parameter. + +Attribute Integer_Value +======================= +.. index:: Integer_Value + +For every integer type `S`, ``S'Integer_Value`` denotes a +function with the following spec: + +.. code-block:: ada + + function S'Integer_Value (Arg : <Universal_Fixed>) return S; + +The value returned is the integer value `V`, such that:: + + Arg = V * T'Small + + +where `T` is the type of `Arg`. +The effect is thus similar to first doing an unchecked conversion from +the fixed-point type to its corresponding implementation type, and then +converting the result to the target integer type. The difference is +that there are full range checks, to ensure that the result is in range. +This attribute is primarily intended for use in implementation of the +standard input-output functions for fixed-point values. + +Attribute Invalid_Value +======================= +.. index:: Invalid_Value + +For every scalar type S, S'Invalid_Value returns an undefined value of the +type. If possible this value is an invalid representation for the type. The +value returned is identical to the value used to initialize an otherwise +uninitialized value of the type if pragma Initialize_Scalars is used, +including the ability to modify the value with the binder -Sxx flag and +relevant environment variables at run time. + +Attribute Iterable +================== +.. index:: Iterable + +Equivalent to Aspect Iterable. + +Attribute Large +=============== +.. index:: Ada 83 attributes + +.. index:: Large + +The `Large` attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +Attribute Library_Level +======================= +.. index:: Library_Level + +`P'Library_Level`, where P is an entity name, +returns a Boolean value which is True if the entity is declared +at the library level, and False otherwise. Note that within a +generic instantition, the name of the generic unit denotes the +instance, which means that this attribute can be used to test +if a generic is instantiated at the library level, as shown +in this example: + +.. code-block:: ada + + generic + ... + package Gen is + pragma Compile_Time_Error + (not Gen'Library_Level, + "Gen can only be instantiated at library level"); + ... + end Gen; + + +Attribute Lock_Free +=================== +.. index:: Lock_Free + +`P'Lock_Free`, where P is a protected object, returns True if a +pragma `Lock_Free` applies to P. + +Attribute Loop_Entry +==================== +.. index:: Loop_Entry + +Syntax:: + + X'Loop_Entry [(loop_name)] + + +The `Loop_Entry` attribute is used to refer to the value that an +expression had upon entry to a given loop in much the same way that the +`Old` attribute in a subprogram postcondition can be used to refer +to the value an expression had upon entry to the subprogram. The +relevant loop is either identified by the given loop name, or it is the +innermost enclosing loop when no loop name is given. + +A `Loop_Entry` attribute can only occur within a +`Loop_Variant` or `Loop_Invariant` pragma. A common use of +`Loop_Entry` is to compare the current value of objects with their +initial value at loop entry, in a `Loop_Invariant` pragma. + +The effect of using `X'Loop_Entry` is the same as declaring +a constant initialized with the initial value of `X` at loop +entry. This copy is not performed if the loop is not entered, or if the +corresponding pragmas are ignored or disabled. + +Attribute Machine_Size +====================== +.. index:: Machine_Size + +This attribute is identical to the `Object_Size` attribute. It is +provided for compatibility with the DEC Ada 83 attribute of this name. + +Attribute Mantissa +================== +.. index:: Ada 83 attributes + +.. index:: Mantissa + +The `Mantissa` attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +.. _Attribute_Maximum_Alignment: + +Attribute Maximum_Alignment +=========================== +.. index:: Alignment, maximum + +.. index:: Maximum_Alignment + +`Standard'Maximum_Alignment` (`Standard` is the only +permissible prefix) provides the maximum useful alignment value for the +target. This is a static value that can be used to specify the alignment +for an object, guaranteeing that it is properly aligned in all +cases. + +Attribute Mechanism_Code +======================== +.. index:: Return values, passing mechanism + +.. index:: Parameters, passing mechanism + +.. index:: Mechanism_Code + +``function'Mechanism_Code`` yields an integer code for the +mechanism used for the result of function, and +``subprogram'Mechanism_Code (n)`` yields the mechanism +used for formal parameter number `n` (a static integer value with 1 +meaning the first parameter) of `subprogram`. The code returned is: + + + +*1* + by copy (value) + +*2* + by reference + +Attribute Null_Parameter +======================== +.. index:: Zero address, passing + +.. index:: Null_Parameter + +A reference ``T'Null_Parameter`` denotes an imaginary object of +type or subtype `T` allocated at machine address zero. The attribute +is allowed only as the default expression of a formal parameter, or as +an actual expression of a subprogram call. In either case, the +subprogram must be imported. + +The identity of the object is represented by the address zero in the +argument list, independent of the passing mechanism (explicit or +default). + +This capability is needed to specify that a zero address should be +passed for a record or other composite object passed by reference. +There is no way of indicating this without the `Null_Parameter` +attribute. + +Attribute Object_Size +===================== +.. index:: Size, used for objects + +.. index:: Object_Size + +The size of an object is not necessarily the same as the size of the type +of an object. This is because by default object sizes are increased to be +a multiple of the alignment of the object. For example, +`Natural'Size` is +31, but by default objects of type `Natural` will have a size of 32 bits. +Similarly, a record containing an integer and a character: + +.. code-block:: ada + + type Rec is record + I : Integer; + C : Character; + end record; + + +will have a size of 40 (that is `Rec'Size` will be 40). The +alignment will be 4, because of the +integer field, and so the default size of record objects for this type +will be 64 (8 bytes). + +If the alignment of the above record is specified to be 1, then the +object size will be 40 (5 bytes). This is true by default, and also +an object size of 40 can be explicitly specified in this case. + +A consequence of this capability is that different object sizes can be +given to subtypes that would otherwise be considered in Ada to be +statically matching. But it makes no sense to consider such subtypes +as statically matching. Consequently, in `GNAT` we add a rule +to the static matching rules that requires object sizes to match. +Consider this example: + +.. code-block:: ada + + 1. procedure BadAVConvert is + 2. type R is new Integer; + 3. subtype R1 is R range 1 .. 10; + 4. subtype R2 is R range 1 .. 10; + 5. for R1'Object_Size use 8; + 6. for R2'Object_Size use 16; + 7. type R1P is access all R1; + 8. type R2P is access all R2; + 9. R1PV : R1P := new R1'(4); + 10. R2PV : R2P; + 11. begin + 12. R2PV := R2P (R1PV); + | + >>> target designated subtype not compatible with + type "R1" defined at line 3 + + 13. end; + + +In the absence of lines 5 and 6, +types `R1` and `R2` statically match and +hence the conversion on line 12 is legal. But since lines 5 and 6 +cause the object sizes to differ, `GNAT` considers that types +`R1` and `R2` are not statically matching, and line 12 +generates the diagnostic shown above. + +Similar additional checks are performed in other contexts requiring +statically matching subtypes. + +Attribute Old +============= +.. index:: Old + +In addition to the usage of `Old` defined in the Ada 2012 RM (usage +within `Post` aspect), GNAT also permits the use of this attribute +in implementation defined pragmas `Postcondition`, +`Contract_Cases` and `Test_Case`. Also usages of +`Old` which would be illegal according to the Ada 2012 RM +definition are allowed under control of +implementation defined pragma `Unevaluated_Use_Of_Old`. + +Attribute Passed_By_Reference +============================= +.. index:: Parameters, when passed by reference + +.. index:: Passed_By_Reference + +``type'Passed_By_Reference`` for any subtype `type` returns +a value of type `Boolean` value that is `True` if the type is +normally passed by reference and `False` if the type is normally +passed by copy in calls. For scalar types, the result is always `False` +and is static. For non-scalar types, the result is non-static. + +Attribute Pool_Address +====================== +.. index:: Parameters, when passed by reference + +.. index:: Pool_Address + +``X'Pool_Address`` for any object `X` returns the address +of X within its storage pool. This is the same as +``X'Address``, except that for an unconstrained array whose +bounds are allocated just before the first component, +``X'Pool_Address`` returns the address of those bounds, +whereas ``X'Address`` returns the address of the first +component. + +Here, we are interpreting 'storage pool' broadly to mean +``wherever the object is allocated``, which could be a +user-defined storage pool, +the global heap, on the stack, or in a static memory area. +For an object created by `new`, ``Ptr.all'Pool_Address`` is +what is passed to `Allocate` and returned from `Deallocate`. + +Attribute Range_Length +====================== +.. index:: Range_Length + +``type'Range_Length`` for any discrete type `type` yields +the number of values represented by the subtype (zero for a null +range). The result is static for static subtypes. `Range_Length` +applied to the index subtype of a one dimensional array always gives the +same result as `Length` applied to the array itself. + +Attribute Ref +============= +.. index:: Ref + +Attribute Restriction_Set +========================= +.. index:: Restriction_Set +.. index:: Restrictions + +This attribute allows compile time testing of restrictions that +are currently in effect. It is primarily intended for specializing +code in the run-time based on restrictions that are active (e.g. +don't need to save fpt registers if restriction No_Floating_Point +is known to be in effect), but can be used anywhere. + +There are two forms: + +.. code-block:: ada + + System'Restriction_Set (partition_boolean_restriction_NAME) + System'Restriction_Set (No_Dependence => library_unit_NAME); + + +In the case of the first form, the only restriction names +allowed are parameterless restrictions that are checked +for consistency at bind time. For a complete list see the +subtype `System.Rident.Partition_Boolean_Restrictions`. + +The result returned is True if the restriction is known to +be in effect, and False if the restriction is known not to +be in effect. An important guarantee is that the value of +a Restriction_Set attribute is known to be consistent throughout +all the code of a partition. + +This is trivially achieved if the entire partition is compiled +with a consistent set of restriction pragmas. However, the +compilation model does not require this. It is possible to +compile one set of units with one set of pragmas, and another +set of units with another set of pragmas. It is even possible +to compile a spec with one set of pragmas, and then WITH the +same spec with a different set of pragmas. Inconsistencies +in the actual use of the restriction are checked at bind time. + +In order to achieve the guarantee of consistency for the +Restriction_Set pragma, we consider that a use of the pragma +that yields False is equivalent to a violation of the +restriction. + +So for example if you write + +.. code-block:: ada + + if System'Restriction_Set (No_Floating_Point) then + ... + else + ... + end if; + + +And the result is False, so that the else branch is executed, +you can assume that this restriction is not set for any unit +in the partition. This is checked by considering this use of +the restriction pragma to be a violation of the restriction +No_Floating_Point. This means that no other unit can attempt +to set this restriction (if some unit does attempt to set it, +the binder will refuse to bind the partition). + +Technical note: The restriction name and the unit name are +intepreted entirely syntactically, as in the corresponding +Restrictions pragma, they are not analyzed semantically, +so they do not have a type. + +Attribute Result +================ +.. index:: Result + +``function'Result`` can only be used with in a Postcondition pragma +for a function. The prefix must be the name of the corresponding function. This +is used to refer to the result of the function in the postcondition expression. +For a further discussion of the use of this attribute and examples of its use, +see the description of pragma Postcondition. + +Attribute Safe_Emax +=================== +.. index:: Ada 83 attributes + +.. index:: Safe_Emax + +The `Safe_Emax` attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +Attribute Safe_Large +==================== +.. index:: Ada 83 attributes + +.. index:: Safe_Large + +The `Safe_Large` attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +Attribute Safe_Small +==================== +.. index:: Ada 83 attributes + +.. index:: Safe_Small + +The `Safe_Small` attribute is provided for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute. + +Attribute Scalar_Storage_Order +============================== +.. index:: Endianness + +.. index:: Scalar storage order + +.. index:: Scalar_Storage_Order + +For every array or record type `S`, the representation attribute +`Scalar_Storage_Order` denotes the order in which storage elements +that make up scalar components are ordered within S. The value given must +be a static expression of type System.Bit_Order. The following is an example +of the use of this feature: + +.. code-block:: ada + + -- Component type definitions + + subtype Yr_Type is Natural range 0 .. 127; + subtype Mo_Type is Natural range 1 .. 12; + subtype Da_Type is Natural range 1 .. 31; + + -- Record declaration + + type Date is record + Years_Since_1980 : Yr_Type; + Month : Mo_Type; + Day_Of_Month : Da_Type; + end record; + + -- Record representation clause + + for Date use record + Years_Since_1980 at 0 range 0 .. 6; + Month at 0 range 7 .. 10; + Day_Of_Month at 0 range 11 .. 15; + end record; + + -- Attribute definition clauses + + for Date'Bit_Order use System.High_Order_First; + for Date'Scalar_Storage_Order use System.High_Order_First; + -- If Scalar_Storage_Order is specified, it must be consistent with + -- Bit_Order, so it's best to always define the latter explicitly if + -- the former is used. + + +Other properties are as for standard representation attribute `Bit_Order`, +as defined by Ada RM 13.5.3(4). The default is `System.Default_Bit_Order`. + +For a record type `T`, if ``T'Scalar_Storage_Order`` is +specified explicitly, it shall be equal to ``T'Bit_Order``. Note: +this means that if a `Scalar_Storage_Order` attribute definition +clause is not confirming, then the type's `Bit_Order` shall be +specified explicitly and set to the same value. + +Derived types inherit an explicitly set scalar storage order from their parent +types. This may be overridden for the derived type by giving an explicit scalar +storage order for the derived type. For a record extension, the derived type +must have the same scalar storage order as the parent type. + +If a component of `T` is of a record or array type, then that type must +also have a `Scalar_Storage_Order` attribute definition clause. + +A component of a record or array type that is a packed array, or that +does not start on a byte boundary, must have the same scalar storage order +as the enclosing record or array type. + +No component of a type that has an explicit `Scalar_Storage_Order` +attribute definition may be aliased. + +A confirming `Scalar_Storage_Order` attribute definition clause (i.e. +with a value equal to `System.Default_Bit_Order`) has no effect. + +If the opposite storage order is specified, then whenever the value of +a scalar component of an object of type `S` is read, the storage +elements of the enclosing machine scalar are first reversed (before +retrieving the component value, possibly applying some shift and mask +operatings on the enclosing machine scalar), and the opposite operation +is done for writes. + +In that case, the restrictions set forth in 13.5.1(10.3/2) for scalar components +are relaxed. Instead, the following rules apply: + +* the underlying storage elements are those at positions + `(position + first_bit / storage_element_size) .. (position + (last_bit + storage_element_size - 1) / storage_element_size)` +* the sequence of underlying storage elements shall have + a size no greater than the largest machine scalar +* the enclosing machine scalar is defined as the smallest machine + scalar starting at a position no greater than + `position + first_bit / storage_element_size` and covering + storage elements at least up to `position + (last_bit + storage_element_size - 1) / storage_element_size` +* the position of the component is interpreted relative to that machine + scalar. + +If no scalar storage order is specified for a type (either directly, or by +inheritance in the case of a derived type), then the default is normally +the native ordering of the target, but this default can be overridden using +pragma `Default_Scalar_Storage_Order`. + +Note that the scalar storage order only affects the in-memory data +representation. It has no effect on the representation used by stream +attributes. + +.. _Attribute_Simple_Storage_Pool: + +Attribute Simple_Storage_Pool +============================= +.. index:: Storage pool, simple + +.. index:: Simple storage pool + +.. index:: Simple_Storage_Pool + +For every nonformal, nonderived access-to-object type `Acc`, the +representation attribute `Simple_Storage_Pool` may be specified +via an attribute_definition_clause (or by specifying the equivalent aspect): + +.. code-block:: ada + + My_Pool : My_Simple_Storage_Pool_Type; + + type Acc is access My_Data_Type; + + for Acc'Simple_Storage_Pool use My_Pool; + + + +The name given in an attribute_definition_clause for the +`Simple_Storage_Pool` attribute shall denote a variable of +a 'simple storage pool type' (see pragma `Simple_Storage_Pool_Type`). + +The use of this attribute is only allowed for a prefix denoting a type +for which it has been specified. The type of the attribute is the type +of the variable specified as the simple storage pool of the access type, +and the attribute denotes that variable. + +It is illegal to specify both `Storage_Pool` and `Simple_Storage_Pool` +for the same access type. + +If the `Simple_Storage_Pool` attribute has been specified for an access +type, then applying the `Storage_Pool` attribute to the type is flagged +with a warning and its evaluation raises the exception `Program_Error`. + +If the Simple_Storage_Pool attribute has been specified for an access +type `S`, then the evaluation of the attribute ``S'Storage_Size`` +returns the result of calling ``Storage_Size (S'Simple_Storage_Pool)``, +which is intended to indicate the number of storage elements reserved for +the simple storage pool. If the Storage_Size function has not been defined +for the simple storage pool type, then this attribute returns zero. + +If an access type `S` has a specified simple storage pool of type +`SSP`, then the evaluation of an allocator for that access type calls +the primitive `Allocate` procedure for type `SSP`, passing +``S'Simple_Storage_Pool`` as the pool parameter. The detailed +semantics of such allocators is the same as those defined for allocators +in section 13.11 of the :title:`Ada Reference Manual`, with the term +`simple storage pool` substituted for `storage pool`. + +If an access type `S` has a specified simple storage pool of type +`SSP`, then a call to an instance of the `Ada.Unchecked_Deallocation` +for that access type invokes the primitive `Deallocate` procedure +for type `SSP`, passing ``S'Simple_Storage_Pool`` as the pool +parameter. The detailed semantics of such unchecked deallocations is the same +as defined in section 13.11.2 of the Ada Reference Manual, except that the +term 'simple storage pool' is substituted for 'storage pool'. + +Attribute Small +=============== +.. index:: Ada 83 attributes + +.. index:: Small + +The `Small` attribute is defined in Ada 95 (and Ada 2005) only for +fixed-point types. +GNAT also allows this attribute to be applied to floating-point types +for compatibility with Ada 83. See +the Ada 83 reference manual for an exact description of the semantics of +this attribute when applied to floating-point types. + +Attribute Storage_Unit +====================== +.. index:: Storage_Unit + +`Standard'Storage_Unit` (`Standard` is the only permissible +prefix) provides the same value as `System.Storage_Unit`. + +Attribute Stub_Type +=================== +.. index:: Stub_Type + +The GNAT implementation of remote access-to-classwide types is +organized as described in AARM section E.4 (20.t): a value of an RACW type +(designating a remote object) is represented as a normal access +value, pointing to a "stub" object which in turn contains the +necessary information to contact the designated remote object. A +call on any dispatching operation of such a stub object does the +remote call, if necessary, using the information in the stub object +to locate the target partition, etc. + +For a prefix `T` that denotes a remote access-to-classwide type, +`T'Stub_Type` denotes the type of the corresponding stub objects. + +By construction, the layout of `T'Stub_Type` is identical to that of +type `RACW_Stub_Type` declared in the internal implementation-defined +unit `System.Partition_Interface`. Use of this attribute will create +an implicit dependency on this unit. + +Attribute System_Allocator_Alignment +==================================== +.. index:: Alignment, allocator + +.. index:: System_Allocator_Alignment + +`Standard'System_Allocator_Alignment` (`Standard` is the only +permissible prefix) provides the observable guaranted to be honored by +the system allocator (malloc). This is a static value that can be used +in user storage pools based on malloc either to reject allocation +with alignment too large or to enable a realignment circuitry if the +alignment request is larger than this value. + +Attribute Target_Name +===================== +.. index:: Target_Name + +`Standard'Target_Name` (`Standard` is the only permissible +prefix) provides a static string value that identifies the target +for the current compilation. For GCC implementations, this is the +standard gcc target name without the terminating slash (for +example, GNAT 5.0 on windows yields "i586-pc-mingw32msv"). + +Attribute To_Address +==================== +.. index:: To_Address + +The `System'To_Address` +(`System` is the only permissible prefix) +denotes a function identical to +`System.Storage_Elements.To_Address` except that +it is a static attribute. This means that if its argument is +a static expression, then the result of the attribute is a +static expression. This means that such an expression can be +used in contexts (e.g., preelaborable packages) which require a +static expression and where the function call could not be used +(since the function call is always non-static, even if its +argument is static). The argument must be in the range +-(2**(m-1) .. 2**m-1, where m is the memory size +(typically 32 or 64). Negative values are intepreted in a +modular manner (e.g., -1 means the same as 16#FFFF_FFFF# on +a 32 bits machine). + +Attribute To_Any +================ +.. index:: To_Any + +This internal attribute is used for the generation of remote subprogram +stubs in the context of the Distributed Systems Annex. + +Attribute Type_Class +==================== +.. index:: Type_Class + +``type'Type_Class`` for any type or subtype `type` yields +the value of the type class for the full type of `type`. If +`type` is a generic formal type, the value is the value for the +corresponding actual subtype. The value of this attribute is of type +``System.Aux_DEC.Type_Class``, which has the following definition: + +.. code-block:: ada + + type Type_Class is + (Type_Class_Enumeration, + Type_Class_Integer, + Type_Class_Fixed_Point, + Type_Class_Floating_Point, + Type_Class_Array, + Type_Class_Record, + Type_Class_Access, + Type_Class_Task, + Type_Class_Address); + + +Protected types yield the value `Type_Class_Task`, which thus +applies to all concurrent types. This attribute is designed to +be compatible with the DEC Ada 83 attribute of the same name. + +Attribute Type_Key +================== +.. index:: Type_Key + +The `Type_Key` attribute is applicable to a type or subtype and +yields a value of type Standard.String containing encoded information +about the type or subtype. This provides improved compatibility with +other implementations that support this attribute. + +Attribute TypeCode +================== +.. index:: TypeCode + +This internal attribute is used for the generation of remote subprogram +stubs in the context of the Distributed Systems Annex. + +Attribute UET_Address +===================== +.. index:: UET_Address + +The `UET_Address` attribute can only be used for a prefix which +denotes a library package. It yields the address of the unit exception +table when zero cost exception handling is used. This attribute is +intended only for use within the GNAT implementation. See the unit +`Ada.Exceptions` in files :file:`a-except.ads` and :file:`a-except.adb` +for details on how this attribute is used in the implementation. + +Attribute Unconstrained_Array +============================= +.. index:: Unconstrained_Array + +The `Unconstrained_Array` attribute can be used with a prefix that +denotes any type or subtype. It is a static attribute that yields +`True` if the prefix designates an unconstrained array, +and `False` otherwise. In a generic instance, the result is +still static, and yields the result of applying this test to the +generic actual. + +Attribute Universal_Literal_String +================================== +.. index:: Named numbers, representation of + +.. index:: Universal_Literal_String + +The prefix of `Universal_Literal_String` must be a named +number. The static result is the string consisting of the characters of +the number as defined in the original source. This allows the user +program to access the actual text of named numbers without intermediate +conversions and without the need to enclose the strings in quotes (which +would preclude their use as numbers). + +For example, the following program prints the first 50 digits of pi: + +.. code-block:: ada + + with Text_IO; use Text_IO; + with Ada.Numerics; + procedure Pi is + begin + Put (Ada.Numerics.Pi'Universal_Literal_String); + end; + + +Attribute Unrestricted_Access +============================= +.. index:: Access, unrestricted + +.. index:: Unrestricted_Access + +The `Unrestricted_Access` attribute is similar to `Access` +except that all accessibility and aliased view checks are omitted. This +is a user-beware attribute. + +For objects, it is similar to `Address`, for which it is a +desirable replacement where the value desired is an access type. +In other words, its effect is similar to first applying the +`Address` attribute and then doing an unchecked conversion to a +desired access type. + +For subprograms, `P'Unrestricted_Access` may be used where +`P'Access` would be illegal, to construct a value of a +less-nested named access type that designates a more-nested +subprogram. This value may be used in indirect calls, so long as the +more-nested subprogram still exists; once the subprogram containing it +has returned, such calls are erroneous. For example: + +.. code-block:: ada + + package body P is + + type Less_Nested is not null access procedure; + Global : Less_Nested; + + procedure P1 is + begin + Global.all; + end P1; + + procedure P2 is + Local_Var : Integer; + + procedure More_Nested is + begin + ... Local_Var ... + end More_Nested; + begin + Global := More_Nested'Unrestricted_Access; + P1; + end P2; + + end P; + + +When P1 is called from P2, the call via Global is OK, but if P1 were +called after P2 returns, it would be an erroneous use of a dangling +pointer. + +For objects, it is possible to use `Unrestricted_Access` for any +type. However, if the result is of an access-to-unconstrained array +subtype, then the resulting pointer has the same scope as the context +of the attribute, and must not be returned to some enclosing scope. +For instance, if a function uses `Unrestricted_Access` to create +an access-to-unconstrained-array and returns that value to the caller, +the result will involve dangling pointers. In addition, it is only +valid to create pointers to unconstrained arrays using this attribute +if the pointer has the normal default 'fat' representation where a +pointer has two components, one points to the array and one points to +the bounds. If a size clause is used to force 'thin' representation +for a pointer to unconstrained where there is only space for a single +pointer, then the resulting pointer is not usable. + +In the simple case where a direct use of Unrestricted_Access attempts +to make a thin pointer for a non-aliased object, the compiler will +reject the use as illegal, as shown in the following example: + +.. code-block:: ada + + with System; use System; + procedure SliceUA2 is + type A is access all String; + for A'Size use Standard'Address_Size; + + procedure P (Arg : A) is + begin + null; + end P; + + X : String := "hello world!"; + X2 : aliased String := "hello world!"; + + AV : A := X'Unrestricted_Access; -- ERROR + | + >>> illegal use of Unrestricted_Access attribute + >>> attempt to generate thin pointer to unaliased object + + begin + P (X'Unrestricted_Access); -- ERROR + | + >>> illegal use of Unrestricted_Access attribute + >>> attempt to generate thin pointer to unaliased object + + P (X(7 .. 12)'Unrestricted_Access); -- ERROR + | + >>> illegal use of Unrestricted_Access attribute + >>> attempt to generate thin pointer to unaliased object + + P (X2'Unrestricted_Access); -- OK + end; + + +but other cases cannot be detected by the compiler, and are +considered to be erroneous. Consider the following example: + +.. code-block:: ada + + with System; use System; + with System; use System; + procedure SliceUA is + type AF is access all String; + + type A is access all String; + for A'Size use Standard'Address_Size; + + procedure P (Arg : A) is + begin + if Arg'Length /= 6 then + raise Program_Error; + end if; + end P; + + X : String := "hello world!"; + Y : AF := X (7 .. 12)'Unrestricted_Access; + + begin + P (A (Y)); + end; + + +A normal unconstrained array value +or a constrained array object marked as aliased has the bounds in memory +just before the array, so a thin pointer can retrieve both the data and +the bounds. But in this case, the non-aliased object `X` does not have the +bounds before the string. If the size clause for type `A` +were not present, then the pointer +would be a fat pointer, where one component is a pointer to the bounds, +and all would be well. But with the size clause present, the conversion from +fat pointer to thin pointer in the call loses the bounds, and so this +is erroneous, and the program likely raises a `Program_Error` exception. + +In general, it is advisable to completely +avoid mixing the use of thin pointers and the use of +`Unrestricted_Access` where the designated type is an +unconstrained array. The use of thin pointers should be restricted to +cases of porting legacy code that implicitly assumes the size of pointers, +and such code should not in any case be using this attribute. + +Another erroneous situation arises if the attribute is +applied to a constant. The resulting pointer can be used to access the +constant, but the effect of trying to modify a constant in this manner +is not well-defined. Consider this example: + +.. code-block:: ada + + P : constant Integer := 4; + type R is access all Integer; + RV : R := P'Unrestricted_Access; + .. + RV.all := 3; + + +Here we attempt to modify the constant P from 4 to 3, but the compiler may +or may not notice this attempt, and subsequent references to P may yield +either the value 3 or the value 4 or the assignment may blow up if the +compiler decides to put P in read-only memory. One particular case where +`Unrestricted_Access` can be used in this way is to modify the +value of an `IN` parameter: + +.. code-block:: ada + + procedure K (S : in String) is + type R is access all Character; + RV : R := S (3)'Unrestricted_Access; + begin + RV.all := 'a'; + end; + + +In general this is a risky approach. It may appear to "work" but such uses of +`Unrestricted_Access` are potentially non-portable, even from one version +of `GNAT` to another, so are best avoided if possible. + +Attribute Update +================ +.. index:: Update + +The `Update` attribute creates a copy of an array or record value +with one or more modified components. The syntax is:: + + PREFIX'Update ( RECORD_COMPONENT_ASSOCIATION_LIST ) + PREFIX'Update ( ARRAY_COMPONENT_ASSOCIATION {, ARRAY_COMPONENT_ASSOCIATION } ) + PREFIX'Update ( MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION + {, MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION } ) + + MULTIDIMENSIONAL_ARRAY_COMPONENT_ASSOCIATION ::= INDEX_EXPRESSION_LIST_LIST => EXPRESSION + INDEX_EXPRESSION_LIST_LIST ::= INDEX_EXPRESSION_LIST {| INDEX_EXPRESSION_LIST } + INDEX_EXPRESSION_LIST ::= ( EXPRESSION {, EXPRESSION } ) + + +where `PREFIX` is the name of an array or record object, the +association list in parentheses does not contain an `others` +choice and the box symbol `<>` may not appear in any +expression. The effect is to yield a copy of the array or record value +which is unchanged apart from the components mentioned in the +association list, which are changed to the indicated value. The +original value of the array or record value is not affected. For +example: + +.. code-block:: ada + + type Arr is Array (1 .. 5) of Integer; + ... + Avar1 : Arr := (1,2,3,4,5); + Avar2 : Arr := Avar1'Update (2 => 10, 3 .. 4 => 20); + + +yields a value for `Avar2` of 1,10,20,20,5 with `Avar1` +begin unmodified. Similarly: + +.. code-block:: ada + + type Rec is A, B, C : Integer; + ... + Rvar1 : Rec := (A => 1, B => 2, C => 3); + Rvar2 : Rec := Rvar1'Update (B => 20); + + +yields a value for `Rvar2` of (A => 1, B => 20, C => 3), +with `Rvar1` being unmodifed. +Note that the value of the attribute reference is computed +completely before it is used. This means that if you write: + +.. code-block:: ada + + Avar1 := Avar1'Update (1 => 10, 2 => Function_Call); + + +then the value of `Avar1` is not modified if `Function_Call` +raises an exception, unlike the effect of a series of direct assignments +to elements of `Avar1`. In general this requires that +two extra complete copies of the object are required, which should be +kept in mind when considering efficiency. + +The `Update` attribute cannot be applied to prefixes of a limited +type, and cannot reference discriminants in the case of a record type. +The accessibility level of an Update attribute result object is defined +as for an aggregate. + +In the record case, no component can be mentioned more than once. In +the array case, two overlapping ranges can appear in the association list, +in which case the modifications are processed left to right. + +Multi-dimensional arrays can be modified, as shown by this example: + +.. code-block:: ada + + A : array (1 .. 10, 1 .. 10) of Integer; + .. + A := A'Update ((1, 2) => 20, (3, 4) => 30); + + +which changes element (1,2) to 20 and (3,4) to 30. + +Attribute Valid_Scalars +======================= +.. index:: Valid_Scalars + +The `'Valid_Scalars` attribute is intended to make it easier to +check the validity of scalar subcomponents of composite objects. It +is defined for any prefix `X` that denotes an object. +The value of this attribute is of the predefined type Boolean. +`X'Valid_Scalars` yields True if and only if evaluation of +`P'Valid` yields True for every scalar part P of X or if X has +no scalar parts. It is not specified in what order the scalar parts +are checked, nor whether any more are checked after any one of them +is determined to be invalid. If the prefix `X` is of a class-wide +type `T'Class` (where `T` is the associated specific type), +or if the prefix `X` is of a specific tagged type `T`, then +only the scalar parts of components of `T` are traversed; in other +words, components of extensions of `T` are not traversed even if +`T'Class (X)'Tag /= T'Tag` . The compiler will issue a warning if it can +be determined at compile time that the prefix of the attribute has no +scalar parts (e.g., if the prefix is of an access type, an interface type, +an undiscriminated task type, or an undiscriminated protected type). + +For scalar types, `Valid_Scalars` is equivalent to `Valid`. The use +of this attribute is not permitted for `Unchecked_Union` types for which +in general it is not possible to determine the values of the discriminants. + +Note: `Valid_Scalars` can generate a lot of code, especially in the case +of a large variant record. If the attribute is called in many places in the +same program applied to objects of the same type, it can reduce program size +to write a function with a single use of the attribute, and then call that +function from multiple places. + +Attribute VADS_Size +=================== +.. index:: Size, VADS compatibility + +.. index:: VADS_Size + +The `'VADS_Size` attribute is intended to make it easier to port +legacy code which relies on the semantics of `'Size` as implemented +by the VADS Ada 83 compiler. GNAT makes a best effort at duplicating the +same semantic interpretation. In particular, `'VADS_Size` applied +to a predefined or other primitive type with no Size clause yields the +Object_Size (for example, `Natural'Size` is 32 rather than 31 on +typical machines). In addition `'VADS_Size` applied to an object +gives the result that would be obtained by applying the attribute to +the corresponding type. + +Attribute Value_Size +==================== +.. index:: Size, setting for not-first subtype + +.. index:: Value_Size + +``type'Value_Size`` is the number of bits required to represent +a value of the given subtype. It is the same as ``type'Size``, +but, unlike `Size`, may be set for non-first subtypes. + +Attribute Wchar_T_Size +====================== +.. index:: Wchar_T_Size + +`Standard'Wchar_T_Size` (`Standard` is the only permissible +prefix) provides the size in bits of the C `wchar_t` type +primarily for constructing the definition of this type in +package `Interfaces.C`. The result is a static constant. + +Attribute Word_Size +=================== +.. index:: Word_Size + +`Standard'Word_Size` (`Standard` is the only permissible +prefix) provides the value `System.Word_Size`. The result is +a static constant. + diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst b/gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst new file mode 100644 index 00000000000..f26dd912998 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/implementation_defined_characteristics.rst @@ -0,0 +1,1295 @@ +.. _Implementation_Defined_Characteristics: + +************************************** +Implementation Defined Characteristics +************************************** + +In addition to the implementation dependent pragmas and attributes, and the +implementation advice, there are a number of other Ada features that are +potentially implementation dependent and are designated as +implementation-defined. These are mentioned throughout the Ada Reference +Manual, and are summarized in Annex M. + +A requirement for conforming Ada compilers is that they provide +documentation describing how the implementation deals with each of these +issues. In this chapter you will find each point in Annex M listed, +followed by a description of how GNAT +handles the implementation dependence. + +You can use this chapter as a guide to minimizing implementation +dependent features in your programs if portability to other compilers +and other operating systems is an important consideration. The numbers +in each entry below correspond to the paragraph numbers in the Ada +Reference Manual. + +* + "Whether or not each recommendation given in Implementation + Advice is followed. See 1.1.2(37)." + +See :ref:`Implementation_Advice`. + +* + "Capacity limitations of the implementation. See 1.1.3(3)." + +The complexity of programs that can be processed is limited only by the +total amount of available virtual memory, and disk space for the +generated object files. + +* + "Variations from the standard that are impractical to avoid + given the implementation's execution environment. See 1.1.3(6)." + +There are no variations from the standard. + +* + "Which code_statements cause external + interactions. See 1.1.3(10)." + +Any `code_statement` can potentially cause external interactions. + +* + "The coded representation for the text of an Ada + program. See 2.1(4)." + +See separate section on source representation. + +* + "The control functions allowed in comments. See 2.1(14)." + +See separate section on source representation. + +* + "The representation for an end of line. See 2.2(2)." + +See separate section on source representation. + +* + "Maximum supported line length and lexical element + length. See 2.2(15)." + +The maximum line length is 255 characters and the maximum length of +a lexical element is also 255 characters. This is the default setting +if not overridden by the use of compiler switch *-gnaty* (which +sets the maximum to 79) or *-gnatyMnn* which allows the maximum +line length to be specified to be any value up to 32767. The maximum +length of a lexical element is the same as the maximum line length. + +* + "Implementation defined pragmas. See 2.8(14)." + +See :ref:`Implementation_Defined_Pragmas`. + +* + "Effect of pragma `Optimize`. See 2.8(27)." + +Pragma `Optimize`, if given with a `Time` or `Space` +parameter, checks that the optimization flag is set, and aborts if it is +not. + +* + "The sequence of characters of the value returned by + ``S'Image`` when some of the graphic characters of + ``S'Wide_Image`` are not defined in `Character`. See + 3.5(37)." + +The sequence of characters is as defined by the wide character encoding +method used for the source. See section on source representation for +further details. + +* + "The predefined integer types declared in + `Standard`. See 3.5.4(25)." + +====================== ======================================= +Type Representation +====================== ======================================= +*Short_Short_Integer* 8 bit signed +*Short_Integer* (Short) 16 bit signed +*Integer* 32 bit signed +*Long_Integer* 64 bit signed (on most 64 bit targets, + depending on the C definition of long). + 32 bit signed (all other targets) +*Long_Long_Integer* 64 bit signed +====================== ======================================= + +* + "Any nonstandard integer types and the operators defined + for them. See 3.5.4(26)." + +There are no nonstandard integer types. + +* + "Any nonstandard real types and the operators defined for + them. See 3.5.6(8)." + +There are no nonstandard real types. + +* + "What combinations of requested decimal precision and range + are supported for floating point types. See 3.5.7(7)." + +The precision and range is as defined by the IEEE standard. + +* + "The predefined floating point types declared in + `Standard`. See 3.5.7(16)." + +====================== ==================================================== +Type Representation +====================== ==================================================== +*Short_Float* 32 bit IEEE short +*Float* (Short) 32 bit IEEE short +*Long_Float* 64 bit IEEE long +*Long_Long_Float* 64 bit IEEE long (80 bit IEEE long on x86 processors) +====================== ==================================================== + +* + "The small of an ordinary fixed point type. See 3.5.9(8)." + +`Fine_Delta` is 2**(-63) + +* + "What combinations of small, range, and digits are + supported for fixed point types. See 3.5.9(10)." + +Any combinations are permitted that do not result in a small less than +`Fine_Delta` and do not result in a mantissa larger than 63 bits. +If the mantissa is larger than 53 bits on machines where Long_Long_Float +is 64 bits (true of all architectures except ia32), then the output from +Text_IO is accurate to only 53 bits, rather than the full mantissa. This +is because floating-point conversions are used to convert fixed point. + + +* + "The result of `Tags.Expanded_Name` for types declared + within an unnamed `block_statement`. See 3.9(10)." + +Block numbers of the form `B`nnn``, where `nnn` is a +decimal integer are allocated. + +* + "Implementation-defined attributes. See 4.1.4(12)." + +See :ref:`Implementation_Defined_Attributes`. + +* + "Any implementation-defined time types. See 9.6(6)." + +There are no implementation-defined time types. + +* + "The time base associated with relative delays." + +See 9.6(20). The time base used is that provided by the C library +function `gettimeofday`. + +* + "The time base of the type `Calendar.Time`. See + 9.6(23)." + +The time base used is that provided by the C library function +`gettimeofday`. + +* + "The time zone used for package `Calendar` + operations. See 9.6(24)." + +The time zone used by package `Calendar` is the current system time zone +setting for local time, as accessed by the C library function +`localtime`. + +* + "Any limit on `delay_until_statements` of + `select_statements`. See 9.6(29)." + +There are no such limits. + +* + "Whether or not two non-overlapping parts of a composite + object are independently addressable, in the case where packing, record + layout, or `Component_Size` is specified for the object. See + 9.10(1)." + +Separate components are independently addressable if they do not share +overlapping storage units. + +* + "The representation for a compilation. See 10.1(2)." + +A compilation is represented by a sequence of files presented to the +compiler in a single invocation of the *gcc* command. + +* + "Any restrictions on compilations that contain multiple + compilation_units. See 10.1(4)." + +No single file can contain more than one compilation unit, but any +sequence of files can be presented to the compiler as a single +compilation. + +* + "The mechanisms for creating an environment and for adding + and replacing compilation units. See 10.1.4(3)." + +See separate section on compilation model. + +* + "The manner of explicitly assigning library units to a + partition. See 10.2(2)." + +If a unit contains an Ada main program, then the Ada units for the partition +are determined by recursive application of the rules in the Ada Reference +Manual section 10.2(2-6). In other words, the Ada units will be those that +are needed by the main program, and then this definition of need is applied +recursively to those units, and the partition contains the transitive +closure determined by this relationship. In short, all the necessary units +are included, with no need to explicitly specify the list. If additional +units are required, e.g., by foreign language units, then all units must be +mentioned in the context clause of one of the needed Ada units. + +If the partition contains no main program, or if the main program is in +a language other than Ada, then GNAT +provides the binder options *-z* and *-n* respectively, and in +this case a list of units can be explicitly supplied to the binder for +inclusion in the partition (all units needed by these units will also +be included automatically). For full details on the use of these +options, refer to the `GNAT Make Program gnatmake` in the +:title:`GNAT User's Guide`. + +* + "The implementation-defined means, if any, of specifying + which compilation units are needed by a given compilation unit. See + 10.2(2)." + +The units needed by a given compilation unit are as defined in +the Ada Reference Manual section 10.2(2-6). There are no +implementation-defined pragmas or other implementation-defined +means for specifying needed units. + +* + "The manner of designating the main subprogram of a + partition. See 10.2(7)." + +The main program is designated by providing the name of the +corresponding :file:`ALI` file as the input parameter to the binder. + +* + "The order of elaboration of `library_items`. See + 10.2(18)." + +The first constraint on ordering is that it meets the requirements of +Chapter 10 of the Ada Reference Manual. This still leaves some +implementation dependent choices, which are resolved by first +elaborating bodies as early as possible (i.e., in preference to specs +where there is a choice), and second by evaluating the immediate with +clauses of a unit to determine the probably best choice, and +third by elaborating in alphabetical order of unit names +where a choice still remains. + +* + "Parameter passing and function return for the main + subprogram. See 10.2(21)." + +The main program has no parameters. It may be a procedure, or a function +returning an integer type. In the latter case, the returned integer +value is the return code of the program (overriding any value that +may have been set by a call to `Ada.Command_Line.Set_Exit_Status`). + +* + "The mechanisms for building and running partitions. See + 10.2(24)." + +GNAT itself supports programs with only a single partition. The GNATDIST +tool provided with the GLADE package (which also includes an implementation +of the PCS) provides a completely flexible method for building and running +programs consisting of multiple partitions. See the separate GLADE manual +for details. + +* + "The details of program execution, including program + termination. See 10.2(25)." + +See separate section on compilation model. + +* + "The semantics of any non-active partitions supported by the + implementation. See 10.2(28)." + +Passive partitions are supported on targets where shared memory is +provided by the operating system. See the GLADE reference manual for +further details. + +* + "The information returned by `Exception_Message`. See + 11.4.1(10)." + +Exception message returns the null string unless a specific message has +been passed by the program. + +* + "The result of `Exceptions.Exception_Name` for types + declared within an unnamed `block_statement`. See 11.4.1(12)." + +Blocks have implementation defined names of the form `B`nnn`` +where `nnn` is an integer. + +* + "The information returned by + `Exception_Information`. See 11.4.1(13)." + +`Exception_Information` returns a string in the following format:: + + *Exception_Name:* nnnnn + *Message:* mmmmm + *PID:* ppp + *Load address:* 0xhhhh + *Call stack traceback locations:* + 0xhhhh 0xhhhh 0xhhhh ... 0xhhh + +where + + * `nnnn` is the fully qualified name of the exception in all upper + case letters. This line is always present. + + * `mmmm` is the message (this line present only if message is non-null) + + * `ppp` is the Process Id value as a decimal integer (this line is + present only if the Process Id is nonzero). Currently we are + not making use of this field. + + * The Load address line, the Call stack traceback locations line and the + following values are present only if at least one traceback location was + recorded. The Load address indicates the address at which the main executable + was loaded; this line may not be present if operating system hasn't relocated + the main executable. The values are given in C style format, with lower case + letters for a-f, and only as many digits present as are necessary. + The line terminator sequence at the end of each line, including + the last line is a single `LF` character (`16#0A#`). + +* + "Implementation-defined check names. See 11.5(27)." + +The implementation defined check name Alignment_Check controls checking of +address clause values for proper alignment (that is, the address supplied +must be consistent with the alignment of the type). + +The implementation defined check name Predicate_Check controls whether +predicate checks are generated. + +The implementation defined check name Validity_Check controls whether +validity checks are generated. + +In addition, a user program can add implementation-defined check names +by means of the pragma Check_Name. + +* + "The interpretation of each aspect of representation. See + 13.1(20)." + +See separate section on data representations. + +* + "Any restrictions placed upon representation items. See + 13.1(20)." + +See separate section on data representations. + +* + "The meaning of `Size` for indefinite subtypes. See + 13.3(48)." + +Size for an indefinite subtype is the maximum possible size, except that +for the case of a subprogram parameter, the size of the parameter object +is the actual size. + +* + "The default external representation for a type tag. See + 13.3(75)." + +The default external representation for a type tag is the fully expanded +name of the type in upper case letters. + +* + "What determines whether a compilation unit is the same in + two different partitions. See 13.3(76)." + +A compilation unit is the same in two different partitions if and only +if it derives from the same source file. + +* + "Implementation-defined components. See 13.5.1(15)." + +The only implementation defined component is the tag for a tagged type, +which contains a pointer to the dispatching table. + +* + "If `Word_Size` = `Storage_Unit`, the default bit + ordering. See 13.5.3(5)." + +`Word_Size` (32) is not the same as `Storage_Unit` (8) for this +implementation, so no non-default bit ordering is supported. The default +bit ordering corresponds to the natural endianness of the target architecture. + +* + "The contents of the visible part of package `System` + and its language-defined children. See 13.7(2)." + +See the definition of these packages in files :file:`system.ads` and +:file:`s-stoele.ads`. Note that two declarations are added to package +System. + +.. code-block:: ada + + Max_Priority : constant Positive := Priority'Last; + Max_Interrupt_Priority : constant Positive := Interrupt_Priority'Last; + +* + "The contents of the visible part of package + `System.Machine_Code`, and the meaning of + `code_statements`. See 13.8(7)." + +See the definition and documentation in file :file:`s-maccod.ads`. + +* + "The effect of unchecked conversion. See 13.9(11)." + +Unchecked conversion between types of the same size +results in an uninterpreted transmission of the bits from one type +to the other. If the types are of unequal sizes, then in the case of +discrete types, a shorter source is first zero or sign extended as +necessary, and a shorter target is simply truncated on the left. +For all non-discrete types, the source is first copied if necessary +to ensure that the alignment requirements of the target are met, then +a pointer is constructed to the source value, and the result is obtained +by dereferencing this pointer after converting it to be a pointer to the +target type. Unchecked conversions where the target subtype is an +unconstrained array are not permitted. If the target alignment is +greater than the source alignment, then a copy of the result is +made with appropriate alignment + +* + "The semantics of operations on invalid representations. + See 13.9.2(10-11)." + +For assignments and other operations where the use of invalid values cannot +result in erroneous behavior, the compiler ignores the possibility of invalid +values. An exception is raised at the point where an invalid value would +result in erroneous behavior. For example executing: + +.. code-block:: ada + + procedure invalidvals is + X : Integer := -1; + Y : Natural range 1 .. 10; + for Y'Address use X'Address; + Z : Natural range 1 .. 10; + A : array (Natural range 1 .. 10) of Integer; + begin + Z := Y; -- no exception + A (Z) := 3; -- exception raised; + end; + +As indicated, an exception is raised on the array assignment, but not +on the simple assignment of the invalid negative value from Y to Z. + +* + "The manner of choosing a storage pool for an access type + when `Storage_Pool` is not specified for the type. See 13.11(17)." + +There are 3 different standard pools used by the compiler when +`Storage_Pool` is not specified depending whether the type is local +to a subprogram or defined at the library level and whether +`Storage_Size`is specified or not. See documentation in the runtime +library units `System.Pool_Global`, `System.Pool_Size` and +`System.Pool_Local` in files :file:`s-poosiz.ads`, +:file:`s-pooglo.ads` and :file:`s-pooloc.ads` for full details on the +default pools used. + +* + "Whether or not the implementation provides user-accessible + names for the standard pool type(s). See 13.11(17)." + +See documentation in the sources of the run time mentioned in the previous +paragraph. All these pools are accessible by means of `with`'ing +these units. + +* + "The meaning of `Storage_Size`. See 13.11(18)." + +`Storage_Size` is measured in storage units, and refers to the +total space available for an access type collection, or to the primary +stack space for a task. + +* + "Implementation-defined aspects of storage pools. See + 13.11(22)." + +See documentation in the sources of the run time mentioned in the +paragraph about standard storage pools above +for details on GNAT-defined aspects of storage pools. + +* + "The set of restrictions allowed in a pragma + `Restrictions`. See 13.12(7)." + +See :ref:`Standard_and_Implementation_Defined_Restrictions`. + +* + "The consequences of violating limitations on + `Restrictions` pragmas. See 13.12(9)." + +Restrictions that can be checked at compile time result in illegalities +if violated. Currently there are no other consequences of violating +restrictions. + +* + "The representation used by the `Read` and + `Write` attributes of elementary types in terms of stream + elements. See 13.13.2(9)." + +The representation is the in-memory representation of the base type of +the type, using the number of bits corresponding to the +``type'Size`` value, and the natural ordering of the machine. + +* + "The names and characteristics of the numeric subtypes + declared in the visible part of package `Standard`. See A.1(3)." + +See items describing the integer and floating-point types supported. + +* + "The string returned by `Character_Set_Version`. + See A.3.5(3)." + +`Ada.Wide_Characters.Handling.Character_Set_Version` returns +the string "Unicode 4.0", referring to version 4.0 of the +Unicode specification. + +* + "The accuracy actually achieved by the elementary + functions. See A.5.1(1)." + +The elementary functions correspond to the functions available in the C +library. Only fast math mode is implemented. + +* + "The sign of a zero result from some of the operators or + functions in `Numerics.Generic_Elementary_Functions`, when + `Float_Type'Signed_Zeros` is `True`. See A.5.1(46)." + +The sign of zeroes follows the requirements of the IEEE 754 standard on +floating-point. + +* + "The value of + `Numerics.Float_Random.Max_Image_Width`. See A.5.2(27)." + +Maximum image width is 6864, see library file :file:`s-rannum.ads`. + +* + "The value of + `Numerics.Discrete_Random.Max_Image_Width`. See A.5.2(27)." + +Maximum image width is 6864, see library file :file:`s-rannum.ads`. + +* + "The algorithms for random number generation. See + A.5.2(32)." + +The algorithm is the Mersenne Twister, as documented in the source file +:file:`s-rannum.adb`. This version of the algorithm has a period of +2**19937-1. + +* + "The string representation of a random number generator's + state. See A.5.2(38)." + +The value returned by the Image function is the concatenation of +the fixed-width decimal representations of the 624 32-bit integers +of the state vector. + +* + "The minimum time interval between calls to the + time-dependent Reset procedure that are guaranteed to initiate different + random number sequences. See A.5.2(45)." + +The minimum period between reset calls to guarantee distinct series of +random numbers is one microsecond. + +* + "The values of the `Model_Mantissa`, + `Model_Emin`, `Model_Epsilon`, `Model`, + `Safe_First`, and `Safe_Last` attributes, if the Numerics + Annex is not supported. See A.5.3(72)." + +Run the compiler with *-gnatS* to produce a listing of package +`Standard`, has the values of all numeric attributes. + +* + "Any implementation-defined characteristics of the + input-output packages. See A.7(14)." + +There are no special implementation defined characteristics for these +packages. + +* + "The value of `Buffer_Size` in `Storage_IO`. See + A.9(10)." + +All type representations are contiguous, and the `Buffer_Size` is +the value of ``type'Size`` rounded up to the next storage unit +boundary. + +* + "External files for standard input, standard output, and + standard error See A.10(5)." + +These files are mapped onto the files provided by the C streams +libraries. See source file :file:`i-cstrea.ads` for further details. + +* + "The accuracy of the value produced by `Put`. See + A.10.9(36)." + +If more digits are requested in the output than are represented by the +precision of the value, zeroes are output in the corresponding least +significant digit positions. + +* + "The meaning of `Argument_Count`, `Argument`, and + `Command_Name`. See A.15(1)." + +These are mapped onto the `argv` and `argc` parameters of the +main program in the natural manner. + +* + "The interpretation of the `Form` parameter in procedure + `Create_Directory`. See A.16(56)." + +The `Form` parameter is not used. + +* + "The interpretation of the `Form` parameter in procedure + `Create_Path`. See A.16(60)." + +The `Form` parameter is not used. + +* + "The interpretation of the `Form` parameter in procedure + `Copy_File`. See A.16(68)." + +The `Form` parameter is case-insensitive. +Two fields are recognized in the `Form` parameter:: + + *preserve=<value>* + *mode=<value>* + +<value> starts immediately after the character '=' and ends with the +character immediately preceding the next comma (',') or with the last +character of the parameter. + +The only possible values for preserve= are: + +================== =================================================================== +Value Meaning +================== =================================================================== +*no_attributes* Do not try to preserve any file attributes. This is the + default if no preserve= is found in Form. +*all_attributes* Try to preserve all file attributes (timestamps, access rights). +*timestamps* Preserve the timestamp of the copied file, but not the other + file attributes. +================== =================================================================== + +The only possible values for mode= are: + +============== =============================================================================== +Value Meaning +============== =============================================================================== +*copy* Only do the copy if the destination file does not already exist. + If it already exists, Copy_File fails. +*overwrite* Copy the file in all cases. Overwrite an already existing destination file. +*append* Append the original file to the destination file. If the destination file + does not exist, the destination file is a copy of the source file. + When mode=append, the field preserve=, if it exists, is not taken into account. +============== =============================================================================== + +If the Form parameter includes one or both of the fields and the value or +values are incorrect, Copy_file fails with Use_Error. + +Examples of correct Forms:: + + Form => "preserve=no_attributes,mode=overwrite" (the default) + Form => "mode=append" + Form => "mode=copy, preserve=all_attributes" + +Examples of incorrect Forms:: + + Form => "preserve=junk" + Form => "mode=internal, preserve=timestamps" + +* + "The interpretation of the `Pattern` parameter, when not the null string, + in the `Start_Search` and `Search` procedures. + See A.16(104) and A.16(112)." + +When the `Pattern` parameter is not the null string, it is interpreted +according to the syntax of regular expressions as defined in the +`GNAT.Regexp` package. + +See :ref:`GNAT.Regexp_(g-regexp.ads)`. + +* + "Implementation-defined convention names. See B.1(11)." + +The following convention names are supported + +======================= ============================================================================== +Convention Name Interpretation +======================= ============================================================================== +*Ada* Ada +*Ada_Pass_By_Copy* Allowed for any types except by-reference types such as limited + records. Compatible with convention Ada, but causes any parameters + with this convention to be passed by copy. +*Ada_Pass_By_Reference* Allowed for any types except by-copy types such as scalars. + Compatible with convention Ada, but causes any parameters + with this convention to be passed by reference. +*Assembler* Assembly language +*Asm* Synonym for Assembler +*Assembly* Synonym for Assembler +*C* C +*C_Pass_By_Copy* Allowed only for record types, like C, but also notes that record + is to be passed by copy rather than reference. +*COBOL* COBOL +*C_Plus_Plus (or CPP)* C++ +*Default* Treated the same as C +*External* Treated the same as C +*Fortran* Fortran +*Intrinsic* For support of pragma `Import` with convention Intrinsic, see + separate section on Intrinsic Subprograms. +*Stdcall* Stdcall (used for Windows implementations only). This convention correspond + to the WINAPI (previously called Pascal convention) C/C++ convention under + Windows. A routine with this convention cleans the stack before + exit. This pragma cannot be applied to a dispatching call. +*DLL* Synonym for Stdcall +*Win32* Synonym for Stdcall +*Stubbed* Stubbed is a special convention used to indicate that the body of the + subprogram will be entirely ignored. Any call to the subprogram + is converted into a raise of the `Program_Error` exception. If a + pragma `Import` specifies convention `stubbed` then no body need + be present at all. This convention is useful during development for the + inclusion of subprograms whose body has not yet been written. + In addition, all otherwise unrecognized convention names are also + treated as being synonymous with convention C. In all implementations + except for VMS, use of such other names results in a warning. In VMS + implementations, these names are accepted silently. +======================= ============================================================================== + +* + "The meaning of link names. See B.1(36)." + +Link names are the actual names used by the linker. + +* + "The manner of choosing link names when neither the link + name nor the address of an imported or exported entity is specified. See + B.1(36)." + +The default linker name is that which would be assigned by the relevant +external language, interpreting the Ada name as being in all lower case +letters. + +* + "The effect of pragma `Linker_Options`. See B.1(37)." + +The string passed to `Linker_Options` is presented uninterpreted as +an argument to the link command, unless it contains ASCII.NUL characters. +NUL characters if they appear act as argument separators, so for example + +.. code-block:: ada + + pragma Linker_Options ("-labc" & ASCII.NUL & "-ldef"); + +causes two separate arguments `-labc` and `-ldef` to be passed to the +linker. The order of linker options is preserved for a given unit. The final +list of options passed to the linker is in reverse order of the elaboration +order. For example, linker options for a body always appear before the options +from the corresponding package spec. + +* + "The contents of the visible part of package + `Interfaces` and its language-defined descendants. See B.2(1)." + +See files with prefix :file:`i-` in the distributed library. + +* + "Implementation-defined children of package + `Interfaces`. The contents of the visible part of package + `Interfaces`. See B.2(11)." + +See files with prefix :file:`i-` in the distributed library. + +* + "The types `Floating`, `Long_Floating`, + `Binary`, `Long_Binary`, `Decimal_ Element`, and + `COBOL_Character`; and the initialization of the variables + `Ada_To_COBOL` and `COBOL_To_Ada`, in + `Interfaces.COBOL`. See B.4(50)." + +===================== ==================================== +COBOL Ada +===================== ==================================== +*Floating* Float +*Long_Floating* (Floating) Long_Float +*Binary* Integer +*Long_Binary* Long_Long_Integer +*Decimal_Element* Character +*COBOL_Character* Character +===================== ==================================== + +For initialization, see the file :file:`i-cobol.ads` in the distributed library. + +* + "Support for access to machine instructions. See C.1(1)." + +See documentation in file :file:`s-maccod.ads` in the distributed library. + +* + "Implementation-defined aspects of access to machine + operations. See C.1(9)." + +See documentation in file :file:`s-maccod.ads` in the distributed library. + +* + "Implementation-defined aspects of interrupts. See C.3(2)." + +Interrupts are mapped to signals or conditions as appropriate. See +definition of unit +`Ada.Interrupt_Names` in source file :file:`a-intnam.ads` for details +on the interrupts supported on a particular target. + +* + "Implementation-defined aspects of pre-elaboration. See + C.4(13)." + +GNAT does not permit a partition to be restarted without reloading, +except under control of the debugger. + +* + "The semantics of pragma `Discard_Names`. See C.5(7)." + +Pragma `Discard_Names` causes names of enumeration literals to +be suppressed. In the presence of this pragma, the Image attribute +provides the image of the Pos of the literal, and Value accepts +Pos values. + +* + "The result of the `Task_Identification.Image` + attribute. See C.7.1(7)." + +The result of this attribute is a string that identifies +the object or component that denotes a given task. If a variable `Var` +has a task type, the image for this task will have the form `Var_`XXXXXXXX``, +where the suffix +is the hexadecimal representation of the virtual address of the corresponding +task control block. If the variable is an array of tasks, the image of each +task will have the form of an indexed component indicating the position of a +given task in the array, e.g., `Group(5)_`XXXXXXX``. If the task is a +component of a record, the image of the task will have the form of a selected +component. These rules are fully recursive, so that the image of a task that +is a subcomponent of a composite object corresponds to the expression that +designates this task. + +If a task is created by an allocator, its image depends on the context. If the +allocator is part of an object declaration, the rules described above are used +to construct its image, and this image is not affected by subsequent +assignments. If the allocator appears within an expression, the image +includes only the name of the task type. + +If the configuration pragma Discard_Names is present, or if the restriction +No_Implicit_Heap_Allocation is in effect, the image reduces to +the numeric suffix, that is to say the hexadecimal representation of the +virtual address of the control block of the task. + +* + "The value of `Current_Task` when in a protected entry + or interrupt handler. See C.7.1(17)." + +Protected entries or interrupt handlers can be executed by any +convenient thread, so the value of `Current_Task` is undefined. + +* + "The effect of calling `Current_Task` from an entry + body or interrupt handler. See C.7.1(19)." + +The effect of calling `Current_Task` from an entry body or +interrupt handler is to return the identification of the task currently +executing the code. + +* + "Implementation-defined aspects of + `Task_Attributes`. See C.7.2(19)." + +There are no implementation-defined aspects of `Task_Attributes`. + +* + "Values of all `Metrics`. See D(2)." + +The metrics information for GNAT depends on the performance of the +underlying operating system. The sources of the run-time for tasking +implementation, together with the output from *-gnatG* can be +used to determine the exact sequence of operating systems calls made +to implement various tasking constructs. Together with appropriate +information on the performance of the underlying operating system, +on the exact target in use, this information can be used to determine +the required metrics. + +* + "The declarations of `Any_Priority` and + `Priority`. See D.1(11)." + +See declarations in file :file:`system.ads`. + +* + "Implementation-defined execution resources. See D.1(15)." + +There are no implementation-defined execution resources. + +* + "Whether, on a multiprocessor, a task that is waiting for + access to a protected object keeps its processor busy. See D.2.1(3)." + +On a multi-processor, a task that is waiting for access to a protected +object does not keep its processor busy. + +* + "The affect of implementation defined execution resources + on task dispatching. See D.2.1(9)." + +Tasks map to threads in the threads package used by GNAT. Where possible +and appropriate, these threads correspond to native threads of the +underlying operating system. + +* + "Implementation-defined `policy_identifiers` allowed + in a pragma `Task_Dispatching_Policy`. See D.2.2(3)." + +There are no implementation-defined policy-identifiers allowed in this +pragma. + +* + "Implementation-defined aspects of priority inversion. See + D.2.2(16)." + +Execution of a task cannot be preempted by the implementation processing +of delay expirations for lower priority tasks. + +* + "Implementation-defined task dispatching. See D.2.2(18)." + +The policy is the same as that of the underlying threads implementation. + +* + "Implementation-defined `policy_identifiers` allowed + in a pragma `Locking_Policy`. See D.3(4)." + +The two implementation defined policies permitted in GNAT are +`Inheritance_Locking` and `Conccurent_Readers_Locking`. On +targets that support the `Inheritance_Locking` policy, locking is +implemented by inheritance, i.e., the task owning the lock operates +at a priority equal to the highest priority of any task currently +requesting the lock. On targets that support the +`Conccurent_Readers_Locking` policy, locking is implemented with a +read/write lock allowing multiple propected object functions to enter +concurrently. + +* + "Default ceiling priorities. See D.3(10)." + +The ceiling priority of protected objects of the type +`System.Interrupt_Priority'Last` as described in the Ada +Reference Manual D.3(10), + +* + "The ceiling of any protected object used internally by + the implementation. See D.3(16)." + +The ceiling priority of internal protected objects is +`System.Priority'Last`. + +* + "Implementation-defined queuing policies. See D.4(1)." + +There are no implementation-defined queuing policies. + +* + "On a multiprocessor, any conditions that cause the + completion of an aborted construct to be delayed later than what is + specified for a single processor. See D.6(3)." + +The semantics for abort on a multi-processor is the same as on a single +processor, there are no further delays. + +* + "Any operations that implicitly require heap storage + allocation. See D.7(8)." + +The only operation that implicitly requires heap storage allocation is +task creation. + +* + "What happens when a task terminates in the presence of + pragma `No_Task_Termination`. See D.7(15)." + +Execution is erroneous in that case. + +* + "Implementation-defined aspects of pragma + `Restrictions`. See D.7(20)." + +There are no such implementation-defined aspects. + +* + "Implementation-defined aspects of package + `Real_Time`. See D.8(17)." + +There are no implementation defined aspects of package `Real_Time`. + +* + "Implementation-defined aspects of + `delay_statements`. See D.9(8)." + +Any difference greater than one microsecond will cause the task to be +delayed (see D.9(7)). + +* + "The upper bound on the duration of interrupt blocking + caused by the implementation. See D.12(5)." + +The upper bound is determined by the underlying operating system. In +no cases is it more than 10 milliseconds. + +* + "The means for creating and executing distributed + programs. See E(5)." + +The GLADE package provides a utility GNATDIST for creating and executing +distributed programs. See the GLADE reference manual for further details. + +* + "Any events that can result in a partition becoming + inaccessible. See E.1(7)." + +See the GLADE reference manual for full details on such events. + +* + "The scheduling policies, treatment of priorities, and + management of shared resources between partitions in certain cases. See + E.1(11)." + +See the GLADE reference manual for full details on these aspects of +multi-partition execution. + +* + "Events that cause the version of a compilation unit to + change. See E.3(5)." + +Editing the source file of a compilation unit, or the source files of +any units on which it is dependent in a significant way cause the version +to change. No other actions cause the version number to change. All changes +are significant except those which affect only layout, capitalization or +comments. + +* + "Whether the execution of the remote subprogram is + immediately aborted as a result of cancellation. See E.4(13)." + +See the GLADE reference manual for details on the effect of abort in +a distributed application. + +* + "Implementation-defined aspects of the PCS. See E.5(25)." + +See the GLADE reference manual for a full description of all implementation +defined aspects of the PCS. + +* + "Implementation-defined interfaces in the PCS. See + E.5(26)." + +See the GLADE reference manual for a full description of all +implementation defined interfaces. + +* + "The values of named numbers in the package + `Decimal`. See F.2(7)." + +==================== ========== +Named Number Value +==================== ========== +*Max_Scale* +18 +*Min_Scale* -18 +*Min_Delta* 1.0E-18 +*Max_Delta* 1.0E+18 +*Max_Decimal_Digits* 18 +==================== ========== + +* + "The value of `Max_Picture_Length` in the package + `Text_IO.Editing`. See F.3.3(16)." + +64 + +* + "The value of `Max_Picture_Length` in the package + `Wide_Text_IO.Editing`. See F.3.4(5)." + +64 + +* + "The accuracy actually achieved by the complex elementary + functions and by other complex arithmetic operations. See G.1(1)." + +Standard library functions are used for the complex arithmetic +operations. Only fast math mode is currently supported. + +* + "The sign of a zero result (or a component thereof) from + any operator or function in `Numerics.Generic_Complex_Types`, when + `Real'Signed_Zeros` is True. See G.1.1(53)." + +The signs of zero values are as recommended by the relevant +implementation advice. + +* + "The sign of a zero result (or a component thereof) from + any operator or function in + `Numerics.Generic_Complex_Elementary_Functions`, when + `Real'Signed_Zeros` is `True`. See G.1.2(45)." + +The signs of zero values are as recommended by the relevant +implementation advice. + +* + "Whether the strict mode or the relaxed mode is the + default. See G.2(2)." + +The strict mode is the default. There is no separate relaxed mode. GNAT +provides a highly efficient implementation of strict mode. + +* + "The result interval in certain cases of fixed-to-float + conversion. See G.2.1(10)." + +For cases where the result interval is implementation dependent, the +accuracy is that provided by performing all operations in 64-bit IEEE +floating-point format. + +* + "The result of a floating point arithmetic operation in + overflow situations, when the `Machine_Overflows` attribute of the + result type is `False`. See G.2.1(13)." + +Infinite and NaN values are produced as dictated by the IEEE +floating-point standard. +Note that on machines that are not fully compliant with the IEEE +floating-point standard, such as Alpha, the *-mieee* compiler flag +must be used for achieving IEEE conforming behavior (although at the cost +of a significant performance penalty), so infinite and NaN values are +properly generated. + +* + "The result interval for division (or exponentiation by a + negative exponent), when the floating point hardware implements division + as multiplication by a reciprocal. See G.2.1(16)." + +Not relevant, division is IEEE exact. + +* + "The definition of close result set, which determines the + accuracy of certain fixed point multiplications and divisions. See + G.2.3(5)." + +Operations in the close result set are performed using IEEE long format +floating-point arithmetic. The input operands are converted to +floating-point, the operation is done in floating-point, and the result +is converted to the target type. + +* + "Conditions on a `universal_real` operand of a fixed + point multiplication or division for which the result shall be in the + perfect result set. See G.2.3(22)." + +The result is only defined to be in the perfect result set if the result +can be computed by a single scaling operation involving a scale factor +representable in 64-bits. + +* + "The result of a fixed point arithmetic operation in + overflow situations, when the `Machine_Overflows` attribute of the + result type is `False`. See G.2.3(27)." + +Not relevant, `Machine_Overflows` is `True` for fixed-point +types. + +* + "The result of an elementary function reference in + overflow situations, when the `Machine_Overflows` attribute of the + result type is `False`. See G.2.4(4)." + +IEEE infinite and Nan values are produced as appropriate. + +* + "The value of the angle threshold, within which certain + elementary functions, complex arithmetic operations, and complex + elementary functions yield results conforming to a maximum relative + error bound. See G.2.4(10)." + +Information on this subject is not yet available. + +* + "The accuracy of certain elementary functions for + parameters beyond the angle threshold. See G.2.4(10)." + +Information on this subject is not yet available. + +* + "The result of a complex arithmetic operation or complex + elementary function reference in overflow situations, when the + `Machine_Overflows` attribute of the corresponding real type is + `False`. See G.2.6(5)." + +IEEE infinite and Nan values are produced as appropriate. + +* + "The accuracy of certain complex arithmetic operations and + certain complex elementary functions for parameters (or components + thereof) beyond the angle threshold. See G.2.6(8)." + +Information on those subjects is not yet available. + +* + "Information regarding bounded errors and erroneous + execution. See H.2(1)." + +Information on this subject is not yet available. + +* + "Implementation-defined aspects of pragma + `Inspection_Point`. See H.3.2(8)." + +Pragma `Inspection_Point` ensures that the variable is live and can +be examined by the debugger at the inspection point. + +* + "Implementation-defined aspects of pragma + `Restrictions`. See H.4(25)." + +There are no implementation-defined aspects of pragma `Restrictions`. The +use of pragma `Restrictions [No_Exceptions]` has no effect on the +generated code. Checks must suppressed by use of pragma `Suppress`. + +* + "Any restrictions on pragma `Restrictions`. See + H.4(27)." + +There are no restrictions on pragma `Restrictions`. diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst new file mode 100644 index 00000000000..a1147adca1c --- /dev/null +++ b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @@ -0,0 +1,6887 @@ +.. _Implementation_Defined_Pragmas: + +****************************** +Implementation Defined Pragmas +****************************** + +Ada defines a set of pragmas that can be used to supply additional +information to the compiler. These language defined pragmas are +implemented in GNAT and work as described in the Ada Reference Manual. + +In addition, Ada allows implementations to define additional pragmas +whose meaning is defined by the implementation. GNAT provides a number +of these implementation-defined pragmas, which can be used to extend +and enhance the functionality of the compiler. This section of the GNAT +Reference Manual describes these additional pragmas. + +Note that any program using these pragmas might not be portable to other +compilers (although GNAT implements this set of pragmas on all +platforms). Therefore if portability to other compilers is an important +consideration, the use of these pragmas should be minimized. + +Pragma Abort_Defer +================== + +.. index:: Deferring aborts + +Syntax: + +.. code-block:: ada + + pragma Abort_Defer; + + +This pragma must appear at the start of the statement sequence of a +handled sequence of statements (right after the `begin`). It has +the effect of deferring aborts for the sequence of statements (but not +for the declarations or handlers, if any, associated with this statement +sequence). + +Pragma Abstract_State +===================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.1.4. + +Pragma Ada_83 +============= + +Syntax: + +.. code-block:: ada + + pragma Ada_83; + + +A configuration pragma that establishes Ada 83 mode for the unit to +which it applies, regardless of the mode set by the command line +switches. In Ada 83 mode, GNAT attempts to be as compatible with +the syntax and semantics of Ada 83, as defined in the original Ada +83 Reference Manual as possible. In particular, the keywords added by Ada 95 +and Ada 2005 are not recognized, optional package bodies are allowed, +and generics may name types with unknown discriminants without using +the `(<>)` notation. In addition, some but not all of the additional +restrictions of Ada 83 are enforced. + +Ada 83 mode is intended for two purposes. Firstly, it allows existing +Ada 83 code to be compiled and adapted to GNAT with less effort. +Secondly, it aids in keeping code backwards compatible with Ada 83. +However, there is no guarantee that code that is processed correctly +by GNAT in Ada 83 mode will in fact compile and execute with an Ada +83 compiler, since GNAT does not enforce all the additional checks +required by Ada 83. + +Pragma Ada_95 +============= + +Syntax: + +.. code-block:: ada + + pragma Ada_95; + + +A configuration pragma that establishes Ada 95 mode for the unit to which +it applies, regardless of the mode set by the command line switches. +This mode is set automatically for the `Ada` and `System` +packages and their children, so you need not specify it in these +contexts. This pragma is useful when writing a reusable component that +itself uses Ada 95 features, but which is intended to be usable from +either Ada 83 or Ada 95 programs. + +Pragma Ada_05 +============= + +Syntax: + +.. code-block:: ada + + pragma Ada_05; + pragma Ada_05 (local_NAME); + + +A configuration pragma that establishes Ada 2005 mode for the unit to which +it applies, regardless of the mode set by the command line switches. +This pragma is useful when writing a reusable component that +itself uses Ada 2005 features, but which is intended to be usable from +either Ada 83 or Ada 95 programs. + +The one argument form (which is not a configuration pragma) +is used for managing the transition from +Ada 95 to Ada 2005 in the run-time library. If an entity is marked +as Ada_2005 only, then referencing the entity in Ada_83 or Ada_95 +mode will generate a warning. In addition, in Ada_83 or Ada_95 +mode, a preference rule is established which does not choose +such an entity unless it is unambiguously specified. This avoids +extra subprograms marked this way from generating ambiguities in +otherwise legal pre-Ada_2005 programs. The one argument form is +intended for exclusive use in the GNAT run-time library. + +Pragma Ada_2005 +=============== + +Syntax: + +.. code-block:: ada + + pragma Ada_2005; + + +This configuration pragma is a synonym for pragma Ada_05 and has the +same syntax and effect. + +Pragma Ada_12 +============= + +Syntax: + +.. code-block:: ada + + pragma Ada_12; + pragma Ada_12 (local_NAME); + + +A configuration pragma that establishes Ada 2012 mode for the unit to which +it applies, regardless of the mode set by the command line switches. +This mode is set automatically for the `Ada` and `System` +packages and their children, so you need not specify it in these +contexts. This pragma is useful when writing a reusable component that +itself uses Ada 2012 features, but which is intended to be usable from +Ada 83, Ada 95, or Ada 2005 programs. + +The one argument form, which is not a configuration pragma, +is used for managing the transition from Ada +2005 to Ada 2012 in the run-time library. If an entity is marked +as Ada_201 only, then referencing the entity in any pre-Ada_2012 +mode will generate a warning. In addition, in any pre-Ada_2012 +mode, a preference rule is established which does not choose +such an entity unless it is unambiguously specified. This avoids +extra subprograms marked this way from generating ambiguities in +otherwise legal pre-Ada_2012 programs. The one argument form is +intended for exclusive use in the GNAT run-time library. + +Pragma Ada_2012 +=============== + +Syntax: + +.. code-block:: ada + + pragma Ada_2012; + + +This configuration pragma is a synonym for pragma Ada_12 and has the +same syntax and effect. + +Pragma Allow_Integer_Address +============================ + +Syntax: + +.. code-block:: ada + + pragma Allow_Integer_Address; + + +In almost all versions of GNAT, `System.Address` is a private +type in accordance with the implementation advice in the RM. This +means that integer values, +in particular integer literals, are not allowed as address values. +If the configuration pragma +`Allow_Integer_Address` is given, then integer expressions may +be used anywhere a value of type `System.Address` is required. +The effect is to introduce an implicit unchecked conversion from the +integer value to type `System.Address`. The reverse case of using +an address where an integer type is required is handled analogously. +The following example compiles without errors: + + +.. code-block:: ada + + pragma Allow_Integer_Address; + with System; use System; + package AddrAsInt is + X : Integer; + Y : Integer; + for X'Address use 16#1240#; + for Y use at 16#3230#; + m : Address := 16#4000#; + n : constant Address := 4000; + p : constant Address := Address (X + Y); + v : Integer := y'Address; + w : constant Integer := Integer (Y'Address); + type R is new integer; + RR : R := 1000; + Z : Integer; + for Z'Address use RR; + end AddrAsInt; + + +Note that pragma `Allow_Integer_Address` is ignored if `System.Address` +is not a private type. In implementations of `GNAT` where +System.Address is a visible integer type, +this pragma serves no purpose but is ignored +rather than rejected to allow common sets of sources to be used +in the two situations. + +Pragma Annotate +=============== + +Syntax:: + + pragma Annotate (IDENTIFIER [, IDENTIFIER {, ARG}] [, entity => local_NAME]); + + ARG ::= NAME | EXPRESSION + + +This pragma is used to annotate programs. `identifier` identifies +the type of annotation. GNAT verifies that it is an identifier, but does +not otherwise analyze it. The second optional identifier is also left +unanalyzed, and by convention is used to control the action of the tool to +which the annotation is addressed. The remaining `arg` arguments +can be either string literals or more generally expressions. +String literals are assumed to be either of type +`Standard.String` or else `Wide_String` or `Wide_Wide_String` +depending on the character literals they contain. +All other kinds of arguments are analyzed as expressions, and must be +unambiguous. The last argument if present must have the identifier +`Entity` and GNAT verifies that a local name is given. + +The analyzed pragma is retained in the tree, but not otherwise processed +by any part of the GNAT compiler, except to generate corresponding note +lines in the generated ALI file. For the format of these note lines, see +the compiler source file lib-writ.ads. This pragma is intended for use by +external tools, including ASIS. The use of pragma Annotate does not +affect the compilation process in any way. This pragma may be used as +a configuration pragma. + +Pragma Assert +============= + +Syntax:: + + pragma Assert ( + boolean_EXPRESSION + [, string_EXPRESSION]); + + +The effect of this pragma depends on whether the corresponding command +line switch is set to activate assertions. The pragma expands into code +equivalent to the following: + +.. code-block:: ada + + if assertions-enabled then + if not boolean_EXPRESSION then + System.Assertions.Raise_Assert_Failure + (string_EXPRESSION); + end if; + end if; + + +The string argument, if given, is the message that will be associated +with the exception occurrence if the exception is raised. If no second +argument is given, the default message is `file`:`nnn`, +where `file` is the name of the source file containing the assert, +and `nnn` is the line number of the assert. A pragma is not a +statement, so if a statement sequence contains nothing but a pragma +assert, then a null statement is required in addition, as in: + +.. code-block:: ada + + ... + if J > 3 then + pragma Assert (K > 3, "Bad value for K"); + null; + end if; + + +Note that, as with the `if` statement to which it is equivalent, the +type of the expression is either `Standard.Boolean`, or any type derived +from this standard type. + +Assert checks can be either checked or ignored. By default they are ignored. +They will be checked if either the command line switch *-gnata* is +used, or if an `Assertion_Policy` or `Check_Policy` pragma is used +to enable `Assert_Checks`. + +If assertions are ignored, then there +is no run-time effect (and in particular, any side effects from the +expression will not occur at run time). (The expression is still +analyzed at compile time, and may cause types to be frozen if they are +mentioned here for the first time). + +If assertions are checked, then the given expression is tested, and if +it is `False` then `System.Assertions.Raise_Assert_Failure` is called +which results in the raising of `Assert_Failure` with the given message. + +You should generally avoid side effects in the expression arguments of +this pragma, because these side effects will turn on and off with the +setting of the assertions mode, resulting in assertions that have an +effect on the program. However, the expressions are analyzed for +semantic correctness whether or not assertions are enabled, so turning +assertions on and off cannot affect the legality of a program. + +Note that the implementation defined policy `DISABLE`, given in a +pragma `Assertion_Policy`, can be used to suppress this semantic analysis. + +Note: this is a standard language-defined pragma in versions +of Ada from 2005 on. In GNAT, it is implemented in all versions +of Ada, and the DISABLE policy is an implementation-defined +addition. + +Pragma Assert_And_Cut +===================== + +Syntax:: + + pragma Assert_And_Cut ( + boolean_EXPRESSION + [, string_EXPRESSION]); + + +The effect of this pragma is identical to that of pragma `Assert`, +except that in an `Assertion_Policy` pragma, the identifier +`Assert_And_Cut` is used to control whether it is ignored or checked +(or disabled). + +The intention is that this be used within a subprogram when the +given test expresion sums up all the work done so far in the +subprogram, so that the rest of the subprogram can be verified +(informally or formally) using only the entry preconditions, +and the expression in this pragma. This allows dividing up +a subprogram into sections for the purposes of testing or +formal verification. The pragma also serves as useful +documentation. + +Pragma Assertion_Policy +======================= + +Syntax:: + + pragma Assertion_Policy (CHECK | DISABLE | IGNORE); + + pragma Assertion_Policy ( + ASSERTION_KIND => POLICY_IDENTIFIER + {, ASSERTION_KIND => POLICY_IDENTIFIER}); + + ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND + + RM_ASSERTION_KIND ::= Assert | + Static_Predicate | + Dynamic_Predicate | + Pre | + Pre'Class | + Post | + Post'Class | + Type_Invariant | + Type_Invariant'Class + + ID_ASSERTION_KIND ::= Assertions | + Assert_And_Cut | + Assume | + Contract_Cases | + Debug | + Invariant | + Invariant'Class | + Loop_Invariant | + Loop_Variant | + Postcondition | + Precondition | + Predicate | + Refined_Post | + Statement_Assertions + + POLICY_IDENTIFIER ::= Check | Disable | Ignore + + +This is a standard Ada 2012 pragma that is available as an +implementation-defined pragma in earlier versions of Ada. +The assertion kinds `RM_ASSERTION_KIND` are those defined in +the Ada standard. The assertion kinds `ID_ASSERTION_KIND` +are implementation defined additions recognized by the GNAT compiler. + +The pragma applies in both cases to pragmas and aspects with matching +names, e.g. `Pre` applies to the Pre aspect, and `Precondition` +applies to both the `Precondition` pragma +and the aspect `Precondition`. Note that the identifiers for +pragmas Pre_Class and Post_Class are Pre'Class and Post'Class (not +Pre_Class and Post_Class), since these pragmas are intended to be +identical to the corresponding aspects). + +If the policy is `CHECK`, then assertions are enabled, i.e. +the corresponding pragma or aspect is activated. +If the policy is `IGNORE`, then assertions are ignored, i.e. +the corresponding pragma or aspect is deactivated. +This pragma overrides the effect of the *-gnata* switch on the +command line. + +The implementation defined policy `DISABLE` is like +`IGNORE` except that it completely disables semantic +checking of the corresponding pragma or aspect. This is +useful when the pragma or aspect argument references subprograms +in a with'ed package which is replaced by a dummy package +for the final build. + +The implementation defined assertion kind `Assertions` applies to all +assertion kinds. The form with no assertion kind given implies this +choice, so it applies to all assertion kinds (RM defined, and +implementation defined). + +The implementation defined assertion kind `Statement_Assertions` +applies to `Assert`, `Assert_And_Cut`, +`Assume`, `Loop_Invariant`, and `Loop_Variant`. + +Pragma Assume +============= + +Syntax: + +:: + + pragma Assume ( + boolean_EXPRESSION + [, string_EXPRESSION]); + + +The effect of this pragma is identical to that of pragma `Assert`, +except that in an `Assertion_Policy` pragma, the identifier +`Assume` is used to control whether it is ignored or checked +(or disabled). + +The intention is that this be used for assumptions about the +external environment. So you cannot expect to verify formally +or informally that the condition is met, this must be +established by examining things outside the program itself. +For example, we may have code that depends on the size of +`Long_Long_Integer` being at least 64. So we could write: + +.. code-block:: ada + + pragma Assume (Long_Long_Integer'Size >= 64); + + +This assumption cannot be proved from the program itself, +but it acts as a useful run-time check that the assumption +is met, and documents the need to ensure that it is met by +reference to information outside the program. + +Pragma Assume_No_Invalid_Values +=============================== +.. index:: Invalid representations + +.. index:: Invalid values + +Syntax: + +.. code-block:: ada + + pragma Assume_No_Invalid_Values (On | Off); + + +This is a configuration pragma that controls the assumptions made by the +compiler about the occurrence of invalid representations (invalid values) +in the code. + +The default behavior (corresponding to an Off argument for this pragma), is +to assume that values may in general be invalid unless the compiler can +prove they are valid. Consider the following example: + +.. code-block:: ada + + V1 : Integer range 1 .. 10; + V2 : Integer range 11 .. 20; + ... + for J in V2 .. V1 loop + ... + end loop; + + +if V1 and V2 have valid values, then the loop is known at compile +time not to execute since the lower bound must be greater than the +upper bound. However in default mode, no such assumption is made, +and the loop may execute. If `Assume_No_Invalid_Values (On)` +is given, the compiler will assume that any occurrence of a variable +other than in an explicit `'Valid` test always has a valid +value, and the loop above will be optimized away. + +The use of `Assume_No_Invalid_Values (On)` is appropriate if +you know your code is free of uninitialized variables and other +possible sources of invalid representations, and may result in +more efficient code. A program that accesses an invalid representation +with this pragma in effect is erroneous, so no guarantees can be made +about its behavior. + +It is peculiar though permissible to use this pragma in conjunction +with validity checking (-gnatVa). In such cases, accessing invalid +values will generally give an exception, though formally the program +is erroneous so there are no guarantees that this will always be the +case, and it is recommended that these two options not be used together. + +Pragma Async_Readers +==================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.1.2. + +Pragma Async_Writers +==================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.1.2. + +Pragma Attribute_Definition +=========================== + +Syntax: + +:: + + pragma Attribute_Definition + ([Attribute =>] ATTRIBUTE_DESIGNATOR, + [Entity =>] LOCAL_NAME, + [Expression =>] EXPRESSION | NAME); + + +If `Attribute` is a known attribute name, this pragma is equivalent to +the attribute definition clause: + + +.. code-block:: ada + + for Entity'Attribute use Expression; + + +If `Attribute` is not a recognized attribute name, the pragma is +ignored, and a warning is emitted. This allows source +code to be written that takes advantage of some new attribute, while remaining +compilable with earlier compilers. + +Pragma C_Pass_By_Copy +===================== +.. index:: Passing by copy + + +Syntax: + +:: + + pragma C_Pass_By_Copy + ([Max_Size =>] static_integer_EXPRESSION); + + +Normally the default mechanism for passing C convention records to C +convention subprograms is to pass them by reference, as suggested by RM +B.3(69). Use the configuration pragma `C_Pass_By_Copy` to change +this default, by requiring that record formal parameters be passed by +copy if all of the following conditions are met: + +* + The size of the record type does not exceed the value specified for + `Max_Size`. +* + The record type has `Convention C`. +* + The formal parameter has this record type, and the subprogram has a + foreign (non-Ada) convention. + +If these conditions are met the argument is passed by copy; i.e., in a +manner consistent with what C expects if the corresponding formal in the +C prototype is a struct (rather than a pointer to a struct). + +You can also pass records by copy by specifying the convention +`C_Pass_By_Copy` for the record type, or by using the extended +`Import` and `Export` pragmas, which allow specification of +passing mechanisms on a parameter by parameter basis. + +Pragma Check +============ +.. index:: Assertions + +.. index:: Named assertions + + +Syntax: + +:: + + pragma Check ( + [Name =>] CHECK_KIND, + [Check =>] Boolean_EXPRESSION + [, [Message =>] string_EXPRESSION] ); + + CHECK_KIND ::= IDENTIFIER | + Pre'Class | + Post'Class | + Type_Invariant'Class | + Invariant'Class + + +This pragma is similar to the predefined pragma `Assert` except that an +extra identifier argument is present. In conjunction with pragma +`Check_Policy`, this can be used to define groups of assertions that can +be independently controlled. The identifier `Assertion` is special, it +refers to the normal set of pragma `Assert` statements. + +Checks introduced by this pragma are normally deactivated by default. They can +be activated either by the command line option *-gnata*, which turns on +all checks, or individually controlled using pragma `Check_Policy`. + +The identifiers `Assertions` and `Statement_Assertions` are not +permitted as check kinds, since this would cause confusion with the use +of these identifiers in `Assertion_Policy` and `Check_Policy` +pragmas, where they are used to refer to sets of assertions. + +Pragma Check_Float_Overflow +=========================== +.. index:: Floating-point overflow + + +Syntax: + +.. code-block:: ada + + pragma Check_Float_Overflow; + + +In Ada, the predefined floating-point types (`Short_Float`, +`Float`, `Long_Float`, `Long_Long_Float`) are +defined to be *unconstrained*. This means that even though each +has a well-defined base range, an operation that delivers a result +outside this base range is not required to raise an exception. +This implementation permission accommodates the notion +of infinities in IEEE floating-point, and corresponds to the +efficient execution mode on most machines. GNAT will not raise +overflow exceptions on these machines; instead it will generate +infinities and NaN's as defined in the IEEE standard. + +Generating infinities, although efficient, is not always desirable. +Often the preferable approach is to check for overflow, even at the +(perhaps considerable) expense of run-time performance. +This can be accomplished by defining your own constrained floating-point subtypes -- i.e., by supplying explicit +range constraints -- and indeed such a subtype +can have the same base range as its base type. For example: + + +.. code-block:: ada + + subtype My_Float is Float range Float'Range; + + +Here `My_Float` has the same range as +`Float` but is constrained, so operations on +`My_Float` values will be checked for overflow +against this range. + +This style will achieve the desired goal, but +it is often more convenient to be able to simply use +the standard predefined floating-point types as long +as overflow checking could be guaranteed. +The `Check_Float_Overflow` +configuration pragma achieves this effect. If a unit is compiled +subject to this configuration pragma, then all operations +on predefined floating-point types including operations on +base types of these floating-point types will be treated as +though those types were constrained, and overflow checks +will be generated. The `Constraint_Error` +exception is raised if the result is out of range. + +This mode can also be set by use of the compiler +switch *-gnateF*. + +Pragma Check_Name +================= +.. index:: Defining check names + +.. index:: Check names, defining + + +Syntax: + +.. code-block:: ada + + pragma Check_Name (check_name_IDENTIFIER); + + +This is a configuration pragma that defines a new implementation +defined check name (unless IDENTIFIER matches one of the predefined +check names, in which case the pragma has no effect). Check names +are global to a partition, so if two or more configuration pragmas +are present in a partition mentioning the same name, only one new +check name is introduced. + +An implementation defined check name introduced with this pragma may +be used in only three contexts: `pragma Suppress`, +`pragma Unsuppress`, +and as the prefix of a `Check_Name'Enabled` attribute reference. For +any of these three cases, the check name must be visible. A check +name is visible if it is in the configuration pragmas applying to +the current unit, or if it appears at the start of any unit that +is part of the dependency set of the current unit (e.g., units that +are mentioned in `with` clauses). + +Check names introduced by this pragma are subject to control by compiler +switches (in particular -gnatp) in the usual manner. + +Pragma Check_Policy +=================== +.. index:: Controlling assertions + +.. index:: Assertions, control + +.. index:: Check pragma control + +.. index:: Named assertions + + +Syntax: + +:: + + pragma Check_Policy + ([Name =>] CHECK_KIND, + [Policy =>] POLICY_IDENTIFIER); + + pragma Check_Policy ( + CHECK_KIND => POLICY_IDENTIFIER + {, CHECK_KIND => POLICY_IDENTIFIER}); + + ASSERTION_KIND ::= RM_ASSERTION_KIND | ID_ASSERTION_KIND + + CHECK_KIND ::= IDENTIFIER | + Pre'Class | + Post'Class | + Type_Invariant'Class | + Invariant'Class + + The identifiers Name and Policy are not allowed as CHECK_KIND values. This + avoids confusion between the two possible syntax forms for this pragma. + + POLICY_IDENTIFIER ::= ON | OFF | CHECK | DISABLE | IGNORE + + +This pragma is used to set the checking policy for assertions (specified +by aspects or pragmas), the `Debug` pragma, or additional checks +to be checked using the `Check` pragma. It may appear either as +a configuration pragma, or within a declarative part of package. In the +latter case, it applies from the point where it appears to the end of +the declarative region (like pragma `Suppress`). + +The `Check_Policy` pragma is similar to the +predefined `Assertion_Policy` pragma, +and if the check kind corresponds to one of the assertion kinds that +are allowed by `Assertion_Policy`, then the effect is identical. + +If the first argument is Debug, then the policy applies to Debug pragmas, +disabling their effect if the policy is `OFF`, `DISABLE`, or +`IGNORE`, and allowing them to execute with normal semantics if +the policy is `ON` or `CHECK`. In addition if the policy is +`DISABLE`, then the procedure call in `Debug` pragmas will +be totally ignored and not analyzed semantically. + +Finally the first argument may be some other identifier than the above +possibilities, in which case it controls a set of named assertions +that can be checked using pragma `Check`. For example, if the pragma: + + +.. code-block:: ada + + pragma Check_Policy (Critical_Error, OFF); + + +is given, then subsequent `Check` pragmas whose first argument is also +`Critical_Error` will be disabled. + +The check policy is `OFF` to turn off corresponding checks, and `ON` +to turn on corresponding checks. The default for a set of checks for which no +`Check_Policy` is given is `OFF` unless the compiler switch +*-gnata* is given, which turns on all checks by default. + +The check policy settings `CHECK` and `IGNORE` are recognized +as synonyms for `ON` and `OFF`. These synonyms are provided for +compatibility with the standard `Assertion_Policy` pragma. The check +policy setting `DISABLE` causes the second argument of a corresponding +`Check` pragma to be completely ignored and not analyzed. + +Pragma CIL_Constructor +====================== + +Syntax: + + +:: + + pragma CIL_Constructor ([Entity =>] function_LOCAL_NAME); + + +This pragma is used to assert that the specified Ada function should be +mapped to the .NET constructor for some Ada tagged record type. + +See section 4.1 of the +`GNAT User's Guide: Supplement for the .NET Platform.` +for related information. + +Pragma Comment +============== + +Syntax: + + +.. code-block:: ada + + pragma Comment (static_string_EXPRESSION); + + +This is almost identical in effect to pragma `Ident`. It allows the +placement of a comment into the object file and hence into the +executable file if the operating system permits such usage. The +difference is that `Comment`, unlike `Ident`, has +no limitations on placement of the pragma (it can be placed +anywhere in the main source unit), and if more than one pragma +is used, all comments are retained. + +Pragma Common_Object +==================== + +Syntax: + + +:: + + pragma Common_Object ( + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Size =>] EXTERNAL_SYMBOL] ); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + + +This pragma enables the shared use of variables stored in overlaid +linker areas corresponding to the use of `COMMON` +in Fortran. The single +object `LOCAL_NAME` is assigned to the area designated by +the `External` argument. +You may define a record to correspond to a series +of fields. The `Size` argument +is syntax checked in GNAT, but otherwise ignored. + +`Common_Object` is not supported on all platforms. If no +support is available, then the code generator will issue a message +indicating that the necessary attribute for implementation of this +pragma is not available. + +Pragma Compile_Time_Error +========================= + +Syntax: + + +.. code-block:: ada + + pragma Compile_Time_Error + (boolean_EXPRESSION, static_string_EXPRESSION); + + +This pragma can be used to generate additional compile time +error messages. It +is particularly useful in generics, where errors can be issued for +specific problematic instantiations. The first parameter is a boolean +expression. The pragma is effective only if the value of this expression +is known at compile time, and has the value True. The set of expressions +whose values are known at compile time includes all static boolean +expressions, and also other values which the compiler can determine +at compile time (e.g., the size of a record type set by an explicit +size representation clause, or the value of a variable which was +initialized to a constant and is known not to have been modified). +If these conditions are met, an error message is generated using +the value given as the second argument. This string value may contain +embedded ASCII.LF characters to break the message into multiple lines. + +Pragma Compile_Time_Warning +=========================== + +Syntax: + + +.. code-block:: ada + + pragma Compile_Time_Warning + (boolean_EXPRESSION, static_string_EXPRESSION); + + +Same as pragma Compile_Time_Error, except a warning is issued instead +of an error message. Note that if this pragma is used in a package that +is with'ed by a client, the client will get the warning even though it +is issued by a with'ed package (normally warnings in with'ed units are +suppressed, but this is a special exception to that rule). + +One typical use is within a generic where compile time known characteristics +of formal parameters are tested, and warnings given appropriately. Another use +with a first parameter of True is to warn a client about use of a package, +for example that it is not fully implemented. + +Pragma Compiler_Unit +==================== + +Syntax: + + +.. code-block:: ada + + pragma Compiler_Unit; + + +This pragma is obsolete. It is equivalent to Compiler_Unit_Warning. It is +retained so that old versions of the GNAT run-time that use this pragma can +be compiled with newer versions of the compiler. + +Pragma Compiler_Unit_Warning +============================ + +Syntax: + + +.. code-block:: ada + + pragma Compiler_Unit_Warning; + + +This pragma is intended only for internal use in the GNAT run-time library. +It indicates that the unit is used as part of the compiler build. The effect +is to generate warnings for the use of constructs (for example, conditional +expressions) that would cause trouble when bootstrapping using an older +version of GNAT. For the exact list of restrictions, see the compiler sources +and references to Check_Compiler_Unit. + +Pragma Complete_Representation +============================== + +Syntax: + + +.. code-block:: ada + + pragma Complete_Representation; + + +This pragma must appear immediately within a record representation +clause. Typical placements are before the first component clause +or after the last component clause. The effect is to give an error +message if any component is missing a component clause. This pragma +may be used to ensure that a record representation clause is +complete, and that this invariant is maintained if fields are +added to the record in the future. + +Pragma Complex_Representation +============================= + +Syntax: + + +:: + + pragma Complex_Representation + ([Entity =>] LOCAL_NAME); + + +The `Entity` argument must be the name of a record type which has +two fields of the same floating-point type. The effect of this pragma is +to force gcc to use the special internal complex representation form for +this record, which may be more efficient. Note that this may result in +the code for this type not conforming to standard ABI (application +binary interface) requirements for the handling of record types. For +example, in some environments, there is a requirement for passing +records by pointer, and the use of this pragma may result in passing +this type in floating-point registers. + +Pragma Component_Alignment +========================== +.. index:: Alignments of components +.. index:: Pragma Component_Alignment + + +Syntax: + +:: + + pragma Component_Alignment ( + [Form =>] ALIGNMENT_CHOICE + [, [Name =>] type_LOCAL_NAME]); + + ALIGNMENT_CHOICE ::= + Component_Size + | Component_Size_4 + | Storage_Unit + | Default + + +Specifies the alignment of components in array or record types. +The meaning of the `Form` argument is as follows: + + + .. index:: Component_Size (in pragma Component_Alignment) + +*Component_Size* + Aligns scalar components and subcomponents of the array or record type + on boundaries appropriate to their inherent size (naturally + aligned). For example, 1-byte components are aligned on byte boundaries, + 2-byte integer components are aligned on 2-byte boundaries, 4-byte + integer components are aligned on 4-byte boundaries and so on. These + alignment rules correspond to the normal rules for C compilers on all + machines except the VAX. + + .. index:: Component_Size_4 (in pragma Component_Alignment) + +*Component_Size_4* + Naturally aligns components with a size of four or fewer + bytes. Components that are larger than 4 bytes are placed on the next + 4-byte boundary. + + .. index:: Storage_Unit (in pragma Component_Alignment) + +*Storage_Unit* + Specifies that array or record components are byte aligned, i.e., + aligned on boundaries determined by the value of the constant + `System.Storage_Unit`. + + .. index:: Default (in pragma Component_Alignment) + +*Default* + Specifies that array or record components are aligned on default + boundaries, appropriate to the underlying hardware or operating system or + both. The `Default` choice is the same as `Component_Size` (natural + alignment). + +If the `Name` parameter is present, `type_LOCAL_NAME` must +refer to a local record or array type, and the specified alignment +choice applies to the specified type. The use of +`Component_Alignment` together with a pragma `Pack` causes the +`Component_Alignment` pragma to be ignored. The use of +`Component_Alignment` together with a record representation clause +is only effective for fields not specified by the representation clause. + +If the `Name` parameter is absent, the pragma can be used as either +a configuration pragma, in which case it applies to one or more units in +accordance with the normal rules for configuration pragmas, or it can be +used within a declarative part, in which case it applies to types that +are declared within this declarative part, or within any nested scope +within this declarative part. In either case it specifies the alignment +to be applied to any record or array type which has otherwise standard +representation. + +If the alignment for a record or array type is not specified (using +pragma `Pack`, pragma `Component_Alignment`, or a record rep +clause), the GNAT uses the default alignment as described previously. + +Pragma Contract_Cases +===================== +.. index:: Contract cases + + +Syntax: + + +:: + + pragma Contract_Cases ( + Condition => Consequence + {,Condition => Consequence}); + + +The `Contract_Cases` pragma allows defining fine-grain specifications +that can complement or replace the contract given by a precondition and a +postcondition. Additionally, the `Contract_Cases` pragma can be used +by testing and formal verification tools. The compiler checks its validity and, +depending on the assertion policy at the point of declaration of the pragma, +it may insert a check in the executable. For code generation, the contract +cases + + +.. code-block:: ada + + pragma Contract_Cases ( + Cond1 => Pred1, + Cond2 => Pred2); + + +are equivalent to + + +.. code-block:: ada + + C1 : constant Boolean := Cond1; -- evaluated at subprogram entry + C2 : constant Boolean := Cond2; -- evaluated at subprogram entry + pragma Precondition ((C1 and not C2) or (C2 and not C1)); + pragma Postcondition (if C1 then Pred1); + pragma Postcondition (if C2 then Pred2); + + +The precondition ensures that one and only one of the conditions is +satisfied on entry to the subprogram. +The postcondition ensures that for the condition that was True on entry, +the corrresponding consequence is True on exit. Other consequence expressions +are not evaluated. + +A precondition `P` and postcondition `Q` can also be +expressed as contract cases: + +.. code-block:: ada + + pragma Contract_Cases (P => Q); + + +The placement and visibility rules for `Contract_Cases` pragmas are +identical to those described for preconditions and postconditions. + +The compiler checks that boolean expressions given in conditions and +consequences are valid, where the rules for conditions are the same as +the rule for an expression in `Precondition` and the rules for +consequences are the same as the rule for an expression in +`Postcondition`. In particular, attributes `'Old` and +`'Result` can only be used within consequence expressions. +The condition for the last contract case may be `others`, to denote +any case not captured by the previous cases. The +following is an example of use within a package spec: + + +.. code-block:: ada + + package Math_Functions is + ... + function Sqrt (Arg : Float) return Float; + pragma Contract_Cases ((Arg in 0 .. 99) => Sqrt'Result < 10, + Arg >= 100 => Sqrt'Result >= 10, + others => Sqrt'Result = 0); + ... + end Math_Functions; + + +The meaning of contract cases is that only one case should apply at each +call, as determined by the corresponding condition evaluating to True, +and that the consequence for this case should hold when the subprogram +returns. + +Pragma Convention_Identifier +============================ +.. index:: Conventions, synonyms + +Syntax: + + +:: + + pragma Convention_Identifier ( + [Name =>] IDENTIFIER, + [Convention =>] convention_IDENTIFIER); + + +This pragma provides a mechanism for supplying synonyms for existing +convention identifiers. The `Name` identifier can subsequently +be used as a synonym for the given convention in other pragmas (including +for example pragma `Import` or another `Convention_Identifier` +pragma). As an example of the use of this, suppose you had legacy code +which used Fortran77 as the identifier for Fortran. Then the pragma: + + +.. code-block:: ada + + pragma Convention_Identifier (Fortran77, Fortran); + + +would allow the use of the convention identifier `Fortran77` in +subsequent code, avoiding the need to modify the sources. As another +example, you could use this to parameterize convention requirements +according to systems. Suppose you needed to use `Stdcall` on +windows systems, and `C` on some other system, then you could +define a convention identifier `Library` and use a single +`Convention_Identifier` pragma to specify which convention +would be used system-wide. + +Pragma CPP_Class +================ +.. index:: Interfacing with C++ + +Syntax: + + +:: + + pragma CPP_Class ([Entity =>] LOCAL_NAME); + + +The argument denotes an entity in the current declarative region that is +declared as a 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. If the C++ class has virtual primitives +then the record must be declared as a tagged record type. + +Types for which `CPP_Class` is specified do not have assignment or +equality operators defined (such operations can be imported or declared +as subprograms as required). Initialization is allowed only by constructor +functions (see pragma `CPP_Constructor`). Such types are implicitly +limited if not explicitly declared as limited or derived from a limited +type, and an error is issued in that case. + +See :ref:`Interfacing_to_C++` for related information. + +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 +====================== +.. index:: Interfacing with C++ + + +Syntax: + + +:: + + pragma CPP_Constructor ([Entity =>] LOCAL_NAME + [, [External_Name =>] static_string_EXPRESSION ] + [, [Link_Name =>] static_string_EXPRESSION ]); + + +This pragma identifies an imported function (imported in the usual way +with pragma `Import`) as corresponding to a C++ constructor. If +`External_Name` and `Link_Name` are not specified then the +`Entity` argument is a name that must have been previously mentioned +in a pragma `Import` with `Convention` = `CPP`. Such name +must be of one of the following forms: + +* + **function** `Fname` **return** T` + +* + **function** `Fname` **return** T'Class + +* + **function** `Fname` (...) **return** T` + +* + **function** `Fname` (...) **return** T'Class + +where `T` is a limited record type imported from C++ with pragma +`Import` and `Convention` = `CPP`. + +The first two forms import the default constructor, used when an object +of type `T` is created on the Ada side with no explicit constructor. +The latter two forms cover all the non-default constructors of the type. +See the GNAT User's Guide for details. + +If no constructors are imported, it is impossible to create any objects +on the Ada side and the type is implicitly declared abstract. + +Pragma `CPP_Constructor` is intended primarily for automatic generation +using an automatic binding generator tool (such as the `-fdump-ada-spec` +GCC switch). +See :ref:`Interfacing_to_C++` for more related information. + +Note: The use of functions returning class-wide types for constructors is +currently obsolete. They are supported for backward compatibility. The +use of functions returning the type T leave the Ada sources more clear +because the imported C++ constructors always return an object of type T; +that is, they never return an object whose type is a descendant of type T. + +Pragma CPP_Virtual +================== +.. index:: Interfacing to C++ + + +This pragma is now obsolete and, other than generating a warning if warnings +on obsolescent features are enabled, is completely ignored. +It is retained for compatibility +purposes. It used to be required to ensure compoatibility with C++, but +is no longer required for that purpose because GNAT generates +the same object layout as the G++ compiler by default. + +See :ref:`Interfacing_to_C++` for related information. + +Pragma CPP_Vtable +================= +.. index:: Interfacing with C++ + + +This pragma is now obsolete and, other than generating a warning if warnings +on obsolescent features are enabled, is completely ignored. +It used to be required to ensure compatibility with C++, but +is no longer required for that purpose because GNAT generates +the same object layout as the G++ compiler by default. + +See :ref:`Interfacing_to_C++` for related information. + +Pragma CPU +========== + +Syntax: + + +.. code-block:: ada + + pragma CPU (EXPRESSION); + + +This pragma is standard in Ada 2012, but is available in all earlier +versions of Ada as an implementation-defined pragma. +See Ada 2012 Reference Manual for details. + +Pragma Debug +============ + +Syntax: + + +:: + + pragma Debug ([CONDITION, ]PROCEDURE_CALL_WITHOUT_SEMICOLON); + + PROCEDURE_CALL_WITHOUT_SEMICOLON ::= + PROCEDURE_NAME + | PROCEDURE_PREFIX ACTUAL_PARAMETER_PART + + +The procedure call argument has the syntactic form of an expression, meeting +the syntactic requirements for pragmas. + +If debug pragmas are not enabled or if the condition is present and evaluates +to False, this pragma has no effect. If debug pragmas are enabled, the +semantics of the pragma is exactly equivalent to the procedure call statement +corresponding to the argument with a terminating semicolon. Pragmas are +permitted in sequences of declarations, so you can use pragma `Debug` to +intersperse calls to debug procedures in the middle of declarations. Debug +pragmas can be enabled either by use of the command line switch *-gnata* +or by use of the pragma `Check_Policy` with a first argument of +`Debug`. + +Pragma Debug_Policy +=================== + +Syntax: + + +.. code-block:: ada + + pragma Debug_Policy (CHECK | DISABLE | IGNORE | ON | OFF); + + +This pragma is equivalent to a corresponding `Check_Policy` pragma +with a first argument of `Debug`. It is retained for historical +compatibility reasons. + +Pragma Default_Scalar_Storage_Order +=================================== +.. index:: Default_Scalar_Storage_Order + +.. index:: Scalar_Storage_Order + + +Syntax: + + +.. code-block:: ada + + pragma Default_Scalar_Storage_Order (High_Order_First | Low_Order_First); + + +Normally if no explicit `Scalar_Storage_Order` is given for a record +type or array type, then the scalar storage order defaults to the ordinary +default for the target. But this default may be overridden using this pragma. +The pragma may appear as a configuration pragma, or locally within a package +spec or declarative part. In the latter case, it applies to all subsequent +types declared within that package spec or declarative part. + +The following example shows the use of this pragma: + + +.. code-block:: ada + + pragma Default_Scalar_Storage_Order (High_Order_First); + with System; use System; + package DSSO1 is + type H1 is record + a : Integer; + end record; + + type L2 is record + a : Integer; + end record; + for L2'Scalar_Storage_Order use Low_Order_First; + + type L2a is new L2; + + package Inner is + type H3 is record + a : Integer; + end record; + + pragma Default_Scalar_Storage_Order (Low_Order_First); + + type L4 is record + a : Integer; + end record; + end Inner; + + type H4a is new Inner.L4; + + type H5 is record + a : Integer; + end record; + end DSSO1; + + +In this example record types L.. have `Low_Order_First` scalar +storage order, and record types H.. have `High_Order_First`. +Note that in the case of `H4a`, the order is not inherited +from the parent type. Only an explicitly set `Scalar_Storage_Order` +gets inherited on type derivation. + +If this pragma is used as a configuration pragma which appears within a +configuration pragma file (as opposed to appearing explicitly at the start +of a single unit), then the binder will require that all units in a partition +be compiled in a similar manner, other than run-time units, which are not +affected by this pragma. Note that the use of this form is discouraged because +it may significantly degrade the run-time performance of the software, instead +the default scalar storage order ought to be changed only on a local basis. + +Pragma Default_Storage_Pool +=========================== +.. index:: Default_Storage_Pool + + +Syntax: + + +.. code-block:: ada + + pragma Default_Storage_Pool (storage_pool_NAME | null); + + +This pragma is standard in Ada 2012, but is available in all earlier +versions of Ada as an implementation-defined pragma. +See Ada 2012 Reference Manual for details. + +Pragma Depends +============== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 6.1.5. + +Pragma Detect_Blocking +====================== + +Syntax: + +.. code-block:: ada + + pragma Detect_Blocking; + + +This is a standard pragma in Ada 2005, that is available in all earlier +versions of Ada as an implementation-defined pragma. + +This is a configuration pragma that forces the detection of potentially +blocking operations within a protected operation, and to raise Program_Error +if that happens. + +Pragma Disable_Atomic_Synchronization +===================================== + +.. index:: Atomic Synchronization + +Syntax: + +:: + + pragma Disable_Atomic_Synchronization [(Entity)]; + + +Ada requires that accesses (reads or writes) of an atomic variable be +regarded as synchronization points in the case of multiple tasks. +Particularly in the case of multi-processors this may require special +handling, e.g. the generation of memory barriers. This capability may +be turned off using this pragma in cases where it is known not to be +required. + +The placement and scope rules for this pragma are the same as those +for `pragma Suppress`. In particular it can be used as a +configuration pragma, or in a declaration sequence where it applies +till the end of the scope. If an `Entity` argument is present, +the action applies only to that entity. + +Pragma Dispatching_Domain +========================= + +Syntax: + + +.. code-block:: ada + + pragma Dispatching_Domain (EXPRESSION); + + +This pragma is standard in Ada 2012, but is available in all earlier +versions of Ada as an implementation-defined pragma. +See Ada 2012 Reference Manual for details. + +Pragma Effective_Reads +====================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.1.2. + +Pragma Effective_Writes +======================= + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.1.2. + +Pragma Elaboration_Checks +========================= +.. index:: Elaboration control + + +Syntax: + + +.. code-block:: ada + + pragma Elaboration_Checks (Dynamic | Static); + + +This is a configuration pragma that provides control over the +elaboration model used by the compilation affected by the +pragma. If the parameter is `Dynamic`, +then the dynamic elaboration +model described in the Ada Reference Manual is used, as though +the *-gnatE* switch had been specified on the command +line. If the parameter is `Static`, then the default GNAT static +model is used. This configuration pragma overrides the setting +of the command line. For full details on the elaboration models +used by the GNAT compiler, see the chapter on elaboration order handling +in the *GNAT User's Guide*. + +Pragma Eliminate +================ +.. index:: Elimination of unused subprograms + + +Syntax: + + +:: + + pragma Eliminate ([Entity =>] DEFINING_DESIGNATOR, + [Source_Location =>] STRING_LITERAL); + + +The string literal given for the source location is a string which +specifies the line number of the occurrence of the entity, using +the syntax for SOURCE_TRACE given below: + + +:: + + SOURCE_TRACE ::= SOURCE_REFERENCE [LBRACKET SOURCE_TRACE RBRACKET] + + LBRACKET ::= [ + RBRACKET ::= ] + + SOURCE_REFERENCE ::= FILE_NAME : LINE_NUMBER + + LINE_NUMBER ::= DIGIT {DIGIT} + + +Spaces around the colon in a `Source_Reference` are optional. + +The `DEFINING_DESIGNATOR` matches the defining designator used in an +explicit subprogram declaration, where the `entity` name in this +designator appears on the source line specified by the source location. + +The source trace that is given as the `Source_Location` shall obey the +following rules. The `FILE_NAME` is the short name (with no directory +information) of an Ada source file, given using exactly the required syntax +for the underlying file system (e.g. case is important if the underlying +operating system is case sensitive). `LINE_NUMBER` gives the line +number of the occurrence of the `entity` +as a decimal literal without an exponent or point. If an `entity` is not +declared in a generic instantiation (this includes generic subprogram +instances), the source trace includes only one source reference. If an entity +is declared inside a generic instantiation, its source trace (when parsing +from left to right) starts with the source location of the declaration of the +entity in the generic unit and ends with the source location of the +instantiation (it is given in square brackets). This approach is recursively +used in case of nested instantiations: the rightmost (nested most deeply in +square brackets) element of the source trace is the location of the outermost +instantiation, the next to left element is the location of the next (first +nested) instantiation in the code of the corresponding generic unit, and so +on, and the leftmost element (that is out of any square brackets) is the +location of the declaration of the entity to eliminate in a generic unit. + +Note that the `Source_Location` argument specifies which of a set of +similarly named entities is being eliminated, dealing both with overloading, +and also appearance of the same entity name in different scopes. + +This pragma indicates that the given entity is not used in the program to be +compiled and built. The effect of the pragma is to allow the compiler to +eliminate the code or data associated with the named entity. Any reference to +an eliminated entity causes a compile-time or link-time error. + +The intention of pragma `Eliminate` is to allow a program to be compiled +in a system-independent manner, with unused entities eliminated, without +needing to modify the source text. Normally the required set of +`Eliminate` pragmas is constructed automatically using the gnatelim tool. + +Any source file change that removes, splits, or +adds lines may make the set of Eliminate pragmas invalid because their +`Source_Location` argument values may get out of date. + +Pragma `Eliminate` may be used where the referenced entity is a dispatching +operation. In this case all the subprograms to which the given operation can +dispatch are considered to be unused (are never called as a result of a direct +or a dispatching call). + +Pragma Enable_Atomic_Synchronization +==================================== +.. index:: Atomic Synchronization + + +Syntax: + + +:: + + pragma Enable_Atomic_Synchronization [(Entity)]; + + +Ada requires that accesses (reads or writes) of an atomic variable be +regarded as synchronization points in the case of multiple tasks. +Particularly in the case of multi-processors this may require special +handling, e.g. the generation of memory barriers. This synchronization +is performed by default, but can be turned off using +`pragma Disable_Atomic_Synchronization`. The +`Enable_Atomic_Synchronization` pragma can be used to turn +it back on. + +The placement and scope rules for this pragma are the same as those +for `pragma Unsuppress`. In particular it can be used as a +configuration pragma, or in a declaration sequence where it applies +till the end of the scope. If an `Entity` argument is present, +the action applies only to that entity. + +Pragma Export_Function +====================== +.. index:: Argument passing mechanisms + + +Syntax: + + +:: + + pragma Export_Function ( + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Result_Type =>] result_SUBTYPE_MARK] + [, [Mechanism =>] MECHANISM] + [, [Result_Mechanism =>] MECHANISM_NAME]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + | "" + + PARAMETER_TYPES ::= + null + | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} + + TYPE_DESIGNATOR ::= + subtype_NAME + | subtype_Name ' Access + + MECHANISM ::= + MECHANISM_NAME + | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) + + MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + + MECHANISM_NAME ::= Value | Reference + + +Use this pragma to make a function externally callable and optionally +provide information on mechanisms to be used for passing parameter and +result values. We recommend, for the purposes of improving portability, +this pragma always be used in conjunction with a separate pragma +`Export`, which must precede the pragma `Export_Function`. +GNAT does not require a separate pragma `Export`, but if none is +present, `Convention Ada` is assumed, which is usually +not what is wanted, so it is usually appropriate to use this +pragma in conjunction with a `Export` or `Convention` +pragma that specifies the desired foreign convention. +Pragma `Export_Function` +(and `Export`, if present) must appear in the same declarative +region as the function to which they apply. + +`internal_name` must uniquely designate the function to which the +pragma applies. If more than one function name exists of this name in +the declarative part you must use the `Parameter_Types` and +`Result_Type` parameters is mandatory to achieve the required +unique designation. `subtype_mark`s in these parameters must +exactly match the subtypes in the corresponding function specification, +using positional notation to match parameters with subtype marks. +The form with an `'Access` attribute can be used to match an +anonymous access parameter. + +.. index:: Suppressing external name + +Special treatment is given if the EXTERNAL is an explicit null +string or a static string expressions that evaluates to the null +string. In this case, no external name is generated. This form +still allows the specification of parameter mechanisms. + +Pragma Export_Object +==================== + +Syntax: + + +:: + + pragma Export_Object + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Size =>] EXTERNAL_SYMBOL] + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + + +This pragma designates an object as exported, and apart from the +extended rules for external symbols, is identical in effect to the use of +the normal `Export` pragma applied to an object. You may use a +separate Export pragma (and you probably should from the point of view +of portability), but it is not required. `Size` is syntax checked, +but otherwise ignored by GNAT. + +Pragma Export_Procedure +======================= + +Syntax: + + +:: + + pragma Export_Procedure ( + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + | "" + + PARAMETER_TYPES ::= + null + | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} + + TYPE_DESIGNATOR ::= + subtype_NAME + | subtype_Name ' Access + + MECHANISM ::= + MECHANISM_NAME + | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) + + MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + + MECHANISM_NAME ::= Value | Reference + + +This pragma is identical to `Export_Function` except that it +applies to a procedure rather than a function and the parameters +`Result_Type` and `Result_Mechanism` are not permitted. +GNAT does not require a separate pragma `Export`, but if none is +present, `Convention Ada` is assumed, which is usually +not what is wanted, so it is usually appropriate to use this +pragma in conjunction with a `Export` or `Convention` +pragma that specifies the desired foreign convention. + +.. index:: Suppressing external name + +Special treatment is given if the EXTERNAL is an explicit null +string or a static string expressions that evaluates to the null +string. In this case, no external name is generated. This form +still allows the specification of parameter mechanisms. + +Pragma Export_Value +=================== + +Syntax: + + +:: + + pragma Export_Value ( + [Value =>] static_integer_EXPRESSION, + [Link_Name =>] static_string_EXPRESSION); + + +This pragma serves to export a static integer value for external use. +The first argument specifies the value to be exported. The Link_Name +argument specifies the symbolic name to be associated with the integer +value. This pragma is useful for defining a named static value in Ada +that can be referenced in assembly language units to be linked with +the application. This pragma is currently supported only for the +AAMP target and is ignored for other targets. + +Pragma Export_Valued_Procedure +============================== + +Syntax: + + +:: + + pragma Export_Valued_Procedure ( + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + | "" + + PARAMETER_TYPES ::= + null + | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} + + TYPE_DESIGNATOR ::= + subtype_NAME + | subtype_Name ' Access + + MECHANISM ::= + MECHANISM_NAME + | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) + + MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + + MECHANISM_NAME ::= Value | Reference + + +This pragma is identical to `Export_Procedure` except that the +first parameter of `LOCAL_NAME`, which must be present, must be of +mode `OUT`, and externally the subprogram is treated as a function +with this parameter as the result of the function. GNAT provides for +this capability to allow the use of `OUT` and `IN OUT` +parameters in interfacing to external functions (which are not permitted +in Ada functions). +GNAT does not require a separate pragma `Export`, but if none is +present, `Convention Ada` is assumed, which is almost certainly +not what is wanted since the whole point of this pragma is to interface +with foreign language functions, so it is usually appropriate to use this +pragma in conjunction with a `Export` or `Convention` +pragma that specifies the desired foreign convention. + +.. index:: Suppressing external name + +Special treatment is given if the EXTERNAL is an explicit null +string or a static string expressions that evaluates to the null +string. In this case, no external name is generated. This form +still allows the specification of parameter mechanisms. + +Pragma Extend_System +==================== +.. index:: System, extending + +.. index:: DEC Ada 83 + + +Syntax: + + +:: + + pragma Extend_System ([Name =>] IDENTIFIER); + + +This pragma is used to provide backwards compatibility with other +implementations that extend the facilities of package `System`. In +GNAT, `System` contains only the definitions that are present in +the Ada RM. However, other implementations, notably the DEC Ada 83 +implementation, provide many extensions to package `System`. + +For each such implementation accommodated by this pragma, GNAT provides a +package `Aux_`xxx``, e.g., `Aux_DEC` for the DEC Ada 83 +implementation, which provides the required additional definitions. You +can use this package in two ways. You can `with` it in the normal +way and access entities either by selection or using a `use` +clause. In this case no special processing is required. + +However, if existing code contains references such as +`System.`xxx`` where `xxx` is an entity in the extended +definitions provided in package `System`, you may use this pragma +to extend visibility in `System` in a non-standard way that +provides greater compatibility with the existing code. Pragma +`Extend_System` is a configuration pragma whose single argument is +the name of the package containing the extended definition +(e.g., `Aux_DEC` for the DEC Ada case). A unit compiled under +control of this pragma will be processed using special visibility +processing that looks in package `System.Aux_`xxx`` where +`Aux_`xxx`` is the pragma argument for any entity referenced in +package `System`, but not found in package `System`. + +You can use this pragma either to access a predefined `System` +extension supplied with the compiler, for example `Aux_DEC` or +you can construct your own extension unit following the above +definition. Note that such a package is a child of `System` +and thus is considered part of the implementation. +To compile it you will have to use the *-gnatg* switch +for compiling System units, as explained in the +GNAT User's Guide. + +Pragma Extensions_Allowed +========================= +.. index:: Ada Extensions + +.. index:: GNAT Extensions + + +Syntax: + +.. code-block:: ada + + pragma Extensions_Allowed (On | Off); + + +This configuration pragma enables or disables the implementation +extension mode (the use of Off as a parameter cancels the effect +of the *-gnatX* command switch). + +In extension mode, the latest version of the Ada language is +implemented (currently Ada 2012), and in addition a small number +of GNAT specific extensions are recognized as follows: + + + +*Constrained attribute for generic objects* + The `Constrained` attribute is permitted for objects of + generic types. The result indicates if the corresponding actual + is constrained. + + +Pragma External +=============== + +Syntax: + + +:: + + pragma External ( + [ Convention =>] convention_IDENTIFIER, + [ Entity =>] LOCAL_NAME + [, [External_Name =>] static_string_EXPRESSION ] + [, [Link_Name =>] static_string_EXPRESSION ]); + + +This pragma is identical in syntax and semantics to pragma +`Export` as defined in the Ada Reference Manual. It is +provided for compatibility with some Ada 83 compilers that +used this pragma for exactly the same purposes as pragma +`Export` before the latter was standardized. + +Pragma External_Name_Casing +=========================== +.. index:: Dec Ada 83 casing compatibility + +.. index:: External Names, casing + +.. index:: Casing of External names + + +Syntax: + + +:: + + pragma External_Name_Casing ( + Uppercase | Lowercase + [, Uppercase | Lowercase | As_Is]); + + +This pragma provides control over the casing of external names associated +with Import and Export pragmas. There are two cases to consider: + + + +* Implicit external names + + Implicit external names are derived from identifiers. The most common case + arises when a standard Ada Import or Export pragma is used with only two + arguments, as in: + + .. code-block:: ada + + pragma Import (C, C_Routine); + + Since Ada is a case-insensitive language, the spelling of the identifier in + the Ada source program does not provide any information on the desired + casing of the external name, and so a convention is needed. In GNAT the + default treatment is that such names are converted to all lower case + letters. This corresponds to the normal C style in many environments. + The first argument of pragma `External_Name_Casing` can be used to + control this treatment. If `Uppercase` is specified, then the name + will be forced to all uppercase letters. If `Lowercase` is specified, + then the normal default of all lower case letters will be used. + + This same implicit treatment is also used in the case of extended DEC Ada 83 + compatible Import and Export pragmas where an external name is explicitly + specified using an identifier rather than a string. + + +* Explicit external names + + Explicit external names are given as string literals. The most common case + arises when a standard Ada Import or Export pragma is used with three + arguments, as in: + + .. code-block:: ada + + pragma Import (C, C_Routine, "C_routine"); + + In this case, the string literal normally provides the exact casing required + for the external name. The second argument of pragma + `External_Name_Casing` may be used to modify this behavior. + If `Uppercase` is specified, then the name + will be forced to all uppercase letters. If `Lowercase` is specified, + then the name will be forced to all lowercase letters. A specification of + `As_Is` provides the normal default behavior in which the casing is + taken from the string provided. + +This pragma may appear anywhere that a pragma is valid. In particular, it +can be used as a configuration pragma in the :file:`gnat.adc` file, in which +case it applies to all subsequent compilations, or it can be used as a program +unit pragma, in which case it only applies to the current unit, or it can +be used more locally to control individual Import/Export pragmas. + +It was primarily intended for use with OpenVMS systems, where many +compilers convert all symbols to upper case by default. For interfacing to +such compilers (e.g., the DEC C compiler), it may be convenient to use +the pragma: + +.. code-block:: ada + + pragma External_Name_Casing (Uppercase, Uppercase); + + +to enforce the upper casing of all external symbols. + +Pragma Fast_Math +================ + +Syntax: + + +.. code-block:: ada + + pragma Fast_Math; + + +This is a configuration pragma which activates a mode in which speed is +considered more important for floating-point operations than absolutely +accurate adherence to the requirements of the standard. Currently the +following operations are affected: + + + +*Complex Multiplication* + The normal simple formula for complex multiplication can result in intermediate + overflows for numbers near the end of the range. The Ada standard requires that + this situation be detected and corrected by scaling, but in Fast_Math mode such + cases will simply result in overflow. Note that to take advantage of this you + must instantiate your own version of `Ada.Numerics.Generic_Complex_Types` + under control of the pragma, rather than use the preinstantiated versions. + +Pragma Favor_Top_Level +====================== + +Syntax: + + +.. code-block:: ada + + pragma Favor_Top_Level (type_NAME); + + +The named type must be an access-to-subprogram type. This pragma is an +efficiency hint to the compiler, regarding the use of 'Access or +'Unrestricted_Access on nested (non-library-level) subprograms. The +pragma means that nested subprograms are not used with this type, or +are rare, so that the generated code should be efficient in the +top-level case. When this pragma is used, dynamically generated +trampolines may be used on some targets for nested subprograms. +See also the No_Implicit_Dynamic_Code restriction. + +Pragma Finalize_Storage_Only +============================ + +Syntax: + + +.. code-block:: ada + + pragma Finalize_Storage_Only (first_subtype_LOCAL_NAME); + + +This pragma allows the compiler not to emit a Finalize call for objects +defined at the library level. This is mostly useful for types where +finalization is only used to deal with storage reclamation since in most +environments it is not necessary to reclaim memory just before terminating +execution, hence the name. + +Pragma Float_Representation +=========================== + +Syntax:: + + pragma Float_Representation (FLOAT_REP[, float_type_LOCAL_NAME]); + + FLOAT_REP ::= VAX_Float | IEEE_Float + + +In the one argument form, this pragma is a configuration pragma which +allows control over the internal representation chosen for the predefined +floating point types declared in the packages `Standard` and +`System`. This pragma is only provided for compatibility and has no effect. + +The two argument form specifies the representation to be used for +the specified floating-point type. The argument must +be `IEEE_Float` to specify the use of IEEE format, as follows: + +* + For a digits value of 6, 32-bit IEEE short format will be used. +* + For a digits value of 15, 64-bit IEEE long format will be used. +* + No other value of digits is permitted. + +Pragma Global +============= + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 6.1.4. + +Pragma Ident +============ + +Syntax: + + +.. code-block:: ada + + pragma Ident (static_string_EXPRESSION); + + +This pragma is identical in effect to pragma `Comment`. It is provided +for compatibility with other Ada compilers providing this pragma. + +Pragma Implementation_Defined +============================= + +Syntax: + + +.. code-block:: ada + + pragma Implementation_Defined (local_NAME); + + +This pragma marks a previously declared entioty as implementation-defined. +For an overloaded entity, applies to the most recent homonym. + + +.. code-block:: ada + + pragma Implementation_Defined; + + +The form with no arguments appears anywhere within a scope, most +typically a package spec, and indicates that all entities that are +defined within the package spec are Implementation_Defined. + +This pragma is used within the GNAT runtime library to identify +implementation-defined entities introduced in language-defined units, +for the purpose of implementing the No_Implementation_Identifiers +restriction. + +Pragma Implemented +================== + +Syntax: + + +:: + + pragma Implemented (procedure_LOCAL_NAME, implementation_kind); + + implementation_kind ::= By_Entry | By_Protected_Procedure | By_Any + + +This is an Ada 2012 representation pragma which applies to protected, task +and synchronized interface primitives. The use of pragma Implemented provides +a way to impose a static requirement on the overriding operation by adhering +to one of the three implementation kinds: entry, protected procedure or any of +the above. This pragma is available in all earlier versions of Ada as an +implementation-defined pragma. + + +.. code-block:: ada + + type Synch_Iface is synchronized interface; + procedure Prim_Op (Obj : in out Iface) is abstract; + pragma Implemented (Prim_Op, By_Protected_Procedure); + + protected type Prot_1 is new Synch_Iface with + procedure Prim_Op; -- Legal + end Prot_1; + + protected type Prot_2 is new Synch_Iface with + entry Prim_Op; -- Illegal + end Prot_2; + + task type Task_Typ is new Synch_Iface with + entry Prim_Op; -- Illegal + end Task_Typ; + + +When applied to the procedure_or_entry_NAME of a requeue statement, pragma +Implemented determines the runtime behavior of the requeue. Implementation kind +By_Entry guarantees that the action of requeueing will proceed from an entry to +another entry. Implementation kind By_Protected_Procedure transforms the +requeue into a dispatching call, thus eliminating the chance of blocking. Kind +By_Any shares the behavior of By_Entry and By_Protected_Procedure depending on +the target's overriding subprogram kind. + +Pragma Implicit_Packing +======================= +.. index:: Rational Profile + +Syntax: + + +.. code-block:: ada + + pragma Implicit_Packing; + + +This is a configuration pragma that requests implicit packing for packed +arrays for which a size clause is given but no explicit pragma Pack or +specification of Component_Size is present. It also applies to records +where no record representation clause is present. Consider this example: + + +.. code-block:: ada + + type R is array (0 .. 7) of Boolean; + for R'Size use 8; + + +In accordance with the recommendation in the RM (RM 13.3(53)), a Size clause +does not change the layout of a composite object. So the Size clause in the +above example is normally rejected, since the default layout of the array uses +8-bit components, and thus the array requires a minimum of 64 bits. + +If this declaration is compiled in a region of code covered by an occurrence +of the configuration pragma Implicit_Packing, then the Size clause in this +and similar examples will cause implicit packing and thus be accepted. For +this implicit packing to occur, the type in question must be an array of small +components whose size is known at compile time, and the Size clause must +specify the exact size that corresponds to the number of elements in the array +multiplied by the size in bits of the component type (both single and +multi-dimensioned arrays can be controlled with this pragma). + +.. index:: Array packing + +Similarly, the following example shows the use in the record case + + +.. code-block:: ada + + type r is record + a, b, c, d, e, f, g, h : boolean; + chr : character; + end record; + for r'size use 16; + + +Without a pragma Pack, each Boolean field requires 8 bits, so the +minimum size is 72 bits, but with a pragma Pack, 16 bits would be +sufficient. The use of pragma Implicit_Packing allows this record +declaration to compile without an explicit pragma Pack. + +Pragma Import_Function +====================== + +Syntax: + + +:: + + pragma Import_Function ( + [Internal =>] LOCAL_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Result_Type =>] SUBTYPE_MARK] + [, [Mechanism =>] MECHANISM] + [, [Result_Mechanism =>] MECHANISM_NAME]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + + PARAMETER_TYPES ::= + null + | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} + + TYPE_DESIGNATOR ::= + subtype_NAME + | subtype_Name ' Access + + MECHANISM ::= + MECHANISM_NAME + | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) + + MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + + MECHANISM_NAME ::= + Value + | Reference + + +This pragma is used in conjunction with a pragma `Import` to +specify additional information for an imported function. The pragma +`Import` (or equivalent pragma `Interface`) must precede the +`Import_Function` pragma and both must appear in the same +declarative part as the function specification. + +The `Internal` argument must uniquely designate +the function to which the +pragma applies. If more than one function name exists of this name in +the declarative part you must use the `Parameter_Types` and +`Result_Type` parameters to achieve the required unique +designation. Subtype marks in these parameters must exactly match the +subtypes in the corresponding function specification, using positional +notation to match parameters with subtype marks. +The form with an `'Access` attribute can be used to match an +anonymous access parameter. + +You may optionally use the `Mechanism` and `Result_Mechanism` +parameters to specify passing mechanisms for the +parameters and result. If you specify a single mechanism name, it +applies to all parameters. Otherwise you may specify a mechanism on a +parameter by parameter basis using either positional or named +notation. If the mechanism is not specified, the default mechanism +is used. + +Pragma Import_Object +==================== + +Syntax: + + +:: + + pragma Import_Object + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Size =>] EXTERNAL_SYMBOL]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + + +This pragma designates an object as imported, and apart from the +extended rules for external symbols, is identical in effect to the use of +the normal `Import` pragma applied to an object. Unlike the +subprogram case, you need not use a separate `Import` pragma, +although you may do so (and probably should do so from a portability +point of view). `size` is syntax checked, but otherwise ignored by +GNAT. + +Pragma Import_Procedure +======================= + +Syntax: + + +:: + + pragma Import_Procedure ( + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + + PARAMETER_TYPES ::= + null + | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} + + TYPE_DESIGNATOR ::= + subtype_NAME + | subtype_Name ' Access + + MECHANISM ::= + MECHANISM_NAME + | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) + + MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + + MECHANISM_NAME ::= Value | Reference + + +This pragma is identical to `Import_Function` except that it +applies to a procedure rather than a function and the parameters +`Result_Type` and `Result_Mechanism` are not permitted. + +Pragma Import_Valued_Procedure +============================== + +Syntax: + + +:: + + pragma Import_Valued_Procedure ( + [Internal =>] LOCAL_NAME + [, [External =>] EXTERNAL_SYMBOL] + [, [Parameter_Types =>] PARAMETER_TYPES] + [, [Mechanism =>] MECHANISM]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + + PARAMETER_TYPES ::= + null + | TYPE_DESIGNATOR {, TYPE_DESIGNATOR} + + TYPE_DESIGNATOR ::= + subtype_NAME + | subtype_Name ' Access + + MECHANISM ::= + MECHANISM_NAME + | (MECHANISM_ASSOCIATION {, MECHANISM_ASSOCIATION}) + + MECHANISM_ASSOCIATION ::= + [formal_parameter_NAME =>] MECHANISM_NAME + + MECHANISM_NAME ::= Value | Reference + + +This pragma is identical to `Import_Procedure` except that the +first parameter of `LOCAL_NAME`, which must be present, must be of +mode `OUT`, and externally the subprogram is treated as a function +with this parameter as the result of the function. The purpose of this +capability is to allow the use of `OUT` and `IN OUT` +parameters in interfacing to external functions (which are not permitted +in Ada functions). You may optionally use the `Mechanism` +parameters to specify passing mechanisms for the parameters. +If you specify a single mechanism name, it applies to all parameters. +Otherwise you may specify a mechanism on a parameter by parameter +basis using either positional or named notation. If the mechanism is not +specified, the default mechanism is used. + +Note that it is important to use this pragma in conjunction with a separate +pragma Import that specifies the desired convention, since otherwise the +default convention is Ada, which is almost certainly not what is required. + +Pragma Independent +================== + +Syntax: + + +.. code-block:: ada + + pragma Independent (Local_NAME); + + +This pragma is standard in Ada 2012 mode (which also provides an aspect +of the same name). It is also available as an implementation-defined +pragma in all earlier versions. It specifies that the +designated object or all objects of the designated type must be +independently addressable. This means that separate tasks can safely +manipulate such objects. For example, if two components of a record are +independent, then two separate tasks may access these two components. +This may place +constraints on the representation of the object (for instance prohibiting +tight packing). + +Pragma Independent_Components +============================= + +Syntax: + + +.. code-block:: ada + + pragma Independent_Components (Local_NAME); + + +This pragma is standard in Ada 2012 mode (which also provides an aspect +of the same name). It is also available as an implementation-defined +pragma in all earlier versions. It specifies that the components of the +designated object, or the components of each object of the designated +type, must be +independently addressable. This means that separate tasks can safely +manipulate separate components in the composite object. This may place +constraints on the representation of the object (for instance prohibiting +tight packing). + +Pragma Initial_Condition +======================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.1.6. + +Pragma Initialize_Scalars +========================= +.. index:: debugging with Initialize_Scalars + +Syntax: + + +.. code-block:: ada + + pragma Initialize_Scalars; + + +This pragma is similar to `Normalize_Scalars` conceptually but has +two important differences. First, there is no requirement for the pragma +to be used uniformly in all units of a partition, in particular, it is fine +to use this just for some or all of the application units of a partition, +without needing to recompile the run-time library. + +In the case where some units are compiled with the pragma, and some without, +then a declaration of a variable where the type is defined in package +Standard or is locally declared will always be subject to initialization, +as will any declaration of a scalar variable. For composite variables, +whether the variable is initialized may also depend on whether the package +in which the type of the variable is declared is compiled with the pragma. + +The other important difference is that you can control the value used +for initializing scalar objects. At bind time, you can select several +options for initialization. You can +initialize with invalid values (similar to Normalize_Scalars, though for +Initialize_Scalars it is not always possible to determine the invalid +values in complex cases like signed component fields with non-standard +sizes). You can also initialize with high or +low values, or with a specified bit pattern. See the GNAT +User's Guide for binder options for specifying these cases. + +This means that you can compile a program, and then without having to +recompile the program, you can run it with different values being used +for initializing otherwise uninitialized values, to test if your program +behavior depends on the choice. Of course the behavior should not change, +and if it does, then most likely you have an incorrect reference to an +uninitialized value. + +It is even possible to change the value at execution time eliminating even +the need to rebind with a different switch using an environment variable. +See the GNAT User's Guide for details. + +Note that pragma `Initialize_Scalars` is particularly useful in +conjunction with the enhanced validity checking that is now provided +in GNAT, which checks for invalid values under more conditions. +Using this feature (see description of the *-gnatV* flag in the +GNAT User's Guide) in conjunction with +pragma `Initialize_Scalars` +provides a powerful new tool to assist in the detection of problems +caused by uninitialized variables. + +Note: the use of `Initialize_Scalars` has a fairly extensive +effect on the generated code. This may cause your code to be +substantially larger. It may also cause an increase in the amount +of stack required, so it is probably a good idea to turn on stack +checking (see description of stack checking in the GNAT +User's Guide) when using this pragma. + +Pragma Initializes +================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.1.5. + +Pragma Inline_Always +==================== + +Syntax: + + +:: + + pragma Inline_Always (NAME [, NAME]); + + +Similar to pragma `Inline` except that inlining is not subject to +the use of option *-gnatn* or *-gnatN* and the inlining +happens regardless of whether these options are used. + +Pragma Inline_Generic +===================== + +Syntax: + + +:: + + pragma Inline_Generic (GNAME {, GNAME}); + + GNAME ::= generic_unit_NAME | generic_instance_NAME + + +This pragma is provided for compatibility with Dec Ada 83. It has +no effect in `GNAT` (which always inlines generics), other +than to check that the given names are all names of generic units or +generic instances. + +Pragma Interface +================ + +Syntax: + + +:: + + pragma Interface ( + [Convention =>] convention_identifier, + [Entity =>] local_NAME + [, [External_Name =>] static_string_expression] + [, [Link_Name =>] static_string_expression]); + + +This pragma is identical in syntax and semantics to +the standard Ada pragma `Import`. It is provided for compatibility +with Ada 83. The definition is upwards compatible both with pragma +`Interface` as defined in the Ada 83 Reference Manual, and also +with some extended implementations of this pragma in certain Ada 83 +implementations. The only difference between pragma `Interface` +and pragma `Import` is that there is special circuitry to allow +both pragmas to appear for the same subprogram entity (normally it +is illegal to have multiple `Import` pragmas. This is useful in +maintaining Ada 83/Ada 95 compatibility and is compatible with other +Ada 83 compilers. + +Pragma Interface_Name +===================== + +Syntax: + + +:: + + pragma Interface_Name ( + [Entity =>] LOCAL_NAME + [, [External_Name =>] static_string_EXPRESSION] + [, [Link_Name =>] static_string_EXPRESSION]); + + +This pragma provides an alternative way of specifying the interface name +for an interfaced subprogram, and is provided for compatibility with Ada +83 compilers that use the pragma for this purpose. You must provide at +least one of `External_Name` or `Link_Name`. + +Pragma Interrupt_Handler +======================== + +Syntax: + + +.. code-block:: ada + + pragma Interrupt_Handler (procedure_LOCAL_NAME); + + +This program unit pragma is supported for parameterless protected procedures +as described in Annex C of the Ada Reference Manual. On the AAMP target +the pragma can also be specified for nonprotected parameterless procedures +that are declared at the library level (which includes procedures +declared at the top level of a library package). In the case of AAMP, +when this pragma is applied to a nonprotected procedure, the instruction +`IERET` is generated for returns from the procedure, enabling +maskable interrupts, in place of the normal return instruction. + +Pragma Interrupt_State +====================== + +Syntax: + + +:: + + pragma Interrupt_State + ([Name =>] value, + [State =>] SYSTEM | RUNTIME | USER); + + +Normally certain interrupts are reserved to the implementation. Any attempt +to attach an interrupt causes Program_Error to be raised, as described in +RM C.3.2(22). A typical example is the `SIGINT` interrupt used in +many systems for an :kbd:`Ctrl-C` interrupt. Normally this interrupt is +reserved to the implementation, so that :kbd:`Ctrl-C` can be used to +interrupt execution. Additionally, signals such as `SIGSEGV`, +`SIGABRT`, `SIGFPE` and `SIGILL` are often mapped to specific +Ada exceptions, or used to implement run-time functions such as the +`abort` statement and stack overflow checking. + +Pragma `Interrupt_State` provides a general mechanism for overriding +such uses of interrupts. It subsumes the functionality of pragma +`Unreserve_All_Interrupts`. Pragma `Interrupt_State` is not +available on Windows or VMS. On all other platforms than VxWorks, +it applies to signals; on VxWorks, it applies to vectored hardware interrupts +and may be used to mark interrupts required by the board support package +as reserved. + +Interrupts can be in one of three states: + +* System + + The interrupt is reserved (no Ada handler can be installed), and the + Ada run-time may not install a handler. As a result you are guaranteed + standard system default action if this interrupt is raised. + +* Runtime + + The interrupt is reserved (no Ada handler can be installed). The run time + is allowed to install a handler for internal control purposes, but is + not required to do so. + +* User + + The interrupt is unreserved. The user may install a handler to provide + some other action. + +These states are the allowed values of the `State` parameter of the +pragma. The `Name` parameter is a value of the type +`Ada.Interrupts.Interrupt_ID`. Typically, it is a name declared in +`Ada.Interrupts.Names`. + +This is a configuration pragma, and the binder will check that there +are no inconsistencies between different units in a partition in how a +given interrupt is specified. It may appear anywhere a pragma is legal. + +The effect is to move the interrupt to the specified state. + +By declaring interrupts to be SYSTEM, you guarantee the standard system +action, such as a core dump. + +By declaring interrupts to be USER, you guarantee that you can install +a handler. + +Note that certain signals on many operating systems cannot be caught and +handled by applications. In such cases, the pragma is ignored. See the +operating system documentation, or the value of the array `Reserved` +declared in the spec of package `System.OS_Interface`. + +Overriding the default state of signals used by the Ada runtime may interfere +with an application's runtime behavior in the cases of the synchronous signals, +and in the case of the signal used to implement the `abort` statement. + +Pragma Invariant +================ + +Syntax: + + +:: + + pragma Invariant + ([Entity =>] private_type_LOCAL_NAME, + [Check =>] EXPRESSION + [,[Message =>] String_Expression]); + + +This pragma provides exactly the same capabilities as the Type_Invariant aspect +defined in AI05-0146-1, and in the Ada 2012 Reference Manual. The +Type_Invariant aspect is fully implemented in Ada 2012 mode, but since it +requires the use of the aspect syntax, which is not available except in 2012 +mode, it is not possible to use the Type_Invariant aspect in earlier versions +of Ada. However the Invariant pragma may be used in any version of Ada. Also +note that the aspect Invariant is a synonym in GNAT for the aspect +Type_Invariant, but there is no pragma Type_Invariant. + +The pragma must appear within the visible part of the package specification, +after the type to which its Entity argument appears. As with the Invariant +aspect, the Check expression is not analyzed until the end of the visible +part of the package, so it may contain forward references. The Message +argument, if present, provides the exception message used if the invariant +is violated. If no Message parameter is provided, a default message that +identifies the line on which the pragma appears is used. + +It is permissible to have multiple Invariants for the same type entity, in +which case they are and'ed together. It is permissible to use this pragma +in Ada 2012 mode, but you cannot have both an invariant aspect and an +invariant pragma for the same entity. + +For further details on the use of this pragma, see the Ada 2012 documentation +of the Type_Invariant aspect. + +Pragma Java_Constructor +======================= + +Syntax: + + +:: + + pragma Java_Constructor ([Entity =>] function_LOCAL_NAME); + + +This pragma is used to assert that the specified Ada function should be +mapped to the Java constructor for some Ada tagged record type. + +See section 7.3.2 of the +`GNAT User's Guide: Supplement for the JVM Platform.` +for related information. + +Pragma Java_Interface +===================== + +Syntax: + + +:: + + pragma Java_Interface ([Entity =>] abstract_tagged_type_LOCAL_NAME); + + +This pragma is used to assert that the specified Ada abstract tagged type +is to be mapped to a Java interface name. + +See sections 7.1 and 7.2 of the +`GNAT User's Guide: Supplement for the JVM Platform.` +for related information. + +Pragma Keep_Names +================= + +Syntax: + + +:: + + pragma Keep_Names ([On =>] enumeration_first_subtype_LOCAL_NAME); + + +The `LOCAL_NAME` argument +must refer to an enumeration first subtype +in the current declarative part. The effect is to retain the enumeration +literal names for use by `Image` and `Value` even if a global +`Discard_Names` pragma applies. This is useful when you want to +generally suppress enumeration literal names and for example you therefore +use a `Discard_Names` pragma in the :file:`gnat.adc` file, but you +want to retain the names for specific enumeration types. + +Pragma License +============== +.. index:: License checking + +Syntax: + + +.. code-block:: ada + + pragma License (Unrestricted | GPL | Modified_GPL | Restricted); + + +This pragma is provided to allow automated checking for appropriate license +conditions with respect to the standard and modified GPL. A pragma +`License`, which is a configuration pragma that typically appears at +the start of a source file or in a separate :file:`gnat.adc` file, specifies +the licensing conditions of a unit as follows: + +* Unrestricted + This is used for a unit that can be freely used with no license restrictions. + Examples of such units are public domain units, and units from the Ada + Reference Manual. + +* GPL + This is used for a unit that is licensed under the unmodified GPL, and which + therefore cannot be `with`'ed by a restricted unit. + +* Modified_GPL + This is used for a unit licensed under the GNAT modified GPL that includes + a special exception paragraph that specifically permits the inclusion of + the unit in programs without requiring the entire program to be released + under the GPL. + +* Restricted + This is used for a unit that is restricted in that it is not permitted to + depend on units that are licensed under the GPL. Typical examples are + proprietary code that is to be released under more restrictive license + conditions. Note that restricted units are permitted to `with` units + which are licensed under the modified GPL (this is the whole point of the + modified GPL). + + +Normally a unit with no `License` pragma is considered to have an +unknown license, and no checking is done. However, standard GNAT headers +are recognized, and license information is derived from them as follows. + +A GNAT license header starts with a line containing 78 hyphens. The following +comment text is searched for the appearance of any of the following strings. + +If the string 'GNU General Public License' is found, then the unit is assumed +to have GPL license, unless the string 'As a special exception' follows, in +which case the license is assumed to be modified GPL. + +If one of the strings +'This specification is adapted from the Ada Semantic Interface' or +'This specification is derived from the Ada Reference Manual' is found +then the unit is assumed to be unrestricted. + +These default actions means that a program with a restricted license pragma +will automatically get warnings if a GPL unit is inappropriately +`with`'ed. For example, the program: + +.. code-block:: ada + + with Sem_Ch3; + with GNAT.Sockets; + procedure Secret_Stuff is + ... + end Secret_Stuff + + +if compiled with pragma `License` (`Restricted`) in a +:file:`gnat.adc` file will generate the warning:: + + 1. with Sem_Ch3; + | + >>> license of withed unit "Sem_Ch3" is incompatible + + 2. with GNAT.Sockets; + 3. procedure Secret_Stuff is + + +Here we get a warning on `Sem_Ch3` since it is part of the GNAT +compiler and is licensed under the +GPL, but no warning for `GNAT.Sockets` which is part of the GNAT +run time, and is therefore licensed under the modified GPL. + +Pragma Link_With +================ + +Syntax: + + +:: + + pragma Link_With (static_string_EXPRESSION {,static_string_EXPRESSION}); + + +This pragma is provided for compatibility with certain Ada 83 compilers. +It has exactly the same effect as pragma `Linker_Options` except +that spaces occurring within one of the string expressions are treated +as separators. For example, in the following case: + +.. code-block:: ada + + pragma Link_With ("-labc -ldef"); + + +results in passing the strings `-labc` and `-ldef` as two +separate arguments to the linker. In addition pragma Link_With allows +multiple arguments, with the same effect as successive pragmas. + +Pragma Linker_Alias +=================== + +Syntax: + + +:: + + pragma Linker_Alias ( + [Entity =>] LOCAL_NAME, + [Target =>] static_string_EXPRESSION); + + +`LOCAL_NAME` must refer to an object that is declared at the library +level. This pragma establishes the given entity as a linker alias for the +given target. It is equivalent to `__attribute__((alias))` in GNU C +and causes `LOCAL_NAME` to be emitted as an alias for the symbol +`static_string_EXPRESSION` in the object file, that is to say no space +is reserved for `LOCAL_NAME` by the assembler and it will be resolved +to the same address as `static_string_EXPRESSION` by the linker. + +The actual linker name for the target must be used (e.g., the fully +encoded name with qualification in Ada, or the mangled name in C++), +or it must be declared using the C convention with `pragma Import` +or `pragma Export`. + +Not all target machines support this pragma. On some of them it is accepted +only if `pragma Weak_External` has been applied to `LOCAL_NAME`. + + +.. code-block:: ada + + -- Example of the use of pragma Linker_Alias + + package p is + i : Integer := 1; + pragma Export (C, i); + + new_name_for_i : Integer; + pragma Linker_Alias (new_name_for_i, "i"); + end p; + + +Pragma Linker_Constructor +========================= + +Syntax: + + +.. code-block:: ada + + pragma Linker_Constructor (procedure_LOCAL_NAME); + + +`procedure_LOCAL_NAME` must refer to a parameterless procedure that +is declared at the library level. A procedure to which this pragma is +applied will be treated as an initialization routine by the linker. +It is equivalent to `__attribute__((constructor))` in GNU C and +causes `procedure_LOCAL_NAME` to be invoked before the entry point +of the executable is called (or immediately after the shared library is +loaded if the procedure is linked in a shared library), in particular +before the Ada run-time environment is set up. + +Because of these specific contexts, the set of operations such a procedure +can perform is very limited and the type of objects it can manipulate is +essentially restricted to the elementary types. In particular, it must only +contain code to which pragma Restrictions (No_Elaboration_Code) applies. + +This pragma is used by GNAT to implement auto-initialization of shared Stand +Alone Libraries, which provides a related capability without the restrictions +listed above. Where possible, the use of Stand Alone Libraries is preferable +to the use of this pragma. + +Pragma Linker_Destructor +======================== + +Syntax: + + +.. code-block:: ada + + pragma Linker_Destructor (procedure_LOCAL_NAME); + + +`procedure_LOCAL_NAME` must refer to a parameterless procedure that +is declared at the library level. A procedure to which this pragma is +applied will be treated as a finalization routine by the linker. +It is equivalent to `__attribute__((destructor))` in GNU C and +causes `procedure_LOCAL_NAME` to be invoked after the entry point +of the executable has exited (or immediately before the shared library +is unloaded if the procedure is linked in a shared library), in particular +after the Ada run-time environment is shut down. + +See `pragma Linker_Constructor` for the set of restrictions that apply +because of these specific contexts. + +Pragma Linker_Section +===================== + +Syntax: + + +:: + + pragma Linker_Section ( + [Entity =>] LOCAL_NAME, + [Section =>] static_string_EXPRESSION); + + +`LOCAL_NAME` must refer to an object, type, or subprogram that is +declared at the library level. This pragma specifies the name of the +linker section for the given entity. It is equivalent to +`__attribute__((section))` in GNU C and causes `LOCAL_NAME` to +be placed in the `static_string_EXPRESSION` section of the +executable (assuming the linker doesn't rename the section). +GNAT also provides an implementation defined aspect of the same name. + +In the case of specifying this aspect for a type, the effect is to +specify the corresponding for all library level objects of the type which +do not have an explicit linker section set. Note that this only applies to +whole objects, not to components of composite objects. + +In the case of a subprogram, the linker section applies to all previously +declared matching overloaded subprograms in the current declarative part +which do not already have a linker section assigned. The linker section +aspect is useful in this case for specifying different linker sections +for different elements of such an overloaded set. + +Note that an empty string specifies that no linker section is specified. +This is not quite the same as omitting the pragma or aspect, since it +can be used to specify that one element of an overloaded set of subprograms +has the default linker section, or that one object of a type for which a +linker section is specified should has the default linker section. + +The compiler normally places library-level entities in standard sections +depending on the class: procedures and functions generally go in the +`.text` section, initialized variables in the `.data` section +and uninitialized variables in the `.bss` section. + +Other, special sections may exist on given target machines to map special +hardware, for example I/O ports or flash memory. This pragma is a means to +defer the final layout of the executable to the linker, thus fully working +at the symbolic level with the compiler. + +Some file formats do not support arbitrary sections so not all target +machines support this pragma. The use of this pragma may cause a program +execution to be erroneous if it is used to place an entity into an +inappropriate section (e.g., a modified variable into the `.text` +section). See also `pragma Persistent_BSS`. + + +.. code-block:: ada + + -- Example of the use of pragma Linker_Section + + package IO_Card is + Port_A : Integer; + pragma Volatile (Port_A); + pragma Linker_Section (Port_A, ".bss.port_a"); + + Port_B : Integer; + pragma Volatile (Port_B); + pragma Linker_Section (Port_B, ".bss.port_b"); + + type Port_Type is new Integer with Linker_Section => ".bss"; + PA : Port_Type with Linker_Section => ".bss.PA"; + PB : Port_Type; -- ends up in linker section ".bss" + + procedure Q with Linker_Section => "Qsection"; + end IO_Card; + + +Pragma Lock_Free +================ + +Syntax: +This pragma may be specified for protected types or objects. It specifies that +the implementation of protected operations must be implemented without locks. +Compilation fails if the compiler cannot generate lock-free code for the +operations. + +Pragma Loop_Invariant +===================== + +Syntax: + + +.. code-block:: ada + + pragma Loop_Invariant ( boolean_EXPRESSION ); + + +The effect of this pragma is similar to that of pragma `Assert`, +except that in an `Assertion_Policy` pragma, the identifier +`Loop_Invariant` is used to control whether it is ignored or checked +(or disabled). + +`Loop_Invariant` can only appear as one of the items in the sequence +of statements of a loop body, or nested inside block statements that +appear in the sequence of statements of a loop body. +The intention is that it be used to +represent a "loop invariant" assertion, i.e. something that is true each +time through the loop, and which can be used to show that the loop is +achieving its purpose. + +Multiple `Loop_Invariant` and `Loop_Variant` pragmas that +apply to the same loop should be grouped in the same sequence of +statements. + +To aid in writing such invariants, the special attribute `Loop_Entry` +may be used to refer to the value of an expression on entry to the loop. This +attribute can only be used within the expression of a `Loop_Invariant` +pragma. For full details, see documentation of attribute `Loop_Entry`. + +Pragma Loop_Optimize +==================== + +Syntax: + + +:: + + pragma Loop_Optimize (OPTIMIZATION_HINT {, OPTIMIZATION_HINT}); + + OPTIMIZATION_HINT ::= Ivdep | No_Unroll | Unroll | No_Vector | Vector + + +This pragma must appear immediately within a loop statement. It allows the +programmer to specify optimization hints for the enclosing loop. The hints +are not mutually exclusive and can be freely mixed, but not all combinations +will yield a sensible outcome. + +There are five supported optimization hints for a loop: + +* Ivdep + + The programmer asserts that there are no loop-carried dependencies + which would prevent consecutive iterations of the loop from being + executed simultaneously. + +* No_Unroll + + The loop must not be unrolled. This is a strong hint: the compiler will not + unroll a loop marked with this hint. + +* Unroll + + The loop should be unrolled. This is a weak hint: the compiler will try to + apply unrolling to this loop preferably to other optimizations, notably + vectorization, but there is no guarantee that the loop will be unrolled. + +* No_Vector + + The loop must not be vectorized. This is a strong hint: the compiler will not + vectorize a loop marked with this hint. + +* Vector + + The loop should be vectorized. This is a weak hint: the compiler will try to + apply vectorization to this loop preferably to other optimizations, notably + unrolling, but there is no guarantee that the loop will be vectorized. + + +These hints do not remove the need to pass the appropriate switches to the +compiler in order to enable the relevant optimizations, that is to say +*-funroll-loops* for unrolling and *-ftree-vectorize* for +vectorization. + +Pragma Loop_Variant +=================== + +Syntax: + + +:: + + pragma Loop_Variant ( LOOP_VARIANT_ITEM {, LOOP_VARIANT_ITEM } ); + LOOP_VARIANT_ITEM ::= CHANGE_DIRECTION => discrete_EXPRESSION + CHANGE_DIRECTION ::= Increases | Decreases + + +`Loop_Variant` can only appear as one of the items in the sequence +of statements of a loop body, or nested inside block statements that +appear in the sequence of statements of a loop body. +It allows the specification of quantities which must always +decrease or increase in successive iterations of the loop. In its simplest +form, just one expression is specified, whose value must increase or decrease +on each iteration of the loop. + +In a more complex form, multiple arguments can be given which are intepreted +in a nesting lexicographic manner. For example: + +.. code-block:: ada + + pragma Loop_Variant (Increases => X, Decreases => Y); + + +specifies that each time through the loop either X increases, or X stays +the same and Y decreases. A `Loop_Variant` pragma ensures that the +loop is making progress. It can be useful in helping to show informally +or prove formally that the loop always terminates. + +`Loop_Variant` is an assertion whose effect can be controlled using +an `Assertion_Policy` with a check name of `Loop_Variant`. The +policy can be `Check` to enable the loop variant check, `Ignore` +to ignore the check (in which case the pragma has no effect on the program), +or `Disable` in which case the pragma is not even checked for correct +syntax. + +Multiple `Loop_Invariant` and `Loop_Variant` pragmas that +apply to the same loop should be grouped in the same sequence of +statements. + +The `Loop_Entry` attribute may be used within the expressions of the +`Loop_Variant` pragma to refer to values on entry to the loop. + +Pragma Machine_Attribute +======================== + +Syntax: + + +:: + + pragma Machine_Attribute ( + [Entity =>] LOCAL_NAME, + [Attribute_Name =>] static_string_EXPRESSION + [, [Info =>] static_EXPRESSION] ); + + +Machine-dependent attributes can be specified for types and/or +declarations. This pragma is semantically equivalent to +`__attribute__((`attribute_name`))` (if `info` is not +specified) or `__attribute__((`attribute_name`(`info`))) +in GNU C, where ``attribute_name`` is recognized by the +compiler middle-end or the `TARGET_ATTRIBUTE_TABLE` machine +specific macro. A string literal for the optional parameter `info` +is transformed into an identifier, which may make this pragma unusable +for some attributes. +For further information see :title:`GNU Compiler Collection (GCC) Internals`. + +Pragma Main +=========== + +Syntax:: + + pragma Main + (MAIN_OPTION [, MAIN_OPTION]); + + MAIN_OPTION ::= + [Stack_Size =>] static_integer_EXPRESSION + | [Task_Stack_Size_Default =>] static_integer_EXPRESSION + | [Time_Slicing_Enabled =>] static_boolean_EXPRESSION + + +This pragma is provided for compatibility with OpenVMS VAX Systems. It has +no effect in GNAT, other than being syntax checked. + +Pragma Main_Storage +=================== + +Syntax:: + + pragma Main_Storage + (MAIN_STORAGE_OPTION [, MAIN_STORAGE_OPTION]); + + MAIN_STORAGE_OPTION ::= + [WORKING_STORAGE =>] static_SIMPLE_EXPRESSION + | [TOP_GUARD =>] static_SIMPLE_EXPRESSION + + +This pragma is provided for compatibility with OpenVMS VAX Systems. It has +no effect in GNAT, other than being syntax checked. + +Pragma No_Body +============== + +Syntax: + + +.. code-block:: ada + + pragma No_Body; + + +There are a number of cases in which a package spec does not require a body, +and in fact a body is not permitted. GNAT will not permit the spec to be +compiled if there is a body around. The pragma No_Body allows you to provide +a body file, even in a case where no body is allowed. The body file must +contain only comments and a single No_Body pragma. This is recognized by +the compiler as indicating that no body is logically present. + +This is particularly useful during maintenance when a package is modified in +such a way that a body needed before is no longer needed. The provision of a +dummy body with a No_Body pragma ensures that there is no interference from +earlier versions of the package body. + +Pragma No_Elaboration_Code_All +============================== + +Syntax: + + +:: + + pragma No_Elaboration_Code_All [(program_unit_NAME)]; + + +This is a program unit pragma (there is also an equivalent aspect of the +same name) that establishes the restriction `No_Elaboration_Code` for +the current unit and any extended main source units (body and subunits. +It also has has the effect of enforcing a transitive application of this +aspect, so that if any unit is implicitly or explicitly WITH'ed by the +current unit, it must also have the No_Elaboration_Code_All aspect set. +It may be applied to package or subprogram specs or their generic versions. + +Pragma No_Inline +================ + +Syntax: + + +:: + + pragma No_Inline (NAME {, NAME}); + + +This pragma suppresses inlining for the callable entity or the instances of +the generic subprogram designated by `NAME`, including inlining that +results from the use of pragma `Inline`. This pragma is always active, +in particular it is not subject to the use of option *-gnatn* or +*-gnatN*. It is illegal to specify both pragma `No_Inline` and +pragma `Inline_Always` for the same `NAME`. + +Pragma No_Return +================ + +Syntax: + + +:: + + pragma No_Return (procedure_LOCAL_NAME {, procedure_LOCAL_NAME}); + + +Each `procedure_LOCAL_NAME` argument must refer to one or more procedure +declarations in the current declarative part. A procedure to which this +pragma is applied may not contain any explicit `return` statements. +In addition, if the procedure contains any implicit returns from falling +off the end of a statement sequence, then execution of that implicit +return will cause Program_Error to be raised. + +One use of this pragma is to identify procedures whose only purpose is to raise +an exception. Another use of this pragma is to suppress incorrect warnings +about missing returns in functions, where the last statement of a function +statement sequence is a call to such a procedure. + +Note that in Ada 2005 mode, this pragma is part of the language. It is +available in all earlier versions of Ada as an implementation-defined +pragma. + +Pragma No_Run_Time +================== + +Syntax: + + +.. code-block:: ada + + pragma No_Run_Time; + + +This is an obsolete configuration pragma that historically was used to +set up a runtime library with no object code. It is now used only for +internal testing. The pragma has been superseded by the reconfigurable +runtime capability of `GNAT`. + +Pragma No_Strict_Aliasing +========================= + +Syntax: + + +:: + + pragma No_Strict_Aliasing [([Entity =>] type_LOCAL_NAME)]; + + +`type_LOCAL_NAME` must refer to an access type +declaration in the current declarative part. The effect is to inhibit +strict aliasing optimization for the given type. The form with no +arguments is a configuration pragma which applies to all access types +declared in units to which the pragma applies. For a detailed +description of the strict aliasing optimization, and the situations +in which it must be suppressed, see the section on Optimization and Strict Aliasing +in the :title:`GNAT User's Guide`. + +This pragma currently has no effects on access to unconstrained array types. + +Pragma No_Tagged_Streams +======================== + +Syntax: + + +:: + + pragma No_Tagged_Streams; + pragma No_Tagged_Streams [([Entity =>] tagged_type_LOCAL_NAME)]; + + +Normally when a tagged type is introduced using a full type declaration, +part of the processing includes generating stream access routines to be +used by stream attributes referencing the type (or one of its subtypes +or derived types). This can involve the generation of significant amounts +of code which is wasted space if stream routines are not needed for the +type in question. + +The `No_Tagged_Streams` pragma causes the generation of these stream +routines to be skipped, and any attempt to use stream operations on +types subject to this pragma will be statically rejected as illegal. + +There are two forms of the pragma. The form with no arguments must appear +in a declarative sequence or in the declarations of a package spec. This +pragma affects all subsequent root tagged types declared in the declaration +sequence, and specifies that no stream routines be generated. The form with +an argument (for which there is also a corresponding aspect) specifies a +single root tagged type for which stream routines are not to be generated. + +Once the pragma has been given for a particular root tagged type, all subtypes +and derived types of this type inherit the pragma automatically, so the effect +applies to a complete hierarchy (this is necessary to deal with the class-wide +dispatching versions of the stream routines). + +Pragma Normalize_Scalars +======================== + +Syntax: + + +.. code-block:: ada + + pragma Normalize_Scalars; + + +This is a language defined pragma which is fully implemented in GNAT. The +effect is to cause all scalar objects that are not otherwise initialized +to be initialized. The initial values are implementation dependent and +are as follows: + + + +*Standard.Character* + Objects whose root type is Standard.Character are initialized to + Character'Last unless the subtype range excludes NUL (in which case + NUL is used). This choice will always generate an invalid value if + one exists. + + +*Standard.Wide_Character* + Objects whose root type is Standard.Wide_Character are initialized to + Wide_Character'Last unless the subtype range excludes NUL (in which case + NUL is used). This choice will always generate an invalid value if + one exists. + + +*Standard.Wide_Wide_Character* + Objects whose root type is Standard.Wide_Wide_Character are initialized to + the invalid value 16#FFFF_FFFF# unless the subtype range excludes NUL (in + which case NUL is used). This choice will always generate an invalid value if + one exists. + + +*Integer types* + Objects of an integer type are treated differently depending on whether + negative values are present in the subtype. If no negative values are + present, then all one bits is used as the initial value except in the + special case where zero is excluded from the subtype, in which case + all zero bits are used. This choice will always generate an invalid + value if one exists. + + For subtypes with negative values present, the largest negative number + is used, except in the unusual case where this largest negative number + is in the subtype, and the largest positive number is not, in which case + the largest positive value is used. This choice will always generate + an invalid value if one exists. + + +*Floating-Point Types* + Objects of all floating-point types are initialized to all 1-bits. For + standard IEEE format, this corresponds to a NaN (not a number) which is + indeed an invalid value. + + +*Fixed-Point Types* + Objects of all fixed-point types are treated as described above for integers, + with the rules applying to the underlying integer value used to represent + the fixed-point value. + + +*Modular types* + Objects of a modular type are initialized to all one bits, except in + the special case where zero is excluded from the subtype, in which + case all zero bits are used. This choice will always generate an + invalid value if one exists. + + +*Enumeration types* + Objects of an enumeration type are initialized to all one-bits, i.e., to + the value `2 ** typ'Size - 1` unless the subtype excludes the literal + whose Pos value is zero, in which case a code of zero is used. This choice + will always generate an invalid value if one exists. + +.. _Pragma_Obsolescent: + +Pragma Obsolescent +================== + +Syntax: + + +:: + + pragma Obsolescent; + + pragma Obsolescent ( + [Message =>] static_string_EXPRESSION + [,[Version =>] Ada_05]]); + + pragma Obsolescent ( + [Entity =>] NAME + [,[Message =>] static_string_EXPRESSION + [,[Version =>] Ada_05]] ); + + +This pragma can occur immediately following a declaration of an entity, +including the case of a record component. If no Entity argument is present, +then this declaration is the one to which the pragma applies. If an Entity +parameter is present, it must either match the name of the entity in this +declaration, or alternatively, the pragma can immediately follow an enumeration +type declaration, where the Entity argument names one of the enumeration +literals. + +This pragma is used to indicate that the named entity +is considered obsolescent and should not be used. Typically this is +used when an API must be modified by eventually removing or modifying +existing subprograms or other entities. The pragma can be used at an +intermediate stage when the entity is still present, but will be +removed later. + +The effect of this pragma is to output a warning message on a reference to +an entity thus marked that the subprogram is obsolescent if the appropriate +warning option in the compiler is activated. If the Message parameter is +present, then a second warning message is given containing this text. In +addition, a reference to the entity is considered to be a violation of pragma +Restrictions (No_Obsolescent_Features). + +This pragma can also be used as a program unit pragma for a package, +in which case the entity name is the name of the package, and the +pragma indicates that the entire package is considered +obsolescent. In this case a client `with`'ing such a package +violates the restriction, and the `with` statement is +flagged with warnings if the warning option is set. + +If the Version parameter is present (which must be exactly +the identifier Ada_05, no other argument is allowed), then the +indication of obsolescence applies only when compiling in Ada 2005 +mode. This is primarily intended for dealing with the situations +in the predefined library where subprograms or packages +have become defined as obsolescent in Ada 2005 +(e.g., in Ada.Characters.Handling), but may be used anywhere. + +The following examples show typical uses of this pragma: + + +.. code-block:: ada + + package p is + pragma Obsolescent (p, Message => "use pp instead of p"); + end p; + + package q is + procedure q2; + pragma Obsolescent ("use q2new instead"); + + type R is new integer; + pragma Obsolescent + (Entity => R, + Message => "use RR in Ada 2005", + Version => Ada_05); + + type M is record + F1 : Integer; + F2 : Integer; + pragma Obsolescent; + F3 : Integer; + end record; + + type E is (a, bc, 'd', quack); + pragma Obsolescent (Entity => bc) + pragma Obsolescent (Entity => 'd') + + function "+" + (a, b : character) return character; + pragma Obsolescent (Entity => "+"); + end; + + +Note that, as for all pragmas, if you use a pragma argument identifier, +then all subsequent parameters must also use a pragma argument identifier. +So if you specify "Entity =>" for the Entity argument, and a Message +argument is present, it must be preceded by "Message =>". + +Pragma Optimize_Alignment +========================= +.. index:: Alignment, default settings + +Syntax: + + +.. code-block:: ada + + pragma Optimize_Alignment (TIME | SPACE | OFF); + + +This is a configuration pragma which affects the choice of default alignments +for types and objects where no alignment is explicitly specified. There is a +time/space trade-off in the selection of these values. Large alignments result +in more efficient code, at the expense of larger data space, since sizes have +to be increased to match these alignments. Smaller alignments save space, but +the access code is slower. The normal choice of default alignments for types +and individual alignment promotions for objects (which is what you get if you +do not use this pragma, or if you use an argument of OFF), tries to balance +these two requirements. + +Specifying SPACE causes smaller default alignments to be chosen in two cases. +First any packed record is given an alignment of 1. Second, if a size is given +for the type, then the alignment is chosen to avoid increasing this size. For +example, consider: + + +.. code-block:: ada + + type R is record + X : Integer; + Y : Character; + end record; + + for R'Size use 5*8; + + +In the default mode, this type gets an alignment of 4, so that access to the +Integer field X are efficient. But this means that objects of the type end up +with a size of 8 bytes. This is a valid choice, since sizes of objects are +allowed to be bigger than the size of the type, but it can waste space if for +example fields of type R appear in an enclosing record. If the above type is +compiled in `Optimize_Alignment (Space)` mode, the alignment is set to 1. + +However, there is one case in which SPACE is ignored. If a variable length +record (that is a discriminated record with a component which is an array +whose length depends on a discriminant), has a pragma Pack, then it is not +in general possible to set the alignment of such a record to one, so the +pragma is ignored in this case (with a warning). + +Specifying SPACE also disables alignment promotions for standalone objects, +which occur when the compiler increases the alignment of a specific object +without changing the alignment of its type. + +Specifying TIME causes larger default alignments to be chosen in the case of +small types with sizes that are not a power of 2. For example, consider: + + +.. code-block:: ada + + type R is record + A : Character; + B : Character; + C : Boolean; + end record; + + pragma Pack (R); + for R'Size use 17; + + +The default alignment for this record is normally 1, but if this type is +compiled in `Optimize_Alignment (Time)` mode, then the alignment is set +to 4, which wastes space for objects of the type, since they are now 4 bytes +long, but results in more efficient access when the whole record is referenced. + +As noted above, this is a configuration pragma, and there is a requirement +that all units in a partition be compiled with a consistent setting of the +optimization setting. This would normally be achieved by use of a configuration +pragma file containing the appropriate setting. The exception to this rule is +that units with an explicit configuration pragma in the same file as the source +unit are excluded from the consistency check, as are all predefined units. The +latter are compiled by default in pragma Optimize_Alignment (Off) mode if no +pragma appears at the start of the file. + +Pragma Ordered +============== + +Syntax: + + +.. code-block:: ada + + pragma Ordered (enumeration_first_subtype_LOCAL_NAME); + + +Most enumeration types are from a conceptual point of view unordered. +For example, consider: + + +.. code-block:: ada + + type Color is (Red, Blue, Green, Yellow); + + +By Ada semantics `Blue > Red` and `Green > Blue`, +but really these relations make no sense; the enumeration type merely +specifies a set of possible colors, and the order is unimportant. + +For unordered enumeration types, it is generally a good idea if +clients avoid comparisons (other than equality or inequality) and +explicit ranges. (A *client* is a unit where the type is referenced, +other than the unit where the type is declared, its body, and its subunits.) +For example, if code buried in some client says: + + +.. code-block:: ada + + if Current_Color < Yellow then ... + if Current_Color in Blue .. Green then ... + + +then the client code is relying on the order, which is undesirable. +It makes the code hard to read and creates maintenance difficulties if +entries have to be added to the enumeration type. Instead, +the code in the client should list the possibilities, or an +appropriate subtype should be declared in the unit that declares +the original enumeration type. E.g., the following subtype could +be declared along with the type `Color`: + + +.. code-block:: ada + + subtype RBG is Color range Red .. Green; + + +and then the client could write: + + +.. code-block:: ada + + if Current_Color in RBG then ... + if Current_Color = Blue or Current_Color = Green then ... + + +However, some enumeration types are legitimately ordered from a conceptual +point of view. For example, if you declare: + + +.. code-block:: ada + + type Day is (Mon, Tue, Wed, Thu, Fri, Sat, Sun); + + +then the ordering imposed by the language is reasonable, and +clients can depend on it, writing for example: + + +.. code-block:: ada + + if D in Mon .. Fri then ... + if D < Wed then ... + + +The pragma *Ordered* is provided to mark enumeration types that +are conceptually ordered, alerting the reader that clients may depend +on the ordering. GNAT provides a pragma to mark enumerations as ordered +rather than one to mark them as unordered, since in our experience, +the great majority of enumeration types are conceptually unordered. + +The types `Boolean`, `Character`, `Wide_Character`, +and `Wide_Wide_Character` +are considered to be ordered types, so each is declared with a +pragma `Ordered` in package `Standard`. + +Normally pragma `Ordered` serves only as documentation and a guide for +coding standards, but GNAT provides a warning switch *-gnatw.u* that +requests warnings for inappropriate uses (comparisons and explicit +subranges) for unordered types. If this switch is used, then any +enumeration type not marked with pragma `Ordered` will be considered +as unordered, and will generate warnings for inappropriate uses. + +Note that generic types are not considered ordered or unordered (since the +template can be instantiated for both cases), so we never generate warnings +for the case of generic enumerated types. + +For additional information please refer to the description of the +*-gnatw.u* switch in the GNAT User's Guide. + +Pragma Overflow_Mode +==================== + +Syntax: + + +:: + + pragma Overflow_Mode + ( [General =>] MODE + [,[Assertions =>] MODE]); + + MODE ::= STRICT | MINIMIZED | ELIMINATED + + +This pragma sets the current overflow mode to the given setting. For details +of the meaning of these modes, please refer to the +'Overflow Check Handling in GNAT' appendix in the +GNAT User's Guide. If only the `General` parameter is present, +the given mode applies to all expressions. If both parameters are present, +the `General` mode applies to expressions outside assertions, and +the `Eliminated` mode applies to expressions within assertions. + +The case of the `MODE` parameter is ignored, +so `MINIMIZED`, `Minimized` and +`minimized` all have the same effect. + +The `Overflow_Mode` pragma has the same scoping and placement +rules as pragma `Suppress`, so it can occur either as a +configuration pragma, specifying a default for the whole +program, or in a declarative scope, where it applies to the +remaining declarations and statements in that scope. + +The pragma `Suppress (Overflow_Check)` suppresses +overflow checking, but does not affect the overflow mode. + +The pragma `Unsuppress (Overflow_Check)` unsuppresses (enables) +overflow checking, but does not affect the overflow mode. + +Pragma Overriding_Renamings +=========================== +.. index:: Rational profile + +.. index:: Rational compatibility + +Syntax: + + +.. code-block:: ada + + pragma Overriding_Renamings; + + +This is a GNAT configuration pragma to simplify porting +legacy code accepted by the Rational +Ada compiler. In the presence of this pragma, a renaming declaration that +renames an inherited operation declared in the same scope is legal if selected +notation is used as in: + + +.. code-block:: ada + + pragma Overriding_Renamings; + ... + package R is + function F (..); + ... + function F (..) renames R.F; + end R; + + +even though +RM 8.3 (15) stipulates that an overridden operation is not visible within the +declaration of the overriding operation. + +Pragma Partition_Elaboration_Policy +=================================== + +Syntax: + + +:: + + pragma Partition_Elaboration_Policy (POLICY_IDENTIFIER); + + POLICY_IDENTIFIER ::= Concurrent | Sequential + + +This pragma is standard in Ada 2005, but is available in all earlier +versions of Ada as an implementation-defined pragma. +See Ada 2012 Reference Manual for details. + +Pragma Part_Of +============== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.2.6. + +Pragma Passive +============== + +Syntax: + + +:: + + pragma Passive [(Semaphore | No)]; + + +Syntax checked, but otherwise ignored by GNAT. This is recognized for +compatibility with DEC Ada 83 implementations, where it is used within a +task definition to request that a task be made passive. If the argument +`Semaphore` is present, or the argument is omitted, then DEC Ada 83 +treats the pragma as an assertion that the containing task is passive +and that optimization of context switch with this task is permitted and +desired. If the argument `No` is present, the task must not be +optimized. GNAT does not attempt to optimize any tasks in this manner +(since protected objects are available in place of passive tasks). + +For more information on the subject of passive tasks, see the section +'Passive Task Optimization' in the GNAT Users Guide. + +Pragma Persistent_BSS +===================== + +Syntax: + + +:: + + pragma Persistent_BSS [(LOCAL_NAME)] + + +This pragma allows selected objects to be placed in the `.persistent_bss` +section. On some targets the linker and loader provide for special +treatment of this section, allowing a program to be reloaded without +affecting the contents of this data (hence the name persistent). + +There are two forms of usage. If an argument is given, it must be the +local name of a library level object, with no explicit initialization +and whose type is potentially persistent. If no argument is given, then +the pragma is a configuration pragma, and applies to all library level +objects with no explicit initialization of potentially persistent types. + +A potentially persistent type is a scalar type, or an untagged, +non-discriminated record, all of whose components have no explicit +initialization and are themselves of a potentially persistent type, +or an array, all of whose constraints are static, and whose component +type is potentially persistent. + +If this pragma is used on a target where this feature is not supported, +then the pragma will be ignored. See also `pragma Linker_Section`. + +Pragma Polling +============== + +Syntax: + + +.. code-block:: ada + + pragma Polling (ON | OFF); + + +This pragma controls the generation of polling code. This is normally off. +If `pragma Polling (ON)` is used then periodic calls are generated to +the routine `Ada.Exceptions.Poll`. This routine is a separate unit in the +runtime library, and can be found in file :file:`a-excpol.adb`. + +Pragma `Polling` can appear as a configuration pragma (for example it +can be placed in the :file:`gnat.adc` file) to enable polling globally, or it +can be used in the statement or declaration sequence to control polling +more locally. + +A call to the polling routine is generated at the start of every loop and +at the start of every subprogram call. This guarantees that the `Poll` +routine is called frequently, and places an upper bound (determined by +the complexity of the code) on the period between two `Poll` calls. + +The primary purpose of the polling interface is to enable asynchronous +aborts on targets that cannot otherwise support it (for example Windows +NT), but it may be used for any other purpose requiring periodic polling. +The standard version is null, and can be replaced by a user program. This +will require re-compilation of the `Ada.Exceptions` package that can +be found in files :file:`a-except.ads` and :file:`a-except.adb`. + +A standard alternative unit (in file :file:`4wexcpol.adb` in the standard GNAT +distribution) is used to enable the asynchronous abort capability on +targets that do not normally support the capability. The version of +`Poll` in this file makes a call to the appropriate runtime routine +to test for an abort condition. + +Note that polling can also be enabled by use of the *-gnatP* switch. +See the section on switches for gcc in the :title:`GNAT User's Guide`. + +Pragma Post +=========== +.. index:: Post + +.. index:: Checks, postconditions + + +Syntax: + + +.. code-block:: ada + + pragma Post (Boolean_Expression); + + +The `Post` pragma is intended to be an exact replacement for +the language-defined +`Post` aspect, and shares its restrictions and semantics. +It must appear either immediately following the corresponding +subprogram declaration (only other pragmas may intervene), or +if there is no separate subprogram declaration, then it can +appear at the start of the declarations in a subprogram body +(preceded only by other pragmas). + +Pragma Postcondition +==================== +.. index:: Postcondition + +.. index:: Checks, postconditions + + +Syntax: + + +:: + + pragma Postcondition ( + [Check =>] Boolean_Expression + [,[Message =>] String_Expression]); + + +The `Postcondition` pragma allows specification of automatic +postcondition checks for subprograms. These checks are similar to +assertions, but are automatically inserted just prior to the return +statements of the subprogram with which they are associated (including +implicit returns at the end of procedure bodies and associated +exception handlers). + +In addition, the boolean expression which is the condition which +must be true may contain references to function'Result in the case +of a function to refer to the returned value. + +`Postcondition` pragmas may appear either immediately following the +(separate) declaration of a subprogram, or at the start of the +declarations of a subprogram body. Only other pragmas may intervene +(that is appear between the subprogram declaration and its +postconditions, or appear before the postcondition in the +declaration sequence in a subprogram body). In the case of a +postcondition appearing after a subprogram declaration, the +formal arguments of the subprogram are visible, and can be +referenced in the postcondition expressions. + +The postconditions are collected and automatically tested just +before any return (implicit or explicit) in the subprogram body. +A postcondition is only recognized if postconditions are active +at the time the pragma is encountered. The compiler switch *gnata* +turns on all postconditions by default, and pragma `Check_Policy` +with an identifier of `Postcondition` can also be used to +control whether postconditions are active. + +The general approach is that postconditions are placed in the spec +if they represent functional aspects which make sense to the client. +For example we might have: + + +.. code-block:: ada + + function Direction return Integer; + pragma Postcondition + (Direction'Result = +1 + or else + Direction'Result = -1); + + +which serves to document that the result must be +1 or -1, and +will test that this is the case at run time if postcondition +checking is active. + +Postconditions within the subprogram body can be used to +check that some internal aspect of the implementation, +not visible to the client, is operating as expected. +For instance if a square root routine keeps an internal +counter of the number of times it is called, then we +might have the following postcondition: + + +.. code-block:: ada + + Sqrt_Calls : Natural := 0; + + function Sqrt (Arg : Float) return Float is + pragma Postcondition + (Sqrt_Calls = Sqrt_Calls'Old + 1); + ... + end Sqrt + + +As this example, shows, the use of the `Old` attribute +is often useful in postconditions to refer to the state on +entry to the subprogram. + +Note that postconditions are only checked on normal returns +from the subprogram. If an abnormal return results from +raising an exception, then the postconditions are not checked. + +If a postcondition fails, then the exception +`System.Assertions.Assert_Failure` is raised. If +a message argument was supplied, then the given string +will be used as the exception message. If no message +argument was supplied, then the default message has +the form "Postcondition failed at file_name:line". The +exception is raised in the context of the subprogram +body, so it is possible to catch postcondition failures +within the subprogram body itself. + +Within a package spec, normal visibility rules +in Ada would prevent forward references within a +postcondition pragma to functions defined later in +the same package. This would introduce undesirable +ordering constraints. To avoid this problem, all +postcondition pragmas are analyzed at the end of +the package spec, allowing forward references. + +The following example shows that this even allows +mutually recursive postconditions as in: + + +.. code-block:: ada + + package Parity_Functions is + function Odd (X : Natural) return Boolean; + pragma Postcondition + (Odd'Result = + (x = 1 + or else + (x /= 0 and then Even (X - 1)))); + + function Even (X : Natural) return Boolean; + pragma Postcondition + (Even'Result = + (x = 0 + or else + (x /= 1 and then Odd (X - 1)))); + + end Parity_Functions; + + +There are no restrictions on the complexity or form of +conditions used within `Postcondition` pragmas. +The following example shows that it is even possible +to verify performance behavior. + + +.. code-block:: ada + + package Sort is + + Performance : constant Float; + -- Performance constant set by implementation + -- to match target architecture behavior. + + procedure Treesort (Arg : String); + -- Sorts characters of argument using N*logN sort + pragma Postcondition + (Float (Clock - Clock'Old) <= + Float (Arg'Length) * + log (Float (Arg'Length)) * + Performance); + end Sort; + + +Note: postcondition pragmas associated with subprograms that are +marked as Inline_Always, or those marked as Inline with front-end +inlining (-gnatN option set) are accepted and legality-checked +by the compiler, but are ignored at run-time even if postcondition +checking is enabled. + +Note that pragma `Postcondition` differs from the language-defined +`Post` aspect (and corresponding `Post` pragma) in allowing +multiple occurrences, allowing occurences in the body even if there +is a separate spec, and allowing a second string parameter, and the +use of the pragma identifier `Check`. Historically, pragma +`Postcondition` was implemented prior to the development of +Ada 2012, and has been retained in its original form for +compatibility purposes. + +Pragma Post_Class +================= +.. index:: Post + +.. index:: Checks, postconditions + + +Syntax: + + +.. code-block:: ada + + pragma Post_Class (Boolean_Expression); + + +The `Post_Class` pragma is intended to be an exact replacement for +the language-defined +`Post'Class` aspect, and shares its restrictions and semantics. +It must appear either immediately following the corresponding +subprogram declaration (only other pragmas may intervene), or +if there is no separate subprogram declaration, then it can +appear at the start of the declarations in a subprogram body +(preceded only by other pragmas). + +Note: This pragma is called `Post_Class` rather than +`Post'Class` because the latter would not be strictly +conforming to the allowed syntax for pragmas. The motivation +for provinding pragmas equivalent to the aspects is to allow a program +to be written using the pragmas, and then compiled if necessary +using an Ada compiler that does not recognize the pragmas or +aspects, but is prepared to ignore the pragmas. The assertion +policy that controls this pragma is `Post'Class`, not +`Post_Class`. + +Pragma Pre +========== +.. index:: Pre + +.. index:: Checks, preconditions + + +Syntax: + + +.. code-block:: ada + + pragma Pre (Boolean_Expression); + + +The `Pre` pragma is intended to be an exact replacement for +the language-defined +`Pre` aspect, and shares its restrictions and semantics. +It must appear either immediately following the corresponding +subprogram declaration (only other pragmas may intervene), or +if there is no separate subprogram declaration, then it can +appear at the start of the declarations in a subprogram body +(preceded only by other pragmas). + +Pragma Precondition +=================== +.. index:: Preconditions + +.. index:: Checks, preconditions + + +Syntax: + + +:: + + pragma Precondition ( + [Check =>] Boolean_Expression + [,[Message =>] String_Expression]); + + +The `Precondition` pragma is similar to `Postcondition` +except that the corresponding checks take place immediately upon +entry to the subprogram, and if a precondition fails, the exception +is raised in the context of the caller, and the attribute 'Result +cannot be used within the precondition expression. + +Otherwise, the placement and visibility rules are identical to those +described for postconditions. The following is an example of use +within a package spec: + + +.. code-block:: ada + + package Math_Functions is + ... + function Sqrt (Arg : Float) return Float; + pragma Precondition (Arg >= 0.0) + ... + end Math_Functions; + + +`Precondition` pragmas may appear either immediately following the +(separate) declaration of a subprogram, or at the start of the +declarations of a subprogram body. Only other pragmas may intervene +(that is appear between the subprogram declaration and its +postconditions, or appear before the postcondition in the +declaration sequence in a subprogram body). + +Note: precondition pragmas associated with subprograms that are +marked as Inline_Always, or those marked as Inline with front-end +inlining (-gnatN option set) are accepted and legality-checked +by the compiler, but are ignored at run-time even if precondition +checking is enabled. + +Note that pragma `Precondition` differs from the language-defined +`Pre` aspect (and corresponding `Pre` pragma) in allowing +multiple occurrences, allowing occurences in the body even if there +is a separate spec, and allowing a second string parameter, and the +use of the pragma identifier `Check`. Historically, pragma +`Precondition` was implemented prior to the development of +Ada 2012, and has been retained in its original form for +compatibility purposes. + +Pragma Predicate +================ + +Syntax: + + +:: + + pragma Predicate + ([Entity =>] type_LOCAL_NAME, + [Check =>] EXPRESSION); + + +This pragma (available in all versions of Ada in GNAT) encompasses both +the `Static_Predicate` and `Dynamic_Predicate` aspects in +Ada 2012. A predicate is regarded as static if it has an allowed form +for `Static_Predicate` and is otherwise treated as a +`Dynamic_Predicate`. Otherwise, predicates specified by this +pragma behave exactly as described in the Ada 2012 reference manual. +For example, if we have + + +.. code-block:: ada + + type R is range 1 .. 10; + subtype S is R; + pragma Predicate (Entity => S, Check => S not in 4 .. 6); + subtype Q is R + pragma Predicate (Entity => Q, Check => F(Q) or G(Q)); + + +the effect is identical to the following Ada 2012 code: + + +.. code-block:: ada + + type R is range 1 .. 10; + subtype S is R with + Static_Predicate => S not in 4 .. 6; + subtype Q is R with + Dynamic_Predicate => F(Q) or G(Q); + + +Note that there is are no pragmas `Dynamic_Predicate` +or `Static_Predicate`. That is +because these pragmas would affect legality and semantics of +the program and thus do not have a neutral effect if ignored. +The motivation behind providing pragmas equivalent to +corresponding aspects is to allow a program to be written +using the pragmas, and then compiled with a compiler that +will ignore the pragmas. That doesn't work in the case of +static and dynamic predicates, since if the corresponding +pragmas are ignored, then the behavior of the program is +fundamentally changed (for example a membership test +`A in B` would not take into account a predicate +defined for subtype B). When following this approach, the +use of predicates should be avoided. + +Pragma Preelaborable_Initialization +=================================== + +Syntax: + + +.. code-block:: ada + + pragma Preelaborable_Initialization (DIRECT_NAME); + + +This pragma is standard in Ada 2005, but is available in all earlier +versions of Ada as an implementation-defined pragma. +See Ada 2012 Reference Manual for details. + +Pragma Prefix_Exception_Messages +================================ +.. index:: Prefix_Exception_Messages + +.. index:: exception + +.. index:: Exception_Message + + +Syntax: + + +.. code-block:: ada + + pragma Prefix_Exception_Messages; + + +This is an implementation-defined configuration pragma that affects the +behavior of raise statements with a message given as a static string +constant (typically a string literal). In such cases, the string will +be automatically prefixed by the name of the enclosing entity (giving +the package and subprogram containing the raise statement). This helps +to identify where messages are coming from, and this mode is automatic +for the run-time library. + +The pragma has no effect if the message is computed with an expression other +than a static string constant, since the assumption in this case is that +the program computes exactly the string it wants. If you still want the +prefixing in this case, you can always call +`GNAT.Source_Info.Enclosing_Entity` and prepend the string manually. + +Pragma Pre_Class +================ +.. index:: Pre_Class + +.. index:: Checks, preconditions + + +Syntax: + + +.. code-block:: ada + + pragma Pre_Class (Boolean_Expression); + + +The `Pre_Class` pragma is intended to be an exact replacement for +the language-defined +`Pre'Class` aspect, and shares its restrictions and semantics. +It must appear either immediately following the corresponding +subprogram declaration (only other pragmas may intervene), or +if there is no separate subprogram declaration, then it can +appear at the start of the declarations in a subprogram body +(preceded only by other pragmas). + +Note: This pragma is called `Pre_Class` rather than +`Pre'Class` because the latter would not be strictly +conforming to the allowed syntax for pragmas. The motivation +for providing pragmas equivalent to the aspects is to allow a program +to be written using the pragmas, and then compiled if necessary +using an Ada compiler that does not recognize the pragmas or +aspects, but is prepared to ignore the pragmas. The assertion +policy that controls this pragma is `Pre'Class`, not +`Pre_Class`. + +Pragma Priority_Specific_Dispatching +==================================== + +Syntax: + + +:: + + pragma Priority_Specific_Dispatching ( + POLICY_IDENTIFIER, + first_priority_EXPRESSION, + last_priority_EXPRESSION) + + POLICY_IDENTIFIER ::= + EDF_Across_Priorities | + FIFO_Within_Priorities | + Non_Preemptive_Within_Priorities | + Round_Robin_Within_Priorities + + +This pragma is standard in Ada 2005, but is available in all earlier +versions of Ada as an implementation-defined pragma. +See Ada 2012 Reference Manual for details. + +Pragma Profile +============== + +Syntax: + + +.. code-block:: ada + + pragma Profile (Ravenscar | Restricted | Rational); + + +This pragma is standard in Ada 2005, but is available in all earlier +versions of Ada as an implementation-defined pragma. This is a +configuration pragma that establishes a set of configuration pragmas +that depend on the argument. `Ravenscar` is standard in Ada 2005. +The other two possibilities (`Restricted` or `Rational`) +are implementation-defined. The set of configuration pragmas +is defined in the following sections. + + +* Pragma Profile (Ravenscar) + + The `Ravenscar` profile is standard in Ada 2005, + but is available in all earlier + versions of Ada as an implementation-defined pragma. This profile + establishes the following set of configuration pragmas: + + * ``Task_Dispatching_Policy (FIFO_Within_Priorities)`` + + [RM D.2.2] Tasks are dispatched following a preemptive + priority-ordered scheduling policy. + + + * ``Locking_Policy (Ceiling_Locking)`` + + [RM D.3] While tasks and interrupts execute a protected action, they inherit + the ceiling priority of the corresponding protected object. + + + * ``Detect_Blocking`` + + This pragma forces the detection of potentially blocking operations within a + protected operation, and to raise Program_Error if that happens. + + plus the following set of restrictions: + + * ``Max_Entry_Queue_Length => 1`` + + No task can be queued on a protected entry. + + * ``Max_Protected_Entries => 1`` + + * ``Max_Task_Entries => 0`` + + No rendezvous statements are allowed. + + * ``No_Abort_Statements`` + + * ``No_Dynamic_Attachment`` + + * ``No_Dynamic_Priorities`` + + * ``No_Implicit_Heap_Allocations`` + + * ``No_Local_Protected_Objects`` + + * ``No_Local_Timing_Events`` + + * ``No_Protected_Type_Allocators`` + + * ``No_Relative_Delay`` + + * ``No_Requeue_Statements`` + + * ``No_Select_Statements`` + + * ``No_Specific_Termination_Handlers`` + + * ``No_Task_Allocators`` + + * ``No_Task_Hierarchy`` + + * ``No_Task_Termination`` + + * ``Simple_Barriers`` + + The Ravenscar profile also includes the following restrictions that specify + that there are no semantic dependences on the corresponding predefined + packages: + + * ``No_Dependence => Ada.Asynchronous_Task_Control`` + + * ``No_Dependence => Ada.Calendar`` + + * ``No_Dependence => Ada.Execution_Time.Group_Budget`` + + * ``No_Dependence => Ada.Execution_Time.Timers`` + + * ``No_Dependence => Ada.Task_Attributes`` + + * ``No_Dependence => System.Multiprocessors.Dispatching_Domains`` + + This set of configuration pragmas and restrictions correspond to the + definition of the 'Ravenscar Profile' for limited tasking, devised and + published by the :title:`International Real-Time Ada Workshop, 1997`. + A description is also available at + `http://www-users.cs.york.ac.uk/~burns/ravenscar.ps <http://www-users.cs.york.ac.uk/~burns/ravenscar.ps>`_. + + The original definition of the profile was revised at subsequent IRTAW + meetings. It has been included in the ISO + :title:`Guide for the Use of the Ada Programming Language in High Integrity Systems`, + and was made part of the Ada 2005 standard. + The formal definition given by + the Ada Rapporteur Group (ARG) can be found in two Ada Issues (AI-249 and + AI-305) available at + `http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt <http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00249.txt>`_ and + `http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt <http://www.ada-auth.org/cgi-bin/cvsweb.cgi/ais/ai-00305.txt>`_. + + The above set is a superset of the restrictions provided by pragma + ``Profile (Restricted)``, it includes six additional restrictions + (``Simple_Barriers``, ``No_Select_Statements``, + ``No_Calendar``, ``No_Implicit_Heap_Allocations``, + ``No_Relative_Delay`` and ``No_Task_Termination``). This means + that pragma ``Profile (Ravenscar)``, like the pragma + ``Profile (Restricted)``, + automatically causes the use of a simplified, + more efficient version of the tasking run-time library. + +* Pragma Profile (Restricted) + + This profile corresponds to the GNAT restricted run time. It + establishes the following set of restrictions: + + * ``No_Abort_Statements`` + * ``No_Entry_Queue`` + * ``No_Task_Hierarchy`` + * ``No_Task_Allocators`` + * ``No_Dynamic_Priorities`` + * ``No_Terminate_Alternatives`` + * ``No_Dynamic_Attachment`` + * ``No_Protected_Type_Allocators`` + * ``No_Local_Protected_Objects`` + * ``No_Requeue_Statements`` + * ``No_Task_Attributes_Package`` + * ``Max_Asynchronous_Select_Nesting = 0`` + * ``Max_Task_Entries = 0`` + * ``Max_Protected_Entries = 1`` + * ``Max_Select_Alternatives = 0`` + + This set of restrictions causes the automatic selection of a simplified + version of the run time that provides improved performance for the + limited set of tasking functionality permitted by this set of restrictions. + +* Pragma Profile (Rational) + + The Rational profile is intended to facilitate porting legacy code that + compiles with the Rational APEX compiler, even when the code includes non- + conforming Ada constructs. The profile enables the following three pragmas: + + * ``pragma Implicit_Packing`` + * ``pragma Overriding_Renamings`` + * ``pragma Use_VADS_Size`` + + +Pragma Profile_Warnings +======================= + +Syntax: + + +.. code-block:: ada + + pragma Profile_Warnings (Ravenscar | Restricted | Rational); + + +This is an implementation-defined pragma that is similar in +effect to `pragma Profile` except that instead of +generating `Restrictions` pragmas, it generates +`Restriction_Warnings` pragmas. The result is that +violations of the profile generate warning messages instead +of error messages. + +Pragma Propagate_Exceptions +=========================== +.. index:: Interfacing to C++ + + +Syntax: + + +.. code-block:: ada + + pragma Propagate_Exceptions; + + +This pragma is now obsolete and, other than generating a warning if warnings +on obsolescent features are enabled, is ignored. +It is retained for compatibility +purposes. It used to be used in connection with optimization of +a now-obsolete mechanism for implementation of exceptions. + +Pragma Provide_Shift_Operators +============================== +.. index:: Shift operators + + +Syntax: + + +.. code-block:: ada + + pragma Provide_Shift_Operators (integer_first_subtype_LOCAL_NAME); + + +This pragma can be applied to a first subtype local name that specifies +either an unsigned or signed type. It has the effect of providing the +five shift operators (Shift_Left, Shift_Right, Shift_Right_Arithmetic, +Rotate_Left and Rotate_Right) for the given type. It is similar to +including the function declarations for these five operators, together +with the pragma Import (Intrinsic, ...) statements. + +Pragma Psect_Object +=================== + +Syntax: + + +:: + + pragma Psect_Object ( + [Internal =>] LOCAL_NAME, + [, [External =>] EXTERNAL_SYMBOL] + [, [Size =>] EXTERNAL_SYMBOL]); + + EXTERNAL_SYMBOL ::= + IDENTIFIER + | static_string_EXPRESSION + + +This pragma is identical in effect to pragma `Common_Object`. + +Pragma Pure_Function +==================== + +Syntax: + + +:: + + pragma Pure_Function ([Entity =>] function_LOCAL_NAME); + + +This pragma appears in the same declarative part as a function +declaration (or a set of function declarations if more than one +overloaded declaration exists, in which case the pragma applies +to all entities). It specifies that the function `Entity` is +to be considered pure for the purposes of code generation. This means +that the compiler can assume that there are no side effects, and +in particular that two calls with identical arguments produce the +same result. It also means that the function can be used in an +address clause. + +Note that, quite deliberately, there are no static checks to try +to ensure that this promise is met, so `Pure_Function` can be used +with functions that are conceptually pure, even if they do modify +global variables. For example, a square root function that is +instrumented to count the number of times it is called is still +conceptually pure, and can still be optimized, even though it +modifies a global variable (the count). Memo functions are another +example (where a table of previous calls is kept and consulted to +avoid re-computation). + +Note also that the normal rules excluding optimization of subprograms +in pure units (when parameter types are descended from System.Address, +or when the full view of a parameter type is limited), do not apply +for the Pure_Function case. If you explicitly specify Pure_Function, +the compiler may optimize away calls with identical arguments, and +if that results in unexpected behavior, the proper action is not to +use the pragma for subprograms that are not (conceptually) pure. + +Note: Most functions in a `Pure` package are automatically pure, and +there is no need to use pragma `Pure_Function` for such functions. One +exception is any function that has at least one formal of type +`System.Address` or a type derived from it. Such functions are not +considered pure by default, since the compiler assumes that the +`Address` parameter may be functioning as a pointer and that the +referenced data may change even if the address value does not. +Similarly, imported functions are not considered to be pure by default, +since there is no way of checking that they are in fact pure. The use +of pragma `Pure_Function` for such a function will override these default +assumption, and cause the compiler to treat a designated subprogram as pure +in these cases. + +Note: If pragma `Pure_Function` is applied to a renamed function, it +applies to the underlying renamed function. This can be used to +disambiguate cases of overloading where some but not all functions +in a set of overloaded functions are to be designated as pure. + +If pragma `Pure_Function` is applied to a library level function, the +function is also considered pure from an optimization point of view, but the +unit is not a Pure unit in the categorization sense. So for example, a function +thus marked is free to `with` non-pure units. + +Pragma Rational +=============== + +Syntax: + + +.. code-block:: ada + + pragma Rational; + + +This pragma is considered obsolescent, but is retained for +compatibility purposes. It is equivalent to: + + +.. code-block:: ada + + pragma Profile (Rational); + + +Pragma Ravenscar +================ + +Syntax: + + +.. code-block:: ada + + pragma Ravenscar; + + +This pragma is considered obsolescent, but is retained for +compatibility purposes. It is equivalent to: + + +.. code-block:: ada + + pragma Profile (Ravenscar); + + +which is the preferred method of setting the `Ravenscar` profile. + +Pragma Refined_Depends +====================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 6.1.5. + +Pragma Refined_Global +===================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 6.1.4. + +Pragma Refined_Post +=================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.2.7. + +Pragma Refined_State +==================== + +For the description of this pragma, see SPARK 2014 Reference Manual, +section 7.2.2. + +Pragma Relative_Deadline +======================== + +Syntax: + + +.. code-block:: ada + + pragma Relative_Deadline (time_span_EXPRESSION); + + +This pragma is standard in Ada 2005, but is available in all earlier +versions of Ada as an implementation-defined pragma. +See Ada 2012 Reference Manual for details. + +Pragma Remote_Access_Type +========================= + +Syntax: + + +:: + + pragma Remote_Access_Type ([Entity =>] formal_access_type_LOCAL_NAME); + + +This pragma appears in the formal part of a generic declaration. +It specifies an exception to the RM rule from E.2.2(17/2), which forbids +the use of a remote access to class-wide type as actual for a formal +access type. + +When this pragma applies to a formal access type `Entity`, that +type is treated as a remote access to class-wide type in the generic. +It must be a formal general access type, and its designated type must +be the class-wide type of a formal tagged limited private type from the +same generic declaration. + +In the generic unit, the formal type is subject to all restrictions +pertaining to remote access to class-wide types. At instantiation, the +actual type must be a remote access to class-wide type. + +Pragma Restricted_Run_Time +========================== + +Syntax: + + +.. code-block:: ada + + pragma Restricted_Run_Time; + + +This pragma is considered obsolescent, but is retained for +compatibility purposes. It is equivalent to: + + +.. code-block:: ada + + pragma Profile (Restricted); + + +which is the preferred method of setting the restricted run time +profile. + +Pragma Restriction_Warnings +=========================== + +Syntax: + + +:: + + pragma Restriction_Warnings + (restriction_IDENTIFIER {, restriction_IDENTIFIER}); + + +This pragma allows a series of restriction identifiers to be +specified (the list of allowed identifiers is the same as for +pragma `Restrictions`). For each of these identifiers +the compiler checks for violations of the restriction, but +generates a warning message rather than an error message +if the restriction is violated. + +One use of this is in situations where you want to know +about violations of a restriction, but you want to ignore some of +these violations. Consider this example, where you want to set +Ada_95 mode and enable style checks, but you want to know about +any other use of implementation pragmas: + + +.. code-block:: ada + + pragma Restriction_Warnings (No_Implementation_Pragmas); + pragma Warnings (Off, "violation of No_Implementation_Pragmas"); + pragma Ada_95; + pragma Style_Checks ("2bfhkM160"); + pragma Warnings (On, "violation of No_Implementation_Pragmas"); + + +By including the above lines in a configuration pragmas file, +the Ada_95 and Style_Checks pragmas are accepted without +generating a warning, but any other use of implementation +defined pragmas will cause a warning to be generated. + +Pragma Reviewable +================= + +Syntax: + + +.. code-block:: ada + + pragma Reviewable; + + +This pragma is an RM-defined standard pragma, but has no effect on the +program being compiled, or on the code generated for the program. + +To obtain the required output specified in RM H.3.1, the compiler must be +run with various special switches as follows: + +* *Where compiler-generated run-time checks remain* + + The switch *-gnatGL* + may be used to list the expanded code in pseudo-Ada form. + Runtime checks show up in the listing either as explicit + checks or operators marked with {} to indicate a check is present. + + +* *An identification of known exceptions at compile time* + + If the program is compiled with *-gnatwa*, + the compiler warning messages will indicate all cases where the compiler + detects that an exception is certain to occur at run time. + + +* *Possible reads of uninitialized variables* + + The compiler warns of many such cases, but its output is incomplete. + +.. only:: PRO or GPL + + The CodePeer analysis tool + may be used to obtain a comprehensive list of all + possible points at which uninitialized data may be read. + +.. only:: FSF + + A supplemental static analysis tool + may be used to obtain a comprehensive list of all + possible points at which uninitialized data may be read. + + +* *Where run-time support routines are implicitly invoked* + + In the output from *-gnatGL*, + run-time calls are explicitly listed as calls to the relevant + run-time routine. + + +* *Object code listing* + + This may be obtained either by using the *-S* switch, + or the objdump utility. + + +* *Constructs known to be erroneous at compile time* + + These are identified by warnings issued by the compiler (use *-gnatwa*). + + +* *Stack usage information* + + Static stack usage data (maximum per-subprogram) can be obtained via the + *-fstack-usage* switch to the compiler. + Dynamic stack usage data (per task) can be obtained via the *-u* switch + to gnatbind + +.. only:: PRO or GPL + + The gnatstack utility + can be used to provide additional information on stack usage. + + +* *Object code listing of entire partition* + + This can be obtained by compiling the partition with *-S*, + or by applying objdump + to all the object files that are part of the partition. + + +* *A description of the run-time model* + + The full sources of the run-time are available, and the documentation of + these routines describes how these run-time routines interface to the + underlying operating system facilities. + + +* *Control and data-flow information* + +.. only:: PRO or GPL + + The CodePeer tool + may be used to obtain complete control and data-flow information, as well as + comprehensive messages identifying possible problems based on this + information. + +.. only:: FSF + + A supplemental static analysis tool + may be used to obtain complete control and data-flow information, as well as + comprehensive messages identifying possible problems based on this + information. + + +Pragma Share_Generic +==================== + +Syntax: + + +:: + + pragma Share_Generic (GNAME {, GNAME}); + + GNAME ::= generic_unit_NAME | generic_instance_NAME + + +This pragma is provided for compatibility with Dec Ada 83. It has +no effect in `GNAT` (which does not implement shared generics), other +than to check that the given names are all names of generic units or +generic instances. + +Pragma Shared +============= + +This pragma is provided for compatibility with Ada 83. The syntax and +semantics are identical to pragma Atomic. + +Pragma Short_Circuit_And_Or +=========================== + +Syntax: + + +.. code-block:: ada + + pragma Short_Circuit_And_Or; + + +This configuration pragma causes any occurrence of the AND operator applied to +operands of type Standard.Boolean to be short-circuited (i.e. the AND operator +is treated as if it were AND THEN). Or is similarly treated as OR ELSE. This +may be useful in the context of certification protocols requiring the use of +short-circuited logical operators. If this configuration pragma occurs locally +within the file being compiled, it applies only to the file being compiled. +There is no requirement that all units in a partition use this option. + +Pragma Short_Descriptors +======================== + +Syntax: + + +.. code-block:: ada + + pragma Short_Descriptors + + +This pragma is provided for compatibility with other Ada implementations. It +is recognized but ignored by all current versions of GNAT. + +Pragma Simple_Storage_Pool_Type +=============================== +.. index:: Storage pool, simple + +.. index:: Simple storage pool + +Syntax: + + +.. code-block:: ada + + pragma Simple_Storage_Pool_Type (type_LOCAL_NAME); + + +A type can be established as a 'simple storage pool type' by applying +the representation pragma `Simple_Storage_Pool_Type` to the type. +A type named in the pragma must be a library-level immutably limited record +type or limited tagged type declared immediately within a package declaration. +The type can also be a limited private type whose full type is allowed as +a simple storage pool type. + +For a simple storage pool type `SSP`, nonabstract primitive subprograms +`Allocate`, `Deallocate`, and `Storage_Size` can be declared that +are subtype conformant with the following subprogram declarations: + + +.. code-block:: ada + + procedure Allocate + (Pool : in out SSP; + Storage_Address : out System.Address; + Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; + Alignment : System.Storage_Elements.Storage_Count); + + procedure Deallocate + (Pool : in out SSP; + Storage_Address : System.Address; + Size_In_Storage_Elements : System.Storage_Elements.Storage_Count; + Alignment : System.Storage_Elements.Storage_Count); + + function Storage_Size (Pool : SSP) + return System.Storage_Elements.Storage_Count; + + +Procedure `Allocate` must be declared, whereas `Deallocate` and +`Storage_Size` are optional. If `Deallocate` is not declared, then +applying an unchecked deallocation has no effect other than to set its actual +parameter to null. If `Storage_Size` is not declared, then the +`Storage_Size` attribute applied to an access type associated with +a pool object of type SSP returns zero. Additional operations can be declared +for a simple storage pool type (such as for supporting a mark/release +storage-management discipline). + +An object of a simple storage pool type can be associated with an access +type by specifying the attribute +:ref:`Simple_Storage_Pool <Attribute_Simple_Storage_Pool>`. For example: + + +.. code-block:: ada + + My_Pool : My_Simple_Storage_Pool_Type; + + type Acc is access My_Data_Type; + + for Acc'Simple_Storage_Pool use My_Pool; + + + +See attribute :ref:`Simple_Storage_Pool <Attribute_Simple_Storage_Pool>` +for further details. + +.. _Pragma_Source_File_Name: + +Pragma Source_File_Name +======================= + +Syntax: + + +:: + + pragma Source_File_Name ( + [Unit_Name =>] unit_NAME, + Spec_File_Name => STRING_LITERAL, + [Index => INTEGER_LITERAL]); + + pragma Source_File_Name ( + [Unit_Name =>] unit_NAME, + Body_File_Name => STRING_LITERAL, + [Index => INTEGER_LITERAL]); + + +Use this to override the normal naming convention. It is a configuration +pragma, and so has the usual applicability of configuration pragmas +(i.e., it applies to either an entire partition, or to all units in a +compilation, or to a single unit, depending on how it is used. +`unit_name` is mapped to `file_name_literal`. The identifier for +the second argument is required, and indicates whether this is the file +name for the spec or for the body. + +The optional Index argument should be used when a file contains multiple +units, and when you do not want to use `gnatchop` to separate then +into multiple files (which is the recommended procedure to limit the +number of recompilations that are needed when some sources change). +For instance, if the source file :file:`source.ada` contains + + +.. code-block:: ada + + package B is + ... + end B; + + with B; + procedure A is + begin + .. + end A; + + +you could use the following configuration pragmas: + + +.. code-block:: ada + + pragma Source_File_Name + (B, Spec_File_Name => "source.ada", Index => 1); + pragma Source_File_Name + (A, Body_File_Name => "source.ada", Index => 2); + + +Note that the `gnatname` utility can also be used to generate those +configuration pragmas. + +Another form of the `Source_File_Name` pragma allows +the specification of patterns defining alternative file naming schemes +to apply to all files. + + +:: + + pragma Source_File_Name + ( [Spec_File_Name =>] STRING_LITERAL + [,[Casing =>] CASING_SPEC] + [,[Dot_Replacement =>] STRING_LITERAL]); + + pragma Source_File_Name + ( [Body_File_Name =>] STRING_LITERAL + [,[Casing =>] CASING_SPEC] + [,[Dot_Replacement =>] STRING_LITERAL]); + + pragma Source_File_Name + ( [Subunit_File_Name =>] STRING_LITERAL + [,[Casing =>] CASING_SPEC] + [,[Dot_Replacement =>] STRING_LITERAL]); + + CASING_SPEC ::= Lowercase | Uppercase | Mixedcase + + +The first argument is a pattern that contains a single asterisk indicating +the point at which the unit name is to be inserted in the pattern string +to form the file name. The second argument is optional. If present it +specifies the casing of the unit name in the resulting file name string. +The default is lower case. Finally the third argument allows for systematic +replacement of any dots in the unit name by the specified string literal. + +Note that Source_File_Name pragmas should not be used if you are using +project files. The reason for this rule is that the project manager is not +aware of these pragmas, and so other tools that use the projet file would not +be aware of the intended naming conventions. If you are using project files, +file naming is controlled by Source_File_Name_Project pragmas, which are +usually supplied automatically by the project manager. A pragma +Source_File_Name cannot appear after a :ref:`Pragma_Source_File_Name_Project`. + +For more details on the use of the `Source_File_Name` pragma, see the +sections on `Using Other File Names` and `Alternative File Naming Schemes' +in the :title:`GNAT User's Guide`. + +.. _Pragma_Source_File_Name_Project: + +Pragma Source_File_Name_Project +=============================== + +This pragma has the same syntax and semantics as pragma Source_File_Name. +It is only allowed as a stand alone configuration pragma. +It cannot appear after a :ref:`Pragma_Source_File_Name`, and +most importantly, once pragma Source_File_Name_Project appears, +no further Source_File_Name pragmas are allowed. + +The intention is that Source_File_Name_Project pragmas are always +generated by the Project Manager in a manner consistent with the naming +specified in a project file, and when naming is controlled in this manner, +it is not permissible to attempt to modify this naming scheme using +Source_File_Name or Source_File_Name_Project pragmas (which would not be +known to the project manager). + +Pragma Source_Reference +======================= + +Syntax: + + +.. code-block:: ada + + pragma Source_Reference (INTEGER_LITERAL, STRING_LITERAL); + + +This pragma must appear as the first line of a source file. +`integer_literal` is the logical line number of the line following +the pragma line (for use in error messages and debugging +information). `string_literal` is a static string constant that +specifies the file name to be used in error messages and debugging +information. This is most notably used for the output of `gnatchop` +with the *-r* switch, to make sure that the original unchopped +source file is the one referred to. + +The second argument must be a string literal, it cannot be a static +string expression other than a string literal. This is because its value +is needed for error messages issued by all phases of the compiler. + +Pragma SPARK_Mode +================= + +Syntax: + + +:: + + pragma SPARK_Mode [(On | Off)] ; + + +In general a program can have some parts that are in SPARK 2014 (and +follow all the rules in the SPARK Reference Manual), and some parts +that are full Ada 2012. + +The SPARK_Mode pragma is used to identify which parts are in SPARK +2014 (by default programs are in full Ada). The SPARK_Mode pragma can +be used in the following places: + + +* + As a configuration pragma, in which case it sets the default mode for + all units compiled with this pragma. + +* + Immediately following a library-level subprogram spec + +* + Immediately within a library-level package body + +* + Immediately following the `private` keyword of a library-level + package spec + +* + Immediately following the `begin` keyword of a library-level + package body + +* + Immediately within a library-level subprogram body + + +Normally a subprogram or package spec/body inherits the current mode +that is active at the point it is declared. But this can be overridden +by pragma within the spec or body as above. + +The basic consistency rule is that you can't turn SPARK_Mode back +`On`, once you have explicitly (with a pragma) turned if +`Off`. So the following rules apply: + +If a subprogram spec has SPARK_Mode `Off`, then the body must +also have SPARK_Mode `Off`. + +For a package, we have four parts: + +* + the package public declarations +* + the package private part +* + the body of the package +* + the elaboration code after `begin` + +For a package, the rule is that if you explicitly turn SPARK_Mode +`Off` for any part, then all the following parts must have +SPARK_Mode `Off`. Note that this may require repeating a pragma +SPARK_Mode (`Off`) in the body. For example, if we have a +configuration pragma SPARK_Mode (`On`) that turns the mode on by +default everywhere, and one particular package spec has pragma +SPARK_Mode (`Off`), then that pragma will need to be repeated in +the package body. + +Pragma Static_Elaboration_Desired +================================= + +Syntax: + + +.. code-block:: ada + + pragma Static_Elaboration_Desired; + + +This pragma is used to indicate that the compiler should attempt to initialize +statically the objects declared in the library unit to which the pragma applies, +when these objects are initialized (explicitly or implicitly) by an aggregate. +In the absence of this pragma, aggregates in object declarations are expanded +into assignments and loops, even when the aggregate components are static +constants. When the aggregate is present the compiler builds a static expression +that requires no run-time code, so that the initialized object can be placed in +read-only data space. If the components are not static, or the aggregate has +more that 100 components, the compiler emits a warning that the pragma cannot +be obeyed. (See also the restriction No_Implicit_Loops, which supports static +construction of larger aggregates with static components that include an others +choice.) + +Pragma Stream_Convert +===================== + +Syntax: + + +:: + + pragma Stream_Convert ( + [Entity =>] type_LOCAL_NAME, + [Read =>] function_NAME, + [Write =>] function_NAME); + + +This pragma provides an efficient way of providing user-defined stream +attributes. Not only is it simpler to use than specifying the attributes +directly, but more importantly, it allows the specification to be made in such +a way that the predefined unit Ada.Streams is not loaded unless it is actually +needed (i.e. unless the stream attributes are actually used); the use of +the Stream_Convert pragma adds no overhead at all, unless the stream +attributes are actually used on the designated type. + +The first argument specifies the type for which stream functions are +provided. The second parameter provides a function used to read values +of this type. It must name a function whose argument type may be any +subtype, and whose returned type must be the type given as the first +argument to the pragma. + +The meaning of the `Read` parameter is that if a stream attribute directly +or indirectly specifies reading of the type given as the first parameter, +then a value of the type given as the argument to the Read function is +read from the stream, and then the Read function is used to convert this +to the required target type. + +Similarly the `Write` parameter specifies how to treat write attributes +that directly or indirectly apply to the type given as the first parameter. +It must have an input parameter of the type specified by the first parameter, +and the return type must be the same as the input type of the Read function. +The effect is to first call the Write function to convert to the given stream +type, and then write the result type to the stream. + +The Read and Write functions must not be overloaded subprograms. If necessary +renamings can be supplied to meet this requirement. +The usage of this attribute is best illustrated by a simple example, taken +from the GNAT implementation of package Ada.Strings.Unbounded: + + +.. code-block:: ada + + function To_Unbounded (S : String) return Unbounded_String + renames To_Unbounded_String; + + pragma Stream_Convert + (Unbounded_String, To_Unbounded, To_String); + + +The specifications of the referenced functions, as given in the Ada +Reference Manual are: + + +.. code-block:: ada + + function To_Unbounded_String (Source : String) + return Unbounded_String; + + function To_String (Source : Unbounded_String) + return String; + + +The effect is that if the value of an unbounded string is written to a stream, +then the representation of the item in the stream is in the same format that +would be used for `Standard.String'Output`, and this same representation +is expected when a value of this type is read from the stream. Note that the +value written always includes the bounds, even for Unbounded_String'Write, +since Unbounded_String is not an array type. + +Note that the `Stream_Convert` pragma is not effective in the case of +a derived type of a non-limited tagged type. If such a type is specified then +the pragma is silently ignored, and the default implementation of the stream +attributes is used instead. + +Pragma Style_Checks +=================== + +Syntax: + + +:: + + pragma Style_Checks (string_LITERAL | ALL_CHECKS | + On | Off [, LOCAL_NAME]); + + +This pragma is used in conjunction with compiler switches to control the +built in style checking provided by GNAT. The compiler switches, if set, +provide an initial setting for the switches, and this pragma may be used +to modify these settings, or the settings may be provided entirely by +the use of the pragma. This pragma can be used anywhere that a pragma +is legal, including use as a configuration pragma (including use in +the :file:`gnat.adc` file). + +The form with a string literal specifies which style options are to be +activated. These are additive, so they apply in addition to any previously +set style check options. The codes for the options are the same as those +used in the *-gnaty* switch to *gcc* or *gnatmake*. +For example the following two methods can be used to enable +layout checking: + +* + + :: + + pragma Style_Checks ("l"); + + +* + + :: + + gcc -c -gnatyl ... + + +The form ALL_CHECKS activates all standard checks (its use is equivalent +to the use of the `gnaty` switch with no options. +See the :title:`GNAT User's Guide` for details.) + +Note: the behavior is slightly different in GNAT mode (*-gnatg* used). +In this case, ALL_CHECKS implies the standard set of GNAT mode style check +options (i.e. equivalent to *-gnatyg*). + +The forms with `Off` and `On` +can be used to temporarily disable style checks +as shown in the following example: + + +.. code-block:: ada + + pragma Style_Checks ("k"); -- requires keywords in lower case + pragma Style_Checks (Off); -- turn off style checks + NULL; -- this will not generate an error message + pragma Style_Checks (On); -- turn style checks back on + NULL; -- this will generate an error message + + +Finally the two argument form is allowed only if the first argument is +`On` or `Off`. The effect is to turn of semantic style checks +for the specified entity, as shown in the following example: + + +.. code-block:: ada + + pragma Style_Checks ("r"); -- require consistency of identifier casing + Arg : Integer; + Rf1 : Integer := ARG; -- incorrect, wrong case + pragma Style_Checks (Off, Arg); + Rf2 : Integer := ARG; -- OK, no error + + +Pragma Subtitle +=============== + +Syntax: + + +:: + + pragma Subtitle ([Subtitle =>] STRING_LITERAL); + + +This pragma is recognized for compatibility with other Ada compilers +but is ignored by GNAT. + +Pragma Suppress +=============== + +Syntax: + + +:: + + pragma Suppress (Identifier [, [On =>] Name]); + + +This is a standard pragma, and supports all the check names required in +the RM. It is included here because GNAT recognizes some additional check +names that are implementation defined (as permitted by the RM): + + +* + `Alignment_Check` can be used to suppress alignment checks + on addresses used in address clauses. Such checks can also be suppressed + by suppressing range checks, but the specific use of `Alignment_Check` + allows suppression of alignment checks without suppressing other range checks. + +* + `Atomic_Synchronization` can be used to suppress the special memory + synchronization instructions that are normally generated for access to + `Atomic` variables to ensure correct synchronization between tasks + that use such variables for synchronization purposes. + +* + `Duplicated_Tag_Check` Can be used to suppress the check that is generated + for a duplicated tag value when a tagged type is declared. + +* + `Predicate_Check` can be used to control whether predicate checks are + active. It is applicable only to predicates for which the policy is + `Check`. Unlike `Assertion_Policy`, which determines if a given + predicate is ignored or checked for the whole program, the use of + `Suppress` and `Unsuppress` with this check name allows a given + predicate to be turned on and off at specific points in the program. + +* + `Validity_Check` can be used specifically to control validity checks. + If `Suppress` is used to suppress validity checks, then no validity + checks are performed, including those specified by the appropriate compiler + switch or the `Validity_Checks` pragma. + +* + Additional check names previously introduced by use of the `Check_Name` + pragma are also allowed. + + +Note that pragma Suppress gives the compiler permission to omit +checks, but does not require the compiler to omit checks. The compiler +will generate checks if they are essentially free, even when they are +suppressed. In particular, if the compiler can prove that a certain +check will necessarily fail, it will generate code to do an +unconditional 'raise', even if checks are suppressed. The compiler +warns in this case. + +Of course, run-time checks are omitted whenever the compiler can prove +that they will not fail, whether or not checks are suppressed. + +Pragma Suppress_All +=================== + +Syntax: + + +.. code-block:: ada + + pragma Suppress_All; + + +This pragma can appear anywhere within a unit. +The effect is to apply `Suppress (All_Checks)` to the unit +in which it appears. This pragma is implemented for compatibility with DEC +Ada 83 usage where it appears at the end of a unit, and for compatibility +with Rational Ada, where it appears as a program unit pragma. +The use of the standard Ada pragma `Suppress (All_Checks)` +as a normal configuration pragma is the preferred usage in GNAT. + +Pragma Suppress_Debug_Info +========================== + +Syntax: + + +:: + + pragma Suppress_Debug_Info ([Entity =>] LOCAL_NAME); + + +This pragma can be used to suppress generation of debug information +for the specified entity. It is intended primarily for use in debugging +the debugger, and navigating around debugger problems. + +Pragma Suppress_Exception_Locations +=================================== + +Syntax: + + +.. code-block:: ada + + pragma Suppress_Exception_Locations; + + +In normal mode, a raise statement for an exception by default generates +an exception message giving the file name and line number for the location +of the raise. This is useful for debugging and logging purposes, but this +entails extra space for the strings for the messages. The configuration +pragma `Suppress_Exception_Locations` can be used to suppress the +generation of these strings, with the result that space is saved, but the +exception message for such raises is null. This configuration pragma may +appear in a global configuration pragma file, or in a specific unit as +usual. It is not required that this pragma be used consistently within +a partition, so it is fine to have some units within a partition compiled +with this pragma and others compiled in normal mode without it. + +Pragma Suppress_Initialization +============================== +.. index:: Suppressing initialization + +.. index:: Initialization, suppression of + +Syntax: + + +:: + + pragma Suppress_Initialization ([Entity =>] variable_or_subtype_Name); + + +Here variable_or_subtype_Name is the name introduced by a type declaration +or subtype declaration or the name of a variable introduced by an +object declaration. + +In the case of a type or subtype +this pragma suppresses any implicit or explicit initialization +for all variables of the given type or subtype, +including initialization resulting from the use of pragmas +Normalize_Scalars or Initialize_Scalars. + +This is considered a representation item, so it cannot be given after +the type is frozen. It applies to all subsequent object declarations, +and also any allocator that creates objects of the type. + +If the pragma is given for the first subtype, then it is considered +to apply to the base type and all its subtypes. If the pragma is given +for other than a first subtype, then it applies only to the given subtype. +The pragma may not be given after the type is frozen. + +Note that this includes eliminating initialization of discriminants +for discriminated types, and tags for tagged types. In these cases, +you will have to use some non-portable mechanism (e.g. address +overlays or unchecked conversion) to achieve required initialization +of these fields before accessing any object of the corresponding type. + +For the variable case, implicit initialization for the named variable +is suppressed, just as though its subtype had been given in a pragma +Suppress_Initialization, as described above. + +Pragma Task_Name +================ + +Syntax + + +.. code-block:: ada + + pragma Task_Name (string_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 String, and provides a name to be used for +the task instance when the task is created. Note that this expression +is not required to be static, and in particular, it can contain +references to task discriminants. This facility can be used to +provide different names for different tasks as they are created, +as illustrated in the example below. + +The task name is recorded internally in the run-time structures +and is accessible to tools like the debugger. In addition the +routine `Ada.Task_Identification.Image` will return this +string, with a unique task address appended. + + +.. code-block:: ada + + -- Example of the use of pragma Task_Name + + with Ada.Task_Identification; + use Ada.Task_Identification; + with Text_IO; use Text_IO; + procedure t3 is + + type Astring is access String; + + task type Task_Typ (Name : access String) is + pragma Task_Name (Name.all); + end Task_Typ; + + task body Task_Typ is + Nam : constant String := Image (Current_Task); + begin + Put_Line ("-->" & Nam (1 .. 14) & "<--"); + end Task_Typ; + + type Ptr_Task is access Task_Typ; + Task_Var : Ptr_Task; + + begin + Task_Var := + new Task_Typ (new String'("This is task 1")); + Task_Var := + new Task_Typ (new String'("This is task 2")); + end; + + +Pragma Task_Storage +=================== +Syntax: + + +:: + + pragma Task_Storage ( + [Task_Type =>] LOCAL_NAME, + [Top_Guard =>] static_integer_EXPRESSION); + + +This pragma specifies the length of the guard area for tasks. The guard +area is an additional storage area allocated to a task. A value of zero +means that either no guard area is created or a minimal guard area is +created, depending on the target. This pragma can appear anywhere a +`Storage_Size` attribute definition clause is allowed for a task +type. + +Pragma Test_Case +================ +.. index:: Test cases + + +Syntax: + + +:: + + pragma Test_Case ( + [Name =>] static_string_Expression + ,[Mode =>] (Nominal | Robustness) + [, Requires => Boolean_Expression] + [, Ensures => Boolean_Expression]); + + +The `Test_Case` pragma allows defining fine-grain specifications +for use by testing tools. +The compiler checks the validity of the `Test_Case` pragma, but its +presence does not lead to any modification of the code generated by the +compiler. + +`Test_Case` pragmas may only appear immediately following the +(separate) declaration of a subprogram in a package declaration, inside +a package spec unit. Only other pragmas may intervene (that is appear +between the subprogram declaration and a test case). + +The compiler checks that boolean expressions given in `Requires` and +`Ensures` are valid, where the rules for `Requires` are the +same as the rule for an expression in `Precondition` and the rules +for `Ensures` are the same as the rule for an expression in +`Postcondition`. In particular, attributes `'Old` and +`'Result` can only be used within the `Ensures` +expression. The following is an example of use within a package spec: + + +.. code-block:: ada + + package Math_Functions is + ... + function Sqrt (Arg : Float) return Float; + pragma Test_Case (Name => "Test 1", + Mode => Nominal, + Requires => Arg < 10000, + Ensures => Sqrt'Result < 10); + ... + end Math_Functions; + + +The meaning of a test case is that there is at least one context where +`Requires` holds such that, if the associated subprogram is executed in +that context, then `Ensures` holds when the subprogram returns. +Mode `Nominal` indicates that the input context should also satisfy the +precondition of the subprogram, and the output context should also satisfy its +postcondition. Mode `Robustness` indicates that the precondition and +postcondition of the subprogram should be ignored for this test case. + +Pragma Thread_Local_Storage +=========================== +.. index:: Task specific storage + +.. index:: TLS (Thread Local Storage) + +.. index:: Task_Attributes + +Syntax: + + +:: + + pragma Thread_Local_Storage ([Entity =>] LOCAL_NAME); + + +This pragma specifies that the specified entity, which must be +a variable declared in a library level package, is to be marked as +"Thread Local Storage" (`TLS`). On systems supporting this (which +include Solaris, GNU/Linux and VxWorks 6), this causes each thread +(and hence each Ada task) to see a distinct copy of the variable. + +The variable may not have default initialization, and if there is +an explicit initialization, it must be either `null` for an +access variable, or a static expression for a scalar variable. +This provides a low level mechanism similar to that provided by +the `Ada.Task_Attributes` package, but much more efficient +and is also useful in writing interface code that will interact +with foreign threads. + +If this pragma is used on a system where `TLS` is not supported, +then an error message will be generated and the program will be rejected. + +Pragma Time_Slice +================= + +Syntax: + + +.. code-block:: ada + + pragma Time_Slice (static_duration_EXPRESSION); + + +For implementations of GNAT on operating systems where it is possible +to supply a time slice value, this pragma may be used for this purpose. +It is ignored if it is used in a system that does not allow this control, +or if it appears in other than the main program unit. + +Pragma Title +============ + +Syntax: + + +:: + + pragma Title (TITLING_OPTION [, TITLING OPTION]); + + TITLING_OPTION ::= + [Title =>] STRING_LITERAL, + | [Subtitle =>] STRING_LITERAL + + +Syntax checked but otherwise ignored by GNAT. This is a listing control +pragma used in DEC Ada 83 implementations to provide a title and/or +subtitle for the program listing. The program listing generated by GNAT +does not have titles or subtitles. + +Unlike other pragmas, the full flexibility of named notation is allowed +for this pragma, i.e., the parameters may be given in any order if named +notation is used, and named and positional notation can be mixed +following the normal rules for procedure calls in Ada. + +Pragma Type_Invariant +===================== + +Syntax: + + +:: + + pragma Type_Invariant + ([Entity =>] type_LOCAL_NAME, + [Check =>] EXPRESSION); + + +The `Type_Invariant` pragma is intended to be an exact +replacement for the language-defined `Type_Invariant` +aspect, and shares its restrictions and semantics. It differs +from the language defined `Invariant` pragma in that it +does not permit a string parameter, and it is +controlled by the assertion identifier `Type_Invariant` +rather than `Invariant`. + +Pragma Type_Invariant_Class +=========================== + +Syntax: + + +:: + + pragma Type_Invariant_Class + ([Entity =>] type_LOCAL_NAME, + [Check =>] EXPRESSION); + + +The `Type_Invariant_Class` pragma is intended to be an exact +replacement for the language-defined `Type_Invariant'Class` +aspect, and shares its restrictions and semantics. + +Note: This pragma is called `Type_Invariant_Class` rather than +`Type_Invariant'Class` because the latter would not be strictly +conforming to the allowed syntax for pragmas. The motivation +for providing pragmas equivalent to the aspects is to allow a program +to be written using the pragmas, and then compiled if necessary +using an Ada compiler that does not recognize the pragmas or +aspects, but is prepared to ignore the pragmas. The assertion +policy that controls this pragma is `Type_Invariant'Class`, +not `Type_Invariant_Class`. + +Pragma Unchecked_Union +====================== +.. index:: Unions in C + + +Syntax: + + +.. code-block:: ada + + pragma Unchecked_Union (first_subtype_LOCAL_NAME); + + +This pragma is used to specify a representation of a record type that is +equivalent to a C union. It was introduced as a GNAT implementation defined +pragma in the GNAT Ada 95 mode. Ada 2005 includes an extended version of this +pragma, making it language defined, and GNAT fully implements this extended +version in all language modes (Ada 83, Ada 95, and Ada 2005). For full +details, consult the Ada 2012 Reference Manual, section B.3.3. + +Pragma Unevaluated_Use_Of_Old +============================= +.. index:: Attribute Old + +.. index:: Attribute Loop_Entry + +.. index:: Unevaluated_Use_Of_Old + + +Syntax: + + +.. code-block:: ada + + pragma Unevaluated_Use_Of_Old (Error | Warn | Allow); + + +This pragma controls the processing of attributes Old and Loop_Entry. +If either of these attributes is used in a potentially unevaluated +expression (e.g. the then or else parts of an if expression), then +normally this usage is considered illegal if the prefix of the attribute +is other than an entity name. The language requires this +behavior for Old, and GNAT copies the same rule for Loop_Entry. + +The reason for this rule is that otherwise, we can have a situation +where we save the Old value, and this results in an exception, even +though we might not evaluate the attribute. Consider this example: + + +.. code-block:: ada + + package UnevalOld is + K : Character; + procedure U (A : String; C : Boolean) -- ERROR + with Post => (if C then A(1)'Old = K else True); + end; + + +If procedure U is called with a string with a lower bound of 2, and +C false, then an exception would be raised trying to evaluate A(1) +on entry even though the value would not be actually used. + +Although the rule guarantees against this possibility, it is sometimes +too restrictive. For example if we know that the string has a lower +bound of 1, then we will never raise an exception. +The pragma `Unevaluated_Use_Of_Old` can be +used to modify this behavior. If the argument is `Error` then an +error is given (this is the default RM behavior). If the argument is +`Warn` then the usage is allowed as legal but with a warning +that an exception might be raised. If the argument is `Allow` +then the usage is allowed as legal without generating a warning. + +This pragma may appear as a configuration pragma, or in a declarative +part or package specification. In the latter case it applies to +uses up to the end of the corresponding statement sequence or +sequence of package declarations. + +Pragma Unimplemented_Unit +========================= + +Syntax: + + +.. code-block:: ada + + pragma Unimplemented_Unit; + + +If this pragma occurs in a unit that is processed by the compiler, GNAT +aborts with the message :samp:`xxx not implemented`, where +`xxx` is the name of the current compilation unit. This pragma is +intended to allow the compiler to handle unimplemented library units in +a clean manner. + +The abort only happens if code is being generated. Thus you can use +specs of unimplemented packages in syntax or semantic checking mode. + +Pragma Universal_Aliasing +========================= + +Syntax: + + +:: + + pragma Universal_Aliasing [([Entity =>] type_LOCAL_NAME)]; + + +`type_LOCAL_NAME` must refer to a type declaration in the current +declarative part. The effect is to inhibit strict type-based aliasing +optimization for the given type. In other words, the effect is as though +access types designating this type were subject to pragma No_Strict_Aliasing. +For a detailed description of the strict aliasing optimization, and the +situations in which it must be suppressed, see the section on +`Optimization and Strict Aliasing` in the :title:`GNAT User's Guide`. + +Pragma Universal_Data +===================== + +Syntax: + + +:: + + pragma Universal_Data [(library_unit_Name)]; + + +This pragma is supported only for the AAMP target and is ignored for +other targets. The pragma specifies that all library-level objects +(Counter 0 data) associated with the library unit are to be accessed +and updated using universal addressing (24-bit addresses for AAMP5) +rather than the default of 16-bit Data Environment (DENV) addressing. +Use of this pragma will generally result in less efficient code for +references to global data associated with the library unit, but +allows such data to be located anywhere in memory. This pragma is +a library unit pragma, but can also be used as a configuration pragma +(including use in the :file:`gnat.adc` file). The functionality +of this pragma is also available by applying the -univ switch on the +compilations of units where universal addressing of the data is desired. + +Pragma Unmodified +================= +.. index:: Warnings, unmodified + +Syntax: + + +:: + + pragma Unmodified (LOCAL_NAME {, LOCAL_NAME}); + + +This pragma signals that the assignable entities (variables, +`out` parameters, `in out` parameters) whose names are listed are +deliberately not assigned in the current source unit. This +suppresses warnings about the +entities being referenced but not assigned, and in addition a warning will be +generated if one of these entities is in fact assigned in the +same unit as the pragma (or in the corresponding body, or one +of its subunits). + +This is particularly useful for clearly signaling that a particular +parameter is not modified, even though the spec suggests that it might +be. + +For the variable case, warnings are never given for unreferenced variables +whose name contains one of the substrings +`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names +are typically to be used in cases where such warnings are expected. +Thus it is never necessary to use `pragma Unmodified` for such +variables, though it is harmless to do so. + +Pragma Unreferenced +=================== +.. index:: Warnings, unreferenced + +Syntax: + + +:: + + pragma Unreferenced (LOCAL_NAME {, LOCAL_NAME}); + pragma Unreferenced (library_unit_NAME {, library_unit_NAME}); + + +This pragma signals that the entities whose names are listed are +deliberately not referenced in the current source unit after the +occurrence of the pragma. This +suppresses warnings about the +entities being unreferenced, and in addition a warning will be +generated if one of these entities is in fact subsequently referenced in the +same unit as the pragma (or in the corresponding body, or one +of its subunits). + +This is particularly useful for clearly signaling that a particular +parameter is not referenced in some particular subprogram implementation +and that this is deliberate. It can also be useful in the case of +objects declared only for their initialization or finalization side +effects. + +If `LOCAL_NAME` identifies more than one matching homonym in the +current scope, then the entity most recently declared is the one to which +the pragma applies. Note that in the case of accept formals, the pragma +Unreferenced may appear immediately after the keyword `do` which +allows the indication of whether or not accept formals are referenced +or not to be given individually for each accept statement. + +The left hand side of an assignment does not count as a reference for the +purpose of this pragma. Thus it is fine to assign to an entity for which +pragma Unreferenced is given. + +Note that if a warning is desired for all calls to a given subprogram, +regardless of whether they occur in the same unit as the subprogram +declaration, then this pragma should not be used (calls from another +unit would not be flagged); pragma Obsolescent can be used instead +for this purpose, see :ref:`Pragma_Obsolescent`. + +The second form of pragma `Unreferenced` is used within a context +clause. In this case the arguments must be unit names of units previously +mentioned in `with` clauses (similar to the usage of pragma +`Elaborate_All`. The effect is to suppress warnings about unreferenced +units and unreferenced entities within these units. + +For the variable case, warnings are never given for unreferenced variables +whose name contains one of the substrings +`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names +are typically to be used in cases where such warnings are expected. +Thus it is never necessary to use `pragma Unreferenced` for such +variables, though it is harmless to do so. + +Pragma Unreferenced_Objects +=========================== +.. index:: Warnings, unreferenced + +Syntax: + + +:: + + pragma Unreferenced_Objects (local_subtype_NAME {, local_subtype_NAME}); + + +This pragma signals that for the types or subtypes whose names are +listed, objects which are declared with one of these types or subtypes may +not be referenced, and if no references appear, no warnings are given. + +This is particularly useful for objects which are declared solely for their +initialization and finalization effect. Such variables are sometimes referred +to as RAII variables (Resource Acquisition Is Initialization). Using this +pragma on the relevant type (most typically a limited controlled type), the +compiler will automatically suppress unwanted warnings about these variables +not being referenced. + +Pragma Unreserve_All_Interrupts +=============================== + +Syntax: + + +.. code-block:: ada + + pragma Unreserve_All_Interrupts; + + +Normally certain interrupts are reserved to the implementation. Any attempt +to attach an interrupt causes Program_Error to be raised, as described in +RM C.3.2(22). A typical example is the `SIGINT` interrupt used in +many systems for a :kbd:`Ctrl-C` interrupt. Normally this interrupt is +reserved to the implementation, so that :kbd:`Ctrl-C` can be used to +interrupt execution. + +If the pragma `Unreserve_All_Interrupts` appears anywhere in any unit in +a program, then all such interrupts are unreserved. This allows the +program to handle these interrupts, but disables their standard +functions. For example, if this pragma is used, then pressing +:kbd:`Ctrl-C` will not automatically interrupt execution. However, +a program can then handle the `SIGINT` interrupt as it chooses. + +For a full list of the interrupts handled in a specific implementation, +see the source code for the spec of `Ada.Interrupts.Names` in +file :file:`a-intnam.ads`. This is a target dependent file that contains the +list of interrupts recognized for a given target. The documentation in +this file also specifies what interrupts are affected by the use of +the `Unreserve_All_Interrupts` pragma. + +For a more general facility for controlling what interrupts can be +handled, see pragma `Interrupt_State`, which subsumes the functionality +of the `Unreserve_All_Interrupts` pragma. + +Pragma Unsuppress +================= + +Syntax: + + +:: + + pragma Unsuppress (IDENTIFIER [, [On =>] NAME]); + + +This pragma undoes the effect of a previous pragma `Suppress`. If +there is no corresponding pragma `Suppress` in effect, it has no +effect. The range of the effect is the same as for pragma +`Suppress`. The meaning of the arguments is identical to that used +in pragma `Suppress`. + +One important application is to ensure that checks are on in cases where +code depends on the checks for its correct functioning, so that the code +will compile correctly even if the compiler switches are set to suppress +checks. For example, in a program that depends on external names of tagged +types and wants to ensure that the duplicated tag check occurs even if all +run-time checks are suppressed by a compiler switch, the following +configuration pragma will ensure this test is not suppressed: + + +.. code-block:: ada + + pragma Unsuppress (Duplicated_Tag_Check); + + +This pragma is standard in Ada 2005. It is available in all earlier versions +of Ada as an implementation-defined pragma. + +Note that in addition to the checks defined in the Ada RM, GNAT recogizes +a number of implementation-defined check names. See description of pragma +`Suppress` for full details. + +Pragma Use_VADS_Size +==================== +.. index:: Size, VADS compatibility + +.. index:: Rational profile + + +Syntax: + + +.. code-block:: ada + + pragma Use_VADS_Size; + + +This is a configuration pragma. In a unit to which it applies, any use +of the 'Size attribute is automatically interpreted as a use of the +'VADS_Size attribute. Note that this may result in incorrect semantic +processing of valid Ada 95 or Ada 2005 programs. This is intended to aid in +the handling of existing code which depends on the interpretation of Size +as implemented in the VADS compiler. See description of the VADS_Size +attribute for further details. + +Pragma Validity_Checks +====================== + +Syntax: + + +.. code-block:: ada + + pragma Validity_Checks (string_LITERAL | ALL_CHECKS | On | Off); + + +This pragma is used in conjunction with compiler switches to control the +built-in validity checking provided by GNAT. The compiler switches, if set +provide an initial setting for the switches, and this pragma may be used +to modify these settings, or the settings may be provided entirely by +the use of the pragma. This pragma can be used anywhere that a pragma +is legal, including use as a configuration pragma (including use in +the :file:`gnat.adc` file). + +The form with a string literal specifies which validity options are to be +activated. The validity checks are first set to include only the default +reference manual settings, and then a string of letters in the string +specifies the exact set of options required. The form of this string +is exactly as described for the *-gnatVx* compiler switch (see the +GNAT User's Guide for details). For example the following two +methods can be used to enable validity checking for mode `in` and +`in out` subprogram parameters: + +* + + .. code-block:: ada + + pragma Validity_Checks ("im"); + + +* + + .. code-block:: sh + + $ gcc -c -gnatVim ... + + +The form ALL_CHECKS activates all standard checks (its use is equivalent +to the use of the `gnatva` switch. + +The forms with `Off` and `On` +can be used to temporarily disable validity checks +as shown in the following example: + + +.. code-block:: ada + + pragma Validity_Checks ("c"); -- validity checks for copies + pragma Validity_Checks (Off); -- turn off validity checks + A := B; -- B will not be validity checked + pragma Validity_Checks (On); -- turn validity checks back on + A := C; -- C will be validity checked + + +Pragma Volatile +=============== + +Syntax: + + +.. code-block:: ada + + pragma Volatile (LOCAL_NAME); + + +This pragma is defined by the Ada Reference Manual, and the GNAT +implementation is fully conformant with this definition. The reason it +is mentioned in this section is that a pragma of the same name was supplied +in some Ada 83 compilers, including DEC Ada 83. The Ada 95 / Ada 2005 +implementation of pragma Volatile is upwards compatible with the +implementation in DEC Ada 83. + +Pragma Warning_As_Error +======================= + +Syntax: + + +.. code-block:: ada + + pragma Warning_As_Error (static_string_EXPRESSION); + + +This configuration pragma allows the programmer to specify a set +of warnings that will be treated as errors. Any warning which +matches the pattern given by the pragma argument will be treated +as an error. This gives much more precise control that -gnatwe +which treats all warnings as errors. + +The pattern may contain asterisks, which match zero or more characters in +the message. For example, you can use +`pragma Warning_As_Error ("bits of*unused")` to treat the warning +message `warning: 960 bits of "a" unused` as an error. No other regular +expression notations are permitted. All characters other than asterisk in +these three specific cases are treated as literal characters in the match. +The match is case insensitive, for example XYZ matches xyz. + +Note that the pattern matches if it occurs anywhere within the warning +message string (it is not necessary to put an asterisk at the start and +the end of the message, since this is implied). + +Another possibility for the static_string_EXPRESSION which works whether +or not error tags are enabled (*-gnatw.d*) is to use the +*-gnatw* tag string, enclosed in brackets, +as shown in the example below, to treat a class of warnings as errors. + +The above use of patterns to match the message applies only to warning +messages generated by the front end. This pragma can also be applied to +warnings provided by the back end and mentioned in :ref:`Pragma_Warnings`. +By using a single full *-Wxxx* switch in the pragma, such warnings +can also be treated as errors. + +The pragma can appear either in a global configuration pragma file +(e.g. :file:`gnat.adc`), or at the start of a file. Given a global +configuration pragma file containing: + + +.. code-block:: ada + + pragma Warning_As_Error ("[-gnatwj]"); + + +which will treat all obsolescent feature warnings as errors, the +following program compiles as shown (compile options here are +*-gnatwa.d -gnatl -gnatj55*). + + +:: + + 1. pragma Warning_As_Error ("*never assigned*"); + 2. function Warnerr return String is + 3. X : Integer; + | + >>> error: variable "X" is never read and + never assigned [-gnatwv] [warning-as-error] + + 4. Y : Integer; + | + >>> warning: variable "Y" is assigned but + never read [-gnatwu] + + 5. begin + 6. Y := 0; + 7. return %ABC%; + | + >>> error: use of "%" is an obsolescent + feature (RM J.2(4)), use """ instead + [-gnatwj] [warning-as-error] + + 8. end; + + 8 lines: No errors, 3 warnings (2 treated as errors) + + +Note that this pragma does not affect the set of warnings issued in +any way, it merely changes the effect of a matching warning if one +is produced as a result of other warnings options. As shown in this +example, if the pragma results in a warning being treated as an error, +the tag is changed from "warning:" to "error:" and the string +"[warning-as-error]" is appended to the end of the message. + +.. _Pragma_Warnings: + +Pragma Warnings +=============== + +Syntax: + + +.. code-block:: ada + + pragma Warnings ([TOOL_NAME,] DETAILS [, REASON]); + + DETAILS ::= On | Off + DETAILS ::= On | Off, local_NAME + DETAILS ::= static_string_EXPRESSION + DETAILS ::= On | Off, static_string_EXPRESSION + + TOOL_NAME ::= GNAT | GNATProve + + REASON ::= Reason => STRING_LITERAL {& STRING_LITERAL} + +Note: in Ada 83 mode, a string literal may be used in place of a static string +expression (which does not exist in Ada 83). + +Note if the second argument of `DETAILS` is a `local_NAME` then the +second form is always understood. If the intention is to use +the fourth form, then you can write `NAME & ""` to force the +intepretation as a `static_string_EXPRESSION`. + +Note: if the first argument is a valid `TOOL_NAME`, it will be interpreted +that way. The use of the `TOOL_NAME` argument is relevant only to users +of SPARK and GNATprove, see last part of this section for details. + +Normally warnings are enabled, with the output being controlled by +the command line switch. Warnings (`Off`) turns off generation of +warnings until a Warnings (`On`) is encountered or the end of the +current unit. If generation of warnings is turned off using this +pragma, then some or all of the warning messages are suppressed, +regardless of the setting of the command line switches. + +The `Reason` parameter may optionally appear as the last argument +in any of the forms of this pragma. It is intended purely for the +purposes of documenting the reason for the `Warnings` pragma. +The compiler will check that the argument is a static string but +otherwise ignore this argument. Other tools may provide specialized +processing for this string. + +The form with a single argument (or two arguments if Reason present), +where the first argument is `ON` or `OFF` +may be used as a configuration pragma. + +If the `LOCAL_NAME` parameter is present, warnings are suppressed for +the specified entity. This suppression is effective from the point where +it occurs till the end of the extended scope of the variable (similar to +the scope of `Suppress`). This form cannot be used as a configuration +pragma. + +In the case where the first argument is other than `ON` or +`OFF`, +the third form with a single static_string_EXPRESSION argument (and possible +reason) provides more precise +control over which warnings are active. The string is a list of letters +specifying which warnings are to be activated and which deactivated. The +code for these letters is the same as the string used in the command +line switch controlling warnings. For a brief summary, use the gnatmake +command with no arguments, which will generate usage information containing +the list of warnings switches supported. For +full details see the section on `Warning Message Control` in the +:title:`GNAT User's Guide`. +This form can also be used as a configuration pragma. + +The warnings controlled by the *-gnatw* switch are generated by the +front end of the compiler. The GCC back end can provide additional warnings +and they are controlled by the *-W* switch. Such warnings can be +identified by the appearance of a string of the form `[-Wxxx]` in the +message which designates the *-Wxxx* switch that controls the message. +The form with a single static_string_EXPRESSION argument also works for these +warnings, but the string must be a single full *-Wxxx* switch in this +case. The above reference lists a few examples of these additional warnings. + +The specified warnings will be in effect until the end of the program +or another pragma Warnings is encountered. The effect of the pragma is +cumulative. Initially the set of warnings is the standard default set +as possibly modified by compiler switches. Then each pragma Warning +modifies this set of warnings as specified. This form of the pragma may +also be used as a configuration pragma. + +The fourth form, with an `On|Off` parameter and a string, is used to +control individual messages, based on their text. The string argument +is a pattern that is used to match against the text of individual +warning messages (not including the initial "warning: " tag). + +The pattern may contain asterisks, which match zero or more characters in +the message. For example, you can use +`pragma Warnings (Off, "bits of*unused")` to suppress the warning +message `warning: 960 bits of "a" unused`. No other regular +expression notations are permitted. All characters other than asterisk in +these three specific cases are treated as literal characters in the match. +The match is case insensitive, for example XYZ matches xyz. + +Note that the pattern matches if it occurs anywhere within the warning +message string (it is not necessary to put an asterisk at the start and +the end of the message, since this is implied). + +The above use of patterns to match the message applies only to warning +messages generated by the front end. This form of the pragma with a string +argument can also be used to control warnings provided by the back end and +mentioned above. By using a single full *-Wxxx* switch in the pragma, +such warnings can be turned on and off. + +There are two ways to use the pragma in this form. The OFF form can be used +as a configuration pragma. The effect is to suppress all warnings (if any) +that match the pattern string throughout the compilation (or match the +-W switch in the back end case). + +The second usage is to suppress a warning locally, and in this case, two +pragmas must appear in sequence: + + +.. code-block:: ada + + pragma Warnings (Off, Pattern); + ... code where given warning is to be suppressed + pragma Warnings (On, Pattern); + + +In this usage, the pattern string must match in the Off and On +pragmas, and (if *-gnatw.w* is given) at least one matching +warning must be suppressed. + +Note: to write a string that will match any warning, use the string +`"***"`. It will not work to use a single asterisk or two +asterisks since this looks like an operator name. This form with three +asterisks is similar in effect to specifying `pragma Warnings (Off)` except (if *-gnatw.w* is given) that a matching +`pragma Warnings (On, "***")` will be required. This can be +helpful in avoiding forgetting to turn warnings back on. + +Note: the debug flag -gnatd.i (`/NOWARNINGS_PRAGMAS` in VMS) can be +used to cause the compiler to entirely ignore all WARNINGS pragmas. This can +be useful in checking whether obsolete pragmas in existing programs are hiding +real problems. + +Note: pragma Warnings does not affect the processing of style messages. See +separate entry for pragma Style_Checks for control of style messages. + +Users of the formal verification tool GNATprove for the SPARK subset of Ada may +use the version of the pragma with a `TOOL_NAME` parameter. + +If present, `TOOL_NAME` is the name of a tool, currently either `GNAT` for the +compiler or `GNATprove` for the formal verification tool. A given tool only +takes into account pragma Warnings that do not specify a tool name, or that +specify the matching tool name. This makes it possible to disable warnings +selectively for each tool, and as a consequence to detect useless pragma +Warnings with switch `-gnatw.w`. + +Pragma Weak_External +==================== + +Syntax: + + +.. code-block:: ada + + pragma Weak_External ([Entity =>] LOCAL_NAME); + + +`LOCAL_NAME` must refer to an object that is declared at the library +level. This pragma specifies that the given entity should be marked as a +weak symbol for the linker. It is equivalent to `__attribute__((weak))` +in GNU C and causes `LOCAL_NAME` to be emitted as a weak symbol instead +of a regular symbol, that is to say a symbol that does not have to be +resolved by the linker if used in conjunction with a pragma Import. + +When a weak symbol is not resolved by the linker, its address is set to +zero. This is useful in writing interfaces to external modules that may +or may not be linked in the final executable, for example depending on +configuration settings. + +If a program references at run time an entity to which this pragma has been +applied, and the corresponding symbol was not resolved at link time, then +the execution of the program is erroneous. It is not erroneous to take the +Address of such an entity, for example to guard potential references, +as shown in the example below. + +Some file formats do not support weak symbols so not all target machines +support this pragma. + + +.. code-block:: ada + + -- Example of the use of pragma Weak_External + + package External_Module is + key : Integer; + pragma Import (C, key); + pragma Weak_External (key); + function Present return boolean; + end External_Module; + + with System; use System; + package body External_Module is + function Present return boolean is + begin + return key'Address /= System.Null_Address; + end Present; + end External_Module; + + +Pragma Wide_Character_Encoding +============================== + +Syntax: + + +.. code-block:: ada + + pragma Wide_Character_Encoding (IDENTIFIER | CHARACTER_LITERAL); + + +This pragma specifies the wide character encoding to be used in program +source text appearing subsequently. It is a configuration pragma, but may +also be used at any point that a pragma is allowed, and it is permissible +to have more than one such pragma in a file, allowing multiple encodings +to appear within the same file. + +The argument can be an identifier or a character literal. In the identifier +case, it is one of `HEX`, `UPPER`, `SHIFT_JIS`, +`EUC`, `UTF8`, or `BRACKETS`. In the character literal +case it is correspondingly one of the characters :kbd:`h`, :kbd:`u`, +:kbd:`s`, :kbd:`e`, :kbd:`8`, or :kbd:`b`. + +Note that when the pragma is used within a file, it affects only the +encoding within that file, and does not affect withed units, specs, +or subunits. diff --git a/gcc/ada/doc/gnat_rm/implementation_of_ada_2012_features.rst b/gcc/ada/doc/gnat_rm/implementation_of_ada_2012_features.rst new file mode 100644 index 00000000000..5ae5faca67f --- /dev/null +++ b/gcc/ada/doc/gnat_rm/implementation_of_ada_2012_features.rst @@ -0,0 +1,1328 @@ +.. _Implementation_of_Ada_2012_Features: + +*********************************** +Implementation of Ada 2012 Features +*********************************** + +.. index:: Ada 2012 implementation status + +.. index:: -gnat12 option (gcc) + +.. index:: pragma Ada_2012 + +.. index:: configuration pragma Ada_2012 + +.. index:: Ada_2012 configuration pragma + +This chapter contains a complete list of Ada 2012 features that have been +implemented as of GNAT version 6.4. Generally, these features are only +available if the *-gnat12* (Ada 2012 features enabled) flag is set +or if the configuration pragma `Ada_2012` is used. + +However, new pragmas, attributes, and restrictions are +unconditionally available, since the Ada 95 standard allows the addition of +new pragmas, attributes, and restrictions (there are exceptions, which are +documented in the individual descriptions), and also certain packages +were made available in earlier versions of Ada. + +An ISO date (YYYY-MM-DD) appears in parentheses on the description line. +This date shows the implementation date of the feature. Any wavefront +subsequent to this date will contain the indicated feature, as will any +subsequent releases. A date of 0000-00-00 means that GNAT has always +implemented the feature, or implemented it as soon as it appeared as a +binding interpretation. + +Each feature corresponds to an Ada Issue ('AI') approved by the Ada +standardization group (ISO/IEC JTC1/SC22/WG9) for inclusion in Ada 2012. +The features are ordered based on the relevant sections of the Ada +Reference Manual ("RM"). When a given AI relates to multiple points +in the RM, the earliest is used. + +A complete description of the AIs may be found in +http://www.ada-auth.org/ai05-summary.html. + +.. index:: AI-0176 (Ada 2012 feature) + +* *AI-0176 Quantified expressions (2010-09-29)* + + Both universally and existentially quantified expressions are implemented. + They use the new syntax for iterators proposed in AI05-139-2, as well as + the standard Ada loop syntax. + + RM References: 1.01.04 (12) 2.09 (2/2) 4.04 (7) 4.05.09 (0) + +.. index:: AI-0079 (Ada 2012 feature) + +* *AI-0079 Allow other_format characters in source (2010-07-10)* + + Wide characters in the unicode category *other_format* are now allowed in + source programs between tokens, but not within a token such as an identifier. + + RM References: 2.01 (4/2) 2.02 (7) + +.. index:: AI-0091 (Ada 2012 feature) + +* *AI-0091 Do not allow other_format in identifiers (0000-00-00)* + + Wide characters in the unicode category *other_format* are not permitted + within an identifier, since this can be a security problem. The error + message for this case has been improved to be more specific, but GNAT has + never allowed such characters to appear in identifiers. + + RM References: 2.03 (3.1/2) 2.03 (4/2) 2.03 (5/2) 2.03 (5.1/2) 2.03 (5.2/2) 2.03 (5.3/2) 2.09 (2/2) + +.. index:: AI-0100 (Ada 2012 feature) + +* *AI-0100 Placement of pragmas (2010-07-01)* + + This AI is an earlier version of AI-163. It simplifies the rules + for legal placement of pragmas. In the case of lists that allow pragmas, if + the list may have no elements, then the list may consist solely of pragmas. + + RM References: 2.08 (7) + +.. index:: AI-0163 (Ada 2012 feature) + +* *AI-0163 Pragmas in place of null (2010-07-01)* + + A statement sequence may be composed entirely of pragmas. It is no longer + necessary to add a dummy `null` statement to make the sequence legal. + + RM References: 2.08 (7) 2.08 (16) + +.. index:: AI-0080 (Ada 2012 feature) + +* *AI-0080 'View of' not needed if clear from context (0000-00-00)* + + This is an editorial change only, described as non-testable in the AI. + + RM References: 3.01 (7) + +.. index:: AI-0183 (Ada 2012 feature) + +* *AI-0183 Aspect specifications (2010-08-16)* + + Aspect specifications have been fully implemented except for pre and post- + conditions, and type invariants, which have their own separate AI's. All + forms of declarations listed in the AI are supported. The following is a + list of the aspects supported (with GNAT implementation aspects marked) + +================================== =========== +Supported Aspect Source +================================== =========== + `Ada_2005` -- GNAT + `Ada_2012` -- GNAT + `Address` + `Alignment` + `Atomic` + `Atomic_Components` + `Bit_Order` + `Component_Size` + `Contract_Cases` -- GNAT + `Discard_Names` + `External_Tag` + `Favor_Top_Level` -- GNAT + `Inline` + `Inline_Always` -- GNAT + `Invariant` -- GNAT + `Machine_Radix` + `No_Return` + `Object_Size` -- GNAT + `Pack` + `Persistent_BSS` -- GNAT + `Post` + `Pre` + `Predicate` + `Preelaborable_Initialization` + `Pure_Function` -- GNAT + `Remote_Access_Type` -- GNAT + `Shared` -- GNAT + `Size` + `Storage_Pool` + `Storage_Size` + `Stream_Size` + `Suppress` + `Suppress_Debug_Info` -- GNAT + `Test_Case` -- GNAT + `Thread_Local_Storage` -- GNAT + `Type_Invariant` + `Unchecked_Union` + `Universal_Aliasing` -- GNAT + `Unmodified` -- GNAT + `Unreferenced` -- GNAT + `Unreferenced_Objects` -- GNAT + `Unsuppress` + `Value_Size` -- GNAT + `Volatile` + `Volatile_Components` + `Warnings` -- GNAT +================================== =========== + + Note that for aspects with an expression, e.g. `Size`, the expression is + treated like a default expression (visibility is analyzed at the point of + occurrence of the aspect, but evaluation of the expression occurs at the + freeze point of the entity involved). + + RM References: 3.02.01 (3) 3.02.02 (2) 3.03.01 (2/2) 3.08 (6) + 3.09.03 (1.1/2) 6.01 (2/2) 6.07 (2/2) 9.05.02 (2/2) 7.01 (3) 7.03 + (2) 7.03 (3) 9.01 (2/2) 9.01 (3/2) 9.04 (2/2) 9.04 (3/2) + 9.05.02 (2/2) 11.01 (2) 12.01 (3) 12.03 (2/2) 12.04 (2/2) 12.05 (2) + 12.06 (2.1/2) 12.06 (2.2/2) 12.07 (2) 13.01 (0.1/2) 13.03 (5/1) + 13.03.01 (0) + +.. index:: AI-0128 (Ada 2012 feature) + +* *AI-0128 Inequality is a primitive operation (0000-00-00)* + + If an equality operator ("=") is declared for a type, then the implicitly + declared inequality operator ("/=") is a primitive operation of the type. + This is the only reasonable interpretation, and is the one always implemented + by GNAT, but the RM was not entirely clear in making this point. + + RM References: 3.02.03 (6) 6.06 (6) + +.. index:: AI-0003 (Ada 2012 feature) + +* *AI-0003 Qualified expressions as names (2010-07-11)* + + In Ada 2012, a qualified expression is considered to be syntactically a name, + meaning that constructs such as `A'(F(X)).B` are now legal. This is + useful in disambiguating some cases of overloading. + + RM References: 3.03 (11) 3.03 (21) 4.01 (2) 4.04 (7) 4.07 (3) + 5.04 (7) + +.. index:: AI-0120 (Ada 2012 feature) + +* *AI-0120 Constant instance of protected object (0000-00-00)* + + This is an RM editorial change only. The section that lists objects that are + constant failed to include the current instance of a protected object + within a protected function. This has always been treated as a constant + in GNAT. + + RM References: 3.03 (21) + +.. index:: AI-0008 (Ada 2012 feature) + +* *AI-0008 General access to constrained objects (0000-00-00)* + + The wording in the RM implied that if you have a general access to a + constrained object, it could be used to modify the discriminants. This was + obviously not intended. `Constraint_Error` should be raised, and GNAT + has always done so in this situation. + + RM References: 3.03 (23) 3.10.02 (26/2) 4.01 (9) 6.04.01 (17) 8.05.01 (5/2) + +.. index:: AI-0093 (Ada 2012 feature) + +* *AI-0093 Additional rules use immutably limited (0000-00-00)* + + This is an editorial change only, to make more widespread use of the Ada 2012 + 'immutably limited'. + + RM References: 3.03 (23.4/3) + +.. index:: AI-0096 (Ada 2012 feature) + +* *AI-0096 Deriving from formal private types (2010-07-20)* + + In general it is illegal for a type derived from a formal limited type to be + nonlimited. This AI makes an exception to this rule: derivation is legal + if it appears in the private part of the generic, and the formal type is not + tagged. If the type is tagged, the legality check must be applied to the + private part of the package. + + RM References: 3.04 (5.1/2) 6.02 (7) + +.. index:: AI-0181 (Ada 2012 feature) + +* *AI-0181 Soft hyphen is a non-graphic character (2010-07-23)* + + From Ada 2005 on, soft hyphen is considered a non-graphic character, which + means that it has a special name (`SOFT_HYPHEN`) in conjunction with the + `Image` and `Value` attributes for the character types. Strictly + speaking this is an inconsistency with Ada 95, but in practice the use of + these attributes is so obscure that it will not cause problems. + + RM References: 3.05.02 (2/2) A.01 (35/2) A.03.03 (21) + +.. index:: AI-0182 (Ada 2012 feature) + +* *AI-0182 Additional forms for `Character'Value* (0000-00-00)` + + This AI allows `Character'Value` to accept the string `'?'` where + `?` is any character including non-graphic control characters. GNAT has + always accepted such strings. It also allows strings such as + `HEX_00000041` to be accepted, but GNAT does not take advantage of this + permission and raises `Constraint_Error`, as is certainly still + permitted. + + RM References: 3.05 (56/2) + +.. index:: AI-0214 (Ada 2012 feature) + +* *AI-0214 Defaulted discriminants for limited tagged (2010-10-01)* + + Ada 2012 relaxes the restriction that forbids discriminants of tagged types + to have default expressions by allowing them when the type is limited. It + is often useful to define a default value for a discriminant even though + it can't be changed by assignment. + + RM References: 3.07 (9.1/2) 3.07.02 (3) + +.. index:: AI-0102 (Ada 2012 feature) + +* *AI-0102 Some implicit conversions are illegal (0000-00-00)* + + It is illegal to assign an anonymous access constant to an anonymous access + variable. The RM did not have a clear rule to prevent this, but GNAT has + always generated an error for this usage. + + RM References: 3.07 (16) 3.07.01 (9) 6.04.01 (6) 8.06 (27/2) + +.. index:: AI-0158 (Ada 2012 feature) + +* *AI-0158 Generalizing membership tests (2010-09-16)* + + This AI extends the syntax of membership tests to simplify complex conditions + that can be expressed as membership in a subset of values of any type. It + introduces syntax for a list of expressions that may be used in loop contexts + as well. + + RM References: 3.08.01 (5) 4.04 (3) 4.05.02 (3) 4.05.02 (5) 4.05.02 (27) + +.. index:: AI-0173 (Ada 2012 feature) + +* *AI-0173 Testing if tags represent abstract types (2010-07-03)* + + The function `Ada.Tags.Type_Is_Abstract` returns `True` if invoked + with the tag of an abstract type, and `False` otherwise. + + RM References: 3.09 (7.4/2) 3.09 (12.4/2) + +.. index:: AI-0076 (Ada 2012 feature) + +* *AI-0076 function with controlling result (0000-00-00)* + + This is an editorial change only. The RM defines calls with controlling + results, but uses the term 'function with controlling result' without an + explicit definition. + + RM References: 3.09.02 (2/2) + +.. index:: AI-0126 (Ada 2012 feature) + +* *AI-0126 Dispatching with no declared operation (0000-00-00)* + + This AI clarifies dispatching rules, and simply confirms that dispatching + executes the operation of the parent type when there is no explicitly or + implicitly declared operation for the descendant type. This has always been + the case in all versions of GNAT. + + RM References: 3.09.02 (20/2) 3.09.02 (20.1/2) 3.09.02 (20.2/2) + +.. index:: AI-0097 (Ada 2012 feature) + +* *AI-0097 Treatment of abstract null extension (2010-07-19)* + + The RM as written implied that in some cases it was possible to create an + object of an abstract type, by having an abstract extension inherit a non- + abstract constructor from its parent type. This mistake has been corrected + in GNAT and in the RM, and this construct is now illegal. + + RM References: 3.09.03 (4/2) + +.. index:: AI-0203 (Ada 2012 feature) + +* *AI-0203 Extended return cannot be abstract (0000-00-00)* + + A return_subtype_indication cannot denote an abstract subtype. GNAT has never + permitted such usage. + + RM References: 3.09.03 (8/3) + +.. index:: AI-0198 (Ada 2012 feature) + +* *AI-0198 Inheriting abstract operators (0000-00-00)* + + This AI resolves a conflict between two rules involving inherited abstract + operations and predefined operators. If a derived numeric type inherits + an abstract operator, it overrides the predefined one. This interpretation + was always the one implemented in GNAT. + + RM References: 3.09.03 (4/3) + +.. index:: AI-0073 (Ada 2012 feature) + +* *AI-0073 Functions returning abstract types (2010-07-10)* + + This AI covers a number of issues regarding returning abstract types. In + particular generic functions cannot have abstract result types or access + result types designated an abstract type. There are some other cases which + are detailed in the AI. Note that this binding interpretation has not been + retrofitted to operate before Ada 2012 mode, since it caused a significant + number of regressions. + + RM References: 3.09.03 (8) 3.09.03 (10) 6.05 (8/2) + +.. index:: AI-0070 (Ada 2012 feature) + +* *AI-0070 Elaboration of interface types (0000-00-00)* + + This is an editorial change only, there are no testable consequences short of + checking for the absence of generated code for an interface declaration. + + RM References: 3.09.04 (18/2) + +.. index:: AI-0208 (Ada 2012 feature) + +* *AI-0208 Characteristics of incomplete views (0000-00-00)* + + The wording in the Ada 2005 RM concerning characteristics of incomplete views + was incorrect and implied that some programs intended to be legal were now + illegal. GNAT had never considered such programs illegal, so it has always + implemented the intent of this AI. + + RM References: 3.10.01 (2.4/2) 3.10.01 (2.6/2) + +.. index:: AI-0162 (Ada 2012 feature) + +* *AI-0162 Incomplete type completed by partial view (2010-09-15)* + + Incomplete types are made more useful by allowing them to be completed by + private types and private extensions. + + RM References: 3.10.01 (2.5/2) 3.10.01 (2.6/2) 3.10.01 (3) 3.10.01 (4/2) + +.. index:: AI-0098 (Ada 2012 feature) + +* *AI-0098 Anonymous subprogram access restrictions (0000-00-00)* + + An unintentional omission in the RM implied some inconsistent restrictions on + the use of anonymous access to subprogram values. These restrictions were not + intentional, and have never been enforced by GNAT. + + RM References: 3.10.01 (6) 3.10.01 (9.2/2) + +.. index:: AI-0199 (Ada 2012 feature) + +* *AI-0199 Aggregate with anonymous access components (2010-07-14)* + + A choice list in a record aggregate can include several components of + (distinct) anonymous access types as long as they have matching designated + subtypes. + + RM References: 4.03.01 (16) + +.. index:: AI-0220 (Ada 2012 feature) + +* *AI-0220 Needed components for aggregates (0000-00-00)* + + This AI addresses a wording problem in the RM that appears to permit some + complex cases of aggregates with non-static discriminants. GNAT has always + implemented the intended semantics. + + RM References: 4.03.01 (17) + +.. index:: AI-0147 (Ada 2012 feature) + +* *AI-0147 Conditional expressions (2009-03-29)* + + Conditional expressions are permitted. The form of such an expression is: + + :: + + (if expr then expr {elsif expr then expr} [else expr]) + + The parentheses can be omitted in contexts where parentheses are present + anyway, such as subprogram arguments and pragma arguments. If the **else** + clause is omitted, **else** *True* is assumed; + thus ``(if A then B)`` is a way to conveniently represent + *(A implies B)* in standard logic. + + RM References: 4.03.03 (15) 4.04 (1) 4.04 (7) 4.05.07 (0) 4.07 (2) + 4.07 (3) 4.09 (12) 4.09 (33) 5.03 (3) 5.03 (4) 7.05 (2.1/2) + +.. index:: AI-0037 (Ada 2012 feature) + +* *AI-0037 Out-of-range box associations in aggregate (0000-00-00)* + + This AI confirms that an association of the form `Indx => <>` in an + array aggregate must raise `Constraint_Error` if `Indx` + is out of range. The RM specified a range check on other associations, but + not when the value of the association was defaulted. GNAT has always inserted + a constraint check on the index value. + + RM References: 4.03.03 (29) + +.. index:: AI-0123 (Ada 2012 feature) + +* *AI-0123 Composability of equality (2010-04-13)* + + Equality of untagged record composes, so that the predefined equality for a + composite type that includes a component of some untagged record type + `R` uses the equality operation of `R` (which may be user-defined + or predefined). This makes the behavior of untagged records identical to that + of tagged types in this respect. + + This change is an incompatibility with previous versions of Ada, but it + corrects a non-uniformity that was often a source of confusion. Analysis of + a large number of industrial programs indicates that in those rare cases + where a composite type had an untagged record component with a user-defined + equality, either there was no use of the composite equality, or else the code + expected the same composability as for tagged types, and thus had a bug that + would be fixed by this change. + + RM References: 4.05.02 (9.7/2) 4.05.02 (14) 4.05.02 (15) 4.05.02 (24) + 8.05.04 (8) + +.. index:: AI-0088 (Ada 2012 feature) + +* *AI-0088 The value of exponentiation (0000-00-00)* + + This AI clarifies the equivalence rule given for the dynamic semantics of + exponentiation: the value of the operation can be obtained by repeated + multiplication, but the operation can be implemented otherwise (for example + using the familiar divide-by-two-and-square algorithm, even if this is less + accurate), and does not imply repeated reads of a volatile base. + + RM References: 4.05.06 (11) + +.. index:: AI-0188 (Ada 2012 feature) + +* *AI-0188 Case expressions (2010-01-09)* + + Case expressions are permitted. This allows use of constructs such as: + + .. code-block:: ada + + X := (case Y is when 1 => 2, when 2 => 3, when others => 31) + + RM References: 4.05.07 (0) 4.05.08 (0) 4.09 (12) 4.09 (33) + +.. index:: AI-0104 (Ada 2012 feature) + +* *AI-0104 Null exclusion and uninitialized allocator (2010-07-15)* + + The assignment ``Ptr := new not null Some_Ptr;`` will raise + ``Constraint_Error`` because the default value of the allocated object is + **null**. This useless construct is illegal in Ada 2012. + + RM References: 4.08 (2) + +.. index:: AI-0157 (Ada 2012 feature) + +* *AI-0157 Allocation/Deallocation from empty pool (2010-07-11)* + + Allocation and Deallocation from an empty storage pool (i.e. allocation or + deallocation of a pointer for which a static storage size clause of zero + has been given) is now illegal and is detected as such. GNAT + previously gave a warning but not an error. + + RM References: 4.08 (5.3/2) 13.11.02 (4) 13.11.02 (17) + +.. index:: AI-0179 (Ada 2012 feature) + +* *AI-0179 Statement not required after label (2010-04-10)* + + It is not necessary to have a statement following a label, so a label + can appear at the end of a statement sequence without the need for putting a + null statement afterwards, but it is not allowable to have only labels and + no real statements in a statement sequence. + + RM References: 5.01 (2) + +.. index:: AI-0139-2 (Ada 2012 feature) + +* *AI-0139-2 Syntactic sugar for iterators (2010-09-29)* + + The new syntax for iterating over arrays and containers is now implemented. + Iteration over containers is for now limited to read-only iterators. Only + default iterators are supported, with the syntax: `for Elem of C`. + + RM References: 5.05 + +.. index:: AI-0134 (Ada 2012 feature) + +* *AI-0134 Profiles must match for full conformance (0000-00-00)* + + For full conformance, the profiles of anonymous-access-to-subprogram + parameters must match. GNAT has always enforced this rule. + + RM References: 6.03.01 (18) + +.. index:: AI-0207 (Ada 2012 feature) + +* *AI-0207 Mode conformance and access constant (0000-00-00)* + + This AI confirms that access_to_constant indication must match for mode + conformance. This was implemented in GNAT when the qualifier was originally + introduced in Ada 2005. + + RM References: 6.03.01 (16/2) + +.. index:: AI-0046 (Ada 2012 feature) + +* *AI-0046 Null exclusion match for full conformance (2010-07-17)* + + For full conformance, in the case of access parameters, the null exclusion + must match (either both or neither must have ``not null``). + + RM References: 6.03.02 (18) + +.. index:: AI-0118 (Ada 2012 feature) + +* *AI-0118 The association of parameter associations (0000-00-00)* + + This AI clarifies the rules for named associations in subprogram calls and + generic instantiations. The rules have been in place since Ada 83. + + RM References: 6.04.01 (2) 12.03 (9) + +.. index:: AI-0196 (Ada 2012 feature) + +* *AI-0196 Null exclusion tests for out parameters (0000-00-00)* + + Null exclusion checks are not made for `**out**` parameters when + evaluating the actual parameters. GNAT has never generated these checks. + + RM References: 6.04.01 (13) + +.. index:: AI-0015 (Ada 2012 feature) + +* *AI-0015 Constant return objects (0000-00-00)* + + The return object declared in an *extended_return_statement* may be + declared constant. This was always intended, and GNAT has always allowed it. + + RM References: 6.05 (2.1/2) 3.03 (10/2) 3.03 (21) 6.05 (5/2) + 6.05 (5.7/2) + +.. index:: AI-0032 (Ada 2012 feature) + +* *AI-0032 Extended return for class-wide functions (0000-00-00)* + + If a function returns a class-wide type, the object of an extended return + statement can be declared with a specific type that is covered by the class- + wide type. This has been implemented in GNAT since the introduction of + extended returns. Note AI-0103 complements this AI by imposing matching + rules for constrained return types. + + RM References: 6.05 (5.2/2) 6.05 (5.3/2) 6.05 (5.6/2) 6.05 (5.8/2) + 6.05 (8/2) + +.. index:: AI-0103 (Ada 2012 feature) + +* *AI-0103 Static matching for extended return (2010-07-23)* + + If the return subtype of a function is an elementary type or a constrained + type, the subtype indication in an extended return statement must match + statically this return subtype. + + RM References: 6.05 (5.2/2) + +.. index:: AI-0058 (Ada 2012 feature) + +* *AI-0058 Abnormal completion of an extended return (0000-00-00)* + + The RM had some incorrect wording implying wrong treatment of abnormal + completion in an extended return. GNAT has always implemented the intended + correct semantics as described by this AI. + + RM References: 6.05 (22/2) + +.. index:: AI-0050 (Ada 2012 feature) + +* *AI-0050 Raising Constraint_Error early for function call (0000-00-00)* + + The implementation permissions for raising `Constraint_Error` early on a function call + when it was clear an exception would be raised were over-permissive and allowed + mishandling of discriminants in some cases. GNAT did + not take advantage of these incorrect permissions in any case. + + RM References: 6.05 (24/2) + +.. index:: AI-0125 (Ada 2012 feature) + +* *AI-0125 Nonoverridable operations of an ancestor (2010-09-28)* + + In Ada 2012, the declaration of a primitive operation of a type extension + or private extension can also override an inherited primitive that is not + visible at the point of this declaration. + + RM References: 7.03.01 (6) 8.03 (23) 8.03.01 (5/2) 8.03.01 (6/2) + +.. index:: AI-0062 (Ada 2012 feature) + +* *AI-0062 Null exclusions and deferred constants (0000-00-00)* + + A full constant may have a null exclusion even if its associated deferred + constant does not. GNAT has always allowed this. + + RM References: 7.04 (6/2) 7.04 (7.1/2) + +.. index:: AI-0178 (Ada 2012 feature) + +* *AI-0178 Incomplete views are limited (0000-00-00)* + + This AI clarifies the role of incomplete views and plugs an omission in the + RM. GNAT always correctly restricted the use of incomplete views and types. + + RM References: 7.05 (3/2) 7.05 (6/2) + +.. index:: AI-0087 (Ada 2012 feature) + +* *AI-0087 Actual for formal nonlimited derived type (2010-07-15)* + + The actual for a formal nonlimited derived type cannot be limited. In + particular, a formal derived type that extends a limited interface but which + is not explicitly limited cannot be instantiated with a limited type. + + RM References: 7.05 (5/2) 12.05.01 (5.1/2) + +.. index:: AI-0099 (Ada 2012 feature) + +* *AI-0099 Tag determines whether finalization needed (0000-00-00)* + + This AI clarifies that 'needs finalization' is part of dynamic semantics, + and therefore depends on the run-time characteristics of an object (i.e. its + tag) and not on its nominal type. As the AI indicates: "we do not expect + this to affect any implementation''. + + RM References: 7.06.01 (6) 7.06.01 (7) 7.06.01 (8) 7.06.01 (9/2) + +.. index:: AI-0064 (Ada 2012 feature) + +* *AI-0064 Redundant finalization rule (0000-00-00)* + + This is an editorial change only. The intended behavior is already checked + by an existing ACATS test, which GNAT has always executed correctly. + + RM References: 7.06.01 (17.1/1) + +.. index:: AI-0026 (Ada 2012 feature) + +* *AI-0026 Missing rules for Unchecked_Union (2010-07-07)* + + Record representation clauses concerning Unchecked_Union types cannot mention + the discriminant of the type. The type of a component declared in the variant + part of an Unchecked_Union cannot be controlled, have controlled components, + nor have protected or task parts. If an Unchecked_Union type is declared + within the body of a generic unit or its descendants, then the type of a + component declared in the variant part cannot be a formal private type or a + formal private extension declared within the same generic unit. + + RM References: 7.06 (9.4/2) B.03.03 (9/2) B.03.03 (10/2) + +.. index:: AI-0205 (Ada 2012 feature) + +* *AI-0205 Extended return declares visible name (0000-00-00)* + + This AI corrects a simple omission in the RM. Return objects have always + been visible within an extended return statement. + + RM References: 8.03 (17) + +.. index:: AI-0042 (Ada 2012 feature) + +* *AI-0042 Overriding versus implemented-by (0000-00-00)* + + This AI fixes a wording gap in the RM. An operation of a synchronized + interface can be implemented by a protected or task entry, but the abstract + operation is not being overridden in the usual sense, and it must be stated + separately that this implementation is legal. This has always been the case + in GNAT. + + RM References: 9.01 (9.2/2) 9.04 (11.1/2) + +.. index:: AI-0030 (Ada 2012 feature) + +* *AI-0030 Requeue on synchronized interfaces (2010-07-19)* + + Requeue is permitted to a protected, synchronized or task interface primitive + providing it is known that the overriding operation is an entry. Otherwise + the requeue statement has the same effect as a procedure call. Use of pragma + `Implemented` provides a way to impose a static requirement on the + overriding operation by adhering to one of the implementation kinds: entry, + protected procedure or any of the above. + + RM References: 9.05 (9) 9.05.04 (2) 9.05.04 (3) 9.05.04 (5) + 9.05.04 (6) 9.05.04 (7) 9.05.04 (12) + +.. index:: AI-0201 (Ada 2012 feature) + +* *AI-0201 Independence of atomic object components (2010-07-22)* + + If an Atomic object has a pragma `Pack` or a `Component_Size` + attribute, then individual components may not be addressable by independent + tasks. However, if the representation clause has no effect (is confirming), + then independence is not compromised. Furthermore, in GNAT, specification of + other appropriately addressable component sizes (e.g. 16 for 8-bit + characters) also preserves independence. GNAT now gives very clear warnings + both for the declaration of such a type, and for any assignment to its components. + + RM References: 9.10 (1/3) C.06 (22/2) C.06 (23/2) + +.. index:: AI-0009 (Ada 2012 feature) + +* *AI-0009 Pragma Independent[_Components] (2010-07-23)* + + This AI introduces the new pragmas `Independent` and + `Independent_Components`, + which control guaranteeing independence of access to objects and components. + The AI also requires independence not unaffected by confirming rep clauses. + + RM References: 9.10 (1) 13.01 (15/1) 13.02 (9) 13.03 (13) C.06 (2) + C.06 (4) C.06 (6) C.06 (9) C.06 (13) C.06 (14) + +.. index:: AI-0072 (Ada 2012 feature) + +* *AI-0072 Task signalling using 'Terminated (0000-00-00)* + + This AI clarifies that task signalling for reading `'Terminated` only + occurs if the result is True. GNAT semantics has always been consistent with + this notion of task signalling. + + RM References: 9.10 (6.1/1) + +.. index:: AI-0108 (Ada 2012 feature) + +* *AI-0108 Limited incomplete view and discriminants (0000-00-00)* + + This AI confirms that an incomplete type from a limited view does not have + discriminants. This has always been the case in GNAT. + + RM References: 10.01.01 (12.3/2) + +.. index:: AI-0129 (Ada 2012 feature) + +* *AI-0129 Limited views and incomplete types (0000-00-00)* + + This AI clarifies the description of limited views: a limited view of a + package includes only one view of a type that has an incomplete declaration + and a full declaration (there is no possible ambiguity in a client package). + This AI also fixes an omission: a nested package in the private part has no + limited view. GNAT always implemented this correctly. + + RM References: 10.01.01 (12.2/2) 10.01.01 (12.3/2) + +.. index:: AI-0077 (Ada 2012 feature) + +* *AI-0077 Limited withs and scope of declarations (0000-00-00)* + + This AI clarifies that a declaration does not include a context clause, + and confirms that it is illegal to have a context in which both a limited + and a nonlimited view of a package are accessible. Such double visibility + was always rejected by GNAT. + + RM References: 10.01.02 (12/2) 10.01.02 (21/2) 10.01.02 (22/2) + +.. index:: AI-0122 (Ada 2012 feature) + +* *AI-0122 Private with and children of generics (0000-00-00)* + + This AI clarifies the visibility of private children of generic units within + instantiations of a parent. GNAT has always handled this correctly. + + RM References: 10.01.02 (12/2) + +.. index:: AI-0040 (Ada 2012 feature) + +* *AI-0040 Limited with clauses on descendant (0000-00-00)* + + This AI confirms that a limited with clause in a child unit cannot name + an ancestor of the unit. This has always been checked in GNAT. + + RM References: 10.01.02 (20/2) + +.. index:: AI-0132 (Ada 2012 feature) + +* *AI-0132 Placement of library unit pragmas (0000-00-00)* + + This AI fills a gap in the description of library unit pragmas. The pragma + clearly must apply to a library unit, even if it does not carry the name + of the enclosing unit. GNAT has always enforced the required check. + + RM References: 10.01.05 (7) + +.. index:: AI-0034 (Ada 2012 feature) + +* *AI-0034 Categorization of limited views (0000-00-00)* + + The RM makes certain limited with clauses illegal because of categorization + considerations, when the corresponding normal with would be legal. This is + not intended, and GNAT has always implemented the recommended behavior. + + RM References: 10.02.01 (11/1) 10.02.01 (17/2) + +.. index:: AI-0035 (Ada 2012 feature) + +* *AI-0035 Inconsistencies with Pure units (0000-00-00)* + + This AI remedies some inconsistencies in the legality rules for Pure units. + Derived access types are legal in a pure unit (on the assumption that the + rule for a zero storage pool size has been enforced on the ancestor type). + The rules are enforced in generic instances and in subunits. GNAT has always + implemented the recommended behavior. + + RM References: 10.02.01 (15.1/2) 10.02.01 (15.4/2) 10.02.01 (15.5/2) 10.02.01 (17/2) + +.. index:: AI-0219 (Ada 2012 feature) + +* *AI-0219 Pure permissions and limited parameters (2010-05-25)* + + This AI refines the rules for the cases with limited parameters which do not + allow the implementations to omit 'redundant'. GNAT now properly conforms + to the requirements of this binding interpretation. + + RM References: 10.02.01 (18/2) + +.. index:: AI-0043 (Ada 2012 feature) + +* *AI-0043 Rules about raising exceptions (0000-00-00)* + + This AI covers various omissions in the RM regarding the raising of + exceptions. GNAT has always implemented the intended semantics. + + RM References: 11.04.01 (10.1/2) 11 (2) + +.. index:: AI-0200 (Ada 2012 feature) + +* *AI-0200 Mismatches in formal package declarations (0000-00-00)* + + This AI plugs a gap in the RM which appeared to allow some obviously intended + illegal instantiations. GNAT has never allowed these instantiations. + + RM References: 12.07 (16) + +.. index:: AI-0112 (Ada 2012 feature) + +* *AI-0112 Detection of duplicate pragmas (2010-07-24)* + + This AI concerns giving names to various representation aspects, but the + practical effect is simply to make the use of duplicate + `Atomic[_Components]`, + `Volatile[_Components]`, and + `Independent[_Components]` pragmas illegal, and GNAT + now performs this required check. + + RM References: 13.01 (8) + +.. index:: AI-0106 (Ada 2012 feature) + +* *AI-0106 No representation pragmas on generic formals (0000-00-00)* + + The RM appeared to allow representation pragmas on generic formal parameters, + but this was not intended, and GNAT has never permitted this usage. + + RM References: 13.01 (9.1/1) + +.. index:: AI-0012 (Ada 2012 feature) + +* *AI-0012 Pack/Component_Size for aliased/atomic (2010-07-15)* + + It is now illegal to give an inappropriate component size or a pragma + `Pack` that attempts to change the component size in the case of atomic + or aliased components. Previously GNAT ignored such an attempt with a + warning. + + RM References: 13.02 (6.1/2) 13.02 (7) C.06 (10) C.06 (11) C.06 (21) + +.. index:: AI-0039 (Ada 2012 feature) + +* *AI-0039 Stream attributes cannot be dynamic (0000-00-00)* + + The RM permitted the use of dynamic expressions (such as ``ptr.all``)` + for stream attributes, but these were never useful and are now illegal. GNAT + has always regarded such expressions as illegal. + + RM References: 13.03 (4) 13.03 (6) 13.13.02 (38/2) + +.. index:: AI-0095 (Ada 2012 feature) + +* *AI-0095 Address of intrinsic subprograms (0000-00-00)* + + The prefix of `'Address` cannot statically denote a subprogram with + convention `Intrinsic`. The use of the `Address` attribute raises + `Program_Error` if the prefix denotes a subprogram with convention + `Intrinsic`. + + RM References: 13.03 (11/1) + +.. index:: AI-0116 (Ada 2012 feature) + +* *AI-0116 Alignment of class-wide objects (0000-00-00)* + + This AI requires that the alignment of a class-wide object be no greater + than the alignment of any type in the class. GNAT has always followed this + recommendation. + + RM References: 13.03 (29) 13.11 (16) + +.. index:: AI-0146 (Ada 2012 feature) + +* *AI-0146 Type invariants (2009-09-21)* + + Type invariants may be specified for private types using the aspect notation. + Aspect `Type_Invariant` may be specified for any private type, + `Type_Invariant'Class` can + only be specified for tagged types, and is inherited by any descendent of the + tagged types. The invariant is a boolean expression that is tested for being + true in the following situations: conversions to the private type, object + declarations for the private type that are default initialized, and + [**in**] **out** + parameters and returned result on return from any primitive operation for + the type that is visible to a client. + GNAT defines the synonyms `Invariant` for `Type_Invariant` and + `Invariant'Class` for `Type_Invariant'Class`. + + RM References: 13.03.03 (00) + +.. index:: AI-0078 (Ada 2012 feature) + +* *AI-0078 Relax Unchecked_Conversion alignment rules (0000-00-00)* + + In Ada 2012, compilers are required to support unchecked conversion where the + target alignment is a multiple of the source alignment. GNAT always supported + this case (and indeed all cases of differing alignments, doing copies where + required if the alignment was reduced). + + RM References: 13.09 (7) + +.. index:: AI-0195 (Ada 2012 feature) + +* *AI-0195 Invalid value handling is implementation defined (2010-07-03)* + + The handling of invalid values is now designated to be implementation + defined. This is a documentation change only, requiring Annex M in the GNAT + Reference Manual to document this handling. + In GNAT, checks for invalid values are made + only when necessary to avoid erroneous behavior. Operations like assignments + which cannot cause erroneous behavior ignore the possibility of invalid + values and do not do a check. The date given above applies only to the + documentation change, this behavior has always been implemented by GNAT. + + RM References: 13.09.01 (10) + +.. index:: AI-0193 (Ada 2012 feature) + +* *AI-0193 Alignment of allocators (2010-09-16)* + + This AI introduces a new attribute `Max_Alignment_For_Allocation`, + analogous to `Max_Size_In_Storage_Elements`, but for alignment instead + of size. + + RM References: 13.11 (16) 13.11 (21) 13.11.01 (0) 13.11.01 (1) + 13.11.01 (2) 13.11.01 (3) + +.. index:: AI-0177 (Ada 2012 feature) + +* *AI-0177 Parameterized expressions (2010-07-10)* + + The new Ada 2012 notion of parameterized expressions is implemented. The form + is: + + .. code-block:: ada + + function-specification is (expression) + + This is exactly equivalent to the + corresponding function body that returns the expression, but it can appear + in a package spec. Note that the expression must be parenthesized. + + RM References: 13.11.01 (3/2) + +.. index:: AI-0033 (Ada 2012 feature) + +* *AI-0033 Attach/Interrupt_Handler in generic (2010-07-24)* + + Neither of these two pragmas may appear within a generic template, because + the generic might be instantiated at other than the library level. + + RM References: 13.11.02 (16) C.03.01 (7/2) C.03.01 (8/2) + +.. index:: AI-0161 (Ada 2012 feature) + +* *AI-0161 Restriction No_Default_Stream_Attributes (2010-09-11)* + + A new restriction `No_Default_Stream_Attributes` prevents the use of any + of the default stream attributes for elementary types. If this restriction is + in force, then it is necessary to provide explicit subprograms for any + stream attributes used. + + RM References: 13.12.01 (4/2) 13.13.02 (40/2) 13.13.02 (52/2) + +.. index:: AI-0194 (Ada 2012 feature) + +* *AI-0194 Value of Stream_Size attribute (0000-00-00)* + + The `Stream_Size` attribute returns the default number of bits in the + stream representation of the given type. + This value is not affected by the presence + of stream subprogram attributes for the type. GNAT has always implemented + this interpretation. + + RM References: 13.13.02 (1.2/2) + +.. index:: AI-0109 (Ada 2012 feature) + +* *AI-0109 Redundant check in S'Class'Input (0000-00-00)* + + This AI is an editorial change only. It removes the need for a tag check + that can never fail. + + RM References: 13.13.02 (34/2) + +.. index:: AI-0007 (Ada 2012 feature) + +* *AI-0007 Stream read and private scalar types (0000-00-00)* + + The RM as written appeared to limit the possibilities of declaring read + attribute procedures for private scalar types. This limitation was not + intended, and has never been enforced by GNAT. + + RM References: 13.13.02 (50/2) 13.13.02 (51/2) + +.. index:: AI-0065 (Ada 2012 feature) + +* *AI-0065 Remote access types and external streaming (0000-00-00)* + + This AI clarifies the fact that all remote access types support external + streaming. This fixes an obvious oversight in the definition of the + language, and GNAT always implemented the intended correct rules. + + RM References: 13.13.02 (52/2) + +.. index:: AI-0019 (Ada 2012 feature) + +* *AI-0019 Freezing of primitives for tagged types (0000-00-00)* + + The RM suggests that primitive subprograms of a specific tagged type are + frozen when the tagged type is frozen. This would be an incompatible change + and is not intended. GNAT has never attempted this kind of freezing and its + behavior is consistent with the recommendation of this AI. + + RM References: 13.14 (2) 13.14 (3/1) 13.14 (8.1/1) 13.14 (10) 13.14 (14) 13.14 (15.1/2) + +.. index:: AI-0017 (Ada 2012 feature) + +* *AI-0017 Freezing and incomplete types (0000-00-00)* + + So-called 'Taft-amendment types' (i.e., types that are completed in package + bodies) are not frozen by the occurrence of bodies in the + enclosing declarative part. GNAT always implemented this properly. + + RM References: 13.14 (3/1) + +.. index:: AI-0060 (Ada 2012 feature) + +* *AI-0060 Extended definition of remote access types (0000-00-00)* + + This AI extends the definition of remote access types to include access + to limited, synchronized, protected or task class-wide interface types. + GNAT already implemented this extension. + + RM References: A (4) E.02.02 (9/1) E.02.02 (9.2/1) E.02.02 (14/2) E.02.02 (18) + +.. index:: AI-0114 (Ada 2012 feature) + +* *AI-0114 Classification of letters (0000-00-00)* + + The code points 170 (`FEMININE ORDINAL INDICATOR`), + 181 (`MICRO SIGN`), and + 186 (`MASCULINE ORDINAL INDICATOR`) are technically considered + lower case letters by Unicode. + However, they are not allowed in identifiers, and they + return `False` to `Ada.Characters.Handling.Is_Letter/Is_Lower`. + This behavior is consistent with that defined in Ada 95. + + RM References: A.03.02 (59) A.04.06 (7) + +.. index:: AI-0185 (Ada 2012 feature) + +* *AI-0185 Ada.Wide_[Wide_]Characters.Handling (2010-07-06)* + + Two new packages `Ada.Wide_[Wide_]Characters.Handling` provide + classification functions for `Wide_Character` and + `Wide_Wide_Character`, as well as providing + case folding routines for `Wide_[Wide_]Character` and + `Wide_[Wide_]String`. + + RM References: A.03.05 (0) A.03.06 (0) + +.. index:: AI-0031 (Ada 2012 feature) + +* *AI-0031 Add From parameter to Find_Token (2010-07-25)* + + A new version of `Find_Token` is added to all relevant string packages, + with an extra parameter `From`. Instead of starting at the first + character of the string, the search for a matching Token starts at the + character indexed by the value of `From`. + These procedures are available in all versions of Ada + but if used in versions earlier than Ada 2012 they will generate a warning + that an Ada 2012 subprogram is being used. + + RM References: A.04.03 (16) A.04.03 (67) A.04.03 (68/1) A.04.04 (51) + A.04.05 (46) + +.. index:: AI-0056 (Ada 2012 feature) + +* *AI-0056 Index on null string returns zero (0000-00-00)* + + The wording in the Ada 2005 RM implied an incompatible handling of the + `Index` functions, resulting in raising an exception instead of + returning zero in some situations. + This was not intended and has been corrected. + GNAT always returned zero, and is thus consistent with this AI. + + RM References: A.04.03 (56.2/2) A.04.03 (58.5/2) + +.. index:: AI-0137 (Ada 2012 feature) + +* *AI-0137 String encoding package (2010-03-25)* + + The packages `Ada.Strings.UTF_Encoding`, together with its child + packages, `Conversions`, `Strings`, `Wide_Strings`, + and `Wide_Wide_Strings` have been + implemented. These packages (whose documentation can be found in the spec + files :file:`a-stuten.ads`, :file:`a-suenco.ads`, :file:`a-suenst.ads`, + :file:`a-suewst.ads`, :file:`a-suezst.ads`) allow encoding and decoding of + `String`, `Wide_String`, and `Wide_Wide_String` + values using UTF coding schemes (including UTF-8, UTF-16LE, UTF-16BE, and + UTF-16), as well as conversions between the different UTF encodings. With + the exception of `Wide_Wide_Strings`, these packages are available in + Ada 95 and Ada 2005 mode as well as Ada 2012 mode. + The `Wide_Wide_Strings package` + is available in Ada 2005 mode as well as Ada 2012 mode (but not in Ada 95 + mode since it uses `Wide_Wide_Character`). + + RM References: A.04.11 + +.. index:: AI-0038 (Ada 2012 feature) + +* *AI-0038 Minor errors in Text_IO (0000-00-00)* + + These are minor errors in the description on three points. The intent on + all these points has always been clear, and GNAT has always implemented the + correct intended semantics. + + RM References: A.10.05 (37) A.10.07 (8/1) A.10.07 (10) A.10.07 (12) A.10.08 (10) A.10.08 (24) + +.. index:: AI-0044 (Ada 2012 feature) + +* *AI-0044 Restrictions on container instantiations (0000-00-00)* + + This AI places restrictions on allowed instantiations of generic containers. + These restrictions are not checked by the compiler, so there is nothing to + change in the implementation. This affects only the RM documentation. + + RM References: A.18 (4/2) A.18.02 (231/2) A.18.03 (145/2) A.18.06 (56/2) A.18.08 (66/2) A.18.09 (79/2) A.18.26 (5/2) A.18.26 (9/2) + +.. index:: AI-0127 (Ada 2012 feature) + +* *AI-0127 Adding Locale Capabilities (2010-09-29)* + + This package provides an interface for identifying the current locale. + + RM References: A.19 A.19.01 A.19.02 A.19.03 A.19.05 A.19.06 + A.19.07 A.19.08 A.19.09 A.19.10 A.19.11 A.19.12 A.19.13 + +.. index:: AI-0002 (Ada 2012 feature) + +* *AI-0002 Export C with unconstrained arrays (0000-00-00)* + + The compiler is not required to support exporting an Ada subprogram with + convention C if there are parameters or a return type of an unconstrained + array type (such as `String`). GNAT allows such declarations but + generates warnings. It is possible, but complicated, to write the + corresponding C code and certainly such code would be specific to GNAT and + non-portable. + + RM References: B.01 (17) B.03 (62) B.03 (71.1/2) + +.. index:: AI05-0216 (Ada 2012 feature) + +* *AI-0216 No_Task_Hierarchy forbids local tasks (0000-00-00)* + + It is clearly the intention that `No_Task_Hierarchy` is intended to + forbid tasks declared locally within subprograms, or functions returning task + objects, and that is the implementation that GNAT has always provided. + However the language in the RM was not sufficiently clear on this point. + Thus this is a documentation change in the RM only. + + RM References: D.07 (3/3) + +.. index:: AI-0211 (Ada 2012 feature) + +* *AI-0211 No_Relative_Delays forbids Set_Handler use (2010-07-09)* + + The restriction `No_Relative_Delays` forbids any calls to the subprogram + `Ada.Real_Time.Timing_Events.Set_Handler`. + + RM References: D.07 (5) D.07 (10/2) D.07 (10.4/2) D.07 (10.7/2) + +.. index:: AI-0190 (Ada 2012 feature) + +* *AI-0190 pragma Default_Storage_Pool (2010-09-15)* + + This AI introduces a new pragma `Default_Storage_Pool`, which can be + used to control storage pools globally. + In particular, you can force every access + type that is used for allocation (**new**) to have an explicit storage pool, + or you can declare a pool globally to be used for all access types that lack + an explicit one. + + RM References: D.07 (8) + +.. index:: AI-0189 (Ada 2012 feature) + +* *AI-0189 No_Allocators_After_Elaboration (2010-01-23)* + + This AI introduces a new restriction `No_Allocators_After_Elaboration`, + which says that no dynamic allocation will occur once elaboration is + completed. + In general this requires a run-time check, which is not required, and which + GNAT does not attempt. But the static cases of allocators in a task body or + in the body of the main program are detected and flagged at compile or bind + time. + + RM References: D.07 (19.1/2) H.04 (23.3/2) + +.. index:: AI-0171 (Ada 2012 feature) + +* *AI-0171 Pragma CPU and Ravenscar Profile (2010-09-24)* + + A new package `System.Multiprocessors` is added, together with the + definition of pragma `CPU` for controlling task affinity. A new no + dependence restriction, on `System.Multiprocessors.Dispatching_Domains`, + is added to the Ravenscar profile. + + RM References: D.13.01 (4/2) D.16 + +.. index:: AI-0210 (Ada 2012 feature) + +* *AI-0210 Correct Timing_Events metric (0000-00-00)* + + This is a documentation only issue regarding wording of metric requirements, + that does not affect the implementation of the compiler. + + RM References: D.15 (24/2) + +.. index:: AI-0206 (Ada 2012 feature) + +* *AI-0206 Remote types packages and preelaborate (2010-07-24)* + + Remote types packages are now allowed to depend on preelaborated packages. + This was formerly considered illegal. + + RM References: E.02.02 (6) + +.. index:: AI-0152 (Ada 2012 feature) + +* *AI-0152 Restriction No_Anonymous_Allocators (2010-09-08)* + + Restriction `No_Anonymous_Allocators` prevents the use of allocators + where the type of the returned value is an anonymous access type. + + RM References: H.04 (8/1) diff --git a/gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst b/gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst new file mode 100644 index 00000000000..5788929bedc --- /dev/null +++ b/gcc/ada/doc/gnat_rm/implementation_of_specific_ada_features.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst b/gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst new file mode 100644 index 00000000000..32403e19903 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst b/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst new file mode 100644 index 00000000000..1558d06bef1 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_rm/obsolescent_features.rst b/gcc/ada/doc/gnat_rm/obsolescent_features.rst new file mode 100644 index 00000000000..f5ea188a34d --- /dev/null +++ b/gcc/ada/doc/gnat_rm/obsolescent_features.rst @@ -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 diff --git a/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst b/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst new file mode 100644 index 00000000000..d2a19877fcc --- /dev/null +++ b/gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst @@ -0,0 +1,2138 @@ +.. _Representation_Clauses_and_Pragmas: + +********************************** +Representation Clauses and Pragmas +********************************** + +.. index:: Representation Clauses + +.. index:: Representation Clause + +.. index:: Representation Pragma + +.. index:: Pragma, representation + +This section describes the representation clauses accepted by GNAT, and +their effect on the representation of corresponding data objects. + +GNAT fully implements Annex C (Systems Programming). This means that all +the implementation advice sections in chapter 13 are fully implemented. +However, these sections only require a minimal level of support for +representation clauses. GNAT provides much more extensive capabilities, +and this section describes the additional capabilities provided. + +.. _Alignment_Clauses: + +Alignment Clauses +================= + +.. index:: Alignment Clause + +GNAT requires that all alignment clauses specify a power of 2, and all +default alignments are always a power of 2. The default alignment +values are as follows: + +* *Primitive Types*. + + For primitive types, the alignment is the minimum of the actual size of + objects of the type divided by `Storage_Unit`, + and the maximum alignment supported by the target. + (This maximum alignment is given by the GNAT-specific attribute + `Standard'Maximum_Alignment`; see :ref:`Attribute_Maximum_Alignment`.) + + .. index:: Maximum_Alignment attribute + + For example, for type `Long_Float`, the object size is 8 bytes, and the + default alignment will be 8 on any target that supports alignments + this large, but on some targets, the maximum alignment may be smaller + than 8, in which case objects of type `Long_Float` will be maximally + aligned. + +* *Arrays*. + + For arrays, the alignment is equal to the alignment of the component type + for the normal case where no packing or component size is given. If the + array is packed, and the packing is effective (see separate section on + packed arrays), then the alignment will be one for long packed arrays, + or arrays whose length is not known at compile time. For short packed + arrays, which are handled internally as modular types, the alignment + will be as described for primitive types, e.g., a packed array of length + 31 bits will have an object size of four bytes, and an alignment of 4. + +* *Records*. + + For the normal non-packed case, the alignment of a record is equal to + the maximum alignment of any of its components. For tagged records, this + includes the implicit access type used for the tag. If a pragma `Pack` + is used and all components are packable (see separate section on pragma + `Pack`), then the resulting alignment is 1, unless the layout of the + record makes it profitable to increase it. + + A special case is when: + + * the size of the record is given explicitly, or a + full record representation clause is given, and + + * the size of the record is 2, 4, or 8 bytes. + + In this case, an alignment is chosen to match the + size of the record. For example, if we have: + + .. code-block:: ada + + type Small is record + A, B : Character; + end record; + for Small'Size use 16; + + then the default alignment of the record type `Small` is 2, not 1. This + leads to more efficient code when the record is treated as a unit, and also + allows the type to specified as `Atomic` on architectures requiring + strict alignment. + +An alignment clause may specify a larger alignment than the default value +up to some maximum value dependent on the target (obtainable by using the +attribute reference `Standard'Maximum_Alignment`). It may also specify +a smaller alignment than the default value for enumeration, integer and +fixed point types, as well as for record types, for example + +.. code-block:: ada + + type V is record + A : Integer; + end record; + + for V'alignment use 1; + +.. index:: Alignment, default + +The default alignment for the type `V` is 4, as a result of the +Integer field in the record, but it is permissible, as shown, to +override the default alignment of the record with a smaller value. + +.. index:: Alignment, subtypes + +Note that according to the Ada standard, an alignment clause applies only +to the first named subtype. If additional subtypes are declared, then the +compiler is allowed to choose any alignment it likes, and there is no way +to control this choice. Consider: + +.. code-block:: ada + + type R is range 1 .. 10_000; + for R'Alignment use 1; + subtype RS is R range 1 .. 1000; + +The alignment clause specifies an alignment of 1 for the first named subtype +`R` but this does not necessarily apply to `RS`. When writing +portable Ada code, you should avoid writing code that explicitly or +implicitly relies on the alignment of such subtypes. + +For the GNAT compiler, if an explicit alignment clause is given, this +value is also used for any subsequent subtypes. So for GNAT, in the +above example, you can count on the alignment of `RS` being 1. But this +assumption is non-portable, and other compilers may choose different +alignments for the subtype `RS`. + +.. _Size_Clauses: + +Size Clauses +============ + +.. index:: Size Clause + +The default size for a type `T` is obtainable through the +language-defined attribute `T'Size` and also through the +equivalent GNAT-defined attribute `T'Value_Size`. +For objects of type `T`, GNAT will generally increase the type size +so that the object size (obtainable through the GNAT-defined attribute +`T'Object_Size`) +is a multiple of `T'Alignment * Storage_Unit`. + +For example: + +.. code-block:: ada + + type Smallint is range 1 .. 6; + + type Rec is record + Y1 : integer; + Y2 : boolean; + end record; + +In this example, `Smallint'Size` = `Smallint'Value_Size` = 3, +as specified by the RM rules, +but objects of this type will have a size of 8 +(`Smallint'Object_Size` = 8), +since objects by default occupy an integral number +of storage units. On some targets, notably older +versions of the Digital Alpha, the size of stand +alone objects of this type may be 32, reflecting +the inability of the hardware to do byte load/stores. + +Similarly, the size of type `Rec` is 40 bits +(`Rec'Size` = `Rec'Value_Size` = 40), but +the alignment is 4, so objects of this type will have +their size increased to 64 bits so that it is a multiple +of the alignment (in bits). This decision is +in accordance with the specific Implementation Advice in RM 13.3(43): + + "A `Size` clause should be supported for an object if the specified + `Size` is at least as large as its subtype's `Size`, and corresponds + to a size in storage elements that is a multiple of the object's + `Alignment` (if the `Alignment` is nonzero)." + +An explicit size clause may be used to override the default size by +increasing it. For example, if we have: + +.. code-block:: ada + + type My_Boolean is new Boolean; + for My_Boolean'Size use 32; + +then values of this type will always be 32 bits long. In the case of +discrete types, the size can be increased up to 64 bits, with the effect +that the entire specified field is used to hold the value, sign- or +zero-extended as appropriate. If more than 64 bits is specified, then +padding space is allocated after the value, and a warning is issued that +there are unused bits. + +Similarly the size of records and arrays may be increased, and the effect +is to add padding bits after the value. This also causes a warning message +to be generated. + +The largest Size value permitted in GNAT is 2**31-1. Since this is a +Size in bits, this corresponds to an object of size 256 megabytes (minus +one). This limitation is true on all targets. The reason for this +limitation is that it improves the quality of the code in many cases +if it is known that a Size value can be accommodated in an object of +type Integer. + + +.. _Storage_Size_Clauses: + +Storage_Size Clauses +==================== + +.. index:: Storage_Size Clause + +For tasks, the `Storage_Size` clause specifies the amount of space +to be allocated for the task stack. This cannot be extended, and if the +stack is exhausted, then `Storage_Error` will be raised (if stack +checking is enabled). Use a `Storage_Size` attribute definition clause, +or a `Storage_Size` pragma in the task definition to set the +appropriate required size. A useful technique is to include in every +task definition a pragma of the form: + +.. code-block:: ada + + pragma Storage_Size (Default_Stack_Size); + +Then `Default_Stack_Size` can be defined in a global package, and +modified as required. Any tasks requiring stack sizes different from the +default can have an appropriate alternative reference in the pragma. + +You can also use the *-d* binder switch to modify the default stack +size. + +For access types, the `Storage_Size` clause specifies the maximum +space available for allocation of objects of the type. If this space is +exceeded then `Storage_Error` will be raised by an allocation attempt. +In the case where the access type is declared local to a subprogram, the +use of a `Storage_Size` clause triggers automatic use of a special +predefined storage pool (`System.Pool_Size`) that ensures that all +space for the pool is automatically reclaimed on exit from the scope in +which the type is declared. + +A special case recognized by the compiler is the specification of a +`Storage_Size` of zero for an access type. This means that no +items can be allocated from the pool, and this is recognized at compile +time, and all the overhead normally associated with maintaining a fixed +size storage pool is eliminated. Consider the following example: + +.. code-block:: ada + + procedure p is + type R is array (Natural) of Character; + type P is access all R; + for P'Storage_Size use 0; + -- Above access type intended only for interfacing purposes + + y : P; + + procedure g (m : P); + pragma Import (C, g); + + -- ... + + begin + -- ... + y := new R; + end; + +As indicated in this example, these dummy storage pools are often useful in +connection with interfacing where no object will ever be allocated. If you +compile the above example, you get the warning: + +:: + + p.adb:16:09: warning: allocation from empty storage pool + p.adb:16:09: warning: Storage_Error will be raised at run time + + +Of course in practice, there will not be any explicit allocators in the +case of such an access declaration. + +.. _Size_of_Variant_Record_Objects: + +Size of Variant Record Objects +============================== + +.. index:: Size, variant record objects + +.. index:: Variant record objects, size + +In the case of variant record objects, there is a question whether Size gives +information about a particular variant, or the maximum size required +for any variant. Consider the following program + +.. code-block:: ada + + with Text_IO; use Text_IO; + procedure q is + type R1 (A : Boolean := False) is record + case A is + when True => X : Character; + when False => null; + end case; + end record; + + V1 : R1 (False); + V2 : R1; + + begin + Put_Line (Integer'Image (V1'Size)); + Put_Line (Integer'Image (V2'Size)); + end q; + +Here we are dealing with a variant record, where the True variant +requires 16 bits, and the False variant requires 8 bits. +In the above example, both V1 and V2 contain the False variant, +which is only 8 bits long. However, the result of running the +program is: + +:: + + 8 + 16 + +The reason for the difference here is that the discriminant value of +V1 is fixed, and will always be False. It is not possible to assign +a True variant value to V1, therefore 8 bits is sufficient. On the +other hand, in the case of V2, the initial discriminant value is +False (from the default), but it is possible to assign a True +variant value to V2, therefore 16 bits must be allocated for V2 +in the general case, even fewer bits may be needed at any particular +point during the program execution. + +As can be seen from the output of this program, the `'Size` +attribute applied to such an object in GNAT gives the actual allocated +size of the variable, which is the largest size of any of the variants. +The Ada Reference Manual is not completely clear on what choice should +be made here, but the GNAT behavior seems most consistent with the +language in the RM. + +In some cases, it may be desirable to obtain the size of the current +variant, rather than the size of the largest variant. This can be +achieved in GNAT by making use of the fact that in the case of a +subprogram parameter, GNAT does indeed return the size of the current +variant (because a subprogram has no way of knowing how much space +is actually allocated for the actual). + +Consider the following modified version of the above program: + +.. code-block:: ada + + with Text_IO; use Text_IO; + procedure q is + type R1 (A : Boolean := False) is record + case A is + when True => X : Character; + when False => null; + end case; + end record; + + V2 : R1; + + function Size (V : R1) return Integer is + begin + return V'Size; + end Size; + + begin + Put_Line (Integer'Image (V2'Size)); + Put_Line (Integer'IMage (Size (V2))); + V2 := (True, 'x'); + Put_Line (Integer'Image (V2'Size)); + Put_Line (Integer'IMage (Size (V2))); + end q; + +The output from this program is + +:: + + 16 + 8 + 16 + 16 + +Here we see that while the `'Size` attribute always returns +the maximum size, regardless of the current variant value, the +`Size` function does indeed return the size of the current +variant value. + + +.. _Biased_Representation: + +Biased Representation +===================== + +.. index:: Size for biased representation + +.. index:: Biased representation + +In the case of scalars with a range starting at other than zero, it is +possible in some cases to specify a size smaller than the default minimum +value, and in such cases, GNAT uses an unsigned biased representation, +in which zero is used to represent the lower bound, and successive values +represent successive values of the type. + +For example, suppose we have the declaration: + +.. code-block:: ada + + type Small is range -7 .. -4; + for Small'Size use 2; + +Although the default size of type `Small` is 4, the `Size` +clause is accepted by GNAT and results in the following representation +scheme: + +:: + + -7 is represented as 2#00# + -6 is represented as 2#01# + -5 is represented as 2#10# + -4 is represented as 2#11# + +Biased representation is only used if the specified `Size` clause +cannot be accepted in any other manner. These reduced sizes that force +biased representation can be used for all discrete types except for +enumeration types for which a representation clause is given. + + +.. _Value_Size_and_Object_Size_Clauses: + +Value_Size and Object_Size Clauses +================================== + +.. index:: Value_Size +.. index:: Object_Size +.. index:: Size, of objects + +In Ada 95 and Ada 2005, `T'Size` for a type `T` is the minimum +number of bits required to hold values of type `T`. +Although this interpretation was allowed in Ada 83, it was not required, +and this requirement in practice can cause some significant difficulties. +For example, in most Ada 83 compilers, `Natural'Size` was 32. +However, in Ada 95 and Ada 2005, +`Natural'Size` is +typically 31. This means that code may change in behavior when moving +from Ada 83 to Ada 95 or Ada 2005. For example, consider: + +.. code-block:: ada + + type Rec is record; + A : Natural; + B : Natural; + end record; + + for Rec use record + at 0 range 0 .. Natural'Size - 1; + at 0 range Natural'Size .. 2 * Natural'Size - 1; + end record; + +In the above code, since the typical size of `Natural` objects +is 32 bits and `Natural'Size` is 31, the above code can cause +unexpected inefficient packing in Ada 95 and Ada 2005, and in general +there are cases where the fact that the object size can exceed the +size of the type causes surprises. + +To help get around this problem GNAT provides two implementation +defined attributes, `Value_Size` and `Object_Size`. When +applied to a type, these attributes yield the size of the type +(corresponding to the RM defined size attribute), and the size of +objects of the type respectively. + +The `Object_Size` is used for determining the default size of +objects and components. This size value can be referred to using the +`Object_Size` attribute. The phrase 'is used' here means that it is +the basis of the determination of the size. The backend is free to +pad this up if necessary for efficiency, e.g., an 8-bit stand-alone +character might be stored in 32 bits on a machine with no efficient +byte access instructions such as the Alpha. + +The default rules for the value of `Object_Size` for +discrete types are as follows: + +* + The `Object_Size` for base subtypes reflect the natural hardware + size in bits (run the compiler with *-gnatS* to find those values + for numeric types). Enumeration types and fixed-point base subtypes have + 8, 16, 32 or 64 bits for this size, depending on the range of values + to be stored. + +* + The `Object_Size` of a subtype is the same as the + `Object_Size` of + the type from which it is obtained. + +* + The `Object_Size` of a derived base type is copied from the parent + base type, and the `Object_Size` of a derived first subtype is copied + from the parent first subtype. + +The `Value_Size` attribute +is the (minimum) number of bits required to store a value +of the type. +This value is used to determine how tightly to pack +records or arrays with components of this type, and also affects +the semantics of unchecked conversion (unchecked conversions where +the `Value_Size` values differ generate a warning, and are potentially +target dependent). + +The default rules for the value of `Value_Size` are as follows: + +* + The `Value_Size` for a base subtype is the minimum number of bits + required to store all values of the type (including the sign bit + only if negative values are possible). + +* + If a subtype statically matches the first subtype of a given type, then it has + by default the same `Value_Size` as the first subtype. This is a + consequence of RM 13.1(14): "if two subtypes statically match, + then their subtype-specific aspects are the same".) + +* + All other subtypes have a `Value_Size` corresponding to the minimum + number of bits required to store all values of the subtype. For + dynamic bounds, it is assumed that the value can range down or up + to the corresponding bound of the ancestor + +The RM defined attribute `Size` corresponds to the +`Value_Size` attribute. + +The `Size` attribute may be defined for a first-named subtype. This sets +the `Value_Size` of +the first-named subtype to the given value, and the +`Object_Size` of this first-named subtype to the given value padded up +to an appropriate boundary. It is a consequence of the default rules +above that this `Object_Size` will apply to all further subtypes. On the +other hand, `Value_Size` is affected only for the first subtype, any +dynamic subtypes obtained from it directly, and any statically matching +subtypes. The `Value_Size` of any other static subtypes is not affected. + +`Value_Size` and +`Object_Size` may be explicitly set for any subtype using +an attribute definition clause. Note that the use of these attributes +can cause the RM 13.1(14) rule to be violated. If two access types +reference aliased objects whose subtypes have differing `Object_Size` +values as a result of explicit attribute definition clauses, then it +is illegal to convert from one access subtype to the other. For a more +complete description of this additional legality rule, see the +description of the `Object_Size` attribute. + +At the implementation level, Esize stores the Object_Size and the +RM_Size field stores the `Value_Size` (and hence the value of the +`Size` attribute, +which, as noted above, is equivalent to `Value_Size`). + +To get a feel for the difference, consider the following examples (note +that in each case the base is `Short_Short_Integer` with a size of 8): + ++---------------------------------------------+-------------+-------------+ +|Type or subtype declaration | Object_Size | Value_Size| ++=============================================+=============+=============+ +|``type x1 is range 0 .. 5;`` | 8 | 3 | ++---------------------------------------------+-------------+-------------+ +|``type x2 is range 0 .. 5;`` | 16 | 12 | +|``for x2'size use 12;`` | | | ++---------------------------------------------+-------------+-------------+ +|``subtype x3 is x2 range 0 .. 3;`` | 16 | 2 | ++---------------------------------------------+-------------+-------------+ +|``subtype x4 is x2'base range 0 .. 10;`` | 8 | 4 | ++---------------------------------------------+-------------+-------------+ +|``subtype x5 is x2 range 0 .. dynamic;`` | 16 | 3* | ++---------------------------------------------+-------------+-------------+ +|``subtype x6 is x2'base range 0 .. dynamic;``| 8 | 3* | ++---------------------------------------------+-------------+-------------+ + +Note: the entries marked '3*' are not actually specified by the Ada +Reference Manual, but it seems in the spirit of the RM rules to allocate +the minimum number of bits (here 3, given the range for `x2`) +known to be large enough to hold the given range of values. + +So far, so good, but GNAT has to obey the RM rules, so the question is +under what conditions must the RM `Size` be used. +The following is a list +of the occasions on which the RM `Size` must be used: + +* + Component size for packed arrays or records + +* + Value of the attribute `Size` for a type + +* + Warning about sizes not matching for unchecked conversion + +For record types, the `Object_Size` is always a multiple of the +alignment of the type (this is true for all types). In some cases the +`Value_Size` can be smaller. Consider: + + +.. code-block:: ada + + type R is record + X : Integer; + Y : Character; + end record; + + +On a typical 32-bit architecture, the X component will be four bytes, and +require four-byte alignment, and the Y component will be one byte. In this +case `R'Value_Size` will be 40 (bits) since this is the minimum size +required to store a value of this type, and for example, it is permissible +to have a component of type R in an outer array whose component size is +specified to be 48 bits. However, `R'Object_Size` will be 64 (bits), +since it must be rounded up so that this value is a multiple of the +alignment (4 bytes = 32 bits). + +For all other types, the `Object_Size` +and Value_Size are the same (and equivalent to the RM attribute `Size`). +Only `Size` may be specified for such types. + +Note that `Value_Size` can be used to force biased representation +for a particular subtype. Consider this example: + + +.. code-block:: ada + + type R is (A, B, C, D, E, F); + subtype RAB is R range A .. B; + subtype REF is R range E .. F; + + +By default, `RAB` +has a size of 1 (sufficient to accommodate the representation +of `A` and `B`, 0 and 1), and `REF` +has a size of 3 (sufficient to accommodate the representation +of `E` and `F`, 4 and 5). But if we add the +following `Value_Size` attribute definition clause: + + +.. code-block:: ada + + for REF'Value_Size use 1; + + +then biased representation is forced for `REF`, +and 0 will represent `E` and 1 will represent `F`. +A warning is issued when a `Value_Size` attribute +definition clause forces biased representation. This +warning can be turned off using `-gnatw.B`. + +.. _Component_Size_Clauses: + +Component_Size Clauses +====================== + +.. index:: Component_Size Clause + +Normally, the value specified in a component size clause must be consistent +with the subtype of the array component with regard to size and alignment. +In other words, the value specified must be at least equal to the size +of this subtype, and must be a multiple of the alignment value. + +In addition, component size clauses are allowed which cause the array +to be packed, by specifying a smaller value. A first case is for +component size values in the range 1 through 63. The value specified +must not be smaller than the Size of the subtype. GNAT will accurately +honor all packing requests in this range. For example, if we have: + + +.. code-block:: ada + + type r is array (1 .. 8) of Natural; + for r'Component_Size use 31; + + +then the resulting array has a length of 31 bytes (248 bits = 8 * 31). +Of course access to the components of such an array is considerably +less efficient than if the natural component size of 32 is used. +A second case is when the subtype of the component is a record type +padded because of its default alignment. For example, if we have: + + +.. code-block:: ada + + type r is record + i : Integer; + j : Integer; + b : Boolean; + end record; + + type a is array (1 .. 8) of r; + for a'Component_Size use 72; + + +then the resulting array has a length of 72 bytes, instead of 96 bytes +if the alignment of the record (4) was obeyed. + +Note that there is no point in giving both a component size clause +and a pragma Pack for the same array type. if such duplicate +clauses are given, the pragma Pack will be ignored. + +.. _Bit_Order_Clauses: + +Bit_Order Clauses +================= + +.. index:: Bit_Order Clause + +.. index:: bit ordering + +.. index:: ordering, of bits + +For record subtypes, GNAT permits the specification of the `Bit_Order` +attribute. The specification may either correspond to the default bit +order for the target, in which case the specification has no effect and +places no additional restrictions, or it may be for the non-standard +setting (that is the opposite of the default). + +In the case where the non-standard value is specified, the effect is +to renumber bits within each byte, but the ordering of bytes is not +affected. There are certain +restrictions placed on component clauses as follows: + + +* Components fitting within a single storage unit. + + These are unrestricted, and the effect is merely to renumber bits. For + example if we are on a little-endian machine with `Low_Order_First` + being the default, then the following two declarations have exactly + the same effect: + + + :: + + type R1 is record + A : Boolean; + B : Integer range 1 .. 120; + end record; + + for R1 use record + A at 0 range 0 .. 0; + B at 0 range 1 .. 7; + end record; + + type R2 is record + A : Boolean; + B : Integer range 1 .. 120; + end record; + + for R2'Bit_Order use High_Order_First; + + for R2 use record + A at 0 range 7 .. 7; + B at 0 range 0 .. 6; + end record; + + + The useful application here is to write the second declaration with the + `Bit_Order` attribute definition clause, and know that it will be treated + the same, regardless of whether the target is little-endian or big-endian. + +* Components occupying an integral number of bytes. + + These are components that exactly fit in two or more bytes. Such component + declarations are allowed, but have no effect, since it is important to realize + that the `Bit_Order` specification does not affect the ordering of bytes. + In particular, the following attempt at getting an endian-independent integer + does not work: + + + :: + + type R2 is record + A : Integer; + end record; + + for R2'Bit_Order use High_Order_First; + + for R2 use record + A at 0 range 0 .. 31; + end record; + + + This declaration will result in a little-endian integer on a + little-endian machine, and a big-endian integer on a big-endian machine. + If byte flipping is required for interoperability between big- and + little-endian machines, this must be explicitly programmed. This capability + is not provided by `Bit_Order`. + +* Components that are positioned across byte boundaries + + but do not occupy an integral number of bytes. Given that bytes are not + reordered, such fields would occupy a non-contiguous sequence of bits + in memory, requiring non-trivial code to reassemble. They are for this + reason not permitted, and any component clause specifying such a layout + will be flagged as illegal by GNAT. + + +Since the misconception that Bit_Order automatically deals with all +endian-related incompatibilities is a common one, the specification of +a component field that is an integral number of bytes will always +generate a warning. This warning may be suppressed using `pragma Warnings (Off)` +if desired. The following section contains additional +details regarding the issue of byte ordering. + +.. _Effect_of_Bit_Order_on_Byte_Ordering: + +Effect of Bit_Order on Byte Ordering +==================================== + +.. index:: byte ordering + +.. index:: ordering, of bytes + +In this section we will review the effect of the `Bit_Order` attribute +definition clause on byte ordering. Briefly, it has no effect at all, but +a detailed example will be helpful. Before giving this +example, let us review the precise +definition of the effect of defining `Bit_Order`. The effect of a +non-standard bit order is described in section 15.5.3 of the Ada +Reference Manual: + + "2 A bit ordering is a method of interpreting the meaning of + the storage place attributes." + +To understand the precise definition of storage place attributes in +this context, we visit section 13.5.1 of the manual: + + "13 A record_representation_clause (without the mod_clause) + specifies the layout. The storage place attributes (see 13.5.2) + are taken from the values of the position, first_bit, and last_bit + expressions after normalizing those values so that first_bit is + less than Storage_Unit." + +The critical point here is that storage places are taken from +the values after normalization, not before. So the `Bit_Order` +interpretation applies to normalized values. The interpretation +is described in the later part of the 15.5.3 paragraph: + + "2 A bit ordering is a method of interpreting the meaning of + the storage place attributes. High_Order_First (known in the + vernacular as 'big endian') means that the first bit of a + storage element (bit 0) is the most significant bit (interpreting + the sequence of bits that represent a component as an unsigned + integer value). Low_Order_First (known in the vernacular as + 'little endian') means the opposite: the first bit is the + least significant." + +Note that the numbering is with respect to the bits of a storage +unit. In other words, the specification affects only the numbering +of bits within a single storage unit. + +We can make the effect clearer by giving an example. + +Suppose that we have an external device which presents two bytes, the first +byte presented, which is the first (low addressed byte) of the two byte +record is called Master, and the second byte is called Slave. + +The left most (most significant bit is called Control for each byte, and +the remaining 7 bits are called V1, V2, ... V7, where V7 is the rightmost +(least significant) bit. + +On a big-endian machine, we can write the following representation clause + + +.. code-block:: ada + + type Data is record + Master_Control : Bit; + Master_V1 : Bit; + Master_V2 : Bit; + Master_V3 : Bit; + Master_V4 : Bit; + Master_V5 : Bit; + Master_V6 : Bit; + Master_V7 : Bit; + Slave_Control : Bit; + Slave_V1 : Bit; + Slave_V2 : Bit; + Slave_V3 : Bit; + Slave_V4 : Bit; + Slave_V5 : Bit; + Slave_V6 : Bit; + Slave_V7 : Bit; + end record; + + for Data use record + Master_Control at 0 range 0 .. 0; + Master_V1 at 0 range 1 .. 1; + Master_V2 at 0 range 2 .. 2; + Master_V3 at 0 range 3 .. 3; + Master_V4 at 0 range 4 .. 4; + Master_V5 at 0 range 5 .. 5; + Master_V6 at 0 range 6 .. 6; + Master_V7 at 0 range 7 .. 7; + Slave_Control at 1 range 0 .. 0; + Slave_V1 at 1 range 1 .. 1; + Slave_V2 at 1 range 2 .. 2; + Slave_V3 at 1 range 3 .. 3; + Slave_V4 at 1 range 4 .. 4; + Slave_V5 at 1 range 5 .. 5; + Slave_V6 at 1 range 6 .. 6; + Slave_V7 at 1 range 7 .. 7; + end record; + + +Now if we move this to a little endian machine, then the bit ordering within +the byte is backwards, so we have to rewrite the record rep clause as: + + +.. code-block:: ada + + for Data use record + Master_Control at 0 range 7 .. 7; + Master_V1 at 0 range 6 .. 6; + Master_V2 at 0 range 5 .. 5; + Master_V3 at 0 range 4 .. 4; + Master_V4 at 0 range 3 .. 3; + Master_V5 at 0 range 2 .. 2; + Master_V6 at 0 range 1 .. 1; + Master_V7 at 0 range 0 .. 0; + Slave_Control at 1 range 7 .. 7; + Slave_V1 at 1 range 6 .. 6; + Slave_V2 at 1 range 5 .. 5; + Slave_V3 at 1 range 4 .. 4; + Slave_V4 at 1 range 3 .. 3; + Slave_V5 at 1 range 2 .. 2; + Slave_V6 at 1 range 1 .. 1; + Slave_V7 at 1 range 0 .. 0; + end record; + + +It is a nuisance to have to rewrite the clause, especially if +the code has to be maintained on both machines. However, +this is a case that we can handle with the +`Bit_Order` attribute if it is implemented. +Note that the implementation is not required on byte addressed +machines, but it is indeed implemented in GNAT. +This means that we can simply use the +first record clause, together with the declaration + + +.. code-block:: ada + + for Data'Bit_Order use High_Order_First; + + +and the effect is what is desired, namely the layout is exactly the same, +independent of whether the code is compiled on a big-endian or little-endian +machine. + +The important point to understand is that byte ordering is not affected. +A `Bit_Order` attribute definition never affects which byte a field +ends up in, only where it ends up in that byte. +To make this clear, let us rewrite the record rep clause of the previous +example as: + + +.. code-block:: ada + + for Data'Bit_Order use High_Order_First; + for Data use record + Master_Control at 0 range 0 .. 0; + Master_V1 at 0 range 1 .. 1; + Master_V2 at 0 range 2 .. 2; + Master_V3 at 0 range 3 .. 3; + Master_V4 at 0 range 4 .. 4; + Master_V5 at 0 range 5 .. 5; + Master_V6 at 0 range 6 .. 6; + Master_V7 at 0 range 7 .. 7; + Slave_Control at 0 range 8 .. 8; + Slave_V1 at 0 range 9 .. 9; + Slave_V2 at 0 range 10 .. 10; + Slave_V3 at 0 range 11 .. 11; + Slave_V4 at 0 range 12 .. 12; + Slave_V5 at 0 range 13 .. 13; + Slave_V6 at 0 range 14 .. 14; + Slave_V7 at 0 range 15 .. 15; + end record; + + +This is exactly equivalent to saying (a repeat of the first example): + + +.. code-block:: ada + + for Data'Bit_Order use High_Order_First; + for Data use record + Master_Control at 0 range 0 .. 0; + Master_V1 at 0 range 1 .. 1; + Master_V2 at 0 range 2 .. 2; + Master_V3 at 0 range 3 .. 3; + Master_V4 at 0 range 4 .. 4; + Master_V5 at 0 range 5 .. 5; + Master_V6 at 0 range 6 .. 6; + Master_V7 at 0 range 7 .. 7; + Slave_Control at 1 range 0 .. 0; + Slave_V1 at 1 range 1 .. 1; + Slave_V2 at 1 range 2 .. 2; + Slave_V3 at 1 range 3 .. 3; + Slave_V4 at 1 range 4 .. 4; + Slave_V5 at 1 range 5 .. 5; + Slave_V6 at 1 range 6 .. 6; + Slave_V7 at 1 range 7 .. 7; + end record; + + +Why are they equivalent? Well take a specific field, the `Slave_V2` +field. The storage place attributes are obtained by normalizing the +values given so that the `First_Bit` value is less than 8. After +normalizing the values (0,10,10) we get (1,2,2) which is exactly what +we specified in the other case. + +Now one might expect that the `Bit_Order` attribute might affect +bit numbering within the entire record component (two bytes in this +case, thus affecting which byte fields end up in), but that is not +the way this feature is defined, it only affects numbering of bits, +not which byte they end up in. + +Consequently it never makes sense to specify a starting bit number +greater than 7 (for a byte addressable field) if an attribute +definition for `Bit_Order` has been given, and indeed it +may be actively confusing to specify such a value, so the compiler +generates a warning for such usage. + +If you do need to control byte ordering then appropriate conditional +values must be used. If in our example, the slave byte came first on +some machines we might write: + +.. code-block:: ada + + Master_Byte_First constant Boolean := ...; + + Master_Byte : constant Natural := + 1 - Boolean'Pos (Master_Byte_First); + Slave_Byte : constant Natural := + Boolean'Pos (Master_Byte_First); + + for Data'Bit_Order use High_Order_First; + for Data use record + Master_Control at Master_Byte range 0 .. 0; + Master_V1 at Master_Byte range 1 .. 1; + Master_V2 at Master_Byte range 2 .. 2; + Master_V3 at Master_Byte range 3 .. 3; + Master_V4 at Master_Byte range 4 .. 4; + Master_V5 at Master_Byte range 5 .. 5; + Master_V6 at Master_Byte range 6 .. 6; + Master_V7 at Master_Byte range 7 .. 7; + Slave_Control at Slave_Byte range 0 .. 0; + Slave_V1 at Slave_Byte range 1 .. 1; + Slave_V2 at Slave_Byte range 2 .. 2; + Slave_V3 at Slave_Byte range 3 .. 3; + Slave_V4 at Slave_Byte range 4 .. 4; + Slave_V5 at Slave_Byte range 5 .. 5; + Slave_V6 at Slave_Byte range 6 .. 6; + Slave_V7 at Slave_Byte range 7 .. 7; + end record; + +Now to switch between machines, all that is necessary is +to set the boolean constant `Master_Byte_First` in +an appropriate manner. + +.. _Pragma_Pack_for_Arrays: + +Pragma Pack for Arrays +====================== + +.. index:: Pragma Pack (for arrays) + +Pragma `Pack` applied to an array has no effect unless the component type +is packable. For a component type to be packable, it must be one of the +following cases: + +* + Any scalar type +* + Any type whose size is specified with a size clause +* + Any packed array type with a static size +* + Any record type padded because of its default alignment + +For all these cases, if the component subtype size is in the range +1 through 63, then the effect of the pragma `Pack` is exactly as though a +component size were specified giving the component subtype size. +For example if we have: + +.. code-block:: ada + + type r is range 0 .. 17; + + type ar is array (1 .. 8) of r; + pragma Pack (ar); + +Then the component size of `ar` will be set to 5 (i.e., to `r'size`, +and the size of the array `ar` will be exactly 40 bits. + +Note that in some cases this rather fierce approach to packing can produce +unexpected effects. For example, in Ada 95 and Ada 2005, +subtype `Natural` typically has a size of 31, meaning that if you +pack an array of `Natural`, you get 31-bit +close packing, which saves a few bits, but results in far less efficient +access. Since many other Ada compilers will ignore such a packing request, +GNAT will generate a warning on some uses of pragma `Pack` that it guesses +might not be what is intended. You can easily remove this warning by +using an explicit `Component_Size` setting instead, which never generates +a warning, since the intention of the programmer is clear in this case. + +GNAT treats packed arrays in one of two ways. If the size of the array is +known at compile time and is less than 64 bits, then internally the array +is represented as a single modular type, of exactly the appropriate number +of bits. If the length is greater than 63 bits, or is not known at compile +time, then the packed array is represented as an array of bytes, and the +length is always a multiple of 8 bits. + +Note that to represent a packed array as a modular type, the alignment must +be suitable for the modular type involved. For example, on typical machines +a 32-bit packed array will be represented by a 32-bit modular integer with +an alignment of four bytes. If you explicitly override the default alignment +with an alignment clause that is too small, the modular representation +cannot be used. For example, consider the following set of declarations: + +.. code-block:: ada + + type R is range 1 .. 3; + type S is array (1 .. 31) of R; + for S'Component_Size use 2; + for S'Size use 62; + for S'Alignment use 1; + +If the alignment clause were not present, then a 62-bit modular +representation would be chosen (typically with an alignment of 4 or 8 +bytes depending on the target). But the default alignment is overridden +with the explicit alignment clause. This means that the modular +representation cannot be used, and instead the array of bytes +representation must be used, meaning that the length must be a multiple +of 8. Thus the above set of declarations will result in a diagnostic +rejecting the size clause and noting that the minimum size allowed is 64. + +.. index:: Pragma Pack (for type Natural) + +.. index:: Pragma Pack warning + +One special case that is worth noting occurs when the base type of the +component size is 8/16/32 and the subtype is one bit less. Notably this +occurs with subtype `Natural`. Consider: + +.. code-block:: ada + + type Arr is array (1 .. 32) of Natural; + pragma Pack (Arr); + +In all commonly used Ada 83 compilers, this pragma Pack would be ignored, +since typically `Natural'Size` is 32 in Ada 83, and in any case most +Ada 83 compilers did not attempt 31 bit packing. + +In Ada 95 and Ada 2005, `Natural'Size` is required to be 31. Furthermore, +GNAT really does pack 31-bit subtype to 31 bits. This may result in a +substantial unintended performance penalty when porting legacy Ada 83 code. +To help prevent this, GNAT generates a warning in such cases. If you really +want 31 bit packing in a case like this, you can set the component size +explicitly: + +.. code-block:: ada + + type Arr is array (1 .. 32) of Natural; + for Arr'Component_Size use 31; + +Here 31-bit packing is achieved as required, and no warning is generated, +since in this case the programmer intention is clear. + +.. _Pragma_Pack_for_Records: + +Pragma Pack for Records +======================= + +.. index:: Pragma Pack (for records) + +Pragma `Pack` applied to a record will pack the components to reduce +wasted space from alignment gaps and by reducing the amount of space +taken by components. We distinguish between *packable* components and +*non-packable* components. +Components of the following types are considered packable: + +* + Components of a primitive type are packable unless they are aliased + or of an atomic type. + +* + Small packed arrays, whose size does not exceed 64 bits, and where the + size is statically known at compile time, are represented internally + as modular integers, and so they are also packable. + + +All packable components occupy the exact number of bits corresponding to +their `Size` value, and are packed with no padding bits, i.e., they +can start on an arbitrary bit boundary. + +All other types are non-packable, they occupy an integral number of +storage units, and +are placed at a boundary corresponding to their alignment requirements. + +For example, consider the record + +.. code-block:: ada + + type Rb1 is array (1 .. 13) of Boolean; + pragma Pack (Rb1); + + type Rb2 is array (1 .. 65) of Boolean; + pragma Pack (Rb2); + + type AF is new Float with Atomic; + + type X2 is record + L1 : Boolean; + L2 : Duration; + L3 : AF; + L4 : Boolean; + L5 : Rb1; + L6 : Rb2; + end record; + pragma Pack (X2); + +The representation for the record X2 is as follows: + +.. code-block:: ada + + for X2'Size use 224; + for X2 use record + L1 at 0 range 0 .. 0; + L2 at 0 range 1 .. 64; + L3 at 12 range 0 .. 31; + L4 at 16 range 0 .. 0; + L5 at 16 range 1 .. 13; + L6 at 18 range 0 .. 71; + end record; + +Studying this example, we see that the packable fields `L1` +and `L2` are +of length equal to their sizes, and placed at specific bit boundaries (and +not byte boundaries) to +eliminate padding. But `L3` is of a non-packable float type (because +it is aliased), so it is on the next appropriate alignment boundary. + +The next two fields are fully packable, so `L4` and `L5` are +minimally packed with no gaps. However, type `Rb2` is a packed +array that is longer than 64 bits, so it is itself non-packable. Thus +the `L6` field is aligned to the next byte boundary, and takes an +integral number of bytes, i.e., 72 bits. + +.. _Record_Representation_Clauses: + +Record Representation Clauses +============================= + +.. index:: Record Representation Clause + +Record representation clauses may be given for all record types, including +types obtained by record extension. Component clauses are allowed for any +static component. The restrictions on component clauses depend on the type +of the component. + +.. index:: Component Clause + +For all components of an elementary type, the only restriction on component +clauses is that the size must be at least the 'Size value of the type +(actually the Value_Size). There are no restrictions due to alignment, +and such components may freely cross storage boundaries. + +Packed arrays with a size up to and including 64 bits are represented +internally using a modular type with the appropriate number of bits, and +thus the same lack of restriction applies. For example, if you declare: + +.. code-block:: ada + + type R is array (1 .. 49) of Boolean; + pragma Pack (R); + for R'Size use 49; + +then a component clause for a component of type R may start on any +specified bit boundary, and may specify a value of 49 bits or greater. + +For packed bit arrays that are longer than 64 bits, there are two +cases. If the component size is a power of 2 (1,2,4,8,16,32 bits), +including the important case of single bits or boolean values, then +there are no limitations on placement of such components, and they +may start and end at arbitrary bit boundaries. + +If the component size is not a power of 2 (e.g., 3 or 5), then +an array of this type longer than 64 bits must always be placed on +on a storage unit (byte) boundary and occupy an integral number +of storage units (bytes). Any component clause that does not +meet this requirement will be rejected. + +Any aliased component, or component of an aliased type, must +have its normal alignment and size. A component clause that +does not meet this requirement will be rejected. + +The tag field of a tagged type always occupies an address sized field at +the start of the record. No component clause may attempt to overlay this +tag. When a tagged type appears as a component, the tag field must have +proper alignment + +In the case of a record extension T1, of a type T, no component clause applied +to the type T1 can specify a storage location that would overlap the first +T'Size bytes of the record. + +For all other component types, including non-bit-packed arrays, +the component can be placed at an arbitrary bit boundary, +so for example, the following is permitted: + +.. code-block:: ada + + type R is array (1 .. 10) of Boolean; + for R'Size use 80; + + type Q is record + G, H : Boolean; + L, M : R; + end record; + + for Q use record + G at 0 range 0 .. 0; + H at 0 range 1 .. 1; + L at 0 range 2 .. 81; + R at 0 range 82 .. 161; + end record; + +Note: the above rules apply to recent releases of GNAT 5. +In GNAT 3, there are more severe restrictions on larger components. +For non-primitive types, including packed arrays with a size greater than +64 bits, component clauses must respect the alignment requirement of the +type, in particular, always starting on a byte boundary, and the length +must be a multiple of the storage unit. + +.. _Handling_of_Records_with_Holes: + +Handling of Records with Holes +============================== + +.. index:: Handling of Records with Holes + +As a result of alignment considerations, records may contain "holes" +or gaps +which do not correspond to the data bits of any of the components. +Record representation clauses can also result in holes in records. + +GNAT does not attempt to clear these holes, so in record objects, +they should be considered to hold undefined rubbish. The generated +equality routine just tests components so does not access these +undefined bits, and assignment and copy operations may or may not +preserve the contents of these holes (for assignments, the holes +in the target will in practice contain either the bits that are +present in the holes in the source, or the bits that were present +in the target before the assignment). + +If it is necessary to ensure that holes in records have all zero +bits, then record objects for which this initialization is desired +should be explicitly set to all zero values using Unchecked_Conversion +or address overlays. For example + +.. code-block:: ada + + type HRec is record + C : Character; + I : Integer; + end record; + +On typical machines, integers need to be aligned on a four-byte +boundary, resulting in three bytes of undefined rubbish following +the 8-bit field for C. To ensure that the hole in a variable of +type HRec is set to all zero bits, +you could for example do: + +.. code-block:: ada + + type Base is record + Dummy1, Dummy2 : Integer := 0; + end record; + + BaseVar : Base; + RealVar : Hrec; + for RealVar'Address use BaseVar'Address; + + +Now the 8-bytes of the value of RealVar start out containing all zero +bits. A safer approach is to just define dummy fields, avoiding the +holes, as in: + +.. code-block:: ada + + type HRec is record + C : Character; + Dummy1 : Short_Short_Integer := 0; + Dummy2 : Short_Short_Integer := 0; + Dummy3 : Short_Short_Integer := 0; + I : Integer; + end record; + +And to make absolutely sure that the intent of this is followed, you +can use representation clauses: + +.. code-block:: ada + + for Hrec use record + C at 0 range 0 .. 7; + Dummy1 at 1 range 0 .. 7; + Dummy2 at 2 range 0 .. 7; + Dummy3 at 3 range 0 .. 7; + I at 4 range 0 .. 31; + end record; + for Hrec'Size use 64; + + +.. _Enumeration_Clauses: + +Enumeration Clauses +=================== + +The only restriction on enumeration clauses is that the range of values +must be representable. For the signed case, if one or more of the +representation values are negative, all values must be in the range: + +.. code-block:: ada + + System.Min_Int .. System.Max_Int + +For the unsigned case, where all values are nonnegative, the values must +be in the range: + +.. code-block:: ada + + 0 .. System.Max_Binary_Modulus; + + +A *confirming* representation clause is one in which the values range +from 0 in sequence, i.e., a clause that confirms the default representation +for an enumeration type. +Such a confirming representation +is permitted by these rules, and is specially recognized by the compiler so +that no extra overhead results from the use of such a clause. + +If an array has an index type which is an enumeration type to which an +enumeration clause has been applied, then the array is stored in a compact +manner. Consider the declarations: + +.. code-block:: ada + + type r is (A, B, C); + for r use (A => 1, B => 5, C => 10); + type t is array (r) of Character; + +The array type t corresponds to a vector with exactly three elements and +has a default size equal to `3*Character'Size`. This ensures efficient +use of space, but means that accesses to elements of the array will incur +the overhead of converting representation values to the corresponding +positional values, (i.e., the value delivered by the `Pos` attribute). + + +.. _Address_Clauses: + +Address Clauses +=============== +.. index:: Address Clause + +The reference manual allows a general restriction on representation clauses, +as found in RM 13.1(22): + + "An implementation need not support representation + items containing nonstatic expressions, except that + an implementation should support a representation item + for a given entity if each nonstatic expression in the + representation item is a name that statically denotes + a constant declared before the entity." + +In practice this is applicable only to address clauses, since this is the +only case in which a non-static expression is permitted by the syntax. As +the AARM notes in sections 13.1 (22.a-22.h): + + 22.a Reason: This is to avoid the following sort of thing: + + 22.b X : Integer := F(...); + Y : Address := G(...); + for X'Address use Y; + + 22.c In the above, we have to evaluate the + initialization expression for X before we + know where to put the result. This seems + like an unreasonable implementation burden. + + 22.d The above code should instead be written + like this: + + 22.e Y : constant Address := G(...); + X : Integer := F(...); + for X'Address use Y; + + 22.f This allows the expression 'Y' to be safely + evaluated before X is created. + + 22.g The constant could be a formal parameter of mode in. + + 22.h An implementation can support other nonstatic + expressions if it wants to. Expressions of type + Address are hardly ever static, but their value + might be known at compile time anyway in many + cases. + +GNAT does indeed permit many additional cases of non-static expressions. In +particular, if the type involved is elementary there are no restrictions +(since in this case, holding a temporary copy of the initialization value, +if one is present, is inexpensive). In addition, if there is no implicit or +explicit initialization, then there are no restrictions. GNAT will reject +only the case where all three of these conditions hold: + +* + The type of the item is non-elementary (e.g., a record or array). + +* + There is explicit or implicit initialization required for the object. + Note that access values are always implicitly initialized. + +* + The address value is non-static. Here GNAT is more permissive than the + RM, and allows the address value to be the address of a previously declared + stand-alone variable, as long as it does not itself have an address clause. + + :: + + Anchor : Some_Initialized_Type; + Overlay : Some_Initialized_Type; + for Overlay'Address use Anchor'Address; + + However, the prefix of the address clause cannot be an array component, or + a component of a discriminated record. + +As noted above in section 22.h, address values are typically non-static. In +particular the To_Address function, even if applied to a literal value, is +a non-static function call. To avoid this minor annoyance, GNAT provides +the implementation defined attribute 'To_Address. The following two +expressions have identical values: + +.. index:: Attribute +.. index:: To_Address + +.. code-block:: ada + + To_Address (16#1234_0000#) + System'To_Address (16#1234_0000#); + +except that the second form is considered to be a static expression, and +thus when used as an address clause value is always permitted. + +Additionally, GNAT treats as static an address clause that is an +unchecked_conversion of a static integer value. This simplifies the porting +of legacy code, and provides a portable equivalent to the GNAT attribute +`To_Address`. + +Another issue with address clauses is the interaction with alignment +requirements. When an address clause is given for an object, the address +value must be consistent with the alignment of the object (which is usually +the same as the alignment of the type of the object). If an address clause +is given that specifies an inappropriately aligned address value, then the +program execution is erroneous. + +Since this source of erroneous behavior can have unfortunate effects, GNAT +checks (at compile time if possible, generating a warning, or at execution +time with a run-time check) that the alignment is appropriate. If the +run-time check fails, then `Program_Error` is raised. This run-time +check is suppressed if range checks are suppressed, or if the special GNAT +check Alignment_Check is suppressed, or if +`pragma Restrictions (No_Elaboration_Code)` is in effect. + +Finally, GNAT does not permit overlaying of objects of controlled types or +composite types containing a controlled component. In most cases, the compiler +can detect an attempt at such overlays and will generate a warning at compile +time and a Program_Error exception at run time. + +.. index:: Export + +An address clause cannot be given for an exported object. More +understandably the real restriction is that objects with an address +clause cannot be exported. This is because such variables are not +defined by the Ada program, so there is no external object to export. + +.. index:: Import + +It is permissible to give an address clause and a pragma Import for the +same object. In this case, the variable is not really defined by the +Ada program, so there is no external symbol to be linked. The link name +and the external name are ignored in this case. The reason that we allow this +combination is that it provides a useful idiom to avoid unwanted +initializations on objects with address clauses. + +When an address clause is given for an object that has implicit or +explicit initialization, then by default initialization takes place. This +means that the effect of the object declaration is to overwrite the +memory at the specified address. This is almost always not what the +programmer wants, so GNAT will output a warning: + +:: + + with System; + package G is + type R is record + M : Integer := 0; + end record; + + Ext : R; + for Ext'Address use System'To_Address (16#1234_1234#); + | + >>> warning: implicit initialization of "Ext" may + modify overlaid storage + >>> warning: use pragma Import for "Ext" to suppress + initialization (RM B(24)) + + end G; + +As indicated by the warning message, the solution is to use a (dummy) pragma +Import to suppress this initialization. The pragma tell the compiler that the +object is declared and initialized elsewhere. The following package compiles +without warnings (and the initialization is suppressed): + +.. code-block:: ada + + with System; + package G is + type R is record + M : Integer := 0; + end record; + + Ext : R; + for Ext'Address use System'To_Address (16#1234_1234#); + pragma Import (Ada, Ext); + end G; + + +A final issue with address clauses involves their use for overlaying +variables, as in the following example: + +.. index:: Overlaying of objects + +.. code-block:: ada + + A : Integer; + B : Integer; + for B'Address use A'Address; + + +or alternatively, using the form recommended by the RM: + +.. code-block:: ada + + A : Integer; + Addr : constant Address := A'Address; + B : Integer; + for B'Address use Addr; + + +In both of these cases, `A` +and `B` become aliased to one another via the +address clause. This use of address clauses to overlay +variables, achieving an effect similar to unchecked +conversion was erroneous in Ada 83, but in Ada 95 and Ada 2005 +the effect is implementation defined. Furthermore, the +Ada RM specifically recommends that in a situation +like this, `B` should be subject to the following +implementation advice (RM 13.3(19)): + + "19 If the Address of an object is specified, or it is imported + or exported, then the implementation should not perform + optimizations based on assumptions of no aliases." + +GNAT follows this recommendation, and goes further by also applying +this recommendation to the overlaid variable (`A` +in the above example) in this case. This means that the overlay +works "as expected", in that a modification to one of the variables +will affect the value of the other. + +Note that when address clause overlays are used in this way, there is an +issue of unintentional initialization, as shown by this example: + +:: + + package Overwrite_Record is + type R is record + A : Character := 'C'; + B : Character := 'A'; + end record; + X : Short_Integer := 3; + Y : R; + for Y'Address use X'Address; + | + >>> warning: default initialization of "Y" may + modify "X", use pragma Import for "Y" to + suppress initialization (RM B.1(24)) + + end Overwrite_Record; + +Here the default initialization of `Y` will clobber the value +of `X`, which justifies the warning. The warning notes that +this effect can be eliminated by adding a `pragma Import` +which suppresses the initialization: + +.. code-block:: ada + + package Overwrite_Record is + type R is record + A : Character := 'C'; + B : Character := 'A'; + end record; + X : Short_Integer := 3; + Y : R; + for Y'Address use X'Address; + pragma Import (Ada, Y); + end Overwrite_Record; + + +Note that the use of `pragma Initialize_Scalars` may cause variables to +be initialized when they would not otherwise have been in the absence +of the use of this pragma. This may cause an overlay to have this +unintended clobbering effect. The compiler avoids this for scalar +types, but not for composite objects (where in general the effect +of `Initialize_Scalars` is part of the initialization routine +for the composite object: + +:: + + pragma Initialize_Scalars; + with Ada.Text_IO; use Ada.Text_IO; + procedure Overwrite_Array is + type Arr is array (1 .. 5) of Integer; + X : Arr := (others => 1); + A : Arr; + for A'Address use X'Address; + | + >>> warning: default initialization of "A" may + modify "X", use pragma Import for "A" to + suppress initialization (RM B.1(24)) + + begin + if X /= Arr'(others => 1) then + Put_Line ("X was clobbered"); + else + Put_Line ("X was not clobbered"); + end if; + end Overwrite_Array; + +The above program generates the warning as shown, and at execution +time, prints `X was clobbered`. If the `pragma Import` is +added as suggested: + +.. code-block:: ada + + pragma Initialize_Scalars; + with Ada.Text_IO; use Ada.Text_IO; + procedure Overwrite_Array is + type Arr is array (1 .. 5) of Integer; + X : Arr := (others => 1); + A : Arr; + for A'Address use X'Address; + pragma Import (Ada, A); + begin + if X /= Arr'(others => 1) then + Put_Line ("X was clobbered"); + else + Put_Line ("X was not clobbered"); + end if; + end Overwrite_Array; + +then the program compiles without the warning and when run will generate +the output `X was not clobbered`. + + +.. _Use_of_Address_Clauses_for_Memory-Mapped_I/O: + +Use of Address Clauses for Memory-Mapped I/O +============================================ + +.. index:: Memory-mapped I/O + +A common pattern is to use an address clause to map an atomic variable to +a location in memory that corresponds to a memory-mapped I/O operation or +operations, for example: + +.. code-block:: ada + + type Mem_Word is record + A,B,C,D : Byte; + end record; + pragma Atomic (Mem_Word); + for Mem_Word_Size use 32; + + Mem : Mem_Word; + for Mem'Address use some-address; + ... + Temp := Mem; + Temp.A := 32; + Mem := Temp; + +For a full access (reference or modification) of the variable (Mem) in +this case, as in the above examples, GNAT guarantees that the entire atomic +word will be accessed. It is not clear whether the RM requires this. For +example in the above, can the compiler reference only the Mem.A field as +an optimization? Whatever the answer to this question is, GNAT makes the +guarantee that for such a reference, the entire word is read or written. + +A problem arises with a component access such as: + +.. code-block:: ada + + Mem.A := 32; + +Note that the component A is not declared as atomic. This means that it is +not clear what this assignment means. It could correspond to full word read +and write as given in the first example, or on architectures that supported +such an operation it might be a single byte store instruction. The RM does +not have anything to say in this situation, and GNAT does not make any +guarantee. The code generated may vary from target to target. GNAT will issue +a warning in such a case: + +:: + + Mem.A := 32; + | + >>> warning: access to non-atomic component of atomic array, + may cause unexpected accesses to atomic object + +It is best to be explicit in this situation, by either declaring the +components to be atomic if you want the byte store, or explicitly writing +the full word access sequence if that is what the hardware requires. + + +.. _Effect_of_Convention_on_Representation: + +Effect of Convention on Representation +====================================== + +.. index:: Convention, effect on representation + +Normally the specification of a foreign language convention for a type or +an object has no effect on the chosen representation. In particular, the +representation chosen for data in GNAT generally meets the standard system +conventions, and for example records are laid out in a manner that is +consistent with C. This means that specifying convention C (for example) +has no effect. + +There are four exceptions to this general rule: + +* *Convention Fortran and array subtypes*. + + If pragma Convention Fortran is specified for an array subtype, then in + accordance with the implementation advice in section 3.6.2(11) of the + Ada Reference Manual, the array will be stored in a Fortran-compatible + column-major manner, instead of the normal default row-major order. + +* *Convention C and enumeration types* + + GNAT normally stores enumeration types in 8, 16, or 32 bits as required + to accommodate all values of the type. For example, for the enumeration + type declared by: + + :: + + type Color is (Red, Green, Blue); + + 8 bits is sufficient to store all values of the type, so by default, objects + of type `Color` will be represented using 8 bits. However, normal C + convention is to use 32 bits for all enum values in C, since enum values + are essentially of type int. If pragma `Convention C` is specified for an + Ada enumeration type, then the size is modified as necessary (usually to + 32 bits) to be consistent with the C convention for enum values. + + Note that this treatment applies only to types. If Convention C is given for + an enumeration object, where the enumeration type is not Convention C, then + Object_Size bits are allocated. For example, for a normal enumeration type, + with less than 256 elements, only 8 bits will be allocated for the object. + Since this may be a surprise in terms of what C expects, GNAT will issue a + warning in this situation. The warning can be suppressed by giving an explicit + size clause specifying the desired size. + +* *Convention C/Fortran and Boolean types* + + In C, the usual convention for boolean values, that is values used for + conditions, is that zero represents false, and nonzero values represent + true. In Ada, the normal convention is that two specific values, typically + 0/1, are used to represent false/true respectively. + + Fortran has a similar convention for `LOGICAL` values (any nonzero + value represents true). + + To accommodate the Fortran and C conventions, if a pragma Convention specifies + C or Fortran convention for a derived Boolean, as in the following example: + + :: + + type C_Switch is new Boolean; + pragma Convention (C, C_Switch); + + + then the GNAT generated code will treat any nonzero value as true. For truth + values generated by GNAT, the conventional value 1 will be used for True, but + when one of these values is read, any nonzero value is treated as True. + + +.. _Conventions_and_Anonymous_Access_Types: + +Conventions and Anonymous Access Types +====================================== + +.. index:: Anonymous access types + +.. index:: Convention for anonymous access types + +The RM is not entirely clear on convention handling in a number of cases, +and in particular, it is not clear on the convention to be given to +anonymous access types in general, and in particular what is to be +done for the case of anonymous access-to-subprogram. + +In GNAT, we decide that if an explicit Convention is applied +to an object or component, and its type is such an anonymous type, +then the convention will apply to this anonymous type as well. This +seems to make sense since it is anomolous in any case to have a +different convention for an object and its type, and there is clearly +no way to explicitly specify a convention for an anonymous type, since +it doesn't have a name to specify! + +Furthermore, we decide that if a convention is applied to a record type, +then this convention is inherited by any of its components that are of an +anonymous access type which do not have an explicitly specified convention. + +The following program shows these conventions in action: + +:: + + package ConvComp is + type Foo is range 1 .. 10; + type T1 is record + A : access function (X : Foo) return Integer; + B : Integer; + end record; + pragma Convention (C, T1); + + type T2 is record + A : access function (X : Foo) return Integer; + pragma Convention (C, A); + B : Integer; + end record; + pragma Convention (COBOL, T2); + + type T3 is record + A : access function (X : Foo) return Integer; + pragma Convention (COBOL, A); + B : Integer; + end record; + pragma Convention (C, T3); + + type T4 is record + A : access function (X : Foo) return Integer; + B : Integer; + end record; + pragma Convention (COBOL, T4); + + function F (X : Foo) return Integer; + pragma Convention (C, F); + + function F (X : Foo) return Integer is (13); + + TV1 : T1 := (F'Access, 12); -- OK + TV2 : T2 := (F'Access, 13); -- OK + + TV3 : T3 := (F'Access, 13); -- ERROR + | + >>> subprogram "F" has wrong convention + >>> does not match access to subprogram declared at line 17 + 38. TV4 : T4 := (F'Access, 13); -- ERROR + | + >>> subprogram "F" has wrong convention + >>> does not match access to subprogram declared at line 24 + 39. end ConvComp; + + +.. _Determining_the_Representations_chosen_by_GNAT: + +Determining the Representations chosen by GNAT +============================================== + +.. index:: Representation, determination of + +.. index:: -gnatR (gcc) + +Although the descriptions in this section are intended to be complete, it is +often easier to simply experiment to see what GNAT accepts and what the +effect is on the layout of types and objects. + +As required by the Ada RM, if a representation clause is not accepted, then +it must be rejected as illegal by the compiler. However, when a +representation clause or pragma is accepted, there can still be questions +of what the compiler actually does. For example, if a partial record +representation clause specifies the location of some components and not +others, then where are the non-specified components placed? Or if pragma +`Pack` is used on a record, then exactly where are the resulting +fields placed? The section on pragma `Pack` in this chapter can be +used to answer the second question, but it is often easier to just see +what the compiler does. + +For this purpose, GNAT provides the option *-gnatR*. If you compile +with this option, then the compiler will output information on the actual +representations chosen, in a format similar to source representation +clauses. For example, if we compile the package: + +.. code-block:: ada + + package q is + type r (x : boolean) is tagged record + case x is + when True => S : String (1 .. 100); + when False => null; + end case; + end record; + + type r2 is new r (false) with record + y2 : integer; + end record; + + for r2 use record + y2 at 16 range 0 .. 31; + end record; + + type x is record + y : character; + end record; + + type x1 is array (1 .. 10) of x; + for x1'component_size use 11; + + type ia is access integer; + + type Rb1 is array (1 .. 13) of Boolean; + pragma Pack (rb1); + + type Rb2 is array (1 .. 65) of Boolean; + pragma Pack (rb2); + + type x2 is record + l1 : Boolean; + l2 : Duration; + l3 : Float; + l4 : Boolean; + l5 : Rb1; + l6 : Rb2; + end record; + pragma Pack (x2); + end q; + +using the switch *-gnatR* we obtain the following output: + +.. code-block:: ada + + Representation information for unit q + ------------------------------------- + + for r'Size use ??; + for r'Alignment use 4; + for r use record + x at 4 range 0 .. 7; + _tag at 0 range 0 .. 31; + s at 5 range 0 .. 799; + end record; + + for r2'Size use 160; + for r2'Alignment use 4; + for r2 use record + x at 4 range 0 .. 7; + _tag at 0 range 0 .. 31; + _parent at 0 range 0 .. 63; + y2 at 16 range 0 .. 31; + end record; + + for x'Size use 8; + for x'Alignment use 1; + for x use record + y at 0 range 0 .. 7; + end record; + + for x1'Size use 112; + for x1'Alignment use 1; + for x1'Component_Size use 11; + + for rb1'Size use 13; + for rb1'Alignment use 2; + for rb1'Component_Size use 1; + + for rb2'Size use 72; + for rb2'Alignment use 1; + for rb2'Component_Size use 1; + + for x2'Size use 224; + for x2'Alignment use 4; + for x2 use record + l1 at 0 range 0 .. 0; + l2 at 0 range 1 .. 64; + l3 at 12 range 0 .. 31; + l4 at 16 range 0 .. 0; + l5 at 16 range 1 .. 13; + l6 at 18 range 0 .. 71; + end record; + +The Size values are actually the Object_Size, i.e., the default size that +will be allocated for objects of the type. +The ``??`` size for type r indicates that we have a variant record, and the +actual size of objects will depend on the discriminant value. + +The Alignment values show the actual alignment chosen by the compiler +for each record or array type. + +The record representation clause for type r shows where all fields +are placed, including the compiler generated tag field (whose location +cannot be controlled by the programmer). + +The record representation clause for the type extension r2 shows all the +fields present, including the parent field, which is a copy of the fields +of the parent type of r2, i.e., r1. + +The component size and size clauses for types rb1 and rb2 show +the exact effect of pragma `Pack` on these arrays, and the record +representation clause for type x2 shows how pragma `Pack` affects +this record type. + +In some cases, it may be useful to cut and paste the representation clauses +generated by the compiler into the original source to fix and guarantee +the actual representation to be used. diff --git a/gcc/ada/doc/gnat_rm/specialized_needs_annexes.rst b/gcc/ada/doc/gnat_rm/specialized_needs_annexes.rst new file mode 100644 index 00000000000..15b4a9483d0 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/specialized_needs_annexes.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst b/gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst new file mode 100644 index 00000000000..c5cabb98af4 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst @@ -0,0 +1,1057 @@ +.. _Standard_and_Implementation_Defined_Restrictions: + +************************************************ +Standard and Implementation Defined Restrictions +************************************************ + +All Ada Reference Manual-defined Restriction identifiers are implemented: + +* language-defined restrictions (see 13.12.1) +* tasking restrictions (see D.7) +* high integrity restrictions (see H.4) + +GNAT implements additional restriction identifiers. All restrictions, whether +language defined or GNAT-specific, are listed in the following. + +.. _Partition-Wide_Restrictions: + +Partition-Wide Restrictions +=========================== + +There are two separate lists of restriction identifiers. The first +set requires consistency throughout a partition (in other words, if the +restriction identifier is used for any compilation unit in the partition, +then all compilation units in the partition must obey the restriction). + +Immediate_Reclamation +--------------------- +.. index:: Immediate_Reclamation + +[RM H.4] This restriction ensures that, except for storage occupied by +objects created by allocators and not deallocated via unchecked +deallocation, any storage reserved at run time for an object is +immediately reclaimed when the object no longer exists. + +Max_Asynchronous_Select_Nesting +------------------------------- +.. index:: Max_Asynchronous_Select_Nesting + +[RM D.7] Specifies the maximum dynamic nesting level of asynchronous +selects. Violations of this restriction with a value of zero are +detected at compile time. Violations of this restriction with values +other than zero cause Storage_Error to be raised. + +Max_Entry_Queue_Length +---------------------- +.. index:: Max_Entry_Queue_Length + +[RM D.7] This restriction is a declaration that any protected entry compiled in +the scope of the restriction has at most the specified number of +tasks waiting on the entry at any one time, and so no queue is required. +Note that this restriction is checked at run time. Violation of this +restriction results in the raising of Program_Error exception at the point of +the call. + +.. index:: Max_Entry_Queue_Depth + +The restriction `Max_Entry_Queue_Depth` is recognized as a +synonym for `Max_Entry_Queue_Length`. This is retained for historical +compatibility purposes (and a warning will be generated for its use if +warnings on obsolescent features are activated). + +Max_Protected_Entries +--------------------- +.. index:: Max_Protected_Entries + +[RM D.7] Specifies the maximum number of entries per protected type. The +bounds of every entry family of a protected unit shall be static, or shall be +defined by a discriminant of a subtype whose corresponding bound is static. + +Max_Select_Alternatives +----------------------- +.. index:: Max_Select_Alternatives + +[RM D.7] Specifies the maximum number of alternatives in a selective accept. + +Max_Storage_At_Blocking +----------------------- +.. index:: Max_Storage_At_Blocking + +[RM D.7] Specifies the maximum portion (in storage elements) of a task's +Storage_Size that can be retained by a blocked task. A violation of this +restriction causes Storage_Error to be raised. + +Max_Task_Entries +---------------- +.. index:: Max_Task_Entries + +[RM D.7] Specifies the maximum number of entries +per task. The bounds of every entry family +of a task unit shall be static, or shall be +defined by a discriminant of a subtype whose +corresponding bound is static. + +Max_Tasks +--------- +.. index:: Max_Tasks + +[RM D.7] Specifies the maximum number of task that may be created, not +counting the creation of the environment task. Violations of this +restriction with a value of zero are detected at compile +time. Violations of this restriction with values other than zero cause +Storage_Error to be raised. + +No_Abort_Statements +------------------- +.. index:: No_Abort_Statements + +[RM D.7] There are no abort_statements, and there are +no calls to Task_Identification.Abort_Task. + +No_Access_Parameter_Allocators +------------------------------ +.. index:: No_Access_Parameter_Allocators + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of an allocator as the actual parameter to an access +parameter. + +No_Access_Subprograms +--------------------- +.. index:: No_Access_Subprograms + +[RM H.4] This restriction ensures at compile time that there are no +declarations of access-to-subprogram types. + +No_Allocators +------------- +.. index:: No_Allocators + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of an allocator. + +No_Anonymous_Allocators +----------------------- +.. index:: No_Anonymous_Allocators + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of an allocator of anonymous access type. + +No_Calendar +----------- +.. index:: No_Calendar + +[GNAT] This restriction ensures at compile time that there is no implicit or +explicit dependence on the package `Ada.Calendar`. + +No_Coextensions +--------------- +.. index:: No_Coextensions + +[RM H.4] This restriction ensures at compile time that there are no +coextensions. See 3.10.2. + +No_Default_Initialization +------------------------- +.. index:: No_Default_Initialization + +[GNAT] This restriction prohibits any instance of default initialization +of variables. The binder implements a consistency rule which prevents +any unit compiled without the restriction from with'ing a unit with the +restriction (this allows the generation of initialization procedures to +be skipped, since you can be sure that no call is ever generated to an +initialization procedure in a unit with the restriction active). If used +in conjunction with Initialize_Scalars or Normalize_Scalars, the effect +is to prohibit all cases of variables declared without a specific +initializer (including the case of OUT scalar parameters). + +No_Delay +-------- +.. index:: No_Delay + +[RM H.4] This restriction ensures at compile time that there are no +delay statements and no dependences on package Calendar. + +No_Dependence +------------- +.. index:: No_Dependence + +[RM 13.12.1] This restriction checks at compile time that there are no +dependence on a library unit. + +No_Direct_Boolean_Operators +--------------------------- +.. index:: No_Direct_Boolean_Operators + +[GNAT] This restriction ensures that no logical operators (and/or/xor) +are used on operands of type Boolean (or any type derived from Boolean). +This is intended for use in safety critical programs where the certification +protocol requires the use of short-circuit (and then, or else) forms for all +composite boolean operations. + +No_Dispatch +----------- +.. index:: No_Dispatch + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of `T'Class`, for any (tagged) subtype `T`. + +No_Dispatching_Calls +-------------------- +.. index:: No_Dispatching_Calls + +[GNAT] This restriction ensures at compile time that the code generated by the +compiler involves no dispatching calls. The use of this restriction allows the +safe use of record extensions, classwide membership tests and other classwide +features not involving implicit dispatching. This restriction ensures that +the code contains no indirect calls through a dispatching mechanism. Note that +this includes internally-generated calls created by the compiler, for example +in the implementation of class-wide objects assignments. The +membership test is allowed in the presence of this restriction, because its +implementation requires no dispatching. +This restriction is comparable to the official Ada restriction +`No_Dispatch` except that it is a bit less restrictive in that it allows +all classwide constructs that do not imply dispatching. +The following example indicates constructs that violate this restriction. + + +.. code-block:: ada + + package Pkg is + type T is tagged record + Data : Natural; + end record; + procedure P (X : T); + + type DT is new T with record + More_Data : Natural; + end record; + procedure Q (X : DT); + end Pkg; + + with Pkg; use Pkg; + procedure Example is + procedure Test (O : T'Class) is + N : Natural := O'Size;-- Error: Dispatching call + C : T'Class := O; -- Error: implicit Dispatching Call + begin + if O in DT'Class then -- OK : Membership test + Q (DT (O)); -- OK : Type conversion plus direct call + else + P (O); -- Error: Dispatching call + end if; + end Test; + + Obj : DT; + begin + P (Obj); -- OK : Direct call + P (T (Obj)); -- OK : Type conversion plus direct call + P (T'Class (Obj)); -- Error: Dispatching call + + Test (Obj); -- OK : Type conversion + + if Obj in T'Class then -- OK : Membership test + null; + end if; + end Example; + + +No_Dynamic_Attachment +--------------------- +.. index:: No_Dynamic_Attachment + +[RM D.7] This restriction ensures that there is no call to any of the +operations defined in package Ada.Interrupts +(Is_Reserved, Is_Attached, Current_Handler, Attach_Handler, Exchange_Handler, +Detach_Handler, and Reference). + +.. index:: No_Dynamic_Interrupts + +The restriction `No_Dynamic_Interrupts` is recognized as a +synonym for `No_Dynamic_Attachment`. This is retained for historical +compatibility purposes (and a warning will be generated for its use if +warnings on obsolescent features are activated). + +No_Dynamic_Priorities +--------------------- +.. index:: No_Dynamic_Priorities + +[RM D.7] There are no semantic dependencies on the package Dynamic_Priorities. + +No_Entry_Calls_In_Elaboration_Code +---------------------------------- +.. index:: No_Entry_Calls_In_Elaboration_Code + +[GNAT] This restriction ensures at compile time that no task or protected entry +calls are made during elaboration code. As a result of the use of this +restriction, the compiler can assume that no code past an accept statement +in a task can be executed at elaboration time. + +No_Enumeration_Maps +------------------- +.. index:: No_Enumeration_Maps + +[GNAT] This restriction ensures at compile time that no operations requiring +enumeration maps are used (that is Image and Value attributes applied +to enumeration types). + +No_Exception_Handlers +--------------------- +.. index:: No_Exception_Handlers + +[GNAT] This restriction ensures at compile time that there are no explicit +exception handlers. It also indicates that no exception propagation will +be provided. In this mode, exceptions may be raised but will result in +an immediate call to the last chance handler, a routine that the user +must define with the following profile: + + +.. code-block:: ada + + procedure Last_Chance_Handler + (Source_Location : System.Address; Line : Integer); + pragma Export (C, Last_Chance_Handler, + "__gnat_last_chance_handler"); + + +The parameter is a C null-terminated string representing a message to be +associated with the exception (typically the source location of the raise +statement generated by the compiler). The Line parameter when nonzero +represents the line number in the source program where the raise occurs. + +No_Exception_Propagation +------------------------ +.. index:: No_Exception_Propagation + +[GNAT] This restriction guarantees that exceptions are never propagated +to an outer subprogram scope. The only case in which an exception may +be raised is when the handler is statically in the same subprogram, so +that the effect of a raise is essentially like a goto statement. Any +other raise statement (implicit or explicit) will be considered +unhandled. Exception handlers are allowed, but may not contain an +exception occurrence identifier (exception choice). In addition, use of +the package GNAT.Current_Exception is not permitted, and reraise +statements (raise with no operand) are not permitted. + +No_Exception_Registration +------------------------- +.. index:: No_Exception_Registration + +[GNAT] This restriction ensures at compile time that no stream operations for +types Exception_Id or Exception_Occurrence are used. This also makes it +impossible to pass exceptions to or from a partition with this restriction +in a distributed environment. If this restriction is active, the generated +code is simplified by omitting the otherwise-required global registration +of exceptions when they are declared. + +No_Exceptions +------------- +.. index:: No_Exceptions + +[RM H.4] This restriction ensures at compile time that there are no +raise statements and no exception handlers. + +No_Finalization +--------------- +.. index:: No_Finalization + +[GNAT] This restriction disables the language features described in +chapter 7.6 of the Ada 2005 RM as well as all form of code generation +performed by the compiler to support these features. The following types +are no longer considered controlled when this restriction is in effect: + +* + `Ada.Finalization.Controlled` +* + `Ada.Finalization.Limited_Controlled` +* + Derivations from `Controlled` or `Limited_Controlled` +* + Class-wide types +* + Protected types +* + Task types +* + Array and record types with controlled components + +The compiler no longer generates code to initialize, finalize or adjust an +object or a nested component, either declared on the stack or on the heap. The +deallocation of a controlled object no longer finalizes its contents. + +No_Fixed_Point +-------------- +.. index:: No_Fixed_Point + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of fixed point types and operations. + +No_Floating_Point +----------------- +.. index:: No_Floating_Point + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of floating point types and operations. + +No_Implicit_Conditionals +------------------------ +.. index:: No_Implicit_Conditionals + +[GNAT] This restriction ensures that the generated code does not contain any +implicit conditionals, either by modifying the generated code where possible, +or by rejecting any construct that would otherwise generate an implicit +conditional. Note that this check does not include run time constraint +checks, which on some targets may generate implicit conditionals as +well. To control the latter, constraint checks can be suppressed in the +normal manner. Constructs generating implicit conditionals include comparisons +of composite objects and the Max/Min attributes. + +No_Implicit_Dynamic_Code +------------------------ +.. index:: No_Implicit_Dynamic_Code +.. index:: trampoline + +[GNAT] This restriction prevents the compiler from building 'trampolines'. +This is a structure that is built on the stack and contains dynamic +code to be executed at run time. On some targets, a trampoline is +built for the following features: `Access`, +`Unrestricted_Access`, or `Address` of a nested subprogram; +nested task bodies; primitive operations of nested tagged types. +Trampolines do not work on machines that prevent execution of stack +data. For example, on windows systems, enabling DEP (data execution +protection) will cause trampolines to raise an exception. +Trampolines are also quite slow at run time. + +On many targets, trampolines have been largely eliminated. Look at the +version of system.ads for your target --- if it has +Always_Compatible_Rep equal to False, then trampolines are largely +eliminated. In particular, a trampoline is built for the following +features: `Address` of a nested subprogram; +`Access` or `Unrestricted_Access` of a nested subprogram, +but only if pragma Favor_Top_Level applies, or the access type has a +foreign-language convention; primitive operations of nested tagged +types. + +No_Implicit_Heap_Allocations +---------------------------- +.. index:: No_Implicit_Heap_Allocations + +[RM D.7] No constructs are allowed to cause implicit heap allocation. + +No_Implicit_Loops +----------------- +.. index:: No_Implicit_Loops + +[GNAT] This restriction ensures that the generated code does not contain any +implicit `for` loops, either by modifying +the generated code where possible, +or by rejecting any construct that would otherwise generate an implicit +`for` loop. If this restriction is active, it is possible to build +large array aggregates with all static components without generating an +intermediate temporary, and without generating a loop to initialize individual +components. Otherwise, a loop is created for arrays larger than about 5000 +scalar components. + +No_Initialize_Scalars +--------------------- +.. index:: No_Initialize_Scalars + +[GNAT] This restriction ensures that no unit in the partition is compiled with +pragma Initialize_Scalars. This allows the generation of more efficient +code, and in particular eliminates dummy null initialization routines that +are otherwise generated for some record and array types. + +No_IO +----- +.. index:: No_IO + +[RM H.4] This restriction ensures at compile time that there are no +dependences on any of the library units Sequential_IO, Direct_IO, +Text_IO, Wide_Text_IO, Wide_Wide_Text_IO, or Stream_IO. + +No_Local_Allocators +------------------- +.. index:: No_Local_Allocators + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of an allocator in subprograms, generic subprograms, tasks, +and entry bodies. + +No_Local_Protected_Objects +-------------------------- +.. index:: No_Local_Protected_Objects + +[RM D.7] This restriction ensures at compile time that protected objects are +only declared at the library level. + +No_Local_Timing_Events +---------------------- +.. index:: No_Local_Timing_Events + +[RM D.7] All objects of type Ada.Timing_Events.Timing_Event are +declared at the library level. + +No_Long_Long_Integers +--------------------- +.. index:: No_Long_Long_Integers + +[GNAT] This partition-wide restriction forbids any explicit reference to +type Standard.Long_Long_Integer, and also forbids declaring range types whose +implicit base type is Long_Long_Integer, and modular types whose size exceeds +Long_Integer'Size. + +No_Multiple_Elaboration +----------------------- +.. index:: No_Multiple_Elaboration + +[GNAT] Normally each package contains a 16-bit counter used to check for access +before elaboration, and to control multiple elaboration attempts. +This counter is eliminated for units compiled with the static model +of elaboration if restriction `No_Elaboration_Code` +is active but because of +the need to check for multiple elaboration in the general case, these +counters cannot be eliminated if elaboration code may be present. The +restriction `No_Multiple_Elaboration` +allows suppression of these counters +in static elaboration units even if they do have elaboration code. If this +restriction is used, then the situations in which multiple elaboration is +possible, including non-Ada main programs, and Stand Alone libraries, are not +permitted, and will be diagnosed by the binder. + +No_Nested_Finalization +---------------------- +.. index:: No_Nested_Finalization + +[RM D.7] All objects requiring finalization are declared at the library level. + +No_Protected_Type_Allocators +---------------------------- +.. index:: No_Protected_Type_Allocators + +[RM D.7] This restriction ensures at compile time that there are no allocator +expressions that attempt to allocate protected objects. + +No_Protected_Types +------------------ +.. index:: No_Protected_Types + +[RM H.4] This restriction ensures at compile time that there are no +declarations of protected types or protected objects. + +No_Recursion +------------ +.. index:: No_Recursion + +[RM H.4] A program execution is erroneous if a subprogram is invoked as +part of its execution. + +No_Reentrancy +------------- +.. index:: No_Reentrancy + +[RM H.4] A program execution is erroneous if a subprogram is executed by +two tasks at the same time. + +No_Relative_Delay +----------------- +.. index:: No_Relative_Delay + +[RM D.7] This restriction ensures at compile time that there are no delay +relative statements and prevents expressions such as `delay 1.23;` from +appearing in source code. + +No_Requeue_Statements +--------------------- +.. index:: No_Requeue_Statements + +[RM D.7] This restriction ensures at compile time that no requeue statements +are permitted and prevents keyword `requeue` from being used in source +code. + +.. index:: No_Requeue + +The restriction `No_Requeue` is recognized as a +synonym for `No_Requeue_Statements`. This is retained for historical +compatibility purposes (and a warning will be generated for its use if +warnings on oNobsolescent features are activated). + +No_Secondary_Stack +------------------ +.. index:: No_Secondary_Stack + +[GNAT] This restriction ensures at compile time that the generated code +does not contain any reference to the secondary stack. The secondary +stack is used to implement functions returning unconstrained objects +(arrays or records) on some targets. + +No_Select_Statements +-------------------- +.. index:: No_Select_Statements + +[RM D.7] This restriction ensures at compile time no select statements of any +kind are permitted, that is the keyword `select` may not appear. + +No_Specific_Termination_Handlers +-------------------------------- +.. index:: No_Specific_Termination_Handlers + +[RM D.7] There are no calls to Ada.Task_Termination.Set_Specific_Handler +or to Ada.Task_Termination.Specific_Handler. + +No_Specification_of_Aspect +-------------------------- +.. index:: No_Specification_of_Aspect + +[RM 13.12.1] This restriction checks at compile time that no aspect +specification, attribute definition clause, or pragma is given for a +given aspect. + +No_Standard_Allocators_After_Elaboration +---------------------------------------- +.. index:: No_Standard_Allocators_After_Elaboration + +[RM D.7] Specifies that an allocator using a standard storage pool +should never be evaluated at run time after the elaboration of the +library items of the partition has completed. Otherwise, Storage_Error +is raised. + +No_Standard_Storage_Pools +------------------------- +.. index:: No_Standard_Storage_Pools + +[GNAT] This restriction ensures at compile time that no access types +use the standard default storage pool. Any access type declared must +have an explicit Storage_Pool attribute defined specifying a +user-defined storage pool. + +No_Stream_Optimizations +----------------------- +.. index:: No_Stream_Optimizations + +[GNAT] This restriction affects the performance of stream operations on types +`String`, `Wide_String` and `Wide_Wide_String`. By default, the +compiler uses block reads and writes when manipulating `String` objects +due to their supperior performance. When this restriction is in effect, the +compiler performs all IO operations on a per-character basis. + +No_Streams +---------- +.. index:: No_Streams + +[GNAT] This restriction ensures at compile/bind time that there are no +stream objects created and no use of stream attributes. +This restriction does not forbid dependences on the package +`Ada.Streams`. So it is permissible to with +`Ada.Streams` (or another package that does so itself) +as long as no actual stream objects are created and no +stream attributes are used. + +Note that the use of restriction allows optimization of tagged types, +since they do not need to worry about dispatching stream operations. +To take maximum advantage of this space-saving optimization, any +unit declaring a tagged type should be compiled with the restriction, +though this is not required. + +No_Task_Allocators +------------------ +.. index:: No_Task_Allocators + +[RM D.7] There are no allocators for task types +or types containing task subcomponents. + +No_Task_Attributes_Package +-------------------------- +.. index:: No_Task_Attributes_Package + +[GNAT] This restriction ensures at compile time that there are no implicit or +explicit dependencies on the package `Ada.Task_Attributes`. + +.. index:: No_Task_Attributes + +The restriction `No_Task_Attributes` is recognized as a synonym +for `No_Task_Attributes_Package`. This is retained for historical +compatibility purposes (and a warning will be generated for its use if +warnings on obsolescent features are activated). + +No_Task_Hierarchy +----------------- +.. index:: No_Task_Hierarchy + +[RM D.7] All (non-environment) tasks depend +directly on the environment task of the partition. + +No_Task_Termination +------------------- +.. index:: No_Task_Termination + +[RM D.7] Tasks that terminate are erroneous. + +No_Tasking +---------- +.. index:: No_Tasking + +[GNAT] This restriction prevents the declaration of tasks or task types +throughout the partition. It is similar in effect to the use of +`Max_Tasks => 0` except that violations are caught at compile time +and cause an error message to be output either by the compiler or +binder. + +No_Terminate_Alternatives +------------------------- +.. index:: No_Terminate_Alternatives + +[RM D.7] There are no selective accepts with terminate alternatives. + +No_Unchecked_Access +------------------- +.. index:: No_Unchecked_Access + +[RM H.4] This restriction ensures at compile time that there are no +occurrences of the Unchecked_Access attribute. + +No_Use_Of_Entity +---------------- +.. index:: No_Use_Of_Entity + +[GNAT] This restriction ensures at compile time that there are no references +to the entity given in the form :: + + No_Use_Of_Entity => Name + +where ``Name`` is the fully qualified entity, for example :: + + No_Use_Of_Entity => Ada.Text_IO.Put_Line + +Simple_Barriers +--------------- +.. index:: Simple_Barriers + +[RM D.7] This restriction ensures at compile time that barriers in entry +declarations for protected types are restricted to either static boolean +expressions or references to simple boolean variables defined in the private +part of the protected type. No other form of entry barriers is permitted. + +.. index:: Boolean_Entry_Barriers + +The restriction `Boolean_Entry_Barriers` is recognized as a +synonym for `Simple_Barriers`. This is retained for historical +compatibility purposes (and a warning will be generated for its use if +warnings on obsolescent features are activated). + +Static_Priorities +----------------- +.. index:: Static_Priorities + +[GNAT] This restriction ensures at compile time that all priority expressions +are static, and that there are no dependences on the package +`Ada.Dynamic_Priorities`. + +Static_Storage_Size +------------------- +.. index:: Static_Storage_Size + +[GNAT] This restriction ensures at compile time that any expression appearing +in a Storage_Size pragma or attribute definition clause is static. + +.. _Program_Unit_Level_Restrictions: + + +Program Unit Level Restrictions +=============================== + +The second set of restriction identifiers +does not require partition-wide consistency. +The restriction may be enforced for a single +compilation unit without any effect on any of the +other compilation units in the partition. + +No_Elaboration_Code +------------------- +.. index:: No_Elaboration_Code + +[GNAT] This restriction ensures at compile time that no elaboration code is +generated. Note that this is not the same condition as is enforced +by pragma `Preelaborate`. There are cases in which pragma +`Preelaborate` still permits code to be generated (e.g., code +to initialize a large array to all zeroes), and there are cases of units +which do not meet the requirements for pragma `Preelaborate`, +but for which no elaboration code is generated. Generally, it is +the case that preelaborable units will meet the restrictions, with +the exception of large aggregates initialized with an others_clause, +and exception declarations (which generate calls to a run-time +registry procedure). This restriction is enforced on +a unit by unit basis, it need not be obeyed consistently +throughout a partition. + +In the case of aggregates with others, if the aggregate has a dynamic +size, there is no way to eliminate the elaboration code (such dynamic +bounds would be incompatible with `Preelaborate` in any case). If +the bounds are static, then use of this restriction actually modifies +the code choice of the compiler to avoid generating a loop, and instead +generate the aggregate statically if possible, no matter how many times +the data for the others clause must be repeatedly generated. + +It is not possible to precisely document +the constructs which are compatible with this restriction, since, +unlike most other restrictions, this is not a restriction on the +source code, but a restriction on the generated object code. For +example, if the source contains a declaration: + + +.. code-block:: ada + + Val : constant Integer := X; + + +where X is not a static constant, it may be possible, depending +on complex optimization circuitry, for the compiler to figure +out the value of X at compile time, in which case this initialization +can be done by the loader, and requires no initialization code. It +is not possible to document the precise conditions under which the +optimizer can figure this out. + +Note that this the implementation of this restriction requires full +code generation. If it is used in conjunction with "semantics only" +checking, then some cases of violations may be missed. + +No_Entry_Queue +-------------- +.. index:: No_Entry_Queue + +[GNAT] This restriction is a declaration that any protected entry compiled in +the scope of the restriction has at most one task waiting on the entry +at any one time, and so no queue is required. This restriction is not +checked at compile time. A program execution is erroneous if an attempt +is made to queue a second task on such an entry. + +No_Implementation_Aspect_Specifications +--------------------------------------- +.. index:: No_Implementation_Aspect_Specifications + +[RM 13.12.1] This restriction checks at compile time that no +GNAT-defined aspects are present. With this restriction, the only +aspects that can be used are those defined in the Ada Reference Manual. + +No_Implementation_Attributes +---------------------------- +.. index:: No_Implementation_Attributes + +[RM 13.12.1] This restriction checks at compile time that no +GNAT-defined attributes are present. With this restriction, the only +attributes that can be used are those defined in the Ada Reference +Manual. + +No_Implementation_Identifiers +----------------------------- +.. index:: No_Implementation_Identifiers + +[RM 13.12.1] This restriction checks at compile time that no +implementation-defined identifiers (marked with pragma Implementation_Defined) +occur within language-defined packages. + +No_Implementation_Pragmas +------------------------- +.. index:: No_Implementation_Pragmas + +[RM 13.12.1] This restriction checks at compile time that no +GNAT-defined pragmas are present. With this restriction, the only +pragmas that can be used are those defined in the Ada Reference Manual. + +No_Implementation_Restrictions +------------------------------ +.. index:: No_Implementation_Restrictions + +[GNAT] This restriction checks at compile time that no GNAT-defined restriction +identifiers (other than `No_Implementation_Restrictions` itself) +are present. With this restriction, the only other restriction identifiers +that can be used are those defined in the Ada Reference Manual. + +No_Implementation_Units +----------------------- +.. index:: No_Implementation_Units + +[RM 13.12.1] This restriction checks at compile time that there is no +mention in the context clause of any implementation-defined descendants +of packages Ada, Interfaces, or System. + +No_Implicit_Aliasing +-------------------- +.. index:: No_Implicit_Aliasing + +[GNAT] This restriction, which is not required to be partition-wide consistent, +requires an explicit aliased keyword for an object to which 'Access, +'Unchecked_Access, or 'Address is applied, and forbids entirely the use of +the 'Unrestricted_Access attribute for objects. Note: the reason that +Unrestricted_Access is forbidden is that it would require the prefix +to be aliased, and in such cases, it can always be replaced by +the standard attribute Unchecked_Access which is preferable. + +No_Obsolescent_Features +----------------------- +.. index:: No_Obsolescent_Features + +[RM 13.12.1] This restriction checks at compile time that no obsolescent +features are used, as defined in Annex J of the Ada Reference Manual. + +No_Wide_Characters +------------------ +.. index:: No_Wide_Characters + +[GNAT] This restriction ensures at compile time that no uses of the types +`Wide_Character` or `Wide_String` or corresponding wide +wide types +appear, and that no wide or wide wide string or character literals +appear in the program (that is literals representing characters not in +type `Character`). + +SPARK_05 +-------- +.. index:: SPARK_05 + +[GNAT] This restriction checks at compile time that some constructs +forbidden in SPARK 2005 are not present. Error messages related to +SPARK restriction have the form: + + +:: + + violation of restriction "SPARK_05" at <source-location> + <error message> + + +.. index:: SPARK + +The restriction `SPARK` is recognized as a +synonym for `SPARK_05`. This is retained for historical +compatibility purposes (and an unconditional warning will be generated +for its use, advising replacement by `SPARK`). + +This is not a replacement for the semantic checks performed by the +SPARK Examiner tool, as the compiler currently only deals with code, +not SPARK 2005 annotations, and does not guarantee catching all +cases of constructs forbidden by SPARK 2005. + +Thus it may well be the case that code which passes the compiler with +the SPARK restriction is rejected by the SPARK Examiner, e.g. due to +the different visibility rules of the Examiner based on SPARK 2005 +`inherit` annotations. + +This restriction can be useful in providing an initial filter for code +developed using SPARK 2005, or in examining legacy code to see how far +it is from meeting SPARK restrictions. + +The list below summarizes the checks that are performed when this +restriction is in force: + +* No block statements +* No case statements with only an others clause +* Exit statements in loops must respect the SPARK 2005 language restrictions +* No goto statements +* Return can only appear as last statement in function +* Function must have return statement +* Loop parameter specification must include subtype mark +* Prefix of expanded name cannot be a loop statement +* Abstract subprogram not allowed +* User-defined operators not allowed +* Access type parameters not allowed +* Default expressions for parameters not allowed +* Default expressions for record fields not allowed +* No tasking constructs allowed +* Label needed at end of subprograms and packages +* No mixing of positional and named parameter association +* No access types as result type +* No unconstrained arrays as result types +* No null procedures +* Initial and later declarations must be in correct order (declaration can't come after body) +* No attributes on private types if full declaration not visible +* No package declaration within package specification +* No controlled types +* No discriminant types +* No overloading +* Selector name cannot be operator symbol (i.e. operator symbol cannot be prefixed) +* Access attribute not allowed +* Allocator not allowed +* Result of catenation must be String +* Operands of catenation must be string literal, static char or another catenation +* No conditional expressions +* No explicit dereference +* Quantified expression not allowed +* Slicing not allowed +* No exception renaming +* No generic renaming +* No object renaming +* No use clause +* Aggregates must be qualified +* Non-static choice in array aggregates not allowed +* The only view conversions which are allowed as in-out parameters are conversions of a tagged type to an ancestor type +* No mixing of positional and named association in aggregate, no multi choice +* AND, OR and XOR for arrays only allowed when operands have same static bounds +* Fixed point operands to * or / must be qualified or converted +* Comparison operators not allowed for Booleans or arrays (except strings) +* Equality not allowed for arrays with non-matching static bounds (except strings) +* Conversion / qualification not allowed for arrays with non-matching static bounds +* Subprogram declaration only allowed in package spec (unless followed by import) +* Access types not allowed +* Incomplete type declaration not allowed +* Object and subtype declarations must respect SPARK restrictions +* Digits or delta constraint not allowed +* Decimal fixed point type not allowed +* Aliasing of objects not allowed +* Modular type modulus must be power of 2 +* Base not allowed on subtype mark +* Unary operators not allowed on modular types (except not) +* Untagged record cannot be null +* No class-wide operations +* Initialization expressions must respect SPARK restrictions +* Non-static ranges not allowed except in iteration schemes +* String subtypes must have lower bound of 1 +* Subtype of Boolean cannot have constraint +* At most one tagged type or extension per package +* Interface is not allowed +* Character literal cannot be prefixed (selector name cannot be character literal) +* Record aggregate cannot contain 'others' +* Component association in record aggregate must contain a single choice +* Ancestor part cannot be a type mark +* Attributes 'Image, 'Width and 'Value not allowed +* Functions may not update globals +* Subprograms may not contain direct calls to themselves (prevents recursion within unit) +* Call to subprogram not allowed in same unit before body has been seen (prevents recursion within unit) + +The following restrictions are enforced, but note that they are actually more +strict that the latest SPARK 2005 language definition: + +* No derived types other than tagged type extensions +* Subtype of unconstrained array must have constraint + +This list summarises the main SPARK 2005 language rules that are not +currently checked by the SPARK_05 restriction: + +* SPARK annotations are treated as comments so are not checked at all +* Based real literals not allowed +* Objects cannot be initialized at declaration by calls to user-defined functions +* Objects cannot be initialized at declaration by assignments from variables +* Objects cannot be initialized at declaration by assignments from indexed/selected components +* Ranges shall not be null +* A fixed point delta expression must be a simple expression +* Restrictions on where renaming declarations may be placed +* Externals of mode 'out' cannot be referenced +* Externals of mode 'in' cannot be updated +* Loop with no iteration scheme or exits only allowed as last statement in main program or task +* Subprogram cannot have parent unit name +* SPARK 2005 inherited subprogram must be prefixed with overriding +* External variables (or functions that reference them) may not be passed as actual parameters +* Globals must be explicitly mentioned in contract +* Deferred constants cannot be completed by pragma Import +* Package initialization cannot read/write variables from other packages +* Prefix not allowed for entities that are directly visible +* Identifier declaration can't override inherited package name +* Cannot use Standard or other predefined packages as identifiers +* After renaming, cannot use the original name +* Subprograms can only be renamed to remove package prefix +* Pragma import must be immediately after entity it names +* No mutual recursion between multiple units (this can be checked with gnatcheck) + +Note that if a unit is compiled in Ada 95 mode with the SPARK restriction, +violations will be reported for constructs forbidden in SPARK 95, +instead of SPARK 2005. + diff --git a/gcc/ada/doc/gnat_rm/standard_library_routines.rst b/gcc/ada/doc/gnat_rm/standard_library_routines.rst new file mode 100644 index 00000000000..8b8d3c27987 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/standard_library_routines.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_rm/the_gnat_library.rst b/gcc/ada/doc/gnat_rm/the_gnat_library.rst new file mode 100644 index 00000000000..a5f0aa210e6 --- /dev/null +++ b/gcc/ada/doc/gnat_rm/the_gnat_library.rst @@ -0,0 +1,2218 @@ +.. _The_GNAT_Library: + +**************** +The GNAT Library +**************** + +The GNAT library contains a number of general and special purpose packages. +It represents functionality that the GNAT developers have found useful, and +which is made available to GNAT users. The packages described here are fully +supported, and upwards compatibility will be maintained in future releases, +so you can use these facilities with the confidence that the same functionality +will be available in future releases. + +The chapter here simply gives a brief summary of the facilities available. +The full documentation is found in the spec file for the package. The full +sources of these library packages, including both spec and body, are provided +with all GNAT releases. For example, to find out the full specifications of +the SPITBOL pattern matching capability, including a full tutorial and +extensive examples, look in the :file:`g-spipat.ads` file in the library. + +For each entry here, the package name (as it would appear in a `with` +clause) is given, followed by the name of the corresponding spec file in +parentheses. The packages are children in four hierarchies, `Ada`, +`Interfaces`, `System`, and `GNAT`, the latter being a +GNAT-specific hierarchy. + +Note that an application program should only use packages in one of these +four hierarchies if the package is defined in the Ada Reference Manual, +or is listed in this section of the GNAT Programmers Reference Manual. +All other units should be considered internal implementation units and +should not be directly `with`'ed by application code. The use of +a `with` statement that references one of these internal implementation +units makes an application potentially dependent on changes in versions +of GNAT, and will generate a warning message. + +.. _`Ada.Characters.Latin_9_(a-chlat9.ads)`: + +`Ada.Characters.Latin_9` (:file:`a-chlat9.ads`) +=============================================== + +.. index:: Ada.Characters.Latin_9 (a-chlat9.ads) + +.. index:: Latin_9 constants for Character + +This child of `Ada.Characters` +provides a set of definitions corresponding to those in the +RM-defined package `Ada.Characters.Latin_1` but with the +few modifications required for `Latin-9` +The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3.3(27)). + +.. _`Ada.Characters.Wide_Latin_1_(a-cwila1.ads)`: + +`Ada.Characters.Wide_Latin_1` (:file:`a-cwila1.ads`) +==================================================== + +.. index:: Ada.Characters.Wide_Latin_1 (a-cwila1.ads) + +.. index:: Latin_1 constants for Wide_Character + +This child of `Ada.Characters` +provides a set of definitions corresponding to those in the +RM-defined package `Ada.Characters.Latin_1` but with the +types of the constants being `Wide_Character` +instead of `Character`. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3.3(27)). + +.. _`Ada.Characters.Wide_Latin_9_(a-cwila1.ads)`: + +`Ada.Characters.Wide_Latin_9` (:file:`a-cwila1.ads`) +==================================================== + +.. index:: Ada.Characters.Wide_Latin_9 (a-cwila1.ads) + +.. index:: Latin_9 constants for Wide_Character + +This child of `Ada.Characters` +provides a set of definitions corresponding to those in the +GNAT defined package `Ada.Characters.Latin_9` but with the +types of the constants being `Wide_Character` +instead of `Character`. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3.3(27)). + +.. _`Ada.Characters.Wide_Wide_Latin_1_(a-chzla1.ads)`: + +`Ada.Characters.Wide_Wide_Latin_1` (:file:`a-chzla1.ads`) +========================================================= + +.. index:: Ada.Characters.Wide_Wide_Latin_1 (a-chzla1.ads) + +.. index:: Latin_1 constants for Wide_Wide_Character + +This child of `Ada.Characters` +provides a set of definitions corresponding to those in the +RM-defined package `Ada.Characters.Latin_1` but with the +types of the constants being `Wide_Wide_Character` +instead of `Character`. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3.3(27)). + +.. _`Ada.Characters.Wide_Wide_Latin_9_(a-chzla9.ads)`: + +`Ada.Characters.Wide_Wide_Latin_9` (:file:`a-chzla9.ads`) +========================================================= + +.. index:: Ada.Characters.Wide_Wide_Latin_9 (a-chzla9.ads) + +.. index:: Latin_9 constants for Wide_Wide_Character + +This child of `Ada.Characters` +provides a set of definitions corresponding to those in the +GNAT defined package `Ada.Characters.Latin_9` but with the +types of the constants being `Wide_Wide_Character` +instead of `Character`. The provision of such a package +is specifically authorized by the Ada Reference Manual +(RM A.3.3(27)). + +.. _`Ada.Containers.Formal_Doubly_Linked_Lists_(a-cfdlli.ads)`: + +`Ada.Containers.Formal_Doubly_Linked_Lists` (:file:`a-cfdlli.ads`) +================================================================== + +.. index:: Ada.Containers.Formal_Doubly_Linked_Lists (a-cfdlli.ads) + +.. index:: Formal container for doubly linked lists + +This child of `Ada.Containers` defines a modified version of the +Ada 2005 container for doubly linked lists, meant to facilitate formal +verification of code using such containers. The specification of this +unit is compatible with SPARK 2014. + +Note that although this container was designed with formal verification +in mind, it may well be generally useful in that it is a simplified more +efficient version than the one defined in the standard. In particular it +does not have the complex overhead required to detect cursor tampering. + +.. _`Ada.Containers.Formal_Hashed_Maps_(a-cfhama.ads)`: + +`Ada.Containers.Formal_Hashed_Maps` (:file:`a-cfhama.ads`) +========================================================== + +.. index:: Ada.Containers.Formal_Hashed_Maps (a-cfhama.ads) + +.. index:: Formal container for hashed maps + +This child of `Ada.Containers` defines a modified version of the +Ada 2005 container for hashed maps, meant to facilitate formal +verification of code using such containers. The specification of this +unit is compatible with SPARK 2014. + +Note that although this container was designed with formal verification +in mind, it may well be generally useful in that it is a simplified more +efficient version than the one defined in the standard. In particular it +does not have the complex overhead required to detect cursor tampering. + +.. _`Ada.Containers.Formal_Hashed_Sets_(a-cfhase.ads)`: + +`Ada.Containers.Formal_Hashed_Sets` (:file:`a-cfhase.ads`) +========================================================== + +.. index:: Ada.Containers.Formal_Hashed_Sets (a-cfhase.ads) + +.. index:: Formal container for hashed sets + +This child of `Ada.Containers` defines a modified version of the +Ada 2005 container for hashed sets, meant to facilitate formal +verification of code using such containers. The specification of this +unit is compatible with SPARK 2014. + +Note that although this container was designed with formal verification +in mind, it may well be generally useful in that it is a simplified more +efficient version than the one defined in the standard. In particular it +does not have the complex overhead required to detect cursor tampering. + +.. _`Ada.Containers.Formal_Ordered_Maps_(a-cforma.ads)`: + +`Ada.Containers.Formal_Ordered_Maps` (:file:`a-cforma.ads`) +=========================================================== + +.. index:: Ada.Containers.Formal_Ordered_Maps (a-cforma.ads) + +.. index:: Formal container for ordered maps + +This child of `Ada.Containers` defines a modified version of the +Ada 2005 container for ordered maps, meant to facilitate formal +verification of code using such containers. The specification of this +unit is compatible with SPARK 2014. + +Note that although this container was designed with formal verification +in mind, it may well be generally useful in that it is a simplified more +efficient version than the one defined in the standard. In particular it +does not have the complex overhead required to detect cursor tampering. + +.. _`Ada.Containers.Formal_Ordered_Sets_(a-cforse.ads)`: + +`Ada.Containers.Formal_Ordered_Sets` (:file:`a-cforse.ads`) +=========================================================== + +.. index:: Ada.Containers.Formal_Ordered_Sets (a-cforse.ads) + +.. index:: Formal container for ordered sets + +This child of `Ada.Containers` defines a modified version of the +Ada 2005 container for ordered sets, meant to facilitate formal +verification of code using such containers. The specification of this +unit is compatible with SPARK 2014. + +Note that although this container was designed with formal verification +in mind, it may well be generally useful in that it is a simplified more +efficient version than the one defined in the standard. In particular it +does not have the complex overhead required to detect cursor tampering. + +.. _`Ada.Containers.Formal_Vectors_(a-cofove.ads)`: + +`Ada.Containers.Formal_Vectors` (:file:`a-cofove.ads`) +====================================================== + +.. index:: Ada.Containers.Formal_Vectors (a-cofove.ads) + +.. index:: Formal container for vectors + +This child of `Ada.Containers` defines a modified version of the +Ada 2005 container for vectors, meant to facilitate formal +verification of code using such containers. The specification of this +unit is compatible with SPARK 2014. + +Note that although this container was designed with formal verification +in mind, it may well be generally useful in that it is a simplified more +efficient version than the one defined in the standard. In particular it +does not have the complex overhead required to detect cursor tampering. + +.. _`Ada.Containers.Formal_Indefinite_Vectors_(a-cfinve.ads)`: + +`Ada.Containers.Formal_Indefinite_Vectors` (:file:`a-cfinve.ads`) +================================================================= + +.. index:: Ada.Containers.Formal_Indefinite_Vectors (a-cfinve.ads) + +.. index:: Formal container for vectors + +This child of `Ada.Containers` defines a modified version of the +Ada 2005 container for vectors of indefinite elements, meant to +facilitate formal verification of code using such containers. The +specification of this unit is compatible with SPARK 2014. + +Note that although this container was designed with formal verification +in mind, it may well be generally useful in that it is a simplified more +efficient version than the one defined in the standard. In particular it +does not have the complex overhead required to detect cursor tampering. + +.. _`Ada.Containers.Bounded_Holders_(a-coboho.ads)`: + +`Ada.Containers.Bounded_Holders` (:file:`a-coboho.ads`) +======================================================= + +.. index:: Ada.Containers.Bounded_Holders (a-coboho.ads) + +.. index:: Formal container for vectors + +This child of `Ada.Containers` defines a modified version of +Indefinite_Holders that avoids heap allocation. + +.. _`Ada.Command_Line.Environment_(a-colien.ads)`: + +`Ada.Command_Line.Environment` (:file:`a-colien.ads`) +===================================================== + +.. index:: Ada.Command_Line.Environment (a-colien.ads) + +.. index:: Environment entries + +This child of `Ada.Command_Line` +provides a mechanism for obtaining environment values on systems +where this concept makes sense. + +.. _`Ada.Command_Line.Remove_(a-colire.ads)`: + +`Ada.Command_Line.Remove` (:file:`a-colire.ads`) +================================================ + +.. index:: Ada.Command_Line.Remove (a-colire.ads) + +.. index:: Removing command line arguments + +.. index:: Command line, argument removal + +This child of `Ada.Command_Line` +provides a mechanism for logically removing +arguments from the argument list. Once removed, an argument is not visible +to further calls on the subprograms in `Ada.Command_Line` will not +see the removed argument. + +.. _`Ada.Command_Line.Response_File_(a-clrefi.ads)`: + +`Ada.Command_Line.Response_File` (:file:`a-clrefi.ads`) +======================================================= + +.. index:: Ada.Command_Line.Response_File (a-clrefi.ads) + +.. index:: Response file for command line + +.. index:: Command line, response file + +.. index:: Command line, handling long command lines + +This child of `Ada.Command_Line` provides a mechanism facilities for +getting command line arguments from a text file, called a "response file". +Using a response file allow passing a set of arguments to an executable longer +than the maximum allowed by the system on the command line. + +.. _`Ada.Direct_IO.C_Streams_(a-diocst.ads)`: + +`Ada.Direct_IO.C_Streams` (:file:`a-diocst.ads`) +================================================ + +.. index:: Ada.Direct_IO.C_Streams (a-diocst.ads) + +.. index:: C Streams, Interfacing with Direct_IO + +This package provides subprograms that allow interfacing between +C streams and `Direct_IO`. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +.. _`Ada.Exceptions.Is_Null_Occurrence_(a-einuoc.ads)`: + +`Ada.Exceptions.Is_Null_Occurrence` (:file:`a-einuoc.ads`) +========================================================== + +.. index:: Ada.Exceptions.Is_Null_Occurrence (a-einuoc.ads) + +.. index:: Null_Occurrence, testing for + +This child subprogram provides a way of testing for the null +exception occurrence (`Null_Occurrence`) without raising +an exception. + +.. _`Ada.Exceptions.Last_Chance_Handler_(a-elchha.ads)`: + +`Ada.Exceptions.Last_Chance_Handler` (:file:`a-elchha.ads`) +=========================================================== + +.. index:: Ada.Exceptions.Last_Chance_Handler (a-elchha.ads) + +.. index:: Null_Occurrence, testing for + +This child subprogram is used for handling otherwise unhandled +exceptions (hence the name last chance), and perform clean ups before +terminating the program. Note that this subprogram never returns. + +.. _`Ada.Exceptions.Traceback_(a-exctra.ads)`: + +`Ada.Exceptions.Traceback` (:file:`a-exctra.ads`) +================================================= + +.. index:: Ada.Exceptions.Traceback (a-exctra.ads) + +.. index:: Traceback for Exception Occurrence + +This child package provides the subprogram (`Tracebacks`) to +give a traceback array of addresses based on an exception +occurrence. + +.. _`Ada.Sequential_IO.C_Streams_(a-siocst.ads)`: + +`Ada.Sequential_IO.C_Streams` (:file:`a-siocst.ads`) +==================================================== + +.. index:: Ada.Sequential_IO.C_Streams (a-siocst.ads) + +.. index:: C Streams, Interfacing with Sequential_IO + +This package provides subprograms that allow interfacing between +C streams and `Sequential_IO`. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +.. _`Ada.Streams.Stream_IO.C_Streams_(a-ssicst.ads)`: + +`Ada.Streams.Stream_IO.C_Streams` (:file:`a-ssicst.ads`) +======================================================== + +.. index:: Ada.Streams.Stream_IO.C_Streams (a-ssicst.ads) + +.. index:: C Streams, Interfacing with Stream_IO + +This package provides subprograms that allow interfacing between +C streams and `Stream_IO`. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +.. _`Ada.Strings.Unbounded.Text_IO_(a-suteio.ads)`: + +`Ada.Strings.Unbounded.Text_IO` (:file:`a-suteio.ads`) +====================================================== + +.. index:: Ada.Strings.Unbounded.Text_IO (a-suteio.ads) + +.. index:: Unbounded_String, IO support + +.. index:: Text_IO, extensions for unbounded strings + +This package provides subprograms for Text_IO for unbounded +strings, avoiding the necessity for an intermediate operation +with ordinary strings. + +.. _`Ada.Strings.Wide_Unbounded.Wide_Text_IO_(a-swuwti.ads)`: + +`Ada.Strings.Wide_Unbounded.Wide_Text_IO` (:file:`a-swuwti.ads`) +================================================================ + +.. index:: Ada.Strings.Wide_Unbounded.Wide_Text_IO (a-swuwti.ads) + +.. index:: Unbounded_Wide_String, IO support + +.. index:: Text_IO, extensions for unbounded wide strings + +This package provides subprograms for Text_IO for unbounded +wide strings, avoiding the necessity for an intermediate operation +with ordinary wide strings. + +.. _`Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO_(a-szuzti.ads)`: + +`Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO` (:file:`a-szuzti.ads`) +========================================================================== + +.. index:: Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO (a-szuzti.ads) + +.. index:: Unbounded_Wide_Wide_String, IO support + +.. index:: Text_IO, extensions for unbounded wide wide strings + +This package provides subprograms for Text_IO for unbounded +wide wide strings, avoiding the necessity for an intermediate operation +with ordinary wide wide strings. + +.. _`Ada.Text_IO.C_Streams_(a-tiocst.ads)`: + +`Ada.Text_IO.C_Streams` (:file:`a-tiocst.ads`) +============================================== + +.. index:: Ada.Text_IO.C_Streams (a-tiocst.ads) + +.. index:: C Streams, Interfacing with `Text_IO` + +This package provides subprograms that allow interfacing between +C streams and `Text_IO`. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +.. _`Ada.Text_IO.Reset_Standard_Files_(a-tirsfi.ads)`: + +`Ada.Text_IO.Reset_Standard_Files` (:file:`a-tirsfi.ads`) +========================================================= + +.. index:: Ada.Text_IO.Reset_Standard_Files (a-tirsfi.ads) + +.. index:: Text_IO resetting standard files + +This procedure is used to reset the status of the standard files used +by Ada.Text_IO. This is useful in a situation (such as a restart in an +embedded application) where the status of the files may change during +execution (for example a standard input file may be redefined to be +interactive). + +.. _`Ada.Wide_Characters.Unicode_(a-wichun.ads)`: + +`Ada.Wide_Characters.Unicode` (:file:`a-wichun.ads`) +==================================================== + +.. index:: Ada.Wide_Characters.Unicode (a-wichun.ads) + +.. index:: Unicode categorization, Wide_Character + +This package provides subprograms that allow categorization of +Wide_Character values according to Unicode categories. + +.. _`Ada.Wide_Text_IO.C_Streams_(a-wtcstr.ads)`: + +`Ada.Wide_Text_IO.C_Streams` (:file:`a-wtcstr.ads`) +=================================================== + +.. index:: Ada.Wide_Text_IO.C_Streams (a-wtcstr.ads) + +.. index:: C Streams, Interfacing with `Wide_Text_IO` + +This package provides subprograms that allow interfacing between +C streams and `Wide_Text_IO`. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +.. _`Ada.Wide_Text_IO.Reset_Standard_Files_(a-wrstfi.ads)`: + +`Ada.Wide_Text_IO.Reset_Standard_Files` (:file:`a-wrstfi.ads`) +============================================================== + +.. index:: Ada.Wide_Text_IO.Reset_Standard_Files (a-wrstfi.ads) + +.. index:: Wide_Text_IO resetting standard files + +This procedure is used to reset the status of the standard files used +by Ada.Wide_Text_IO. This is useful in a situation (such as a restart in an +embedded application) where the status of the files may change during +execution (for example a standard input file may be redefined to be +interactive). + +.. _`Ada.Wide_Wide_Characters.Unicode_(a-zchuni.ads)`: + +`Ada.Wide_Wide_Characters.Unicode` (:file:`a-zchuni.ads`) +========================================================= + +.. index:: Ada.Wide_Wide_Characters.Unicode (a-zchuni.ads) + +.. index:: Unicode categorization, Wide_Wide_Character + +This package provides subprograms that allow categorization of +Wide_Wide_Character values according to Unicode categories. + +.. _`Ada.Wide_Wide_Text_IO.C_Streams_(a-ztcstr.ads)`: + +`Ada.Wide_Wide_Text_IO.C_Streams` (:file:`a-ztcstr.ads`) +======================================================== + +.. index:: Ada.Wide_Wide_Text_IO.C_Streams (a-ztcstr.ads) + +.. index:: C Streams, Interfacing with `Wide_Wide_Text_IO` + +This package provides subprograms that allow interfacing between +C streams and `Wide_Wide_Text_IO`. The stream identifier can be +extracted from a file opened on the Ada side, and an Ada file +can be constructed from a stream opened on the C side. + +.. _`Ada.Wide_Wide_Text_IO.Reset_Standard_Files_(a-zrstfi.ads)`: + +`Ada.Wide_Wide_Text_IO.Reset_Standard_Files` (:file:`a-zrstfi.ads`) +=================================================================== + +.. index:: Ada.Wide_Wide_Text_IO.Reset_Standard_Files (a-zrstfi.ads) + +.. index:: Wide_Wide_Text_IO resetting standard files + +This procedure is used to reset the status of the standard files used +by Ada.Wide_Wide_Text_IO. This is useful in a situation (such as a +restart in an embedded application) where the status of the files may +change during execution (for example a standard input file may be +redefined to be interactive). + +.. _`GNAT.Altivec_(g-altive.ads)`: + +`GNAT.Altivec` (:file:`g-altive.ads`) +===================================== + +.. index:: GNAT.Altivec (g-altive.ads) + +.. index:: AltiVec + +This is the root package of the GNAT AltiVec binding. It provides +definitions of constants and types common to all the versions of the +binding. + +.. _`GNAT.Altivec.Conversions_(g-altcon.ads)`: + +`GNAT.Altivec.Conversions` (:file:`g-altcon.ads`) +================================================= + +.. index:: GNAT.Altivec.Conversions (g-altcon.ads) + +.. index:: AltiVec + +This package provides the Vector/View conversion routines. + +.. _`GNAT.Altivec.Vector_Operations_(g-alveop.ads)`: + +`GNAT.Altivec.Vector_Operations` (:file:`g-alveop.ads`) +======================================================= + +.. index:: GNAT.Altivec.Vector_Operations (g-alveop.ads) + +.. index:: AltiVec + +This package exposes the Ada interface to the AltiVec operations on +vector objects. A soft emulation is included by default in the GNAT +library. The hard binding is provided as a separate package. This unit +is common to both bindings. + +.. _`GNAT.Altivec.Vector_Types_(g-alvety.ads)`: + +`GNAT.Altivec.Vector_Types` (:file:`g-alvety.ads`) +================================================== + +.. index:: GNAT.Altivec.Vector_Types (g-alvety.ads) + +.. index:: AltiVec + +This package exposes the various vector types part of the Ada binding +to AltiVec facilities. + +.. _`GNAT.Altivec.Vector_Views_(g-alvevi.ads)`: + +`GNAT.Altivec.Vector_Views` (:file:`g-alvevi.ads`) +================================================== + +.. index:: GNAT.Altivec.Vector_Views (g-alvevi.ads) + +.. index:: AltiVec + +This package provides public 'View' data types from/to which private +vector representations can be converted via +GNAT.Altivec.Conversions. This allows convenient access to individual +vector elements and provides a simple way to initialize vector +objects. + +.. _`GNAT.Array_Split_(g-arrspl.ads)`: + +`GNAT.Array_Split` (:file:`g-arrspl.ads`) +========================================= + +.. index:: GNAT.Array_Split (g-arrspl.ads) + +.. index:: Array splitter + +Useful array-manipulation routines: given a set of separators, split +an array wherever the separators appear, and provide direct access +to the resulting slices. + +.. _`GNAT.AWK_(g-awk.ads)`: + +`GNAT.AWK` (:file:`g-awk.ads`) +============================== + +.. index:: GNAT.AWK (g-awk.ads) + +.. index:: Parsing + +.. index:: AWK + +Provides AWK-like parsing functions, with an easy interface for parsing one +or more files containing formatted data. The file is viewed as a database +where each record is a line and a field is a data element in this line. + +.. _`GNAT.Bounded_Buffers_(g-boubuf.ads)`: + +`GNAT.Bounded_Buffers` (:file:`g-boubuf.ads`) +============================================= + +.. index:: GNAT.Bounded_Buffers (g-boubuf.ads) + +.. index:: Parsing + +.. index:: Bounded Buffers + +Provides a concurrent generic bounded buffer abstraction. Instances are +useful directly or as parts of the implementations of other abstractions, +such as mailboxes. + +.. _`GNAT.Bounded_Mailboxes_(g-boumai.ads)`: + +`GNAT.Bounded_Mailboxes` (:file:`g-boumai.ads`) +=============================================== + +.. index:: GNAT.Bounded_Mailboxes (g-boumai.ads) + +.. index:: Parsing + +.. index:: Mailboxes + +Provides a thread-safe asynchronous intertask mailbox communication facility. + +.. _`GNAT.Bubble_Sort_(g-bubsor.ads)`: + +`GNAT.Bubble_Sort` (:file:`g-bubsor.ads`) +========================================= + +.. index:: GNAT.Bubble_Sort (g-bubsor.ads) + +.. index:: Sorting + +.. index:: Bubble sort + +Provides a general implementation of bubble sort usable for sorting arbitrary +data items. Exchange and comparison procedures are provided by passing +access-to-procedure values. + +.. _`GNAT.Bubble_Sort_A_(g-busora.ads)`: + +`GNAT.Bubble_Sort_A` (:file:`g-busora.ads`) +=========================================== + +.. index:: GNAT.Bubble_Sort_A (g-busora.ads) + +.. index:: Sorting + +.. index:: Bubble sort + +Provides a general implementation of bubble sort usable for sorting arbitrary +data items. Move and comparison procedures are provided by passing +access-to-procedure values. This is an older version, retained for +compatibility. Usually `GNAT.Bubble_Sort` will be preferable. + +.. _`GNAT.Bubble_Sort_G_(g-busorg.ads)`: + +`GNAT.Bubble_Sort_G` (:file:`g-busorg.ads`) +=========================================== + +.. index:: GNAT.Bubble_Sort_G (g-busorg.ads) + +.. index:: Sorting + +.. index:: Bubble sort + +Similar to `Bubble_Sort_A` except that the move and sorting procedures +are provided as generic parameters, this improves efficiency, especially +if the procedures can be inlined, at the expense of duplicating code for +multiple instantiations. + +.. _`GNAT.Byte_Order_Mark_(g-byorma.ads)`: + +`GNAT.Byte_Order_Mark` (:file:`g-byorma.ads`) +============================================= + +.. index:: GNAT.Byte_Order_Mark (g-byorma.ads) + +.. index:: UTF-8 representation + +.. index:: Wide characte representations + +Provides a routine which given a string, reads the start of the string to +see whether it is one of the standard byte order marks (BOM's) which signal +the encoding of the string. The routine includes detection of special XML +sequences for various UCS input formats. + +.. _`GNAT.Byte_Swapping_(g-bytswa.ads)`: + +`GNAT.Byte_Swapping` (:file:`g-bytswa.ads`) +=========================================== + +.. index:: GNAT.Byte_Swapping (g-bytswa.ads) + +.. index:: Byte swapping + +.. index:: Endianness + +General routines for swapping the bytes in 2-, 4-, and 8-byte quantities. +Machine-specific implementations are available in some cases. + +.. _`GNAT.Calendar_(g-calend.ads)`: + +`GNAT.Calendar` (:file:`g-calend.ads`) +====================================== + +.. index:: GNAT.Calendar (g-calend.ads) + +.. index:: Calendar + +Extends the facilities provided by `Ada.Calendar` to include handling +of days of the week, an extended `Split` and `Time_Of` capability. +Also provides conversion of `Ada.Calendar.Time` values to and from the +C `timeval` format. + +.. _`GNAT.Calendar.Time_IO_(g-catiio.ads)`: + +`GNAT.Calendar.Time_IO` (:file:`g-catiio.ads`) +============================================== + +.. index:: Calendar + +.. index:: Time + +.. index:: GNAT.Calendar.Time_IO (g-catiio.ads) + +.. _`GNAT.CRC32_(g-crc32.ads)`: + +`GNAT.CRC32` (:file:`g-crc32.ads`) +================================== + +.. index:: GNAT.CRC32 (g-crc32.ads) + +.. index:: CRC32 + +.. index:: Cyclic Redundancy Check + +This package implements the CRC-32 algorithm. For a full description +of this algorithm see +*Computation of Cyclic Redundancy Checks via Table Look-Up*, +:title:`Communications of the ACM`, Vol. 31 No. 8, pp. 1008-1013, +Aug. 1988. Sarwate, D.V. + +.. _`GNAT.Case_Util_(g-casuti.ads)`: + +`GNAT.Case_Util` (:file:`g-casuti.ads`) +======================================= + +.. index:: GNAT.Case_Util (g-casuti.ads) + +.. index:: Casing utilities + +.. index:: Character handling (`GNAT.Case_Util`) + +A set of simple routines for handling upper and lower casing of strings +without the overhead of the full casing tables +in `Ada.Characters.Handling`. + +.. _`GNAT.CGI_(g-cgi.ads)`: + +`GNAT.CGI` (:file:`g-cgi.ads`) +============================== + +.. index:: GNAT.CGI (g-cgi.ads) + +.. index:: CGI (Common Gateway Interface) + +This is a package for interfacing a GNAT program with a Web server via the +Common Gateway Interface (CGI). Basically this package parses the CGI +parameters, which are a set of key/value pairs sent by the Web server. It +builds a table whose index is the key and provides some services to deal +with this table. + +.. _`GNAT.CGI.Cookie_(g-cgicoo.ads)`: + +`GNAT.CGI.Cookie` (:file:`g-cgicoo.ads`) +======================================== + +.. index:: GNAT.CGI.Cookie (g-cgicoo.ads) + +.. index:: CGI (Common Gateway Interface) cookie support + +.. index:: Cookie support in CGI + +This is a package to interface a GNAT program with a Web server via the +Common Gateway Interface (CGI). It exports services to deal with Web +cookies (piece of information kept in the Web client software). + +.. _`GNAT.CGI.Debug_(g-cgideb.ads)`: + +`GNAT.CGI.Debug` (:file:`g-cgideb.ads`) +======================================= + +.. index:: GNAT.CGI.Debug (g-cgideb.ads) + +.. index:: CGI (Common Gateway Interface) debugging + +This is a package to help debugging CGI (Common Gateway Interface) +programs written in Ada. + +.. _`GNAT.Command_Line_(g-comlin.ads)`: + +`GNAT.Command_Line` (:file:`g-comlin.ads`) +========================================== + +.. index:: GNAT.Command_Line (g-comlin.ads) + +.. index:: Command line + +Provides a high level interface to `Ada.Command_Line` facilities, +including the ability to scan for named switches with optional parameters +and expand file names using wild card notations. + +.. _`GNAT.Compiler_Version_(g-comver.ads)`: + +`GNAT.Compiler_Version` (:file:`g-comver.ads`) +============================================== + +.. index:: GNAT.Compiler_Version (g-comver.ads) + +.. index:: Compiler Version + +.. index:: Version, of compiler + +Provides a routine for obtaining the version of the compiler used to +compile the program. More accurately this is the version of the binder +used to bind the program (this will normally be the same as the version +of the compiler if a consistent tool set is used to compile all units +of a partition). + +.. _`GNAT.Ctrl_C_(g-ctrl_c.ads)`: + +`GNAT.Ctrl_C` (:file:`g-ctrl_c.ads`) +==================================== + +.. index:: GNAT.Ctrl_C (g-ctrl_c.ads) + +.. index:: Interrupt + +Provides a simple interface to handle Ctrl-C keyboard events. + +.. _`GNAT.Current_Exception_(g-curexc.ads)`: + +`GNAT.Current_Exception` (:file:`g-curexc.ads`) +=============================================== + +.. index:: GNAT.Current_Exception (g-curexc.ads) + +.. index:: Current exception + +.. index:: Exception retrieval + +Provides access to information on the current exception that has been raised +without the need for using the Ada 95 / Ada 2005 exception choice parameter +specification syntax. +This is particularly useful in simulating typical facilities for +obtaining information about exceptions provided by Ada 83 compilers. + +.. _`GNAT.Debug_Pools_(g-debpoo.ads)`: + +`GNAT.Debug_Pools` (:file:`g-debpoo.ads`) +========================================= + +.. index:: GNAT.Debug_Pools (g-debpoo.ads) + +.. index:: Debugging + +.. index:: Debug pools + +.. index:: Memory corruption debugging + +Provide a debugging storage pools that helps tracking memory corruption +problems. +See `The GNAT Debug_Pool Facility` section in the :title:`GNAT User's Guide`. + +.. _`GNAT.Debug_Utilities_(g-debuti.ads)`: + +`GNAT.Debug_Utilities` (:file:`g-debuti.ads`) +============================================= + +.. index:: GNAT.Debug_Utilities (g-debuti.ads) + +.. index:: Debugging + +Provides a few useful utilities for debugging purposes, including conversion +to and from string images of address values. Supports both C and Ada formats +for hexadecimal literals. + +.. _`GNAT.Decode_String_(g-decstr.ads)`: + +`GNAT.Decode_String` (:file:`g-decstr.ads`) +=========================================== + +.. index:: GNAT.Decode_String (g-decstr.ads) + +.. index:: Decoding strings + +.. index:: String decoding + +.. index:: Wide character encoding + +.. index:: UTF-8 + +.. index:: Unicode + +A generic package providing routines for decoding wide character and wide wide +character strings encoded as sequences of 8-bit characters using a specified +encoding method. Includes validation routines, and also routines for stepping +to next or previous encoded character in an encoded string. +Useful in conjunction with Unicode character coding. Note there is a +preinstantiation for UTF-8. See next entry. + +.. _`GNAT.Decode_UTF8_String_(g-deutst.ads)`: + +`GNAT.Decode_UTF8_String` (:file:`g-deutst.ads`) +================================================ + +.. index:: GNAT.Decode_UTF8_String (g-deutst.ads) + +.. index:: Decoding strings + +.. index:: Decoding UTF-8 strings + +.. index:: UTF-8 string decoding + +.. index:: Wide character decoding + +.. index:: UTF-8 + +.. index:: Unicode + +A preinstantiation of GNAT.Decode_Strings for UTF-8 encoding. + +.. _`GNAT.Directory_Operations_(g-dirope.ads)`: + +`GNAT.Directory_Operations` (:file:`g-dirope.ads`) +================================================== + +.. index:: GNAT.Directory_Operations (g-dirope.ads) + +.. index:: Directory operations + +Provides a set of routines for manipulating directories, including changing +the current directory, making new directories, and scanning the files in a +directory. + +.. _`GNAT.Directory_Operations.Iteration_(g-diopit.ads)`: + +`GNAT.Directory_Operations.Iteration` (:file:`g-diopit.ads`) +============================================================ + +.. index:: GNAT.Directory_Operations.Iteration (g-diopit.ads) + +.. index:: Directory operations iteration + +A child unit of GNAT.Directory_Operations providing additional operations +for iterating through directories. + +.. _`GNAT.Dynamic_HTables_(g-dynhta.ads)`: + +`GNAT.Dynamic_HTables` (:file:`g-dynhta.ads`) +============================================= + +.. index:: GNAT.Dynamic_HTables (g-dynhta.ads) + +.. index:: Hash tables + +A generic implementation of hash tables that can be used to hash arbitrary +data. Provided in two forms, a simple form with built in hash functions, +and a more complex form in which the hash function is supplied. + +This package provides a facility similar to that of `GNAT.HTable`, +except that this package declares a type that can be used to define +dynamic instances of the hash table, while an instantiation of +`GNAT.HTable` creates a single instance of the hash table. + +.. _`GNAT.Dynamic_Tables_(g-dyntab.ads)`: + +`GNAT.Dynamic_Tables` (:file:`g-dyntab.ads`) +============================================ + +.. index:: GNAT.Dynamic_Tables (g-dyntab.ads) + +.. index:: Table implementation + +.. index:: Arrays, extendable + +A generic package providing a single dimension array abstraction where the +length of the array can be dynamically modified. + +This package provides a facility similar to that of `GNAT.Table`, +except that this package declares a type that can be used to define +dynamic instances of the table, while an instantiation of +`GNAT.Table` creates a single instance of the table type. + +.. _`GNAT.Encode_String_(g-encstr.ads)`: + +`GNAT.Encode_String` (:file:`g-encstr.ads`) +=========================================== + +.. index:: GNAT.Encode_String (g-encstr.ads) + +.. index:: Encoding strings + +.. index:: String encoding + +.. index:: Wide character encoding + +.. index:: UTF-8 + +.. index:: Unicode + +A generic package providing routines for encoding wide character and wide +wide character strings as sequences of 8-bit characters using a specified +encoding method. Useful in conjunction with Unicode character coding. +Note there is a preinstantiation for UTF-8. See next entry. + +.. _`GNAT.Encode_UTF8_String_(g-enutst.ads)`: + +`GNAT.Encode_UTF8_String` (:file:`g-enutst.ads`) +================================================ + +.. index:: GNAT.Encode_UTF8_String (g-enutst.ads) + +.. index:: Encoding strings + +.. index:: Encoding UTF-8 strings + +.. index:: UTF-8 string encoding + +.. index:: Wide character encoding + +.. index:: UTF-8 + +.. index:: Unicode + +A preinstantiation of GNAT.Encode_Strings for UTF-8 encoding. + +.. _`GNAT.Exception_Actions_(g-excact.ads)`: + +`GNAT.Exception_Actions` (:file:`g-excact.ads`) +=============================================== + +.. index:: GNAT.Exception_Actions (g-excact.ads) + +.. index:: Exception actions + +Provides callbacks when an exception is raised. Callbacks can be registered +for specific exceptions, or when any exception is raised. This +can be used for instance to force a core dump to ease debugging. + +.. _`GNAT.Exception_Traces_(g-exctra.ads)`: + +`GNAT.Exception_Traces` (:file:`g-exctra.ads`) +============================================== + +.. index:: GNAT.Exception_Traces (g-exctra.ads) + +.. index:: Exception traces + +.. index:: Debugging + +Provides an interface allowing to control automatic output upon exception +occurrences. + +.. _`GNAT.Exceptions_(g-expect.ads)`: + +`GNAT.Exceptions` (:file:`g-expect.ads`) +======================================== + +.. index:: GNAT.Exceptions (g-expect.ads) + +.. index:: Exceptions, Pure + +.. index:: Pure packages, exceptions + +Normally it is not possible to raise an exception with +a message from a subprogram in a pure package, since the +necessary types and subprograms are in `Ada.Exceptions` +which is not a pure unit. `GNAT.Exceptions` provides a +facility for getting around this limitation for a few +predefined exceptions, and for example allow raising +`Constraint_Error` with a message from a pure subprogram. + +.. _`GNAT.Expect_(g-expect.ads)`: + +`GNAT.Expect` (:file:`g-expect.ads`) +==================================== + +.. index:: GNAT.Expect (g-expect.ads) + +Provides a set of subprograms similar to what is available +with the standard Tcl Expect tool. +It allows you to easily spawn and communicate with an external process. +You can send commands or inputs to the process, and compare the output +with some expected regular expression. Currently `GNAT.Expect` +is implemented on all native GNAT ports. +It is not implemented for cross ports, and in particular is not +implemented for VxWorks or LynxOS. + +.. _`GNAT.Expect.TTY_(g-exptty.ads)`: + +`GNAT.Expect.TTY` (:file:`g-exptty.ads`) +======================================== + +.. index:: GNAT.Expect.TTY (g-exptty.ads) + +As GNAT.Expect but using pseudo-terminal. +Currently `GNAT.Expect.TTY` is implemented on all native GNAT +ports. It is not implemented for cross ports, and +in particular is not implemented for VxWorks or LynxOS. + +.. _`GNAT.Float_Control_(g-flocon.ads)`: + +`GNAT.Float_Control` (:file:`g-flocon.ads`) +=========================================== + +.. index:: GNAT.Float_Control (g-flocon.ads) + +.. index:: Floating-Point Processor + +Provides an interface for resetting the floating-point processor into the +mode required for correct semantic operation in Ada. Some third party +library calls may cause this mode to be modified, and the Reset procedure +in this package can be used to reestablish the required mode. + +.. _`GNAT.Formatted_String_(g-forstr.ads)`: + +`GNAT.Formatted_String` (:file:`g-forstr.ads`) +============================================== + +.. index:: GNAT.Formatted_String (g-forstr.ads) + +.. index:: Formatted String + +Provides support for C/C++ printf() formatted strings. The format is +copied from the printf() routine and should therefore gives identical +output. Some generic routines are provided to be able to use types +derived from Integer, Float or enumerations as values for the +formatted string. + +.. _`GNAT.Heap_Sort_(g-heasor.ads)`: + +`GNAT.Heap_Sort` (:file:`g-heasor.ads`) +======================================= + +.. index:: GNAT.Heap_Sort (g-heasor.ads) + +.. index:: Sorting + +Provides a general implementation of heap sort usable for sorting arbitrary +data items. Exchange and comparison procedures are provided by passing +access-to-procedure values. The algorithm used is a modified heap sort +that performs approximately N*log(N) comparisons in the worst case. + +.. _`GNAT.Heap_Sort_A_(g-hesora.ads)`: + +`GNAT.Heap_Sort_A` (:file:`g-hesora.ads`) +========================================= + +.. index:: GNAT.Heap_Sort_A (g-hesora.ads) + +.. index:: Sorting + +Provides a general implementation of heap sort usable for sorting arbitrary +data items. Move and comparison procedures are provided by passing +access-to-procedure values. The algorithm used is a modified heap sort +that performs approximately N*log(N) comparisons in the worst case. +This differs from `GNAT.Heap_Sort` in having a less convenient +interface, but may be slightly more efficient. + +.. _`GNAT.Heap_Sort_G_(g-hesorg.ads)`: + +`GNAT.Heap_Sort_G` (:file:`g-hesorg.ads`) +========================================= + +.. index:: GNAT.Heap_Sort_G (g-hesorg.ads) + +.. index:: Sorting + +Similar to `Heap_Sort_A` except that the move and sorting procedures +are provided as generic parameters, this improves efficiency, especially +if the procedures can be inlined, at the expense of duplicating code for +multiple instantiations. + +.. _`GNAT.HTable_(g-htable.ads)`: + +`GNAT.HTable` (:file:`g-htable.ads`) +==================================== + +.. index:: GNAT.HTable (g-htable.ads) + +.. index:: Hash tables + +A generic implementation of hash tables that can be used to hash arbitrary +data. Provides two approaches, one a simple static approach, and the other +allowing arbitrary dynamic hash tables. + +.. _`GNAT.IO_(g-io.ads)`: + +`GNAT.IO` (:file:`g-io.ads`) +============================ + +.. index:: GNAT.IO (g-io.ads) + +.. index:: Simple I/O + +.. index:: Input/Output facilities + +A simple preelaborable input-output package that provides a subset of +simple Text_IO functions for reading characters and strings from +Standard_Input, and writing characters, strings and integers to either +Standard_Output or Standard_Error. + +.. _`GNAT.IO_Aux_(g-io_aux.ads)`: + +`GNAT.IO_Aux` (:file:`g-io_aux.ads`) +==================================== + +.. index:: GNAT.IO_Aux (g-io_aux.ads) + +.. index:: Text_IO + +.. index:: Input/Output facilities + +Provides some auxiliary functions for use with Text_IO, including a test +for whether a file exists, and functions for reading a line of text. + +.. _`GNAT.Lock_Files_(g-locfil.ads)`: + +`GNAT.Lock_Files` (:file:`g-locfil.ads`) +======================================== + +.. index:: GNAT.Lock_Files (g-locfil.ads) + +.. index:: File locking + +.. index:: Locking using files + +Provides a general interface for using files as locks. Can be used for +providing program level synchronization. + +.. _`GNAT.MBBS_Discrete_Random_(g-mbdira.ads)`: + +`GNAT.MBBS_Discrete_Random` (:file:`g-mbdira.ads`) +================================================== + +.. index:: GNAT.MBBS_Discrete_Random (g-mbdira.ads) + +.. index:: Random number generation + +The original implementation of `Ada.Numerics.Discrete_Random`. Uses +a modified version of the Blum-Blum-Shub generator. + +.. _`GNAT.MBBS_Float_Random_(g-mbflra.ads)`: + +`GNAT.MBBS_Float_Random` (:file:`g-mbflra.ads`) +=============================================== + +.. index:: GNAT.MBBS_Float_Random (g-mbflra.ads) + +.. index:: Random number generation + +The original implementation of `Ada.Numerics.Float_Random`. Uses +a modified version of the Blum-Blum-Shub generator. + +.. _`GNAT.MD5_(g-md5.ads)`: + +`GNAT.MD5` (:file:`g-md5.ads`) +============================== + +.. index:: GNAT.MD5 (g-md5.ads) + +.. index:: Message Digest MD5 + +Implements the MD5 Message-Digest Algorithm as described in RFC 1321, and +the HMAC-MD5 message authentication function as described in RFC 2104 and +FIPS PUB 198. + +.. _`GNAT.Memory_Dump_(g-memdum.ads)`: + +`GNAT.Memory_Dump` (:file:`g-memdum.ads`) +========================================= + +.. index:: GNAT.Memory_Dump (g-memdum.ads) + +.. index:: Dump Memory + +Provides a convenient routine for dumping raw memory to either the +standard output or standard error files. Uses GNAT.IO for actual +output. + +.. _`GNAT.Most_Recent_Exception_(g-moreex.ads)`: + +`GNAT.Most_Recent_Exception` (:file:`g-moreex.ads`) +=================================================== + +.. index:: GNAT.Most_Recent_Exception (g-moreex.ads) + +.. index:: Exception, obtaining most recent + +Provides access to the most recently raised exception. Can be used for +various logging purposes, including duplicating functionality of some +Ada 83 implementation dependent extensions. + +.. _`GNAT.OS_Lib_(g-os_lib.ads)`: + +`GNAT.OS_Lib` (:file:`g-os_lib.ads`) +==================================== + +.. index:: GNAT.OS_Lib (g-os_lib.ads) + +.. index:: Operating System interface + +.. index:: Spawn capability + +Provides a range of target independent operating system interface functions, +including time/date management, file operations, subprocess management, +including a portable spawn procedure, and access to environment variables +and error return codes. + +.. _`GNAT.Perfect_Hash_Generators_(g-pehage.ads)`: + +`GNAT.Perfect_Hash_Generators` (:file:`g-pehage.ads`) +===================================================== + +.. index:: GNAT.Perfect_Hash_Generators (g-pehage.ads) + +.. index:: Hash functions + +Provides a generator of static minimal perfect hash functions. No +collisions occur and each item can be retrieved from the table in one +probe (perfect property). The hash table size corresponds to the exact +size of the key set and no larger (minimal property). The key set has to +be know in advance (static property). The hash functions are also order +preserving. If w2 is inserted after w1 in the generator, their +hashcode are in the same order. These hashing functions are very +convenient for use with realtime applications. + +.. _`GNAT.Random_Numbers_(g-rannum.ads)`: + +`GNAT.Random_Numbers` (:file:`g-rannum.ads`) +============================================ + +.. index:: GNAT.Random_Numbers (g-rannum.ads) + +.. index:: Random number generation + +Provides random number capabilities which extend those available in the +standard Ada library and are more convenient to use. + +.. _`GNAT.Regexp_(g-regexp.ads)`: + +`GNAT.Regexp` (:file:`g-regexp.ads`) +==================================== + +.. index:: GNAT.Regexp (g-regexp.ads) + +.. index:: Regular expressions + +.. index:: Pattern matching + +A simple implementation of regular expressions, using a subset of regular +expression syntax copied from familiar Unix style utilities. This is the +simplest of the three pattern matching packages provided, and is particularly +suitable for 'file globbing' applications. + +.. _`GNAT.Registry_(g-regist.ads)`: + +`GNAT.Registry` (:file:`g-regist.ads`) +====================================== + +.. index:: GNAT.Registry (g-regist.ads) + +.. index:: Windows Registry + +This is a high level binding to the Windows registry. It is possible to +do simple things like reading a key value, creating a new key. For full +registry API, but at a lower level of abstraction, refer to the Win32.Winreg +package provided with the Win32Ada binding + +.. _`GNAT.Regpat_(g-regpat.ads)`: + +`GNAT.Regpat` (:file:`g-regpat.ads`) +==================================== + +.. index:: GNAT.Regpat (g-regpat.ads) + +.. index:: Regular expressions + +.. index:: Pattern matching + +A complete implementation of Unix-style regular expression matching, copied +from the original V7 style regular expression library written in C by +Henry Spencer (and binary compatible with this C library). + +.. _`GNAT.Rewrite_Data_(g-rewdat.ads)`: + +`GNAT.Rewrite_Data` (:file:`g-rewdat.ads`) +========================================== + +.. index:: GNAT.Rewrite_Data (g-rewdat.ads) + +.. index:: Rewrite data + +A unit to rewrite on-the-fly string occurrences in a stream of +data. The implementation has a very minimal memory footprint as the +full content to be processed is not loaded into memory all at once. This makes +this interface usable for large files or socket streams. + +.. _`GNAT.Secondary_Stack_Info_(g-sestin.ads)`: + +`GNAT.Secondary_Stack_Info` (:file:`g-sestin.ads`) +================================================== + +.. index:: GNAT.Secondary_Stack_Info (g-sestin.ads) + +.. index:: Secondary Stack Info + +Provide the capability to query the high water mark of the current task's +secondary stack. + +.. _`GNAT.Semaphores_(g-semaph.ads)`: + +`GNAT.Semaphores` (:file:`g-semaph.ads`) +======================================== + +.. index:: GNAT.Semaphores (g-semaph.ads) + +.. index:: Semaphores + +Provides classic counting and binary semaphores using protected types. + +.. _`GNAT.Serial_Communications_(g-sercom.ads)`: + +`GNAT.Serial_Communications` (:file:`g-sercom.ads`) +=================================================== + +.. index:: GNAT.Serial_Communications (g-sercom.ads) + +.. index:: Serial_Communications + +Provides a simple interface to send and receive data over a serial +port. This is only supported on GNU/Linux and Windows. + +.. _`GNAT.SHA1_(g-sha1.ads)`: + +`GNAT.SHA1` (:file:`g-sha1.ads`) +================================ + +.. index:: GNAT.SHA1 (g-sha1.ads) + +.. index:: Secure Hash Algorithm SHA-1 + +Implements the SHA-1 Secure Hash Algorithm as described in FIPS PUB 180-3 +and RFC 3174, and the HMAC-SHA1 message authentication function as described +in RFC 2104 and FIPS PUB 198. + +.. _`GNAT.SHA224_(g-sha224.ads)`: + +`GNAT.SHA224` (:file:`g-sha224.ads`) +==================================== + +.. index:: GNAT.SHA224 (g-sha224.ads) + +.. index:: Secure Hash Algorithm SHA-224 + +Implements the SHA-224 Secure Hash Algorithm as described in FIPS PUB 180-3, +and the HMAC-SHA224 message authentication function as described +in RFC 2104 and FIPS PUB 198. + +.. _`GNAT.SHA256_(g-sha256.ads)`: + +`GNAT.SHA256` (:file:`g-sha256.ads`) +==================================== + +.. index:: GNAT.SHA256 (g-sha256.ads) + +.. index:: Secure Hash Algorithm SHA-256 + +Implements the SHA-256 Secure Hash Algorithm as described in FIPS PUB 180-3, +and the HMAC-SHA256 message authentication function as described +in RFC 2104 and FIPS PUB 198. + +.. _`GNAT.SHA384_(g-sha384.ads)`: + +`GNAT.SHA384` (:file:`g-sha384.ads`) +==================================== + +.. index:: GNAT.SHA384 (g-sha384.ads) + +.. index:: Secure Hash Algorithm SHA-384 + +Implements the SHA-384 Secure Hash Algorithm as described in FIPS PUB 180-3, +and the HMAC-SHA384 message authentication function as described +in RFC 2104 and FIPS PUB 198. + +.. _`GNAT.SHA512_(g-sha512.ads)`: + +`GNAT.SHA512` (:file:`g-sha512.ads`) +==================================== + +.. index:: GNAT.SHA512 (g-sha512.ads) + +.. index:: Secure Hash Algorithm SHA-512 + +Implements the SHA-512 Secure Hash Algorithm as described in FIPS PUB 180-3, +and the HMAC-SHA512 message authentication function as described +in RFC 2104 and FIPS PUB 198. + +.. _`GNAT.Signals_(g-signal.ads)`: + +`GNAT.Signals` (:file:`g-signal.ads`) +===================================== + +.. index:: GNAT.Signals (g-signal.ads) + +.. index:: Signals + +Provides the ability to manipulate the blocked status of signals on supported +targets. + +.. _`GNAT.Sockets_(g-socket.ads)`: + +`GNAT.Sockets` (:file:`g-socket.ads`) +===================================== + +.. index:: GNAT.Sockets (g-socket.ads) + +.. index:: Sockets + +A high level and portable interface to develop sockets based applications. +This package is based on the sockets thin binding found in +`GNAT.Sockets.Thin`. Currently `GNAT.Sockets` is implemented +on all native GNAT ports and on VxWorks cross prots. It is not implemented for +the LynxOS cross port. + +.. _`GNAT.Source_Info_(g-souinf.ads)`: + +`GNAT.Source_Info` (:file:`g-souinf.ads`) +========================================= + +.. index:: GNAT.Source_Info (g-souinf.ads) + +.. index:: Source Information + +Provides subprograms that give access to source code information known at +compile time, such as the current file name and line number. Also provides +subprograms yielding the date and time of the current compilation (like the +C macros `__DATE__` and `__TIME__`) + +.. _`GNAT.Spelling_Checker_(g-speche.ads)`: + +`GNAT.Spelling_Checker` (:file:`g-speche.ads`) +============================================== + +.. index:: GNAT.Spelling_Checker (g-speche.ads) + +.. index:: Spell checking + +Provides a function for determining whether one string is a plausible +near misspelling of another string. + +.. _`GNAT.Spelling_Checker_Generic_(g-spchge.ads)`: + +`GNAT.Spelling_Checker_Generic` (:file:`g-spchge.ads`) +====================================================== + +.. index:: GNAT.Spelling_Checker_Generic (g-spchge.ads) + +.. index:: Spell checking + +Provides a generic function that can be instantiated with a string type for +determining whether one string is a plausible near misspelling of another +string. + +.. _`GNAT.Spitbol.Patterns_(g-spipat.ads)`: + +`GNAT.Spitbol.Patterns` (:file:`g-spipat.ads`) +============================================== + +.. index:: GNAT.Spitbol.Patterns (g-spipat.ads) + +.. index:: SPITBOL pattern matching + +.. index:: Pattern matching + +A complete implementation of SNOBOL4 style pattern matching. This is the +most elaborate of the pattern matching packages provided. It fully duplicates +the SNOBOL4 dynamic pattern construction and matching capabilities, using the +efficient algorithm developed by Robert Dewar for the SPITBOL system. + +.. _`GNAT.Spitbol_(g-spitbo.ads)`: + +`GNAT.Spitbol` (:file:`g-spitbo.ads`) +===================================== + +.. index:: GNAT.Spitbol (g-spitbo.ads) + +.. index:: SPITBOL interface + +The top level package of the collection of SPITBOL-style functionality, this +package provides basic SNOBOL4 string manipulation functions, such as +Pad, Reverse, Trim, Substr capability, as well as a generic table function +useful for constructing arbitrary mappings from strings in the style of +the SNOBOL4 TABLE function. + +.. _`GNAT.Spitbol.Table_Boolean_(g-sptabo.ads)`: + +`GNAT.Spitbol.Table_Boolean` (:file:`g-sptabo.ads`) +=================================================== + +.. index:: GNAT.Spitbol.Table_Boolean (g-sptabo.ads) + +.. index:: Sets of strings + +.. index:: SPITBOL Tables + +A library level of instantiation of `GNAT.Spitbol.Patterns.Table` +for type `Standard.Boolean`, giving an implementation of sets of +string values. + +.. _`GNAT.Spitbol.Table_Integer_(g-sptain.ads)`: + +`GNAT.Spitbol.Table_Integer` (:file:`g-sptain.ads`) +=================================================== + +.. index:: GNAT.Spitbol.Table_Integer (g-sptain.ads) + +.. index:: Integer maps + +.. index:: Maps + +.. index:: SPITBOL Tables + +A library level of instantiation of `GNAT.Spitbol.Patterns.Table` +for type `Standard.Integer`, giving an implementation of maps +from string to integer values. + +.. _`GNAT.Spitbol.Table_VString_(g-sptavs.ads)`: + +`GNAT.Spitbol.Table_VString` (:file:`g-sptavs.ads`) +=================================================== + +.. index:: GNAT.Spitbol.Table_VString (g-sptavs.ads) + +.. index:: String maps + +.. index:: Maps + +.. index:: SPITBOL Tables + +A library level of instantiation of `GNAT.Spitbol.Patterns.Table` for +a variable length string type, giving an implementation of general +maps from strings to strings. + +.. _`GNAT.SSE_(g-sse.ads)`: + +`GNAT.SSE` (:file:`g-sse.ads`) +============================== + +.. index:: GNAT.SSE (g-sse.ads) + +Root of a set of units aimed at offering Ada bindings to a subset of +the Intel(r) Streaming SIMD Extensions with GNAT on the x86 family of +targets. It exposes vector component types together with a general +introduction to the binding contents and use. + +.. _`GNAT.SSE.Vector_Types_(g-ssvety.ads)`: + +`GNAT.SSE.Vector_Types` (:file:`g-ssvety.ads`) +============================================== + +.. index:: GNAT.SSE.Vector_Types (g-ssvety.ads) + +SSE vector types for use with SSE related intrinsics. + +.. _`GNAT.Strings_(g-string.ads)`: + +`GNAT.Strings` (:file:`g-string.ads`) +===================================== + +.. index:: GNAT.Strings (g-string.ads) + +Common String access types and related subprograms. Basically it +defines a string access and an array of string access types. + +.. _`GNAT.String_Split_(g-strspl.ads)`: + +`GNAT.String_Split` (:file:`g-strspl.ads`) +========================================== + +.. index:: GNAT.String_Split (g-strspl.ads) + +.. index:: String splitter + +Useful string manipulation routines: given a set of separators, split +a string wherever the separators appear, and provide direct access +to the resulting slices. This package is instantiated from +`GNAT.Array_Split`. + +.. _`GNAT.Table_(g-table.ads)`: + +`GNAT.Table` (:file:`g-table.ads`) +================================== + +.. index:: GNAT.Table (g-table.ads) + +.. index:: Table implementation + +.. index:: Arrays, extendable + +A generic package providing a single dimension array abstraction where the +length of the array can be dynamically modified. + +This package provides a facility similar to that of `GNAT.Dynamic_Tables`, +except that this package declares a single instance of the table type, +while an instantiation of `GNAT.Dynamic_Tables` creates a type that can be +used to define dynamic instances of the table. + +.. _`GNAT.Task_Lock_(g-tasloc.ads)`: + +`GNAT.Task_Lock` (:file:`g-tasloc.ads`) +======================================= + +.. index:: GNAT.Task_Lock (g-tasloc.ads) + +.. index:: Task synchronization + +.. index:: Task locking + +.. index:: Locking + +A very simple facility for locking and unlocking sections of code using a +single global task lock. Appropriate for use in situations where contention +between tasks is very rarely expected. + +.. _`GNAT.Time_Stamp_(g-timsta.ads)`: + +`GNAT.Time_Stamp` (:file:`g-timsta.ads`) +======================================== + +.. index:: GNAT.Time_Stamp (g-timsta.ads) + +.. index:: Time stamp + +.. index:: Current time + +Provides a simple function that returns a string YYYY-MM-DD HH:MM:SS.SS that +represents the current date and time in ISO 8601 format. This is a very simple +routine with minimal code and there are no dependencies on any other unit. + +.. _`GNAT.Threads_(g-thread.ads)`: + +`GNAT.Threads` (:file:`g-thread.ads`) +===================================== + +.. index:: GNAT.Threads (g-thread.ads) + +.. index:: Foreign threads + +.. index:: Threads, foreign + +Provides facilities for dealing with foreign threads which need to be known +by the GNAT run-time system. Consult the documentation of this package for +further details if your program has threads that are created by a non-Ada +environment which then accesses Ada code. + +.. _`GNAT.Traceback_(g-traceb.ads)`: + +`GNAT.Traceback` (:file:`g-traceb.ads`) +======================================= + +.. index:: GNAT.Traceback (g-traceb.ads) + +.. index:: Trace back facilities + +Provides a facility for obtaining non-symbolic traceback information, useful +in various debugging situations. + +.. _`GNAT.Traceback.Symbolic_(g-trasym.ads)`: + +`GNAT.Traceback.Symbolic` (:file:`g-trasym.ads`) +================================================ + +.. index:: GNAT.Traceback.Symbolic (g-trasym.ads) + +.. index:: Trace back facilities + +.. _`GNAT.UTF_32_(g-table.ads)`: + +`GNAT.UTF_32` (:file:`g-table.ads`) +=================================== + +.. index:: GNAT.UTF_32 (g-table.ads) + +.. index:: Wide character codes + +This is a package intended to be used in conjunction with the +`Wide_Character` type in Ada 95 and the +`Wide_Wide_Character` type in Ada 2005 (available +in `GNAT` in Ada 2005 mode). This package contains +Unicode categorization routines, as well as lexical +categorization routines corresponding to the Ada 2005 +lexical rules for identifiers and strings, and also a +lower case to upper case fold routine corresponding to +the Ada 2005 rules for identifier equivalence. + +.. _`GNAT.Wide_Spelling_Checker_(g-u3spch.ads)`: + +`GNAT.Wide_Spelling_Checker` (:file:`g-u3spch.ads`) +=================================================== + +.. index:: GNAT.Wide_Spelling_Checker (g-u3spch.ads) + +.. index:: Spell checking + +Provides a function for determining whether one wide wide string is a plausible +near misspelling of another wide wide string, where the strings are represented +using the UTF_32_String type defined in System.Wch_Cnv. + +.. _`GNAT.Wide_Spelling_Checker_(g-wispch.ads)`: + +`GNAT.Wide_Spelling_Checker` (:file:`g-wispch.ads`) +=================================================== + +.. index:: GNAT.Wide_Spelling_Checker (g-wispch.ads) + +.. index:: Spell checking + +Provides a function for determining whether one wide string is a plausible +near misspelling of another wide string. + +.. _`GNAT.Wide_String_Split_(g-wistsp.ads)`: + +`GNAT.Wide_String_Split` (:file:`g-wistsp.ads`) +=============================================== + +.. index:: GNAT.Wide_String_Split (g-wistsp.ads) + +.. index:: Wide_String splitter + +Useful wide string manipulation routines: given a set of separators, split +a wide string wherever the separators appear, and provide direct access +to the resulting slices. This package is instantiated from +`GNAT.Array_Split`. + +.. _`GNAT.Wide_Wide_Spelling_Checker_(g-zspche.ads)`: + +`GNAT.Wide_Wide_Spelling_Checker` (:file:`g-zspche.ads`) +======================================================== + +.. index:: GNAT.Wide_Wide_Spelling_Checker (g-zspche.ads) + +.. index:: Spell checking + +Provides a function for determining whether one wide wide string is a plausible +near misspelling of another wide wide string. + +.. _`GNAT.Wide_Wide_String_Split_(g-zistsp.ads)`: + +`GNAT.Wide_Wide_String_Split` (:file:`g-zistsp.ads`) +==================================================== + +.. index:: GNAT.Wide_Wide_String_Split (g-zistsp.ads) + +.. index:: Wide_Wide_String splitter + +Useful wide wide string manipulation routines: given a set of separators, split +a wide wide string wherever the separators appear, and provide direct access +to the resulting slices. This package is instantiated from +`GNAT.Array_Split`. + +.. _`Interfaces.C.Extensions_(i-cexten.ads)`: + +`Interfaces.C.Extensions` (:file:`i-cexten.ads`) +================================================ + +.. index:: Interfaces.C.Extensions (i-cexten.ads) + +This package contains additional C-related definitions, intended +for use with either manually or automatically generated bindings +to C libraries. + +.. _`Interfaces.C.Streams_(i-cstrea.ads)`: + +`Interfaces.C.Streams` (:file:`i-cstrea.ads`) +============================================= + +.. index:: Interfaces.C.Streams (i-cstrea.ads) + +.. index:: C streams, interfacing + +This package is a binding for the most commonly used operations +on C streams. + +.. _`Interfaces.Packed_Decimal_(i-pacdec.ads)`: + +`Interfaces.Packed_Decimal` (:file:`i-pacdec.ads`) +================================================== + +.. index:: Interfaces.Packed_Decimal (i-pacdec.ads) + +.. index:: IBM Packed Format + +.. index:: Packed Decimal + +This package provides a set of routines for conversions to and +from a packed decimal format compatible with that used on IBM +mainframes. + +.. _`Interfaces.VxWorks_(i-vxwork.ads)`: + +`Interfaces.VxWorks` (:file:`i-vxwork.ads`) +=========================================== + +.. index:: Interfaces.VxWorks (i-vxwork.ads) + +.. index:: Interfacing to VxWorks + +.. index:: VxWorks, interfacing + +This package provides a limited binding to the VxWorks API. +In particular, it interfaces with the +VxWorks hardware interrupt facilities. + +.. _`Interfaces.VxWorks.IO_(i-vxwoio.ads)`: + +`Interfaces.VxWorks.IO` (:file:`i-vxwoio.ads`) +============================================== + +.. index:: Interfaces.VxWorks.IO (i-vxwoio.ads) + +.. index:: Interfacing to VxWorks' I/O + +.. index:: VxWorks, I/O interfacing + +.. index:: VxWorks, Get_Immediate + +.. index:: Get_Immediate, VxWorks + +This package provides a binding to the ioctl (IO/Control) +function of VxWorks, defining a set of option values and +function codes. A particular use of this package is +to enable the use of Get_Immediate under VxWorks. + +.. _`System.Address_Image_(s-addima.ads)`: + +`System.Address_Image` (:file:`s-addima.ads`) +============================================= + +.. index:: System.Address_Image (s-addima.ads) + +.. index:: Address image + +.. index:: Image, of an address + +This function provides a useful debugging +function that gives an (implementation dependent) +string which identifies an address. + +.. _`System.Assertions_(s-assert.ads)`: + +`System.Assertions` (:file:`s-assert.ads`) +========================================== + +.. index:: System.Assertions (s-assert.ads) + +.. index:: Assertions + +.. index:: Assert_Failure, exception + +This package provides the declaration of the exception raised +by an run-time assertion failure, as well as the routine that +is used internally to raise this assertion. + +.. _`System.Atomic_Counters_(s-atocou.ads)`: + +`System.Atomic_Counters` (:file:`s-atocou.ads`) +=============================================== + +.. index:: System.Atomic_Counters (s-atocou.ads) + +This package provides the declaration of an atomic counter type, +together with efficient routines (using hardware +synchronization primitives) for incrementing, decrementing, +and testing of these counters. This package is implemented +on most targets, including all Alpha, ia64, PowerPC, SPARC V9, +x86, and x86_64 platforms. + +.. _`System.Memory_(s-memory.ads)`: + +`System.Memory` (:file:`s-memory.ads`) +====================================== + +.. index:: System.Memory (s-memory.ads) + +.. index:: Memory allocation + +This package provides the interface to the low level routines used +by the generated code for allocation and freeing storage for the +default storage pool (analogous to the C routines malloc and free. +It also provides a reallocation interface analogous to the C routine +realloc. The body of this unit may be modified to provide alternative +allocation mechanisms for the default pool, and in addition, direct +calls to this unit may be made for low level allocation uses (for +example see the body of `GNAT.Tables`). + +.. _`System.Multiprocessors_(s-multip.ads)`: + +`System.Multiprocessors` (:file:`s-multip.ads`) +=============================================== + +.. index:: System.Multiprocessors (s-multip.ads) + +.. index:: Multiprocessor interface + +This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but +in GNAT we also make it available in Ada 95 and Ada 2005 (where it is +technically an implementation-defined addition). + +.. _`System.Multiprocessors.Dispatching_Domains_(s-mudido.ads)`: + +`System.Multiprocessors.Dispatching_Domains` (:file:`s-mudido.ads`) +=================================================================== + +.. index:: System.Multiprocessors.Dispatching_Domains (s-mudido.ads) + +.. index:: Multiprocessor interface + +This is an Ada 2012 unit defined in the Ada 2012 Reference Manual, but +in GNAT we also make it available in Ada 95 and Ada 2005 (where it is +technically an implementation-defined addition). + +.. _`System.Partition_Interface_(s-parint.ads)`: + +`System.Partition_Interface` (:file:`s-parint.ads`) +=================================================== + +.. index:: System.Partition_Interface (s-parint.ads) + +.. index:: Partition interfacing functions + +This package provides facilities for partition interfacing. It +is used primarily in a distribution context when using Annex E +with `GLADE`. + +.. _`System.Pool_Global_(s-pooglo.ads)`: + +`System.Pool_Global` (:file:`s-pooglo.ads`) +=========================================== + +.. index:: System.Pool_Global (s-pooglo.ads) + +.. index:: Storage pool, global + +.. index:: Global storage pool + +This package provides a storage pool that is equivalent to the default +storage pool used for access types for which no pool is specifically +declared. It uses malloc/free to allocate/free and does not attempt to +do any automatic reclamation. + +.. _`System.Pool_Local_(s-pooloc.ads)`: + +`System.Pool_Local` (:file:`s-pooloc.ads`) +========================================== + +.. index:: System.Pool_Local (s-pooloc.ads) + +.. index:: Storage pool, local + +.. index:: Local storage pool + +This package provides a storage pool that is intended for use with locally +defined access types. It uses malloc/free for allocate/free, and maintains +a list of allocated blocks, so that all storage allocated for the pool can +be freed automatically when the pool is finalized. + +.. _`System.Restrictions_(s-restri.ads)`: + +`System.Restrictions` (:file:`s-restri.ads`) +============================================ + +.. index:: System.Restrictions (s-restri.ads) + +.. index:: Run-time restrictions access + +This package provides facilities for accessing at run time +the status of restrictions specified at compile time for +the partition. Information is available both with regard +to actual restrictions specified, and with regard to +compiler determined information on which restrictions +are violated by one or more packages in the partition. + +.. _`System.Rident_(s-rident.ads)`: + +`System.Rident` (:file:`s-rident.ads`) +====================================== + +.. index:: System.Rident (s-rident.ads) + +.. index:: Restrictions definitions + +This package provides definitions of the restrictions +identifiers supported by GNAT, and also the format of +the restrictions provided in package System.Restrictions. +It is not normally necessary to `with` this generic package +since the necessary instantiation is included in +package System.Restrictions. + +.. _`System.Strings.Stream_Ops_(s-ststop.ads)`: + +`System.Strings.Stream_Ops` (:file:`s-ststop.ads`) +================================================== + +.. index:: System.Strings.Stream_Ops (s-ststop.ads) + +.. index:: Stream operations + +.. index:: String stream operations + +This package provides a set of stream subprograms for standard string types. +It is intended primarily to support implicit use of such subprograms when +stream attributes are applied to string types, but the subprograms in this +package can be used directly by application programs. + +.. _`System.Unsigned_Types_(s-unstyp.ads)`: + +`System.Unsigned_Types` (:file:`s-unstyp.ads`) +============================================== + +.. index:: System.Unsigned_Types (s-unstyp.ads) + +This package contains definitions of standard unsigned types that +correspond in size to the standard signed types declared in Standard, +and (unlike the types in Interfaces) have corresponding names. It +also contains some related definitions for other specialized types +used by the compiler in connection with packed array types. + +.. _`System.Wch_Cnv_(s-wchcnv.ads)`: + +`System.Wch_Cnv` (:file:`s-wchcnv.ads`) +======================================= + +.. index:: System.Wch_Cnv (s-wchcnv.ads) + +.. index:: Wide Character, Representation + +.. index:: Wide String, Conversion + +.. index:: Representation of wide characters + +This package provides routines for converting between +wide and wide wide characters and a representation as a value of type +`Standard.String`, using a specified wide character +encoding method. It uses definitions in +package `System.Wch_Con`. + +.. _`System.Wch_Con_(s-wchcon.ads)`: + +`System.Wch_Con` (:file:`s-wchcon.ads`) +======================================= + +.. index:: System.Wch_Con (s-wchcon.ads) + +This package provides definitions and descriptions of +the various methods used for encoding wide characters +in ordinary strings. These definitions are used by +the package `System.Wch_Cnv`. + diff --git a/gcc/ada/doc/gnat_rm/the_implementation_of_standard_i_o.rst b/gcc/ada/doc/gnat_rm/the_implementation_of_standard_i_o.rst new file mode 100644 index 00000000000..3d39876c2dd --- /dev/null +++ b/gcc/ada/doc/gnat_rm/the_implementation_of_standard_i_o.rst @@ -0,0 +1,1252 @@ +.. _The_Implementation_of_Standard_I/O: + +********************************** +The Implementation of Standard I/O +********************************** + +GNAT implements all the required input-output facilities described in +A.6 through A.14. These sections of the Ada Reference Manual describe the +required behavior of these packages from the Ada point of view, and if +you are writing a portable Ada program that does not need to know the +exact manner in which Ada maps to the outside world when it comes to +reading or writing external files, then you do not need to read this +chapter. As long as your files are all regular files (not pipes or +devices), and as long as you write and read the files only from Ada, the +description in the Ada Reference Manual is sufficient. + +However, if you want to do input-output to pipes or other devices, such +as the keyboard or screen, or if the files you are dealing with are +either generated by some other language, or to be read by some other +language, then you need to know more about the details of how the GNAT +implementation of these input-output facilities behaves. + +In this chapter we give a detailed description of exactly how GNAT +interfaces to the file system. As always, the sources of the system are +available to you for answering questions at an even more detailed level, +but for most purposes the information in this chapter will suffice. + +Another reason that you may need to know more about how input-output is +implemented arises when you have a program written in mixed languages +where, for example, files are shared between the C and Ada sections of +the same program. GNAT provides some additional facilities, in the form +of additional child library packages, that facilitate this sharing, and +these additional facilities are also described in this chapter. + +.. _Standard_I/O_Packages: + +Standard I/O Packages +===================== + +The Standard I/O packages described in Annex A for + +* + Ada.Text_IO +* + Ada.Text_IO.Complex_IO +* + Ada.Text_IO.Text_Streams +* + Ada.Wide_Text_IO +* + Ada.Wide_Text_IO.Complex_IO +* + Ada.Wide_Text_IO.Text_Streams +* + Ada.Wide_Wide_Text_IO +* + Ada.Wide_Wide_Text_IO.Complex_IO +* + Ada.Wide_Wide_Text_IO.Text_Streams +* + Ada.Stream_IO +* + Ada.Sequential_IO +* + Ada.Direct_IO + +are implemented using the C +library streams facility; where + +* + All files are opened using `fopen`. +* + All input/output operations use `fread`/`fwrite`. + +There is no internal buffering of any kind at the Ada library level. The only +buffering is that provided at the system level in the implementation of the +library routines that support streams. This facilitates shared use of these +streams by mixed language programs. Note though that system level buffering is +explicitly enabled at elaboration of the standard I/O packages and that can +have an impact on mixed language programs, in particular those using I/O before +calling the Ada elaboration routine (e.g., adainit). It is recommended to call +the Ada elaboration routine before performing any I/O or when impractical, +flush the common I/O streams and in particular Standard_Output before +elaborating the Ada code. + +.. _FORM_Strings: + +FORM Strings +============ + +The format of a FORM string in GNAT is: + + +:: + + "keyword=value,keyword=value,...,keyword=value" + + +where letters may be in upper or lower case, and there are no spaces +between values. The order of the entries is not important. Currently +the following keywords defined. + + +:: + + TEXT_TRANSLATION=[YES|NO|TEXT|BINARY|U8TEXT|WTEXT|U16TEXT] + SHARED=[YES|NO] + WCEM=[n|h|u|s|e|8|b] + ENCODING=[UTF8|8BITS] + + +The use of these parameters is described later in this section. If an +unrecognized keyword appears in a form string, it is silently ignored +and not considered invalid. + +.. _Direct_IO: + +Direct_IO +========= + +Direct_IO can only be instantiated for definite types. This is a +restriction of the Ada language, which means that the records are fixed +length (the length being determined by ``type'Size``, rounded +up to the next storage unit boundary if necessary). + +The records of a Direct_IO file are simply written to the file in index +sequence, with the first record starting at offset zero, and subsequent +records following. There is no control information of any kind. For +example, if 32-bit integers are being written, each record takes +4-bytes, so the record at index `K` starts at offset +(`K`-1)*4. + +There is no limit on the size of Direct_IO files, they are expanded as +necessary to accommodate whatever records are written to the file. + +.. _Sequential_IO: + +Sequential_IO +============= + +Sequential_IO may be instantiated with either a definite (constrained) +or indefinite (unconstrained) type. + +For the definite type case, the elements written to the file are simply +the memory images of the data values with no control information of any +kind. The resulting file should be read using the same type, no validity +checking is performed on input. + +For the indefinite type case, the elements written consist of two +parts. First is the size of the data item, written as the memory image +of a `Interfaces.C.size_t` value, followed by the memory image of +the data value. The resulting file can only be read using the same +(unconstrained) type. Normal assignment checks are performed on these +read operations, and if these checks fail, `Data_Error` is +raised. In particular, in the array case, the lengths must match, and in +the variant record case, if the variable for a particular read operation +is constrained, the discriminants must match. + +Note that it is not possible to use Sequential_IO to write variable +length array items, and then read the data back into different length +arrays. For example, the following will raise `Data_Error`: + + +.. code-block:: ada + + package IO is new Sequential_IO (String); + F : IO.File_Type; + S : String (1..4); + ... + IO.Create (F) + IO.Write (F, "hello!") + IO.Reset (F, Mode=>In_File); + IO.Read (F, S); + Put_Line (S); + + + +On some Ada implementations, this will print `hell`, but the program is +clearly incorrect, since there is only one element in the file, and that +element is the string `hello!`. + +In Ada 95 and Ada 2005, this kind of behavior can be legitimately achieved +using Stream_IO, and this is the preferred mechanism. In particular, the +above program fragment rewritten to use Stream_IO will work correctly. + +.. _Text_IO: + +Text_IO +======= + +Text_IO files consist of a stream of characters containing the following +special control characters: + + +:: + + LF (line feed, 16#0A#) Line Mark + FF (form feed, 16#0C#) Page Mark + + +A canonical Text_IO file is defined as one in which the following +conditions are met: + +* + The character `LF` is used only as a line mark, i.e., to mark the end + of the line. + +* + The character `FF` is used only as a page mark, i.e., to mark the + end of a page and consequently can appear only immediately following a + `LF` (line mark) character. + +* + The file ends with either `LF` (line mark) or `LF`-`FF` + (line mark, page mark). In the former case, the page mark is implicitly + assumed to be present. + +A file written using Text_IO will be in canonical form provided that no +explicit `LF` or `FF` characters are written using `Put` +or `Put_Line`. There will be no `FF` character at the end of +the file unless an explicit `New_Page` operation was performed +before closing the file. + +A canonical Text_IO file that is a regular file (i.e., not a device or a +pipe) can be read using any of the routines in Text_IO. The +semantics in this case will be exactly as defined in the Ada Reference +Manual, and all the routines in Text_IO are fully implemented. + +A text file that does not meet the requirements for a canonical Text_IO +file has one of the following: + +* + The file contains `FF` characters not immediately following a + `LF` character. + +* + The file contains `LF` or `FF` characters written by + `Put` or `Put_Line`, which are not logically considered to be + line marks or page marks. + +* + The file ends in a character other than `LF` or `FF`, + i.e., there is no explicit line mark or page mark at the end of the file. + +Text_IO can be used to read such non-standard text files but subprograms +to do with line or page numbers do not have defined meanings. In +particular, a `FF` character that does not follow a `LF` +character may or may not be treated as a page mark from the point of +view of page and line numbering. Every `LF` character is considered +to end a line, and there is an implied `LF` character at the end of +the file. + +.. _Stream_Pointer_Positioning: + +Stream Pointer Positioning +-------------------------- + +`Ada.Text_IO` has a definition of current position for a file that +is being read. No internal buffering occurs in Text_IO, and usually the +physical position in the stream used to implement the file corresponds +to this logical position defined by Text_IO. There are two exceptions: + +* + After a call to `End_Of_Page` that returns `True`, the stream + is positioned past the `LF` (line mark) that precedes the page + mark. Text_IO maintains an internal flag so that subsequent read + operations properly handle the logical position which is unchanged by + the `End_Of_Page` call. + +* + After a call to `End_Of_File` that returns `True`, if the + Text_IO file was positioned before the line mark at the end of file + before the call, then the logical position is unchanged, but the stream + is physically positioned right at the end of file (past the line mark, + and past a possible page mark following the line mark. Again Text_IO + maintains internal flags so that subsequent read operations properly + handle the logical position. + +These discrepancies have no effect on the observable behavior of +Text_IO, but if a single Ada stream is shared between a C program and +Ada program, or shared (using ``shared=yes`` in the form string) +between two Ada files, then the difference may be observable in some +situations. + +.. _Reading_and_Writing_Non-Regular_Files: + +Reading and Writing Non-Regular Files +------------------------------------- + +A non-regular file is a device (such as a keyboard), or a pipe. Text_IO +can be used for reading and writing. Writing is not affected and the +sequence of characters output is identical to the normal file case, but +for reading, the behavior of Text_IO is modified to avoid undesirable +look-ahead as follows: + +An input file that is not a regular file is considered to have no page +marks. Any `Ascii.FF` characters (the character normally used for a +page mark) appearing in the file are considered to be data +characters. In particular: + +* + `Get_Line` and `Skip_Line` do not test for a page mark + following a line mark. If a page mark appears, it will be treated as a + data character. + +* + This avoids the need to wait for an extra character to be typed or + entered from the pipe to complete one of these operations. + +* + `End_Of_Page` always returns `False` + +* + `End_Of_File` will return `False` if there is a page mark at + the end of the file. + +Output to non-regular files is the same as for regular files. Page marks +may be written to non-regular files using `New_Page`, but as noted +above they will not be treated as page marks on input if the output is +piped to another Ada program. + +Another important discrepancy when reading non-regular files is that the end +of file indication is not 'sticky'. If an end of file is entered, e.g., by +pressing the :kbd:`EOT` key, +then end of file +is signaled once (i.e., the test `End_Of_File` +will yield `True`, or a read will +raise `End_Error`), but then reading can resume +to read data past that end of +file indication, until another end of file indication is entered. + +.. _Get_Immediate: + +Get_Immediate +------------- + +.. index:: Get_Immediate + +Get_Immediate returns the next character (including control characters) +from the input file. In particular, Get_Immediate will return LF or FF +characters used as line marks or page marks. Such operations leave the +file positioned past the control character, and it is thus not treated +as having its normal function. This means that page, line and column +counts after this kind of Get_Immediate call are set as though the mark +did not occur. In the case where a Get_Immediate leaves the file +positioned between the line mark and page mark (which is not normally +possible), it is undefined whether the FF character will be treated as a +page mark. + +.. _Treating_Text_IO_Files_as_Streams: + +Treating Text_IO Files as Streams +--------------------------------- + +.. index:: Stream files + +The package `Text_IO.Streams` allows a Text_IO file to be treated +as a stream. Data written to a Text_IO file in this stream mode is +binary data. If this binary data contains bytes 16#0A# (`LF`) or +16#0C# (`FF`), the resulting file may have non-standard +format. Similarly if read operations are used to read from a Text_IO +file treated as a stream, then `LF` and `FF` characters may be +skipped and the effect is similar to that described above for +`Get_Immediate`. + +.. _Text_IO_Extensions: + +Text_IO Extensions +------------------ + +.. index:: Text_IO extensions + +A package GNAT.IO_Aux in the GNAT library provides some useful extensions +to the standard `Text_IO` package: + +* function File_Exists (Name : String) return Boolean; + Determines if a file of the given name exists. + +* function Get_Line return String; + Reads a string from the standard input file. The value returned is exactly + the length of the line that was read. + +* function Get_Line (File : Ada.Text_IO.File_Type) return String; + Similar, except that the parameter File specifies the file from which + the string is to be read. + + +.. _Text_IO_Facilities_for_Unbounded_Strings: + +Text_IO Facilities for Unbounded Strings +---------------------------------------- + +.. index:: Text_IO for unbounded strings + +.. index:: Unbounded_String, Text_IO operations + +The package `Ada.Strings.Unbounded.Text_IO` +in library files `a-suteio.ads/adb` contains some GNAT-specific +subprograms useful for Text_IO operations on unbounded strings: + + +* function Get_Line (File : File_Type) return Unbounded_String; + Reads a line from the specified file + and returns the result as an unbounded string. + +* procedure Put (File : File_Type; U : Unbounded_String); + Writes the value of the given unbounded string to the specified file + Similar to the effect of + `Put (To_String (U))` except that an extra copy is avoided. + +* procedure Put_Line (File : File_Type; U : Unbounded_String); + Writes the value of the given unbounded string to the specified file, + followed by a `New_Line`. + Similar to the effect of `Put_Line (To_String (U))` except + that an extra copy is avoided. + +In the above procedures, `File` is of type `Ada.Text_IO.File_Type` +and is optional. If the parameter is omitted, then the standard input or +output file is referenced as appropriate. + +The package `Ada.Strings.Wide_Unbounded.Wide_Text_IO` in library +files :file:`a-swuwti.ads` and :file:`a-swuwti.adb` provides similar extended +`Wide_Text_IO` functionality for unbounded wide strings. + +The package `Ada.Strings.Wide_Wide_Unbounded.Wide_Wide_Text_IO` in library +files :file:`a-szuzti.ads` and :file:`a-szuzti.adb` provides similar extended +`Wide_Wide_Text_IO` functionality for unbounded wide wide strings. + +.. _Wide_Text_IO: + +Wide_Text_IO +============ + +`Wide_Text_IO` is similar in most respects to Text_IO, except that +both input and output files may contain special sequences that represent +wide character values. The encoding scheme for a given file may be +specified using a FORM parameter: + + +:: + + WCEM=`x` + + +as part of the FORM string (WCEM = wide character encoding method), +where `x` is one of the following characters + +========== ==================== +Character Encoding +========== ==================== +*h* Hex ESC encoding +*u* Upper half encoding +*s* Shift-JIS encoding +*e* EUC Encoding +*8* UTF-8 encoding +*b* Brackets encoding +========== ==================== + +The encoding methods match those that +can be used in a source +program, but there is no requirement that the encoding method used for +the source program be the same as the encoding method used for files, +and different files may use different encoding methods. + +The default encoding method for the standard files, and for opened files +for which no WCEM parameter is given in the FORM string matches the +wide character encoding specified for the main program (the default +being brackets encoding if no coding method was specified with -gnatW). + + + +*Hex Coding* + In this encoding, a wide character is represented by a five character + sequence: + + +:: + + ESC a b c d + +.. + + where `a`, `b`, `c`, `d` are the four hexadecimal + characters (using upper case letters) of the wide character code. For + example, ESC A345 is used to represent the wide character with code + 16#A345#. This scheme is compatible with use of the full + `Wide_Character` set. + + +*Upper Half Coding* + The wide character with encoding 16#abcd#, where the upper bit is on + (i.e., a is in the range 8-F) is represented as two bytes 16#ab# and + 16#cd#. The second byte may never be a format control character, but is + not required to be in the upper half. This method can be also used for + shift-JIS or EUC where the internal coding matches the external coding. + + +*Shift JIS Coding* + A wide character is represented by a two character sequence 16#ab# and + 16#cd#, with the restrictions described for upper half encoding as + described above. The internal character code is the corresponding JIS + character according to the standard algorithm for Shift-JIS + conversion. Only characters defined in the JIS code set table can be + used with this encoding method. + + +*EUC Coding* + A wide character is represented by a two character sequence 16#ab# and + 16#cd#, with both characters being in the upper half. The internal + character code is the corresponding JIS character according to the EUC + encoding algorithm. Only characters defined in the JIS code set table + can be used with this encoding method. + + +*UTF-8 Coding* + A wide character is represented using + UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO + 10646-1/Am.2. Depending on the character value, the representation + is a one, two, or three byte sequence: + + +:: + + 16#0000#-16#007f#: 2#0xxxxxxx# + 16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx# + 16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# + +.. + + where the `xxx` bits correspond to the left-padded bits of the + 16-bit character value. Note that all lower half ASCII characters + are represented as ASCII bytes and all upper half characters and + other wide characters are represented as sequences of upper-half + (The full UTF-8 scheme allows for encoding 31-bit characters as + 6-byte sequences, but in this implementation, all UTF-8 sequences + of four or more bytes length will raise a Constraint_Error, as + will all invalid UTF-8 sequences.) + + +*Brackets Coding* + In this encoding, a wide character is represented by the following eight + character sequence: + + +:: + + [ " a b c d " ] + +.. + + where `a`, `b`, `c`, `d` are the four hexadecimal + characters (using uppercase letters) of the wide character code. For + example, `["A345"]` is used to represent the wide character with code + `16#A345#`. + This scheme is compatible with use of the full Wide_Character set. + On input, brackets coding can also be used for upper half characters, + e.g., `["C1"]` for lower case a. However, on output, brackets notation + is only used for wide characters with a code greater than `16#FF#`. + + Note that brackets coding is not normally used in the context of + Wide_Text_IO or Wide_Wide_Text_IO, since it is really just designed as + a portable way of encoding source files. In the context of Wide_Text_IO + or Wide_Wide_Text_IO, it can only be used if the file does not contain + any instance of the left bracket character other than to encode wide + character values using the brackets encoding method. In practice it is + expected that some standard wide character encoding method such + as UTF-8 will be used for text input output. + + If brackets notation is used, then any occurrence of a left bracket + in the input file which is not the start of a valid wide character + sequence will cause Constraint_Error to be raised. It is possible to + encode a left bracket as ["5B"] and Wide_Text_IO and Wide_Wide_Text_IO + input will interpret this as a left bracket. + + However, when a left bracket is output, it will be output as a left bracket + and not as ["5B"]. We make this decision because for normal use of + Wide_Text_IO for outputting messages, it is unpleasant to clobber left + brackets. For example, if we write: + + + .. code-block:: ada + + Put_Line ("Start of output [first run]"); + + + we really do not want to have the left bracket in this message clobbered so + that the output reads: + + +:: + + Start of output ["5B"]first run] + +.. + + In practice brackets encoding is reasonably useful for normal Put_Line use + since we won't get confused between left brackets and wide character + sequences in the output. But for input, or when files are written out + and read back in, it really makes better sense to use one of the standard + encoding methods such as UTF-8. + + +For the coding schemes other than UTF-8, Hex, or Brackets encoding, +not all wide character +values can be represented. An attempt to output a character that cannot +be represented using the encoding scheme for the file causes +Constraint_Error to be raised. An invalid wide character sequence on +input also causes Constraint_Error to be raised. + +.. _Stream_Pointer_Positioning_1: + +Stream Pointer Positioning +-------------------------- + +`Ada.Wide_Text_IO` is similar to `Ada.Text_IO` in its handling +of stream pointer positioning (:ref:`Text_IO`). There is one additional +case: + +If `Ada.Wide_Text_IO.Look_Ahead` reads a character outside the +normal lower ASCII set (i.e., a character in the range: + + +.. code-block:: ada + + Wide_Character'Val (16#0080#) .. Wide_Character'Val (16#FFFF#) + + +then although the logical position of the file pointer is unchanged by +the `Look_Ahead` call, the stream is physically positioned past the +wide character sequence. Again this is to avoid the need for buffering +or backup, and all `Wide_Text_IO` routines check the internal +indication that this situation has occurred so that this is not visible +to a normal program using `Wide_Text_IO`. However, this discrepancy +can be observed if the wide text file shares a stream with another file. + +.. _Reading_and_Writing_Non-Regular_Files_1: + +Reading and Writing Non-Regular Files +------------------------------------- + +As in the case of Text_IO, when a non-regular file is read, it is +assumed that the file contains no page marks (any form characters are +treated as data characters), and `End_Of_Page` always returns +`False`. Similarly, the end of file indication is not sticky, so +it is possible to read beyond an end of file. + +.. _Wide_Wide_Text_IO: + +Wide_Wide_Text_IO +================= + +`Wide_Wide_Text_IO` is similar in most respects to Text_IO, except that +both input and output files may contain special sequences that represent +wide wide character values. The encoding scheme for a given file may be +specified using a FORM parameter: + + +:: + + WCEM=`x` + + +as part of the FORM string (WCEM = wide character encoding method), +where `x` is one of the following characters + +========== ==================== +Character Encoding +========== ==================== +*h* Hex ESC encoding +*u* Upper half encoding +*s* Shift-JIS encoding +*e* EUC Encoding +*8* UTF-8 encoding +*b* Brackets encoding +========== ==================== + + +The encoding methods match those that +can be used in a source +program, but there is no requirement that the encoding method used for +the source program be the same as the encoding method used for files, +and different files may use different encoding methods. + +The default encoding method for the standard files, and for opened files +for which no WCEM parameter is given in the FORM string matches the +wide character encoding specified for the main program (the default +being brackets encoding if no coding method was specified with -gnatW). + + + +*UTF-8 Coding* + A wide character is represented using + UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO + 10646-1/Am.2. Depending on the character value, the representation + is a one, two, three, or four byte sequence: + + +:: + + 16#000000#-16#00007f#: 2#0xxxxxxx# + 16#000080#-16#0007ff#: 2#110xxxxx# 2#10xxxxxx# + 16#000800#-16#00ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx# + 16#010000#-16#10ffff#: 2#11110xxx# 2#10xxxxxx# 2#10xxxxxx# 2#10xxxxxx# + +.. + + where the `xxx` bits correspond to the left-padded bits of the + 21-bit character value. Note that all lower half ASCII characters + are represented as ASCII bytes and all upper half characters and + other wide characters are represented as sequences of upper-half + characters. + + +*Brackets Coding* + In this encoding, a wide wide character is represented by the following eight + character sequence if is in wide character range + + +:: + + [ " a b c d " ] + +.. + + and by the following ten character sequence if not + + +:: + + [ " a b c d e f " ] + +.. + + where `a`, `b`, `c`, `d`, `e`, and `f` + are the four or six hexadecimal + characters (using uppercase letters) of the wide wide character code. For + example, `["01A345"]` is used to represent the wide wide character + with code `16#01A345#`. + + This scheme is compatible with use of the full Wide_Wide_Character set. + On input, brackets coding can also be used for upper half characters, + e.g., `["C1"]` for lower case a. However, on output, brackets notation + is only used for wide characters with a code greater than `16#FF#`. + + +If is also possible to use the other Wide_Character encoding methods, +such as Shift-JIS, but the other schemes cannot support the full range +of wide wide characters. +An attempt to output a character that cannot +be represented using the encoding scheme for the file causes +Constraint_Error to be raised. An invalid wide character sequence on +input also causes Constraint_Error to be raised. + +.. _Stream_Pointer_Positioning_2: + +Stream Pointer Positioning +-------------------------- + +`Ada.Wide_Wide_Text_IO` is similar to `Ada.Text_IO` in its handling +of stream pointer positioning (:ref:`Text_IO`). There is one additional +case: + +If `Ada.Wide_Wide_Text_IO.Look_Ahead` reads a character outside the +normal lower ASCII set (i.e., a character in the range: + + +.. code-block:: ada + + Wide_Wide_Character'Val (16#0080#) .. Wide_Wide_Character'Val (16#10FFFF#) + + +then although the logical position of the file pointer is unchanged by +the `Look_Ahead` call, the stream is physically positioned past the +wide character sequence. Again this is to avoid the need for buffering +or backup, and all `Wide_Wide_Text_IO` routines check the internal +indication that this situation has occurred so that this is not visible +to a normal program using `Wide_Wide_Text_IO`. However, this discrepancy +can be observed if the wide text file shares a stream with another file. + +.. _Reading_and_Writing_Non-Regular_Files_2: + +Reading and Writing Non-Regular Files +------------------------------------- + +As in the case of Text_IO, when a non-regular file is read, it is +assumed that the file contains no page marks (any form characters are +treated as data characters), and `End_Of_Page` always returns +`False`. Similarly, the end of file indication is not sticky, so +it is possible to read beyond an end of file. + +.. _Stream_IO: + +Stream_IO +========= + +A stream file is a sequence of bytes, where individual elements are +written to the file as described in the Ada Reference Manual. The type +`Stream_Element` is simply a byte. There are two ways to read or +write a stream file. + +* + The operations `Read` and `Write` directly read or write a + sequence of stream elements with no control information. + +* + The stream attributes applied to a stream file transfer data in the + manner described for stream attributes. + +.. _Text_Translation: + +Text Translation +================ + +``Text_Translation=xxx`` may be used as the Form parameter +passed to Text_IO.Create and Text_IO.Open. ``Text_Translation=xxx`` +has no effect on Unix systems. Possible values are: + + +* + ``Yes`` or ``Text`` is the default, which means to + translate LF to/from CR/LF on Windows systems. + + ``No`` disables this translation; i.e. it + uses binary mode. For output files, ``Text_Translation=No`` + may be used to create Unix-style files on + Windows. + +* + ``wtext`` translation enabled in Unicode mode. + (corresponds to _O_WTEXT). + +* + ``u8text`` translation enabled in Unicode UTF-8 mode. + (corresponds to O_U8TEXT). + +* + ``u16text`` translation enabled in Unicode UTF-16 + mode. (corresponds to_O_U16TEXT). + + +.. _Shared_Files: + +Shared Files +============ + +Section A.14 of the Ada Reference Manual allows implementations to +provide a wide variety of behavior if an attempt is made to access the +same external file with two or more internal files. + +To provide a full range of functionality, while at the same time +minimizing the problems of portability caused by this implementation +dependence, GNAT handles file sharing as follows: + +* + In the absence of a ``shared=xxx`` form parameter, an attempt + to open two or more files with the same full name is considered an error + and is not supported. The exception `Use_Error` will be + raised. Note that a file that is not explicitly closed by the program + remains open until the program terminates. + +* + If the form parameter ``shared=no`` appears in the form string, the + file can be opened or created with its own separate stream identifier, + regardless of whether other files sharing the same external file are + opened. The exact effect depends on how the C stream routines handle + multiple accesses to the same external files using separate streams. + +* + If the form parameter ``shared=yes`` appears in the form string for + each of two or more files opened using the same full name, the same + stream is shared between these files, and the semantics are as described + in Ada Reference Manual, Section A.14. + +When a program that opens multiple files with the same name is ported +from another Ada compiler to GNAT, the effect will be that +`Use_Error` is raised. + +The documentation of the original compiler and the documentation of the +program should then be examined to determine if file sharing was +expected, and ``shared=xxx`` parameters added to `Open` +and `Create` calls as required. + +When a program is ported from GNAT to some other Ada compiler, no +special attention is required unless the ``shared=xxx`` form +parameter is used in the program. In this case, you must examine the +documentation of the new compiler to see if it supports the required +file sharing semantics, and form strings modified appropriately. Of +course it may be the case that the program cannot be ported if the +target compiler does not support the required functionality. The best +approach in writing portable code is to avoid file sharing (and hence +the use of the ``shared=xxx`` parameter in the form string) +completely. + +One common use of file sharing in Ada 83 is the use of instantiations of +Sequential_IO on the same file with different types, to achieve +heterogeneous input-output. Although this approach will work in GNAT if +``shared=yes`` is specified, it is preferable in Ada to use Stream_IO +for this purpose (using the stream attributes) + +.. _Filenames_encoding: + +Filenames encoding +================== + +An encoding form parameter can be used to specify the filename +encoding ``encoding=xxx``. + +* + If the form parameter ``encoding=utf8`` appears in the form string, the + filename must be encoded in UTF-8. + +* + If the form parameter ``encoding=8bits`` appears in the form + string, the filename must be a standard 8bits string. + +In the absence of a ``encoding=xxx`` form parameter, the +encoding is controlled by the ``GNAT_CODE_PAGE`` environment +variable. And if not set ``utf8`` is assumed. + + + +*CP_ACP* + The current system Windows ANSI code page. + +*CP_UTF8* + UTF-8 encoding + +This encoding form parameter is only supported on the Windows +platform. On the other Operating Systems the run-time is supporting +UTF-8 natively. + +.. _File_content_encoding: + +File content encoding +===================== + +For text files it is possible to specify the encoding to use. This is +controlled by the by the ``GNAT_CCS_ENCODING`` environment +variable. And if not set ``TEXT`` is assumed. + +The possible values are those supported on Windows: + + + +*TEXT* + Translated text mode + +*WTEXT* + Translated unicode encoding + +*U16TEXT* + Unicode 16-bit encoding + +*U8TEXT* + Unicode 8-bit encoding + +This encoding is only supported on the Windows platform. + +.. _Open_Modes: + +Open Modes +========== + +`Open` and `Create` calls result in a call to `fopen` +using the mode shown in the following table: + ++----------------------------+---------------+------------------+ +| `Open` and `Create` Call Modes | ++----------------------------+---------------+------------------+ +| | **OPEN** | **CREATE** | ++============================+===============+==================+ +| Append_File | "r+" | "w+" | ++----------------------------+---------------+------------------+ +| In_File | "r" | "w+" | ++----------------------------+---------------+------------------+ +| Out_File (Direct_IO) | "r+" | "w" | ++----------------------------+---------------+------------------+ +| Out_File (all other cases) | "w" | "w" | ++----------------------------+---------------+------------------+ +| Inout_File | "r+" | "w+" | ++----------------------------+---------------+------------------+ + + +If text file translation is required, then either ``b`` or ``t`` +is added to the mode, depending on the setting of Text. Text file +translation refers to the mapping of CR/LF sequences in an external file +to LF characters internally. This mapping only occurs in DOS and +DOS-like systems, and is not relevant to other systems. + +A special case occurs with Stream_IO. As shown in the above table, the +file is initially opened in ``r`` or ``w`` mode for the +`In_File` and `Out_File` cases. If a `Set_Mode` operation +subsequently requires switching from reading to writing or vice-versa, +then the file is reopened in ``r+`` mode to permit the required operation. + +.. _Operations_on_C_Streams: + +Operations on C Streams +======================= + +The package `Interfaces.C_Streams` provides an Ada program with direct +access to the C library functions for operations on C streams: + + +.. code-block:: ada + + package Interfaces.C_Streams is + -- Note: the reason we do not use the types that are in + -- Interfaces.C is that we want to avoid dragging in the + -- code in this unit if possible. + subtype chars is System.Address; + -- Pointer to null-terminated array of characters + subtype FILEs is System.Address; + -- Corresponds to the C type FILE* + subtype voids is System.Address; + -- Corresponds to the C type void* + subtype int is Integer; + subtype long is Long_Integer; + -- Note: the above types are subtypes deliberately, and it + -- is part of this spec that the above correspondences are + -- guaranteed. This means that it is legitimate to, for + -- example, use Integer instead of int. We provide these + -- synonyms for clarity, but in some cases it may be + -- convenient to use the underlying types (for example to + -- avoid an unnecessary dependency of a spec on the spec + -- of this unit). + type size_t is mod 2 ** Standard'Address_Size; + NULL_Stream : constant FILEs; + -- Value returned (NULL in C) to indicate an + -- fdopen/fopen/tmpfile error + ---------------------------------- + -- Constants Defined in stdio.h -- + ---------------------------------- + EOF : constant int; + -- Used by a number of routines to indicate error or + -- end of file + IOFBF : constant int; + IOLBF : constant int; + IONBF : constant int; + -- Used to indicate buffering mode for setvbuf call + SEEK_CUR : constant int; + SEEK_END : constant int; + SEEK_SET : constant int; + -- Used to indicate origin for fseek call + function stdin return FILEs; + function stdout return FILEs; + function stderr return FILEs; + -- Streams associated with standard files + -------------------------- + -- Standard C functions -- + -------------------------- + -- The functions selected below are ones that are + -- available in UNIX (but not necessarily in ANSI C). + -- These are very thin interfaces + -- which copy exactly the C headers. For more + -- documentation on these functions, see the Microsoft C + -- "Run-Time Library Reference" (Microsoft Press, 1990, + -- ISBN 1-55615-225-6), which includes useful information + -- on system compatibility. + procedure clearerr (stream : FILEs); + function fclose (stream : FILEs) return int; + function fdopen (handle : int; mode : chars) return FILEs; + function feof (stream : FILEs) return int; + function ferror (stream : FILEs) return int; + function fflush (stream : FILEs) return int; + function fgetc (stream : FILEs) return int; + function fgets (strng : chars; n : int; stream : FILEs) + return chars; + function fileno (stream : FILEs) return int; + function fopen (filename : chars; Mode : chars) + return FILEs; + -- Note: to maintain target independence, use + -- text_translation_required, a boolean variable defined in + -- a-sysdep.c to deal with the target dependent text + -- translation requirement. If this variable is set, + -- then b/t should be appended to the standard mode + -- argument to set the text translation mode off or on + -- as required. + function fputc (C : int; stream : FILEs) return int; + function fputs (Strng : chars; Stream : FILEs) return int; + function fread + (buffer : voids; + size : size_t; + count : size_t; + stream : FILEs) + return size_t; + function freopen + (filename : chars; + mode : chars; + stream : FILEs) + return FILEs; + function fseek + (stream : FILEs; + offset : long; + origin : int) + return int; + function ftell (stream : FILEs) return long; + function fwrite + (buffer : voids; + size : size_t; + count : size_t; + stream : FILEs) + return size_t; + function isatty (handle : int) return int; + procedure mktemp (template : chars); + -- The return value (which is just a pointer to template) + -- is discarded + procedure rewind (stream : FILEs); + function rmtmp return int; + function setvbuf + (stream : FILEs; + buffer : chars; + mode : int; + size : size_t) + return int; + + function tmpfile return FILEs; + function ungetc (c : int; stream : FILEs) return int; + function unlink (filename : chars) return int; + --------------------- + -- Extra functions -- + --------------------- + -- These functions supply slightly thicker bindings than + -- those above. They are derived from functions in the + -- C Run-Time Library, but may do a bit more work than + -- just directly calling one of the Library functions. + function is_regular_file (handle : int) return int; + -- Tests if given handle is for a regular file (result 1) + -- or for a non-regular file (pipe or device, result 0). + --------------------------------- + -- Control of Text/Binary Mode -- + --------------------------------- + -- If text_translation_required is true, then the following + -- functions may be used to dynamically switch a file from + -- binary to text mode or vice versa. These functions have + -- no effect if text_translation_required is false (i.e., in + -- normal UNIX mode). Use fileno to get a stream handle. + procedure set_binary_mode (handle : int); + procedure set_text_mode (handle : int); + ---------------------------- + -- Full Path Name support -- + ---------------------------- + procedure full_name (nam : chars; buffer : chars); + -- Given a NUL terminated string representing a file + -- name, returns in buffer a NUL terminated string + -- representing the full path name for the file name. + -- On systems where it is relevant the drive is also + -- part of the full path name. It is the responsibility + -- of the caller to pass an actual parameter for buffer + -- that is big enough for any full path name. Use + -- max_path_len given below as the size of buffer. + max_path_len : integer; + -- Maximum length of an allowable full path name on the + -- system, including a terminating NUL character. + end Interfaces.C_Streams; + + +.. _Interfacing_to_C_Streams: + +Interfacing to C Streams +======================== + +The packages in this section permit interfacing Ada files to C Stream +operations. + + +.. code-block:: ada + + with Interfaces.C_Streams; + package Ada.Sequential_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Sequential_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Direct_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Direct_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Text_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Text_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Wide_Text_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Wide_Text_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Wide_Wide_Text_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Wide_Wide_Text_IO.C_Streams; + + with Interfaces.C_Streams; + package Ada.Stream_IO.C_Streams is + function C_Stream (F : File_Type) + return Interfaces.C_Streams.FILEs; + procedure Open + (File : in out File_Type; + Mode : in File_Mode; + C_Stream : in Interfaces.C_Streams.FILEs; + Form : in String := ""); + end Ada.Stream_IO.C_Streams; + + +In each of these six packages, the `C_Stream` function obtains the +`FILE` pointer from a currently opened Ada file. It is then +possible to use the `Interfaces.C_Streams` package to operate on +this stream, or the stream can be passed to a C program which can +operate on it directly. Of course the program is responsible for +ensuring that only appropriate sequences of operations are executed. + +One particular use of relevance to an Ada program is that the +`setvbuf` function can be used to control the buffering of the +stream used by an Ada file. In the absence of such a call the standard +default buffering is used. + +The `Open` procedures in these packages open a file giving an +existing C Stream instead of a file name. Typically this stream is +imported from a C program, allowing an Ada file to operate on an +existing C file. + diff --git a/gcc/ada/doc/gnat_ugn.rst b/gcc/ada/doc/gnat_ugn.rst new file mode 100644 index 00000000000..7892160b477 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn.rst @@ -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> + + diff --git a/gcc/ada/doc/gnat_ugn/about_this_guide.rst b/gcc/ada/doc/gnat_ugn/about_this_guide.rst new file mode 100644 index 00000000000..467d3366b66 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/about_this_guide.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst new file mode 100644 index 00000000000..495e9fa4578 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst @@ -0,0 +1,7381 @@ +.. |with| replace:: *with* +.. |withs| replace:: *with*\ s +.. |withed| replace:: *with*\ ed +.. |withing| replace:: *with*\ ing + +.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit + + + +.. _Building_Executable_Programs_With_GNAT: + +************************************** +Building Executable Programs with GNAT +************************************** + +This chapter describes first the gnatmake tool +(:ref:`The_GNAT_Make_Program_gnatmake`), +which automatically determines the set of sources +needed by an Ada compilation unit and executes the necessary +(re)compilations, binding and linking. +It also explains how to use each tool individually: the +compiler (gcc, see :ref:`Compiling_with_gcc`), +binder (gnatbind, see :ref:`Binding_with_gnatbind`), +and linker (gnatlink, see :ref:`Linking_with_gnatlink`) +to build executable programs. +Finally, this chapter provides examples of +how to make use of the general GNU make mechanism +in a GNAT context (see :ref:`Using_the_GNU_make_Utility`). + + +.. _The_GNAT_Make_Program_gnatmake: + +Building with *gnatmake* +======================== + +.. index:: gnatmake + +A typical development cycle when working on an Ada program consists of +the following steps: + +#. Edit some sources to fix bugs; + +#. Add enhancements; + +#. Compile all sources affected; + +#. Rebind and relink; and + +#. Test. + +.. index:: Dependency rules (compilation) + +The third step in particular can be tricky, because not only do the modified +files have to be compiled, but any files depending on these files must also be +recompiled. The dependency rules in Ada can be quite complex, especially +in the presence of overloading, `use` clauses, generics and inlined +subprograms. + +*gnatmake* automatically takes care of the third and fourth steps +of this process. It determines which sources need to be compiled, +compiles them, and binds and links the resulting object files. + +Unlike some other Ada make programs, the dependencies are always +accurately recomputed from the new sources. The source based approach of +the GNAT compilation model makes this possible. This means that if +changes to the source program cause corresponding changes in +dependencies, they will always be tracked exactly correctly by +*gnatmake*. + +Note that for advanced description of project structure, we recommend creating +a project file as explained in :ref:`GNAT_Project_Manager` and use the +*gprbuild* tool which supports building with project files and works similarly +to *gnatmake*. + +.. _Running_gnatmake: + +Running *gnatmake* +------------------ + +The usual form of the *gnatmake* command is + +.. code-block:: sh + + $ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>] + +The only required argument is one `file_name`, which specifies +a compilation unit that is a main program. Several `file_names` can be +specified: this will result in several executables being built. +If `switches` are present, they can be placed before the first +`file_name`, between `file_names` or after the last `file_name`. +If `mode_switches` are present, they must always be placed after +the last `file_name` and all `switches`. + +If you are using standard file extensions (:file:`.adb` and +:file:`.ads`), then the +extension may be omitted from the `file_name` arguments. However, if +you are using non-standard extensions, then it is required that the +extension be given. A relative or absolute directory path can be +specified in a `file_name`, in which case, the input source file will +be searched for in the specified directory only. Otherwise, the input +source file will first be searched in the directory where +*gnatmake* was invoked and if it is not found, it will be search on +the source path of the compiler as described in +:ref:`Search_Paths_and_the_Run-Time_Library_RTL`. + +All *gnatmake* output (except when you specify *-M*) is sent to +:file:`stderr`. The output produced by the +*-M* switch is sent to :file:`stdout`. + + +.. _Switches_for_gnatmake: + +Switches for *gnatmake* +----------------------- + +You may specify any of the following switches to *gnatmake*: + + +.. index:: --version (gnatmake) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + + +.. index:: --help (gnatmake) + +:samp:`--help` + If ``--version`` was not used, display usage, then exit disregarding + all other options. + + +.. index:: --GCC=compiler_name (gnatmake) + +:samp:`--GCC={compiler_name}` + Program used for compiling. The default is ``gcc``. You need to use + quotes around `compiler_name` if `compiler_name` contains + spaces or other separator characters. + As an example ``--GCC="foo -x -y"`` + will instruct *gnatmake* to use ``foo -x -y`` as your + compiler. A limitation of this syntax is that the name and path name of + the executable itself must not include any embedded spaces. Note that + switch ``-c`` is always inserted after your command name. Thus in the + above example the compiler command that will be used by *gnatmake* + will be ``foo -c -x -y``. If several ``--GCC=compiler_name`` are + used, only the last `compiler_name` is taken into account. However, + all the additional switches are also taken into account. Thus, + ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to + ``--GCC="bar -x -y -z -t"``. + + +.. index:: --GNATBIND=binder_name (gnatmake) + +:samp:`--GNATBIND={binder_name}` + Program used for binding. The default is ``gnatbind``. You need to + use quotes around `binder_name` if `binder_name` contains spaces + or other separator characters. + As an example ``--GNATBIND="bar -x -y"`` + will instruct *gnatmake* to use `bar -x -y` as your + binder. Binder switches that are normally appended by *gnatmake* + to ``gnatbind`` are now appended to the end of `bar -x -y`. + A limitation of this syntax is that the name and path name of the executable + itself must not include any embedded spaces. + +.. index:: --GNATLINK=linker_name (gnatmake) + +:samp:`--GNATLINK={linker_name}` + Program used for linking. The default is ``gnatlink``. You need to + use quotes around `linker_name` if `linker_name` contains spaces + or other separator characters. + As an example ``--GNATLINK="lan -x -y"`` + will instruct *gnatmake* to use ``lan -x -y`` as your + linker. Linker switches that are normally appended by ``gnatmake`` to + ``gnatlink`` are now appended to the end of ``lan -x -y``. + A limitation of this syntax is that the name and path name of the executable + itself must not include any embedded spaces. + +:samp:`--create-map-file` + When linking an executable, create a map file. The name of the map file + has the same name as the executable with extension ".map". + +:samp:`--create-map-file={mapfile}` + When linking an executable, create a map file with the specified name. + +.. index:: --create-missing-dirs (gnatmake) + +:samp:`--create-missing-dirs` + When using project files (:samp:`-P{project}`), automatically create + missing object directories, library directories and exec + directories. + +:samp:`--single-compile-per-obj-dir` + Disallow simultaneous compilations in the same object directory when + project files are used. + +:samp:`--subdirs={subdir}` + Actual object directory of each project file is the subdirectory subdir of the + object directory specified or defaulted in the project file. + +:samp:`--unchecked-shared-lib-imports` + By default, shared library projects are not allowed to import static library + projects. When this switch is used on the command line, this restriction is + relaxed. + +:samp:`--source-info={source info file}` + Specify a source info file. This switch is active only when project files + are used. If the source info file is specified as a relative path, then it is + relative to the object directory of the main project. If the source info file + does not exist, then after the Project Manager has successfully parsed and + processed the project files and found the sources, it creates the source info + file. If the source info file already exists and can be read successfully, + then the Project Manager will get all the needed information about the sources + from the source info file and will not look for them. This reduces the time + to process the project files, especially when looking for sources that take a + long time. If the source info file exists but cannot be parsed successfully, + the Project Manager will attempt to recreate it. If the Project Manager fails + to create the source info file, a message is issued, but gnatmake does not + fail. *gnatmake* "trusts" the source info file. This means that + if the source files have changed (addition, deletion, moving to a different + source directory), then the source info file need to be deleted and recreated. + + +.. index:: -a (gnatmake) + +:samp:`-a` + Consider all files in the make process, even the GNAT internal system + files (for example, the predefined Ada library files), as well as any + locked files. Locked files are files whose ALI file is write-protected. + By default, + *gnatmake* does not check these files, + because the assumption is that the GNAT internal files are properly up + to date, and also that any write protected ALI files have been properly + installed. Note that if there is an installation problem, such that one + of these files is not up to date, it will be properly caught by the + binder. + You may have to specify this switch if you are working on GNAT + itself. The switch ``-a`` is also useful + in conjunction with ``-f`` + if you need to recompile an entire application, + including run-time files, using special configuration pragmas, + such as a `Normalize_Scalars` pragma. + + By default + ``gnatmake -a`` compiles all GNAT + internal files with + ``gcc -c -gnatpg`` rather than ``gcc -c``. + + +.. index:: -b (gnatmake) + +:samp:`-b` + Bind only. Can be combined with *-c* to do + compilation and binding, but no link. + Can be combined with *-l* + to do binding and linking. When not combined with + *-c* + all the units in the closure of the main program must have been previously + compiled and must be up to date. The root unit specified by `file_name` + may be given without extension, with the source extension or, if no GNAT + Project File is specified, with the ALI file extension. + + +.. index:: -c (gnatmake) + +:samp:`-c` + Compile only. Do not perform binding, except when *-b* + is also specified. Do not perform linking, except if both + *-b* and + *-l* are also specified. + If the root unit specified by `file_name` is not a main unit, this is the + default. Otherwise *gnatmake* will attempt binding and linking + unless all objects are up to date and the executable is more recent than + the objects. + + +.. index:: -C (gnatmake) + +:samp:`-C` + Use a temporary mapping file. A mapping file is a way to communicate + to the compiler two mappings: from unit names to file names (without + any directory information) and from file names to path names (with + full directory information). A mapping file can make the compiler's + file searches faster, especially if there are many source directories, + or the sources are read over a slow network connection. If + *-P* is used, a mapping file is always used, so + *-C* is unnecessary; in this case the mapping file + is initially populated based on the project file. If + *-C* is used without + *-P*, + the mapping file is initially empty. Each invocation of the compiler + will add any newly accessed sources to the mapping file. + + +.. index:: -C= (gnatmake) + +:samp:`-C={file}` + Use a specific mapping file. The file, specified as a path name (absolute or + relative) by this switch, should already exist, otherwise the switch is + ineffective. The specified mapping file will be communicated to the compiler. + This switch is not compatible with a project file + (-P`file`) or with multiple compiling processes + (-jnnn, when nnn is greater than 1). + + +.. index:: -d (gnatmake) + +:samp:`-d` + Display progress for each source, up to date or not, as a single line: + + :: + + completed x out of y (zz%) + + If the file needs to be compiled this is displayed after the invocation of + the compiler. These lines are displayed even in quiet output mode. + + +.. index:: -D (gnatmake) + +:samp:`-D {dir}` + Put all object files and ALI file in directory `dir`. + If the *-D* switch is not used, all object files + and ALI files go in the current working directory. + + This switch cannot be used when using a project file. + + +.. index:: -eI (gnatmake) + +:samp:`-eI{nnn}` + Indicates that the main source is a multi-unit source and the rank of the unit + in the source file is nnn. nnn needs to be a positive number and a valid + index in the source. This switch cannot be used when *gnatmake* is + invoked for several mains. + + +.. index:: -eL (gnatmake) +.. index:: symbolic links + +:samp:`-eL` + Follow all symbolic links when processing project files. + This should be used if your project uses symbolic links for files or + directories, but is not needed in other cases. + + .. index:: naming scheme + + This also assumes that no directory matches the naming scheme for files (for + instance that you do not have a directory called "sources.ads" when using the + default GNAT naming scheme). + + When you do not have to use this switch (i.e., by default), gnatmake is able to + save a lot of system calls (several per source file and object file), which + can result in a significant speed up to load and manipulate a project file, + especially when using source files from a remote system. + + +.. index:: -eS (gnatmake) + +:samp:`-eS` + Output the commands for the compiler, the binder and the linker + on standard output, + instead of standard error. + + +.. index:: -f (gnatmake) + +:samp:`-f` + Force recompilations. Recompile all sources, even though some object + files may be up to date, but don't recompile predefined or GNAT internal + files or locked files (files with a write-protected ALI file), + unless the *-a* switch is also specified. + + +.. index:: -F (gnatmake) + +:samp:`-F` + When using project files, if some errors or warnings are detected during + parsing and verbose mode is not in effect (no use of switch + -v), then error lines start with the full path name of the project + file, rather than its simple file name. + + +.. index:: -g (gnatmake) + +:samp:`-g` + Enable debugging. This switch is simply passed to the compiler and to the + linker. + + +.. index:: -i (gnatmake) + +:samp:`-i` + In normal mode, *gnatmake* compiles all object files and ALI files + into the current directory. If the *-i* switch is used, + then instead object files and ALI files that already exist are overwritten + in place. This means that once a large project is organized into separate + directories in the desired manner, then *gnatmake* will automatically + maintain and update this organization. If no ALI files are found on the + Ada object path (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`), + the new object and ALI files are created in the + directory containing the source being compiled. If another organization + is desired, where objects and sources are kept in different directories, + a useful technique is to create dummy ALI files in the desired directories. + When detecting such a dummy file, *gnatmake* will be forced to + recompile the corresponding source file, and it will be put the resulting + object and ALI files in the directory where it found the dummy file. + + +.. index:: -j (gnatmake) +.. index:: Parallel make + +:samp:`-j{n}` + Use `n` processes to carry out the (re)compilations. On a multiprocessor + machine compilations will occur in parallel. If `n` is 0, then the + maximum number of parallel compilations is the number of core processors + on the platform. In the event of compilation errors, messages from various + compilations might get interspersed (but *gnatmake* will give you the + full ordered list of failing compiles at the end). If this is problematic, + rerun the make process with n set to 1 to get a clean list of messages. + + +.. index:: -k (gnatmake) + +:samp:`-k` + Keep going. Continue as much as possible after a compilation error. To + ease the programmer's task in case of compilation errors, the list of + sources for which the compile fails is given when *gnatmake* + terminates. + + If *gnatmake* is invoked with several :file:`file_names` and with this + switch, if there are compilation errors when building an executable, + *gnatmake* will not attempt to build the following executables. + + +.. index:: -l (gnatmake) + +:samp:`-l` + Link only. Can be combined with *-b* to binding + and linking. Linking will not be performed if combined with + *-c* + but not with *-b*. + When not combined with *-b* + all the units in the closure of the main program must have been previously + compiled and must be up to date, and the main program needs to have been bound. + The root unit specified by `file_name` + may be given without extension, with the source extension or, if no GNAT + Project File is specified, with the ALI file extension. + + +.. index:: -m (gnatmake) + +:samp:`-m` + Specify that the minimum necessary amount of recompilations + be performed. In this mode *gnatmake* ignores time + stamp differences when the only + modifications to a source file consist in adding/removing comments, + empty lines, spaces or tabs. This means that if you have changed the + comments in a source file or have simply reformatted it, using this + switch will tell *gnatmake* not to recompile files that depend on it + (provided other sources on which these files depend have undergone no + semantic modifications). Note that the debugging information may be + out of date with respect to the sources if the *-m* switch causes + a compilation to be switched, so the use of this switch represents a + trade-off between compilation time and accurate debugging information. + + +.. index:: Dependencies, producing list +.. index:: -M (gnatmake) + +:samp:`-M` + Check if all objects are up to date. If they are, output the object + dependences to :file:`stdout` in a form that can be directly exploited in + a :file:`Makefile`. By default, each source file is prefixed with its + (relative or absolute) directory name. This name is whatever you + specified in the various *-aI* + and *-I* switches. If you use + `gnatmake -M` *-q* + (see below), only the source file names, + without relative paths, are output. If you just specify the *-M* + switch, dependencies of the GNAT internal system files are omitted. This + is typically what you want. If you also specify + the *-a* switch, + dependencies of the GNAT internal files are also listed. Note that + dependencies of the objects in external Ada libraries (see + switch :samp:`-aL{dir}` in the following list) + are never reported. + + +.. index:: -n (gnatmake) + +:samp:`-n` + Don't compile, bind, or link. Checks if all objects are up to date. + If they are not, the full name of the first file that needs to be + recompiled is printed. + Repeated use of this option, followed by compiling the indicated source + file, will eventually result in recompiling all required units. + + +.. index:: -o (gnatmake) + +:samp:`-o {exec_name}` + Output executable name. The name of the final executable program will be + `exec_name`. If the *-o* switch is omitted the default + name for the executable will be the name of the input file in appropriate form + for an executable file on the host system. + + This switch cannot be used when invoking *gnatmake* with several + :file:`file_names`. + + +.. index:: -p (gnatmake) + +:samp:`-p` + Same as :samp:`--create-missing-dirs` + +.. index:: -P (gnatmake) + +:samp:`-P{project}` + Use project file `project`. Only one such switch can be used. + :ref:`gnatmake_and_Project_Files`. + + +.. index:: -q (gnatmake) + +:samp:`-q` + Quiet. When this flag is not set, the commands carried out by + *gnatmake* are displayed. + + +.. index:: -s (gnatmake) + +:samp:`-s` + Recompile if compiler switches have changed since last compilation. + All compiler switches but -I and -o are taken into account in the + following way: + orders between different 'first letter' switches are ignored, but + orders between same switches are taken into account. For example, + *-O -O2* is different than *-O2 -O*, but *-g -O* + is equivalent to *-O -g*. + + This switch is recommended when Integrated Preprocessing is used. + + +.. index:: -u (gnatmake) + +:samp:`-u` + Unique. Recompile at most the main files. It implies -c. Combined with + -f, it is equivalent to calling the compiler directly. Note that using + -u with a project file and no main has a special meaning + (:ref:`Project_Files_and_Main_Subprograms`). + + +.. index:: -U (gnatmake) + +:samp:`-U` + When used without a project file or with one or several mains on the command + line, is equivalent to -u. When used with a project file and no main + on the command line, all sources of all project files are checked and compiled + if not up to date, and libraries are rebuilt, if necessary. + + +.. index:: -v (gnatmake) + +:samp:`-v` + Verbose. Display the reason for all recompilations *gnatmake* + decides are necessary, with the highest verbosity level. + + +.. index:: -vl (gnatmake) + +:samp:`-vl` + Verbosity level Low. Display fewer lines than in verbosity Medium. + + +.. index:: -vm (gnatmake) + +:samp:`-vm` + Verbosity level Medium. Potentially display fewer lines than in verbosity High. + + +.. index:: -vm (gnatmake) + +:samp:`-vh` + Verbosity level High. Equivalent to -v. + + +:samp:`-vP{x}` + Indicate the verbosity of the parsing of GNAT project files. + See :ref:`Switches_Related_to_Project_Files`. + + +.. index:: -x (gnatmake) + +:samp:`-x` + Indicate that sources that are not part of any Project File may be compiled. + Normally, when using Project Files, only sources that are part of a Project + File may be compile. When this switch is used, a source outside of all Project + Files may be compiled. The ALI file and the object file will be put in the + object directory of the main Project. The compilation switches used will only + be those specified on the command line. Even when + *-x* is used, mains specified on the + command line need to be sources of a project file. + + +:samp:`-X{name}={value}` + Indicate 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. + :ref:`Switches_Related_to_Project_Files`. + + +.. index:: -z (gnatmake) + +:samp:`-z` + No main subprogram. Bind and link the program even if the unit name + given on the command line is a package name. The resulting executable + will execute the elaboration routines of the package and its closure, + then the finalization routines. + + +.. rubric:: GCC switches + +Any uppercase or multi-character switch that is not a *gnatmake* switch +is passed to *gcc* (e.g., *-O*, *-gnato,* etc.) + + +.. rubric:: Source and library search path switches + +.. index:: -aI (gnatmake) + +:samp:`-aI{dir}` + When looking for source files also look in directory `dir`. + The order in which source files search is undertaken is + described in :ref:`Search_Paths_and_the_Run-Time_Library_RTL`. + + +.. index:: -aL (gnatmake) + +:samp:`-aL{dir}` + Consider `dir` as being an externally provided Ada library. + Instructs *gnatmake* to skip compilation units whose :file:`.ALI` + files have been located in directory `dir`. This allows you to have + missing bodies for the units in `dir` and to ignore out of date bodies + for the same units. You still need to specify + the location of the specs for these units by using the switches + :samp:`-aI{dir}` or :samp:`-I{dir}`. + Note: this switch is provided for compatibility with previous versions + of *gnatmake*. The easier method of causing standard libraries + to be excluded from consideration is to write-protect the corresponding + ALI files. + + +.. index:: -aO (gnatmake) + +:samp:`-aO{dir}` + When searching for library and object files, look in directory + `dir`. The order in which library files are searched is described in + :ref:`Search_Paths_for_gnatbind`. + + +.. index:: Search paths, for gnatmake +.. index:: -A (gnatmake) + +:samp:`-A{dir}` + Equivalent to :samp:`-aL{dir}` :samp:`-aI{dir}`. + + + .. index:: -I (gnatmake) + +:samp:`-I{dir}` + Equivalent to :samp:`-aO{dir} -aI{dir}`. + + +.. index:: -I- (gnatmake) +.. index:: Source files, suppressing search + +:samp:`-I-` + Do not look for source files in the directory containing the source + file named in the command line. + Do not look for ALI or object files in the directory + where *gnatmake* was invoked. + + +.. index:: -L (gnatmake) +.. index:: Linker libraries + +:samp:`-L{dir}` + Add directory `dir` to the list of directories in which the linker + will search for libraries. This is equivalent to + :samp:`-largs` :samp:`-L{dir}`. + Furthermore, under Windows, the sources pointed to by the libraries path + set in the registry are not searched for. + + +.. index:: -nostdinc (gnatmake) + +:samp:`-nostdinc` + Do not look for source files in the system default directory. + + +.. index:: -nostdlib (gnatmake) + +:samp:`-nostdlib` + Do not look for library files in the system default directory. + + +.. index:: --RTS (gnatmake) + +:samp:`--RTS={rts-path}` + Specifies the default location of the runtime library. GNAT looks for the + runtime + in the following directories, and stops as soon as a valid runtime is found + (:file:`adainclude` or :file:`ada_source_path`, and :file:`adalib` or + :file:`ada_object_path` present): + + * *<current directory>/$rts_path* + + * *<default-search-dir>/$rts_path* + + * *<default-search-dir>/rts-$rts_path* + + * The selected path is handled like a normal RTS path. + + +.. _Mode_Switches_for_gnatmake: + +Mode Switches for *gnatmake* +---------------------------- + +The mode switches (referred to as `mode_switches`) allow the +inclusion of switches that are to be passed to the compiler itself, the +binder or the linker. The effect of a mode switch is to cause all +subsequent switches up to the end of the switch list, or up to the next +mode switch, to be interpreted as switches to be passed on to the +designated component of GNAT. + +.. index:: -cargs (gnatmake) + +:samp:`-cargs {switches}` + Compiler switches. Here `switches` is a list of switches + that are valid switches for *gcc*. They will be passed on to + all compile steps performed by *gnatmake*. + + +.. index:: -bargs (gnatmake) + +:samp:`-bargs {switches}` + Binder switches. Here `switches` is a list of switches + that are valid switches for `gnatbind`. They will be passed on to + all bind steps performed by *gnatmake*. + + +.. index:: -largs (gnatmake) + +:samp:`-largs {switches}` + Linker switches. Here `switches` is a list of switches + that are valid switches for *gnatlink*. They will be passed on to + all link steps performed by *gnatmake*. + + +.. index:: -margs (gnatmake) + +:samp:`-margs {switches}` + Make switches. The switches are directly interpreted by *gnatmake*, + regardless of any previous occurrence of *-cargs*, *-bargs* + or *-largs*. + + +.. _Notes_on_the_Command_Line: + +Notes on the Command Line +------------------------- + +This section contains some additional useful notes on the operation +of the *gnatmake* command. + +.. index:: Recompilation (by gnatmake) + +* If *gnatmake* finds no ALI files, it recompiles the main program + and all other units required by the main program. + This means that *gnatmake* + can be used for the initial compile, as well as during subsequent steps of + the development cycle. + +* If you enter ``gnatmake foo.adb``, where ``foo`` + is a subunit or body of a generic unit, *gnatmake* recompiles + :file:`foo.adb` (because it finds no ALI) and stops, issuing a + warning. + +* In *gnatmake* the switch *-I* + is used to specify both source and + library file paths. Use *-aI* + instead if you just want to specify + source paths only and *-aO* + if you want to specify library paths + only. + +* *gnatmake* will ignore any files whose ALI file is write-protected. + This may conveniently be used to exclude standard libraries from + consideration and in particular it means that the use of the + *-f* switch will not recompile these files + unless *-a* is also specified. + +* *gnatmake* has been designed to make the use of Ada libraries + particularly convenient. Assume you have an Ada library organized + as follows: *obj-dir* contains the objects and ALI files for + of your Ada compilation units, + whereas *include-dir* contains the + specs of these units, but no bodies. Then to compile a unit + stored in `main.adb`, which uses this Ada library you would just type: + + .. code-block:: sh + + $ gnatmake -aI`include-dir` -aL`obj-dir` main + +* Using *gnatmake* along with the *-m (minimal recompilation)* + switch provides a mechanism for avoiding unnecessary recompilations. Using + this switch, + you can update the comments/format of your + source files without having to recompile everything. Note, however, that + adding or deleting lines in a source files may render its debugging + info obsolete. If the file in question is a spec, the impact is rather + limited, as that debugging info will only be useful during the + elaboration phase of your program. For bodies the impact can be more + significant. In all events, your debugger will warn you if a source file + is more recent than the corresponding object, and alert you to the fact + that the debugging information may be out of date. + + +.. _How_gnatmake_Works: + +How *gnatmake* Works +-------------------- + +Generally *gnatmake* automatically performs all necessary +recompilations and you don't need to worry about how it works. However, +it may be useful to have some basic understanding of the *gnatmake* +approach and in particular to understand how it uses the results of +previous compilations without incorrectly depending on them. + +First a definition: an object file is considered *up to date* if the +corresponding ALI file exists and if all the source files listed in the +dependency section of this ALI file have time stamps matching those in +the ALI file. This means that neither the source file itself nor any +files that it depends on have been modified, and hence there is no need +to recompile this file. + +*gnatmake* works by first checking if the specified main unit is up +to date. If so, no compilations are required for the main unit. If not, +*gnatmake* compiles the main program to build a new ALI file that +reflects the latest sources. Then the ALI file of the main unit is +examined to find all the source files on which the main program depends, +and *gnatmake* recursively applies the above procedure on all these +files. + +This process ensures that *gnatmake* only trusts the dependencies +in an existing ALI file if they are known to be correct. Otherwise it +always recompiles to determine a new, guaranteed accurate set of +dependencies. As a result the program is compiled 'upside down' from what may +be more familiar as the required order of compilation in some other Ada +systems. In particular, clients are compiled before the units on which +they depend. The ability of GNAT to compile in any order is critical in +allowing an order of compilation to be chosen that guarantees that +*gnatmake* will recompute a correct set of new dependencies if +necessary. + +When invoking *gnatmake* with several `file_names`, if a unit is +imported by several of the executables, it will be recompiled at most once. + +Note: when using non-standard naming conventions +(:ref:`Using_Other_File_Names`), changing through a configuration pragmas +file the version of a source and invoking *gnatmake* to recompile may +have no effect, if the previous version of the source is still accessible +by *gnatmake*. It may be necessary to use the switch +-f. + + +.. _Examples_of_gnatmake_Usage: + +Examples of *gnatmake* Usage +---------------------------- + +*gnatmake hello.adb* + Compile all files necessary to bind and link the main program + :file:`hello.adb` (containing unit `Hello`) and bind and link the + resulting object files to generate an executable file :file:`hello`. + +*gnatmake main1 main2 main3* + Compile all files necessary to bind and link the main programs + :file:`main1.adb` (containing unit `Main1`), :file:`main2.adb` + (containing unit `Main2`) and :file:`main3.adb` + (containing unit `Main3`) and bind and link the resulting object files + to generate three executable files :file:`main1`, + :file:`main2` and :file:`main3`. + +*gnatmake -q Main_Unit -cargs -O2 -bargs -l* + Compile all files necessary to bind and link the main program unit + `Main_Unit` (from file :file:`main_unit.adb`). All compilations will + be done with optimization level 2 and the order of elaboration will be + listed by the binder. *gnatmake* will operate in quiet mode, not + displaying commands it is executing. + + +.. _Compiling_with_gcc: + +Compiling with *gcc* +==================== + +This section discusses how to compile Ada programs using the *gcc* +command. It also describes the set of switches +that can be used to control the behavior of the compiler. + +.. _Compiling_Programs: + +Compiling Programs +------------------ + +The first step in creating an executable program is to compile the units +of the program using the *gcc* command. You must compile the +following files: + +* the body file (:file:`.adb`) for a library level subprogram or generic + subprogram + +* the spec file (:file:`.ads`) for a library level package or generic + package that has no body + +* the body file (:file:`.adb`) for a library level package + or generic package that has a body + +You need *not* compile the following files + +* the spec of a library unit which has a body + +* subunits + +because they are compiled as part of compiling related units. GNAT +package specs +when the corresponding body is compiled, and subunits when the parent is +compiled. + +.. index:: cannot generate code + +If you attempt to compile any of these files, you will get one of the +following error messages (where `fff` is the name of the file you +compiled): + + :: + + cannot generate code for file `fff` (package spec) + to check package spec, use -gnatc + + cannot generate code for file `fff` (missing subunits) + to check parent unit, use -gnatc + + cannot generate code for file `fff` (subprogram spec) + to check subprogram spec, use -gnatc + + cannot generate code for file `fff` (subunit) + to check subunit, use -gnatc + + +As indicated by the above error messages, if you want to submit +one of these files to the compiler to check for correct semantics +without generating code, then use the *-gnatc* switch. + +The basic command for compiling a file containing an Ada unit is: + +.. code-block:: sh + + $ gcc -c [switches] <file name> + +where `file name` is the name of the Ada file (usually +having an extension :file:`.ads` for a spec or :file:`.adb` for a body). +You specify the +:option:`-c` switch to tell *gcc* to compile, but not link, the file. +The result of a successful compilation is an object file, which has the +same name as the source file but an extension of :file:`.o` and an Ada +Library Information (ALI) file, which also has the same name as the +source file, but with :file:`.ali` as the extension. GNAT creates these +two output files in the current directory, but you may specify a source +file in any directory using an absolute or relative path specification +containing the directory information. + +.. index:: gnat1 + +*gcc* is actually a driver program that looks at the extensions of +the file arguments and loads the appropriate compiler. For example, the +GNU C compiler is :file:`cc1`, and the Ada compiler is :file:`gnat1`. +These programs are in directories known to the driver program (in some +configurations via environment variables you set), but need not be in +your path. The *gcc* driver also calls the assembler and any other +utilities needed to complete the generation of the required object +files. + +It is possible to supply several file names on the same *gcc* +command. This causes *gcc* to call the appropriate compiler for +each file. For example, the following command lists two separate +files to be compiled: + +.. code-block:: sh + + $ gcc -c x.adb y.adb + + +calls `gnat1` (the Ada compiler) twice to compile :file:`x.adb` and +:file:`y.adb`. +The compiler generates two object files :file:`x.o` and :file:`y.o` +and the two ALI files :file:`x.ali` and :file:`y.ali`. + +Any switches apply to all the files listed, see :ref:`Switches_for_gcc` for a +list of available *gcc* switches. + +.. _Search_Paths_and_the_Run-Time_Library_RTL: + +Search Paths and the Run-Time Library (RTL) +------------------------------------------- + +With the GNAT source-based library system, the compiler must be able to +find source files for units that are needed by the unit being compiled. +Search paths are used to guide this process. + +The compiler compiles one source file whose name must be given +explicitly on the command line. In other words, no searching is done +for this file. To find all other source files that are needed (the most +common being the specs of units), the compiler examines the following +directories, in the following order: + +* The directory containing the source file of the main unit being compiled + (the file name on the command line). + +* Each directory named by an *-I* switch given on the *gcc* + command line, in the order given. + + .. index:: ADA_PRJ_INCLUDE_FILE + +* Each of the directories listed in the text file whose name is given + by the :envvar:`ADA_PRJ_INCLUDE_FILE` environment variable. + :envvar:`ADA_PRJ_INCLUDE_FILE` is normally set by gnatmake or by the gnat + driver when project files are used. It should not normally be set + by other means. + + .. index:: ADA_INCLUDE_PATH + +* Each of the directories listed in the value of the + :envvar:`ADA_INCLUDE_PATH` environment variable. + Construct this value + exactly as the :envvar:`PATH` environment variable: a list of directory + names separated by colons (semicolons when working with the NT version). + +* The content of the :file:`ada_source_path` file which is part of the GNAT + installation tree and is used to store standard libraries such as the + GNAT Run Time Library (RTL) source files. + :ref:`Installing_a_library` + +Specifying the switch *-I-* +inhibits the use of the directory +containing the source file named in the command line. You can still +have this directory on your search path, but in this case it must be +explicitly requested with a *-I* switch. + +Specifying the switch *-nostdinc* +inhibits the search of the default location for the GNAT Run Time +Library (RTL) source files. + +The compiler outputs its object files and ALI files in the current +working directory. +Caution: The object file can be redirected with the *-o* switch; +however, *gcc* and `gnat1` have not been coordinated on this +so the :file:`ALI` file will not go to the right place. Therefore, you should +avoid using the *-o* switch. + +.. index:: System.IO + +The packages `Ada`, `System`, and `Interfaces` and their +children make up the GNAT RTL, together with the simple `System.IO` +package used in the `"Hello World"` example. The sources for these units +are needed by the compiler and are kept together in one directory. Not +all of the bodies are needed, but all of the sources are kept together +anyway. In a normal installation, you need not specify these directory +names when compiling or binding. Either the environment variables or +the built-in defaults cause these files to be found. + +In addition to the language-defined hierarchies (`System`, `Ada` and +`Interfaces`), the GNAT distribution provides a fourth hierarchy, +consisting of child units of `GNAT`. This is a collection of generally +useful types, subprograms, etc. See the :title:`GNAT_Reference_Manual` +for further details. + +Besides simplifying access to the RTL, a major use of search paths is +in compiling sources from multiple directories. This can make +development environments much more flexible. + +.. _Order_of_Compilation_Issues: + +Order of Compilation Issues +--------------------------- + +If, in our earlier example, there was a spec for the `hello` +procedure, it would be contained in the file :file:`hello.ads`; yet this +file would not have to be explicitly compiled. This is the result of the +model we chose to implement library management. Some of the consequences +of this model are as follows: + +* There is no point in compiling specs (except for package + specs with no bodies) because these are compiled as needed by clients. If + you attempt a useless compilation, you will receive an error message. + It is also useless to compile subunits because they are compiled as needed + by the parent. + +* There are no order of compilation requirements: performing a + compilation never obsoletes anything. The only way you can obsolete + something and require recompilations is to modify one of the + source files on which it depends. + +* There is no library as such, apart from the ALI files + (:ref:`The_Ada_Library_Information_Files`, for information on the format + of these files). For now we find it convenient to create separate ALI files, + but eventually the information therein may be incorporated into the object + file directly. + +* When you compile a unit, the source files for the specs of all units + that it |withs|, all its subunits, and the bodies of any generics it + instantiates must be available (reachable by the search-paths mechanism + described above), or you will receive a fatal error message. + +.. _Examples: + +Examples +-------- + +The following are some typical Ada compilation command line examples: + +.. code-block:: sh + + $ gcc -c xyz.adb + +Compile body in file :file:`xyz.adb` with all default options. + +.. code-block:: sh + + $ gcc -c -O2 -gnata xyz-def.adb + +Compile the child unit package in file :file:`xyz-def.adb` with extensive +optimizations, and pragma `Assert`/`Debug` statements +enabled. + +.. code-block:: sh + + $ gcc -c -gnatc abc-def.adb + +Compile the subunit in file :file:`abc-def.adb` in semantic-checking-only +mode. + + +.. _Switches_for_gcc: + +Compiler Switches +================= + +The *gcc* command accepts switches that control the +compilation process. These switches are fully described in this section: +first an alphabetical listing of all switches with a brief description, +and then functionally grouped sets of switches with more detailed +information. + +More switches exist for GCC than those documented here, especially +for specific targets. However, their use is not recommended as +they may change code generation in ways that are incompatible with +the Ada run-time library, or can cause inconsistencies between +compilation units. + +.. _Alphabetical_List_of_All_Switches: + +Alphabetical List of All Switches +--------------------------------- + +.. index:: -b (gcc) + +:samp:`-b {target}` + Compile your program to run on `target`, which is the name of a + system configuration. You must have a GNAT cross-compiler built if + `target` is not the same as your host system. + + +.. index:: -B (gcc) + +:samp:`-B{dir}` + Load compiler executables (for example, `gnat1`, the Ada compiler) + from `dir` instead of the default location. Only use this switch + when multiple versions of the GNAT compiler are available. + See the "Options for Directory Search" section in the + :title:`Using the GNU Compiler Collection (GCC)` manual for further details. + You would normally use the *-b* or *-V* switch instead. + +.. index:: -c (gcc) + +:samp:`-c` + Compile. Always use this switch when compiling Ada programs. + + Note: for some other languages when using *gcc*, notably in + the case of C and C++, it is possible to use + use *gcc* without a *-c* switch to + compile and link in one step. In the case of GNAT, you + cannot use this approach, because the binder must be run + and *gcc* cannot be used to run the GNAT binder. + + +.. index:: -fcallgraph-info (gcc) + +:samp:`-fcallgraph-info[=su,da]` + Makes the compiler output callgraph information for the program, on a + per-file basis. The information is generated in the VCG format. It can + be decorated with additional, per-node and/or per-edge information, if a + list of comma-separated markers is additionally specified. When the + `su` marker is specified, the callgraph is decorated with stack usage + information; it is equivalent to *-fstack-usage*. When the `da` + marker is specified, the callgraph is decorated with information about + dynamically allocated objects. + + +.. index:: -fdump-scos (gcc) + +:samp:`-fdump-scos` + Generates SCO (Source Coverage Obligation) information in the ALI file. + This information is used by advanced coverage tools. See unit :file:`SCOs` + in the compiler sources for details in files :file:`scos.ads` and + :file:`scos.adb`. + + +.. index:: -fdump-xref (gcc) + +:samp:`-fdump-xref` + Generates cross reference information in GLI files for C and C++ sources. + The GLI files have the same syntax as the ALI files for Ada, and can be used + for source navigation in IDEs and on the command line using e.g. gnatxref + and the *--ext=gli* switch. + + +.. index:: -flto (gcc) + +:samp:`-flto[={n}]` + Enables Link Time Optimization. This switch must be used in conjunction + with the traditional *-Ox* switches and instructs the compiler to + defer most optimizations until the link stage. The advantage of this + approach is that the compiler can do a whole-program analysis and choose + the best interprocedural optimization strategy based on a complete view + of the program, instead of a fragmentary view with the usual approach. + This can also speed up the compilation of big programs and reduce the + size of the executable, compared with a traditional per-unit compilation + with inlining across modules enabled by the *-gnatn* switch. + The drawback of this approach is that it may require more memory and that + the debugging information generated by -g with it might be hardly usable. + The switch, as well as the accompanying *-Ox* switches, must be + specified both for the compilation and the link phases. + If the `n` parameter is specified, the optimization and final code + generation at link time are executed using `n` parallel jobs by + means of an installed *make* program. + + +.. index:: -fno-inline (gcc) + +:samp:`-fno-inline` + Suppresses all inlining, unless requested with pragma `Inline_Always`. The + effect is enforced regardless of other optimization or inlining switches. + Note that inlining can also be suppressed on a finer-grained basis with + pragma `No_Inline`. + + +.. index:: -fno-inline-functions (gcc) + +:samp:`-fno-inline-functions` + Suppresses automatic inlining of subprograms, which is enabled + if *-O3* is used. + + +.. index:: -fno-inline-small-functions (gcc) + +:samp:`-fno-inline-small-functions` + Suppresses automatic inlining of small subprograms, which is enabled + if *-O2* is used. + + +.. index:: -fno-inline-functions-called-once (gcc) + +:samp:`-fno-inline-functions-called-once` + Suppresses inlining of subprograms local to the unit and called once + from within it, which is enabled if *-O1* is used. + + +.. index:: -fno-ivopts (gcc) + +:samp:`-fno-ivopts` + Suppresses high-level loop induction variable optimizations, which are + enabled if *-O1* is used. These optimizations are generally + profitable but, for some specific cases of loops with numerous uses + of the iteration variable that follow a common pattern, they may end + up destroying the regularity that could be exploited at a lower level + and thus producing inferior code. + + +.. index:: -fno-strict-aliasing (gcc) + +:samp:`-fno-strict-aliasing` + Causes the compiler to avoid assumptions regarding non-aliasing + of objects of different types. See + :ref:`Optimization_and_Strict_Aliasing` for details. + + +.. index:: -fstack-check (gcc) + +:samp:`-fstack-check` + Activates stack checking. + See :ref:`Stack_Overflow_Checking` for details. + + +.. index:: -fstack-usage (gcc) + +:samp:`-fstack-usage` + Makes the compiler output stack usage information for the program, on a + per-subprogram basis. See :ref:`Static_Stack_Usage_Analysis` for details. + + +.. index:: -g (gcc) + +:samp:`-g` + Generate debugging information. This information is stored in the object + file and copied from there to the final executable file by the linker, + where it can be read by the debugger. You must use the + *-g* switch if you plan on using the debugger. + + +.. index:: -gnat05 (gcc) + +:samp:`-gnat05` + Allow full Ada 2005 features. + + +.. index:: -gnat12 (gcc) + +:samp:`-gnat12` + Allow full Ada 2012 features. + +.. index:: -gnat83 (gcc) + +.. index:: -gnat2005 (gcc) + +:samp:`-gnat2005` + Allow full Ada 2005 features (same as *-gnat05*) + + +.. index:: -gnat2012 (gcc) + +:samp:`-gnat2012` + Allow full Ada 2012 features (same as *-gnat12*) + + +:samp:`-gnat83` + Enforce Ada 83 restrictions. + + +.. index:: -gnat95 (gcc) + +:samp:`-gnat95` + Enforce Ada 95 restrictions. + + Note: for compatibility with some Ada 95 compilers which support only + the `overriding` keyword of Ada 2005, the *-gnatd.D* switch can + be used along with *-gnat95* to achieve a similar effect with GNAT. + + *-gnatd.D* instructs GNAT to consider `overriding` as a keyword + and handle its associated semantic checks, even in Ada 95 mode. + + +.. index:: -gnata (gcc) + +:samp:`-gnata` + Assertions enabled. `Pragma Assert` and `pragma Debug` to be + activated. Note that these pragmas can also be controlled using the + configuration pragmas `Assertion_Policy` and `Debug_Policy`. + It also activates pragmas `Check`, `Precondition`, and + `Postcondition`. Note that these pragmas can also be controlled + using the configuration pragma `Check_Policy`. In Ada 2012, it + also activates all assertions defined in the RM as aspects: preconditions, + postconditions, type invariants and (sub)type predicates. In all Ada modes, + corresponding pragmas for type invariants and (sub)type predicates are + also activated. The default is that all these assertions are disabled, + and have no effect, other than being checked for syntactic validity, and + in the case of subtype predicates, constructions such as membership tests + still test predicates even if assertions are turned off. + + +.. index:: -gnatA (gcc) + +:samp:`-gnatA` + Avoid processing :file:`gnat.adc`. If a :file:`gnat.adc` file is present, + it will be ignored. + + +.. index:: -gnatb (gcc) + +:samp:`-gnatb` + Generate brief messages to :file:`stderr` even if verbose mode set. + + +.. index:: -gnatB (gcc) + +:samp:`-gnatB` + Assume no invalid (bad) values except for 'Valid attribute use + (:ref:`Validity_Checking`). + + +.. index:: -gnatc (gcc) + +:samp:`-gnatc` + Check syntax and semantics only (no code generation attempted). When the + compiler is invoked by *gnatmake*, if the switch *-gnatc* is + only given to the compiler (after *-cargs* or in package Compiler of + the project file, *gnatmake* will fail because it will not find the + object file after compilation. If *gnatmake* is called with + *-gnatc* as a builder switch (before *-cargs* or in package + Builder of the project file) then *gnatmake* will not fail because + it will not look for the object files after compilation, and it will not try + to build and link. This switch may not be given if a previous `-gnatR` + switch has been given, since `-gnatR` requires that the code generator + be called to complete determination of representation information. + + +.. index:: -gnatC (gcc) + +:samp:`-gnatC` + Generate CodePeer intermediate format (no code generation attempted). + This switch will generate an intermediate representation suitable for + use by CodePeer (:file:`.scil` files). This switch is not compatible with + code generation (it will, among other things, disable some switches such + as -gnatn, and enable others such as -gnata). + + +.. index:: -gnatd (gcc) + +:samp:`-gnatd` + Specify debug options for the compiler. The string of characters after + the *-gnatd* specify the specific debug options. The possible + characters are 0-9, a-z, A-Z, optionally preceded by a dot. See + compiler source file :file:`debug.adb` for details of the implemented + debug options. Certain debug options are relevant to applications + programmers, and these are documented at appropriate points in this + users guide. + + +.. index:: -gnatD[nn] (gcc) + +:samp:`-gnatD` + Create expanded source files for source level debugging. This switch + also suppress generation of cross-reference information + (see *-gnatx*). Note that this switch is not allowed if a previous + -gnatR switch has been given, since these two switches are not compatible. + + +.. index:: -gnateA (gcc) + +:samp:`-gnateA` + Check that the actual parameters of a subprogram call are not aliases of one + another. To qualify as aliasing, the actuals must denote objects of a composite + type, their memory locations must be identical or overlapping, and at least one + of the corresponding formal parameters must be of mode OUT or IN OUT. + + + .. code-block:: ada + + type Rec_Typ is record + Data : Integer := 0; + end record; + + function Self (Val : Rec_Typ) return Rec_Typ is + begin + return Val; + end Self; + + procedure Detect_Aliasing (Val_1 : in out Rec_Typ; Val_2 : Rec_Typ) is + begin + null; + end Detect_Aliasing; + + Obj : Rec_Typ; + + Detect_Aliasing (Obj, Obj); + Detect_Aliasing (Obj, Self (Obj)); + + + In the example above, the first call to `Detect_Aliasing` fails with a + `Program_Error` at runtime because the actuals for `Val_1` and + `Val_2` denote the same object. The second call executes without raising + an exception because `Self(Obj)` produces an anonymous object which does + not share the memory location of `Obj`. + + +.. index:: -gnatec (gcc) + +:samp:`-gnatec={path}` + Specify a configuration pragma file + (the equal sign is optional) + (:ref:`The_Configuration_Pragmas_Files`). + + +.. index:: -gnateC (gcc) + +:samp:`-gnateC` + Generate CodePeer messages in a compiler-like format. This switch is only + effective if *-gnatcC* is also specified and requires an installation + of CodePeer. + + +.. index:: -gnated (gcc) + +:samp:`-gnated` + Disable atomic synchronization + + +.. index:: -gnateD (gcc) + +:samp:`-gnateDsymbol[={value}]` + Defines a symbol, associated with `value`, for preprocessing. + (:ref:`Integrated_Preprocessing`). + + +.. index:: -gnateE (gcc) + +:samp:`-gnateE` + Generate extra information in exception messages. In particular, display + extra column information and the value and range associated with index and + range check failures, and extra column information for access checks. + In cases where the compiler is able to determine at compile time that + a check will fail, it gives a warning, and the extra information is not + produced at run time. + + +.. index:: -gnatef (gcc) + +:samp:`-gnatef` + Display full source path name in brief error messages. + + +.. index:: -gnateF (gcc) + +:samp:`-gnateF` + Check for overflow on all floating-point operations, including those + for unconstrained predefined types. See description of pragma + `Check_Float_Overflow` in GNAT RM. + + +.. index:: -gnateG (gcc) + +:samp:`-gnateG` + Save result of preprocessing in a text file. + + +.. index:: -gnatei (gcc) + +:samp:`-gnatei{nnn}` + Set maximum number of instantiations during compilation of a single unit to + `nnn`. This may be useful in increasing the default maximum of 8000 for + the rare case when a single unit legitimately exceeds this limit. + + +.. index:: -gnateI (gcc) + +:samp:`-gnateI{nnn}` + Indicates that the source is a multi-unit source and that the index of the + unit to compile is `nnn`. `nnn` needs to be a positive number and need + to be a valid index in the multi-unit source. + + +.. index:: -gnatel (gcc) + +:samp:`-gnatel` + This switch can be used with the static elaboration model to issue info + messages showing + where implicit `pragma Elaborate` and `pragma Elaborate_All` + are generated. This is useful in diagnosing elaboration circularities + caused by these implicit pragmas when using the static elaboration + model. See See the section in this guide on elaboration checking for + further details. These messages are not generated by default, and are + intended only for temporary use when debugging circularity problems. + + +.. index:: -gnatel (gcc) + +:samp:`-gnateL` + This switch turns off the info messages about implicit elaboration pragmas. + + +.. index:: -gnatem (gcc) + +:samp:`-gnatem={path}` + Specify a mapping file + (the equal sign is optional) + (:ref:`Units_to_Sources_Mapping_Files`). + + +.. index:: -gnatep (gcc) + +:samp:`-gnatep={file}` + Specify a preprocessing data file + (the equal sign is optional) + (:ref:`Integrated_Preprocessing`). + + +.. index:: -gnateP (gcc) + +:samp:`-gnateP` + Turn categorization dependency errors into warnings. + Ada requires that units that WITH one another have compatible categories, for + example a Pure unit cannot WITH a Preelaborate unit. If this switch is used, + these errors become warnings (which can be ignored, or suppressed in the usual + manner). This can be useful in some specialized circumstances such as the + temporary use of special test software. + + +.. index:: -gnateS (gcc) + +:samp:`-gnateS` + Synonym of *-fdump-scos*, kept for backwards compatibility. + + +.. index:: -gnatet=file (gcc) + +:samp:`-gnatet={path}` + Generate target dependent information. The format of the output file is + described in the section about switch *-gnateT*. + + +.. index:: -gnateT (gcc) + +:samp:`-gnateT={path}` + Read target dependent information, such as endianness or sizes and alignments + of base type. If this switch is passed, the default target dependent + information of the compiler is replaced by the one read from the input file. + This is used by tools other than the compiler, e.g. to do + semantic analysis of programs that will run on some other target than + the machine on which the tool is run. + + The following target dependent values should be defined, + where `Nat` denotes a natural integer value, `Pos` denotes a + positive integer value, and fields marked with a question mark are + boolean fields, where a value of 0 is False, and a value of 1 is True: + + + :: + + Bits_BE : Nat; -- Bits stored big-endian? + Bits_Per_Unit : Pos; -- Bits in a storage unit + Bits_Per_Word : Pos; -- Bits in a word + Bytes_BE : Nat; -- Bytes stored big-endian? + Char_Size : Pos; -- Standard.Character'Size + Double_Float_Alignment : Nat; -- Alignment of double float + Double_Scalar_Alignment : Nat; -- Alignment of double length scalar + Double_Size : Pos; -- Standard.Long_Float'Size + Float_Size : Pos; -- Standard.Float'Size + Float_Words_BE : Nat; -- Float words stored big-endian? + Int_Size : Pos; -- Standard.Integer'Size + Long_Double_Size : Pos; -- Standard.Long_Long_Float'Size + Long_Long_Size : Pos; -- Standard.Long_Long_Integer'Size + Long_Size : Pos; -- Standard.Long_Integer'Size + Maximum_Alignment : Pos; -- Maximum permitted alignment + Max_Unaligned_Field : Pos; -- Maximum size for unaligned bit field + Pointer_Size : Pos; -- System.Address'Size + Short_Enums : Nat; -- Short foreign convention enums? + Short_Size : Pos; -- Standard.Short_Integer'Size + Strict_Alignment : Nat; -- Strict alignment? + System_Allocator_Alignment : Nat; -- Alignment for malloc calls + Wchar_T_Size : Pos; -- Interfaces.C.wchar_t'Size + Words_BE : Nat; -- Words stored big-endian? + + + The format of the input file is as follows. First come the values of + the variables defined above, with one line per value: + + + :: + + name value + + where `name` is the name of the parameter, spelled out in full, + and cased as in the above list, and `value` is an unsigned decimal + integer. Two or more blanks separates the name from the value. + + All the variables must be present, in alphabetical order (i.e. the + same order as the list above). + + Then there is a blank line to separate the two parts of the file. Then + come the lines showing the floating-point types to be registered, with + one line per registered mode: + + + :: + + name digs float_rep size alignment + + + where `name` is the string name of the type (which can have + single spaces embedded in the name (e.g. long double), `digs` is + the number of digits for the floating-point type, `float_rep` is + the float representation (I/V/A for IEEE-754-Binary, Vax_Native, + AAMP), `size` is the size in bits, `alignment` is the + alignment in bits. The name is followed by at least two blanks, fields + are separated by at least one blank, and a LF character immediately + follows the alignment field. + + Here is an example of a target parameterization file: + + + :: + + Bits_BE 0 + Bits_Per_Unit 8 + Bits_Per_Word 64 + Bytes_BE 0 + Char_Size 8 + Double_Float_Alignment 0 + Double_Scalar_Alignment 0 + Double_Size 64 + Float_Size 32 + Float_Words_BE 0 + Int_Size 64 + Long_Double_Size 128 + Long_Long_Size 64 + Long_Size 64 + Maximum_Alignment 16 + Max_Unaligned_Field 64 + Pointer_Size 64 + Short_Size 16 + Strict_Alignment 0 + System_Allocator_Alignment 16 + Wchar_T_Size 32 + Words_BE 0 + + float 15 I 64 64 + double 15 I 64 64 + long double 18 I 80 128 + TF 33 I 128 128 + + + +.. index:: -gnateu (gcc) + +:samp:`-gnateu` + Ignore unrecognized validity, warning, and style switches that + appear after this switch is given. This may be useful when + compiling sources developed on a later version of the compiler + with an earlier version. Of course the earlier version must + support this switch. + + +.. index:: -gnateV (gcc) + +:samp:`-gnateV` + Check that all actual parameters of a subprogram call are valid according to + the rules of validity checking (:ref:`Validity_Checking`). + + +.. index:: -gnateY (gcc) + +:samp:`-gnateY` + Ignore all STYLE_CHECKS pragmas. Full legality checks + are still carried out, but the pragmas have no effect + on what style checks are active. This allows all style + checking options to be controlled from the command line. + + +.. index:: -gnatE (gcc) + +:samp:`-gnatE` + Full dynamic elaboration checks. + + +.. index:: -gnatf (gcc) + +:samp:`-gnatf` + Full errors. Multiple errors per line, all undefined references, do not + attempt to suppress cascaded errors. + + +.. index:: -gnatF (gcc) + +:samp:`-gnatF` + Externals names are folded to all uppercase. + + +.. index:: -gnatg (gcc) + +:samp:`-gnatg` + Internal GNAT implementation mode. This should not be used for + applications programs, it is intended only for use by the compiler + and its run-time library. For documentation, see the GNAT sources. + Note that *-gnatg* implies + *-gnatw.ge* and + *-gnatyg* + so that all standard warnings and all standard style options are turned on. + All warnings and style messages are treated as errors. + + +.. index:: -gnatG[nn] (gcc) + +:samp:`-gnatG=nn` + List generated expanded code in source form. + + +.. index:: -gnath (gcc) + +:samp:`-gnath` + Output usage information. The output is written to :file:`stdout`. + + +.. index:: -gnati (gcc) + +:samp:`-gnati{c}` + Identifier character set (`c` = 1/2/3/4/8/9/p/f/n/w). + For details of the possible selections for `c`, + see :ref:`Character_Set_Control`. + + +.. index:: -gnatI (gcc) + +:samp:`-gnatI` + Ignore representation clauses. When this switch is used, + representation clauses are treated as comments. This is useful + when initially porting code where you want to ignore rep clause + problems, and also for compiling foreign code (particularly + for use with ASIS). The representation clauses that are ignored + are: enumeration_representation_clause, record_representation_clause, + and attribute_definition_clause for the following attributes: + Address, Alignment, Bit_Order, Component_Size, Machine_Radix, + Object_Size, Size, Small, Stream_Size, and Value_Size. + Note that this option should be used only for compiling -- the + code is likely to malfunction at run time. + + Note that when `-gnatct` is used to generate trees for input + into `ASIS` tools, these representation clauses are removed + from the tree and ignored. This means that the tool will not see them. + + +.. index:: -gnatjnn (gcc) + +:samp:`-gnatj{nn}` + Reformat error messages to fit on `nn` character lines + + +.. index:: -gnatk (gcc) + +:samp:`-gnatk={n}` + Limit file names to `n` (1-999) characters (`k` = krunch). + + +.. index:: -gnatl (gcc) + +:samp:`-gnatl` + Output full source listing with embedded error messages. + + +.. index:: -gnatL (gcc) + +:samp:`-gnatL` + Used in conjunction with -gnatG or -gnatD to intersperse original + source lines (as comment lines with line numbers) in the expanded + source output. + + +.. index:: -gnatm (gcc) + +:samp:`-gnatm={n}` + Limit number of detected error or warning messages to `n` + where `n` is in the range 1..999999. The default setting if + no switch is given is 9999. If the number of warnings reaches this + limit, then a message is output and further warnings are suppressed, + but the compilation is continued. If the number of error messages + reaches this limit, then a message is output and the compilation + is abandoned. The equal sign here is optional. A value of zero + means that no limit applies. + + +.. index:: -gnatn (gcc) + +:samp:`-gnatn[12]` + Activate inlining for subprograms for which pragma `Inline` is + specified. This inlining is performed by the GCC back-end. An optional + digit sets the inlining level: 1 for moderate inlining across modules + or 2 for full inlining across modules. If no inlining level is specified, + the compiler will pick it based on the optimization level. + + +.. index:: -gnatN (gcc) + +:samp:`-gnatN` + Activate front end inlining for subprograms for which + pragma `Inline` is specified. This inlining is performed + by the front end and will be visible in the + *-gnatG* output. + + When using a gcc-based back end (in practice this means using any version + of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of + *-gnatN* is deprecated, and the use of *-gnatn* is preferred. + Historically front end inlining was more extensive than the gcc back end + inlining, but that is no longer the case. + + +.. index:: -gnato0 (gcc) + +:samp:`-gnato0` + Suppresses overflow checking. This causes the behavior of the compiler to + match the default for older versions where overflow checking was suppressed + by default. This is equivalent to having + `pragma Suppress (Overflow_Mode)` in a configuration pragma file. + + +.. index:: -gnato?? (gcc) + +:samp:`-gnato??` + Set default mode for handling generation of code to avoid intermediate + arithmetic overflow. Here `??` is two digits, a + single digit, or nothing. Each digit is one of the digits `1` + through `3`: + + ===== =============================================================== + Digit Interpretation + ----- --------------------------------------------------------------- + *1* All intermediate overflows checked against base type (`STRICT`) + *2* Minimize intermediate overflows (`MINIMIZED`) + *3* Eliminate intermediate overflows (`ELIMINATED`) + ===== =============================================================== + + If only one digit appears then it applies to all + cases; if two digits are given, then the first applies outside + assertions, and the second within assertions. + + If no digits follow the *-gnato*, then it is equivalent to + *-gnato11*, + causing all intermediate overflows to be handled in strict mode. + + This switch also causes arithmetic overflow checking to be performed + (as though `pragma Unsuppress (Overflow_Mode)` had been specified. + + The default if no option *-gnato* is given is that overflow handling + is in `STRICT` mode (computations done using the base type), and that + overflow checking is enabled. + + Note that division by zero is a separate check that is not + controlled by this switch (division by zero checking is on by default). + + See also :ref:`Specifying_the_Desired_Mode`. + + +.. index:: -gnatp (gcc) + +:samp:`-gnatp` + Suppress all checks. See :ref:`Run-Time_Checks` for details. This switch + has no effect if cancelled by a subsequent *-gnat-p* switch. + + +.. index:: -gnat-p (gcc) + +:samp:`-gnat-p` + Cancel effect of previous *-gnatp* switch. + + +.. index:: -gnatP (gcc) + +:samp:`-gnatP` + Enable polling. This is required on some systems (notably Windows NT) to + obtain asynchronous abort and asynchronous transfer of control capability. + See `Pragma_Polling` in the :title:`GNAT_Reference_Manual` for full + details. + + +.. index:: -gnatq (gcc) + +:samp:`-gnatq` + Don't quit. Try semantics, even if parse errors. + + +.. index:: -gnatQ (gcc) + +:samp:`-gnatQ` + Don't quit. Generate :file:`ALI` and tree files even if illegalities. + Note that code generation is still suppressed in the presence of any + errors, so even with *-gnatQ* no object file is generated. + + +.. index:: -gnatr (gcc) + +:samp:`-gnatr` + Treat pragma Restrictions as Restriction_Warnings. + + +.. index:: -gnatR (gcc) + +:samp:`-gnatR[0/1/2/3[s]]` + Output representation information for declared types and objects. + Note that this switch is not allowed if a previous `-gnatD` switch has + been given, since these two switches are not compatible. + + +:samp:`-gnatRm[s]` + Output convention and parameter passing mechanisms for all subprograms. + + +.. index:: -gnats (gcc) + +:samp:`-gnats` + Syntax check only. + + +.. index:: -gnatS (gcc) + +:samp:`-gnatS` + Print package Standard. + + +.. index:: -gnatt (gcc) + +:samp:`-gnatt` + Generate tree output file. + + +.. index:: -gnatT (gcc) + +:samp:`-gnatT{nnn}` + All compiler tables start at `nnn` times usual starting size. + + +.. index:: -gnatu (gcc) + +:samp:`-gnatu` + List units for this compilation. + + +.. index:: -gnatU (gcc) + +:samp:`-gnatU` + Tag all error messages with the unique string 'error:' + + +.. index:: -gnatv (gcc) + +:samp:`-gnatv` + Verbose mode. Full error output with source lines to :file:`stdout`. + + +.. index:: -gnatV (gcc) + +:samp:`-gnatV` + Control level of validity checking (:ref:`Validity_Checking`). + + +.. index:: -gnatw (gcc) + +:samp:`-gnatw{xxx}` + Warning mode where + `xxx` is a string of option letters that denotes + the exact warnings that + are enabled or disabled (:ref:`Warning_Message_Control`). + + +.. index:: -gnatW (gcc) + +:samp:`-gnatW{e}` + Wide character encoding method + (`e`\ =n/h/u/s/e/8). + + +.. index:: -gnatx (gcc) + +:samp:`-gnatx` + Suppress generation of cross-reference information. + + +.. index:: -gnatX (gcc) + +:samp:`-gnatX` + Enable GNAT implementation extensions and latest Ada version. + + +.. index:: -gnaty (gcc) + +:samp:`-gnaty` + Enable built-in style checks (:ref:`Style_Checking`). + + +.. index:: -gnatz (gcc) + +:samp:`-gnatz{m}` + Distribution stub generation and compilation + (`m`\ =r/c for receiver/caller stubs). + + +.. index:: -I (gcc) + +:samp:`-I{dir}` + .. index:: RTL + + Direct GNAT to search the `dir` directory for source files needed by + the current compilation + (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). + + +.. index:: -I- (gcc) + +:samp:`-I-` + .. index:: RTL + + Except for the source file named in the command line, do not look for source + files in the directory containing the source file named in the command line + (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). + + +.. index:: -o (gcc) + +:samp:`-o {file}` + This switch is used in *gcc* to redirect the generated object file + and its associated ALI file. Beware of this switch with GNAT, because it may + cause the object file and ALI file to have different names which in turn + may confuse the binder and the linker. + + +.. index:: -nostdinc (gcc) + +:samp:`-nostdinc` + Inhibit the search of the default location for the GNAT Run Time + Library (RTL) source files. + + +.. index:: -nostdlib (gcc) + +:samp:`-nostdlib` + Inhibit the search of the default location for the GNAT Run Time + Library (RTL) ALI files. + + +.. index:: -O (gcc) + +:samp:`-O[{n}]` + `n` controls the optimization level: + + ======= ================================================================== + *n* Effect + ------- ------------------------------------------------------------------ + *0* No optimization, the default setting if no *-O* appears + *1* Normal optimization, the default if you specify *-O* without an + operand. A good compromise between code quality and compilation + time. + *2* Extensive optimization, may improve execution time, possibly at + the cost of substantially increased compilation time. + *3* Same as *-O2*, and also includes inline expansion for small + subprograms in the same unit. + *s* Optimize space usage + ======= ================================================================== + + See also :ref:`Optimization_Levels`. + + +.. index:: -pass-exit-codes (gcc) + +:samp:`-pass-exit-codes` + Catch exit codes from the compiler and use the most meaningful as + exit status. + + +.. index:: --RTS (gcc) + +:samp:`--RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + +.. index:: -S (gcc) + +:samp:`-S` + Used in place of *-c* to + cause the assembler source file to be + generated, using :file:`.s` as the extension, + instead of the object file. + This may be useful if you need to examine the generated assembly code. + + +.. index:: -fverbose-asm (gcc) + +:samp:`-fverbose-asm` + Used in conjunction with *-S* + to cause the generated assembly code file to be annotated with variable + names, making it significantly easier to follow. + + +.. index:: -v (gcc) + +:samp:`-v` + Show commands generated by the *gcc* driver. Normally used only for + debugging purposes or if you need to be sure what version of the + compiler you are executing. + + +.. index:: -V (gcc) + +:samp:`-V {ver}` + Execute `ver` version of the compiler. This is the *gcc* + version, not the GNAT version. + + +.. index:: -w (gcc) + +:samp:`-w` + Turn off warnings generated by the back end of the compiler. Use of + this switch also causes the default for front end warnings to be set + to suppress (as though *-gnatws* had appeared at the start of + the options). + + +.. index:: Combining GNAT switches + +You may combine a sequence of GNAT switches into a single switch. For +example, the combined switch + + :: + + -gnatofi3 + +is equivalent to specifying the following sequence of switches: + + :: + + -gnato -gnatf -gnati3 + +The following restrictions apply to the combination of switches +in this manner: + +* The switch *-gnatc* if combined with other switches must come + first in the string. + +* The switch *-gnats* if combined with other switches must come + first in the string. + +* The switches + *-gnatzc* and *-gnatzr* may not be combined with any other + switches, and only one of them may appear in the command line. + +* The switch *-gnat-p* may not be combined with any other switch. + +* Once a 'y' appears in the string (that is a use of the *-gnaty* + switch), then all further characters in the switch are interpreted + as style modifiers (see description of *-gnaty*). + +* Once a 'd' appears in the string (that is a use of the *-gnatd* + switch), then all further characters in the switch are interpreted + as debug flags (see description of *-gnatd*). + +* Once a 'w' appears in the string (that is a use of the *-gnatw* + switch), then all further characters in the switch are interpreted + as warning mode modifiers (see description of *-gnatw*). + +* Once a 'V' appears in the string (that is a use of the *-gnatV* + switch), then all further characters in the switch are interpreted + as validity checking options (:ref:`Validity_Checking`). + +* Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in + a combined list of options. + +.. _Output_and_Error_Message_Control: + +Output and Error Message Control +-------------------------------- + +.. index:: stderr + +The standard default format for error messages is called 'brief format'. +Brief format messages are written to :file:`stderr` (the standard error +file) and have the following form: + +:: + + e.adb:3:04: Incorrect spelling of keyword "function" + e.adb:4:20: ";" should be "is" + +The first integer after the file name is the line number in the file, +and the second integer is the column number within the line. +`GPS` can parse the error messages +and point to the referenced character. +The following switches provide control over the error message +format: + + +.. index:: -gnatv (gcc) + +:samp:`-gnatv` + The `v` stands for verbose. + The effect of this setting is to write long-format error + messages to :file:`stdout` (the standard output file. + The same program compiled with the + *-gnatv* switch would generate: + + :: + + 3. funcion X (Q : Integer) + | + >>> Incorrect spelling of keyword "function" + 4. return Integer; + | + >>> ";" should be "is" + + + The vertical bar indicates the location of the error, and the :samp:`>>>` + prefix can be used to search for error messages. When this switch is + used the only source lines output are those with errors. + + +.. index:: -gnatl (gcc) + +:samp:`-gnatl` + The `l` stands for list. + This switch causes a full listing of + the file to be generated. In the case where a body is + compiled, the corresponding spec is also listed, along + with any subunits. Typical output from compiling a package + body :file:`p.adb` might look like:: + + Compiling: p.adb + + 1. package body p is + 2. procedure a; + 3. procedure a is separate; + 4. begin + 5. null + | + >>> missing ";" + + 6. end; + + Compiling: p.ads + + 1. package p is + 2. pragma Elaborate_Body + | + >>> missing ";" + + 3. end p; + + Compiling: p-a.adb + + 1. separate p + | + >>> missing "(" + + 2. procedure a is + 3. begin + 4. null + | + >>> missing ";" + + 5. end; + + + When you specify the *-gnatv* or *-gnatl* switches and + standard output is redirected, a brief summary is written to + :file:`stderr` (standard error) giving the number of error messages and + warning messages generated. + + +.. index:: -gnatl=fname (gcc) + +:samp:`-gnatl={fname}` + This has the same effect as *-gnatl* except that the output is + written to a file instead of to standard output. If the given name + :file:`fname` does not start with a period, then it is the full name + of the file to be written. If :file:`fname` is an extension, it is + appended to the name of the file being compiled. For example, if + file :file:`xyz.adb` is compiled with *-gnatl=.lst*, + then the output is written to file xyz.adb.lst. + + +.. index:: -gnatU (gcc) + +:samp:`-gnatU` + This switch forces all error messages to be preceded by the unique + string 'error:'. This means that error messages take a few more + characters in space, but allows easy searching for and identification + of error messages. + + +.. index:: -gnatb (gcc) + +:samp:`-gnatb` + The `b` stands for brief. + This switch causes GNAT to generate the + brief format error messages to :file:`stderr` (the standard error + file) as well as the verbose + format message or full listing (which as usual is written to + :file:`stdout` (the standard output file). + + +.. index:: -gnatm (gcc) + +:samp:`-gnatm={n}` + The `m` stands for maximum. + `n` is a decimal integer in the + range of 1 to 999999 and limits the number of error or warning + messages to be generated. For example, using + *-gnatm2* might yield + + :: + + e.adb:3:04: Incorrect spelling of keyword "function" + e.adb:5:35: missing ".." + fatal error: maximum number of errors detected + compilation abandoned + + + The default setting if + no switch is given is 9999. If the number of warnings reaches this + limit, then a message is output and further warnings are suppressed, + but the compilation is continued. If the number of error messages + reaches this limit, then a message is output and the compilation + is abandoned. A value of zero means that no limit applies. + + Note that the equal sign is optional, so the switches + *-gnatm2* and *-gnatm=2* are equivalent. + + +.. index:: -gnatf (gcc) + +:samp:`-gnatf` + .. index:: Error messages, suppressing + + The `f` stands for full. + Normally, the compiler suppresses error messages that are likely to be + redundant. This switch causes all error + messages to be generated. In particular, in the case of + references to undefined variables. If a given variable is referenced + several times, the normal format of messages is + + :: + + e.adb:7:07: "V" is undefined (more references follow) + + where the parenthetical comment warns that there are additional + references to the variable `V`. Compiling the same program with the + *-gnatf* switch yields + + :: + + e.adb:7:07: "V" is undefined + e.adb:8:07: "V" is undefined + e.adb:8:12: "V" is undefined + e.adb:8:16: "V" is undefined + e.adb:9:07: "V" is undefined + e.adb:9:12: "V" is undefined + + The *-gnatf* switch also generates additional information for + some error messages. Some examples are: + + * Details on possibly non-portable unchecked conversion + + * List possible interpretations for ambiguous calls + + * Additional details on incorrect parameters + + +.. index:: -gnatjnn (gcc) + +:samp:`-gnatjnn` + In normal operation mode (or if *-gnatj0* is used), then error messages + with continuation lines are treated as though the continuation lines were + separate messages (and so a warning with two continuation lines counts as + three warnings, and is listed as three separate messages). + + If the *-gnatjnn* switch is used with a positive value for nn, then + messages are output in a different manner. A message and all its continuation + lines are treated as a unit, and count as only one warning or message in the + statistics totals. Furthermore, the message is reformatted so that no line + is longer than nn characters. + + +.. index:: -gnatq (gcc) + +:samp:`-gnatq` + The `q` stands for quit (really 'don't quit'). + In normal operation mode, the compiler first parses the program and + determines if there are any syntax errors. If there are, appropriate + error messages are generated and compilation is immediately terminated. + This switch tells + GNAT to continue with semantic analysis even if syntax errors have been + found. This may enable the detection of more errors in a single run. On + the other hand, the semantic analyzer is more likely to encounter some + internal fatal error when given a syntactically invalid tree. + + +.. index:: -gnatQ (gcc) + +:samp:`-gnatQ` + In normal operation mode, the :file:`ALI` file is not generated if any + illegalities are detected in the program. The use of *-gnatQ* forces + generation of the :file:`ALI` file. This file is marked as being in + error, so it cannot be used for binding purposes, but it does contain + reasonably complete cross-reference information, and thus may be useful + for use by tools (e.g., semantic browsing tools or integrated development + environments) that are driven from the :file:`ALI` file. This switch + implies *-gnatq*, since the semantic phase must be run to get a + meaningful ALI file. + + In addition, if *-gnatt* is also specified, then the tree file is + generated even if there are illegalities. It may be useful in this case + to also specify *-gnatq* to ensure that full semantic processing + occurs. The resulting tree file can be processed by ASIS, for the purpose + of providing partial information about illegal units, but if the error + causes the tree to be badly malformed, then ASIS may crash during the + analysis. + + When *-gnatQ* is used and the generated :file:`ALI` file is marked as + being in error, *gnatmake* will attempt to recompile the source when it + finds such an :file:`ALI` file, including with switch *-gnatc*. + + Note that *-gnatQ* has no effect if *-gnats* is specified, + since ALI files are never generated if *-gnats* is set. + + +.. _Warning_Message_Control: + +Warning Message Control +----------------------- + +.. index:: Warning messages + +In addition to error messages, which correspond to illegalities as defined +in the Ada Reference Manual, the compiler detects two kinds of warning +situations. + +First, the compiler considers some constructs suspicious and generates a +warning message to alert you to a possible error. Second, if the +compiler detects a situation that is sure to raise an exception at +run time, it generates a warning message. The following shows an example +of warning messages: + +:: + + e.adb:4:24: warning: creation of object may raise Storage_Error + e.adb:10:17: warning: static value out of range + e.adb:10:17: warning: "Constraint_Error" will be raised at run time + + +GNAT considers a large number of situations as appropriate +for the generation of warning messages. As always, warnings are not +definite indications of errors. For example, if you do an out-of-range +assignment with the deliberate intention of raising a +`Constraint_Error` exception, then the warning that may be +issued does not indicate an error. Some of the situations for which GNAT +issues warnings (at least some of the time) are given in the following +list. This list is not complete, and new warnings are often added to +subsequent versions of GNAT. The list is intended to give a general idea +of the kinds of warnings that are generated. + +* Possible infinitely recursive calls + +* Out-of-range values being assigned + +* Possible order of elaboration problems + +* Size not a multiple of alignment for a record type + +* Assertions (pragma Assert) that are sure to fail + +* Unreachable code + +* Address clauses with possibly unaligned values, or where an attempt is + made to overlay a smaller variable with a larger one. + +* Fixed-point type declarations with a null range + +* Direct_IO or Sequential_IO instantiated with a type that has access values + +* Variables that are never assigned a value + +* Variables that are referenced before being initialized + +* Task entries with no corresponding `accept` statement + +* Duplicate accepts for the same task entry in a `select` + +* Objects that take too much storage + +* Unchecked conversion between types of differing sizes + +* Missing `return` statement along some execution path in a function + +* Incorrect (unrecognized) pragmas + +* Incorrect external names + +* Allocation from empty storage pool + +* Potentially blocking operation in protected type + +* Suspicious parenthesization of expressions + +* Mismatching bounds in an aggregate + +* Attempt to return local value by reference + +* Premature instantiation of a generic body + +* Attempt to pack aliased components + +* Out of bounds array subscripts + +* Wrong length on string assignment + +* Violations of style rules if style checking is enabled + +* Unused |with| clauses + +* `Bit_Order` usage that does not have any effect + +* `Standard.Duration` used to resolve universal fixed expression + +* Dereference of possibly null value + +* Declaration that is likely to cause storage error + +* Internal GNAT unit |withed| by application unit + +* Values known to be out of range at compile time + +* Unreferenced or unmodified variables. Note that a special + exemption applies to variables which contain any of the substrings + `DISCARD, DUMMY, IGNORE, JUNK, UNUSED`, in any casing. Such variables + are considered likely to be intentionally used in a situation where + otherwise a warning would be given, so warnings of this kind are + always suppressed for such variables. + +* Address overlays that could clobber memory + +* Unexpected initialization when address clause present + +* Bad alignment for address clause + +* Useless type conversions + +* Redundant assignment statements and other redundant constructs + +* Useless exception handlers + +* Accidental hiding of name by child unit + +* Access before elaboration detected at compile time + +* A range in a `for` loop that is known to be null or might be null + + +The following section lists compiler switches that are available +to control the handling of warning messages. It is also possible +to exercise much finer control over what warnings are issued and +suppressed using the GNAT pragma Warnings (see the description +of the pragma in the :title:`GNAT_Reference_manual`). + + +.. index:: -gnatwa (gcc) + +:samp:`-gnatwa` + *Activate most optional warnings.* + + This switch activates most optional warning messages. See the remaining list + in this section for details on optional warning messages that can be + individually controlled. The warnings that are not turned on by this + switch are: + + + * :samp:`-gnatwd` (implicit dereferencing) + + * :samp:`-gnatw.d` (tag warnings with -gnatw switch) + + * :samp:`-gnatwh` (hiding) + + * :samp:`-gnatw.h` (holes in record layouts) + + * :samp:`-gnatw.k` (redefinition of names in standard) + + * :samp:`-gnatwl` (elaboration warnings) + + * :samp:`-gnatw.l` (inherited aspects) + + * :samp:`-gnatw.n` (atomic synchronization) + + * :samp:`-gnatwo` (address clause overlay) + + * :samp:`-gnatw.o` (values set by out parameters ignored) + + * :samp:`-gnatw.s` (overridden size clause) + + * :samp:`-gnatwt` (tracking of deleted conditional code) + + * :samp:`-gnatw.u` (unordered enumeration) + + * :samp:`-gnatw.w` (use of Warnings Off) + + * :samp:`-gnatw.y` (reasons for package needing body) + + All other optional warnings are turned on. + + +.. index:: -gnatwA (gcc) + +:samp:`-gnatwA` + *Suppress all optional errors.* + + This switch suppresses all optional warning messages, see remaining list + in this section for details on optional warning messages that can be + individually controlled. Note that unlike switch *-gnatws*, the + use of switch *-gnatwA* does not suppress warnings that are + normally given unconditionally and cannot be individually controlled + (for example, the warning about a missing exit path in a function). + Also, again unlike switch *-gnatws*, warnings suppressed by + the use of switch *-gnatwA* can be individually turned back + on. For example the use of switch *-gnatwA* followed by + switch *-gnatwd* will suppress all optional warnings except + the warnings for implicit dereferencing. + +.. index:: -gnatw.a (gcc) + +:samp:`-gnatw.a` + *Activate warnings on failing assertions.* + + .. index:: Assert failures + + This switch activates warnings for assertions where the compiler can tell at + compile time that the assertion will fail. Note that this warning is given + even if assertions are disabled. The default is that such warnings are + generated. + + +.. index:: -gnatw.A (gcc) + +:samp:`-gnatw.A` + *Suppress warnings on failing assertions.* + + .. index:: Assert failures + + This switch suppresses warnings for assertions where the compiler can tell at + compile time that the assertion will fail. + + +.. index:: -gnatwb (gcc) + +:samp:`-gnatwb` + *Activate warnings on bad fixed values.* + + .. index:: Bad fixed values + + .. index:: Fixed-point Small value + + .. index:: Small value + + This switch activates warnings for static fixed-point expressions whose + value is not an exact multiple of Small. Such values are implementation + dependent, since an implementation is free to choose either of the multiples + that surround the value. GNAT always chooses the closer one, but this is not + required behavior, and it is better to specify a value that is an exact + multiple, ensuring predictable execution. The default is that such warnings + are not generated. + + +.. index:: -gnatwB (gcc) + +:samp:`-gnatwB` + *Suppress warnings on bad fixed values.* + + This switch suppresses warnings for static fixed-point expressions whose + value is not an exact multiple of Small. + + +.. index:: -gnatw.b (gcc) + +:samp:`-gnatw.b` + *Activate warnings on biased representation.* + + .. index:: Biased representation + + This switch activates warnings when a size clause, value size clause, component + clause, or component size clause forces the use of biased representation for an + integer type (e.g. representing a range of 10..11 in a single bit by using 0/1 + to represent 10/11). The default is that such warnings are generated. + + +.. index:: -gnatwB (gcc) + +:samp:`-gnatw.B` + *Suppress warnings on biased representation.* + + This switch suppresses warnings for representation clauses that force the use + of biased representation. + + +.. index:: -gnatwc (gcc) + +:samp:`-gnatwc` + *Activate warnings on conditionals.* + + .. index:: Conditionals, constant + + This switch activates warnings for conditional expressions used in + tests that are known to be True or False at compile time. The default + is that such warnings are not generated. + Note that this warning does + not get issued for the use of boolean variables or constants whose + values are known at compile time, since this is a standard technique + for conditional compilation in Ada, and this would generate too many + false positive warnings. + + This warning option also activates a special test for comparisons using + the operators '>=' and' <='. + If the compiler can tell that only the equality condition is possible, + then it will warn that the '>' or '<' part of the test + is useless and that the operator could be replaced by '='. + An example would be comparing a `Natural` variable <= 0. + + This warning option also generates warnings if + one or both tests is optimized away in a membership test for integer + values if the result can be determined at compile time. Range tests on + enumeration types are not included, since it is common for such tests + to include an end point. + + This warning can also be turned on using *-gnatwa*. + + +.. index:: -gnatwC (gcc) + +:samp:`-gnatwC` + *Suppress warnings on conditionals.* + + This switch suppresses warnings for conditional expressions used in + tests that are known to be True or False at compile time. + + +.. index:: -gnatw.c (gcc) + +:samp:`-gnatw.c` + *Activate warnings on missing component clauses.* + + .. index:: Component clause, missing + + This switch activates warnings for record components where a record + representation clause is present and has component clauses for the + majority, but not all, of the components. A warning is given for each + component for which no component clause is present. + + +.. index:: -gnatwC (gcc) + +:samp:`-gnatw.C` + *Suppress warnings on missing component clauses.* + + This switch suppresses warnings for record components that are + missing a component clause in the situation described above. + + +.. index:: -gnatwd (gcc) + +:samp:`-gnatwd` + *Activate warnings on implicit dereferencing.* + + If this switch is set, then the use of a prefix of an access type + in an indexed component, slice, or selected component without an + explicit `.all` will generate a warning. With this warning + enabled, access checks occur only at points where an explicit + `.all` appears in the source code (assuming no warnings are + generated as a result of this switch). The default is that such + warnings are not generated. + + +.. index:: -gnatwD (gcc) + +:samp:`-gnatwD` + *Suppress warnings on implicit dereferencing.* + + .. index:: Implicit dereferencing + + .. index:: Dereferencing, implicit + + This switch suppresses warnings for implicit dereferences in + indexed components, slices, and selected components. + + +.. index:: -gnatw.d (gcc) + +:samp:`-gnatw.d` + *Activate tagging of warning and info messages.* + + If this switch is set, then warning messages are tagged, with one of the + following strings: + + - *[-gnatw?]* + Used to tag warnings controlled by the switch *-gnatwx* where x + is a letter a-z. + + + - *[-gnatw.?]* + Used to tag warnings controlled by the switch *-gnatw.x* where x + is a letter a-z. + + + - *[-gnatel]* + Used to tag elaboration information (info) messages generated when the + static model of elaboration is used and the *-gnatel* switch is set. + + + - *[restriction warning]* + Used to tag warning messages for restriction violations, activated by use + of the pragma *Restriction_Warnings*. + + + - *[warning-as-error]* + Used to tag warning messages that have been converted to error messages by + use of the pragma Warning_As_Error. Note that such warnings are prefixed by + the string "error: " rather than "warning: ". + + + - *[enabled by default]* + Used to tag all other warnings that are always given by default, unless + warnings are completely suppressed using pragma *Warnings(Off)* or + the switch *-gnatws*. + + + +.. index:: -gnatw.d (gcc) + +:samp:`-gnatw.D` + *Deactivate tagging of warning and info messages messages.* + + If this switch is set, then warning messages return to the default + mode in which warnings and info messages are not tagged as described above for + `-gnatw.d`. + + +.. index:: -gnatwe (gcc) +.. index:: Warnings, treat as error + +:samp:`-gnatwe` + *Treat warnings and style checks as errors.* + + This switch causes warning messages and style check messages to be + treated as errors. + The warning string still appears, but the warning messages are counted + as errors, and prevent the generation of an object file. Note that this + is the only -gnatw switch that affects the handling of style check messages. + Note also that this switch has no effect on info (information) messages, which + are not treated as errors if this switch is present. + + +.. index:: -gnatw.e (gcc) + +:samp:`-gnatw.e` + *Activate every optional warning* + + .. index:: Warnings, activate every optional warning + + This switch activates all optional warnings, including those which + are not activated by `-gnatwa`. The use of this switch is not + recommended for normal use. If you turn this switch on, it is almost + certain that you will get large numbers of useless warnings. The + warnings that are excluded from `-gnatwa` are typically highly + specialized warnings that are suitable for use only in code that has + been specifically designed according to specialized coding rules. + + +.. index:: -gnatwf (gcc) + +:samp:`-gnatwf` + *Activate warnings on unreferenced formals.* + + .. index:: Formals, unreferenced + + This switch causes a warning to be generated if a formal parameter + is not referenced in the body of the subprogram. This warning can + also be turned on using *-gnatwu*. The + default is that these warnings are not generated. + + +.. index:: -gnatwF (gcc) + +:samp:`-gnatwF` + *Suppress warnings on unreferenced formals.* + + This switch suppresses warnings for unreferenced formal + parameters. Note that the + combination *-gnatwu* followed by *-gnatwF* has the + effect of warning on unreferenced entities other than subprogram + formals. + + +.. index:: -gnatwg (gcc) + +:samp:`-gnatwg` + *Activate warnings on unrecognized pragmas.* + + .. index:: Pragmas, unrecognized + + This switch causes a warning to be generated if an unrecognized + pragma is encountered. Apart from issuing this warning, the + pragma is ignored and has no effect. The default + is that such warnings are issued (satisfying the Ada Reference + Manual requirement that such warnings appear). + + +.. index:: -gnatwG (gcc) + +:samp:`-gnatwG` + *Suppress warnings on unrecognized pragmas.* + + This switch suppresses warnings for unrecognized pragmas. + + +.. index:: -gnatw.g (gcc) + +:samp:`-gnatw.g` + *Warnings used for GNAT sources* + + This switch sets the warning categories that are used by the standard + GNAT style. Currently this is equivalent to + *-gnatwAao.sI.C.V.X* + but more warnings may be added in the future without advanced notice. + + +.. index:: -gnatwh (gcc) + +:samp:`-gnatwh` + *Activate warnings on hiding.* + + .. index:: Hiding of Declarations + + This switch activates warnings on hiding declarations. + A declaration is considered hiding + if it is for a non-overloadable entity, and it declares an entity with the + same name as some other entity that is directly or use-visible. The default + is that such warnings are not generated. + + +.. index:: -gnatwH (gcc) + +:samp:`-gnatwH` + *Suppress warnings on hiding.* + + This switch suppresses warnings on hiding declarations. + + +.. index:: -gnatw.h (gcc) + +:samp:`-gnatw.h` + *Activate warnings on holes/gaps in records.* + + .. index:: Record Representation (gaps) + + This switch activates warnings on component clauses in record + representation clauses that leave holes (gaps) in the record layout. + If this warning option is active, then record representation clauses + should specify a contiguous layout, adding unused fill fields if needed. + + +.. index:: -gnatw.H (gcc) + +:samp:`-gnatw.H` + *Suppress warnings on holes/gaps in records.* + + This switch suppresses warnings on component clauses in record + representation clauses that leave holes (haps) in the record layout. + + +.. index:: -gnatwi (gcc) + +:samp:`-gnatwi` + *Activate warnings on implementation units.* + + This switch activates warnings for a |with| of an internal GNAT + implementation unit, defined as any unit from the `Ada`, + `Interfaces`, `GNAT`, + or `System` + hierarchies that is not + documented in either the Ada Reference Manual or the GNAT + Programmer's Reference Manual. Such units are intended only + for internal implementation purposes and should not be |withed| + by user programs. The default is that such warnings are generated + + +.. index:: -gnatwI (gcc) + +:samp:`-gnatwI` + *Disable warnings on implementation units.* + + This switch disables warnings for a |with| of an internal GNAT + implementation unit. + + +.. index:: -gnatw.i (gcc) + +:samp:`-gnatw.i` + *Activate warnings on overlapping actuals.* + + This switch enables a warning on statically detectable overlapping actuals in + a subprogram call, when one of the actuals is an in-out parameter, and the + types of the actuals are not by-copy types. This warning is off by default. + + +.. index:: -gnatw.I (gcc) + +:samp:`-gnatw.I` + *Disable warnings on overlapping actuals.* + + This switch disables warnings on overlapping actuals in a call.. + + +.. index:: -gnatwj (gcc) + +:samp:`-gnatwj` + *Activate warnings on obsolescent features (Annex J).* + + .. index:: Features, obsolescent + + .. index:: Obsolescent features + + If this warning option is activated, then warnings are generated for + calls to subprograms marked with `pragma Obsolescent` and + for use of features in Annex J of the Ada Reference Manual. In the + case of Annex J, not all features are flagged. In particular use + of the renamed packages (like `Text_IO`) and use of package + `ASCII` are not flagged, since these are very common and + would generate many annoying positive warnings. The default is that + such warnings are not generated. + + In addition to the above cases, warnings are also generated for + GNAT features that have been provided in past versions but which + have been superseded (typically by features in the new Ada standard). + For example, `pragma Ravenscar` will be flagged since its + function is replaced by `pragma Profile(Ravenscar)`, and + `pragma Interface_Name` will be flagged since its function + is replaced by `pragma Import`. + + Note that this warning option functions differently from the + restriction `No_Obsolescent_Features` in two respects. + First, the restriction applies only to annex J features. + Second, the restriction does flag uses of package `ASCII`. + + +:samp:`-gnatwJ` + *Suppress warnings on obsolescent features (Annex J).* + .. index:: -gnatwJ (gcc) + + This switch disables warnings on use of obsolescent features. + + +:samp:`-gnatwk` + *Activate warnings on variables that could be constants.* + .. index:: -gnatwk (gcc) + + This switch activates warnings for variables that are initialized but + never modified, and then could be declared constants. The default is that + such warnings are not given. + + +.. index:: -gnatwK (gcc) + +:samp:`-gnatwK` + *Suppress warnings on variables that could be constants.* + + This switch disables warnings on variables that could be declared constants. + + +.. index:: -gnatw.k (gcc) + +:samp:`-gnatw.k` + *Activate warnings on redefinition of names in standard.* + + This switch activates warnings for declarations that declare a name that + is defined in package Standard. Such declarations can be confusing, + especially since the names in package Standard continue to be directly + visible, meaning that use visibiliy on such redeclared names does not + work as expected. Names of discriminants and components in records are + not included in this check. + + +.. index:: -gnatwK (gcc) + +:samp:`-gnatw.K` + *Suppress warnings on redefinition of names in standard.* + + This switch activates warnings for declarations that declare a name that + is defined in package Standard. + + +.. index:: -gnatwl (gcc) + +:samp:`-gnatwl` + *Activate warnings for elaboration pragmas.* + + .. index:: Elaboration, warnings + + This switch activates warnings for possible elaboration problems, + including suspicious use + of `Elaborate` pragmas, when using the static elaboration model, and + possible situations that may raise `Program_Error` when using the + dynamic elaboration model. + See the section in this guide on elaboration checking for further details. + The default is that such warnings + are not generated. + + +.. index:: -gnatwL (gcc) + +:samp:`-gnatwL` + *Suppress warnings for elaboration pragmas.* + + This switch suppresses warnings for possible elaboration problems. + + +.. index:: -gnatw.l (gcc) + +:samp:`-gnatw.l` + *List inherited aspects.* + + This switch causes the compiler to list inherited invariants, + preconditions, and postconditions from Type_Invariant'Class, Invariant'Class, + Pre'Class, and Post'Class aspects. Also list inherited subtype predicates. + + +.. index:: -gnatw.L (gcc) + +:samp:`-gnatw.L` + *Suppress listing of inherited aspects.* + + This switch suppresses listing of inherited aspects. + + +.. index:: -gnatwm (gcc) + +:samp:`-gnatwm` + *Activate warnings on modified but unreferenced variables.* + + This switch activates warnings for variables that are assigned (using + an initialization value or with one or more assignment statements) but + whose value is never read. The warning is suppressed for volatile + variables and also for variables that are renamings of other variables + or for which an address clause is given. + The default is that these warnings are not given. + + +.. index:: -gnatwM (gcc) + +:samp:`-gnatwM` + *Disable warnings on modified but unreferenced variables.* + + This switch disables warnings for variables that are assigned or + initialized, but never read. + + +.. index:: -gnatw.m (gcc) + +:samp:`-gnatw.m` + *Activate warnings on suspicious modulus values.* + + This switch activates warnings for modulus values that seem suspicious. + The cases caught are where the size is the same as the modulus (e.g. + a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64 + with no size clause. The guess in both cases is that 2**x was intended + rather than x. In addition expressions of the form 2*x for small x + generate a warning (the almost certainly accurate guess being that + 2**x was intended). The default is that these warnings are given. + + +.. index:: -gnatw.M (gcc) + +:samp:`-gnatw.M` + *Disable warnings on suspicious modulus values.* + + This switch disables warnings for suspicious modulus values. + + +.. index:: -gnatwn (gcc) + +:samp:`-gnatwn` + *Set normal warnings mode.* + + This switch sets normal warning mode, in which enabled warnings are + issued and treated as warnings rather than errors. This is the default + mode. the switch *-gnatwn* can be used to cancel the effect of + an explicit *-gnatws* or + *-gnatwe*. It also cancels the effect of the + implicit *-gnatwe* that is activated by the + use of *-gnatg*. + + +.. index:: -gnatw.n (gcc) +.. index:: Atomic Synchronization, warnings + +:samp:`-gnatw.n` + *Activate warnings on atomic synchronization.* + + This switch actives warnings when an access to an atomic variable + requires the generation of atomic synchronization code. These + warnings are off by default. + +.. index:: -gnatw.N (gcc) + +:samp:`-gnatw.N` + *Suppress warnings on atomic synchronization.* + + .. index:: Atomic Synchronization, warnings + + This switch suppresses warnings when an access to an atomic variable + requires the generation of atomic synchronization code. + + +.. index:: -gnatwo (gcc) +.. index:: Address Clauses, warnings + +:samp:`-gnatwo` + *Activate warnings on address clause overlays.* + + This switch activates warnings for possibly unintended initialization + effects of defining address clauses that cause one variable to overlap + another. The default is that such warnings are generated. + + +.. index:: -gnatwO (gcc) + +:samp:`-gnatwO` + *Suppress warnings on address clause overlays.* + + This switch suppresses warnings on possibly unintended initialization + effects of defining address clauses that cause one variable to overlap + another. + + +.. index:: -gnatw.o (gcc) + +:samp:`-gnatw.o` + *Activate warnings on modified but unreferenced out parameters.* + + This switch activates warnings for variables that are modified by using + them as actuals for a call to a procedure with an out mode formal, where + the resulting assigned value is never read. It is applicable in the case + where there is more than one out mode formal. If there is only one out + mode formal, the warning is issued by default (controlled by -gnatwu). + The warning is suppressed for volatile + variables and also for variables that are renamings of other variables + or for which an address clause is given. + The default is that these warnings are not given. + + +.. index:: -gnatw.O (gcc) + +:samp:`-gnatw.O` + *Disable warnings on modified but unreferenced out parameters.* + + This switch suppresses warnings for variables that are modified by using + them as actuals for a call to a procedure with an out mode formal, where + the resulting assigned value is never read. + + +.. index:: -gnatwp (gcc) +.. index:: Inlining, warnings + +:samp:`-gnatwp` + *Activate warnings on ineffective pragma Inlines.* + + This switch activates warnings for failure of front end inlining + (activated by *-gnatN*) to inline a particular call. There are + many reasons for not being able to inline a call, including most + commonly that the call is too complex to inline. The default is + that such warnings are not given. + Warnings on ineffective inlining by the gcc back-end can be activated + separately, using the gcc switch -Winline. + + +.. index:: -gnatwP (gcc) + +:samp:`-gnatwP` + *Suppress warnings on ineffective pragma Inlines.* + + This switch suppresses warnings on ineffective pragma Inlines. If the + inlining mechanism cannot inline a call, it will simply ignore the + request silently. + + +.. index:: -gnatw.p (gcc) +.. index:: Parameter order, warnings + +:samp:`-gnatw.p` + *Activate warnings on parameter ordering.* + + This switch activates warnings for cases of suspicious parameter + ordering when the list of arguments are all simple identifiers that + match the names of the formals, but are in a different order. The + warning is suppressed if any use of named parameter notation is used, + so this is the appropriate way to suppress a false positive (and + serves to emphasize that the "misordering" is deliberate). The + default is that such warnings are not given. + + +.. index:: -gnatw.P (gcc) + +:samp:`-gnatw.P` + *Suppress warnings on parameter ordering.* + + This switch suppresses warnings on cases of suspicious parameter + ordering. + + +.. index:: -gnatwq (gcc) +.. index:: Parentheses, warnings + +:samp:`-gnatwq` + *Activate warnings on questionable missing parentheses.* + + This switch activates warnings for cases where parentheses are not used and + the result is potential ambiguity from a readers point of view. For example + (not a > b) when a and b are modular means ((not a) > b) and very likely the + programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and + quite likely ((-x) mod 5) was intended. In such situations it seems best to + follow the rule of always parenthesizing to make the association clear, and + this warning switch warns if such parentheses are not present. The default + is that these warnings are given. + + +.. index:: -gnatwQ (gcc) + +:samp:`-gnatwQ` + *Suppress warnings on questionable missing parentheses.* + + This switch suppresses warnings for cases where the association is not + clear and the use of parentheses is preferred. + + +.. index:: -gnatwr (gcc) + +:samp:`-gnatwr` + *Activate warnings on redundant constructs.* + + This switch activates warnings for redundant constructs. The following + is the current list of constructs regarded as redundant: + + * Assignment of an item to itself. + + * Type conversion that converts an expression to its own type. + + * Use of the attribute `Base` where `typ'Base` is the same + as `typ`. + + * Use of pragma `Pack` when all components are placed by a record + representation clause. + + * Exception handler containing only a reraise statement (raise with no + operand) which has no effect. + + * Use of the operator abs on an operand that is known at compile time + to be non-negative + + * Comparison of boolean expressions to an explicit True value. + + The default is that warnings for redundant constructs are not given. + + +.. index:: -gnatwR (gcc) + +:samp:`-gnatwR` + *Suppress warnings on redundant constructs.* + + This switch suppresses warnings for redundant constructs. + + +.. index:: -gnatw.r (gcc) + +:samp:`-gnatw.r` + *Activate warnings for object renaming function.* + + This switch activates warnings for an object renaming that renames a + function call, which is equivalent to a constant declaration (as + opposed to renaming the function itself). The default is that these + warnings are given. + + +.. index:: -gnatwT (gcc) + +:samp:`-gnatw.R` + *Suppress warnings for object renaming function.* + + This switch suppresses warnings for object renaming function. + + +.. index:: -gnatws (gcc) + +:samp:`-gnatws` + *Suppress all warnings.* + + This switch completely suppresses the + output of all warning messages from the GNAT front end, including + both warnings that can be controlled by switches described in this + section, and those that are normally given unconditionally. The + effect of this suppress action can only be cancelled by a subsequent + use of the switch *-gnatwn*. + + Note that switch *-gnatws* does not suppress + warnings from the *gcc* back end. + To suppress these back end warnings as well, use the switch *-w* + in addition to *-gnatws*. Also this switch has no effect on the + handling of style check messages. + + +.. index:: -gnatw.s (gcc) +.. index:: Record Representation (component sizes) + +:samp:`-gnatw.s` + *Activate warnings on overridden size clauses.* + + This switch activates warnings on component clauses in record + representation clauses where the length given overrides that + specified by an explicit size clause for the component type. A + warning is similarly given in the array case if a specified + component size overrides an explicit size clause for the array + component type. + + +.. index:: -gnatw.S (gcc) + +:samp:`-gnatw.S` + *Suppress warnings on overridden size clauses.* + + This switch suppresses warnings on component clauses in record + representation clauses that override size clauses, and similar + warnings when an array component size overrides a size clause. + + +.. index:: -gnatwt (gcc) +.. index:: Deactivated code, warnings +.. index:: Deleted code, warnings + +:samp:`-gnatwt` + *Activate warnings for tracking of deleted conditional code.* + + This switch activates warnings for tracking of code in conditionals (IF and + CASE statements) that is detected to be dead code which cannot be executed, and + which is removed by the front end. This warning is off by default. This may be + useful for detecting deactivated code in certified applications. + + +.. index:: -gnatwT (gcc) + +:samp:`-gnatwT` + *Suppress warnings for tracking of deleted conditional code.* + + This switch suppresses warnings for tracking of deleted conditional code. + + +.. index:: -gnatw.t (gcc) + +:samp:`-gnatw.t` + *Activate warnings on suspicious contracts.* + + This switch activates warnings on suspicious contracts. This includes + warnings on suspicious postconditions (whether a pragma `Postcondition` or a + `Post` aspect in Ada 2012) and suspicious contract cases (pragma or aspect + `Contract_Cases`). A function postcondition or contract case is suspicious + when no postcondition or contract case for this function mentions the result + of the function. A procedure postcondition or contract case is suspicious + when it only refers to the pre-state of the procedure, because in that case + it should rather be expressed as a precondition. This switch also controls + warnings on suspicious cases of expressions typically found in contracts like + quantified expressions and uses of Update attribute. The default is that such + warnings are generated. + + +.. index:: -gnatw.T (gcc) + +:samp:`-gnatw.T` + *Suppress warnings on suspicious contracts.* + + This switch suppresses warnings on suspicious contracts. + + +.. index:: -gnatwu (gcc) + +:samp:`-gnatwu` + *Activate warnings on unused entities.* + + This switch activates warnings to be generated for entities that + are declared but not referenced, and for units that are |withed| + and not + referenced. In the case of packages, a warning is also generated if + no entities in the package are referenced. This means that if a with'ed + package is referenced but the only references are in `use` + clauses or `renames` + declarations, a warning is still generated. A warning is also generated + for a generic package that is |withed| but never instantiated. + In the case where a package or subprogram body is compiled, and there + is a |with| on the corresponding spec + that is only referenced in the body, + a warning is also generated, noting that the + |with| can be moved to the body. The default is that + such warnings are not generated. + This switch also activates warnings on unreferenced formals + (it includes the effect of *-gnatwf*). + + +.. index:: -gnatwU (gcc) + +:samp:`-gnatwU` + *Suppress warnings on unused entities.* + + This switch suppresses warnings for unused entities and packages. + It also turns off warnings on unreferenced formals (and thus includes + the effect of *-gnatwF*). + + +.. index:: -gnatw.u (gcc) + +:samp:`-gnatw.u` + *Activate warnings on unordered enumeration types.* + + This switch causes enumeration types to be considered as conceptually + unordered, unless an explicit pragma `Ordered` is given for the type. + The effect is to generate warnings in clients that use explicit comparisons + or subranges, since these constructs both treat objects of the type as + ordered. (A *client* is defined as a unit that is other than the unit in + which the type is declared, or its body or subunits.) Please refer to + the description of pragma `Ordered` in the + :title:`GNAT Reference Manual` for further details. + The default is that such warnings are not generated. + + +.. index:: -gnatw.U (gcc) + +:samp:`-gnatw.U` + *Deactivate warnings on unordered enumeration types.* + + This switch causes all enumeration types to be considered as ordered, so + that no warnings are given for comparisons or subranges for any type. + + +.. index:: -gnatwv (gcc) +.. index:: Unassigned variable warnings + +:samp:`-gnatwv` + *Activate warnings on unassigned variables.* + + This switch activates warnings for access to variables which + may not be properly initialized. The default is that + such warnings are generated. + + +.. index:: -gnatwV (gcc) + +:samp:`-gnatwV` + *Suppress warnings on unassigned variables.* + + This switch suppresses warnings for access to variables which + may not be properly initialized. + For variables of a composite type, the warning can also be suppressed in + Ada 2005 by using a default initialization with a box. For example, if + Table is an array of records whose components are only partially uninitialized, + then the following code: + + .. code-block:: ada + + Tab : Table := (others => <>); + + will suppress warnings on subsequent statements that access components + of variable Tab. + + +.. index:: -gnatw.v (gcc) +.. index:: bit order warnings + +:samp:`-gnatw.v` + *Activate info messages for non-default bit order.* + + This switch activates messages (labeled "info", they are not warnings, + just informational messages) about the effects of non-default bit-order + on records to which a component clause is applied. The effect of specifying + non-default bit ordering is a bit subtle (and changed with Ada 2005), so + these messages, which are given by default, are useful in understanding the + exact consequences of using this feature. + + +.. index:: -gnatw.V (gcc) + +:samp:`-gnatw.V` + *Suppress info messages for non-default bit order.* + + This switch suppresses information messages for the effects of specifying + non-default bit order on record components with component clauses. + + +.. index:: -gnatww (gcc) +.. index:: String indexing warnings + +:samp:`-gnatww` + *Activate warnings on wrong low bound assumption.* + + This switch activates warnings for indexing an unconstrained string parameter + with a literal or S'Length. This is a case where the code is assuming that the + low bound is one, which is in general not true (for example when a slice is + passed). The default is that such warnings are generated. + + +.. index:: -gnatwW (gcc) + +:samp:`-gnatwW` + *Suppress warnings on wrong low bound assumption.* + + This switch suppresses warnings for indexing an unconstrained string parameter + with a literal or S'Length. Note that this warning can also be suppressed + in a particular case by adding an assertion that the lower bound is 1, + as shown in the following example: + + .. code-block:: ada + + procedure K (S : String) is + pragma Assert (S'First = 1); + ... + + +.. index:: -gnatw.w (gcc) +.. index:: Warnings Off control + +:samp:`-gnatw.w` + *Activate warnings on Warnings Off pragmas* + + This switch activates warnings for use of `pragma Warnings (Off, entity)` + where either the pragma is entirely useless (because it suppresses no + warnings), or it could be replaced by `pragma Unreferenced` or + `pragma Unmodified`. + Also activates warnings for the case of + Warnings (Off, String), where either there is no matching + Warnings (On, String), or the Warnings (Off) did not suppress any warning. + The default is that these warnings are not given. + + +.. index:: -gnatw.W (gcc) + +:samp:`-gnatw.W` + *Suppress warnings on unnecessary Warnings Off pragmas* + + This switch suppresses warnings for use of `pragma Warnings (Off, ...)`. + + +.. index:: -gnatwx (gcc) +.. index:: Export/Import pragma warnings + +:samp:`-gnatwx` + *Activate warnings on Export/Import pragmas.* + + This switch activates warnings on Export/Import pragmas when + the compiler detects a possible conflict between the Ada and + foreign language calling sequences. For example, the use of + default parameters in a convention C procedure is dubious + because the C compiler cannot supply the proper default, so + a warning is issued. The default is that such warnings are + generated. + + +.. index:: -gnatwX (gcc) + +:samp:`-gnatwX` + *Suppress warnings on Export/Import pragmas.* + + This switch suppresses warnings on Export/Import pragmas. + The sense of this is that you are telling the compiler that + you know what you are doing in writing the pragma, and it + should not complain at you. + + +.. index:: -gnatwm (gcc) + +:samp:`-gnatw.x` + *Activate warnings for No_Exception_Propagation mode.* + + This switch activates warnings for exception usage when pragma Restrictions + (No_Exception_Propagation) is in effect. Warnings are given for implicit or + explicit exception raises which are not covered by a local handler, and for + exception handlers which do not cover a local raise. The default is that these + warnings are not given. + + +:samp:`-gnatw.X` + *Disable warnings for No_Exception_Propagation mode.* + + This switch disables warnings for exception usage when pragma Restrictions + (No_Exception_Propagation) is in effect. + + +.. index:: -gnatwy (gcc) +.. index:: Ada compatibility issues warnings + +:samp:`-gnatwy` + *Activate warnings for Ada compatibility issues.* + + For the most part, newer versions of Ada are upwards compatible + with older versions. For example, Ada 2005 programs will almost + always work when compiled as Ada 2012. + However there are some exceptions (for example the fact that + `some` is now a reserved word in Ada 2012). This + switch activates several warnings to help in identifying + and correcting such incompatibilities. The default is that + these warnings are generated. Note that at one point Ada 2005 + was called Ada 0Y, hence the choice of character. + + +.. index:: -gnatwY (gcc) +.. index:: Ada compatibility issues warnings + +:samp:`-gnatwY` + *Disable warnings for Ada compatibility issues.* + + This switch suppresses the warnings intended to help in identifying + incompatibilities between Ada language versions. + + +.. index:: -gnatw.y (gcc) +.. index:: Package spec needing body + +:samp:`-gnatw.y` + *Activate information messages for why package spec needs body* + + There are a number of cases in which a package spec needs a body. + For example, the use of pragma Elaborate_Body, or the declaration + of a procedure specification requiring a completion. This switch + causes information messages to be output showing why a package + specification requires a body. This can be useful in the case of + a large package specification which is unexpectedly requiring a + body. The default is that such information messages are not output. + + +.. index:: -gnatw.Y (gcc) +.. index:: No information messages for why package spec needs body + +:samp:`-gnatw.Y` + *Disable information messages for why package spec needs body* + + This switch suppresses the output of information messages showing why + a package specification needs a body. + + +.. index:: -gnatwz (gcc) +.. index:: Unchecked_Conversion warnings + +:samp:`-gnatwz` + *Activate warnings on unchecked conversions.* + + This switch activates warnings for unchecked conversions + where the types are known at compile time to have different + sizes. The default is that such warnings are generated. Warnings are also + generated for subprogram pointers with different conventions. + + +.. index:: -gnatwZ (gcc) + +:samp:`-gnatwZ` + *Suppress warnings on unchecked conversions.* + + This switch suppresses warnings for unchecked conversions + where the types are known at compile time to have different + sizes or conventions. + + +.. index:: -gnatw.z (gcc) +.. index:: Size/Alignment warnings + +:samp:`-gnatw.z` + *Activate warnings for size not a multiple of alignment.* + + This switch activates warnings for cases of record types with + specified `Size` and `Alignment` attributes where the + size is not a multiple of the alignment, resulting in an object + size that is greater than the specified size. The default + is that such warnings are generated. + + +.. index:: -gnatw.Z (gcc) +.. index:: Size/Alignment warnings + +:samp:`-gnatw.Z` + *Suppress warnings for size not a multiple of alignment.* + + This switch suppresses warnings for cases of record types with + specified `Size` and `Alignment` attributes where the + size is not a multiple of the alignment, resulting in an object + size that is greater than the specified size. + The warning can also be + suppressed by giving an explicit `Object_Size` value. + + +.. index:: -Wunused (gcc) + +:samp:`-Wunused` + The warnings controlled by the *-gnatw* switch are generated by + the front end of the compiler. The *GCC* back end can provide + additional warnings and they are controlled by the *-W* switch. + For example, *-Wunused* activates back end + warnings for entities that are declared but not referenced. + + +.. index:: -Wuninitialized (gcc) + +:samp:`-Wuninitialized` + Similarly, *-Wuninitialized* activates + the back end warning for uninitialized variables. This switch must be + used in conjunction with an optimization level greater than zero. + + +.. index:: -Wstack-usage (gcc) + +:samp:`-Wstack-usage={len}` + Warn if the stack usage of a subprogram might be larger than `len` bytes. + See :ref:`Static_Stack_Usage_Analysis` for details. + + +.. index:: -Wall (gcc) + +:samp:`-Wall` + This switch enables most warnings from the *GCC* back end. + The code generator detects a number of warning situations that are missed + by the *GNAT* front end, and this switch can be used to activate them. + The use of this switch also sets the default front end warning mode to + *-gnatwa*, that is, most front end warnings activated as well. + + +.. index:: -w (gcc) + +:samp:`-w` + Conversely, this switch suppresses warnings from the *GCC* back end. + The use of this switch also sets the default front end warning mode to + *-gnatws*, that is, front end warnings suppressed as well. + + +.. index:: -Werror (gcc) + +:samp:`-Werror` + This switch causes warnings from the *GCC* back end to be treated as + errors. The warning string still appears, but the warning messages are + counted as errors, and prevent the generation of an object file. + + +A string of warning parameters can be used in the same parameter. For example:: + + -gnatwaGe + + +will turn on all optional warnings except for unrecognized pragma warnings, +and also specify that warnings should be treated as errors. + +When no switch *-gnatw* is used, this is equivalent to: + + * :samp:`-gnatw.a` + + * :samp:`-gnatwB` + + * :samp:`-gnatw.b` + + * :samp:`-gnatwC` + + * :samp:`-gnatw.C` + + * :samp:`-gnatwD` + + * :samp:`-gnatwF` + + * :samp:`-gnatwg` + + * :samp:`-gnatwH` + + * :samp:`-gnatwi` + + * :samp:`-gnatw.I` + + * :samp:`-gnatwJ` + + * :samp:`-gnatwK` + + * :samp:`-gnatwL` + + * :samp:`-gnatw.L` + + * :samp:`-gnatwM` + + * :samp:`-gnatw.m` + + * :samp:`-gnatwn` + + * :samp:`-gnatwo` + + * :samp:`-gnatw.O` + + * :samp:`-gnatwP` + + * :samp:`-gnatw.P` + + * :samp:`-gnatwq` + + * :samp:`-gnatwR` + + * :samp:`-gnatw.R` + + * :samp:`-gnatw.S` + + * :samp:`-gnatwT` + + * :samp:`-gnatw.T` + + * :samp:`-gnatwU` + + * :samp:`-gnatwv` + + * :samp:`-gnatww` + + * :samp:`-gnatw.W` + + * :samp:`-gnatwx` + + * :samp:`-gnatw.X` + + * :samp:`-gnatwy` + + * :samp:`-gnatwz` + +.. _Debugging_and_Assertion_Control: + +Debugging and Assertion Control +------------------------------- + + + +.. index:: -gnata (gcc) + +:samp:`-gnata` + .. index:: Assert + .. index:: Debug + .. index:: Assertions + + The pragmas `Assert` and `Debug` normally have no effect and + are ignored. This switch, where :samp:`a` stands for assert, causes + `Assert` and `Debug` pragmas to be activated. + + The pragmas have the form:: + + pragma Assert (<Boolean-expression> [, <static-string-expression>]) + pragma Debug (<procedure call>) + + + The `Assert` pragma causes `Boolean-expression` to be tested. + If the result is `True`, the pragma has no effect (other than + possible side effects from evaluating the expression). If the result is + `False`, the exception `Assert_Failure` declared in the package + `System.Assertions` is + raised (passing `static-string-expression`, if present, as the + message associated with the exception). If no string expression is + given the default is a string giving the file name and line number + of the pragma. + + The `Debug` pragma causes `procedure` to be called. Note that + `pragma Debug` may appear within a declaration sequence, allowing + debugging procedures to be called between declarations. + + +.. _Validity_Checking: + +Validity Checking +----------------- + +.. index:: Validity Checking + +The Ada Reference Manual defines the concept of invalid values (see +RM 13.9.1). The primary source of invalid values is uninitialized +variables. A scalar variable that is left uninitialized may contain +an invalid value; the concept of invalid does not apply to access or +composite types. + +It is an error to read an invalid value, but the RM does not require +run-time checks to detect such errors, except for some minimal +checking to prevent erroneous execution (i.e. unpredictable +behavior). This corresponds to the *-gnatVd* switch below, +which is the default. For example, by default, if the expression of a +case statement is invalid, it will raise Constraint_Error rather than +causing a wild jump, and if an array index on the left-hand side of an +assignment is invalid, it will raise Constraint_Error rather than +overwriting an arbitrary memory location. + +The *-gnatVa* may be used to enable additional validity checks, +which are not required by the RM. These checks are often very +expensive (which is why the RM does not require them). These checks +are useful in tracking down uninitialized variables, but they are +not usually recommended for production builds, and in particular +we do not recommend using these extra validity checking options in +combination with optimization, since this can confuse the optimizer. +If performance is a consideration, leading to the need to optimize, +then the validity checking options should not be used. + +The other *-gnatV*\ ``x`` switches below allow finer-grained +control; you can enable whichever validity checks you desire. However, +for most debugging purposes, *-gnatVa* is sufficient, and the +default *-gnatVd* (i.e. standard Ada behavior) is usually +sufficient for non-debugging use. + +The *-gnatB* switch tells the compiler to assume that all +values are valid (that is, within their declared subtype range) +except in the context of a use of the Valid attribute. This means +the compiler can generate more efficient code, since the range +of values is better known at compile time. However, an uninitialized +variable can cause wild jumps and memory corruption in this mode. + +The *-gnatV*\ ``x`` switch allows control over the validity +checking mode as described below. +The ``x`` argument is a string of letters that +indicate validity checks that are performed or not performed in addition +to the default checks required by Ada as described above. + + +.. index:: -gnatVa (gcc) + +:samp:`-gnatVa` + *All validity checks.* + + All validity checks are turned on. + That is, *-gnatVa* is + equivalent to *gnatVcdfimorst*. + + +.. index:: -gnatVc (gcc) + +:samp:`-gnatVc` + *Validity checks for copies.* + + The right hand side of assignments, and the initializing values of + object declarations are validity checked. + + +.. index:: -gnatVd (gcc) + +:samp:`-gnatVd` + *Default (RM) validity checks.* + + Some validity checks are done by default following normal Ada semantics + (RM 13.9.1 (9-11)). + A check is done in case statements that the expression is within the range + of the subtype. If it is not, Constraint_Error is raised. + For assignments to array components, a check is done that the expression used + as index is within the range. If it is not, Constraint_Error is raised. + Both these validity checks may be turned off using switch *-gnatVD*. + They are turned on by default. If *-gnatVD* is specified, a subsequent + switch *-gnatVd* will leave the checks turned on. + Switch *-gnatVD* should be used only if you are sure that all such + expressions have valid values. If you use this switch and invalid values + are present, then the program is erroneous, and wild jumps or memory + overwriting may occur. + + +.. index:: -gnatVe (gcc) + +:samp:`-gnatVe` + *Validity checks for elementary components.* + + In the absence of this switch, assignments to record or array components are + not validity checked, even if validity checks for assignments generally + (*-gnatVc*) are turned on. In Ada, assignment of composite values do not + require valid data, but assignment of individual components does. So for + example, there is a difference between copying the elements of an array with a + slice assignment, compared to assigning element by element in a loop. This + switch allows you to turn off validity checking for components, even when they + are assigned component by component. + + +.. index:: -gnatVf (gcc) + +:samp:`-gnatVf` + *Validity checks for floating-point values.* + + In the absence of this switch, validity checking occurs only for discrete + values. If *-gnatVf* is specified, then validity checking also applies + for floating-point values, and NaNs and infinities are considered invalid, + as well as out of range values for constrained types. Note that this means + that standard IEEE infinity mode is not allowed. The exact contexts + in which floating-point values are checked depends on the setting of other + options. For example, *-gnatVif* or *-gnatVfi* + (the order does not matter) specifies that floating-point parameters of mode + `in` should be validity checked. + + +.. index:: -gnatVi (gcc) + +:samp:`-gnatVi` + *Validity checks for `in* mode parameters` + + Arguments for parameters of mode `in` are validity checked in function + and procedure calls at the point of call. + + +.. index:: -gnatVm (gcc) + +:samp:`-gnatVm` + *Validity checks for `in out* mode parameters.` + + Arguments for parameters of mode `in out` are validity checked in + procedure calls at the point of call. The `'m'` here stands for + modify, since this concerns parameters that can be modified by the call. + Note that there is no specific option to test `out` parameters, + but any reference within the subprogram will be tested in the usual + manner, and if an invalid value is copied back, any reference to it + will be subject to validity checking. + + +.. index:: -gnatVn (gcc) + +:samp:`-gnatVn` + *No validity checks.* + + This switch turns off all validity checking, including the default checking + for case statements and left hand side subscripts. Note that the use of + the switch *-gnatp* suppresses all run-time checks, including + validity checks, and thus implies *-gnatVn*. When this switch + is used, it cancels any other *-gnatV* previously issued. + + +:samp:`-gnatVo` + *Validity checks for operator and attribute operands.* + .. index:: -gnatVo (gcc) + + Arguments for predefined operators and attributes are validity checked. + This includes all operators in package `Standard`, + the shift operators defined as intrinsic in package `Interfaces` + and operands for attributes such as `Pos`. Checks are also made + on individual component values for composite comparisons, and on the + expressions in type conversions and qualified expressions. Checks are + also made on explicit ranges using :samp:`..` (e.g., slices, loops etc). + + +.. index:: -gnatVp (gcc) + +:samp:`-gnatVp` + *Validity checks for parameters.* + + This controls the treatment of parameters within a subprogram (as opposed + to *-gnatVi* and *-gnatVm* which control validity testing + of parameters on a call. If either of these call options is used, then + normally an assumption is made within a subprogram that the input arguments + have been validity checking at the point of call, and do not need checking + again within a subprogram). If *-gnatVp* is set, then this assumption + is not made, and parameters are not assumed to be valid, so their validity + will be checked (or rechecked) within the subprogram. + + +.. index:: -gnatVr (gcc) + +:samp:`-gnatVr` + *Validity checks for function returns.* + + The expression in `return` statements in functions is validity + checked. + + +.. index:: -gnatVs (gcc) + +:samp:`-gnatVs` + *Validity checks for subscripts.* + + All subscripts expressions are checked for validity, whether they appear + on the right side or left side (in default mode only left side subscripts + are validity checked). + + +.. index:: -gnatVt (gcc) + +:samp:`-gnatVt` + *Validity checks for tests.* + + Expressions used as conditions in `if`, `while` or `exit` + statements are checked, as well as guard expressions in entry calls. + + +The *-gnatV* switch may be followed by a string of letters +to turn on a series of validity checking options. +For example, :samp:`-gnatVcr` +specifies that in addition to the default validity checking, copies and +function return expressions are to be validity checked. +In order to make it easier to specify the desired combination of effects, +the upper case letters `CDFIMORST` may +be used to turn off the corresponding lower case option. +Thus :samp:`-gnatVaM` turns on all validity checking options except for +checking of `**in out**` procedure arguments. + +The specification of additional validity checking generates extra code (and +in the case of *-gnatVa* the code expansion can be substantial). +However, these additional checks can be very useful in detecting +uninitialized variables, incorrect use of unchecked conversion, and other +errors leading to invalid values. The use of pragma `Initialize_Scalars` +is useful in conjunction with the extra validity checking, since this +ensures that wherever possible uninitialized variables have invalid values. + +See also the pragma `Validity_Checks` which allows modification of +the validity checking mode at the program source level, and also allows for +temporary disabling of validity checks. + +.. _Style_Checking: + +Style Checking +-------------- + +.. index:: Style checking + +.. index:: -gnaty (gcc) + +The *-gnatyx* switch causes the compiler to +enforce specified style rules. A limited set of style rules has been used +in writing the GNAT sources themselves. This switch allows user programs +to activate all or some of these checks. If the source program fails a +specified style check, an appropriate message is given, preceded by +the character sequence '(style)'. This message does not prevent +successful compilation (unless the *-gnatwe* switch is used). + +Note that this is by no means intended to be a general facility for +checking arbitrary coding standards. It is simply an embedding of the +style rules we have chosen for the GNAT sources. If you are starting +a project which does not have established style standards, you may +find it useful to adopt the entire set of GNAT coding standards, or +some subset of them. + +.. only:: PRO or GPL + + If you already have an established set of coding + standards, then the selected style checking options may + indeed correspond to choices you have made, but for general checking + of an existing set of coding rules, you should look to the gnatcheck + tool, which is designed for that purpose. + +The string `x` is a sequence of letters or digits +indicating the particular style +checks to be performed. The following checks are defined: + + +.. index:: -gnaty[0-9] (gcc) + +:samp:`-gnaty0` + *Specify indentation level.* + + If a digit from 1-9 appears + in the string after *-gnaty* + then proper indentation is checked, with the digit indicating the + indentation level required. A value of zero turns off this style check. + The general style of required indentation is as specified by + the examples in the Ada Reference Manual. Full line comments must be + aligned with the `--` starting on a column that is a multiple of + the alignment level, or they may be aligned the same way as the following + non-blank line (this is useful when full line comments appear in the middle + of a statement, or they may be aligned with the source line on the previous + non-blank line. + +.. index:: -gnatya (gcc) + +:samp:`-gnatya` + *Check attribute casing.* + + Attribute names, including the case of keywords such as `digits` + used as attributes names, must be written in mixed case, that is, the + initial letter and any letter following an underscore must be uppercase. + All other letters must be lowercase. + + +.. index:: -gnatyA (gcc) + +:samp:`-gnatyA` + *Use of array index numbers in array attributes.* + + When using the array attributes First, Last, Range, + or Length, the index number must be omitted for one-dimensional arrays + and is required for multi-dimensional arrays. + + +.. index:: -gnatyb (gcc) + +:samp:`-gnatyb` + *Blanks not allowed at statement end.* + + Trailing blanks are not allowed at the end of statements. The purpose of this + rule, together with h (no horizontal tabs), is to enforce a canonical format + for the use of blanks to separate source tokens. + + +.. index:: -gnatyB (gcc) + +:samp:`-gnatyB` + *Check Boolean operators.* + + The use of AND/OR operators is not permitted except in the cases of modular + operands, array operands, and simple stand-alone boolean variables or + boolean constants. In all other cases `and then`/`or else` are + required. + + +.. index:: -gnatyc (gcc) + +:samp:`-gnatyc` + *Check comments, double space.* + + Comments must meet the following set of rules: + + * The '`--`' that starts the column must either start in column one, + or else at least one blank must precede this sequence. + + * Comments that follow other tokens on a line must have at least one blank + following the '`--`' at the start of the comment. + + * Full line comments must have at least two blanks following the + '`--`' that starts the comment, with the following exceptions. + + * A line consisting only of the '`--`' characters, possibly preceded + by blanks is permitted. + + * A comment starting with '`--x`' where `x` is a special character + is permitted. + This allows proper processing of the output generated by specialized tools + including *gnatprep* (where '`--!`' is used) and the SPARK + annotation + language (where '`--#`' is used). For the purposes of this rule, a + special character is defined as being in one of the ASCII ranges + `16#21#...16#2F#` or `16#3A#...16#3F#`. + Note that this usage is not permitted + in GNAT implementation units (i.e., when *-gnatg* is used). + + * A line consisting entirely of minus signs, possibly preceded by blanks, is + permitted. This allows the construction of box comments where lines of minus + signs are used to form the top and bottom of the box. + + * A comment that starts and ends with '`--`' is permitted as long as at + least one blank follows the initial '`--`'. Together with the preceding + rule, this allows the construction of box comments, as shown in the following + example: + + .. code-block:: ada + + --------------------------- + -- This is a box comment -- + -- with two text lines. -- + --------------------------- + + +.. index:: -gnatyC (gcc) + +:samp:`-gnatyC` + *Check comments, single space.* + + This is identical to `c` except that only one space + is required following the `--` of a comment instead of two. + + +.. index:: -gnatyd (gcc) + +:samp:`-gnatyd` + *Check no DOS line terminators present.* + + All lines must be terminated by a single ASCII.LF + character (in particular the DOS line terminator sequence CR/LF is not + allowed). + + +.. index:: -gnatye (gcc) + +:samp:`-gnatye` + *Check end/exit labels.* + + Optional labels on `end` statements ending subprograms and on + `exit` statements exiting named loops, are required to be present. + + +.. index:: -gnatyf (gcc) + +:samp:`-gnatyf` + *No form feeds or vertical tabs.* + + Neither form feeds nor vertical tab characters are permitted + in the source text. + + +.. index:: -gnatyg (gcc) + +:samp:`-gnatyg` + *GNAT style mode.* + + The set of style check switches is set to match that used by the GNAT sources. + This may be useful when developing code that is eventually intended to be + incorporated into GNAT. Currently this is equivalent to *-gnatwydISux*) + but additional style switches may be added to this set in the future without + advance notice. + + +.. index:: -gnatyh (gcc) + +:samp:`-gnatyh` + *No horizontal tabs.* + + Horizontal tab characters are not permitted in the source text. + Together with the b (no blanks at end of line) check, this + enforces a canonical form for the use of blanks to separate + source tokens. + + +.. index:: -gnatyi (gcc) + +:samp:`-gnatyi` + *Check if-then layout.* + + The keyword `then` must appear either on the same + line as corresponding `if`, or on a line on its own, lined + up under the `if`. + + +.. index:: -gnatyI (gcc) + +:samp:`-gnatyI` + *check mode IN keywords.* + + Mode `in` (the default mode) is not + allowed to be given explicitly. `in out` is fine, + but not `in` on its own. + + +.. index:: -gnatyk (gcc) + +:samp:`-gnatyk` + *Check keyword casing.* + + All keywords must be in lower case (with the exception of keywords + such as `digits` used as attribute names to which this check + does not apply). + + +.. index:: -gnatyl (gcc) + +:samp:`-gnatyl` + *Check layout.* + + Layout of statement and declaration constructs must follow the + recommendations in the Ada Reference Manual, as indicated by the + form of the syntax rules. For example an `else` keyword must + be lined up with the corresponding `if` keyword. + + There are two respects in which the style rule enforced by this check + option are more liberal than those in the Ada Reference Manual. First + in the case of record declarations, it is permissible to put the + `record` keyword on the same line as the `type` keyword, and + then the `end` in `end record` must line up under `type`. + This is also permitted when the type declaration is split on two lines. + For example, any of the following three layouts is acceptable: + + .. code-block:: ada + + type q is record + a : integer; + b : integer; + end record; + + type q is + record + a : integer; + b : integer; + end record; + + type q is + record + a : integer; + b : integer; + end record; + + Second, in the case of a block statement, a permitted alternative + is to put the block label on the same line as the `declare` or + `begin` keyword, and then line the `end` keyword up under + the block label. For example both the following are permitted: + + .. code-block:: ada + + Block : declare + A : Integer := 3; + begin + Proc (A, A); + end Block; + + Block : + declare + A : Integer := 3; + begin + Proc (A, A); + end Block; + + The same alternative format is allowed for loops. For example, both of + the following are permitted: + + .. code-block:: ada + + Clear : while J < 10 loop + A (J) := 0; + end loop Clear; + + Clear : + while J < 10 loop + A (J) := 0; + end loop Clear; + + +.. index:: -gnatyLnnn (gcc) + +:samp:`-gnatyL` + *Set maximum nesting level.* + + The maximum level of nesting of constructs (including subprograms, loops, + blocks, packages, and conditionals) may not exceed the given value + *nnn*. A value of zero disconnects this style check. + + +.. index:: -gnatym (gcc) + +:samp:`-gnatym` + *Check maximum line length.* + + The length of source lines must not exceed 79 characters, including + any trailing blanks. The value of 79 allows convenient display on an + 80 character wide device or window, allowing for possible special + treatment of 80 character lines. Note that this count is of + characters in the source text. This means that a tab character counts + as one character in this count and a wide character sequence counts as + a single character (however many bytes are needed in the encoding). + + +.. index:: -gnatyMnnn (gcc) + +:samp:`-gnatyM` + *Set maximum line length.* + + The length of lines must not exceed the + given value *nnn*. The maximum value that can be specified is 32767. + If neither style option for setting the line length is used, then the + default is 255. This also controls the maximum length of lexical elements, + where the only restriction is that they must fit on a single line. + + +.. index:: -gnatyn (gcc) + +:samp:`-gnatyn` + *Check casing of entities in Standard.* + + Any identifier from Standard must be cased + to match the presentation in the Ada Reference Manual (for example, + `Integer` and `ASCII.NUL`). + + +.. index:: -gnatyN (gcc) + +:samp:`-gnatyN` + *Turn off all style checks.* + + All style check options are turned off. + + +.. index:: -gnatyo (gcc) + +:samp:`-gnatyo` + *Check order of subprogram bodies.* + + All subprogram bodies in a given scope + (e.g., a package body) must be in alphabetical order. The ordering + rule uses normal Ada rules for comparing strings, ignoring casing + of letters, except that if there is a trailing numeric suffix, then + the value of this suffix is used in the ordering (e.g., Junk2 comes + before Junk10). + + +.. index:: -gnatyO (gcc) + +:samp:`-gnatyO` + *Check that overriding subprograms are explicitly marked as such.* + + The declaration of a primitive operation of a type extension that overrides + an inherited operation must carry an overriding indicator. + + +.. index:: -gnatyp (gcc) + +:samp:`-gnatyp` + *Check pragma casing.* + + Pragma names must be written in mixed case, that is, the + initial letter and any letter following an underscore must be uppercase. + All other letters must be lowercase. An exception is that SPARK_Mode is + allowed as an alternative for Spark_Mode. + + +.. index:: -gnatyr (gcc) + +:samp:`-gnatyr` + *Check references.* + + All identifier references must be cased in the same way as the + corresponding declaration. No specific casing style is imposed on + identifiers. The only requirement is for consistency of references + with declarations. + + +.. index:: -gnatys (gcc) + +:samp:`-gnatys` + *Check separate specs.* + + Separate declarations ('specs') are required for subprograms (a + body is not allowed to serve as its own declaration). The only + exception is that parameterless library level procedures are + not required to have a separate declaration. This exception covers + the most frequent form of main program procedures. + + +.. index:: -gnatyS (gcc) + +:samp:`-gnatyS` + *Check no statements after then/else.* + + No statements are allowed + on the same line as a `then` or `else` keyword following the + keyword in an `if` statement. `or else` and `and then` are not + affected, and a special exception allows a pragma to appear after `else`. + + +.. index:: -gnatyt (gcc) + +:samp:`-gnatyt` + *Check token spacing.* + + The following token spacing rules are enforced: + + * The keywords `abs` and `not` must be followed by a space. + + * The token `=>` must be surrounded by spaces. + + * The token `<>` must be preceded by a space or a left parenthesis. + + * Binary operators other than `**` must be surrounded by spaces. + There is no restriction on the layout of the `**` binary operator. + + * Colon must be surrounded by spaces. + + * Colon-equal (assignment, initialization) must be surrounded by spaces. + + * Comma must be the first non-blank character on the line, or be + immediately preceded by a non-blank character, and must be followed + by a space. + + * If the token preceding a left parenthesis ends with a letter or digit, then + a space must separate the two tokens. + + * If the token following a right parenthesis starts with a letter or digit, then + a space must separate the two tokens. + + * A right parenthesis must either be the first non-blank character on + a line, or it must be preceded by a non-blank character. + + * A semicolon must not be preceded by a space, and must not be followed by + a non-blank character. + + * A unary plus or minus may not be followed by a space. + + * A vertical bar must be surrounded by spaces. + + Exactly one blank (and no other white space) must appear between + a `not` token and a following `in` token. + + +.. index:: -gnatyu (gcc) + +:samp:`-gnatyu` + *Check unnecessary blank lines.* + + Unnecessary blank lines are not allowed. A blank line is considered + unnecessary if it appears at the end of the file, or if more than + one blank line occurs in sequence. + + +.. index:: -gnatyx (gcc) + +:samp:`-gnatyx` + *Check extra parentheses.* + + Unnecessary extra level of parentheses (C-style) are not allowed + around conditions in `if` statements, `while` statements and + `exit` statements. + + +.. index:: -gnatyy (gcc) + +:samp:`-gnatyy` + *Set all standard style check options* + + This is equivalent to `gnaty3aAbcefhiklmnprst`, that is all checking + options enabled with the exception of *-gnatyB*, *-gnatyd*, + *-gnatyI*, *-gnatyLnnn*, *-gnatyo*, *-gnatyO*, + *-gnatyS*, *-gnatyu*, and *-gnatyx*. + + +.. index:: -gnaty- (gcc) + +:samp:`-gnaty-` + *Remove style check options* + + This causes any subsequent options in the string to act as canceling the + corresponding style check option. To cancel maximum nesting level control, + use *L* parameter witout any integer value after that, because any + digit following *-* in the parameter string of the *-gnaty* + option will be threated as canceling indentation check. The same is true + for *M* parameter. *y* and *N* parameters are not + allowed after *-*. + + +.. index:: -gnaty+ (gcc) + +:samp:`-gnaty+` + *Enable style check options* + + This causes any subsequent options in the string to enable the corresponding + style check option. That is, it cancels the effect of a previous -, + if any. + + +.. end of switch description (leave this comment to ease automatic parsing for +.. GPS + +In the above rules, appearing in column one is always permitted, that is, +counts as meeting either a requirement for a required preceding space, +or as meeting a requirement for no preceding space. + +Appearing at the end of a line is also always permitted, that is, counts +as meeting either a requirement for a following space, or as meeting +a requirement for no following space. + +If any of these style rules is violated, a message is generated giving +details on the violation. The initial characters of such messages are +always '`(style)`'. Note that these messages are treated as warning +messages, so they normally do not prevent the generation of an object +file. The *-gnatwe* switch can be used to treat warning messages, +including style messages, as fatal errors. + +The switch :samp:`-gnaty` on its own (that is not +followed by any letters or digits) is equivalent +to the use of *-gnatyy* as described above, that is all +built-in standard style check options are enabled. + +The switch :samp:`-gnatyN` clears any previously set style checks. + +.. _Run-Time_Checks: + +Run-Time Checks +--------------- + +.. index:: Division by zero + +.. index:: Access before elaboration + +.. index:: Checks, division by zero + +.. index:: Checks, access before elaboration + +.. index:: Checks, stack overflow checking + +By default, the following checks are suppressed: integer overflow +checks, stack overflow checks, and checks for access before +elaboration on subprogram calls. All other checks, including range +checks and array bounds checks, are turned on by default. The +following *gcc* switches refine this default behavior. + +.. index:: -gnatp (gcc) + +:samp:`-gnatp` + .. index:: Suppressing checks + + .. index:: Checks, suppressing + + This switch causes the unit to be compiled + as though `pragma Suppress (All_checks)` + had been present in the source. Validity checks are also eliminated (in + other words *-gnatp* also implies *-gnatVn*. + Use this switch to improve the performance + of the code at the expense of safety in the presence of invalid data or + program bugs. + + Note that when checks are suppressed, the compiler is allowed, but not + required, to omit the checking code. If the run-time cost of the + checking code is zero or near-zero, the compiler will generate it even + if checks are suppressed. In particular, if the compiler can prove + that a certain check will necessarily fail, it will generate code to + do an unconditional 'raise', even if checks are suppressed. The + compiler warns in this case. Another case in which checks may not be + eliminated is when they are embedded in certain run time routines such + as math library routines. + + Of course, run-time checks are omitted whenever the compiler can prove + that they will not fail, whether or not checks are suppressed. + + Note that if you suppress a check that would have failed, program + execution is erroneous, which means the behavior is totally + unpredictable. The program might crash, or print wrong answers, or + do anything else. It might even do exactly what you wanted it to do + (and then it might start failing mysteriously next week or next + year). The compiler will generate code based on the assumption that + the condition being checked is true, which can result in erroneous + execution if that assumption is wrong. + + The checks subject to suppression include all the checks defined by + the Ada standard, the additional implementation defined checks + `Alignment_Check`, + `Duplicated_Tag_Check`, `Predicate_Check`, and + `Validity_Check`, as well as any checks introduced using + `pragma Check_Name`. Note that `Atomic_Synchronization` + is not automatically suppressed by use of this option. + + If the code depends on certain checks being active, you can use + pragma `Unsuppress` either as a configuration pragma or as + a local pragma to make sure that a specified check is performed + even if *gnatp* is specified. + + The *-gnatp* switch has no effect if a subsequent + *-gnat-p* switch appears. + + +.. index:: -gnat-p (gcc) +.. index:: Suppressing checks +.. index:: Checks, suppressing +.. index:: Suppress + +:samp:`-gnat-p` + This switch cancels the effect of a previous *gnatp* switch. + + +.. index:: -gnato?? (gcc) +.. index:: Overflow checks +.. index:: Overflow mode +.. index:: Check, overflow + +:samp:`-gnato??` + This switch controls the mode used for computing intermediate + arithmetic integer operations, and also enables overflow checking. + For a full description of overflow mode and checking control, see + the 'Overflow Check Handling in GNAT' appendix in this + User's Guide. + + Overflow checks are always enabled by this switch. The argument + controls the mode, using the codes + + + *1 = STRICT* + In STRICT mode, intermediate operations are always done using the + base type, and overflow checking ensures that the result is within + the base type range. + + + *2 = MINIMIZED* + In MINIMIZED mode, overflows in intermediate operations are avoided + where possible by using a larger integer type for the computation + (typically `Long_Long_Integer`). Overflow checking ensures that + the result fits in this larger integer type. + + + *3 = ELIMINATED* + In ELIMINATED mode, overflows in intermediate operations are avoided + by using multi-precision arithmetic. In this case, overflow checking + has no effect on intermediate operations (since overflow is impossible). + + If two digits are present after *-gnato* then the first digit + sets the mode for expressions outside assertions, and the second digit + sets the mode for expressions within assertions. Here assertions is used + in the technical sense (which includes for example precondition and + postcondition expressions). + + If one digit is present, the corresponding mode is applicable to both + expressions within and outside assertion expressions. + + If no digits are present, the default is to enable overflow checks + and set STRICT mode for both kinds of expressions. This is compatible + with the use of *-gnato* in previous versions of GNAT. + + .. index:: Machine_Overflows + + Note that the *-gnato??* switch does not affect the code generated + for any floating-point operations; it applies only to integer semantics. + For floating-point, GNAT has the `Machine_Overflows` + attribute set to `False` and the normal mode of operation is to + generate IEEE NaN and infinite values on overflow or invalid operations + (such as dividing 0.0 by 0.0). + + The reason that we distinguish overflow checking from other kinds of + range constraint checking is that a failure of an overflow check, unlike + for example the failure of a range check, can result in an incorrect + value, but cannot cause random memory destruction (like an out of range + subscript), or a wild jump (from an out of range case value). Overflow + checking is also quite expensive in time and space, since in general it + requires the use of double length arithmetic. + + Note again that the default is *-gnato00*, + so overflow checking is not performed in default mode. This means that out of + the box, with the default settings, GNAT does not do all the checks + expected from the language description in the Ada Reference Manual. + If you want all constraint checks to be performed, as described in this Manual, + then you must explicitly use the *-gnato??* + switch either on the *gnatmake* or *gcc* command. + + +.. index:: -gnatE (gcc) +.. index:: Elaboration checks +.. index:: Check, elaboration + +:samp:`-gnatE` + Enables dynamic checks for access-before-elaboration + on subprogram calls and generic instantiations. + Note that *-gnatE* is not necessary for safety, because in the + default mode, GNAT ensures statically that the checks would not fail. + For full details of the effect and use of this switch, + :ref:`Compiling_with_gcc`. + + +.. index:: -fstack-check (gcc) +.. index:: Stack Overflow Checking +.. index:: Checks, stack overflow checking + +:samp:`-fstack-check` + Activates stack overflow checking. For full details of the effect and use of + this switch see :ref:`Stack_Overflow_Checking`. + +.. index:: Unsuppress + +The setting of these switches only controls the default setting of the +checks. You may modify them using either `Suppress` (to remove +checks) or `Unsuppress` (to add back suppressed checks) pragmas in +the program source. + + +.. _Using_gcc_for_Syntax_Checking: + +Using *gcc* for Syntax Checking +------------------------------- + +.. index:: -gnats (gcc) + +:samp:`-gnats` + The `s` stands for 'syntax'. + + Run GNAT in syntax checking only mode. For + example, the command + + :: + + $ gcc -c -gnats x.adb + + compiles file :file:`x.adb` in syntax-check-only mode. You can check a + series of files in a single command + , and can use wild cards to specify such a group of files. + Note that you must specify the *-c* (compile + only) flag in addition to the *-gnats* flag. + + You may use other switches in conjunction with *-gnats*. In + particular, *-gnatl* and *-gnatv* are useful to control the + format of any generated error messages. + + When the source file is empty or contains only empty lines and/or comments, + the output is a warning: + + + :: + + $ gcc -c -gnats -x ada toto.txt + toto.txt:1:01: warning: empty file, contains no compilation units + $ + + + Otherwise, the output is simply the error messages, if any. No object file or + ALI file is generated by a syntax-only compilation. Also, no units other + than the one specified are accessed. For example, if a unit `X` + |withs| a unit `Y`, compiling unit `X` in syntax + check only mode does not access the source file containing unit + `Y`. + + .. index:: Multiple units, syntax checking + + Normally, GNAT allows only a single unit in a source file. However, this + restriction does not apply in syntax-check-only mode, and it is possible + to check a file containing multiple compilation units concatenated + together. This is primarily used by the `gnatchop` utility + (:ref:`Renaming_Files_with_gnatchop`). + +.. _Using_gcc_for_Semantic_Checking: + +Using *gcc* for Semantic Checking +--------------------------------- + + + +.. index:: -gnatc (gcc) + +:samp:`-gnatc` + The `c` stands for 'check'. + Causes the compiler to operate in semantic check mode, + with full checking for all illegalities specified in the + Ada Reference Manual, but without generation of any object code + (no object file is generated). + + Because dependent files must be accessed, you must follow the GNAT + semantic restrictions on file structuring to operate in this mode: + + * The needed source files must be accessible + (see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). + + * Each file must contain only one compilation unit. + + * The file name and unit name must match (:ref:`File_Naming_Rules`). + + The output consists of error messages as appropriate. No object file is + generated. An :file:`ALI` file is generated for use in the context of + cross-reference tools, but this file is marked as not being suitable + for binding (since no object file is generated). + The checking corresponds exactly to the notion of + legality in the Ada Reference Manual. + + Any unit can be compiled in semantics-checking-only mode, including + units that would not normally be compiled (subunits, + and specifications where a separate body is present). + +.. _Compiling_Different_Versions_of_Ada: + +Compiling Different Versions of Ada +----------------------------------- + +The switches described in this section allow you to explicitly specify +the version of the Ada language that your programs are written in. +The default mode is Ada 2012, +but you can also specify Ada 95, Ada 2005 mode, or +indicate Ada 83 compatibility mode. + + +.. index:: Compatibility with Ada 83 +.. index:: -gnat83 (gcc) +.. index:: ACVC, Ada 83 tests +.. index:: Ada 83 mode + +:samp:`-gnat83 (Ada 83 Compatibility Mode)` + Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch + specifies that the program is to be compiled in Ada 83 mode. With + *-gnat83*, GNAT rejects most post-Ada 83 extensions and applies Ada 83 + semantics where this can be done easily. + It is not possible to guarantee this switch does a perfect + job; some subtle tests, such as are + found in earlier ACVC tests (and that have been removed from the ACATS suite + for Ada 95), might not compile correctly. + Nevertheless, this switch may be useful in some circumstances, for example + where, due to contractual reasons, existing code needs to be maintained + using only Ada 83 features. + + With few exceptions (most notably the need to use `<>` on + .. index:: Generic formal parameters + + unconstrained generic formal parameters, the use of the new Ada 95 / Ada 2005 + reserved words, and the use of packages + with optional bodies), it is not necessary to specify the + *-gnat83* switch when compiling Ada 83 programs, because, with rare + exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus + a correct Ada 83 program is usually also a correct program + in these later versions of the language standard. For further information + please refer to the `Compatibility_and_Porting_Guide` chapter in the + :title:`GNAT Reference Manual`. + + +.. index:: -gnat95 (gcc) +.. index:: Ada 95 mode + +:samp:`-gnat95` (Ada 95 mode) + This switch directs the compiler to implement the Ada 95 version of the + language. + Since Ada 95 is almost completely upwards + compatible with Ada 83, Ada 83 programs may generally be compiled using + this switch (see the description of the *-gnat83* switch for further + information about Ada 83 mode). + If an Ada 2005 program is compiled in Ada 95 mode, + uses of the new Ada 2005 features will cause error + messages or warnings. + + This switch also can be used to cancel the effect of a previous + *-gnat83*, *-gnat05/2005*, or *-gnat12/2012* + switch earlier in the command line. + + +.. index:: -gnat05 (gcc) +.. index:: -gnat2005 (gcc) +.. index:: Ada 2005 mode + +:samp:`-gnat05` or :samp:`-gnat2005` (Ada 2005 mode) + This switch directs the compiler to implement the Ada 2005 version of the + language, as documented in the official Ada standards document. + Since Ada 2005 is almost completely upwards + compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs + may generally be compiled using this switch (see the description of the + *-gnat83* and *-gnat95* switches for further + information). + + +.. index:: -gnat12 (gcc) +.. index:: -gnat2012 (gcc) +.. index:: Ada 2012 mode + +:samp:`-gnat12` or :samp:`-gnat2012` (Ada 2012 mode) + This switch directs the compiler to implement the Ada 2012 version of the + language (also the default). + Since Ada 2012 is almost completely upwards + compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), + Ada 83 and Ada 95 programs + may generally be compiled using this switch (see the description of the + *-gnat83*, *-gnat95*, and *-gnat05/2005* switches + for further information). + + +.. index:: -gnatX (gcc) +.. index:: Ada language extensions +.. index:: GNAT extensions + +:samp:`-gnatX` (Enable GNAT Extensions) + This switch directs the compiler to implement the latest version of the + language (currently Ada 2012) and also to enable certain GNAT implementation + extensions that are not part of any Ada standard. For a full list of these + extensions, see the GNAT reference manual. + + +.. _Character_Set_Control: + +Character Set Control +--------------------- + +.. index:: -gnati (gcc) + +:samp:`-gnati{c}` + Normally GNAT recognizes the Latin-1 character set in source program + identifiers, as described in the Ada Reference Manual. + This switch causes + GNAT to recognize alternate character sets in identifiers. `c` is a + single character indicating the character set, as follows: + + ========== ====================================================== + *1* ISO 8859-1 (Latin-1) identifiers + *2* ISO 8859-2 (Latin-2) letters allowed in identifiers + *3* ISO 8859-3 (Latin-3) letters allowed in identifiers + *4* ISO 8859-4 (Latin-4) letters allowed in identifiers + *5* ISO 8859-5 (Cyrillic) letters allowed in identifiers + *9* ISO 8859-15 (Latin-9) letters allowed in identifiers + *p* IBM PC letters (code page 437) allowed in identifiers + *8* IBM PC letters (code page 850) allowed in identifiers + *f* Full upper-half codes allowed in identifiers + *n* No upper-half codes allowed in identifiers + *w* Wide-character codes (that is, codes greater than 255) + allowed in identifiers + ========== ====================================================== + + See :ref:`Foreign_Language_Representation` for full details on the + implementation of these character sets. + + +.. index:: -gnatW (gcc) + +:samp:`-gnatW{e}` + Specify the method of encoding for wide characters. + `e` is one of the following: + + ========== ====================================================== + *h* Hex encoding (brackets coding also recognized) + *u* Upper half encoding (brackets encoding also recognized) + *s* Shift/JIS encoding (brackets encoding also recognized) + *e* EUC encoding (brackets encoding also recognized) + *8* UTF-8 encoding (brackets encoding also recognized) + *b* Brackets encoding only (default value) + ========== ====================================================== + + For full details on these encoding + methods see :ref:`Wide_Character_Encodings`. + Note that brackets coding is always accepted, even if one of the other + options is specified, so for example *-gnatW8* specifies that both + brackets and UTF-8 encodings will be recognized. The units that are + with'ed directly or indirectly will be scanned using the specified + representation scheme, and so if one of the non-brackets scheme is + used, it must be used consistently throughout the program. However, + since brackets encoding is always recognized, it may be conveniently + used in standard libraries, allowing these libraries to be used with + any of the available coding schemes. + + Note that brackets encoding only applies to program text. Within comments, + brackets are considered to be normal graphic characters, and bracket sequences + are never recognized as wide characters. + + If no *-gnatW?* parameter is present, then the default + representation is normally Brackets encoding only. However, if the + first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard + byte order mark or BOM for UTF-8), then these three characters are + skipped and the default representation for the file is set to UTF-8. + + Note that the wide character representation that is specified (explicitly + or by default) for the main program also acts as the default encoding used + for Wide_Text_IO files if not specifically overridden by a WCEM form + parameter. + + +When no *-gnatW?* is specified, then characters (other than wide +characters represented using brackets notation) are treated as 8-bit +Latin-1 codes. The codes recognized are the Latin-1 graphic characters, +and ASCII format effectors (CR, LF, HT, VT). Other lower half control +characters in the range 16#00#..16#1F# are not accepted in program text +or in comments. Upper half control characters (16#80#..16#9F#) are rejected +in program text, but allowed and ignored in comments. Note in particular +that the Next Line (NEL) character whose encoding is 16#85# is not recognized +as an end of line in this default mode. If your source program contains +instances of the NEL character used as a line terminator, +you must use UTF-8 encoding for the whole +source program. In default mode, all lines must be ended by a standard +end of line sequence (CR, CR/LF, or LF). + +Note that the convention of simply accepting all upper half characters in +comments means that programs that use standard ASCII for program text, but +UTF-8 encoding for comments are accepted in default mode, providing that the +comments are ended by an appropriate (CR, or CR/LF, or LF) line terminator. +This is a common mode for many programs with foreign language comments. + +.. _File_Naming_Control: + +File Naming Control +------------------- + +.. index:: -gnatk (gcc) + +:samp:`-gnatk{n}` + Activates file name 'krunching'. `n`, a decimal integer in the range + 1-999, indicates the maximum allowable length of a file name (not + including the :file:`.ads` or :file:`.adb` extension). The default is not + to enable file name krunching. + + For the source file naming rules, :ref:`File_Naming_Rules`. + +.. _Subprogram_Inlining_Control: + +Subprogram Inlining Control +--------------------------- + +.. index:: -gnatn (gcc) + +:samp:`-gnatn[12]` + The `n` here is intended to suggest the first syllable of the + word 'inline'. + GNAT recognizes and processes `Inline` pragmas. However, for the + inlining to actually occur, optimization must be enabled and, in order + to enable inlining of subprograms specified by pragma `Inline`, + you must also specify this switch. + In the absence of this switch, GNAT does not attempt + inlining and does not need to access the bodies of + subprograms for which `pragma Inline` is specified if they are not + in the current unit. + + You can optionally specify the inlining level: 1 for moderate inlining across + modules, which is a good compromise between compilation times and performances + at run time, or 2 for full inlining across modules, which may bring about + longer compilation times. If no inlining level is specified, the compiler will + pick it based on the optimization level: 1 for *-O1*, *-O2* or + *-Os* and 2 for *-O3*. + + If you specify this switch the compiler will access these bodies, + creating an extra source dependency for the resulting object file, and + where possible, the call will be inlined. + For further details on when inlining is possible + see :ref:`Inlining_of_Subprograms`. + + +.. index:: -gnatN (gcc) + +:samp:`-gnatN` + This switch activates front-end inlining which also + generates additional dependencies. + + When using a gcc-based back end (in practice this means using any version + of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of + *-gnatN* is deprecated, and the use of *-gnatn* is preferred. + Historically front end inlining was more extensive than the gcc back end + inlining, but that is no longer the case. + +.. _Auxiliary_Output_Control: + +Auxiliary Output Control +------------------------ + +.. index:: -gnatt (gcc) +.. index:: Writing internal trees +.. index:: Internal trees, writing to file + +:samp:`-gnatt` + Causes GNAT to write the internal tree for a unit to a file (with the + extension :file:`.adt`. + This not normally required, but is used by separate analysis tools. + Typically + these tools do the necessary compilations automatically, so you should + not have to specify this switch in normal operation. + Note that the combination of switches *-gnatct* + generates a tree in the form required by ASIS applications. + + +.. index:: -gnatu (gcc) + +:samp:`-gnatu` + Print a list of units required by this compilation on :file:`stdout`. + The listing includes all units on which the unit being compiled depends + either directly or indirectly. + + +.. index:: -pass-exit-codes (gcc) + +:samp:`-pass-exit-codes` + If this switch is not used, the exit code returned by *gcc* when + compiling multiple files indicates whether all source files have + been successfully used to generate object files or not. + + When *-pass-exit-codes* is used, *gcc* exits with an extended + exit status and allows an integrated development environment to better + react to a compilation failure. Those exit status are: + + ========== ====================================================== + *5* There was an error in at least one source file. + *3* At least one source file did not generate an object file. + *2* The compiler died unexpectedly (internal error for example). + *0* An object file has been generated for every source file. + ========== ====================================================== + +.. _Debugging_Control: + +Debugging Control +----------------- + + .. index:: Debugging options + + +.. index:: -gnatd (gcc) + +:samp:`-gnatd{x}` + Activate internal debugging switches. `x` is a letter or digit, or + string of letters or digits, which specifies the type of debugging + outputs desired. Normally these are used only for internal development + or system debugging purposes. You can find full documentation for these + switches in the body of the `Debug` unit in the compiler source + file :file:`debug.adb`. + + +.. index:: -gnatG (gcc) + +:samp:`-gnatG[={nn}]` + This switch causes the compiler to generate auxiliary output containing + a pseudo-source listing of the generated expanded code. Like most Ada + compilers, GNAT works by first transforming the high level Ada code into + lower level constructs. For example, tasking operations are transformed + into calls to the tasking run-time routines. A unique capability of GNAT + is to list this expanded code in a form very close to normal Ada source. + This is very useful in understanding the implications of various Ada + usage on the efficiency of the generated code. There are many cases in + Ada (e.g., the use of controlled types), where simple Ada statements can + generate a lot of run-time code. By using *-gnatG* you can identify + these cases, and consider whether it may be desirable to modify the coding + approach to improve efficiency. + + The optional parameter `nn` if present after -gnatG specifies an + alternative maximum line length that overrides the normal default of 72. + This value is in the range 40-999999, values less than 40 being silently + reset to 40. The equal sign is optional. + + The format of the output is very similar to standard Ada source, and is + easily understood by an Ada programmer. The following special syntactic + additions correspond to low level features used in the generated code that + do not have any exact analogies in pure Ada source form. The following + is a partial list of these special constructions. See the spec + of package `Sprint` in file :file:`sprint.ads` for a full list. + + .. index:: -gnatL (gcc) + + If the switch *-gnatL* is used in conjunction with + *-gnatG*, then the original source lines are interspersed + in the expanded source (as comment lines with the original line number). + + :samp:`new {xxx} [storage_pool = {yyy}]` + Shows the storage pool being used for an allocator. + + + :samp:`at end {procedure-name};` + Shows the finalization (cleanup) procedure for a scope. + + + :samp:`(if {expr} then {expr} else {expr})` + Conditional expression equivalent to the `x?y:z` construction in C. + + + :samp:`{target}^({source})` + A conversion with floating-point truncation instead of rounding. + + + :samp:`{target}?({source})` + A conversion that bypasses normal Ada semantic checking. In particular + enumeration types and fixed-point types are treated simply as integers. + + + :samp:`{target}?^({source})` + Combines the above two cases. + + + :samp:`{x} #/ {y}` + + :samp:`{x} #mod {y}` + + :samp:`{x} # {y}` + + :samp:`{x} #rem {y}` + A division or multiplication of fixed-point values which are treated as + integers without any kind of scaling. + + + :samp:`free {expr} [storage_pool = {xxx}]` + Shows the storage pool associated with a `free` statement. + + + :samp:`[subtype or type declaration]` + Used to list an equivalent declaration for an internally generated + type that is referenced elsewhere in the listing. + + + :samp:`freeze {type-name} [{actions}]` + Shows the point at which `type-name` is frozen, with possible + associated actions to be performed at the freeze point. + + + :samp:`reference {itype}` + Reference (and hence definition) to internal type `itype`. + + + :samp:`{function-name}! ({arg}, {arg}, {arg})` + Intrinsic function call. + + + :samp:`{label-name} : label` + Declaration of label `labelname`. + + + :samp:`#$ {subprogram-name}` + An implicit call to a run-time support routine + (to meet the requirement of H.3.1(9) in a + convenient manner). + + + :samp:`{expr} && {expr} && {expr} ... && {expr}` + A multiple concatenation (same effect as `expr` & `expr` & + `expr`, but handled more efficiently). + + + :samp:`[constraint_error]` + Raise the `Constraint_Error` exception. + + + :samp:`{expression}'reference` + A pointer to the result of evaluating {expression}. + + + :samp:`{target-type}!({source-expression})` + An unchecked conversion of `source-expression` to `target-type`. + + + :samp:`[{numerator}/{denominator}]` + Used to represent internal real literals (that) have no exact + representation in base 2-16 (for example, the result of compile time + evaluation of the expression 1.0/27.0). + + +.. index:: -gnatD (gcc) + +:samp:`-gnatD[=nn]` + When used in conjunction with *-gnatG*, this switch causes + the expanded source, as described above for + *-gnatG* to be written to files with names + :file:`xxx.dg`, where :file:`xxx` is the normal file name, + instead of to the standard output file. For + example, if the source file name is :file:`hello.adb`, then a file + :file:`hello.adb.dg` will be written. The debugging + information generated by the *gcc* *-g* switch + will refer to the generated :file:`xxx.dg` file. This allows + you to do source level debugging using the generated code which is + sometimes useful for complex code, for example to find out exactly + which part of a complex construction raised an exception. This switch + also suppress generation of cross-reference information (see + *-gnatx*) since otherwise the cross-reference information + would refer to the :file:`.dg` file, which would cause + confusion since this is not the original source file. + + Note that *-gnatD* actually implies *-gnatG* + automatically, so it is not necessary to give both options. + In other words *-gnatD* is equivalent to *-gnatDG*). + + .. index:: -gnatL (gcc) + + If the switch *-gnatL* is used in conjunction with + *-gnatDG*, then the original source lines are interspersed + in the expanded source (as comment lines with the original line number). + + The optional parameter `nn` if present after -gnatD specifies an + alternative maximum line length that overrides the normal default of 72. + This value is in the range 40-999999, values less than 40 being silently + reset to 40. The equal sign is optional. + + +.. index:: -gnatr (gcc) +.. index:: pragma Restrictions + +:samp:`-gnatr` + This switch causes pragma Restrictions to be treated as Restriction_Warnings + so that violation of restrictions causes warnings rather than illegalities. + This is useful during the development process when new restrictions are added + or investigated. The switch also causes pragma Profile to be treated as + Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set + restriction warnings rather than restrictions. + + +.. index:: -gnatR (gcc) + +:samp:`-gnatR[0|1|2|3[s]]` + This switch controls output from the compiler of a listing showing + representation information for declared types and objects. For + *-gnatR0*, no information is output (equivalent to omitting + the *-gnatR* switch). For *-gnatR1* (which is the default, + so *-gnatR* with no parameter has the same effect), size and alignment + information is listed for declared array and record types. For + *-gnatR2*, size and alignment information is listed for all + declared types and objects. The `Linker_Section` is also listed for any + entity for which the `Linker_Section` is set explicitly or implicitly (the + latter case occurs for objects of a type for which a `Linker_Section` + is set). + + Finally *-gnatR3* includes symbolic + expressions for values that are computed at run time for + variant records. These symbolic expressions have a mostly obvious + format with #n being used to represent the value of the n'th + discriminant. See source files :file:`repinfo.ads/adb` in the + `GNAT` sources for full details on the format of *-gnatR3* + output. If the switch is followed by an s (e.g., *-gnatR2s*), then + the output is to a file with the name :file:`file.rep` where + file is the name of the corresponding source file. + + +:samp:`-gnatRm[s]` + This form of the switch controls output of subprogram conventions + and parameter passing mechanisms for all subprograms. A following + `s` means output to a file as described above. + + Note that it is possible for record components to have zero size. In + this case, the component clause uses an obvious extension of permitted + Ada syntax, for example `at 0 range 0 .. -1`. + + Representation information requires that code be generated (since it is the + code generator that lays out complex data structures). If an attempt is made + to output representation information when no code is generated, for example + when a subunit is compiled on its own, then no information can be generated + and the compiler outputs a message to this effect. + + +.. index:: -gnatS (gcc) + +:samp:`-gnatS` + The use of the switch *-gnatS* for an + Ada compilation will cause the compiler to output a + representation of package Standard in a form very + close to standard Ada. It is not quite possible to + do this entirely in standard Ada (since new + numeric base types cannot be created in standard + Ada), but the output is easily + readable to any Ada programmer, and is useful to + determine the characteristics of target dependent + types in package Standard. + + +.. index:: -gnatx (gcc) + +:samp:`-gnatx` + Normally the compiler generates full cross-referencing information in + the :file:`ALI` file. This information is used by a number of tools, + including `gnatfind` and `gnatxref`. The *-gnatx* switch + suppresses this information. This saves some space and may slightly + speed up compilation, but means that these tools cannot be used. + +.. _Exception_Handling_Control: + +Exception Handling Control +-------------------------- + +GNAT uses two methods for handling exceptions at run-time. The +`setjmp/longjmp` method saves the context when entering +a frame with an exception handler. Then when an exception is +raised, the context can be restored immediately, without the +need for tracing stack frames. This method provides very fast +exception propagation, but introduces significant overhead for +the use of exception handlers, even if no exception is raised. + +The other approach is called 'zero cost' exception handling. +With this method, the compiler builds static tables to describe +the exception ranges. No dynamic code is required when entering +a frame containing an exception handler. When an exception is +raised, the tables are used to control a back trace of the +subprogram invocation stack to locate the required exception +handler. This method has considerably poorer performance for +the propagation of exceptions, but there is no overhead for +exception handlers if no exception is raised. Note that in this +mode and in the context of mixed Ada and C/C++ programming, +to propagate an exception through a C/C++ code, the C/C++ code +must be compiled with the *-funwind-tables* GCC's +option. + +The following switches may be used to control which of the +two exception handling methods is used. + + + +.. index:: --RTS=sjlj (gnatmake) + +:samp:`--RTS=sjlj` + This switch causes the setjmp/longjmp run-time (when available) to be used + for exception handling. If the default + mechanism for the target is zero cost exceptions, then + this switch can be used to modify this default, and must be + used for all units in the partition. + This option is rarely used. One case in which it may be + advantageous is if you have an application where exception + raising is common and the overall performance of the + application is improved by favoring exception propagation. + + +.. index:: --RTS=zcx (gnatmake) +.. index:: Zero Cost Exceptions + +:samp:`--RTS=zcx` + This switch causes the zero cost approach to be used + for exception handling. If this is the default mechanism for the + target (see below), then this switch is unneeded. If the default + mechanism for the target is setjmp/longjmp exceptions, then + this switch can be used to modify this default, and must be + used for all units in the partition. + This option can only be used if the zero cost approach + is available for the target in use, otherwise it will generate an error. + +The same option *--RTS* must be used both for *gcc* +and *gnatbind*. Passing this option to *gnatmake* +(:ref:`Switches_for_gnatmake`) will ensure the required consistency +through the compilation and binding steps. + +.. _Units_to_Sources_Mapping_Files: + +Units to Sources Mapping Files +------------------------------ + + + +.. index:: -gnatem (gcc) + +:samp:`-gnatem={path}` + A mapping file is a way to communicate to the compiler two mappings: + from unit names to file names (without any directory information) and from + file names to path names (with full directory information). These mappings + are used by the compiler to short-circuit the path search. + + The use of mapping files is not required for correct operation of the + compiler, but mapping files can improve efficiency, particularly when + sources are read over a slow network connection. In normal operation, + you need not be concerned with the format or use of mapping files, + and the *-gnatem* switch is not a switch that you would use + explicitly. It is intended primarily for use by automatic tools such as + *gnatmake* running under the project file facility. The + description here of the format of mapping files is provided + for completeness and for possible use by other tools. + + A mapping file is a sequence of sets of three lines. In each set, the + first line is the unit name, in lower case, with `%s` appended + for specs and `%b` appended for bodies; the second line is the + file name; and the third line is the path name. + + Example:: + + main%b + main.2.ada + /gnat/project1/sources/main.2.ada + + + When the switch *-gnatem* is specified, the compiler will + create in memory the two mappings from the specified file. If there is + any problem (nonexistent file, truncated file or duplicate entries), + no mapping will be created. + + Several *-gnatem* switches may be specified; however, only the + last one on the command line will be taken into account. + + When using a project file, *gnatmake* creates a temporary + mapping file and communicates it to the compiler using this switch. + + +.. _Code_Generation_Control: + +Code Generation Control +----------------------- + +The GCC technology provides a wide range of target dependent +:samp:`-m` switches for controlling +details of code generation with respect to different versions of +architectures. This includes variations in instruction sets (e.g., +different members of the power pc family), and different requirements +for optimal arrangement of instructions (e.g., different members of +the x86 family). The list of available *-m* switches may be +found in the GCC documentation. + +Use of these *-m* switches may in some cases result in improved +code performance. + +The GNAT technology is tested and qualified without any +:samp:`-m` switches, +so generally the most reliable approach is to avoid the use of these +switches. However, we generally expect most of these switches to work +successfully with GNAT, and many customers have reported successful +use of these options. + +Our general advice is to avoid the use of *-m* switches unless +special needs lead to requirements in this area. In particular, +there is no point in using *-m* switches to improve performance +unless you actually see a performance improvement. + + +.. _Binding_with_gnatbind: + +Binding with `gnatbind` +======================= + +.. index:: ! gnatbind + +This chapter describes the GNAT binder, `gnatbind`, which is used +to bind compiled GNAT objects. + +Note: to invoke `gnatbind` with a project file, use the `gnat` +driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + +The `gnatbind` program performs four separate functions: + +* Checks that a program is consistent, in accordance with the rules in + Chapter 10 of the Ada Reference Manual. In particular, error + messages are generated if a program uses inconsistent versions of a + given unit. + +* Checks that an acceptable order of elaboration exists for the program + and issues an error message if it cannot find an order of elaboration + that satisfies the rules in Chapter 10 of the Ada Language Manual. + +* Generates a main program incorporating the given elaboration order. + This program is a small Ada package (body and spec) that + must be subsequently compiled + using the GNAT compiler. The necessary compilation step is usually + performed automatically by *gnatlink*. The two most important + functions of this program + are to call the elaboration routines of units in an appropriate order + and to call the main program. + +* Determines the set of object files required by the given main program. + This information is output in the forms of comments in the generated program, + to be read by the *gnatlink* utility used to link the Ada application. + +.. _Running_gnatbind: + +Running `gnatbind` +------------------ + +The form of the `gnatbind` command is + +.. code-block:: sh + + $ gnatbind [`switches`] `mainprog`[.ali] [`switches`] + + +where :file:`mainprog.adb` is the Ada file containing the main program +unit body. `gnatbind` constructs an Ada +package in two files whose names are +:file:`b~mainprog.ads`, and :file:`b~mainprog.adb`. +For example, if given the +parameter :file:`hello.ali`, for a main program contained in file +:file:`hello.adb`, the binder output files would be :file:`b~hello.ads` +and :file:`b~hello.adb`. + +When doing consistency checking, the binder takes into consideration +any source files it can locate. For example, if the binder determines +that the given main program requires the package `Pack`, whose +:file:`.ALI` +file is :file:`pack.ali` and whose corresponding source spec file is +:file:`pack.ads`, it attempts to locate the source file :file:`pack.ads` +(using the same search path conventions as previously described for the +*gcc* command). If it can locate this source file, it checks that +the time stamps +or source checksums of the source and its references to in :file:`ALI` files +match. In other words, any :file:`ALI` files that mentions this spec must have +resulted from compiling this version of the source file (or in the case +where the source checksums match, a version close enough that the +difference does not matter). + +.. index:: Source files, use by binder + +The effect of this consistency checking, which includes source files, is +that the binder ensures that the program is consistent with the latest +version of the source files that can be located at bind time. Editing a +source file without compiling files that depend on the source file cause +error messages to be generated by the binder. + +For example, suppose you have a main program :file:`hello.adb` and a +package `P`, from file :file:`p.ads` and you perform the following +steps: + +* Enter `gcc -c hello.adb` to compile the main program. + +* Enter `gcc -c p.ads` to compile package `P`. + +* Edit file :file:`p.ads`. + +* Enter `gnatbind hello`. + +At this point, the file :file:`p.ali` contains an out-of-date time stamp +because the file :file:`p.ads` has been edited. The attempt at binding +fails, and the binder generates the following error messages: + + +:: + + error: "hello.adb" must be recompiled ("p.ads" has been modified) + error: "p.ads" has been modified and must be recompiled + + +Now both files must be recompiled as indicated, and then the bind can +succeed, generating a main program. You need not normally be concerned +with the contents of this file, but for reference purposes a sample +binder output file is given in :ref:`Example_of_Binder_Output_File`. + +In most normal usage, the default mode of *gnatbind* which is to +generate the main package in Ada, as described in the previous section. +In particular, this means that any Ada programmer can read and understand +the generated main program. It can also be debugged just like any other +Ada code provided the *-g* switch is used for +*gnatbind* and *gnatlink*. + +.. _Switches_for_gnatbind: + +Switches for *gnatbind* +----------------------- + +The following switches are available with `gnatbind`; details will +be presented in subsequent sections. + + +.. index:: --version (gnatbind) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + + +.. index:: --help (gnatbind) + +:samp:`--help` + If *--version* was not used, display usage, then exit disregarding + all other options. + + +.. index:: -a (gnatbind) + +:samp:`-a` + Indicates that, if supported by the platform, the adainit procedure should + be treated as an initialisation routine by the linker (a constructor). This + is intended to be used by the Project Manager to automatically initialize + shared Stand-Alone Libraries. + + +.. index:: -aO (gnatbind) + +:samp:`-aO` + Specify directory to be searched for ALI files. + + +.. index:: -aI (gnatbind) + +:samp:`-aI` + Specify directory to be searched for source file. + + +.. index:: -A (gnatbind) + +:samp:`-A[={filename}]` + Output ALI list (to standard output or to the named file). + + +.. index:: -b (gnatbind) + +:samp:`-b` + Generate brief messages to :file:`stderr` even if verbose mode set. + + +.. index:: -c (gnatbind) + +:samp:`-c` + Check only, no generation of binder output file. + + +.. index:: -dnn[k|m] (gnatbind) + +:samp:`-d{nn}[k|m]` + This switch can be used to change the default task stack size value + to a specified size `nn`, which is expressed in bytes by default, or + in kilobytes when suffixed with `k` or in megabytes when suffixed + with `m`. + In the absence of a :samp:`[k|m]` suffix, this switch is equivalent, + in effect, to completing all task specs with + + .. code-block:: ada + + pragma Storage_Size (nn); + + When they do not already have such a pragma. + + +.. index:: -D (gnatbind) + +:samp:`-D{nn}[k|m]` + This switch can be used to change the default secondary stack size value + to a specified size `nn`, which is expressed in bytes by default, or + in kilobytes when suffixed with `k` or in megabytes when suffixed + with `m`. + + The secondary stack is used to deal with functions that return a variable + sized result, for example a function returning an unconstrained + String. There are two ways in which this secondary stack is allocated. + + For most targets, the secondary stack is growing on demand and is allocated + as a chain of blocks in the heap. The -D option is not very + relevant. It only give some control over the size of the allocated + blocks (whose size is the minimum of the default secondary stack size value, + and the actual size needed for the current allocation request). + + For certain targets, notably VxWorks 653, + the secondary stack is allocated by carving off a fixed ratio chunk of the + primary task stack. The -D option is used to define the + size of the environment task's secondary stack. + + +.. index:: -e (gnatbind) + +:samp:`-e` + Output complete list of elaboration-order dependencies. + + +.. index:: -E (gnatbind) + +:samp:`-E` + Store tracebacks in exception occurrences when the target supports it. + + See also the packages `GNAT.Traceback` and + `GNAT.Traceback.Symbolic` for more information. + Note that on x86 ports, you must not use *-fomit-frame-pointer* + *gcc* option. + + +.. index:: -F (gnatbind) + +:samp:`-F` + Force the checks of elaboration flags. *gnatbind* does not normally + generate checks of elaboration flags for the main executable, except when + a Stand-Alone Library is used. However, there are cases when this cannot be + detected by gnatbind. An example is importing an interface of a Stand-Alone + Library through a pragma Import and only specifying through a linker switch + this Stand-Alone Library. This switch is used to guarantee that elaboration + flag checks are generated. + + +.. index:: -h (gnatbind) + +:samp:`-h` + Output usage (help) information + + + .. index:: -H32 (gnatbind) + +:samp:`-H32` + Use 32-bit allocations for `__gnat_malloc` (and thus for access types). + For further details see :ref:`Dynamic_Allocation_Control`. + + + .. index:: -H64 (gnatbind) + .. index:: __gnat_malloc + +:samp:`-H64` + Use 64-bit allocations for `__gnat_malloc` (and thus for access types). + For further details see :ref:`Dynamic_Allocation_Control`. + + + .. index:: -I (gnatbind) + +:samp:`-I` + Specify directory to be searched for source and ALI files. + + + .. index:: -I- (gnatbind) + +:samp:`-I-` + Do not look for sources in the current directory where `gnatbind` was + invoked, and do not look for ALI files in the directory containing the + ALI file named in the `gnatbind` command line. + + + .. index:: -l (gnatbind) + +:samp:`-l` + Output chosen elaboration order. + + + .. index:: -L (gnatbind) + +:samp:`-L{xxx}` + Bind the units for library building. In this case the adainit and + adafinal procedures (:ref:`Binding_with_Non-Ada_Main_Programs`) + are renamed to `xxx`init and + `xxx`final. + Implies -n. + (:ref:`GNAT_and_Libraries`, for more details.) + + + .. index:: -M (gnatbind) + +:samp:`-M{xyz}` + Rename generated main program from main to xyz. This option is + supported on cross environments only. + + + .. index:: -m (gnatbind) + +:samp:`-m{n}` + Limit number of detected errors or warnings to `n`, where `n` is + in the range 1..999999. The default value if no switch is + given is 9999. If the number of warnings reaches this limit, then a + message is output and further warnings are suppressed, the bind + continues in this case. If the number of errors reaches this + limit, then a message is output and the bind is abandoned. + A value of zero means that no limit is enforced. The equal + sign is optional. + + + .. index:: -n (gnatbind) + +:samp:`-n` + No main program. + + + .. index:: -nostdinc (gnatbind) + +:samp:`-nostdinc` + Do not look for sources in the system default directory. + + + .. index:: -nostdlib (gnatbind) + +:samp:`-nostdlib` + Do not look for library files in the system default directory. + + + .. index:: --RTS (gnatbind) + +:samp:`--RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + .. index:: -o (gnatbind) + +:samp:`-o {file}` + Name the output file `file` (default is :file:`b~`xxx`.adb`). + Note that if this option is used, then linking must be done manually, + gnatlink cannot be used. + + + .. index:: -O (gnatbind) + +:samp:`-O[={filename}]` + Output object list (to standard output or to the named file). + + + .. index:: -p (gnatbind) + +:samp:`-p` + Pessimistic (worst-case) elaboration order + + + .. index:: -P (gnatbind) + +:samp:`-P` + Generate binder file suitable for CodePeer. + + + .. index:: -R (gnatbind) + +:samp:`-R` + Output closure source list, which includes all non-run-time units that are + included in the bind. + + + .. index:: -Ra (gnatbind) + +:samp:`-Ra` + Like *-R* but the list includes run-time units. + + + .. index:: -s (gnatbind) + +:samp:`-s` + Require all source files to be present. + + + .. index:: -S (gnatbind) + +:samp:`-S{xxx}` + Specifies the value to be used when detecting uninitialized scalar + objects with pragma Initialize_Scalars. + The `xxx` string specified with the switch is one of: + + * ``in`` for an invalid value*. + + If zero is invalid for the discrete type in question, + then the scalar value is set to all zero bits. + For signed discrete types, the largest possible negative value of + the underlying scalar is set (i.e. a one bit followed by all zero bits). + For unsigned discrete types, the underlying scalar value is set to all + one bits. For floating-point types, a NaN value is set + (see body of package System.Scalar_Values for exact values). + + * ``lo`` for low value. + + If zero is invalid for the discrete type in question, + then the scalar value is set to all zero bits. + For signed discrete types, the largest possible negative value of + the underlying scalar is set (i.e. a one bit followed by all zero bits). + For unsigned discrete types, the underlying scalar value is set to all + zero bits. For floating-point, a small value is set + (see body of package System.Scalar_Values for exact values). + + * ``hi`` for high value. + + If zero is invalid for the discrete type in question, + then the scalar value is set to all one bits. + For signed discrete types, the largest possible positive value of + the underlying scalar is set (i.e. a zero bit followed by all one bits). + For unsigned discrete types, the underlying scalar value is set to all + one bits. For floating-point, a large value is set + (see body of package System.Scalar_Values for exact values). + + * `xx` for hex value (two hex digits). + + The underlying scalar is set to a value consisting of repeated bytes, whose + value corresponds to the given value. For example if ``BF`` is given, + then a 32-bit scalar value will be set to the bit patterm ``16#BFBFBFBF#``. + + .. index:: GNAT_INIT_SCALARS + + In addition, you can specify *-Sev* to indicate that the value is + to be set at run time. In this case, the program will look for an environment + variable of the form :samp:`GNAT_INIT_SCALARS={yy}`, where `yy` is one + of *in/lo/hi/`xx*` with the same meanings as above. + If no environment variable is found, or if it does not have a valid value, + then the default is *in* (invalid values). + +.. index:: -static (gnatbind) + +:samp:`-static` + Link against a static GNAT run time. + + + .. index:: -shared (gnatbind) + +:samp:`-shared` + Link against a shared GNAT run time when available. + + + .. index:: -t (gnatbind) + +:samp:`-t` + Tolerate time stamp and other consistency errors + + + .. index:: -T (gnatbind) + +:samp:`-T{n}` + Set the time slice value to `n` milliseconds. If the system supports + the specification of a specific time slice value, then the indicated value + is used. If the system does not support specific time slice values, but + does support some general notion of round-robin scheduling, then any + nonzero value will activate round-robin scheduling. + + A value of zero is treated specially. It turns off time + slicing, and in addition, indicates to the tasking run time that the + semantics should match as closely as possible the Annex D + requirements of the Ada RM, and in particular sets the default + scheduling policy to `FIFO_Within_Priorities`. + + + .. index:: -u (gnatbind) + +:samp:`-u{n}` + Enable dynamic stack usage, with `n` results stored and displayed + at program termination. A result is generated when a task + terminates. Results that can't be stored are displayed on the fly, at + task termination. This option is currently not supported on Itanium + platforms. (See :ref:`Dynamic_Stack_Usage_Analysis` for details.) + + + .. index:: -v (gnatbind) + +:samp:`-v` + Verbose mode. Write error messages, header, summary output to + :file:`stdout`. + + + .. index:: -w (gnatbind) + +:samp:`-w{x}` + Warning mode; `x` = s/e for suppress/treat as error + + + .. index:: -Wx (gnatbind) + +:samp:`-Wx{e}` + Override default wide character encoding for standard Text_IO files. + + + .. index:: -x (gnatbind) + +:samp:`-x` + Exclude source files (check object consistency only). + + + .. index:: -Xnnn (gnatbind) + +:samp:`-X{nnn}` + Set default exit status value, normally 0 for POSIX compliance. + + + .. index:: -y (gnatbind) + +:samp:`-y` + Enable leap seconds support in `Ada.Calendar` and its children. + + + .. index:: -z (gnatbind) + +:samp:`-z` + No main subprogram. + +You may obtain this listing of switches by running `gnatbind` with +no arguments. + + +.. _Consistency-Checking_Modes: + +Consistency-Checking Modes +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As described earlier, by default `gnatbind` checks +that object files are consistent with one another and are consistent +with any source files it can locate. The following switches control binder +access to sources. + + + .. index:: -s (gnatbind) + +:samp:`-s` + Require source files to be present. In this mode, the binder must be + able to locate all source files that are referenced, in order to check + their consistency. In normal mode, if a source file cannot be located it + is simply ignored. If you specify this switch, a missing source + file is an error. + + + .. index:: -Wx (gnatbind) + +:samp:`-Wx{e}` + Override default wide character encoding for standard Text_IO files. + Normally the default wide character encoding method used for standard + [Wide\_[Wide\_]]Text_IO files is taken from the encoding specified for + the main source input (see description of switch + *-gnatWx* for the compiler). The + use of this switch for the binder (which has the same set of + possible arguments) overrides this default as specified. + + + .. index:: -x (gnatbind) + +:samp:`-x` + Exclude source files. In this mode, the binder only checks that ALI + files are consistent with one another. Source files are not accessed. + The binder runs faster in this mode, and there is still a guarantee that + the resulting program is self-consistent. + If a source file has been edited since it was last compiled, and you + specify this switch, the binder will not detect that the object + file is out of date with respect to the source file. Note that this is the + mode that is automatically used by *gnatmake* because in this + case the checking against sources has already been performed by + *gnatmake* in the course of compilation (i.e., before binding). + + +.. _Binder_Error_Message_Control: + +Binder Error Message Control +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following switches provide control over the generation of error +messages from the binder: + + + + .. index:: -v (gnatbind) + +:samp:`-v` + Verbose mode. In the normal mode, brief error messages are generated to + :file:`stderr`. If this switch is present, a header is written + to :file:`stdout` and any error messages are directed to :file:`stdout`. + All that is written to :file:`stderr` is a brief summary message. + + + .. index:: -b (gnatbind) + +:samp:`-b` + Generate brief error messages to :file:`stderr` even if verbose mode is + specified. This is relevant only when used with the + *-v* switch. + + + .. index:: -m (gnatbind) + +:samp:`-m{n}` + Limits the number of error messages to `n`, a decimal integer in the + range 1-999. The binder terminates immediately if this limit is reached. + + + .. index:: -M (gnatbind) + +:samp:`-M{xxx}` + Renames the generated main program from `main` to `xxx`. + This is useful in the case of some cross-building environments, where + the actual main program is separate from the one generated + by `gnatbind`. + + + .. index:: -ws (gnatbind) + .. index:: Warnings + +:samp:`-ws` + Suppress all warning messages. + + + .. index:: -we (gnatbind) + +:samp:`-we` + Treat any warning messages as fatal errors. + + + .. index:: -t (gnatbind) + .. index:: Time stamp checks, in binder + .. index:: Binder consistency checks + .. index:: Consistency checks, in binder + +:samp:`-t` + The binder performs a number of consistency checks including: + + + * Check that time stamps of a given source unit are consistent + + * Check that checksums of a given source unit are consistent + + * Check that consistent versions of `GNAT` were used for compilation + + * Check consistency of configuration pragmas as required + + Normally failure of such checks, in accordance with the consistency + requirements of the Ada Reference Manual, causes error messages to be + generated which abort the binder and prevent the output of a binder + file and subsequent link to obtain an executable. + + The *-t* switch converts these error messages + into warnings, so that + binding and linking can continue to completion even in the presence of such + errors. The result may be a failed link (due to missing symbols), or a + non-functional executable which has undefined semantics. + + .. note:: + + This means that *-t* should be used only in unusual situations, + with extreme care. + +.. _Elaboration_Control: + +Elaboration Control +^^^^^^^^^^^^^^^^^^^ + +The following switches provide additional control over the elaboration +order. For full details see :ref:`Elaboration_Order_Handling_in_GNAT`. + + + .. index:: -p (gnatbind) + +:samp:`-p` + Normally the binder attempts to choose an elaboration order that is + likely to minimize the likelihood of an elaboration order error resulting + in raising a `Program_Error` exception. This switch reverses the + action of the binder, and requests that it deliberately choose an order + that is likely to maximize the likelihood of an elaboration error. + This is useful in ensuring portability and avoiding dependence on + accidental fortuitous elaboration ordering. + + Normally it only makes sense to use the *-p* + switch if dynamic + elaboration checking is used (*-gnatE* switch used for compilation). + This is because in the default static elaboration mode, all necessary + `Elaborate` and `Elaborate_All` pragmas are implicitly inserted. + These implicit pragmas are still respected by the binder in + *-p* mode, so a + safe elaboration order is assured. + + Note that *-p* is not intended for + production use; it is more for debugging/experimental use. + +.. _Output_Control: + +Output Control +^^^^^^^^^^^^^^ + +The following switches allow additional control over the output +generated by the binder. + + + .. index:: -c (gnatbind) + +:samp:`-c` + Check only. Do not generate the binder output file. In this mode the + binder performs all error checks but does not generate an output file. + + + .. index:: -e (gnatbind) + +:samp:`-e` + Output complete list of elaboration-order dependencies, showing the + reason for each dependency. This output can be rather extensive but may + be useful in diagnosing problems with elaboration order. The output is + written to :file:`stdout`. + + + .. index:: -h (gnatbind) + +:samp:`-h` + Output usage information. The output is written to :file:`stdout`. + + + .. index:: -K (gnatbind) + +:samp:`-K` + Output linker options to :file:`stdout`. Includes library search paths, + contents of pragmas Ident and Linker_Options, and libraries added + by `gnatbind`. + + + .. index:: -l (gnatbind) + +:samp:`-l` + Output chosen elaboration order. The output is written to :file:`stdout`. + + + .. index:: -O (gnatbind) + +:samp:`-O` + Output full names of all the object files that must be linked to provide + the Ada component of the program. The output is written to :file:`stdout`. + This list includes the files explicitly supplied and referenced by the user + as well as implicitly referenced run-time unit files. The latter are + omitted if the corresponding units reside in shared libraries. The + directory names for the run-time units depend on the system configuration. + + + .. index:: -o (gnatbind) + +:samp:`-o {file}` + Set name of output file to `file` instead of the normal + :file:`b~`mainprog`.adb` default. Note that `file` denote the Ada + binder generated body filename. + Note that if this option is used, then linking must be done manually. + It is not possible to use gnatlink in this case, since it cannot locate + the binder file. + + + .. index:: -r (gnatbind) + +:samp:`-r` + Generate list of `pragma Restrictions` that could be applied to + the current unit. This is useful for code audit purposes, and also may + be used to improve code generation in some cases. + + +.. _Dynamic_Allocation_Control: + +Dynamic Allocation Control +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The heap control switches -- *-H32* and *-H64* -- +determine whether dynamic allocation uses 32-bit or 64-bit memory. +They only affect compiler-generated allocations via `__gnat_malloc`; +explicit calls to `malloc` and related functions from the C +run-time library are unaffected. + +:samp:`-H32` + Allocate memory on 32-bit heap + + +:samp:`-H64` + Allocate memory on 64-bit heap. This is the default + unless explicitly overridden by a `'Size` clause on the access type. + +These switches are only effective on VMS platforms. + + +.. _Binding_with_Non-Ada_Main_Programs: + +Binding with Non-Ada Main Programs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The description so far has assumed that the main +program is in Ada, and that the task of the binder is to generate a +corresponding function `main` that invokes this Ada main +program. GNAT also supports the building of executable programs where +the main program is not in Ada, but some of the called routines are +written in Ada and compiled using GNAT (:ref:`Mixed_Language_Programming`). +The following switch is used in this situation: + + + .. index:: -n (gnatbind) + +:samp:`-n` + No main program. The main program is not in Ada. + +In this case, most of the functions of the binder are still required, +but instead of generating a main program, the binder generates a file +containing the following callable routines: + + .. index:: adainit + + *adainit* + You must call this routine to initialize the Ada part of the program by + calling the necessary elaboration routines. A call to `adainit` is + required before the first call to an Ada subprogram. + + Note that it is assumed that the basic execution environment must be setup + to be appropriate for Ada execution at the point where the first Ada + subprogram is called. In particular, if the Ada code will do any + floating-point operations, then the FPU must be setup in an appropriate + manner. For the case of the x86, for example, full precision mode is + required. The procedure GNAT.Float_Control.Reset may be used to ensure + that the FPU is in the right state. + + .. index:: adafinal + + *adafinal* + You must call this routine to perform any library-level finalization + required by the Ada subprograms. A call to `adafinal` is required + after the last call to an Ada subprogram, and before the program + terminates. + +.. index:: -n (gnatbind) +.. index:: Binder, multiple input files + +If the *-n* switch +is given, more than one ALI file may appear on +the command line for `gnatbind`. The normal *closure* +calculation is performed for each of the specified units. Calculating +the closure means finding out the set of units involved by tracing +|with| references. The reason it is necessary to be able to +specify more than one ALI file is that a given program may invoke two or +more quite separate groups of Ada units. + +The binder takes the name of its output file from the last specified ALI +file, unless overridden by the use of the *-o file*. + +.. index:: -o (gnatbind) + +The output is an Ada unit in source form that can be compiled with GNAT. +This compilation occurs automatically as part of the *gnatlink* +processing. + +Currently the GNAT run time requires a FPU using 80 bits mode +precision. Under targets where this is not the default it is required to +call GNAT.Float_Control.Reset before using floating point numbers (this +include float computation, float input and output) in the Ada code. A +side effect is that this could be the wrong mode for the foreign code +where floating point computation could be broken after this call. + + +.. _Binding_Programs_with_No_Main_Subprogram: + +Binding Programs with No Main Subprogram +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is possible to have an Ada program which does not have a main +subprogram. This program will call the elaboration routines of all the +packages, then the finalization routines. + +The following switch is used to bind programs organized in this manner: + + .. index:: -z (gnatbind) + +:samp:`-z` + Normally the binder checks that the unit name given on the command line + corresponds to a suitable main subprogram. When this switch is used, + a list of ALI files can be given, and the execution of the program + consists of elaboration of these units in an appropriate order. Note + that the default wide character encoding method for standard Text_IO + files is always set to Brackets if this switch is set (you can use + the binder switch + *-Wx* to override this default). + + +.. _Command-Line_Access: + +Command-Line Access +------------------- + +The package `Ada.Command_Line` provides access to the command-line +arguments and program name. In order for this interface to operate +correctly, the two variables + +.. code-block:: c + + int gnat_argc; + char **gnat_argv; + +.. index:: gnat_argv +.. index:: gnat_argc + +are declared in one of the GNAT library routines. These variables must +be set from the actual `argc` and `argv` values passed to the +main program. With no *n* present, `gnatbind` +generates the C main program to automatically set these variables. +If the *n* switch is used, there is no automatic way to +set these variables. If they are not set, the procedures in +`Ada.Command_Line` will not be available, and any attempt to use +them will raise `Constraint_Error`. If command line access is +required, your main program must set `gnat_argc` and +`gnat_argv` from the `argc` and `argv` values passed to +it. + + +.. _Search_Paths_for_gnatbind: + +Search Paths for `gnatbind` +--------------------------- + +The binder takes the name of an ALI file as its argument and needs to +locate source files as well as other ALI files to verify object consistency. + +For source files, it follows exactly the same search rules as *gcc* +(see :ref:`Search_Paths_and_the_Run-Time_Library_RTL`). For ALI files the +directories searched are: + +* The directory containing the ALI file named in the command line, unless + the switch *-I-* is specified. + +* All directories specified by *-I* + switches on the `gnatbind` + command line, in the order given. + + .. index:: ADA_PRJ_OBJECTS_FILE + +* Each of the directories listed in the text file whose name is given + by the :envvar:`ADA_PRJ_OBJECTS_FILE` environment variable. + + :envvar:`ADA_PRJ_OBJECTS_FILE` is normally set by gnatmake or by the gnat + driver when project files are used. It should not normally be set + by other means. + + .. index:: ADA_OBJECTS_PATH + +* Each of the directories listed in the value of the + :envvar:`ADA_OBJECTS_PATH` environment variable. + Construct this value + exactly as the :envvar:`PATH` environment variable: a list of directory + names separated by colons (semicolons when working with the NT version + of GNAT). + +* The content of the :file:`ada_object_path` file which is part of the GNAT + installation tree and is used to store standard libraries such as the + GNAT Run Time Library (RTL) unless the switch *-nostdlib* is + specified. See :ref:`Installing_a_library` + +.. index:: -I (gnatbind) +.. index:: -aI (gnatbind) +.. index:: -aO (gnatbind) + +In the binder the switch *-I* +is used to specify both source and +library file paths. Use *-aI* +instead if you want to specify +source paths only, and *-aO* +if you want to specify library paths +only. This means that for the binder +:samp:`-I{dir}` is equivalent to +:samp:`-aI{dir}` +:samp:`-aO`{dir}`. +The binder generates the bind file (a C language source file) in the +current working directory. + +.. index:: Ada +.. index:: System +.. index:: Interfaces +.. index:: GNAT + +The packages `Ada`, `System`, and `Interfaces` and their +children make up the GNAT Run-Time Library, together with the package +GNAT and its children, which contain a set of useful additional +library functions provided by GNAT. The sources for these units are +needed by the compiler and are kept together in one directory. The ALI +files and object files generated by compiling the RTL are needed by the +binder and the linker and are kept together in one directory, typically +different from the directory containing the sources. In a normal +installation, you need not specify these directory names when compiling +or binding. Either the environment variables or the built-in defaults +cause these files to be found. + +Besides simplifying access to the RTL, a major use of search paths is +in compiling sources from multiple directories. This can make +development environments much more flexible. + + +.. _Examples_of_gnatbind_Usage: + +Examples of `gnatbind` Usage +---------------------------- + +Here are some examples of `gnatbind` invovations: + + :: + + gnatbind hello + + The main program `Hello` (source program in :file:`hello.adb`) is + bound using the standard switch settings. The generated main program is + :file:`b~hello.adb`. This is the normal, default use of the binder. + + :: + + gnatbind hello -o mainprog.adb + + The main program `Hello` (source program in :file:`hello.adb`) is + bound using the standard switch settings. The generated main program is + :file:`mainprog.adb` with the associated spec in + :file:`mainprog.ads`. Note that you must specify the body here not the + spec. Note that if this option is used, then linking must be done manually, + since gnatlink will not be able to find the generated file. + + +.. _Linking_with_gnatlink: + +Linking with *gnatlink* +======================= + +.. index: ! gnatlink + +This chapter discusses *gnatlink*, a tool that links +an Ada program and builds an executable file. This utility +invokes the system linker (via the *gcc* command) +with a correct list of object files and library references. +*gnatlink* automatically determines the list of files and +references for the Ada part of a program. It uses the binder file +generated by the *gnatbind* to determine this list. + +Note: to invoke `gnatlink` with a project file, use the `gnat` +driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + +.. _Running_gnatlink: + +Running *gnatlink* +------------------ + +The form of the *gnatlink* command is + + +.. code-block:: sh + + $ gnatlink [`switches`] `mainprog`[.ali] + [`non-Ada objects`] [`linker options`] + + + +The arguments of *gnatlink* (switches, main :file:`ALI` file, +non-Ada objects +or linker options) may be in any order, provided that no non-Ada object may +be mistaken for a main :file:`ALI` file. +Any file name :file:`F` without the :file:`.ali` +extension will be taken as the main :file:`ALI` file if a file exists +whose name is the concatenation of :file:`F` and :file:`.ali`. + +:file:`mainprog.ali` references the ALI file of the main program. +The :file:`.ali` extension of this file can be omitted. From this +reference, *gnatlink* locates the corresponding binder file +:file:`b~mainprog.adb` and, using the information in this file along +with the list of non-Ada objects and linker options, constructs a +linker command file to create the executable. + +The arguments other than the *gnatlink* switches and the main +:file:`ALI` file are passed to the linker uninterpreted. +They typically include the names of +object files for units written in other languages than Ada and any library +references required to resolve references in any of these foreign language +units, or in `Import` pragmas in any Ada units. + +`linker options` is an optional list of linker specific +switches. +The default linker called by gnatlink is *gcc* which in +turn calls the appropriate system linker. + +One useful option for the linker is *-s*: it reduces the size of the +executable by removing all symbol table and relocation information from the +executable. + +Standard options for the linker such as *-lmy_lib* or +*-Ldir* can be added as is. +For options that are not recognized by +*gcc* as linker options, use the *gcc* switches +*-Xlinker* or *-Wl,*. + +Refer to the GCC documentation for +details. + +Here is an example showing how to generate a linker map: + +.. code-block:: sh + + $ gnatlink my_prog -Wl,-Map,MAPFILE + + +Using `linker options` it is possible to set the program stack and +heap size. +See :ref:`Setting_Stack_Size_from_gnatlink` and +:ref:`Setting_Heap_Size_from_gnatlink`. + +*gnatlink* determines the list of objects required by the Ada +program and prepends them to the list of objects passed to the linker. +*gnatlink* also gathers any arguments set by the use of +`pragma Linker_Options` and adds them to the list of arguments +presented to the linker. + + +.. _Switches_for_gnatlink: + +Switches for *gnatlink* +----------------------- + +The following switches are available with the *gnatlink* utility: + +.. index:: --version (gnatlink) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + + +.. index:: --help (gnatlink) + +:samp:`--help` + If *--version* was not used, display usage, then exit disregarding + all other options. + + +.. index:: Command line length +.. index:: -f (gnatlink) + +:samp:`-f` + On some targets, the command line length is limited, and *gnatlink* + will generate a separate file for the linker if the list of object files + is too long. + The *-f* switch forces this file + to be generated even if + the limit is not exceeded. This is useful in some cases to deal with + special situations where the command line length is exceeded. + + +.. index:: Debugging information, including +.. index:: -g (gnatlink) + +:samp:`-g` + The option to include debugging information causes the Ada bind file (in + other words, :file:`b~mainprog.adb`) to be compiled with *-g*. + In addition, the binder does not delete the :file:`b~mainprog.adb`, + :file:`b~mainprog.o` and :file:`b~mainprog.ali` files. + Without *-g*, the binder removes these files by default. + +.. index:: -n (gnatlink) + +:samp:`-n` + Do not compile the file generated by the binder. This may be used when + a link is rerun with different options, but there is no need to recompile + the binder file. + + +.. index:: -v (gnatlink) + +:samp:`-v` + Verbose mode. Causes additional information to be output, including a full + list of the included object files. + This switch option is most useful when you want + to see what set of object files are being used in the link step. + + +.. index:: -v -v (gnatlink) + +:samp:`-v -v` + Very verbose mode. Requests that the compiler operate in verbose mode when + it compiles the binder file, and that the system linker run in verbose mode. + + +.. index:: -o (gnatlink) + +:samp:`-o {exec-name}` + `exec-name` specifies an alternate name for the generated + executable program. If this switch is omitted, the executable has the same + name as the main unit. For example, `gnatlink try.ali` creates + an executable called :file:`try`. + + +.. index:: -b (gnatlink) + +:samp:`-b {target}` + Compile your program to run on `target`, which is the name of a + system configuration. You must have a GNAT cross-compiler built if + `target` is not the same as your host system. + + +.. index:: -B (gnatlink) + +:samp:`-B{dir}` + Load compiler executables (for example, `gnat1`, the Ada compiler) + from `dir` instead of the default location. Only use this switch + when multiple versions of the GNAT compiler are available. + See the `Directory Options` section in :title:`The_GNU_Compiler_Collection` + for further details. You would normally use the *-b* or + *-V* switch instead. + + +.. index:: -M (gnatlink) + +:samp:`-M` + When linking an executable, create a map file. The name of the map file + has the same name as the executable with extension ".map". + + +.. index:: -M= (gnatlink) + +:samp:`-M={mapfile}` + When linking an executable, create a map file. The name of the map file is + `mapfile`. + + +.. index:: --GCC=compiler_name (gnatlink) + +:samp:`--GCC={compiler_name}` + Program used for compiling the binder file. The default is + ``gcc``. You need to use quotes around `compiler_name` if + `compiler_name` contains spaces or other separator characters. + As an example ``--GCC="foo -x -y"`` will instruct *gnatlink* to + use ``foo -x -y`` as your compiler. Note that switch ``-c`` is always + inserted after your command name. Thus in the above example the compiler + command that will be used by *gnatlink* will be ``foo -c -x -y``. + A limitation of this syntax is that the name and path name of the executable + itself must not include any embedded spaces. If the compiler executable is + different from the default one (gcc or <prefix>-gcc), then the back-end + switches in the ALI file are not used to compile the binder generated source. + For example, this is the case with ``--GCC="foo -x -y"``. But the back end + switches will be used for ``--GCC="gcc -gnatv"``. If several + ``--GCC=compiler_name`` are used, only the last `compiler_name` + is taken into account. However, all the additional switches are also taken + into account. Thus, + ``--GCC="foo -x -y" --GCC="bar -z -t"`` is equivalent to + ``--GCC="bar -x -y -z -t"``. + + +.. index:: --LINK= (gnatlink) + +:samp:`--LINK={name}` + `name` is the name of the linker to be invoked. This is especially + useful in mixed language programs since languages such as C++ require + their own linker to be used. When this switch is omitted, the default + name for the linker is *gcc*. When this switch is used, the + specified linker is called instead of *gcc* with exactly the same + parameters that would have been passed to *gcc* so if the desired + linker requires different parameters it is necessary to use a wrapper + script that massages the parameters before invoking the real linker. It + may be useful to control the exact invocation by using the verbose + switch. + + +.. _Using_the_GNU_make_Utility: + +Using the GNU `make` Utility +============================ + +.. index:: make (GNU), GNU make + +This chapter offers some examples of makefiles that solve specific +problems. It does not explain how to write a makefile, nor does it try to replace the +*gnatmake* utility (:ref:`The_GNAT_Make_Program_gnatmake`). + +All the examples in this section are specific to the GNU version of +make. Although *make* is a standard utility, and the basic language +is the same, these examples use some advanced features found only in +`GNU make`. + +.. _Using_gnatmake_in_a_Makefile: + +Using gnatmake in a Makefile +---------------------------- + +.. index makefile (GNU make) + +Complex project organizations can be handled in a very powerful way by +using GNU make combined with gnatmake. For instance, here is a Makefile +which allows you to build each subsystem of a big project into a separate +shared library. Such a makefile allows you to significantly reduce the link +time of very big applications while maintaining full coherence at +each step of the build process. + +The list of dependencies are handled automatically by +*gnatmake*. The Makefile is simply used to call gnatmake in each of +the appropriate directories. + +Note that you should also read the example on how to automatically +create the list of directories +(:ref:`Automatically_Creating_a_List_of_Directories`) +which might help you in case your project has a lot of subdirectories. + + +.. code-block:: makefile + + ## This Makefile is intended to be used with the following directory + ## configuration: + ## - The sources are split into a series of csc (computer software components) + ## Each of these csc is put in its own directory. + ## Their name are referenced by the directory names. + ## They will be compiled into shared library (although this would also work + ## with static libraries + ## - The main program (and possibly other packages that do not belong to any + ## csc is put in the top level directory (where the Makefile is). + ## toplevel_dir __ first_csc (sources) __ lib (will contain the library) + ## \\_ second_csc (sources) __ lib (will contain the library) + ## \\_ ... + ## Although this Makefile is build for shared library, it is easy to modify + ## to build partial link objects instead (modify the lines with -shared and + ## gnatlink below) + ## + ## With this makefile, you can change any file in the system or add any new + ## file, and everything will be recompiled correctly (only the relevant shared + ## objects will be recompiled, and the main program will be re-linked). + + # The list of computer software component for your project. This might be + # generated automatically. + CSC_LIST=aa bb cc + + # Name of the main program (no extension) + MAIN=main + + # If we need to build objects with -fPIC, uncomment the following line + #NEED_FPIC=-fPIC + + # The following variable should give the directory containing libgnat.so + # You can get this directory through 'gnatls -v'. This is usually the last + # directory in the Object_Path. + GLIB=... + + # The directories for the libraries + # (This macro expands the list of CSC to the list of shared libraries, you + # could simply use the expanded form: + # LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so + LIB_DIR=${foreach dir,${CSC_LIST},${dir}/lib/lib${dir}.so} + + ${MAIN}: objects ${LIB_DIR} + gnatbind ${MAIN} ${CSC_LIST:%=-aO%/lib} -shared + gnatlink ${MAIN} ${CSC_LIST:%=-l%} + + objects:: + # recompile the sources + gnatmake -c -i ${MAIN}.adb ${NEED_FPIC} ${CSC_LIST:%=-I%} + + # Note: In a future version of GNAT, the following commands will be simplified + # by a new tool, gnatmlib + ${LIB_DIR}: + mkdir -p ${dir $@ } + cd ${dir $@ } && gcc -shared -o ${notdir $@ } ../*.o -L${GLIB} -lgnat + cd ${dir $@ } && cp -f ../*.ali . + + # The dependencies for the modules + # Note that we have to force the expansion of *.o, since in some cases + # make won't be able to do it itself. + aa/lib/libaa.so: ${wildcard aa/*.o} + bb/lib/libbb.so: ${wildcard bb/*.o} + cc/lib/libcc.so: ${wildcard cc/*.o} + + # Make sure all of the shared libraries are in the path before starting the + # program + run:: + LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./${MAIN} + + clean:: + ${RM} -rf ${CSC_LIST:%=%/lib} + ${RM} ${CSC_LIST:%=%/*.ali} + ${RM} ${CSC_LIST:%=%/*.o} + ${RM} *.o *.ali ${MAIN} + + +.. _Automatically_Creating_a_List_of_Directories: + +Automatically Creating a List of Directories +-------------------------------------------- + +In most makefiles, you will have to specify a list of directories, and +store it in a variable. For small projects, it is often easier to +specify each of them by hand, since you then have full control over what +is the proper order for these directories, which ones should be +included. + +However, in larger projects, which might involve hundreds of +subdirectories, it might be more convenient to generate this list +automatically. + +The example below presents two methods. The first one, although less +general, gives you more control over the list. It involves wildcard +characters, that are automatically expanded by *make*. Its +shortcoming is that you need to explicitly specify some of the +organization of your project, such as for instance the directory tree +depth, whether some directories are found in a separate tree, etc. + +The second method is the most general one. It requires an external +program, called *find*, which is standard on all Unix systems. All +the directories found under a given root directory will be added to the +list. + +.. code-block:: makefile + + # The examples below are based on the following directory hierarchy: + # All the directories can contain any number of files + # ROOT_DIRECTORY -> a -> aa -> aaa + # -> ab + # -> ac + # -> b -> ba -> baa + # -> bb + # -> bc + # This Makefile creates a variable called DIRS, that can be reused any time + # you need this list (see the other examples in this section) + + # The root of your project's directory hierarchy + ROOT_DIRECTORY=. + + #### + # First method: specify explicitly the list of directories + # This allows you to specify any subset of all the directories you need. + #### + + DIRS := a/aa/ a/ab/ b/ba/ + + #### + # Second method: use wildcards + # Note that the argument(s) to wildcard below should end with a '/'. + # Since wildcards also return file names, we have to filter them out + # to avoid duplicate directory names. + # We thus use make's `dir` and `sort` functions. + # It sets DIRs to the following value (note that the directories aaa and baa + # are not given, unless you change the arguments to wildcard). + # DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ + #### + + DIRS := ${sort ${dir ${wildcard ${ROOT_DIRECTORY}/*/ + ${ROOT_DIRECTORY}/*/*/}}} + + #### + # Third method: use an external program + # This command is much faster if run on local disks, avoiding NFS slowdowns. + # This is the most complete command: it sets DIRs to the following value: + # DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc + #### + + DIRS := ${shell find ${ROOT_DIRECTORY} -type d -print} + + + +.. _Generating_the_Command_Line_Switches: + +Generating the Command Line Switches +------------------------------------ + +Once you have created the list of directories as explained in the +previous section (:ref:`Automatically_Creating_a_List_of_Directories`), +you can easily generate the command line arguments to pass to gnatmake. + +For the sake of completeness, this example assumes that the source path +is not the same as the object path, and that you have two separate lists +of directories. + +.. code-block:: makefile + + # see "Automatically creating a list of directories" to create + # these variables + SOURCE_DIRS= + OBJECT_DIRS= + + GNATMAKE_SWITCHES := ${patsubst %,-aI%,${SOURCE_DIRS}} + GNATMAKE_SWITCHES += ${patsubst %,-aO%,${OBJECT_DIRS}} + + all: + gnatmake ${GNATMAKE_SWITCHES} main_unit + + +.. _Overcoming_Command_Line_Length_Limits: + +Overcoming Command Line Length Limits +------------------------------------- + +One problem that might be encountered on big projects is that many +operating systems limit the length of the command line. It is thus hard to give +gnatmake the list of source and object directories. + +This example shows how you can set up environment variables, which will +make *gnatmake* behave exactly as if the directories had been +specified on the command line, but have a much higher length limit (or +even none on most systems). + +It assumes that you have created a list of directories in your Makefile, +using one of the methods presented in +:ref:`Automatically_Creating_a_List_of_Directories`. +For the sake of completeness, we assume that the object +path (where the ALI files are found) is different from the sources patch. + +Note a small trick in the Makefile below: for efficiency reasons, we +create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are +expanded immediately by `make`. This way we overcome the standard +make behavior which is to expand the variables only when they are +actually used. + +On Windows, if you are using the standard Windows command shell, you must +replace colons with semicolons in the assignments to these variables. + +.. code-block:: makefile + + # In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECTS_PATH. + # This is the same thing as putting the -I arguments on the command line. + # (the equivalent of using -aI on the command line would be to define + # only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECTS_PATH). + # You can of course have different values for these variables. + # + # Note also that we need to keep the previous values of these variables, since + # they might have been set before running 'make' to specify where the GNAT + # library is installed. + + # see "Automatically creating a list of directories" to create these + # variables + SOURCE_DIRS= + OBJECT_DIRS= + + empty:= + space:=${empty} ${empty} + SOURCE_LIST := ${subst ${space},:,${SOURCE_DIRS}} + OBJECT_LIST := ${subst ${space},:,${OBJECT_DIRS}} + ADA_INCLUDE_PATH += ${SOURCE_LIST} + ADA_OBJECTS_PATH += ${OBJECT_LIST} + export ADA_INCLUDE_PATH + export ADA_OBJECTS_PATH + + all: + gnatmake main_unit diff --git a/gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst b/gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst new file mode 100644 index 00000000000..90b64a7f17a --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst @@ -0,0 +1,1864 @@ +.. |with| replace:: *with* +.. |withs| replace:: *with*\ s +.. |withed| replace:: *with*\ ed +.. |withing| replace:: *with*\ ing + +.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit + + +.. _Elaboration_Order_Handling_in_GNAT: + +********************************** +Elaboration Order Handling in GNAT +********************************** + +.. index:: Order of elaboration +.. index:: Elaboration control + +This appendix describes the handling of elaboration code in Ada and +in GNAT, and discusses how the order of elaboration of program units can +be controlled in GNAT, either automatically or with explicit programming +features. + +.. _Elaboration_Code: + +Elaboration Code +================ + +Ada provides rather general mechanisms for executing code at elaboration +time, that is to say before the main program starts executing. Such code arises +in three contexts: + +* *Initializers for variables* + + Variables declared at the library level, in package specs or bodies, can + require initialization that is performed at elaboration time, as in: + + .. code-block:: ada + + Sqrt_Half : Float := Sqrt (0.5); + +* *Package initialization code* + + Code in a `BEGIN-END` section at the outer level of a package body is + executed as part of the package body elaboration code. + +* *Library level task allocators* + + Tasks that are declared using task allocators at the library level + start executing immediately and hence can execute at elaboration time. + +Subprogram calls are possible in any of these contexts, which means that +any arbitrary part of the program may be executed as part of the elaboration +code. It is even possible to write a program which does all its work at +elaboration time, with a null main program, although stylistically this +would usually be considered an inappropriate way to structure +a program. + +An important concern arises in the context of elaboration code: +we have to be sure that it is executed in an appropriate order. What we +have is a series of elaboration code sections, potentially one section +for each unit in the program. It is important that these execute +in the correct order. Correctness here means that, taking the above +example of the declaration of `Sqrt_Half`, +if some other piece of +elaboration code references `Sqrt_Half`, +then it must run after the +section of elaboration code that contains the declaration of +`Sqrt_Half`. + +There would never be any order of elaboration problem if we made a rule +that whenever you |with| a unit, you must elaborate both the spec and body +of that unit before elaborating the unit doing the |withing|: + +.. code-block:: ada + + with Unit_1; + package Unit_2 is ... + +would require that both the body and spec of `Unit_1` be elaborated +before the spec of `Unit_2`. However, a rule like that would be far too +restrictive. In particular, it would make it impossible to have routines +in separate packages that were mutually recursive. + +You might think that a clever enough compiler could look at the actual +elaboration code and determine an appropriate correct order of elaboration, +but in the general case, this is not possible. Consider the following +example. + +In the body of `Unit_1`, we have a procedure `Func_1` +that references +the variable `Sqrt_1`, which is declared in the elaboration code +of the body of `Unit_1`: + +.. code-block:: ada + + Sqrt_1 : Float := Sqrt (0.1); + +The elaboration code of the body of `Unit_1` also contains: + +.. code-block:: ada + + if expression_1 = 1 then + Q := Unit_2.Func_2; + end if; + +`Unit_2` is exactly parallel, +it has a procedure `Func_2` that references +the variable `Sqrt_2`, which is declared in the elaboration code of +the body `Unit_2`: + +.. code-block:: ada + + Sqrt_2 : Float := Sqrt (0.1); + +The elaboration code of the body of `Unit_2` also contains: + +.. code-block:: ada + + if expression_2 = 2 then + Q := Unit_1.Func_1; + end if; + +Now the question is, which of the following orders of elaboration is +acceptable: + +:: + + Spec of Unit_1 + Spec of Unit_2 + Body of Unit_1 + Body of Unit_2 + +or + +:: + + Spec of Unit_2 + Spec of Unit_1 + Body of Unit_2 + Body of Unit_1 + +If you carefully analyze the flow here, you will see that you cannot tell +at compile time the answer to this question. +If `expression_1` is not equal to 1, +and `expression_2` is not equal to 2, +then either order is acceptable, because neither of the function calls is +executed. If both tests evaluate to true, then neither order is acceptable +and in fact there is no correct order. + +If one of the two expressions is true, and the other is false, then one +of the above orders is correct, and the other is incorrect. For example, +if `expression_1` /= 1 and `expression_2` = 2, +then the call to `Func_1` +will occur, but not the call to `Func_2.` +This means that it is essential +to elaborate the body of `Unit_1` before +the body of `Unit_2`, so the first +order of elaboration is correct and the second is wrong. + +By making `expression_1` and `expression_2` +depend on input data, or perhaps +the time of day, we can make it impossible for the compiler or binder +to figure out which of these expressions will be true, and hence it +is impossible to guarantee a safe order of elaboration at run time. + +.. _Checking_the_Elaboration_Order: + +Checking the Elaboration Order +============================== + +In some languages that involve the same kind of elaboration problems, +e.g., Java and C++, the programmer needs to take these +ordering problems into account, and it is common to +write a program in which an incorrect elaboration order gives +surprising results, because it references variables before they +are initialized. +Ada is designed to be a safe language, and a programmer-beware approach is +clearly not sufficient. Consequently, the language provides three lines +of defense: + +* *Standard rules* + + Some standard rules restrict the possible choice of elaboration + order. In particular, if you |with| a unit, then its spec is always + elaborated before the unit doing the |with|. Similarly, a parent + spec is always elaborated before the child spec, and finally + a spec is always elaborated before its corresponding body. + +.. index:: Elaboration checks +.. index:: Checks, elaboration + +* *Dynamic elaboration checks* + + Dynamic checks are made at run time, so that if some entity is accessed + before it is elaborated (typically by means of a subprogram call) + then the exception (`Program_Error`) is raised. + +* *Elaboration control* + + Facilities are provided for the programmer to specify the desired order + of elaboration. + +Let's look at these facilities in more detail. First, the rules for +dynamic checking. One possible rule would be simply to say that the +exception is raised if you access a variable which has not yet been +elaborated. The trouble with this approach is that it could require +expensive checks on every variable reference. Instead Ada has two +rules which are a little more restrictive, but easier to check, and +easier to state: + +* *Restrictions on calls* + + A subprogram can only be called at elaboration time if its body + has been elaborated. The rules for elaboration given above guarantee + that the spec of the subprogram has been elaborated before the + call, but not the body. If this rule is violated, then the + exception `Program_Error` is raised. + +* *Restrictions on instantiations* + + A generic unit can only be instantiated if the body of the generic + unit has been elaborated. Again, the rules for elaboration given above + guarantee that the spec of the generic unit has been elaborated + before the instantiation, but not the body. If this rule is + violated, then the exception `Program_Error` is raised. + +The idea is that if the body has been elaborated, then any variables +it references must have been elaborated; by checking for the body being +elaborated we guarantee that none of its references causes any +trouble. As we noted above, this is a little too restrictive, because a +subprogram that has no non-local references in its body may in fact be safe +to call. However, it really would be unsafe to rely on this, because +it would mean that the caller was aware of details of the implementation +in the body. This goes against the basic tenets of Ada. + +A plausible implementation can be described as follows. +A Boolean variable is associated with each subprogram +and each generic unit. This variable is initialized to False, and is set to +True at the point body is elaborated. Every call or instantiation checks the +variable, and raises `Program_Error` if the variable is False. + +Note that one might think that it would be good enough to have one Boolean +variable for each package, but that would not deal with cases of trying +to call a body in the same package as the call +that has not been elaborated yet. +Of course a compiler may be able to do enough analysis to optimize away +some of the Boolean variables as unnecessary, and `GNAT` indeed +does such optimizations, but still the easiest conceptual model is to +think of there being one variable per subprogram. + +.. _Controlling_the_Elaboration_Order: + +Controlling the Elaboration Order +================================= + +In the previous section we discussed the rules in Ada which ensure +that `Program_Error` is raised if an incorrect elaboration order is +chosen. This prevents erroneous executions, but we need mechanisms to +specify a correct execution and avoid the exception altogether. +To achieve this, Ada provides a number of features for controlling +the order of elaboration. We discuss these features in this section. + +First, there are several ways of indicating to the compiler that a given +unit has no elaboration problems: + +* *packages that do not require a body* + + A library package that does not require a body does not permit + a body (this rule was introduced in Ada 95). + Thus if we have a such a package, as in: + + .. code-block:: ada + + package Definitions is + generic + type m is new integer; + package Subp is + type a is array (1 .. 10) of m; + type b is array (1 .. 20) of m; + end Subp; + end Definitions; + + A package that |withs| `Definitions` may safely instantiate + `Definitions.Subp` because the compiler can determine that there + definitely is no package body to worry about in this case + +.. index:: pragma Pure + +* *pragma Pure* + + This pragma places sufficient restrictions on a unit to guarantee that + no call to any subprogram in the unit can result in an + elaboration problem. This means that the compiler does not need + to worry about the point of elaboration of such units, and in + particular, does not need to check any calls to any subprograms + in this unit. + +.. index:: pragma Preelaborate + +* *pragma Preelaborate* + + This pragma places slightly less stringent restrictions on a unit than + does pragma Pure, + but these restrictions are still sufficient to ensure that there + are no elaboration problems with any calls to the unit. + +.. index:: pragma Elaborate_Body + +* *pragma Elaborate_Body* + + This pragma requires that the body of a unit be elaborated immediately + after its spec. Suppose a unit `A` has such a pragma, + and unit `B` does + a |with| of unit `A`. Recall that the standard rules require + the spec of unit `A` + to be elaborated before the |withing| unit; given the pragma in + `A`, we also know that the body of `A` + will be elaborated before `B`, so + that calls to `A` are safe and do not need a check. + + Note that, unlike pragma `Pure` and pragma `Preelaborate`, + the use of `Elaborate_Body` does not guarantee that the program is + free of elaboration problems, because it may not be possible + to satisfy the requested elaboration order. + Let's go back to the example with `Unit_1` and `Unit_2`. + If a programmer marks `Unit_1` as `Elaborate_Body`, + and not `Unit_2,` then the order of + elaboration will be:: + + Spec of Unit_2 + Spec of Unit_1 + Body of Unit_1 + Body of Unit_2 + + Now that means that the call to `Func_1` in `Unit_2` + need not be checked, + it must be safe. But the call to `Func_2` in + `Unit_1` may still fail if + `Expression_1` is equal to 1, + and the programmer must still take + responsibility for this not being the case. + + If all units carry a pragma `Elaborate_Body`, then all problems are + eliminated, except for calls entirely within a body, which are + in any case fully under programmer control. However, using the pragma + everywhere is not always possible. + In particular, for our `Unit_1`/`Unit_2` example, if + we marked both of them as having pragma `Elaborate_Body`, then + clearly there would be no possible elaboration order. + +The above pragmas allow a server to guarantee safe use by clients, and +clearly this is the preferable approach. Consequently a good rule +is to mark units as `Pure` or `Preelaborate` if possible, +and if this is not possible, +mark them as `Elaborate_Body` if possible. +As we have seen, there are situations where neither of these +three pragmas can be used. +So we also provide methods for clients to control the +order of elaboration of the servers on which they depend: + +.. index:: pragma Elaborate + +* *pragma Elaborate (unit)* + + This pragma is placed in the context clause, after a |with| clause, + and it requires that the body of the named unit be elaborated before + the unit in which the pragma occurs. The idea is to use this pragma + if the current unit calls at elaboration time, directly or indirectly, + some subprogram in the named unit. + + +.. index:: pragma Elaborate_All + +* *pragma Elaborate_All (unit)* + + This is a stronger version of the Elaborate pragma. Consider the + following example:: + + Unit A |withs| unit B and calls B.Func in elab code + Unit B |withs| unit C, and B.Func calls C.Func + + + Now if we put a pragma `Elaborate (B)` + in unit `A`, this ensures that the + body of `B` is elaborated before the call, but not the + body of `C`, so + the call to `C.Func` could still cause `Program_Error` to + be raised. + + The effect of a pragma `Elaborate_All` is stronger, it requires + not only that the body of the named unit be elaborated before the + unit doing the |with|, but also the bodies of all units that the + named unit uses, following |with| links transitively. For example, + if we put a pragma `Elaborate_All (B)` in unit `A`, + then it requires not only that the body of `B` be elaborated before `A`, + but also the body of `C`, because `B` |withs| `C`. + +We are now in a position to give a usage rule in Ada for avoiding +elaboration problems, at least if dynamic dispatching and access to +subprogram values are not used. We will handle these cases separately +later. + +The rule is simple: + +*If a unit has elaboration code that can directly or +indirectly make a call to a subprogram in a |withed| unit, or instantiate +a generic package in a |withed| unit, +then if the |withed| unit does not have +pragma `Pure` or `Preelaborate`, then the client should have +a pragma `Elaborate_All`for the |withed| unit.** + +By following this rule a client is +assured that calls can be made without risk of an exception. + +For generic subprogram instantiations, the rule can be relaxed to +require only a pragma `Elaborate` since elaborating the body +of a subprogram cannot cause any transitive elaboration (we are +not calling the subprogram in this case, just elaborating its +declaration). + +If this rule is not followed, then a program may be in one of four +states: + +* *No order exists* + + No order of elaboration exists which follows the rules, taking into + account any `Elaborate`, `Elaborate_All`, + or `Elaborate_Body` pragmas. In + this case, an Ada compiler must diagnose the situation at bind + time, and refuse to build an executable program. + +* *One or more orders exist, all incorrect* + + One or more acceptable elaboration orders exist, and all of them + generate an elaboration order problem. In this case, the binder + can build an executable program, but `Program_Error` will be raised + when the program is run. + +* *Several orders exist, some right, some incorrect* + + One or more acceptable elaboration orders exists, and some of them + work, and some do not. The programmer has not controlled + the order of elaboration, so the binder may or may not pick one of + the correct orders, and the program may or may not raise an + exception when it is run. This is the worst case, because it means + that the program may fail when moved to another compiler, or even + another version of the same compiler. + +* *One or more orders exists, all correct* + + One ore more acceptable elaboration orders exist, and all of them + work. In this case the program runs successfully. This state of + affairs can be guaranteed by following the rule we gave above, but + may be true even if the rule is not followed. + +Note that one additional advantage of following our rules on the use +of `Elaborate` and `Elaborate_All` +is that the program continues to stay in the ideal (all orders OK) state +even if maintenance +changes some bodies of some units. Conversely, if a program that does +not follow this rule happens to be safe at some point, this state of affairs +may deteriorate silently as a result of maintenance changes. + +You may have noticed that the above discussion did not mention +the use of `Elaborate_Body`. This was a deliberate omission. If you +|with| an `Elaborate_Body` unit, it still may be the case that +code in the body makes calls to some other unit, so it is still necessary +to use `Elaborate_All` on such units. + + +.. _Controlling_Elaboration_in_GNAT_-_Internal_Calls: + +Controlling Elaboration in GNAT - Internal Calls +================================================ + +In the case of internal calls, i.e., calls within a single package, the +programmer has full control over the order of elaboration, and it is up +to the programmer to elaborate declarations in an appropriate order. For +example writing: + +.. code-block:: ada + + function One return Float; + + Q : Float := One; + + function One return Float is + begin + return 1.0; + end One; + +will obviously raise `Program_Error` at run time, because function +One will be called before its body is elaborated. In this case GNAT will +generate a warning that the call will raise `Program_Error`:: + + 1. procedure y is + 2. function One return Float; + 3. + 4. Q : Float := One; + | + >>> warning: cannot call "One" before body is elaborated + >>> warning: Program_Error will be raised at run time + + 5. + 6. function One return Float is + 7. begin + 8. return 1.0; + 9. end One; + 10. + 11. begin + 12. null; + 13. end; + + +Note that in this particular case, it is likely that the call is safe, because +the function `One` does not access any global variables. +Nevertheless in Ada, we do not want the validity of the check to depend on +the contents of the body (think about the separate compilation case), so this +is still wrong, as we discussed in the previous sections. + +The error is easily corrected by rearranging the declarations so that the +body of `One` appears before the declaration containing the call +(note that in Ada 95 as well as later versions of the Ada standard, +declarations can appear in any order, so there is no restriction that +would prevent this reordering, and if we write: + +.. code-block:: ada + + function One return Float; + + function One return Float is + begin + return 1.0; + end One; + + Q : Float := One; + +then all is well, no warning is generated, and no +`Program_Error` exception +will be raised. +Things are more complicated when a chain of subprograms is executed: + +.. code-block:: ada + + function A return Integer; + function B return Integer; + function C return Integer; + + function B return Integer is begin return A; end; + function C return Integer is begin return B; end; + + X : Integer := C; + + function A return Integer is begin return 1; end; + +Now the call to `C` +at elaboration time in the declaration of `X` is correct, because +the body of `C` is already elaborated, +and the call to `B` within the body of +`C` is correct, but the call +to `A` within the body of `B` is incorrect, because the body +of `A` has not been elaborated, so `Program_Error` +will be raised on the call to `A`. +In this case GNAT will generate a +warning that `Program_Error` may be +raised at the point of the call. Let's look at the warning:: + + 1. procedure x is + 2. function A return Integer; + 3. function B return Integer; + 4. function C return Integer; + 5. + 6. function B return Integer is begin return A; end; + | + >>> warning: call to "A" before body is elaborated may + raise Program_Error + >>> warning: "B" called at line 7 + >>> warning: "C" called at line 9 + + 7. function C return Integer is begin return B; end; + 8. + 9. X : Integer := C; + 10. + 11. function A return Integer is begin return 1; end; + 12. + 13. begin + 14. null; + 15. end; + + +Note that the message here says 'may raise', instead of the direct case, +where the message says 'will be raised'. That's because whether +`A` is +actually called depends in general on run-time flow of control. +For example, if the body of `B` said + +.. code-block:: ada + + function B return Integer is + begin + if some-condition-depending-on-input-data then + return A; + else + return 1; + end if; + end B; + +then we could not know until run time whether the incorrect call to A would +actually occur, so `Program_Error` might +or might not be raised. It is possible for a compiler to +do a better job of analyzing bodies, to +determine whether or not `Program_Error` +might be raised, but it certainly +couldn't do a perfect job (that would require solving the halting problem +and is provably impossible), and because this is a warning anyway, it does +not seem worth the effort to do the analysis. Cases in which it +would be relevant are rare. + +In practice, warnings of either of the forms given +above will usually correspond to +real errors, and should be examined carefully and eliminated. +In the rare case where a warning is bogus, it can be suppressed by any of +the following methods: + +* Compile with the *-gnatws* switch set + +* Suppress `Elaboration_Check` for the called subprogram + +* Use pragma `Warnings_Off` to turn warnings off for the call + +For the internal elaboration check case, +GNAT by default generates the +necessary run-time checks to ensure +that `Program_Error` is raised if any +call fails an elaboration check. Of course this can only happen if a +warning has been issued as described above. The use of pragma +`Suppress (Elaboration_Check)` may (but is not guaranteed to) suppress +some of these checks, meaning that it may be possible (but is not +guaranteed) for a program to be able to call a subprogram whose body +is not yet elaborated, without raising a `Program_Error` exception. + + +.. _Controlling_Elaboration_in_GNAT_-_External_Calls: + +Controlling Elaboration in GNAT - External Calls +================================================ + +The previous section discussed the case in which the execution of a +particular thread of elaboration code occurred entirely within a +single unit. This is the easy case to handle, because a programmer +has direct and total control over the order of elaboration, and +furthermore, checks need only be generated in cases which are rare +and which the compiler can easily detect. +The situation is more complex when separate compilation is taken into account. +Consider the following: + +.. code-block:: ada + + package Math is + function Sqrt (Arg : Float) return Float; + end Math; + + package body Math is + function Sqrt (Arg : Float) return Float is + begin + ... + end Sqrt; + end Math; + + with Math; + package Stuff is + X : Float := Math.Sqrt (0.5); + end Stuff; + + with Stuff; + procedure Main is + begin + ... + end Main; + +where `Main` is the main program. When this program is executed, the +elaboration code must first be executed, and one of the jobs of the +binder is to determine the order in which the units of a program are +to be elaborated. In this case we have four units: the spec and body +of `Math`, +the spec of `Stuff` and the body of `Main`). +In what order should the four separate sections of elaboration code +be executed? + +There are some restrictions in the order of elaboration that the binder +can choose. In particular, if unit U has a |with| +for a package `X`, then you +are assured that the spec of `X` +is elaborated before U , but you are +not assured that the body of `X` +is elaborated before U. +This means that in the above case, the binder is allowed to choose the +order:: + + spec of Math + spec of Stuff + body of Math + body of Main + +but that's not good, because now the call to `Math.Sqrt` +that happens during +the elaboration of the `Stuff` +spec happens before the body of `Math.Sqrt` is +elaborated, and hence causes `Program_Error` exception to be raised. +At first glance, one might say that the binder is misbehaving, because +obviously you want to elaborate the body of something you |with| first, but +that is not a general rule that can be followed in all cases. Consider + +.. code-block:: ada + + package X is ... + + package Y is ... + + with X; + package body Y is ... + + with Y; + package body X is ... + +This is a common arrangement, and, apart from the order of elaboration +problems that might arise in connection with elaboration code, this works fine. +A rule that says that you must first elaborate the body of anything you +|with| cannot work in this case: +the body of `X` |withs| `Y`, +which means you would have to +elaborate the body of `Y` first, but that |withs| `X`, +which means +you have to elaborate the body of `X` first, but ... and we have a +loop that cannot be broken. + +It is true that the binder can in many cases guess an order of elaboration +that is unlikely to cause a `Program_Error` +exception to be raised, and it tries to do so (in the +above example of `Math/Stuff/Spec`, the GNAT binder will +by default +elaborate the body of `Math` right after its spec, so all will be well). + +However, a program that blindly relies on the binder to be helpful can +get into trouble, as we discussed in the previous sections, so GNAT +provides a number of facilities for assisting the programmer in +developing programs that are robust with respect to elaboration order. + + +.. _Default_Behavior_in_GNAT_-_Ensuring_Safety: + +Default Behavior in GNAT - Ensuring Safety +========================================== + +The default behavior in GNAT ensures elaboration safety. In its +default mode GNAT implements the +rule we previously described as the right approach. Let's restate it: + +*If a unit has elaboration code that can directly or indirectly make a +call to a subprogram in a |withed| unit, or instantiate a generic +package in a |withed| unit, then if the |withed| unit +does not have pragma `Pure` or `Preelaborate`, then the client should have an +`Elaborate_All` pragma for the |withed| unit.* + +*In the case of instantiating a generic subprogram, it is always +sufficient to have only an `Elaborate` pragma for the +|withed| unit.* + +By following this rule a client is assured that calls and instantiations +can be made without risk of an exception. + +In this mode GNAT traces all calls that are potentially made from +elaboration code, and puts in any missing implicit `Elaborate` +and `Elaborate_All` pragmas. +The advantage of this approach is that no elaboration problems +are possible if the binder can find an elaboration order that is +consistent with these implicit `Elaborate` and +`Elaborate_All` pragmas. The +disadvantage of this approach is that no such order may exist. + +If the binder does not generate any diagnostics, then it means that it has +found an elaboration order that is guaranteed to be safe. However, the binder +may still be relying on implicitly generated `Elaborate` and +`Elaborate_All` pragmas so portability to other compilers than GNAT is not +guaranteed. + +If it is important to guarantee portability, then the compilations should +use the *-gnatel* +(info messages for elaboration pragmas) switch. This will cause info messages +to be generated indicating the missing `Elaborate` and +`Elaborate_All` pragmas. +Consider the following source program: + +.. code-block:: ada + + with k; + package j is + m : integer := k.r; + end; + +where it is clear that there +should be a pragma `Elaborate_All` +for unit `k`. An implicit pragma will be generated, and it is +likely that the binder will be able to honor it. However, if you want +to port this program to some other Ada compiler than GNAT. +it is safer to include the pragma explicitly in the source. If this +unit is compiled with the *-gnatel* +switch, then the compiler outputs an information message:: + + 1. with k; + 2. package j is + 3. m : integer := k.r; + | + >>> info: call to "r" may raise Program_Error + >>> info: missing pragma Elaborate_All for "k" + + 4. end; + +and these messages can be used as a guide for supplying manually +the missing pragmas. It is usually a bad idea to use this +option during development. That's because it will tell you when +you need to put in a pragma, but cannot tell you when it is time +to take it out. So the use of pragma `Elaborate_All` may lead to +unnecessary dependencies and even false circularities. + +This default mode is more restrictive than the Ada Reference +Manual, and it is possible to construct programs which will compile +using the dynamic model described there, but will run into a +circularity using the safer static model we have described. + +Of course any Ada compiler must be able to operate in a mode +consistent with the requirements of the Ada Reference Manual, +and in particular must have the capability of implementing the +standard dynamic model of elaboration with run-time checks. + +In GNAT, this standard mode can be achieved either by the use of +the *-gnatE* switch on the compiler (*gcc* or +*gnatmake*) command, or by the use of the configuration pragma: + +.. code-block:: ada + + pragma Elaboration_Checks (DYNAMIC); + +Either approach will cause the unit affected to be compiled using the +standard dynamic run-time elaboration checks described in the Ada +Reference Manual. The static model is generally preferable, since it +is clearly safer to rely on compile and link time checks rather than +run-time checks. However, in the case of legacy code, it may be +difficult to meet the requirements of the static model. This +issue is further discussed in +:ref:`What_to_Do_If_the_Default_Elaboration_Behavior_Fails`. + +Note that the static model provides a strict subset of the allowed +behavior and programs of the Ada Reference Manual, so if you do +adhere to the static model and no circularities exist, +then you are assured that your program will +work using the dynamic model, providing that you remove any +pragma Elaborate statements from the source. + + +.. _Treatment_of_Pragma_Elaborate: + +Treatment of Pragma Elaborate +============================= + +.. index:: Pragma Elaborate + +The use of `pragma Elaborate` +should generally be avoided in Ada 95 and Ada 2005 programs, +since there is no guarantee that transitive calls +will be properly handled. Indeed at one point, this pragma was placed +in Annex J (Obsolescent Features), on the grounds that it is never useful. + +Now that's a bit restrictive. In practice, the case in which +`pragma Elaborate` is useful is when the caller knows that there +are no transitive calls, or that the called unit contains all necessary +transitive `pragma Elaborate` statements, and legacy code often +contains such uses. + +Strictly speaking the static mode in GNAT should ignore such pragmas, +since there is no assurance at compile time that the necessary safety +conditions are met. In practice, this would cause GNAT to be incompatible +with correctly written Ada 83 code that had all necessary +`pragma Elaborate` statements in place. Consequently, we made the +decision that GNAT in its default mode will believe that if it encounters +a `pragma Elaborate` then the programmer knows what they are doing, +and it will trust that no elaboration errors can occur. + +The result of this decision is two-fold. First to be safe using the +static mode, you should remove all `pragma Elaborate` statements. +Second, when fixing circularities in existing code, you can selectively +use `pragma Elaborate` statements to convince the static mode of +GNAT that it need not generate an implicit `pragma Elaborate_All` +statement. + +When using the static mode with *-gnatwl*, any use of +`pragma Elaborate` will generate a warning about possible +problems. + + +.. _Elaboration_Issues_for_Library_Tasks: + +Elaboration Issues for Library Tasks +==================================== + +.. index:: Library tasks, elaboration issues + +.. index:: Elaboration of library tasks + +In this section we examine special elaboration issues that arise for +programs that declare library level tasks. + +Generally the model of execution of an Ada program is that all units are +elaborated, and then execution of the program starts. However, the +declaration of library tasks definitely does not fit this model. The +reason for this is that library tasks start as soon as they are declared +(more precisely, as soon as the statement part of the enclosing package +body is reached), that is to say before elaboration +of the program is complete. This means that if such a task calls a +subprogram, or an entry in another task, the callee may or may not be +elaborated yet, and in the standard +Reference Manual model of dynamic elaboration checks, you can even +get timing dependent Program_Error exceptions, since there can be +a race between the elaboration code and the task code. + +The static model of elaboration in GNAT seeks to avoid all such +dynamic behavior, by being conservative, and the conservative +approach in this particular case is to assume that all the code +in a task body is potentially executed at elaboration time if +a task is declared at the library level. + +This can definitely result in unexpected circularities. Consider +the following example + +.. code-block:: ada + + package Decls is + task Lib_Task is + entry Start; + end Lib_Task; + + type My_Int is new Integer; + + function Ident (M : My_Int) return My_Int; + end Decls; + + with Utils; + package body Decls is + task body Lib_Task is + begin + accept Start; + Utils.Put_Val (2); + end Lib_Task; + + function Ident (M : My_Int) return My_Int is + begin + return M; + end Ident; + end Decls; + + with Decls; + package Utils is + procedure Put_Val (Arg : Decls.My_Int); + end Utils; + + with Text_IO; + package body Utils is + procedure Put_Val (Arg : Decls.My_Int) is + begin + Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); + end Put_Val; + end Utils; + + with Decls; + procedure Main is + begin + Decls.Lib_Task.Start; + end; + +If the above example is compiled in the default static elaboration +mode, then a circularity occurs. The circularity comes from the call +`Utils.Put_Val` in the task body of `Decls.Lib_Task`. Since +this call occurs in elaboration code, we need an implicit pragma +`Elaborate_All` for `Utils`. This means that not only must +the spec and body of `Utils` be elaborated before the body +of `Decls`, but also the spec and body of any unit that is +|withed| by the body of `Utils` must also be elaborated before +the body of `Decls`. This is the transitive implication of +pragma `Elaborate_All` and it makes sense, because in general +the body of `Put_Val` might have a call to something in a +|withed| unit. + +In this case, the body of Utils (actually its spec) |withs| +`Decls`. Unfortunately this means that the body of `Decls` +must be elaborated before itself, in case there is a call from the +body of `Utils`. + +Here is the exact chain of events we are worrying about: + +* In the body of `Decls` a call is made from within the body of a library + task to a subprogram in the package `Utils`. Since this call may + occur at elaboration time (given that the task is activated at elaboration + time), we have to assume the worst, i.e., that the + call does happen at elaboration time. + +* This means that the body and spec of `Util` must be elaborated before + the body of `Decls` so that this call does not cause an access before + elaboration. + +* Within the body of `Util`, specifically within the body of + `Util.Put_Val` there may be calls to any unit |withed| + by this package. + +* One such |withed| package is package `Decls`, so there + might be a call to a subprogram in `Decls` in `Put_Val`. + In fact there is such a call in this example, but we would have to + assume that there was such a call even if it were not there, since + we are not supposed to write the body of `Decls` knowing what + is in the body of `Utils`; certainly in the case of the + static elaboration model, the compiler does not know what is in + other bodies and must assume the worst. + +* This means that the spec and body of `Decls` must also be + elaborated before we elaborate the unit containing the call, but + that unit is `Decls`! This means that the body of `Decls` + must be elaborated before itself, and that's a circularity. + +Indeed, if you add an explicit pragma `Elaborate_All` for `Utils` in +the body of `Decls` you will get a true Ada Reference Manual +circularity that makes the program illegal. + +In practice, we have found that problems with the static model of +elaboration in existing code often arise from library tasks, so +we must address this particular situation. + +Note that if we compile and run the program above, using the dynamic model of +elaboration (that is to say use the *-gnatE* switch), +then it compiles, binds, +links, and runs, printing the expected result of 2. Therefore in some sense +the circularity here is only apparent, and we need to capture +the properties of this program that distinguish it from other library-level +tasks that have real elaboration problems. + +We have four possible answers to this question: + + +* Use the dynamic model of elaboration. + + If we use the *-gnatE* switch, then as noted above, the program works. + Why is this? If we examine the task body, it is apparent that the task cannot + proceed past the + `accept` statement until after elaboration has been completed, because + the corresponding entry call comes from the main program, not earlier. + This is why the dynamic model works here. But that's really giving + up on a precise analysis, and we prefer to take this approach only if we cannot + solve the + problem in any other manner. So let us examine two ways to reorganize + the program to avoid the potential elaboration problem. + +* Split library tasks into separate packages. + + Write separate packages, so that library tasks are isolated from + other declarations as much as possible. Let us look at a variation on + the above program. + + + .. code-block:: ada + + package Decls1 is + task Lib_Task is + entry Start; + end Lib_Task; + end Decls1; + + with Utils; + package body Decls1 is + task body Lib_Task is + begin + accept Start; + Utils.Put_Val (2); + end Lib_Task; + end Decls1; + + package Decls2 is + type My_Int is new Integer; + function Ident (M : My_Int) return My_Int; + end Decls2; + + with Utils; + package body Decls2 is + function Ident (M : My_Int) return My_Int is + begin + return M; + end Ident; + end Decls2; + + with Decls2; + package Utils is + procedure Put_Val (Arg : Decls2.My_Int); + end Utils; + + with Text_IO; + package body Utils is + procedure Put_Val (Arg : Decls2.My_Int) is + begin + Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); + end Put_Val; + end Utils; + + with Decls1; + procedure Main is + begin + Decls1.Lib_Task.Start; + end; + + + All we have done is to split `Decls` into two packages, one + containing the library task, and one containing everything else. Now + there is no cycle, and the program compiles, binds, links and executes + using the default static model of elaboration. + +* Declare separate task types. + + A significant part of the problem arises because of the use of the + single task declaration form. This means that the elaboration of + the task type, and the elaboration of the task itself (i.e., the + creation of the task) happen at the same time. A good rule + of style in Ada is to always create explicit task types. By + following the additional step of placing task objects in separate + packages from the task type declaration, many elaboration problems + are avoided. Here is another modified example of the example program: + + .. code-block:: ada + + package Decls is + task type Lib_Task_Type is + entry Start; + end Lib_Task_Type; + + type My_Int is new Integer; + + function Ident (M : My_Int) return My_Int; + end Decls; + + with Utils; + package body Decls is + task body Lib_Task_Type is + begin + accept Start; + Utils.Put_Val (2); + end Lib_Task_Type; + + function Ident (M : My_Int) return My_Int is + begin + return M; + end Ident; + end Decls; + + with Decls; + package Utils is + procedure Put_Val (Arg : Decls.My_Int); + end Utils; + + with Text_IO; + package body Utils is + procedure Put_Val (Arg : Decls.My_Int) is + begin + Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); + end Put_Val; + end Utils; + + with Decls; + package Declst is + Lib_Task : Decls.Lib_Task_Type; + end Declst; + + with Declst; + procedure Main is + begin + Declst.Lib_Task.Start; + end; + + + What we have done here is to replace the `task` declaration in + package `Decls` with a `task type` declaration. Then we + introduce a separate package `Declst` to contain the actual + task object. This separates the elaboration issues for + the `task type` + declaration, which causes no trouble, from the elaboration issues + of the task object, which is also unproblematic, since it is now independent + of the elaboration of `Utils`. + This separation of concerns also corresponds to + a generally sound engineering principle of separating declarations + from instances. This version of the program also compiles, binds, links, + and executes, generating the expected output. + +.. index:: No_Entry_Calls_In_Elaboration_Code restriction + +* Use No_Entry_Calls_In_Elaboration_Code restriction. + + The previous two approaches described how a program can be restructured + to avoid the special problems caused by library task bodies. in practice, + however, such restructuring may be difficult to apply to existing legacy code, + so we must consider solutions that do not require massive rewriting. + + Let us consider more carefully why our original sample program works + under the dynamic model of elaboration. The reason is that the code + in the task body blocks immediately on the `accept` + statement. Now of course there is nothing to prohibit elaboration + code from making entry calls (for example from another library level task), + so we cannot tell in isolation that + the task will not execute the accept statement during elaboration. + + However, in practice it is very unusual to see elaboration code + make any entry calls, and the pattern of tasks starting + at elaboration time and then immediately blocking on `accept` or + `select` statements is very common. What this means is that + the compiler is being too pessimistic when it analyzes the + whole package body as though it might be executed at elaboration + time. + + If we know that the elaboration code contains no entry calls, (a very safe + assumption most of the time, that could almost be made the default + behavior), then we can compile all units of the program under control + of the following configuration pragma: + + .. code-block:: ada + + pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); + + This pragma can be placed in the :file:`gnat.adc` file in the usual + manner. If we take our original unmodified program and compile it + in the presence of a :file:`gnat.adc` containing the above pragma, + then once again, we can compile, bind, link, and execute, obtaining + the expected result. In the presence of this pragma, the compiler does + not trace calls in a task body, that appear after the first `accept` + or `select` statement, and therefore does not report a potential + circularity in the original program. + + The compiler will check to the extent it can that the above + restriction is not violated, but it is not always possible to do a + complete check at compile time, so it is important to use this + pragma only if the stated restriction is in fact met, that is to say + no task receives an entry call before elaboration of all units is completed. + + +.. _Mixing_Elaboration_Models: + +Mixing Elaboration Models +========================= + +So far, we have assumed that the entire program is either compiled +using the dynamic model or static model, ensuring consistency. It +is possible to mix the two models, but rules have to be followed +if this mixing is done to ensure that elaboration checks are not +omitted. + +The basic rule is that +**a unit compiled with the static model cannot +be |withed| by a unit compiled with the dynamic model**. +The reason for this is that in the static model, a unit assumes that +its clients guarantee to use (the equivalent of) pragma +`Elaborate_All` so that no elaboration checks are required +in inner subprograms, and this assumption is violated if the +client is compiled with dynamic checks. + +The precise rule is as follows. A unit that is compiled with dynamic +checks can only |with| a unit that meets at least one of the +following criteria: + + +* The |withed| unit is itself compiled with dynamic elaboration + checks (that is with the *-gnatE* switch. + +* The |withed| unit is an internal GNAT implementation unit from + the System, Interfaces, Ada, or GNAT hierarchies. + +* The |withed| unit has pragma Preelaborate or pragma Pure. + +* The |withing| unit (that is the client) has an explicit pragma + `Elaborate_All` for the |withed| unit. + + +If this rule is violated, that is if a unit with dynamic elaboration +checks |withs| a unit that does not meet one of the above four +criteria, then the binder (`gnatbind`) will issue a warning +similar to that in the following example:: + + warning: "x.ads" has dynamic elaboration checks and with's + warning: "y.ads" which has static elaboration checks + +These warnings indicate that the rule has been violated, and that as a result +elaboration checks may be missed in the resulting executable file. +This warning may be suppressed using the *-ws* binder switch +in the usual manner. + +One useful application of this mixing rule is in the case of a subsystem +which does not itself |with| units from the remainder of the +application. In this case, the entire subsystem can be compiled with +dynamic checks to resolve a circularity in the subsystem, while +allowing the main application that uses this subsystem to be compiled +using the more reliable default static model. + + +.. _What_to_Do_If_the_Default_Elaboration_Behavior_Fails: + +What to Do If the Default Elaboration Behavior Fails +==================================================== + +If the binder cannot find an acceptable order, it outputs detailed +diagnostics. For example:: + + error: elaboration circularity detected + info: "proc (body)" must be elaborated before "pack (body)" + info: reason: Elaborate_All probably needed in unit "pack (body)" + info: recompile "pack (body)" with -gnatel + info: for full details + info: "proc (body)" + info: is needed by its spec: + info: "proc (spec)" + info: which is withed by: + info: "pack (body)" + info: "pack (body)" must be elaborated before "proc (body)" + info: reason: pragma Elaborate in unit "proc (body)" + +In this case we have a cycle that the binder cannot break. On the one +hand, there is an explicit pragma Elaborate in `proc` for +`pack`. This means that the body of `pack` must be elaborated +before the body of `proc`. On the other hand, there is elaboration +code in `pack` that calls a subprogram in `proc`. This means +that for maximum safety, there should really be a pragma +Elaborate_All in `pack` for `proc` which would require that +the body of `proc` be elaborated before the body of +`pack`. Clearly both requirements cannot be satisfied. +Faced with a circularity of this kind, you have three different options. + + +* *Fix the program* + + The most desirable option from the point of view of long-term maintenance + is to rearrange the program so that the elaboration problems are avoided. + One useful technique is to place the elaboration code into separate + child packages. Another is to move some of the initialization code to + explicitly called subprograms, where the program controls the order + of initialization explicitly. Although this is the most desirable option, + it may be impractical and involve too much modification, especially in + the case of complex legacy code. + +* *Perform dynamic checks* + + If the compilations are done using the *-gnatE* + (dynamic elaboration check) switch, then GNAT behaves in a quite different + manner. Dynamic checks are generated for all calls that could possibly result + in raising an exception. With this switch, the compiler does not generate + implicit `Elaborate` or `Elaborate_All` pragmas. The behavior then is + exactly as specified in the :title:`Ada Reference Manual`. + The binder will generate + an executable program that may or may not raise `Program_Error`, and then + it is the programmer's job to ensure that it does not raise an exception. Note + that it is important to compile all units with the switch, it cannot be used + selectively. + +* *Suppress checks* + + The drawback of dynamic checks is that they generate a + significant overhead at run time, both in space and time. If you + are absolutely sure that your program cannot raise any elaboration + exceptions, and you still want to use the dynamic elaboration model, + then you can use the configuration pragma + `Suppress (Elaboration_Check)` to suppress all such checks. For + example this pragma could be placed in the :file:`gnat.adc` file. + +* *Suppress checks selectively* + + When you know that certain calls or instantiations in elaboration code cannot + possibly lead to an elaboration error, and the binder nevertheless complains + about implicit `Elaborate` and `Elaborate_All` pragmas that lead to + elaboration circularities, it is possible to remove those warnings locally and + obtain a program that will bind. Clearly this can be unsafe, and it is the + responsibility of the programmer to make sure that the resulting program has no + elaboration anomalies. The pragma `Suppress (Elaboration_Check)` can be + used with different granularity to suppress warnings and break elaboration + circularities: + + * Place the pragma that names the called subprogram in the declarative part + that contains the call. + + * Place the pragma in the declarative part, without naming an entity. This + disables warnings on all calls in the corresponding declarative region. + + * Place the pragma in the package spec that declares the called subprogram, + and name the subprogram. This disables warnings on all elaboration calls to + that subprogram. + + * Place the pragma in the package spec that declares the called subprogram, + without naming any entity. This disables warnings on all elaboration calls to + all subprograms declared in this spec. + + * Use Pragma Elaborate. + + As previously described in section :ref:`Treatment_of_Pragma_Elaborate`, + GNAT in static mode assumes that a `pragma` Elaborate indicates correctly + that no elaboration checks are required on calls to the designated unit. + There may be cases in which the caller knows that no transitive calls + can occur, so that a `pragma Elaborate` will be sufficient in a + case where `pragma Elaborate_All` would cause a circularity. + + These five cases are listed in order of decreasing safety, and therefore + require increasing programmer care in their application. Consider the + following program: + + .. code-block:: ada + + package Pack1 is + function F1 return Integer; + X1 : Integer; + end Pack1; + + package Pack2 is + function F2 return Integer; + function Pure (x : integer) return integer; + -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) + -- pragma Suppress (Elaboration_Check); -- (4) + end Pack2; + + with Pack2; + package body Pack1 is + function F1 return Integer is + begin + return 100; + end F1; + Val : integer := Pack2.Pure (11); -- Elab. call (1) + begin + declare + -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) + -- pragma Suppress(Elaboration_Check); -- (2) + begin + X1 := Pack2.F2 + 1; -- Elab. call (2) + end; + end Pack1; + + with Pack1; + package body Pack2 is + function F2 return Integer is + begin + return Pack1.F1; + end F2; + function Pure (x : integer) return integer is + begin + return x ** 3 - 3 * x; + end; + end Pack2; + + with Pack1, Ada.Text_IO; + procedure Proc3 is + begin + Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 + end Proc3; + + In the absence of any pragmas, an attempt to bind this program produces + the following diagnostics:: + + error: elaboration circularity detected + info: "pack1 (body)" must be elaborated before "pack1 (body)" + info: reason: Elaborate_All probably needed in unit "pack1 (body)" + info: recompile "pack1 (body)" with -gnatel for full details + info: "pack1 (body)" + info: must be elaborated along with its spec: + info: "pack1 (spec)" + info: which is withed by: + info: "pack2 (body)" + info: which must be elaborated along with its spec: + info: "pack2 (spec)" + info: which is withed by: + info: "pack1 (body)" + + The sources of the circularity are the two calls to `Pack2.Pure` and + `Pack2.F2` in the body of `Pack1`. We can see that the call to + F2 is safe, even though F2 calls F1, because the call appears after the + elaboration of the body of F1. Therefore the pragma (1) is safe, and will + remove the warning on the call. It is also possible to use pragma (2) + because there are no other potentially unsafe calls in the block. + + The call to `Pure` is safe because this function does not depend on the + state of `Pack2`. Therefore any call to this function is safe, and it + is correct to place pragma (3) in the corresponding package spec. + + Finally, we could place pragma (4) in the spec of `Pack2` to disable + warnings on all calls to functions declared therein. Note that this is not + necessarily safe, and requires more detailed examination of the subprogram + bodies involved. In particular, a call to `F2` requires that `F1` + be already elaborated. + +It is hard to generalize on which of these four approaches should be +taken. Obviously if it is possible to fix the program so that the default +treatment works, this is preferable, but this may not always be practical. +It is certainly simple enough to use *-gnatE* +but the danger in this case is that, even if the GNAT binder +finds a correct elaboration order, it may not always do so, +and certainly a binder from another Ada compiler might not. A +combination of testing and analysis (for which the +information messages generated with the *-gnatel* +switch can be useful) must be used to ensure that the program is free +of errors. One switch that is useful in this testing is the +*-p (pessimistic elaboration order)* switch for `gnatbind`. +Normally the binder tries to find an order that has the best chance +of avoiding elaboration problems. However, if this switch is used, the binder +plays a devil's advocate role, and tries to choose the order that +has the best chance of failing. If your program works even with this +switch, then it has a better chance of being error free, but this is still +not a guarantee. + +For an example of this approach in action, consider the C-tests (executable +tests) from the ACATS suite. If these are compiled and run with the default +treatment, then all but one of them succeed without generating any error +diagnostics from the binder. However, there is one test that fails, and +this is not surprising, because the whole point of this test is to ensure +that the compiler can handle cases where it is impossible to determine +a correct order statically, and it checks that an exception is indeed +raised at run time. + +This one test must be compiled and run using the *-gnatE* +switch, and then it passes. Alternatively, the entire suite can +be run using this switch. It is never wrong to run with the dynamic +elaboration switch if your code is correct, and we assume that the +C-tests are indeed correct (it is less efficient, but efficiency is +not a factor in running the ACATS tests.) + + +.. _Elaboration_for_Indirect_Calls: + +Elaboration for Indirect Calls +============================== + +.. index:: Dispatching calls +.. index:: Indirect calls + +In rare cases, the static elaboration model fails to prevent +dispatching calls to not-yet-elaborated subprograms. In such cases, we +fall back to run-time checks; premature calls to any primitive +operation of a tagged type before the body of the operation has been +elaborated will raise `Program_Error`. + +Access-to-subprogram types, however, are handled conservatively, and +do not require run-time checks. This was not true in earlier versions +of the compiler; you can use the *-gnatd.U* debug switch to +revert to the old behavior if the new conservative behavior causes +elaboration cycles. Here, 'conservative' means that if you do +`P'Access` during elaboration, the compiler will assume that you +might call `P` indirectly during elaboration, so it adds an +implicit `pragma Elaborate_All` on the library unit containing +`P`. The *-gnatd.U* switch is safe if you know there are +no such calls. If the program worked before, it will continue to work +with *-gnatd.U*. But beware that code modifications such as +adding an indirect call can cause erroneous behavior in the presence +of *-gnatd.U*. + + +.. _Summary_of_Procedures_for_Elaboration_Control: + +Summary of Procedures for Elaboration Control +============================================= + +.. index:: Elaboration control + +First, compile your program with the default options, using none of +the special elaboration control switches. If the binder successfully +binds your program, then you can be confident that, apart from issues +raised by the use of access-to-subprogram types and dynamic dispatching, +the program is free of elaboration errors. If it is important that the +program be portable to other compilers than GNAT, then use the +*-gnatel* +switch to generate messages about missing `Elaborate` or +`Elaborate_All` pragmas, and supply the missing pragmas. + +If the program fails to bind using the default static elaboration +handling, then you can fix the program to eliminate the binder +message, or recompile the entire program with the +*-gnatE* switch to generate dynamic elaboration checks, +and, if you are sure there really are no elaboration problems, +use a global pragma `Suppress (Elaboration_Check)`. + + +.. _Other_Elaboration_Order_Considerations: + +Other Elaboration Order Considerations +====================================== + +This section has been entirely concerned with the issue of finding a valid +elaboration order, as defined by the Ada Reference Manual. In a case +where several elaboration orders are valid, the task is to find one +of the possible valid elaboration orders (and the static model in GNAT +will ensure that this is achieved). + +The purpose of the elaboration rules in the Ada Reference Manual is to +make sure that no entity is accessed before it has been elaborated. For +a subprogram, this means that the spec and body must have been elaborated +before the subprogram is called. For an object, this means that the object +must have been elaborated before its value is read or written. A violation +of either of these two requirements is an access before elaboration order, +and this section has been all about avoiding such errors. + +In the case where more than one order of elaboration is possible, in the +sense that access before elaboration errors are avoided, then any one of +the orders is 'correct' in the sense that it meets the requirements of +the Ada Reference Manual, and no such error occurs. + +However, it may be the case for a given program, that there are +constraints on the order of elaboration that come not from consideration +of avoiding elaboration errors, but rather from extra-lingual logic +requirements. Consider this example: + +.. code-block:: ada + + with Init_Constants; + package Constants is + X : Integer := 0; + Y : Integer := 0; + end Constants; + + package Init_Constants is + procedure P; --* require a body* + end Init_Constants; + + with Constants; + package body Init_Constants is + procedure P is begin null; end; + begin + Constants.X := 3; + Constants.Y := 4; + end Init_Constants; + + with Constants; + package Calc is + Z : Integer := Constants.X + Constants.Y; + end Calc; + + with Calc; + with Text_IO; use Text_IO; + procedure Main is + begin + Put_Line (Calc.Z'Img); + end Main; + +In this example, there is more than one valid order of elaboration. For +example both the following are correct orders:: + + Init_Constants spec + Constants spec + Calc spec + Init_Constants body + Main body + +and + +:: + + Init_Constants spec + Init_Constants body + Constants spec + Calc spec + Main body + +There is no language rule to prefer one or the other, both are correct +from an order of elaboration point of view. But the programmatic effects +of the two orders are very different. In the first, the elaboration routine +of `Calc` initializes `Z` to zero, and then the main program +runs with this value of zero. But in the second order, the elaboration +routine of `Calc` runs after the body of Init_Constants has set +`X` and `Y` and thus `Z` is set to 7 before `Main` runs. + +One could perhaps by applying pretty clever non-artificial intelligence +to the situation guess that it is more likely that the second order of +elaboration is the one desired, but there is no formal linguistic reason +to prefer one over the other. In fact in this particular case, GNAT will +prefer the second order, because of the rule that bodies are elaborated +as soon as possible, but it's just luck that this is what was wanted +(if indeed the second order was preferred). + +If the program cares about the order of elaboration routines in a case like +this, it is important to specify the order required. In this particular +case, that could have been achieved by adding to the spec of Calc: + +.. code-block:: ada + + pragma Elaborate_All (Constants); + +which requires that the body (if any) and spec of `Constants`, +as well as the body and spec of any unit |withed| by +`Constants` be elaborated before `Calc` is elaborated. + +Clearly no automatic method can always guess which alternative you require, +and if you are working with legacy code that had constraints of this kind +which were not properly specified by adding `Elaborate` or +`Elaborate_All` pragmas, then indeed it is possible that two different +compilers can choose different orders. + +However, GNAT does attempt to diagnose the common situation where there +are uninitialized variables in the visible part of a package spec, and the +corresponding package body has an elaboration block that directly or +indirectly initialized one or more of these variables. This is the situation +in which a pragma Elaborate_Body is usually desirable, and GNAT will generate +a warning that suggests this addition if it detects this situation. + +The `gnatbind` *-p* switch may be useful in smoking +out problems. This switch causes bodies to be elaborated as late as possible +instead of as early as possible. In the example above, it would have forced +the choice of the first elaboration order. If you get different results +when using this switch, and particularly if one set of results is right, +and one is wrong as far as you are concerned, it shows that you have some +missing `Elaborate` pragmas. For the example above, we have the +following output: + +.. code-block:: sh + + $ gnatmake -f -q main + $ main + 7 + $ gnatmake -f -q main -bargs -p + $ main + 0 + +It is of course quite unlikely that both these results are correct, so +it is up to you in a case like this to investigate the source of the +difference, by looking at the two elaboration orders that are chosen, +and figuring out which is correct, and then adding the necessary +`Elaborate` or `Elaborate_All` pragmas to ensure the desired order. + + +.. _Determining_the_Chosen_Elaboration_Order: + +Determining the Chosen Elaboration Order +======================================== + +To see the elaboration order that the binder chooses, you can look at +the last part of the file:`b~xxx.adb` binder output file. Here is an example:: + + System.Soft_Links'Elab_Body; + E14 := True; + System.Secondary_Stack'Elab_Body; + E18 := True; + System.Exception_Table'Elab_Body; + E24 := True; + Ada.Io_Exceptions'Elab_Spec; + E67 := True; + Ada.Tags'Elab_Spec; + Ada.Streams'Elab_Spec; + E43 := True; + Interfaces.C'Elab_Spec; + E69 := True; + System.Finalization_Root'Elab_Spec; + E60 := True; + System.Os_Lib'Elab_Body; + E71 := True; + System.Finalization_Implementation'Elab_Spec; + System.Finalization_Implementation'Elab_Body; + E62 := True; + Ada.Finalization'Elab_Spec; + E58 := True; + Ada.Finalization.List_Controller'Elab_Spec; + E76 := True; + System.File_Control_Block'Elab_Spec; + E74 := True; + System.File_Io'Elab_Body; + E56 := True; + Ada.Tags'Elab_Body; + E45 := True; + Ada.Text_Io'Elab_Spec; + Ada.Text_Io'Elab_Body; + E07 := True; + +Here Elab_Spec elaborates the spec +and Elab_Body elaborates the body. The assignments to the :samp:`E{xx}` flags +flag that the corresponding body is now elaborated. + +You can also ask the binder to generate a more +readable list of the elaboration order using the +`-l` switch when invoking the binder. Here is +an example of the output generated by this switch:: + + ada (spec) + interfaces (spec) + system (spec) + system.case_util (spec) + system.case_util (body) + system.concat_2 (spec) + system.concat_2 (body) + system.concat_3 (spec) + system.concat_3 (body) + system.htable (spec) + system.parameters (spec) + system.parameters (body) + system.crtl (spec) + interfaces.c_streams (spec) + interfaces.c_streams (body) + system.restrictions (spec) + system.restrictions (body) + system.standard_library (spec) + system.exceptions (spec) + system.exceptions (body) + system.storage_elements (spec) + system.storage_elements (body) + system.secondary_stack (spec) + system.stack_checking (spec) + system.stack_checking (body) + system.string_hash (spec) + system.string_hash (body) + system.htable (body) + system.strings (spec) + system.strings (body) + system.traceback (spec) + system.traceback (body) + system.traceback_entries (spec) + system.traceback_entries (body) + ada.exceptions (spec) + ada.exceptions.last_chance_handler (spec) + system.soft_links (spec) + system.soft_links (body) + ada.exceptions.last_chance_handler (body) + system.secondary_stack (body) + system.exception_table (spec) + system.exception_table (body) + ada.io_exceptions (spec) + ada.tags (spec) + ada.streams (spec) + interfaces.c (spec) + interfaces.c (body) + system.finalization_root (spec) + system.finalization_root (body) + system.memory (spec) + system.memory (body) + system.standard_library (body) + system.os_lib (spec) + system.os_lib (body) + system.unsigned_types (spec) + system.stream_attributes (spec) + system.stream_attributes (body) + system.finalization_implementation (spec) + system.finalization_implementation (body) + ada.finalization (spec) + ada.finalization (body) + ada.finalization.list_controller (spec) + ada.finalization.list_controller (body) + system.file_control_block (spec) + system.file_io (spec) + system.file_io (body) + system.val_uns (spec) + system.val_util (spec) + system.val_util (body) + system.val_uns (body) + system.wch_con (spec) + system.wch_con (body) + system.wch_cnv (spec) + system.wch_jis (spec) + system.wch_jis (body) + system.wch_cnv (body) + system.wch_stw (spec) + system.wch_stw (body) + ada.tags (body) + ada.exceptions (body) + ada.text_io (spec) + ada.text_io (body) + text_io (spec) + gdbstr (body) diff --git a/gcc/ada/doc/gnat_ugn/example_of_binder_output.rst b/gcc/ada/doc/gnat_ugn/example_of_binder_output.rst new file mode 100644 index 00000000000..b2c34c0b820 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/example_of_binder_output.rst @@ -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). + diff --git a/gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst b/gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst new file mode 100644 index 00000000000..fcfb07875e4 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst @@ -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. + diff --git a/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst new file mode 100644 index 00000000000..9e332d9d076 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst @@ -0,0 +1,4190 @@ +.. |with| replace:: *with* +.. |withs| replace:: *with*\ s +.. |withed| replace:: *with*\ ed +.. |withing| replace:: *with*\ ing + +.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit + + +.. _GNAT_and_Program_Execution: + +************************** +GNAT and Program Execution +************************** + +This chapter covers several topics: + +* `Running and Debugging Ada Programs`_ +* `Code Coverage and Profiling`_ +* `Improving Performance`_ +* `Overflow Check Handling in GNAT`_ +* `Performing Dimensionality Analysis in GNAT`_ +* `Stack Related Facilities`_ +* `Memory Management Issues`_ + +.. _Running_and_Debugging_Ada_Programs: + +Running and Debugging Ada Programs +================================== + +.. index:: Debugging + +This section discusses how to debug Ada programs. + +An incorrect Ada program may be handled in three ways by the GNAT compiler: + +* The illegality may be a violation of the static semantics of Ada. In + that case GNAT diagnoses the constructs in the program that are illegal. + It is then a straightforward matter for the user to modify those parts of + the program. + +* The illegality may be a violation of the dynamic semantics of Ada. In + that case the program compiles and executes, but may generate incorrect + results, or may terminate abnormally with some exception. + +* When presented with a program that contains convoluted errors, GNAT + itself may terminate abnormally without providing full diagnostics on + the incorrect user program. + +.. index:: Debugger + +.. index:: ! gdb + +.. _The_GNAT_Debugger_GDB: + +The GNAT Debugger GDB +--------------------- + +`GDB` is a general purpose, platform-independent debugger that +can be used to debug mixed-language programs compiled with *gcc*, +and in particular is capable of debugging Ada programs compiled with +GNAT. The latest versions of `GDB` are Ada-aware and can handle +complex Ada data structures. + +See :title:`Debugging with GDB`, +for full details on the usage of `GDB`, including a section on +its usage on programs. This manual should be consulted for full +details. The section that follows is a brief introduction to the +philosophy and use of `GDB`. + +When GNAT programs are compiled, the compiler optionally writes debugging +information into the generated object file, including information on +line numbers, and on declared types and variables. This information is +separate from the generated code. It makes the object files considerably +larger, but it does not add to the size of the actual executable that +will be loaded into memory, and has no impact on run-time performance. The +generation of debug information is triggered by the use of the +-g switch in the *gcc* or *gnatmake* command +used to carry out the compilations. It is important to emphasize that +the use of these options does not change the generated code. + +The debugging information is written in standard system formats that +are used by many tools, including debuggers and profilers. The format +of the information is typically designed to describe C types and +semantics, but GNAT implements a translation scheme which allows full +details about Ada types and variables to be encoded into these +standard C formats. Details of this encoding scheme may be found in +the file exp_dbug.ads in the GNAT source distribution. However, the +details of this encoding are, in general, of no interest to a user, +since `GDB` automatically performs the necessary decoding. + +When a program is bound and linked, the debugging information is +collected from the object files, and stored in the executable image of +the program. Again, this process significantly increases the size of +the generated executable file, but it does not increase the size of +the executable program itself. Furthermore, if this program is run in +the normal manner, it runs exactly as if the debug information were +not present, and takes no more actual memory. + +However, if the program is run under control of `GDB`, the +debugger is activated. The image of the program is loaded, at which +point it is ready to run. If a run command is given, then the program +will run exactly as it would have if `GDB` were not present. This +is a crucial part of the `GDB` design philosophy. `GDB` is +entirely non-intrusive until a breakpoint is encountered. If no +breakpoint is ever hit, the program will run exactly as it would if no +debugger were present. When a breakpoint is hit, `GDB` accesses +the debugging information and can respond to user commands to inspect +variables, and more generally to report on the state of execution. + +.. _Running_GDB: + +Running GDB +----------- + +This section describes how to initiate the debugger. + +The debugger can be launched from a `GPS` menu or +directly from the command line. The description below covers the latter use. +All the commands shown can be used in the `GPS` debug console window, +but there are usually more GUI-based ways to achieve the same effect. + +The command to run `GDB` is + + :: + + $ gdb program + +where `program` is the name of the executable file. This +activates the debugger and results in a prompt for debugger commands. +The simplest command is simply `run`, which causes the program to run +exactly as if the debugger were not present. The following section +describes some of the additional commands that can be given to `GDB`. + + +.. _Introduction_to_GDB_Commands: + +Introduction to GDB Commands +---------------------------- + +`GDB` contains a large repertoire of commands. +See :title:`Debugging with GDB` for extensive documentation on the use +of these commands, together with examples of their use. Furthermore, +the command *help* invoked from within GDB activates a simple help +facility which summarizes the available commands and their options. +In this section we summarize a few of the most commonly +used commands to give an idea of what `GDB` is about. You should create +a simple program with debugging information and experiment with the use of +these `GDB` commands on the program as you read through the +following section. + +* *set args `arguments`* + The `arguments` list above is a list of arguments to be passed to + the program on a subsequent run command, just as though the arguments + had been entered on a normal invocation of the program. The `set args` + command is not needed if the program does not require arguments. + + +* *run* + The `run` command causes execution of the program to start from + the beginning. If the program is already running, that is to say if + you are currently positioned at a breakpoint, then a prompt will ask + for confirmation that you want to abandon the current execution and + restart. + + +* *breakpoint `location`* + The breakpoint command sets a breakpoint, that is to say a point at which + execution will halt and `GDB` will await further + commands. `location` is + either a line number within a file, given in the format `file:linenumber`, + or it is the name of a subprogram. If you request that a breakpoint be set on + a subprogram that is overloaded, a prompt will ask you to specify on which of + those subprograms you want to breakpoint. You can also + specify that all of them should be breakpointed. If the program is run + and execution encounters the breakpoint, then the program + stops and `GDB` signals that the breakpoint was encountered by + printing the line of code before which the program is halted. + + +* *catch exception `name`* + This command causes the program execution to stop whenever exception + `name` is raised. If `name` is omitted, then the execution is + suspended when any exception is raised. + + +* *print `expression`* + This will print the value of the given expression. Most simple + Ada expression formats are properly handled by `GDB`, so the expression + can contain function calls, variables, operators, and attribute references. + + +* *continue* + Continues execution following a breakpoint, until the next breakpoint or the + termination of the program. + + +* *step* + Executes a single line after a breakpoint. If the next statement + is a subprogram call, execution continues into (the first statement of) + the called subprogram. + + +* *next* + Executes a single line. If this line is a subprogram call, executes and + returns from the call. + + +* *list* + Lists a few lines around the current source location. In practice, it + is usually more convenient to have a separate edit window open with the + relevant source file displayed. Successive applications of this command + print subsequent lines. The command can be given an argument which is a + line number, in which case it displays a few lines around the specified one. + + +* *backtrace* + Displays a backtrace of the call chain. This command is typically + used after a breakpoint has occurred, to examine the sequence of calls that + leads to the current breakpoint. The display includes one line for each + activation record (frame) corresponding to an active subprogram. + + +* *up* + At a breakpoint, `GDB` can display the values of variables local + to the current frame. The command `up` can be used to + examine the contents of other active frames, by moving the focus up + the stack, that is to say from callee to caller, one frame at a time. + + +* *down* + Moves the focus of `GDB` down from the frame currently being + examined to the frame of its callee (the reverse of the previous command), + + +* *frame `n`* + Inspect the frame with the given number. The value 0 denotes the frame + of the current breakpoint, that is to say the top of the call stack. + + +* *kill* + Kills the child process in which the program is running under GDB. + This may be useful for several purposes: + + * It allows you to recompile and relink your program, since on many systems + you cannot regenerate an executable file while it is running in a process. + + * You can run your program outside the debugger, on systems that do not + permit executing a program outside GDB while breakpoints are set + within GDB. + + * It allows you to debug a core dump rather than a running process. + +The above list is a very short introduction to the commands that +`GDB` provides. Important additional capabilities, including conditional +breakpoints, the ability to execute command sequences on a breakpoint, +the ability to debug at the machine instruction level and many other +features are described in detail in :title:`Debugging with GDB`. +Note that most commands can be abbreviated +(for example, c for continue, bt for backtrace). + + +.. _Using_Ada_Expressions: + +Using Ada Expressions +--------------------- + +.. index:: Ada expressions (in gdb) + +`GDB` supports a fairly large subset of Ada expression syntax, with some +extensions. The philosophy behind the design of this subset is + + * That `GDB` should provide basic literals and access to operations for + arithmetic, dereferencing, field selection, indexing, and subprogram calls, + leaving more sophisticated computations to subprograms written into the + program (which therefore may be called from `GDB`). + + * That type safety and strict adherence to Ada language restrictions + are not particularly relevant in a debugging context. + + * That brevity is important to the `GDB` user. + +Thus, for brevity, the debugger acts as if there were +implicit `with` and `use` clauses in effect for all user-written +packages, thus making it unnecessary to fully qualify most names with +their packages, regardless of context. Where this causes ambiguity, +`GDB` asks the user's intent. + +For details on the supported Ada syntax, see :title:`Debugging with GDB`. + + +.. _Calling_User-Defined_Subprograms: + +Calling User-Defined Subprograms +-------------------------------- + +An important capability of `GDB` is the ability to call user-defined +subprograms while debugging. This is achieved simply by entering +a subprogram call statement in the form: + + :: + + call subprogram-name (parameters) + +The keyword `call` can be omitted in the normal case where the +`subprogram-name` does not coincide with any of the predefined +`GDB` commands. + +The effect is to invoke the given subprogram, passing it the +list of parameters that is supplied. The parameters can be expressions and +can include variables from the program being debugged. The +subprogram must be defined +at the library level within your program, and `GDB` will call the +subprogram within the environment of your program execution (which +means that the subprogram is free to access or even modify variables +within your program). + +The most important use of this facility is in allowing the inclusion of +debugging routines that are tailored to particular data structures +in your program. Such debugging routines can be written to provide a suitably +high-level description of an abstract type, rather than a low-level dump +of its physical layout. After all, the standard +`GDB print` command only knows the physical layout of your +types, not their abstract meaning. Debugging routines can provide information +at the desired semantic level and are thus enormously useful. + +For example, when debugging GNAT itself, it is crucial to have access to +the contents of the tree nodes used to represent the program internally. +But tree nodes are represented simply by an integer value (which in turn +is an index into a table of nodes). +Using the `print` command on a tree node would simply print this integer +value, which is not very useful. But the PN routine (defined in file +treepr.adb in the GNAT sources) takes a tree node as input, and displays +a useful high level representation of the tree node, which includes the +syntactic category of the node, its position in the source, the integers +that denote descendant nodes and parent node, as well as varied +semantic information. To study this example in more detail, you might want to +look at the body of the PN procedure in the stated file. + +Another useful application of this capability is to deal with situations of +complex data which are not handled suitably by GDB. For example, if you specify +Convention Fortran for a multi-dimensional array, GDB does not know that +the ordering of array elements has been switched and will not properly +address the array elements. In such a case, instead of trying to print the +elements directly from GDB, you can write a callable procedure that prints +the elements in the desired format. + + +.. _Using_the_Next_Command_in_a_Function: + +Using the *next* Command in a Function +-------------------------------------- + +When you use the `next` command in a function, the current source +location will advance to the next statement as usual. A special case +arises in the case of a `return` statement. + +Part of the code for a return statement is the 'epilogue' of the function. +This is the code that returns to the caller. There is only one copy of +this epilogue code, and it is typically associated with the last return +statement in the function if there is more than one return. In some +implementations, this epilogue is associated with the first statement +of the function. + +The result is that if you use the `next` command from a return +statement that is not the last return statement of the function you +may see a strange apparent jump to the last return statement or to +the start of the function. You should simply ignore this odd jump. +The value returned is always that from the first return statement +that was stepped through. + + +.. _Stopping_When_Ada_Exceptions_Are_Raised: + +Stopping When Ada Exceptions Are Raised +--------------------------------------- + +.. index:: Exceptions (in gdb) + +You can set catchpoints that stop the program execution when your program +raises selected exceptions. + + +* *catch exception* + Set a catchpoint that stops execution whenever (any task in the) program + raises any exception. + + +* *catch exception `name`* + Set a catchpoint that stops execution whenever (any task in the) program + raises the exception `name`. + + +* *catch exception unhandled* + Set a catchpoint that stops executing whenever (any task in the) program + raises an exception for which there is no handler. + + +* *info exceptions*, *info exceptions `regexp`* + The `info exceptions` command permits the user to examine all defined + exceptions within Ada programs. With a regular expression, `regexp`, as + argument, prints out only those exceptions whose name matches `regexp`. + + +.. index:: Tasks (in gdb) + +.. _Ada_Tasks: + +Ada Tasks +--------- + +`GDB` allows the following task-related commands: + + +* *info tasks* + This command shows a list of current Ada tasks, as in the following example: + + :: + + (gdb) info tasks + ID TID P-ID Thread Pri State Name + 1 8088000 0 807e000 15 Child Activation Wait main_task + 2 80a4000 1 80ae000 15 Accept/Select Wait b + 3 809a800 1 80a4800 15 Child Activation Wait a + * 4 80ae800 3 80b8000 15 Running c + + + In this listing, the asterisk before the first task indicates it to be the + currently running task. The first column lists the task ID that is used + to refer to tasks in the following commands. + + +.. index:: Breakpoints and tasks + +* *break `linespec` task `taskid`*, *break `linespec` task `taskid` if ...* + + These commands are like the `break ... thread ...`. + `linespec` specifies source lines. + + Use the qualifier :samp:`task {taskid}` with a breakpoint command + to specify that you only want `GDB` to stop the program when a + particular Ada task reaches this breakpoint. `taskid` is one of the + numeric task identifiers assigned by `GDB`, shown in the first + column of the ``info tasks`` display. + + If you do not specify :samp:`task {taskid}` when you set a + breakpoint, the breakpoint applies to *all* tasks of your + program. + + You can use the `task` qualifier on conditional breakpoints as + well; in this case, place :samp:`task {taskid}` before the + breakpoint condition (before the `if`). + +.. index:: Task switching (in gdb) + +* *task `taskno`* + + This command allows switching to the task referred by `taskno`. In + particular, this allows browsing of the backtrace of the specified + task. It is advisable to switch back to the original task before + continuing execution otherwise the scheduling of the program may be + perturbed. + +For more detailed information on the tasking support, +see :title:`Debugging with GDB`. + + +.. index:: Debugging Generic Units +.. index:: Generics + +.. _Debugging_Generic_Units: + +Debugging Generic Units +----------------------- + +GNAT always uses code expansion for generic instantiation. This means that +each time an instantiation occurs, a complete copy of the original code is +made, with appropriate substitutions of formals by actuals. + +It is not possible to refer to the original generic entities in +`GDB`, but it is always possible to debug a particular instance of +a generic, by using the appropriate expanded names. For example, if we have + + .. code-block:: ada + + procedure g is + + generic package k is + procedure kp (v1 : in out integer); + end k; + + package body k is + procedure kp (v1 : in out integer) is + begin + v1 := v1 + 1; + end kp; + end k; + + package k1 is new k; + package k2 is new k; + + var : integer := 1; + + begin + k1.kp (var); + k2.kp (var); + k1.kp (var); + k2.kp (var); + end; + +Then to break on a call to procedure kp in the k2 instance, simply +use the command: + + :: + + (gdb) break g.k2.kp + +When the breakpoint occurs, you can step through the code of the +instance in the normal manner and examine the values of local variables, as for +other units. + + +.. index:: Remote Debugging with gdbserver + +.. _Remote_Debugging_with_gdbserver: + +Remote Debugging with gdbserver +------------------------------- + +On platforms where gdbserver is supported, it is possible to use this tool +to debug your application remotely. This can be useful in situations +where the program needs to be run on a target host that is different +from the host used for development, particularly when the target has +a limited amount of resources (either CPU and/or memory). + +To do so, start your program using gdbserver on the target machine. +gdbserver then automatically suspends the execution of your program +at its entry point, waiting for a debugger to connect to it. The +following commands starts an application and tells gdbserver to +wait for a connection with the debugger on localhost port 4444. + + + :: + + $ gdbserver localhost:4444 program + Process program created; pid = 5685 + Listening on port 4444 + +Once gdbserver has started listening, we can tell the debugger to establish +a connection with this gdbserver, and then start the same debugging session +as if the program was being debugged on the same host, directly under +the control of GDB. + + :: + + $ gdb program + (gdb) target remote targethost:4444 + Remote debugging using targethost:4444 + 0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so. + (gdb) b foo.adb:3 + Breakpoint 1 at 0x401f0c: file foo.adb, line 3. + (gdb) continue + Continuing. + + Breakpoint 1, foo () at foo.adb:4 + 4 end foo; + +It is also possible to use gdbserver to attach to an already running +program, in which case the execution of that program is simply suspended +until the connection between the debugger and gdbserver is established. + +For more information on how to use gdbserver, see the *Using the gdbserver Program* +section in :title:`Debugging with GDB`. +GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux. + + +.. index:: Abnormal Termination or Failure to Terminate + +.. _GNAT_Abnormal_Termination_or_Failure_to_Terminate: + +GNAT Abnormal Termination or Failure to Terminate +------------------------------------------------- + +When presented with programs that contain serious errors in syntax +or semantics, +GNAT may on rare occasions experience problems in operation, such +as aborting with a +segmentation fault or illegal memory access, raising an internal +exception, terminating abnormally, or failing to terminate at all. +In such cases, you can activate +various features of GNAT that can help you pinpoint the construct in your +program that is the likely source of the problem. + +The following strategies are presented in increasing order of +difficulty, corresponding to your experience in using GNAT and your +familiarity with compiler internals. + +* Run *gcc* with the *-gnatf*. This first + switch causes all errors on a given line to be reported. In its absence, + only the first error on a line is displayed. + + The *-gnatdO* switch causes errors to be displayed as soon as they + are encountered, rather than after compilation is terminated. If GNAT + terminates prematurely or goes into an infinite loop, the last error + message displayed may help to pinpoint the culprit. + +* Run *gcc* with the *-v (verbose)* switch. In this + mode, *gcc* produces ongoing information about the progress of the + compilation and provides the name of each procedure as code is + generated. This switch allows you to find which Ada procedure was being + compiled when it encountered a code generation problem. + +.. index:: -gnatdc switch + +* Run *gcc* with the *-gnatdc* switch. This is a GNAT specific + switch that does for the front-end what *-v* does + for the back end. The system prints the name of each unit, + either a compilation unit or nested unit, as it is being analyzed. + +* Finally, you can start + `gdb` directly on the `gnat1` executable. `gnat1` is the + front-end of GNAT, and can be run independently (normally it is just + called from *gcc*). You can use `gdb` on `gnat1` as you + would on a C program (but :ref:`The_GNAT_Debugger_GDB` for caveats). The + `where` command is the first line of attack; the variable + `lineno` (seen by `print lineno`), used by the second phase of + `gnat1` and by the *gcc* backend, indicates the source line at + which the execution stopped, and `input_file name` indicates the name of + the source file. + + +.. _Naming_Conventions_for_GNAT_Source_Files: + +Naming Conventions for GNAT Source Files +---------------------------------------- + +In order to examine the workings of the GNAT system, the following +brief description of its organization may be helpful: + +* Files with prefix :file:`sc` contain the lexical scanner. + +* All files prefixed with :file:`par` are components of the parser. The + numbers correspond to chapters of the Ada Reference Manual. For example, + parsing of select statements can be found in :file:`par-ch9.adb`. + +* All files prefixed with :file:`sem` perform semantic analysis. The + numbers correspond to chapters of the Ada standard. For example, all + issues involving context clauses can be found in :file:`sem_ch10.adb`. In + addition, some features of the language require sufficient special processing + to justify their own semantic files: sem_aggr for aggregates, sem_disp for + dynamic dispatching, etc. + +* All files prefixed with :file:`exp` perform normalization and + expansion of the intermediate representation (abstract syntax tree, or AST). + these files use the same numbering scheme as the parser and semantics files. + For example, the construction of record initialization procedures is done in + :file:`exp_ch3.adb`. + +* The files prefixed with :file:`bind` implement the binder, which + verifies the consistency of the compilation, determines an order of + elaboration, and generates the bind file. + +* The files :file:`atree.ads` and :file:`atree.adb` detail the low-level + data structures used by the front-end. + +* The files :file:`sinfo.ads` and :file:`sinfo.adb` detail the structure of + the abstract syntax tree as produced by the parser. + +* The files :file:`einfo.ads` and :file:`einfo.adb` detail the attributes of + all entities, computed during semantic analysis. + +* Library management issues are dealt with in files with prefix + :file:`lib`. + + .. index:: Annex A (in Ada Reference Manual) + +* Ada files with the prefix :file:`a-` are children of `Ada`, as + defined in Annex A. + + .. index:: Annex B (in Ada reference Manual) + +* Files with prefix :file:`i-` are children of `Interfaces`, as + defined in Annex B. + + .. index:: System (package in Ada Reference Manual) + +* Files with prefix :file:`s-` are children of `System`. This includes + both language-defined children and GNAT run-time routines. + + .. index:: GNAT (package) + +* Files with prefix :file:`g-` are children of `GNAT`. These are useful + general-purpose packages, fully documented in their specs. All + the other :file:`.c` files are modifications of common *gcc* files. + + +.. _Getting_Internal_Debugging_Information: + +Getting Internal Debugging Information +-------------------------------------- + +Most compilers have internal debugging switches and modes. GNAT +does also, except GNAT internal debugging switches and modes are not +secret. A summary and full description of all the compiler and binder +debug flags are in the file :file:`debug.adb`. You must obtain the +sources of the compiler to see the full detailed effects of these flags. + +The switches that print the source of the program (reconstructed from +the internal tree) are of general interest for user programs, as are the +options to print +the full internal tree, and the entity table (the symbol table +information). The reconstructed source provides a readable version of the +program after the front-end has completed analysis and expansion, +and is useful when studying the performance of specific constructs. +For example, constraint checks are indicated, complex aggregates +are replaced with loops and assignments, and tasking primitives +are replaced with run-time calls. + + +.. index:: traceback +.. index:: stack traceback +.. index:: stack unwinding + +.. _Stack_Traceback: + +Stack Traceback +--------------- + +Traceback is a mechanism to display the sequence of subprogram calls that +leads to a specified execution point in a program. Often (but not always) +the execution point is an instruction at which an exception has been raised. +This mechanism is also known as *stack unwinding* because it obtains +its information by scanning the run-time stack and recovering the activation +records of all active subprograms. Stack unwinding is one of the most +important tools for program debugging. + +The first entry stored in traceback corresponds to the deepest calling level, +that is to say the subprogram currently executing the instruction +from which we want to obtain the traceback. + +Note that there is no runtime performance penalty when stack traceback +is enabled, and no exception is raised during program execution. + +.. index:: traceback, non-symbolic + +.. _Non-Symbolic_Traceback: + +Non-Symbolic Traceback +^^^^^^^^^^^^^^^^^^^^^^ + +Note: this feature is not supported on all platforms. See +:samp:`GNAT.Traceback` spec in :file:`g-traceb.ads` +for a complete list of supported platforms. + +.. rubric:: Tracebacks From an Unhandled Exception + +A runtime non-symbolic traceback is a list of addresses of call instructions. +To enable this feature you must use the *-E* +`gnatbind`'s option. With this option a stack traceback is stored as part +of exception information. You can retrieve this information using the +`addr2line` tool. + +Here is a simple example: + + .. code-block:: ada + + procedure STB is + + procedure P1 is + begin + raise Constraint_Error; + end P1; + + procedure P2 is + begin + P1; + end P2; + + begin + P2; + end STB; + + :: + + $ gnatmake stb -bargs -E + $ stb + + Execution terminated by unhandled exception + Exception name: CONSTRAINT_ERROR + Message: stb.adb:5 + Call stack traceback locations: + 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 + +As we see the traceback lists a sequence of addresses for the unhandled +exception `CONSTRAINT_ERROR` raised in procedure P1. It is easy to +guess that this exception come from procedure P1. To translate these +addresses into the source lines where the calls appear, the +`addr2line` tool, described below, is invaluable. The use of this tool +requires the program to be compiled with debug information. + + :: + + $ gnatmake -g stb -bargs -E + $ stb + + Execution terminated by unhandled exception + Exception name: CONSTRAINT_ERROR + Message: stb.adb:5 + Call stack traceback locations: + 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 + + $ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 + 0x4011f1 0x77e892a4 + + 00401373 at d:/stb/stb.adb:5 + 0040138B at d:/stb/stb.adb:10 + 0040139C at d:/stb/stb.adb:14 + 00401335 at d:/stb/b~stb.adb:104 + 004011C4 at /build/.../crt1.c:200 + 004011F1 at /build/.../crt1.c:222 + 77E892A4 in ?? at ??:0 + +The `addr2line` tool has several other useful options: + + ======================== ======================================================== + :samp:`--functions` to get the function name corresponding to any location + :samp:`--demangle=gnat` to use the gnat decoding mode for the function names. + Note that for binutils version 2.9.x the option is + simply :samp:`--demangle`. + ======================== ======================================================== + + :: + + $ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b + 0x40139c 0x401335 0x4011c4 0x4011f1 + + 00401373 in stb.p1 at d:/stb/stb.adb:5 + 0040138B in stb.p2 at d:/stb/stb.adb:10 + 0040139C in stb at d:/stb/stb.adb:14 + 00401335 in main at d:/stb/b~stb.adb:104 + 004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200 + 004011F1 in <mainCRTStartup> at /build/.../crt1.c:222 + +From this traceback we can see that the exception was raised in +:file:`stb.adb` at line 5, which was reached from a procedure call in +:file:`stb.adb` at line 10, and so on. The :file:`b~std.adb` is the binder file, +which contains the call to the main program. +:ref:`Running_gnatbind`. The remaining entries are assorted runtime routines, +and the output will vary from platform to platform. + +It is also possible to use `GDB` with these traceback addresses to debug +the program. For example, we can break at a given code location, as reported +in the stack traceback: + + :: + + $ gdb -nw stb + +Furthermore, this feature is not implemented inside Windows DLL. Only +the non-symbolic traceback is reported in this case. + + :: + + (gdb) break *0x401373 + Breakpoint 1 at 0x401373: file stb.adb, line 5. + +It is important to note that the stack traceback addresses +do not change when debug information is included. This is particularly useful +because it makes it possible to release software without debug information (to +minimize object size), get a field report that includes a stack traceback +whenever an internal bug occurs, and then be able to retrieve the sequence +of calls with the same program compiled with debug information. + + +.. rubric:: Tracebacks From Exception Occurrences + +Non-symbolic tracebacks are obtained by using the *-E* binder argument. +The stack traceback is attached to the exception information string, and can +be retrieved in an exception handler within the Ada program, by means of the +Ada facilities defined in `Ada.Exceptions`. Here is a simple example: + + .. code-block:: ada + + with Ada.Text_IO; + with Ada.Exceptions; + + procedure STB is + + use Ada; + use Ada.Exceptions; + + procedure P1 is + K : Positive := 1; + begin + K := K - 1; + exception + when E : others => + Text_IO.Put_Line (Exception_Information (E)); + end P1; + + procedure P2 is + begin + P1; + end P2; + + begin + P2; + end STB; + +This program will output: + + :: + + $ stb + + Exception name: CONSTRAINT_ERROR + Message: stb.adb:12 + Call stack traceback locations: + 0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 + + +.. rubric:: Tracebacks From Anywhere in a Program + +It is also possible to retrieve a stack traceback from anywhere in a +program. For this you need to +use the `GNAT.Traceback` API. This package includes a procedure called +`Call_Chain` that computes a complete stack traceback, as well as useful +display procedures described below. It is not necessary to use the +*-E gnatbind* option in this case, because the stack traceback mechanism +is invoked explicitly. + +In the following example we compute a traceback at a specific location in +the program, and we display it using `GNAT.Debug_Utilities.Image` to +convert addresses to strings: + + + .. code-block:: ada + + with Ada.Text_IO; + with GNAT.Traceback; + with GNAT.Debug_Utilities; + + procedure STB is + + use Ada; + use GNAT; + use GNAT.Traceback; + + procedure P1 is + TB : Tracebacks_Array (1 .. 10); + -- We are asking for a maximum of 10 stack frames. + Len : Natural; + -- Len will receive the actual number of stack frames returned. + begin + Call_Chain (TB, Len); + + Text_IO.Put ("In STB.P1 : "); + + for K in 1 .. Len loop + Text_IO.Put (Debug_Utilities.Image (TB (K))); + Text_IO.Put (' '); + end loop; + + Text_IO.New_Line; + end P1; + + procedure P2 is + begin + P1; + end P2; + + begin + P2; + end STB; + + :: + + $ gnatmake -g stb + $ stb + + In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# + 16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# + + +You can then get further information by invoking the `addr2line` +tool as described earlier (note that the hexadecimal addresses +need to be specified in C format, with a leading '0x'). + +.. index:: traceback, symbolic + +.. _Symbolic_Traceback: + +Symbolic Traceback +^^^^^^^^^^^^^^^^^^ + +A symbolic traceback is a stack traceback in which procedure names are +associated with each code location. + +Note that this feature is not supported on all platforms. See +:samp:`GNAT.Traceback.Symbolic` spec in :file:`g-trasym.ads` for a complete +list of currently supported platforms. + +Note that the symbolic traceback requires that the program be compiled +with debug information. If it is not compiled with debug information +only the non-symbolic information will be valid. + + +.. rubric:: Tracebacks From Exception Occurrences + +Here is an example: + + .. code-block:: ada + + with Ada.Text_IO; + with GNAT.Traceback.Symbolic; + + procedure STB is + + procedure P1 is + begin + raise Constraint_Error; + end P1; + + procedure P2 is + begin + P1; + end P2; + + procedure P3 is + begin + P2; + end P3; + + begin + P3; + exception + when E : others => + Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); + end STB; + + :: + + $ gnatmake -g .\stb -bargs -E + $ stb + + 0040149F in stb.p1 at stb.adb:8 + 004014B7 in stb.p2 at stb.adb:13 + 004014CF in stb.p3 at stb.adb:18 + 004015DD in ada.stb at stb.adb:22 + 00401461 in main at b~stb.adb:168 + 004011C4 in __mingw_CRTStartup at crt1.c:200 + 004011F1 in mainCRTStartup at crt1.c:222 + 77E892A4 in ?? at ??:0 + +In the above example the ``.\`` syntax in the *gnatmake* command +is currently required by *addr2line* for files that are in +the current working directory. +Moreover, the exact sequence of linker options may vary from platform +to platform. +The above *-largs* section is for Windows platforms. By contrast, +under Unix there is no need for the *-largs* section. +Differences across platforms are due to details of linker implementation. + + +.. rubric:: Tracebacks From Anywhere in a Program + +It is possible to get a symbolic stack traceback +from anywhere in a program, just as for non-symbolic tracebacks. +The first step is to obtain a non-symbolic +traceback, and then call `Symbolic_Traceback` to compute the symbolic +information. Here is an example: + + .. code-block:: ada + + with Ada.Text_IO; + with GNAT.Traceback; + with GNAT.Traceback.Symbolic; + + procedure STB is + + use Ada; + use GNAT.Traceback; + use GNAT.Traceback.Symbolic; + + procedure P1 is + TB : Tracebacks_Array (1 .. 10); + -- We are asking for a maximum of 10 stack frames. + Len : Natural; + -- Len will receive the actual number of stack frames returned. + begin + Call_Chain (TB, Len); + Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); + end P1; + + procedure P2 is + begin + P1; + end P2; + + begin + P2; + end STB; + + +.. index:: Code Coverage +.. index:: Profiling + + +.. _Code_Coverage_and_Profiling: + +Code Coverage and Profiling +=========================== + +This section describes how to use the `gcov` coverage testing tool and +the `gprof` profiler tool on Ada programs. + +.. index:: ! gcov + +.. _Code_Coverage_of_Ada_Programs_with_gcov: + +Code Coverage of Ada Programs with gcov +--------------------------------------- + +`gcov` is a test coverage program: it analyzes the execution of a given +program on selected tests, to help you determine the portions of the program +that are still untested. + +`gcov` is part of the GCC suite, and is described in detail in the GCC +User's Guide. You can refer to this documentation for a more complete +description. + +This chapter provides a quick startup guide, and +details some GNAT-specific features. + +.. _Quick_startup_guide: + +Quick startup guide +^^^^^^^^^^^^^^^^^^^ + +In order to perform coverage analysis of a program using `gcov`, several +steps are needed: + +#. Instrument the code during the compilation process, +#. Execute the instrumented program, and +#. Invoke the `gcov` tool to generate the coverage results. + +.. index:: -fprofile-arcs (gcc) +.. index:: -ftest-coverage (gcc +.. index:: -fprofile-arcs (gnatbind) + +The code instrumentation needed by gcov is created at the object level. +The source code is not modified in any way, because the instrumentation code is +inserted by gcc during the compilation process. To compile your code with code +coverage activated, you need to recompile your whole project using the +switches +`-fprofile-arcs` and `-ftest-coverage`, and link it using +`-fprofile-arcs`. + + :: + + $ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \\ + -largs -fprofile-arcs + +This compilation process will create :file:`.gcno` files together with +the usual object files. + +Once the program is compiled with coverage instrumentation, you can +run it as many times as needed -- on portions of a test suite for +example. The first execution will produce :file:`.gcda` files at the +same location as the :file:`.gcno` files. Subsequent executions +will update those files, so that a cumulative result of the covered +portions of the program is generated. + +Finally, you need to call the `gcov` tool. The different options of +`gcov` are described in the GCC User's Guide, section 'Invoking gcov'. + +This will create annotated source files with a :file:`.gcov` extension: +:file:`my_main.adb` file will be analyzed in :file:`my_main.adb.gcov`. + + +.. _GNAT_specifics: + +GNAT specifics +^^^^^^^^^^^^^^ + +Because of Ada semantics, portions of the source code may be shared among +several object files. This is the case for example when generics are +involved, when inlining is active or when declarations generate initialisation +calls. In order to take +into account this shared code, you need to call `gcov` on all +source files of the tested program at once. + +The list of source files might exceed the system's maximum command line +length. In order to bypass this limitation, a new mechanism has been +implemented in `gcov`: you can now list all your project's files into a +text file, and provide this file to gcov as a parameter, preceded by a ``@`` +(e.g. :samp:`gcov @mysrclist.txt`). + +Note that on AIX compiling a static library with `-fprofile-arcs` is +not supported as there can be unresolved symbols during the final link. + + +.. index:: ! gprof +.. index:: Profiling + +.. _Profiling_an_Ada_Program_with_gprof: + +Profiling an Ada Program with gprof +----------------------------------- + +This section is not meant to be an exhaustive documentation of `gprof`. +Full documentation for it can be found in the :title:`GNU Profiler User's Guide` +documentation that is part of this GNAT distribution. + +Profiling a program helps determine the parts of a program that are executed +most often, and are therefore the most time-consuming. + +`gprof` is the standard GNU profiling tool; it has been enhanced to +better handle Ada programs and multitasking. +It is currently supported on the following platforms + +* linux x86/x86_64 +* solaris sparc/sparc64/x86 +* windows x86 + +In order to profile a program using `gprof`, several steps are needed: + +#. Instrument the code, which requires a full recompilation of the project with the + proper switches. + +#. Execute the program under the analysis conditions, i.e. with the desired + input. + +#. Analyze the results using the `gprof` tool. + +The following sections detail the different steps, and indicate how +to interpret the results. + + +.. _Compilation_for_profiling: + +Compilation for profiling +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: -pg (gcc), for profiling +.. index:: -pg (gnatlink), for profiling + +In order to profile a program the first step is to tell the compiler +to generate the necessary profiling information. The compiler switch to be used +is ``-pg``, which must be added to other compilation switches. This +switch needs to be specified both during compilation and link stages, and can +be specified once when using gnatmake: + + :: + + $ gnatmake -f -pg -P my_project + +Note that only the objects that were compiled with the ``-pg`` switch will +be profiled; if you need to profile your whole project, use the ``-f`` +gnatmake switch to force full recompilation. + +.. _Program_execution: + + +Program execution +^^^^^^^^^^^^^^^^^ + +Once the program has been compiled for profiling, you can run it as usual. + +The only constraint imposed by profiling is that the program must terminate +normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be +properly analyzed. + +Once the program completes execution, a data file called :file:`gmon.out` is +generated in the directory where the program was launched from. If this file +already exists, it will be overwritten. + + +.. _Running_gprof: + +Running gprof +^^^^^^^^^^^^^ + +The `gprof` tool is called as follow: + + :: + + $ gprof my_prog gmon.out + +or simply: + + :: + + $ gprof my_prog + +The complete form of the gprof command line is the following: + + :: + + $ gprof [switches] [executable [data-file]] + +`gprof` supports numerous switches. The order of these +switch does not matter. The full list of options can be found in +the GNU Profiler User's Guide documentation that comes with this documentation. + +The following is the subset of those switches that is most relevant: + +.. index:: --demangle (gprof) + +:samp:`--demangle[={style}]`, :samp:`--no-demangle` + These options control whether symbol names should be demangled when + printing output. The default is to demangle C++ symbols. The + ``--no-demangle`` option may be used to turn off demangling. Different + compilers have different mangling styles. The optional demangling style + argument can be used to choose an appropriate demangling style for your + compiler, in particular Ada symbols generated by GNAT can be demangled using + ``--demangle=gnat``. + + +.. index:: -e (gprof) + +:samp:`-e {function_name}` + The :samp:`-e {function}` option tells `gprof` not to print + information about the function `function_name` (and its + children...) in the call graph. The function will still be listed + as a child of any functions that call it, but its index number will be + shown as ``[not printed]``. More than one ``-e`` option may be + given; only one `function_name` may be indicated with each ``-e`` + option. + + +.. index:: -E (gprof) + +:samp:`-E {function_name}` + The :samp:`-E {function}` option works like the ``-e`` option, but + execution time spent in the function (and children who were not called from + anywhere else), will not be used to compute the percentages-of-time for + the call graph. More than one ``-E`` option may be given; only one + `function_name` may be indicated with each ``-E`` option. + + +.. index:: -f (gprof) + +:samp:`-f {function_name}` + The :samp:`-f {function}` option causes `gprof` to limit the + call graph to the function `function_name` and its children (and + their children...). More than one ``-f`` option may be given; + only one `function_name` may be indicated with each ``-f`` + option. + + +.. index:: -F (gprof) + +:samp:`-F {function_name}` + The :samp:`-F {function}` option works like the ``-f`` option, but + only time spent in the function and its children (and their + children...) will be used to determine total-time and + percentages-of-time for the call graph. More than one ``-F`` option + may be given; only one `function_name` may be indicated with each + ``-F`` option. The ``-F`` option overrides the ``-E`` option. + + +.. _Interpretation_of_profiling_results: + +Interpretation of profiling results +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The results of the profiling analysis are represented by two arrays: the +'flat profile' and the 'call graph'. Full documentation of those outputs +can be found in the GNU Profiler User's Guide. + +The flat profile shows the time spent in each function of the program, and how +many time it has been called. This allows you to locate easily the most +time-consuming functions. + +The call graph shows, for each subprogram, the subprograms that call it, +and the subprograms that it calls. It also provides an estimate of the time +spent in each of those callers/called subprograms. + + + +.. _Improving_Performance: + +Improving Performance +===================== + +.. index:: Improving performance + +This section presents several topics related to program performance. +It first describes some of the tradeoffs that need to be considered +and some of the techniques for making your program run faster. + +.. only:: PRO or GPL + + It then documents the unused subprogram/data elimination feature + and the *gnatelim* tool, + which can reduce the size of program executables. + + +.. only:: FSF + + It then documents the unused subprogram/data elimination feature, + which can reduce the size of program executables. + + +.. _Performance_Considerations: + +Performance Considerations +-------------------------- + +The GNAT system provides a number of options that allow a trade-off +between + +* performance of the generated code + +* speed of compilation + +* minimization of dependences and recompilation + +* the degree of run-time checking. + +The defaults (if no options are selected) aim at improving the speed +of compilation and minimizing dependences, at the expense of performance +of the generated code: + +* no optimization + +* no inlining of subprogram calls + +* all run-time checks enabled except overflow and elaboration checks + +These options are suitable for most program development purposes. This +section describes how you can modify these choices, and also provides +some guidelines on debugging optimized code. + + +.. _Controlling_Run-Time_Checks: + +Controlling Run-Time Checks +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, GNAT generates all run-time checks, except integer overflow +checks, stack overflow checks, and checks for access before elaboration on +subprogram calls. The latter are not required in default mode, because all +necessary checking is done at compile time. + +.. index:: -gnatp (gcc) +.. index:: -gnato (gcc) + +Two gnat switches, *-gnatp* and *-gnato* allow this default to +be modified. See :ref:`Run-Time_Checks`. + +Our experience is that the default is suitable for most development +purposes. + +We treat integer overflow specially because these +are quite expensive and in our experience are not as important as other +run-time checks in the development process. Note that division by zero +is not considered an overflow check, and divide by zero checks are +generated where required by default. + +Elaboration checks are off by default, and also not needed by default, since +GNAT uses a static elaboration analysis approach that avoids the need for +run-time checking. This manual contains a full chapter discussing the issue +of elaboration checks, and if the default is not satisfactory for your use, +you should read this chapter. + +For validity checks, the minimal checks required by the Ada Reference +Manual (for case statements and assignments to array elements) are on +by default. These can be suppressed by use of the *-gnatVn* switch. +Note that in Ada 83, there were no validity checks, so if the Ada 83 mode +is acceptable (or when comparing GNAT performance with an Ada 83 compiler), +it may be reasonable to routinely use *-gnatVn*. Validity checks +are also suppressed entirely if *-gnatp* is used. + +.. index:: Overflow checks +.. index:: Checks, overflow + +.. index:: Suppress +.. index:: Unsuppress +.. index:: pragma Suppress +.. index:: pragma Unsuppress + +Note that the setting of the switches controls the default setting of +the checks. They may be modified using either `pragma Suppress` (to +remove checks) or `pragma Unsuppress` (to add back suppressed +checks) in the program source. + + +.. _Use_of_Restrictions: + +Use of Restrictions +^^^^^^^^^^^^^^^^^^^ + +The use of pragma Restrictions allows you to control which features are +permitted in your program. Apart from the obvious point that if you avoid +relatively expensive features like finalization (enforceable by the use +of pragma Restrictions (No_Finalization), the use of this pragma does not +affect the generated code in most cases. + +One notable exception to this rule is that the possibility of task abort +results in some distributed overhead, particularly if finalization or +exception handlers are used. The reason is that certain sections of code +have to be marked as non-abortable. + +If you use neither the `abort` statement, nor asynchronous transfer +of control (`select ... then abort`), then this distributed overhead +is removed, which may have a general positive effect in improving +overall performance. Especially code involving frequent use of tasking +constructs and controlled types will show much improved performance. +The relevant restrictions pragmas are + + .. code-block:: ada + + pragma Restrictions (No_Abort_Statements); + pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); + +It is recommended that these restriction pragmas be used if possible. Note +that this also means that you can write code without worrying about the +possibility of an immediate abort at any point. + + +.. _Optimization_Levels: + +Optimization Levels +^^^^^^^^^^^^^^^^^^^ + +.. index:: -O (gcc) + +Without any optimization option, +the compiler's goal is to reduce the cost of +compilation and to make debugging produce the expected results. +Statements are independent: if you stop the program with a breakpoint between +statements, you can then assign a new value to any variable or change +the program counter to any other statement in the subprogram and get exactly +the results you would expect from the source code. + +Turning on optimization makes the compiler attempt to improve the +performance and/or code size at the expense of compilation time and +possibly the ability to debug the program. + +If you use multiple +-O options, with or without level numbers, +the last such option is the one that is effective. + +The default is optimization off. This results in the fastest compile +times, but GNAT makes absolutely no attempt to optimize, and the +generated programs are considerably larger and slower than when +optimization is enabled. You can use the +*-O* switch (the permitted forms are *-O0*, *-O1* +*-O2*, *-O3*, and *-Os*) +to *gcc* to control the optimization level: + + +* *-O0* + No optimization (the default); + generates unoptimized code but has + the fastest compilation time. + + Note that many other compilers do fairly extensive optimization + even if 'no optimization' is specified. With gcc, it is + very unusual to use -O0 for production if + execution time is of any concern, since -O0 + really does mean no optimization at all. This difference between + gcc and other compilers should be kept in mind when doing + performance comparisons. + +* *-O1* + Moderate optimization; + optimizes reasonably well but does not + degrade compilation time significantly. + +* *-O2* + Full optimization; + generates highly optimized code and has + the slowest compilation time. + +* *-O3* + Full optimization as in *-O2*; + also uses more aggressive automatic inlining of subprograms within a unit + (:ref:`Inlining_of_Subprograms`) and attempts to vectorize loops. + + +* *-Os* + Optimize space usage (code and data) of resulting program. + +Higher optimization levels perform more global transformations on the +program and apply more expensive analysis algorithms in order to generate +faster and more compact code. The price in compilation time, and the +resulting improvement in execution time, +both depend on the particular application and the hardware environment. +You should experiment to find the best level for your application. + +Since the precise set of optimizations done at each level will vary from +release to release (and sometime from target to target), it is best to think +of the optimization settings in general terms. +See the *Options That Control Optimization* section in +:title:`Using the GNU Compiler Collection (GCC)` +for details about +the *-O* settings and a number of *-f* options that +individually enable or disable specific optimizations. + +Unlike some other compilation systems, *gcc* has +been tested extensively at all optimization levels. There are some bugs +which appear only with optimization turned on, but there have also been +bugs which show up only in *unoptimized* code. Selecting a lower +level of optimization does not improve the reliability of the code +generator, which in practice is highly reliable at all optimization +levels. + +Note regarding the use of *-O3*: The use of this optimization level +is generally discouraged with GNAT, since it often results in larger +executables which may run more slowly. See further discussion of this point +in :ref:`Inlining_of_Subprograms`. + + +.. _Debugging_Optimized_Code: + +Debugging Optimized Code +^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Debugging optimized code +.. index:: Optimization and debugging + +Although it is possible to do a reasonable amount of debugging at +nonzero optimization levels, +the higher the level the more likely that +source-level constructs will have been eliminated by optimization. +For example, if a loop is strength-reduced, the loop +control variable may be completely eliminated and thus cannot be +displayed in the debugger. +This can only happen at *-O2* or *-O3*. +Explicit temporary variables that you code might be eliminated at +level *-O1* or higher. + +.. index:: -g (gcc) + +The use of the *-g* switch, +which is needed for source-level debugging, +affects the size of the program executable on disk, +and indeed the debugging information can be quite large. +However, it has no effect on the generated code (and thus does not +degrade performance) + +Since the compiler generates debugging tables for a compilation unit before +it performs optimizations, the optimizing transformations may invalidate some +of the debugging data. You therefore need to anticipate certain +anomalous situations that may arise while debugging optimized code. +These are the most common cases: + +* *The 'hopping Program Counter':* Repeated `step` or `next` + commands show + the PC bouncing back and forth in the code. This may result from any of + the following optimizations: + + - *Common subexpression elimination:* using a single instance of code for a + quantity that the source computes several times. As a result you + may not be able to stop on what looks like a statement. + + - *Invariant code motion:* moving an expression that does not change within a + loop, to the beginning of the loop. + + - *Instruction scheduling:* moving instructions so as to + overlap loads and stores (typically) with other code, or in + general to move computations of values closer to their uses. Often + this causes you to pass an assignment statement without the assignment + happening and then later bounce back to the statement when the + value is actually needed. Placing a breakpoint on a line of code + and then stepping over it may, therefore, not always cause all the + expected side-effects. + +* *The 'big leap':* More commonly known as *cross-jumping*, in which + two identical pieces of code are merged and the program counter suddenly + jumps to a statement that is not supposed to be executed, simply because + it (and the code following) translates to the same thing as the code + that *was* supposed to be executed. This effect is typically seen in + sequences that end in a jump, such as a `goto`, a `return`, or + a `break` in a C `switch` statement. + +* *The 'roving variable':* The symptom is an unexpected value in a variable. + There are various reasons for this effect: + + - In a subprogram prologue, a parameter may not yet have been moved to its + 'home'. + + - A variable may be dead, and its register re-used. This is + probably the most common cause. + + - As mentioned above, the assignment of a value to a variable may + have been moved. + + - A variable may be eliminated entirely by value propagation or + other means. In this case, GCC may incorrectly generate debugging + information for the variable + + In general, when an unexpected value appears for a local variable or parameter + you should first ascertain if that value was actually computed by + your program, as opposed to being incorrectly reported by the debugger. + Record fields or + array elements in an object designated by an access value + are generally less of a problem, once you have ascertained that the access + value is sensible. + Typically, this means checking variables in the preceding code and in the + calling subprogram to verify that the value observed is explainable from other + values (one must apply the procedure recursively to those + other values); or re-running the code and stopping a little earlier + (perhaps before the call) and stepping to better see how the variable obtained + the value in question; or continuing to step *from* the point of the + strange value to see if code motion had simply moved the variable's + assignments later. + +In light of such anomalies, a recommended technique is to use *-O0* +early in the software development cycle, when extensive debugging capabilities +are most needed, and then move to *-O1* and later *-O2* as +the debugger becomes less critical. +Whether to use the *-g* switch in the release version is +a release management issue. +Note that if you use *-g* you can then use the *strip* program +on the resulting executable, +which removes both debugging information and global symbols. + + +.. _Inlining_of_Subprograms: + +Inlining of Subprograms +^^^^^^^^^^^^^^^^^^^^^^^ + +A call to a subprogram in the current unit is inlined if all the +following conditions are met: + +* The optimization level is at least *-O1*. + +* The called subprogram is suitable for inlining: It must be small enough + and not contain something that *gcc* cannot support in inlined + subprograms. + + .. index:: pragma Inline + .. index:: Inline + +* Any one of the following applies: `pragma Inline` is applied to the + subprogram and the *-gnatn* switch is specified; the + subprogram is local to the unit and called once from within it; the + subprogram is small and optimization level *-O2* is specified; + optimization level *-O3* is specified. + +Calls to subprograms in |withed| units are normally not inlined. +To achieve actual inlining (that is, replacement of the call by the code +in the body of the subprogram), the following conditions must all be true: + +* The optimization level is at least *-O1*. + +* The called subprogram is suitable for inlining: It must be small enough + and not contain something that *gcc* cannot support in inlined + subprograms. + +* The call appears in a body (not in a package spec). + +* There is a `pragma Inline` for the subprogram. + +* The *-gnatn* switch is used on the command line. + +Even if all these conditions are met, it may not be possible for +the compiler to inline the call, due to the length of the body, +or features in the body that make it impossible for the compiler +to do the inlining. + +Note that specifying the *-gnatn* switch causes additional +compilation dependencies. Consider the following: + + .. code-block:: ada + + package R is + procedure Q; + pragma Inline (Q); + end R; + package body R is + ... + end R; + + with R; + procedure Main is + begin + ... + R.Q; + end Main; + +With the default behavior (no *-gnatn* switch specified), the +compilation of the `Main` procedure depends only on its own source, +:file:`main.adb`, and the spec of the package in file :file:`r.ads`. This +means that editing the body of `R` does not require recompiling +`Main`. + +On the other hand, the call `R.Q` is not inlined under these +circumstances. If the *-gnatn* switch is present when `Main` +is compiled, the call will be inlined if the body of `Q` is small +enough, but now `Main` depends on the body of `R` in +:file:`r.adb` as well as on the spec. This means that if this body is edited, +the main program must be recompiled. Note that this extra dependency +occurs whether or not the call is in fact inlined by *gcc*. + +The use of front end inlining with *-gnatN* generates similar +additional dependencies. + +.. index:: -fno-inline (gcc) + +Note: The *-fno-inline* switch overrides all other conditions and ensures that +no inlining occurs, unless requested with pragma Inline_Always for gcc +back-ends. The extra dependences resulting from *-gnatn* will still be active, +even if this switch is used to suppress the resulting inlining actions. + +.. index:: -fno-inline-functions (gcc) + +Note: The *-fno-inline-functions* switch can be used to prevent +automatic inlining of subprograms if *-O3* is used. + +.. index:: -fno-inline-small-functions (gcc) + +Note: The *-fno-inline-small-functions* switch can be used to prevent +automatic inlining of small subprograms if *-O2* is used. + +.. index:: -fno-inline-functions-called-once (gcc) + +Note: The *-fno-inline-functions-called-once* switch +can be used to prevent inlining of subprograms local to the unit +and called once from within it if *-O1* is used. + +Note regarding the use of *-O3*: *-gnatn* is made up of two +sub-switches *-gnatn1* and *-gnatn2* that can be directly +specified in lieu of it, *-gnatn* being translated into one of them +based on the optimization level. With *-O2* or below, *-gnatn* +is equivalent to *-gnatn1* which activates pragma `Inline` with +moderate inlining across modules. With *-O3*, *-gnatn* is +equivalent to *-gnatn2* which activates pragma `Inline` with +full inlining across modules. If you have used pragma `Inline` in +appropriate cases, then it is usually much better to use *-O2* +and *-gnatn* and avoid the use of *-O3* which has the additional +effect of inlining subprograms you did not think should be inlined. We have +found that the use of *-O3* may slow down the compilation and increase +the code size by performing excessive inlining, leading to increased +instruction cache pressure from the increased code size and thus minor +performance improvements. So the bottom line here is that you should not +automatically assume that *-O3* is better than *-O2*, and +indeed you should use *-O3* only if tests show that it actually +improves performance for your program. + +.. _Floating_Point_Operations: + +Floating_Point_Operations +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Floating-Point Operations + +On almost all targets, GNAT maps Float and Long_Float to the 32-bit and +64-bit standard IEEE floating-point representations, and operations will +use standard IEEE arithmetic as provided by the processor. On most, but +not all, architectures, the attribute Machine_Overflows is False for these +types, meaning that the semantics of overflow is implementation-defined. +In the case of GNAT, these semantics correspond to the normal IEEE +treatment of infinities and NaN (not a number) values. For example, +1.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By +avoiding explicit overflow checks, the performance is greatly improved +on many targets. However, if required, floating-point overflow can be +enabled by the use of the pragma Check_Float_Overflow. + +Another consideration that applies specifically to x86 32-bit +architectures is which form of floating-point arithmetic is used. +By default the operations use the old style x86 floating-point, +which implements an 80-bit extended precision form (on these +architectures the type Long_Long_Float corresponds to that form). +In addition, generation of efficient code in this mode means that +the extended precision form will be used for intermediate results. +This may be helpful in improving the final precision of a complex +expression. However it means that the results obtained on the x86 +will be different from those on other architectures, and for some +algorithms, the extra intermediate precision can be detrimental. + +In addition to this old-style floating-point, all modern x86 chips +implement an alternative floating-point operation model referred +to as SSE2. In this model there is no extended form, and furthermore +execution performance is significantly enhanced. To force GNAT to use +this more modern form, use both of the switches: + + -msse2 -mfpmath=sse + +A unit compiled with these switches will automatically use the more +efficient SSE2 instruction set for Float and Long_Float operations. +Note that the ABI has the same form for both floating-point models, +so it is permissible to mix units compiled with and without these +switches. + + + + + +.. _Vectorization_of_loops: + +Vectorization of loops +^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Optimization Switches + +You can take advantage of the auto-vectorizer present in the *gcc* +back end to vectorize loops with GNAT. The corresponding command line switch +is *-ftree-vectorize* but, as it is enabled by default at *-O3* +and other aggressive optimizations helpful for vectorization also are enabled +by default at this level, using *-O3* directly is recommended. + +You also need to make sure that the target architecture features a supported +SIMD instruction set. For example, for the x86 architecture, you should at +least specify *-msse2* to get significant vectorization (but you don't +need to specify it for x86-64 as it is part of the base 64-bit architecture). +Similarly, for the PowerPC architecture, you should specify *-maltivec*. + +The preferred loop form for vectorization is the `for` iteration scheme. +Loops with a `while` iteration scheme can also be vectorized if they are +very simple, but the vectorizer will quickly give up otherwise. With either +iteration scheme, the flow of control must be straight, in particular no +`exit` statement may appear in the loop body. The loop may however +contain a single nested loop, if it can be vectorized when considered alone: + + .. code-block:: ada + + A : array (1..4, 1..4) of Long_Float; + S : array (1..4) of Long_Float; + + procedure Sum is + begin + for I in A'Range(1) loop + for J in A'Range(2) loop + S (I) := S (I) + A (I, J); + end loop; + end loop; + end Sum; + +The vectorizable operations depend on the targeted SIMD instruction set, but +the adding and some of the multiplying operators are generally supported, as +well as the logical operators for modular types. Note that, in the former +case, enabling overflow checks, for example with *-gnato*, totally +disables vectorization. The other checks are not supposed to have the same +definitive effect, although compiling with *-gnatp* might well reveal +cases where some checks do thwart vectorization. + +Type conversions may also prevent vectorization if they involve semantics that +are not directly supported by the code generator or the SIMD instruction set. +A typical example is direct conversion from floating-point to integer types. +The solution in this case is to use the following idiom: + + .. code-block:: ada + + Integer (S'Truncation (F)) + +if `S` is the subtype of floating-point object `F`. + +In most cases, the vectorizable loops are loops that iterate over arrays. +All kinds of array types are supported, i.e. constrained array types with +static bounds: + + .. code-block:: ada + + type Array_Type is array (1 .. 4) of Long_Float; + +constrained array types with dynamic bounds: + + + .. code-block:: ada + + type Array_Type is array (1 .. Q.N) of Long_Float; + + type Array_Type is array (Q.K .. 4) of Long_Float; + + type Array_Type is array (Q.K .. Q.N) of Long_Float; + +or unconstrained array types: + + .. code-block:: ada + + type Array_Type is array (Positive range <>) of Long_Float; + +The quality of the generated code decreases when the dynamic aspect of the +array type increases, the worst code being generated for unconstrained array +types. This is so because, the less information the compiler has about the +bounds of the array, the more fallback code it needs to generate in order to +fix things up at run time. + +It is possible to specify that a given loop should be subject to vectorization +preferably to other optimizations by means of pragma `Loop_Optimize`: + + .. code-block:: ada + + pragma Loop_Optimize (Vector); + +placed immediately within the loop will convey the appropriate hint to the +compiler for this loop. + +It is also possible to help the compiler generate better vectorized code +for a given loop by asserting that there are no loop-carried dependencies +in the loop. Consider for example the procedure: + + .. code-block:: ada + + type Arr is array (1 .. 4) of Long_Float; + + procedure Add (X, Y : not null access Arr; R : not null access Arr) is + begin + for I in Arr'Range loop + R(I) := X(I) + Y(I); + end loop; + end; + +By default, the compiler cannot unconditionally vectorize the loop because +assigning to a component of the array designated by R in one iteration could +change the value read from the components of the array designated by X or Y +in a later iteration. As a result, the compiler will generate two versions +of the loop in the object code, one vectorized and the other not vectorized, +as well as a test to select the appropriate version at run time. This can +be overcome by another hint: + + .. code-block:: ada + + pragma Loop_Optimize (Ivdep); + +placed immediately within the loop will tell the compiler that it can safely +omit the non-vectorized version of the loop as well as the run-time test. + + +.. _Other_Optimization_Switches: + +Other Optimization Switches +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Optimization Switches + +Since `GNAT` uses the *gcc* back end, all the specialized +*gcc* optimization switches are potentially usable. These switches +have not been extensively tested with GNAT but can generally be expected +to work. Examples of switches in this category are *-funroll-loops* +and the various target-specific *-m* options (in particular, it has +been observed that *-march=xxx* can significantly improve performance +on appropriate machines). For full details of these switches, see +the `Submodel Options` section in the `Hardware Models and Configurations` +chapter of :title:`Using the GNU Compiler Collection (GCC)`. + + +.. _Optimization_and_Strict_Aliasing: + +Optimization and Strict Aliasing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Aliasing +.. index:: Strict Aliasing +.. index:: No_Strict_Aliasing + +The strong typing capabilities of Ada allow an optimizer to generate +efficient code in situations where other languages would be forced to +make worst case assumptions preventing such optimizations. Consider +the following example: + + .. code-block:: ada + + procedure R is + type Int1 is new Integer; + type Int2 is new Integer; + type Int1A is access Int1; + type Int2A is access Int2; + Int1V : Int1A; + Int2V : Int2A; + ... + + begin + ... + for J in Data'Range loop + if Data (J) = Int1V.all then + Int2V.all := Int2V.all + 1; + end if; + end loop; + ... + end R; + +In this example, since the variable `Int1V` can only access objects +of type `Int1`, and `Int2V` can only access objects of type +`Int2`, there is no possibility that the assignment to +`Int2V.all` affects the value of `Int1V.all`. This means that +the compiler optimizer can "know" that the value `Int1V.all` is constant +for all iterations of the loop and avoid the extra memory reference +required to dereference it each time through the loop. + +This kind of optimization, called strict aliasing analysis, is +triggered by specifying an optimization level of *-O2* or +higher or *-Os* and allows `GNAT` to generate more efficient code +when access values are involved. + +However, although this optimization is always correct in terms of +the formal semantics of the Ada Reference Manual, difficulties can +arise if features like `Unchecked_Conversion` are used to break +the typing system. Consider the following complete program example: + + .. code-block:: ada + + package p1 is + type int1 is new integer; + type int2 is new integer; + type a1 is access int1; + type a2 is access int2; + end p1; + + with p1; use p1; + package p2 is + function to_a2 (Input : a1) return a2; + end p2; + + with Unchecked_Conversion; + package body p2 is + function to_a2 (Input : a1) return a2 is + function to_a2u is + new Unchecked_Conversion (a1, a2); + begin + return to_a2u (Input); + end to_a2; + end p2; + + with p2; use p2; + with p1; use p1; + with Text_IO; use Text_IO; + procedure m is + v1 : a1 := new int1; + v2 : a2 := to_a2 (v1); + begin + v1.all := 1; + v2.all := 0; + put_line (int1'image (v1.all)); + end; + +This program prints out 0 in *-O0* or *-O1* +mode, but it prints out 1 in *-O2* mode. That's +because in strict aliasing mode, the compiler can and +does assume that the assignment to `v2.all` could not +affect the value of `v1.all`, since different types +are involved. + +This behavior is not a case of non-conformance with the standard, since +the Ada RM specifies that an unchecked conversion where the resulting +bit pattern is not a correct value of the target type can result in an +abnormal value and attempting to reference an abnormal value makes the +execution of a program erroneous. That's the case here since the result +does not point to an object of type `int2`. This means that the +effect is entirely unpredictable. + +However, although that explanation may satisfy a language +lawyer, in practice an applications programmer expects an +unchecked conversion involving pointers to create true +aliases and the behavior of printing 1 seems plain wrong. +In this case, the strict aliasing optimization is unwelcome. + +Indeed the compiler recognizes this possibility, and the +unchecked conversion generates a warning: + + :: + + p2.adb:5:07: warning: possible aliasing problem with type "a2" + p2.adb:5:07: warning: use -fno-strict-aliasing switch for references + p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);" + +Unfortunately the problem is recognized when compiling the body of +package `p2`, but the actual "bad" code is generated while +compiling the body of `m` and this latter compilation does not see +the suspicious `Unchecked_Conversion`. + +As implied by the warning message, there are approaches you can use to +avoid the unwanted strict aliasing optimization in a case like this. + +One possibility is to simply avoid the use of *-O2*, but +that is a bit drastic, since it throws away a number of useful +optimizations that do not involve strict aliasing assumptions. + +A less drastic approach is to compile the program using the +option *-fno-strict-aliasing*. Actually it is only the +unit containing the dereferencing of the suspicious pointer +that needs to be compiled. So in this case, if we compile +unit `m` with this switch, then we get the expected +value of zero printed. Analyzing which units might need +the switch can be painful, so a more reasonable approach +is to compile the entire program with options *-O2* +and *-fno-strict-aliasing*. If the performance is +satisfactory with this combination of options, then the +advantage is that the entire issue of possible "wrong" +optimization due to strict aliasing is avoided. + +To avoid the use of compiler switches, the configuration +pragma `No_Strict_Aliasing` with no parameters may be +used to specify that for all access types, the strict +aliasing optimization should be suppressed. + +However, these approaches are still overkill, in that they causes +all manipulations of all access values to be deoptimized. A more +refined approach is to concentrate attention on the specific +access type identified as problematic. + +First, if a careful analysis of uses of the pointer shows +that there are no possible problematic references, then +the warning can be suppressed by bracketing the +instantiation of `Unchecked_Conversion` to turn +the warning off: + + .. code-block:: ada + + pragma Warnings (Off); + function to_a2u is + new Unchecked_Conversion (a1, a2); + pragma Warnings (On); + +Of course that approach is not appropriate for this particular +example, since indeed there is a problematic reference. In this +case we can take one of two other approaches. + +The first possibility is to move the instantiation of unchecked +conversion to the unit in which the type is declared. In +this example, we would move the instantiation of +`Unchecked_Conversion` from the body of package +`p2` to the spec of package `p1`. Now the +warning disappears. That's because any use of the +access type knows there is a suspicious unchecked +conversion, and the strict aliasing optimization +is automatically suppressed for the type. + +If it is not practical to move the unchecked conversion to the same unit +in which the destination access type is declared (perhaps because the +source type is not visible in that unit), you may use pragma +`No_Strict_Aliasing` for the type. This pragma must occur in the +same declarative sequence as the declaration of the access type: + + .. code-block:: ada + + type a2 is access int2; + pragma No_Strict_Aliasing (a2); + +Here again, the compiler now knows that the strict aliasing optimization +should be suppressed for any reference to type `a2` and the +expected behavior is obtained. + +Finally, note that although the compiler can generate warnings for +simple cases of unchecked conversions, there are tricker and more +indirect ways of creating type incorrect aliases which the compiler +cannot detect. Examples are the use of address overlays and unchecked +conversions involving composite types containing access types as +components. In such cases, no warnings are generated, but there can +still be aliasing problems. One safe coding practice is to forbid the +use of address clauses for type overlaying, and to allow unchecked +conversion only for primitive types. This is not really a significant +restriction since any possible desired effect can be achieved by +unchecked conversion of access values. + +The aliasing analysis done in strict aliasing mode can certainly +have significant benefits. We have seen cases of large scale +application code where the time is increased by up to 5% by turning +this optimization off. If you have code that includes significant +usage of unchecked conversion, you might want to just stick with +*-O1* and avoid the entire issue. If you get adequate +performance at this level of optimization level, that's probably +the safest approach. If tests show that you really need higher +levels of optimization, then you can experiment with *-O2* +and *-O2 -fno-strict-aliasing* to see how much effect this +has on size and speed of the code. If you really need to use +*-O2* with strict aliasing in effect, then you should +review any uses of unchecked conversion of access types, +particularly if you are getting the warnings described above. + + +.. _Aliased_Variables_and_Optimization: + +Aliased Variables and Optimization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Aliasing + +There are scenarios in which programs may +use low level techniques to modify variables +that otherwise might be considered to be unassigned. For example, +a variable can be passed to a procedure by reference, which takes +the address of the parameter and uses the address to modify the +variable's value, even though it is passed as an IN parameter. +Consider the following example: + + .. code-block:: ada + + procedure P is + Max_Length : constant Natural := 16; + type Char_Ptr is access all Character; + + procedure Get_String(Buffer: Char_Ptr; Size : Integer); + pragma Import (C, Get_String, "get_string"); + + Name : aliased String (1 .. Max_Length) := (others => ' '); + Temp : Char_Ptr; + + function Addr (S : String) return Char_Ptr is + function To_Char_Ptr is + new Ada.Unchecked_Conversion (System.Address, Char_Ptr); + begin + return To_Char_Ptr (S (S'First)'Address); + end; + + begin + Temp := Addr (Name); + Get_String (Temp, Max_Length); + end; + +where Get_String is a C function that uses the address in Temp to +modify the variable `Name`. This code is dubious, and arguably +erroneous, and the compiler would be entitled to assume that +`Name` is never modified, and generate code accordingly. + +However, in practice, this would cause some existing code that +seems to work with no optimization to start failing at high +levels of optimzization. + +What the compiler does for such cases is to assume that marking +a variable as aliased indicates that some "funny business" may +be going on. The optimizer recognizes the aliased keyword and +inhibits optimizations that assume the value cannot be assigned. +This means that the above example will in fact "work" reliably, +that is, it will produce the expected results. + + +.. _Atomic_Variables_and_Optimization: + +Atomic Variables and Optimization +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Atomic + +There are two considerations with regard to performance when +atomic variables are used. + +First, the RM only guarantees that access to atomic variables +be atomic, it has nothing to say about how this is achieved, +though there is a strong implication that this should not be +achieved by explicit locking code. Indeed GNAT will never +generate any locking code for atomic variable access (it will +simply reject any attempt to make a variable or type atomic +if the atomic access cannot be achieved without such locking code). + +That being said, it is important to understand that you cannot +assume that the entire variable will always be accessed. Consider +this example: + + .. code-block:: ada + + type R is record + A,B,C,D : Character; + end record; + for R'Size use 32; + for R'Alignment use 4; + + RV : R; + pragma Atomic (RV); + X : Character; + ... + X := RV.B; + +You cannot assume that the reference to `RV.B` +will read the entire 32-bit +variable with a single load instruction. It is perfectly legitimate if +the hardware allows it to do a byte read of just the B field. This read +is still atomic, which is all the RM requires. GNAT can and does take +advantage of this, depending on the architecture and optimization level. +Any assumption to the contrary is non-portable and risky. Even if you +examine the assembly language and see a full 32-bit load, this might +change in a future version of the compiler. + +If your application requires that all accesses to `RV` in this +example be full 32-bit loads, you need to make a copy for the access +as in: + + .. code-block:: ada + + declare + RV_Copy : constant R := RV; + begin + X := RV_Copy.B; + end; + +Now the reference to RV must read the whole variable. +Actually one can imagine some compiler which figures +out that the whole copy is not required (because only +the B field is actually accessed), but GNAT +certainly won't do that, and we don't know of any +compiler that would not handle this right, and the +above code will in practice work portably across +all architectures (that permit the Atomic declaration). + +The second issue with atomic variables has to do with +the possible requirement of generating synchronization +code. For more details on this, consult the sections on +the pragmas Enable/Disable_Atomic_Synchronization in the +GNAT Reference Manual. If performance is critical, and +such synchronization code is not required, it may be +useful to disable it. + + +.. _Passive_Task_Optimization: + +Passive Task Optimization +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Passive Task + +A passive task is one which is sufficiently simple that +in theory a compiler could recognize it an implement it +efficiently without creating a new thread. The original design +of Ada 83 had in mind this kind of passive task optimization, but +only a few Ada 83 compilers attempted it. The problem was that +it was difficult to determine the exact conditions under which +the optimization was possible. The result is a very fragile +optimization where a very minor change in the program can +suddenly silently make a task non-optimizable. + +With the revisiting of this issue in Ada 95, there was general +agreement that this approach was fundamentally flawed, and the +notion of protected types was introduced. When using protected +types, the restrictions are well defined, and you KNOW that the +operations will be optimized, and furthermore this optimized +performance is fully portable. + +Although it would theoretically be possible for GNAT to attempt to +do this optimization, but it really doesn't make sense in the +context of Ada 95, and none of the Ada 95 compilers implement +this optimization as far as we know. In particular GNAT never +attempts to perform this optimization. + +In any new Ada 95 code that is written, you should always +use protected types in place of tasks that might be able to +be optimized in this manner. +Of course this does not help if you have legacy Ada 83 code +that depends on this optimization, but it is unusual to encounter +a case where the performance gains from this optimization +are significant. + +Your program should work correctly without this optimization. If +you have performance problems, then the most practical +approach is to figure out exactly where these performance problems +arise, and update those particular tasks to be protected types. Note +that typically clients of the tasks who call entries, will not have +to be modified, only the task definition itself. + + +.. _Text_IO_Suggestions: + +`Text_IO` Suggestions +--------------------- + +.. index:: Text_IO and performance + +The `Ada.Text_IO` package has fairly high overheads due in part to +the requirement of maintaining page and line counts. If performance +is critical, a recommendation is to use `Stream_IO` instead of +`Text_IO` for volume output, since this package has less overhead. + +If `Text_IO` must be used, note that by default output to the standard +output and standard error files is unbuffered (this provides better +behavior when output statements are used for debugging, or if the +progress of a program is observed by tracking the output, e.g. by +using the Unix *tail -f* command to watch redirected output. + +If you are generating large volumes of output with `Text_IO` and +performance is an important factor, use a designated file instead +of the standard output file, or change the standard output file to +be buffered using `Interfaces.C_Streams.setvbuf`. + + +.. _Reducing_Size_of_Executables_with_Unused_Subprogram/Data_Elimination: + +Reducing Size of Executables with Unused Subprogram/Data Elimination +-------------------------------------------------------------------- + +.. index:: Uunused subprogram/data elimination + +This section describes how you can eliminate unused subprograms and data from +your executable just by setting options at compilation time. + +.. _About_unused_subprogram/data_elimination: + +About unused subprogram/data elimination +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +By default, an executable contains all code and data of its composing objects +(directly linked or coming from statically linked libraries), even data or code +never used by this executable. + +This feature will allow you to eliminate such unused code from your +executable, making it smaller (in disk and in memory). + +This functionality is available on all Linux platforms except for the IA-64 +architecture and on all cross platforms using the ELF binary file format. +In both cases GNU binutils version 2.16 or later are required to enable it. + +.. _Compilation_options: + +Compilation options +^^^^^^^^^^^^^^^^^^^ + +The operation of eliminating the unused code and data from the final executable +is directly performed by the linker. + +.. index:: -ffunction-sections (gcc) +.. index:: -fdata-sections (gcc) + +In order to do this, it has to work with objects compiled with the +following options: +*-ffunction-sections* *-fdata-sections*. + +These options are usable with C and Ada files. +They will place respectively each +function or data in a separate section in the resulting object file. + +Once the objects and static libraries are created with these options, the +linker can perform the dead code elimination. You can do this by setting +the *-Wl,--gc-sections* option to gcc command or in the +*-largs* section of *gnatmake*. This will perform a +garbage collection of code and data never referenced. + +If the linker performs a partial link (*-r* linker option), then you +will need to provide the entry point using the *-e* / *--entry* +linker option. + +Note that objects compiled without the *-ffunction-sections* and +*-fdata-sections* options can still be linked with the executable. +However, no dead code elimination will be performed on those objects (they will +be linked as is). + +The GNAT static library is now compiled with -ffunction-sections and +-fdata-sections on some platforms. This allows you to eliminate the unused code +and data of the GNAT library from your executable. + + +.. _Example_of_unused_subprogram/data_elimination: + +Example of unused subprogram/data elimination +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Here is a simple example: + + .. code-block:: ada + + with Aux; + + procedure Test is + begin + Aux.Used (10); + end Test; + + package Aux is + Used_Data : Integer; + Unused_Data : Integer; + + procedure Used (Data : Integer); + procedure Unused (Data : Integer); + end Aux; + + package body Aux is + procedure Used (Data : Integer) is + begin + Used_Data := Data; + end Used; + + procedure Unused (Data : Integer) is + begin + Unused_Data := Data; + end Unused; + end Aux; + +`Unused` and `Unused_Data` are never referenced in this code +excerpt, and hence they may be safely removed from the final executable. + + :: + + $ gnatmake test + + $ nm test | grep used + 020015f0 T aux__unused + 02005d88 B aux__unused_data + 020015cc T aux__used + 02005d84 B aux__used_data + + $ gnatmake test -cargs -fdata-sections -ffunction-sections \\ + -largs -Wl,--gc-sections + + $ nm test | grep used + 02005350 T aux__used + 0201ffe0 B aux__used_data + +It can be observed that the procedure `Unused` and the object +`Unused_Data` are removed by the linker when using the +appropriate options. + +.. only:: PRO or GPL + + .. _Reducing_Size_of_Ada_Executables_with_gnatelim: + + Reducing Size of Ada Executables with `gnatelim` + ------------------------------------------------ + + .. index:: gnatelim + + This section describes *gnatelim*, a tool which detects unused + subprograms and helps the compiler to create a smaller executable for your + program. + + .. _About_gnatelim: + + About `gnatelim` + ^^^^^^^^^^^^^^^^ + + When a program shares a set of Ada + packages with other programs, it may happen that this program uses + only a fraction of the subprograms defined in these packages. The code + created for these unused subprograms increases the size of the executable. + + `gnatelim` tracks unused subprograms in an Ada program and + outputs a list of GNAT-specific pragmas `Eliminate` marking all the + subprograms that are declared but never called. By placing the list of + `Eliminate` pragmas in the GNAT configuration file :file:`gnat.adc` and + recompiling your program, you may decrease the size of its executable, + because the compiler will not generate the code for 'eliminated' subprograms. + See `Pragma_Eliminate` in the :title:`GNAT_Reference_Manual` for more + information about this pragma. + + `gnatelim` needs as its input data the name of the main subprogram. + + If a set of source files is specified as `gnatelim` arguments, it + treats these files as a complete set of sources making up a program to + analyse, and analyses only these sources. + + After a full successful build of the main subprogram `gnatelim` can be + called without specifying sources to analyse, in this case it computes + the source closure of the main unit from the :file:`ALI` files. + + If the set of sources to be processed by `gnatelim` contains sources with + preprocessing directives + then the needed options should be provided to run preprocessor as a part of + the *gnatelim* call, and the generated set of pragmas `Eliminate` + will correspond to preprocessed sources. + + The following command will create the set of :file:`ALI` files needed for + `gnatelim`: + + :: + + $ gnatmake -c Main_Prog + + Note that `gnatelim` does not need object files. + + + .. _Running_gnatelim: + + Running `gnatelim` + ^^^^^^^^^^^^^^^^^^ + + `gnatelim` has the following command-line interface: + + + :: + + $ gnatelim [`switches`] -main=`main_unit_name` {`filename`} [-cargs `gcc_switches`] + + `main_unit_name` should be a name of a source file that contains the main + subprogram of a program (partition). + + Each `filename` is the name (including the extension) of a source + file to process. 'Wildcards' are allowed, and + the file name may contain path information. + + `gcc_switches` is a list of switches for + *gcc*. They will be passed on to all compiler invocations made by + *gnatelim* to generate the ASIS trees. Here you can provide + *-I* switches to form the source search path, + use the *-gnatec* switch to set the configuration file, + use the *-gnat05* switch if sources should be compiled in + Ada 2005 mode etc. + + `gnatelim` has the following switches: + + + .. index:: --version (gnatelim) + + :samp:`--version` + Display Copyright and version, then exit disregarding all other options. + + + .. index:: --help (gnatelim) + + :samp:`--help` + Display usage, then exit disregarding all other options. + + + .. index:: -P (gnatelim) + + :samp:`-P {file}` + Indicates the name of the project file that describes the set of sources + to be processed. + + + .. index:: -X (gnatelim) + + :samp:`-X{name}={value}` + Indicates that external variable `name` in the argument project + has the value `value`. Has no effect if no project is specified as + tool argument. + + + .. index:: --RTS (gnatelim) + + :samp:`--RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + + .. index:: -files (gnatelim) + + :samp:`-files={filename}` + Take the argument source files from the specified file. This file should be an + ordinary text file containing file names separated by spaces or + line breaks. You can use this switch more than once in the same call to + *gnatelim*. You also can combine this switch with + an explicit list of files. + + + .. index:: -log (gnatelim) + + :samp:`-log` + Duplicate all the output sent to :file:`stderr` into a log file. The log file + is named :file:`gnatelim.log` and is located in the current directory. + + .. index:: --no-elim-dispatch (gnatelim) + + :samp:`--no-elim-dispatch` + Do not generate pragmas for dispatching operations. + + + .. index:: --ignore (gnatelim) + + :samp:`--ignore={filename}` + Do not generate pragmas for subprograms declared in the sources + listed in a specified file + + .. index:: -o (gnatelim) + + + :samp:`-o={report_file}` + Put *gnatelim* output into a specified file. If this file already exists, + it is overridden. If this switch is not used, *gnatelim* outputs its results + into :file:`stderr` + + + .. index:: -j (gnatelim) + + :samp:`-j{n}` + Use `n` processes to carry out the tree creations (internal representations + of the argument sources). On a multiprocessor machine this speeds up processing + of big sets of argument sources. If `n` is 0, then the maximum number of + parallel tree creations is the number of core processors on the platform. + + + .. index:: -q (gnatelim) + + :samp:`-q` + Quiet mode: by default `gnatelim` outputs to the standard error + stream the number of program units left to be processed. This option turns + this trace off. + + .. index:: -t (gnatelim) + + + :samp:`-t` + Print out execution time. + + + .. index:: -v (gnatelim) + + :samp:`-v` + Verbose mode: `gnatelim` version information is printed as Ada + comments to the standard output stream. Also, in addition to the number of + program units left `gnatelim` will output the name of the current unit + being processed. + + + .. index:: -wq (gnatelim) + + :samp:`-wq` + Quiet warning mode - some warnings are suppressed. In particular warnings that + indicate that the analysed set of sources is incomplete to make up a + partition and that some subprogram bodies are missing are not generated. + + Note: to invoke *gnatelim* with a project file, use the `gnat` + driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + + + .. _Processing_Precompiled_Libraries: + + Processing Precompiled Libraries + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + If some program uses a precompiled Ada library, it can be processed by + `gnatelim` in a usual way. `gnatelim` will newer generate an + Eliminate pragma for a subprogram if the body of this subprogram has not + been analysed, this is a typical case for subprograms from precompiled + libraries. Switch *-wq* may be used to suppress + warnings about missing source files and non-analyzed subprogram bodies + that can be generated when processing precompiled Ada libraries. + + + .. _Correcting_the_List_of_Eliminate_Pragmas: + + Correcting the List of Eliminate Pragmas + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + In some rare cases `gnatelim` may try to eliminate + subprograms that are actually called in the program. In this case, the + compiler will generate an error message of the form: + + :: + + main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5 + + You will need to manually remove the wrong `Eliminate` pragmas from + the configuration file indicated in the error message. You should recompile + your program from scratch after that, because you need a consistent + configuration file(s) during the entire compilation. + + + .. _Making_Your_Executables_Smaller: + + Making Your Executables Smaller + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + In order to get a smaller executable for your program you now have to + recompile the program completely with the configuration file containing + pragmas Eliminate generated by gnatelim. If these pragmas are placed in + :file:`gnat.adc` file located in your current directory, just do: + + :: + + $ gnatmake -f main_prog + + (Use the *-f* option for *gnatmake* to + recompile everything + with the set of pragmas `Eliminate` that you have obtained with + *gnatelim*). + + Be aware that the set of `Eliminate` pragmas is specific to each + program. It is not recommended to merge sets of `Eliminate` + pragmas created for different programs in one configuration file. + + + .. _Summary_of_the_gnatelim_Usage_Cycle: + + Summary of the `gnatelim` Usage Cycle + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + Here is a quick summary of the steps to be taken in order to reduce + the size of your executables with `gnatelim`. You may use + other GNAT options to control the optimization level, + to produce the debugging information, to set search path, etc. + + * Create a complete set of :file:`ALI` files (if the program has not been + built already) + + :: + + $ gnatmake -c main_prog + + * Generate a list of `Eliminate` pragmas in default configuration file + :file:`gnat.adc` in the current directory + + :: + + $ gnatelim main_prog >[>] gnat.adc + + * Recompile the application + + :: + + $ gnatmake -f main_prog + + + +.. index:: Overflow checks +.. index:: Checks (overflow) + +.. _Overflow_Check_Handling_in_GNAT: + +Overflow Check Handling in GNAT +=============================== + +This section explains how to control the handling of overflow checks. + +.. _Background: + +Background +---------- + +Overflow checks are checks that the compiler may make to ensure +that intermediate results are not out of range. For example: + + .. code-block:: ada + + A : Integer; + ... + A := A + 1; + +If `A` has the value `Integer'Last`, then the addition may cause +overflow since the result is out of range of the type `Integer`. +In this case `Constraint_Error` will be raised if checks are +enabled. + +A trickier situation arises in examples like the following: + + .. code-block:: ada + + A, C : Integer; + ... + A := (A + 1) + C; + +where `A` is `Integer'Last` and `C` is `-1`. +Now the final result of the expression on the right hand side is +`Integer'Last` which is in range, but the question arises whether the +intermediate addition of `(A + 1)` raises an overflow error. + +The (perhaps surprising) answer is that the Ada language +definition does not answer this question. Instead it leaves +it up to the implementation to do one of two things if overflow +checks are enabled. + +* raise an exception (`Constraint_Error`), or + +* yield the correct mathematical result which is then used in + subsequent operations. + +If the compiler chooses the first approach, then the assignment of this +example will indeed raise `Constraint_Error` if overflow checking is +enabled, or result in erroneous execution if overflow checks are suppressed. + +But if the compiler +chooses the second approach, then it can perform both additions yielding +the correct mathematical result, which is in range, so no exception +will be raised, and the right result is obtained, regardless of whether +overflow checks are suppressed. + +Note that in the first example an +exception will be raised in either case, since if the compiler +gives the correct mathematical result for the addition, it will +be out of range of the target type of the assignment, and thus +fails the range check. + +This lack of specified behavior in the handling of overflow for +intermediate results is a source of non-portability, and can thus +be problematic when programs are ported. Most typically this arises +in a situation where the original compiler did not raise an exception, +and then the application is moved to a compiler where the check is +performed on the intermediate result and an unexpected exception is +raised. + +Furthermore, when using Ada 2012's preconditions and other +assertion forms, another issue arises. Consider: + + .. code-block:: ada + + procedure P (A, B : Integer) with + Pre => A + B <= Integer'Last; + +One often wants to regard arithmetic in a context like this from +a mathematical point of view. So for example, if the two actual parameters +for a call to `P` are both `Integer'Last`, then +the precondition should be regarded as False. If we are executing +in a mode with run-time checks enabled for preconditions, then we would +like this precondition to fail, rather than raising an exception +because of the intermediate overflow. + +However, the language definition leaves the specification of +whether the above condition fails (raising `Assert_Error`) or +causes an intermediate overflow (raising `Constraint_Error`) +up to the implementation. + +The situation is worse in a case such as the following: + + .. code-block:: ada + + procedure Q (A, B, C : Integer) with + Pre => A + B + C <= Integer'Last; + +Consider the call + + .. code-block:: ada + + Q (A => Integer'Last, B => 1, C => -1); + +From a mathematical point of view the precondition +is True, but at run time we may (but are not guaranteed to) get an +exception raised because of the intermediate overflow (and we really +would prefer this precondition to be considered True at run time). + + +.. _Overflow_Checking_Modes_in_GNAT: + +Overflow Checking Modes in GNAT +------------------------------- + +To deal with the portability issue, and with the problem of +mathematical versus run-time interpretation of the expressions in +assertions, GNAT provides comprehensive control over the handling +of intermediate overflow. GNAT can operate in three modes, and +furthemore, permits separate selection of operating modes for +the expressions within assertions (here the term 'assertions' +is used in the technical sense, which includes preconditions and so forth) +and for expressions appearing outside assertions. + +The three modes are: + +* *Use base type for intermediate operations* (`STRICT`) + + In this mode, all intermediate results for predefined arithmetic + operators are computed using the base type, and the result must + be in range of the base type. If this is not the + case then either an exception is raised (if overflow checks are + enabled) or the execution is erroneous (if overflow checks are suppressed). + This is the normal default mode. + +* *Most intermediate overflows avoided* (`MINIMIZED`) + + In this mode, the compiler attempts to avoid intermediate overflows by + using a larger integer type, typically `Long_Long_Integer`, + as the type in which arithmetic is + performed for predefined arithmetic operators. This may be slightly more + expensive at + run time (compared to suppressing intermediate overflow checks), though + the cost is negligible on modern 64-bit machines. For the examples given + earlier, no intermediate overflows would have resulted in exceptions, + since the intermediate results are all in the range of + `Long_Long_Integer` (typically 64-bits on nearly all implementations + of GNAT). In addition, if checks are enabled, this reduces the number of + checks that must be made, so this choice may actually result in an + improvement in space and time behavior. + + However, there are cases where `Long_Long_Integer` is not large + enough, consider the following example: + + .. code-block:: ada + + procedure R (A, B, C, D : Integer) with + Pre => (A**2 * B**2) / (C**2 * D**2) <= 10; + + where `A` = `B` = `C` = `D` = `Integer'Last`. + Now the intermediate results are + out of the range of `Long_Long_Integer` even though the final result + is in range and the precondition is True (from a mathematical point + of view). In such a case, operating in this mode, an overflow occurs + for the intermediate computation (which is why this mode + says *most* intermediate overflows are avoided). In this case, + an exception is raised if overflow checks are enabled, and the + execution is erroneous if overflow checks are suppressed. + +* *All intermediate overflows avoided* (`ELIMINATED`) + + In this mode, the compiler avoids all intermediate overflows + by using arbitrary precision arithmetic as required. In this + mode, the above example with `A**2 * B**2` would + not cause intermediate overflow, because the intermediate result + would be evaluated using sufficient precision, and the result + of evaluating the precondition would be True. + + This mode has the advantage of avoiding any intermediate + overflows, but at the expense of significant run-time overhead, + including the use of a library (included automatically in this + mode) for multiple-precision arithmetic. + + This mode provides cleaner semantics for assertions, since now + the run-time behavior emulates true arithmetic behavior for the + predefined arithmetic operators, meaning that there is never a + conflict between the mathematical view of the assertion, and its + run-time behavior. + + Note that in this mode, the behavior is unaffected by whether or + not overflow checks are suppressed, since overflow does not occur. + It is possible for gigantic intermediate expressions to raise + `Storage_Error` as a result of attempting to compute the + results of such expressions (e.g. `Integer'Last ** Integer'Last`) + but overflow is impossible. + + +Note that these modes apply only to the evaluation of predefined +arithmetic, membership, and comparison operators for signed integer +aritmetic. + +For fixed-point arithmetic, checks can be suppressed. But if checks +are enabled +then fixed-point values are always checked for overflow against the +base type for intermediate expressions (that is such checks always +operate in the equivalent of `STRICT` mode). + +For floating-point, on nearly all architectures, `Machine_Overflows` +is False, and IEEE infinities are generated, so overflow exceptions +are never raised. If you want to avoid infinities, and check that +final results of expressions are in range, then you can declare a +constrained floating-point type, and range checks will be carried +out in the normal manner (with infinite values always failing all +range checks). + + +.. _Specifying_the_Desired_Mode: + +Specifying the Desired Mode +--------------------------- + +.. index:: pragma Overflow_Mode + +The desired mode of for handling intermediate overflow can be specified using +either the `Overflow_Mode` pragma or an equivalent compiler switch. +The pragma has the form + + .. code-block:: ada + + pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]); + +where `MODE` is one of + +* `STRICT`: intermediate overflows checked (using base type) +* `MINIMIZED`: minimize intermediate overflows +* `ELIMINATED`: eliminate intermediate overflows + +The case is ignored, so `MINIMIZED`, `Minimized` and +`minimized` all have the same effect. + +If only the `General` parameter is present, then the given `MODE` +applies +to expressions both within and outside assertions. If both arguments +are present, then `General` applies to expressions outside assertions, +and `Assertions` applies to expressions within assertions. For example: + + .. code-block:: ada + + pragma Overflow_Mode + (General => Minimized, Assertions => Eliminated); + +specifies that general expressions outside assertions be evaluated +in 'minimize intermediate overflows' mode, and expressions within +assertions be evaluated in 'eliminate intermediate overflows' mode. +This is often a reasonable choice, avoiding excessive overhead +outside assertions, but assuring a high degree of portability +when importing code from another compiler, while incurring +the extra overhead for assertion expressions to ensure that +the behavior at run time matches the expected mathematical +behavior. + +The `Overflow_Mode` pragma has the same scoping and placement +rules as pragma `Suppress`, so it can occur either as a +configuration pragma, specifying a default for the whole +program, or in a declarative scope, where it applies to the +remaining declarations and statements in that scope. + +Note that pragma `Overflow_Mode` does not affect whether +overflow checks are enabled or suppressed. It only controls the +method used to compute intermediate values. To control whether +overflow checking is enabled or suppressed, use pragma `Suppress` +or `Unsuppress` in the usual manner + + +.. index:: -gnato? (gcc) +.. index:: -gnato?? (gcc) + +Additionally, a compiler switch *-gnato?* or *-gnato??* +can be used to control the checking mode default (which can be subsequently +overridden using pragmas). + +Here ``?`` is one of the digits ``1`` through ``3``: + + ====== ===================================================== + ``1`` use base type for intermediate operations (`STRICT`) + ``2`` minimize intermediate overflows (`MINIMIZED`) + ``3`` eliminate intermediate overflows (`ELIMINATED`) + ====== ===================================================== + +As with the pragma, if only one digit appears then it applies to all +cases; if two digits are given, then the first applies outside +assertions, and the second within assertions. Thus the equivalent +of the example pragma above would be +*-gnato23*. + +If no digits follow the *-gnato*, then it is equivalent to +*-gnato11*, +causing all intermediate operations to be computed using the base +type (`STRICT` mode). + +In addition to setting the mode used for computation of intermediate +results, the `-gnato` switch also enables overflow checking (which +is suppressed by default). It thus combines the effect of using +a pragma `Overflow_Mode` and pragma `Unsuppress`. + +.. _Default_Settings: + +Default Settings +---------------- + +The default mode for overflow checks is + + :: + + General => Strict + +which causes all computations both inside and outside assertions to use +the base type. In addition overflow checks are suppressed. + +This retains compatibility with previous versions of +GNAT which suppressed overflow checks by default and always +used the base type for computation of intermediate results. + +The switch *-gnato* (with no digits following) is equivalent to +.. index:: -gnato (gcc) + + :: + + General => Strict + +which causes overflow checking of all intermediate overflows +both inside and outside assertions against the base type. +This provides compatibility +with this switch as implemented in previous versions of GNAT. + +The pragma `Suppress (Overflow_Check)` disables overflow +checking, but it has no effect on the method used for computing +intermediate results. + +The pragma `Unsuppress (Overflow_Check)` enables overflow +checking, but it has no effect on the method used for computing +intermediate results. + + +.. _Implementation_Notes: + +Implementation Notes +-------------------- + +In practice on typical 64-bit machines, the `MINIMIZED` mode is +reasonably efficient, and can be generally used. It also helps +to ensure compatibility with code imported from some other +compiler to GNAT. + +Setting all intermediate overflows checking (`CHECKED` mode) +makes sense if you want to +make sure that your code is compatible with any other possible +Ada implementation. This may be useful in ensuring portability +for code that is to be exported to some other compiler than GNAT. + +The Ada standard allows the reassociation of expressions at +the same precedence level if no parentheses are present. For +example, `A+B+C` parses as though it were `(A+B)+C`, but +the compiler can reintepret this as `A+(B+C)`, possibly +introducing or eliminating an overflow exception. The GNAT +compiler never takes advantage of this freedom, and the +expression `A+B+C` will be evaluated as `(A+B)+C`. +If you need the other order, you can write the parentheses +explicitly `A+(B+C)` and GNAT will respect this order. + +The use of `ELIMINATED` mode will cause the compiler to +automatically include an appropriate arbitrary precision +integer arithmetic package. The compiler will make calls +to this package, though only in cases where it cannot be +sure that `Long_Long_Integer` is sufficient to guard against +intermediate overflows. This package does not use dynamic +alllocation, but it does use the secondary stack, so an +appropriate secondary stack package must be present (this +is always true for standard full Ada, but may require +specific steps for restricted run times such as ZFP). + +Although `ELIMINATED` mode causes expressions to use arbitrary +precision arithmetic, avoiding overflow, the final result +must be in an appropriate range. This is true even if the +final result is of type `[Long_[Long_]]Integer'Base`, which +still has the same bounds as its associated constrained +type at run-time. + +Currently, the `ELIMINATED` mode is only available on target +platforms for which `Long_Long_Integer` is 64-bits (nearly all GNAT +platforms). + + + +.. _Performing_Dimensionality_Analysis_in_GNAT: + +Performing Dimensionality Analysis in GNAT +========================================== + +.. index:: Dimensionality analysis + +The GNAT compiler supports dimensionality checking. The user can +specify physical units for objects, and the compiler will verify that uses +of these objects are compatible with their dimensions, in a fashion that is +familiar to engineering practice. The dimensions of algebraic expressions +(including powers with static exponents) are computed from their constituents. + +.. index:: Dimension_System aspect +.. index:: Dimension aspect + +This feature depends on Ada 2012 aspect specifications, and is available from +version 7.0.1 of GNAT onwards. +The GNAT-specific aspect `Dimension_System` +allows you to define a system of units; the aspect `Dimension` +then allows the user to declare dimensioned quantities within a given system. +(These aspects are described in the *Implementation Defined Aspects* +chapter of the *GNAT Reference Manual*). + +The major advantage of this model is that it does not require the declaration of +multiple operators for all possible combinations of types: it is only necessary +to use the proper subtypes in object declarations. + +.. index:: System.Dim.Mks package (GNAT library) +.. index:: MKS_Type type + +The simplest way to impose dimensionality checking on a computation is to make +use of the package `System.Dim.Mks`, +which is part of the GNAT library. This +package defines a floating-point type `MKS_Type`, +for which a sequence of +dimension names are specified, together with their conventional abbreviations. +The following should be read together with the full specification of the +package, in file :file:`s-dimmks.ads`. + + .. index:: s-dimmks.ads file + + .. 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 => "Theta"), + (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'), + (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J')); + +The package then defines a series of subtypes that correspond to these +conventional units. For example: + + .. code-block:: ada + + subtype Length is Mks_Type + with + Dimension => (Symbol => 'm', Meter => 1, others => 0); + +and similarly for `Mass`, `Time`, `Electric_Current`, +`Thermodynamic_Temperature`, `Amount_Of_Substance`, and +`Luminous_Intensity` (the standard set of units of the SI system). + +The package also defines conventional names for values of each unit, for +example: + + .. code-block":: ada + + m : constant Length := 1.0; + kg : constant Mass := 1.0; + s : constant Time := 1.0; + A : constant Electric_Current := 1.0; + +as well as useful multiples of these units: + + .. code-block:: ada + + cm : constant Length := 1.0E-02; + g : constant Mass := 1.0E-03; + min : constant Time := 60.0; + day : constant Time := 60.0 * 24.0 * min; + ... + +Using this package, you can then define a derived unit by +providing the aspect that +specifies its dimensions within the MKS system, as well as the string to +be used for output of a value of that unit: + + .. code-block:: ada + + subtype Acceleration is Mks_Type + with Dimension => ("m/sec^2", + Meter => 1, + Second => -2, + others => 0); + +Here is a complete example of use: + + .. code-block:: ada + + with System.Dim.MKS; use System.Dim.Mks; + with System.Dim.Mks_IO; use System.Dim.Mks_IO; + with Text_IO; use Text_IO; + procedure Free_Fall is + subtype Acceleration is Mks_Type + with Dimension => ("m/sec^2", 1, 0, -2, others => 0); + G : constant acceleration := 9.81 * m / (s ** 2); + T : Time := 10.0*s; + Distance : Length; + + begin + Put ("Gravitational constant: "); + Put (G, Aft => 2, Exp => 0); Put_Line (""); + Distance := 0.5 * G * T ** 2; + Put ("distance travelled in 10 seconds of free fall "); + Put (Distance, Aft => 2, Exp => 0); + Put_Line (""); + end Free_Fall; + +Execution of this program yields: + + :: + + Gravitational constant: 9.81 m/sec^2 + distance travelled in 10 seconds of free fall 490.50 m + +However, incorrect assignments such as: + + .. code-block:: ada + + Distance := 5.0; + Distance := 5.0 * kg: + +are rejected with the following diagnoses: + + :: + + Distance := 5.0; + >>> dimensions mismatch in assignment + >>> left-hand side has dimension [L] + >>> right-hand side is dimensionless + + Distance := 5.0 * kg: + >>> dimensions mismatch in assignment + >>> left-hand side has dimension [L] + >>> right-hand side has dimension [M] + +The dimensions of an expression are properly displayed, even if there is +no explicit subtype for it. If we add to the program: + + .. code-block:: ada + + Put ("Final velocity: "); + Put (G * T, Aft =>2, Exp =>0); + Put_Line (""); + +then the output includes: + + :: + + Final velocity: 98.10 m.s**(-1) + + + +.. _Stack_Related_Facilities: + +Stack Related Facilities +======================== + +This section describes some useful tools associated with stack +checking and analysis. In +particular, it deals with dynamic and static stack usage measurements. + +.. _Stack_Overflow_Checking: + +Stack Overflow Checking +----------------------- + +.. index:: Stack Overflow Checking + +.. index:: -fstack-check (gcc) + +For most operating systems, *gcc* does not perform stack overflow +checking by default. This means that if the main environment task or +some other task exceeds the available stack space, then unpredictable +behavior will occur. Most native systems offer some level of protection by +adding a guard page at the end of each task stack. This mechanism is usually +not enough for dealing properly with stack overflow situations because +a large local variable could "jump" above the guard page. +Furthermore, when the +guard page is hit, there may not be any space left on the stack for executing +the exception propagation code. Enabling stack checking avoids +such situations. + +To activate stack checking, compile all units with the gcc option +`-fstack-check`. For example: + + :: + + $ gcc -c -fstack-check package1.adb + +Units compiled with this option will generate extra instructions to check +that any use of the stack (for procedure calls or for declaring local +variables in declare blocks) does not exceed the available stack space. +If the space is exceeded, then a `Storage_Error` exception is raised. + +For declared tasks, the stack size is controlled by the size +given in an applicable `Storage_Size` pragma or by the value specified +at bind time with ``-d`` (:ref:`Switches_for_gnatbind`) or is set to +the default size as defined in the GNAT runtime otherwise. + +.. index:: GNAT_STACK_LIMIT + +For the environment task, the stack size depends on +system defaults and is unknown to the compiler. Stack checking +may still work correctly if a fixed +size stack is allocated, but this cannot be guaranteed. +To ensure that a clean exception is signalled for stack +overflow, set the environment variable +:envvar:`GNAT_STACK_LIMIT` to indicate the maximum +stack area that can be used, as in: + + :: + + $ SET GNAT_STACK_LIMIT 1600 + +The limit is given in kilobytes, so the above declaration would +set the stack limit of the environment task to 1.6 megabytes. +Note that the only purpose of this usage is to limit the amount +of stack used by the environment task. If it is necessary to +increase the amount of stack for the environment task, then this +is an operating systems issue, and must be addressed with the +appropriate operating systems commands. + + +.. _Static_Stack_Usage_Analysis: + +Static Stack Usage Analysis +--------------------------- + +.. index:: Static Stack Usage Analysis + +.. index:: -fstack-usage + +A unit compiled with ``-fstack-usage`` will generate an extra file +that specifies +the maximum amount of stack used, on a per-function basis. +The file has the same +basename as the target object file with a :file:`.su` extension. +Each line of this file is made up of three fields: + +* The name of the function. +* A number of bytes. +* One or more qualifiers: `static`, `dynamic`, `bounded`. + +The second field corresponds to the size of the known part of the function +frame. + +The qualifier `static` means that the function frame size +is purely static. +It usually means that all local variables have a static size. +In this case, the second field is a reliable measure of the function stack +utilization. + +The qualifier `dynamic` means that the function frame size is not static. +It happens mainly when some local variables have a dynamic size. When this +qualifier appears alone, the second field is not a reliable measure +of the function stack analysis. When it is qualified with `bounded`, it +means that the second field is a reliable maximum of the function stack +utilization. + +A unit compiled with ``-Wstack-usage`` will issue a warning for each +subprogram whose stack usage might be larger than the specified amount of +bytes. The wording is in keeping with the qualifier documented above. + + +.. _Dynamic_Stack_Usage_Analysis: + +Dynamic Stack Usage Analysis +---------------------------- + +It is possible to measure the maximum amount of stack used by a task, by +adding a switch to *gnatbind*, as: + + :: + + $ gnatbind -u0 file + +With this option, at each task termination, its stack usage is output on +:file:`stderr`. +It is not always convenient to output the stack usage when the program +is still running. Hence, it is possible to delay this output until program +termination. for a given number of tasks specified as the argument of the +``-u`` option. For instance: + + :: + + $ gnatbind -u100 file + +will buffer the stack usage information of the first 100 tasks to terminate and +output this info at program termination. Results are displayed in four +columns: + + :: + + Index | Task Name | Stack Size | Stack Usage + +where: + +* *Index* is a number associated with each task. + +* *Task Name* is the name of the task analyzed. + +* *Stack Size* is the maximum size for the stack. + +* *Stack Usage* is the measure done by the stack analyzer. + In order to prevent overflow, the stack + is not entirely analyzed, and it's not possible to know exactly how + much has actually been used. + +The environment task stack, e.g., the stack that contains the main unit, is +only processed when the environment variable GNAT_STACK_LIMIT is set. + +The package `GNAT.Task_Stack_Usage` provides facilities to get +stack usage reports at run-time. See its body for the details. + + + +.. _Memory_Management_Issues: + +Memory Management Issues +======================== + +This section describes some useful memory pools provided in the GNAT library +and in particular the GNAT Debug Pool facility, which can be used to detect +incorrect uses of access values (including 'dangling references'). + +.. only:: PRO or GPL + + It also describes the *gnatmem* tool, which can be used to track down + "memory leaks". + +.. _Some_Useful_Memory_Pools: + +Some Useful Memory Pools +------------------------ + +.. index:: Memory Pool +.. index:: storage, pool + +The `System.Pool_Global` package offers the Unbounded_No_Reclaim_Pool +storage pool. Allocations use the standard system call `malloc` while +deallocations use the standard system call `free`. No reclamation is +performed when the pool goes out of scope. For performance reasons, the +standard default Ada allocators/deallocators do not use any explicit storage +pools but if they did, they could use this storage pool without any change in +behavior. That is why this storage pool is used when the user +manages to make the default implicit allocator explicit as in this example: + + .. code-block:: ada + + type T1 is access Something; + -- no Storage pool is defined for T2 + + type T2 is access Something_Else; + for T2'Storage_Pool use T1'Storage_Pool; + -- the above is equivalent to + for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object; + +The `System.Pool_Local` package offers the Unbounded_Reclaim_Pool storage +pool. The allocation strategy is similar to `Pool_Local`'s +except that the all +storage allocated with this pool is reclaimed when the pool object goes out of +scope. This pool provides a explicit mechanism similar to the implicit one +provided by several Ada 83 compilers for allocations performed through a local +access type and whose purpose was to reclaim memory when exiting the +scope of a given local access. As an example, the following program does not +leak memory even though it does not perform explicit deallocation: + + .. code-block:: ada + + with System.Pool_Local; + procedure Pooloc1 is + procedure Internal is + type A is access Integer; + X : System.Pool_Local.Unbounded_Reclaim_Pool; + for A'Storage_Pool use X; + v : A; + begin + for I in 1 .. 50 loop + v := new Integer; + end loop; + end Internal; + begin + for I in 1 .. 100 loop + Internal; + end loop; + end Pooloc1; + +The `System.Pool_Size` package implements the Stack_Bounded_Pool used when +`Storage_Size` is specified for an access type. +The whole storage for the pool is +allocated at once, usually on the stack at the point where the access type is +elaborated. It is automatically reclaimed when exiting the scope where the +access type is defined. This package is not intended to be used directly by the +user and it is implicitly used for each such declaration: + + .. code-block:: ada + + type T1 is access Something; + for T1'Storage_Size use 10_000; + + +.. _The_GNAT_Debug_Pool_Facility: + +The GNAT Debug Pool Facility +---------------------------- + +.. index:: Debug Pool +.. index:: storage, pool, memory corruption + +The use of unchecked deallocation and unchecked conversion can easily +lead to incorrect memory references. The problems generated by such +references are usually difficult to tackle because the symptoms can be +very remote from the origin of the problem. In such cases, it is +very helpful to detect the problem as early as possible. This is the +purpose of the Storage Pool provided by `GNAT.Debug_Pools`. + +In order to use the GNAT specific debugging pool, the user must +associate a debug pool object with each of the access types that may be +related to suspected memory problems. See Ada Reference Manual 13.11. + + .. code-block:: ada + + type Ptr is access Some_Type; + Pool : GNAT.Debug_Pools.Debug_Pool; + for Ptr'Storage_Pool use Pool; + +`GNAT.Debug_Pools` is derived from a GNAT-specific kind of +pool: the `Checked_Pool`. Such pools, like standard Ada storage pools, +allow the user to redefine allocation and deallocation strategies. They +also provide a checkpoint for each dereference, through the use of +the primitive operation `Dereference` which is implicitly called at +each dereference of an access value. + +Once an access type has been associated with a debug pool, operations on +values of the type may raise four distinct exceptions, +which correspond to four potential kinds of memory corruption: + +* `GNAT.Debug_Pools.Accessing_Not_Allocated_Storage` +* `GNAT.Debug_Pools.Accessing_Deallocated_Storage` +* `GNAT.Debug_Pools.Freeing_Not_Allocated_Storage` +* `GNAT.Debug_Pools.Freeing_Deallocated_Storage` + +For types associated with a Debug_Pool, dynamic allocation is performed using +the standard GNAT allocation routine. References to all allocated chunks of +memory are kept in an internal dictionary. Several deallocation strategies are +provided, whereupon the user can choose to release the memory to the system, +keep it allocated for further invalid access checks, or fill it with an easily +recognizable pattern for debug sessions. The memory pattern is the old IBM +hexadecimal convention: `16#DEADBEEF#`. + +See the documentation in the file g-debpoo.ads for more information on the +various strategies. + +Upon each dereference, a check is made that the access value denotes a +properly allocated memory location. Here is a complete example of use of +`Debug_Pools`, that includes typical instances of memory corruption: + + .. code-block:: ada + + with Gnat.Io; use Gnat.Io; + with Unchecked_Deallocation; + with Unchecked_Conversion; + with GNAT.Debug_Pools; + with System.Storage_Elements; + with Ada.Exceptions; use Ada.Exceptions; + procedure Debug_Pool_Test is + + type T is access Integer; + type U is access all T; + + P : GNAT.Debug_Pools.Debug_Pool; + for T'Storage_Pool use P; + + procedure Free is new Unchecked_Deallocation (Integer, T); + function UC is new Unchecked_Conversion (U, T); + A, B : aliased T; + + procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line); + + begin + Info (P); + A := new Integer; + B := new Integer; + B := A; + Info (P); + Free (A); + begin + Put_Line (Integer'Image(B.all)); + exception + when E : others => Put_Line ("raised: " & Exception_Name (E)); + end; + begin + Free (B); + exception + when E : others => Put_Line ("raised: " & Exception_Name (E)); + end; + B := UC(A'Access); + begin + Put_Line (Integer'Image(B.all)); + exception + when E : others => Put_Line ("raised: " & Exception_Name (E)); + end; + begin + Free (B); + exception + when E : others => Put_Line ("raised: " & Exception_Name (E)); + end; + Info (P); + end Debug_Pool_Test; + +The debug pool mechanism provides the following precise diagnostics on the +execution of this erroneous program: + + :: + + Debug Pool info: + Total allocated bytes : 0 + Total deallocated bytes : 0 + Current Water Mark: 0 + High Water Mark: 0 + + Debug Pool info: + Total allocated bytes : 8 + Total deallocated bytes : 0 + Current Water Mark: 8 + High Water Mark: 8 + + raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE + raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE + raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE + raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE + Debug Pool info: + Total allocated bytes : 8 + Total deallocated bytes : 4 + Current Water Mark: 4 + High Water Mark: 8 + +.. only:: PRO or GPL + + .. _The_gnatmem_Tool: + + The *gnatmem* Tool + ------------------ + + .. index:: ! gnatmem + + The `gnatmem` utility monitors dynamic allocation and + deallocation activity in a program, and displays information about + incorrect deallocations and possible sources of memory leaks. + It is designed to work in association with a static runtime library + only and in this context provides three types of information: + + * General information concerning memory management, such as the total + number of allocations and deallocations, the amount of allocated + memory and the high water mark, i.e., the largest amount of allocated + memory in the course of program execution. + + * Backtraces for all incorrect deallocations, that is to say deallocations + which do not correspond to a valid allocation. + + * Information on each allocation that is potentially the origin of a memory + leak. + + .. _Running_gnatmem: + + Running `gnatmem` + ^^^^^^^^^^^^^^^^^ + + `gnatmem` makes use of the output created by the special version of + allocation and deallocation routines that record call information. This allows + it to obtain accurate dynamic memory usage history at a minimal cost to the + execution speed. Note however, that `gnatmem` is not supported on all + platforms (currently, it is supported on AIX, HP-UX, GNU/Linux, Solaris and + Windows NT/2000/XP (x86). + + The `gnatmem` command has the form + + :: + + $ gnatmem [`switches`] `user_program` + + The program must have been linked with the instrumented version of the + allocation and deallocation routines. This is done by linking with the + :file:`libgmem.a` library. For correct symbolic backtrace information, + the user program should be compiled with debugging options + (see :ref:`Switches_for_gcc`). For example to build :file:`my_program`: + + :: + + $ gnatmake -g my_program -largs -lgmem + + As library :file:`libgmem.a` contains an alternate body for package + `System.Memory`, :file:`s-memory.adb` should not be compiled and linked + when an executable is linked with library :file:`libgmem.a`. It is then not + recommended to use *gnatmake* with switch *-a*. + + When :file:`my_program` is executed, the file :file:`gmem.out` is produced. + This file contains information about all allocations and deallocations + performed by the program. It is produced by the instrumented allocations and + deallocations routines and will be used by `gnatmem`. + + In order to produce symbolic backtrace information for allocations and + deallocations performed by the GNAT run-time library, you need to use a + version of that library that has been compiled with the *-g* switch + (see :ref:`Rebuilding_the_GNAT_Run-Time_Library`). + + *gnatmem* must be supplied with the :file:`gmem.out` file and the executable to + examine. If the location of :file:`gmem.out` file was not explicitly supplied by + *-i* switch, gnatmem will assume that this file can be found in the + current directory. For example, after you have executed :file:`my_program`, + :file:`gmem.out` can be analyzed by `gnatmem` using the command: + + :: + + $ gnatmem my_program + + This will produce the output with the following format: + + :: + + $ gnatmem my_program + + Global information + ------------------ + Total number of allocations : 45 + Total number of deallocations : 6 + Final Water Mark (non freed mem) : 11.29 Kilobytes + High Water Mark : 11.40 Kilobytes + + . + . + . + Allocation Root # 2 + ------------------- + Number of non freed allocations : 11 + Final Water Mark (non freed mem) : 1.16 Kilobytes + High Water Mark : 1.27 Kilobytes + Backtrace : + my_program.adb:23 my_program.alloc + . + . + . + + The first block of output gives general information. In this case, the + Ada construct **new** was executed 45 times, and only 6 calls to an + Unchecked_Deallocation routine occurred. + + Subsequent paragraphs display information on all allocation roots. + An allocation root is a specific point in the execution of the program + that generates some dynamic allocation, such as a **new** + construct. This root is represented by an execution backtrace (or subprogram + call stack). By default the backtrace depth for allocations roots is 1, so + that a root corresponds exactly to a source location. The backtrace can + be made deeper, to make the root more specific. + + .. _Switches_for_gnatmem: + + Switches for `gnatmem` + ^^^^^^^^^^^^^^^^^^^^^^ + + `gnatmem` recognizes the following switches: + + .. index:: -q (gnatmem) + + :samp:`-q` + Quiet. Gives the minimum output needed to identify the origin of the + memory leaks. Omits statistical information. + + + .. index:: N switch (gnatmem) + + :samp:`{N}` + `N` is an integer literal (usually between 1 and 10) which controls the + depth of the backtraces defining allocation root. The default value for + N is 1. The deeper the backtrace, the more precise the localization of + the root. Note that the total number of roots can depend on this + parameter. This parameter must be specified *before* the name of the + executable to be analyzed, to avoid ambiguity. + + + .. index:: -b (gnatmem) + + :samp:`-b {N}` + This switch has the same effect as just a depth parameter `N`. + + + .. index:: -i (gnatmem) + + :samp:`-i {file}` + Do the `gnatmem` processing starting from :file:`file`, rather than + :file:`gmem.out` in the current directory. + + + .. index:: -m (gnatmem) + + :samp:`-m {n}` + This switch causes `gnatmem` to mask the allocation roots that have less + than n leaks. The default value is 1. Specifying the value of 0 will allow + examination of even the roots that did not result in leaks. + + + .. index:: -s (gnatmem) + + :samp:`-s {order}` + This switch causes `gnatmem` to sort the allocation roots according to the + specified order of sort criteria, each identified by a single letter. The + currently supported criteria are `n`, `h`, and `w` standing respectively for + number of unfreed allocations, high watermark, and final watermark + corresponding to a specific root. The default order is `nwh`. + + + .. index:: -t (gnatmem) + + :samp:`-t` + This switch causes memory allocated size to be always output in bytes. + Default `gnatmem` behavior is to show memory sizes less then 1 kilobyte + in bytes, from 1 kilobyte till 1 megabyte in kilobytes and the rest in + megabytes. + + + .. _Example_of_gnatmem_Usage: + + Example of `gnatmem` Usage + ^^^^^^^^^^^^^^^^^^^^^^^^^^ + + The following example shows the use of `gnatmem` + on a simple memory-leaking program. + Suppose that we have the following Ada program: + + .. code-block:: ada + + with Unchecked_Deallocation; + procedure Test_Gm is + + type T is array (1..1000) of Integer; + type Ptr is access T; + procedure Free is new Unchecked_Deallocation (T, Ptr); + A : Ptr; + + procedure My_Alloc is + begin + A := new T; + end My_Alloc; + + procedure My_DeAlloc is + B : Ptr := A; + begin + Free (B); + end My_DeAlloc; + + begin + My_Alloc; + for I in 1 .. 5 loop + for J in I .. 5 loop + My_Alloc; + end loop; + My_Dealloc; + end loop; + end; + + The program needs to be compiled with the debugging option and linked with + the `gmem` library: + + :: + + $ gnatmake -g test_gm -largs -lgmem + + Then we execute the program as usual: + + :: + + $ test_gm + + Then `gnatmem` is invoked simply with + + :: + + $ gnatmem test_gm + + which produces the following output (result may vary on different platforms): + + :: + + Global information + ------------------ + Total number of allocations : 18 + Total number of deallocations : 5 + Final Water Mark (non freed mem) : 53.00 Kilobytes + High Water Mark : 56.90 Kilobytes + + Allocation Root # 1 + ------------------- + Number of non freed allocations : 11 + Final Water Mark (non freed mem) : 42.97 Kilobytes + High Water Mark : 46.88 Kilobytes + Backtrace : + test_gm.adb:11 test_gm.my_alloc + + Allocation Root # 2 + ------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 10.02 Kilobytes + High Water Mark : 10.02 Kilobytes + Backtrace : + s-secsta.adb:81 system.secondary_stack.ss_init + + Allocation Root # 3 + ------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 12 Bytes + High Water Mark : 12 Bytes + Backtrace : + s-secsta.adb:181 system.secondary_stack.ss_init + + + Note that the GNAT runtime contains itself a certain number of + allocations that have no corresponding deallocation, + as shown here for root #2 and root #3. + This is a normal behavior when the number of non-freed allocations + is one, it allocates dynamic data structures that the run time needs for + the complete lifetime of the program. Note also that there is only one + allocation root in the user program with a single line back trace: + test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the + program shows that 'My_Alloc' is called at 2 different points in the + source (line 21 and line 24). If those two allocation roots need to be + distinguished, the backtrace depth parameter can be used: + + :: + + $ gnatmem 3 test_gm + + which will give the following output: + + + :: + + Global information + ------------------ + Total number of allocations : 18 + Total number of deallocations : 5 + Final Water Mark (non freed mem) : 53.00 Kilobytes + High Water Mark : 56.90 Kilobytes + + Allocation Root # 1 + ------------------- + Number of non freed allocations : 10 + Final Water Mark (non freed mem) : 39.06 Kilobytes + High Water Mark : 42.97 Kilobytes + Backtrace : + test_gm.adb:11 test_gm.my_alloc + test_gm.adb:24 test_gm + b_test_gm.c:52 main + + Allocation Root # 2 + ------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 10.02 Kilobytes + High Water Mark : 10.02 Kilobytes + Backtrace : + s-secsta.adb:81 system.secondary_stack.ss_init + s-secsta.adb:283 <system__secondary_stack___elabb> + b_test_gm.c:33 adainit + + Allocation Root # 3 + ------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 3.91 Kilobytes + High Water Mark : 3.91 Kilobytes + Backtrace : + test_gm.adb:11 test_gm.my_alloc + test_gm.adb:21 test_gm + b_test_gm.c:52 main + + Allocation Root # 4 + ------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 12 Bytes + High Water Mark : 12 Bytes + Backtrace : + s-secsta.adb:181 system.secondary_stack.ss_init + s-secsta.adb:283 <system__secondary_stack___elabb> + b_test_gm.c:33 adainit + + The allocation root #1 of the first example has been split in 2 roots #1 + and #3, thanks to the more precise associated backtrace. + + + + diff --git a/gcc/ada/doc/gnat_ugn/gnat_project_manager.rst b/gcc/ada/doc/gnat_ugn/gnat_project_manager.rst new file mode 100644 index 00000000000..70d3c284276 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/gnat_project_manager.rst @@ -0,0 +1,4907 @@ +.. |with| replace:: *with* +.. |withs| replace:: *with*\ s +.. |withed| replace:: *with*\ ed +.. |withing| replace:: *with*\ ing + +.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit + + +.. _GNAT_Project_Manager: + +******************** +GNAT Project Manager +******************** + + +.. _GNAT_Project_Manager_Introduction: + +Introduction +============ + +This chapter describes GNAT's *Project Manager*, a facility that allows +you to manage complex builds involving a number of source files, directories, +and options for different system configurations. In particular, +project files allow you to specify: + +* The directory or set of directories containing the source files, and/or the + names of the specific source files themselves +* The directory in which the compiler's output + (:file:`ALI` files, object files, tree files, etc.) is to be placed +* The directory in which the executable programs are to be placed +* Switch settings for any of the project-enabled tools; + you can apply these settings either globally or to individual compilation units. +* The source files containing the main subprogram(s) to be built +* The source programming language(s) +* Source file naming conventions; you can specify these either globally or for + individual compilation units (see :ref:`Naming_Schemes`). +* Change any of the above settings depending on external values, thus enabling + the reuse of the projects in various **scenarios** (see :ref:`Scenarios_in_Projects`). +* Automatically build libraries as part of the build process + (see :ref:`Library_Projects`). + + +Project files are written in a syntax close to that of Ada, using familiar +notions such as packages, context clauses, declarations, default values, +assignments, and inheritance (see :ref:`Project_File_Reference`). + +Project files can be built hierarchically from other project files, simplifying +complex system integration and project reuse (see :ref:`Organizing_Projects_into_Subsystems`). + +* One project can import other projects containing needed source files. + More generally, the Project Manager lets you structure large development + efforts into hierarchical subsystems, where build decisions are delegated + to the subsystem level, and thus different compilation environments + (switch settings) used for different subsystems. +* You can organize GNAT projects in a hierarchy: a child project + can extend a parent project, inheriting the parent's source files and + optionally overriding any of them with alternative versions + (see :ref:`Project_Extension`). + + +Several tools support project files, generally in addition to specifying +the information on the command line itself). They share common switches +to control the loading of the project (in particular +:samp:`-P{projectfile}` and +:samp:`-X{vbl}={value}`). + +The Project Manager supports a wide range of development strategies, +for systems of all sizes. Here are some typical practices that are +easily handled: + +* Using a common set of source files and generating object files in different + directories via different switch settings. It can be used for instance, for + generating separate sets of object files for debugging and for production. +* Using a mostly-shared set of source files with different versions of + some units or subunits. It can be used for instance, for grouping and hiding + all OS dependencies in a small number of implementation units. + +Project files can be used to achieve some of the effects of a source +versioning system (for example, defining separate projects for +the different sets of sources that comprise different releases) but the +Project Manager is independent of any source configuration management tool +that might be used by the developers. + +The various sections below introduce the different concepts related to +projects. Each section starts with examples and use cases, and then goes into +the details of related project file capabilities. + +.. _Building_With_Projects: + +Building With Projects +====================== + +In its simplest form, a unique project is used to build a single executable. +This section concentrates on such a simple setup. Later sections will extend +this basic model to more complex setups. + +The following concepts are the foundation of project files, and will be further +detailed later in this documentation. They are summarized here as a reference. + +**Project file**: + A text file using an Ada-like syntax, generally using the :file:`.gpr` + extension. It defines build-related characteristics of an application. + The characteristics include the list of sources, the location of those + sources, the location for the generated object files, the name of + the main program, and the options for the various tools involved in the + build process. + + +**Project attribute**: + A specific project characteristic is defined by an attribute clause. Its + value is a string or a sequence of strings. All settings in a project + are defined through a list of predefined attributes with precise + semantics. See :ref:`Attributes`. + + +**Package in a project**: + Global attributes are defined at the top level of a project. + Attributes affecting specific tools are grouped in a + package whose name is related to tool's function. The most common + packages are `Builder`, `Compiler`, `Binder`, + and `Linker`. See :ref:`Packages`. + + +**Project variables**: + In addition to attributes, a project can use variables to store intermediate + values and avoid duplication in complex expressions. It can be initialized + with a value coming from the environment. + A frequent use of variables is to define scenarios. + See :ref:`External_Values`, :ref:`Scenarios_in_Projects`, and :ref:`Variables`. + + +**Source files** and **source directories**: + A source file is associated with a language through a naming convention. For + instance, `foo.c` is typically the name of a C source file; + `bar.ads` or `bar.1.ada` are two common naming conventions for a + file containing an Ada spec. A compilation unit is often composed of a main + source file and potentially several auxiliary ones, such as header files in C. + The naming conventions can be user defined :ref:`Naming_Schemes`, and will + drive the builder to call the appropriate compiler for the given source file. + Source files are searched for in the source directories associated with the + project through the **Source_Dirs** attribute. By default, all the files (in + these source directories) following the naming conventions associated with the + declared languages are considered to be part of the project. It is also + possible to limit the list of source files using the **Source_Files** or + **Source_List_File** attributes. Note that those last two attributes only + accept basenames with no directory information. + + +**Object files** and **object directory**: + An object file is an intermediate file produced by the compiler from a + compilation unit. It is used by post-compilation tools to produce + final executables or libraries. Object files produced in the context of + a given project are stored in a single directory that can be specified by the + **Object_Dir** attribute. In order to store objects in + two or more object directories, the system must be split into + distinct subsystems with their own project file. + + +The following subsections introduce gradually all the attributes of interest +for simple build needs. Here is the simple setup that will be used in the +following examples. + +The Ada source files :file:`pack.ads`, :file:`pack.adb`, and :file:`proc.adb` are in +the :file:`common/` directory. The file :file:`proc.adb` contains an Ada main +subprogram `Proc` that |withs| package `Pack`. We want to compile +these source files with the switch +*-O2*, and put the resulting files in +the directory :file:`obj/`. + +:: + + common/ + pack.ads + pack.adb + proc.adb + common/obj/ + proc.ali, proc.o pack.ali, pack.o + + +Our project is to be called *Build*. The name of the +file is the name of the project (case-insensitive) with the +:file:`.gpr` extension, therefore the project file name is :file:`build.gpr`. This +is not mandatory, but a warning is issued when this convention is not followed. + +This is a very simple example, and as stated above, a single project +file is enough for it. We will thus create a new file, that for now +should contain the following code: + +.. code-block:: gpr + + project Build is + end Build; + + +.. _Source_Files_and_Directories: + +Source Files and Directories +---------------------------- + +When you create a new project, the first thing to describe is how to find the +corresponding source files. These are the only settings that are needed by all +the tools that will use this project (builder, compiler, binder and linker for +the compilation, IDEs to edit the source files,...). + +.. index:: Source directories (GNAT Project Manager) + +The first step is to declare the source directories, which are the directories +to be searched to find source files. In the case of the example, +the :file:`common` directory is the only source directory. + +.. index:: Source_Dirs (GNAT Project Manager) + +There are several ways of defining source directories: + +* When the attribute **Source_Dirs** is not used, a project contains a + single source directory which is the one where the project file itself + resides. In our example, if :file:`build.gpr` is placed in the :file:`common` + directory, the project has the needed implicit source directory. + +* The attribute **Source_Dirs** can be set to a list of path names, one + for each of the source directories. Such paths can either be absolute + names (for instance :file:`"/usr/local/common/"` on UNIX), or relative to the + directory in which the project file resides (for instance "." if + :file:`build.gpr` is inside :file:`common/`, or "common" if it is one level up). + Each of the source directories must exist and be readable. + + .. index:: portability of path names (GNAT Project Manager) + + The syntax for directories is platform specific. For portability, however, + the project manager will always properly translate UNIX-like path names to + the native format of the specific platform. For instance, when the same + project file is to be used both on Unix and Windows, "/" should be used as + the directory separator rather than "\\". + +* The attribute **Source_Dirs** can automatically include subdirectories + using a special syntax inspired by some UNIX shells. If any of the paths in + the list ends with ":file:`**`", then that path and all its subdirectories + (recursively) are included in the list of source directories. For instance, + :file:`**` and :file:`./**` represent the complete directory tree rooted at + the directory in which the project file resides. + + .. index:: Source directories (GNAT Project Manager) + + .. index:: Excluded_Source_Dirs (GNAT Project Manager) + + When using that construct, it can sometimes be convenient to also use the + attribute **Excluded_Source_Dirs**, which is also a list of paths. Each entry + specifies a directory whose immediate content, not including subdirs, is to + be excluded. It is also possible to exclude a complete directory subtree + using the "**" notation. + + .. index:: Ignore_Source_Sub_Dirs (GNAT Project Manager) + + It is often desirable to remove, from the source directories, directory + subtrees rooted at some subdirectories. An example is the subdirectories + created by a Version Control System such as Subversion that creates directory + subtrees rooted at subdirectories ".svn". To do that, attribute + **Ignore_Source_Sub_Dirs** can be used. It specifies the list of simple + file names for the roots of these undesirable directory subtrees. + + + .. code-block: ada-project + + for Source_Dirs use ("./**"); + for Ignore_Source_Sub_Dirs use (".svn"); + + +When applied to the simple example, and because we generally prefer to have +the project file at the toplevel directory rather than mixed with the sources, +we will create the following file + + +.. code-block: ada-project + + build.gpr + project Build is + for Source_Dirs use ("common"); -- <<<< + end Build; + + +Once source directories have been specified, one may need to indicate +source files of interest. By default, all source files present in the source +directories are considered by the project manager. When this is not desired, +it is possible to specify the list of sources to consider explicitly. +In such a case, only source file base names are indicated and not +their absolute or relative path names. The project manager is in charge of +locating the specified source files in the specified source directories. + +* By default, the project manager searches for all source files of all + specified languages in all the source directories. + + Since the project manager was initially developed for Ada environments, the + default language is usually Ada and the above project file is complete: it + defines without ambiguity the sources composing the project: that is to say, + all the sources in subdirectory "common" for the default language (Ada) using + the default naming convention. + + .. index:: Languages (GNAT Project Manager) + + However, when compiling a multi-language application, or a pure C + application, the project manager must be told which languages are of + interest, which is done by setting the **Languages** attribute to a list of + strings, each of which is the name of a language. Tools like + *gnatmake* only know about Ada, while other tools like + *gprbuild* know about many more languages such as C, C++, Fortran, + assembly and others can be added dynamically. + + .. index:: Naming scheme (GNAT Project Manager) + + Even when using only Ada, the default naming might not be suitable. Indeed, + how does the project manager recognizes an "Ada file" from any other + file? Project files can describe the naming scheme used for source files, + and override the default (see :ref:`Naming_Schemes`). The default is the + standard GNAT extension (:file:`.adb` for bodies and :file:`.ads` for + specs), which is what is used in our example, explaining why no naming scheme + is explicitly specified. + See :ref:`Naming_Schemes`. + + .. index:: Source_Files (GNAT Project Manager) + +* `Source_Files`. + In some cases, source directories might contain files that should not be + included in a project. One can specify the explicit list of file names to + be considered through the **Source_Files** attribute. + When this attribute is defined, instead of looking at every file in the + source directories, the project manager takes only those names into + consideration reports errors if they cannot be found in the source + directories or does not correspond to the naming scheme. + +* For various reasons, it is sometimes useful to have a project with no + sources (most of the time because the attributes defined in the project + file will be reused in other projects, as explained in + :ref:`Organizing_Projects_into_Subsystems`. To do this, the attribute + *Source_Files* is set to the empty list, i.e. `()`. Alternatively, + *Source_Dirs* can be set to the empty list, with the same + result. + + .. index:: Source_List_File (GNAT Project Manager) + +* `Source_List_File`. + If there is a great number of files, it might be more convenient to use + the attribute **Source_List_File**, which specifies the full path of a file. + This file must contain a list of source file names (one per line, no + directory information) that are searched as if they had been defined + through *Source_Files*. Such a file can easily be created through + external tools. + + A warning is issued if both attributes `Source_Files` and + `Source_List_File` are given explicit values. In this case, the + attribute `Source_Files` prevails. + + .. index:: Excluded_Source_Files (GNAT Project Manager) + .. index:: Locally_Removed_Files (GNAT Project Manager) + .. index:: Excluded_Source_List_File (GNAT Project Manager) + +* `Excluded_Source_Files`. + Specifying an explicit list of files is not always convenient.It might be + more convenient to use the default search rules with specific exceptions. + This can be done thanks to the attribute **Excluded_Source_Files** + (or its synonym **Locally_Removed_Files**). + Its value is the list of file names that should not be taken into account. + This attribute is often used when extending a project, + see :ref:`Project_Extension`. A similar attribute + **Excluded_Source_List_File** plays the same + role but takes the name of file containing file names similarly to + `Source_List_File`. + + +In most simple cases, such as the above example, the default source file search +behavior provides the expected result, and we do not need to add anything after +setting `Source_Dirs`. The project manager automatically finds +:file:`pack.ads`, :file:`pack.adb`, and :file:`proc.adb` as source files of the +project. + +Note that by default a warning is issued when a project has no sources attached +to it and this is not explicitly indicated in the project file. + +.. _Duplicate_Sources_in_Projects: + +Duplicate Sources in Projects +----------------------------- + +If the order of the source directories is known statically, that is if +`"/**"` is not used in the string list `Source_Dirs`, then there may +be several files with the same name sitting in different directories of the +project. In this case, only the file in the first directory is considered as a +source of the project and the others are hidden. If `"/**"` is used in the +string list `Source_Dirs`, it is an error to have several files with the +same name in the same directory `"/**"` subtree, since there would be an +ambiguity as to which one should be used. However, two files with the same name +may exist in two single directories or directory subtrees. In this case, the +one in the first directory or directory subtree is a source of the project. + +If there are two sources in different directories of the same `"/**"` +subtree, one way to resolve the problem is to exclude the directory of the +file that should not be used as a source of the project. + +.. _Object_and_Exec_Directory: + +Object and Exec Directory +------------------------- + +The next step when writing a project is to indicate where the compiler should +put the object files. In fact, the compiler and other tools might create +several different kind of files (for GNAT, there is the object file and the ALI +file for instance). One of the important concepts in projects is that most +tools may consider source directories as read-only and do not attempt to create +new or temporary files there. Instead, all files are created in the object +directory. It is of course not true for project-aware IDEs, whose purpose it is +to create the source files. + +.. index:: Object_Dir (GNAT Project Manager) + +The object directory is specified through the **Object_Dir** attribute. +Its value is the path to the object directory, either absolute or +relative to the directory containing the project file. This +directory must already exist and be readable and writable, although +some tools have a switch to create the directory if needed (See +the switch `-p` for *gnatmake* +and *gprbuild*). + +If the attribute `Object_Dir` is not specified, it defaults to +the project directory, that is the directory containing the project file. + +For our example, we can specify the object dir in this way: + +.. code-block: ada-project + + project Build is + for Source_Dirs use ("common"); + for Object_Dir use "obj"; -- <<<< + end Build; + +As mentioned earlier, there is a single object directory per project. As a +result, if you have an existing system where the object files are spread across +several directories, you can either move all of them into the same directory if +you want to build it with a single project file, or study the section on +subsystems (see :ref:`Organizing_Projects_into_Subsystems`) to see how each +separate object directory can be associated with one of the subsystems +constituting the application. + +When the *linker* is called, it usually creates an executable. By +default, this executable is placed in the object directory of the project. It +might be convenient to store it in its own directory. + +.. index:: Exec_Dir (GNAT Project Manager) + +This can be done through the `Exec_Dir` attribute, which, like +*Object_Dir* contains a single absolute or relative path and must point to +an existing and writable directory, unless you ask the tool to create it on +your behalf. When not specified, It defaults to the object directory and +therefore to the project file's directory if neither *Object_Dir* nor +*Exec_Dir* was specified. + +In the case of the example, let's place the executable in the root +of the hierarchy, ie the same directory as :file:`build.gpr`. Hence +the project file is now + +.. code-block: ada-project + + project Build is + for Source_Dirs use ("common"); + for Object_Dir use "obj"; + for Exec_Dir use "."; -- <<<< + end Build; + + +.. _Main_Subprograms: + +Main Subprograms +---------------- + +In the previous section, executables were mentioned. The project manager needs +to be taught what they are. In a project file, an executable is indicated by +pointing to the source file of a main subprogram. In C this is the file that +contains the `main` function, and in Ada the file that contains the main +unit. + +There can be any number of such main files within a given project, and thus +several executables can be built in the context of a single project file. Of +course, one given executable might not (and in fact will not) need all the +source files referenced by the project. As opposed to other build environments +such as *makefile*, one does not need to specify the list of +dependencies of each executable, the project-aware builder knows enough of the +semantics of the languages to build and link only the necessary elements. + +.. index:: Main (GNAT Project Manager) + +The list of main files is specified via the **Main** attribute. It contains +a list of file names (no directories). If a project defines this +attribute, it is not necessary to identify main files on the +command line when invoking a builder, and editors like +*GPS* will be able to create extra menus to spawn or debug the +corresponding executables. + +.. code-block: ada-project + + project Build is + for Source_Dirs use ("common"); + for Object_Dir use "obj"; + for Exec_Dir use "."; + for Main use ("proc.adb"); -- <<<< + end Build; + + +If this attribute is defined in the project, then spawning the builder +with a command such as + +.. code-block:: sh + + gprbuild -Pbuild + + +automatically builds all the executables corresponding to the files +listed in the *Main* attribute. It is possible to specify one +or more executables on the command line to build a subset of them. + +.. _Tools_Options_in_Project_Files: + +Tools Options in Project Files +------------------------------ + +We now have a project file that fully describes our environment, and can be +used to build the application with a simple *gprbuild* command as seen +in the previous section. In fact, the empty project we showed immediately at +the beginning (with no attribute at all) could already fulfill that need if it +was put in the :file:`common` directory. + +Of course, we might want more control. This section shows you how to specify +the compilation switches that the various tools involved in the building of the +executable should use. + +.. index:: command line length (GNAT Project Manager) + +Since source names and locations are described in the project file, it is not +necessary to use switches on the command line for this purpose (switches such +as -I for gcc). This removes a major source of command line length overflow. +Clearly, the builders will have to communicate this information one way or +another to the underlying compilers and tools they call but they usually use +response files for this and thus are not subject to command line overflows. + +Several tools participate to the creation of an executable: the compiler +produces object files from the source files; the binder (in the Ada case) +creates a "source" file that takes care, among other things, of elaboration +issues and global variable initialization; and the linker gathers everything +into a single executable that users can execute. All these tools are known to +the project manager and will be called with user defined switches from the +project files. However, we need to introduce a new project file concept to +express the switches to be used for any of the tools involved in the build. + +.. index:: project file packages (GNAT Project Manager) + +A project file is subdivided into zero or more **packages**, each of which +contains the attributes specific to one tool (or one set of tools). Project +files use an Ada-like syntax for packages. Package names permitted in project +files are restricted to a predefined set (see :ref:`Packages`), and the contents +of packages are limited to a small set of constructs and attributes +(see :ref:`Attributes`). + +Our example project file can be extended with the following empty packages. At +this stage, they could all be omitted since they are empty, but they show which +packages would be involved in the build process. + +.. code-block: ada-project + + project Build is + for Source_Dirs use ("common"); + for Object_Dir use "obj"; + for Exec_Dir use "."; + for Main use ("proc.adb"); + + package Builder is --<<< for gnatmake and gprbuild + end Builder; + + package Compiler is --<<< for the compiler + end Compiler; + + package Binder is --<<< for the binder + end Binder; + + package Linker is --<<< for the linker + end Linker; + end Build; + +Let's first examine the compiler switches. As stated in the initial description +of the example, we want to compile all files with *-O2*. This is a +compiler switch, although it is usual, on the command line, to pass it to the +builder which then passes it to the compiler. It is recommended to use directly +the right package, which will make the setup easier to understand for other +people. + +Several attributes can be used to specify the switches: + +.. index:: Default_Switches (GNAT Project Manager) + +**Default_Switches**: + + This is the first mention in this manual of an **indexed attribute**. When + this attribute is defined, one must supply an *index* in the form of a + literal string. + In the case of *Default_Switches*, the index is the name of the + language to which the switches apply (since a different compiler will + likely be used for each language, and each compiler has its own set of + switches). The value of the attribute is a list of switches. + + In this example, we want to compile all Ada source files with the switch + *-O2*, and the resulting project file is as follows + (only the `Compiler` package is shown): + + .. code-block: ada-project + + package Compiler is + for Default_Switches ("Ada") use ("-O2"); + end Compiler; + +.. index:: Switches (GNAT Project Manager) + +**Switches**: + + In some cases, we might want to use specific switches + for one or more files. For instance, compiling :file:`proc.adb` might not be + possible at high level of optimization because of a compiler issue. + In such a case, the *Switches* + attribute (indexed on the file name) can be used and will override the + switches defined by *Default_Switches*. Our project file would + become: + + .. code-block: ada-project + + + package Compiler is + for Default_Switches ("Ada") + use ("-O2"); + for Switches ("proc.adb") + use ("-O0"); + end Compiler; + + + `Switches` may take a pattern as an index, such as in: + + .. code-block: ada-project + + package Compiler is + for Default_Switches ("Ada") + use ("-O2"); + for Switches ("pkg*") + use ("-O0"); + end Compiler; + + Sources :file:`pkg.adb` and :file:`pkg-child.adb` would be compiled with -O0, + not -O2. + + `Switches` can also be given a language name as index instead of a file + name in which case it has the same semantics as *Default_Switches*. + However, indexes with wild cards are never valid for language name. + + +.. index:: Local_Configuration_Pragmas (GNAT Project Manager) + +**Local_Configuration_Pragmas**: + + This attribute may specify the path + of a file containing configuration pragmas for use by the Ada compiler, + such as `pragma Restrictions (No_Tasking)`. These pragmas will be + used for all the sources of the project. + + +The switches for the other tools are defined in a similar manner through the +**Default_Switches** and **Switches** attributes, respectively in the +*Builder* package (for *gnatmake* and *gprbuild*), +the *Binder* package (binding Ada executables) and the *Linker* +package (for linking executables). + + +.. _Compiling_with_Project_Files: + +Compiling with Project Files +---------------------------- + +Now that our project files are written, let's build our executable. +Here is the command we would use from the command line: + +.. code-block:: sh + + gnatmake -Pbuild + +This will automatically build the executables specified through the +*Main* attribute: for each, it will compile or recompile the +sources for which the object file does not exist or is not up-to-date; it +will then run the binder; and finally run the linker to create the +executable itself. + +*gnatmake* only knows how to handle Ada files. By using +*gprbuild* as a builder, you could automatically manage C files the +same way: create the file :file:`utils.c` in the :file:`common` directory, +set the attribute *Languages* to `"(Ada, C)"`, and run + +.. code-block:: sh + + gprbuild -Pbuild + +Gprbuild knows how to recompile the C files and will +recompile them only if one of their dependencies has changed. No direct +indication on how to build the various elements is given in the +project file, which describes the project properties rather than a +set of actions to be executed. Here is the invocation of +*gprbuild* when building a multi-language program: + +.. code-block:: sh + + $ gprbuild -Pbuild + gcc -c proc.adb + gcc -c pack.adb + gcc -c utils.c + gprbind proc + ... + gcc proc.o -o proc + +Notice the three steps described earlier: + +* The first three gcc commands correspond to the compilation phase. +* The gprbind command corresponds to the post-compilation phase. +* The last gcc command corresponds to the final link. + + +.. index:: -v option (for GPRbuild) + +The default output of GPRbuild's execution is kept reasonably simple and easy +to understand. In particular, some of the less frequently used commands are not +shown, and some parameters are abbreviated. So it is not possible to rerun the +effect of the *gprbuild* command by cut-and-pasting its output. +GPRbuild's option `-v` provides a much more verbose output which includes, +among other information, more complete compilation, post-compilation and link +commands. + + +.. _Executable_File_Names: + +Executable File Names +--------------------- + +.. index:: Executable (GNAT Project Manager) + +By default, the executable name corresponding to a main file is +computed from the main source file name. Through the attribute +**Builder.Executable**, it is possible to change this default. + +For instance, instead of building *proc* (or *proc.exe* +on Windows), we could configure our project file to build "proc1" +(resp proc1.exe) with the following addition: + +.. code-block:: gpr + + project Build is + ... -- same as before + package Builder is + for Executable ("proc.adb") use "proc1"; + end Builder + end Build; + +.. index:: Executable_Suffix (GNAT Project Manager) + +Attribute **Executable_Suffix**, when specified, may change the suffix +of the executable files, when no attribute `Executable` applies: +its value replaces the platform-specific executable suffix. +The default executable suffix is empty on UNIX and ".exe" on Windows. + +It is also possible to change the name of the produced executable by using the +command line switch *-o*. When several mains are defined in the project, +it is not possible to use the *-o* switch and the only way to change the +names of the executable is provided by Attributes `Executable` and +`Executable_Suffix`. + + +.. _Avoid_Duplication_With_Variables: + +Avoid Duplication With Variables +-------------------------------- + +To illustrate some other project capabilities, here is a slightly more complex +project using similar sources and a main program in C: + + +.. code-block:: gpr + + project C_Main is + for Languages use ("Ada", "C"); + for Source_Dirs use ("common"); + for Object_Dir use "obj"; + for Main use ("main.c"); + package Compiler is + C_Switches := ("-pedantic"); + for Default_Switches ("C") use C_Switches; + for Default_Switches ("Ada") use ("-gnaty"); + for Switches ("main.c") use C_Switches & ("-g"); + end Compiler; + end C_Main; + +This project has many similarities with the previous one. +As expected, its `Main` attribute now refers to a C source. +The attribute *Exec_Dir* is now omitted, thus the resulting +executable will be put in the directory :file:`obj`. + +The most noticeable difference is the use of a variable in the +*Compiler* package to store settings used in several attributes. +This avoids text duplication, and eases maintenance (a single place to +modify if we want to add new switches for C files). We will revisit +the use of variables in the context of scenarios (see :ref:`Scenarios_in_Projects`). + +In this example, we see how the file :file:`main.c` can be compiled with +the switches used for all the other C files, plus *-g*. +In this specific situation the use of a variable could have been +replaced by a reference to the `Default_Switches` attribute: + +.. code-block:: gpr + + for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g"); + +Note the tick (*'*) used to refer to attributes defined in a package. + +Here is the output of the GPRbuild command using this project: + +.. code-block:: sh + + $ gprbuild -Pc_main + gcc -c -pedantic -g main.c + gcc -c -gnaty proc.adb + gcc -c -gnaty pack.adb + gcc -c -pedantic utils.c + gprbind main.bexch + ... + gcc main.o -o main + +The default switches for Ada sources, +the default switches for C sources (in the compilation of :file:`lib.c`), +and the specific switches for :file:`main.c` have all been taken into +account. + + +.. _Naming_Schemes: + +Naming Schemes +-------------- + +Sometimes an Ada software system is ported from one compilation environment to +another (say GNAT), and the file are not named using the default GNAT +conventions. Instead of changing all the file names, which for a variety of +reasons might not be possible, you can define the relevant file naming scheme +in the **Naming** package of your project file. + +The naming scheme has two distinct goals for the project manager: it +allows finding of source files when searching in the source +directories, and given a source file name it makes it possible to guess +the associated language, and thus the compiler to use. + +Note that the use by the Ada compiler of pragmas Source_File_Name is not +supported when using project files. You must use the features described in this +paragraph. You can however specify other configuration pragmas. + +The following attributes can be defined in package `Naming`: + +.. index:: Casing (GNAT Project Manager) + +**Casing**: + + Its value must be one of `"lowercase"` (the default if + unspecified), `"uppercase"` or `"mixedcase"`. It describes the + casing of file names with regards to the Ada unit name. Given an Ada unit + My_Unit, the file name will respectively be :file:`my_unit.adb` (lowercase), + :file:`MY_UNIT.ADB` (uppercase) or :file:`My_Unit.adb` (mixedcase). + On Windows, file names are case insensitive, so this attribute is + irrelevant. + + +.. index:: Dot_Replacement (GNAT Project Manager) + +**Dot_Replacement**: + + This attribute specifies the string that should replace the "." in unit + names. Its default value is `"-"` so that a unit + `Parent.Child` is expected to be found in the file + :file:`parent-child.adb`. The replacement string must satisfy the following + requirements to avoid ambiguities in the naming scheme: + + * It must not be empty + + * It cannot start or end with an alphanumeric character + + * It cannot be a single underscore + + * It cannot start with an underscore followed by an alphanumeric + + * It cannot contain a dot `'.'` except if the entire string is `"."` + +.. index:: Spec_Suffix (GNAT Project Manager) +.. index:: Specification_Suffix (GNAT Project Manager) + +**Spec_Suffix** and **Specification_Suffix**: + + For Ada, these attributes give the suffix used in file names that contain + specifications. For other languages, they give the extension for files + that contain declaration (header files in C for instance). The attribute + is indexed on the language. + The two attributes are equivalent, but the latter is obsolescent. + + If the value of the attribute is the empty string, it indicates to the + Project Manager that the only specifications/header files for the language + are those specified with attributes `Spec` or + `Specification_Exceptions`. + + If `Spec_Suffix ("Ada")` is not specified, then the default is + `".ads"`. + + A non empty value must satisfy the following requirements: + + * It must include at least one dot + + * If `Dot_Replacement` is a single dot, then it cannot include + more than one dot. + +.. index:: Body_Suffix (GNAT Project Manager) +.. index:: Implementation_Suffix (GNAT Project Manager) + +**Body_Suffix** and **Implementation_Suffix**: + + These attributes give the extension used for file names that contain + code (bodies in Ada). They are indexed on the language. The second + version is obsolescent and fully replaced by the first attribute. + + For each language of a project, one of these two attributes need to be + specified, either in the project itself or in the configuration project file. + + If the value of the attribute is the empty string, it indicates to the + Project Manager that the only source files for the language + are those specified with attributes `Body` or + `Implementation_Exceptions`. + + These attributes must satisfy the same requirements as `Spec_Suffix`. + In addition, they must be different from any of the values in + `Spec_Suffix`. + If `Body_Suffix ("Ada")` is not specified, then the default is + `".adb"`. + + If `Body_Suffix ("Ada")` and `Spec_Suffix ("Ada")` end with the + same string, then a file name that ends with the longest of these two + suffixes will be a body if the longest suffix is `Body_Suffix ("Ada")` + or a spec if the longest suffix is `Spec_Suffix ("Ada")`. + + If the suffix does not start with a '.', a file with a name exactly equal to + the suffix will also be part of the project (for instance if you define the + suffix as `Makefile.in`, a file called :file:`Makefile.in` will be part + of the project. This capability is usually not interesting when building. + However, it might become useful when a project is also used to + find the list of source files in an editor, like the GNAT Programming System + (GPS). + +.. index:: Separate_Suffix (GNAT Project Manager) + +**Separate_Suffix**: + + This attribute is specific to Ada. It denotes the suffix used in file names + that contain separate bodies. If it is not specified, then it defaults to + same value as `Body_Suffix ("Ada")`. + + The value of this attribute cannot be the empty string. + + Otherwise, the same rules apply as for the + `Body_Suffix` attribute. The only accepted index is "Ada". + + +**Spec** or **Specification**: + + .. index:: Spec (GNAT Project Manager) + + .. index:: Specification (GNAT Project Manager) + + This attribute `Spec` can be used to define the source file name for a + given Ada compilation unit's spec. The index is the literal name of the Ada + unit (case insensitive). The value is the literal base name of the file that + contains this unit's spec (case sensitive or insensitive depending on the + operating system). This attribute allows the definition of exceptions to the + general naming scheme, in case some files do not follow the usual + convention. + + When a source file contains several units, the relative position of the unit + can be indicated. The first unit in the file is at position 1 + + + .. code-block:: gpr + + for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; + for Spec ("top") use "foo.a" at 1; + for Spec ("foo") use "foo.a" at 2; + + +.. index:: Body (GNAT Project Manager) + +.. index:: Implementation (GNAT Project Manager) + +**Body** or **Implementation**: + + These attribute play the same role as *Spec* for Ada bodies. + + +.. index:: Specification_Exceptions (GNAT Project Manager) + +.. index:: Implementation_Exceptions (GNAT Project Manager) + +**Specification_Exceptions** and **Implementation_Exceptions**: + + These attributes define exceptions to the naming scheme for languages + other than Ada. They are indexed on the language name, and contain + a list of file names respectively for headers and source code. + + +For example, the following package models the Apex file naming rules: + +.. code-block:: gpr + + package Naming is + for Casing use "lowercase"; + for Dot_Replacement use "."; + for Spec_Suffix ("Ada") use ".1.ada"; + for Body_Suffix ("Ada") use ".2.ada"; + end Naming; + + +.. _Installation: + +Installation +------------ + +After building an application or a library it is often required to +install it into the development environment. For instance this step is +required if the library is to be used by another application. +The *gprinstall* tool provides an easy way to install +libraries, executable or object code generated during the build. The +**Install** package can be used to change the default locations. + +The following attributes can be defined in package `Install`: + +.. index:: Active (GNAT Project Manager) + +**Active** + Whether the project is to be installed, values are `true` + (default) or `false`. + + +.. index:: Artifacts (GNAT Project Manager) + +**Artifacts** + + An array attribute to declare a set of files not part of the sources + to be installed. The array discriminant is the directory where the + file is to be installed. If a relative directory then Prefix (see + below) is prepended. + + +.. index:: Prefix (GNAT Project Manager) + +**Prefix**: + + Root directory for the installation. + + +**Exec_Subdir** + + Subdirectory of **Prefix** where executables are to be + installed. Default is **bin**. + + +**Lib_Subdir** + + Subdirectory of **Prefix** where directory with the library or object + files is to be installed. Default is **lib**. + + +**Sources_Subdir** + + Subdirectory of **Prefix** where directory with sources is to be + installed. Default is **include**. + + +**Project_Subdir** + + Subdirectory of **Prefix** where the generated project file is to be + installed. Default is **share/gpr**. + + +**Mode** + + The installation mode, it is either **dev** (default) or **usage**. + See **gprbuild** user's guide for details. + + +**Install_Name** + + Specify the name to use for recording the installation. The default is + the project name without the extension. + + +.. _Distributed_support: + +Distributed support +------------------- + +For large projects the compilation time can become a limitation in +the development cycle. To cope with that, GPRbuild supports +distributed compilation. + +The following attributes can be defined in package `Remote`: + +.. index:: Root_Dir (GNAT Project Manager) + +**Root_Dir**: + + Root directory of the project's sources. The default value is the + project's directory. + + +.. _Organizing_Projects_into_Subsystems: + +Organizing Projects into Subsystems +=================================== + +A **subsystem** is a coherent part of the complete system to be built. It is +represented by a set of sources and one single object directory. A system can +be composed of a single subsystem when it is simple as we have seen in the +first section. Complex systems are usually composed of several interdependent +subsystems. A subsystem is dependent on another subsystem if knowledge of the +other one is required to build it, and in particular if visibility on some of +the sources of this other subsystem is required. Each subsystem is usually +represented by its own project file. + +In this section, the previous example is being extended. Let's assume some +sources of our `Build` project depend on other sources. +For instance, when building a graphical interface, it is usual to depend upon +a graphical library toolkit such as GtkAda. Furthermore, we also need +sources from a logging module we had previously written. + +.. _Project_Dependencies: + +Project Dependencies +-------------------- + +GtkAda comes with its own project file (appropriately called +:file:`gtkada.gpr`), and we will assume we have already built a project +called :file:`logging.gpr` for the logging module. With the information provided +so far in :file:`build.gpr`, building the application would fail with an error +indicating that the gtkada and logging units that are relied upon by the sources +of this project cannot be found. + +This is solved by adding the following **with** clauses at the beginning of our +project: + +.. code-block:: gpr + + with "gtkada.gpr"; + with "a/b/logging.gpr"; + project Build is + ... -- as before + end Build; + + +.. index:: Externally_Built (GNAT Project Manager) + +When such a project is compiled, *gprbuild* will automatically check +the other projects and recompile their sources when needed. It will also +recompile the sources from `Build` when needed, and finally create the +executable. In some cases, the implementation units needed to recompile a +project are not available, or come from some third party and you do not want to +recompile it yourself. In this case, set the attribute **Externally_Built** to +"true", indicating to the builder that this project can be assumed to be +up-to-date, and should not be considered for recompilation. In Ada, if the +sources of this externally built project were compiled with another version of +the compiler or with incompatible options, the binder will issue an error. + +The project's |with| clause has several effects. It provides source +visibility between projects during the compilation process. It also guarantees +that the necessary object files from `Logging` and `GtkAda` are +available when linking `Build`. + +As can be seen in this example, the syntax for importing projects is similar +to the syntax for importing compilation units in Ada. However, project files +use literal strings instead of names, and the |with| clause identifies +project files rather than packages. + +Each literal string after |with| is the path +(absolute or relative) to a project file. The `.gpr` extension is +optional, although we recommend adding it. If no extension is specified, +and no project file with the :file:`.gpr` extension is found, then +the file is searched for exactly as written in the |with| clause, +that is with no extension. + +As mentioned above, the path after a |with| has to be a literal +string, and you cannot use concatenation, or lookup the value of external +variables to change the directories from which a project is loaded. +A solution if you need something like this is to use aggregate projects +(see :ref:`Aggregate_Projects`). + +.. index:: project path (GNAT Project Manager) + +When a relative path or a base name is used, the +project files are searched relative to each of the directories in the +**project path**. This path includes all the directories found with the +following algorithm, in this order; the first matching file is used: + +* First, the file is searched relative to the directory that contains the + current project file. + + .. index:: GPR_PROJECT_PATH_FILE (GNAT Project Manager) + .. index:: GPR_PROJECT_PATH (GNAT Project Manager) + .. index:: ADA_PROJECT_PATH (GNAT Project Manager) + +* Then it is searched relative to all the directories specified in the + environment variables **GPR_PROJECT_PATH_FILE**, + **GPR_PROJECT_PATH** and **ADA_PROJECT_PATH** (in that order) if they exist. + The value of **GPR_PROJECT_PATH_FILE**, when defined, is the path name of + a text file that contains project directory path names, one per line. + **GPR_PROJECT_PATH** and **ADA_PROJECT_PATH**, when defined, contain + project directory path names separated by directory separators. + **ADA_PROJECT_PATH** is used for compatibility, it is recommended to + use **GPR_PROJECT_PATH_FILE** or **GPR_PROJECT_PATH**. + +* Finally, it is searched relative to the default project directories. + Such directories depend on the tool used. The locations searched in the + specified order are: + + * :file:`<prefix>/<target>/lib/gnat` + (for *gnatmake* in all cases, and for *gprbuild* if option + *--target* is specified) + * :file:`<prefix>/<target>/share/gpr` + (for *gnatmake* in all cases, and for *gprbuild* if option + *--target* is specified) + * :file:`<prefix>/share/gpr/` + (for *gnatmake* and *gprbuild*) + * :file:`<prefix>/lib/gnat/` + (for *gnatmake* and *gprbuild*) + + In our example, :file:`gtkada.gpr` is found in the predefined directory if + it was installed at the same root as GNAT. + +Some tools also support extending the project path from the command line, +generally through the *-aP*. You can see the value of the project +path by using the *gnatls -v* command. + +Any symbolic link will be fully resolved in the directory of the +importing project file before the imported project file is examined. + +Any source file in the imported project can be used by the sources of the +importing project, transitively. +Thus if `A` imports `B`, which imports `C`, the sources of +`A` may depend on the sources of `C`, even if `A` does not +import `C` explicitly. However, this is not recommended, because if +and when `B` ceases to import `C`, some sources in `A` will +no longer compile. *gprbuild* has a switch *--no-indirect-imports* +that will report such indirect dependencies. + +.. note:: + + One very important aspect of a project hierarchy is that + **a given source can only belong to one project** (otherwise the project manager + would not know which settings apply to it and when to recompile it). It means + that different project files do not usually share source directories or + when they do, they need to specify precisely which project owns which sources + using attribute `Source_Files` or equivalent. By contrast, 2 projects + can each own a source with the same base file name as long as they live in + different directories. The latter is not true for Ada Sources because of the + correlation between source files and Ada units. + +.. _Cyclic_Project_Dependencies: + +Cyclic Project Dependencies +--------------------------- + +Cyclic dependencies are mostly forbidden: +if `A` imports `B` (directly or indirectly) then `B` +is not allowed to import `A`. However, there are cases when cyclic +dependencies would be beneficial. For these cases, another form of import +between projects exists: the **limited with**. A project `A` that +imports a project `B` with a straight |with| may also be imported, +directly or indirectly, by `B` through a `limited with`. + +The difference between straight |with| and `limited with` is that +the name of a project imported with a `limited with` cannot be used in the +project importing it. In particular, its packages cannot be renamed and +its variables cannot be referred to. + +.. code-block:: gpr + + with "b.gpr"; + with "c.gpr"; + project A is + for Exec_Dir use B'Exec_Dir; -- ok + end A; + + limited with "a.gpr"; -- Cyclic dependency: A -> B -> A + project B is + for Exec_Dir use A'Exec_Dir; -- not ok + end B; + + with "d.gpr"; + project C is + end C; + + limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A + project D is + for Exec_Dir use A'Exec_Dir; -- not ok + end D; + + +.. _Sharing_Between_Projects: + +Sharing Between Projects +------------------------ + +When building an application, it is common to have similar needs in several of +the projects corresponding to the subsystems under construction. For instance, +they will all have the same compilation switches. + +As seen before (see :ref:`Tools_Options_in_Project_Files`), setting compilation +switches for all sources of a subsystem is simple: it is just a matter of +adding a `Compiler.Default_Switches` attribute to each project files with +the same value. Of course, that means duplication of data, and both places need +to be changed in order to recompile the whole application with different +switches. It can become a real problem if there are many subsystems and thus +many project files to edit. + +There are two main approaches to avoiding this duplication: + +* Since :file:`build.gpr` imports :file:`logging.gpr`, we could change it + to reference the attribute in Logging, either through a package renaming, + or by referencing the attribute. The following example shows both cases: + + .. code-block:: gpr + + project Logging is + package Compiler is + for Switches ("Ada") + use ("-O2"); + end Compiler; + package Binder is + for Switches ("Ada") + use ("-E"); + end Binder; + end Logging; + + with "logging.gpr"; + project Build is + package Compiler renames Logging.Compiler; + package Binder is + for Switches ("Ada") use Logging.Binder'Switches ("Ada"); + end Binder; + end Build; + + The solution used for `Compiler` gets the same value for all + attributes of the package, but you cannot modify anything from the + package (adding extra switches or some exceptions). The second + version is more flexible, but more verbose. + + If you need to refer to the value of a variable in an imported + project, rather than an attribute, the syntax is similar but uses + a "." rather than an apostrophe. For instance: + + .. code-block:: gpr + + with "imported"; + project Main is + Var1 := Imported.Var; + end Main; + +* The second approach is to define the switches in a third project. + That project is set up without any sources (so that, as opposed to + the first example, none of the project plays a special role), and + will only be used to define the attributes. Such a project is + typically called :file:`shared.gpr`. + + .. code-block:: gpr + + abstract project Shared is + for Source_Files use (); -- no sources + package Compiler is + for Switches ("Ada") + use ("-O2"); + end Compiler; + end Shared; + + with "shared.gpr"; + project Logging is + package Compiler renames Shared.Compiler; + end Logging; + + with "shared.gpr"; + project Build is + package Compiler renames Shared.Compiler; + end Build; + + As for the first example, we could have chosen to set the attributes + one by one rather than to rename a package. The reason we explicitly + indicate that `Shared` has no sources is so that it can be created + in any directory and we are sure it shares no sources with `Build` + or `Logging`, which of course would be invalid. + + .. index:: project qualifier (GNAT Project Manager) + + Note the additional use of the **abstract** qualifier in :file:`shared.gpr`. + This qualifier is optional, but helps convey the message that we do not + intend this project to have sources (see :ref:`Qualified_Projects` for + more qualifiers). + + +.. _Global_Attributes: + +Global Attributes +----------------- + +We have already seen many examples of attributes used to specify a special +option of one of the tools involved in the build process. Most of those +attributes are project specific. That it to say, they only affect the invocation +of tools on the sources of the project where they are defined. + +There are a few additional attributes that apply to all projects in a +hierarchy as long as they are defined on the "main" project. +The main project is the project explicitly mentioned on the command-line. +The project hierarchy is the "with"-closure of the main project. + +Here is a list of commonly used global attributes: + +.. index:: Global_Configuration_Pragmas (GNAT Project Manager) + +**Builder.Global_Configuration_Pragmas**: + + This attribute points to a file that contains configuration pragmas + to use when building executables. These pragmas apply for all + executables built from this project hierarchy. As we have seen before, + additional pragmas can be specified on a per-project basis by setting the + `Compiler.Local_Configuration_Pragmas` attribute. + +.. index:: Global_Compilation_Switches (GNAT Project Manager) + +**Builder.Global_Compilation_Switches**: + + This attribute is a list of compiler switches to use when compiling any + source file in the project hierarchy. These switches are used in addition + to the ones defined in the `Compiler` package, which only apply to + the sources of the corresponding project. This attribute is indexed on + the name of the language. + +Using such global capabilities is convenient. It can also lead to unexpected +behavior. Especially when several subsystems are shared among different main +projects and the different global attributes are not +compatible. Note that using aggregate projects can be a safer and more powerful +replacement to global attributes. + +.. _Scenarios_in_Projects: + +Scenarios in Projects +===================== + +Various aspects of the projects can be modified based on **scenarios**. These +are user-defined modes that change the behavior of a project. Typical +examples are the setup of platform-specific compiler options, or the use of +a debug and a release mode (the former would activate the generation of debug +information, while the second will focus on improving code optimization). + +Let's enhance our example to support debug and release modes. The issue is to +let the user choose what kind of system he is building: use *-g* as +compiler switches in debug mode and *-O2* in release mode. We will also +set up the projects so that we do not share the same object directory in both +modes; otherwise switching from one to the other might trigger more +recompilations than needed or mix objects from the two modes. + +One naive approach is to create two different project files, say +:file:`build_debug.gpr` and :file:`build_release.gpr`, that set the appropriate +attributes as explained in previous sections. This solution does not scale +well, because in the presence of multiple projects depending on each other, you +will also have to duplicate the complete hierarchy and adapt the project files +to point to the right copies. + +.. index:: scenarios (GNAT Project Manager) + +Instead, project files support the notion of scenarios controlled +by external values. Such values can come from several sources (in decreasing +order of priority): + +.. index:: -X (usage with GNAT Project Manager) + +**Command line**: + When launching *gnatmake* or *gprbuild*, the user can pass + extra *-X* switches to define the external value. In + our case, the command line might look like + + :: + + gnatmake -Pbuild.gpr -Xmode=debug + + or + + :: + + gnatmake -Pbuild.gpr -Xmode=release + + +**Environment variables**: + When the external value does not come from the command line, it can come from + the value of environment variables of the appropriate name. + In our case, if an environment variable called "mode" + exists, its value will be taken into account. + + + +.. index:: external (GNAT Project Manager) + +**External function second parameter**. + +We now need to get that value in the project. The general form is to use +the predefined function **external** which returns the current value of +the external. For instance, we could set up the object directory to point to +either :file:`obj/debug` or :file:`obj/release` by changing our project to + +.. code-block:: gpr + + project Build is + for Object_Dir use "obj/" & external ("mode", "debug"); + ... -- as before + end Build; + +The second parameter to `external` is optional, and is the default +value to use if "mode" is not set from the command line or the environment. + +In order to set the switches according to the different scenarios, other +constructs have to be introduced such as typed variables and case constructions. + +.. index:: typed variable (GNAT Project Manager) +.. index:: case construction (GNAT Project Manager) + +A **typed variable** is a variable that +can take only a limited number of values, similar to an enumeration in Ada. +Such a variable can then be used in a **case construction** and create conditional +sections in the project. The following example shows how this can be done: + +.. code-block:: gpr + + project Build is + type Mode_Type is ("debug", "release"); -- all possible values + Mode : Mode_Type := external ("mode", "debug"); -- a typed variable + + package Compiler is + case Mode is + when "debug" => + for Switches ("Ada") + use ("-g"); + when "release" => + for Switches ("Ada") + use ("-O2"); + end case; + end Compiler; + end Build; + +The project has suddenly grown in size, but has become much more flexible. +`Mode_Type` defines the only valid values for the `mode` variable. If +any other value is read from the environment, an error is reported and the +project is considered as invalid. + +The `Mode` variable is initialized with an external value +defaulting to `"debug"`. This default could be omitted and that would +force the user to define the value. Finally, we can use a case construction to set the +switches depending on the scenario the user has chosen. + +Most aspects of the projects can depend on scenarios. The notable exception +are project dependencies (|with| clauses), which cannot depend on a scenario. + +Scenarios work the same way with **project hierarchies**: you can either +duplicate a variable similar to `Mode` in each of the project (as long +as the first argument to `external` is always the same and the type is +the same), or simply set the variable in the :file:`shared.gpr` project +(see :ref:`Sharing_Between_Projects`). + + +.. _Library_Projects: + +Library Projects +================ + +So far, we have seen examples of projects that create executables. However, +it is also possible to create libraries instead. A **library** is a specific +type of subsystem where, for convenience, objects are grouped together +using system-specific means such as archives or windows DLLs. + +Library projects provide a system- and language-independent way of building +both **static** and **dynamic** libraries. They also support the concept of +**standalone libraries** (SAL) which offer two significant properties: the +elaboration (e.g. initialization) of the library is either automatic or +very simple; a change in the +implementation part of the library implies minimal post-compilation actions on +the complete system and potentially no action at all for the rest of the +system in the case of dynamic SALs. + +There is a restriction on shared library projects: by default, they are only +allowed to import other shared library projects. They are not allowed to +import non library projects or static library projects. + +The GNAT Project Manager takes complete care of the library build, rebuild and +installation tasks, including recompilation of the source files for which +objects do not exist or are not up to date, assembly of the library archive, and +installation of the library (i.e., copying associated source, object and +:file:`ALI` files to the specified location). + + +.. _Building_Libraries: + +Building Libraries +------------------ + +Let's enhance our example and transform the `logging` subsystem into a +library. In order to do so, a few changes need to be made to +:file:`logging.gpr`. Some attributes need to be defined: at least +`Library_Name` and `Library_Dir`; in addition, some other attributes +can be used to specify specific aspects of the library. For readability, it is +also recommended (although not mandatory), to use the qualifier `library` +in front of the `project` keyword. + +.. index:: Library_Name (GNAT Project Manager) + +**Library_Name**: + + This attribute is the name of the library to be built. There is no + restriction on the name of a library imposed by the project manager, except + for stand-alone libraries whose names must follow the syntax of Ada + identifiers; however, there may be system-specific restrictions on the name. + In general, it is recommended to stick to alphanumeric characters (and + possibly single underscores) to help portability. + +.. index:: Library_Dir (GNAT Project Manager) + +**Library_Dir**: + + This attribute is the path (absolute or relative) of the directory where + the library is to be installed. In the process of building a library, + the sources are compiled, the object files end up in the explicit or + implicit `Object_Dir` directory. When all sources of a library + are compiled, some of the compilation artifacts, including the library itself, + are copied to the library_dir directory. This directory must exist and be + writable. It must also be different from the object directory so that cleanup + activities in the Library_Dir do not affect recompilation needs. + +Here is the new version of :file:`logging.gpr` that makes it a library: + +.. code-block:: gpr + + library project Logging is -- "library" is optional + for Library_Name use "logging"; -- will create "liblogging.a" on Unix + for Object_Dir use "obj"; + for Library_Dir use "lib"; -- different from object_dir + end Logging; + +Once the above two attributes are defined, the library project is valid and +is enough for building a library with default characteristics. +Other library-related attributes can be used to change the defaults: + +.. index:: Library_Kind (GNAT Project Manager) + +**Library_Kind**: + + The value of this attribute must be either `"static"`, `"dynamic"` or + `"relocatable"` (the latter is a synonym for dynamic). It indicates + which kind of library should be built (the default is to build a + static library, that is an archive of object files that can potentially + be linked into a static executable). When the library is set to be dynamic, + a separate image is created that will be loaded independently, usually + at the start of the main program execution. Support for dynamic libraries is + very platform specific, for instance on Windows it takes the form of a DLL + while on GNU/Linux, it is a dynamic elf image whose suffix is usually + :file:`.so`. Library project files, on the other hand, can be written in + a platform independent way so that the same project file can be used to build + a library on different operating systems. + + If you need to build both a static and a dynamic library, it is recommended + to use two different object directories, since in some cases some extra code + needs to be generated for the latter. For such cases, one can either define + two different project files, or a single one that uses scenarios to indicate + the various kinds of library to be built and their corresponding object_dir. + +.. index:: Library_ALI_Dir (GNAT Project Manager) + +**Library_ALI_Dir**: + + This attribute may be specified to indicate the directory where the ALI + files of the library are installed. By default, they are copied into the + `Library_Dir` directory, but as for the executables where we have a + separate `Exec_Dir` attribute, you might want to put them in a separate + directory since there can be hundreds of them. The same restrictions as for + the `Library_Dir` attribute apply. + +.. index:: Library_Version (GNAT Project Manager) + +**Library_Version**: + + This attribute is platform dependent, and has no effect on Windows. + On Unix, it is used only for dynamic libraries as the internal + name of the library (the `"soname"`). If the library file name (built + from the `Library_Name`) is different from the `Library_Version`, + then the library file will be a symbolic link to the actual file whose name + will be `Library_Version`. This follows the usual installation schemes + for dynamic libraries on many Unix systems. + + .. code-block:: gpr + + project Logging is + Version := "1"; + for Library_Dir use "lib"; + for Library_Name use "logging"; + for Library_Kind use "dynamic"; + for Library_Version use "liblogging.so." & Version; + end Logging; + + + After the compilation, the directory :file:`lib` will contain both a + :file:`libdummy.so.1` library and a symbolic link to it called + :file:`libdummy.so`. + +.. index:: Library_GCC (GNAT Project Manager) + +**Library_GCC**: + + This attribute is the name of the tool to use instead of "gcc" to link shared + libraries. A common use of this attribute is to define a wrapper script that + accomplishes specific actions before calling gcc (which itself calls the + linker to build the library image). + +.. index:: Library_Options (GNAT Project Manager) + +**Library_Options**: + + This attribute may be used to specify additional switches (last switches) + when linking a shared library. + + It may also be used to add foreign object files to a static library. + Each string in Library_Options is an absolute or relative path of an object + file. When a relative path, it is relative to the object directory. + +.. index:: Leading_Library_Options (GNAT Project Manager) + +**Leading_Library_Options**: + + This attribute, that is taken into account only by *gprbuild*, may be + used to specified leading options (first switches) when linking a shared + library. + +.. index:: Linker_Options (GNAT Project Manager) + +**Linker.Linker_Options**: + + This attribute specifies additional switches to be given to the linker when + linking an executable. It is ignored when defined in the main project and + taken into account in all other projects that are imported directly or + indirectly. These switches complement the `Linker.Switches` + defined in the main project. This is useful when a particular subsystem + depends on an external library: adding this dependency as a + `Linker_Options` in the project of the subsystem is more convenient than + adding it to all the `Linker.Switches` of the main projects that depend + upon this subsystem. + + +.. _Using_Library_Projects: + +Using Library Projects +---------------------- + +When the builder detects that a project file is a library project file, it +recompiles all sources of the project that need recompilation and rebuild the +library if any of the sources have been recompiled. It then groups all object +files into a single file, which is a shared or a static library. This library +can later on be linked with multiple executables. Note that the use +of shard libraries reduces the size of the final executable and can also reduce +the memory footprint at execution time when the library is shared among several +executables. + +It is also possible to build **multi-language libraries**. When using +*gprbuild* as a builder, multi-language library projects allow naturally +the creation of multi-language libraries . *gnatmake*, does not try to +compile non Ada sources. However, when the project is multi-language, it will +automatically link all object files found in the object directory, whether or +not they were compiled from an Ada source file. This specific behavior does not +apply to Ada-only projects which only take into account the objects +corresponding to the sources of the project. + +A non-library project can import a library project. When the builder is invoked +on the former, the library of the latter is only rebuilt when absolutely +necessary. For instance, if a unit of the library is not up-to-date but none of +the executables need this unit, then the unit is not recompiled and the library +is not reassembled. For instance, let's assume in our example that logging has +the following sources: :file:`log1.ads`, :file:`log1.adb`, :file:`log2.ads` and +:file:`log2.adb`. If :file:`log1.adb` has been modified, then the library +:file:`liblogging` will be rebuilt when compiling all the sources of +`Build` only if :file:`proc.ads`, :file:`pack.ads` or :file:`pack.adb` +include a `"with Log1"`. + +To ensure that all the sources in the `Logging` library are +up to date, and that all the sources of `Build` are also up to date, +the following two commands need to be used: + +.. code-block:: sh + + gnatmake -Plogging.gpr + gnatmake -Pbuild.gpr + +All :file:`ALI` files will also be copied from the object directory to the +library directory. To build executables, *gnatmake* will use the +library rather than the individual object files. + +Library projects can also be useful to describe a library that needs to be used +but, for some reason, cannot be rebuilt. For instance, it is the case when some +of the library sources are not available. Such library projects need to use the +`Externally_Built` attribute as in the example below: + +.. code-block: ada-project + + library project Extern_Lib is + for Languages use ("Ada", "C"); + for Source_Dirs use ("lib_src"); + for Library_Dir use "lib2"; + for Library_Kind use "dynamic"; + for Library_Name use "l2"; + for Externally_Built use "true"; -- <<<< + end Extern_Lib; + +In the case of externally built libraries, the `Object_Dir` +attribute does not need to be specified because it will never be +used. + +The main effect of using such an externally built library project is mostly to +affect the linker command in order to reference the desired library. It can +also be achieved by using `Linker.Linker_Options` or `Linker.Switches` +in the project corresponding to the subsystem needing this external library. +This latter method is more straightforward in simple cases but when several +subsystems depend upon the same external library, finding the proper place +for the `Linker.Linker_Options` might not be easy and if it is +not placed properly, the final link command is likely to present ordering issues. +In such a situation, it is better to use the externally built library project +so that all other subsystems depending on it can declare this dependency thanks +to a project |with| clause, which in turn will trigger the builder to find +the proper order of libraries in the final link command. + + +.. _Stand-alone_Library_Projects: + +Stand-alone Library Projects +---------------------------- + +.. index:: standalone libraries (usage with GNAT Project Manager) + +A **stand-alone library** is a library that contains the necessary code to +elaborate the Ada units that are included in the library. A stand-alone +library is a convenient way to add an Ada subsystem to a more global system +whose main is not in Ada since it makes the elaboration of the Ada part mostly +transparent. However, stand-alone libraries are also useful when the main is in +Ada: they provide a means for minimizing relinking & redeployment of complex +systems when localized changes are made. + +The name of a stand-alone library, specified with attribute +`Library_Name`, must have the syntax of an Ada identifier. + +The most prominent characteristic of a stand-alone library is that it offers a +distinction between interface units and implementation units. Only the former +are visible to units outside the library. A stand-alone library project is thus +characterised by a third attribute, usually **Library_Interface**, in addition +to the two attributes that make a project a Library Project +(`Library_Name` and `Library_Dir`). This third attribute may also be +**Interfaces**. **Library_Interface** only works when the interface is in Ada +and takes a list of units as parameter. **Interfaces** works for any supported +language and takes a list of sources as parameter. + +.. index:: Library_Interface (GNAT Project Manager) + +**Library_Interface**: + + This attribute defines an explicit subset of the units of the project. Units + from projects importing this library project may only "with" units whose + sources are listed in the `Library_Interface`. Other sources are + considered implementation units. + + .. code-block:: gpr + + for Library_Dir use "lib"; + for Library_Name use "logging"; + for Library_Interface use ("lib1", "lib2"); -- unit names + +**Interfaces** + + This attribute defines an explicit subset of the source files of a project. + Sources from projects importing this project, can only depend on sources from + this subset. This attribute can be used on non library projects. It can also + be used as a replacement for attribute `Library_Interface`, in which + case, units have to be replaced by source files. For multi-language library + projects, it is the only way to make the project a Stand-Alone Library project + whose interface is not purely Ada. + + +.. index:: Library_Standalone (GNAT Project Manager) + +**Library_Standalone**: + + This attribute defines the kind of standalone library to + build. Values are either `standard` (the default), `no` or + `encapsulated`. When `standard` is used the code to elaborate and + finalize the library is embedded, when `encapsulated` is used the + library can furthermore depend only on static libraries (including + the GNAT runtime). This attribute can be set to `no` to make it clear + that the library should not be standalone in which case the + `Library_Interface` should not defined. Note that this attribute + only applies to shared libraries, so `Library_Kind` must be set + to `dynamic`. + + .. code-block:: gpr + + for Library_Dir use "lib"; + for Library_Name use "logging"; + for Library_Kind use "dynamic"; + for Library_Interface use ("lib1", "lib2"); -- unit names + for Library_Standalone use "encapsulated"; + +In order to include the elaboration code in the stand-alone library, the binder +is invoked on the closure of the library units creating a package whose name +depends on the library name (b~logging.ads/b in the example). +This binder-generated package includes **initialization** and **finalization** +procedures whose names depend on the library name (`logginginit` and +`loggingfinal` in the example). The object corresponding to this package is +included in the library. + +.. index:: Library_Auto_Init (GNAT Project Manager) + +**Library_Auto_Init**: + + A dynamic stand-alone Library is automatically initialized + if automatic initialization of Stand-alone Libraries is supported on the + platform and if attribute **Library_Auto_Init** is not specified or + is specified with the value "true". A static Stand-alone Library is never + automatically initialized. Specifying "false" for this attribute + prevents automatic initialization. + + When a non-automatically initialized stand-alone library is used in an + executable, its initialization procedure must be called before any service of + the library is used. When the main subprogram is in Ada, it may mean that the + initialization procedure has to be called during elaboration of another + package. + + +.. index:: Library_Dir (GNAT Project Manager) + +**Library_Dir**: + + For a stand-alone library, only the :file:`ALI` files of the interface units + (those that are listed in attribute `Library_Interface`) are copied to + the library directory. As a consequence, only the interface units may be + imported from Ada units outside of the library. If other units are imported, + the binding phase will fail. + + +**Binder.Default_Switches**: + + When a stand-alone library is bound, the switches that are specified in + the attribute **Binder.Default_Switches ("Ada")** are + used in the call to *gnatbind*. + + +.. index:: Library_Src_Dir (GNAT Project Manager) + +**Library_Src_Dir**: + + This attribute defines the location (absolute or relative to the project + directory) where the sources of the interface units are copied at + installation time. + These sources includes the specs of the interface units along with the + closure of sources necessary to compile them successfully. That may include + bodies and subunits, when pragmas `Inline` are used, or when there are + generic units in specs. This directory cannot point to the object directory + or one of the source directories, but it can point to the library directory, + which is the default value for this attribute. + + +.. index:: Library_Symbol_Policy (GNAT Project Manager) + +**Library_Symbol_Policy**: + + This attribute controls the export of symbols and, on some platforms (like + VMS) that have the notions of major and minor IDs built in the library + files, it controls the setting of these IDs. It is not supported on all + platforms (where it will just have no effect). It may have one of the + following values: + + * `"autonomous"` or `"default"`: exported symbols are not controlled + + * `"compliant"`: if attribute **Library_Reference_Symbol_File** + is not defined, then it is equivalent to policy "autonomous". If there + are exported symbols in the reference symbol file that are not in the + object files of the interfaces, the major ID of the library is increased. + If there are symbols in the object files of the interfaces that are not + in the reference symbol file, these symbols are put at the end of the list + in the newly created symbol file and the minor ID is increased. + + * `"controlled"`: the attribute **Library_Reference_Symbol_File** must be + defined. The library will fail to build if the exported symbols in the + object files of the interfaces do not match exactly the symbol in the + symbol file. + + * `"restricted"`: The attribute **Library_Symbol_File** must be defined. + The library will fail to build if there are symbols in the symbol file that + are not in the exported symbols of the object files of the interfaces. + Additional symbols in the object files are not added to the symbol file. + + * `"direct"`: The attribute **Library_Symbol_File** must be defined and + must designate an existing file in the object directory. This symbol file + is passed directly to the underlying linker without any symbol processing. + + +.. index:: Library_Reference_Symbol_File (GNAT Project Manager) + +**Library_Reference_Symbol_File** + + This attribute may define the path name of a reference symbol file that is + read when the symbol policy is either "compliant" or "controlled", on + platforms that support symbol control, such as VMS, when building a + stand-alone library. The path may be an absolute path or a path relative + to the project directory. + + +.. index:: Library_Symbol_File (GNAT Project Manager) + +**Library_Symbol_File** + + This attribute may define the name of the symbol file to be created when + building a stand-alone library when the symbol policy is either "compliant", + "controlled" or "restricted", on platforms that support symbol control, + such as VMS. When symbol policy is "direct", then a file with this name + must exist in the object directory. + + +.. _Installing_a_library_with_project_files: + +Installing a library with project files +--------------------------------------- + +When using project files, a usable version of the library is created in the +directory specified by the `Library_Dir` attribute of the library +project file. Thus no further action is needed in order to make use of +the libraries that are built as part of the general application build. + +You may want to install a library in a context different from where the library +is built. This situation arises with third party suppliers, who may want +to distribute a library in binary form where the user is not expected to be +able to recompile the library. The simplest option in this case is to provide +a project file slightly different from the one used to build the library, by +using the `externally_built` attribute. See :ref:`Using_Library_Projects` + +Another option is to use *gprinstall* to install the library in a +different context than the build location. *gprinstall* automatically +generates a project to use this library, and also copies the minimum set of +sources needed to use the library to the install location. +:ref:`Installation` + + +.. _Project_Extension: + +Project Extension +================= + +During development of a large system, it is sometimes necessary to use +modified versions of some of the source files, without changing the original +sources. This can be achieved through the **project extension** facility. + +Suppose for instance that our example `Build` project is built every night +for the whole team, in some shared directory. A developer usually needs to work +on a small part of the system, and might not want to have a copy of all the +sources and all the object files (mostly because that would require too much +disk space, time to recompile everything). He prefers to be able to override +some of the source files in his directory, while taking advantage of all the +object files generated at night. + +Another example can be taken from large software systems, where it is common to have +multiple implementations of a common interface; in Ada terms, multiple +versions of a package body for the same spec. For example, one implementation +might be safe for use in tasking programs, while another might be used only +in sequential applications. This can be modeled in GNAT using the concept +of *project extension*. If one project (the 'child') *extends* +another project (the 'parent') then by default all source files of the +parent project are inherited by the child, but the child project can +override any of the parent's source files with new versions, and can also +add new files or remove unnecessary ones. +This facility is the project analog of a type extension in +object-oriented programming. Project hierarchies are permitted (an extending +project may itself be extended), and a project that +extends a project can also import other projects. + +A third example is that of using project extensions to provide different +versions of the same system. For instance, assume that a `Common` +project is used by two development branches. One of the branches has now +been frozen, and no further change can be done to it or to `Common`. +However, the other development branch still needs evolution of `Common`. +Project extensions provide a flexible solution to create a new version +of a subsystem while sharing and reusing as much as possible from the original +one. + +A project extension implicitly inherits all the sources and objects from the +project it extends. It is possible to create a new version of some of the +sources in one of the additional source directories of the extending +project. Those new versions hide the original versions. Adding new sources or +removing existing ones is also possible. Here is an example on how to extend +the project `Build` from previous examples: + +.. code-block:: gpr + + project Work extends "../bld/build.gpr" is + end Work; + +The project after **extends** is the one being extended. As usual, it can be +specified using an absolute path, or a path relative to any of the directories +in the project path (see :ref:`Project_Dependencies`). This project does not +specify source or object directories, so the default values for these +attributes will be used that is to say the current directory (where project +`Work` is placed). We can compile that project with + +.. code-block:: sh + + gprbuild -Pwork + +If no sources have been placed in the current directory, this command +won't do anything, since this project does not change the +sources it inherited from `Build`, therefore all the object files +in `Build` and its dependencies are still valid and are reused +automatically. + +Suppose we now want to supply an alternate version of :file:`pack.adb` but use +the existing versions of :file:`pack.ads` and :file:`proc.adb`. We can create +the new file in Work's current directory (likely by copying the one from the +`Build` project and making changes to it. If new packages are needed at +the same time, we simply create new files in the source directory of the +extending project. + +When we recompile, *gprbuild* will now automatically recompile +this file (thus creating :file:`pack.o` in the current directory) and +any file that depends on it (thus creating :file:`proc.o`). Finally, the +executable is also linked locally. + +Note that we could have obtained the desired behavior using project import +rather than project inheritance. A `base` project would contain the +sources for :file:`pack.ads` and :file:`proc.adb`, and `Work` would +import `base` and add :file:`pack.adb`. In this scenario, `base` +cannot contain the original version of :file:`pack.adb` otherwise there would be +2 versions of the same unit in the closure of the project and this is not +allowed. Generally speaking, it is not recommended to put the spec and the +body of a unit in different projects since this affects their autonomy and +reusability. + +In a project file that extends another project, it is possible to +indicate that an inherited source is **not part** of the sources of the +extending project. This is necessary sometimes when a package spec has +been overridden and no longer requires a body: in this case, it is +necessary to indicate that the inherited body is not part of the sources +of the project, otherwise there will be a compilation error +when compiling the spec. + +.. index:: Excluded_Source_Files (GNAT Project Manager) + +.. index:: Excluded_Source_List_File (GNAT Project Manager) + +For that purpose, the attribute **Excluded_Source_Files** is used. +Its value is a list of file names. +It is also possible to use attribute `Excluded_Source_List_File`. +Its value is the path of a text file containing one file name per +line. + +.. code-block:: gpr + + project Work extends "../bld/build.gpr" is + for Source_Files use ("pack.ads"); + -- New spec of Pkg does not need a completion + for Excluded_Source_Files use ("pack.adb"); + end Work; + + +All packages that are not declared in the extending project are inherited from +the project being extended, with their attributes, with the exception of +`Linker'Linker_Options` which is never inherited. In particular, an +extending project retains all the switches specified in the project being +extended. + +At the project level, if they are not declared in the extending project, some +attributes are inherited from the project being extended. They are: +`Languages`, `Main` (for a root non library project) and +`Library_Name` (for a project extending a library project). + +.. _Project_Hierarchy_Extension: + +Project Hierarchy Extension +--------------------------- + +One of the fundamental restrictions in project extension is the following: +**A project is not allowed to import directly or indirectly at the same time an extending project and one of its ancestors**. + +For example, consider the following hierarchy of projects. + +:: + + a.gpr contains package A1 + b.gpr, imports a.gpr and contains B1, which depends on A1 + c.gpr, imports b.gpr and contains C1, which depends on B1 + +If we want to locally extend the packages `A1` and `C1`, we need to +create several extending projects: + +:: + + a_ext.gpr which extends a.gpr, and overrides A1 + b_ext.gpr which extends b.gpr and imports a_ext.gpr + c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1 + +.. code-block:: gpr + + project A_Ext extends "a.gpr" is + for Source_Files use ("a1.adb", "a1.ads"); + end A_Ext; + + with "a_ext.gpr"; + project B_Ext extends "b.gpr" is + end B_Ext; + + with "b_ext.gpr"; + project C_Ext extends "c.gpr" is + for Source_Files use ("c1.adb"); + end C_Ext; + +The extension :file:`b_ext.gpr` is required, even though we are not overriding +any of the sources of :file:`b.gpr` because otherwise :file:`c_expr.gpr` would +import :file:`b.gpr` which itself knows nothing about :file:`a_ext.gpr`. + +.. index:: extends all (GNAT Project Manager) + +When extending a large system spanning multiple projects, it is often +inconvenient to extend every project in the hierarchy that is impacted by a +small change introduced in a low layer. In such cases, it is possible to create +an **implicit extension** of an entire hierarchy using **extends all** +relationship. + +When the project is extended using `extends all` inheritance, all projects +that are imported by it, both directly and indirectly, are considered virtually +extended. That is, the project manager creates implicit projects +that extend every project in the hierarchy; all these implicit projects do not +control sources on their own and use the object directory of +the "extending all" project. + +It is possible to explicitly extend one or more projects in the hierarchy +in order to modify the sources. These extending projects must be imported by +the "extending all" project, which will replace the corresponding virtual +projects with the explicit ones. + +When building such a project hierarchy extension, the project manager will +ensure that both modified sources and sources in implicit extending projects +that depend on them are recompiled. + +Thus, in our example we could create the following projects instead: + +:: + + a_ext.gpr, extends a.gpr and overrides A1 + c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1 + +.. code-block:: gpr + + project A_Ext extends "a.gpr" is + for Source_Files use ("a1.adb", "a1.ads"); + end A_Ext; + + with "a_ext.gpr"; + project C_Ext extends all "c.gpr" is + for Source_Files use ("c1.adb"); + end C_Ext; + + +When building project :file:`c_ext.gpr`, the entire modified project space is +considered for recompilation, including the sources of :file:`b.gpr` that are +impacted by the changes in `A1` and `C1`. + + +.. _Aggregate_Projects: + +Aggregate Projects +================== + +Aggregate projects are an extension of the project paradigm, and are +meant to solve a few specific use cases that cannot be solved directly +using standard projects. This section will go over a few of these use +cases to try to explain what you can use aggregate projects for. + + +.. _Building_all_main_programs_from_a_single_project_tree: + +Building all main programs from a single project tree +----------------------------------------------------- + +Most often, an application is organized into modules and submodules, +which are very conveniently represented as a project tree or graph +(the root project A |withs| the projects for each modules (say B and C), +which in turn |with| projects for submodules. + +Very often, modules will build their own executables (for testing +purposes for instance), or libraries (for easier reuse in various +contexts). + +However, if you build your project through *gnatmake* or +*gprbuild*, using a syntax similar to + +:: + + gprbuild -PA.gpr + +this will only rebuild the main programs of project A, not those of the +imported projects B and C. Therefore you have to spawn several +*gnatmake* commands, one per project, to build all executables. +This is a little inconvenient, but more importantly is inefficient +because *gnatmake* needs to do duplicate work to ensure that sources are +up-to-date, and cannot easily compile things in parallel when using +the -j switch. + +Also libraries are always rebuilt when building a project. + +You could therefore define an aggregate project Agg that groups A, B +and C. Then, when you build with + +:: + + gprbuild -PAgg.gpr + +this will build all mains from A, B and C. + +.. code-block:: gpr + + aggregate project Agg is + for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); + end Agg; + +If B or C do not define any main program (through their Main +attribute), all their sources are built. When you do not group them +in the aggregate project, only those sources that are needed by A +will be built. + +If you add a main to a project P not already explicitly referenced in the +aggregate project, you will need to add "p.gpr" in the list of project +files for the aggregate project, or the main will not be built when +building the aggregate project. + +Aggregate projects are supported only with *gprbuild*, not with +*gnatmake*. + + +.. _Building_a_set_of_projects_with_a_single_command: + +Building a set of projects with a single command +------------------------------------------------ + +One other case is when you have multiple applications and libraries +that are built independently from each other (but can be built in +parallel). For instance, you have a project tree rooted at A, and +another one (which might share some subprojects) rooted at B. + +Using only *gprbuild*, you could do + +.. code-block:: sh + + gprbuild -PA.gpr + gprbuild -PB.gpr + +to build both. But again, *gprbuild* has to do some duplicate work for +those files that are shared between the two, and cannot truly build +things in parallel efficiently. + +If the two projects are really independent, share no sources other +than through a common subproject, and have no source files with a +common basename, you could create a project C that imports A and +B. But these restrictions are often too strong, and one has to build +them independently. An aggregate project does not have these +limitations and can aggregate two project trees that have common +sources. + +This scenario is particularly useful in environments like VxWorks 653 +where the applications running in the multiple partitions can be built +in parallel through a single *gprbuild* command. This also works nicely +with Annex E. + + +.. _Define_a_build_environment: + +Define a build environment +-------------------------- + +The environment variables at the time you launch *gprbuild* +will influence the view these tools have of the project +(PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the +projects, environment variables that are referenced in project files +through the "external" built-in function, ...). Several command line switches +can be used to override those (-X or -aP), but on some systems and +with some projects, this might make the command line too long, and on +all systems often make it hard to read. + +An aggregate project can be used to set the environment for all +projects built through that aggregate. One of the nice aspects is that +you can put the aggregate project under configuration management, and +make sure all your user have a consistent environment when +building. The syntax looks like + +.. code-block:: gpr + + aggregate project Agg is + for Project_Files use ("A.gpr", "B.gpr"); + for Project_Path use ("../dir1", "../dir1/dir2"); + for External ("BUILD") use "PRODUCTION"; + + package Builder is + for Switches ("Ada") use ("-q"); + end Builder; + end Agg; + +One of the often requested features in projects is to be able to +reference external variables in |with| declarations, as in + +.. code-block:: gpr + + with external("SETUP") & "path/prj.gpr"; -- ILLEGAL + project MyProject is + ... + end MyProject; + +For various reasons, this is not allowed. But using aggregate projects provide +an elegant solution. For instance, you could use a project file like: + +.. code-block:: gpr + + aggregate project Agg is + for Project_Path use (external("SETUP") & "path"); + for Project_Files use ("myproject.gpr"); + end Agg; + + with "prj.gpr"; -- searched on Agg'Project_Path + project MyProject is + ... + end MyProject; + + +.. _Performance_improvements_in_builder: + +Performance improvements in builder +----------------------------------- + +The loading of aggregate projects is optimized in *gprbuild*, +so that all files are searched for only once on the disk +(thus reducing the number of system calls and contributing to faster +compilation times, especially on systems with sources on remote +servers). As part of the loading, *gprbuild* +computes how and where a source file should be compiled, and even if it is +found several times in the aggregated projects it will be compiled only +once. + +Since there is no ambiguity as to which switches should be used, files +can be compiled in parallel (through the usual -j switch) and this can +be done while maximizing the use of CPUs (compared to launching +multiple *gprbuild* and *gnatmake* commands in parallel). + + +.. _Syntax_of_aggregate_projects: + +Syntax of aggregate projects +---------------------------- + +An aggregate project follows the general syntax of project files. The +recommended extension is still :file:`.gpr`. However, a special +`aggregate` qualifier must be put before the keyword +`project`. + +An aggregate project cannot |with| any other project (standard or +aggregate), except an abstract project which can be used to share attribute +values. Also, aggregate projects cannot be extended or imported though a +|with| clause by any other project. Building other aggregate projects from +an aggregate project is done through the Project_Files attribute (see below). + +An aggregate project does not have any source files directly (only +through other standard projects). Therefore a number of the standard +attributes and packages are forbidden in an aggregate project. Here is the +(non exhaustive) list: + +* Languages +* Source_Files, Source_List_File and other attributes dealing with + list of sources. +* Source_Dirs, Exec_Dir and Object_Dir +* Library_Dir, Library_Name and other library-related attributes +* Main +* Roots +* Externally_Built +* Inherit_Source_Path +* Excluded_Source_Dirs +* Locally_Removed_Files +* Excluded_Source_Files +* Excluded_Source_List_File +* Interfaces + +The only package that is authorized (albeit optional) is +Builder. Other packages (in particular Compiler, Binder and Linker) +are forbidden. + +The following three attributes can be used only in an aggregate project: + +.. index:: Project_Files (GNAT Project Manager) + +**Project_Files**: + + This attribute is compulsory (or else we are not aggregating any project, + and thus not doing anything). It specifies a list of :file:`.gpr` files + that are grouped in the aggregate. The list may be empty. The project + files can be either other aggregate projects, or standard projects. When + grouping standard projects, you can have both the root of a project tree + (and you do not need to specify all its imported projects), and any project + within the tree. + + Basically, the idea is to specify all those projects that have + main programs you want to build and link, or libraries you want to + build. You can even specify projects that do not use the Main + attribute nor the `Library_*` attributes, and the result will be to + build all their source files (not just the ones needed by other + projects). + + The file can include paths (absolute or relative). Paths are relative to + the location of the aggregate project file itself (if you use a base name, + we expect to find the .gpr file in the same directory as the aggregate + project file). The environment variables `ADA_PROJECT_PATH`, + `GPR_PROJECT_PATH` and `GPR_PROJECT_PATH_FILE` are not used to find + the project files. The extension :file:`.gpr` is mandatory, since this attribute + contains file names, not project names. + + Paths can also include the `"*"` and `"**"` globbing patterns. The + latter indicates that any subdirectory (recursively) will be + searched for matching files. The latter (`"**"`) can only occur at the + last position in the directory part (ie `"a/**/*.gpr"` is supported, but + not `"**/a/*.gpr"`). Starting the pattern with `"**"` is equivalent + to starting with `"./**"`. + + For now, the pattern `"*"` is only allowed in the filename part, not + in the directory part. This is mostly for efficiency reasons to limit the + number of system calls that are needed. + + Here are a few valid examples: + + .. code-block:: gpr + + for Project_Files use ("a.gpr", "subdir/b.gpr"); + -- two specific projects relative to the directory of agg.gpr + + for Project_Files use ("/.gpr"); + -- all projects recursively + + +.. index:: Project_Path (GNAT Project Manager) + +**Project_Path**: + + This attribute can be used to specify a list of directories in + which to look for project files in |with| declarations. + + When you specify a project in Project_Files (say `x/y/a.gpr`), and + `a.gpr` imports a project `b.gpr`, only `b.gpr` is searched in + the project path. `a.gpr` must be exactly at + `<dir of the aggregate>/x/y/a.gpr`. + + This attribute, however, does not affect the search for the aggregated + project files specified with `Project_Files`. + + Each aggregate project has its own `Project_Path` (that is if + `agg1.gpr` includes `agg2.gpr`, they can potentially both have a + different `Project_Path`). + + This project path is defined as the concatenation, in that order, of: + + * the current directory; + + * followed by the command line -aP switches; + + * then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment + variables; + + * then the directories from the Project_Path attribute; + + * and finally the predefined directories. + + In the example above, agg2.gpr's project path is not influenced by + the attribute agg1'Project_Path, nor is agg1 influenced by + agg2'Project_Path. + + This can potentially lead to errors. Consider the following example: + + .. -- + -- +---------------+ +----------------+ + -- | Agg1.gpr |-=--includes--=-->| Agg2.gpr | + -- | 'project_path| | 'project_path | + -- | | | | + -- +---------------+ +----------------+ + -- : : + -- includes includes + -- : : + -- v v + -- +-------+ +---------+ + -- | P.gpr |<---------- withs --------| Q.gpr | + -- +-------+---------\ +---------+ + -- | | + -- withs | + -- | | + -- v v + -- +-------+ +---------+ + -- | R.gpr | | R'.gpr | + -- +-------+ +---------+ + + .. image:: project-manager-figure.png + + When looking for p.gpr, both aggregates find the same physical file on + the disk. However, it might happen that with their different project + paths, both aggregate projects would in fact find a different r.gpr. + Since we have a common project (p.gpr) "with"ing two different r.gpr, + this will be reported as an error by the builder. + + Directories are relative to the location of the aggregate project file. + + Example: + + .. code-block:: gpr + + for Project_Path use ("/usr/local/gpr", "gpr/"); + +.. index:: External (GNAT Project Manager) + +**External**: + + This attribute can be used to set the value of environment + variables as retrieved through the `external` function + in projects. It does not affect the environment variables + themselves (so for instance you cannot use it to change the value + of your PATH as seen from the spawned compiler). + + This attribute affects the external values as seen in the rest of + the aggregate project, and in the aggregated projects. + + The exact value of external a variable comes from one of three + sources (each level overrides the previous levels): + + * An External attribute in aggregate project, for instance + `for External ("BUILD_MODE") use "DEBUG"`; + + * Environment variables. + These override the value given by the attribute, so that + users can override the value set in the (presumably shared + with others team members) aggregate project. + + * The -X command line switch to *gprbuild*. + This always takes precedence. + + This attribute is only taken into account in the main aggregate + project (i.e. the one specified on the command line to *gprbuild*), + and ignored in other aggregate projects. It is invalid + in standard projects. + The goal is to have a consistent value in all + projects that are built through the aggregate, which would not + be the case in the diamond case: A groups the aggregate + projects B and C, which both (either directly or indirectly) + build the project P. If B and C could set different values for + the environment variables, we would have two different views of + P, which in particular might impact the list of source files in P. + + +.. _package_Builder_in_aggregate_projects: + +package Builder in aggregate projects +------------------------------------- + +As mentioned above, only the package Builder can be specified in +an aggregate project. In this package, only the following attributes +are valid: + +.. index:: Switches (GNAT Project Manager) + +**Switches**: + + This attribute gives the list of switches to use for *gprbuild*. + Because no mains can be specified for aggregate projects, the only possible + index for attribute `Switches` is `others`. All other indexes will + be ignored. + + Example: + + .. code-block:: gpr + + for Switches (others) use ("-v", "-k", "-j8"); + + These switches are only read from the main aggregate project (the + one passed on the command line), and ignored in all other aggregate + projects or projects. + + It can only contain builder switches, not compiler switches. + +.. index:: Global_Compilation_Switches (GNAT Project Manager) + +**Global_Compilation_Switches** + + This attribute gives the list of compiler switches for the various + languages. For instance, + + .. code-block:: gpr + + for Global_Compilation_Switches ("Ada") use ("O1", "-g"); + for Global_Compilation_Switches ("C") use ("-O2"); + + This attribute is only taken into account in the aggregate project + specified on the command line, not in other aggregate projects. + + In the projects grouped by that aggregate, the attribute + Builder.Global_Compilation_Switches is also ignored. However, the + attribute Compiler.Default_Switches will be taken into account (but + that of the aggregate have higher priority). The attribute + Compiler.Switches is also taken into account and can be used to + override the switches for a specific file. As a result, it always + has priority. + + The rules are meant to avoid ambiguities when compiling. For + instance, aggregate project Agg groups the projects A and B, that + both depend on C. Here is an extra for all of these projects: + + + .. code-block:: gpr + + aggregate project Agg is + for Project_Files use ("a.gpr", "b.gpr"); + package Builder is + for Global_Compilation_Switches ("Ada") use ("-O2"); + end Builder; + end Agg; + + with "c.gpr"; + project A is + package Builder is + for Global_Compilation_Switches ("Ada") use ("-O1"); + -- ignored + end Builder; + + package Compiler is + for Default_Switches ("Ada") + use ("-O1", "-g"); + for Switches ("a_file1.adb") + use ("-O0"); + end Compiler; + end A; + + with "c.gpr"; + project B is + package Compiler is + for Default_Switches ("Ada") use ("-O0"); + end Compiler; + end B; + + project C is + package Compiler is + for Default_Switches ("Ada") + use ("-O3", + "-gnatn"); + for Switches ("c_file1.adb") + use ("-O0", "-g"); + end Compiler; + end C; + + + then the following switches are used: + + * all files from project A except a_file1.adb are compiled + with "-O2 -g", since the aggregate project has priority. + + * the file a_file1.adb is compiled with + "-O0", since the Compiler.Switches has priority + + * all files from project B are compiled with + "-O2", since the aggregate project has priority + + * all files from C are compiled with "-O2 -gnatn", except for + c_file1.adb which is compiled with "-O0 -g" + + Even though C is seen through two paths (through A and through + B), the switches used by the compiler are unambiguous. + + +.. index:: Global_Configuration_Pragmas (GNAT Project Manager) + +**Global_Configuration_Pragmas** + + This attribute can be used to specify a file containing + configuration pragmas, to be passed to the Ada compiler. Since we + ignore the package Builder in other aggregate projects and projects, + only those pragmas defined in the main aggregate project will be + taken into account. + + Projects can locally add to those by using the + `Compiler.Local_Configuration_Pragmas` attribute if they need. + + +.. index:: Global_Config_File (GNAT Project Manager) + +**Global_Config_File** + + This attribute, indexed with a language name, can be used to specify a config + when compiling sources of the language. For Ada, these files are configuration + pragmas files. + +For projects that are built through the aggregate, the package Builder +is ignored, except for the Executable attribute which specifies the +name of the executables resulting from the link of the main programs, and +for the Executable_Suffix. + + +.. _Aggregate_Library_Projects: + +Aggregate Library Projects +========================== + +Aggregate library projects make it possible to build a single library +using object files built using other standard or library +projects. This gives the flexibility to describe an application as +having multiple modules (a GUI, database access, ...) using different +project files (so possibly built with different compiler options) and +yet create a single library (static or relocatable) out of the +corresponding object files. + +.. _Building_aggregate_library_projects: + +Building aggregate library projects +----------------------------------- + +For example, we can define an aggregate project Agg that groups A, B +and C: + +.. code-block:: gpr + + aggregate library project Agg is + for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); + for Library_Name use ("agg"); + for Library_Dir use ("lagg"); + end Agg; + +Then, when you build with: + +.. code-block:: sh + + gprbuild agg.gpr + +This will build all units from projects A, B and C and will create a +static library named :file:`libagg.a` in the :file:`lagg` +directory. An aggregate library project has the same set of +restriction as a standard library project. + +Note that a shared aggregate library project cannot aggregate a +static library project. In platforms where a compiler option is +required to create relocatable object files, a Builder package in the +aggregate library project may be used: + +.. code-block:: gpr + + aggregate library project Agg is + for Project_Files use ("a.gpr", "b.gpr", "c.gpr"); + for Library_Name use ("agg"); + for Library_Dir use ("lagg"); + for Library_Kind use "relocatable"; + + package Builder is + for Global_Compilation_Switches ("Ada") use ("-fPIC"); + end Builder; + end Agg; + +With the above aggregate library Builder package, the `-fPIC` +option will be passed to the compiler when building any source code +from projects :file:`a.gpr`, :file:`b.gpr` and :file:`c.gpr`. + + +.. _Syntax_of_aggregate_library_projects: + +Syntax of aggregate library projects +------------------------------------ + +An aggregate library project follows the general syntax of project +files. The recommended extension is still :file:`.gpr`. However, a special +`aggregate library` qualifier must be put before the keyword +`project`. + +An aggregate library project cannot |with| any other project +(standard or aggregate), except an abstract project which can be used +to share attribute values. + +An aggregate library project does not have any source files directly (only +through other standard projects). Therefore a number of the standard +attributes and packages are forbidden in an aggregate library +project. Here is the (non exhaustive) list: + +* Languages +* Source_Files, Source_List_File and other attributes dealing with + list of sources. +* Source_Dirs, Exec_Dir and Object_Dir +* Main +* Roots +* Externally_Built +* Inherit_Source_Path +* Excluded_Source_Dirs +* Locally_Removed_Files +* Excluded_Source_Files +* Excluded_Source_List_File +* Interfaces + +The only package that is authorized (albeit optional) is Builder. + +The Project_Files attribute (See :ref:`Aggregate_Projects`) is used to +described the aggregated projects whose object files have to be +included into the aggregate library. The environment variables +`ADA_PROJECT_PATH`, `GPR_PROJECT_PATH` and +`GPR_PROJECT_PATH_FILE` are not used to find the project files. + + +.. _Project_File_Reference: + +Project File Reference +====================== + +This section describes the syntactic structure of project files, the various +constructs that can be used. Finally, it ends with a summary of all available +attributes. + + +.. _Project_Declaration: + +Project Declaration +------------------- + +Project files have an Ada-like syntax. The minimal project file is: + +.. code-block:: gpr + + project Empty is + end Empty; + +The identifier `Empty` is the name of the project. +This project name must be present after the reserved +word `end` at the end of the project file, followed by a semi-colon. + +**Identifiers** (i.e., the user-defined names such as project or variable names) +have the same syntax as Ada identifiers: they must start with a letter, +and be followed by zero or more letters, digits or underscore characters; +it is also illegal to have two underscores next to each other. Identifiers +are always case-insensitive ("Name" is the same as "name"). + +:: + + simple_name ::= identifier + name ::= simple_name { . simple_name } + +**Strings** are used for values of attributes or as indexes for these +attributes. They are in general case sensitive, except when noted +otherwise (in particular, strings representing file names will be case +insensitive on some systems, so that "file.adb" and "File.adb" both +represent the same file). + +**Reserved words** are the same as for standard Ada 95, and cannot +be used for identifiers. In particular, the following words are currently +used in project files, but others could be added later on. In bold are the +extra reserved words in project files: +``all``, ``at``, ``case``, ``end``, ``for``, ``is``, ``limited``, +``null``, ``others``, ``package``, ``renames``, ``type``, ``use``, ``when``, +``with``, **extends**, **external**, **project**. + +**Comments** in project files have the same syntax as in Ada, two consecutive +hyphens through the end of the line. + +A project may be an **independent project**, entirely defined by a single +project file. Any source file in an independent project depends only +on the predefined library and other source files in the same project. +But a project may also depend on other projects, either by importing them +through **with clauses**, or by **extending** at most one other project. Both +types of dependency can be used in the same project. + +A path name denotes a project file. It can be absolute or relative. +An absolute path name includes a sequence of directories, in the syntax of +the host operating system, that identifies uniquely the project file in the +file system. A relative path name identifies the project file, relative +to the directory that contains the current project, or relative to a +directory listed in the environment variables ADA_PROJECT_PATH and +GPR_PROJECT_PATH. Path names are case sensitive if file names in the host +operating system are case sensitive. As a special case, the directory +separator can always be "/" even on Windows systems, so that project files +can be made portable across architectures. +The syntax of the environment variables ADA_PROJECT_PATH and +GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and +semicolons on Windows. + +A given project name can appear only once in a context clause. + +It is illegal for a project imported by a context clause to refer, directly +or indirectly, to the project in which this context clause appears (the +dependency graph cannot contain cycles), except when one of the with clauses +in the cycle is a **limited with**. + +.. code-block:: gpr + + with "other_project.gpr"; + project My_Project extends "extended.gpr" is + end My_Project; + +These dependencies form a **directed graph**, potentially cyclic when using +**limited with**. The subgraph reflecting the **extends** relations is a tree. + +A project's **immediate sources** are the source files directly defined by +that project, either implicitly by residing in the project source directories, +or explicitly through any of the source-related attributes. +More generally, a project's **sources** are the immediate sources of the +project together with the immediate sources (unless overridden) of any project +on which it depends directly or indirectly. + +A **project hierarchy** can be created, where projects are children of +other projects. The name of such a child project must be `Parent.Child`, +where `Parent` is the name of the parent project. In particular, this +makes all |with| clauses of the parent project automatically visible +in the child project. + +:: + + project ::= context_clause project_declaration + + context_clause ::= {with_clause} + with_clause ::= *with* path_name { , path_name } ; + path_name ::= string_literal + + project_declaration ::= simple_project_declaration | project_extension + simple_project_declaration ::= + project <project_>name is + {declarative_item} + end <project_>simple_name; + + +.. _Qualified_Projects: + +Qualified Projects +------------------ + +Before the reserved `project`, there may be one or two **qualifiers**, that +is identifiers or reserved words, to qualify the project. +The current list of qualifiers is: + +**abstract**: + Qualifies a project with no sources. + Such a project must either have no declaration of attributes `Source_Dirs`, + `Source_Files`, `Languages` or `Source_List_File`, or one of + `Source_Dirs`, `Source_Files`, or `Languages` must be declared + as empty. If it extends another project, the project it extends must also be a + qualified abstract project. + +**standard**: + A standard project is a non library project with sources. + This is the default (implicit) qualifier. + +**aggregate**: + A project whose sources are aggregated from other project files. + +**aggregate library**: + A library whose sources are aggregated from other project + or library project files. + +**library**: + A library project must declare both attributes + Library_Name` and `Library_Dir`. + +**configuration**: + A configuration project cannot be in a project tree. + It describes compilers and other tools to *gprbuild*. + + +.. _Declarations: + +Declarations +------------ + +Declarations introduce new entities that denote types, variables, attributes, +and packages. Some declarations can only appear immediately within a project +declaration. Others can appear within a project or within a package. + +:: + + declarative_item ::= simple_declarative_item + | typed_string_declaration + | package_declaration + + simple_declarative_item ::= variable_declaration + | typed_variable_declaration + | attribute_declaration + | case_construction + | empty_declaration + + empty_declaration ::= *null* ; + +An empty declaration is allowed anywhere a declaration is allowed. It has +no effect. + + +.. _Packages: + +Packages +-------- + +A project file may contain **packages**, that group attributes (typically +all the attributes that are used by one of the GNAT tools). + +A package with a given name may only appear once in a project file. +The following packages are currently supported in project files +(See :ref:`Attributes` for the list of attributes that each can contain). + +*Binder* + This package specifies characteristics useful when invoking the binder either + directly via the *gnat* driver or when using a builder such as + *gnatmake* or *gprbuild*. See :ref:`Main_Subprograms`. + +*Builder* + This package specifies the compilation options used when building an + executable or a library for a project. Most of the options should be + set in one of `Compiler`, `Binder` or `Linker` packages, + but there are some general options that should be defined in this + package. See :ref:`Main_Subprograms`, and :ref:`Executable_File_Names` in + particular. + +.. only:: PRO or GPL + + *Check* + This package specifies the options used when calling the checking tool + *gnatcheck* via the *gnat* driver. Its attribute + **Default_Switches** has the same semantics as for the package + `Builder`. The first string should always be `-rules` to specify + that all the other options belong to the `-rules` section of the + parameters to *gnatcheck*. + +*Clean* + This package specifies the options used when cleaning a project or a project + tree using the tools *gnatclean* or *gprclean*. + +*Compiler* + This package specifies the compilation options used by the compiler for + each languages. See :ref:`Tools_Options_in_Project_Files`. + +*Cross_Reference* + This package specifies the options used when calling the library tool + *gnatxref* via the *gnat* driver. Its attributes + **Default_Switches** and **Switches** have the same semantics as for the + package `Builder`. + +.. only:: PRO or GPL + + *Eliminate* + This package specifies the options used when calling the tool + *gnatelim* via the *gnat* driver. Its attributes + **Default_Switches** and **Switches** have the same semantics as for the + package `Builder`. + +*Finder* + This package specifies the options used when calling the search tool + *gnatfind* via the *gnat* driver. Its attributes + **Default_Switches** and **Switches** have the same semantics as for the + package `Builder`. + +*Gnatls* + This package specifies the options to use when invoking *gnatls* + via the *gnat* driver. + +.. only:: PRO or GPL + + *Gnatstub* + This package specifies the options used when calling the tool + *gnatstub* via the *gnat* driver. Its attributes + **Default_Switches** and **Switches** have the same semantics as for the + package `Builder`. + +*IDE* + This package specifies the options used when starting an integrated + development environment, for instance *GPS* or *Gnatbench*. + +*Install* + This package specifies the options used when installing a project + with *gprinstall*. See :ref:`Installation`. + +*Linker* + This package specifies the options used by the linker. + See :ref:`Main_Subprograms`. + +.. only:: PRO or GPL + + *Metrics* + This package specifies the options used when calling the tool + *gnatmetric* via the *gnat* driver. Its attributes + **Default_Switches** and **Switches** have the same semantics as for the + package `Builder`. + +*Naming* + This package specifies the naming conventions that apply + to the source files in a project. In particular, these conventions are + used to automatically find all source files in the source directories, + or given a file name to find out its language for proper processing. + See :ref:`Naming_Schemes`. + + .. only: PRO or GPL + + *Pretty_Printer* + This package specifies the options used when calling the formatting tool + *gnatpp* via the *gnat* driver. Its attributes + **Default_Switches** and **Switches** have the same semantics as for the + package `Builder`. + +*Remote* + This package is used by *gprbuild* to describe how distributed + compilation should be done. + +*Stack* + This package specifies the options used when calling the tool + *gnatstack* via the *gnat* driver. Its attributes + **Default_Switches** and **Switches** have the same semantics as for the + package `Builder`. + +*Synchronize* + This package specifies the options used when calling the tool + *gnatsync* via the *gnat* driver. + +In its simplest form, a package may be empty: + +.. code-block:: gpr + + project Simple is + package Builder is + end Builder; + end Simple; + +A package may contain **attribute declarations**, +**variable declarations** and **case constructions**, as will be +described below. + +When there is ambiguity between a project name and a package name, +the name always designates the project. To avoid possible confusion, it is +always a good idea to avoid naming a project with one of the +names allowed for packages or any name that starts with `gnat`. + +A package can also be defined by a **renaming declaration**. The new package +renames a package declared in a different project file, and has the same +attributes as the package it renames. The name of the renamed package +must be the same as the name of the renaming package. The project must +contain a package declaration with this name, and the project +must appear in the context clause of the current project, or be its parent +project. It is not possible to add or override attributes to the renaming +project. If you need to do so, you should use an **extending declaration** +(see below). + +Packages that are renamed in other project files often come from project files +that have no sources: they are just used as templates. Any modification in the +template will be reflected automatically in all the project files that rename +a package from the template. This is a very common way to share settings +between projects. + +Finally, a package can also be defined by an **extending declaration**. This is +similar to a **renaming declaration**, except that it is possible to add or +override attributes. + +:: + + package_declaration ::= package_spec | package_renaming | package_extension + package_spec ::= + package <package_>simple_name is + {simple_declarative_item} + end package_identifier ; + package_renaming ::== + package <package_>simple_name renames <project_>simple_name.package_identifier ; + package_extension ::== + package <package_>simple_name extends <project_>simple_name.package_identifier is + {simple_declarative_item} + end package_identifier ; + + +.. _Expressions: + +Expressions +----------- + +An expression is any value that can be assigned to an attribute or a +variable. It is either a literal value, or a construct requiring runtime +computation by the project manager. In a project file, the computed value of +an expression is either a string or a list of strings. + +A string value is one of: + +* A literal string, for instance `"comm/my_proj.gpr"` +* The name of a variable that evaluates to a string (see :ref:`Variables`) +* The name of an attribute that evaluates to a string (see :ref:`Attributes`) +* An external reference (see :ref:`External_Values`) +* A concatenation of the above, as in `"prefix_" & Var`. + +A list of strings is one of the following: + +* A parenthesized comma-separated list of zero or more string expressions, for + instance `(File_Name, "gnat.adc", File_Name & ".orig")` or `()`. +* The name of a variable that evaluates to a list of strings +* The name of an attribute that evaluates to a list of strings +* A concatenation of a list of strings and a string (as defined above), for + instance `("A", "B") & "C"` +* A concatenation of two lists of strings + +The following is the grammar for expressions + +:: + + string_literal ::= "{string_element}" -- Same as Ada + string_expression ::= string_literal + | *variable_*name + | external_value + | attribute_reference + | ( string_expression { & string_expression } ) + string_list ::= ( string_expression { , string_expression } ) + | *string_variable*_name + | *string_*attribute_reference + term ::= string_expression | string_list + expression ::= term { & term } -- Concatenation + +Concatenation involves strings and list of strings. As soon as a list of +strings is involved, the result of the concatenation is a list of strings. The +following Ada declarations show the existing operators: + +.. code-block:: ada + + function "&" (X : String; Y : String) return String; + function "&" (X : String_List; Y : String) return String_List; + function "&" (X : String_List; Y : String_List) return String_List; + + +Here are some specific examples: + +.. code-block:: ada + + List := () & File_Name; -- One string in this list + List2 := List & (File_Name & ".orig"); -- Two strings + Big_List := List & Lists2; -- Three strings + Illegal := "gnat.adc" & List2; -- Illegal, must start with list + + +.. _External_Values: + +External Values +--------------- + +An external value is an expression whose value is obtained from the command +that invoked the processing of the current project file (typically a +*gnatmake* or *gprbuild* command). + +There are two kinds of external values, one that returns a single string, and +one that returns a string list. + +The syntax of a single string external value is:: + + external_value ::= *external* ( string_literal [, string_literal] ) + + +The first string_literal is the string to be used on the command line or +in the environment to specify the external value. The second string_literal, +if present, is the default to use if there is no specification for this +external value either on the command line or in the environment. + +Typically, the external value will either exist in the +environment variables +or be specified on the command line through the +:samp:`-X{vbl}={value}` switch. If both +are specified, then the command line value is used, so that a user can more +easily override the value. + +The function `external` always returns a string. It is an error if the +value was not found in the environment and no default was specified in the +call to `external`. + +An external reference may be part of a string expression or of a string +list expression, and can therefore appear in a variable declaration or +an attribute declaration. + +Most of the time, this construct is used to initialize typed variables, which +are then used in **case** constructions to control the value assigned to +attributes in various scenarios. Thus such variables are often called +**scenario variables**. + +The syntax for a string list external value is:: + + external_value ::= *external_as_list* ( string_literal , string_literal ) + + +The first string_literal is the string to be used on the command line or +in the environment to specify the external value. The second string_literal is +the separator between each component of the string list. + +If the external value does not exist in the environment or on the command line, +the result is an empty list. This is also the case, if the separator is an +empty string or if the external value is only one separator. + +Any separator at the beginning or at the end of the external value is +discarded. Then, if there is no separator in the external value, the result is +a string list with only one string. Otherwise, any string between the beginning +and the first separator, between two consecutive separators and between the +last separator and the end are components of the string list. + +:: + + *external_as_list* ("SWITCHES", ",") + +If the external value is "-O2,-g", +the result is ("-O2", "-g"). + +If the external value is ",-O2,-g,", +the result is also ("-O2", "-g"). + +if the external value is "-gnatv", +the result is ("-gnatv"). + +If the external value is ",,", the result is (""). + +If the external value is ",", the result is (), the empty string list. + + +.. _Typed_String_Declaration: + +Typed String Declaration +------------------------ + +A **type declaration** introduces a discrete set of string literals. +If a string variable is declared to have this type, its value +is restricted to the given set of literals. These are the only named +types in project files. A string type may only be declared at the project +level, not inside a package. + +:: + + typed_string_declaration ::= + *type* *<typed_string_>*_simple_name *is* ( string_literal {, string_literal} ); + +The string literals in the list are case sensitive and must all be different. +They may include any graphic characters allowed in Ada, including spaces. +Here is an example of a string type declaration: + +.. code-block:: ada + + type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS"); + +Variables of a string type are called **typed variables**; all other +variables are called **untyped variables**. Typed variables are +particularly useful in `case` constructions, to support conditional +attribute declarations. (See :ref:`Case_Constructions`). + +A string type may be referenced by its name if it has been declared in the same +project file, or by an expanded name whose prefix is the name of the project +in which it is declared. + + +.. _Variables: + +Variables +--------- + +**Variables** store values (strings or list of strings) and can appear +as part of an expression. The declaration of a variable creates the +variable and assigns the value of the expression to it. The name of the +variable is available immediately after the assignment symbol, if you +need to reuse its old value to compute the new value. Before the completion +of its first declaration, the value of a variable defaults to the empty +string (""). + +A **typed** variable can be used as part of a **case** expression to +compute the value, but it can only be declared once in the project file, +so that all case constructions see the same value for the variable. This +provides more consistency and makes the project easier to understand. +The syntax for its declaration is identical to the Ada syntax for an +object declaration. In effect, a typed variable acts as a constant. + +An **untyped** variable can be declared and overridden multiple times +within the same project. It is declared implicitly through an Ada +assignment. The first declaration establishes the kind of the variable +(string or list of strings) and successive declarations must respect +the initial kind. Assignments are executed in the order in which they +appear, so the new value replaces the old one and any subsequent reference +to the variable uses the new value. + +A variable may be declared at the project file level, or within a package. + +:: + + typed_variable_declaration ::= + *<typed_variable_>*simple_name : *<typed_string_>*name := string_expression; + + variable_declaration ::= *<variable_>*simple_name := expression; + +Here are some examples of variable declarations: + +.. code-block:: gpr + + This_OS : OS := external ("OS"); -- a typed variable declaration + That_OS := "GNU/Linux"; -- an untyped variable declaration + + Name := "readme.txt"; + Save_Name := Name & ".saved"; + + Empty_List := (); + List_With_One_Element := ("-gnaty"); + List_With_Two_Elements := List_With_One_Element & "-gnatg"; + Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada"); + +A **variable reference** may take several forms: + +* The simple variable name, for a variable in the current package (if any) + or in the current project +* An expanded name, whose prefix is a context name. + +A **context** may be one of the following: + +* The name of an existing package in the current project +* The name of an imported project of the current project +* The name of an ancestor project (i.e., a project extended by the current + project, either directly or indirectly) +* An expanded name whose prefix is an imported/parent project name, and + whose selector is a package name in that project. + + +.. _Case_Constructions: + +Case Constructions +------------------ + +A **case** construction is used in a project file to effect conditional +behavior. Through this construction, you can set the value of attributes +and variables depending on the value previously assigned to a typed +variable. + +All choices in a choice list must be distinct. Unlike Ada, the choice +lists of all alternatives do not need to include all values of the type. +An `others` choice must appear last in the list of alternatives. + +The syntax of a `case` construction is based on the Ada case construction +(although the `null` declaration for empty alternatives is optional). + +The case expression must be a string variable, either typed or not, whose value +is often given by an external reference (see :ref:`External_Values`). + +Each alternative starts with the reserved word `when`, either a list of +literal strings separated by the `"|"` character or the reserved word +`others`, and the `"=>"` token. +When the case expression is a typed string variable, each literal string must +belong to the string type that is the type of the case variable. +After each `=>`, there are zero or more declarations. The only +declarations allowed in a case construction are other case constructions, +attribute declarations and variable declarations. String type declarations and +package declarations are not allowed. Variable declarations are restricted to +variables that have already been declared before the case construction. + +:: + + case_construction ::= + *case* *<variable_>*name *is* {case_item} *end case* ; + + case_item ::= + *when* discrete_choice_list => + {case_declaration + | attribute_declaration + | variable_declaration + | empty_declaration} + + discrete_choice_list ::= string_literal {| string_literal} | *others* + +Here is a typical example, with a typed string variable: + +.. code-block:: gpr + + project MyProj is + type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS"); + OS : OS_Type := external ("OS", "GNU/Linux"); + + package Compiler is + case OS is + when "GNU/Linux" | "Unix" => + for Switches ("Ada") + use ("-gnath"); + when "NT" => + for Switches ("Ada") + use ("-gnatP"); + when others => + null; + end case; + end Compiler; + end MyProj; + + +.. _Attributes: + +Attributes +---------- + +A project (and its packages) may have **attributes** that define +the project's properties. Some attributes have values that are strings; +others have values that are string lists. + +:: + + attribute_declaration ::= + simple_attribute_declaration | indexed_attribute_declaration + + simple_attribute_declaration ::= *for* attribute_designator *use* expression ; + + indexed_attribute_declaration ::= + *for* *<indexed_attribute_>*simple_name ( string_literal) *use* expression ; + + attribute_designator ::= + *<simple_attribute_>*simple_name + | *<indexed_attribute_>*simple_name ( string_literal ) + +There are two categories of attributes: **simple attributes** +and **indexed attributes**. +Each simple attribute has a default value: the empty string (for string +attributes) and the empty list (for string list attributes). +An attribute declaration defines a new value for an attribute, and overrides +the previous value. The syntax of a simple attribute declaration is similar to +that of an attribute definition clause in Ada. + +Some attributes are indexed. These attributes are mappings whose +domain is a set of strings. They are declared one association +at a time, by specifying a point in the domain and the corresponding image +of the attribute. +Like untyped variables and simple attributes, indexed attributes +may be declared several times. Each declaration supplies a new value for the +attribute, and replaces the previous setting. + +Here are some examples of attribute declarations: + +.. code-block:: gpr + + -- simple attributes + for Object_Dir use "objects"; + for Source_Dirs use ("units", "test/drivers"); + + -- indexed attributes + for Body ("main") use "Main.ada"; + for Switches ("main.ada") + use ("-v", "-gnatv"); + for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g"; + + -- indexed attributes copy (from package Builder in project Default) + -- The package name must always be specified, even if it is the current + -- package. + for Default_Switches use Default.Builder'Default_Switches; + +Attributes references may appear anywhere in expressions, and are used +to retrieve the value previously assigned to the attribute. If an attribute +has not been set in a given package or project, its value defaults to the +empty string or the empty list, with some exceptions. + +:: + + attribute_reference ::= + attribute_prefix ' *<simple_attribute>_*simple_name [ (string_literal) ] + attribute_prefix ::= *project* + | *<project_>*simple_name + | package_identifier + | *<project_>*simple_name . package_identifier + +Examples are:: + + <project>'Object_Dir + Naming'Dot_Replacement + Imported_Project'Source_Dirs + Imported_Project.Naming'Casing + Builder'Default_Switches ("Ada") + +The exceptions to the empty defaults are: + +* Object_Dir: default is "." +* Exec_Dir: default is 'Object_Dir, that is the value of attribute + Object_Dir in the same project, declared or defaulted. +* Source_Dirs: default is (".") + +The prefix of an attribute may be: + +* `project` for an attribute of the current project +* The name of an existing package of the current project +* The name of an imported project +* The name of a parent project that is extended by the current project +* An expanded name whose prefix is imported/parent project name, + and whose selector is a package name + +In the following sections, all predefined attributes are succinctly described, +first the project level attributes, that is those attributes that are not in a +package, then the attributes in the different packages. + +It is possible for different tools to dynamically create new packages with +attributes, or new attributes in predefined packages. These attributes are +not documented here. + +The attributes under Configuration headings are usually found only in +configuration project files. + +The characteristics of each attribute are indicated as follows: + +* **Type of value** + + The value of an attribute may be a single string, indicated by the word + "single", or a string list, indicated by the word "list". + +* **Read-only** + + When the attribute is read-only, that is when it is not allowed to declare + the attribute, this is indicated by the words "read-only". + +* **Optional index** + + If it is allowed in the value of the attribute (both single and list) to have + an optional index, this is indicated by the words "optional index". + +* **Indexed attribute** + + When it is an indexed attribute, this is indicated by the word "indexed". + +* **Case-sensitivity of the index** + + For an indexed attribute, if the index is case-insensitive, this is indicated + by the words "case-insensitive index". + +* **File name index** + + For an indexed attribute, when the index is a file name, this is indicated by + the words "file name index". The index may or may not be case-sensitive, + depending on the platform. + +* **others allowed in index** + + For an indexed attribute, if it is allowed to use **others** as the index, + this is indicated by the words "others allowed". + + When **others** is used as the index of an indexed attribute, the value of + the attribute indexed by **others** is used when no other index would apply. + + +.. _Project_Level_Attributes: + +Project Level Attributes +^^^^^^^^^^^^^^^^^^^^^^^^ + + +* **General** + + * **Name**: single, read-only + + The name of the project. + + * **Project_Dir**: single, read-only + + The path name of the project directory. + + * **Main**: list, optional index + + The list of main sources for the executables. + + * **Languages**: list + + The list of languages of the sources of the project. + + * **Roots**: list, indexed, file name index + + The index is the file name of an executable source. Indicates the list of units + from the main project that need to be bound and linked with their closures + with the executable. The index is either a file name, a language name or "*". + The roots for an executable source are those in **Roots** with an index that + is the executable source file name, if declared. Otherwise, they are those in + **Roots** with an index that is the language name of the executable source, + if present. Otherwise, they are those in **Roots ("*")**, if declared. If none + of these three possibilities are declared, then there are no roots for the + executable source. + + * **Externally_Built**: single + + Indicates if the project is externally built. + Only case-insensitive values allowed are "true" and "false", the default. + +* **Directories** + + * **Object_Dir**: single + + Indicates the object directory for the project. + + * **Exec_Dir**: single + + Indicates the exec directory for the project, that is the directory where the + executables are. + + * **Source_Dirs**: list + + The list of source directories of the project. + + * **Inherit_Source_Path**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of language names. Indicates that + in the source search path of the index language the source directories of + the languages in the list should be included. + + Example: + + .. code-block:: gpr + + for Inherit_Source_Path ("C++") use ("C"); + + * **Exclude_Source_Dirs**: list + + The list of directories that are included in Source_Dirs but are not source + directories of the project. + + * **Ignore_Source_Sub_Dirs**: list + + Value is a list of simple names for subdirectories that are removed from the + list of source directories, including theur subdirectories. + +* **Source Files** + + * **Source_Files**: list + + Value is a list of source file simple names. + + * **Locally_Removed_Files**: list + + Obsolescent. Equivalent to Excluded_Source_Files. + + * **Excluded_Source_Files**: list + + Value is a list of simple file names that are not sources of the project. + Allows to remove sources that are inherited or found in the source directories + and that match the naming scheme. + + * **Source_List_File**: single + + Value is a text file name that contains a list of source file simple names, + one on each line. + + * **Excluded_Source_List_File**: single + + Value is a text file name that contains a list of file simple names that + are not sources of the project. + + * **Interfaces**: list + + Value is a list of file names that constitutes the interfaces of the project. + +* **Aggregate Projects** + + * **Project_Files**: list + + Value is the list of aggregated projects. + + * **Project_Path**: list + + Value is a list of directories that are added to the project search path when + looking for the aggregated projects. + + * **External**: single, indexed + + Index is the name of an external reference. Value is the value of the + external reference to be used when parsing the aggregated projects. + +* **Libraries** + + * **Library_Dir**: single + + Value is the name of the library directory. This attribute needs to be + declared for each library project. + + * **Library_Name**: single + + Value is the name of the library. This attribute needs to be declared or + inherited for each library project. + + * **Library_Kind**: single + + Specifies the kind of library: static library (archive) or shared library. + Case-insensitive values must be one of "static" for archives (the default) or + "dynamic" or "relocatable" for shared libraries. + + * **Library_Version**: single + + Value is the name of the library file. + + * **Library_Interface**: list + + Value is the list of unit names that constitutes the interfaces + of a Stand-Alone Library project. + + * **Library_Standalone**: single + + Specifies if a Stand-Alone Library (SAL) is encapsulated or not. + Only authorized case-insensitive values are "standard" for non encapsulated + SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project. + + * **Library_Encapsulated_Options**: list + + Value is a list of options that need to be used when linking an encapsulated + Stand-Alone Library. + + * **Library_Encapsulated_Supported**: single + + Indicates if encapsulated Stand-Alone Libraries are supported. Only + authorized case-insensitive values are "true" and "false" (the default). + + * **Library_Auto_Init**: single + + Indicates if a Stand-Alone Library is auto-initialized. Only authorized + case-insentive values are "true" and "false". + + * **Leading_Library_Options**: list + + Value is a list of options that are to be used at the beginning of + the command line when linking a shared library. + + * **Library_Options**: list + + Value is a list of options that are to be used when linking a shared library. + + * **Library_Rpath_Options**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of options for an invocation of the + compiler of the language. This invocation is done for a shared library project + with sources of the language. The output of the invocation is the path name + of a shared library file. The directory name is to be put in the run path + option switch when linking the shared library for the project. + + * **Library_Src_Dir**: single + + Value is the name of the directory where copies of the sources of the + interfaces of a Stand-Alone Library are to be copied. + + * **Library_ALI_Dir**: single + + Value is the name of the directory where the ALI files of the interfaces + of a Stand-Alone Library are to be copied. When this attribute is not declared, + the directory is the library directory. + + * **Library_gcc**: single + + Obsolescent attribute. Specify the linker driver used to link a shared library. + Use instead attribute Linker'Driver. + + * **Library_Symbol_File**: single + + Value is the name of the library symbol file. + + * **Library_Symbol_Policy**: single + + Indicates the symbol policy kind. Only authorized case-insensitive values are + "autonomous", "default", "compliant", "controlled" or "direct". + + * **Library_Reference_Symbol_File**: single + + Value is the name of the reference symbol file. + +* **Configuration - General** + + * **Default_Language**: single + + Value is the case-insensitive name of the language of a project when attribute + Languages is not specified. + + * **Run_Path_Option**: list + + Value is the list of switches to be used when specifying the run path option + in an executable. + + * **Run_Path_Origin**: single + + Value is the the string that may replace the path name of the executable + directory in the run path options. + + * **Separate_Run_Path_Options**: single + + Indicates if there may be several run path options specified when linking an + executable. Only authorized case-insensitive values are "true" or "false" (the + default). + + * **Toolchain_Version**: single, indexed, case-insensitive index + + Index is a language name. Specify the version of a toolchain for a language. + + * **Toolchain_Description**: single, indexed, case-insensitive index + + Obsolescent. No longer used. + + * **Object_Generated**: single, indexed, case-insensitive index + + Index is a language name. Indicates if invoking the compiler for a language + produces an object file. Only authorized case-insensitive values are "false" + and "true" (the default). + + * **Objects_Linked**: single, indexed, case-insensitive index + + Index is a language name. Indicates if the object files created by the compiler + for a language need to be linked in the executable. Only authorized + case-insensitive values are "false" and "true" (the default). + + * **Target**: single + + Value is the name of the target platform. Taken into account only in the main + project. + + * **Runtime**: single, indexed, case-insensitive index + + Index is a language name. Indicates the runtime directory that is to be used + when using the compiler of the language. Taken into account only in the main + project. + +* **Configuration - Libraries** + + * **Library_Builder**: single + + Value is the path name of the application that is to be used to build + libraries. Usually the path name of "gprlib". + + * **Library_Support**: single + + Indicates the level of support of libraries. Only authorized case-insensitive + values are "static_only", "full" or "none" (the default). + +* **Configuration - Archives** + + * **Archive_Builder**: list + + Value is the name of the application to be used to create a static library + (archive), followed by the options to be used. + + * **Archive_Builder_Append_Option**: list + + Value is the list of options to be used when invoking the archive builder + to add project files into an archive. + + * **Archive_Indexer**: list + + Value is the name of the archive indexer, followed by the required options. + + * **Archive_Suffix**: single + + Value is the extension of archives. When not declared, the extension is ".a". + + * **Library_Partial_Linker**: list + + Value is the name of the partial linker executable, followed by the required + options. + +* **Configuration - Shared Libraries** + + * **Shared_Library_Prefix**: single + + Value is the prefix in the name of shared library files. When not declared, + the prefix is "lib". + + * **Shared_Library_Suffix**: single + + Value is the the extension of the name of shared library files. When not + declared, the extension is ".so". + + * **Symbolic_Link_Supported**: single + + Indicates if symbolic links are supported on the platform. Only authorized + case-insensitive values are "true" and "false" (the default). + + * **Library_Major_Minor_Id_Supported**: single + + Indicates if major and minor ids for shared library names are supported on + the platform. Only authorized case-insensitive values are "true" and "false" + (the default). + + * **Library_Auto_Init_Supported**: single + + Indicates if auto-initialization of Stand-Alone Libraries is supported. Only + authorized case-insensitive values are "true" and "false" (the default). + + * **Shared_Library_Minimum_Switches**: list + + Value is the list of required switches when linking a shared library. + + * **Library_Version_Switches**: list + + Value is the list of switches to specify a internal name for a shared library. + + * **Library_Install_Name_Option**: single + + Value is the name of the option that needs to be used, concatenated with the + path name of the library file, when linking a shared library. + + * **Runtime_Library_Dir**: single, indexed, case-insensitive index + + Index is a language name. Value is the path name of the directory where the + runtime libraries are located. + + * **Runtime_Source_Dir**: single, indexed, case-insensitive index + + Index is a language name. Value is the path name of the directory where the + sources of runtime libraries are located. + + +.. _Package_Binder_Attributes: + +Package Binder Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **General** + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to be used when binding + code of the language, if there is no applicable attribute Switches. + + * **Switches**: list, optional index, indexed, + case-insensitive index, others allowed + + Index is either a language name or a source file name. Value is the list of + switches to be used when binding code. Index is either the source file name + of the executable to be bound or the language name of the code to be bound. + +* **Configuration - Binding** + + * **Driver**: single, indexed, case-insensitive index + + Index is a language name. Value is the name of the application to be used when + binding code of the language. + + * **Required_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of the required switches to be + used when binding code of the language. + + * **Prefix**: single, indexed, case-insensitive index + + Index is a language name. Value is a prefix to be used for the binder exchange + file name for the language. Used to have different binder exchange file names + when binding different languages. + + * **Objects_Path**: single,indexed, case-insensitive index + + Index is a language name. Value is the name of the environment variable that + contains the path for the object directories. + + * **Object_Path_File**: single,indexed, case-insensitive index + + Index is a language name. Value is the name of the environment variable. The + value of the environment variable is the path name of a text file that + contains the list of object directories. + + +.. _Package_Builder_Attributes: + +Package Builder Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of builder switches to be used when + building an executable of the language, if there is no applicable attribute + Switches. + +* **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is either a language name or a source file name. Value is the list of + builder switches to be used when building an executable. Index is either the + source file name of the executable to be built or its language name. + +* **Global_Compilation_Switches**: list, optional index, indexed, + case-insensitive index + + Index is either a language name or a source file name. Value is the list of + compilation switches to be used when building an executable. Index is either + the source file name of the executable to be built or its language name. + +* **Executable**: single, indexed, case-insensitive index + + Index is an executable source file name. Value is the simple file name of the + executable to be built. + +* **Executable_Suffix**: single + + Value is the extension of the file names of executable. When not specified, + the extension is the default extension of executables on the platform. + +* **Global_Configuration_Pragmas**: single + + Value is the file name of a configuration pragmas file that is specified to + the Ada compiler when compiling any Ada source in the project tree. + +* **Global_Config_File**: single, indexed, case-insensitive index + + Index is a language name. Value is the file name of a configuration file that + is specified to the compiler when compiling any source of the language in the + project tree. + + +.. only:: PRO and GPL + + .. _Package_Check_Attributes: + + Package Check Attributes + ^^^^^^^^^^^^^^^^^^^^^^^^ + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatcheck` for a source of the language, if there is no applicable + attribute Switches. + + * **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatcheck` for the source. + +.. _Package_Clean_Attributes: + +Package Clean Attributes +^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Switches**: list + + Value is a list of switches to be used by the cleaning application. + +* **Source_Artifact_Extensions**: list, indexed, case-insensitive index + + Index is a language names. Value is the list of extensions for file names + derived from object file names that need to be cleaned in the object + directory of the project. + +* **Object_Artifact_Extensions**: list, indexed, case-insensitive index + + Index is a language names. Value is the list of extensions for file names + derived from source file names that need to be cleaned in the object + directory of the project. + +* **Artifacts_In_Object_Dir**: single + + Value is a list of file names expressed as regular expressions that are to be + deleted by gprclean in the object directory of the project. + +* **Artifacts_In_Exec_Dir**: single + + Value is list of file names expressed as regular expressions that are to be + deleted by gprclean in the exec directory of the main project. + +.. _Package_Compiler_Attributes: + +Package Compiler Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **General** + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + the compiler for the language for a source of the project, if there is no + applicable attribute Switches. + + * **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name or a language name. Value is the list of switches + to be used when invoking the compiler for the source or for its language. + + * **Local_Configuration_Pragmas**: single + + Value is the file name of a configuration pragmas file that is specified to + the Ada compiler when compiling any Ada source in the project. + + * **Local_Config_File**: single, indexed, case-insensitive index + + Index is a language name. Value is the file name of a configuration file that + is specified to the compiler when compiling any source of the language in the + project. + +* **Configuration - Compiling** + + * **Driver**: single, indexed, case-insensitive index + + Index is a language name. Value is the name of the executable for the compiler + of the language. + + * **Language_Kind**: single, indexed, case-insensitive index + + Index is a language name. Indicates the kind of the language, either file based + or unit based. Only authorized case-insensitive values are "unit_based" and + "file_based" (the default). + + * **Dependency_Kind**: single, indexed, case-insensitive index + + Index is a language name. Indicates how the dependencies are handled for the + language. Only authorized case-insensitive values are "makefile", "ali_file", + "ali_closure" or "none" (the default). + + * **Required_Switches**: list, indexed, case-insensitive index + + Equivalent to attribute Leading_Required_Switches. + + * **Leading_Required_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of the minimum switches to be used + at the beginning of the command line when invoking the compiler for the + language. + + * **Trailing_Required_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of the minimum switches to be used + at the end of the command line when invoking the compiler for the language. + + * **PIC_Option**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to be used when + compiling a source of the language when the project is a shared library + project. + + * **Path_Syntax**: single, indexed, case-insensitive index + + Index is a language name. Value is the kind of path syntax to be used when + invoking the compiler for the language. Only authorized case-insensitive + values are "canonical" and "host" (the default). + + * **Source_File_Switches**: single, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used just before + the path name of the source to compile when invoking the compiler for a source + of the language. + + * **Object_File_Suffix**: single, indexed, case-insensitive index + + Index is a language name. Value is the extension of the object files created + by the compiler of the language. When not specified, the extension is the + default one for the platform. + + * **Object_File_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to be used by the + compiler of the language to specify the path name of the object file. When not + specified, the switch used is "-o". + + * **Multi_Unit_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to be used to compile + a unit in a multi unit source of the language. The index of the unit in the + source is concatenated with the last switches in the list. + + * **Multi_Unit_Object_Separator**: single, indexed, case-insensitive index + + Index is a language name. Value is the string to be used in the object file + name before the index of the unit, when compiling a unit in a multi unit source + of the language. + +* **Configuration - Mapping Files** + + * **Mapping_File_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to be used to specify + a mapping file when invoking the compiler for a source of the language. + + * **Mapping_Spec_Suffix**: single, indexed, case-insensitive index + + Index is a language name. Value is the suffix to be used in a mapping file + to indicate that the source is a spec. + + * **Mapping_Body_Suffix**: single, indexed, case-insensitive index + + Index is a language name. Value is the suffix to be used in a mapping file + to indicate that the source is a body. + +* **Configuration - Config Files** + + * **Config_File_Switches**: list: single, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to specify to the + compiler of the language a configuration file. + + * **Config_Body_File_Name**: single, indexed, case-insensitive index + + Index is a language name. Value is the template to be used to indicate a + configuration specific to a body of the language in a configuration + file. + + * **Config_Body_File_Name_Index**: single, indexed, case-insensitive index + + Index is a language name. Value is the template to be used to indicate a + configuration specific to the body a unit in a multi unit source of the + language in a configuration file. + + * **Config_Body_File_Name_Pattern**: single, indexed, + case-insensitive index + + Index is a language name. Value is the template to be used to indicate a + configuration for all bodies of the languages in a configuration file. + + * **Config_Spec_File_Name**: single, indexed, case-insensitive index + + Index is a language name. Value is the template to be used to indicate a + configuration specific to a spec of the language in a configuration + file. + + * **Config_Spec_File_Name_Index**: single, indexed, case-insensitive index + + Index is a language name. Value is the template to be used to indicate a + configuration specific to the spec a unit in a multi unit source of the + language in a configuration file. + + * **Config_Spec_File_Name_Pattern**: single, indexed, + case-insensitive index + + Index is a language name. Value is the template to be used to indicate a + configuration for all specs of the languages in a configuration file. + + * **Config_File_Unique**: single, indexed, case-insensitive index + + Index is a language name. Indicates if there should be only one configuration + file specified to the compiler of the language. Only authorized + case-insensitive values are "true" and "false" (the default). + +* **Configuration - Dependencies** + + * **Dependency_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to be used to specify + to the compiler the dependency file when the dependency kind of the language is + file based, and when Dependency_Driver is not specified for the language. + + * **Dependency_Driver**: list, indexed, case-insensitive index + + Index is a language name. Value is the name of the executable to be used to + create the dependency file for a source of the language, followed by the + required switches. + +* **Configuration - Search Paths** + + * **Include_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to specify to the + compiler of the language to indicate a directory to look for sources. + + * **Include_Path**: single, indexed, case-insensitive index + + Index is a language name. Value is the name of an environment variable that + contains the path of all the directories that the compiler of the language + may search for sources. + + * **Include_Path_File**: single, indexed, case-insensitive index + + Index is a language name. Value is the name of an environment variable the + value of which is the path name of a text file that contains the directories + that the compiler of the language may search for sources. + + * **Object_Path_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is the list of switches to specify to the + compiler of the language the name of a text file that contains the list of + object directories. When this attribute is not declared, the text file is + not created. + + +.. _Package_Cross_Reference_Attributes: + +Package Cross_Reference Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatxref` for a source of the language, if there is no applicable + attribute Switches. + +* **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatxref` for the source. + + +.. only:: PRO or GPL + + .. _Package_Eliminate_Attributes: + + Package Eliminate Attributes + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatelim` for a source of the language, if there is no applicable + attribute Switches. + + * **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatelim` for the source. + +.. _Package_Finder_Attributes: + +Package Finder Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatfind` for a source of the language, if there is no applicable + attribute Switches. + +* **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatfind` for the source. + + +.. _Package_gnatls_Attributes: + +Package gnatls Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Switches**: list + + Value is a list of switches to be used when invoking `gnatls`. + + +.. only:: PRO or GPL + + Package gnatstub Attributes + ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatstub` for a source of the language, if there is no applicable + attribute Switches. + + * **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatstub` for the source. + + +.. _Package_IDE_Attributes: + +Package IDE Attributes +^^^^^^^^^^^^^^^^^^^^^^ + +* **Default_Switches**: list, indexed + + Index is the name of an external tool that the GNAT Programming System (GPS) + is supporting. Value is a list of switches to use when invoking that tool. + +* **Remote_Host**: single + + Value is a string that designates the remote host in a cross-compilation + environment, to be used for remote compilation and debugging. This attribute + should not be specified when running on the local machine. + +* **Program_Host**: single + + Value is a string that specifies the name of IP address of the embedded target + in a cross-compilation environment, on which the program should execute. + +* **Communication_Protocol**: single + + Value is the name of the protocol to use to communicate with the target + in a cross-compilation environment, for example `"wtx"` or + `"vxworks"`. + +* **Compiler_Command**: single, indexed, case-insensitive index + + Index is a language Name. Value is a string that denotes the command to be + used to invoke the compiler. The value of `Compiler_Command ("Ada")` is + expected to be compatible with *gnatmake*, in particular in + the handling of switches. + +* **Debugger_Command**: single + + Value is a string that specifies the name of the debugger to be used, such as + gdb, powerpc-wrs-vxworks-gdb or gdb-4. + +* **gnatlist**: single + + Value is a string that specifies the name of the *gnatls* utility + to be used to retrieve information about the predefined path; for example, + `"gnatls"`, `"powerpc-wrs-vxworks-gnatls"`. + +* **VCS_Kind**: single + + Value is a string used to specify the Version Control System (VCS) to be used + for this project, for example "Subversion", "ClearCase". If the + value is set to "Auto", the IDE will try to detect the actual VCS used + on the list of supported ones. + +* **VCS_File_Check**: single + + Value is a string that specifies the command used by the VCS to check + the validity of a file, either when the user explicitly asks for a check, + or as a sanity check before doing the check-in. + +* **VCS_Log_Check**: single + + Value is a string that specifies the command used by the VCS to check + the validity of a log file. + +* **Documentation_Dir**: single + + Value is the directory used to generate the documentation of source code. + + +.. _Package_Install_Attributes: + +Package Install Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Artifacts**: list, indexed + + An array attribute to declare a set of files not part of the sources + to be installed. The array discriminant is the directory where the + file is to be installed. If a relative directory then Prefix (see + below) is prepended. + +* **Prefix**: single + + Value is the install destination directory. + +* **Sources_Subdir**: single + + Value is the sources directory or subdirectory of Prefix. + +* **Exec_Subdir**: single + + Value is the executables directory or subdirectory of Prefix. + +* **Lib_Subdir**: single + + Value is library directory or subdirectory of Prefix. + +* **Project_Subdir**: single + + Value is the project directory or subdirectory of Prefix. + +* **Active**: single + + Indicates that the project is to be installed or not. Case-insensitive value + "false" means that the project is not to be installed, all other values mean + that the project is to be installed. + +* **Mode**: single + + Value is the installation mode, it is either **dev** (default) or **usage**. + +* **Install_Name**: single + + Specify the name to use for recording the installation. The default is + the project name without the extension. + + +.. _Package_Linker_Attributes: + +Package Linker Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **General** + + * **Required_Switches**: list + + Value is a list of switches that are required when invoking the linker to link + an executable. + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches for the linker when + linking an executable for a main source of the language, when there is no + applicable Switches. + + * **Leading_Switches**: list, optional index, indexed, + case-insensitive index, others allowed + + Index is a source file name or a language name. Value is the list of switches + to be used at the beginning of the command line when invoking the linker to + build an executable for the source or for its language. + + * **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name or a language name. Value is the list of switches + to be used when invoking the linker to build an executable for the source or + for its language. + + * **Trailing_Switches**: list, optional index, indexed, + case-insensitive index, others allowed + + Index is a source file name or a language name. Value is the list of switches + to be used at the end of the command line when invoking the linker to + build an executable for the source or for its language. These switches may + override the Required_Switches. + + * **Linker_Options**: list + + Value is a list of switches/options that are to be added when linking an + executable from a project importing the current project directly or indirectly. + Linker_Options are not used when linking an executable from the current + project. + + * **Map_File_Option**: single + + Value is the switch to specify the map file name that the linker needs to + create. + +* **Configuration - Linking** + + * **Driver**: single + + Value is the name of the linker executable. + +* **Configuration - Response Files** + + * **Max_Command_Line_Length**: single + + Value is the maximum number of character in the command line when invoking + the linker to link an executable. + + * **Response_File_Format**: single + + Indicates the kind of response file to create when the length of the linking + command line is too large. Only authorized case-insensitive values are "none", + "gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list". + + * **Response_File_Switches**: list + + Value is the list of switches to specify a response file to the linker. + + + +.. only PRO or GPL + + .. _Package_Metrics_Attribute: + + Package Metrics Attribute + ^^^^^^^^^^^^^^^^^^^^^^^^^ + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatmetric` for a source of the language, if there is no applicable + attribute Switches. + + * **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatmetric` for the source. + + +.. _Package_Naming_Attributes: + +Package Naming Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Specification_Suffix**: single, indexed, case-insensitive index + + Equivalent to attribute Spec_Suffix. + +* **Spec_Suffix**: single, indexed, case-insensitive index + + Index is a language name. Value is the extension of file names for specs of + the language. + +* **Implementation_Suffix**: single, indexed, case-insensitive index + + Equivalent to attribute Body_Suffix. + +* **Body_Suffix**: single, indexed, case-insensitive index + + Index is a language name. Value is the extension of file names for bodies of + the language. + +* **Separate_Suffix**: single + + Value is the extension of file names for subunits of Ada. + +* **Casing**: single + + Indicates the casing of sources of the Ada language. Only authorized + case-insensitive values are "lowercase", "uppercase" and "mixedcase". + +* **Dot_Replacement**: single + + Value is the string that replace the dot of unit names in the source file names + of the Ada language. + +* **Specification**: single, optional index, indexed, + case-insensitive index + + Equivalent to attribute Spec. + +* **Spec**: single, optional index, indexed, case-insensitive index + + Index is a unit name. Value is the file name of the spec of the unit. + +* **Implementation**: single, optional index, indexed, + case-insensitive index + + Equivalent to attribute Body. + +* **Body**: single, optional index, indexed, case-insensitive index + + Index is a unit name. Value is the file name of the body of the unit. + +* **Specification_Exceptions**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of specs for the language that do not + necessarily follow the naming scheme for the language and that may or may not + be found in the source directories of the project. + +* **Implementation_Exceptions**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of bodies for the language that do not + necessarily follow the naming scheme for the language and that may or may not + be found in the source directories of the project. + + +.. only:: PRO or GPL + + .. _Package_Pretty_Printer_Attributes: + + Package Pretty_Printer Attributes + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + * **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatpp` for a source of the language, if there is no applicable + attribute Switches. + + * **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatpp` for the source. + + +.. _Package_Remote_Attributes: + +Package Remote Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Included_Patterns**: list + + If this attribute is defined it sets the patterns to + synchronized from the master to the slaves. It is exclusive + with Excluded_Patterns, that is it is an error to define + both. + +* **Included_Artifact_Patterns**: list + + If this attribute is defined it sets the patterns of compilation + artifacts to synchronized from the slaves to the build master. + This attribute replace the default hard-coded patterns. + +* **Excluded_Patterns**: list + + Set of patterns to ignore when synchronizing sources from the build + master to the slaves. A set of predefined patterns are supported + (e.g. \*.o, \*.ali, \*.exe, etc.), this attributes make it possible to + add some more patterns. + +* **Root_Dir**: single + + Value is the root directory used by the slave machines. + + +.. _Package_Stack_Attributes: + +Package Stack Attributes +^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Switches**: list + + Value is the list of switches to be used when invoking `gnatstack`. + + +Package Synchronize Attributes +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +* **Default_Switches**: list, indexed, case-insensitive index + + Index is a language name. Value is a list of switches to be used when invoking + `gnatsync` for a source of the language, if there is no applicable + attribute Switches. + +* **Switches**: list, optional index, indexed, case-insensitive index, + others allowed + + Index is a source file name. Value is the list of switches to be used when + invoking `gnatsync` for the source. + + diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst new file mode 100644 index 00000000000..f3af60c25ea --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst @@ -0,0 +1,4997 @@ +.. _GNAT_Utility_Programs: + +********************* +GNAT Utility Programs +********************* + +This chapter describes a number of utility programs: + +.. 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` + +Other GNAT utilities are described elsewhere in this manual: + +* :ref:`Handling_Arbitrary_File_Naming_Conventions_with_gnatname` +* :ref:`File_Name_Krunching_with_gnatkr` +* :ref:`Renaming_Files_with_gnatchop` +* :ref:`Preprocessing_with_gnatprep` + + +.. _The_File_Cleanup_Utility_gnatclean: + +The File Cleanup Utility *gnatclean* +==================================== + +.. index:: File cleanup tool +.. index:: gnatclean + +`gnatclean` is a tool that allows the deletion of files produced by the +compiler, binder and linker, including ALI files, object files, tree files, +expanded source files, library files, interface copy source files, binder +generated files and executable files. + +.. _Running_gnatclean: + +Running `gnatclean` +------------------- + +The `gnatclean` command has the form: + + :: + + $ gnatclean switches `names` + +where `names` is a list of source file names. Suffixes :file:`.ads` and +:file:`adb` may be omitted. If a project file is specified using switch +:samp:`-P`, then `names` may be completely omitted. + +In normal mode, `gnatclean` delete the files produced by the compiler and, +if switch `-c` is not specified, by the binder and +the linker. In informative-only mode, specified by switch +`-n`, the list of files that would have been deleted in +normal mode is listed, but no file is actually deleted. + + +.. _Switches_for_gnatclean: + +Switches for `gnatclean` +------------------------ + +`gnatclean` recognizes the following switches: + +.. index:: --version (gnatclean) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + +.. index:: --help (gnatclean) + +:samp:`--help` + If *--version* was not used, display usage, then exit disregarding + all other options. + +:samp:`--subdirs={subdir}` + Actual object directory of each project file is the subdirectory subdir of the + object directory specified or defaulted in the project file. + +:samp:`--unchecked-shared-lib-imports` + By default, shared library projects are not allowed to import static library + projects. When this switch is used on the command line, this restriction is + relaxed. + +.. index:: -c (gnatclean) + +:samp:`-c` + Only attempt to delete the files produced by the compiler, not those produced + by the binder or the linker. The files that are not to be deleted are library + files, interface copy files, binder generated files and executable files. + +.. index:: -D (gnatclean) + +:samp:`-D {dir}` + Indicate that ALI and object files should normally be found in directory `dir`. + +.. index:: -F (gnatclean) + +:samp:`-F` + When using project files, if some errors or warnings are detected during + parsing and verbose mode is not in effect (no use of switch + -v), then error lines start with the full path name of the project + file, rather than its simple file name. + +.. index:: -h (gnatclean) + +:samp:`-h` + Output a message explaining the usage of `gnatclean`. + +.. index:: -n (gnatclean) + +:samp:`-n` + Informative-only mode. Do not delete any files. Output the list of the files + that would have been deleted if this switch was not specified. + +.. index:: -P (gnatclean) + +:samp:`-P{project}` + Use project file `project`. Only one such switch can be used. + When cleaning a project file, the files produced by the compilation of the + immediate sources or inherited sources of the project files are to be + deleted. This is not depending on the presence or not of executable names + on the command line. + +.. index:: -q (gnatclean) + +:samp:`-q` + Quiet output. If there are no errors, do not output anything, except in + verbose mode (switch -v) or in informative-only mode + (switch -n). + +.. index:: -r (gnatclean) + +:samp:`-r` + When a project file is specified (using switch -P), + clean all imported and extended project files, recursively. If this switch + is not specified, only the files related to the main project file are to be + deleted. This switch has no effect if no project file is specified. + +.. index:: -v (gnatclean) + +:samp:`-v` + Verbose mode. + +.. index:: -vP (gnatclean) + +:samp:`-vP{x}` + Indicates the verbosity of the parsing of GNAT project files. + :ref:`Switches_Related_to_Project_Files`. + +.. index:: -X (gnatclean) + +: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. + :ref:`Switches_Related_to_Project_Files`. + +.. index:: -aO (gnatclean) + +:samp:`-aO{dir}` + When searching for ALI and object files, look in directory `dir`. + +.. index:: -I (gnatclean) + +:samp:`-I{dir}` + Equivalent to :samp:`-aO{dir}`. + +.. index:: -I- (gnatclean) + +.. index:: Source files, suppressing search + +:samp:`-I-` + Do not look for ALI or object files in the directory + where `gnatclean` was invoked. + + + +.. _The_GNAT_Library_Browser_gnatls: + +The GNAT Library Browser `gnatls` +================================= + +.. index:: Library browser +.. index: ! gnatls + +`gnatls` is a tool that outputs information about compiled +units. It gives the relationship between objects, unit names and source +files. It can also be used to check the source dependencies of a unit +as well as various characteristics. + +Note: to invoke `gnatls` with a project file, use the `gnat` +driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + +.. _Running_gnatls: + +Running `gnatls` +---------------- + +The `gnatls` command has the form + + :: + + $ gnatls switches `object_or_ali_file` + +The main argument is the list of object or :file:`ali` files +(see :ref:`The_Ada_Library_Information_Files`) +for which information is requested. + +In normal mode, without additional option, `gnatls` produces a +four-column listing. Each line represents information for a specific +object. The first column gives the full path of the object, the second +column gives the name of the principal unit in this object, the third +column gives the status of the source and the fourth column gives the +full path of the source representing this unit. +Here is a simple example of use: + + + :: + + $ gnatls *.o + ./demo1.o demo1 DIF demo1.adb + ./demo2.o demo2 OK demo2.adb + ./hello.o h1 OK hello.adb + ./instr-child.o instr.child MOK instr-child.adb + ./instr.o instr OK instr.adb + ./tef.o tef DIF tef.adb + ./text_io_example.o text_io_example OK text_io_example.adb + ./tgef.o tgef DIF tgef.adb + +The first line can be interpreted as follows: the main unit which is +contained in +object file :file:`demo1.o` is demo1, whose main source is in +:file:`demo1.adb`. Furthermore, the version of the source used for the +compilation of demo1 has been modified (DIF). Each source file has a status +qualifier which can be: + +*OK (unchanged)* + The version of the source file used for the compilation of the + specified unit corresponds exactly to the actual source file. + +*MOK (slightly modified)* + The version of the source file used for the compilation of the + specified unit differs from the actual source file but not enough to + require recompilation. If you use gnatmake with the qualifier + *-m (minimal recompilation)*, a file marked + MOK will not be recompiled. + +*DIF (modified)* + No version of the source found on the path corresponds to the source + used to build this object. + +*??? (file not found)* + No source file was found for this unit. + +*HID (hidden, unchanged version not first on PATH)* + The version of the source that corresponds exactly to the source used + for compilation has been found on the path but it is hidden by another + version of the same source that has been modified. + + +.. _Switches_for_gnatls: + +Switches for `gnatls` +--------------------- + +`gnatls` recognizes the following switches: + + +.. index:: --version (gnatls) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + + +.. index:: --help (gnatls) + +:samp:`*--help` + If *--version* was not used, display usage, then exit disregarding + all other options. + + +.. index:: -a (gnatls) + +:samp:`-a` + Consider all units, including those of the predefined Ada library. + Especially useful with *-d*. + + +.. index:: -d (gnatls) + +:samp:`-d` + List sources from which specified units depend on. + + +.. index:: -h (gnatls) + +:samp:`-h` + Output the list of options. + + +.. index:: -o (gnatls) + +:samp:`-o` + Only output information about object files. + + +.. index:: -s (gnatls) + +:samp:`-s` + Only output information about source files. + + +.. index:: -u (gnatls) + +:samp:`-u` + Only output information about compilation units. + + +.. index:: -files (gnatls) + +:samp:`-files={file}` + Take as arguments the files listed in text file `file`. + Text file `file` may contain empty lines that are ignored. + Each nonempty line should contain the name of an existing file. + Several such switches may be specified simultaneously. + + +.. index:: -aO (gnatls) + +.. index:: -aI (gnatls) + +.. index:: -I (gnatls) + +.. index:: -I- (gnatls) + +:samp:`-aO{dir}`, :samp:`-aI{dir}`, :samp:`-I{dir}`, :samp:`-I-`, :samp:`-nostdinc` + Source path manipulation. Same meaning as the equivalent *gnatmake* + flags (:ref:`Switches_for_gnatmake`). + + +.. index:: -aP (gnatls) + +:samp:`-aP{dir}` + Add `dir` at the beginning of the project search dir. + + +.. index:: --RTS (gnatls) + +:samp:`--RTS={rts-path}`` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + +.. index:: -v (gnatls) + +:samp:`-v` + Verbose mode. Output the complete source, object and project paths. Do not use + the default column layout but instead use long format giving as much as + information possible on each requested units, including special + characteristics such as: + + * *Preelaborable*: The unit is preelaborable in the Ada sense. + + * *No_Elab_Code*: No elaboration code has been produced by the compiler for this unit. + + * *Pure*: The unit is pure in the Ada sense. + + * *Elaborate_Body*: The unit contains a pragma Elaborate_Body. + + * *Remote_Types*: The unit contains a pragma Remote_Types. + + * *Shared_Passive*: The unit contains a pragma Shared_Passive. + + * *Predefined*: This unit is part of the predefined environment and cannot be modified + by the user. + + * *Remote_Call_Interface*: The unit contains a pragma Remote_Call_Interface. + + +.. _Example_of_gnatls_Usage: + +Example of `gnatls` Usage +------------------------- + +Example of using the verbose switch. Note how the source and +object paths are affected by the -I switch. + + :: + + $ gnatls -v -I.. demo1.o + + GNATLS 5.03w (20041123-34) + Copyright 1997-2004 Free Software Foundation, Inc. + + Source Search Path: + <Current_Directory> + ../ + /home/comar/local/adainclude/ + + Object Search Path: + <Current_Directory> + ../ + /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ + + Project Search Path: + <Current_Directory> + /home/comar/local/lib/gnat/ + + ./demo1.o + Unit => + Name => demo1 + Kind => subprogram body + Flags => No_Elab_Code + Source => demo1.adb modified + +The following is an example of use of the dependency list. +Note the use of the -s switch +which gives a straight list of source files. This can be useful for +building specialized scripts. + + :: + + $ gnatls -d demo2.o + ./demo2.o demo2 OK demo2.adb + OK gen_list.ads + OK gen_list.adb + OK instr.ads + OK instr-child.ads + + $ gnatls -d -s -a demo1.o + demo1.adb + /home/comar/local/adainclude/ada.ads + /home/comar/local/adainclude/a-finali.ads + /home/comar/local/adainclude/a-filico.ads + /home/comar/local/adainclude/a-stream.ads + /home/comar/local/adainclude/a-tags.ads + gen_list.ads + gen_list.adb + /home/comar/local/adainclude/gnat.ads + /home/comar/local/adainclude/g-io.ads + instr.ads + /home/comar/local/adainclude/system.ads + /home/comar/local/adainclude/s-exctab.ads + /home/comar/local/adainclude/s-finimp.ads + /home/comar/local/adainclude/s-finroo.ads + /home/comar/local/adainclude/s-secsta.ads + /home/comar/local/adainclude/s-stalib.ads + /home/comar/local/adainclude/s-stoele.ads + /home/comar/local/adainclude/s-stratt.ads + /home/comar/local/adainclude/s-tasoli.ads + /home/comar/local/adainclude/s-unstyp.ads + /home/comar/local/adainclude/unchconv.ads + + +.. _The_Cross-Referencing_Tools_gnatxref_and_gnatfind: + +The Cross-Referencing Tools `gnatxref` and `gnatfind` +===================================================== + +.. index:: ! gnatxref +.. index:: ! gnatfind + +The compiler generates cross-referencing information (unless +you set the :samp:`-gnatx` switch), which are saved in the :file:`.ali` files. +This information indicates where in the source each entity is declared and +referenced. Note that entities in package Standard are not included, but +entities in all other predefined units are included in the output. + +Before using any of these two tools, you need to compile successfully your +application, so that GNAT gets a chance to generate the cross-referencing +information. + +The two tools `gnatxref` and `gnatfind` take advantage of this +information to provide the user with the capability to easily locate the +declaration and references to an entity. These tools are quite similar, +the difference being that `gnatfind` is intended for locating +definitions and/or references to a specified entity or entities, whereas +`gnatxref` is oriented to generating a full report of all +cross-references. + +To use these tools, you must not compile your application using the +*-gnatx* switch on the *gnatmake* command line +(see :ref:`The_GNAT_Make_Program_gnatmake`). Otherwise, cross-referencing +information will not be generated. + +Note: to invoke `gnatxref` or `gnatfind` with a project file, +use the `gnat` driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + +.. _gnatxref_Switches: + +`gnatxref` Switches +------------------- + +The command invocation for `gnatxref` is: + + :: + + $ gnatxref [`switches`] `sourcefile1` [`sourcefile2` ...] + +where + +*sourcefile1* [, *sourcefile2* ...] + identify the source files for which a report is to be generated. The + 'with'ed units will be processed too. You must provide at least one file. + + These file names are considered to be regular expressions, so for instance + specifying :file:`source\*.adb` is the same as giving every file in the current + directory whose name starts with :file:`source` and whose extension is + :file:`adb`. + + You shouldn't specify any directory name, just base names. *gnatxref* + and *gnatfind* will be able to locate these files by themselves using + the source path. If you specify directories, no result is produced. + +The following switches are available for *gnatxref*: + + +.. index:: --version (gnatxref) + +:samp:`-version` + Display Copyright and version, then exit disregarding all other options. + + +.. index:: --help (gnatxref) + +:samp:`-help` + If *--version* was not used, display usage, then exit disregarding + all other options. + + +.. index:: -a (gnatxref) + +:samp:`a` + If this switch is present, `gnatfind` and `gnatxref` will parse + the read-only files found in the library search path. Otherwise, these files + will be ignored. This option can be used to protect Gnat sources or your own + libraries from being parsed, thus making `gnatfind` and `gnatxref` + much faster, and their output much smaller. Read-only here refers to access + or permissions status in the file system for the current user. + + +.. index:: -aIDIR (gnatxref) + +:samp:`aI{DIR}` + When looking for source files also look in directory DIR. The order in which + source file search is undertaken is the same as for *gnatmake*. + + +.. index:: -aODIR (gnatxref) + +:samp:`aO{DIR}` + When searching for library and object files, look in directory + DIR. The order in which library files are searched is the same as for + *gnatmake*. + + +.. index:: -nostdinc (gnatxref) + +:samp:`nostdinc` + Do not look for sources in the system default directory. + + +.. index:: -nostdlib (gnatxref) + +:samp:`nostdlib` + Do not look for library files in the system default directory. + + +.. index:: --ext (gnatxref) + +:samp:`-ext={extension}` + Specify an alternate ali file extension. The default is `ali` and other + extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*) + may be specified via this switch. Note that if this switch overrides the + default, which means that only the new extension will be considered. + + +.. index:: --RTS (gnatxref) + +:samp:`-RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + +.. index:: -d (gnatxref) + +:samp:`d` + If this switch is set `gnatxref` will output the parent type + reference for each matching derived types. + + +.. index:: -f (gnatxref) + +:samp:`f` + If this switch is set, the output file names will be preceded by their + directory (if the file was found in the search path). If this switch is + not set, the directory will not be printed. + + +.. index:: -g (gnatxref) + +:samp:`g` + If this switch is set, information is output only for library-level + entities, ignoring local entities. The use of this switch may accelerate + `gnatfind` and `gnatxref`. + + +.. index:: -IDIR (gnatxref) + +:samp:`I{DIR}` + Equivalent to :samp:`-aODIR -aIDIR`. + + +.. index:: -pFILE (gnatxref) + +:samp:`p{FILE}` + Specify a project file to use :ref:`GNAT_Project_Manager`. + If you need to use the :file:`.gpr` + project files, you should use gnatxref through the GNAT driver + (*gnat xref -Pproject*). + + By default, `gnatxref` and `gnatfind` will try to locate a + project file in the current directory. + + If a project file is either specified or found by the tools, then the content + of the source directory and object directory lines are added as if they + had been specified respectively by :samp:`-aI` + and :samp:`-aO`. + +:samp:`u` + Output only unused symbols. This may be really useful if you give your + main compilation unit on the command line, as `gnatxref` will then + display every unused entity and 'with'ed package. + + +:samp:`v` + Instead of producing the default output, `gnatxref` will generate a + :file:`tags` file that can be used by vi. For examples how to use this + feature, see :ref:`Examples_of_gnatxref_Usage`. The tags file is output + to the standard output, thus you will have to redirect it to a file. + +All these switches may be in any order on the command line, and may even +appear after the file names. They need not be separated by spaces, thus +you can say :samp:`gnatxref -ag` instead of :samp:`gnatxref -a -g`. + +.. _gnatfind_Switches: + +`gnatfind` Switches +------------------- + +The command invocation for `gnatfind` is: + + :: + + $ gnatfind [`switches`] `pattern`[:`sourcefile`[:`line`[:`column`]]] + [`file1` `file2` ...] + +with the following iterpretation of the command arguments: + +*pattern* + An entity will be output only if it matches the regular expression found + in `pattern`, see :ref:`Regular_Expressions_in_gnatfind_and_gnatxref`. + + Omitting the pattern is equivalent to specifying ``*``, which + will match any entity. Note that if you do not provide a pattern, you + have to provide both a sourcefile and a line. + + Entity names are given in Latin-1, with uppercase/lowercase equivalence + for matching purposes. At the current time there is no support for + 8-bit codes other than Latin-1, or for wide characters in identifiers. + +*sourcefile* + `gnatfind` will look for references, bodies or declarations + of symbols referenced in :file:`sourcefile`, at line `line` + and column `column`. See :ref:`Examples_of_gnatfind_Usage` + for syntax examples. + +*line* + A decimal integer identifying the line number containing + the reference to the entity (or entities) to be located. + + +*column* + A decimal integer identifying the exact location on the + line of the first character of the identifier for the + entity reference. Columns are numbered from 1. + + +*file1 file2 ...* + The search will be restricted to these source files. If none are given, then + the search will be conducted for every library file in the search path. + These files must appear only after the pattern or sourcefile. + + These file names are considered to be regular expressions, so for instance + specifying :file:`source\*.adb` is the same as giving every file in the current + directory whose name starts with :file:`source` and whose extension is + :file:`adb`. + + The location of the spec of the entity will always be displayed, even if it + isn't in one of :file:`file1`, :file:`file2`, ... The + occurrences of the entity in the separate units of the ones given on the + command line will also be displayed. + + Note that if you specify at least one file in this part, `gnatfind` may + sometimes not be able to find the body of the subprograms. + + +At least one of 'sourcefile' or 'pattern' has to be present on +the command line. + +The following switches are available: + +.. index:: --version (gnatfind) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + + +.. index:: --help (gnatfind) + +:samp:`-help` + If *--version* was not used, display usage, then exit disregarding + all other options. + + +.. index:: -a (gnatfind) + +:samp:`a` + If this switch is present, `gnatfind` and `gnatxref` will parse + the read-only files found in the library search path. Otherwise, these files + will be ignored. This option can be used to protect Gnat sources or your own + libraries from being parsed, thus making `gnatfind` and `gnatxref` + much faster, and their output much smaller. Read-only here refers to access + or permission status in the file system for the current user. + + +.. index:: -aIDIR (gnatfind) + +:samp:`aI{DIR}` + When looking for source files also look in directory DIR. The order in which + source file search is undertaken is the same as for *gnatmake*. + + +.. index:: -aODIR (gnatfind) + +:samp:`aO{DIR}` + When searching for library and object files, look in directory + DIR. The order in which library files are searched is the same as for + *gnatmake*. + + +.. index:: -nostdinc (gnatfind) + +:samp:`nostdinc` + Do not look for sources in the system default directory. + + +.. index:: -nostdlib (gnatfind) + +:samp:`nostdlib` + Do not look for library files in the system default directory. + + +.. index:: --ext (gnatfind) + +:samp:`-ext={extension}` + Specify an alternate ali file extension. The default is `ali` and other + extensions (e.g. `gli` for C/C++ sources when using *-fdump-xref*) + may be specified via this switch. Note that if this switch overrides the + default, which means that only the new extension will be considered. + + +.. index:: --RTS (gnatfind) + +:samp:`-RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + +.. index:: -d (gnatfind) + +:samp:`d` + If this switch is set, then `gnatfind` will output the parent type + reference for each matching derived types. + + +.. index:: -e (gnatfind) + +:samp:`e` + By default, `gnatfind` accept the simple regular expression set for + `pattern`. If this switch is set, then the pattern will be + considered as full Unix-style regular expression. + + +.. index:: -f (gnatfind) + +:samp:`f` + If this switch is set, the output file names will be preceded by their + directory (if the file was found in the search path). If this switch is + not set, the directory will not be printed. + + +.. index:: -g (gnatfind) + +:samp:`g` + If this switch is set, information is output only for library-level + entities, ignoring local entities. The use of this switch may accelerate + `gnatfind` and `gnatxref`. + + +.. index:: -IDIR (gnatfind) + +:samp:`I{DIR}` + Equivalent to :samp:`-aODIR -aIDIR`. + + +.. index:: -pFILE (gnatfind) + +:samp:`p{FILE}` + Specify a project file (:ref:`GNAT_Project_Manager`) to use. + By default, `gnatxref` and `gnatfind` will try to locate a + project file in the current directory. + + If a project file is either specified or found by the tools, then the content + of the source directory and object directory lines are added as if they + had been specified respectively by :samp:`-aI` and + :samp:`-aO`. + + +.. index:: -r (gnatfind) + +:samp:`r` + By default, `gnatfind` will output only the information about the + declaration, body or type completion of the entities. If this switch is + set, the `gnatfind` will locate every reference to the entities in + the files specified on the command line (or in every file in the search + path if no file is given on the command line). + + +.. index:: -s (gnatfind) + +:samp:`s` + If this switch is set, then `gnatfind` will output the content + of the Ada source file lines were the entity was found. + + +.. index:: -t (gnatfind) + +:samp:`t` + If this switch is set, then `gnatfind` will output the type hierarchy for + the specified type. It act like -d option but recursively from parent + type to parent type. When this switch is set it is not possible to + specify more than one file. + + +All these switches may be in any order on the command line, and may even +appear after the file names. They need not be separated by spaces, thus +you can say :samp:`gnatxref -ag` instead of +:samp:`gnatxref -a -g`. + +As stated previously, gnatfind will search in every directory in the +search path. You can force it to look only in the current directory if +you specify `*` at the end of the command line. + +.. _Project_Files_for_gnatxref_and_gnatfind: + +Project Files for *gnatxref* and *gnatfind* +------------------------------------------- + +Project files allow a programmer to specify how to compile its +application, where to find sources, etc. These files are used +primarily by GPS, but they can also be used +by the two tools `gnatxref` and `gnatfind`. + +A project file name must end with :file:`.gpr`. If a single one is +present in the current directory, then `gnatxref` and `gnatfind` will +extract the information from it. If multiple project files are found, none of +them is read, and you have to use the :samp:`-p` switch to specify the one +you want to use. + +The following lines can be included, even though most of them have default +values which can be used in most cases. +The lines can be entered in any order in the file. +Except for :file:`src_dir` and :file:`obj_dir`, you can only have one instance of +each line. If you have multiple instances, only the last one is taken into +account. + +* *src_dir=DIR* + [default: `"./"`]. + Specifies a directory where to look for source files. Multiple `src_dir` + lines can be specified and they will be searched in the order they + are specified. + + +* *obj_dir=DIR* + [default: `"./"`]. + Specifies a directory where to look for object and library files. Multiple + `obj_dir` lines can be specified, and they will be searched in the order + they are specified + + +* *comp_opt=SWITCHES* + [default: `""`]. + Creates a variable which can be referred to subsequently by using + the `${comp_opt}` notation. This is intended to store the default + switches given to *gnatmake* and *gcc*. + + +* *bind_opt=SWITCHES* + [default: `""`]. + Creates a variable which can be referred to subsequently by using + the :samp:`${bind_opt}` notation. This is intended to store the default + switches given to *gnatbind*. + + +* *link_opt=SWITCHES* + [default: `""`]. + Creates a variable which can be referred to subsequently by using + the :samp:`${link_opt}` notation. This is intended to store the default + switches given to *gnatlink*. + + +* *main=EXECUTABLE* + [default: `""`]. + Specifies the name of the executable for the application. This variable can + be referred to in the following lines by using the :samp:`{${main}` notation. + + +* *comp_cmd=COMMAND* + [default: `"gcc -c -I${src_dir} -g -gnatq"`]. + Specifies the command used to compile a single file in the application. + + +* *make_cmd=COMMAND* + [default: `"gnatmake ${main} -aI${src_dir} + -aO${obj_dir} -g -gnatq -cargs ${comp_opt} + -bargs ${bind_opt} -largs ${link_opt}"`]. + Specifies the command used to recompile the whole application. + + +* *run_cmd=COMMAND* + [default: `"${main}"`]. + Specifies the command used to run the application. + + +* *debug_cmd=COMMAND* + [default: `"gdb ${main}"`]. + Specifies the command used to debug the application + + +*gnatxref* and *gnatfind* only take into account the +`src_dir` and `obj_dir` lines, and ignore the others. + + +.. _Regular_Expressions_in_gnatfind_and_gnatxref: + +Regular Expressions in `gnatfind` and `gnatxref` +------------------------------------------------ + +As specified in the section about *gnatfind*, the pattern can be a +regular expression. Two kinds of regular expressions +are recognized: + +* *Globbing pattern* + These are the most common regular expression. They are the same as are + generally used in a Unix shell command line, or in a DOS session. + + Here is a more formal grammar: + + :: + + regexp ::= term + term ::= elmt -- matches elmt + term ::= elmt elmt -- concatenation (elmt then elmt) + term ::= * -- any string of 0 or more characters + term ::= ? -- matches any character + term ::= [char {char}] -- matches any character listed + term ::= [char - char] -- matches any character in range + +* *Full regular expression* + The second set of regular expressions is much more powerful. This is the + type of regular expressions recognized by utilities such as :samp:`grep`. + + The following is the form of a regular expression, expressed in same BNF + style as is found in the Ada Reference Manual: + + :: + + regexp ::= term {| term} -- alternation (term or term ...) + + term ::= item {item} -- concatenation (item then item) + + item ::= elmt -- match elmt + item ::= elmt * -- zero or more elmt's + item ::= elmt + -- one or more elmt's + item ::= elmt ? -- matches elmt or nothing + + elmt ::= nschar -- matches given character + elmt ::= [nschar {nschar}] -- matches any character listed + elmt ::= [^ nschar {nschar}] -- matches any character not listed + elmt ::= [char - char] -- matches chars in given range + elmt ::= \\ char -- matches given character + elmt ::= . -- matches any single character + elmt ::= ( regexp ) -- parens used for grouping + + char ::= any character, including special characters + nschar ::= any character except ()[].*+?^ + + Here are a few examples: + + ``abcde|fghi`` + will match any of the two strings :samp:`abcde` and :samp:`fghi`, + + ``abc*d`` + will match any string like ``abd``, ``abcd``, ``abccd``, + ``abcccd``, and so on, + + ``[a-z]+`` + will match any string which has only lowercase characters in it (and at + least one character. + + +.. _Examples_of_gnatxref_Usage: + +Examples of `gnatxref` Usage +---------------------------- + +General Usage +^^^^^^^^^^^^^ + +For the following examples, we will consider the following units: + + .. code-block:: ada + + main.ads: + 1: with Bar; + 2: package Main is + 3: procedure Foo (B : in Integer); + 4: C : Integer; + 5: private + 6: D : Integer; + 7: end Main; + + main.adb: + 1: package body Main is + 2: procedure Foo (B : in Integer) is + 3: begin + 4: C := B; + 5: D := B; + 6: Bar.Print (B); + 7: Bar.Print (C); + 8: end Foo; + 9: end Main; + + bar.ads: + 1: package Bar is + 2: procedure Print (B : Integer); + 3: end bar; + +The first thing to do is to recompile your application (for instance, in +that case just by doing a ``gnatmake main``, so that GNAT generates +the cross-referencing information. +You can then issue any of the following commands: + + * ``gnatxref main.adb`` + `gnatxref` generates cross-reference information for main.adb + and every unit 'with'ed by main.adb. + + The output would be: + + :: + + B Type: Integer + Decl: bar.ads 2:22 + B Type: Integer + Decl: main.ads 3:20 + Body: main.adb 2:20 + Ref: main.adb 4:13 5:13 6:19 + Bar Type: Unit + Decl: bar.ads 1:9 + Ref: main.adb 6:8 7:8 + main.ads 1:6 + C Type: Integer + Decl: main.ads 4:5 + Modi: main.adb 4:8 + Ref: main.adb 7:19 + D Type: Integer + Decl: main.ads 6:5 + Modi: main.adb 5:8 + Foo Type: Unit + Decl: main.ads 3:15 + Body: main.adb 2:15 + Main Type: Unit + Decl: main.ads 2:9 + Body: main.adb 1:14 + Print Type: Unit + Decl: bar.ads 2:15 + Ref: main.adb 6:12 7:12 + + + This shows that the entity `Main` is declared in main.ads, line 2, column 9, + its body is in main.adb, line 1, column 14 and is not referenced any where. + + The entity `Print` is declared in bar.ads, line 2, column 15 and it + is referenced in main.adb, line 6 column 12 and line 7 column 12. + + + * ``gnatxref package1.adb package2.ads`` + `gnatxref` will generates cross-reference information for + package1.adb, package2.ads and any other package 'with'ed by any + of these. + + +Using gnatxref with vi +^^^^^^^^^^^^^^^^^^^^^^ + +`gnatxref` can generate a tags file output, which can be used +directly from *vi*. Note that the standard version of *vi* +will not work properly with overloaded symbols. Consider using another +free implementation of *vi*, such as *vim*. + + :: + + $ gnatxref -v gnatfind.adb > tags + + +The following command will generate the tags file for `gnatfind` itself +(if the sources are in the search path!): + + :: + + $ gnatxref -v gnatfind.adb > tags + +From *vi*, you can then use the command :samp:`:tag {entity}` +(replacing `entity` by whatever you are looking for), and vi will +display a new file with the corresponding declaration of entity. + + +.. _Examples_of_gnatfind_Usage: + +Examples of `gnatfind` Usage +---------------------------- + +* ``gnatfind -f xyz:main.adb`` + Find declarations for all entities xyz referenced at least once in + main.adb. The references are search in every library file in the search + path. + + The directories will be printed as well (as the ``-f`` + switch is set) + + The output will look like: + + :: + + directory/main.ads:106:14: xyz <= declaration + directory/main.adb:24:10: xyz <= body + directory/foo.ads:45:23: xyz <= declaration + + I.e., one of the entities xyz found in main.adb is declared at + line 12 of main.ads (and its body is in main.adb), and another one is + declared at line 45 of foo.ads + +* ``gnatfind -fs xyz:main.adb`` + This is the same command as the previous one, but `gnatfind` will + display the content of the Ada source file lines. + + The output will look like: + + :: + + directory/main.ads:106:14: xyz <= declaration + procedure xyz; + directory/main.adb:24:10: xyz <= body + procedure xyz is + directory/foo.ads:45:23: xyz <= declaration + xyz : Integer; + + This can make it easier to find exactly the location your are looking + for. + + +* ``gnatfind -r "*x*":main.ads:123 foo.adb`` + Find references to all entities containing an x that are + referenced on line 123 of main.ads. + The references will be searched only in main.ads and foo.adb. + + +* ``gnatfind main.ads:123`` + Find declarations and bodies for all entities that are referenced on + line 123 of main.ads. + + This is the same as ``gnatfind "*":main.adb:123``` + +* ``gnatfind mydir/main.adb:123:45`` + Find the declaration for the entity referenced at column 45 in + line 123 of file main.adb in directory mydir. Note that it + is usual to omit the identifier name when the column is given, + since the column position identifies a unique reference. + + The column has to be the beginning of the identifier, and should not + point to any character in the middle of the identifier. + + +.. _The_Ada_to_HTML_Converter_gnathtml: + +The Ada to HTML Converter `gnathtml` +==================================== + +.. index:: ! gnathtml + +*gnathtml* is a Perl script that allows Ada source files to be browsed using +standard Web browsers. For installation information, see :ref:`Installing_gnathtml`. + +Ada reserved keywords are highlighted in a bold font and Ada comments in +a blue font. Unless your program was compiled with the gcc *-gnatx* +switch to suppress the generation of cross-referencing information, user +defined variables and types will appear in a different color; you will +be able to click on any identifier and go to its declaration. + +.. _Invoking_gnathtml: + +Invoking *gnathtml* +------------------- + +The command line is as follows: + + :: + + $ perl gnathtml.pl [`switches`] `ada-files` + +You can specify as many Ada files as you want. `gnathtml` will generate +an html file for every ada file, and a global file called :file:`index.htm`. +This file is an index of every identifier defined in the files. + +The following switches are available: + +.. index:: -83 (gnathtml) + +:samp:`83` + Only the Ada 83 subset of keywords will be highlighted. + +.. index:: -cc (gnathtml) + +:samp:`cc {color}` + This option allows you to change the color used for comments. The default + value is green. The color argument can be any name accepted by html. + +.. index:: -d (gnathtml) + +:samp:`d` + If the Ada files depend on some other files (for instance through + `with` clauses, the latter files will also be converted to html. + Only the files in the user project will be converted to html, not the files + in the run-time library itself. + +.. index:: -D (gnathtml) + +:samp:`D` + This command is the same as *-d* above, but *gnathtml* will + also look for files in the run-time library, and generate html files for them. + +.. index:: -ext (gnathtml) + +:samp:`ext {extension}` + This option allows you to change the extension of the generated HTML files. + If you do not specify an extension, it will default to :file:`htm`. + +.. index:: -f (gnathtml) + +:samp:`f` + By default, gnathtml will generate html links only for global entities + ('with'ed units, global variables and types,...). If you specify + *-f* on the command line, then links will be generated for local + entities too. + +.. index:: -l (gnathtml) + +:samp:`l {number}` + If this switch is provided and `number` is not 0, then + `gnathtml` will number the html files every `number` line. + +.. index:: -I (gnathtml) + +:samp:`I {dir}` + Specify a directory to search for library files (:file:`.ALI` files) and + source files. You can provide several -I switches on the command line, + and the directories will be parsed in the order of the command line. + +.. index:: -o (gnathtml) + +:samp:`o {dir}` + Specify the output directory for html files. By default, gnathtml will + saved the generated html files in a subdirectory named :file:`html/`. + +.. index:: -p (gnathtml) + +:samp:`p {file}` + If you are using Emacs and the most recent Emacs Ada mode, which provides + a full Integrated Development Environment for compiling, checking, + running and debugging applications, you may use :file:`.gpr` files + to give the directories where Emacs can find sources and object files. + + Using this switch, you can tell gnathtml to use these files. + This allows you to get an html version of your application, even if it + is spread over multiple directories. + +.. index:: -sc (gnathtml) + +:samp:`sc {color}` + This switch allows you to change the color used for symbol + definitions. + The default value is red. The color argument can be any name accepted by html. + +.. index:: -t (gnathtml) + +:samp:`t {file}` + This switch provides the name of a file. This file contains a list of + file names to be converted, and the effect is exactly as though they had + appeared explicitly on the command line. This + is the recommended way to work around the command line length limit on some + systems. + +.. _Installing_gnathtml: + +Installing `gnathtml` +--------------------- + +`Perl` needs to be installed on your machine to run this script. +`Perl` is freely available for almost every architecture and +operating system via the Internet. + +On Unix systems, you may want to modify the first line of the script +`gnathtml`, to explicitly specify where Perl +is located. The syntax of this line is: + + :: + + #!full_path_name_to_perl + +Alternatively, you may run the script using the following command line: + + :: + + $ perl gnathtml.pl [`switches`] `files` + + + + +.. -- +---------------------------------------------------------------------+ +.. -- | The following sections are present only in the PRO and GPL editions | +.. -- +---------------------------------------------------------------------+ + +.. only:: PRO or GPL + + .. _The_Ada-to-XML_converter_gnat2xml: + + The Ada-to-XML converter *gnat2xml* + =================================== + + .. index: ! gnat2xml + .. index:: XML generation + + The *gnat2xml* tool is an ASIS-based utility that converts + Ada source code into XML. + + .. _Switches_for_*gnat2xml*: + + Switches for *gnat2xml* + ----------------------- + + *gnat2xml* takes Ada source code as input, and produces XML + that conforms to the schema. + + Usage: + + :: + + $ gnat2xml [options] filenames [-files filename] [-cargs gcc_switches] + + Options: + + :samp:`--help` + Generate usage information and quit, ignoring all other options + + :samp:`-h` + Same as ``--help`` + + :samp:`--version` + Print version and quit, ignoring all other options + + :samp:`-P{file}` + indicates the name of the project file that describes + the set of sources to be processed. The exact set of argument + sources depends on other options specified, see below. + + :samp:`-U` + If a project file is specified and no argument source is explicitly + specified, process all the units of the closure of the argument project. + Otherwise this option has no effect. + + :samp:`-U {main_unit}` + If a project file is specified and no argument source + is explicitly specified (either directly or by means of *-files* + option), process the closure of units rooted at `main_unit`. + Otherwise this option has no effect. + + :samp:`-X{name}={value}` + Indicates that external variable `name` in + the argument project has the value `value`. Has no effect if no + project is specified as tool argument. + + :samp:`--RTS={rts-path}` + Specifies the default location of the runtime + library. Same meaning as the equivalent *gnatmake* flag + (:ref:`Switches_for_gnatmake`). + + :samp:`--incremental` + Incremental processing on a per-file basis. Source files are + only processed if they have been modified, or if files they depend + on have been modified. This is similar to the way gnatmake/gprbuild + only compiles files that need to be recompiled. A project file + is required in this mode. + + :samp:`-j{n}` + In *--incremental* mode, use `n` *gnat2xml* + processes to perform XML generation in parallel. If `n` is 0, then + the maximum number of parallel tree creations is the number of core + processors on the platform. + + :samp:`--output-dir={dir}` + Generate one .xml file for each Ada source file, in + directory :file:`dir`. (Default is to generate the XML to standard + output.) + + :samp:`-I{include-dir}` + Directories to search for dependencies. + You can also set the ADA_INCLUDE_PATH environment variable for this. + + :samp:`--compact` + Debugging version, with interspersed source, and a more + compact representation of "sloc". This version does not conform + to any schema. + + :samp:`--rep-clauses` + generate representation clauses (see :ref:`Generating_Representation_Clauses`). + + :samp:`-files={filename}` + The name of a text file containing a list of Ada source files to process + + :samp:`-q` + Quiet + + :samp:`-v` + Verbose + + :samp:`-cargs` ... + Options to pass to gcc + + If a project file is specified and no argument source is explicitly + specified, and no *-U* is specified, then the set of processed + sources is all the immediate units of the argument project. + + Example: + + :: + + $ gnat2xml -v -output-dir=xml-files *.ad[sb] + + The above will create \*.xml files in the :file:`xml-files` subdirectory. + For example, if there is an Ada package Mumble.Dumble, whose spec and + body source code lives in mumble-dumble.ads and mumble-dumble.adb, + the above will produce xml-files/mumble-dumble.ads.xml and + xml-files/mumble-dumble.adb.xml. + + .. _Other_Programs: + + Other Programs + -------------- + + The distribution includes two other programs that are related to + *gnat2xml*: + + *gnat2xsd* is the schema generator, which generates the schema + to standard output, based on the structure of Ada as encoded by + ASIS. You don't need to run *gnat2xsd* in order to use + *gnat2xml*. To generate the schema, type: + + + :: + + $ gnat2xsd > ada-schema.xsd + + + *gnat2xml* generates XML files that will validate against + :file:`ada-schema.xsd`. + + *xml2gnat* is a back-translator that translates the XML back + into Ada source code. The Ada generated by *xml2gnat* has + identical semantics to the original Ada code passed to + *gnat2xml*. It is not textually identical, however --- for + example, no attempt is made to preserve the original indentation. + + .. _Structure_of_the_XML: + + Structure of the XML + -------------------- + + The primary documentation for the structure of the XML generated by + *gnat2xml* is the schema (see *gnat2xsd* above). The + following documentation gives additional details needed to understand + the schema and therefore the XML. + + The elements listed under Defining Occurrences, Usage Occurrences, and + Other Elements represent the syntactic structure of the Ada program. + Element names are given in lower case, with the corresponding element + type Capitalized_Like_This. The element and element type names are + derived directly from the ASIS enumeration type Flat_Element_Kinds, + declared in Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_`` + removed. For example, the ASIS enumeration literal + An_Assignment_Statement corresponds to the XML element + assignment_statement of XML type Assignment_Statement. + + To understand the details of the schema and the corresponding XML, it is + necessary to understand the ASIS standard, as well as the GNAT-specific + extension to ASIS. + + A defining occurrence is an identifier (or character literal or operator + symbol) declared by a declaration. A usage occurrence is an identifier + (or ...) that references such a declared entity. For example, in: + + + .. code-block:: ada + + type T is range 1..10; + X, Y : constant T := 1; + + + The first 'T' is the defining occurrence of a type. The 'X' is the + defining occurrence of a constant, as is the 'Y', and the second 'T' is + a usage occurrence referring to the defining occurrence of T. + + Each element has a 'sloc' (source location), and subelements for each + syntactic subtree, reflecting the Ada grammar as implemented by ASIS. + The types of subelements are as defined in the ASIS standard. For + example, for the right-hand side of an assignment_statement we have + the following comment in asis-statements.ads: + + .. code-block:: ada + + ------------------------------------------------------------------------------ + -- 18.3 function Assignment_Expression + ------------------------------------------------------------------------------ + + function Assignment_Expression + (Statement : Asis.Statement) + return Asis.Expression; + + ------------------------------------------------------------------------------ + ... + -- Returns the expression from the right hand side of the assignment. + ... + -- Returns Element_Kinds: + -- An_Expression + + + The corresponding sub-element of type Assignment_Statement is: + + :: + + <xsd:element name="assignment_expression_q" type="Expression_Class"/> + + where Expression_Class is defined by an xsd:choice of all the + various kinds of expression. + + The 'sloc' of each element indicates the starting and ending line and + column numbers. Column numbers are character counts; that is, a tab + counts as 1, not as however many spaces it might expand to. + + Subelements of type Element have names ending in '_q' (for ASIS + "Query"), and those of type Element_List end in '_ql' + ("Query returning List"). + + Some subelements are 'Boolean'. For example, Private_Type_Definition + has has_abstract_q and has_limited_q, to indicate whether those + keywords are present, as in `type T is abstract limited private;`. + False is represented by a Nil_Element. True is represented + by an element type specific to that query (for example, Abstract and + Limited). + + The root of the tree is a Compilation_Unit, with attributes: + + * unit_kind, unit_class, and unit_origin. These are strings that match the + enumeration literals of types Unit_Kinds, Unit_Classes, and Unit_Origins + in package Asis. + + * unit_full_name is the full expanded name of the unit, starting from a + root library unit. So for `package P.Q.R is ...`, + `unit_full_name="P.Q.R"`. Same for `separate (P.Q) package R is ...`. + + * def_name is the same as unit_full_name for library units; for subunits, + it is just the simple name. + + * source_file is the name of the Ada source file. For example, for + the spec of `P.Q.R`, `source_file="p-q-r.ads"`. This allows one to + interpret the source locations --- the 'sloc' of all elements + within this Compilation_Unit refers to line and column numbers + within the named file. + + Defining occurrences have these attributes: + + * def_name is the simple name of the declared entity, as written in the Ada + source code. + + * def is a unique URI of the form: + + :: + + ada://kind/fully/qualified/name + + where: + + * kind indicates the kind of Ada entity being declared (see below), and + + * fully/qualified/name, is the fully qualified name of the Ada + entity, with each of 'fully', 'qualified', and 'name' being + mangled for uniqueness. We do not document the mangling + algorithm, which is subject to change; we just guarantee that the + names are unique in the face of overloading. + + * type is the type of the declared object, or `null` for + declarations of things other than objects. + + Usage occurrences have these attributes: + + * ref_name is the same as the def_name of the corresponding defining + occurrence. This attribute is not of much use, because of + overloading; use ref for lookups, instead. + + * ref is the same as the def of the corresponding defining + occurrence. + + In summary, `def_name` and `ref_name` are as in the source + code of the declaration, possibly overloaded, whereas `def` and + `ref` are unique-ified. + + Literal elements have this attribute: + + * lit_val is the value of the literal as written in the source text, + appropriately escaped (e.g. `"` ---> `"`). This applies + only to numeric and string literals. Enumeration literals in Ada are + not really "literals" in the usual sense; they are usage occurrences, + and have ref_name and ref as described above. Note also that string + literals used as operator symbols are treated as defining or usage + occurrences, not as literals. + + Elements that can syntactically represent names and expressions (which + includes usage occurrences, plus function calls and so forth) have this + attribute: + + * type. If the element represents an expression or the name of an object, + 'type' is the 'def' for the defining occurrence of the type of that + expression or name. Names of other kinds of entities, such as package + names and type names, do not have a type in Ada; these have type="null" + in the XML. + + Pragma elements have this attribute: + + * pragma_name is the name of the pragma. For language-defined pragmas, the + pragma name is redundant with the element kind (for example, an + assert_pragma element necessarily has pragma_name="Assert"). However, all + implementation-defined pragmas are lumped together in ASIS as a single + element kind (for example, the GNAT-specific pragma Unreferenced is + represented by an implementation_defined_pragma element with + pragma_name="Unreferenced"). + + Defining occurrences of formal parameters and generic formal objects have this + attribute: + + * mode indicates that the parameter is of mode 'in', 'in out', or 'out'. + + All elements other than Not_An_Element have this attribute: + + * checks is a comma-separated list of run-time checks that are needed + for that element. The possible checks are: do_accessibility_check, + do_discriminant_check,do_division_check,do_length_check, + do_overflow_check,do_range_check,do_storage_check,do_tag_check. + + The "kind" part of the "def" and "ref" attributes is taken from the ASIS + enumeration type Flat_Declaration_Kinds, declared in + Asis.Extensions.Flat_Kinds, with the leading ``An_`` or ``A_`` removed, and + any trailing ``_Declaration`` or ``_Specification`` removed. Thus, the + possible kinds are as follows: + + :: + + ordinary_type + task_type + protected_type + incomplete_type + tagged_incomplete_type + private_type + private_extension + subtype + variable + constant + deferred_constant + single_task + single_protected + integer_number + real_number + enumeration_literal + discriminant + component + loop_parameter + generalized_iterator + element_iterator + procedure + function + parameter + procedure_body + function_body + return_variable + return_constant + null_procedure + expression_function + package + package_body + object_renaming + exception_renaming + package_renaming + procedure_renaming + function_renaming + generic_package_renaming + generic_procedure_renaming + generic_function_renaming + task_body + protected_body + entry + entry_body + entry_index + procedure_body_stub + function_body_stub + package_body_stub + task_body_stub + protected_body_stub + exception + choice_parameter + generic_procedure + generic_function + generic_package + package_instantiation + procedure_instantiation + function_instantiation + formal_object + formal_type + formal_incomplete_type + formal_procedure + formal_function + formal_package + formal_package_declaration_with_box + + .. _Generating_Representation_Clauses: + + Generating Representation Clauses + --------------------------------- + + If the *--rep-clauses* switch is given, *gnat2xml* will + generate representation clauses for certain types showing the + representation chosen by the compiler. The information is produced by + the ASIS 'Data Decomposition' facility --- see the + `Asis.Data_Decomposition` package for details. + + Not all types are supported. For example, `Type_Model_Kind` must + be `A_Simple_Static_Model`. Types declared within generic units + have no representation. The clauses that are generated include + `attribute_definition_clauses` for `Size` and + `Component_Size`, as well as + `record_representation_clauses`. + + There is no guarantee that the generated representation clauses could + have actually come from legal Ada code; Ada has some restrictions that + are not necessarily obeyed by the generated clauses. + + The representation clauses are surrounded by comment elements to + indicate that they are automatically generated, something like this: + + :: + + <comment text="--gen+"> + ... + <attribute_definition_clause> + ... + <comment text="--gen-"> + ... + + +.. only:: PRO or GPL + + .. _The_Program_Property_Verifier_gnatcheck: + + The Program Property Verifier *gnatcheck* + ========================================= + + .. index:: ! gnatcheck + .. index:: ASIS + + The *gnatcheck* tool is an ASIS-based utility that checks properties + of Ada source files according to a given set of semantic rules. + + In order to check compliance with a given rule, *gnatcheck* has to + semantically analyze the Ada sources. + Therefore, checks can only be performed on + legal Ada units. Moreover, when a unit depends semantically upon units located + outside the current directory, the source search path has to be provided when + calling *gnatcheck*, either through a specified project file or + through *gnatcheck* switches. + + For full details, refer to :title:`GNATcheck Reference Manual`. + + + +.. only:: PRO or GPL + + .. _The_GNAT_Metrics_Tool_gnatmetric: + + The GNAT Metrics Tool *gnatmetric* + ================================== + + .. index:: ! gnatmetric + .. index:: Metric tool + + The *gnatmetric* tool is an ASIS-based utility + for computing various program metrics. + It takes an Ada source file as input and generates a file containing the + metrics data as output. Various switches control which + metrics are computed and output. + + To compute program metrics, *gnatmetric* invokes the Ada + compiler and generates and uses the ASIS tree for the input source; + thus the input must be legal Ada code, and the tool should have all the + information needed to compile the input source. To provide this information, + you may specify as a tool parameter the project file the input source belongs to + (or you may call *gnatmetric* + through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + Another possibility is to specify the source search + path and needed configuration files in *-cargs* section of *gnatmetric* + call, see the description of the *gnatmetric* switches below. + + If the set of sources to be processed by `gnatmetric` contains sources with + preprocessing directives + then the needed options should be provided to run preprocessor as a part of + the *gnatmetric* call, and the computed metrics + will correspond to preprocessed sources. + + The *gnatmetric* command has the form + + :: + + $ gnatmetric [`switches`] {`filename`} [-cargs `gcc_switches`] + + where: + + * `switches` specify the metrics to compute and define the destination for + the output + + * Each `filename` is the name (including the extension) of a source + file to process. 'Wildcards' are allowed, and + the file name may contain path information. + If no `filename` is supplied, then the `switches` list must contain + at least one + *-files* switch (see :ref:`Other_gnatmetric_Switches`). + Including both a *-files* switch and one or more + `filename` arguments is permitted. + + * `gcc_switches` is a list of switches for + *gcc*. They will be passed on to all compiler invocations made by + *gnatmetric* to generate the ASIS trees. Here you can provide + *-I* switches to form the source search path, + and use the *-gnatec* switch to set the configuration file, + use the *-gnat05* switch if sources should be compiled in + Ada 2005 mode etc. + + The following subsections describe the various switches accepted by + *gnatmetric*, organized by category. + + .. _Output_File_Control-gnatmetric: + + Output File Control + ------------------- + + .. index:: Output file control in gnatmetric + + *gnatmetric* has two output formats. It can generate a + textual (human-readable) form, and also XML. By default only textual + output is generated. + + When generating the output in textual form, *gnatmetric* creates + for each Ada source file a corresponding text file + containing the computed metrics, except for the case when the set of metrics + specified by gnatmetric parameters consists only of metrics that are computed + for the whole set of analyzed sources, but not for each Ada source. + By default, the name of the file containing metric information for a source + is obtained by appending the :file:`.metrix` suffix to the + name of the input source file. If not otherwise specified and no project file + is specified as *gnatmetric* option this file is placed in the same + directory as where the source file is located. If *gnatmetric* has a + project file as its parameter, it places all the generated files in the + object directory of the project (or in the project source directory if the + project does not define an objects directory), if *--subdirs* option + is specified, the files are placed in the subrirectory of this directory + specified by this option. + + All the output information generated in XML format is placed in a single + file. By default the name of this file is :file:`metrix.xml`. + If not otherwise specified and if no project file is specified + as *gnatmetric* option this file is placed in the + current directory. + + Some of the computed metrics are summed over the units passed to + *gnatmetric*; for example, the total number of lines of code. + By default this information is sent to :file:`stdout`, but a file + can be specified with the *-og* switch. + + The following switches control the *gnatmetric* output: + + .. index:: -x (gnatmetric) + + :samp:`-x` + Generate the XML output + + .. index:: -xs (gnatmetric) + + :samp:`-xs` + Generate the XML output and the XML schema file that describes the structure + of the XML metric report, this schema is assigned to the XML file. The schema + file has the same name as the XML output file with :file:`.xml` suffix replaced + with :file:`.xsd` + + .. index:: -nt (gnatmetric) + + + :samp:`-nt` + Do not generate the output in text form (implies *-x*) + + .. index:: -d (gnatmetric) + + + :samp:`-d {output_dir}` + Put text files with detailed metrics into `output_dir` + + .. index:: -o (gnatmetric) + + + :samp:`-o {file_suffix}` + Use `file_suffix`, instead of :file:`.metrix` + in the name of the output file. + + .. index:: -og (gnatmetric) + + + :samp:`-og {file_name}` + Put global metrics into `file_name` + + .. index:: -ox (gnatmetric) + + + :samp:`-ox {file_name}` + Put the XML output into `file_name` (also implies *-x*) + + .. index:: -sfn (gnatmetric) + + + :samp:`-sfn` + Use 'short' source file names in the output. (The *gnatmetric* + output includes the name(s) of the Ada source file(s) from which the metrics + are computed. By default each name includes the absolute path. The + *-sfn* switch causes *gnatmetric* + to exclude all directory information from the file names that are output.) + + + .. index:: Disable Metrics For Local Units in gnatmetric + + .. _Disable_Metrics_For_Local_Units: + + Disable Metrics For Local Units + ------------------------------- + + *gnatmetric* relies on the GNAT compilation model -- + one compilation + unit per one source file. It computes line metrics for the whole source + file, and it also computes syntax + and complexity metrics for the file's outermost unit. + + By default, *gnatmetric* will also compute all metrics for certain + kinds of locally declared program units: + + * subprogram (and generic subprogram) bodies; + + * package (and generic package) specs and bodies; + + * task object and type specifications and bodies; + + * protected object and type specifications and bodies. + + .. index:: Eligible local unit (for gnatmetric) + + These kinds of entities will be referred to as + *eligible local program units*, or simply *eligible local units*, + in the discussion below. + + Note that a subprogram declaration, generic instantiation, + or renaming declaration only receives metrics + computation when it appear as the outermost entity + in a source file. + + Suppression of metrics computation for eligible local units can be + obtained via the following switch: + + + .. index:: -nolocal (gnatmetric) + + + :samp:`-nolocal` + Do not compute detailed metrics for eligible local program units + + + .. _Specifying_a_set_of_metrics_to_compute: + + Specifying a set of metrics to compute + -------------------------------------- + + By default all the metrics are computed and reported. The switches + described in this subsection allow you to control, on an individual + basis, whether metrics are computed and + reported. If at least one positive metric + switch is specified (that is, a switch that defines that a given + metric or set of metrics is to be computed), then only + explicitly specified metrics are reported. + + .. _Line_Metrics_Control: + + Line Metrics Control + ^^^^^^^^^^^^^^^^^^^^ + + .. index:: Line metrics control in gnatmetric + + For any (legal) source file, and for each of its + eligible local program units, *gnatmetric* computes the following + metrics: + + * the total number of lines; + + * the total number of code lines (i.e., non-blank lines that are not comments) + + * the number of comment lines + + * the number of code lines containing end-of-line comments; + + * the comment percentage: the ratio between the number of lines that contain + comments and the number of all non-blank lines, expressed as a percentage; + + * the number of empty lines and lines containing only space characters and/or + format effectors (blank lines) + + * the average number of code lines in subprogram bodies, task bodies, entry + bodies and statement sequences in package bodies (this metric is only computed + across the whole set of the analyzed units) + + *gnatmetric* sums the values of the line metrics for all the + files being processed and then generates the cumulative results. The tool + also computes for all the files being processed the average number of code + lines in bodies. + + You can use the following switches to select the specific line metrics + to be computed and reported. + + + .. index:: --lines (gnatmetric) + .. index:: --no-lines (gnatmetric) + + + :samp:`-lines-all` + Report all the line metrics + + + :samp:`-no-lines-all` + Do not report any of line metrics + + + :samp:`-lines` + Report the number of all lines + + + :samp:`-no-lines` + Do not report the number of all lines + + + :samp:`-lines-code` + Report the number of code lines + + + :samp:`-no-lines-code` + Do not report the number of code lines + + + :samp:`-lines-comment` + Report the number of comment lines + + + :samp:`-no-lines-comment` + Do not report the number of comment lines + + + :samp:`-lines-eol-comment` + Report the number of code lines containing + end-of-line comments + + + :samp:`-no-lines-eol-comment` + Do not report the number of code lines containing + end-of-line comments + + + :samp:`-lines-ratio` + Report the comment percentage in the program text + + + :samp:`-no-lines-ratio` + Do not report the comment percentage in the program text + + + :samp:`-lines-blank` + Report the number of blank lines + + + :samp:`-no-lines-blank` + Do not report the number of blank lines + + + :samp:`-lines-average` + Report the average number of code lines in subprogram bodies, task bodies, + entry bodies and statement sequences in package bodies. The metric is computed + and reported for the whole set of processed Ada sources only. + + + :samp:`-no-lines-average` + Do not report the average number of code lines in subprogram bodies, + task bodies, entry bodies and statement sequences in package bodies. + + + .. _Syntax_Metrics_Control: + + Syntax Metrics Control + ^^^^^^^^^^^^^^^^^^^^^^ + + .. index:: Syntax metrics control in gnatmetric + + *gnatmetric* computes various syntactic metrics for the + outermost unit and for each eligible local unit: + + * *LSLOC ('Logical Source Lines Of Code')* + The total number of declarations and the total number of statements. Note + that the definition of declarations is the one given in the reference + manual: + + "Each of the following is defined to be a declaration: any basic_declaration; + an enumeration_literal_specification; a discriminant_specification; + a component_declaration; a loop_parameter_specification; a + parameter_specification; a subprogram_body; an entry_declaration; + an entry_index_specification; a choice_parameter_specification; + a generic_formal_parameter_declaration." + + This means for example that each enumeration literal adds one to the count, + as well as each subprogram parameter. + + Thus the results from this metric will be significantly greater than might + be expected from a naive view of counting semicolons. + + * *Maximal static nesting level of inner program units* + According to :title:`Ada Reference Manual`, 10.1(1): + + "A program unit is either a package, a task unit, a protected unit, a + protected entry, a generic unit, or an explicitly declared subprogram other + than an enumeration literal." + + * *Maximal nesting level of composite syntactic constructs* + This corresponds to the notion of the + maximum nesting level in the GNAT built-in style checks + (see :ref:`Style_Checking`) + + For the outermost unit in the file, *gnatmetric* additionally computes + the following metrics: + + * *Public subprograms* + This metric is computed for package specs. It is the + number of subprograms and generic subprograms declared in the visible + part (including the visible part of nested packages, protected objects, and + protected types). + + + * *All subprograms* + This metric is computed for bodies and subunits. The + metric is equal to a total number of subprogram bodies in the compilation + unit. + Neither generic instantiations nor renamings-as-a-body nor body stubs + are counted. Any subprogram body is counted, independently of its nesting + level and enclosing constructs. Generic bodies and bodies of protected + subprograms are counted in the same way as 'usual' subprogram bodies. + + + * *Public types* + This metric is computed for package specs and + generic package declarations. It is the total number of types + that can be referenced from outside this compilation unit, plus the + number of types from all the visible parts of all the visible generic + packages. Generic formal types are not counted. Only types, not subtypes, + are included. + + Along with the total number of public types, the following + types are counted and reported separately: + + * *Abstract types* + + * *Root tagged types^ (abstract, non-abstract, private, non-private). Type + extensions are *not* counted + + * *Private types* (including private extensions) + + * *Task types* + + * *Protected types* + + * *All types* + This metric is computed for any compilation unit. It is equal to the total + number of the declarations of different types given in the compilation unit. + The private and the corresponding full type declaration are counted as one + type declaration. Incomplete type declarations and generic formal types + are not counted. + No distinction is made among different kinds of types (abstract, + private etc.); the total number of types is computed and reported. + + By default, all the syntax metrics are computed and reported. You can use the + following switches to select specific syntax metrics. + + + .. index:: --syntax (gnatmetric) + .. index:: --no-syntax (gnatmetric) + + + :samp:`-syntax-all` + Report all the syntax metrics + + + :samp:`-no-syntax-all` + Do not report any of syntax metrics + + + :samp:`-declarations` + Report the total number of declarations + + + :samp:`-no-declarations` + Do not report the total number of declarations + + + :samp:`-statements` + Report the total number of statements + + + :samp:`-no-statements` + Do not report the total number of statements + + + :samp:`-public-subprograms` + Report the number of public subprograms in a compilation unit + + + :samp:`-no-public-subprograms` + Do not report the number of public subprograms in a compilation unit + + + :samp:`-all-subprograms` + Report the number of all the subprograms in a compilation unit + + + :samp:`-no-all-subprograms` + Do not report the number of all the subprograms in a compilation unit + + + :samp:`-public-types` + Report the number of public types in a compilation unit + + + :samp:`-no-public-types` + Do not report the number of public types in a compilation unit + + + :samp:`-all-types` + Report the number of all the types in a compilation unit + + + :samp:`-no-all-types` + Do not report the number of all the types in a compilation unit + + + :samp:`-unit-nesting` + Report the maximal program unit nesting level + + + :samp:`-no-unit-nesting` + Do not report the maximal program unit nesting level + + + :samp:`-construct-nesting` + Report the maximal construct nesting level + + + :samp:`-no-construct-nesting` + Do not report the maximal construct nesting level + + + .. _Complexity_Metrics_Control: + + Complexity Metrics Control + ^^^^^^^^^^^^^^^^^^^^^^^^^^ + + .. index:: Complexity metrics control in gnatmetric + + For a program unit that is an executable body (a subprogram body (including + generic bodies), task body, entry body or a package body containing + its own statement sequence) *gnatmetric* computes the following + complexity metrics: + + * McCabe cyclomatic complexity; + + * McCabe essential complexity; + + * maximal loop nesting level; + + * extra exit points (for subprograms); + + The McCabe cyclomatic complexity metric is defined + in `http://www.mccabe.com/pdf/mccabe-nist235r.pdf <http://www.mccabe.com/pdf/mccabe-nist235r.pdf>`_ + + According to McCabe, both control statements and short-circuit control forms + should be taken into account when computing cyclomatic complexity. + For Ada 2012 we have also take into account conditional expressions + and quantified expressions. For each body, we compute three metric values: + + * the complexity introduced by control + statements only, without taking into account short-circuit forms + (referred as `statement complexity` in *gnatmetric* output), + + * the complexity introduced by short-circuit control forms only + (referred as `expression complexity` in *gnatmetric* output), and + + * the total + cyclomatic complexity, which is the sum of these two values + (referred as `cyclomatic complexity` in *gnatmetric* output). + + The cyclomatic complexity is also computed for Ada 2012 expression functions. + An expression function cannot have statements as its components, so only one + metric value is computed as a cyclomatic complexity of an expression function. + + The origin of cyclomatic complexity metric is the need to estimate the number + of independent paths in the control flow graph that in turn gives the number + of tests needed to satisfy paths coverage testing completeness criterion. + Considered from the testing point of view, a static Ada `loop` (that is, + the `loop` statement having static subtype in loop parameter + specification) does not add to cyclomatic complexity. By providing + *--no-static-loop* option a user + may specify that such loops should not be counted when computing the + cyclomatic complexity metric + + The Ada essential complexity metric is a McCabe cyclomatic complexity metric + counted for the code that is reduced by excluding all the pure structural Ada + control statements. An compound statement is considered as a non-structural + if it contains a `raise` or `return` statement as it subcomponent, + or if it contains a `goto` statement that transfers the control outside + the operator. A selective accept statement with `terminate` alternative + is considered as non-structural statement. When computing this metric, + `exit` statements are treated in the same way as `goto` + statements unless *-ne* option is specified. + + The Ada essential complexity metric defined here is intended to quantify + the extent to which the software is unstructured. It is adapted from + the McCabe essential complexity metric defined in + http://www.mccabe.com/pdf/mccabe-nist235r.pdf + but is modified to be more + suitable for typical Ada usage. For example, short circuit forms + are not penalized as unstructured in the Ada essential complexity metric. + + When computing cyclomatic and essential complexity, *gnatmetric* skips + the code in the exception handlers and in all the nested program units. The + code of assertions and predicates (that is, subprogram preconditions and + postconditions, subtype predicates and type invariants) is also skipped. + + By default, all the complexity metrics are computed and reported. + For more fine-grained control you can use + the following switches: + + + .. index:: -complexity (gnatmetric) + .. index:: --no-complexity (gnatmetric) + + + :samp:`-complexity-all` + Report all the complexity metrics + + + :samp:`-no-complexity-all` + Do not report any of complexity metrics + + + :samp:`-complexity-cyclomatic` + Report the McCabe Cyclomatic Complexity + + + :samp:`-no-complexity-cyclomatic` + Do not report the McCabe Cyclomatic Complexity + + + :samp:`-complexity-essential` + Report the Essential Complexity + + + :samp:`-no-complexity-essential` + Do not report the Essential Complexity + + + :samp:`-loop-nesting` + Report maximal loop nesting level + + + :samp:`-no-loop-nesting` + Do not report maximal loop nesting level + + + :samp:`-complexity-average` + Report the average McCabe Cyclomatic Complexity for all the subprogram bodies, + task bodies, entry bodies and statement sequences in package bodies. + The metric is computed and reported for whole set of processed Ada sources + only. + + + :samp:`-no-complexity-average` + Do not report the average McCabe Cyclomatic Complexity for all the subprogram + bodies, task bodies, entry bodies and statement sequences in package bodies + + .. index:: -ne (gnatmetric) + + + :samp:`-ne` + Do not consider `exit` statements as `goto`\ s when + computing Essential Complexity + + .. index:: --no-static-loop (gnatmetric) + + + :samp:`-no-static-loop` + Do not consider static loops when computing cyclomatic complexity + + + :samp:`-extra-exit-points` + Report the extra exit points for subprogram bodies. As an exit point, this + metric counts `return` statements and raise statements in case when the + raised exception is not handled in the same body. In case of a function this + metric subtracts 1 from the number of exit points, because a function body + must contain at least one `return` statement. + + + :samp:`-no-extra-exit-points` + Do not report the extra exit points for subprogram bodies + + + .. _Coupling_Metrics_Control: + + Coupling Metrics Control + ^^^^^^^^^^^^^^^^^^^^^^^^ + + .. index:: Coupling metrics control in gnatmetric + + .. index:: Coupling metrics (in gnatmetric) + + Coupling metrics measure the dependencies between a given entity and other + entities in the program. This information is useful since high coupling + may signal potential issues with maintainability as the program evolves. + + *gnatmetric* computes the following coupling metrics: + + + * *object-oriented coupling*, for classes in traditional object-oriented + sense; + + * *unit coupling*, for all the program units making up a program; + + * *control coupling*, reflecting dependencies between a unit and + other units that contain subprograms. + + .. index:: fan-out coupling + .. index:: efferent coupling + + Two kinds of coupling metrics are computed: + + * fan-out coupling ('efferent coupling'): + the number of entities the given entity depends upon. This metric + reflects how the given entity depends on the changes in the + 'external world'. + + .. index:: fan-in coupling + .. index:: afferent coupling + + * fan-in coupling ('afferent' coupling): + the number of entities that depend on a given entity. + This metric reflects how the 'external world' depends on the changes in a + given entity. + + Object-oriented coupling metrics measure the dependencies + between a given class (or a group of classes) and the other classes in the + program. In this subsection the term 'class' is used in its traditional + object-oriented programming sense (an instantiable module that contains data + and/or method members). A *category* (of classes) is a group of closely + related classes that are reused and/or modified together. + + A class `K`'s fan-out coupling is the number of classes + that `K` depends upon. + A category's fan-out coupling is the number of classes outside the + category that the classes inside the category depend upon. + + A class `K`'s fan-in coupling is the number of classes + that depend upon `K`. + A category's fan-in coupling is the number of classes outside the + category that depend on classes belonging to the category. + + Ada's object-oriented paradigm separates the instantiable entity + (type) from the module (package), so the definition of the coupling + metrics for Ada maps the class and class category notions + onto Ada constructs. + + For the coupling metrics, several kinds of modules that define a tagged type + or an interface type -- library packages, library generic packages, and + library generic package instantiations -- are considered to be classes. + A category consists of a library package (or + a library generic package) that defines a tagged or an interface type, + together with all its descendant (generic) packages that define tagged + or interface types. Thus a + category is an Ada hierarchy of library-level program units. Class + coupling in Ada is referred to as 'tagged coupling', and category coupling + is referred to as 'hierarchy coupling'. + + For any package serving as a class, its body and subunits (if any) are + considered together with its spec when computing dependencies, and coupling + metrics are reported for spec units only. Dependencies between classes + mean Ada semantic dependencies. For object-oriented coupling + metrics, only dependencies on units treated as classes are + considered. + + Similarly, for unit and control coupling an entity is considered to be the + conceptual construct consisting of the entity's specification, body, and + any subunits (transitively). + *gnatmetric* computes + the dependencies of all these units as a whole, but + metrics are only reported for spec + units (or for a subprogram body unit in case if there is no + separate spec for the given subprogram). + + For unit coupling, dependencies are computed between all kinds of program + units. For control coupling, the dependencies of a given unit are limited to + those units that define subprograms. Thus control fan-out coupling is reported + for all units, but control fan-in coupling is only reported for units + that define subprograms. + + The following simple example illustrates the difference between unit coupling + and control coupling metrics: + + .. code-block:: ada + + package Lib_1 is + function F_1 (I : Integer) return Integer; + end Lib_1; + + package Lib_2 is + type T_2 is new Integer; + end Lib_2; + + package body Lib_1 is + function F_1 (I : Integer) return Integer is + begin + return I + 1; + end F_1; + end Lib_1; + + with Lib_2; use Lib_2; + package Pack is + Var : T_2; + function Fun (I : Integer) return Integer; + end Pack; + + with Lib_1; use Lib_1; + package body Pack is + function Fun (I : Integer) return Integer is + begin + return F_1 (I); + end Fun; + end Pack; + + If we apply *gnatmetric* with the *--coupling-all* option to + these units, the result will be: + + :: + + Coupling metrics: + ================= + Unit Lib_1 (C:\\customers\\662\\L406-007\\lib_1.ads) + control fan-out coupling : 0 + control fan-in coupling : 1 + unit fan-out coupling : 0 + unit fan-in coupling : 1 + + Unit Pack (C:\\customers\\662\\L406-007\\pack.ads) + control fan-out coupling : 1 + control fan-in coupling : 0 + unit fan-out coupling : 2 + unit fan-in coupling : 0 + + Unit Lib_2 (C:\\customers\\662\\L406-007\\lib_2.ads) + control fan-out coupling : 0 + unit fan-out coupling : 0 + unit fan-in coupling : 1 + + The result does not contain values for object-oriented + coupling because none of the argument units contains a tagged type and + therefore none of these units can be treated as a class. + + The `Pack` package (spec and body) depends on two + units -- `Lib_1` `and Lib_2` -- and so its unit fan-out coupling + is 2. Since nothing depends on it, its unit fan-in coupling is 0, as + is its control fan-in coupling. Only one of the units `Pack` depends + upon defines a subprogram, so its control fan-out coupling is 1. + + `Lib_2` depends on nothing, so its fan-out metrics are 0. It does + not define any subprograms, so it has no control fan-in metric. + One unit (`Pack`) depends on it , so its unit fan-in coupling is 1. + + `Lib_1` is similar to `Lib_2`, but it does define a subprogram. + Its control fan-in coupling is 1 (because there is one unit + depending on it). + + When computing coupling metrics, *gnatmetric* counts only + dependencies between units that are arguments of the *gnatmetric* + invocation. Coupling metrics are program-wide (or project-wide) metrics, so + you should invoke *gnatmetric* for + the complete set of sources comprising your program. This can be done + by invoking *gnatmetric* with the corresponding project file + and with the *-U* option. + + By default, all the coupling metrics are disabled. You can use the following + switches to specify the coupling metrics to be computed and reported: + + .. index:: --tagged-coupling (gnatmetric) + .. index:: --hierarchy-coupling (gnatmetric) + .. index:: --unit-coupling (gnatmetric) + .. index:: --control-coupling (gnatmetric) + + :samp:`-coupling-all` + Report all the coupling metrics + + + :samp:`-tagged-coupling-out` + Report tagged (class) fan-out coupling + + + :samp:`-tagged-coupling-in` + Report tagged (class) fan-in coupling + + + :samp:`-hierarchy-coupling-out` + Report hierarchy (category) fan-out coupling + + + :samp:`-hierarchy-coupling-in` + Report hierarchy (category) fan-in coupling + + + :samp:`-unit-coupling-out` + Report unit fan-out coupling + + + :samp:`-unit-coupling-in` + Report unit fan-in coupling + + + :samp:`-control-coupling-out` + Report control fan-out coupling + + + :samp:`-control-coupling-in` + Report control fan-in coupling + + + .. _Other_gnatmetric_Switches: + + Other `gnatmetric` Switches + --------------------------- + + Additional *gnatmetric* switches are as follows: + + + .. index:: --version (gnatmetric) + + :samp:`-version` + Display Copyright and version, then exit disregarding all other options. + + + .. index:: --help (gnatmetric) + + :samp:`-help` + Display usage, then exit disregarding all other options. + + + .. index:: -P (gnatmetric) + + :samp:`-P {file}` + Indicates the name of the project file that describes the set of sources + to be processed. The exact set of argument sources depends on other options + specified, see below. + + + .. index:: -U (gnatmetric) + + :samp:`-U` + If a project file is specified and no argument source is explicitly + specified (either directly or by means of *-files* option), process + all the units of the closure of the argument project. Otherwise this option + has no effect. + + + :samp:`-U {main_unit}` + If a project file is specified and no argument source is explicitly + specified (either directly or by means of *-files* option), process + the closure of units rooted at `main_unit`. Otherwise this option + has no effect. + + + .. index:: -X (gnatmetric) + + :samp:`-X{name}={value}` + Indicates that external variable `name` in the argument project + has the value `value`. Has no effect if no project is specified as + tool argument. + + + .. index:: --RTS (gnatmetric) + + :samp:`-RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (see :ref:`Switches_for_gnatmake`). + + + .. index:: --subdirs=dir (gnatmetric) + + :samp:`-subdirs={dir}` + Use the specified subdirectory of the project objects file (or of the + project file directory if the project does not specify an object directory) + for tool output files. Has no effect if no project is specified as + tool argument r if *--no_objects_dir* is specified. + + + .. index:: --no_objects_dir (gnatmetric) + + :samp:`-no_objects_dir` + Place all the result files into the current directory instead of + project objects directory. This corresponds to the *gnatcheck* + behavior when it is called with the project file from the + GNAT driver. Has no effect if no project is specified. + + + .. index:: -files (gnatmetric) + + :samp:`-files {filename}` + Take the argument source files from the specified file. This file should be an + ordinary text file containing file names separated by spaces or + line breaks. You can use this switch more than once in the same call to + *gnatmetric*. You also can combine this switch with + an explicit list of files. + + + .. index:: -j (gnatmetric) + + :samp:`-j{n}` + Use `n` processes to carry out the tree creations (internal representations + of the argument sources). On a multiprocessor machine this speeds up processing + of big sets of argument sources. If `n` is 0, then the maximum number of + parallel tree creations is the number of core processors on the platform. + + .. index:: -t (gnatmetric) + + + :samp:`-t` + Print out execution time. + + + .. index:: -v (gnatmetric) + + :samp:`-v` + Verbose mode; + *gnatmetric* generates version information and then + a trace of sources being processed. + + + .. index:: -q (gnatmetric) + + :samp:`-q` + Quiet mode. + + If a project file is specified and no argument source is explicitly + specified (either directly or by means of *-files* option), and no + *-U* is specified, then the set of processed sources is + all the immediate units of the argument project. + + +.. only:: PRO or GPL + + .. _The_GNAT_Pretty-Printer_gnatpp: + + The GNAT Pretty-Printer *gnatpp* + ================================ + + .. index:: ! gnatpp + .. index:: Pretty-Printer + + The *gnatpp* tool is an ASIS-based utility + for source reformatting / pretty-printing. + It takes an Ada source file as input and generates a reformatted + version as output. + You can specify various style directives via switches; e.g., + identifier case conventions, rules of indentation, and comment layout. + + Note: A newly-redesigned set of formatting algorithms used by gnatpp + is now available. + To invoke the old formatting algorithms, use the ``--pp-old`` switch. + Support for ``--pp-old`` will be removed in some future version. + + To produce a reformatted file, *gnatpp* invokes the Ada + compiler and generates and uses the ASIS tree for the input source; + thus the input must be legal Ada code, and the tool should have all the + information needed to compile the input source. To provide this information, + you may specify as a tool parameter the project file the input source belongs to + (or you may call *gnatpp* + through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + Another possibility is to specify the source search + path and needed configuration files in ``-cargs`` section of *gnatpp* + call, see the description of the *gnatpp* switches below. + + *gnatpp* cannot process sources that contain preprocessing directives. + + The *gnatpp* command has the form + + :: + + $ gnatpp [`switches`] `filename` [-cargs `gcc_switches`] + + where + + * `switches` is an optional sequence of switches defining such properties as + the formatting rules, the source search path, and the destination for the + output source file + + * `filename` is the name (including the extension) of the source file to + reformat; wildcards or several file names on the same gnatpp command are + allowed. The file name may contain path information; it does not have to + follow the GNAT file naming rules + + * `gcc_switches` is a list of switches for + *gcc*. They will be passed on to all compiler invocations made by + *gnatpp* to generate the ASIS trees. Here you can provide + ``-I`` switches to form the source search path, + use the ``-gnatec`` switch to set the configuration file, etc. + + + .. _Switches_for_gnatpp: + + Switches for *gnatpp* + --------------------- + + The following subsections describe the various switches accepted by + *gnatpp*, organized by category. + + You specify a switch by supplying a name and generally also a value. + In many cases the values for a switch with a given name are incompatible with + each other + (for example the switch that controls the casing of a reserved word may have + exactly one value: upper case, lower case, or + mixed case) and thus exactly one such switch can be in effect for an + invocation of *gnatpp*. + If more than one is supplied, the last one is used. + However, some values for the same switch are mutually compatible. + You may supply several such switches to *gnatpp*, but then + each must be specified in full, with both the name and the value. + Abbreviated forms (the name appearing once, followed by each value) are + not permitted. + + .. _Alignment_Control: + + Alignment Control + ^^^^^^^^^^^^^^^^^ + + .. index:: Alignment control in gnatpp + + Programs can be easier to read if certain constructs are vertically aligned. + By default, alignment of the following constructs is set ON: + + * ``:`` in declarations, + * ``:=`` in initializations in declarations, + * ``:=`` in assignment statements, + * ``=>`` in associations, and + * ``at`` keywords in the component clauses in record representation clauses. + + + .. index:: -A0 (gnatpp) + .. index:: -A1 (gnatpp) + + + :samp:`-A0` + Set alignment to OFF + + + :samp:`-A1` + Set alignment to ON + + .. _Casing_Control: + + + Casing Control + ^^^^^^^^^^^^^^ + + .. index:: Casing control in gnatpp + + *gnatpp* allows you to specify the casing for reserved words, + pragma names, attribute designators and identifiers. + For identifiers you may define a + general rule for name casing but also override this rule + via a set of dictionary files. + + Three types of casing are supported: lower case, upper case, and mixed case. + 'Mixed case' means that the first letter, and also each letter immediately + following an underscore, are converted to their uppercase forms; + all the other letters are converted to their lowercase forms. + + .. index:: -a (gnatpp) + + + :samp:`-aL` + Attribute designators are lower case + + + :samp:`-aU` + Attribute designators are upper case + + + :samp:`-aM` + Attribute designators are mixed case (this is the default) + + .. index:: -k (gnatpp) + + + :samp:`-kL` + Keywords (technically, these are known in Ada as *reserved words*) are + lower case (this is the default) + + + :samp:`-kU` + Keywords are upper case + + .. index:: -n (gnatpp) + + + :samp:`-nD` + Name casing for defining occurrences are as they appear in the source file + (this is the default) + + + :samp:`-nU` + Names are in upper case + + + :samp:`-nL` + Names are in lower case + + + :samp:`-nM` + Names are in mixed case + + .. index:: -ne (gnatpp) + + + :samp:`-neD` + Enumeration literal casing for defining occurrences are as they appear in the + source file. Overrides -n casing setting. + + + :samp:`-neU` + Enumeration literals are in upper case. Overrides -n casing + setting. + + + :samp:`-neL` + Enumeration literals are in lower case. Overrides -n casing + setting. + + + :samp:`-neM` + Enumeration literals are in mixed case. Overrides -n casing + setting. + + .. index:: -nt (gnatpp) + + + :samp:`-neD` + Names introduced by type and subtype declarations are always + cased as they appear in the declaration in the source file. + Overrides -n casing setting. + + + :samp:`-ntU` + Names introduced by type and subtype declarations are always in + upper case. Overrides -n casing setting. + + + :samp:`-ntL` + Names introduced by type and subtype declarations are always in + lower case. Overrides -n casing setting. + + + :samp:`-ntM` + Names introduced by type and subtype declarations are always in + mixed case. Overrides -n casing setting. + + + :samp:`-nnU` + Names introduced by number declarations are always in + upper case. Overrides -n casing setting. + + + :samp:`-nnL` + Names introduced by number declarations are always in + lower case. Overrides -n casing setting. + + + :samp:`-nnM` + Names introduced by number declarations are always in + mixed case. Overrides -n casing setting. + + .. index:: -p (gnatpp) + + + :samp:`-pL` + Pragma names are lower case + + + :samp:`-pU` + Pragma names are upper case + + + :samp:`-pM` + Pragma names are mixed case (this is the default) + + + .. index:: -D (gnatpp) + + :samp:`-D{file}` + Use `file` as a *dictionary file* that defines + the casing for a set of specified names, + thereby overriding the effect on these names by + any explicit or implicit + -n switch. + To supply more than one dictionary file, + use several ``-D`` switches. + + *gnatpp* implicitly uses a *default dictionary file* + to define the casing for the Ada predefined names and + the names declared in the GNAT libraries. + + + .. index:: -D- (gnatpp) + + :samp:`-D-` + Do not use the default dictionary file; + instead, use the casing + defined by a ``-n`` switch and any explicit + dictionary file(s) + + The structure of a dictionary file, and details on the conventions + used in the default dictionary file, are defined in :ref:`Name_Casing`. + + The ``-D-`` and + ``-D-``\ `file` switches are mutually + compatible. + + This group of *gnatpp* switches controls the layout of comments and + complex syntactic constructs. See :ref:`Formatting_Comments` for details + on their effect. + + + .. index:: -c (gnatpp) + + + :samp:`-c0` + All comments remain unchanged. + + + :samp:`-c1` + GNAT-style comment line indentation. + This is the default. + + + :samp:`-c3` + GNAT-style comment beginning. + + + :samp:`-c4` + Fill comment blocks. + + + :samp:`-c5` + Keep unchanged special form comments. + This is the default. + + + .. index:: --comments-only (gnatpp) + + :samp:`--comments-only` + Format just the comments. + + .. index:: --no-separate-is (gnatpp) + + + :samp:`--no-separate-is` + Do not place the keyword `is` on a separate line in a subprogram body in + case if the spec occupies more than one line. + + .. index:: --separate-loop-then (gnatpp) + + + :samp:`--separate-loop-then` + Place the keyword `loop` in FOR and WHILE loop statements and the + keyword `then` in IF statements on a separate line. + + .. index:: --no-separate-loop-then (gnatpp) + + + :samp:`--no-separate-loop-then` + Do not place the keyword `loop` in FOR and WHILE loop statements and the + keyword `then` in IF statements on a separate line. This option is + incompatible with ``--separate-loop-then`` option. + + .. index:: --use-on-new-line (gnatpp) + + + :samp:`--use-on-new-line` + Start each USE clause in a context clause from a separate line. + + .. index:: --insert-blank-lines (gnatpp) + + + :samp:`--insert-blank-lines` + Insert blank lines where appropriate (between bodies and other large + constructs). + + .. index:: --preserve-blank-lines (gnatpp) + + + :samp:`--preserve-blank-lines` + Preserve blank lines in the input. By default, gnatpp will squeeze + multiple blank lines down to one. + + + The ``-c`` switches are compatible with one another, except that + the ``-c0`` switch disables all other comment formatting + switches. + + + .. _General_Text_Layout_Control: + + General Text Layout Control + ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + These switches allow control over line length and indentation. + + .. index:: -M (gnatpp) + + :samp:`-M{nnn}` + Maximum line length, `nnn` from 32...256, the default value is 79 + + + .. index:: -i (gnatpp) + + :samp:`-i{nnn}` + Indentation level, `nnn` from 1...9, the default value is 3 + + + .. index:: -cl (gnatpp) + + :samp:`-cl{nnn}` + Indentation level for continuation lines (relative to the line being + continued), `nnn` from 1...9. + The default + value is one less than the (normal) indentation level, unless the + indentation is set to 1 (in which case the default value for continuation + line indentation is also 1) + + + .. _Other_Formatting_Options: + + Other Formatting Options + ^^^^^^^^^^^^^^^^^^^^^^^^ + + These switches control other formatting not listed above. + + .. index:: --decimal-grouping (gnatpp) + + :samp:`--decimal-grouping={n}` + Put underscores in decimal literals (numeric literals without a base) + every `n` characters. If a literal already has one or more + underscores, it is not modified. For example, with + `--decimal-grouping=3`, `1000000` will be changed to + `1_000_000`. + + + .. index:: --based-grouping (gnatpp) + + :samp:`--based-grouping={n}` + Same as `--decimal-grouping`, but for based literals. For + example, with `--based-grouping=4`, `16#0001FFFE#` will be + changed to `16#0001_FFFE#`. + + + .. index:: --split-line-before-op (gnatpp) + + :samp:`--split-line-before-op` + If it is necessary to split a line at a binary operator, by default + the line is split after the operator. With this option, it is split + before the operator. + + + .. index:: --RM-style-spacing (gnatpp) + + :samp:`--RM-style-spacing` + Do not insert an extra blank before various occurrences of + '(' and ':'. This also turns off alignment. + + + .. index:: -ff (gnatpp) + + :samp:`-ff` + Insert a Form Feed character after a pragma Page. + + + .. index:: --call_threshold (gnatpp) + + :samp:`--call_threshold={nnn}` + If the number of parameter associations is greater than `nnn` and if at + least one association uses named notation, start each association from + a new line. If `nnn` is 0, no check for the number of associations + is made; this is the default. + + + .. index:: --par_threshold (gnatpp) + + :samp:`--par_threshold={nnn}` + If the number of parameter specifications is greater than `nnn` + (or equal to `nnn` in case of a function), start each specification from + a new line. This feature is disabled by default. + + + .. _Setting_the_Source_Search_Path: + + Setting the Source Search Path + ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + To define the search path for the input source file, *gnatpp* + uses the same switches as the GNAT compiler, with the same effects: + + .. index:: -I (gnatpp) + + + :samp:`-I{dir}` + + .. index:: -I- (gnatpp) + + :samp:`-I-` + + .. index:: -gnatec (gnatpp) + + :samp:`-gnatec={path}` + + + .. _Output_File_Control-gnatpp: + + Output File Control + ^^^^^^^^^^^^^^^^^^^ + + By default the output is sent to a file whose name is obtained by appending + the :file:`.pp` suffix to the name of the input file. + If the file with this name already exists, it is overwritten. + Thus if the input file is :file:`my_ada_proc.adb` then + *gnatpp* will produce :file:`my_ada_proc.adb.pp` + as output file. + The output may be redirected by the following switches: + + + .. index:: --output-dir (gnatpp) + + :samp:`--output-dir={dir}` + Generate output file in directory :file:`dir` with the same name as the input + file. If :file:`dir` is the same as the directory containing the input file, + the input file is not processed; use ``-rnb`` + if you want to update the input file in place. + + + .. index:: -pipe (gnatpp) + + :samp:`-pipe` + Send the output to `Standard_Output` + + + .. index:: -o (gnatpp) + + :samp:`-o {output_file}` + Write the output into `output_file`. + If `output_file` already exists, *gnatpp* terminates without + reading or processing the input file. + + + .. index:: -of (gnatpp) + + :samp:`-of {output_file}` + Write the output into `output_file`, overwriting the existing file + (if one is present). + + + .. index:: -r (gnatpp) + + :samp:`-r` + Replace the input source file with the reformatted output, and copy the + original input source into the file whose name is obtained by appending the + :file:`.npp` suffix to the name of the input file. + If a file with this name already exists, *gnatpp* terminates without + reading or processing the input file. + + + .. index:: -rf (gnatpp) + + :samp:`-rf` + Like ``-r`` except that if the file with the specified name + already exists, it is overwritten. + + + .. index:: -rnb (gnatpp) + + :samp:`-rnb` + Replace the input source file with the reformatted output without + creating any backup copy of the input source. + + + .. index:: --eol (gnatpp) + + :samp:`--eol={xxx}` + Specifies the line-ending style of the reformatted output file. The `xxx` + string specified with the switch may be: + + * *dos* - MS DOS style, lines end with CR LF characters* + * *crlf* - the same as *dos* + * *unix* - UNIX style, lines end with LF character* + * *lf* - the same as *unix* + + .. index:: -W (gnatpp) + + :samp:`-W{e}` + Specify the wide character encoding method for the input and output files. + `e` is one of the following: + + * *h* - Hex encoding + + * *u* - Upper half encoding + + * *s* - Shift/JIS encoding + + * *e* - EUC encoding + + * *8* - UTF-8 encoding + + * *b* - Brackets encoding (default value) + + Options ``-o`` and ``-of`` are allowed only if the call to gnatpp + contains only one file to reformat. + + Option ``--eol`` and ``-W`` cannot be used together + with the ``-pipe`` option. + + + .. _Other_gnatpp_Switches: + + Other `gnatpp` Switches + ^^^^^^^^^^^^^^^^^^^^^^^ + + The additional *gnatpp* switches are defined in this subsection. + + + .. index:: --version (gnatpp) + + :samp:`--version` + Display copyright and version, then exit disregarding all other options. + + + .. index:: --help (gnatpp) + + :samp:`--help` + Display usage, then exit disregarding all other options. + + + .. index:: -P (gnatpp) + + :samp:`-P {file}` + Indicates the name of the project file that describes the set of sources + to be processed. The exact set of argument sources depends on other options + specified; see below. + + + .. index:: -U (gnatpp) + + :samp:`-U` + If a project file is specified and no argument source is explicitly + specified (either directly or by means of ``-files`` option), process + all the units of the closure of the argument project. Otherwise this option + has no effect. + + + :samp:`-U {main_unit}` + If a project file is specified and no argument source is explicitly + specified (either directly or by means of ``-files`` option), process + the closure of units rooted at `main_unit`. Otherwise this option + has no effect. + + + .. index:: -X (gnatpp) + + :samp:`-X{name}={value}` + Indicates that external variable `name` in the argument project + has the value `value`. Has no effect if no project is specified as + tool argument. + + + .. index:: --RTS (gnatpp) + + :samp:`--RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + + .. index:: --incremental (gnatpp) + + :samp:`--incremental` + Incremental processing on a per-file basis. Source files are only + processed if they have been modified, or if files they depend on have + been modified. This is similar to the way gnatmake/gprbuild only + compiles files that need to be recompiled. A project file is required + in this mode, and the gnat driver (as in *gnat pretty*) is not + supported. + + + .. index:: --pp-off (gnatpp) + + :samp:`--pp-off={xxx}` + Use `--xxx` as the command to turn off pretty printing, instead + of the default `--!pp off`. + + + .. index:: --pp-on (gnatpp) + + :samp:`--pp-on={xxx}` + Use `--xxx` as the command to turn pretty printing back on, instead + of the default `--!pp on`. + + + .. index:: --pp-old (gnatpp) + + :samp:`--pp-old` + Use the old formatting algorithms. + + + .. index:: -files (gnatpp) + + :samp:`-files {filename}` + Take the argument source files from the specified file. This file should be an + ordinary text file containing file names separated by spaces or + line breaks. You can use this switch more than once in the same call to + *gnatpp*. You also can combine this switch with an explicit list of + files. + + + .. index:: -j (gnatpp) + + :samp:`-j{n}` + Without ``--incremental``, use `n` processes to carry out the + tree creations (internal representations of the argument sources). On + a multiprocessor machine this speeds up processing of big sets of + argument sources. If `n` is 0, then the maximum number of parallel + tree creations is the number of core processors on the platform. This + option cannot be used together with ``-r``, + ``-rf`` or + ``-rnb`` option. + + With ``--incremental``, use `n` *gnatpp* processes to + perform pretty-printing in parallel. `n` = 0 means the same as + above. In this case, ``-r``, + ``-rf`` or + ``-rnb`` options are allowed. + + .. index:: -t (gnatpp) + + + :samp:`-t` + Print out execution time. + + + .. index:: -v (gnatpp) + + :samp:`-v` + Verbose mode + + + .. index:: -q (gnatpp) + + :samp:`-q` + Quiet mode + + If a project file is specified and no argument source is explicitly + specified (either directly or by means of ``-files`` option), and no + ``-U`` is specified, then the set of processed sources is + all the immediate units of the argument project. + + + .. _Formatting_Rules: + + Formatting Rules + ---------------- + + The following subsections show how *gnatpp* treats white space, + comments, program layout, and name casing. + They provide detailed descriptions of the switches shown above. + + + .. _Disabling_Pretty_Printing: + + Disabling Pretty Printing + ^^^^^^^^^^^^^^^^^^^^^^^^^ + + Pretty printing is highly heuristic in nature, and sometimes doesn't + do exactly what you want. If you wish to format a certain region of + code by hand, you can turn off pretty printing in that region by + surrounding it with special comments that start with ``--!pp off`` + and ``--!pp on``. The text in that region will then be reproduced + verbatim in the output with no formatting. + + To disable pretty printing for the whole file, put ``--!pp off`` at + the top, with no following ``--!pp on``. + + The comments must appear on a line by themselves, with nothing + preceding except spaces. The initial text of the comment must be + exactly ``--!pp off`` or ``--!pp on`` (case sensitive), but may + be followed by arbitrary additional text. For example: + + .. code-block:: ada + + package Interrupts is + --!pp off -- turn off pretty printing so "Interrupt_Kind" lines up + type Interrupt_Kind is + (Asynchronous_Interrupt_Kind, + Synchronous_Interrupt_Kind, + Green_Interrupt_Kind); + --!pp on -- reenable pretty printing + ... + + You can specify different comment strings using the ``--pp-off`` + and ``--pp-on`` switches. For example, if you say: + + :: + + $ gnatpp --pp-off=' pp-' *.ad? + + then gnatpp will recognize comments of the form + ``-- pp-`` instead of ``--!pp off`` for disabling pretty + printing. Note that the leading ``--`` of the comment is not + included in the argument to these switches. + + + .. _White_Space_and_Empty_Lines: + + White Space and Empty Lines + ^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + *gnatpp* does not have an option to control space characters. + It will add or remove spaces according to the style illustrated by the + examples in the :title:`Ada Reference Manual`. + The output file will contain no lines with trailing white space. + + By default, a sequence of one or more blank lines in the input is + converted to a single blank line in the output; multiple blank lines + are squeezed down to one. + The ``--preserve-blank-lines`` option + turns off the squeezing; each blank line in the input is copied + to the output. + The ``--insert-blank-lines`` option + causes additional blank lines to be inserted if not already + present in the input (e.g. between bodies). + + + .. _Formatting_Comments: + + Formatting Comments + ^^^^^^^^^^^^^^^^^^^ + + Comments in Ada code are of two kinds: + + * a *whole-line comment*, which appears by itself (possibly preceded by + white space) on a line + + * an *end-of-line comment*, which follows some other Ada code on + the same line. + + A whole-line comment is indented according to the surrounding code, + with some exceptions. + Comments that start in column 1 are kept there. + If possible, comments are not moved so far to the right that the maximum + line length is exceeded. + The ``-c0`` option + turns off comment formatting. + Special-form comments such as SPARK-style ``--#...`` are left alone. + + For an end-of-line comment, *gnatpp* tries to leave the same + number of spaces between the end of the preceding Ada code and the + beginning of the comment as appear in the original source. + + The ``-c3`` switch + (GNAT style comment beginning) has the following + effect: + + * For each whole-line comment that does not end with two hyphens, + *gnatpp* inserts spaces if necessary after the starting two hyphens + to ensure that there are at least two spaces between these hyphens and the + first non-blank character of the comment. + + The ``-c4`` switch specifies that + whole-line comments that form a paragraph will be filled in typical + word processor style (that is, moving words between lines to make the + lines other than the last similar in length ). + + The ``--comments-only`` switch specifies that only the comments + are formatted; the rest of the program text is left alone. The + comments are formatted according to the -c3 and -c4 switches; other + formatting switches are ignored. For example, + ``--comments-only -c4`` means to fill comment paragraphs, and do nothing else. + Likewise, + ``--comments-only -c3`` ensures comments start with at least two + spaces after `--`, and ``--comments-only -c3 -c4`` does + both. If ``--comments-only`` is given without ``-c3`` or + ``-c4``, then gnatpp doesn't format anything. + + + .. _Name_Casing: + + Name Casing + ^^^^^^^^^^^ + + *gnatpp* always converts the usage occurrence of a (simple) name to + the same casing as the corresponding defining identifier. + + You control the casing for defining occurrences via the + ``-n`` switch. + With ``-nD`` ('as declared', which is the default), + defining occurrences appear exactly as in the source file + where they are declared. + The other values for this switch -- + ``-nU``, + ``-nL``, + ``-nM`` -- + result in + upper, lower, or mixed case, respectively. + If *gnatpp* changes the casing of a defining + occurrence, it analogously changes the casing of all the + usage occurrences of this name. + + If the defining occurrence of a name is not in the source compilation unit + currently being processed by *gnatpp*, the casing of each reference to + this name is changed according to the value of the ``-n`` + switch (subject to the dictionary file mechanism described below). + Thus *gnatpp* acts as though the ``-n`` switch + had affected the + casing for the defining occurrence of the name. + + The options + :samp:`-a{x}`, + :samp:`-k{x}`, + :samp:`-ne{x}`, + :samp:`-nt{x}`, + :samp:`-nn{x}`, and + :samp:`-p{x}` + allow finer-grained control over casing for + attributes, keywords, enumeration literals, + types, named numbers and pragmas, respectively. + :samp:`-nt{x}` covers subtypes and + task and protected bodies as well. + + Some names may need to be spelled with casing conventions that are not + covered by the upper-, lower-, and mixed-case transformations. + You can arrange correct casing by placing such names in a + *dictionary file*, + and then supplying a ``-D`` switch. + The casing of names from dictionary files overrides + any ``-n`` switch. + + To handle the casing of Ada predefined names and the names from GNAT libraries, + *gnatpp* assumes a default dictionary file. + The name of each predefined entity is spelled with the same casing as is used + for the entity in the :title:`Ada Reference Manual` (usually mixed case). + The name of each entity in the GNAT libraries is spelled with the same casing + as is used in the declaration of that entity. + + The ``-D-`` switch suppresses the use of + the default dictionary file. Instead, the casing for predefined and + GNAT-defined names will be established by the + ``-n`` switch or explicit dictionary files. For + example, by default the names `Ada.Text_IO` and + `GNAT.OS_Lib` will appear as just shown, even in the presence of + a ``-nU`` switch. To ensure that even + such names are rendered in uppercase, additionally supply the + -D- switch (or else place these names + in upper case in a dictionary file). + + A dictionary file is a plain text file; each line in this file can be + either a blank line (containing only space characters), an Ada comment + line, or the specification of exactly one *casing schema*. + + A casing schema is a string that has the following syntax: + + :: + + `casing_schema` ::= `identifier` | `simple_identifier` + + `simple_identifier` ::= `letter`{`letter_or_digit`} + + + (See :title:`Ada Reference Manual`, Section 2.3) for the definition of the + `identifier` lexical element and the `letter_or_digit` category.) + + The casing schema string can be followed by white space and/or an Ada-style + comment; any amount of white space is allowed before the string. + + If a dictionary file is passed as + the value of a :samp:`-D{file}` switch + then for every + simple name and every identifier, *gnatpp* checks if the dictionary + defines the casing for the name or for some of its parts (the term 'subword' + is used below to denote the part of a name which is delimited by '_' or by + the beginning or end of the word and which does not contain any '_' inside): + + * if the whole name is in the dictionary, *gnatpp* uses for this name + the casing defined by the dictionary; no subwords are checked for this word + + * for every subword *gnatpp* checks if the dictionary contains the + corresponding string of the form `*`simple_identifier`*`, + and if it does, the casing of this `simple_identifier` is used + for this subword + + * if the whole name does not contain any '_' inside, and if for this name + the dictionary contains two entries - one of the form `identifier`, + and another - of the form *`simple_identifier`*, then the first one + is applied to define the casing of this name + + * if more than one dictionary file is passed as *gnatpp* switches, each + dictionary adds new casing exceptions and overrides all the existing casing + exceptions set by the previous dictionaries + + * when *gnatpp* checks if the word or subword is in the dictionary, + this check is not case sensitive + + For example, suppose we have the following source to reformat: + + .. code-block:: ada + + procedure test is + name1 : integer := 1; + name4_name3_name2 : integer := 2; + name2_name3_name4 : Boolean; + name1_var : Float; + begin + name2_name3_name4 := name4_name3_name2 > name1; + end; + + And suppose we have two dictionaries: + + :: + + *dict1:* + NAME1 + *NaMe3* + *Name1* + + *dict2:* + *NAME3* + + If *gnatpp* is called with the following switches: + + :: + + $ gnatpp -nM -D dict1 -D dict2 test.adb + + then we will get the following name casing in the *gnatpp* output: + + + .. code-block:: ada + + procedure Test is + NAME1 : Integer := 1; + Name4_NAME3_Name2 : Integer := 2; + Name2_NAME3_Name4 : Boolean; + Name1_Var : Float; + begin + Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1; + end Test; + + +.. only:: PRO or GPL + + .. _The_Body_Stub_Generator_gnatstub: + + The Body Stub Generator *gnatstub* + ================================== + + .. index:: ! gnatstub + + *gnatstub* creates empty but compilable bodies + for library unit declarations, and empty but compilable + subunit for body stubs. + + To create a body or a subunit, *gnatstub* invokes the Ada + compiler and generates and uses the ASIS tree for the input source; + thus the input must be legal Ada code, and the tool should have all the + information needed to compile the input source. To provide this information, + you may specify as a tool parameter the project file the input source belongs to + (or you may call *gnatstub* + through the *gnat* driver (see :ref:`The_GNAT_Driver_and_Project_Files`). + Another possibility is to specify the source search + path and needed configuration files in ``-cargs`` section of *gnatstub* + call, see the description of the *gnatstub* switches below. + + If the *gnatstub* argument source contains preprocessing directives + then the needed options should be provided to run preprocessor as a part of + the *gnatstub* call, and the generated body stub will correspond to + the preprocessed source. + + By default, all the program unit bodies generated by `gnatstub` + raise the predefined `Program_Error` exception, which will catch + accidental calls of generated stubs. This behavior can be changed with + option ``--no-exception`` (see below). + + .. _Running_gnatstub: + + Running *gnatstub* + ------------------ + + *gnatstub* invocation has the following form: + + :: + + $ gnatstub [`switches`] `filename` [-cargs `gcc_switches`] + + where + + * *filename* + is the name of the source file that contains a library unit declaration + for which a body must be created or a library unit body for which subunits + must be created for the body stubs declared in this body. + The file name may contain the path information. + If the name does not follow GNAT file naming conventions and a set + of seitches does not contain a project file that defines naming + conventions, the name of the body file must + be provided + explicitly as the value of the :samp:`-o{body-name}` option. + If the file name follows the GNAT file naming + conventions and the name of the body file is not provided, + *gnatstub* + takes the naming conventions for the generated source from the + project file provided as a parameter of ``-P`` switch if any, + or creates the name file to generate using the standard GNAT + naming conventions. + + * *gcc_switches* is a list of switches for *gcc*. + They will be passed on to all compiler invocations made by + *gnatstub* to generate the ASIS trees. Here you can provide + ``-I`` switches to form the source search path, + use the ``-gnatec`` switch to set the configuration file, + use the ``-gnat05`` switch if sources should be compiled in + Ada 2005 mode etc. + + * *switches* + is an optional sequence of switches as described in the next section + + + .. _Switches_for_gnatstub: + + Switches for *gnatstub* + ----------------------- + + .. index:: --version (gnatstub) + + :samp:`--version` + Display Copyright and version, then exit disregarding all other options. + + + .. index:: --help (gnatstub) + + :samp:`--help` + Display usage, then exit disregarding all other options. + + + .. index:: -P (gnatstub) + + :samp:`-P {file}` + Indicates the name of the project file that describes the set of sources + to be processed. + + + .. index:: -X (gnatstub) + + :samp:`-X{name}={value}` + Indicates that external variable `name` in the argument project + has the value `value`. Has no effect if no project is specified as + tool argument. + + + .. index:: --RTS (gnatstub) + + :samp:`--RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + + .. index:: --subunits (gnatstub) + + :samp:`--subunits` + Generate subunits for body stubs. If this switch is specified, + *gnatstub* expects a library unit body as an agrument file, + otherwise a library unit declaration is expected. If a body stub + already has a corresponding subunit, *gnatstub* does not + generate anything for it. + + + .. index:: -f (gnatstub) + + :samp:`-f` + If the destination directory already contains a file with the name of the + body file + for the argument spec file, replace it with the generated body stub. + This switch cannot be used together with ``--subunits``. + + + .. index:: -hs (gnatstub) + + :samp:`-hs` + Put the comment header (i.e., all the comments preceding the + compilation unit) from the source of the library unit declaration + into the body stub. + + + .. index:: -hg (gnatstub) + + :samp:`-hg` + Put a sample comment header into the body stub. + + + .. index:: --header-file (gnatstub) + + :samp:`--header-file={filename}` + Use the content of the file as the comment header for a generated body stub. + + + .. index:: -IDIR (gnatstub) + .. index:: -I- (gnatstub) + + :samp:`-I{DIR}`, :samp:`-I-` + These switches have the same meaning as in calls to + *gcc*. + They define the source search path in the call to + *gcc* issued + by *gnatstub* to compile an argument source file. + + + .. index:: -gnatec (gnatstub) + + :samp:`-gnatec{PATH}` + This switch has the same meaning as in calls to *gcc*. + It defines the additional configuration file to be passed to the call to + *gcc* issued + by *gnatstub* to compile an argument source file. + + + .. index:: -gnatyM (gnatstub) + + :samp:`-gnatyM{n}` + (`n` is a non-negative integer). Set the maximum line length that is + allowed in a source file. The default is 79. The maximum value that can be + specified is 32767. Note that in the special case of configuration + pragma files, the maximum is always 32767 regardless of whether or + not this switch appears. + + + .. index:: -gnaty (gnatstub) + + :samp:`-gnaty{n}` + (`n` is a non-negative integer from 1 to 9). Set the indentation level in + the generated body sample to `n`. + The default indentation is 3. + + + .. index:: -gnatyo (gnatstub) + + :samp:`-gnatyo` + Order local bodies alphabetically. (By default local bodies are ordered + in the same way as the corresponding local specs in the argument spec file.) + + + .. index:: -i (gnatstub) + + :samp:`-i{n}` + Same as :samp:`-gnaty{n}`` + + + .. index:: -k (gnatstub) + + :samp:`-k` + Do not remove the tree file (i.e., the snapshot of the compiler internal + structures used by *gnatstub*) after creating the body stub. + + + .. index:: -l (gnatstub) + + :samp:`-l{n}` + Same as ``-gnatyM`n``` + + + .. index:: --no-exception (gnatstub) + + :samp:`--no-exception` + Avoid raising PROGRAM_ERROR in the generated bodies of program unit stubs. + This is not always possible for function stubs. + + + .. index:: --no-local-header (gnatstub) + + :samp:`--no-local-header` + Do not place local comment header with unit name before body stub for a + unit. + + + .. index:: -o (gnatstub) + + :samp:`-o {body-name}` + Body file name. This should be set if the argument file name does not + follow + the GNAT file naming + conventions. If this switch is omitted the default name for the body will be + obtained + from the argument file name according to the GNAT file naming conventions. + + + .. index:: --dir (gnatstub) + + :samp:`--dir={dir-name}` + The path to the directory to place the generated files into. + If this switch is not set, the generated library unit body is + placed in the current directory, and generated sununits - + in the directory where the argument body is located. + + + .. index:: -W (gnatstub) + + :samp:`-W{e}` + Specify the wide character encoding method for the output body file. + `e` is one of the following: + + ==== ================================== + *h* Hex encoding + *u* Upper half encoding + *s* Shift/JIS encoding + *e* EUC encoding + *8* UTF-8 encoding + *b* Brackets encoding (default value) + ==== ================================== + + + .. index:: -q (gnatstub) + + :samp:`-q` + Quiet mode: do not generate a confirmation when a body is + successfully created, and do not generate a message when a body is not + required for an + argument unit. + + + .. index:: -r (gnatstub) + + :samp:`-r` + Reuse the tree file (if it exists) instead of creating it. Instead of + creating the tree file for the library unit declaration, *gnatstub* + tries to find it in the current directory and use it for creating + a body. If the tree file is not found, no body is created. This option + also implies ``-k``, whether or not + the latter is set explicitly. + + + .. index:: -t (gnatstub) + + :samp:`-t` + Overwrite the existing tree file. If the current directory already + contains the file which, according to the GNAT file naming rules should + be considered as a tree file for the argument source file, + *gnatstub* + will refuse to create the tree file needed to create a sample body + unless this option is set. + + + .. index:: -v (gnatstub) + + :samp:`-v` + Verbose mode: generate version information. + + + +.. only:: PRO or GPL + + .. _The_Unit_Test_Generator_gnattest: + + The Unit Test Generator *gnattest* + ================================== + + .. index:: ! gnattest + + *gnattest* is an ASIS-based utility that creates unit-test skeletons + as well as a test driver infrastructure (harness). *gnattest* creates + a skeleton for each visible subprogram in the packages under consideration when + they do not exist already. + + The user can choose to generate a single test driver + that will run all individual tests, or separate test drivers for each test. The + second option allows much greater flexibility in test execution environment, + allows to benefit from parallel tests execution to increase performance, and + provides stubbing support. + + *gnattest* also has a mode of operation where it acts as the test + aggregator when multiple test executables must be run, in particular when + the separate test drivers were generated. In this mode it handles individual + tests execution and upon completion reports the summary results of the test + run. + + In order to process source files from a project, *gnattest* has to + semantically analyze the sources. Therefore, test skeletons can only be + generated for legal Ada units. If a unit is dependent on other units, + those units should be among the source files of the project or of other projects + imported by this one. + + Generated skeletons and harnesses are based on the AUnit testing framework. + AUnit is an Ada adaptation of the xxxUnit testing frameworks, similar to JUnit + for Java or CppUnit for C++. While it is advised that gnattest users read + the AUnit manual, deep knowledge of AUnit is not necessary for using gnattest. + For correct operation of *gnattest*, AUnit should be installed and + aunit.gpr must be on the project path. This happens automatically when Aunit + is installed at its default location. + + + .. _Running_gnattest: + + Running *gnattest* + ------------------ + + There are two ways of running *gnattest*. + + .. _Framework_Generation_Mode: + + Framework Generation Mode + ^^^^^^^^^^^^^^^^^^^^^^^^^ + + In this mode *gnattest* has the following command-line interface: + + :: + + $ gnattest `-Pprojname` [`--harness-dir=dirname`] [`switches`] [`filename`] [-cargs `gcc_switches`] + + where + + * :samp:`-P{projname}` + specifies the project defining the location of source files. When no + file names are provided on the command line, all sources in the project + are used as input. This switch is required. + + * :samp:`{filename}` + is the name of the source file containing the library unit package declaration + for which a test package will be created. The file name may be given with a + path. + + * :samp:`{gcc_switches}` + is a list of switches for + *gcc*. These switches will be passed on to all compiler invocations + made by *gnattest* to generate a set of ASIS trees. Here you can provide + ``-I`` switches to form the source search path, + use the ``-gnatec`` switch to set the configuration file, + use the ``-gnat05`` switch if sources should be compiled in + Ada 2005 mode, etc. + + + * :samp:`{switches}` + is an optional sequence of switches as described below. + + + *gnattest* results can be found in two different places. + + * *automatic harness*: + This is the harness code, which is located by default in "gnattest/harness" directory + that is created in the object directory of corresponding project file. All of + this code is generated completely automatically and can be destroyed and + regenerated at will. It is not recommended to modify this code manually, since + it could easily be overridden by mistake. The entry point in the harness code is + the project file named *test_driver.gpr*. Tests can be compiled and run + using a command such as: + + :: + + $ gnatmake -P<harness-dir>/test_driver test_runner + + Note that you might need to specify the necessary values of scenario variables + when you are not using the AUnit defaults. + + * *actual unit test skeletons*: + A test skeleton for each visible subprogram is created in a separate file, if it + doesn't exist already. By default, those separate test files are located in a + "gnattest/tests" directory that is created in the object directory of + corresponding project file. For example, if a source file my_unit.ads in + directory src contains a visible subprogram Proc, then the corresponding unit + test will be found in file src/tests/my_unit-test_data-tests.adb and will be + called Test_Proc_<code>. <code> is a signature encoding used to differentiate + test names in case of overloading. + + Note that if the project already has both my_unit.ads and my_unit-test_data.ads, + this will cause a name conflict with the generated test package. + + + .. _Test_Execution_Mode: + + Test Execution Mode + ^^^^^^^^^^^^^^^^^^^ + + In this mode *gnattest* has a the following command-line interface: + + :: + + $ gnattest `test_drivers.list` [`switches`] + + where + + * :samp:`{test_drivers.list}` + is the name of the text file containing the list of executables to treat as + test drivers. This file is automatically generated by gnattest, but can be + hand-edited to add or remove tests. This switch is required. + + + * :samp:`{switches}` + is an optional sequence of switches as described below. + + + .. _Switches_for_gnattest_in_framework_generation_mode: + + Switches for *gnattest* in framework generation mode + ---------------------------------------------------- + + .. index:: -q (gnattest) + + :samp:`-q` + Quiet mode: suppresses noncritical output messages. + + + .. index:: -v (gnattest) + + :samp:`-v` + Verbose mode: generates version information if specified by itself on the + command line. If specified via GNATtest_Switches, produces output + about the execution of the tool. + + + .. index:: -r (gnattest) + + :samp:`-r` + Recursively considers all sources from all projects. + + + .. index:: -X (gnattest) + + :samp:`-X{name}={value}` + Indicate that external variable `name` has the value `value`. + + + .. index:: --RTS (gnattest) + + :samp:`--RTS={rts-path}` + Specifies the default location of the runtime library. Same meaning as the + equivalent *gnatmake* flag (:ref:`Switches_for_gnatmake`). + + + .. index:: --additional-tests (gnattest) + + :samp:`--additional-tests={projname}` + Sources described in `projname` are considered potential additional + manual tests to be added to the test suite. + + + .. index:: --harness-only (gnattest) + + :samp:`--harness-only` + When this option is given, *gnattest* creates a harness for all + sources, treating them as test packages. + + + .. index:: --separate-drivers (gnattest) + + :samp:`--separate-drivers` + Generates a separate test driver for each test, rather than a single + executable incorporating all tests. + + + .. index:: --stub (gnattest) + + :samp:`--stub` + Generates the testing framework that uses subsystem stubbing to isolate the + code under test. + + + .. index:: --harness-dir (gnattest) + + :samp:`--harness-dir={dirname}` + Specifies the directory that will hold the harness packages and project file + for the test driver. If the `dirname` is a relative path, it is considered + relative to the object directory of the project file. + + + .. index:: --tests-dir (gnattest) + + :samp:`--tests-dir={dirname}` + All test packages are placed in the `dirname` directory. + If the `dirname` is a relative path, it is considered relative to the object + directory of the project file. When all sources from all projects are taken + recursively from all projects, `dirname` directories are created for each + project in their object directories and test packages are placed accordingly. + + + .. index:: --subdir (gnattest) + + :samp:`--subdir={dirname}` + Test packages are placed in a subdirectory of the corresponding source + directory, with the name `dirname`. Thus, each set of unit tests is located + in a subdirectory of the code under test. If the sources are in separate + directories, each source directory has a test subdirectory named `dirname`. + + + .. index:: --tests-root (gnattest) + + :samp:`--tests-root={dirname}` + The hierarchy of source directories, if any, is recreated in the `dirname` + directory, with test packages placed in directories corresponding to those + of the sources. + If the `dirname` is a relative path, it is considered relative to the object + directory of the project file. When projects are considered recursively, + directory hierarchies of tested sources are + recreated for each project in their object directories and test packages are + placed accordingly. + + + .. index:: --stubs-dir (gnattest) + + :samp:`--stubs-dir={dirname}` + The hierarchy of directories containing stubbed units is recreated in + the `dirname` directory, with stubs placed in directories corresponding to + projects they are derived from. + If the `dirname` is a relative path, it is considered relative to the object + directory of the project file. When projects are considered recursively, + directory hierarchies of stubs are + recreated for each project in their object directories and test packages are + placed accordingly. + + + .. index:: --validate-type-extensions (gnattest) + + :samp:`--validate-type-extensions` + Enables substitution check: run all tests from all parents in order + to check substitutability in accordance with LSP. + + + .. index:: --skeleton-default (gnattest) + + :samp:`--skeleton-default={val}` + Specifies the default behavior of generated skeletons. `val` can be either + "fail" or "pass", "fail" being the default. + + + .. index:: --passed-tests (gnattest) + + :samp:`--passed-tests={val}` + Specifies whether or not passed tests should be shown. `val` can be either + "show" or "hide", "show" being the default. + + + .. index:: --exit-status (gnattest) + + :samp:`--exit-status={val}` + Specifies whether or not generated test driver should return failure exit + status if at least one test fails or crashes. `val` can be either + "on" or "off", "off" being the default. + + + .. index:: --omit-sloc (gnattest) + + :samp:`--omit-sloc` + Suppresses comment line containing file name and line number of corresponding + subprograms in test skeletons. + + + .. index:: --no-command-line (gnattest) + + :samp:`--no-command-line` + Don't add command line support to test driver. Note that regardless of this + switch, *gnattest* will automatically refrain from adding command + line support if it detects that the selected run-time doesn't provide + this capability. + + + .. index:: --separates (gnattest) + + :samp:`--separates` + Bodies of all test routines are generated as separates. Note that this mode is + kept for compatibility reasons only and it is not advised to use it due to + possible problems with hash in names of test skeletons when using an + inconsistent casing. Separate test skeletons can be incorporated to monolith + test package with improved hash being used by using ``--transition`` + switch. + + + .. index:: --transition (gnattest) + + :samp:`--transition` + This allows transition from separate test routines to monolith test packages. + All matching test routines are overwritten with contents of corresponding + separates. Note that if separate test routines had any manually added with + clauses they will be moved to the test package body as is and have to be moved + by hand. + + + .. index:: --test-duration (gnattest) + + :samp:`--test-duration` + Adds time measurements for each test in generated test driver. + + + :samp:`--tests_root`, ``--subdir`` and ``--tests-dir`` switches are mutually exclusive. + + + .. _Switches_for_gnattest_in_test_execution_mode: + + Switches for *gnattest* in test execution mode + ---------------------------------------------- + + + .. index:: --passed-tests (gnattest) + + :samp:`--passed-tests={val}` + Specifies whether or not passed tests should be shown. `val` can be either + "show" or "hide", "show" being the default. + + + .. index:: --queues (gnattest) + .. index:: -j (gnattest) + + :samp:`--queues={n}`, :samp:`-j{n}` + Runs `n` tests in parallel (default is 1). + + + .. _Project_Attributes_for_gnattest: + + Project Attributes for *gnattest* + --------------------------------- + + Most of the command-line options can also be passed to the tool by adding + special attributes to the project file. Those attributes should be put in + package gnattest. Here is the list of attributes: + + + * ``Tests_Root`` + is used to select the same output mode as with the ``--tests-root`` option. + This attribute cannot be used together with Subdir or Tests_Dir. + + * ``Subdir`` + is used to select the same output mode as with the ``--subdir`` option. + This attribute cannot be used together with ``Tests_Root`` or ``Tests_Dir``. + + * ``Tests_Dir`` + is used to select the same output mode as with the ``--tests-dir`` option. + This attribute cannot be used together with ``Subdir`` or ``Tests_Root``. + + * ``Harness_Dir`` + is used to specify the directory in which to place harness packages and project + file for the test driver, otherwise specified by ``--harness-dir``. + + * ``Additional_Tests`` + is used to specify the project file, otherwise given by + ``--additional-tests`` switch. + + * ``Skeletons_Default`` + is used to specify the default behaviour of test skeletons, otherwise + specified by ``--skeleton-default`` option. The value of this attribute + should be either ``pass`` or ``fail``. + + Each of those attributes can be overridden from the command line if needed. + Other *gnattest* switches can also be passed via the project + file as an attribute list called GNATtest_Switches. + + + .. _Simple_gnattest_Example: + + Simple Example + -------------- + + Let's take a very simple example using the first *gnattest* example + located in: + + :: + + <install_prefix>/share/examples/gnattest/simple + + This project contains a simple package containing one subprogram. By running gnattest: + + :: + + $ gnattest --harness-dir=driver -Psimple.gpr + + a test driver is created in directory ``driver``. It can be compiled and run: + + :: + + $ cd obj/driver + $ gnatmake -Ptest_driver + $ test_runner + + One failed test with diagnosis ``test not implemented`` is reported. + Since no special output option was specified, the test package ``Simple.Tests`` + is located in: + + :: + + <install_prefix>/share/examples/gnattest/simple/obj/gnattest/tests + + + For each package containing visible subprograms, a child test package is + generated. It contains one test routine per tested subprogram. Each + declaration of a test subprogram has a comment specifying which tested + subprogram it corresponds to. Bodies of test routines are placed in test package + bodies and are surrounded by special comment sections. Those comment sections + should not be removed or modified in order for gnattest to be able to regenerate + test packages and keep already written tests in place. + The test routine Test_Inc_5eaee3 located at simple-test_data-tests.adb contains + a single statement: a call to procedure Assert. It has two arguments: + the Boolean expression we want to check and the diagnosis message to display if + the condition is false. + + That is where actual testing code should be written after a proper setup. + An actual check can be performed by replacing the Assert call with: + + :: + + Assert (Inc (1) = 2, "wrong incrementation"); + + After recompiling and running the test driver, one successfully passed test + is reported. + + + .. _Setting_Up_and_Tearing_Down_the_Testing_Environment: + + Setting Up and Tearing Down the Testing Environment + --------------------------------------------------- + + Besides test routines themselves, each test package has a parent package + Test_Data that has two procedures: Set_Up and Tear_Down. This package is never + overwritten by the tool. Set_Up is called before each test routine of the + package and Tear_Down is called after each test routine. Those two procedures + can be used to perform necessary initialization and finalization, + memory allocation, etc. Test type declared in Test_Data package is parent type + for the test type of test package and can have user-defined components whose + values can be set by Set_Up routine and used in test routines afterwards. + + + .. _Regenerating_Tests: + + Regenerating Tests + ------------------ + + Bodies of test routines and test_data packages are never overridden after they + have been created once. As long as the name of the subprogram, full expanded Ada + names, and the order of its parameters is the same, and comment sections are + intact the old test routine will fit in its place and no test skeleton will be + generated for the subprogram. + + This can be demonstrated with the previous example. By uncommenting declaration + and body of function Dec in simple.ads and simple.adb, running + *gnattest* on the project, and then running the test driver: + + :: + + $ gnattest --harness-dir=driver -Psimple.gpr + $ cd obj/driver + $ gnatmake -Ptest_driver + $ test_runner + + The old test is not replaced with a stub, nor is it lost, but a new test + skeleton is created for function Dec. + + The only way of regenerating tests skeletons is to remove the previously created + tests together with corresponding comment sections. + + + .. _Default_Test_Behavior: + + Default Test Behavior + --------------------- + + The generated test driver can treat unimplemented tests in two ways: + either count them all as failed (this is useful to see which tests are still + left to implement) or as passed (to sort out unimplemented ones from those + actually failing). + + The test driver accepts a switch to specify this behavior: + :samp:`--skeleton-default={val}`, where ``val`` is either ``pass`` or ``fail`` (exactly as for + *gnattest*). + + The default behavior of the test driver is set with the same switch + as passed to gnattest when generating the test driver. + + Passing it to the driver generated on the first example: + + :: + + $ test_runner --skeleton-default=pass + + makes both tests pass, even the unimplemented one. + + + .. _Testing_Primitive_Operations_of_Tagged_Types: + + Testing Primitive Operations of Tagged Types + -------------------------------------------- + + Creation of test skeletons for primitive operations of tagged types entails + a number of features. Test routines for all primitives of a given tagged type + are placed in a separate child package named according to the tagged type. For + example, if you have tagged type T in package P, all tests for primitives + of T will be in P.T_Test_Data.T_Tests. + + Consider running gnattest on the second example (note: actual tests for this + example already exist, so there's no need to worry if the tool reports that + no new stubs were generated): + + :: + + $ cd <install_prefix>/share/examples/gnattest/tagged_rec + $ gnattest --harness-dir=driver -Ptagged_rec.gpr + + Taking a closer look at the test type declared in the test package + Speed1.Controller_Test_Data is necessary. It is declared in: + + :: + + <install_prefix>/share/examples/gnattest/tagged_rec/obj/gnattest/tests + + Test types are direct or indirect descendants of + AUnit.Test_Fixtures.Test_Fixture type. In the case of nonprimitive tested + subprograms, the user doesn't need to be concerned with them. However, + when generating test packages for primitive operations, there are some things + the user needs to know. + + Type Test_Controller has components that allow assignment of various + derivations of type Controller. And if you look at the specification of + package Speed2.Auto_Controller, you will see that Test_Auto_Controller + actually derives from Test_Controller rather than AUnit type Test_Fixture. + Thus, test types mirror the hierarchy of tested types. + + The Set_Up procedure of Test_Data package corresponding to a test package + of primitive operations of type T assigns to Fixture a reference to an + object of that exact type T. Notice, however, that if the tagged type has + discriminants, the Set_Up only has a commented template for setting + up the fixture, since filling the discriminant with actual value is up + to the user. + + The knowledge of the structure of test types allows additional testing + without additional effort. Those possibilities are described below. + + + .. _Testing_Inheritance: + + Testing Inheritance + ------------------- + + Since the test type hierarchy mimics the hierarchy of tested types, the + inheritance of tests takes place. An example of such inheritance can be + seen by running the test driver generated for the second example. As previously + mentioned, actual tests are already written for this example. + + :: + + $ cd obj/driver + $ gnatmake -Ptest_driver + $ test_runner + + There are 6 passed tests while there are only 5 testable subprograms. The test + routine for function Speed has been inherited and run against objects of the + derived type. + + + .. _Tagged_Type_Substitutability_Testing: + + Tagged Type Substitutability Testing + ------------------------------------- + + *Tagged Type Substitutability Testing* is a way of verifying the global type + consistency by testing. Global type consistency is a principle stating that if + S is a subtype of T (in Ada, S is a derived type of tagged type T), + then objects of type T may be replaced with objects of type S (that is, + objects of type S may be substituted for objects of type T), without + altering any of the desirable properties of the program. When the properties + of the program are expressed in the form of subprogram preconditions and + postconditions (let's call them pre and post), the principle is formulated as + relations between the pre and post of primitive operations and the pre and post + of their derived operations. The pre of a derived operation should not be + stronger than the original pre, and the post of the derived operation should + not be weaker than the original post. Those relations ensure that verifying if + a dispatching call is safe can be done just by using the pre and post of the + root operation. + + Verifying global type consistency by testing consists of running all the unit + tests associated with the primitives of a given tagged type with objects of its + derived types. + + In the example used in the previous section, there was clearly a violation of + type consistency. The overriding primitive Adjust_Speed in package Speed2 + removes the functionality of the overridden primitive and thus doesn't respect + the consistency principle. + Gnattest has a special option to run overridden parent tests against objects + of the type which have overriding primitives: + + :: + + $ gnattest --harness-dir=driver --validate-type-extensions -Ptagged_rec.gpr + $ cd obj/driver + $ gnatmake -Ptest_driver + $ test_runner + + While all the tests pass by themselves, the parent test for Adjust_Speed fails + against objects of the derived type. + + Non-overridden tests are already inherited for derived test types, so the + ``--validate-type-extensions`` enables the application of overriden tests to objects + of derived types. + + + .. _Testing_with_Contracts: + + Testing with Contracts + ---------------------- + + *gnattest* supports pragmas Precondition, Postcondition, and Test_Case, + as well as the corresponding Ada 2012 aspects. + Test routines are generated, one per each Test_Case associated with a tested + subprogram. Those test routines have special wrappers for tested functions + that have composition of pre- and postcondition of the subprogram with + "requires" and "ensures" of the Test_Case (depending on the mode, pre and post + either count for Nominal mode or do not count for Robustness mode). + + The third example demonstrates how this works: + + :: + + $ cd <install_prefix>/share/examples/gnattest/contracts + $ gnattest --harness-dir=driver -Pcontracts.gpr + + Putting actual checks within the range of the contract does not cause any + error reports. For example, for the test routine which corresponds to + test case 1: + + :: + + Assert (Sqrt (9.0) = 3.0, "wrong sqrt"); + + and for the test routine corresponding to test case 2: + + :: + + Assert (Sqrt (-5.0) = -1.0, "wrong error indication"); + + are acceptable: + + :: + + $ cd obj/driver + $ gnatmake -Ptest_driver + $ test_runner + + However, by changing 9.0 to 25.0 and 3.0 to 5.0, for example, you can get + a precondition violation for test case one. Also, by using any otherwise + correct but positive pair of numbers in the second test routine, you can also + get a precondition violation. Postconditions are checked and reported + the same way. + + + .. _Additional_Tests: + + Additional Tests + ---------------- + + *gnattest* can add user-written tests to the main suite of the test + driver. *gnattest* traverses the given packages and searches for test + routines. All procedures with a single in out parameter of a type which is + derived from AUnit.Test_Fixtures.Test_Fixture and that are declared in package + specifications are added to the suites and are then executed by the test driver. + (Set_Up and Tear_Down are filtered out.) + + An example illustrates two ways of creating test harnesses for user-written + tests. Directory additional_tests contains an AUnit-based test driver written + by hand. + + :: + + <install_prefix>/share/examples/gnattest/additional_tests/ + + To create a test driver for already-written tests, use the ``--harness-only`` + option: + + :: + + gnattest -Padditional/harness/harness.gpr --harness-dir=harness_only \\ + --harness-only + gnatmake -Pharness_only/test_driver.gpr + harness_only/test_runner + + Additional tests can also be executed together with generated tests: + + :: + + gnattest -Psimple.gpr --additional-tests=additional/harness/harness.gpr \\ + --harness-dir=mixing + gnatmake -Pmixing/test_driver.gpr + mixing/test_runner + + + .. _Individual_Test_Drivers: + + Individual Test Drivers + ----------------------- + + By default, *gnattest* generates a monolithic test driver that + aggregates the individual tests into a single executable. It is also possible + to generate separate executables for each test, by passing the switch + ``--separate-drivers``. This approach scales better for large testing + campaigns, especially involving target architectures with limited resources + typical for embedded development. It can also provide a major performance + benefit on multi-core systems by allowing simultaneous execution of multiple + tests. + + *gnattest* can take charge of executing the individual tests; for this, + instead of passing a project file, a text file containing the list of + executables can be passed. Such a file is automatically generated by gnattest + under the name :file:`test_drivers.list`, but it can be + hand-edited to add or remove tests, or replaced. The individual tests can + also be executed standalone, or from any user-defined scripted framework. + + + .. _Stubbing: + + Stubbing + -------- + + Depending on the testing campaign, it is sometimes necessary to isolate the + part of the algorithm under test from its dependencies. This is accomplished + via *stubbing*, i.e. replacing the subprograms that are called from the + subprogram under test by stand-in subprograms that match the profiles of the + original ones, but simply return predetermined values required by the test + scenario. + + This mode of test harness generation is activated by the switch ``--stub``. + + The implementation approach chosen by *gnattest* is as follows. + For each package under consideration all the packages it is directly depending + on are stubbed, excluding the generic packages and package instantiations. + The stubs are shared for each package under test. The specs of packages to stub + remain intact, while their bodies are replaced, and hide the original bodies by + means of extending projects. Also, for each stubbed + package, a child package with setter routines for each subprogram declaration + is created. These setters are meant to be used to set the behaviour of + stubbed subprograms from within test cases. + + Note that subprograms belonging to the same package as the subprogram under + test are not stubbed. This guarantees that the sources being tested are + exactly the sources used for production, which is an important property for + establishing the traceability between the testing campaign and production code. + + Due to the nature of stubbing process, this mode implies the switch + ``--separate-drivers``, i.e. an individual test driver (with the + corresponding hierarchy of extending projects) is generated for each test. + + .. note:: + + Developing a stubs-based testing campaign requires + good understanding of the infrastructure created by *gnattest* for + this purpose. We recommend following the stubbing tutorials provided + under :file:`<install_prefix>/share/examples/gnattest/stubbing*` before + attempting to use this powerful feature. + + + .. _Putting_Tests_under_Version_Control: + + Putting Tests under Version Control + ----------------------------------- + + As has been stated earlier, *gnattest* generates two different types + of code, test skeletons and harness. The harness is generated completely + automatically each time, does not require manual changes and therefore should + not be put under version control. + It makes sense to put under version control files containing test data packages, + both specs and bodies, and files containing bodies of test packages. Note that + test package specs are also generated automatically each time and should not be + put under version control. + Option ``--omit-sloc`` may be useful when putting test packages under version control. + + + .. _Support_for_other_platforms/run-times: + + Support for other platforms/run-times + ------------------------------------- + + *gnattest* can be used to generate the test harness for platforms + and run-time libraries others than the default native target with the + default full run-time. For example, when using a limited run-time library + such as Zero FootPrint (ZFP), a simplified harness is generated. + + Two variables are used to tell the underlying AUnit framework how to generate + the test harness: `PLATFORM`, which identifies the target, and + `RUNTIME`, used to determine the run-time library for which the harness + is generated. Corresponding prefix should also be used when calling + *gnattest* for non-native targets. For example, the following options + are used to generate the AUnit test harness for a PowerPC ELF target using + the ZFP run-time library: + + :: + + $ powerpc-elf-gnattest -Psimple.gpr -XPLATFORM=powerpc-elf -XRUNTIME=zfp + + + .. _Current_Limitations: + + Current Limitations + ------------------- + + The tool currently does not support following features: + + * generic tests for nested generic packages and their instantiations + * tests for protected subprograms and entries + diff --git a/gcc/ada/doc/gnat_ugn/inline_assembler.rst b/gcc/ada/doc/gnat_ugn/inline_assembler.rst new file mode 100644 index 00000000000..d79b70b0814 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/inline_assembler.rst @@ -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. diff --git a/gcc/ada/doc/gnat_ugn/platform_specific_information.rst b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst new file mode 100644 index 00000000000..dc3dfec22c8 --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/platform_specific_information.rst @@ -0,0 +1,2191 @@ +.. -- Non-breaking space in running text + -- E.g. Ada |nbsp| 95 + +.. |nbsp| unicode:: 0xA0 + :trim: + +.. _Platform_Specific_Information: + +***************************** +Platform-Specific Information +***************************** + +This appendix contains information relating to the implementation +of run-time libraries on various platforms and also covers +topics related to the GNAT implementation on Windows and Mac OS. + +.. _`Run_Time_Libraries`: + +Run-Time Libraries +================== + +.. index:: Tasking and threads libraries +.. index:: Threads libraries and tasking +.. index:: Run-time libraries (platform-specific information) + +The GNAT run-time implementation may vary with respect to both the +underlying threads library and the exception handling scheme. +For threads support, one or more of the following are supplied: + +* **native threads library**, a binding to the thread package from + the underlying operating system + +* **pthreads library** (Sparc Solaris only), a binding to the Solaris + POSIX thread package + +For exception handling, either or both of two models are supplied: + + .. index:: Zero-Cost Exceptions + .. index:: ZCX (Zero-Cost Exceptions) + +* **Zero-Cost Exceptions** ("ZCX"), + which uses binder-generated tables that + are interrogated at run time to locate a handler. + + .. index:: setjmp/longjmp Exception Model + .. index:: SJLJ (setjmp/longjmp Exception Model) + +* **setjmp / longjmp** ('SJLJ'), + which uses dynamically-set data to establish + the set of handlers + +Most programs should experience a substantial speed improvement by +being compiled with a ZCX run-time. +This is especially true for +tasking applications or applications with many exception handlers.} + +This section summarizes which combinations of threads and exception support +are supplied on various GNAT platforms. +It then shows how to select a particular library either +permanently or temporarily, +explains the properties of (and tradeoffs among) the various threads +libraries, and provides some additional +information about several specific platforms. + +.. _Summary_of_Run-Time_Configurations: + +Summary of Run-Time Configurations +---------------------------------- + ++-----------------+--------------+-------------------------+------------+ +| Platform | Run-Time | Tasking | Exceptions | ++=================+==============+=========================+============+ +| ppc-aix | rts-native | native AIX threads | ZCX | +| | (default) | | | +| +--------------+-------------------------+------------+ +| | rts-sjlj | native AIX threads | SJLJ | ++-----------------+--------------+-------------------------+------------+ +| sparc-solaris | rts-native | native Solaris | ZCX | +| | (default) | threads library | | +| +--------------+-------------------------+------------+ +| | rts-pthread | pthread library | ZCX | +| +--------------+-------------------------+------------+ +| | rts-sjlj | native Solaris | SJLJ | +| | | threads library | | ++-----------------+--------------+-------------------------+------------+ +| sparc64-solaris | rts-native | native Solaris | ZCX | +| | (default) | threads library | | ++-----------------+--------------+-------------------------+------------+ +| x86-linux | rts-native | pthread library | ZCX | +| | (default) | | | +| +--------------+-------------------------+------------+ +| | rts-sjlj | pthread library | SJLJ | ++-----------------+--------------+-------------------------+------------+ +| x86-lynx | rts-native | native LynxOS threads | SJLJ | +| | (default) | | | ++-----------------+--------------+-------------------------+------------+ +| x86-solaris | rts-native | native Solaris | ZCX | +| | (default) | threads library | | +| +--------------+-------------------------+------------+ +| | rts-sjlj | native Solaris | SJLJ | +| | | threads library | | ++-----------------+--------------+-------------------------+------------+ +| x86-windows | rts-native | native Win32 threads | ZCX | +| | (default) | | | +| +--------------+-------------------------+------------+ +| | rts-sjlj | native Win32 threads | SJLJ | ++-----------------+--------------+-------------------------+------------+ +| x86_64-linux | rts-native | pthread library | ZCX | +| | (default) | | | +| +--------------+-------------------------+------------+ +| | rts-sjlj | pthread library | SJLJ | ++-----------------+--------------+-------------------------+------------+ + + +.. _Specifying_a_Run-Time_Library: + +Specifying a Run-Time Library +============================= + +The :file:`adainclude` subdirectory containing the sources of the GNAT +run-time library, and the :file:`adalib` subdirectory containing the +:file:`ALI` files and the static and/or shared GNAT library, are located +in the gcc target-dependent area: + + + :: + + target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/ + +As indicated above, on some platforms several run-time libraries are supplied. +These libraries are installed in the target dependent area and +contain a complete source and binary subdirectory. The detailed description +below explains the differences between the different libraries in terms of +their thread support. + +The default run-time library (when GNAT is installed) is *rts-native*. +This default run time is selected by the means of soft links. +For example on x86-linux: + + .. image:: rtlibrary-structure.png + +.. -- + -- $(target-dir) + -- | + -- +--- adainclude----------+ + -- | | + -- +--- adalib-----------+ | + -- | | | + -- +--- rts-native | | + -- | | | | + -- | +--- adainclude <---+ + -- | | | + -- | +--- adalib <----+ + -- | + -- +--- rts-sjlj + -- | + -- +--- adainclude + -- | + -- +--- adalib + + +If the *rts-sjlj* library is to be selected on a permanent basis, +these soft links can be modified with the following commands: + + :: + + $ cd $target + $ rm -f adainclude adalib + $ ln -s rts-sjlj/adainclude adainclude + $ ln -s rts-sjlj/adalib adalib + +Alternatively, you can specify :file:`rts-sjlj/adainclude` in the file +:file:`$target/ada_source_path` and :file:`rts-sjlj/adalib` in +:file:`$target/ada_object_path`. + +.. index:: --RTS option + +Selecting another run-time library temporarily can be +achieved by using the *--RTS* switch, e.g., *--RTS=sjlj* + + +.. _Choosing_the_Scheduling_Policy: + +.. index:: SCHED_FIFO scheduling policy +.. index:: SCHED_RR scheduling policy +.. index:: SCHED_OTHER scheduling policy + +Choosing the Scheduling Policy +------------------------------ + +When using a POSIX threads implementation, you have a choice of several +scheduling policies: `SCHED_FIFO`, `SCHED_RR` and `SCHED_OTHER`. + +Typically, the default is `SCHED_OTHER`, while using `SCHED_FIFO` +or `SCHED_RR` requires special (e.g., root) privileges. + +.. index:: pragma Time_Slice +.. index:: -T0 option +.. index:: pragma Task_Dispatching_Policy + + +By default, GNAT uses the `SCHED_OTHER` policy. To specify +`SCHED_FIFO`, +you can use one of the following: + +* `pragma Time_Slice (0.0)` +* the corresponding binder option *-T0* +* `pragma Task_Dispatching_Policy (FIFO_Within_Priorities)` + + +To specify `SCHED_RR`, +you should use `pragma Time_Slice` with a +value greater than 0.0, or else use the corresponding *-T* +binder option. + + +.. index:: Solaris Sparc threads libraries + +.. _Solaris-Specific_Considerations: + +Solaris-Specific Considerations +------------------------------- + +This section addresses some topics related to the various threads libraries +on Sparc Solaris. + +.. index:: rts-pthread threads library + +.. _Solaris_Threads_Issues: + +Solaris Threads Issues +---------------------- + +GNAT under Solaris/Sparc 32 bits comes with an alternate tasking run-time +library based on POSIX threads --- *rts-pthread*. + +.. index:: PTHREAD_PRIO_INHERIT policy (under rts-pthread) +.. index:: PTHREAD_PRIO_PROTECT policy (under rts-pthread) +.. index:: pragma Locking_Policy (under rts-pthread) +.. index:: Inheritance_Locking (under rts-pthread) +.. index:: Ceiling_Locking (under rts-pthread) + +This run-time library has the advantage of being mostly shared across all +POSIX-compliant thread implementations, and it also provides under +Solaris |nbsp| 8 the `PTHREAD_PRIO_INHERIT` +and `PTHREAD_PRIO_PROTECT` +semantics that can be selected using the predefined pragma +`Locking_Policy` +with respectively +`Inheritance_Locking` and `Ceiling_Locking` as the policy. + +As explained above, the native run-time library is based on the Solaris thread +library (`libthread`) and is the default library. + +.. index:: GNAT_PROCESSOR environment variable (on Sparc Solaris) + +When the Solaris threads library is used (this is the default), programs +compiled with GNAT can automatically take advantage of +and can thus execute on multiple processors. +The user can alternatively specify a processor on which the program should run +to emulate a single-processor system. The multiprocessor / uniprocessor choice +is made by +setting the environment variable :envvar:`GNAT_PROCESSOR` +to one of the following: + + ========================= =================================================================== + ``GNAT_PROCESSOR`` Value Effect + ========================= =================================================================== + *-2* Use the default configuration (run the program on all + available processors) - this is the same as having `GNAT_PROCESSOR` + unset + *-1* Let the run-time implementation choose one processor and run the + program on that processor + *0 .. Last_Proc* Run the program on the specified processor. + `Last_Proc` is equal to `_SC_NPROCESSORS_CONF - 1` + (where `_SC_NPROCESSORS_CONF` is a system variable). + ========================= =================================================================== + + +.. _AIX-Specific_Considerations: + +AIX-Specific Considerations +--------------------------- + +.. index:: AIX resolver library + +On AIX, the resolver library initializes some internal structure on +the first call to `get*by*` functions, which are used to implement +`GNAT.Sockets.Get_Host_By_Name` and +`GNAT.Sockets.Get_Host_By_Address`. +If such initialization occurs within an Ada task, and the stack size for +the task is the default size, a stack overflow may occur. + +To avoid this overflow, the user should either ensure that the first call +to `GNAT.Sockets.Get_Host_By_Name` or +`GNAT.Sockets.Get_Host_By_Addrss` +occurs in the environment task, or use `pragma Storage_Size` to +specify a sufficiently large size for the stack of the task that contains +this call. + + +.. index:: Windows NT +.. index:: Windows 95 +.. index:: Windows 98 + +.. _Microsoft_Windows_Topics: + +Microsoft Windows Topics +======================== + +This section describes topics that are specific to the Microsoft Windows +platforms. + + +.. only:: PRO or GPL + + .. rubric:: Installing from the Command Line + + By default the GNAT installers display a GUI that prompts you to enter + the installation path and similar information, and then guides you through the + installation process. It is also possible to perform silent installations + using the command-line interface. + + In order to install one of the GNAT installers from the command + line you should pass parameter `/S` (and, optionally, + `/D=<directory>`) as command-line arguments. + +.. only:: PRO + + For example, for an unattended installation of + GNAT 7.0.2 into the default directory + `C:\\GNATPRO\\7.0.2` you would run: + + :: + + gnatpro-7.0.2-i686-pc-mingw32-bin.exe /S + + To install into a custom directory, say, `C:\\TOOLS\\GNATPRO\\7.0.2`: + + :: + + gnatpro-7.0.2-i686-pc-mingw32-bin /S /D=C:\TOOLS\GNATPRO\7.0.2 + +.. only:: GPL + + For example, for an unattended installation of + GNAT 2012 into `C:\\GNAT\\2012`: + + :: + + gnat-gpl-2012-i686-pc-mingw32-bin /S /D=C:\GNAT\2012 + +.. only:: PRO or GPL + + You can use the same syntax for all installers. + + Note that unattended installations don't modify system path, nor create file + associations, so such activities need to be done by hand. + + + +.. _Using_GNAT_on_Windows: + +Using GNAT on Windows +--------------------- + +One of the strengths of the GNAT technology is that its tool set +(*gcc*, *gnatbind*, *gnatlink*, *gnatmake*, the +`gdb` debugger, etc.) is used in the same way regardless of the +platform. + +On Windows this tool set is complemented by a number of Microsoft-specific +tools that have been provided to facilitate interoperability with Windows +when this is required. With these tools: + + +* You can build applications using the `CONSOLE` or `WINDOWS` + subsystems. + +* You can use any Dynamically Linked Library (DLL) in your Ada code (both + relocatable and non-relocatable DLLs are supported). + +* You can build Ada DLLs for use in other applications. These applications + can be written in a language other than Ada (e.g., C, C++, etc). Again both + relocatable and non-relocatable Ada DLLs are supported. + +* You can include Windows resources in your Ada application. + +* You can use or create COM/DCOM objects. + +Immediately below are listed all known general GNAT-for-Windows restrictions. +Other restrictions about specific features like Windows Resources and DLLs +are listed in separate sections below. + + +* It is not possible to use `GetLastError` and `SetLastError` + when tasking, protected records, or exceptions are used. In these + cases, in order to implement Ada semantics, the GNAT run-time system + calls certain Win32 routines that set the last error variable to 0 upon + success. It should be possible to use `GetLastError` and + `SetLastError` when tasking, protected record, and exception + features are not used, but it is not guaranteed to work. + +* It is not possible to link against Microsoft C++ libraries except for + import libraries. Interfacing must be done by the mean of DLLs. + +* It is possible to link against Microsoft C libraries. Yet the preferred + solution is to use C/C++ compiler that comes with GNAT, since it + doesn't require having two different development environments and makes the + inter-language debugging experience smoother. + +* When the compilation environment is located on FAT32 drives, users may + experience recompilations of the source files that have not changed if + Daylight Saving Time (DST) state has changed since the last time files + were compiled. NTFS drives do not have this problem. + +* No components of the GNAT toolset use any entries in the Windows + registry. The only entries that can be created are file associations and + PATH settings, provided the user has chosen to create them at installation + time, as well as some minimal book-keeping information needed to correctly + uninstall or integrate different GNAT products. + + +.. _Using_a_network_installation_of_GNAT: + +Using a network installation of GNAT +------------------------------------ + +Make sure the system on which GNAT is installed is accessible from the +current machine, i.e., the install location is shared over the network. +Shared resources are accessed on Windows by means of UNC paths, which +have the format `\\\\server\\sharename\\path` + +In order to use such a network installation, simply add the UNC path of the +:file:`bin` directory of your GNAT installation in front of your PATH. For +example, if GNAT is installed in :file:`\\GNAT` directory of a share location +called :file:`c-drive` on a machine :file:`LOKI`, the following command will +make it available: + + :: + + $ path \\loki\c-drive\gnat\bin;%path%` + +Be aware that every compilation using the network installation results in the +transfer of large amounts of data across the network and will likely cause +serious performance penalty. + +.. _CONSOLE_and_WINDOWS_subsystems: + +CONSOLE and WINDOWS subsystems +------------------------------ + +.. index:: CONSOLE Subsystem +.. index:: WINDOWS Subsystem +.. index:: -mwindows + +There are two main subsystems under Windows. The `CONSOLE` subsystem +(which is the default subsystem) will always create a console when +launching the application. This is not something desirable when the +application has a Windows GUI. To get rid of this console the +application must be using the `WINDOWS` subsystem. To do so +the *-mwindows* linker option must be specified. + + :: + + $ gnatmake winprog -largs -mwindows + +.. _Temporary_Files: + +Temporary Files +--------------- + +.. index:: Temporary files + +It is possible to control where temporary files gets created by setting +the :envvar:`TMP` environment variable. The file will be created: + +* Under the directory pointed to by the :envvar:`TMP` environment variable if + this directory exists. + +* Under :file:`c:\\temp`, if the :envvar:`TMP` environment variable is not + set (or not pointing to a directory) and if this directory exists. + +* Under the current working directory otherwise. + +This allows you to determine exactly where the temporary +file will be created. This is particularly useful in networked +environments where you may not have write access to some +directories. + + +.. _Mixed-Language_Programming_on_Windows: + +Mixed-Language Programming on Windows +------------------------------------- + +Developing pure Ada applications on Windows is no different than on +other GNAT-supported platforms. However, when developing or porting an +application that contains a mix of Ada and C/C++, the choice of your +Windows C/C++ development environment conditions your overall +interoperability strategy. + +If you use *gcc* or Microsoft C to compile the non-Ada part of +your application, there are no Windows-specific restrictions that +affect the overall interoperability with your Ada code. If you do want +to use the Microsoft tools for your C++ code, you have two choices: + +* Encapsulate your C++ code in a DLL to be linked with your Ada + application. In this case, use the Microsoft or whatever environment to + build the DLL and use GNAT to build your executable + (:ref:`Using_DLLs_with_GNAT`). + +* Or you can encapsulate your Ada code in a DLL to be linked with the + other part of your application. In this case, use GNAT to build the DLL + (:ref:`Building_DLLs_with_GNAT_Project_files`) and use the Microsoft + or whatever environment to build your executable. + +In addition to the description about C main in +:ref:`Mixed_Language_Programming` section, if the C main uses a +stand-alone library it is required on x86-windows to +setup the SEH context. For this the C main must looks like this: + + + .. code-block:: c + + /* main.c */ + extern void adainit (void); + extern void adafinal (void); + extern void __gnat_initialize(void*); + extern void call_to_ada (void); + + int main (int argc, char *argv[]) + { + int SEH [2]; + + /* Initialize the SEH context */ + __gnat_initialize (&SEH); + + adainit(); + + /* Then call Ada services in the stand-alone library */ + + call_to_ada(); + + adafinal(); + } + +Note that this is not needed on x86_64-windows where the Windows +native SEH support is used. + + +.. _Windows_Calling_Conventions: + +Windows Calling Conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Stdcall +.. index:: APIENTRY + +This section pertain only to Win32. On Win64 there is a single native +calling convention. All convention specifiers are ignored on this +platform. + +When a subprogram `F` (caller) calls a subprogram `G` +(callee), there are several ways to push `G`'s parameters on the +stack and there are several possible scenarios to clean up the stack +upon `G`'s return. A calling convention is an agreed upon software +protocol whereby the responsibilities between the caller (`F`) and +the callee (`G`) are clearly defined. Several calling conventions +are available for Windows: + +* `C` (Microsoft defined) + +* `Stdcall` (Microsoft defined) + +* `Win32` (GNAT specific) + +* `DLL` (GNAT specific) + + +.. _C_Calling_Convention: + +`C` Calling Convention +"""""""""""""""""""""" + +This is the default calling convention used when interfacing to C/C++ +routines compiled with either *gcc* or Microsoft Visual C++. + +In the `C` calling convention subprogram parameters are pushed on the +stack by the caller from right to left. The caller itself is in charge of +cleaning up the stack after the call. In addition, the name of a routine +with `C` calling convention is mangled by adding a leading underscore. + +The name to use on the Ada side when importing (or exporting) a routine +with `C` calling convention is the name of the routine. For +instance the C function: + + :: + + int get_val (long); + +should be imported from Ada as follows: + + .. code-block:: ada + + function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; + pragma Import (C, Get_Val, External_Name => "get_val"); + +Note that in this particular case the `External_Name` parameter could +have been omitted since, when missing, this parameter is taken to be the +name of the Ada entity in lower case. When the `Link_Name` parameter +is missing, as in the above example, this parameter is set to be the +`External_Name` with a leading underscore. + +When importing a variable defined in C, you should always use the `C` +calling convention unless the object containing the variable is part of a +DLL (in which case you should use the `Stdcall` calling +convention, :ref:`Stdcall_Calling_Convention`). + + +.. _Stdcall_Calling_Convention: + +`Stdcall` Calling Convention +"""""""""""""""""""""""""""" + +This convention, which was the calling convention used for Pascal +programs, is used by Microsoft for all the routines in the Win32 API for +efficiency reasons. It must be used to import any routine for which this +convention was specified. + +In the `Stdcall` calling convention subprogram parameters are pushed +on the stack by the caller from right to left. The callee (and not the +caller) is in charge of cleaning the stack on routine exit. In addition, +the name of a routine with `Stdcall` calling convention is mangled by +adding a leading underscore (as for the `C` calling convention) and a +trailing :samp:`@{nn}`, where `nn` is the overall size (in +bytes) of the parameters passed to the routine. + +The name to use on the Ada side when importing a C routine with a +`Stdcall` calling convention is the name of the C routine. The leading +underscore and trailing :samp:`@{nn}` are added automatically by +the compiler. For instance the Win32 function: + + :: + + APIENTRY int get_val (long); + +should be imported from Ada as follows: + + .. code-block:: ada + + function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; + pragma Import (Stdcall, Get_Val); + -- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@4" + +As for the `C` calling convention, when the `External_Name` +parameter is missing, it is taken to be the name of the Ada entity in lower +case. If instead of writing the above import pragma you write: + + .. code-block:: ada + + function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; + pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); + +then the imported routine is `_retrieve_val@4`. However, if instead +of specifying the `External_Name` parameter you specify the +`Link_Name` as in the following example: + + .. code-block:: ada + + function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; + pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); + +then the imported routine is `retrieve_val`, that is, there is no +decoration at all. No leading underscore and no Stdcall suffix +:samp:`@{nn}`. + +This is especially important as in some special cases a DLL's entry +point name lacks a trailing :samp:`@{nn}` while the exported +name generated for a call has it. + +It is also possible to import variables defined in a DLL by using an +import pragma for a variable. As an example, if a DLL contains a +variable defined as: + + .. code-block:: c + + int my_var; + +then, to access this variable from Ada you should write: + + .. code-block:: ada + + My_Var : Interfaces.C.int; + pragma Import (Stdcall, My_Var); + +Note that to ease building cross-platform bindings this convention +will be handled as a `C` calling convention on non-Windows platforms. + + +.. _Win32_Calling_Convention: + +`Win32` Calling Convention +"""""""""""""""""""""""""" + +This convention, which is GNAT-specific is fully equivalent to the +`Stdcall` calling convention described above. + + +.. _DLL_Calling_Convention: + +`DLL` Calling Convention +"""""""""""""""""""""""" + +This convention, which is GNAT-specific is fully equivalent to the +`Stdcall` calling convention described above. + + +.. _Introduction_to_Dynamic_Link_Libraries_DLLs: + +Introduction to Dynamic Link Libraries (DLLs) +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: DLL + +A Dynamically Linked Library (DLL) is a library that can be shared by +several applications running under Windows. A DLL can contain any number of +routines and variables. + +One advantage of DLLs is that you can change and enhance them without +forcing all the applications that depend on them to be relinked or +recompiled. However, you should be aware than all calls to DLL routines are +slower since, as you will understand below, such calls are indirect. + +To illustrate the remainder of this section, suppose that an application +wants to use the services of a DLL :file:`API.dll`. To use the services +provided by :file:`API.dll` you must statically link against the DLL or +an import library which contains a jump table with an entry for each +routine and variable exported by the DLL. In the Microsoft world this +import library is called :file:`API.lib`. When using GNAT this import +library is called either :file:`libAPI.dll.a`, :file:`libapi.dll.a`, +:file:`libAPI.a` or :file:`libapi.a` (names are case insensitive). + +After you have linked your application with the DLL or the import library +and you run your application, here is what happens: + +* Your application is loaded into memory. + +* The DLL :file:`API.dll` is mapped into the address space of your + application. This means that: + + - The DLL will use the stack of the calling thread. + + - The DLL will use the virtual address space of the calling process. + + - The DLL will allocate memory from the virtual address space of the calling + process. + + - Handles (pointers) can be safely exchanged between routines in the DLL + routines and routines in the application using the DLL. + +* The entries in the jump table (from the import library :file:`libAPI.dll.a` + or :file:`API.lib` or automatically created when linking against a DLL) + which is part of your application are initialized with the addresses + of the routines and variables in :file:`API.dll`. + +* If present in :file:`API.dll`, routines `DllMain` or + `DllMainCRTStartup` are invoked. These routines typically contain + the initialization code needed for the well-being of the routines and + variables exported by the DLL. + +There is an additional point which is worth mentioning. In the Windows +world there are two kind of DLLs: relocatable and non-relocatable +DLLs. Non-relocatable DLLs can only be loaded at a very specific address +in the target application address space. If the addresses of two +non-relocatable DLLs overlap and these happen to be used by the same +application, a conflict will occur and the application will run +incorrectly. Hence, when possible, it is always preferable to use and +build relocatable DLLs. Both relocatable and non-relocatable DLLs are +supported by GNAT. Note that the *-s* linker option (see GNU Linker +User's Guide) removes the debugging symbols from the DLL but the DLL can +still be relocated. + +As a side note, an interesting difference between Microsoft DLLs and +Unix shared libraries, is the fact that on most Unix systems all public +routines are exported by default in a Unix shared library, while under +Windows it is possible (but not required) to list exported routines in +a definition file (see :ref:`The Definition File <The_Definition_File>`). + + +.. _Using_DLLs_with_GNAT: + +Using DLLs with GNAT +^^^^^^^^^^^^^^^^^^^^ + +To use the services of a DLL, say :file:`API.dll`, in your Ada application +you must have: + +* The Ada spec for the routines and/or variables you want to access in + :file:`API.dll`. If not available this Ada spec must be built from the C/C++ + header files provided with the DLL. + +* The import library (:file:`libAPI.dll.a` or :file:`API.lib`). As previously + mentioned an import library is a statically linked library containing the + import table which will be filled at load time to point to the actual + :file:`API.dll` routines. Sometimes you don't have an import library for the + DLL you want to use. The following sections will explain how to build + one. Note that this is optional. + +* The actual DLL, :file:`API.dll`. + +Once you have all the above, to compile an Ada application that uses the +services of :file:`API.dll` and whose main subprogram is `My_Ada_App`, +you simply issue the command + + :: + + $ gnatmake my_ada_app -largs -lAPI + +The argument *-largs -lAPI* at the end of the *gnatmake* command +tells the GNAT linker to look for an import library. The linker will +look for a library name in this specific order: + +* :file:`libAPI.dll.a` +* :file:`API.dll.a` +* :file:`libAPI.a` +* :file:`API.lib` +* :file:`libAPI.dll` +* :file:`API.dll` + +The first three are the GNU style import libraries. The third is the +Microsoft style import libraries. The last two are the actual DLL names. + +Note that if the Ada package spec for :file:`API.dll` contains the +following pragma + + .. code-block:: ada + + pragma Linker_Options ("-lAPI"); + +you do not have to add *-largs -lAPI* at the end of the +*gnatmake* command. + +If any one of the items above is missing you will have to create it +yourself. The following sections explain how to do so using as an +example a fictitious DLL called :file:`API.dll`. + + +.. _Creating_an_Ada_Spec_for_the_DLL_Services: + +Creating an Ada Spec for the DLL Services +""""""""""""""""""""""""""""""""""""""""" + +A DLL typically comes with a C/C++ header file which provides the +definitions of the routines and variables exported by the DLL. The Ada +equivalent of this header file is a package spec that contains definitions +for the imported entities. If the DLL you intend to use does not come with +an Ada spec you have to generate one such spec yourself. For example if +the header file of :file:`API.dll` is a file :file:`api.h` containing the +following two definitions: + + .. code-block:: c + + int some_var; + int get (char *); + +then the equivalent Ada spec could be: + + .. code-block:: ada + + with Interfaces.C.Strings; + package API is + use Interfaces; + + Some_Var : C.int; + function Get (Str : C.Strings.Chars_Ptr) return C.int; + + private + pragma Import (C, Get); + pragma Import (DLL, Some_Var); + end API; + + +.. _Creating_an_Import_Library: + +Creating an Import Library +"""""""""""""""""""""""""" + +.. index:: Import library + +If a Microsoft-style import library :file:`API.lib` or a GNAT-style +import library :file:`libAPI.dll.a` or :file:`libAPI.a` is available +with :file:`API.dll` you can skip this section. You can also skip this +section if :file:`API.dll` or :file:`libAPI.dll` is built with GNU tools +as in this case it is possible to link directly against the +DLL. Otherwise read on. + + +.. index:: Definition file + +.. _The_Definition_File: + +.. rubric:: The Definition File + +As previously mentioned, and unlike Unix systems, the list of symbols +that are exported from a DLL must be provided explicitly in Windows. +The main goal of a definition file is precisely that: list the symbols +exported by a DLL. A definition file (usually a file with a `.def` +suffix) has the following structure: + + :: + + [LIBRARY `name`] + [DESCRIPTION `string`] + EXPORTS + `symbol1` + `symbol2` + ... + +*LIBRARY `name`* + This section, which is optional, gives the name of the DLL. + + +*DESCRIPTION `string`* + This section, which is optional, gives a description string that will be + embedded in the import library. + + +*EXPORTS* + This section gives the list of exported symbols (procedures, functions or + variables). For instance in the case of :file:`API.dll` the `EXPORTS` + section of :file:`API.def` looks like: + + :: + + EXPORTS + some_var + get + +Note that you must specify the correct suffix (:samp:`@{nn}`) +(see :ref:`Windows_Calling_Conventions`) for a Stdcall +calling convention function in the exported symbols list. + +There can actually be other sections in a definition file, but these +sections are not relevant to the discussion at hand. + + +.. rubric:: GNAT-Style Import Library + +.. _GNAT-Style_Import_Library: + +To create a static import library from :file:`API.dll` with the GNAT tools +you should proceed as follows: + +* Create the definition file :file:`API.def` + (see :ref:`The Definition File <The_Definition_File>`). + For that use the `dll2def` tool as follows: + + :: + + $ dll2def API.dll > API.def + + `dll2def` is a very simple tool: it takes as input a DLL and prints + to standard output the list of entry points in the DLL. Note that if + some routines in the DLL have the `Stdcall` convention + (:ref:`Windows_Calling_Conventions`) with stripped :samp:`@{nn}` + suffix then you'll have to edit :file:`api.def` to add it, and specify + *-k* to *gnatdll* when creating the import library. + + Here are some hints to find the right :samp:`@{nn}` suffix. + + - If you have the Microsoft import library (.lib), it is possible to get + the right symbols by using Microsoft `dumpbin` tool (see the + corresponding Microsoft documentation for further details). + + :: + + $ dumpbin /exports api.lib + + - If you have a message about a missing symbol at link time the compiler + tells you what symbol is expected. You just have to go back to the + definition file and add the right suffix. + +* Build the import library `libAPI.dll.a`, using `gnatdll` + (see :ref:`Using_gnatdll`) as follows: + + :: + + $ gnatdll -e API.def -d API.dll + + `gnatdll` takes as input a definition file :file:`API.def` and the + name of the DLL containing the services listed in the definition file + :file:`API.dll`. The name of the static import library generated is + computed from the name of the definition file as follows: if the + definition file name is `xyz``.def`, the import library name will + be `lib``xyz``.a`. Note that in the previous example option + *-e* could have been removed because the name of the definition + file (before the '`.def`' suffix) is the same as the name of the + DLL (:ref:`Using_gnatdll` for more information about `gnatdll`). + + +.. rubric:: Microsoft-Style Import Library + +With GNAT you can either use a GNAT-style or Microsoft-style import +library. A Microsoft import library is needed only if you plan to make an +Ada DLL available to applications developed with Microsoft +tools (:ref:`Mixed-Language_Programming_on_Windows`). + +To create a Microsoft-style import library for :file:`API.dll` you +should proceed as follows: + +* Create the definition file :file:`API.def` from the DLL. For this use either + the `dll2def` tool as described above or the Microsoft `dumpbin` + tool (see the corresponding Microsoft documentation for further details). + +* Build the actual import library using Microsoft's `lib` utility: + + :: + + $ lib -machine:IX86 -def:API.def -out:API.lib + + If you use the above command the definition file :file:`API.def` must + contain a line giving the name of the DLL: + + :: + + LIBRARY "API" + + See the Microsoft documentation for further details about the usage of + `lib`. + + +.. _Building_DLLs_with_GNAT_Project_files: + +Building DLLs with GNAT Project files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: DLLs, building + +There is nothing specific to Windows in the build process. +:ref:`Library_Projects`. + +Due to a system limitation, it is not possible under Windows to create threads +when inside the `DllMain` routine which is used for auto-initialization +of shared libraries, so it is not possible to have library level tasks in SALs. + + +.. _Building_DLLs_with_GNAT: + +Building DLLs with GNAT +^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: DLLs, building + +This section explain how to build DLLs using the GNAT built-in DLL +support. With the following procedure it is straight forward to build +and use DLLs with GNAT. + + +* Building object files. + The first step is to build all objects files that are to be included + into the DLL. This is done by using the standard *gnatmake* tool. + +* Building the DLL. + To build the DLL you must use *gcc*'s *-shared* and + *-shared-libgcc* options. It is quite simple to use this method: + + :: + + $ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ... + + It is important to note that in this case all symbols found in the + object files are automatically exported. It is possible to restrict + the set of symbols to export by passing to *gcc* a definition + file (see :ref:`The Definition File <The_Definition_File>`). + For example: + + :: + + $ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ... + + If you use a definition file you must export the elaboration procedures + for every package that required one. Elaboration procedures are named + using the package name followed by "_E". + +* Preparing DLL to be used. + For the DLL to be used by client programs the bodies must be hidden + from it and the .ali set with read-only attribute. This is very important + otherwise GNAT will recompile all packages and will not actually use + the code in the DLL. For example: + + :: + + $ mkdir apilib + $ copy *.ads *.ali api.dll apilib + $ attrib +R apilib\\*.ali + +At this point it is possible to use the DLL by directly linking +against it. Note that you must use the GNAT shared runtime when using +GNAT shared libraries. This is achieved by using *-shared* binder's +option. + + :: + + $ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI + + +.. _Building_DLLs_with_gnatdll: + +Building DLLs with gnatdll +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: DLLs, building + +Note that it is preferred to use GNAT Project files +(:ref:`Building_DLLs_with_GNAT_Project_files`) or the built-in GNAT +DLL support (:ref:`Building_DLLs_with_GNAT`) or to build DLLs. + +This section explains how to build DLLs containing Ada code using +`gnatdll`. These DLLs will be referred to as Ada DLLs in the +remainder of this section. + +The steps required to build an Ada DLL that is to be used by Ada as well as +non-Ada applications are as follows: + +* You need to mark each Ada *entity* exported by the DLL with a `C` or + `Stdcall` calling convention to avoid any Ada name mangling for the + entities exported by the DLL + (see :ref:`Exporting Ada Entities <Exporting_Ada_Entities>`). You can + skip this step if you plan to use the Ada DLL only from Ada applications. + +* Your Ada code must export an initialization routine which calls the routine + `adainit` generated by *gnatbind* to perform the elaboration of + the Ada code in the DLL (:ref:`Ada_DLLs_and_Elaboration`). The initialization + routine exported by the Ada DLL must be invoked by the clients of the DLL + to initialize the DLL. + +* When useful, the DLL should also export a finalization routine which calls + routine `adafinal` generated by *gnatbind* to perform the + finalization of the Ada code in the DLL (:ref:`Ada_DLLs_and_Finalization`). + The finalization routine exported by the Ada DLL must be invoked by the + clients of the DLL when the DLL services are no further needed. + +* You must provide a spec for the services exported by the Ada DLL in each + of the programming languages to which you plan to make the DLL available. + +* You must provide a definition file listing the exported entities + (:ref:`The Definition File <The_Definition_File>`). + +* Finally you must use `gnatdll` to produce the DLL and the import + library (:ref:`Using_gnatdll`). + +Note that a relocatable DLL stripped using the `strip` +binutils tool will not be relocatable anymore. To build a DLL without +debug information pass `-largs -s` to `gnatdll`. This +restriction does not apply to a DLL built using a Library Project. +See :ref:`Library_Projects`. + +.. Limitations_When_Using_Ada_DLLs_from Ada: + +Limitations When Using Ada DLLs from Ada +"""""""""""""""""""""""""""""""""""""""" + +When using Ada DLLs from Ada applications there is a limitation users +should be aware of. Because on Windows the GNAT run time is not in a DLL of +its own, each Ada DLL includes a part of the GNAT run time. Specifically, +each Ada DLL includes the services of the GNAT run time that are necessary +to the Ada code inside the DLL. As a result, when an Ada program uses an +Ada DLL there are two independent GNAT run times: one in the Ada DLL and +one in the main program. + +It is therefore not possible to exchange GNAT run-time objects between the +Ada DLL and the main Ada program. Example of GNAT run-time objects are file +handles (e.g., `Text_IO.File_Type`), tasks types, protected objects +types, etc. + +It is completely safe to exchange plain elementary, array or record types, +Windows object handles, etc. + + +.. _Exporting_Ada_Entities: + +Exporting Ada Entities +"""""""""""""""""""""" + +.. index:: Export table + +Building a DLL is a way to encapsulate a set of services usable from any +application. As a result, the Ada entities exported by a DLL should be +exported with the `C` or `Stdcall` calling conventions to avoid +any Ada name mangling. As an example here is an Ada package +`API`, spec and body, exporting two procedures, a function, and a +variable: + + + .. code-block:: ada + + with Interfaces.C; use Interfaces; + package API is + Count : C.int := 0; + function Factorial (Val : C.int) return C.int; + + procedure Initialize_API; + procedure Finalize_API; + -- Initialization & Finalization routines. More in the next section. + private + pragma Export (C, Initialize_API); + pragma Export (C, Finalize_API); + pragma Export (C, Count); + pragma Export (C, Factorial); + end API; + + .. code-block:: ada + + package body API is + function Factorial (Val : C.int) return C.int is + Fact : C.int := 1; + begin + Count := Count + 1; + for K in 1 .. Val loop + Fact := Fact * K; + end loop; + return Fact; + end Factorial; + + procedure Initialize_API is + procedure Adainit; + pragma Import (C, Adainit); + begin + Adainit; + end Initialize_API; + + procedure Finalize_API is + procedure Adafinal; + pragma Import (C, Adafinal); + begin + Adafinal; + end Finalize_API; + end API; + +If the Ada DLL you are building will only be used by Ada applications +you do not have to export Ada entities with a `C` or `Stdcall` +convention. As an example, the previous package could be written as +follows: + + .. code-block:: ada + + package API is + Count : Integer := 0; + function Factorial (Val : Integer) return Integer; + + procedure Initialize_API; + procedure Finalize_API; + -- Initialization and Finalization routines. + end API; + + .. code-block:: ada + + package body API is + function Factorial (Val : Integer) return Integer is + Fact : Integer := 1; + begin + Count := Count + 1; + for K in 1 .. Val loop + Fact := Fact * K; + end loop; + return Fact; + end Factorial; + + ... + -- The remainder of this package body is unchanged. + end API; + +Note that if you do not export the Ada entities with a `C` or +`Stdcall` convention you will have to provide the mangled Ada names +in the definition file of the Ada DLL +(:ref:`Creating_the_Definition_File`). + + +.. _Ada_DLLs_and_Elaboration: + +Ada DLLs and Elaboration +"""""""""""""""""""""""" + +.. index:: DLLs and elaboration + +The DLL that you are building contains your Ada code as well as all the +routines in the Ada library that are needed by it. The first thing a +user of your DLL must do is elaborate the Ada code +(:ref:`Elaboration_Order_Handling_in_GNAT`). + +To achieve this you must export an initialization routine +(`Initialize_API` in the previous example), which must be invoked +before using any of the DLL services. This elaboration routine must call +the Ada elaboration routine `adainit` generated by the GNAT binder +(:ref:`Binding_with_Non-Ada_Main_Programs`). See the body of +`Initialize_Api` for an example. Note that the GNAT binder is +automatically invoked during the DLL build process by the `gnatdll` +tool (:ref:`Using_gnatdll`). + +When a DLL is loaded, Windows systematically invokes a routine called +`DllMain`. It would therefore be possible to call `adainit` +directly from `DllMain` without having to provide an explicit +initialization routine. Unfortunately, it is not possible to call +`adainit` from the `DllMain` if your program has library level +tasks because access to the `DllMain` entry point is serialized by +the system (that is, only a single thread can execute 'through' it at a +time), which means that the GNAT run time will deadlock waiting for the +newly created task to complete its initialization. + + +.. _Ada_DLLs_and_Finalization: + +Ada DLLs and Finalization +^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: DLLs and finalization + +When the services of an Ada DLL are no longer needed, the client code should +invoke the DLL finalization routine, if available. The DLL finalization +routine is in charge of releasing all resources acquired by the DLL. In the +case of the Ada code contained in the DLL, this is achieved by calling +routine `adafinal` generated by the GNAT binder +(:ref:`Binding_with_Non-Ada_Main_Programs`). +See the body of `Finalize_Api` for an +example. As already pointed out the GNAT binder is automatically invoked +during the DLL build process by the `gnatdll` tool +(:ref:`Using_gnatdll`). + + +.. _Creating_a_Spec_for_Ada_DLLs: + +Creating a Spec for Ada DLLs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To use the services exported by the Ada DLL from another programming +language (e.g., C), you have to translate the specs of the exported Ada +entities in that language. For instance in the case of `API.dll`, +the corresponding C header file could look like: + + .. code-block:: c + + extern int *_imp__count; + #define count (*_imp__count) + int factorial (int); + +It is important to understand that when building an Ada DLL to be used by +other Ada applications, you need two different specs for the packages +contained in the DLL: one for building the DLL and the other for using +the DLL. This is because the `DLL` calling convention is needed to +use a variable defined in a DLL, but when building the DLL, the variable +must have either the `Ada` or `C` calling convention. As an +example consider a DLL comprising the following package `API`: + + .. code-block:: ada + + package API is + Count : Integer := 0; + ... + -- Remainder of the package omitted. + end API; + +After producing a DLL containing package `API`, the spec that +must be used to import `API.Count` from Ada code outside of the +DLL is: + + .. code-block:: ada + + package API is + Count : Integer; + pragma Import (DLL, Count); + end API; + + +.. _Creating_the_Definition_File: + +Creating the Definition File +"""""""""""""""""""""""""""" + +The definition file is the last file needed to build the DLL. It lists +the exported symbols. As an example, the definition file for a DLL +containing only package `API` (where all the entities are exported +with a `C` calling convention) is: + + :: + + EXPORTS + count + factorial + finalize_api + initialize_api + +If the `C` calling convention is missing from package `API`, +then the definition file contains the mangled Ada names of the above +entities, which in this case are: + + :: + + EXPORTS + api__count + api__factorial + api__finalize_api + api__initialize_api + + +.. _Using_gnatdll: + +Using `gnatdll` +""""""""""""""" + +.. index:: gnatdll + +`gnatdll` is a tool to automate the DLL build process once all the Ada +and non-Ada sources that make up your DLL have been compiled. +`gnatdll` is actually in charge of two distinct tasks: build the +static import library for the DLL and the actual DLL. The form of the +`gnatdll` command is + + :: + + $ gnatdll [`switches`] `list-of-files` [-largs `opts`] + +where `list-of-files` is a list of ALI and object files. The object +file list must be the exact list of objects corresponding to the non-Ada +sources whose services are to be included in the DLL. The ALI file list +must be the exact list of ALI files for the corresponding Ada sources +whose services are to be included in the DLL. If `list-of-files` is +missing, only the static import library is generated. + +You may specify any of the following switches to `gnatdll`: + + + .. index:: -a (gnatdll) + +:samp:`-a[{address}]` + Build a non-relocatable DLL at `address`. If `address` is not + specified the default address `0x11000000` will be used. By default, + when this switch is missing, `gnatdll` builds relocatable DLL. We + advise the reader to build relocatable DLL. + + + .. index:: -b (gnatdll) + +:samp:`-b {address}` + Set the relocatable DLL base address. By default the address is + `0x11000000`. + + + .. index:: -bargs (gnatdll) + +:samp:`-bargs {opts}` + Binder options. Pass `opts` to the binder. + + + .. index:: -d (gnatdll) + +:samp:`-d {dllfile}` + `dllfile` is the name of the DLL. This switch must be present for + `gnatdll` to do anything. The name of the generated import library is + obtained algorithmically from `dllfile` as shown in the following + example: if `dllfile` is `xyz.dll`, the import library name is + `libxyz.dll.a`. The name of the definition file to use (if not specified + by option *-e*) is obtained algorithmically from `dllfile` + as shown in the following example: + if `dllfile` is `xyz.dll`, the definition + file used is `xyz.def`. + + + .. index:: -e (gnatdll) + +:samp:`-e {deffile}` + `deffile` is the name of the definition file. + + + .. index:: -g (gnatdll) + +:samp:`-g` + Generate debugging information. This information is stored in the object + file and copied from there to the final DLL file by the linker, + where it can be read by the debugger. You must use the + *-g* switch if you plan on using the debugger or the symbolic + stack traceback. + + + .. index:: -h (gnatdll) + +:samp:`-h` + Help mode. Displays `gnatdll` switch usage information. + + + .. index:: -I (gnatdll) + +:samp:`-I{dir}` + Direct `gnatdll` to search the `dir` directory for source and + object files needed to build the DLL. + (:ref:`Search_Paths_and_the_Run-Time_Library_RTL`). + + + .. index:: -k (gnatdll) + +:samp:`-k` + Removes the :samp:`@{nn}` suffix from the import library's exported + names, but keeps them for the link names. You must specify this + option if you want to use a `Stdcall` function in a DLL for which + the :samp:`@{nn}` suffix has been removed. This is the case for most + of the Windows NT DLL for example. This option has no effect when + *-n* option is specified. + + + .. index:: -l (gnatdll) + +:samp:`-l {file}` + The list of ALI and object files used to build the DLL are listed in + `file`, instead of being given in the command line. Each line in + `file` contains the name of an ALI or object file. + + + .. index:: -n (gnatdll) + +:samp:`-n` + No Import. Do not create the import library. + + + .. index:: -q (gnatdll) + +:samp:`-q` + Quiet mode. Do not display unnecessary messages. + + + .. index:: -v (gnatdll) + +:samp:`-v` + Verbose mode. Display extra information. + + + .. index:: -largs (gnatdll) + +:samp:`-largs {opts}` + Linker options. Pass `opts` to the linker. + + +.. rubric:: `gnatdll` Example + +As an example the command to build a relocatable DLL from :file:`api.adb` +once :file:`api.adb` has been compiled and :file:`api.def` created is + + :: + + $ gnatdll -d api.dll api.ali + +The above command creates two files: :file:`libapi.dll.a` (the import +library) and :file:`api.dll` (the actual DLL). If you want to create +only the DLL, just type: + + :: + + $ gnatdll -d api.dll -n api.ali + +Alternatively if you want to create just the import library, type: + + :: + + $ gnatdll -d api.dll + + +.. rubric:: `gnatdll` behind the Scenes + +This section details the steps involved in creating a DLL. `gnatdll` +does these steps for you. Unless you are interested in understanding what +goes on behind the scenes, you should skip this section. + +We use the previous example of a DLL containing the Ada package `API`, +to illustrate the steps necessary to build a DLL. The starting point is a +set of objects that will make up the DLL and the corresponding ALI +files. In the case of this example this means that :file:`api.o` and +:file:`api.ali` are available. To build a relocatable DLL, `gnatdll` does +the following: + +* `gnatdll` builds the base file (:file:`api.base`). A base file gives + the information necessary to generate relocation information for the + DLL. + + :: + + $ gnatbind -n api + $ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base + + In addition to the base file, the *gnatlink* command generates an + output file :file:`api.jnk` which can be discarded. The *-mdll* switch + asks *gnatlink* to generate the routines `DllMain` and + `DllMainCRTStartup` that are called by the Windows loader when the DLL + is loaded into memory. + +* `gnatdll` uses `dlltool` (see :ref:`Using dlltool <Using_dlltool>`) to build the + export table (:file:`api.exp`). The export table contains the relocation + information in a form which can be used during the final link to ensure + that the Windows loader is able to place the DLL anywhere in memory. + + :: + + $ dlltool --dllname api.dll --def api.def --base-file api.base \\ + --output-exp api.exp + +* `gnatdll` builds the base file using the new export table. Note that + *gnatbind* must be called once again since the binder generated file + has been deleted during the previous call to *gnatlink*. + + :: + + $ gnatbind -n api + $ gnatlink api -o api.jnk api.exp -mdll + -Wl,--base-file,api.base + + +* `gnatdll` builds the new export table using the new base file and + generates the DLL import library :file:`libAPI.dll.a`. + + + :: + + $ dlltool --dllname api.dll --def api.def --base-file api.base \\ + --output-exp api.exp --output-lib libAPI.a + +* Finally `gnatdll` builds the relocatable DLL using the final export + table. + + :: + + $ gnatbind -n api + $ gnatlink api api.exp -o api.dll -mdll + + +.. _Using_dlltool: + +.. rubric:: Using `dlltool` + +`dlltool` is the low-level tool used by `gnatdll` to build +DLLs and static import libraries. This section summarizes the most +common `dlltool` switches. The form of the `dlltool` command +is + + :: + + $ dlltool [`switches`] + +`dlltool` switches include: + + +.. index:: --base-file (dlltool) + +:samp:`--base-file {basefile}` + Read the base file `basefile` generated by the linker. This switch + is used to create a relocatable DLL. + + +.. index:: --def (dlltool) + +:samp:`--def {deffile}` + Read the definition file. + + +.. index:: --dllname (dlltool) + +:samp:`--dllname {name}` + Gives the name of the DLL. This switch is used to embed the name of the + DLL in the static import library generated by `dlltool` with switch + *--output-lib*. + + +.. index:: -k (dlltool) + +:samp:`-k` + Kill :samp:`@{nn}` from exported names + (:ref:`Windows_Calling_Conventions` + for a discussion about `Stdcall`-style symbols. + + +.. index:: --help (dlltool) + +:samp:`--help` + Prints the `dlltool` switches with a concise description. + + +.. index:: --output-exp (dlltool) + +:samp:`--output-exp {exportfile}` + Generate an export file `exportfile`. The export file contains the + export table (list of symbols in the DLL) and is used to create the DLL. + + +.. index:: --output-lib (dlltool) + +:samp:`--output-lib {libfile}` + Generate a static import library `libfile`. + + +.. index:: -v (dlltool) + +:samp:`-v` + Verbose mode. + + +.. index:: --as (dlltool) + +:samp:`--as {assembler-name}` + Use `assembler-name` as the assembler. The default is `as`. + + +.. _GNAT_and_Windows_Resources: + +GNAT and Windows Resources +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: Resources, windows + +Resources are an easy way to add Windows specific objects to your +application. The objects that can be added as resources include: + +* menus + +* accelerators + +* dialog boxes + +* string tables + +* bitmaps + +* cursors + +* icons + +* fonts + +* version information + +For example, a version information resource can be defined as follow and +embedded into an executable or DLL: + +A version information resource can be used to embed information into an +executable or a DLL. These information can be viewed using the file properties +from the Windows Explorer. Here is an example of a version information +resource: + + :: + + 1 VERSIONINFO + FILEVERSION 1,0,0,0 + PRODUCTVERSION 1,0,0,0 + BEGIN + BLOCK "StringFileInfo" + BEGIN + BLOCK "080904E4" + BEGIN + VALUE "CompanyName", "My Company Name" + VALUE "FileDescription", "My application" + VALUE "FileVersion", "1.0" + VALUE "InternalName", "my_app" + VALUE "LegalCopyright", "My Name" + VALUE "OriginalFilename", "my_app.exe" + VALUE "ProductName", "My App" + VALUE "ProductVersion", "1.0" + END + END + + BLOCK "VarFileInfo" + BEGIN + VALUE "Translation", 0x809, 1252 + END + END + +The value `0809` (langID) is for the U.K English language and +`04E4` (charsetID), which is equal to `1252` decimal, for +multilingual. + +This section explains how to build, compile and use resources. Note that this +section does not cover all resource objects, for a complete description see +the corresponding Microsoft documentation. + + +.. _Building_Resources: + +Building Resources +"""""""""""""""""" + +.. index:: Resources, building + +A resource file is an ASCII file. By convention resource files have an +:file:`.rc` extension. +The easiest way to build a resource file is to use Microsoft tools +such as `imagedit.exe` to build bitmaps, icons and cursors and +`dlgedit.exe` to build dialogs. +It is always possible to build an :file:`.rc` file yourself by writing a +resource script. + +It is not our objective to explain how to write a resource file. A +complete description of the resource script language can be found in the +Microsoft documentation. + + +.. _Compiling_Resources: + +Compiling Resources +""""""""""""""""""" + +.. index:: rc +.. index:: windres +.. index:: Resources, compiling + +This section describes how to build a GNAT-compatible (COFF) object file +containing the resources. This is done using the Resource Compiler +`windres` as follows: + + :: + + $ windres -i myres.rc -o myres.o + +By default `windres` will run *gcc* to preprocess the :file:`.rc` +file. You can specify an alternate preprocessor (usually named +:file:`cpp.exe`) using the `windres` *--preprocessor* +parameter. A list of all possible options may be obtained by entering +the command `windres` *--help*. + +It is also possible to use the Microsoft resource compiler `rc.exe` +to produce a :file:`.res` file (binary resource file). See the +corresponding Microsoft documentation for further details. In this case +you need to use `windres` to translate the :file:`.res` file to a +GNAT-compatible object file as follows: + + :: + + $ windres -i myres.res -o myres.o + + +.. _Using_Resources: + +Using Resources +""""""""""""""" + +.. index:: Resources, using + +To include the resource file in your program just add the +GNAT-compatible object file for the resource(s) to the linker +arguments. With *gnatmake* this is done by using the *-largs* +option: + + :: + + $ gnatmake myprog -largs myres.o + + +.. _Debugging_a_DLL: + +Debugging a DLL +^^^^^^^^^^^^^^^ + +.. index:: DLL debugging + +Debugging a DLL is similar to debugging a standard program. But +we have to deal with two different executable parts: the DLL and the +program that uses it. We have the following four possibilities: + +* The program and the DLL are built with `GCC/GNAT`. +* The program is built with foreign tools and the DLL is built with + `GCC/GNAT`. +* The program is built with `GCC/GNAT` and the DLL is built with + foreign tools. + +In this section we address only cases one and two above. +There is no point in trying to debug +a DLL with `GNU/GDB`, if there is no GDB-compatible debugging +information in it. To do so you must use a debugger compatible with the +tools suite used to build the DLL. + +.. _Program_and_DLL_Both_Built_with_GCC/GNAT: + +Program and DLL Both Built with GCC/GNAT +"""""""""""""""""""""""""""""""""""""""" + +This is the simplest case. Both the DLL and the program have `GDB` +compatible debugging information. It is then possible to break anywhere in +the process. Let's suppose here that the main procedure is named +`ada_main` and that in the DLL there is an entry point named +`ada_dll`. + +The DLL (:ref:`Introduction_to_Dynamic_Link_Libraries_DLLs`) and +program must have been built with the debugging information (see GNAT -g +switch). Here are the step-by-step instructions for debugging it: + +* Launch `GDB` on the main program. + + :: + + $ gdb -nw ada_main + +* Start the program and stop at the beginning of the main procedure + + :: + + (gdb) start + + This step is required to be able to set a breakpoint inside the DLL. As long + as the program is not run, the DLL is not loaded. This has the + consequence that the DLL debugging information is also not loaded, so it is not + possible to set a breakpoint in the DLL. + +* Set a breakpoint inside the DLL + + :: + + (gdb) break ada_dll + (gdb) cont + +At this stage a breakpoint is set inside the DLL. From there on +you can use the standard approach to debug the whole program +(:ref:`Running_and_Debugging_Ada_Programs`). + + +.. _Program_Built_with_Foreign_Tools_and_DLL_Built_with_GCC/GNAT: + +Program Built with Foreign Tools and DLL Built with GCC/GNAT +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +In this case things are slightly more complex because it is not possible to +start the main program and then break at the beginning to load the DLL and the +associated DLL debugging information. It is not possible to break at the +beginning of the program because there is no `GDB` debugging information, +and therefore there is no direct way of getting initial control. This +section addresses this issue by describing some methods that can be used +to break somewhere in the DLL to debug it. + +First suppose that the main procedure is named `main` (this is for +example some C code built with Microsoft Visual C) and that there is a +DLL named `test.dll` containing an Ada entry point named +`ada_dll`. + +The DLL (see :ref:`Introduction_to_Dynamic_Link_Libraries_DLLs`) must have +been built with debugging information (see GNAT `-g` option). + + +.. rubric:: Debugging the DLL Directly + +* Find out the executable starting address + + :: + + $ objdump --file-header main.exe + + The starting address is reported on the last line. For example: + + :: + + main.exe: file format pei-i386 + architecture: i386, flags 0x0000010a: + EXEC_P, HAS_DEBUG, D_PAGED + start address 0x00401010 + +* Launch the debugger on the executable. + + :: + + $ gdb main.exe + +* Set a breakpoint at the starting address, and launch the program. + + :: + + $ (gdb) break *0x00401010 + $ (gdb) run + + The program will stop at the given address. + +* Set a breakpoint on a DLL subroutine. + + :: + + (gdb) break ada_dll.adb:45 + + Or if you want to break using a symbol on the DLL, you need first to + select the Ada language (language used by the DLL). + + :: + + (gdb) set language ada + (gdb) break ada_dll + +* Continue the program. + + :: + + (gdb) cont + + This will run the program until it reaches the breakpoint that has been + set. From that point you can use the standard way to debug a program + as described in (:ref:`Running_and_Debugging_Ada_Programs`). + +It is also possible to debug the DLL by attaching to a running process. + + +.. rubric:: Attaching to a Running Process + +.. index:: DLL debugging, attach to process + +With `GDB` it is always possible to debug a running process by +attaching to it. It is possible to debug a DLL this way. The limitation +of this approach is that the DLL must run long enough to perform the +attach operation. It may be useful for instance to insert a time wasting +loop in the code of the DLL to meet this criterion. + +* Launch the main program :file:`main.exe`. + + :: + + $ main + +* Use the Windows *Task Manager* to find the process ID. Let's say + that the process PID for :file:`main.exe` is 208. + +* Launch gdb. + + :: + + $ gdb + +* Attach to the running process to be debugged. + + :: + + (gdb) attach 208 + +* Load the process debugging information. + + :: + + (gdb) symbol-file main.exe + +* Break somewhere in the DLL. + + :: + + (gdb) break ada_dll + +* Continue process execution. + + :: + + (gdb) cont + +This last step will resume the process execution, and stop at +the breakpoint we have set. From there you can use the standard +approach to debug a program as described in +:ref:`Running_and_Debugging_Ada_Programs`. + + +.. _Setting_Stack_Size_from_gnatlink: + +Setting Stack Size from *gnatlink* +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is possible to specify the program stack size at link time. On modern +versions of Windows, starting with XP, this is mostly useful to set the size of +the main stack (environment task). The other task stacks are set with pragma +Storage_Size or with the *gnatbind -d* command. + +Since older versions of Windows (2000, NT4, etc.) do not allow setting the +reserve size of individual tasks, the link-time stack size applies to all +tasks, and pragma Storage_Size has no effect. +In particular, Stack Overflow checks are made against this +link-time specified size. + +This setting can be done with *gnatlink* using either of the following: + + +* *-Xlinker* linker option + + :: + + $ gnatlink hello -Xlinker --stack=0x10000,0x1000 + + + This sets the stack reserve size to 0x10000 bytes and the stack commit + size to 0x1000 bytes. + +* *-Wl* linker option + + :: + + $ gnatlink hello -Wl,--stack=0x1000000 + + This sets the stack reserve size to 0x1000000 bytes. Note that with + *-Wl* option it is not possible to set the stack commit size + because the coma is a separator for this option. + + +.. _Setting_Heap_Size_from_gnatlink: + +Setting Heap Size from *gnatlink* +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Under Windows systems, it is possible to specify the program heap size from +*gnatlink* using either of the following: + +* *-Xlinker* linker option + + :: + + $ gnatlink hello -Xlinker --heap=0x10000,0x1000 + + This sets the heap reserve size to 0x10000 bytes and the heap commit + size to 0x1000 bytes. + +* *-Wl* linker option + + :: + + $ gnatlink hello -Wl,--heap=0x1000000 + + + This sets the heap reserve size to 0x1000000 bytes. Note that with + *-Wl* option it is not possible to set the heap commit size + because the coma is a separator for this option. + + +.. _Mac_OS_Topics: + +Mac OS Topics +============= + +.. index:: OS X + +This section describes topics that are specific to Apple's OS X +platform. + +Codesigning the Debugger +------------------------ + +The Darwin Kernel requires the debugger to have special permissions +before it is allowed to control other processes. These permissions +are granted by codesigning the GDB executable. Without these +permissions, the debugger will report error messages such as:: + + Starting program: /x/y/foo + Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5). + (please check gdb is codesigned - see taskgated(8)) + +Codesigning requires a certificate. The following procedure explains +how to create one: + +* Start the Keychain Access application (in + /Applications/Utilities/Keychain Access.app) + +* Select the Keychain Access -> Certificate Assistant -> + Create a Certificate... menu + +* Then: + + * Choose a name for the new certificate (this procedure will use + "gdb-cert" as an example) + + * Set "Identity Type" to "Self Signed Root" + + * Set "Certificate Type" to "Code Signing" + + * Activate the "Let me override defaults" option + + +* Click several times on "Continue" until the "Specify a Location + For The Certificate" screen appears, then set "Keychain" to "System" + +* Click on "Continue" until the certificate is created + +* Finally, in the view, double-click on the new certificate, + and set "When using this certificate" to "Always Trust" + +* Exit the Keychain Access application and restart the computer + (this is unfortunately required) + + +Once a certificate has been created, the debugger can be codesigned +as follow. In a Terminal, run the following command: + + :: + + $ codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb + +where "gdb-cert" should be replaced by the actual certificate +name chosen above, and <gnat_install_prefix> should be replaced by +the location where you installed GNAT. Also, be sure that users are +in the Unix group ``_developer``. + + diff --git a/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst new file mode 100644 index 00000000000..30eb860789e --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst @@ -0,0 +1,4846 @@ +.. |with| replace:: *with* +.. |withs| replace:: *with*\ s +.. |withed| replace:: *with*\ ed +.. |withing| replace:: *with*\ ing + +.. -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit + + +.. _The_GNAT_Compilation_Model: + +************************** +The GNAT Compilation Model +************************** + +.. index:: ! GNAT compilation model + +.. index:: Compilation model + +This chapter describes the compilation model used by GNAT. Although +similar to that used by other languages such as C and C++, this model +is substantially different from the traditional Ada compilation models, +which are based on a centralized program library. The chapter covers +the following material: + +* Topics related to source file makeup and naming + + * :ref:`Source_Representation` + * :ref:`Foreign_Language_Representation` + * :ref:`File_Naming_Topics_and_Utilities` + +* :ref:`Configuration_Pragmas` +* :ref:`Generating_Object_Files` +* :ref:`Source_Dependencies` +* :ref:`The_Ada_Library_Information_Files` +* :ref:`Binding_an_Ada_Program` +* :ref:`GNAT_and_Libraries` +* :ref:`Conditional_Compilation` +* :ref:`Mixed_Language_Programming` +* :ref:`GNAT_and_Other_Compilation_Models` +* :ref:`Using_GNAT_Files_with_External_Tools` + + +.. _Source_Representation: + +Source Representation +===================== + +.. index:: Latin-1 + +.. index:: VT, HT, CR, LF, FF + +Ada source programs are represented in standard text files, using +Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar +7-bit ASCII set, plus additional characters used for +representing foreign languages (see :ref:`Foreign_Language_Representation` +for support of non-USA character sets). The format effector characters +are represented using their standard ASCII encodings, as follows: + + =========== ======================= ========= + Character Effect Code + ----------- ----------------------- --------- + :kbd:`VT` Vertical tab `16#0B#` + :kbd:`HT` Horizontal tab `16#09#` + :kbd:`CR` Carriage return `16#0D#` + :kbd:`LF` Line feed `16#0A#` + :kbd:`FF` Form feed `16#0C#` + =========== ======================= ========= + +Source files are in standard text file format. In addition, GNAT will +recognize a wide variety of stream formats, in which the end of +physical lines is marked by any of the following sequences: +`LF`, `CR`, `CR-LF`, or `LF-CR`. This is useful +in accommodating files that are imported from other operating systems. + +.. index:: pair: End of source file; Source file, end + +.. index:: SUB (control character) + +The end of a source file is normally represented by the physical end of +file. However, the control character `16#1A#` (:kbd:`SUB`) is also +recognized as signalling the end of the source file. Again, this is +provided for compatibility with other operating systems where this +code is used to represent the end of file. + +.. index:: spec (definition), compilation (definition) + +Each file contains a single Ada compilation unit, including any pragmas +associated with the unit. For example, this means you must place a +package declaration (a package `spec`) and the corresponding body in +separate files. An Ada `compilation` (which is a sequence of +compilation units) is represented using a sequence of files. Similarly, +you will place each subunit or child unit in a separate file. + +.. _Foreign_Language_Representation: + +Foreign Language Representation +=============================== + +GNAT supports the standard character sets defined in Ada as well as +several other non-standard character sets for use in localized versions +of the compiler (:ref:`Character_Set_Control`). + +.. _Latin-1: + +Latin-1 +------- + +.. index:: Latin-1 + +The basic character set is Latin-1. This character set is defined by ISO +standard 8859, part 1. The lower half (character codes `16#00#` +... `16#7F#)` is identical to standard ASCII coding, but the upper +half is used to represent additional characters. These include extended letters +used by European languages, such as French accents, the vowels with umlauts +used in German, and the extra letter A-ring used in Swedish. + +.. index:: Ada.Characters.Latin_1 + +For a complete list of Latin-1 codes and their encodings, see the source +file of library unit `Ada.Characters.Latin_1` in file +:file:`a-chlat1.ads`. +You may use any of these extended characters freely in character or +string literals. In addition, the extended characters that represent +letters can be used in identifiers. + +.. _Other_8-Bit_Codes: + +Other 8-Bit Codes +----------------- + +GNAT also supports several other 8-bit coding schemes: + + +.. index:: Latin-2 +.. index:: ISO 8859-2 + +*ISO 8859-2 (Latin-2)* + Latin-2 letters allowed in identifiers, with uppercase and lowercase + equivalence. + +.. index:: Latin-3 +.. index:: ISO 8859-3 + +*ISO 8859-3 (Latin-3)* + Latin-3 letters allowed in identifiers, with uppercase and lowercase + equivalence. + + +.. index:: Latin-4 +.. index:: ISO 8859-4 + +*ISO 8859-4 (Latin-4)* + Latin-4 letters allowed in identifiers, with uppercase and lowercase + equivalence. + + +.. index:: ISO 8859-5 +.. index:: Cyrillic + +*ISO 8859-5 (Cyrillic)* + ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and + lowercase equivalence. + +.. index:: ISO 8859-15 +.. index:: Latin-9 + +*ISO 8859-15 (Latin-9)* + ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and + lowercase equivalence + +.. index:: code page 437 (IBM PC) + +*IBM PC (code page 437)* + This code page is the normal default for PCs in the U.S. It corresponds + to the original IBM PC character set. This set has some, but not all, of + the extended Latin-1 letters, but these letters do not have the same + encoding as Latin-1. In this mode, these letters are allowed in + identifiers with uppercase and lowercase equivalence. + +.. index:: code page 850 (IBM PC) + +*IBM PC (code page 850)* + This code page is a modification of 437 extended to include all the + Latin-1 letters, but still not with the usual Latin-1 encoding. In this + mode, all these letters are allowed in identifiers with uppercase and + lowercase equivalence. + + +*Full Upper 8-bit* + Any character in the range 80-FF allowed in identifiers, and all are + considered distinct. In other words, there are no uppercase and lowercase + equivalences in this range. This is useful in conjunction with + certain encoding schemes used for some foreign character sets (e.g., + the typical method of representing Chinese characters on the PC). + + +*No Upper-Half* + No upper-half characters in the range 80-FF are allowed in identifiers. + This gives Ada 83 compatibility for identifier names. + +For precise data on the encodings permitted, and the uppercase and lowercase +equivalences that are recognized, see the file :file:`csets.adb` in +the GNAT compiler sources. You will need to obtain a full source release +of GNAT to obtain this file. + +.. _Wide_Character_Encodings: + +Wide_Character Encodings +------------------------ + +GNAT allows wide character codes to appear in character and string +literals, and also optionally in identifiers, by means of the following +possible encoding schemes: + +*Hex Coding* + In this encoding, a wide character is represented by the following five + character sequence:: + + ESC a b c d + + where `a`, `b`, `c`, `d` are the four hexadecimal + characters (using uppercase letters) of the wide character code. For + example, ESC A345 is used to represent the wide character with code + `16#A345#`. + This scheme is compatible with use of the full Wide_Character set. + +*Upper-Half Coding* + .. index:: Upper-Half Coding + + The wide character with encoding `16#abcd#` where the upper bit is on + (in other words, 'a' is in the range 8-F) is represented as two bytes, + `16#ab#` and `16#cd#`. The second byte cannot be a format control + character, but is not required to be in the upper half. This method can + be also used for shift-JIS or EUC, where the internal coding matches the + external coding. + +*Shift JIS Coding* + .. index:: Shift JIS Coding + + A wide character is represented by a two-character sequence, + `16#ab#` and + `16#cd#`, with the restrictions described for upper-half encoding as + described above. The internal character code is the corresponding JIS + character according to the standard algorithm for Shift-JIS + conversion. Only characters defined in the JIS code set table can be + used with this encoding method. + + +*EUC Coding* + .. index:: EUC Coding + + A wide character is represented by a two-character sequence + `16#ab#` and + `16#cd#`, with both characters being in the upper half. The internal + character code is the corresponding JIS character according to the EUC + encoding algorithm. Only characters defined in the JIS code set table + can be used with this encoding method. + + +*UTF-8 Coding* + A wide character is represented using + UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO + 10646-1/Am.2. Depending on the character value, the representation + is a one, two, or three byte sequence:: + + 16#0000#-16#007f#: 2#0`xxxxxxx`# + 16#0080#-16#07ff#: 2#110`xxxxx`# 2#10`xxxxxx`# + 16#0800#-16#ffff#: 2#1110`xxxx`# 2#10`xxxxxx`# 2#10`xxxxxx`# + + where the `xxx` bits correspond to the left-padded bits of the + 16-bit character value. Note that all lower half ASCII characters + are represented as ASCII bytes and all upper half characters and + other wide characters are represented as sequences of upper-half + (The full UTF-8 scheme allows for encoding 31-bit characters as + 6-byte sequences, and in the following section on wide wide + characters, the use of these sequences is documented). + + +*Brackets Coding* + In this encoding, a wide character is represented by the following eight + character sequence:: + + [ " a b c d " ] + + where `a`, `b`, `c`, `d` are the four hexadecimal + characters (using uppercase letters) of the wide character code. For + example, ['A345'] is used to represent the wide character with code + `16#A345#`. It is also possible (though not required) to use the + Brackets coding for upper half characters. For example, the code + `16#A3#` can be represented as `['A3']`. + + This scheme is compatible with use of the full Wide_Character set, + and is also the method used for wide character encoding in some standard + ACATS (Ada Conformity Assessment Test Suite) test suite distributions. + +.. note:: + + Some of these coding schemes do not permit the full use of the + Ada character set. For example, neither Shift JIS nor EUC allow the + use of the upper half of the Latin-1 set. + +.. _Wide_Wide_Character_Encodings: + +Wide_Wide_Character Encodings +----------------------------- + +GNAT allows wide wide character codes to appear in character and string +literals, and also optionally in identifiers, by means of the following +possible encoding schemes: + +*UTF-8 Coding* + A wide character is represented using + UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO + 10646-1/Am.2. Depending on the character value, the representation + of character codes with values greater than 16#FFFF# is a + is a four, five, or six byte sequence:: + + 16#01_0000#-16#10_FFFF#: 11110xxx 10xxxxxx 10xxxxxx + 10xxxxxx + 16#0020_0000#-16#03FF_FFFF#: 111110xx 10xxxxxx 10xxxxxx + 10xxxxxx 10xxxxxx + 16#0400_0000#-16#7FFF_FFFF#: 1111110x 10xxxxxx 10xxxxxx + 10xxxxxx 10xxxxxx 10xxxxxx + + + where the `xxx` bits correspond to the left-padded bits of the + 32-bit character value. + +*Brackets Coding* + In this encoding, a wide wide character is represented by the following ten or + twelve byte character sequence:: + + [ " a b c d e f " ] + [ " a b c d e f g h " ] + + where `a-h` are the six or eight hexadecimal + characters (using uppercase letters) of the wide wide character code. For + example, ["1F4567"] is used to represent the wide wide character with code + `16#001F_4567#`. + + This scheme is compatible with use of the full Wide_Wide_Character set, + and is also the method used for wide wide character encoding in some standard + ACATS (Ada Conformity Assessment Test Suite) test suite distributions. + + +.. _File_Naming_Topics_and_Utilities: + +File Naming Topics and Utilities +================================ + +GNAT has a default file naming scheme and also provides the user with +a high degree of control over how the names and extensions of the +source files correspond to the Ada compilation units that they contain. + + +.. _File_Naming_Rules: + +File Naming Rules +----------------- + +The default file name is determined by the name of the unit that the +file contains. The name is formed by taking the full expanded name of +the unit and replacing the separating dots with hyphens and using +lowercase for all letters. + +An exception arises if the file name generated by the above rules starts +with one of the characters +`a`, `g`, `i`, or `s`, and the second character is a +minus. In this case, the character tilde is used in place +of the minus. The reason for this special rule is to avoid clashes with +the standard names for child units of the packages System, Ada, +Interfaces, and GNAT, which use the prefixes +`s-`, `a-`, `i-`, and `g-`, +respectively. + +The file extension is :file:`.ads` for a spec and +:file:`.adb` for a body. The following table shows some +examples of these rules. + + ============================ =============================== + Source File Ada Compilation Unit + ---------------------------- ------------------------------- + :file:`main.ads` Main (spec) + :file:`main.adb` Main (body) + :file:`arith_functions.ads` Arith_Functions (package spec) + :file:`arith_functions.adb` Arith_Functions (package body) + :file:`func-spec.ads` Func.Spec (child package spec) + :file:`func-spec.adb` Func.Spec (child package body) + :file:`main-sub.adb` Sub (subunit of Main) + :file:`a~bad.adb` A.Bad (child package body) + ============================ =============================== + +Following these rules can result in excessively long +file names if corresponding +unit names are long (for example, if child units or subunits are +heavily nested). An option is available to shorten such long file names +(called file name 'krunching'). This may be particularly useful when +programs being developed with GNAT are to be used on operating systems +with limited file name lengths. :ref:`Using_gnatkr`. + +Of course, no file shortening algorithm can guarantee uniqueness over +all possible unit names; if file name krunching is used, it is your +responsibility to ensure no name clashes occur. Alternatively you +can specify the exact file names that you want used, as described +in the next section. Finally, if your Ada programs are migrating from a +compiler with a different naming convention, you can use the gnatchop +utility to produce source files that follow the GNAT naming conventions. +(For details see :ref:`Renaming_Files_with_gnatchop`.) + +Note: in the case of Windows or Mac OS operating systems, case is not +significant. So for example on `Windows` if the canonical name is +`main-sub.adb`, you can use the file name :file:`Main-Sub.adb` instead. +However, case is significant for other operating systems, so for example, +if you want to use other than canonically cased file names on a Unix system, +you need to follow the procedures described in the next section. + +.. _Using_Other_File_Names: + +Using Other File Names +---------------------- + +.. index:: File names + +In the previous section, we have described the default rules used by +GNAT to determine the file name in which a given unit resides. It is +often convenient to follow these default rules, and if you follow them, +the compiler knows without being explicitly told where to find all +the files it needs. + +.. index:: Source_File_Name pragma + +However, in some cases, particularly when a program is imported from +another Ada compiler environment, it may be more convenient for the +programmer to specify which file names contain which units. GNAT allows +arbitrary file names to be used by means of the Source_File_Name pragma. +The form of this pragma is as shown in the following examples: + +.. code-block:: ada + + pragma Source_File_Name (My_Utilities.Stacks, + Spec_File_Name => "myutilst_a.ada"); + pragma Source_File_name (My_Utilities.Stacks, + Body_File_Name => "myutilst.ada"); + +As shown in this example, the first argument for the pragma is the unit +name (in this example a child unit). The second argument has the form +of a named association. The identifier +indicates whether the file name is for a spec or a body; +the file name itself is given by a string literal. + +The source file name pragma is a configuration pragma, which means that +normally it will be placed in the :file:`gnat.adc` +file used to hold configuration +pragmas that apply to a complete compilation environment. +For more details on how the :file:`gnat.adc` file is created and used +see :ref:`Handling_of_Configuration_Pragmas`. + +.. index:: gnat.adc + +GNAT allows completely arbitrary file names to be specified using the +source file name pragma. However, if the file name specified has an +extension other than :file:`.ads` or :file:`.adb` it is necessary to use +a special syntax when compiling the file. The name in this case must be +preceded by the special sequence *-x* followed by a space and the name +of the language, here `ada`, as in: + +.. code-block:: sh + + $ gcc -c -x ada peculiar_file_name.sim + +`gnatmake` handles non-standard file names in the usual manner (the +non-standard file name for the main program is simply used as the +argument to gnatmake). Note that if the extension is also non-standard, +then it must be included in the `gnatmake` command, it may not +be omitted. + +.. _Alternative_File_Naming_Schemes: + +Alternative File Naming Schemes +------------------------------- + +.. index:: File naming schemes, alternative + +.. index:: File names + +The previous section described the use of the `Source_File_Name` +pragma to allow arbitrary names to be assigned to individual source files. +However, this approach requires one pragma for each file, and especially in +large systems can result in very long :file:`gnat.adc` files, and also create +a maintenance problem. + +.. index:: Source_File_Name pragma + +GNAT also provides a facility for specifying systematic file naming schemes +other than the standard default naming scheme previously described. An +alternative scheme for naming is specified by the use of +`Source_File_Name` pragmas having the following format: + +.. code-block:: ada + + pragma Source_File_Name ( + Spec_File_Name => FILE_NAME_PATTERN + [ , Casing => CASING_SPEC] + [ , Dot_Replacement => STRING_LITERAL ] ); + + pragma Source_File_Name ( + Body_File_Name => FILE_NAME_PATTERN + [ , Casing => CASING_SPEC ] + [ , Dot_Replacement => STRING_LITERAL ] ) ; + + pragma Source_File_Name ( + Subunit_File_Name => FILE_NAME_PATTERN + [ , Casing => CASING_SPEC ] + [ , Dot_Replacement => STRING_LITERAL ] ) ; + + FILE_NAME_PATTERN ::= STRING_LITERAL + CASING_SPEC ::= Lowercase | Uppercase | Mixedcase + +The `FILE_NAME_PATTERN` string shows how the file name is constructed. +It contains a single asterisk character, and the unit name is substituted +systematically for this asterisk. The optional parameter +`Casing` indicates +whether the unit name is to be all upper-case letters, all lower-case letters, +or mixed-case. If no +`Casing` parameter is used, then the default is all +lower-case. + +The optional `Dot_Replacement` string is used to replace any periods +that occur in subunit or child unit names. If no `Dot_Replacement` +argument is used then separating dots appear unchanged in the resulting +file name. +Although the above syntax indicates that the +`Casing` argument must appear +before the `Dot_Replacement` argument, but it +is also permissible to write these arguments in the opposite order. + +As indicated, it is possible to specify different naming schemes for +bodies, specs, and subunits. Quite often the rule for subunits is the +same as the rule for bodies, in which case, there is no need to give +a separate `Subunit_File_Name` rule, and in this case the +`Body_File_name` rule is used for subunits as well. + +The separate rule for subunits can also be used to implement the rather +unusual case of a compilation environment (e.g., a single directory) which +contains a subunit and a child unit with the same unit name. Although +both units cannot appear in the same partition, the Ada Reference Manual +allows (but does not require) the possibility of the two units coexisting +in the same environment. + +The file name translation works in the following steps: + +* If there is a specific `Source_File_Name` pragma for the given unit, + then this is always used, and any general pattern rules are ignored. + +* If there is a pattern type `Source_File_Name` pragma that applies to + the unit, then the resulting file name will be used if the file exists. If + more than one pattern matches, the latest one will be tried first, and the + first attempt resulting in a reference to a file that exists will be used. + +* If no pattern type `Source_File_Name` pragma that applies to the unit + for which the corresponding file exists, then the standard GNAT default + naming rules are used. + +As an example of the use of this mechanism, consider a commonly used scheme +in which file names are all lower case, with separating periods copied +unchanged to the resulting file name, and specs end with :file:`.1.ada`, and +bodies end with :file:`.2.ada`. GNAT will follow this scheme if the following +two pragmas appear: + +.. code-block:: ada + + pragma Source_File_Name + (Spec_File_Name => ".1.ada"); + pragma Source_File_Name + (Body_File_Name => ".2.ada"); + +The default GNAT scheme is actually implemented by providing the following +default pragmas internally: + +.. code-block:: ada + + pragma Source_File_Name + (Spec_File_Name => ".ads", Dot_Replacement => "-"); + pragma Source_File_Name + (Body_File_Name => ".adb", Dot_Replacement => "-"); + +Our final example implements a scheme typically used with one of the +Ada 83 compilers, where the separator character for subunits was '__' +(two underscores), specs were identified by adding :file:`_.ADA`, bodies +by adding :file:`.ADA`, and subunits by +adding :file:`.SEP`. All file names were +upper case. Child units were not present of course since this was an +Ada 83 compiler, but it seems reasonable to extend this scheme to use +the same double underscore separator for child units. + +.. code-block:: ada + + pragma Source_File_Name + (Spec_File_Name => "_.ADA", + Dot_Replacement => "__", + Casing = Uppercase); + pragma Source_File_Name + (Body_File_Name => ".ADA", + Dot_Replacement => "__", + Casing = Uppercase); + pragma Source_File_Name + (Subunit_File_Name => ".SEP", + Dot_Replacement => "__", + Casing = Uppercase); + + +.. index:: ! gnatname + +.. _Handling_Arbitrary_File_Naming_Conventions_with_gnatname: + +Handling Arbitrary File Naming Conventions with `gnatname` +---------------------------------------------------------- + +.. index:: File Naming Conventions + +.. _Arbitrary_File_Naming_Conventions: + +Arbitrary File Naming Conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The GNAT compiler must be able to know the source file name of a compilation +unit. When using the standard GNAT default file naming conventions +(`.ads` for specs, `.adb` for bodies), the GNAT compiler +does not need additional information. + +When the source file names do not follow the standard GNAT default file naming +conventions, the GNAT compiler must be given additional information through +a configuration pragmas file (:ref:`Configuration_Pragmas`) +or a project file. +When the non-standard file naming conventions are well-defined, +a small number of pragmas `Source_File_Name` specifying a naming pattern +(:ref:`Alternative_File_Naming_Schemes`) may be sufficient. However, +if the file naming conventions are irregular or arbitrary, a number +of pragma `Source_File_Name` for individual compilation units +must be defined. +To help maintain the correspondence between compilation unit names and +source file names within the compiler, +GNAT provides a tool `gnatname` to generate the required pragmas for a +set of files. + +.. _Running_gnatname: + +Running `gnatname` +^^^^^^^^^^^^^^^^^^ + +The usual form of the `gnatname` command is: + +.. code-block:: sh + + $ gnatname [`switches`] `naming_pattern` [`naming_patterns`] + [--and [`switches`] `naming_pattern` [`naming_patterns`]] + + +All of the arguments are optional. If invoked without any argument, +`gnatname` will display its usage. + +When used with at least one naming pattern, `gnatname` will attempt to +find all the compilation units in files that follow at least one of the +naming patterns. To find these compilation units, +`gnatname` will use the GNAT compiler in syntax-check-only mode on all +regular files. + +One or several Naming Patterns may be given as arguments to `gnatname`. +Each Naming Pattern is enclosed between double quotes (or single +quotes on Windows). +A Naming Pattern is a regular expression similar to the wildcard patterns +used in file names by the Unix shells or the DOS prompt. + +`gnatname` may be called with several sections of directories/patterns. +Sections are separated by switch `--and`. In each section, there must be +at least one pattern. If no directory is specified in a section, the current +directory (or the project directory is `-P` is used) is implied. +The options other that the directory switches and the patterns apply globally +even if they are in different sections. + +Examples of Naming Patterns are:: + + "*.[12].ada" + "*.ad[sb]*" + "body_*" "spec_*" + +For a more complete description of the syntax of Naming Patterns, +see the second kind of regular expressions described in :file:`g-regexp.ads` +(the 'Glob' regular expressions). + +When invoked with no switch `-P`, `gnatname` will create a +configuration pragmas file :file:`gnat.adc` in the current working directory, +with pragmas `Source_File_Name` for each file that contains a valid Ada +unit. + +.. _Switches_for_gnatname: + +Switches for `gnatname` +^^^^^^^^^^^^^^^^^^^^^^^ + +Switches for `gnatname` must precede any specified Naming Pattern. + +You may specify any of the following switches to `gnatname`: + +.. index:: --version (gnatname) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + +.. index:: --help (gnatname) + +:samp:`--help` + If *--version* was not used, display usage, then exit disregarding + all other options. + +:samp:`--subdirs={dir}` + Real object, library or exec directories are subdirectories <dir> of the + specified ones. + +:samp:`--no-backup` + Do not create a backup copy of an existing project file. + +:samp:`--and` + Start another section of directories/patterns. + +.. index:: -c (gnatname) + +:samp:`-c{filename}` + Create a configuration pragmas file :file:`filename` (instead of the default + :file:`gnat.adc`). + There may be zero, one or more space between *-c* and + :file:`filename`. + :file:`filename` may include directory information. :file:`filename` must be + writable. There may be only one switch *-c*. + When a switch *-c* is + specified, no switch *-P* may be specified (see below). + +.. index:: -d (gnatname) + +:samp:`-d{dir}` + Look for source files in directory :file:`dir`. There may be zero, one or more + spaces between *-d* and :file:`dir`. + :file:`dir` may end with `/**`, that is it may be of the form + `root_dir/**`. In this case, the directory `root_dir` and all of its + subdirectories, recursively, have to be searched for sources. + When a switch *-d* + is specified, the current working directory will not be searched for source + files, unless it is explicitly specified with a *-d* + or *-D* switch. + Several switches *-d* may be specified. + If :file:`dir` is a relative path, it is relative to the directory of + the configuration pragmas file specified with switch + *-c*, + or to the directory of the project file specified with switch + *-P* or, + if neither switch *-c* + nor switch *-P* are specified, it is relative to the + current working directory. The directory + specified with switch *-d* must exist and be readable. + +.. index:: -D (gnatname) + +:samp:`-D{filename}` + Look for source files in all directories listed in text file :file:`filename`. + There may be zero, one or more spaces between *-D* + and :file:`filename`. + :file:`filename` must be an existing, readable text file. + Each nonempty line in :file:`filename` must be a directory. + Specifying switch *-D* is equivalent to specifying as many + switches *-d* as there are nonempty lines in + :file:`file`. + +:samp:`-eL` + Follow symbolic links when processing project files. + + .. index:: -f (gnatname) + +:samp:`-f{pattern}` + Foreign patterns. Using this switch, it is possible to add sources of languages + other than Ada to the list of sources of a project file. + It is only useful if a -P switch is used. + For example, + + .. code-block:: sh + + gnatname -Pprj -f"*.c" "*.ada" + + will look for Ada units in all files with the :file:`.ada` extension, + and will add to the list of file for project :file:`prj.gpr` the C files + with extension :file:`.c`. + + .. index:: -h (gnatname) + +:samp:`-h` + Output usage (help) information. The output is written to :file:`stdout`. + + .. index:: -P (gnatname) + +:samp:`-P{proj}` + Create or update project file :file:`proj`. There may be zero, one or more space + between *-P* and :file:`proj`. :file:`proj` may include directory + information. :file:`proj` must be writable. + There may be only one switch *-P*. + When a switch *-P* is specified, + no switch *-c* may be specified. + On all platforms, except on VMS, when `gnatname` is invoked for an + existing project file <proj>.gpr, a backup copy of the project file is created + in the project directory with file name <proj>.gpr.saved_x. 'x' is the first + non negative number that makes this backup copy a new file. + + .. index:: -v (gnatname) + +:samp:`-v` + Verbose mode. Output detailed explanation of behavior to :file:`stdout`. + This includes name of the file written, the name of the directories to search + and, for each file in those directories whose name matches at least one of + the Naming Patterns, an indication of whether the file contains a unit, + and if so the name of the unit. + +.. index:: -v -v (gnatname) + +:samp:`-v -v` + Very Verbose mode. In addition to the output produced in verbose mode, + for each file in the searched directories whose name matches none of + the Naming Patterns, an indication is given that there is no match. + + .. index:: -x (gnatname) + +:samp:`-x{pattern}` + Excluded patterns. Using this switch, it is possible to exclude some files + that would match the name patterns. For example, + + .. code-block:: sh + + gnatname -x "*_nt.ada" "*.ada" + + will look for Ada units in all files with the :file:`.ada` extension, + except those whose names end with :file:`_nt.ada`. + + +.. _Examples_of_gnatname_Usage: + +Examples of `gnatname` Usage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: sh + + $ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" + +In this example, the directory :file:`/home/me` must already exist +and be writable. In addition, the directory +:file:`/home/me/sources` (specified by +*-d sources*) must exist and be readable. + +Note the optional spaces after *-c* and *-d*. + +.. code-block:: sh + + $ gnatname -P/home/me/proj -x "*_nt_body.ada" + -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" + +Note that several switches *-d* may be used, +even in conjunction with one or several switches +*-D*. Several Naming Patterns and one excluded pattern +are used in this example. + + +.. _File_Name_Krunching_with_gnatkr: + +File Name Krunching with `gnatkr` +--------------------------------- + +.. index:: ! gnatkr + +This chapter discusses the method used by the compiler to shorten +the default file names chosen for Ada units so that they do not +exceed the maximum length permitted. It also describes the +`gnatkr` utility that can be used to determine the result of +applying this shortening. + +.. _About_gnatkr: + +About `gnatkr` +^^^^^^^^^^^^^^ + +The default file naming rule in GNAT +is that the file name must be derived from +the unit name. The exact default rule is as follows: + +* Take the unit name and replace all dots by hyphens. + +* If such a replacement occurs in the + second character position of a name, and the first character is + :samp:`a`, :samp:`g`, :samp:`s`, or :samp:`i`, + then replace the dot by the character + :samp:`~` (tilde) + instead of a minus. + + The reason for this exception is to avoid clashes + with the standard names for children of System, Ada, Interfaces, + and GNAT, which use the prefixes + :samp:`s-`, :samp:`a-`, :samp:`i-`, and :samp:`g-`, + respectively. + +The :samp:`-gnatk{nn}` +switch of the compiler activates a 'krunching' +circuit that limits file names to nn characters (where nn is a decimal +integer). + +The `gnatkr` utility can be used to determine the krunched name for +a given file, when krunched to a specified maximum length. + +.. _Using_gnatkr: + +Using `gnatkr` +^^^^^^^^^^^^^^ + +The `gnatkr` command has the form: + +.. code-block:: sh + + $ gnatkr `name` [`length`] + +`name` is the uncrunched file name, derived from the name of the unit +in the standard manner described in the previous section (i.e., in particular +all dots are replaced by hyphens). The file name may or may not have an +extension (defined as a suffix of the form period followed by arbitrary +characters other than period). If an extension is present then it will +be preserved in the output. For example, when krunching :file:`hellofile.ads` +to eight characters, the result will be hellofil.ads. + +Note: for compatibility with previous versions of `gnatkr` dots may +appear in the name instead of hyphens, but the last dot will always be +taken as the start of an extension. So if `gnatkr` is given an argument +such as :file:`Hello.World.adb` it will be treated exactly as if the first +period had been a hyphen, and for example krunching to eight characters +gives the result :file:`hellworl.adb`. + +Note that the result is always all lower case. +Characters of the other case are folded as required. + +`length` represents the length of the krunched name. The default +when no argument is given is 8 characters. A length of zero stands for +unlimited, in other words do not chop except for system files where the +implied crunching length is always eight characters. + +The output is the krunched name. The output has an extension only if the +original argument was a file name with an extension. + +.. _Krunching_Method: + +Krunching Method +^^^^^^^^^^^^^^^^ + +The initial file name is determined by the name of the unit that the file +contains. The name is formed by taking the full expanded name of the +unit and replacing the separating dots with hyphens and +using lowercase +for all letters, except that a hyphen in the second character position is +replaced by a tilde if the first character is +:samp:`a`, :samp:`i`, :samp:`g`, or :samp:`s`. +The extension is `.ads` for a +spec and `.adb` for a body. +Krunching does not affect the extension, but the file name is shortened to +the specified length by following these rules: + +* The name is divided into segments separated by hyphens, tildes or + underscores and all hyphens, tildes, and underscores are + eliminated. If this leaves the name short enough, we are done. + +* If the name is too long, the longest segment is located (left-most + if there are two of equal length), and shortened by dropping + its last character. This is repeated until the name is short enough. + + As an example, consider the krunching of :file:`our-strings-wide_fixed.adb` + to fit the name into 8 characters as required by some operating systems:: + + our-strings-wide_fixed 22 + our strings wide fixed 19 + our string wide fixed 18 + our strin wide fixed 17 + our stri wide fixed 16 + our stri wide fixe 15 + our str wide fixe 14 + our str wid fixe 13 + our str wid fix 12 + ou str wid fix 11 + ou st wid fix 10 + ou st wi fix 9 + ou st wi fi 8 + Final file name: oustwifi.adb + +* The file names for all predefined units are always krunched to eight + characters. The krunching of these predefined units uses the following + special prefix replacements: + + ===================== ============== + Prefix Replacement + --------------------- -------------- + :file:`ada-` :file:`a-` + :file:`gnat-` :file:`g-` + :file:`interfac es-` :file:`i-` + :file:`system-` :file:`s-` + ===================== ============== + + These system files have a hyphen in the second character position. That + is why normal user files replace such a character with a + tilde, to avoid confusion with system file names. + + As an example of this special rule, consider + :file:`ada-strings-wide_fixed.adb`, which gets krunched as follows:: + + ada-strings-wide_fixed 22 + a- strings wide fixed 18 + a- string wide fixed 17 + a- strin wide fixed 16 + a- stri wide fixed 15 + a- stri wide fixe 14 + a- str wide fixe 13 + a- str wid fixe 12 + a- str wid fix 11 + a- st wid fix 10 + a- st wi fix 9 + a- st wi fi 8 + Final file name: a-stwifi.adb + +Of course no file shortening algorithm can guarantee uniqueness over all +possible unit names, and if file name krunching is used then it is your +responsibility to ensure that no name clashes occur. The utility +program `gnatkr` is supplied for conveniently determining the +krunched name of a file. + +.. _Examples_of_gnatkr_Usage: + +Examples of `gnatkr` Usage +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + $ gnatkr very_long_unit_name.ads --> velounna.ads + $ gnatkr grandparent-parent-child.ads --> grparchi.ads + $ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads + $ gnatkr grandparent-parent-child --> grparchi + $ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads + $ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads + + +.. _Renaming_Files_with_gnatchop: + +Renaming Files with `gnatchop` +------------------------------ + +.. index:: ! gnatchop + +This chapter discusses how to handle files with multiple units by using +the `gnatchop` utility. This utility is also useful in renaming +files to meet the standard GNAT default file naming conventions. + +.. _Handling_Files_with_Multiple_Units: + +Handling Files with Multiple Units +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The basic compilation model of GNAT requires that a file submitted to the +compiler have only one unit and there be a strict correspondence +between the file name and the unit name. + +The `gnatchop` utility allows both of these rules to be relaxed, +allowing GNAT to process files which contain multiple compilation units +and files with arbitrary file names. `gnatchop` +reads the specified file and generates one or more output files, +containing one unit per file. The unit and the file name correspond, +as required by GNAT. + +If you want to permanently restructure a set of 'foreign' files so that +they match the GNAT rules, and do the remaining development using the +GNAT structure, you can simply use *gnatchop* once, generate the +new set of files and work with them from that point on. + +Alternatively, if you want to keep your files in the 'foreign' format, +perhaps to maintain compatibility with some other Ada compilation +system, you can set up a procedure where you use *gnatchop* each +time you compile, regarding the source files that it writes as temporary +files that you throw away. + +Note that if your file containing multiple units starts with a byte order +mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop +will each start with a copy of this BOM, meaning that they can be compiled +automatically in UTF-8 mode without needing to specify an explicit encoding. + +.. _Operating_gnatchop_in_Compilation_Mode: + +Operating gnatchop in Compilation Mode +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The basic function of `gnatchop` is to take a file with multiple units +and split it into separate files. The boundary between files is reasonably +clear, except for the issue of comments and pragmas. In default mode, the +rule is that any pragmas between units belong to the previous unit, except +that configuration pragmas always belong to the following unit. Any comments +belong to the following unit. These rules +almost always result in the right choice of +the split point without needing to mark it explicitly and most users will +find this default to be what they want. In this default mode it is incorrect to +submit a file containing only configuration pragmas, or one that ends in +configuration pragmas, to `gnatchop`. + +However, using a special option to activate 'compilation mode', +`gnatchop` +can perform another function, which is to provide exactly the semantics +required by the RM for handling of configuration pragmas in a compilation. +In the absence of configuration pragmas (at the main file level), this +option has no effect, but it causes such configuration pragmas to be handled +in a quite different manner. + +First, in compilation mode, if `gnatchop` is given a file that consists of +only configuration pragmas, then this file is appended to the +:file:`gnat.adc` file in the current directory. This behavior provides +the required behavior described in the RM for the actions to be taken +on submitting such a file to the compiler, namely that these pragmas +should apply to all subsequent compilations in the same compilation +environment. Using GNAT, the current directory, possibly containing a +:file:`gnat.adc` file is the representation +of a compilation environment. For more information on the +:file:`gnat.adc` file, see :ref:`Handling_of_Configuration_Pragmas`. + +Second, in compilation mode, if `gnatchop` +is given a file that starts with +configuration pragmas, and contains one or more units, then these +configuration pragmas are prepended to each of the chopped files. This +behavior provides the required behavior described in the RM for the +actions to be taken on compiling such a file, namely that the pragmas +apply to all units in the compilation, but not to subsequently compiled +units. + +Finally, if configuration pragmas appear between units, they are appended +to the previous unit. This results in the previous unit being illegal, +since the compiler does not accept configuration pragmas that follow +a unit. This provides the required RM behavior that forbids configuration +pragmas other than those preceding the first compilation unit of a +compilation. + +For most purposes, `gnatchop` will be used in default mode. The +compilation mode described above is used only if you need exactly +accurate behavior with respect to compilations, and you have files +that contain multiple units and configuration pragmas. In this +circumstance the use of `gnatchop` with the compilation mode +switch provides the required behavior, and is for example the mode +in which GNAT processes the ACVC tests. + + +.. _Command_Line_for_gnatchop: + +Command Line for `gnatchop` +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `gnatchop` command has the form: + +.. code-block:: sh + + $ gnatchop switches file_name [file_name ...] + [directory] + +The only required argument is the file name of the file to be chopped. +There are no restrictions on the form of this file name. The file itself +contains one or more Ada units, in normal GNAT format, concatenated +together. As shown, more than one file may be presented to be chopped. + +When run in default mode, `gnatchop` generates one output file in +the current directory for each unit in each of the files. + +`directory`, if specified, gives the name of the directory to which +the output files will be written. If it is not specified, all files are +written to the current directory. + +For example, given a +file called :file:`hellofiles` containing + +.. code-block:: ada + + procedure Hello; + + with Ada.Text_IO; use Ada.Text_IO; + procedure Hello is + begin + Put_Line ("Hello"); + end Hello; + +the command + +.. code-block:: sh + + $ gnatchop hellofiles + +generates two files in the current directory, one called +:file:`hello.ads` containing the single line that is the procedure spec, +and the other called :file:`hello.adb` containing the remaining text. The +original file is not affected. The generated files can be compiled in +the normal manner. + +When gnatchop is invoked on a file that is empty or that contains only empty +lines and/or comments, gnatchop will not fail, but will not produce any +new sources. + +For example, given a +file called :file:`toto.txt` containing + +.. code-block:: ada + + -- Just a comment + +the command + +.. code-block:: sh + + $ gnatchop toto.txt + +will not produce any new file and will result in the following warnings:: + + toto.txt:1:01: warning: empty file, contains no compilation units + no compilation units found + no source files written + + +.. _Switches_for_gnatchop: + +Switches for `gnatchop` +^^^^^^^^^^^^^^^^^^^^^^^ + +*gnatchop* recognizes the following switches: + + +.. index:: --version (gnatchop) + +:samp:`--version` + Display Copyright and version, then exit disregarding all other options. + +.. index:: --help (gnatchop) + +:samp:`--help` + If *--version* was not used, display usage, then exit disregarding + all other options. + +.. index:: -c (gnatchop) + +:samp:`-c` + Causes `gnatchop` to operate in compilation mode, in which + configuration pragmas are handled according to strict RM rules. See + previous section for a full description of this mode. + +:samp:`-gnat{xxx}` + This passes the given *-gnat`xxx*` switch to `gnat` which is + used to parse the given file. Not all `xxx` options make sense, + but for example, the use of *-gnati2* allows `gnatchop` to + process a source file that uses Latin-2 coding for identifiers. + +:samp:`-h` + Causes `gnatchop` to generate a brief help summary to the standard + output file showing usage information. + +.. index:: -k (gnatchop) + +:samp:`-k{mm}` + Limit generated file names to the specified number `mm` + of characters. + This is useful if the + resulting set of files is required to be interoperable with systems + which limit the length of file names. + No space is allowed between the *-k* and the numeric value. The numeric + value may be omitted in which case a default of *-k8*, + suitable for use + with DOS-like file systems, is used. If no *-k* switch + is present then + there is no limit on the length of file names. + +.. index:: -p (gnatchop) + +:samp:`-p` + Causes the file modification time stamp of the input file to be + preserved and used for the time stamp of the output file(s). This may be + useful for preserving coherency of time stamps in an environment where + `gnatchop` is used as part of a standard build process. + +.. index:: -q (gnatchop) + +:samp:`-q` + Causes output of informational messages indicating the set of generated + files to be suppressed. Warnings and error messages are unaffected. + +.. index:: -r (gnatchop) +.. index:: Source_Reference pragmas + +:samp:`-r` + Generate `Source_Reference` pragmas. Use this switch if the output + files are regarded as temporary and development is to be done in terms + of the original unchopped file. This switch causes + `Source_Reference` pragmas to be inserted into each of the + generated files to refers back to the original file name and line number. + The result is that all error messages refer back to the original + unchopped file. + In addition, the debugging information placed into the object file (when + the *-g* switch of *gcc* or *gnatmake* is + specified) + also refers back to this original file so that tools like profilers and + debuggers will give information in terms of the original unchopped file. + + If the original file to be chopped itself contains + a `Source_Reference` + pragma referencing a third file, then gnatchop respects + this pragma, and the generated `Source_Reference` pragmas + in the chopped file refer to the original file, with appropriate + line numbers. This is particularly useful when `gnatchop` + is used in conjunction with `gnatprep` to compile files that + contain preprocessing statements and multiple units. + +.. index:: -v (gnatchop) + +:samp:`-v` + Causes `gnatchop` to operate in verbose mode. The version + number and copyright notice are output, as well as exact copies of + the gnat1 commands spawned to obtain the chop control information. + +.. index:: -w (gnatchop) + +:samp:`-w` + Overwrite existing file names. Normally `gnatchop` regards it as a + fatal error if there is already a file with the same name as a + file it would otherwise output, in other words if the files to be + chopped contain duplicated units. This switch bypasses this + check, and causes all but the last instance of such duplicated + units to be skipped. + +.. index:: --GCC= (gnatchop) + +:samp:`--GCC={xxxx}` + Specify the path of the GNAT parser to be used. When this switch is used, + no attempt is made to add the prefix to the GNAT parser executable. + + +.. _Examples_of_gnatchop_Usage: + +Examples of `gnatchop` Usage +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: sh + + $ gnatchop -w hello_s.ada prerelease/files + +Chops the source file :file:`hello_s.ada`. The output files will be +placed in the directory :file:`prerelease/files`, +overwriting any +files with matching names in that directory (no files in the current +directory are modified). + +.. code-block:: sh + + $ gnatchop archive + +Chops the source file :file:`archive` +into the current directory. One +useful application of `gnatchop` is in sending sets of sources +around, for example in email messages. The required sources are simply +concatenated (for example, using a Unix `cat` +command), and then +*gnatchop* is used at the other end to reconstitute the original +file names. + +.. code-block:: sh + + $ gnatchop file1 file2 file3 direc + +Chops all units in files :file:`file1`, :file:`file2`, :file:`file3`, placing +the resulting files in the directory :file:`direc`. Note that if any units +occur more than once anywhere within this set of files, an error message +is generated, and no files are written. To override this check, use the +*-w* switch, +in which case the last occurrence in the last file will +be the one that is output, and earlier duplicate occurrences for a given +unit will be skipped. + +.. _Configuration_Pragmas: + +Configuration Pragmas +===================== + +.. index:: Configuration pragmas + +.. index:: Pragmas, configuration + +Configuration pragmas include those pragmas described as +such in the Ada Reference Manual, as well as +implementation-dependent pragmas that are configuration pragmas. +See the `Implementation_Defined_Pragmas` chapter in the +:title:`GNAT_Reference_Manual` for details on these +additional GNAT-specific configuration pragmas. +Most notably, the pragma `Source_File_Name`, which allows +specifying non-default names for source files, is a configuration +pragma. The following is a complete list of configuration pragmas +recognized by GNAT:: + + Ada_83 + Ada_95 + Ada_05 + Ada_2005 + Ada_12 + Ada_2012 + Allow_Integer_Address + Annotate + Assertion_Policy + Assume_No_Invalid_Values + C_Pass_By_Copy + Check_Name + Check_Policy + Compile_Time_Error + Compile_Time_Warning + Compiler_Unit + Component_Alignment + Convention_Identifier + Debug_Policy + Detect_Blocking + Default_Storage_Pool + Discard_Names + Elaboration_Checks + Eliminate + Extend_System + Extensions_Allowed + External_Name_Casing + Fast_Math + Favor_Top_Level + Float_Representation + Implicit_Packing + Initialize_Scalars + Interrupt_State + License + Locking_Policy + Long_Float + No_Run_Time + No_Strict_Aliasing + Normalize_Scalars + Optimize_Alignment + Persistent_BSS + Polling + Priority_Specific_Dispatching + Profile + Profile_Warnings + Propagate_Exceptions + Queuing_Policy + Ravenscar + Restricted_Run_Time + Restrictions + Restrictions_Warnings + Reviewable + Short_Circuit_And_Or + Source_File_Name + Source_File_Name_Project + SPARK_Mode + Style_Checks + Suppress + Suppress_Exception_Locations + Task_Dispatching_Policy + Universal_Data + Unsuppress + Use_VADS_Size + Validity_Checks + Warnings + Wide_Character_Encoding + + +.. _Handling_of_Configuration_Pragmas: + +Handling of Configuration Pragmas +--------------------------------- + +Configuration pragmas may either appear at the start of a compilation +unit, or they can appear in a configuration pragma file to apply to +all compilations performed in a given compilation environment. + +GNAT also provides the `gnatchop` utility to provide an automatic +way to handle configuration pragmas following the semantics for +compilations (that is, files with multiple units), described in the RM. +See :ref:`Operating_gnatchop_in_Compilation_Mode` for details. +However, for most purposes, it will be more convenient to edit the +:file:`gnat.adc` file that contains configuration pragmas directly, +as described in the following section. + +In the case of `Restrictions` pragmas appearing as configuration +pragmas in individual compilation units, the exact handling depends on +the type of restriction. + +Restrictions that require partition-wide consistency (like +`No_Tasking`) are +recognized wherever they appear +and can be freely inherited, e.g. from a |withed| unit to the |withing| +unit. This makes sense since the binder will in any case insist on seeing +consistent use, so any unit not conforming to any restrictions that are +anywhere in the partition will be rejected, and you might as well find +that out at compile time rather than at bind time. + +For restrictions that do not require partition-wide consistency, e.g. +SPARK or No_Implementation_Attributes, in general the restriction applies +only to the unit in which the pragma appears, and not to any other units. + +The exception is No_Elaboration_Code which always applies to the entire +object file from a compilation, i.e. to the body, spec, and all subunits. +This restriction can be specified in a configuration pragma file, or it +can be on the body and/or the spec (in eithe case it applies to all the +relevant units). It can appear on a subunit only if it has previously +appeared in the body of spec. + + +.. _The_Configuration_Pragmas_Files: + +The Configuration Pragmas Files +------------------------------- + +.. index:: gnat.adc + +In GNAT a compilation environment is defined by the current +directory at the time that a compile command is given. This current +directory is searched for a file whose name is :file:`gnat.adc`. If +this file is present, it is expected to contain one or more +configuration pragmas that will be applied to the current compilation. +However, if the switch *-gnatA* is used, :file:`gnat.adc` is not +considered. When taken into account, :file:`gnat.adc` is added to the +dependencies, so that if :file:`gnat.adc` is modified later, an invocation of +*gnatmake* will recompile the source. + +Configuration pragmas may be entered into the :file:`gnat.adc` file +either by running `gnatchop` on a source file that consists only of +configuration pragmas, or more conveniently by direct editing of the +:file:`gnat.adc` file, which is a standard format source file. + +Besides :file:`gnat.adc`, additional files containing configuration +pragmas may be applied to the current compilation using the switch +:samp:`-gnatec={path}` where `path` must designate an existing file that +contains only configuration pragmas. These configuration pragmas are +in addition to those found in :file:`gnat.adc` (provided :file:`gnat.adc` +is present and switch *-gnatA* is not used). + +It is allowable to specify several switches *-gnatec=*, all of which +will be taken into account. + +Files containing configuration pragmas specified with switches +*-gnatec=* are added to the dependencies, unless they are +temporary files. A file is considered temporary if its name ends in +:file:`.tmp` or :file:`.TMP`. Certain tools follow this naming +convention because they pass information to *gcc* via +temporary files that are immediately deleted; it doesn't make sense to +depend on a file that no longer exists. Such tools include +*gprbuild*, *gnatmake*, and *gnatcheck*. + +If you are using project file, a separate mechanism is provided using +project attributes, see :ref:`Specifying_Configuration_Pragmas` for more +details. + + +.. _Generating_Object_Files: + +Generating Object Files +======================= + +An Ada program consists of a set of source files, and the first step in +compiling the program is to generate the corresponding object files. +These are generated by compiling a subset of these source files. +The files you need to compile are the following: + +* If a package spec has no body, compile the package spec to produce the + object file for the package. + +* If a package has both a spec and a body, compile the body to produce the + object file for the package. The source file for the package spec need + not be compiled in this case because there is only one object file, which + contains the code for both the spec and body of the package. + +* For a subprogram, compile the subprogram body to produce the object file + for the subprogram. The spec, if one is present, is as usual in a + separate file, and need not be compiled. + +.. index:: Subunits + +* In the case of subunits, only compile the parent unit. A single object + file is generated for the entire subunit tree, which includes all the + subunits. + +* Compile child units independently of their parent units + (though, of course, the spec of all the ancestor unit must be present in order + to compile a child unit). + + .. index:: Generics + +* Compile generic units in the same manner as any other units. The object + files in this case are small dummy files that contain at most the + flag used for elaboration checking. This is because GNAT always handles generic + instantiation by means of macro expansion. However, it is still necessary to + compile generic units, for dependency checking and elaboration purposes. + +The preceding rules describe the set of files that must be compiled to +generate the object files for a program. Each object file has the same +name as the corresponding source file, except that the extension is +:file:`.o` as usual. + +You may wish to compile other files for the purpose of checking their +syntactic and semantic correctness. For example, in the case where a +package has a separate spec and body, you would not normally compile the +spec. However, it is convenient in practice to compile the spec to make +sure it is error-free before compiling clients of this spec, because such +compilations will fail if there is an error in the spec. + +GNAT provides an option for compiling such files purely for the +purposes of checking correctness; such compilations are not required as +part of the process of building a program. To compile a file in this +checking mode, use the *-gnatc* switch. + +.. _Source_Dependencies: + +Source Dependencies +=================== + +A given object file clearly depends on the source file which is compiled +to produce it. Here we are using "depends" in the sense of a typical +`make` utility; in other words, an object file depends on a source +file if changes to the source file require the object file to be +recompiled. +In addition to this basic dependency, a given object may depend on +additional source files as follows: + +* If a file being compiled |withs| a unit `X`, the object file + depends on the file containing the spec of unit `X`. This includes + files that are |withed| implicitly either because they are parents + of |withed| child units or they are run-time units required by the + language constructs used in a particular unit. + +* If a file being compiled instantiates a library level generic unit, the + object file depends on both the spec and body files for this generic + unit. + +* If a file being compiled instantiates a generic unit defined within a + package, the object file depends on the body file for the package as + well as the spec file. + +.. index:: Inline +.. index:: -gnatn switch + +* If a file being compiled contains a call to a subprogram for which + pragma `Inline` applies and inlining is activated with the + *-gnatn* switch, the object file depends on the file containing the + body of this subprogram as well as on the file containing the spec. Note + that for inlining to actually occur as a result of the use of this switch, + it is necessary to compile in optimizing mode. + + .. index:: -gnatN switch + + The use of *-gnatN* activates inlining optimization + that is performed by the front end of the compiler. This inlining does + not require that the code generation be optimized. Like *-gnatn*, + the use of this switch generates additional dependencies. + + When using a gcc-based back end (in practice this means using any version + of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of + *-gnatN* is deprecated, and the use of *-gnatn* is preferred. + Historically front end inlining was more extensive than the gcc back end + inlining, but that is no longer the case. + +* If an object file :file:`O` depends on the proper body of a subunit through + inlining or instantiation, it depends on the parent unit of the subunit. + This means that any modification of the parent unit or one of its subunits + affects the compilation of :file:`O`. + +* The object file for a parent unit depends on all its subunit body files. + +* The previous two rules meant that for purposes of computing dependencies and + recompilation, a body and all its subunits are treated as an indivisible whole. + + These rules are applied transitively: if unit `A` |withs| + unit `B`, whose elaboration calls an inlined procedure in package + `C`, the object file for unit `A` will depend on the body of + `C`, in file :file:`c.adb`. + + The set of dependent files described by these rules includes all the + files on which the unit is semantically dependent, as dictated by the + Ada language standard. However, it is a superset of what the + standard describes, because it includes generic, inline, and subunit + dependencies. + + An object file must be recreated by recompiling the corresponding source + file if any of the source files on which it depends are modified. For + example, if the `make` utility is used to control compilation, + the rule for an Ada object file must mention all the source files on + which the object file depends, according to the above definition. + The determination of the necessary + recompilations is done automatically when one uses *gnatmake*. + +.. _The_Ada_Library_Information_Files: + +The Ada Library Information Files +================================= + +.. index:: Ada Library Information files + +.. index:: ALI files + +Each compilation actually generates two output files. The first of these +is the normal object file that has a :file:`.o` extension. The second is a +text file containing full dependency information. It has the same +name as the source file, but an :file:`.ali` extension. +This file is known as the Ada Library Information (:file:`ALI`) file. +The following information is contained in the :file:`ALI` file. + +* Version information (indicates which version of GNAT was used to compile + the unit(s) in question) + +* Main program information (including priority and time slice settings, + as well as the wide character encoding used during compilation). + +* List of arguments used in the *gcc* command for the compilation + +* Attributes of the unit, including configuration pragmas used, an indication + of whether the compilation was successful, exception model used etc. + +* A list of relevant restrictions applying to the unit (used for consistency) + checking. + +* Categorization information (e.g., use of pragma `Pure`). + +* Information on all |withed| units, including presence of + Elaborate` or `Elaborate_All` pragmas. + +* Information from any `Linker_Options` pragmas used in the unit + +* Information on the use of `Body_Version` or `Version` + attributes in the unit. + +* Dependency information. This is a list of files, together with + time stamp and checksum information. These are files on which + the unit depends in the sense that recompilation is required + if any of these units are modified. + +* Cross-reference data. Contains information on all entities referenced + in the unit. Used by tools like `gnatxref` and `gnatfind` to + provide cross-reference information. + +For a full detailed description of the format of the :file:`ALI` file, +see the source of the body of unit `Lib.Writ`, contained in file +:file:`lib-writ.adb` in the GNAT compiler sources. + + +.. _Binding_an_Ada_Program: + +Binding an Ada Program +====================== + +When using languages such as C and C++, once the source files have been +compiled the only remaining step in building an executable program +is linking the object modules together. This means that it is possible to +link an inconsistent version of a program, in which two units have +included different versions of the same header. + +The rules of Ada do not permit such an inconsistent program to be built. +For example, if two clients have different versions of the same package, +it is illegal to build a program containing these two clients. +These rules are enforced by the GNAT binder, which also determines an +elaboration order consistent with the Ada rules. + +The GNAT binder is run after all the object files for a program have +been created. It is given the name of the main program unit, and from +this it determines the set of units required by the program, by reading the +corresponding ALI files. It generates error messages if the program is +inconsistent or if no valid order of elaboration exists. + +If no errors are detected, the binder produces a main program, in Ada by +default, that contains calls to the elaboration procedures of those +compilation unit that require them, followed by +a call to the main program. This Ada program is compiled to generate the +object file for the main program. The name of +the Ada file is :file:`b~xxx`.adb` (with the corresponding spec +:file:`b~xxx`.ads`) where `xxx` is the name of the +main program unit. + +Finally, the linker is used to build the resulting executable program, +using the object from the main program from the bind step as well as the +object files for the Ada units of the program. + + +.. _GNAT_and_Libraries: + +GNAT and Libraries +================== + +.. index:: Library building and using + +This chapter describes how to build and use libraries with GNAT, and also shows +how to recompile the GNAT run-time library. You should be familiar with the +Project Manager facility (:ref:`GNAT_Project_Manager`) before reading this +chapter. + +.. _Introduction_to_Libraries_in_GNAT: + +Introduction to Libraries in GNAT +--------------------------------- + +A library is, conceptually, a collection of objects which does not have its +own main thread of execution, but rather provides certain services to the +applications that use it. A library can be either statically linked with the +application, in which case its code is directly included in the application, +or, on platforms that support it, be dynamically linked, in which case +its code is shared by all applications making use of this library. + +GNAT supports both types of libraries. +In the static case, the compiled code can be provided in different ways. The +simplest approach is to provide directly the set of objects resulting from +compilation of the library source files. Alternatively, you can group the +objects into an archive using whatever commands are provided by the operating +system. For the latter case, the objects are grouped into a shared library. + +In the GNAT environment, a library has three types of components: + +* Source files, + +* :file:`ALI` files (see :ref:`The_Ada_Library_Information_Files`), and + +* Object files, an archive or a shared library. + +A GNAT library may expose all its source files, which is useful for +documentation purposes. Alternatively, it may expose only the units needed by +an external user to make use of the library. That is to say, the specs +reflecting the library services along with all the units needed to compile +those specs, which can include generic bodies or any body implementing an +inlined routine. In the case of *stand-alone libraries* those exposed +units are called *interface units* (:ref:`Stand-alone_Ada_Libraries`). + +All compilation units comprising an application, including those in a library, +need to be elaborated in an order partially defined by Ada's semantics. GNAT +computes the elaboration order from the :file:`ALI` files and this is why they +constitute a mandatory part of GNAT libraries. +*Stand-alone libraries* are the exception to this rule because a specific +library elaboration routine is produced independently of the application(s) +using the library. + +.. _General_Ada_Libraries: + +General Ada Libraries +--------------------- + + +.. _Building_a_library: + +Building a library +^^^^^^^^^^^^^^^^^^ + +The easiest way to build a library is to use the Project Manager, +which supports a special type of project called a *Library Project* +(see :ref:`Library_Projects`). + +A project is considered a library project, when two project-level attributes +are defined in it: `Library_Name` and `Library_Dir`. In order to +control different aspects of library configuration, additional optional +project-level attributes can be specified: + +* *Library_Kind* + This attribute controls whether the library is to be static or dynamic + + +* *Library_Version* + This attribute specifies the library version; this value is used + during dynamic linking of shared libraries to determine if the currently + installed versions of the binaries are compatible. + +* *Library_Options* + +* *Library_GCC* + These attributes specify additional low-level options to be used during + library generation, and redefine the actual application used to generate + library. + +The GNAT Project Manager takes full care of the library maintenance task, +including recompilation of the source files for which objects do not exist +or are not up to date, assembly of the library archive, and installation of +the library (i.e., copying associated source, object and :file:`ALI` files +to the specified location). + +Here is a simple library project file: + +.. code-block:: gpr + + project My_Lib is + for Source_Dirs use ("src1", "src2"); + for Object_Dir use "obj"; + for Library_Name use "mylib"; + for Library_Dir use "lib"; + for Library_Kind use "dynamic"; + end My_lib; + +and the compilation command to build and install the library: + +.. code-block:: sh + + $ gnatmake -Pmy_lib + +It is not entirely trivial to perform manually all the steps required to +produce a library. We recommend that you use the GNAT Project Manager +for this task. In special cases where this is not desired, the necessary +steps are discussed below. + +There are various possibilities for compiling the units that make up the +library: for example with a Makefile (:ref:`Using_the_GNU_make_Utility`) or +with a conventional script. For simple libraries, it is also possible to create +a dummy main program which depends upon all the packages that comprise the +interface of the library. This dummy main program can then be given to +*gnatmake*, which will ensure that all necessary objects are built. + +After this task is accomplished, you should follow the standard procedure +of the underlying operating system to produce the static or shared library. + +Here is an example of such a dummy program: + +.. code-block:: ada + + with My_Lib.Service1; + with My_Lib.Service2; + with My_Lib.Service3; + procedure My_Lib_Dummy is + begin + null; + end; + +Here are the generic commands that will build an archive or a shared library. + +.. code-block:: sh + + # compiling the library + $ gnatmake -c my_lib_dummy.adb + + # we don't need the dummy object itself + $ rm my_lib_dummy.o my_lib_dummy.ali + + # create an archive with the remaining objects + $ ar rc libmy_lib.a *.o + # some systems may require "ranlib" to be run as well + + # or create a shared library + $ gcc -shared -o libmy_lib.so *.o + # some systems may require the code to have been compiled with -fPIC + + # remove the object files that are now in the library + $ rm *.o + + # Make the ALI files read-only so that gnatmake will not try to + # regenerate the objects that are in the library + $ chmod -w *.ali + +Please note that the library must have a name of the form :file:`lib{xxx}.a` +or :file:`lib{xxx}.so` (or :file:`lib{xxx}.dll` on Windows) in order to +be accessed by the directive :samp:`-l{xxx}` at link time. + +.. _Installing_a_library: + +Installing a library +^^^^^^^^^^^^^^^^^^^^ + +.. index:: ADA_PROJECT_PATH +.. index:: GPR_PROJECT_PATH + +If you use project files, library installation is part of the library build +process (:ref:`Installing_a_library_with_project_files`). + +When project files are not an option, it is also possible, but not recommended, +to install the library so that the sources needed to use the library are on the +Ada source path and the ALI files & libraries be on the Ada Object path (see +:ref:`Search_Paths_and_the_Run-Time_Library_RTL`. Alternatively, the system +administrator can place general-purpose libraries in the default compiler +paths, by specifying the libraries' location in the configuration files +:file:`ada_source_path` and :file:`ada_object_path`. These configuration files +must be located in the GNAT installation tree at the same place as the gcc spec +file. The location of the gcc spec file can be determined as follows: + +.. code-block:: sh + + $ gcc -v + + +The configuration files mentioned above have a simple format: each line +must contain one unique directory name. +Those names are added to the corresponding path +in their order of appearance in the file. The names can be either absolute +or relative; in the latter case, they are relative to where theses files +are located. + +The files :file:`ada_source_path` and :file:`ada_object_path` might not be +present in a +GNAT installation, in which case, GNAT will look for its run-time library in +the directories :file:`adainclude` (for the sources) and :file:`adalib` (for the +objects and :file:`ALI` files). When the files exist, the compiler does not +look in :file:`adainclude` and :file:`adalib`, and thus the +:file:`ada_source_path` file +must contain the location for the GNAT run-time sources (which can simply +be :file:`adainclude`). In the same way, the :file:`ada_object_path` file must +contain the location for the GNAT run-time objects (which can simply +be :file:`adalib`). + +You can also specify a new default path to the run-time library at compilation +time with the switch *--RTS=rts-path*. You can thus choose / change +the run-time library you want your program to be compiled with. This switch is +recognized by *gcc*, *gnatmake*, *gnatbind*, +*gnatls*, *gnatfind* and *gnatxref*. + +It is possible to install a library before or after the standard GNAT +library, by reordering the lines in the configuration files. In general, a +library must be installed before the GNAT library if it redefines +any part of it. + +.. _Using_a_library: + +Using a library +^^^^^^^^^^^^^^^ + +Once again, the project facility greatly simplifies the use of +libraries. In this context, using a library is just a matter of adding a +|with| clause in the user project. For instance, to make use of the +library `My_Lib` shown in examples in earlier sections, you can +write: + +.. code-block:: gpr + + with "my_lib"; + project My_Proj is + ... + end My_Proj; + +Even if you have a third-party, non-Ada library, you can still use GNAT's +Project Manager facility to provide a wrapper for it. For example, the +following project, when |withed| by your main project, will link with the +third-party library :file:`liba.a`: + +.. code-block:: gpr + + project Liba is + for Externally_Built use "true"; + for Source_Files use (); + for Library_Dir use "lib"; + for Library_Name use "a"; + for Library_Kind use "static"; + end Liba; + +This is an alternative to the use of `pragma Linker_Options`. It is +especially interesting in the context of systems with several interdependent +static libraries where finding a proper linker order is not easy and best be +left to the tools having visibility over project dependence information. + +In order to use an Ada library manually, you need to make sure that this +library is on both your source and object path +(see :ref:`Search_Paths_and_the_Run-Time_Library_RTL` +and :ref:`Search_Paths_for_gnatbind`). Furthermore, when the objects are grouped +in an archive or a shared library, you need to specify the desired +library at link time. + +For example, you can use the library :file:`mylib` installed in +:file:`/dir/my_lib_src` and :file:`/dir/my_lib_obj` with the following commands: + +.. code-block:: sh + + $ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \\ + -largs -lmy_lib + +This can be expressed more simply: + +.. code-block:: sh + + $ gnatmake my_appl + +when the following conditions are met: + +* :file:`/dir/my_lib_src` has been added by the user to the environment + variable :envvar:`ADA_INCLUDE_PATH`, or by the administrator to the file + :file:`ada_source_path` + +* :file:`/dir/my_lib_obj` has been added by the user to the environment + variable :envvar:`ADA_OBJECTS_PATH`, or by the administrator to the file + :file:`ada_object_path` + +* a pragma `Linker_Options` has been added to one of the sources. + For example: + + .. code-block:: ada + + pragma Linker_Options ("-lmy_lib"); + +Note that you may also load a library dynamically at +run time given its filename, as illustrated in the GNAT :file:`plugins` example +in the directory :file:`share/examples/gnat/plugins` within the GNAT +install area. + +.. _Stand-alone_Ada_Libraries: + +Stand-alone Ada Libraries +------------------------- + +.. index:: ! Stand-alone libraries + +.. _Introduction_to_Stand-alone_Libraries: + +Introduction to Stand-alone Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A Stand-alone Library (abbreviated 'SAL') is a library that contains the +necessary code to +elaborate the Ada units that are included in the library. In contrast with +an ordinary library, which consists of all sources, objects and :file:`ALI` +files of the +library, a SAL may specify a restricted subset of compilation units +to serve as a library interface. In this case, the fully +self-sufficient set of files will normally consist of an objects +archive, the sources of interface units' specs, and the :file:`ALI` +files of interface units. +If an interface spec contains a generic unit or an inlined subprogram, +the body's +source must also be provided; if the units that must be provided in the source +form depend on other units, the source and :file:`ALI` files of those must +also be provided. + +The main purpose of a SAL is to minimize the recompilation overhead of client +applications when a new version of the library is installed. Specifically, +if the interface sources have not changed, client applications do not need to +be recompiled. If, furthermore, a SAL is provided in the shared form and its +version, controlled by `Library_Version` attribute, is not changed, +then the clients do not need to be relinked. + +SALs also allow the library providers to minimize the amount of library source +text exposed to the clients. Such 'information hiding' might be useful or +necessary for various reasons. + +Stand-alone libraries are also well suited to be used in an executable whose +main routine is not written in Ada. + +.. _Building_a_Stand-alone_Library: + +Building a Stand-alone Library +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +GNAT's Project facility provides a simple way of building and installing +stand-alone libraries; see :ref:`Stand-alone_Library_Projects`. +To be a Stand-alone Library Project, in addition to the two attributes +that make a project a Library Project (`Library_Name` and +`Library_Dir`; see :ref:`Library_Projects`), the attribute +`Library_Interface` must be defined. For example: + +.. code-block:: gpr + + for Library_Dir use "lib_dir"; + for Library_Name use "dummy"; + for Library_Interface use ("int1", "int1.child"); + +Attribute `Library_Interface` has a non-empty string list value, +each string in the list designating a unit contained in an immediate source +of the project file. + +When a Stand-alone Library is built, first the binder is invoked to build +a package whose name depends on the library name +(:file:`b~dummy.ads/b` in the example above). +This binder-generated package includes initialization and +finalization procedures whose +names depend on the library name (`dummyinit` and `dummyfinal` +in the example +above). The object corresponding to this package is included in the library. + +You must ensure timely (e.g., prior to any use of interfaces in the SAL) +calling of these procedures if a static SAL is built, or if a shared SAL +is built +with the project-level attribute `Library_Auto_Init` set to +`"false"`. + +For a Stand-Alone Library, only the :file:`ALI` files of the Interface Units +(those that are listed in attribute `Library_Interface`) are copied to +the Library Directory. As a consequence, only the Interface Units may be +imported from Ada units outside of the library. If other units are imported, +the binding phase will fail. + +It is also possible to build an encapsulated library where not only +the code to elaborate and finalize the library is embedded but also +ensuring that the library is linked only against static +libraries. So an encapsulated library only depends on system +libraries, all other code, including the GNAT runtime, is embedded. To +build an encapsulated library the attribute +`Library_Standalone` must be set to `encapsulated`: + +.. code-block:: gpr + + for Library_Dir use "lib_dir"; + for Library_Name use "dummy"; + for Library_Kind use "dynamic"; + for Library_Interface use ("int1", "int1.child"); + for Library_Standalone use "encapsulated"; + +The default value for this attribute is `standard` in which case +a stand-alone library is built. + +The attribute `Library_Src_Dir` may be specified for a +Stand-Alone Library. `Library_Src_Dir` is a simple attribute that has a +single string value. Its value must be the path (absolute or relative to the +project directory) of an existing directory. This directory cannot be the +object directory or one of the source directories, but it can be the same as +the library directory. The sources of the Interface +Units of the library that are needed by an Ada client of the library will be +copied to the designated directory, called the Interface Copy directory. +These sources include the specs of the Interface Units, but they may also +include bodies and subunits, when pragmas `Inline` or `Inline_Always` +are used, or when there is a generic unit in the spec. Before the sources +are copied to the Interface Copy directory, an attempt is made to delete all +files in the Interface Copy directory. + +Building stand-alone libraries by hand is somewhat tedious, but for those +occasions when it is necessary here are the steps that you need to perform: + +* Compile all library sources. + +* Invoke the binder with the switch *-n* (No Ada main program), + with all the :file:`ALI` files of the interfaces, and + with the switch *-L* to give specific names to the `init` + and `final` procedures. For example: + + .. code-block:: sh + + $ gnatbind -n int1.ali int2.ali -Lsal1 + +* Compile the binder generated file: + + .. code-block:: sh + + $ gcc -c b~int2.adb + +* Link the dynamic library with all the necessary object files, + indicating to the linker the names of the `init` (and possibly + `final`) procedures for automatic initialization (and finalization). + The built library should be placed in a directory different from + the object directory. + +* Copy the `ALI` files of the interface to the library directory, + add in this copy an indication that it is an interface to a SAL + (i.e., add a word *SL* on the line in the :file:`ALI` file that starts + with letter 'P') and make the modified copy of the :file:`ALI` file + read-only. + +Using SALs is not different from using other libraries +(see :ref:`Using_a_library`). + +.. _Creating_a_Stand-alone_Library_to_be_used_in_a_non-Ada_context: + +Creating a Stand-alone Library to be used in a non-Ada context +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +It is easy to adapt the SAL build procedure discussed above for use of a SAL in +a non-Ada context. + +The only extra step required is to ensure that library interface subprograms +are compatible with the main program, by means of `pragma Export` +or `pragma Convention`. + +Here is an example of simple library interface for use with C main program: + +.. code-block:: ada + + package My_Package is + + procedure Do_Something; + pragma Export (C, Do_Something, "do_something"); + + procedure Do_Something_Else; + pragma Export (C, Do_Something_Else, "do_something_else"); + + end My_Package; + +On the foreign language side, you must provide a 'foreign' view of the +library interface; remember that it should contain elaboration routines in +addition to interface subprograms. + +The example below shows the content of `mylib_interface.h` (note +that there is no rule for the naming of this file, any name can be used) + +.. code-block:: c + + /* the library elaboration procedure */ + extern void mylibinit (void); + + /* the library finalization procedure */ + extern void mylibfinal (void); + + /* the interface exported by the library */ + extern void do_something (void); + extern void do_something_else (void); + +Libraries built as explained above can be used from any program, provided +that the elaboration procedures (named `mylibinit` in the previous +example) are called before the library services are used. Any number of +libraries can be used simultaneously, as long as the elaboration +procedure of each library is called. + +Below is an example of a C program that uses the `mylib` library. + +.. code-block:: c + + #include "mylib_interface.h" + + int + main (void) + { + /* First, elaborate the library before using it */ + mylibinit (); + + /* Main program, using the library exported entities */ + do_something (); + do_something_else (); + + /* Library finalization at the end of the program */ + mylibfinal (); + return 0; + } + +Note that invoking any library finalization procedure generated by +`gnatbind` shuts down the Ada run-time environment. +Consequently, the +finalization of all Ada libraries must be performed at the end of the program. +No call to these libraries or to the Ada run-time library should be made +after the finalization phase. + +Note also that special care must be taken with multi-tasks +applications. The initialization and finalization routines are not +protected against concurrent access. If such requirement is needed it +must be ensured at the application level using a specific operating +system services like a mutex or a critical-section. + +.. _Restrictions_in_Stand-alone_Libraries: + +Restrictions in Stand-alone Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The pragmas listed below should be used with caution inside libraries, +as they can create incompatibilities with other Ada libraries: + +* pragma `Locking_Policy` +* pragma `Partition_Elaboration_Policy` +* pragma `Queuing_Policy` +* pragma `Task_Dispatching_Policy` +* pragma `Unreserve_All_Interrupts` + +When using a library that contains such pragmas, the user must make sure +that all libraries use the same pragmas with the same values. Otherwise, +`Program_Error` will +be raised during the elaboration of the conflicting +libraries. The usage of these pragmas and its consequences for the user +should therefore be well documented. + +Similarly, the traceback in the exception occurrence mechanism should be +enabled or disabled in a consistent manner across all libraries. +Otherwise, Program_Error will be raised during the elaboration of the +conflicting libraries. + +If the `Version` or `Body_Version` +attributes are used inside a library, then you need to +perform a `gnatbind` step that specifies all :file:`ALI` files in all +libraries, so that version identifiers can be properly computed. +In practice these attributes are rarely used, so this is unlikely +to be a consideration. + +.. _Rebuilding_the_GNAT_Run-Time_Library: + +Rebuilding the GNAT Run-Time Library +------------------------------------ + +.. index:: GNAT Run-Time Library, rebuilding +.. index:: Building the GNAT Run-Time Library +.. index:: Rebuilding the GNAT Run-Time Library +.. index:: Run-Time Library, rebuilding + +It may be useful to recompile the GNAT library in various contexts, the +most important one being the use of partition-wide configuration pragmas +such as `Normalize_Scalars`. A special Makefile called +`Makefile.adalib` is provided to that effect and can be found in +the directory containing the GNAT library. The location of this +directory depends on the way the GNAT environment has been installed and can +be determined by means of the command: + +.. code-block:: sh + + $ gnatls -v + +The last entry in the object search path usually contains the +gnat library. This Makefile contains its own documentation and in +particular the set of instructions needed to rebuild a new library and +to use it. + + +.. index:: ! Conditional compilation + +.. _Conditional_Compilation: + +Conditional Compilation +======================= + +This section presents some guidelines for modeling conditional compilation in Ada and describes the +gnatprep preprocessor utility. + +.. index:: ! Conditional compilation + +.. _Modeling_Conditional_Compilation_in_Ada: + +Modeling Conditional Compilation in Ada +--------------------------------------- + +It is often necessary to arrange for a single source program +to serve multiple purposes, where it is compiled in different +ways to achieve these different goals. Some examples of the +need for this feature are + +* Adapting a program to a different hardware environment +* Adapting a program to a different target architecture +* Turning debugging features on and off +* Arranging for a program to compile with different compilers + +In C, or C++, the typical approach would be to use the preprocessor +that is defined as part of the language. The Ada language does not +contain such a feature. This is not an oversight, but rather a very +deliberate design decision, based on the experience that overuse of +the preprocessing features in C and C++ can result in programs that +are extremely difficult to maintain. For example, if we have ten +switches that can be on or off, this means that there are a thousand +separate programs, any one of which might not even be syntactically +correct, and even if syntactically correct, the resulting program +might not work correctly. Testing all combinations can quickly become +impossible. + +Nevertheless, the need to tailor programs certainly exists, and in +this section we will discuss how this can +be achieved using Ada in general, and GNAT in particular. + +.. _Use_of_Boolean_Constants: + +Use of Boolean Constants +^^^^^^^^^^^^^^^^^^^^^^^^ + +In the case where the difference is simply which code +sequence is executed, the cleanest solution is to use Boolean +constants to control which code is executed. + +.. code-block:: ada + + FP_Initialize_Required : constant Boolean := True; + ... + if FP_Initialize_Required then + ... + end if; + +Not only will the code inside the `if` statement not be executed if +the constant Boolean is `False`, but it will also be completely +deleted from the program. +However, the code is only deleted after the `if` statement +has been checked for syntactic and semantic correctness. +(In contrast, with preprocessors the code is deleted before the +compiler ever gets to see it, so it is not checked until the switch +is turned on.) + +.. index:: Preprocessors (contrasted with conditional compilation) + +Typically the Boolean constants will be in a separate package, +something like: + +.. code-block:: ada + + package Config is + FP_Initialize_Required : constant Boolean := True; + Reset_Available : constant Boolean := False; + ... + end Config; + +The `Config` package exists in multiple forms for the various targets, +with an appropriate script selecting the version of `Config` needed. +Then any other unit requiring conditional compilation can do a |with| +of `Config` to make the constants visible. + +.. _Debugging_-_A_Special_Case: + +Debugging - A Special Case +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +A common use of conditional code is to execute statements (for example +dynamic checks, or output of intermediate results) under control of a +debug switch, so that the debugging behavior can be turned on and off. +This can be done using a Boolean constant to control whether the code +is active: + +.. code-block:: ada + + if Debugging then + Put_Line ("got to the first stage!"); + end if; + +or + +.. code-block:: ada + + if Debugging and then Temperature > 999.0 then + raise Temperature_Crazy; + end if; + +.. index:: pragma Assert + +Since this is a common case, there are special features to deal with +this in a convenient manner. For the case of tests, Ada 2005 has added +a pragma `Assert` that can be used for such tests. This pragma is modeled +on the `Assert` pragma that has always been available in GNAT, so this +feature may be used with GNAT even if you are not using Ada 2005 features. +The use of pragma `Assert` is described in the +:title:`GNAT_Reference_Manual`, but as an +example, the last test could be written: + +.. code-block:: ada + + pragma Assert (Temperature <= 999.0, "Temperature Crazy"); + +or simply + +.. code-block:: ada + + pragma Assert (Temperature <= 999.0); + +In both cases, if assertions are active and the temperature is excessive, +the exception `Assert_Failure` will be raised, with the given string in +the first case or a string indicating the location of the pragma in the second +case used as the exception message. + +.. index:: pragma Assertion_Policy + +You can turn assertions on and off by using the `Assertion_Policy` +pragma. + +.. index:: -gnata switch + +This is an Ada 2005 pragma which is implemented in all modes by +GNAT. Alternatively, you can use the *-gnata* switch +to enable assertions from the command line, which applies to +all versions of Ada. + +.. index:: pragma Debug + +For the example above with the `Put_Line`, the GNAT-specific pragma +`Debug` can be used: + +.. code-block:: ada + + pragma Debug (Put_Line ("got to the first stage!")); + +If debug pragmas are enabled, the argument, which must be of the form of +a procedure call, is executed (in this case, `Put_Line` will be called). +Only one call can be present, but of course a special debugging procedure +containing any code you like can be included in the program and then +called in a pragma `Debug` argument as needed. + +One advantage of pragma `Debug` over the `if Debugging then` +construct is that pragma `Debug` can appear in declarative contexts, +such as at the very beginning of a procedure, before local declarations have +been elaborated. + +.. index:: pragma Debug_Policy + +Debug pragmas are enabled using either the *-gnata* switch that also +controls assertions, or with a separate Debug_Policy pragma. + +The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used +in Ada 95 and Ada 83 programs as well), and is analogous to +pragma `Assertion_Policy` to control assertions. + +`Assertion_Policy` and `Debug_Policy` are configuration pragmas, +and thus they can appear in :file:`gnat.adc` if you are not using a +project file, or in the file designated to contain configuration pragmas +in a project file. +They then apply to all subsequent compilations. In practice the use of +the *-gnata* switch is often the most convenient method of controlling +the status of these pragmas. + +Note that a pragma is not a statement, so in contexts where a statement +sequence is required, you can't just write a pragma on its own. You have +to add a `null` statement. + +.. code-block:: ada + + if ... then + ... -- some statements + else + pragma Assert (Num_Cases < 10); + null; + end if; + +.. _Conditionalizing_Declarations: + +Conditionalizing Declarations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases it may be necessary to conditionalize declarations to meet +different requirements. For example we might want a bit string whose length +is set to meet some hardware message requirement. + +This may be possible using declare blocks controlled +by conditional constants: + +.. code-block:: ada + + if Small_Machine then + declare + X : Bit_String (1 .. 10); + begin + ... + end; + else + declare + X : Large_Bit_String (1 .. 1000); + begin + ... + end; + end if; + +Note that in this approach, both declarations are analyzed by the +compiler so this can only be used where both declarations are legal, +even though one of them will not be used. + +Another approach is to define integer constants, e.g., `Bits_Per_Word`, +or Boolean constants, e.g., `Little_Endian`, and then write declarations +that are parameterized by these constants. For example + +.. code-block:: ada + + for Rec use + Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word; + end record; + +If `Bits_Per_Word` is set to 32, this generates either + +.. code-block:: ada + + for Rec use + Field1 at 0 range 0 .. 32; + end record; + +for the big endian case, or + +.. code-block:: ada + + for Rec use record + Field1 at 0 range 10 .. 32; + end record; + +for the little endian case. Since a powerful subset of Ada expression +notation is usable for creating static constants, clever use of this +feature can often solve quite difficult problems in conditionalizing +compilation (note incidentally that in Ada 95, the little endian +constant was introduced as `System.Default_Bit_Order`, so you do not +need to define this one yourself). + +.. _Use_of_Alternative_Implementations: + +Use of Alternative Implementations +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In some cases, none of the approaches described above are adequate. This +can occur for example if the set of declarations required is radically +different for two different configurations. + +In this situation, the official Ada way of dealing with conditionalizing +such code is to write separate units for the different cases. As long as +this does not result in excessive duplication of code, this can be done +without creating maintenance problems. The approach is to share common +code as far as possible, and then isolate the code and declarations +that are different. Subunits are often a convenient method for breaking +out a piece of a unit that is to be conditionalized, with separate files +for different versions of the subunit for different targets, where the +build script selects the right one to give to the compiler. + +.. index:: Subunits (and conditional compilation) + +As an example, consider a situation where a new feature in Ada 2005 +allows something to be done in a really nice way. But your code must be able +to compile with an Ada 95 compiler. Conceptually you want to say: + +.. code-block:: ada + + if Ada_2005 then + ... neat Ada 2005 code + else + ... not quite as neat Ada 95 code + end if; + +where `Ada_2005` is a Boolean constant. + +But this won't work when `Ada_2005` is set to `False`, +since the `then` clause will be illegal for an Ada 95 compiler. +(Recall that although such unreachable code would eventually be deleted +by the compiler, it still needs to be legal. If it uses features +introduced in Ada 2005, it will be illegal in Ada 95.) + +So instead we write + +.. code-block:: ada + + procedure Insert is separate; + +Then we have two files for the subunit `Insert`, with the two sets of +code. +If the package containing this is called `File_Queries`, then we might +have two files + +* :file:`file_queries-insert-2005.adb` +* :file:`file_queries-insert-95.adb` + +and the build script renames the appropriate file to :file:`file_queries-insert.adb` and then carries out the compilation. + +This can also be done with project files' naming schemes. For example: + +.. code-block:: gpr + + for body ("File_Queries.Insert") use "file_queries-insert-2005.ada"; + +Note also that with project files it is desirable to use a different extension +than :file:`ads` / :file:`adb` for alternative versions. Otherwise a naming +conflict may arise through another commonly used feature: to declare as part +of the project a set of directories containing all the sources obeying the +default naming scheme. + +The use of alternative units is certainly feasible in all situations, +and for example the Ada part of the GNAT run-time is conditionalized +based on the target architecture using this approach. As a specific example, +consider the implementation of the AST feature in VMS. There is one +spec: :file:`s-asthan.ads` which is the same for all architectures, and three +bodies: + +* :file:`s-asthan.adb` + used for all non-VMS operating systems + +* :file:`s-asthan-vms-alpha.adb` + used for VMS on the Alpha + +* :file:`s-asthan-vms-ia64.adb` + used for VMS on the ia64 + +The dummy version :file:`s-asthan.adb` simply raises exceptions noting that +this operating system feature is not available, and the two remaining +versions interface with the corresponding versions of VMS to provide +VMS-compatible AST handling. The GNAT build script knows the architecture +and operating system, and automatically selects the right version, +renaming it if necessary to :file:`s-asthan.adb` before the run-time build. + +Another style for arranging alternative implementations is through Ada's +access-to-subprogram facility. +In case some functionality is to be conditionally included, +you can declare an access-to-procedure variable `Ref` that is initialized +to designate a 'do nothing' procedure, and then invoke `Ref.all` +when appropriate. +In some library package, set `Ref` to `Proc'Access` for some +procedure `Proc` that performs the relevant processing. +The initialization only occurs if the library package is included in the +program. +The same idea can also be implemented using tagged types and dispatching +calls. + +.. _Preprocessing: + +Preprocessing +^^^^^^^^^^^^^ + +.. index:: Preprocessing + +Although it is quite possible to conditionalize code without the use of +C-style preprocessing, as described earlier in this section, it is +nevertheless convenient in some cases to use the C approach. Moreover, +older Ada compilers have often provided some preprocessing capability, +so legacy code may depend on this approach, even though it is not +standard. + +To accommodate such use, GNAT provides a preprocessor (modeled to a large +extent on the various preprocessors that have been used +with legacy code on other compilers, to enable easier transition). + +.. index:: gnatprep + +The preprocessor may be used in two separate modes. It can be used quite +separately from the compiler, to generate a separate output source file +that is then fed to the compiler as a separate step. This is the +`gnatprep` utility, whose use is fully described in +:ref:`Preprocessing_with_gnatprep`. + +The preprocessing language allows such constructs as + +.. code-block:: c + + #if DEBUG or else (PRIORITY > 4) then + bunch of declarations + #else + completely different bunch of declarations + #end if; + +The values of the symbols `DEBUG` and `PRIORITY` can be +defined either on the command line or in a separate file. + +The other way of running the preprocessor is even closer to the C style and +often more convenient. In this approach the preprocessing is integrated into +the compilation process. The compiler is fed the preprocessor input which +includes `#if` lines etc, and then the compiler carries out the +preprocessing internally and processes the resulting output. +For more details on this approach, see :ref:`Integrated_Preprocessing`. + +.. _Preprocessing_with_gnatprep: + +Preprocessing with `gnatprep` +----------------------------- + +.. index:: ! gnatprep +.. index:: Preprocessing (gnatprep) + +This section discusses how to use GNAT's `gnatprep` utility for simple +preprocessing. +Although designed for use with GNAT, `gnatprep` does not depend on any +special GNAT features. +For further discussion of conditional compilation in general, see +:ref:`Conditional_Compilation`. + +.. _Preprocessing_Symbols: + +Preprocessing Symbols +^^^^^^^^^^^^^^^^^^^^^ + +Preprocessing symbols are defined in definition files and referred to in +sources to be preprocessed. A Preprocessing symbol is an identifier, following +normal Ada (case-insensitive) rules for its syntax, with the restriction that +all characters need to be in the ASCII set (no accented letters). + +.. _Using_gnatprep: + +Using `gnatprep` +^^^^^^^^^^^^^^^^ + +To call `gnatprep` use: + +.. code-block:: sh + + $ gnatprep [`switches`] `infile` `outfile` [`deffile`] + +where + +* *switches* + is an optional sequence of switches as described in the next section. + +* *infile* + is the full name of the input file, which is an Ada source + file containing preprocessor directives. + +* *outfile* + is the full name of the output file, which is an Ada source + in standard Ada form. When used with GNAT, this file name will + normally have an ads or adb suffix. + +* *deffile* + is the full name of a text file containing definitions of + preprocessing symbols to be referenced by the preprocessor. This argument is + optional, and can be replaced by the use of the *-D* switch. + + +.. _Switches_for_gnatprep: + +Switches for `gnatprep` +^^^^^^^^^^^^^^^^^^^^^^^ + +.. index:: -b (gnatprep) + +:samp:`-b` + Causes both preprocessor lines and the lines deleted by + preprocessing to be replaced by blank lines in the output source file, + preserving line numbers in the output file. + +.. index:: -c (gnatprep) + +:samp:`-c` + Causes both preprocessor lines and the lines deleted + by preprocessing to be retained in the output source as comments marked + with the special string `"--! "`. This option will result in line numbers + being preserved in the output file. + +.. index:: -C (gnatprep) + +:samp:`-C` + Causes comments to be scanned. Normally comments are ignored by gnatprep. + If this option is specified, then comments are scanned and any $symbol + substitutions performed as in program text. This is particularly useful + when structured comments are used (e.g., when writing programs in the + SPARK dialect of Ada). Note that this switch is not available when + doing integrated preprocessing (it would be useless in this context + since comments are ignored by the compiler in any case). + +.. index:: -D (gnatprep) + +:samp:`-D{symbol}={value}` + Defines a new preprocessing symbol, associated with value. If no value is given + on the command line, then symbol is considered to be `True`. This switch + can be used in place of a definition file. + +.. index:: -r (gnatprep) + +:samp:`-r` + Causes a `Source_Reference` pragma to be generated that + references the original input file, so that error messages will use + the file name of this original file. The use of this switch implies + that preprocessor lines are not to be removed from the file, so its + use will force *-b* mode if *-c* + has not been specified explicitly. + + Note that if the file to be preprocessed contains multiple units, then + it will be necessary to `gnatchop` the output file from + `gnatprep`. If a `Source_Reference` pragma is present + in the preprocessed file, it will be respected by + `gnatchop -r` + so that the final chopped files will correctly refer to the original + input source file for `gnatprep`. + +.. index:: -s (gnatprep) + +:samp:`-s` + Causes a sorted list of symbol names and values to be + listed on the standard output file. + +.. index:: -u (gnatprep) + +:samp:`-u` + Causes undefined symbols to be treated as having the value FALSE in the context + of a preprocessor test. In the absence of this option, an undefined symbol in + a `#if` or `#elsif` test will be treated as an error. + + +Note: if neither *-b* nor *-c* is present, +then preprocessor lines and +deleted lines are completely removed from the output, unless -r is +specified, in which case -b is assumed. + + +.. _Form_of_Definitions_File: + +Form of Definitions File +^^^^^^^^^^^^^^^^^^^^^^^^ + +The definitions file contains lines of the form:: + + symbol := value + +where `symbol` is a preprocessing symbol, and `value` is one of the following: + +* Empty, corresponding to a null substitution, +* A string literal using normal Ada syntax, or +* Any sequence of characters from the set {letters, digits, period, underline}. + +Comment lines may also appear in the definitions file, starting with +the usual ``--``, +and comments may be added to the definitions lines. + + +.. _Form_of_Input_Text_for_gnatprep: + +Form of Input Text for `gnatprep` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The input text may contain preprocessor conditional inclusion lines, +as well as general symbol substitution sequences. + +The preprocessor conditional inclusion commands have the form: + +.. code-block:: c + + #if <expression> [then] + lines + #elsif <expression> [then] + lines + #elsif <expression> [then] + lines + ... + #else + lines + #end if; + +In this example, <expression> is defined by the following grammar:: + + <expression> ::= <symbol> + <expression> ::= <symbol> = "<value>" + <expression> ::= <symbol> = <symbol> + <expression> ::= <symbol> = <integer> + <expression> ::= <symbol> > <integer> + <expression> ::= <symbol> >= <integer> + <expression> ::= <symbol> < <integer> + <expression> ::= <symbol> <= <integer> + <expression> ::= <symbol> 'Defined + <expression> ::= not <expression> + <expression> ::= <expression> and <expression> + <expression> ::= <expression> or <expression> + <expression> ::= <expression> and then <expression> + <expression> ::= <expression> or else <expression> + <expression> ::= ( <expression> ) + +Note the following restriction: it is not allowed to have "and" or "or" +following "not" in the same expression without parentheses. For example, this +is not allowed: + +.. code-block:: ada + + not X or Y + +This can be expressed instead as one of the following forms: + +.. code-block:: ada + + (not X) or Y + not (X or Y) + +For the first test (<expression> ::= <symbol>) the symbol must have +either the value true or false, that is to say the right-hand of the +symbol definition must be one of the (case-insensitive) literals +`True` or `False`. If the value is true, then the +corresponding lines are included, and if the value is false, they are +excluded. + +When comparing a symbol to an integer, the integer is any non negative +literal integer as defined in the Ada Reference Manual, such as 3, 16#FF# or +2#11#. The symbol value must also be a non negative integer. Integer values +in the range 0 .. 2**31-1 are supported. + +The test (<expression> ::= <symbol>'Defined) is true only if +the symbol has been defined in the definition file or by a *-D* +switch on the command line. Otherwise, the test is false. + +The equality tests are case insensitive, as are all the preprocessor lines. + +If the symbol referenced is not defined in the symbol definitions file, +then the effect depends on whether or not switch *-u* +is specified. If so, then the symbol is treated as if it had the value +false and the test fails. If this switch is not specified, then +it is an error to reference an undefined symbol. It is also an error to +reference a symbol that is defined with a value other than `True` +or `False`. + +The use of the `not` operator inverts the sense of this logical test. +The `not` operator cannot be combined with the `or` or `and` +operators, without parentheses. For example, "if not X or Y then" is not +allowed, but "if (not X) or Y then" and "if not (X or Y) then" are. + +The `then` keyword is optional as shown + +The `#` must be the first non-blank character on a line, but +otherwise the format is free form. Spaces or tabs may appear between +the `#` and the keyword. The keywords and the symbols are case +insensitive as in normal Ada code. Comments may be used on a +preprocessor line, but other than that, no other tokens may appear on a +preprocessor line. Any number of `elsif` clauses can be present, +including none at all. The `else` is optional, as in Ada. + +The `#` marking the start of a preprocessor line must be the first +non-blank character on the line, i.e., it must be preceded only by +spaces or horizontal tabs. + +Symbol substitution outside of preprocessor lines is obtained by using +the sequence:: + + $symbol + +anywhere within a source line, except in a comment or within a +string literal. The identifier +following the `$` must match one of the symbols defined in the symbol +definition file, and the result is to substitute the value of the +symbol in place of `$symbol` in the output file. + +Note that although the substitution of strings within a string literal +is not possible, it is possible to have a symbol whose defined value is +a string literal. So instead of setting XYZ to `hello` and writing: + +.. code-block:: c + + Header : String := "$XYZ"; + +you should set XYZ to `"hello"` and write: + +.. code-block:: c + + Header : String := $XYZ; + +and then the substitution will occur as desired. + + +.. _Integrated_Preprocessing: + +Integrated Preprocessing +------------------------ + +GNAT sources may be preprocessed immediately before compilation. +In this case, the actual +text of the source is not the text of the source file, but is derived from it +through a process called preprocessing. Integrated preprocessing is specified +through switches *-gnatep* and/or *-gnateD*. *-gnatep* +indicates, through a text file, the preprocessing data to be used. +:samp:`-gnateD` specifies or modifies the values of preprocessing symbol. +Note that integrated preprocessing applies only to Ada source files, it is +not available for configuration pragma files. + +Note that when integrated preprocessing is used, the output from the +preprocessor is not written to any external file. Instead it is passed +internally to the compiler. If you need to preserve the result of +preprocessing in a file, then you should use *gnatprep* +to perform the desired preprocessing in stand-alone mode. + +It is recommended that *gnatmake* switch -s should be +used when Integrated Preprocessing is used. The reason is that preprocessing +with another Preprocessing Data file without changing the sources will +not trigger recompilation without this switch. + +Note that *gnatmake* switch -m will almost +always trigger recompilation for sources that are preprocessed, +because *gnatmake* cannot compute the checksum of the source after +preprocessing. + +The actual preprocessing function is described in detail in section +:ref:`Preprocessing_with_gnatprep`. This section only describes how integrated +preprocessing is triggered and parameterized. + + +.. index:: -gnatep (gcc) + +:samp:`-gnatep={file}` + This switch indicates to the compiler the file name (without directory + information) of the preprocessor data file to use. The preprocessor data file + should be found in the source directories. Note that when the compiler is + called by a builder such as (*gnatmake* with a project + file, if the object directory is not also a source directory, the builder needs + to be called with *-x*. + + A preprocessing data file is a text file with significant lines indicating + how should be preprocessed either a specific source or all sources not + mentioned in other lines. A significant line is a nonempty, non-comment line. + Comments are similar to Ada comments. + + Each significant line starts with either a literal string or the character '*'. + A literal string is the file name (without directory information) of the source + to preprocess. A character '*' indicates the preprocessing for all the sources + that are not specified explicitly on other lines (order of the lines is not + significant). It is an error to have two lines with the same file name or two + lines starting with the character '*'. + + After the file name or the character '*', another optional literal string + indicating the file name of the definition file to be used for preprocessing + (:ref:`Form_of_Definitions_File`). The definition files are found by the + compiler in one of the source directories. In some cases, when compiling + a source in a directory other than the current directory, if the definition + file is in the current directory, it may be necessary to add the current + directory as a source directory through switch -I., otherwise + the compiler would not find the definition file. + + Then, optionally, switches similar to those of `gnatprep` may + be found. Those switches are: + + :samp:`-b` + Causes both preprocessor lines and the lines deleted by + preprocessing to be replaced by blank lines, preserving the line number. + This switch is always implied; however, if specified after *-c* + it cancels the effect of *-c*. + + + :samp:`-c` + Causes both preprocessor lines and the lines deleted + by preprocessing to be retained as comments marked + with the special string '`--!`'. + + + :samp:`-Dsymbol={value}` + Define or redefine a symbol, associated with value. A symbol is an Ada + identifier, or an Ada reserved word, with the exception of `if`, + `else`, `elsif`, `end`, `and`, `or` and `then`. + `value` is either a literal string, an Ada identifier or any Ada reserved + word. A symbol declared with this switch replaces a symbol with the + same name defined in a definition file. + + + :samp:`-s` + Causes a sorted list of symbol names and values to be + listed on the standard output file. + + + :samp:`-u` + Causes undefined symbols to be treated as having the value `FALSE` + in the context + of a preprocessor test. In the absence of this option, an undefined symbol in + a `#if` or `#elsif` test will be treated as an error. + + + Examples of valid lines in a preprocessor data file: + + .. code-block:: ada + + "toto.adb" "prep.def" -u + -- preprocess "toto.adb", using definition file "prep.def", + -- undefined symbol are False. + + * -c -DVERSION=V101 + -- preprocess all other sources without a definition file; + -- suppressed lined are commented; symbol VERSION has the value V101. + + "titi.adb" "prep2.def" -s + -- preprocess "titi.adb", using definition file "prep2.def"; + -- list all symbols with their values. + +.. index:: -gnateD (gcc) + +:samp:`-gnateDsymbol[=value]` + Define or redefine a preprocessing symbol, associated with value. If no value + is given on the command line, then the value of the symbol is `True`. + A symbol is an identifier, following normal Ada (case-insensitive) + rules for its syntax, and value is either an arbitrary string between double + quotes or any sequence (including an empty sequence) of characters from the + set (letters, digits, period, underline). + Ada reserved words may be used as symbols, with the exceptions of `if`, + `else`, `elsif`, `end`, `and`, `or` and `then`. + + Examples:: + + -gnateDToto=Titi + -gnateDFoo + -gnateDFoo=\"Foo-Bar\" + + A symbol declared with this switch on the command line replaces a + symbol with the same name either in a definition file or specified with a + switch -D in the preprocessor data file. + + This switch is similar to switch *-D* of `gnatprep`. + + +:samp:`-gnateG` + When integrated preprocessing is performed and the preprocessor modifies + the source text, write the result of this preprocessing into a file + <source>.prep. + + +.. _Mixed_Language_Programming: + +Mixed Language Programming +========================== + +.. index:: Mixed Language Programming + +This section describes how to develop a mixed-language program, +with a focus on combining Ada with C or C++. + +.. _Interfacing_to_C: + +Interfacing to C +---------------- + +Interfacing Ada with a foreign language such as C involves using +compiler directives to import and/or export entity definitions in each +language -- using `extern` statements in C, for instance, and the +`Import`, `Export`, and `Convention` pragmas in Ada. +A full treatment of these topics is provided in Appendix B, section 1 +of the Ada Reference Manual. + +There are two ways to build a program using GNAT that contains some Ada +sources and some foreign language sources, depending on whether or not +the main subprogram is written in Ada. Here is a source example with +the main subprogram in Ada: + +.. code-block:: c + + /* file1.c */ + #include <stdio.h> + + void print_num (int num) + { + printf ("num is %d.\\n", num); + return; + } + +.. code-block:: c + + /* file2.c */ + + /* num_from_Ada is declared in my_main.adb */ + extern int num_from_Ada; + + int get_num (void) + { + return num_from_Ada; + } + +.. code-block:: ada + + -- my_main.adb + procedure My_Main is + + -- Declare then export an Integer entity called num_from_Ada + My_Num : Integer := 10; + pragma Export (C, My_Num, "num_from_Ada"); + + -- Declare an Ada function spec for Get_Num, then use + -- C function get_num for the implementation. + function Get_Num return Integer; + pragma Import (C, Get_Num, "get_num"); + + -- Declare an Ada procedure spec for Print_Num, then use + -- C function print_num for the implementation. + procedure Print_Num (Num : Integer); + pragma Import (C, Print_Num, "print_num"; + + begin + Print_Num (Get_Num); + end My_Main; + +To build this example: + +* First compile the foreign language files to + generate object files: + + .. code-block:: sh + + $ gcc -c file1.c + $ gcc -c file2.c + +* Then, compile the Ada units to produce a set of object files and ALI + files: + + .. code-block:: sh + + $ gnatmake -c my_main.adb + +* Run the Ada binder on the Ada main program: + + .. code-block:: sh + + $ gnatbind my_main.ali + +* Link the Ada main program, the Ada objects and the other language + objects: + + .. code-block:: sh + + $ gnatlink my_main.ali file1.o file2.o + +The last three steps can be grouped in a single command: + +.. code-block:: sh + + $ gnatmake my_main.adb -largs file1.o file2.o + + +.. index:: Binder output file + +If the main program is in a language other than Ada, then you may have +more than one entry point into the Ada subsystem. You must use a special +binder option to generate callable routines that initialize and +finalize the Ada units (:ref:`Binding_with_Non-Ada_Main_Programs`). +Calls to the initialization and finalization routines must be inserted +in the main program, or some other appropriate point in the code. The +call to initialize the Ada units must occur before the first Ada +subprogram is called, and the call to finalize the Ada units must occur +after the last Ada subprogram returns. The binder will place the +initialization and finalization subprograms into the +:file:`b~xxx.adb` file where they can be accessed by your C +sources. To illustrate, we have the following example: + +.. code-block:: c + + /* main.c */ + extern void adainit (void); + extern void adafinal (void); + extern int add (int, int); + extern int sub (int, int); + + int main (int argc, char *argv[]) + { + int a = 21, b = 7; + + adainit(); + + /* Should print "21 + 7 = 28" */ + printf ("%d + %d = %d\\n", a, b, add (a, b)); + + /* Should print "21 - 7 = 14" */ + printf ("%d - %d = %d\\n", a, b, sub (a, b)); + + adafinal(); + } + +.. code-block:: ada + + -- unit1.ads + package Unit1 is + function Add (A, B : Integer) return Integer; + pragma Export (C, Add, "add"); + end Unit1; + +.. code-block:: ada + + -- unit1.adb + package body Unit1 is + function Add (A, B : Integer) return Integer is + begin + return A + B; + end Add; + end Unit1; + +.. code-block:: ada + + -- unit2.ads + package Unit2 is + function Sub (A, B : Integer) return Integer; + pragma Export (C, Sub, "sub"); + end Unit2; + +.. code-block:: ada + + -- unit2.adb + package body Unit2 is + function Sub (A, B : Integer) return Integer is + begin + return A - B; + end Sub; + end Unit2; + +The build procedure for this application is similar to the last +example's: + +* First, compile the foreign language files to generate object files: + + .. code-block:: sh + + $ gcc -c main.c + + +* Next, compile the Ada units to produce a set of object files and ALI + files: + + .. code-block:: sh + + $ gnatmake -c unit1.adb + $ gnatmake -c unit2.adb + +* Run the Ada binder on every generated ALI file. Make sure to use the + :option:`-n` option to specify a foreign main program: + + .. code-block:: sh + + $ gnatbind -n unit1.ali unit2.ali + +* Link the Ada main program, the Ada objects and the foreign language + objects. You need only list the last ALI file here: + + .. code-block:: sh + + $ gnatlink unit2.ali main.o -o exec_file + + This procedure yields a binary executable called :file:`exec_file`. + +Depending on the circumstances (for example when your non-Ada main object +does not provide symbol `main`), you may also need to instruct the +GNAT linker not to include the standard startup objects by passing the +:option:`-nostartfiles` switch to `gnatlink`. + +.. _Calling_Conventions: + +Calling Conventions +------------------- + +.. index:: Foreign Languages + +.. index:: Calling Conventions + +GNAT follows standard calling sequence conventions and will thus interface +to any other language that also follows these conventions. The following +Convention identifiers are recognized by GNAT: + + +.. index:: Interfacing to Ada + +.. index:: Other Ada compilers + +.. index:: Convention Ada + +*Ada* + This indicates that the standard Ada calling sequence will be + used and all Ada data items may be passed without any limitations in the + case where GNAT is used to generate both the caller and callee. It is also + possible to mix GNAT generated code and code generated by another Ada + compiler. In this case, the data types should be restricted to simple + cases, including primitive types. Whether complex data types can be passed + depends on the situation. Probably it is safe to pass simple arrays, such + as arrays of integers or floats. Records may or may not work, depending + on whether both compilers lay them out identically. Complex structures + involving variant records, access parameters, tasks, or protected types, + are unlikely to be able to be passed. + + Note that in the case of GNAT running + on a platform that supports HP Ada 83, a higher degree of compatibility + can be guaranteed, and in particular records are laid out in an identical + manner in the two compilers. Note also that if output from two different + compilers is mixed, the program is responsible for dealing with elaboration + issues. Probably the safest approach is to write the main program in the + version of Ada other than GNAT, so that it takes care of its own elaboration + requirements, and then call the GNAT-generated adainit procedure to ensure + elaboration of the GNAT components. Consult the documentation of the other + Ada compiler for further details on elaboration. + + However, it is not possible to mix the tasking run time of GNAT and + HP Ada 83, All the tasking operations must either be entirely within + GNAT compiled sections of the program, or entirely within HP Ada 83 + compiled sections of the program. + +.. index:: Interfacing to Assembly + +.. index:: Convention Assembler + + +*Assembler* + Specifies assembler as the convention. In practice this has the + same effect as convention Ada (but is not equivalent in the sense of being + considered the same convention). + +.. index:: Convention Asm + +.. index:: Asm + +*Asm* + Equivalent to Assembler. + + .. index:: Interfacing to COBOL + + .. index:: Convention COBOL + +.. index:: COBOL + +*COBOL* + Data will be passed according to the conventions described + in section B.4 of the Ada Reference Manual. + +.. index:: C +.. index:: Interfacing to C + +.. index:: Convention C + + +*C* + Data will be passed according to the conventions described + in section B.3 of the Ada Reference Manual. + + A note on interfacing to a C 'varargs' function: + + .. index:: C varargs function + .. index:: Interfacing to C varargs function + .. index:: varargs function interfaces + + In C, `varargs` allows a function to take a variable number of + arguments. There is no direct equivalent in this to Ada. One + approach that can be used is to create a C wrapper for each + different profile and then interface to this C wrapper. For + example, to print an `int` value using `printf`, + create a C function `printfi` that takes two arguments, a + pointer to a string and an int, and calls `printf`. + Then in the Ada program, use pragma `Import` to + interface to `printfi`. + + It may work on some platforms to directly interface to + a `varargs` function by providing a specific Ada profile + for a particular call. However, this does not work on + all platforms, since there is no guarantee that the + calling sequence for a two argument normal C function + is the same as for calling a `varargs` C function with + the same two arguments. + +.. index:: Convention Default + +.. index:: Default + +*Default* + Equivalent to C. + +.. index:: Convention External + +.. index:: External + +*External* + Equivalent to C. + +.. index:: C++ +.. index:: Interfacing to C++ + +.. index:: Convention C++ + + +*C_Plus_Plus (or CPP)* + This stands for C++. For most purposes this is identical to C. + See the separate description of the specialized GNAT pragmas relating to + C++ interfacing for further details. + +.. index:: Fortran +.. index:: Interfacing to Fortran +.. index:: Convention Fortran + + +*Fortran* + Data will be passed according to the conventions described + in section B.5 of the Ada Reference Manual. + + +*Intrinsic* + This applies to an intrinsic operation, as defined in the Ada + Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram, + this means that the body of the subprogram is provided by the compiler itself, + usually by means of an efficient code sequence, and that the user does not + supply an explicit body for it. In an application program, the pragma may + be applied to the following sets of names: + + + * Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_Arithmetic. + The corresponding subprogram declaration must have + two formal parameters. The + first one must be a signed integer type or a modular type with a binary + modulus, and the second parameter must be of type Natural. + The return type must be the same as the type of the first argument. The size + of this type can only be 8, 16, 32, or 64. + + + * Binary arithmetic operators: '+', '-', '*', '/'. + The corresponding operator declaration must have parameters and result type + that have the same root numeric type (for example, all three are long_float + types). This simplifies the definition of operations that use type checking + to perform dimensional checks: + + + .. code-block: ada + + type Distance is new Long_Float; + type Time is new Long_Float; + type Velocity is new Long_Float; + function "/" (D : Distance; T : Time) + return Velocity; + pragma Import (Intrinsic, "/"); + + This common idiom is often programmed with a generic definition and an + explicit body. The pragma makes it simpler to introduce such declarations. + It incurs no overhead in compilation time or code size, because it is + implemented as a single machine instruction. + + + * General subprogram entities. This is used to bind an Ada subprogram + declaration to + a compiler builtin by name with back-ends where such interfaces are + available. A typical example is the set of `__builtin` functions + exposed by the GCC back-end, as in the following example: + + + .. code-block:: ada + + function builtin_sqrt (F : Float) return Float; + pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf"); + + Most of the GCC builtins are accessible this way, and as for other + import conventions (e.g. C), it is the user's responsibility to ensure + that the Ada subprogram profile matches the underlying builtin + expectations. + +.. index:: Stdcall +.. index:: Convention Stdcall + +*Stdcall* + This is relevant only to Windows XP/2000/NT implementations of GNAT, + and specifies that the `Stdcall` calling sequence will be used, + as defined by the NT API. Nevertheless, to ease building + cross-platform bindings this convention will be handled as a `C` calling + convention on non-Windows platforms. + +.. index:: DLL +.. index:: Convention DLL + + +*DLL* + This is equivalent to `Stdcall`. + +.. index:: Win32 +.. index:: Convention Win32 + + +*Win32* + This is equivalent to `Stdcall`. + +.. index:: Stubbed +.. index:: Convention Stubbed + + +*Stubbed* + This is a special convention that indicates that the compiler + should provide a stub body that raises `Program_Error`. + +GNAT additionally provides a useful pragma `Convention_Identifier` +that can be used to parameterize conventions and allow additional synonyms +to be specified. For example if you have legacy code in which the convention +identifier Fortran77 was used for Fortran, you can use the configuration +pragma: + +.. code-block:: ada + + pragma Convention_Identifier (Fortran77, Fortran); + +And from now on the identifier Fortran77 may be used as a convention +identifier (for example in an `Import` pragma) with the same +meaning as Fortran. + + +.. _Building_Mixed_Ada_and_C++_Programs: + +Building Mixed Ada and C++ Programs +----------------------------------- + +A programmer inexperienced with mixed-language development may find that +building an application containing both Ada and C++ code can be a +challenge. This section gives a few hints that should make this task easier. + +.. _Interfacing_to_C++: + +Interfacing to C++ +^^^^^^^^^^^^^^^^^^ + +GNAT supports interfacing with the G++ compiler (or any C++ compiler +generating code that is compatible with the G++ Application Binary +Interface ---see http://www.codesourcery.com/archives/cxx-abi). + +Interfacing can be done at 3 levels: simple data, subprograms, and +classes. In the first two cases, GNAT offers a specific `Convention C_Plus_Plus` +(or `CPP`) that behaves exactly like `Convention C`. +Usually, C++ mangles the names of subprograms. To generate proper mangled +names automatically, see :ref:`Generating_Ada_Bindings_for_C_and_C++_headers`). +This problem can also be addressed manually in two ways: + +* by modifying the C++ code in order to force a C convention using + the `extern "C"` syntax. + +* by figuring out the mangled name (using e.g. *nm*) and using it as the + Link_Name argument of the pragma import. + +Interfacing at the class level can be achieved by using the GNAT specific +pragmas such as `CPP_Constructor`. See the :title:`GNAT_Reference_Manual` for additional information. + +.. _Linking_a_Mixed_C++_and_Ada_Program: + +Linking a Mixed C++ & Ada Program +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Usually the linker of the C++ development system must be used to link +mixed applications because most C++ systems will resolve elaboration +issues (such as calling constructors on global class instances) +transparently during the link phase. GNAT has been adapted to ease the +use of a foreign linker for the last phase. Three cases can be +considered: + + +* Using GNAT and G++ (GNU C++ compiler) from the same GCC installation: + The C++ linker can simply be called by using the C++ specific driver + called `g++`. + + Note that if the C++ code uses inline functions, you will need to + compile your C++ code with the `-fkeep-inline-functions` switch in + order to provide an existing function implementation that the Ada code can + link with. + + .. code-block:: sh + + $ g++ -c -fkeep-inline-functions file1.C + $ g++ -c -fkeep-inline-functions file2.C + $ gnatmake ada_unit -largs file1.o file2.o --LINK=g++ + + +* Using GNAT and G++ from two different GCC installations: If both + compilers are on the :envvar`PATH`, the previous method may be used. It is + important to note that environment variables such as + :envvar:`C_INCLUDE_PATH`, :envvar:`GCC_EXEC_PREFIX`, + :envvar:`BINUTILS_ROOT`, and + :envvar:`GCC_ROOT` will affect both compilers + at the same time and may make one of the two compilers operate + improperly if set during invocation of the wrong compiler. It is also + very important that the linker uses the proper :file:`libgcc.a` GCC + library -- that is, the one from the C++ compiler installation. The + implicit link command as suggested in the `gnatmake` command + from the former example can be replaced by an explicit link command with + the full-verbosity option in order to verify which library is used: + + .. code-block:: sh + + $ gnatbind ada_unit + $ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ + + If there is a problem due to interfering environment variables, it can + be worked around by using an intermediate script. The following example + shows the proper script to use when GNAT has not been installed at its + default location and g++ has been installed at its default location: + + .. code-block:: sh + + $ cat ./my_script + #!/bin/sh + unset BINUTILS_ROOT + unset GCC_ROOT + c++ $* + $ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script + + +* Using a non-GNU C++ compiler: The commands previously described can be + used to insure that the C++ linker is used. Nonetheless, you need to add + a few more parameters to the link command line, depending on the exception + mechanism used. + + If the `setjmp/longjmp` exception mechanism is used, only the paths + to the libgcc libraries are required: + + .. code-block:: sh + + $ cat ./my_script + #!/bin/sh + CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` + $ gnatlink ada_unit file1.o file2.o --LINK=./my_script + + + where CC is the name of the non-GNU C++ compiler. + + If the `zero cost` exception mechanism is used, and the platform + supports automatic registration of exception tables (e.g., Solaris), + paths to more objects are required: + + .. code-block:: sh + + $ cat ./my_script + #!/bin/sh + CC `gcc -print-file-name=crtbegin.o` $* \\ + `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \\ + `gcc -print-file-name=crtend.o` + $ gnatlink ada_unit file1.o file2.o --LINK=./my_script + + + If the "zero cost exception" mechanism is used, and the platform + doesn't support automatic registration of exception tables (e.g., HP-UX + or AIX), the simple approach described above will not work and + a pre-linking phase using GNAT will be necessary. + + +Another alternative is to use the :command:`gprbuild` multi-language builder +which has a large knowledge base and knows how to link Ada and C++ code +together automatically in most cases. + +.. _A_Simple_Example: + +A Simple Example +^^^^^^^^^^^^^^^^ + +The following example, provided as part of the GNAT examples, shows how +to achieve procedural interfacing between Ada and C++ in both +directions. The C++ class A has two methods. The first method is exported +to Ada by the means of an extern C wrapper function. The second method +calls an Ada subprogram. On the Ada side, The C++ calls are modelled by +a limited record with a layout comparable to the C++ class. The Ada +subprogram, in turn, calls the C++ method. So, starting from the C++ +main program, the process passes back and forth between the two +languages. + +Here are the compilation commands: + +.. code-block:: sh + + $ gnatmake -c simple_cpp_interface + $ g++ -c cpp_main.C + $ g++ -c ex7.C + $ gnatbind -n simple_cpp_interface + $ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ -lstdc++ ex7.o cpp_main.o + +Here are the corresponding sources: + +.. code-block:: cpp + + //cpp_main.C + + #include "ex7.h" + + extern "C" { + void adainit (void); + void adafinal (void); + void method1 (A *t); + } + + void method1 (A *t) + { + t->method1 (); + } + + int main () + { + A obj; + adainit (); + obj.method2 (3030); + adafinal (); + } + +.. code-block:: cpp + + //ex7.h + + class Origin { + public: + int o_value; + }; + class A : public Origin { + public: + void method1 (void); + void method2 (int v); + A(); + int a_value; + }; + +.. code-block:: cpp + + //ex7.C + + #include "ex7.h" + #include <stdio.h> + + extern "C" { void ada_method2 (A *t, int v);} + + void A::method1 (void) + { + a_value = 2020; + printf ("in A::method1, a_value = %d \\n",a_value); + } + + void A::method2 (int v) + { + ada_method2 (this, v); + printf ("in A::method2, a_value = %d \\n",a_value); + } + + A::A(void) + { + a_value = 1010; + printf ("in A::A, a_value = %d \\n",a_value); + } + +.. code-block:: ada + + -- simple_cpp_interface.ads + with System; + package Simple_Cpp_Interface is + type A is limited + record + Vptr : System.Address; + O_Value : Integer; + A_Value : Integer; + end record; + pragma Convention (C, A); + + procedure Method1 (This : in out A); + pragma Import (C, Method1); + + procedure Ada_Method2 (This : in out A; V : Integer); + pragma Export (C, Ada_Method2); + + end Simple_Cpp_Interface; + +.. code-block:: ada + + -- simple_cpp_interface.adb + package body Simple_Cpp_Interface is + + procedure Ada_Method2 (This : in out A; V : Integer) is + begin + Method1 (This); + This.A_Value := V; + end Ada_Method2; + + end Simple_Cpp_Interface; + + +.. _Interfacing_with_C++_constructors: + +Interfacing with C++ constructors +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In order to interface with C++ constructors GNAT provides the +`pragma CPP_Constructor` (see the :title:`GNAT_Reference_Manual` +for additional information). +In this section we present some common uses of C++ constructors +in mixed-languages programs in GNAT. + +Let us assume that we need to interface with the following +C++ class: + +.. code-block:: cpp + + class Root { + public: + int a_value; + int b_value; + virtual int Get_Value (); + Root(); // Default constructor + Root(int v); // 1st non-default constructor + Root(int v, int w); // 2nd non-default constructor + }; + +For this purpose we can write the following package spec (further +information on how to build this spec is available in +:ref:`Interfacing_with_C++_at_the_Class_Level` and +:ref:`Generating_Ada_Bindings_for_C_and_C++_headers`). + +.. code-block:: ada + + with Interfaces.C; use Interfaces.C; + package Pkg_Root is + type Root is tagged limited record + A_Value : int; + B_Value : int; + end record; + pragma Import (CPP, Root); + + function Get_Value (Obj : Root) return int; + pragma Import (CPP, Get_Value); + + function Constructor return Root; + pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev"); + + function Constructor (v : Integer) return Root; + pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei"); + + function Constructor (v, w : Integer) return Root; + pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii"); + end Pkg_Root; + +On the Ada side the constructor is represented by a function (whose +name is arbitrary) that returns the classwide type corresponding to +the imported C++ class. Although the constructor is described as a +function, it is typically a procedure with an extra implicit argument +(the object being initialized) at the implementation level. GNAT +issues the appropriate call, whatever it is, to get the object +properly initialized. + +Constructors can only appear in the following contexts: + +* On the right side of an initialization of an object of type `T`. +* On the right side of an initialization of a record component of type `T`. +* In an Ada 2005 limited aggregate. +* In an Ada 2005 nested limited aggregate. +* In an Ada 2005 limited aggregate that initializes an object built in + place by an extended return statement. + +In a declaration of an object whose type is a class imported from C++, +either the default C++ constructor is implicitly called by GNAT, or +else the required C++ constructor must be explicitly called in the +expression that initializes the object. For example: + +.. code-block:: ada + + Obj1 : Root; + Obj2 : Root := Constructor; + Obj3 : Root := Constructor (v => 10); + Obj4 : Root := Constructor (30, 40); + +The first two declarations are equivalent: in both cases the default C++ +constructor is invoked (in the former case the call to the constructor is +implicit, and in the latter case the call is explicit in the object +declaration). `Obj3` is initialized by the C++ non-default constructor +that takes an integer argument, and `Obj4` is initialized by the +non-default C++ constructor that takes two integers. + +Let us derive the imported C++ class in the Ada side. For example: + +.. code-block:: ada + + type DT is new Root with record + C_Value : Natural := 2009; + end record; + +In this case the components DT inherited from the C++ side must be +initialized by a C++ constructor, and the additional Ada components +of type DT are initialized by GNAT. The initialization of such an +object is done either by default, or by means of a function returning +an aggregate of type DT, or by means of an extension aggregate. + +.. code-block:: ada + + Obj5 : DT; + Obj6 : DT := Function_Returning_DT (50); + Obj7 : DT := (Constructor (30,40) with C_Value => 50); + +The declaration of `Obj5` invokes the default constructors: the +C++ default constructor of the parent type takes care of the initialization +of the components inherited from Root, and GNAT takes care of the default +initialization of the additional Ada components of type DT (that is, +`C_Value` is initialized to value 2009). The order of invocation of +the constructors is consistent with the order of elaboration required by +Ada and C++. That is, the constructor of the parent type is always called +before the constructor of the derived type. + +Let us now consider a record that has components whose type is imported +from C++. For example: + +.. code-block:: ada + + type Rec1 is limited record + Data1 : Root := Constructor (10); + Value : Natural := 1000; + end record; + + type Rec2 (D : Integer := 20) is limited record + Rec : Rec1; + Data2 : Root := Constructor (D, 30); + end record; + +The initialization of an object of type `Rec2` will call the +non-default C++ constructors specified for the imported components. +For example: + +.. code-block:: ada + + Obj8 : Rec2 (40); + +Using Ada 2005 we can use limited aggregates to initialize an object +invoking C++ constructors that differ from those specified in the type +declarations. For example: + +.. code-block:: ada + + Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16), + others => <>), + others => <>); + +The above declaration uses an Ada 2005 limited aggregate to +initialize `Obj9`, and the C++ constructor that has two integer +arguments is invoked to initialize the `Data1` component instead +of the constructor specified in the declaration of type `Rec1`. In +Ada 2005 the box in the aggregate indicates that unspecified components +are initialized using the expression (if any) available in the component +declaration. That is, in this case discriminant `D` is initialized +to value `20`, `Value` is initialized to value 1000, and the +non-default C++ constructor that handles two integers takes care of +initializing component `Data2` with values `20,30`. + +In Ada 2005 we can use the extended return statement to build the Ada +equivalent to C++ non-default constructors. For example: + +.. code-block:: ada + + function Constructor (V : Integer) return Rec2 is + begin + return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20), + others => <>), + others => <>) do + -- Further actions required for construction of + -- objects of type Rec2 + ... + end record; + end Constructor; + +In this example the extended return statement construct is used to +build in place the returned object whose components are initialized +by means of a limited aggregate. Any further action associated with +the constructor can be placed inside the construct. + +.. _Interfacing_with_C++_at_the_Class_Level: + +Interfacing with C++ at the Class Level +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In this section we demonstrate the GNAT features for interfacing with +C++ by means of an example making use of Ada 2005 abstract interface +types. This example consists of a classification of animals; classes +have been used to model our main classification of animals, and +interfaces provide support for the management of secondary +classifications. We first demonstrate a case in which the types and +constructors are defined on the C++ side and imported from the Ada +side, and latter the reverse case. + +The root of our derivation will be the `Animal` class, with a +single private attribute (the `Age` of the animal), a constructor, +and two public primitives to set and get the value of this attribute. + +.. code-block:: cpp + + class Animal { + public: + virtual void Set_Age (int New_Age); + virtual int Age (); + Animal() {Age_Count = 0;}; + private: + int Age_Count; + }; + +Abstract interface types are defined in C++ by means of classes with pure +virtual functions and no data members. In our example we will use two +interfaces that provide support for the common management of `Carnivore` +and `Domestic` animals: + +.. code-block:: cpp + + class Carnivore { + public: + virtual int Number_Of_Teeth () = 0; + }; + + class Domestic { + public: + virtual void Set_Owner (char* Name) = 0; + }; + +Using these declarations, we can now say that a `Dog` is an animal that is +both Carnivore and Domestic, that is: + +.. code-block:: cpp + + class Dog : Animal, Carnivore, Domestic { + public: + virtual int Number_Of_Teeth (); + virtual void Set_Owner (char* Name); + + Dog(); // Constructor + private: + int Tooth_Count; + char *Owner; + }; + +In the following examples we will assume that the previous declarations are +located in a file named `animals.h`. The following package demonstrates +how to import these C++ declarations from the Ada side: + +.. code-block:: ada + + with Interfaces.C.Strings; use Interfaces.C.Strings; + package Animals is + type Carnivore is limited interface; + pragma Convention (C_Plus_Plus, Carnivore); + function Number_Of_Teeth (X : Carnivore) + return Natural is abstract; + + type Domestic is limited interface; + pragma Convention (C_Plus_Plus, Domestic); + procedure Set_Owner + (X : in out Domestic; + Name : Chars_Ptr) is abstract; + + type Animal is tagged limited record + Age : Natural; + end record; + pragma Import (C_Plus_Plus, Animal); + + procedure Set_Age (X : in out Animal; Age : Integer); + pragma Import (C_Plus_Plus, Set_Age); + + function Age (X : Animal) return Integer; + pragma Import (C_Plus_Plus, Age); + + function New_Animal return Animal; + pragma CPP_Constructor (New_Animal); + pragma Import (CPP, New_Animal, "_ZN6AnimalC1Ev"); + + type Dog is new Animal and Carnivore and Domestic with record + Tooth_Count : Natural; + Owner : String (1 .. 30); + end record; + pragma Import (C_Plus_Plus, Dog); + + function Number_Of_Teeth (A : Dog) return Natural; + pragma Import (C_Plus_Plus, Number_Of_Teeth); + + procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); + pragma Import (C_Plus_Plus, Set_Owner); + + function New_Dog return Dog; + pragma CPP_Constructor (New_Dog); + pragma Import (CPP, New_Dog, "_ZN3DogC2Ev"); + end Animals; + +Thanks to the compatibility between GNAT run-time structures and the C++ ABI, +interfacing with these C++ classes is easy. The only requirement is that all +the primitives and components must be declared exactly in the same order in +the two languages. + +Regarding the abstract interfaces, we must indicate to the GNAT compiler by +means of a `pragma Convention (C_Plus_Plus)`, the convention used to pass +the arguments to the called primitives will be the same as for C++. For the +imported classes we use `pragma Import` with convention `C_Plus_Plus` +to indicate that they have been defined on the C++ side; this is required +because the dispatch table associated with these tagged types will be built +in the C++ side and therefore will not contain the predefined Ada primitives +which Ada would otherwise expect. + +As the reader can see there is no need to indicate the C++ mangled names +associated with each subprogram because it is assumed that all the calls to +these primitives will be dispatching calls. The only exception is the +constructor, which must be registered with the compiler by means of +`pragma CPP_Constructor` and needs to provide its associated C++ +mangled name because the Ada compiler generates direct calls to it. + +With the above packages we can now declare objects of type Dog on the Ada side +and dispatch calls to the corresponding subprograms on the C++ side. We can +also extend the tagged type Dog with further fields and primitives, and +override some of its C++ primitives on the Ada side. For example, here we have +a type derivation defined on the Ada side that inherits all the dispatching +primitives of the ancestor from the C++ side. + +.. code-block:: ada + + with Animals; use Animals; + package Vaccinated_Animals is + type Vaccinated_Dog is new Dog with null record; + function Vaccination_Expired (A : Vaccinated_Dog) return Boolean; + end Vaccinated_Animals; + +It is important to note that, because of the ABI compatibility, the programmer +does not need to add any further information to indicate either the object +layout or the dispatch table entry associated with each dispatching operation. + +Now let us define all the types and constructors on the Ada side and export +them to C++, using the same hierarchy of our previous example: + +.. code-block:: ada + + with Interfaces.C.Strings; + use Interfaces.C.Strings; + package Animals is + type Carnivore is limited interface; + pragma Convention (C_Plus_Plus, Carnivore); + function Number_Of_Teeth (X : Carnivore) + return Natural is abstract; + + type Domestic is limited interface; + pragma Convention (C_Plus_Plus, Domestic); + procedure Set_Owner + (X : in out Domestic; + Name : Chars_Ptr) is abstract; + + type Animal is tagged record + Age : Natural; + end record; + pragma Convention (C_Plus_Plus, Animal); + + procedure Set_Age (X : in out Animal; Age : Integer); + pragma Export (C_Plus_Plus, Set_Age); + + function Age (X : Animal) return Integer; + pragma Export (C_Plus_Plus, Age); + + function New_Animal return Animal'Class; + pragma Export (C_Plus_Plus, New_Animal); + + type Dog is new Animal and Carnivore and Domestic with record + Tooth_Count : Natural; + Owner : String (1 .. 30); + end record; + pragma Convention (C_Plus_Plus, Dog); + + function Number_Of_Teeth (A : Dog) return Natural; + pragma Export (C_Plus_Plus, Number_Of_Teeth); + + procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); + pragma Export (C_Plus_Plus, Set_Owner); + + function New_Dog return Dog'Class; + pragma Export (C_Plus_Plus, New_Dog); + end Animals; + +Compared with our previous example the only differences are the use of +`pragma Convention` (instead of `pragma Import`), and the use of +`pragma Export` to indicate to the GNAT compiler that the primitives will +be available to C++. Thanks to the ABI compatibility, on the C++ side there is +nothing else to be done; as explained above, the only requirement is that all +the primitives and components are declared in exactly the same order. + +For completeness, let us see a brief C++ main program that uses the +declarations available in `animals.h` (presented in our first example) to +import and use the declarations from the Ada side, properly initializing and +finalizing the Ada run-time system along the way: + +.. code-block:: cpp + + #include "animals.h" + #include <iostream> + using namespace std; + + void Check_Carnivore (Carnivore *obj) {...} + void Check_Domestic (Domestic *obj) {...} + void Check_Animal (Animal *obj) {...} + void Check_Dog (Dog *obj) {...} + + extern "C" { + void adainit (void); + void adafinal (void); + Dog* new_dog (); + } + + void test () + { + Dog *obj = new_dog(); // Ada constructor + Check_Carnivore (obj); // Check secondary DT + Check_Domestic (obj); // Check secondary DT + Check_Animal (obj); // Check primary DT + Check_Dog (obj); // Check primary DT + } + + int main () + { + adainit (); test(); adafinal (); + return 0; + } + +.. _Generating_Ada_Bindings_for_C_and_C++_headers: + +Generating Ada Bindings for C and C++ headers +--------------------------------------------- + +.. index:: Binding generation (for C and C++ headers) +.. index:: C headers (binding generation) +.. index:: C++ headers (binding generation) + +GNAT includes a binding generator for C and C++ headers which is +intended to do 95% of the tedious work of generating Ada specs from C +or C++ header files. + +Note that this capability is not intended to generate 100% correct Ada specs, +and will is some cases require manual adjustments, although it can often +be used out of the box in practice. + +Some of the known limitations include: + +* only very simple character constant macros are translated into Ada + constants. Function macros (macros with arguments) are partially translated + as comments, to be completed manually if needed. +* some extensions (e.g. vector types) are not supported +* pointers to pointers or complex structures are mapped to System.Address +* identifiers with identical name (except casing) will generate compilation + errors (e.g. `shm_get` vs `SHM_GET`). + +The code generated is using the Ada 2005 syntax, which makes it +easier to interface with other languages than previous versions of Ada. + +.. _Running_the_binding_generator: + +Running the binding generator +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The binding generator is part of the *gcc* compiler and can be +invoked via the *-fdump-ada-spec* switch, which will generate Ada +spec files for the header files specified on the command line, and all +header files needed by these files transitively. For example: + +.. code-block:: sh + + $ g++ -c -fdump-ada-spec -C /usr/include/time.h + $ gcc -c -gnat05 *.ads + +will generate, under GNU/Linux, the following files: :file:`time_h.ads`, +:file:`bits_time_h.ads`, :file:`stddef_h.ads`, :file:`bits_types_h.ads` which +correspond to the files :file:`/usr/include/time.h`, +:file:`/usr/include/bits/time.h`, etc..., and will then compile in Ada 2005 +mode these Ada specs. + +The `-C` switch tells *gcc* to extract comments from headers, +and will attempt to generate corresponding Ada comments. + +If you want to generate a single Ada file and not the transitive closure, you +can use instead the *-fdump-ada-spec-slim* switch. + +You can optionally specify a parent unit, of which all generated units will +be children, using `-fada-spec-parent=``unit`. + +Note that we recommend when possible to use the *g++* driver to +generate bindings, even for most C headers, since this will in general +generate better Ada specs. For generating bindings for C++ headers, it is +mandatory to use the *g++* command, or *gcc -x c++* which +is equivalent in this case. If *g++* cannot work on your C headers +because of incompatibilities between C and C++, then you can fallback to +*gcc* instead. + +For an example of better bindings generated from the C++ front-end, +the name of the parameters (when available) are actually ignored by the C +front-end. Consider the following C header: + +.. code-block:: c + + extern void foo (int variable); + +with the C front-end, `variable` is ignored, and the above is handled as: + +.. code-block:: c + + extern void foo (int); + +generating a generic: + +.. code-block:: ada + + procedure foo (param1 : int); + +with the C++ front-end, the name is available, and we generate: + +.. code-block:: ada + + procedure foo (variable : int); + +In some cases, the generated bindings will be more complete or more meaningful +when defining some macros, which you can do via the *-D* switch. This +is for example the case with :file:`Xlib.h` under GNU/Linux: + +.. code-block:: sh + + $ g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h + +The above will generate more complete bindings than a straight call without +the *-DXLIB_ILLEGAL_ACCESS* switch. + +In other cases, it is not possible to parse a header file in a stand-alone +manner, because other include files need to be included first. In this +case, the solution is to create a small header file including the needed +`#include` and possible `#define` directives. For example, to +generate Ada bindings for :file:`readline/readline.h`, you need to first +include :file:`stdio.h`, so you can create a file with the following two +lines in e.g. :file:`readline1.h`: + +.. code-block:: cpp + + #include <stdio.h> + #include <readline/readline.h> + +and then generate Ada bindings from this file: + +.. code-block:: sh + + $ g++ -c -fdump-ada-spec readline1.h + + +.. _Generating_bindings_for_C++_headers: + +Generating bindings for C++ headers +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Generating bindings for C++ headers is done using the same options, always +with the *g++* compiler. Note that generating Ada spec from C++ headers is a +much more complex job and support for C++ headers is much more limited that +support for C headers. As a result, you will need to modify the resulting +bindings by hand more extensively when using C++ headers. + +In this mode, C++ classes will be mapped to Ada tagged types, constructors +will be mapped using the `CPP_Constructor` pragma, and when possible, +multiple inheritance of abstract classes will be mapped to Ada interfaces +(see the *Interfacing to C++* section in the :title:`GNAT Reference Manual` +for additional information on interfacing to C++). + +For example, given the following C++ header file: + +.. code-block:: cpp + + class Carnivore { + public: + virtual int Number_Of_Teeth () = 0; + }; + + class Domestic { + public: + virtual void Set_Owner (char* Name) = 0; + }; + + class Animal { + public: + int Age_Count; + virtual void Set_Age (int New_Age); + }; + + class Dog : Animal, Carnivore, Domestic { + public: + int Tooth_Count; + char *Owner; + + virtual int Number_Of_Teeth (); + virtual void Set_Owner (char* Name); + + Dog(); + }; + +The corresponding Ada code is generated: + +.. code-block:: ada + + package Class_Carnivore is + type Carnivore is limited interface; + pragma Import (CPP, Carnivore); + + function Number_Of_Teeth (this : access Carnivore) return int is abstract; + end; + use Class_Carnivore; + + package Class_Domestic is + type Domestic is limited interface; + pragma Import (CPP, Domestic); + + procedure Set_Owner + (this : access Domestic; + Name : Interfaces.C.Strings.chars_ptr) is abstract; + end; + use Class_Domestic; + + package Class_Animal is + type Animal is tagged limited record + Age_Count : aliased int; + end record; + pragma Import (CPP, Animal); + + procedure Set_Age (this : access Animal; New_Age : int); + pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi"); + end; + use Class_Animal; + + package Class_Dog is + type Dog is new Animal and Carnivore and Domestic with record + Tooth_Count : aliased int; + Owner : Interfaces.C.Strings.chars_ptr; + end record; + pragma Import (CPP, Dog); + + function Number_Of_Teeth (this : access Dog) return int; + pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv"); + + procedure Set_Owner + (this : access Dog; Name : Interfaces.C.Strings.chars_ptr); + pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc"); + + function New_Dog return Dog; + pragma CPP_Constructor (New_Dog); + pragma Import (CPP, New_Dog, "_ZN3DogC1Ev"); + end; + use Class_Dog; + + +.. _Switches_for_Ada_Binding_Generation: + +Switches +^^^^^^^^ + +.. index:: -fdump-ada-spec (gcc) + +:samp:`-fdump-ada-spec` + Generate Ada spec files for the given header files transitively (including + all header files that these headers depend upon). + +.. index:: -fdump-ada-spec-slim (gcc) + +:samp:`-fdump-ada-spec-slim` + Generate Ada spec files for the header files specified on the command line + only. + +.. index:: -fada-spec-parent (gcc) + +:samp:`-fada-spec-parent={unit}` + Specifies that all files generated by *-fdump-ada-spec** are + to be child units of the specified parent unit. + +.. index:: -C (gcc) + +:samp:`-C` + Extract comments from headers and generate Ada comments in the Ada spec files. + + +.. _GNAT_and_Other_Compilation_Models: + +GNAT and Other Compilation Models +================================= + +This section compares the GNAT model with the approaches taken in +other environents, first the C/C++ model and then the mechanism that +has been used in other Ada systems, in particular those traditionally +used for Ada 83. + +.. _Comparison_between_GNAT_and_C/C++_Compilation_Models: + +Comparison between GNAT and C/C++ Compilation Models +---------------------------------------------------- + +The GNAT model of compilation is close to the C and C++ models. You can +think of Ada specs as corresponding to header files in C. As in C, you +don't need to compile specs; they are compiled when they are used. The +Ada |with| is similar in effect to the `#include` of a C +header. + +One notable difference is that, in Ada, you may compile specs separately +to check them for semantic and syntactic accuracy. This is not always +possible with C headers because they are fragments of programs that have +less specific syntactic or semantic rules. + +The other major difference is the requirement for running the binder, +which performs two important functions. First, it checks for +consistency. In C or C++, the only defense against assembling +inconsistent programs lies outside the compiler, in a makefile, for +example. The binder satisfies the Ada requirement that it be impossible +to construct an inconsistent program when the compiler is used in normal +mode. + +.. index:: Elaboration order control + +The other important function of the binder is to deal with elaboration +issues. There are also elaboration issues in C++ that are handled +automatically. This automatic handling has the advantage of being +simpler to use, but the C++ programmer has no control over elaboration. +Where `gnatbind` might complain there was no valid order of +elaboration, a C++ compiler would simply construct a program that +malfunctioned at run time. + +.. _Comparison_between_GNAT_and_Conventional_Ada_Library_Models: + +Comparison between GNAT and Conventional Ada Library Models +----------------------------------------------------------- + +This section is intended for Ada programmers who have +used an Ada compiler implementing the traditional Ada library +model, as described in the Ada Reference Manual. + +.. index:: GNAT library + +In GNAT, there is no 'library' in the normal sense. Instead, the set of +source files themselves acts as the library. Compiling Ada programs does +not generate any centralized information, but rather an object file and +a ALI file, which are of interest only to the binder and linker. +In a traditional system, the compiler reads information not only from +the source file being compiled, but also from the centralized library. +This means that the effect of a compilation depends on what has been +previously compiled. In particular: + +* When a unit is |withed|, the unit seen by the compiler corresponds + to the version of the unit most recently compiled into the library. + +* Inlining is effective only if the necessary body has already been + compiled into the library. + +* Compiling a unit may obsolete other units in the library. + +In GNAT, compiling one unit never affects the compilation of any other +units because the compiler reads only source files. Only changes to source +files can affect the results of a compilation. In particular: + +* When a unit is |withed|, the unit seen by the compiler corresponds + to the source version of the unit that is currently accessible to the + compiler. + + .. index:: Inlining + +* Inlining requires the appropriate source files for the package or + subprogram bodies to be available to the compiler. Inlining is always + effective, independent of the order in which units are compiled. + +* Compiling a unit never affects any other compilations. The editing of + sources may cause previous compilations to be out of date if they + depended on the source file being modified. + +The most important result of these differences is that order of compilation +is never significant in GNAT. There is no situation in which one is +required to do one compilation before another. What shows up as order of +compilation requirements in the traditional Ada library becomes, in +GNAT, simple source dependencies; in other words, there is only a set +of rules saying what source files must be present when a file is +compiled. + + +.. _Using_GNAT_Files_with_External_Tools: + +Using GNAT Files with External Tools +==================================== + +This section explains how files that are produced by GNAT may be +used with tools designed for other languages. + + +.. _Using_Other_Utility_Programs_with_GNAT: + +Using Other Utility Programs with GNAT +-------------------------------------- + +The object files generated by GNAT are in standard system format and in +particular the debugging information uses this format. This means +programs generated by GNAT can be used with existing utilities that +depend on these formats. + +In general, any utility program that works with C will also often work with +Ada programs generated by GNAT. This includes software utilities such as +gprof (a profiling program), gdb (the FSF debugger), and utilities such +as Purify. + + +.. _The_External_Symbol_Naming_Scheme_of_GNAT: + +The External Symbol Naming Scheme of GNAT +----------------------------------------- + +In order to interpret the output from GNAT, when using tools that are +originally intended for use with other languages, it is useful to +understand the conventions used to generate link names from the Ada +entity names. + +All link names are in all lowercase letters. With the exception of library +procedure names, the mechanism used is simply to use the full expanded +Ada name with dots replaced by double underscores. For example, suppose +we have the following package spec: + +.. code-block:: ada + + package QRS is + MN : Integer; + end QRS; + +.. index:: pragma Export + +The variable `MN` has a full expanded Ada name of `QRS.MN`, so +the corresponding link name is `qrs__mn`. +Of course if a `pragma Export` is used this may be overridden: + +.. code-block:: ada + + package Exports is + Var1 : Integer; + pragma Export (Var1, C, External_Name => "var1_name"); + Var2 : Integer; + pragma Export (Var2, C, Link_Name => "var2_link_name"); + end Exports; + +In this case, the link name for `Var1` is whatever link name the +C compiler would assign for the C function `var1_name`. This typically +would be either `var1_name` or `_var1_name`, depending on operating +system conventions, but other possibilities exist. The link name for +`Var2` is `var2_link_name`, and this is not operating system +dependent. + +One exception occurs for library level procedures. A potential ambiguity +arises between the required name `_main` for the C main program, +and the name we would otherwise assign to an Ada library level procedure +called `Main` (which might well not be the main program). + +To avoid this ambiguity, we attach the prefix `_ada_` to such +names. So if we have a library level procedure such as: + +.. code-block:: ada + + procedure Hello (S : String); + +the external name of this procedure will be `_ada_hello`. + diff --git a/gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst b/gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst new file mode 100644 index 00000000000..7360acb0b8a --- /dev/null +++ b/gcc/ada/doc/gnat_ugn/tools_supporting_project_files.rst @@ -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. diff --git a/gcc/ada/doc/share/ada_pygments.py b/gcc/ada/doc/share/ada_pygments.py new file mode 100644 index 00000000000..27462a3226d --- /dev/null +++ b/gcc/ada/doc/share/ada_pygments.py @@ -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) diff --git a/gcc/ada/doc/share/conf.py b/gcc/ada/doc/share/conf.py new file mode 100644 index 00000000000..c6c45b08aa8 --- /dev/null +++ b/gcc/ada/doc/share/conf.py @@ -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()) diff --git a/gcc/ada/doc/share/gnu_free_documentation_license.rst b/gcc/ada/doc/share/gnu_free_documentation_license.rst new file mode 100644 index 00000000000..c18cf6673c5 --- /dev/null +++ b/gcc/ada/doc/share/gnu_free_documentation_license.rst @@ -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. diff --git a/gcc/ada/doc/share/latex_elements.py b/gcc/ada/doc/share/latex_elements.py new file mode 100644 index 00000000000..cf8fbe1a949 --- /dev/null +++ b/gcc/ada/doc/share/latex_elements.py @@ -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'}']) diff --git a/gcc/ada/doc/share/sphinx.sty b/gcc/ada/doc/share/sphinx.sty new file mode 100644 index 00000000000..2af577a3b3e --- /dev/null +++ b/gcc/ada/doc/share/sphinx.sty @@ -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 |