@copying
@quotation
-GNAT User's Guide for Native Platforms , Dec 15, 2017
+GNAT User's Guide for Native Platforms , Dec 11, 2020
AdaCore
-Copyright @copyright{} 2008-2017, Free Software Foundation
+Copyright @copyright{} 2008-2021, Free Software Foundation
@end quotation
@end copying
* What This Guide Contains::
* What You Should Know before Reading This Guide::
* Related Information::
-* A Note to Readers of Previous Versions of the Manual::
* Conventions::
Getting Started with GNAT
+* System Requirements::
* Running GNAT::
* Running a Simple Ada Program::
* Running a Program with Multiple Units::
-* Using the gnatmake Utility::
The GNAT Compilation Model
* The File Cleanup Utility gnatclean::
* The GNAT Library Browser gnatls::
-* The Cross-Referencing Tools gnatxref and gnatfind::
-* The Ada to HTML Converter gnathtml::
The File Cleanup Utility gnatclean
* Switches for gnatls::
* Example of gnatls Usage::
-The Cross-Referencing Tools gnatxref and gnatfind
-
-* gnatxref Switches::
-* gnatfind Switches::
-* Configuration Files for gnatxref and gnatfind::
-* Regular Expressions in gnatfind and gnatxref::
-* Examples of gnatxref Usage::
-* Examples of gnatfind Usage::
-
-Examples of gnatxref Usage
-
-* General Usage::
-* Using gnatxref with vi::
-
-The Ada to HTML Converter gnathtml
-
-* Invoking gnathtml::
-* Installing gnathtml::
-
GNAT and Program Execution
* Running and Debugging Ada Programs::
-* Code Coverage and Profiling::
+* Profiling::
* Improving Performance::
* Overflow Check Handling in GNAT::
* Performing Dimensionality Analysis in GNAT::
* Non-Symbolic Traceback::
* Symbolic Traceback::
-Code Coverage and Profiling
+Profiling
-* Code Coverage of Ada Programs with gcov::
* Profiling an Ada Program with gprof::
-Code Coverage of Ada Programs with gcov
-
-* Quick startup guide::
-* GNAT specifics::
-
Profiling an Ada Program with gprof
* Compilation for profiling::
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
-* Floating_Point_Operations::
+* Floating Point Operations::
* Vectorization of loops::
* Other Optimization Switches::
* Optimization and Strict Aliasing::
* CONSOLE and WINDOWS subsystems::
* Temporary Files::
* Disabling Command Line Argument Expansion::
+* Windows Socket Timeouts::
* Mixed-Language Programming on Windows::
* Windows Specific Add-Ons::
* Checking the Elaboration Order::
* Controlling the Elaboration Order in Ada::
* Controlling the Elaboration Order in GNAT::
-* Common Elaboration-model Traits::
-* Dynamic Elaboration Model in GNAT::
-* Static Elaboration Model in GNAT::
-* SPARK Elaboration Model in GNAT::
-* Legacy Elaboration Model in GNAT::
* Mixing Elaboration Models::
+* ABE Diagnostics::
+* SPARK Diagnostics::
* Elaboration Circularities::
* Resolving Elaboration Circularities::
-* Resolving Task Issues::
* Elaboration-related Compiler Switches::
* Summary of Procedures for Elaboration Control::
* Inspecting the Chosen Elaboration Order::
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
+GNAT implements Ada 95, Ada 2005, Ada 2012, and Ada 202x, 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{6,,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.
+apply to all Ada versions of the language, starting with Ada 95.
@menu
* What This Guide Contains::
* What You Should Know before Reading This Guide::
* Related Information::
-* A Note to Readers of Previous Versions of the Manual::
* Conventions::
@end menu
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.
-@node Related Information,A Note to Readers of Previous Versions of the Manual,What You Should Know before Reading This Guide,About This Guide
+@node Related Information,Conventions,What You Should Know before Reading This Guide,About This Guide
@anchor{gnat_ugn/about_this_guide related-information}@anchor{12}
@section Related Information
implementation of Ada.
@item
-@cite{Using the GNAT Programming Studio}, which describes the GPS
+@cite{Using GNAT Studio}, which describes the GNAT Studio
Integrated Development Environment.
@item
-@cite{GNAT Programming Studio Tutorial}, which introduces the
-main GPS features through examples.
+@cite{GNAT Studio Tutorial}, which introduces the
+main GNAT Studio features through examples.
@item
@cite{Debugging with GDB},
environment Emacs.
@end itemize
-@node A Note to Readers of Previous Versions of the Manual,Conventions,Related Information,About This Guide
-@anchor{gnat_ugn/about_this_guide a-note-to-readers-of-previous-versions-of-the-manual}@anchor{13}
-@section 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 @cite{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.
-
-
-@itemize *
-
-@item
-@ref{9,,The GNAT Compilation Model} has been extended so that it now covers
-the following material:
-
-
-@itemize -
-
-@item
-The @code{gnatname}, @code{gnatkr}, and @code{gnatchop} tools
-
-@item
-@ref{14,,Configuration Pragmas}
-
-@item
-@ref{15,,GNAT and Libraries}
-
-@item
-@ref{16,,Conditional Compilation} including @ref{17,,Preprocessing with gnatprep}
-and @ref{18,,Integrated Preprocessing}
-
-@item
-@ref{19,,Generating Ada Bindings for C and C++ headers}
-
-@item
-@ref{1a,,Using GNAT Files with External Tools}
-@end itemize
-
-@item
-@ref{a,,Building Executable Programs with GNAT} is a new chapter consolidating
-the following content:
-
-
-@itemize -
-
-@item
-@ref{1b,,Building with gnatmake}
-
-@item
-@ref{1c,,Compiling with gcc}
-
-@item
-@ref{1d,,Binding with gnatbind}
-
-@item
-@ref{1e,,Linking with gnatlink}
-
-@item
-@ref{1f,,Using the GNU make Utility}
-@end itemize
-
-@item
-@ref{b,,GNAT Utility Programs} is a new chapter consolidating the information about several
-GNAT tools:
-
-
-
-@itemize -
-
-@item
-@ref{20,,The File Cleanup Utility gnatclean}
-
-@item
-@ref{21,,The GNAT Library Browser gnatls}
-
-@item
-@ref{22,,The Cross-Referencing Tools gnatxref and gnatfind}
-
-@item
-@ref{23,,The Ada to HTML Converter gnathtml}
-@end itemize
-
-@item
-@ref{c,,GNAT and Program Execution} is a new chapter consolidating the following:
-
-
-@itemize -
-
-@item
-@ref{24,,Running and Debugging Ada Programs}
-
-@item
-@ref{25,,Code Coverage and Profiling}
-
-@item
-@ref{26,,Improving Performance}
-
-@item
-@ref{27,,Overflow Check Handling in GNAT}
-
-@item
-@ref{28,,Performing Dimensionality Analysis in GNAT}
-
-@item
-@ref{29,,Stack Related Facilities}
-
-@item
-@ref{2a,,Memory Management Issues}
-@end itemize
-
-@item
-@ref{d,,Platform-Specific Information} is a new appendix consolidating the following:
-
-
-@itemize -
-
-@item
-@ref{2b,,Run-Time Libraries}
-
-@item
-@ref{2c,,Microsoft Windows Topics}
-
-@item
-@ref{2d,,Mac OS Topics}
-@end itemize
-
-@item
-The @emph{Compatibility and Porting Guide} appendix has been moved to the
-@cite{GNAT Reference Manual}. It now includes a section
-@emph{Writing Portable Fixed-Point Declarations} which was previously
-a separate chapter in the @cite{GNAT User's Guide}.
-@end itemize
-
-@node Conventions,,A Note to Readers of Previous Versions of the Manual,About This Guide
-@anchor{gnat_ugn/about_this_guide conventions}@anchor{2e}
+@node Conventions,,Related Information,About This Guide
+@anchor{gnat_ugn/about_this_guide conventions}@anchor{13}
@section Conventions
@end itemize
@node Getting Started with GNAT,The GNAT Compilation Model,About This Guide,Top
-@anchor{gnat_ugn/getting_started_with_gnat getting-started-with-gnat}@anchor{8}@anchor{gnat_ugn/getting_started_with_gnat doc}@anchor{2f}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{30}
+@anchor{gnat_ugn/getting_started_with_gnat getting-started-with-gnat}@anchor{8}@anchor{gnat_ugn/getting_started_with_gnat doc}@anchor{14}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{15}
@chapter 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
+is also available: GNAT Studio.
+GNAT Studio 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
-@cite{Using the GNAT Programming Studio}.
+For information on GNAT Studio please refer to the
+@cite{GNAT Studio documentation}.
@menu
+* System Requirements::
* Running GNAT::
* Running a Simple Ada Program::
* Running a Program with Multiple Units::
-* Using the gnatmake Utility::
@end menu
-@node Running GNAT,Running a Simple Ada Program,,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat running-gnat}@anchor{31}@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{32}
+@node System Requirements,Running GNAT,,Getting Started with GNAT
+@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{16}@anchor{gnat_ugn/getting_started_with_gnat system-requirements}@anchor{17}
+@section System Requirements
+
+
+Even though any machine can run the GNAT toolset and GNAT Studio IDE, in order
+to get the best experience, we recommend using a machine with as many cores
+as possible since all individual compilations can run in parallel.
+A comfortable setup for a compiler server is a machine with 24 physical cores
+or more, with at least 48 GB of memory (2 GB per core).
+
+For a desktop machine, a minimum of 4 cores is recommended (8 preferred),
+with at least 2GB per core (so 8 to 16GB).
+
+In addition, for running and navigating sources in GNAT Studio smoothly, we
+recommend at least 1.5 GB plus 3 GB of RAM per 1 million source line of code.
+In other words, we recommend at least 3 GB for for 500K lines of code and
+7.5 GB for 2 million lines of code.
+
+Note that using local and fast drives will also make a difference in terms of
+build and link time. Network drives such as NFS, SMB, or worse, configuration
+management filesystems (such as ClearCase dynamic views) should be avoided as
+much as possible and will produce very degraded performance (typically 2 to 3
+times slower than on local fast drives). If such slow drives cannot be avoided
+for accessing the source code, then you should at least configure your project
+file so that the result of the compilation is stored on a drive local to the
+machine performing the run. This can be achieved by setting the @code{Object_Dir}
+project file attribute.
+
+@node Running GNAT,Running a Simple Ada Program,System Requirements,Getting Started with GNAT
+@anchor{gnat_ugn/getting_started_with_gnat running-gnat}@anchor{18}@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{19}
@section Running GNAT
performs the necessary compilation, binding and linking steps.
@node Running a Simple Ada Program,Running a Program with Multiple Units,Running GNAT,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat running-a-simple-ada-program}@anchor{33}@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{34}
+@anchor{gnat_ugn/getting_started_with_gnat running-a-simple-ada-program}@anchor{1a}@anchor{gnat_ugn/getting_started_with_gnat id4}@anchor{1b}
@section Running a Simple Ada Program
spec and @code{adb} for a body.
You can override this default file naming convention by use of the
special pragma @code{Source_File_Name} (for further information please
-see @ref{35,,Using Other File Names}).
+see @ref{1c,,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 @code{gnatchop} utility
can be used to generate correctly-named source files
-(see @ref{36,,Renaming Files with gnatchop}).
+(see @ref{1d,,Renaming Files with gnatchop}).
You can compile the program using the following command (@code{$} is used
as the command prompt in the examples in this document):
an 'Ada Library Information' file @code{hello.ali},
which contains additional information used to check
that an Ada program is consistent.
-To build an executable file,
-use @code{gnatbind} to bind the program
-and @code{gnatlink} to link it. The
-argument to both @code{gnatbind} and @code{gnatlink} is the name of the
-@code{ALI} file, but the default extension of @code{.ali} can
-be omitted. This means that in the most common case, the argument
-is simply the name of the main program:
-
-@example
-$ gnatbind hello
-$ gnatlink hello
-@end example
-A simpler method of carrying out these steps is to use @code{gnatmake},
-a master program that invokes all the required
-compilation, binding and linking tools in the correct order. In particular,
-@code{gnatmake} automatically recompiles any sources that have been
-modified since they were last compiled, or sources that depend
+To build an executable file, use either @code{gnatmake} or gprbuild with
+the name of the main file: these tools are builders that will take care of
+all the necessary build steps in the correct order.
+In particular, these builders automatically recompile 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.
@geindex Version skew (avoided by `@w{`}gnatmake`@w{`})
appear in response to this command.
-@node Running a Program with Multiple Units,Using the gnatmake Utility,Running a Simple Ada Program,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat id4}@anchor{37}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{38}
+@node Running a Program with Multiple Units,,Running a Simple Ada Program,Getting Started with GNAT
+@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{1e}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{1f}
@section Running a Program with Multiple Units
body of main program
@end table
-To build an executable version of
-this program, we could use four separate steps to compile, bind, and link
-the program, as follows:
-
-@example
-$ gcc -c gmain.adb
-$ gcc -c greetings.adb
-$ gnatbind gmain
-$ gnatlink gmain
-@end example
-
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
$ gcc -c greetings.ads -gnatc
@end example
-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 @code{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:
+Although the compilation can be done in separate steps, in practice it is
+almost always more convenient to use the @code{gnatmake} or @code{gprbuild} tools:
@example
$ gnatmake gmain.adb
@end example
-In the next section we discuss the advantages of using @code{gnatmake} in
-more detail.
-
-@node Using the gnatmake Utility,,Running a Program with Multiple Units,Getting Started with GNAT
-@anchor{gnat_ugn/getting_started_with_gnat using-the-gnatmake-utility}@anchor{39}@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{3a}
-@section Using the @code{gnatmake} Utility
-
-
-If you work on a program by compiling single components at a time using
-@code{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 @code{gmain.adb}, you only need to recompile that file. But if
-you edit @code{greetings.ads}, you must recompile both
-@code{greetings.adb} and @code{gmain.adb}, because both files contain
-units that depend on @code{greetings.ads}.
-
-@code{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 @code{gnatmake} utility takes care of these details automatically.
-Invoke it using either one of the following forms:
-
-@example
-$ gnatmake gmain.adb
-$ gnatmake gmain
-@end example
-
-The argument is the name of the file containing the main program;
-you may omit the extension. @code{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, @code{gmain}.
-In a large program, it
-can be extremely helpful to use @code{gnatmake}, because working out by hand
-what needs to be recompiled can be difficult.
-
-Note that @code{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, @code{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. @code{gnatmake} determines the exact set of
-dependencies from scratch each time it is run.
-
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@node The GNAT Compilation Model,Building Executable Programs with GNAT,Getting Started with GNAT,Top
-@anchor{gnat_ugn/the_gnat_compilation_model doc}@anchor{3b}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{3c}
+@anchor{gnat_ugn/the_gnat_compilation_model doc}@anchor{20}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{21}
@chapter The GNAT Compilation Model
@itemize *
@item
-@ref{3d,,Source Representation}
+@ref{22,,Source Representation}
@item
-@ref{3e,,Foreign Language Representation}
+@ref{23,,Foreign Language Representation}
@item
-@ref{3f,,File Naming Topics and Utilities}
+@ref{24,,File Naming Topics and Utilities}
@end itemize
@item
-@ref{14,,Configuration Pragmas}
+@ref{25,,Configuration Pragmas}
@item
-@ref{40,,Generating Object Files}
+@ref{26,,Generating Object Files}
@item
-@ref{41,,Source Dependencies}
+@ref{27,,Source Dependencies}
@item
-@ref{42,,The Ada Library Information Files}
+@ref{28,,The Ada Library Information Files}
@item
-@ref{43,,Binding an Ada Program}
+@ref{29,,Binding an Ada Program}
@item
-@ref{15,,GNAT and Libraries}
+@ref{2a,,GNAT and Libraries}
@item
-@ref{16,,Conditional Compilation}
+@ref{2b,,Conditional Compilation}
@item
-@ref{44,,Mixed Language Programming}
+@ref{2c,,Mixed Language Programming}
@item
-@ref{45,,GNAT and Other Compilation Models}
+@ref{2d,,GNAT and Other Compilation Models}
@item
-@ref{1a,,Using GNAT Files with External Tools}
+@ref{2e,,Using GNAT Files with External Tools}
@end itemize
@menu
@end menu
@node Source Representation,Foreign Language Representation,,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model source-representation}@anchor{3d}@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{46}
+@anchor{gnat_ugn/the_gnat_compilation_model source-representation}@anchor{22}@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{2f}
@section Source Representation
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{3e,,Foreign Language Representation}
+representing foreign languages (see @ref{23,,Foreign Language Representation}
for support of non-USA character sets). The format effector characters
are represented using their standard ASCII encodings, as follows:
you will place each subunit or child unit in a separate file.
@node Foreign Language Representation,File Naming Topics and Utilities,Source Representation,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model foreign-language-representation}@anchor{3e}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{47}
+@anchor{gnat_ugn/the_gnat_compilation_model foreign-language-representation}@anchor{23}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{30}
@section 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{48,,Character Set Control}).
+of the compiler (@ref{31,,Character Set Control}).
@menu
* Latin-1::
@end menu
@node Latin-1,Other 8-Bit Codes,,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{49}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{4a}
+@anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{32}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{33}
@subsection Latin-1
letters can be used in identifiers.
@node Other 8-Bit Codes,Wide_Character Encodings,Latin-1,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model other-8-bit-codes}@anchor{4b}@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{4c}
+@anchor{gnat_ugn/the_gnat_compilation_model other-8-bit-codes}@anchor{34}@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{35}
@subsection Other 8-Bit Codes
of GNAT to obtain this file.
@node Wide_Character Encodings,Wide_Wide_Character Encodings,Other 8-Bit Codes,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id6}@anchor{4d}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{4e}
+@anchor{gnat_ugn/the_gnat_compilation_model id6}@anchor{36}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{37}
@subsection Wide_Character Encodings
@end cartouche
@node Wide_Wide_Character Encodings,,Wide_Character Encodings,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{4f}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{50}
+@anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{38}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{39}
@subsection Wide_Wide_Character Encodings
@end table
@node File Naming Topics and Utilities,Configuration Pragmas,Foreign Language Representation,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id8}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{3f}
+@anchor{gnat_ugn/the_gnat_compilation_model id8}@anchor{3a}@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{24}
@section File Naming Topics and Utilities
@end menu
@node File Naming Rules,Using Other File Names,,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model file-naming-rules}@anchor{52}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{53}
+@anchor{gnat_ugn/the_gnat_compilation_model file-naming-rules}@anchor{3b}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{3c}
@subsection File Naming Rules
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{54,,Using gnatkr}.
+with limited file name lengths. @ref{3d,,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
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{36,,Renaming Files with gnatchop}.)
+(For details see @ref{1d,,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
you need to follow the procedures described in the next section.
@node Using Other File Names,Alternative File Naming Schemes,File Naming Rules,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model id10}@anchor{55}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{35}
+@anchor{gnat_ugn/the_gnat_compilation_model id10}@anchor{3e}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{1c}
@subsection Using Other File Names
file used to hold configuration
pragmas that apply to a complete compilation environment.
For more details on how the @code{gnat.adc} file is created and used
-see @ref{56,,Handling of Configuration Pragmas}.
+see @ref{3f,,Handling of Configuration Pragmas}.
@geindex gnat.adc
be omitted.
@node Alternative File Naming Schemes,Handling Arbitrary File Naming Conventions with gnatname,Using Other File Names,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model id11}@anchor{57}@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{58}
+@anchor{gnat_ugn/the_gnat_compilation_model id11}@anchor{40}@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{41}
@subsection Alternative File Naming Schemes
@geindex gnatname
@node Handling Arbitrary File Naming Conventions with gnatname,File Name Krunching with gnatkr,Alternative File Naming Schemes,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model handling-arbitrary-file-naming-conventions-with-gnatname}@anchor{59}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{5a}
+@anchor{gnat_ugn/the_gnat_compilation_model handling-arbitrary-file-naming-conventions-with-gnatname}@anchor{42}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{43}
@subsection Handling Arbitrary File Naming Conventions with @code{gnatname}
@end menu
@node Arbitrary File Naming Conventions,Running gnatname,,Handling Arbitrary File Naming Conventions with gnatname
-@anchor{gnat_ugn/the_gnat_compilation_model arbitrary-file-naming-conventions}@anchor{5b}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{5c}
+@anchor{gnat_ugn/the_gnat_compilation_model arbitrary-file-naming-conventions}@anchor{44}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{45}
@subsubsection Arbitrary File Naming Conventions
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{14,,Configuration Pragmas})
+a configuration pragmas file (@ref{25,,Configuration Pragmas})
or a project file.
When the non-standard file naming conventions are well-defined,
a small number of pragmas @code{Source_File_Name} specifying a naming pattern
-(@ref{58,,Alternative File Naming Schemes}) may be sufficient. However,
+(@ref{41,,Alternative File Naming Schemes}) may be sufficient. However,
if the file naming conventions are irregular or arbitrary, a number
of pragma @code{Source_File_Name} for individual compilation units
must be defined.
set of files.
@node Running gnatname,Switches for gnatname,Arbitrary File Naming Conventions,Handling Arbitrary File Naming Conventions with gnatname
-@anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{5d}@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{5e}
+@anchor{gnat_ugn/the_gnat_compilation_model running-gnatname}@anchor{46}@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{47}
@subsubsection Running @code{gnatname}
unit.
@node Switches for gnatname,Examples of gnatname Usage,Running gnatname,Handling Arbitrary File Naming Conventions with gnatname
-@anchor{gnat_ugn/the_gnat_compilation_model id15}@anchor{5f}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{60}
+@anchor{gnat_ugn/the_gnat_compilation_model id15}@anchor{48}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{49}
@subsubsection Switches for @code{gnatname}
@end table
@node Examples of gnatname Usage,,Switches for gnatname,Handling Arbitrary File Naming Conventions with gnatname
-@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatname-usage}@anchor{61}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{62}
+@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatname-usage}@anchor{4a}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{4b}
@subsubsection Examples of @code{gnatname} Usage
are used in this example.
@node File Name Krunching with gnatkr,Renaming Files with gnatchop,Handling Arbitrary File Naming Conventions with gnatname,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model file-name-krunching-with-gnatkr}@anchor{63}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{64}
+@anchor{gnat_ugn/the_gnat_compilation_model file-name-krunching-with-gnatkr}@anchor{4c}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{4d}
@subsection File Name Krunching with @code{gnatkr}
@end menu
@node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr
-@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{66}
+@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{4e}@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{4f}
@subsubsection About @code{gnatkr}
a given file, when krunched to a specified maximum length.
@node Using gnatkr,Krunching Method,About gnatkr,File Name Krunching with gnatkr
-@anchor{gnat_ugn/the_gnat_compilation_model id19}@anchor{67}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{54}
+@anchor{gnat_ugn/the_gnat_compilation_model id19}@anchor{50}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{3d}
@subsubsection Using @code{gnatkr}
original argument was a file name with an extension.
@node Krunching Method,Examples of gnatkr Usage,Using gnatkr,File Name Krunching with gnatkr
-@anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{68}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{69}
+@anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{52}
@subsubsection Krunching Method
krunched name of a file.
@node Examples of gnatkr Usage,,Krunching Method,File Name Krunching with gnatkr
-@anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{6a}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{6b}
+@anchor{gnat_ugn/the_gnat_compilation_model id21}@anchor{53}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{54}
@subsubsection Examples of @code{gnatkr} Usage
@end example
@node Renaming Files with gnatchop,,File Name Krunching with gnatkr,File Naming Topics and Utilities
-@anchor{gnat_ugn/the_gnat_compilation_model id22}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{36}
+@anchor{gnat_ugn/the_gnat_compilation_model id22}@anchor{55}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{1d}
@subsection Renaming Files with @code{gnatchop}
@end menu
@node Handling Files with Multiple Units,Operating gnatchop in Compilation Mode,,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model id23}@anchor{6d}@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{6e}
+@anchor{gnat_ugn/the_gnat_compilation_model id23}@anchor{56}@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{57}
@subsubsection Handling Files with Multiple Units
compiler have only one unit and there be a strict correspondence
between the file name and the unit name.
-The @code{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. @code{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 keep your files with multiple units,
+perhaps to maintain compatibility with some other Ada compilation system,
+you can use @code{gnatname} to generate or update your project files.
+Generated or modified project files can be processed 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 @code{gnatchop} once, generate the
-new set of files and work with them from that point on.
+See @ref{42,,Handling Arbitrary File Naming Conventions with gnatname}
+for more details on how to use @cite{gnatname}.
-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 @code{gnatchop} each
-time you compile, regarding the source files that it writes as temporary
-files that you throw away.
+Alternatively, 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 @code{gnatchop} once, generate the
+new set of files and work with them from that point on.
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
automatically in UTF-8 mode without needing to specify an explicit encoding.
@node Operating gnatchop in Compilation Mode,Command Line for gnatchop,Handling Files with Multiple Units,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model operating-gnatchop-in-compilation-mode}@anchor{6f}@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{70}
+@anchor{gnat_ugn/the_gnat_compilation_model operating-gnatchop-in-compilation-mode}@anchor{58}@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{59}
@subsubsection Operating gnatchop in Compilation Mode
environment. Using GNAT, the current directory, possibly containing a
@code{gnat.adc} file is the representation
of a compilation environment. For more information on the
-@code{gnat.adc} file, see @ref{56,,Handling of Configuration Pragmas}.
+@code{gnat.adc} file, see @ref{3f,,Handling of Configuration Pragmas}.
Second, in compilation mode, if @code{gnatchop}
is given a file that starts with
in which GNAT processes the ACVC tests.
@node Command Line for gnatchop,Switches for gnatchop,Operating gnatchop in Compilation Mode,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{72}
+@anchor{gnat_ugn/the_gnat_compilation_model id25}@anchor{5a}@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{5b}
@subsubsection Command Line for @code{gnatchop}
@end example
@node Switches for gnatchop,Examples of gnatchop Usage,Command Line for gnatchop,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{73}@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{74}
+@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatchop}@anchor{5c}@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{5d}
@subsubsection Switches for @code{gnatchop}
@end table
@node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{75}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{76}
+@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{5e}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{5f}
@subsubsection Examples of @code{gnatchop} Usage
unit will be skipped.
@node Configuration Pragmas,Generating Object Files,File Naming Topics and Utilities,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{77}@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{14}
+@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{60}@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{25}
@section Configuration Pragmas
Overriding_Renamings
Partition_Elaboration_Policy
Persistent_BSS
-Polling
Prefix_Exception_Messages
Priority_Specific_Dispatching
Profile
@end menu
@node Handling of Configuration Pragmas,The Configuration Pragmas Files,,Configuration Pragmas
-@anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{78}@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{56}
+@anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{61}@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{3f}
@subsection Handling of Configuration Pragmas
GNAT also provides the @code{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{6f,,Operating gnatchop in Compilation Mode} for details.
+See @ref{58,,Operating gnatchop in Compilation Mode} for details.
However, for most purposes, it will be more convenient to edit the
@code{gnat.adc} file that contains configuration pragmas directly,
as described in the following section.
appeared in the body of spec.
@node The Configuration Pragmas Files,,Handling of Configuration Pragmas,Configuration Pragmas
-@anchor{gnat_ugn/the_gnat_compilation_model the-configuration-pragmas-files}@anchor{79}@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{7a}
+@anchor{gnat_ugn/the_gnat_compilation_model the-configuration-pragmas-files}@anchor{62}@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{63}
@subsection The Configuration Pragmas Files
depend on a file that no longer exists. Such tools include
@code{gprbuild}, @code{gnatmake}, and @code{gnatcheck}.
+By default, configuration pragma files are stored by their absolute paths in
+ALI files. You can use the @code{-gnateb} switch in order to store them by
+their basename instead.
+
If you are using project file, a separate mechanism is provided using
project attributes.
@c See :ref:`Specifying_Configuration_Pragmas` for more details.
@node Generating Object Files,Source Dependencies,Configuration Pragmas,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model generating-object-files}@anchor{40}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{7b}
+@anchor{gnat_ugn/the_gnat_compilation_model generating-object-files}@anchor{26}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{64}
@section Generating Object Files
checking mode, use the @code{-gnatc} switch.
@node Source Dependencies,The Ada Library Information Files,Generating Object Files,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{7c}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{41}
+@anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{27}
@section Source Dependencies
@end itemize
@node The Ada Library Information Files,Binding an Ada Program,Source Dependencies,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id33}@anchor{7d}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{42}
+@anchor{gnat_ugn/the_gnat_compilation_model id33}@anchor{66}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{28}
@section The Ada Library Information Files
@code{lib-writ.adb} in the GNAT compiler sources.
@node Binding an Ada Program,GNAT and Libraries,The Ada Library Information Files,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id34}@anchor{7e}@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{43}
+@anchor{gnat_ugn/the_gnat_compilation_model id34}@anchor{67}@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{29}
@section Binding an Ada Program
object files for the Ada units of the program.
@node GNAT and Libraries,Conditional Compilation,Binding an Ada Program,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-libraries}@anchor{15}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{7f}
+@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-libraries}@anchor{2a}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{68}
@section GNAT and Libraries
@end menu
@node Introduction to Libraries in GNAT,General Ada Libraries,,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-libraries-in-gnat}@anchor{80}@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{81}
+@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-libraries-in-gnat}@anchor{69}@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{6a}
@subsection Introduction to Libraries in GNAT
Source files,
@item
-@code{ALI} files (see @ref{42,,The Ada Library Information Files}), and
+@code{ALI} files (see @ref{28,,The Ada Library Information Files}), and
@item
Object files, an archive or a shared library.
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 @emph{stand-alone libraries} those exposed
-units are called @emph{interface units} (@ref{82,,Stand-alone Ada Libraries}).
+units are called @emph{interface units} (@ref{6b,,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
using the library.
@node General Ada Libraries,Stand-alone Ada Libraries,Introduction to Libraries in GNAT,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model general-ada-libraries}@anchor{83}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{84}
+@anchor{gnat_ugn/the_gnat_compilation_model general-ada-libraries}@anchor{6c}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{6d}
@subsection General Ada Libraries
@end menu
@node Building a library,Installing a library,,General Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model building-a-library}@anchor{85}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{86}
+@anchor{gnat_ugn/the_gnat_compilation_model building-a-library}@anchor{6e}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{6f}
@subsubsection Building a library
steps are discussed below.
There are various possibilities for compiling the units that make up the
-library: for example with a Makefile (@ref{1f,,Using the GNU make Utility}) or
+library: for example with a Makefile (@ref{70,,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
be accessed by the directive @code{-l@emph{xxx}} at link time.
@node Installing a library,Using a library,Building a library,General Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model installing-a-library}@anchor{87}@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{88}
+@anchor{gnat_ugn/the_gnat_compilation_model installing-a-library}@anchor{71}@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{72}
@subsubsection Installing a library
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{89,,Search Paths and the Run-Time Library (RTL)}. Alternatively, the system
+@ref{73,,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
@code{ada_source_path} and @code{ada_object_path}. These configuration files
any part of it.
@node Using a library,,Installing a library,General Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model using-a-library}@anchor{8a}@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{8b}
+@anchor{gnat_ugn/the_gnat_compilation_model using-a-library}@anchor{74}@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{75}
@subsubsection Using a library
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{89,,Search Paths and the Run-Time Library (RTL)}
-and @ref{8c,,Search Paths for gnatbind}). Furthermore, when the objects are grouped
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}
+and @ref{76,,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.
install area.
@node Stand-alone Ada Libraries,Rebuilding the GNAT Run-Time Library,General Ada Libraries,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model stand-alone-ada-libraries}@anchor{82}@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{8d}
+@anchor{gnat_ugn/the_gnat_compilation_model stand-alone-ada-libraries}@anchor{6b}@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{77}
@subsection Stand-alone Ada Libraries
@end menu
@node Introduction to Stand-alone Libraries,Building a Stand-alone Library,,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-stand-alone-libraries}@anchor{8e}@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{8f}
+@anchor{gnat_ugn/the_gnat_compilation_model introduction-to-stand-alone-libraries}@anchor{78}@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{79}
@subsubsection Introduction to Stand-alone Libraries
main routine is not written in Ada.
@node Building a Stand-alone Library,Creating a Stand-alone Library to be used in a non-Ada context,Introduction to Stand-alone Libraries,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id43}@anchor{90}@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{91}
+@anchor{gnat_ugn/the_gnat_compilation_model id43}@anchor{7a}@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{7b}
@subsubsection Building a Stand-alone Library
@end itemize
Using SALs is not different from using other libraries
-(see @ref{8a,,Using a library}).
+(see @ref{74,,Using a library}).
@node Creating a Stand-alone Library to be used in a non-Ada context,Restrictions in Stand-alone Libraries,Building a Stand-alone Library,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model creating-a-stand-alone-library-to-be-used-in-a-non-ada-context}@anchor{92}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{93}
+@anchor{gnat_ugn/the_gnat_compilation_model creating-a-stand-alone-library-to-be-used-in-a-non-ada-context}@anchor{7c}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{7d}
@subsubsection Creating a Stand-alone Library to be used in a non-Ada context
system services like a mutex or a critical-section.
@node Restrictions in Stand-alone Libraries,,Creating a Stand-alone Library to be used in a non-Ada context,Stand-alone Ada Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id45}@anchor{94}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{95}
+@anchor{gnat_ugn/the_gnat_compilation_model id45}@anchor{7e}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{7f}
@subsubsection Restrictions in Stand-alone Libraries
to be a consideration.
@node Rebuilding the GNAT Run-Time Library,,Stand-alone Ada Libraries,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{96}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{97}
+@anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{80}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{81}
@subsection Rebuilding the GNAT Run-Time Library
@geindex Run-Time Library
@geindex 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 @code{Normalize_Scalars}. A special Makefile called
-@code{Makefile.adalib} is provided to that effect and can be found in
+It may be useful to recompile the GNAT library in various debugging or
+experimentation contexts. A project file called
+@code{libada.gpr} 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:
$ gnatls -v
@end example
-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.
+The last entry in the source search path usually contains the
+gnat library (the @code{adainclude} directory). This project file contains its
+own documentation and in particular the set of instructions needed to rebuild a
+new library and to use it.
+
+Note that rebuilding the GNAT Run-Time is only recommended for temporary
+experiments or debugging, and is not supported.
@geindex Conditional compilation
@node Conditional Compilation,Mixed Language Programming,GNAT and Libraries,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id47}@anchor{98}@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{16}
+@anchor{gnat_ugn/the_gnat_compilation_model id47}@anchor{82}@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{2b}
@section Conditional Compilation
@end menu
@node Modeling Conditional Compilation in Ada,Preprocessing with gnatprep,,Conditional Compilation
-@anchor{gnat_ugn/the_gnat_compilation_model modeling-conditional-compilation-in-ada}@anchor{99}@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{9a}
+@anchor{gnat_ugn/the_gnat_compilation_model modeling-conditional-compilation-in-ada}@anchor{83}@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{84}
@subsection Modeling Conditional Compilation in Ada
@end menu
@node Use of Boolean Constants,Debugging - A Special Case,,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model id49}@anchor{9b}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{9c}
+@anchor{gnat_ugn/the_gnat_compilation_model id49}@anchor{85}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{86}
@subsubsection Use of Boolean Constants
of @code{Config} to make the constants visible.
@node Debugging - A Special Case,Conditionalizing Declarations,Use of Boolean Constants,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model debugging-a-special-case}@anchor{9d}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{9e}
+@anchor{gnat_ugn/the_gnat_compilation_model debugging-a-special-case}@anchor{87}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{88}
@subsubsection Debugging - A Special Case
@end example
@node Conditionalizing Declarations,Use of Alternative Implementations,Debugging - A Special Case,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{9f}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{a0}
+@anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{89}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{8a}
@subsubsection Conditionalizing Declarations
need to define this one yourself).
@node Use of Alternative Implementations,Preprocessing,Conditionalizing Declarations,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model use-of-alternative-implementations}@anchor{a1}@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{a2}
+@anchor{gnat_ugn/the_gnat_compilation_model use-of-alternative-implementations}@anchor{8b}@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{8c}
@subsubsection Use of Alternative Implementations
calls.
@node Preprocessing,,Use of Alternative Implementations,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{a3}@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{a4}
+@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{8d}@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{8e}
@subsubsection Preprocessing
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
@code{gnatprep} utility, whose use is fully described in
-@ref{17,,Preprocessing with gnatprep}.
+@ref{8f,,Preprocessing with gnatprep}.
The preprocessing language allows such constructs as
the compilation process. The compiler is given the preprocessor input which
includes @code{#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{18,,Integrated Preprocessing}.
+For more details on this approach, see @ref{90,,Integrated Preprocessing}.
@node Preprocessing with gnatprep,Integrated Preprocessing,Modeling Conditional Compilation in Ada,Conditional Compilation
-@anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{17}
+@anchor{gnat_ugn/the_gnat_compilation_model id54}@anchor{91}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{8f}
@subsection Preprocessing with @code{gnatprep}
Although designed for use with GNAT, @code{gnatprep} does not depend on any
special GNAT features.
For further discussion of conditional compilation in general, see
-@ref{16,,Conditional Compilation}.
+@ref{2b,,Conditional Compilation}.
@menu
* Preprocessing Symbols::
@end menu
@node Preprocessing Symbols,Using gnatprep,,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{a6}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{a7}
+@anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{92}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{93}
@subsubsection Preprocessing Symbols
all characters need to be in the ASCII set (no accented letters).
@node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{a8}@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{a9}
+@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{94}@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{95}
@subsubsection Using @code{gnatprep}
@end itemize
@node Switches for gnatprep,Form of Definitions File,Using gnatprep,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{aa}@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{ab}
+@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatprep}@anchor{96}@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{97}
@subsubsection Switches for @code{gnatprep}
specified, in which case -b is assumed.
@node Form of Definitions File,Form of Input Text for gnatprep,Switches for gnatprep,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model form-of-definitions-file}@anchor{ac}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{ad}
+@anchor{gnat_ugn/the_gnat_compilation_model form-of-definitions-file}@anchor{98}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{99}
@subsubsection Form of Definitions File
and comments may be added to the definitions lines.
@node Form of Input Text for gnatprep,,Form of Definitions File,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{ae}@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{af}
+@anchor{gnat_ugn/the_gnat_compilation_model id59}@anchor{9a}@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{9b}
@subsubsection Form of Input Text for @code{gnatprep}
and then the substitution will occur as desired.
@node Integrated Preprocessing,,Preprocessing with gnatprep,Conditional Compilation
-@anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{b0}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{18}
+@anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{90}
@subsection Integrated Preprocessing
preprocessing.
The actual preprocessing function is described in detail in
-@ref{17,,Preprocessing with gnatprep}. This section explains the switches
+@ref{8f,,Preprocessing with gnatprep}. This section explains the switches
that relate to integrated preprocessing.
@geindex -gnatep (gcc)
After the file name or '*', an optional literal string specifies the name of
the definition file to be used for preprocessing
-(@ref{ac,,Form of Definitions File}). The definition files are found by the
+(@ref{98,,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
@end table
@node Mixed Language Programming,GNAT and Other Compilation Models,Conditional Compilation,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model mixed-language-programming}@anchor{44}@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{b1}
+@anchor{gnat_ugn/the_gnat_compilation_model mixed-language-programming}@anchor{2c}@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{9d}
@section Mixed Language Programming
@end menu
@node Interfacing to C,Calling Conventions,,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{b2}@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{b3}
+@anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{9e}@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{9f}
@subsection Interfacing to C
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{b4,,Binding with Non-Ada Main Programs}).
+finalize the Ada units (@ref{a0,,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
@code{-nostartfiles} switch to @code{gnatlink}.
@node Calling Conventions,Building Mixed Ada and C++ Programs,Interfacing to C,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{b5}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{b6}
+@anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{a1}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{a2}
@subsection Calling Conventions
meaning as Fortran.
@node Building Mixed Ada and C++ Programs,Generating Ada Bindings for C and C++ headers,Calling Conventions,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model id64}@anchor{b7}@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{b8}
+@anchor{gnat_ugn/the_gnat_compilation_model id64}@anchor{a3}@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{a4}
@subsection Building Mixed Ada and C++ Programs
@end menu
@node Interfacing to C++,Linking a Mixed C++ & Ada Program,,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{b9}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{ba}
+@anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{a6}
@subsubsection Interfacing to C++
classes. In the first two cases, GNAT offers a specific @code{Convention C_Plus_Plus}
(or @code{CPP}) that behaves exactly like @code{Convention C}.
Usually, C++ mangles the names of subprograms. To generate proper mangled
-names automatically, see @ref{19,,Generating Ada Bindings for C and C++ headers}).
+names automatically, see @ref{a7,,Generating Ada Bindings for C and C++ headers}).
This problem can also be addressed manually in two ways:
pragmas such as @code{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information.
@node Linking a Mixed C++ & Ada Program,A Simple Example,Interfacing to C++,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-ada-program}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{bc}
+@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-ada-program}@anchor{a8}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{a9}
@subsubsection Linking a Mixed C++ & Ada Program
together automatically in most cases.
@node A Simple Example,Interfacing with C++ constructors,Linking a Mixed C++ & Ada Program,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model id67}@anchor{bd}@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{be}
+@anchor{gnat_ugn/the_gnat_compilation_model id67}@anchor{aa}@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{ab}
@subsubsection A Simple Example
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
+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
@end example
@node Interfacing with C++ constructors,Interfacing with C++ at the Class Level,A Simple Example,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model id68}@anchor{bf}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{c0}
+@anchor{gnat_ugn/the_gnat_compilation_model id68}@anchor{ac}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{ad}
@subsubsection Interfacing with C++ constructors
For this purpose we can write the following package spec (further
information on how to build this spec is available in
-@ref{c1,,Interfacing with C++ at the Class Level} and
-@ref{19,,Generating Ada Bindings for C and C++ headers}).
+@ref{ae,,Interfacing with C++ at the Class Level} and
+@ref{a7,,Generating Ada Bindings for C and C++ headers}).
@example
with Interfaces.C; use Interfaces.C;
the constructor can be placed inside the construct.
@node Interfacing with C++ at the Class Level,,Interfacing with C++ constructors,Building Mixed Ada and C++ Programs
-@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-at-the-class-level}@anchor{c1}@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{c2}
+@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-at-the-class-level}@anchor{ae}@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{af}
@subsubsection Interfacing with C++ at the Class Level
@end example
@node Generating Ada Bindings for C and C++ headers,Generating C Headers for Ada Specifications,Building Mixed Ada and C++ Programs,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{c3}@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{19}
+@anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{b0}@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{a7}
@subsection Generating Ada Bindings for C and C++ headers
errors (e.g. @code{shm_get} vs @code{SHM_GET}).
@end itemize
-The code generated is using the Ada 2005 syntax, which makes it
-easier to interface with other languages than previous versions of Ada.
+The code is generated using Ada 2012 syntax, which makes it easier to interface
+with other languages. In most cases you can still use the generated binding
+even if your code is compiled using earlier versions of Ada (e.g. @code{-gnat95}).
@menu
* Running the Binding Generator::
@end menu
@node Running the Binding Generator,Generating Bindings for C++ Headers,,Generating Ada Bindings for C and C++ headers
-@anchor{gnat_ugn/the_gnat_compilation_model id71}@anchor{c4}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{c5}
+@anchor{gnat_ugn/the_gnat_compilation_model id71}@anchor{b1}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{b2}
@subsubsection Running the Binding Generator
@example
$ g++ -c -fdump-ada-spec -C /usr/include/time.h
-$ gcc -c -gnat05 *.ads
+$ gcc -c *.ads
@end example
will generate, under GNU/Linux, the following files: @code{time_h.ads},
@end example
@node Generating Bindings for C++ Headers,Switches,Running the Binding Generator,Generating Ada Bindings for C and C++ headers
-@anchor{gnat_ugn/the_gnat_compilation_model id72}@anchor{c6}@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{c7}
+@anchor{gnat_ugn/the_gnat_compilation_model id72}@anchor{b3}@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{b4}
@subsubsection Generating Bindings for C++ Headers
@end example
@node Switches,,Generating Bindings for C++ Headers,Generating Ada Bindings for C and C++ headers
-@anchor{gnat_ugn/the_gnat_compilation_model switches}@anchor{c8}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{c9}
+@anchor{gnat_ugn/the_gnat_compilation_model switches}@anchor{b5}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{b6}
@subsubsection Switches
@end table
@node Generating C Headers for Ada Specifications,,Generating Ada Bindings for C and C++ headers,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model generating-c-headers-for-ada-specifications}@anchor{ca}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{cb}
+@anchor{gnat_ugn/the_gnat_compilation_model generating-c-headers-for-ada-specifications}@anchor{b7}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{b8}
@subsection Generating C Headers for Ada Specifications
@end menu
@node Running the C Header Generator,,,Generating C Headers for Ada Specifications
-@anchor{gnat_ugn/the_gnat_compilation_model running-the-c-header-generator}@anchor{cc}
+@anchor{gnat_ugn/the_gnat_compilation_model running-the-c-header-generator}@anchor{b9}
@subsubsection Running the C Header Generator
call subprograms, reference objects, and constants.
@node GNAT and Other Compilation Models,Using GNAT Files with External Tools,Mixed Language Programming,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{cd}@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{45}
+@anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{ba}@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{2d}
@section GNAT and Other Compilation Models
@end menu
@node Comparison between GNAT and C/C++ Compilation Models,Comparison between GNAT and Conventional Ada Library Models,,GNAT and Other Compilation Models
-@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-c-c-compilation-models}@anchor{ce}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{cf}
+@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-c-c-compilation-models}@anchor{bb}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{bc}
@subsection Comparison between GNAT and C/C++ Compilation Models
malfunctioned at run time.
@node Comparison between GNAT and Conventional Ada Library Models,,Comparison between GNAT and C/C++ Compilation Models,GNAT and Other Compilation Models
-@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-conventional-ada-library-models}@anchor{d0}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{d1}
+@anchor{gnat_ugn/the_gnat_compilation_model comparison-between-gnat-and-conventional-ada-library-models}@anchor{bd}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{be}
@subsection Comparison between GNAT and Conventional Ada Library Models
compiled.
@node Using GNAT Files with External Tools,,GNAT and Other Compilation Models,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model using-gnat-files-with-external-tools}@anchor{1a}@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{d2}
+@anchor{gnat_ugn/the_gnat_compilation_model using-gnat-files-with-external-tools}@anchor{2e}@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{bf}
@section Using GNAT Files with External Tools
@end menu
@node Using Other Utility Programs with GNAT,The External Symbol Naming Scheme of GNAT,,Using GNAT Files with External Tools
-@anchor{gnat_ugn/the_gnat_compilation_model using-other-utility-programs-with-gnat}@anchor{d3}@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{d4}
+@anchor{gnat_ugn/the_gnat_compilation_model using-other-utility-programs-with-gnat}@anchor{c0}@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{c1}
@subsection Using Other Utility Programs with GNAT
as Purify.
@node The External Symbol Naming Scheme of GNAT,,Using Other Utility Programs with GNAT,Using GNAT Files with External Tools
-@anchor{gnat_ugn/the_gnat_compilation_model the-external-symbol-naming-scheme-of-gnat}@anchor{d5}@anchor{gnat_ugn/the_gnat_compilation_model id79}@anchor{d6}
+@anchor{gnat_ugn/the_gnat_compilation_model the-external-symbol-naming-scheme-of-gnat}@anchor{c2}@anchor{gnat_ugn/the_gnat_compilation_model id79}@anchor{c3}
@subsection The External Symbol Naming Scheme of GNAT
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@node Building Executable Programs with GNAT,GNAT Utility Programs,The GNAT Compilation Model,Top
-@anchor{gnat_ugn/building_executable_programs_with_gnat building-executable-programs-with-gnat}@anchor{a}@anchor{gnat_ugn/building_executable_programs_with_gnat doc}@anchor{d7}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{d8}
+@anchor{gnat_ugn/building_executable_programs_with_gnat building-executable-programs-with-gnat}@anchor{a}@anchor{gnat_ugn/building_executable_programs_with_gnat doc}@anchor{c4}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{c5}
@chapter Building Executable Programs with GNAT
This chapter describes first the gnatmake tool
-(@ref{1b,,Building with gnatmake}),
+(@ref{c6,,Building with 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{1c,,Compiling with gcc}),
-binder (gnatbind, see @ref{1d,,Binding with gnatbind}),
-and linker (gnatlink, see @ref{1e,,Linking with gnatlink})
+compiler (gcc, see @ref{c7,,Compiling with gcc}),
+binder (gnatbind, see @ref{c8,,Binding with gnatbind}),
+and linker (gnatlink, see @ref{c9,,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{1f,,Using the GNU make Utility}).
+in a GNAT context (see @ref{70,,Using the GNU make Utility}).
@menu
@end menu
@node Building with gnatmake,Compiling with gcc,,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{1b}@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{d9}
+@anchor{gnat_ugn/building_executable_programs_with_gnat the-gnat-make-program-gnatmake}@anchor{c6}@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{ca}
@section Building with @code{gnatmake}
@end menu
@node Running gnatmake,Switches for gnatmake,,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{da}@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{db}
+@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{cb}@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{cc}
@subsection Running @code{gnatmake}
source file will first be searched in the directory where
@code{gnatmake} was invoked and if it is not found, it will be search on
the source path of the compiler as described in
-@ref{89,,Search Paths and the Run-Time Library (RTL)}.
+@ref{73,,Search Paths and the Run-Time Library (RTL)}.
All @code{gnatmake} output (except when you specify @code{-M}) is sent to
@code{stderr}. The output produced by the
@code{-M} switch is sent to @code{stdout}.
@node Switches for gnatmake,Mode Switches for gnatmake,Running gnatmake,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{dc}@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{dd}
+@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatmake}@anchor{cd}@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{ce}
@subsection Switches for @code{gnatmake}
in place. This means that once a large project is organized into separate
directories in the desired manner, then @code{gnatmake} will automatically
maintain and update this organization. If no ALI files are found on the
-Ada object path (see @ref{89,,Search Paths and the Run-Time Library (RTL)}),
+Ada object path (see @ref{73,,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,
@item @code{-vP@emph{x}}
Indicate the verbosity of the parsing of GNAT project files.
-See @ref{de,,Switches Related to Project Files}.
+See @ref{cf,,Switches Related to Project Files}.
@end table
@geindex -x (gnatmake)
Indicate that external variable @code{name} has the value @code{value}.
The Project Manager will use this value for occurrences of
@code{external(name)} when parsing the project file.
-@ref{de,,Switches Related to Project Files}.
+@ref{cf,,Switches Related to Project Files}.
@end table
@geindex -z (gnatmake)
When looking for source files also look in directory @code{dir}.
The order in which source files search is undertaken is
-described in @ref{89,,Search Paths and the Run-Time Library (RTL)}.
+described in @ref{73,,Search Paths and the Run-Time Library (RTL)}.
@end table
@geindex -aL (gnatmake)
When searching for library and object files, look in directory
@code{dir}. The order in which library files are searched is described in
-@ref{8c,,Search Paths for gnatbind}.
+@ref{76,,Search Paths for gnatbind}.
@end table
@geindex Search paths
@item @code{--RTS=@emph{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
+Specifies the default location of the run-time library. GNAT looks for the
+run-time
+in the following directories, and stops as soon as a valid run-time is found
(@code{adainclude} or @code{ada_source_path}, and @code{adalib} or
@code{ada_object_path} present):
@end table
@node Mode Switches for gnatmake,Notes on the Command Line,Switches for gnatmake,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat id4}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{e0}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id4}@anchor{d0}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{d1}
@subsection Mode Switches for @code{gnatmake}
@end table
@node Notes on the Command Line,How gnatmake Works,Mode Switches for gnatmake,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat id5}@anchor{e1}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{e2}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id5}@anchor{d2}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{d3}
@subsection Notes on the Command Line
@end itemize
@node How gnatmake Works,Examples of gnatmake Usage,Notes on the Command Line,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{e3}@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{e4}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id6}@anchor{d4}@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{d5}
@subsection How @code{gnatmake} Works
imported by several of the executables, it will be recompiled at most once.
Note: when using non-standard naming conventions
-(@ref{35,,Using Other File Names}), changing through a configuration pragmas
+(@ref{1c,,Using Other File Names}), changing through a configuration pragmas
file the version of a source and invoking @code{gnatmake} to recompile may
have no effect, if the previous version of the source is still accessible
by @code{gnatmake}. It may be necessary to use the switch
-f.
@node Examples of gnatmake Usage,,How gnatmake Works,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatmake-usage}@anchor{e5}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{e6}
+@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatmake-usage}@anchor{d6}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{d7}
@subsection Examples of @code{gnatmake} Usage
@end table
@node Compiling with gcc,Compiler Switches,Building with gnatmake,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-with-gcc}@anchor{1c}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{e7}
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-with-gcc}@anchor{c7}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{d8}
@section Compiling with @code{gcc}
@end menu
@node Compiling Programs,Search Paths and the Run-Time Library RTL,,Compiling with gcc
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-programs}@anchor{e8}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{e9}
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-programs}@anchor{d9}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{da}
@subsection Compiling Programs
The compiler generates two object files @code{x.o} and @code{y.o}
and the two ALI files @code{x.ali} and @code{y.ali}.
-Any switches apply to all the files listed, see @ref{ea,,Compiler Switches} for a
+Any switches apply to all the files listed, see @ref{db,,Compiler Switches} for a
list of available @code{gcc} switches.
@node Search Paths and the Run-Time Library RTL,Order of Compilation Issues,Compiling Programs,Compiling with gcc
-@anchor{gnat_ugn/building_executable_programs_with_gnat id10}@anchor{eb}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{89}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id10}@anchor{dc}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{73}
@subsection Search Paths and the Run-Time Library (RTL)
The content of the @code{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{87,,Installing a library}
+@ref{71,,Installing a library}
@end itemize
Specifying the switch @code{-I-}
development environments much more flexible.
@node Order of Compilation Issues,Examples,Search Paths and the Run-Time Library RTL,Compiling with gcc
-@anchor{gnat_ugn/building_executable_programs_with_gnat id11}@anchor{ec}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{ed}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id11}@anchor{dd}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{de}
@subsection Order of Compilation Issues
@item
There is no library as such, apart from the ALI files
-(@ref{42,,The Ada Library Information Files}, for information on the format
+(@ref{28,,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.
@end itemize
@node Examples,,Order of Compilation Issues,Compiling with gcc
-@anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{ee}@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{ef}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{e0}
@subsection Examples
mode.
@node Compiler Switches,Linker Switches,Compiling with gcc,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{f0}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{ea}
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{e1}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{db}
@section Compiler Switches
@end menu
@node Alphabetical List of All Switches,Output and Error Message Control,,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id13}@anchor{f1}@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{f2}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id13}@anchor{e2}@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{e3}
@subsection Alphabetical List of All Switches
@code{scos.adb}.
@end table
+@geindex -fgnat-encodings (gcc)
+
+
+@table @asis
+
+@item @code{-fgnat-encodings=[all|gdb|minimal]}
+
+This switch controls the balance between GNAT encodings and standard DWARF
+emitted in the debug information.
+@end table
+
@geindex -flto (gcc)
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 @code{-gnatn} switch.
+with inlining across units enabled by the @code{-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 @code{-Ox} switches, must be
Causes the compiler to avoid assumptions regarding non-aliasing
of objects of different types. See
-@ref{f3,,Optimization and Strict Aliasing} for details.
+@ref{e4,,Optimization and Strict Aliasing} for details.
@end table
@geindex -fno-strict-overflow (gcc)
@item @code{-fstack-check}
Activates stack checking.
-See @ref{f4,,Stack Overflow Checking} for details.
+See @ref{e5,,Stack Overflow Checking} for details.
@end table
@geindex -fstack-usage (gcc)
@item @code{-fstack-usage}
Makes the compiler output stack usage information for the program, on a
-per-subprogram basis. See @ref{f5,,Static Stack Usage Analysis} for details.
+per-subprogram basis. See @ref{e6,,Static Stack Usage Analysis} for details.
@end table
@geindex -g (gcc)
@item @code{-gnatB}
Assume no invalid (bad) values except for 'Valid attribute use
-(@ref{f6,,Validity Checking}).
+(@ref{e7,,Validity Checking}).
@end table
@geindex -gnatc (gcc)
@end example
In the example above, the first call to @code{Detect_Aliasing} fails with a
-@code{Program_Error} at runtime because the actuals for @code{Val_1} and
+@code{Program_Error} at run time because the actuals for @code{Val_1} and
@code{Val_2} denote the same object. The second call executes without raising
an exception because @code{Self(Obj)} produces an anonymous object which does
not share the memory location of @code{Obj}.
@end table
+@geindex -gnateb (gcc)
+
+
+@table @asis
+
+@item @code{-gnateb}
+
+Store configuration files by their basename in ALI files. This switch is
+used for instance by gprbuild for distributed builds in order to prevent
+issues where machine-specific absolute paths could end up being stored in
+ALI files.
+@end table
+
@geindex -gnatec (gcc)
Specify a configuration pragma file
(the equal sign is optional)
-(@ref{79,,The Configuration Pragmas Files}).
+(@ref{62,,The Configuration Pragmas Files}).
@end table
@geindex -gnateC (gcc)
@item @code{-gnateDsymbol[=@emph{value}]}
Defines a symbol, associated with @code{value}, for preprocessing.
-(@ref{18,,Integrated Preprocessing}).
+(@ref{90,,Integrated Preprocessing}).
@end table
@geindex -gnateE (gcc)
The @code{-gnatc} switch must always be specified before this switch, e.g.
@code{-gnatceg}. Generate a C header from the Ada input file. See
-@ref{ca,,Generating C Headers for Ada Specifications} for more
+@ref{b7,,Generating C Headers for Ada Specifications} for more
information.
@end quotation
Specify a mapping file
(the equal sign is optional)
-(@ref{f7,,Units to Sources Mapping Files}).
+(@ref{e8,,Units to Sources Mapping Files}).
@end table
@geindex -gnatep (gcc)
Specify a preprocessing data file
(the equal sign is optional)
-(@ref{18,,Integrated Preprocessing}).
+(@ref{90,,Integrated Preprocessing}).
@end table
@geindex -gnateP (gcc)
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_Enums : Nat; -- Foreign enums use short size?
Short_Size : Pos; -- Standard.Short_Integer'Size
Strict_Alignment : Nat; -- Strict alignment?
System_Allocator_Alignment : Nat; -- Alignment for malloc calls
Words_BE : Nat; -- Words stored big-endian?
@end example
+@code{Bits_Per_Unit} is the number of bits in a storage unit, the equivalent of
+GCC macro @code{BITS_PER_UNIT} documented as follows: @cite{Define this macro to be the number of bits in an addressable storage unit (byte); normally 8.}
+
+@code{Bits_Per_Word} is the number of bits in a machine word, the equivalent of
+GCC macro @code{BITS_PER_WORD} documented as follows: @cite{Number of bits in a word; normally 32.}
+
+@code{Double_Float_Alignment}, if not zero, is the maximum alignment that the
+compiler can choose by default for a 64-bit floating-point type or object.
+
+@code{Double_Scalar_Alignment}, if not zero, is the maximum alignment that the
+compiler can choose by default for a 64-bit or larger scalar type or object.
+
+@code{Maximum_Alignment} is the maximum alignment that the compiler can choose
+by default for a type or object, which is also the maximum alignment that can
+be specified in GNAT. It is computed for GCC backends as @code{BIGGEST_ALIGNMENT
+/ BITS_PER_UNIT} where GCC macro @code{BIGGEST_ALIGNMENT} is documented as
+follows: @cite{Biggest alignment that any data type can require on this machine@comma{} in bits.}
+
+@code{Max_Unaligned_Field} is the maximum size for unaligned bit field, which is
+64 for the majority of GCC targets (but can be different on some targets like
+AAMP).
+
+@code{Strict_Alignment} is the equivalent of GCC macro @code{STRICT_ALIGNMENT}
+documented as follows: @cite{Define this macro to be the value 1 if instructions will fail to work if given data not on the nominal alignment. If instructions will merely go slower in that case@comma{} define this macro as 0.}
+
+@code{System_Allocator_Alignment} is the guaranteed alignment of data returned
+by calls to @code{malloc}.
+
The format of the input file is as follows. First come the values of
the variables defined above, with one line per value:
@item @code{-gnateV}
Check that all actual parameters of a subprogram call are valid according to
-the rules of validity checking (@ref{f6,,Validity Checking}).
+the rules of validity checking (@ref{e7,,Validity Checking}).
@end table
@geindex -gnateY (gcc)
@item @code{-gnatE}
-Full dynamic elaboration checks.
+Dynamic elaboration checking mode enabled. For further details see
+@ref{f,,Elaboration Order Handling in GNAT}.
@end table
@geindex -gnatf (gcc)
@item @code{-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 @code{-gnatg} implies
-@code{-gnatw.ge} and
-@code{-gnatyg}
-so that all standard warnings and all standard style options are turned on.
-All warnings and style messages are treated as errors.
+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 @code{-gnatg}
+implies @code{-gnatw.ge} and @code{-gnatyg} so that all standard
+warnings and all standard style options are turned on. All warnings and style
+messages are treated as errors.
@end table
@geindex -gnatG[nn] (gcc)
Output usage information. The output is written to @code{stdout}.
@end table
+@geindex -gnatH (gcc)
+
+
+@table @asis
+
+@item @code{-gnatH}
+
+Legacy elaboration-checking mode enabled. When this switch is in effect,
+the pre-18.x access-before-elaboration model becomes the de facto model.
+For further details see @ref{f,,Elaboration Order Handling in GNAT}.
+@end table
+
@geindex -gnati (gcc)
Identifier character set (@code{c} = 1/2/3/4/8/9/p/f/n/w).
For details of the possible selections for @code{c},
-see @ref{48,,Character Set Control}.
+see @ref{31,,Character Set Control}.
@end table
@geindex -gnatI (gcc)
and Value_Size. Pragma Default_Scalar_Storage_Order is also ignored.
Note that this option should be used only for compiling -- the
code is likely to malfunction at run time.
-
-Note that when @code{-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.
@end table
@geindex -gnatjnn (gcc)
Reformat error messages to fit on @code{nn} character lines
@end table
+@geindex -gnatJ (gcc)
+
+
+@table @asis
+
+@item @code{-gnatJ}
+
+Permissive elaboration-checking mode enabled. When this switch is in effect,
+the post-18.x access-before-elaboration model ignores potential issues with:
+
+
+@itemize -
+
+@item
+Accept statements
+
+@item
+Activations of tasks defined in instances
+
+@item
+Assertion pragmas
+
+@item
+Calls from within an instance to its enclosing context
+
+@item
+Calls through generic formal parameters
+
+@item
+Calls to subprograms defined in instances
+
+@item
+Entry calls
+
+@item
+Indirect calls using 'Access
+
+@item
+Requeue statements
+
+@item
+Select statements
+
+@item
+Synchronous task suspension
+@end itemize
+
+and does not emit compile-time diagnostics or run-time checks. For further
+details see @ref{f,,Elaboration Order Handling in GNAT}.
+@end table
+
@geindex -gnatk (gcc)
@item @code{-gnatn[12]}
-Activate inlining across modules for subprograms for which pragma @code{Inline}
+Activate inlining across units for subprograms for which pragma @code{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,
+digit sets the inlining level: 1 for moderate inlining across units
+or 2 for full inlining across units. If no inlining level is specified,
the compiler will pick it based on the optimization level.
@end table
Note that division by zero is a separate check that is not
controlled by this switch (divide-by-zero checking is on by default).
-See also @ref{f8,,Specifying the Desired Mode}.
+See also @ref{e9,,Specifying the Desired Mode}.
@end table
@geindex -gnatp (gcc)
@item @code{-gnatp}
-Suppress all checks. See @ref{f9,,Run-Time Checks} for details. This switch
+Suppress all checks. See @ref{ea,,Run-Time Checks} for details. This switch
has no effect if cancelled by a subsequent @code{-gnat-p} switch.
@end table
Cancel effect of previous @code{-gnatp} switch.
@end table
-@geindex -gnatP (gcc)
-
-
-@table @asis
-
-@item @code{-gnatP}
-
-Enable polling. This is required on some systems (notably Windows NT) to
-obtain asynchronous abort and asynchronous transfer of control capability.
-See @code{Pragma_Polling} in the @cite{GNAT_Reference_Manual} for full
-details.
-@end table
-
@geindex -gnatq (gcc)
@table @asis
-@item @code{-gnatR[0/1/2/3][e][m][s]}
+@item @code{-gnatR[0|1|2|3|4][e][j][m][s]}
Output representation information for declared types, objects and
subprograms. Note that this switch is not allowed if a previous
Print package Standard.
@end table
-@geindex -gnatt (gcc)
-
-
-@table @asis
-
-@item @code{-gnatt}
-
-Generate tree output file.
-@end table
-
@geindex -gnatT (gcc)
@item @code{-gnatV}
-Control level of validity checking (@ref{f6,,Validity Checking}).
+Control level of validity checking (@ref{e7,,Validity Checking}).
@end table
@geindex -gnatw (gcc)
Warning mode where
@code{xxx} is a string of option letters that denotes
the exact warnings that
-are enabled or disabled (@ref{fa,,Warning Message Control}).
+are enabled or disabled (@ref{eb,,Warning Message Control}).
@end table
@geindex -gnatW (gcc)
@item @code{-gnaty}
-Enable built-in style checks (@ref{fb,,Style Checking}).
+Enable built-in style checks (@ref{ec,,Style Checking}).
@end table
@geindex -gnatz (gcc)
Direct GNAT to search the @code{dir} directory for source files needed by
the current compilation
-(see @ref{89,,Search Paths and the Run-Time Library (RTL)}).
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
@end table
@geindex -I- (gcc)
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{89,,Search Paths and the Run-Time Library (RTL)}).
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
@end table
@geindex -o (gcc)
@end multitable
-See also @ref{fc,,Optimization Levels}.
+See also @ref{ed,,Optimization Levels}.
@end table
@geindex -pass-exit-codes (gcc)
@item @code{--RTS=@emph{rts-path}}
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+Specifies the default location of the run-time library. Same meaning as the
+equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}).
@end table
@geindex -S (gcc)
@item
Once a 'V' appears in the string (that is a use of the @code{-gnatV}
switch), then all further characters in the switch are interpreted
-as validity checking options (@ref{f6,,Validity Checking}).
+as validity checking options (@ref{e7,,Validity Checking}).
@item
Option 'em', 'ec', 'ep', 'l=' and 'R' must be the last options in
@end itemize
@node Output and Error Message Control,Warning Message Control,Alphabetical List of All Switches,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id14}@anchor{fd}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{fe}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id14}@anchor{ee}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{ef}
@subsection Output and Error Message Control
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.
-@code{GPS} can parse the error messages
+@code{GNAT Studio} can parse the error messages
and point to the referenced character.
The following switches provide control over the error message
format:
implies @code{-gnatq}, since the semantic phase must be run to get a
meaningful ALI file.
-In addition, if @code{-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 @code{-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 @code{-gnatQ} is used and the generated @code{ALI} file is marked as
being in error, @code{gnatmake} will attempt to recompile the source when it
finds such an @code{ALI} file, including with switch @code{-gnatc}.
@end table
@node Warning Message Control,Debugging and Assertion Control,Output and Error Message Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat warning-message-control}@anchor{fa}@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{ff}
+@anchor{gnat_ugn/building_executable_programs_with_gnat warning-message-control}@anchor{eb}@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{f0}
@subsection Warning Message Control
@emph{Activate most optional warnings.}
-This switch activates most optional warning messages. See the remaining list
+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:
@item
@code{-gnatw.q} (questionable layout of record types)
+@item
+@code{-gnatw_r} (out-of-order record representation clauses)
+
@item
@code{-gnatw.s} (overridden size clause)
compile time that the assertion will fail.
@end table
+@geindex -gnatw_a
+
+
+@table @asis
+
+@item @code{-gnatw_a}
+
+@emph{Activate warnings on anonymous allocators.}
+
+@geindex Anonymous allocators
+
+This switch activates warnings for allocators of anonymous access types,
+which can involve run-time accessibility checks and lead to unexpected
+accessibility violations. For more details on the rules involved, see
+RM 3.10.2 (14).
+@end table
+
+@geindex -gnatw_A
+
+
+@table @asis
+
+@item @code{-gnatw_A}
+
+@emph{Supress warnings on anonymous allocators.}
+
+@geindex Anonymous allocators
+
+This switch suppresses warnings for anonymous access type allocators.
+@end table
+
@geindex -gnatwb (gcc)
component for which no component clause is present.
@end table
-@geindex -gnatwC (gcc)
+@geindex -gnatw.C (gcc)
@table @asis
missing a component clause in the situation described above.
@end table
+@geindex -gnatw_c (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_c}
+
+@emph{Activate warnings on unknown condition in Compile_Time_Warning.}
+
+@geindex Compile_Time_Warning
+
+@geindex Compile_Time_Error
+
+This switch activates warnings on a pragma Compile_Time_Warning
+or Compile_Time_Error whose condition has a value that is not
+known at compile time.
+The default is that such warnings are generated.
+@end table
+
+@geindex -gnatw_C (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_C}
+
+@emph{Suppress warnings on unknown condition in Compile_Time_Warning.}
+
+This switch supresses warnings on a pragma Compile_Time_Warning
+or Compile_Time_Error whose condition has a value that is not
+known at compile time.
+@end table
+
@geindex -gnatwd (gcc)
@emph{Suppress warnings on redefinition of names in standard.}
-This switch activates warnings for declarations that declare a name that
+This switch disables warnings for declarations that declare a name that
is defined in package Standard.
@end table
warnings are given.
@end table
-@geindex -gnatwT (gcc)
+@geindex -gnatw.R (gcc)
@table @asis
This switch suppresses warnings for object renaming function.
@end table
-@geindex -gnatws (gcc)
+@geindex -gnatw_r (gcc)
@table @asis
-@item @code{-gnatws}
+@item @code{-gnatw_r}
-@emph{Suppress all warnings.}
+@emph{Activate warnings for out-of-order record representation clauses.}
-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 @code{-gnatwn}.
+This switch activates warnings for record representation clauses,
+if the order of component declarations, component clauses,
+and bit-level layout do not all agree.
+The default is that these warnings are not given.
+@end table
-Note that switch @code{-gnatws} does not suppress
+@geindex -gnatw_R (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_R}
+
+@emph{Suppress warnings for out-of-order record representation clauses.}
+@end table
+
+@geindex -gnatws (gcc)
+
+
+@table @asis
+
+@item @code{-gnatws}
+
+@emph{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 @code{-gnatwn}.
+
+Note that switch @code{-gnatws} does not suppress
warnings from the @code{gcc} back end.
To suppress these back end warnings as well, use the switch @code{-w}
in addition to @code{-gnatws}. Also this switch has no effect on the
This switch activates warnings for access to variables which
may not be properly initialized. The default is that
-such warnings are generated.
+such warnings are generated. This switch will also be emitted when
+initializing an array or record object via the following aggregate:
+
+@example
+Array_Or_Record : XXX := (others => <>);
+@end example
+
+unless the relevant type fully initializes all components.
@end table
@geindex -gnatwV (gcc)
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:
-
-@example
-Tab : Table := (others => <>);
-@end example
-
-will suppress warnings on subsequent statements that access components
-of variable Tab.
@end table
@geindex -gnatw.v (gcc)
@emph{Activate warnings for size not a multiple of alignment.}
-This switch activates warnings for cases of record types with
-specified @code{Size} and @code{Alignment} attributes where the
+This switch activates warnings for cases of array and record types
+with specified @code{Size} and @code{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.
@emph{Suppress warnings for size not a multiple of alignment.}
-This switch suppresses warnings for cases of record types with
-specified @code{Size} and @code{Alignment} attributes where the
+This switch suppresses warnings for cases of array and record types
+with specified @code{Size} and @code{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 @code{Object_Size} value.
+size that is greater than the specified size. The warning can also
+be suppressed by giving an explicit @code{Object_Size} value.
@end table
@geindex -Wunused (gcc)
@item @code{-Wstack-usage=@emph{len}}
Warn if the stack usage of a subprogram might be larger than @code{len} bytes.
-See @ref{f5,,Static Stack Usage Analysis} for details.
+See @ref{e6,,Static Stack Usage Analysis} for details.
@end table
@geindex -Wall (gcc)
@end quotation
@node Debugging and Assertion Control,Validity Checking,Warning Message Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-and-assertion-control}@anchor{100}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{101}
+@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-and-assertion-control}@anchor{f1}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{f2}
@subsection Debugging and Assertion Control
@end table
@node Validity Checking,Style Checking,Debugging and Assertion Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{102}
+@anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{e7}@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{f3}
@subsection Validity Checking
All validity checks are turned on.
That is, @code{-gnatVa} is
-equivalent to @code{gnatVcdfimorst}.
+equivalent to @code{gnatVcdfimoprst}.
@end table
@geindex -gnatVc (gcc)
temporary disabling of validity checks.
@node Style Checking,Run-Time Checks,Validity Checking,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id18}@anchor{103}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{fb}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id18}@anchor{f4}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{ec}
@subsection Style Checking
allowed).
@end table
+@geindex -gnatyD (gcc)
+
+
+@table @asis
+
+@item @code{-gnatyD}
+
+@emph{Check declared identifiers in mixed case.}
+
+Declared identifiers must be in mixed case, as in
+This_Is_An_Identifier. Use -gnatyr in addition to ensure
+that references match declarations.
+@end table
+
@geindex -gnatye (gcc)
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 @code{-gnatwydISux})
+incorporated into GNAT. Currently this is equivalent to @code{-gnatyydISux})
but additional style switches may be added to this set in the future without
advance notice.
@end table
All keywords must be in lower case (with the exception of keywords
such as @code{digits} used as attribute names to which this check
-does not apply).
+does not apply). A single error is reported for each line breaking
+this rule even if multiple casing issues exist on a same line.
@end table
@geindex -gnatyl (gcc)
@c end of switch description (leave this comment to ease automatic parsing for
-@c GPS
+@c GNAT Studio
In the above rules, appearing in column one is always permitted, that is,
counts as meeting either a requirement for a required preceding space,
The switch @code{-gnatyN} clears any previously set style checks.
@node Run-Time Checks,Using gcc for Syntax Checking,Style Checking,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat run-time-checks}@anchor{f9}@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{104}
+@anchor{gnat_ugn/building_executable_programs_with_gnat run-time-checks}@anchor{ea}@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{f5}
@subsection Run-Time Checks
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
+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
Note that @code{-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{1c,,Compiling with gcc}.
+@ref{c7,,Compiling with gcc}.
@end table
@geindex -fstack-check (gcc)
@item @code{-fstack-check}
Activates stack overflow checking. For full details of the effect and use of
-this switch see @ref{f4,,Stack Overflow Checking}.
+this switch see @ref{e5,,Stack Overflow Checking}.
@end table
@geindex Unsuppress
the program source.
@node Using gcc for Syntax Checking,Using gcc for Semantic Checking,Run-Time Checks,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id20}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{106}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id20}@anchor{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{f7}
@subsection Using @code{gcc} for Syntax Checking
compiles file @code{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.
+, and can use wildcards to specify such a group of files.
Note that you must specify the @code{-c} (compile
only) flag in addition to the @code{-gnats} flag.
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 @code{gnatchop} utility
-(@ref{36,,Renaming Files with gnatchop}).
+(@ref{1d,,Renaming Files with gnatchop}).
@end table
@node Using gcc for Semantic Checking,Compiling Different Versions of Ada,Using gcc for Syntax Checking,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id21}@anchor{107}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{108}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id21}@anchor{f8}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{f9}
@subsection Using @code{gcc} for Semantic Checking
@item
The needed source files must be accessible
-(see @ref{89,,Search Paths and the Run-Time Library (RTL)}).
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
@item
Each file must contain only one compilation unit.
@item
-The file name and unit name must match (@ref{52,,File Naming Rules}).
+The file name and unit name must match (@ref{3b,,File Naming Rules}).
@end itemize
The output consists of error messages as appropriate. No object file is
@end table
@node Compiling Different Versions of Ada,Character Set Control,Using gcc for Semantic Checking,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-different-versions-of-ada}@anchor{6}@anchor{gnat_ugn/building_executable_programs_with_gnat id22}@anchor{109}
+@anchor{gnat_ugn/building_executable_programs_with_gnat compiling-different-versions-of-ada}@anchor{6}@anchor{gnat_ugn/building_executable_programs_with_gnat id22}@anchor{fa}
@subsection Compiling Different Versions of Ada
@end table
@node Character Set Control,File Naming Control,Compiling Different Versions of Ada,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id23}@anchor{10a}@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{48}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id23}@anchor{fb}@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{31}
@subsection Character Set Control
@end multitable
-See @ref{3e,,Foreign Language Representation} for full details on the
+See @ref{23,,Foreign Language Representation} for full details on the
implementation of these character sets.
@end table
For full details on these encoding
-methods see @ref{4e,,Wide_Character Encodings}.
+methods see @ref{37,,Wide_Character Encodings}.
Note that brackets coding is always accepted, even if one of the other
options is specified, so for example @code{-gnatW8} specifies that both
brackets and UTF-8 encodings will be recognized. The units that are
This is a common mode for many programs with foreign language comments.
@node File Naming Control,Subprogram Inlining Control,Character Set Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat file-naming-control}@anchor{10b}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{10c}
+@anchor{gnat_ugn/building_executable_programs_with_gnat file-naming-control}@anchor{fc}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{fd}
@subsection File Naming Control
including the @code{.ads} or @code{.adb} extension). The default is not
to enable file name krunching.
-For the source file naming rules, @ref{52,,File Naming Rules}.
+For the source file naming rules, @ref{3b,,File Naming Rules}.
@end table
@node Subprogram Inlining Control,Auxiliary Output Control,File Naming Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat subprogram-inlining-control}@anchor{10d}@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{10e}
+@anchor{gnat_ugn/building_executable_programs_with_gnat subprogram-inlining-control}@anchor{fe}@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{ff}
@subsection Subprogram Inlining Control
The @code{n} here is intended to suggest the first syllable of the word 'inline'.
GNAT recognizes and processes @code{Inline} pragmas. However, for inlining to
actually occur, optimization must be enabled and, by default, inlining of
-subprograms across modules is not performed. If you want to additionally
-enable inlining of subprograms specified by pragma @code{Inline} across modules,
+subprograms across units is not performed. If you want to additionally
+enable inlining of subprograms specified by pragma @code{Inline} across units,
you must also specify this switch.
-In the absence of this switch, GNAT does not attempt inlining across modules
+In the absence of this switch, GNAT does not attempt inlining across units
and does not access the bodies of subprograms for which @code{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
+units, which is a good compromise between compilation times and performances
+at run time, or 2 for full inlining across units, 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 @code{-O1}, @code{-O2} or
@code{-Os} and 2 for @code{-O3}.
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{10f,,Inlining of Subprograms}.
+see @ref{100,,Inlining of Subprograms}.
@end table
@geindex -gnatN (gcc)
@end table
@node Auxiliary Output Control,Debugging Control,Subprogram Inlining Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat auxiliary-output-control}@anchor{110}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{111}
+@anchor{gnat_ugn/building_executable_programs_with_gnat auxiliary-output-control}@anchor{101}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{102}
@subsection Auxiliary Output Control
-@geindex -gnatt (gcc)
-
-@geindex Writing internal trees
-
-@geindex Internal trees
-@geindex writing to file
-
-
-@table @asis
-
-@item @code{-gnatt}
-
-Causes GNAT to write the internal tree for a unit to a file (with the
-extension @code{.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 @code{-gnatct}
-generates a tree in the form required by ASIS applications.
-@end table
-
@geindex -gnatu (gcc)
@end table
@node Debugging Control,Exception Handling Control,Auxiliary Output Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{112}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{113}
+@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{103}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{104}
@subsection Debugging Control
@table @asis
-@item @code{-gnatR[0|1|2|3][e][m][s]}
+@item @code{-gnatR[0|1|2|3|4][e][j][m][s]}
This switch controls output from the compiler of a listing showing
representation information for declared types, objects and subprograms.
the @code{-gnatR} switch). For @code{-gnatR1} (which is the default,
so @code{-gnatR} with no parameter has the same effect), size and
alignment information is listed for declared array and record types.
+
For @code{-gnatR2}, size and alignment information is listed for all
declared types and objects. The @code{Linker_Section} is also listed for any
entity for which the @code{Linker_Section} is set explicitly or implicitly (the
n'th discriminant. See source files @code{repinfo.ads/adb} in the
GNAT sources for full details on the format of @code{-gnatR3} output.
+For @code{-gnatR4}, information for relevant compiler-generated types
+is also listed, i.e. when they are structurally part of other declared
+types and objects.
+
If the switch is followed by an @code{e} (e.g. @code{-gnatR2e}), then
extended representation information for record sub-components of records
-are included.
+is included.
If the switch is followed by an @code{m} (e.g. @code{-gnatRm}), then
subprogram conventions and parameter passing mechanisms for all the
subprograms are included.
+If the switch is followed by a @code{j} (e.g., @code{-gnatRj}), then
+the output is in the JSON data interchange format specified by the
+ECMA-404 standard. The semantic description of this JSON output is
+available in the specification of the Repinfo unit present in the
+compiler sources.
+
If the switch is followed by an @code{s} (e.g., @code{-gnatR3s}), then
-the output is to a file with the name @code{file.rep} where file is
-the name of the corresponding source file.
+the output is to a file with the name @code{file.rep} where @code{file} is
+the name of the corresponding source file, except if @code{j} is also
+specified, in which case the file name is @code{file.json}.
Note that it is possible for record components to have zero size. In
this case, the component clause uses an obvious extension of permitted
speed up compilation, but means that these tools cannot be used.
@end table
+@geindex -fgnat-encodings (gcc)
+
+
+@table @asis
+
+@item @code{-fgnat-encodings=[all|gdb|minimal]}
+
+This switch controls the balance between GNAT encodings and standard DWARF
+emitted in the debug information.
+
+Historically, old debug formats like stabs were not powerful enough to
+express some Ada types (for instance, variant records or fixed-point types).
+To work around this, GNAT introduced proprietary encodings that embed the
+missing information ("GNAT encodings").
+
+Recent versions of the DWARF debug information format are now able to
+correctly describe most of these Ada constructs ("standard DWARF"). As
+third-party tools started to use this format, GNAT has been enhanced to
+generate it. However, most tools (including GDB) are still relying on GNAT
+encodings.
+
+To support all tools, GNAT needs to be versatile about the balance between
+generation of GNAT encodings and standard DWARF. This is what
+@code{-fgnat-encodings} is about.
+
+
+@itemize *
+
+@item
+@code{=all}: Emit all GNAT encodings, and then emit as much standard DWARF as
+possible so it does not conflict with GNAT encodings.
+
+@item
+@code{=gdb}: Emit as much standard DWARF as possible as long as the current
+GDB handles it. Emit GNAT encodings for the rest.
+
+@item
+@code{=minimal}: Emit as much standard DWARF as possible and emit GNAT
+encodings for the rest.
+@end itemize
+@end table
+
@node Exception Handling Control,Units to Sources Mapping Files,Debugging Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{114}@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{115}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id28}@anchor{105}@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{106}
@subsection Exception Handling Control
-GNAT uses two methods for handling exceptions at run-time. The
+GNAT uses two methods for handling exceptions at run time. The
@code{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
The same option @code{--RTS} must be used both for @code{gcc}
and @code{gnatbind}. Passing this option to @code{gnatmake}
-(@ref{dc,,Switches for gnatmake}) will ensure the required consistency
+(@ref{cd,,Switches for gnatmake}) will ensure the required consistency
through the compilation and binding steps.
@node Units to Sources Mapping Files,Code Generation Control,Exception Handling Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat id29}@anchor{116}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{f7}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id29}@anchor{107}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{e8}
@subsection Units to Sources Mapping Files
@end table
@node Code Generation Control,,Units to Sources Mapping Files,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat code-generation-control}@anchor{117}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{118}
+@anchor{gnat_ugn/building_executable_programs_with_gnat code-generation-control}@anchor{108}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{109}
@subsection Code Generation Control
unless you actually see a performance improvement.
@node Linker Switches,Binding with gnatbind,Compiler Switches,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat linker-switches}@anchor{119}@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{11a}
+@anchor{gnat_ugn/building_executable_programs_with_gnat linker-switches}@anchor{10a}@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{10b}
@section Linker Switches
@end table
@node Binding with gnatbind,Linking with gnatlink,Linker Switches,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{1d}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{11b}
+@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{c8}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{10c}
@section Binding with @code{gnatbind}
@end menu
@node Running gnatbind,Switches for gnatbind,,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{11c}@anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{11d}
+@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{10d}@anchor{gnat_ugn/building_executable_programs_with_gnat id33}@anchor{10e}
@subsection Running @code{gnatbind}
@code{gnatbind} and @code{gnatlink}.
@node Switches for gnatbind,Command-Line Access,Running gnatbind,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{11e}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{11f}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{10f}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{110}
@subsection Switches for @code{gnatbind}
@item @code{-D@emph{nn}[k|m]}
-This switch can be used to change the default secondary stack size value
-to a specified size @code{nn}, which is expressed in bytes by default, or
-in kilobytes when suffixed with @code{k} or in megabytes when suffixed
-with @code{m}.
+Set the default secondary stack size to @code{nn}. The suffix indicates whether
+the size is in bytes (no suffix), kilobytes (@code{k} suffix) or megabytes
+(@code{m} suffix).
-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.
+The secondary stack holds objects of unconstrained types that are returned by
+functions, for example unconstrained Strings. The size of the secondary stack
+can be dynamic or fixed depending on the target.
-For most targets, the secondary stack grows on demand and is allocated
-as a chain of blocks in the heap. The -D option is not very
-relevant. It only give some control over the size of the allocated
-blocks (whose size is the minimum of the default secondary stack size value,
-and the actual size needed for the current allocation request).
+For most targets, the secondary stack grows on demand and is implemented as
+a chain of blocks in the heap. In this case, the default secondary stack size
+determines the initial size of the secondary stack for each task and the
+smallest amount the secondary stack can grow by.
-For certain targets, notably VxWorks 653 and bare board targets,
-the secondary stack is allocated by carving off a chunk of the primary task
-stack. By default this is a fixed percentage of the primary task stack as
-defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per
-task using the Secondary_Stack_Size pragma/aspect. The -D option is used to
-define the size of the environment task's secondary stack.
+For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
+fixed. This switch can be used to change the default size of these stacks.
+The default secondary stack size can be overridden on a per-task basis if
+individual tasks have different secondary stack requirements. This is
+achieved through the Secondary_Stack_Size aspect that takes the size of the
+secondary stack in bytes.
@end table
@geindex -e (gnatbind)
@item @code{-f@emph{elab-order}}
-Force elaboration order.
+Force elaboration order. For further details see @ref{111,,Elaboration Control}
+and @ref{f,,Elaboration Order Handling in GNAT}.
@end table
@geindex -F (gnatbind)
@item @code{-h}
Output usage (help) information.
+@end table
+
+@geindex -H (gnatbind)
+
+
+@table @asis
+
+@item @code{-H}
+
+Legacy elaboration order model enabled. For further details see
+@ref{f,,Elaboration Order Handling in GNAT}.
+@end table
@geindex -H32 (gnatbind)
+
+@table @asis
+
@item @code{-H32}
Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types).
-For further details see @ref{120,,Dynamic Allocation Control}.
+For further details see @ref{112,,Dynamic Allocation Control}.
+@end table
@geindex -H64 (gnatbind)
@geindex __gnat_malloc
+
+@table @asis
+
@item @code{-H64}
Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types).
-For further details see @ref{120,,Dynamic Allocation Control}.
+For further details see @ref{112,,Dynamic Allocation Control}.
@geindex -I (gnatbind)
@item @code{-L@emph{xxx}}
Bind the units for library building. In this case the @code{adainit} and
-@code{adafinal} procedures (@ref{b4,,Binding with Non-Ada Main Programs})
+@code{adafinal} procedures (@ref{a0,,Binding with Non-Ada Main Programs})
are renamed to @code{@emph{xxx}init} and
@code{@emph{xxx}final}.
Implies -n.
-(@ref{15,,GNAT and Libraries}, for more details.)
+(@ref{2a,,GNAT and Libraries}, for more details.)
@geindex -M (gnatbind)
A value of zero means that no limit is enforced. The equal
sign is optional.
+@geindex -minimal (gnatbind)
+
+@item @code{-minimal}
+
+Generate a binder file suitable for space-constrained applications. When
+active, binder-generated objects not required for program operation are no
+longer generated. @strong{Warning:} this option comes with the following
+limitations:
+
+
+@itemize *
+
+@item
+Starting the program's execution in the debugger will cause it to
+stop at the start of the @code{main} function instead of the main subprogram.
+This can be worked around by manually inserting a breakpoint on that
+subprogram and resuming the program's execution until reaching that breakpoint.
+
+@item
+Programs using GNAT.Compiler_Version will not link.
+@end itemize
+
@geindex -n (gnatbind)
@item @code{-n}
@item @code{--RTS=@emph{rts-path}}
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+Specifies the default location of the run-time library. Same meaning as the
+equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}).
@geindex -o (gnatbind)
@item @code{-static}
-Link against a static GNAT run time.
+Link against a static GNAT run-time.
@geindex -shared (gnatbind)
@item @code{-shared}
-Link against a shared GNAT run time when available.
+Link against a shared GNAT run-time when available.
@geindex -t (gnatbind)
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
+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 @code{FIFO_Within_Priorities}.
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{121,,Dynamic Stack Usage Analysis} for details.)
+platforms. (See @ref{113,,Dynamic Stack Usage Analysis} for details.)
@geindex -v (gnatbind)
Exclude source files (check object consistency only).
+@geindex -xdr (gnatbind)
+
+@item @code{-xdr}
+
+Use the target-independent XDR protocol for stream oriented attributes
+instead of the default implementation which is based on direct binary
+representations and is therefore target-and endianness-dependent.
+However it does not support 128-bit integer types and the exception
+@code{Ada.IO_Exceptions.Device_Error} is raised if any attempt is made
+at streaming 128-bit integer types with it.
+
@geindex -Xnnn (gnatbind)
@item @code{-X@emph{nnn}}
@end menu
@node Consistency-Checking Modes,Binder Error Message Control,,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat consistency-checking-modes}@anchor{122}@anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{123}
+@anchor{gnat_ugn/building_executable_programs_with_gnat consistency-checking-modes}@anchor{114}@anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{115}
@subsubsection Consistency-Checking Modes
@end table
@node Binder Error Message Control,Elaboration Control,Consistency-Checking Modes,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{124}@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{125}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{116}@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{117}
@subsubsection Binder Error Message Control
@end table
@node Elaboration Control,Output Control,Binder Error Message Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{126}@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{127}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{118}@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{111}
@subsubsection Elaboration Control
The following switches provide additional control over the elaboration
-order. For full details see @ref{f,,Elaboration Order Handling in GNAT}.
+order. For further details see @ref{f,,Elaboration Order Handling in GNAT}.
@geindex -f (gnatbind)
Blank lines and Ada-style comments are ignored. Unit names that do not exist
in the program are ignored. Units in the GNAT predefined library are also
ignored.
+@end table
@geindex -p (gnatbind)
+
+@table @asis
+
@item @code{-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 @code{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.
+Pessimistic elaboration order
+
+This switch is only applicable to the pre-20.x legacy elaboration models.
+The post-20.x elaboration model uses a more informed approach of ordering
+the units.
+
+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
+@code{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 @code{-p}
-switch if dynamic
+Normally it only makes sense to use the @code{-p} switch if dynamic
elaboration checking is used (@code{-gnatE} switch used for compilation).
This is because in the default static elaboration mode, all necessary
@code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted.
-These implicit pragmas are still respected by the binder in
-@code{-p} mode, so a
-safe elaboration order is assured.
+These implicit pragmas are still respected by the binder in @code{-p}
+mode, so a safe elaboration order is assured.
-Note that @code{-p} is not intended for
-production use; it is more for debugging/experimental use.
+Note that @code{-p} is not intended for production use; it is more for
+debugging/experimental use.
@end table
@node Output Control,Dynamic Allocation Control,Elaboration Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat output-control}@anchor{128}@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{129}
+@anchor{gnat_ugn/building_executable_programs_with_gnat output-control}@anchor{119}@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{11a}
@subsubsection Output Control
@end table
@node Dynamic Allocation Control,Binding with Non-Ada Main Programs,Output Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat dynamic-allocation-control}@anchor{120}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{12a}
+@anchor{gnat_ugn/building_executable_programs_with_gnat dynamic-allocation-control}@anchor{112}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{11b}
@subsubsection Dynamic Allocation Control
These switches are only effective on VMS platforms.
@node Binding with Non-Ada Main Programs,Binding Programs with No Main Subprogram,Dynamic Allocation Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-non-ada-main-programs}@anchor{b4}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{12b}
+@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-non-ada-main-programs}@anchor{a0}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{11c}
@subsubsection Binding with Non-Ada Main Programs
corresponding function @code{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{44,,Mixed Language Programming}).
+written in Ada and compiled using GNAT (@ref{2c,,Mixed Language Programming}).
The following switch is used in this situation:
@quotation
This compilation occurs automatically as part of the @code{gnatlink}
processing.
-Currently the GNAT run time requires a FPU using 80 bits mode
+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
where floating point computation could be broken after this call.
@node Binding Programs with No Main Subprogram,,Binding with Non-Ada Main Programs,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat binding-programs-with-no-main-subprogram}@anchor{12c}@anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{12d}
+@anchor{gnat_ugn/building_executable_programs_with_gnat binding-programs-with-no-main-subprogram}@anchor{11d}@anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{11e}
@subsubsection Binding Programs with No Main Subprogram
@end table
@node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{12e}@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{12f}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{11f}@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{120}
@subsection Command-Line Access
it.
@node Search Paths for gnatbind,Examples of gnatbind Usage,Command-Line Access,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{8c}@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{130}
+@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-for-gnatbind}@anchor{76}@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{121}
@subsection Search Paths for @code{gnatbind}
locate source files as well as other ALI files to verify object consistency.
For source files, it follows exactly the same search rules as @code{gcc}
-(see @ref{89,,Search Paths and the Run-Time Library (RTL)}). For ALI files the
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). For ALI files the
directories searched are:
@item
The content of the @code{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 @code{-nostdlib} is
-specified. See @ref{87,,Installing a library}
+GNAT Run-Time Library (RTL) unless the switch @code{-nostdlib} is
+specified. See @ref{71,,Installing a library}
@end itemize
@geindex -I (gnatbind)
development environments much more flexible.
@node Examples of gnatbind Usage,,Search Paths for gnatbind,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{131}@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{132}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id44}@anchor{122}@anchor{gnat_ugn/building_executable_programs_with_gnat examples-of-gnatbind-usage}@anchor{123}
@subsection Examples of @code{gnatbind} Usage
@end quotation
@node Linking with gnatlink,Using the GNU make Utility,Binding with gnatbind,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{133}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{1e}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{124}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{c9}
@section Linking with @code{gnatlink}
@end menu
@node Running gnatlink,Switches for gnatlink,,Linking with gnatlink
-@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{134}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{135}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{125}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{126}
@subsection Running @code{gnatlink}
Using @code{linker options} it is possible to set the program stack and
heap size.
-See @ref{136,,Setting Stack Size from gnatlink} and
-@ref{137,,Setting Heap Size from gnatlink}.
+See @ref{127,,Setting Stack Size from gnatlink} and
+@ref{128,,Setting Heap Size from gnatlink}.
@code{gnatlink} determines the list of objects required by the Ada
program and prepends them to the list of objects passed to the linker.
presented to the linker.
@node Switches for gnatlink,,Running gnatlink,Linking with gnatlink
-@anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{138}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{139}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{129}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{12a}
@subsection Switches for @code{gnatlink}
an executable called @code{try}.
@end table
-@geindex -b (gnatlink)
-
-
-@table @asis
-
-@item @code{-b @emph{target}}
-
-Compile your program to run on @code{target}, which is the name of a
-system configuration. You must have a GNAT cross-compiler built if
-@code{target} is not the same as your host system.
-@end table
-
@geindex -B (gnatlink)
@end table
@node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{1f}@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{13a}
+@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{70}@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{12b}
@section Using the GNU @code{make} Utility
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
-@code{gnatmake} utility (@ref{1b,,Building with gnatmake}).
+@code{gnatmake} utility (@ref{c6,,Building with gnatmake}).
All the examples in this section are specific to the GNU version of
make. Although @code{make} is a standard utility, and the basic language
@end menu
@node Using gnatmake in a Makefile,Automatically Creating a List of Directories,,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat using-gnatmake-in-a-makefile}@anchor{13b}@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{13c}
+@anchor{gnat_ugn/building_executable_programs_with_gnat using-gnatmake-in-a-makefile}@anchor{12c}@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{12d}
@subsection Using gnatmake in a Makefile
Note that you should also read the example on how to automatically
create the list of directories
-(@ref{13d,,Automatically Creating a List of Directories})
+(@ref{12e,,Automatically Creating a List of Directories})
which might help you in case your project has a lot of subdirectories.
@example
@end example
@node Automatically Creating a List of Directories,Generating the Command Line Switches,Using gnatmake in a Makefile,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat id50}@anchor{13e}@anchor{gnat_ugn/building_executable_programs_with_gnat automatically-creating-a-list-of-directories}@anchor{13d}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id50}@anchor{12f}@anchor{gnat_ugn/building_executable_programs_with_gnat automatically-creating-a-list-of-directories}@anchor{12e}
@subsection Automatically Creating a List of Directories
@end example
@node Generating the Command Line Switches,Overcoming Command Line Length Limits,Automatically Creating a List of Directories,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{13f}@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{140}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{130}@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{131}
@subsection Generating the Command Line Switches
Once you have created the list of directories as explained in the
-previous section (@ref{13d,,Automatically Creating a List of Directories}),
+previous section (@ref{12e,,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
@end example
@node Overcoming Command Line Length Limits,,Generating the Command Line Switches,Using the GNU make Utility
-@anchor{gnat_ugn/building_executable_programs_with_gnat overcoming-command-line-length-limits}@anchor{141}@anchor{gnat_ugn/building_executable_programs_with_gnat id52}@anchor{142}
+@anchor{gnat_ugn/building_executable_programs_with_gnat overcoming-command-line-length-limits}@anchor{132}@anchor{gnat_ugn/building_executable_programs_with_gnat id52}@anchor{133}
@subsection Overcoming Command Line Length Limits
It assumes that you have created a list of directories in your Makefile,
using one of the methods presented in
-@ref{13d,,Automatically Creating a List of Directories}.
+@ref{12e,,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.
@end example
@node GNAT Utility Programs,GNAT and Program Execution,Building Executable Programs with GNAT,Top
-@anchor{gnat_ugn/gnat_utility_programs doc}@anchor{143}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{b}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{144}
+@anchor{gnat_ugn/gnat_utility_programs doc}@anchor{134}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{b}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{135}
@chapter GNAT Utility Programs
@itemize *
@item
-@ref{20,,The File Cleanup Utility gnatclean}
-
-@item
-@ref{21,,The GNAT Library Browser gnatls}
-
-@item
-@ref{22,,The Cross-Referencing Tools gnatxref and gnatfind}
+@ref{136,,The File Cleanup Utility gnatclean}
@item
-@ref{23,,The Ada to HTML Converter gnathtml}
+@ref{137,,The GNAT Library Browser gnatls}
@end itemize
Other GNAT utilities are described elsewhere in this manual:
@itemize *
@item
-@ref{59,,Handling Arbitrary File Naming Conventions with gnatname}
+@ref{42,,Handling Arbitrary File Naming Conventions with gnatname}
@item
-@ref{63,,File Name Krunching with gnatkr}
+@ref{4c,,File Name Krunching with gnatkr}
@item
-@ref{36,,Renaming Files with gnatchop}
+@ref{1d,,Renaming Files with gnatchop}
@item
-@ref{17,,Preprocessing with gnatprep}
+@ref{8f,,Preprocessing with gnatprep}
@end itemize
@menu
* The File Cleanup Utility gnatclean::
* The GNAT Library Browser gnatls::
-* The Cross-Referencing Tools gnatxref and gnatfind::
-* The Ada to HTML Converter gnathtml::
@end menu
@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{145}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{20}
+@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{138}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{136}
@section The File Cleanup Utility @code{gnatclean}
@end menu
@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean
-@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{146}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{147}
+@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{13a}
@subsection Running @code{gnatclean}
normal mode is listed, but no file is actually deleted.
@node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean
-@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{148}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{149}
+@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{13b}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{13c}
@subsection Switches for @code{gnatclean}
@item @code{--version}
-Display Copyright and version, then exit disregarding all other options.
+Display copyright and version, then exit disregarding all other options.
@end table
@geindex --help (gnatclean)
@item @code{-vP@emph{x}}
Indicates the verbosity of the parsing of GNAT project files.
-@ref{de,,Switches Related to Project Files}.
+@ref{cf,,Switches Related to Project Files}.
@end table
@geindex -X (gnatclean)
Indicates that external variable @code{name} has the value @code{value}.
The Project Manager will use this value for occurrences of
@code{external(name)} when parsing the project file.
-See @ref{de,,Switches Related to Project Files}.
+See @ref{cf,,Switches Related to Project Files}.
@end table
@geindex -aO (gnatclean)
where @code{gnatclean} was invoked.
@end table
-@node The GNAT Library Browser gnatls,The Cross-Referencing Tools gnatxref and gnatfind,The File Cleanup Utility gnatclean,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{21}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{14a}
+@node The GNAT Library Browser gnatls,,The File Cleanup Utility gnatclean,GNAT Utility Programs
+@anchor{gnat_ugn/gnat_utility_programs the-gnat-library-browser-gnatls}@anchor{137}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{13d}
@section The GNAT Library Browser @code{gnatls}
@end menu
@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{14b}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{14c}
+@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{13e}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{13f}
@subsection Running @code{gnatls}
@end quotation
The main argument is the list of object or @code{ali} files
-(see @ref{42,,The Ada Library Information Files})
+(see @ref{28,,The Ada Library Information Files})
for which information is requested.
In normal mode, without additional option, @code{gnatls} produces a
@end table
@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{14d}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{14e}
+@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{140}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{141}
@subsection Switches for @code{gnatls}
@item @code{--version}
-Display Copyright and version, then exit disregarding all other options.
+Display copyright and version, then exit disregarding all other options.
@end table
@geindex --help (gnatls)
@item @code{-aO@emph{dir}}, @code{-aI@emph{dir}}, @code{-I@emph{dir}}, @code{-I-}, @code{-nostdinc}
Source path manipulation. Same meaning as the equivalent @code{gnatmake}
-flags (@ref{dc,,Switches for gnatmake}).
+flags (@ref{cd,,Switches for gnatmake}).
@end table
@geindex -aP (gnatls)
@item @code{--RTS=@emph{rts-path}}
Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
+equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}).
@end table
@geindex -v (gnatls)
@end table
@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{14f}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{150}
+@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{142}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{143}
@subsection Example of @code{gnatls} Usage
@end example
@end quotation
-@node The Cross-Referencing Tools gnatxref and gnatfind,The Ada to HTML Converter gnathtml,The GNAT Library Browser gnatls,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs the-cross-referencing-tools-gnatxref-and-gnatfind}@anchor{22}@anchor{gnat_ugn/gnat_utility_programs id9}@anchor{151}
-@section The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
-
-
-@geindex gnatxref
-@geindex gnatfind
-The compiler generates cross-referencing information (unless
-you set the @code{-gnatx} switch), which are saved in the @code{.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 @code{gnatxref} and @code{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 @code{gnatfind} is intended for locating
-definitions and/or references to a specified entity or entities, whereas
-@code{gnatxref} is oriented to generating a full report of all
-cross-references.
-To use these tools, you must not compile your application using the
-@code{-gnatx} switch on the @code{gnatmake} command line
-(see @ref{1b,,Building with gnatmake}). Otherwise, cross-referencing
-information will not be generated.
-
-@menu
-* gnatxref Switches::
-* gnatfind Switches::
-* Configuration Files for gnatxref and gnatfind::
-* Regular Expressions in gnatfind and gnatxref::
-* Examples of gnatxref Usage::
-* Examples of gnatfind Usage::
-@end menu
-@node gnatxref Switches,gnatfind Switches,,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id10}@anchor{152}@anchor{gnat_ugn/gnat_utility_programs gnatxref-switches}@anchor{153}
-@subsection @code{gnatxref} Switches
+@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-The command invocation for @code{gnatxref} is:
+@node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top
+@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{144}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{145}
+@chapter GNAT and Program Execution
-@quotation
-@example
-$ gnatxref [ switches ] sourcefile1 [ sourcefile2 ... ]
-@end example
-@end quotation
+This chapter covers several topics:
-where
+@itemize *
-@table @asis
+@item
+@ref{146,,Running and Debugging Ada Programs}
-@item @code{sourcefile1} [, @code{sourcefile2} ...]
+@item
+@ref{147,,Profiling}
-identify the source files for which a report is to be generated. The
-@code{with}ed units will be processed too. You must provide at least one file.
+@item
+@ref{148,,Improving Performance}
-These file names are considered to be regular expressions, so for instance
-specifying @code{source*.adb} is the same as giving every file in the current
-directory whose name starts with @code{source} and whose extension is
-@code{adb}.
+@item
+@ref{149,,Overflow Check Handling in GNAT}
-You shouldn't specify any directory name, just base names. @code{gnatxref}
-and @code{gnatfind} will be able to locate these files by themselves using
-the source path. If you specify directories, no result is produced.
-@end table
+@item
+@ref{14a,,Performing Dimensionality Analysis in GNAT}
-The following switches are available for @code{gnatxref}:
+@item
+@ref{14b,,Stack Related Facilities}
-@geindex --version (gnatxref)
+@item
+@ref{14c,,Memory Management Issues}
+@end itemize
+@menu
+* Running and Debugging Ada Programs::
+* Profiling::
+* Improving Performance::
+* Overflow Check Handling in GNAT::
+* Performing Dimensionality Analysis in GNAT::
+* Stack Related Facilities::
+* Memory Management Issues::
-@table @asis
+@end menu
-@item @code{--version}
+@node Running and Debugging Ada Programs,Profiling,,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{146}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{14d}
+@section Running and Debugging Ada Programs
-Display Copyright and version, then exit disregarding all other options.
-@end table
-@geindex --help (gnatxref)
+@geindex Debugging
+This section discusses how to debug Ada programs.
-@table @asis
+An incorrect Ada program may be handled in three ways by the GNAT compiler:
-@item @code{--help}
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
+@itemize *
-@geindex -a (gnatxref)
+@item
+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.
+@item
+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.
-@table @asis
+@item
+When presented with a program that contains convoluted errors, GNAT
+itself may terminate abnormally without providing full diagnostics on
+the incorrect user program.
+@end itemize
-@item @code{-a}
+@geindex Debugger
-If this switch is present, @code{gnatfind} and @code{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 @code{gnatfind} and @code{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.
-@end table
+@geindex gdb
-@geindex -aIDIR (gnatxref)
+@menu
+* The GNAT Debugger GDB::
+* Running GDB::
+* Introduction to GDB Commands::
+* Using Ada Expressions::
+* Calling User-Defined Subprograms::
+* Using the next Command in a Function::
+* Stopping When Ada Exceptions Are Raised::
+* Ada Tasks::
+* Debugging Generic Units::
+* Remote Debugging with gdbserver::
+* GNAT Abnormal Termination or Failure to Terminate::
+* Naming Conventions for GNAT Source Files::
+* Getting Internal Debugging Information::
+* Stack Traceback::
+* Pretty-Printers for the GNAT runtime::
+@end menu
-@table @asis
+@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs
+@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{14e}@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{14f}
+@subsection The GNAT Debugger GDB
-@item @code{-aI@emph{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 @code{gnatmake}.
-@end table
+@code{GDB} is a general purpose, platform-independent debugger that
+can be used to debug mixed-language programs compiled with @code{gcc},
+and in particular is capable of debugging Ada programs compiled with
+GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
+complex Ada data structures.
-@geindex -aODIR (gnatxref)
+See @cite{Debugging with GDB},
+for full details on the usage of @code{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 @code{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
+@code{-g} switch in the @code{gcc} or @code{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.
-@table @asis
+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 @code{GDB} automatically performs the necessary decoding.
-@item @code{aO@emph{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
-@code{gnatmake}.
-@end table
-
-@geindex -nostdinc (gnatxref)
-
-
-@table @asis
-
-@item @code{-nostdinc}
-
-Do not look for sources in the system default directory.
-@end table
-
-@geindex -nostdlib (gnatxref)
-
-
-@table @asis
-
-@item @code{-nostdlib}
-
-Do not look for library files in the system default directory.
-@end table
-
-@geindex --ext (gnatxref)
-
-
-@table @asis
-
-@item @code{--ext=@emph{extension}}
-
-Specify an alternate ali file extension. The default is @code{ali} and other
-extensions (e.g. @code{gli} for C/C++ sources) may be specified via this switch.
-Note that if this switch overrides the default, only the new extension will
-be considered.
-@end table
-
-@geindex --RTS (gnatxref)
-
-
-@table @asis
-
-@item @code{--RTS=@emph{rts-path}}
-
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
-@end table
-
-@geindex -d (gnatxref)
-
-
-@table @asis
-
-@item @code{-d}
-
-If this switch is set @code{gnatxref} will output the parent type
-reference for each matching derived types.
-@end table
-
-@geindex -f (gnatxref)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -g (gnatxref)
-
-
-@table @asis
-
-@item @code{-g}
-
-If this switch is set, information is output only for library-level
-entities, ignoring local entities. The use of this switch may accelerate
-@code{gnatfind} and @code{gnatxref}.
-@end table
-
-@geindex -IDIR (gnatxref)
-
-
-@table @asis
-
-@item @code{-I@emph{DIR}}
-
-Equivalent to @code{-aODIR -aIDIR}.
-@end table
-
-@geindex -pFILE (gnatxref)
-
-
-@table @asis
-
-@item @code{-p@emph{FILE}}
-
-Specify a configuration file to use to list the source and object directories.
-
-If a file is specified, then the content of the source directory and object
-directory lines are added as if they had been specified respectively
-by @code{-aI} and @code{-aO}.
-
-See @ref{154,,Configuration Files for gnatxref and gnatfind} for the syntax
-of this configuration file.
-
-@item @code{-u}
-
-Output only unused symbols. This may be really useful if you give your
-main compilation unit on the command line, as @code{gnatxref} will then
-display every unused entity and 'with'ed package.
-
-@item @code{-v}
-
-Instead of producing the default output, @code{gnatxref} will generate a
-@code{tags} file that can be used by vi. For examples how to use this
-feature, see @ref{155,,Examples of gnatxref Usage}. The tags file is output
-to the standard output, thus you will have to redirect it to a file.
-@end table
-
-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 @code{gnatxref -ag} instead of @code{gnatxref -a -g}.
-
-@node gnatfind Switches,Configuration Files for gnatxref and gnatfind,gnatxref Switches,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id11}@anchor{156}@anchor{gnat_ugn/gnat_utility_programs gnatfind-switches}@anchor{157}
-@subsection @code{gnatfind} Switches
-
-
-The command invocation for @code{gnatfind} is:
-
-@quotation
-
-@example
-$ gnatfind [ switches ] pattern[:sourcefile[:line[:column]]]
- [file1 file2 ...]
-@end example
-@end quotation
-
-with the following iterpretation of the command arguments:
-
-
-@table @asis
-
-@item @emph{pattern}
-
-An entity will be output only if it matches the regular expression found
-in @emph{pattern}, see @ref{158,,Regular Expressions in gnatfind and gnatxref}.
-
-Omitting the pattern is equivalent to specifying @code{*}, 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.
-
-@item @emph{sourcefile}
-
-@code{gnatfind} will look for references, bodies or declarations
-of symbols referenced in @code{sourcefile}, at line @code{line}
-and column @code{column}. See @ref{159,,Examples of gnatfind Usage}
-for syntax examples.
-
-@item @emph{line}
-
-A decimal integer identifying the line number containing
-the reference to the entity (or entities) to be located.
-
-@item @emph{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.
-
-@item @emph{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 @code{source*.adb} is the same as giving every file in the current
-directory whose name starts with @code{source} and whose extension is
-@code{adb}.
-
-The location of the spec of the entity will always be displayed, even if it
-isn't in one of @code{file1}, @code{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, @code{gnatfind} may
-sometimes not be able to find the body of the subprograms.
-@end table
-
-At least one of 'sourcefile' or 'pattern' has to be present on
-the command line.
-
-The following switches are available:
-
-@geindex --version (gnatfind)
-
-
-@table @asis
-
-@item @code{--version}
-
-Display Copyright and version, then exit disregarding all other options.
-@end table
-
-@geindex --help (gnatfind)
-
-
-@table @asis
-
-@item @code{--help}
-
-If @code{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-
-@geindex -a (gnatfind)
-
-
-@table @asis
-
-@item @code{-a}
-
-If this switch is present, @code{gnatfind} and @code{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 @code{gnatfind} and @code{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.
-@end table
-
-@geindex -aIDIR (gnatfind)
-
-
-@table @asis
-
-@item @code{-aI@emph{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 @code{gnatmake}.
-@end table
-
-@geindex -aODIR (gnatfind)
-
-
-@table @asis
-
-@item @code{-aO@emph{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
-@code{gnatmake}.
-@end table
-
-@geindex -nostdinc (gnatfind)
-
-
-@table @asis
-
-@item @code{-nostdinc}
-
-Do not look for sources in the system default directory.
-@end table
-
-@geindex -nostdlib (gnatfind)
-
-
-@table @asis
-
-@item @code{-nostdlib}
-
-Do not look for library files in the system default directory.
-@end table
-
-@geindex --ext (gnatfind)
-
-
-@table @asis
-
-@item @code{--ext=@emph{extension}}
-
-Specify an alternate ali file extension. The default is @code{ali} and other
-extensions may be specified via this switch. Note that if this switch
-overrides the default, only the new extension will be considered.
-@end table
-
-@geindex --RTS (gnatfind)
-
-
-@table @asis
-
-@item @code{--RTS=@emph{rts-path}}
-
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (@ref{dc,,Switches for gnatmake}).
-@end table
-
-@geindex -d (gnatfind)
-
-
-@table @asis
-
-@item @code{-d}
-
-If this switch is set, then @code{gnatfind} will output the parent type
-reference for each matching derived types.
-@end table
-
-@geindex -e (gnatfind)
-
-
-@table @asis
-
-@item @code{-e}
-
-By default, @code{gnatfind} accept the simple regular expression set for
-@code{pattern}. If this switch is set, then the pattern will be
-considered as full Unix-style regular expression.
-@end table
-
-@geindex -f (gnatfind)
-
-
-@table @asis
-
-@item @code{-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.
-@end table
-
-@geindex -g (gnatfind)
-
-
-@table @asis
-
-@item @code{-g}
-
-If this switch is set, information is output only for library-level
-entities, ignoring local entities. The use of this switch may accelerate
-@code{gnatfind} and @code{gnatxref}.
-@end table
-
-@geindex -IDIR (gnatfind)
-
-
-@table @asis
-
-@item @code{-I@emph{DIR}}
-
-Equivalent to @code{-aODIR -aIDIR}.
-@end table
-
-@geindex -pFILE (gnatfind)
-
-
-@table @asis
-
-@item @code{-p@emph{FILE}}
-
-Specify a configuration file to use to list the source and object directories.
-
-If a file is specified, then the content of the source directory and object
-directory lines are added as if they had been specified respectively
-by @code{-aI} and @code{-aO}.
-
-See @ref{154,,Configuration Files for gnatxref and gnatfind} for the syntax
-of this configuration file.
-@end table
-
-@geindex -r (gnatfind)
-
-
-@table @asis
-
-@item @code{-r}
-
-By default, @code{gnatfind} will output only the information about the
-declaration, body or type completion of the entities. If this switch is
-set, the @code{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).
-@end table
-
-@geindex -s (gnatfind)
-
-
-@table @asis
-
-@item @code{-s}
-
-If this switch is set, then @code{gnatfind} will output the content
-of the Ada source file lines were the entity was found.
-@end table
-
-@geindex -t (gnatfind)
-
-
-@table @asis
-
-@item @code{-t}
-
-If this switch is set, then @code{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.
-@end table
-
-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 @code{gnatxref -ag} instead of
-@code{gnatxref -a -g}.
-
-As stated previously, @code{gnatfind} will search in every directory in the
-search path. You can force it to look only in the current directory if
-you specify @code{*} at the end of the command line.
-
-@node Configuration Files for gnatxref and gnatfind,Regular Expressions in gnatfind and gnatxref,gnatfind Switches,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs configuration-files-for-gnatxref-and-gnatfind}@anchor{154}@anchor{gnat_ugn/gnat_utility_programs id12}@anchor{15a}
-@subsection Configuration Files for @code{gnatxref} and @code{gnatfind}
-
-
-Configuration files are used by @code{gnatxref} and @code{gnatfind} to specify
-the list of source and object directories to consider. They can be
-specified via the @code{-p} switch.
-
-The following lines can be included, in any order in the file:
-
-
-@itemize *
-
-@item
-
-@table @asis
-
-@item @emph{src_dir=DIR}
-
-[default: @code{"./"}].
-Specifies a directory where to look for source files. Multiple @code{src_dir}
-lines can be specified and they will be searched in the order they
-are specified.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{obj_dir=DIR}
-
-[default: @code{"./"}].
-Specifies a directory where to look for object and library files. Multiple
-@code{obj_dir} lines can be specified, and they will be searched in the order
-they are specified
-@end table
-@end itemize
-
-Any other line will be silently ignored.
-
-@node Regular Expressions in gnatfind and gnatxref,Examples of gnatxref Usage,Configuration Files for gnatxref and gnatfind,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id13}@anchor{15b}@anchor{gnat_ugn/gnat_utility_programs regular-expressions-in-gnatfind-and-gnatxref}@anchor{158}
-@subsection Regular Expressions in @code{gnatfind} and @code{gnatxref}
-
-
-As specified in the section about @code{gnatfind}, the pattern can be a
-regular expression. Two kinds of regular expressions
-are recognized:
-
-
-@itemize *
-
-@item
-
-@table @asis
-
-@item @emph{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:
-
-@example
-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
-@end example
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{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 @code{grep}.
-
-The following is the form of a regular expression, expressed in same BNF
-style as is found in the Ada Reference Manual:
-
-@example
-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 ()[].*+?^
-@end example
-
-Here are a few examples:
-
-@quotation
-
-
-@table @asis
-
-@item @code{abcde|fghi}
-
-will match any of the two strings @code{abcde} and @code{fghi},
-
-@item @code{abc*d}
-
-will match any string like @code{abd}, @code{abcd}, @code{abccd},
-@code{abcccd}, and so on,
-
-@item @code{[a-z]+}
-
-will match any string which has only lowercase characters in it (and at
-least one character.
-@end table
-@end quotation
-@end table
-@end itemize
-
-@node Examples of gnatxref Usage,Examples of gnatfind Usage,Regular Expressions in gnatfind and gnatxref,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatxref-usage}@anchor{155}@anchor{gnat_ugn/gnat_utility_programs id14}@anchor{15c}
-@subsection Examples of @code{gnatxref} Usage
-
-
-@menu
-* General Usage::
-* Using gnatxref with vi::
-
-@end menu
-
-@node General Usage,Using gnatxref with vi,,Examples of gnatxref Usage
-@anchor{gnat_ugn/gnat_utility_programs general-usage}@anchor{15d}
-@subsubsection General Usage
-
-
-For the following examples, we will consider the following units:
-
-@quotation
-
-@example
-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;
-@end example
-@end quotation
-
-The first thing to do is to recompile your application (for instance, in
-that case just by doing a @code{gnatmake main}, so that GNAT generates
-the cross-referencing information.
-You can then issue any of the following commands:
-
-@quotation
-
-
-@itemize *
-
-@item
-@code{gnatxref main.adb}
-@code{gnatxref} generates cross-reference information for main.adb
-and every unit 'with'ed by main.adb.
-
-The output would be:
-
-@quotation
-
-@example
-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
-@end example
-@end quotation
-
-This shows that the entity @code{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 @code{Print} is declared in @code{bar.ads}, line 2, column 15 and it
-is referenced in @code{main.adb}, line 6 column 12 and line 7 column 12.
-
-@item
-@code{gnatxref package1.adb package2.ads}
-@code{gnatxref} will generates cross-reference information for
-@code{package1.adb}, @code{package2.ads} and any other package @code{with}ed by any
-of these.
-@end itemize
-@end quotation
-
-@node Using gnatxref with vi,,General Usage,Examples of gnatxref Usage
-@anchor{gnat_ugn/gnat_utility_programs using-gnatxref-with-vi}@anchor{15e}
-@subsubsection Using @code{gnatxref} with @code{vi}
-
-
-@code{gnatxref} can generate a tags file output, which can be used
-directly from @code{vi}. Note that the standard version of @code{vi}
-will not work properly with overloaded symbols. Consider using another
-free implementation of @code{vi}, such as @code{vim}.
-
-@quotation
-
-@example
-$ gnatxref -v gnatfind.adb > tags
-@end example
-@end quotation
-
-The following command will generate the tags file for @code{gnatfind} itself
-(if the sources are in the search path!):
-
-@quotation
-
-@example
-$ gnatxref -v gnatfind.adb > tags
-@end example
-@end quotation
-
-From @code{vi}, you can then use the command @code{:tag @emph{entity}}
-(replacing @code{entity} by whatever you are looking for), and vi will
-display a new file with the corresponding declaration of entity.
-
-@node Examples of gnatfind Usage,,Examples of gnatxref Usage,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id15}@anchor{15f}@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatfind-usage}@anchor{159}
-@subsection Examples of @code{gnatfind} Usage
-
-
-
-@itemize *
-
-@item
-@code{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 @code{-f}
-switch is set)
-
-The output will look like:
-
-@quotation
-
-@example
-directory/main.ads:106:14: xyz <= declaration
-directory/main.adb:24:10: xyz <= body
-directory/foo.ads:45:23: xyz <= declaration
-@end example
-@end quotation
-
-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
-
-@item
-@code{gnatfind -fs xyz:main.adb}
-This is the same command as the previous one, but @code{gnatfind} will
-display the content of the Ada source file lines.
-
-The output will look like:
-
-@example
-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;
-@end example
-
-This can make it easier to find exactly the location your are looking
-for.
-
-@item
-@code{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.
-
-@item
-@code{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 @code{gnatfind "*":main.adb:123`}
-
-@item
-@code{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.
-@end itemize
-
-@node The Ada to HTML Converter gnathtml,,The Cross-Referencing Tools gnatxref and gnatfind,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs the-ada-to-html-converter-gnathtml}@anchor{23}@anchor{gnat_ugn/gnat_utility_programs id16}@anchor{160}
-@section The Ada to HTML Converter @code{gnathtml}
-
-
-@geindex gnathtml
-
-@code{gnathtml} is a Perl script that allows Ada source files to be browsed using
-standard Web browsers. For installation information, see @ref{161,,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 @code{-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.
-
-@menu
-* Invoking gnathtml::
-* Installing gnathtml::
-
-@end menu
-
-@node Invoking gnathtml,Installing gnathtml,,The Ada to HTML Converter gnathtml
-@anchor{gnat_ugn/gnat_utility_programs invoking-gnathtml}@anchor{162}@anchor{gnat_ugn/gnat_utility_programs id17}@anchor{163}
-@subsection Invoking @code{gnathtml}
-
-
-The command line is as follows:
-
-@quotation
-
-@example
-$ perl gnathtml.pl [ switches ] ada-files
-@end example
-@end quotation
-
-You can specify as many Ada files as you want. @code{gnathtml} will generate
-an html file for every ada file, and a global file called @code{index.htm}.
-This file is an index of every identifier defined in the files.
-
-The following switches are available:
-
-@geindex -83 (gnathtml)
-
-
-@table @asis
-
-@item @code{83}
-
-Only the Ada 83 subset of keywords will be highlighted.
-@end table
-
-@geindex -cc (gnathtml)
-
-
-@table @asis
-
-@item @code{cc @emph{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.
-@end table
-
-@geindex -d (gnathtml)
-
-
-@table @asis
-
-@item @code{d}
-
-If the Ada files depend on some other files (for instance through
-@code{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.
-@end table
-
-@geindex -D (gnathtml)
-
-
-@table @asis
-
-@item @code{D}
-
-This command is the same as @code{-d} above, but @code{gnathtml} will
-also look for files in the run-time library, and generate html files for them.
-@end table
-
-@geindex -ext (gnathtml)
-
-
-@table @asis
-
-@item @code{ext @emph{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 @code{htm}.
-@end table
-
-@geindex -f (gnathtml)
-
-
-@table @asis
-
-@item @code{f}
-
-By default, gnathtml will generate html links only for global entities
-('with'ed units, global variables and types,...). If you specify
-@code{-f} on the command line, then links will be generated for local
-entities too.
-@end table
-
-@geindex -l (gnathtml)
-
-
-@table @asis
-
-@item @code{l @emph{number}}
-
-If this switch is provided and @code{number} is not 0, then
-@code{gnathtml} will number the html files every @code{number} line.
-@end table
-
-@geindex -I (gnathtml)
-
-
-@table @asis
-
-@item @code{I @emph{dir}}
-
-Specify a directory to search for library files (@code{.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.
-@end table
-
-@geindex -o (gnathtml)
-
-
-@table @asis
-
-@item @code{o @emph{dir}}
-
-Specify the output directory for html files. By default, gnathtml will
-saved the generated html files in a subdirectory named @code{html/}.
-@end table
-
-@geindex -p (gnathtml)
-
-
-@table @asis
-
-@item @code{p @emph{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 @code{.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.
-@end table
-
-@geindex -sc (gnathtml)
-
-
-@table @asis
-
-@item @code{sc @emph{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.
-@end table
-
-@geindex -t (gnathtml)
-
-
-@table @asis
-
-@item @code{t @emph{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.
-@end table
-
-@node Installing gnathtml,,Invoking gnathtml,The Ada to HTML Converter gnathtml
-@anchor{gnat_ugn/gnat_utility_programs installing-gnathtml}@anchor{161}@anchor{gnat_ugn/gnat_utility_programs id18}@anchor{164}
-@subsection Installing @code{gnathtml}
-
-
-@code{Perl} needs to be installed on your machine to run this script.
-@code{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
-@code{gnathtml}, to explicitly specify where Perl
-is located. The syntax of this line is:
-
-@quotation
-
-@example
-#!full_path_name_to_perl
-@end example
-@end quotation
-
-Alternatively, you may run the script using the following command line:
-
-@quotation
-
-@example
-$ perl gnathtml.pl [ switches ] files
-@end example
-@end quotation
-
-@c -- +---------------------------------------------------------------------+
-
-@c -- | The following sections are present only in the PRO and GPL editions |
-
-@c -- +---------------------------------------------------------------------+
-
-
-
-
-
-
-
-
-
-@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-
-@node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top
-@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{c}@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{165}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{166}
-@chapter GNAT and Program Execution
-
-
-This chapter covers several topics:
-
-
-@itemize *
-
-@item
-@ref{167,,Running and Debugging Ada Programs}
-
-@item
-@ref{168,,Code Coverage and Profiling}
-
-@item
-@ref{169,,Improving Performance}
-
-@item
-@ref{16a,,Overflow Check Handling in GNAT}
-
-@item
-@ref{16b,,Performing Dimensionality Analysis in GNAT}
-
-@item
-@ref{16c,,Stack Related Facilities}
-
-@item
-@ref{16d,,Memory Management Issues}
-@end itemize
-
-@menu
-* 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::
-
-@end menu
-
-@node Running and Debugging Ada Programs,Code Coverage and Profiling,,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{167}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{24}
-@section Running and Debugging Ada Programs
-
-
-@geindex Debugging
-
-This section discusses how to debug Ada programs.
-
-An incorrect Ada program may be handled in three ways by the GNAT compiler:
-
-
-@itemize *
-
-@item
-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.
-
-@item
-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.
-
-@item
-When presented with a program that contains convoluted errors, GNAT
-itself may terminate abnormally without providing full diagnostics on
-the incorrect user program.
-@end itemize
-
-@geindex Debugger
-
-@geindex gdb
-
-@menu
-* The GNAT Debugger GDB::
-* Running GDB::
-* Introduction to GDB Commands::
-* Using Ada Expressions::
-* Calling User-Defined Subprograms::
-* Using the next Command in a Function::
-* Stopping When Ada Exceptions Are Raised::
-* Ada Tasks::
-* Debugging Generic Units::
-* Remote Debugging with gdbserver::
-* GNAT Abnormal Termination or Failure to Terminate::
-* Naming Conventions for GNAT Source Files::
-* Getting Internal Debugging Information::
-* Stack Traceback::
-* Pretty-Printers for the GNAT runtime::
-
-@end menu
-
-@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{16e}@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{16f}
-@subsection The GNAT Debugger GDB
-
-
-@code{GDB} is a general purpose, platform-independent debugger that
-can be used to debug mixed-language programs compiled with @code{gcc},
-and in particular is capable of debugging Ada programs compiled with
-GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
-complex Ada data structures.
-
-See @cite{Debugging with GDB},
-for full details on the usage of @code{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 @code{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
-@code{-g} switch in the @code{gcc} or @code{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 @code{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.
+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 @code{GDB}, the
debugger is activated. The image of the program is loaded, at which
variables, and more generally to report on the state of execution.
@node Running GDB,Introduction to GDB Commands,The GNAT Debugger GDB,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{170}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{171}
+@anchor{gnat_ugn/gnat_and_program_execution id4}@anchor{150}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{151}
@subsection Running GDB
This section describes how to initiate the debugger.
-The debugger can be launched from a @code{GPS} menu or
+The debugger can be launched from a @code{GNAT Studio} menu or
directly from the command line. The description below covers the latter use.
-All the commands shown can be used in the @code{GPS} debug console window,
+All the commands shown can be used in the @code{GNAT Studio} debug console window,
but there are usually more GUI-based ways to achieve the same effect.
The command to run @code{GDB} is
describes some of the additional commands that can be given to @code{GDB}.
@node Introduction to GDB Commands,Using Ada Expressions,Running GDB,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{172}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{173}
+@anchor{gnat_ugn/gnat_and_program_execution introduction-to-gdb-commands}@anchor{152}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{153}
@subsection Introduction to GDB Commands
(for example, c for continue, bt for backtrace).
@node Using Ada Expressions,Calling User-Defined Subprograms,Introduction to GDB Commands,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{174}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{175}
+@anchor{gnat_ugn/gnat_and_program_execution id6}@anchor{154}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{155}
@subsection Using Ada Expressions
For details on the supported Ada syntax, see @cite{Debugging with GDB}.
@node Calling User-Defined Subprograms,Using the next Command in a Function,Using Ada Expressions,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{176}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{177}
+@anchor{gnat_ugn/gnat_and_program_execution id7}@anchor{156}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{157}
@subsection Calling User-Defined Subprograms
the elements in the desired format.
@node Using the next Command in a Function,Stopping When Ada Exceptions Are Raised,Calling User-Defined Subprograms,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{178}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{179}
+@anchor{gnat_ugn/gnat_and_program_execution using-the-next-command-in-a-function}@anchor{158}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{159}
@subsection Using the @emph{next} Command in a Function
that was stepped through.
@node Stopping When Ada Exceptions Are Raised,Ada Tasks,Using the next Command in a Function,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{17a}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{17b}
+@anchor{gnat_ugn/gnat_and_program_execution stopping-when-ada-exceptions-are-raised}@anchor{15a}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{15b}
@subsection Stopping When Ada Exceptions Are Raised
@geindex Tasks (in gdb)
@node Ada Tasks,Debugging Generic Units,Stopping When Ada Exceptions Are Raised,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{17d}
+@anchor{gnat_ugn/gnat_and_program_execution ada-tasks}@anchor{15c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{15d}
@subsection Ada Tasks
@geindex Generics
@node Debugging Generic Units,Remote Debugging with gdbserver,Ada Tasks,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{17f}
+@anchor{gnat_ugn/gnat_and_program_execution debugging-generic-units}@anchor{15e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{15f}
@subsection Debugging Generic Units
@geindex Remote Debugging with gdbserver
@node Remote Debugging with gdbserver,GNAT Abnormal Termination or Failure to Terminate,Debugging Generic Units,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{180}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{181}
+@anchor{gnat_ugn/gnat_and_program_execution remote-debugging-with-gdbserver}@anchor{160}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{161}
@subsection Remote Debugging with gdbserver
@geindex Abnormal Termination or Failure to Terminate
@node GNAT Abnormal Termination or Failure to Terminate,Naming Conventions for GNAT Source Files,Remote Debugging with gdbserver,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{183}
+@anchor{gnat_ugn/gnat_and_program_execution gnat-abnormal-termination-or-failure-to-terminate}@anchor{162}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{163}
@subsection GNAT Abnormal Termination or Failure to Terminate
@code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the
front-end of GNAT, and can be run independently (normally it is just
called from @code{gcc}). You can use @code{gdb} on @code{gnat1} as you
-would on a C program (but @ref{16e,,The GNAT Debugger GDB} for caveats). The
+would on a C program (but @ref{14e,,The GNAT Debugger GDB} for caveats). The
@code{where} command is the first line of attack; the variable
@code{lineno} (seen by @code{print lineno}), used by the second phase of
@code{gnat1} and by the @code{gcc} backend, indicates the source line at
@end itemize
@node Naming Conventions for GNAT Source Files,Getting Internal Debugging Information,GNAT Abnormal Termination or Failure to Terminate,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{184}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{185}
+@anchor{gnat_ugn/gnat_and_program_execution naming-conventions-for-gnat-source-files}@anchor{164}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{165}
@subsection Naming Conventions for GNAT Source Files
@end itemize
@node Getting Internal Debugging Information,Stack Traceback,Naming Conventions for GNAT Source Files,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{186}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{187}
+@anchor{gnat_ugn/gnat_and_program_execution id15}@anchor{166}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{167}
@subsection Getting Internal Debugging Information
@geindex stack unwinding
@node Stack Traceback,Pretty-Printers for the GNAT runtime,Getting Internal Debugging Information,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{188}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{189}
+@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{169}
@subsection Stack Traceback
@end menu
@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{18a}@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{18b}
+@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{16b}
@subsubsection Non-Symbolic Traceback
@code{stb.adb} at line 5, which was reached from a procedure call in
@code{stb.adb} at line 10, and so on. The @code{b~std.adb} is the binder file,
which contains the call to the main program.
-@ref{11c,,Running gnatbind}. The remaining entries are assorted runtime routines,
+@ref{10d,,Running gnatbind}. The remaining entries are assorted runtime routines,
and the output will vary from platform to platform.
It is also possible to use @code{GDB} with these traceback addresses to debug
@geindex symbolic
@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{18c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{18d}
+@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{16d}
@subsubsection Symbolic Traceback
program.
@node Pretty-Printers for the GNAT runtime,,Stack Traceback,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{18e}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{18f}
+@anchor{gnat_ugn/gnat_and_program_execution id19}@anchor{16e}@anchor{gnat_ugn/gnat_and_program_execution pretty-printers-for-the-gnat-runtime}@anchor{16f}
@subsection Pretty-Printers for the GNAT runtime
Finer control of pretty-printers is also possible: see GDB's online documentation@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Commands}
for more information.
-@geindex Code Coverage
-
@geindex Profiling
-@node Code Coverage and Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{168}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-and-profiling}@anchor{25}
-@section Code Coverage and Profiling
-
+@node Profiling,Improving Performance,Running and Debugging Ada Programs,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution profiling}@anchor{147}@anchor{gnat_ugn/gnat_and_program_execution id20}@anchor{170}
+@section Profiling
-This section describes how to use the @code{gcov} coverage testing tool and
-the @code{gprof} profiler tool on Ada programs.
-@geindex gcov
+This section describes how to use the @code{gprof} profiler tool on Ada programs.
-@menu
-* Code Coverage of Ada Programs with gcov::
-* Profiling an Ada Program with gprof::
-
-@end menu
-
-@node Code Coverage of Ada Programs with gcov,Profiling an Ada Program with gprof,,Code Coverage and Profiling
-@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{190}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-of-ada-programs-with-gcov}@anchor{191}
-@subsection Code Coverage of Ada Programs with gcov
-
-
-@code{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.
-
-@code{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.
+@geindex gprof
-This chapter provides a quick startup guide, and
-details some GNAT-specific features.
+@geindex Profiling
@menu
-* Quick startup guide::
-* GNAT specifics::
+* Profiling an Ada Program with gprof::
@end menu
-@node Quick startup guide,GNAT specifics,,Code Coverage of Ada Programs with gcov
-@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{192}@anchor{gnat_ugn/gnat_and_program_execution quick-startup-guide}@anchor{193}
-@subsubsection Quick startup guide
-
-
-In order to perform coverage analysis of a program using @code{gcov}, several
-steps are needed:
-
-
-@enumerate
-
-@item
-Instrument the code during the compilation process,
-
-@item
-Execute the instrumented program, and
-
-@item
-Invoke the @code{gcov} tool to generate the coverage results.
-@end enumerate
-
-@geindex -fprofile-arcs (gcc)
-
-@geindex -ftest-coverage (gcc
-
-@geindex -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
-@code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using
-@code{-fprofile-arcs}.
-
-@quotation
-
-@example
-$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \\
- -largs -fprofile-arcs
-@end example
-@end quotation
-
-This compilation process will create @code{.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 @code{.gcda} files at the
-same location as the @code{.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 @code{gcov} tool. The different options of
-@code{gcov} are described in the GCC User's Guide, section @emph{Invoking gcov}.
-
-This will create annotated source files with a @code{.gcov} extension:
-@code{my_main.adb} file will be analyzed in @code{my_main.adb.gcov}.
-
-@node GNAT specifics,,Quick startup guide,Code Coverage of Ada Programs with gcov
-@anchor{gnat_ugn/gnat_and_program_execution gnat-specifics}@anchor{194}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{195}
-@subsubsection 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 @code{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 @code{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 @code{@@}
-(e.g. @code{gcov @@mysrclist.txt}).
-
-Note that on AIX compiling a static library with @code{-fprofile-arcs} is
-not supported as there can be unresolved symbols during the final link.
-
-@geindex gprof
-
-@geindex Profiling
-
-@node Profiling an Ada Program with gprof,,Code Coverage of Ada Programs with gcov,Code Coverage and Profiling
-@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{196}@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{197}
+@node Profiling an Ada Program with gprof,,,Profiling
+@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{171}@anchor{gnat_ugn/gnat_and_program_execution profiling-an-ada-program-with-gprof}@anchor{172}
@subsection Profiling an Ada Program with gprof
@item
linux x86/x86_64
-@item
-solaris sparc/sparc64/x86
-
@item
windows x86
@end itemize
@end menu
@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{198}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{199}
+@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{173}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{174}
@subsubsection Compilation for profiling
gnatmake switch to force full recompilation.
@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{19a}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{19b}
+@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{175}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{176}
@subsubsection Program execution
already exists, it will be overwritten.
@node Running gprof,Interpretation of profiling results,Program execution,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{19c}@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{19d}
+@anchor{gnat_ugn/gnat_and_program_execution running-gprof}@anchor{177}@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{178}
@subsubsection Running gprof
@end table
@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{19f}
+@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{179}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{17a}
@subsubsection Interpretation of profiling results
and the subprograms that it calls. It also provides an estimate of the time
spent in each of those callers/called subprograms.
-@node Improving Performance,Overflow Check Handling in GNAT,Code Coverage and Profiling,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{169}@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{26}
+@node Improving Performance,Overflow Check Handling in GNAT,Profiling,GNAT and Program Execution
+@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{17b}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{148}
@section Improving Performance
It first describes some of the tradeoffs that need to be considered
and some of the techniques for making your program run faster.
-
It then documents the unused subprogram/data elimination feature,
which can reduce the size of program executables.
@end menu
@node Performance Considerations,Text_IO Suggestions,,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{1a1}
+@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{17d}
@subsection Performance Considerations
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
-* Floating_Point_Operations::
+* Floating Point Operations::
* Vectorization of loops::
* Other Optimization Switches::
* Optimization and Strict Aliasing::
@end menu
@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{1a2}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{1a3}
+@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{17e}@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{17f}
@subsubsection Controlling Run-Time Checks
@geindex -gnato (gcc)
The gnat switch, @code{-gnatp} allows this default to be modified. See
-@ref{f9,,Run-Time Checks}.
+@ref{ea,,Run-Time Checks}.
Our experience is that the default is suitable for most development
purposes.
checks) in the program source.
@node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{1a4}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{1a5}
+@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{180}@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{181}
@subsubsection Use of Restrictions
possibility of an immediate abort at any point.
@node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{1a6}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{fc}
+@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed}
@subsubsection Optimization Levels
Full optimization as in @code{-O2};
also uses more aggressive automatic inlining of subprograms within a unit
-(@ref{10f,,Inlining of Subprograms}) and attempts to vectorize loops.
+(@ref{100,,Inlining of Subprograms}) and attempts to vectorize loops.
@end table
@item
Note regarding the use of @code{-O3}: The use of this optimization level
ought not to be automatically preferred over that of level @code{-O2},
since it often results in larger executables which may run more slowly.
-See further discussion of this point in @ref{10f,,Inlining of Subprograms}.
+See further discussion of this point in @ref{100,,Inlining of Subprograms}.
@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{1a8}
+@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{183}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{184}
@subsubsection Debugging Optimized Code
on the resulting executable,
which removes both debugging information and global symbols.
-@node Inlining of Subprograms,Floating_Point_Operations,Debugging Optimized Code,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{10f}
+@node Inlining of Subprograms,Floating Point Operations,Debugging Optimized Code,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{185}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{100}
@subsubsection Inlining of Subprograms
indeed you should use @code{-O3} only if tests show that it actually
improves performance for your program.
-@node Floating_Point_Operations,Vectorization of loops,Inlining of Subprograms,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{1ab}
-@subsubsection Floating_Point_Operations
+@node Floating Point Operations,Vectorization of loops,Inlining of Subprograms,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution floating-point-operations}@anchor{186}@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{187}
+@subsubsection Floating Point Operations
@geindex Floating-Point Operations
so it is permissible to mix units compiled with and without these
switches.
-@node Vectorization of loops,Other Optimization Switches,Floating_Point_Operations,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{1ac}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{1ad}
+@node Vectorization of loops,Other Optimization Switches,Floating Point Operations,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id34}@anchor{188}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{189}
@subsubsection Vectorization of loops
omit the non-vectorized version of the loop as well as the run-time test.
@node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{1ae}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{1af}
+@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{18a}@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{18b}
@subsubsection Other Optimization Switches
chapter of @cite{Using the GNU Compiler Collection (GCC)}.
@node Optimization and Strict Aliasing,Aliased Variables and Optimization,Other Optimization Switches,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{f3}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{1b0}
+@anchor{gnat_ugn/gnat_and_program_execution optimization-and-strict-aliasing}@anchor{e4}@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{18c}
@subsubsection Optimization and Strict Aliasing
particularly if you are getting the warnings described above.
@node Aliased Variables and Optimization,Atomic Variables and Optimization,Optimization and Strict Aliasing,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{1b1}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{1b2}
+@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{18d}@anchor{gnat_ugn/gnat_and_program_execution aliased-variables-and-optimization}@anchor{18e}
@subsubsection Aliased Variables and Optimization
that is, it will produce the expected results.
@node Atomic Variables and Optimization,Passive Task Optimization,Aliased Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{1b3}@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{1b4}
+@anchor{gnat_ugn/gnat_and_program_execution atomic-variables-and-optimization}@anchor{18f}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{190}
@subsubsection Atomic Variables and Optimization
useful to disable it.
@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{1b5}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{1b6}
+@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{191}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{192}
@subsubsection Passive Task Optimization
to be modified, only the task definition itself.
@node Text_IO Suggestions,Reducing Size of Executables with Unused Subprogram/Data Elimination,Performance Considerations,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{1b7}@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{1b8}
+@anchor{gnat_ugn/gnat_and_program_execution text-io-suggestions}@anchor{193}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{194}
@subsection @code{Text_IO} Suggestions
be buffered using @code{Interfaces.C_Streams.setvbuf}.
@node Reducing Size of Executables with Unused Subprogram/Data Elimination,,Text_IO Suggestions,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{1b9}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{1ba}
+@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{195}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{196}
@subsection Reducing Size of Executables with Unused Subprogram/Data Elimination
@end menu
@node About unused subprogram/data elimination,Compilation options,,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{1bb}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{1bc}
+@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{197}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{198}
@subsubsection About unused subprogram/data elimination
In both cases GNU binutils version 2.16 or later are required to enable it.
@node Compilation options,Example of unused subprogram/data elimination,About unused subprogram/data elimination,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{1bd}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{1be}
+@anchor{gnat_ugn/gnat_and_program_execution id43}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{19a}
@subsubsection Compilation options
and data of the GNAT library from your executable.
@node Example of unused subprogram/data elimination,,Compilation options,Reducing Size of Executables with Unused Subprogram/Data Elimination
-@anchor{gnat_ugn/gnat_and_program_execution id47}@anchor{1bf}@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{1c0}
+@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{19b}@anchor{gnat_ugn/gnat_and_program_execution id44}@anchor{19c}
@subsubsection Example of unused subprogram/data elimination
@geindex Checks (overflow)
-
@node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{16a}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{27}
+@anchor{gnat_ugn/gnat_and_program_execution id45}@anchor{149}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{19d}
@section Overflow Check Handling in GNAT
@end menu
@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{1c1}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{1c2}
+@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{19f}
@subsection Background
would prefer this precondition to be considered True at run time).
@node Management of Overflows in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1c3}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1c4}
+@anchor{gnat_ugn/gnat_and_program_execution id47}@anchor{1a0}@anchor{gnat_ugn/gnat_and_program_execution management-of-overflows-in-gnat}@anchor{1a1}
@subsection Management of Overflows in GNAT
range checks).
@node Specifying the Desired Mode,Default Settings,Management of Overflows in GNAT,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{f8}@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1c5}
+@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{e9}@anchor{gnat_ugn/gnat_and_program_execution id48}@anchor{1a2}
@subsection Specifying the Desired Mode
type (@code{STRICT} mode).
@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id59}@anchor{1c6}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1c7}
+@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1a4}
@subsection Default Settings
intermediate results.
@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1c8}@anchor{gnat_ugn/gnat_and_program_execution id60}@anchor{1c9}
+@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution id50}@anchor{1a6}
@subsection Implementation Notes
to this package, though only in cases where it cannot be
sure that @code{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
+allocation, 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).
platforms).
@node Performing Dimensionality Analysis in GNAT,Stack Related Facilities,Overflow Check Handling in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id61}@anchor{16b}@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{28}
+@anchor{gnat_ugn/gnat_and_program_execution performing-dimensionality-analysis-in-gnat}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution id51}@anchor{14a}
@section Performing Dimensionality Analysis in GNAT
@geindex MKS_Type type
The simplest way to impose dimensionality checking on a computation is to make
-use of the package @code{System.Dim.Mks},
-which is part of the GNAT library. This
-package defines a floating-point type @code{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 @code{s-dimmks.ads}.
+use of one of the instantiations of the package @code{System.Dim.Generic_Mks}, which
+are part of the GNAT library. This generic package defines a floating-point
+type @code{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
+@code{s-digemk.ads}.
@quotation
-@geindex s-dimmks.ads file
+@geindex s-digemk.ads file
@example
-type Mks_Type is new Long_Long_Float
+type Mks_Type is new Float_Type
with
Dimension_System => (
(Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
@end example
@end quotation
-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:
+There are three instantiations of @code{System.Dim.Generic_Mks} defined in the
+GNAT library:
+
+
+@itemize *
+
+@item
+@code{System.Dim.Float_Mks} based on @code{Float} defined in @code{s-diflmk.ads}.
+
+@item
+@code{System.Dim.Long_Mks} based on @code{Long_Float} defined in @code{s-dilomk.ads}.
+
+@item
+@code{System.Dim.Mks} based on @code{Long_Long_Float} defined in @code{s-dimmks.ads}.
+@end itemize
+
+Using one of these packages, 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:
@quotation
dimension vector for the formal parameter).
@node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{29}@anchor{gnat_ugn/gnat_and_program_execution id62}@anchor{16c}
+@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{1a8}@anchor{gnat_ugn/gnat_and_program_execution id52}@anchor{14b}
@section Stack Related Facilities
@end menu
@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id63}@anchor{1ca}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{f4}
+@anchor{gnat_ugn/gnat_and_program_execution id53}@anchor{1a9}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{e5}
@subsection Stack Overflow Checking
For declared tasks, the default stack size is defined by the GNAT runtime,
whose size may be modified at bind time through the @code{-d} bind switch
-(@ref{11f,,Switches for gnatbind}). Task specific stack sizes may be set using the
+(@ref{110,,Switches for gnatbind}). Task specific stack sizes may be set using the
@code{Storage_Size} pragma.
For the environment task, the stack size is determined by the operating system.
operating system documentation.
@node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id64}@anchor{1cb}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{f5}
+@anchor{gnat_ugn/gnat_and_program_execution id54}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6}
@subsection Static Stack Usage Analysis
bytes. The wording is in keeping with the qualifier documented above.
@node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id65}@anchor{1cc}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{121}
+@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{1ab}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{113}
@subsection Dynamic Stack Usage Analysis
@end example
@end quotation
-With this option, at each task termination, its stack usage is output on
+With this option, at each task termination, its stack usage is output on
@code{stderr}.
+Note that this switch is not compatible with tools like
+Valgrind and DrMemory; they will report errors.
+
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
stack-usage reports at run time. See its body for the details.
@node Memory Management Issues,,Stack Related Facilities,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id66}@anchor{16d}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{2a}
+@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{14c}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{1ac}
@section Memory Management Issues
@end menu
@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id67}@anchor{1cd}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1ce}
+@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{1ad}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{1ae}
@subsection Some Useful Memory Pools
@end quotation
@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id68}@anchor{1cf}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1d0}
+@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{1af}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{1b0}
@subsection The GNAT Debug Pool Facility
@c -- E.g. Ada |nbsp| 95
@node Platform-Specific Information,Example of Binder Output File,GNAT and Program Execution,Top
-@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}@anchor{gnat_ugn/platform_specific_information doc}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1d2}
+@anchor{gnat_ugn/platform_specific_information platform-specific-information}@anchor{d}@anchor{gnat_ugn/platform_specific_information doc}@anchor{1b1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1b2}
@chapter Platform-Specific Information
@end menu
@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id2}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{2b}
+@anchor{gnat_ugn/platform_specific_information id2}@anchor{1b3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1b4}
@section Run-Time Libraries
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.@}
+tasking applications or applications with many exception handlers.
+Note however that the ZCX run-time does not support asynchronous abort
+of tasks (@code{abort} and @code{select-then-abort} constructs) and will instead
+implement abort by polling points in the runtime. You can also add additional
+polling points explicitly if needed in your application via @code{pragma
+Abort_Defer}.
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.
@menu
* Summary of Run-Time Configurations::
@end menu
@node Summary of Run-Time Configurations,,,Run-Time Libraries
-@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1d4}@anchor{gnat_ugn/platform_specific_information id3}@anchor{1d5}
+@anchor{gnat_ugn/platform_specific_information summary-of-run-time-configurations}@anchor{1b5}@anchor{gnat_ugn/platform_specific_information id3}@anchor{1b6}
@subsection Summary of Run-Time Configurations
@node Specifying a Run-Time Library,GNU/Linux Topics,Run-Time Libraries,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1d6}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1d7}
+@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{1b7}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1b8}
@section Specifying a Run-Time Library
Selecting another run-time library temporarily can be
achieved by using the @code{--RTS} switch, e.g., @code{--RTS=sjlj}
-@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1d8}
+@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{1b9}
@geindex SCHED_FIFO scheduling policy
@geindex SCHED_RR scheduling policy
@end menu
@node Choosing the Scheduling Policy,,,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id5}@anchor{1d9}
+@anchor{gnat_ugn/platform_specific_information id5}@anchor{1ba}
@subsection Choosing the Scheduling Policy
@geindex GNU/Linux
@node GNU/Linux Topics,Microsoft Windows Topics,Specifying a Run-Time Library,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id6}@anchor{1da}@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1db}
+@anchor{gnat_ugn/platform_specific_information id6}@anchor{1bb}@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1bc}
@section GNU/Linux Topics
@end menu
@node Required Packages on GNU/Linux,,,GNU/Linux Topics
-@anchor{gnat_ugn/platform_specific_information id7}@anchor{1dc}@anchor{gnat_ugn/platform_specific_information required-packages-on-gnu-linux}@anchor{1dd}
+@anchor{gnat_ugn/platform_specific_information id7}@anchor{1bd}@anchor{gnat_ugn/platform_specific_information required-packages-on-gnu-linux}@anchor{1be}
@subsection Required Packages on GNU/Linux
@end itemize
If using the 32-bit version of GNAT on a 64-bit version of GNU/Linux,
-you'll need the 32-bit version of the glibc and glibc-devel packages:
+you'll need the 32-bit version of the following packages:
@itemize *
@item
-RedHat, SUSE: @code{glibc.i686}, @code{glibc-devel.i686}
+RedHat, SUSE: @code{glibc.i686}, @code{glibc-devel.i686}, @code{ncurses-libs.i686}
@item
-Debian, Ubuntu: @code{libc6:i386}, @code{libc6-dev:i386}
+Debian, Ubuntu: @code{libc6:i386}, @code{libc6-dev:i386}, @code{lib32ncursesw5}
@end itemize
Other GNU/Linux distributions might be choosing a different name
-for that package.
+for those packages.
@geindex Windows
@node Microsoft Windows Topics,Mac OS Topics,GNU/Linux Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{2c}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1de}
+@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1bf}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1c0}
@section Microsoft Windows Topics
platforms.
-
-
-
@menu
* Using GNAT on Windows::
* Using a network installation of GNAT::
* CONSOLE and WINDOWS subsystems::
* Temporary Files::
* Disabling Command Line Argument Expansion::
+* Windows Socket Timeouts::
* Mixed-Language Programming on Windows::
* Windows Specific Add-Ons::
@end menu
@node Using GNAT on Windows,Using a network installation of GNAT,,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1df}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1e0}
+@anchor{gnat_ugn/platform_specific_information using-gnat-on-windows}@anchor{1c1}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1c2}
@subsection Using GNAT on Windows
@end itemize
@node Using a network installation of GNAT,CONSOLE and WINDOWS subsystems,Using GNAT on Windows,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id10}@anchor{1e1}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1e2}
+@anchor{gnat_ugn/platform_specific_information id10}@anchor{1c3}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1c4}
@subsection Using a network installation of GNAT
serious performance penalty.
@node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id11}@anchor{1e3}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1e4}
+@anchor{gnat_ugn/platform_specific_information id11}@anchor{1c5}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{1c6}
@subsection CONSOLE and WINDOWS subsystems
@end quotation
@node Temporary Files,Disabling Command Line Argument Expansion,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id12}@anchor{1e5}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1e6}
+@anchor{gnat_ugn/platform_specific_information id12}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1c8}
@subsection Temporary Files
environments where you may not have write access to some
directories.
-@node Disabling Command Line Argument Expansion,Mixed-Language Programming on Windows,Temporary Files,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1e7}
+@node Disabling Command Line Argument Expansion,Windows Socket Timeouts,Temporary Files,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information disabling-command-line-argument-expansion}@anchor{1c9}
@subsection Disabling Command Line Argument Expansion
Ada.Command_Line.Argument (1) -> "'*.txt'"
@end example
-@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Disabling Command Line Argument Expansion,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id13}@anchor{1e8}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1e9}
+@node Windows Socket Timeouts,Mixed-Language Programming on Windows,Disabling Command Line Argument Expansion,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information windows-socket-timeouts}@anchor{1ca}
+@subsection Windows Socket Timeouts
+
+
+Microsoft Windows desktops older than @code{8.0} and Microsoft Windows Servers
+older than @code{2019} set a socket timeout 500 milliseconds longer than the value
+set by setsockopt with @code{SO_RCVTIMEO} and @code{SO_SNDTIMEO} options. The GNAT
+runtime makes a correction for the difference in the corresponding Windows
+versions. For Windows Server starting with version @code{2019}, the user must
+provide a manifest file for the GNAT runtime to be able to recognize that
+the Windows version does not need the timeout correction. The manifest file
+should be located in the same directory as the executable file, and its file
+name must match the executable name suffixed by @code{.manifest}. For example,
+if the executable name is @code{sock_wto.exe}, then the manifest file name
+has to be @code{sock_wto.exe.manifest}. The manifest file must contain at
+least the following data:
+
+@example
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+<compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+<application>
+ <!-- Windows Vista -->
+ <supportedOS Id="@{e2011457-1546-43c5-a5fe-008deee3d3f0@}"/>
+ <!-- Windows 7 -->
+ <supportedOS Id="@{35138b9a-5d96-4fbd-8e2d-a2440225f93a@}"/>
+ <!-- Windows 8 -->
+ <supportedOS Id="@{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38@}"/>
+ <!-- Windows 8.1 -->
+ <supportedOS Id="@{1f676c76-80e1-4239-95bb-83d0f6d0da78@}"/>
+ <!-- Windows 10 -->
+ <supportedOS Id="@{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a@}"/>
+</application>
+</compatibility>
+</assembly>
+@end example
+
+Without the manifest file, the socket timeout is going to be overcorrected on
+these Windows Server versions and the actual time is going to be 500
+milliseconds shorter than what was set with GNAT.Sockets.Set_Socket_Option.
+Note that on Microsoft Windows versions where correction is necessary, there
+is no way to set a socket timeout shorter than 500 ms. If a socket timeout
+shorter than 500 ms is needed on these Windows versions, a call to
+Check_Selector should be added before any socket read or write operations.
+
+@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Windows Socket Timeouts,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information id13}@anchor{1cb}@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{1cc}
@subsection Mixed-Language Programming on Windows
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{1ea,,Using DLLs with GNAT}).
+(@ref{1cd,,Using DLLs with GNAT}).
@item
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{1eb,,Building DLLs with GNAT Project files}) and use the Microsoft
+(@ref{1ce,,Building DLLs with GNAT Project files}) and use the Microsoft
or whatever environment to build your executable.
@end itemize
In addition to the description about C main in
-@ref{44,,Mixed Language Programming} section, if the C main uses a
+@ref{2c,,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:
@end menu
@node Windows Calling Conventions,Introduction to Dynamic Link Libraries DLLs,,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1ec}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1ed}
+@anchor{gnat_ugn/platform_specific_information windows-calling-conventions}@anchor{1cf}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1d0}
@subsubsection Windows Calling Conventions
@end menu
@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1ee}@anchor{gnat_ugn/platform_specific_information id15}@anchor{1ef}
+@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{1d1}@anchor{gnat_ugn/platform_specific_information id15}@anchor{1d2}
@subsubsection @code{C} Calling Convention
When importing a variable defined in C, you should always use the @code{C}
calling convention unless the object containing the variable is part of a
DLL (in which case you should use the @code{Stdcall} calling
-convention, @ref{1f0,,Stdcall Calling Convention}).
+convention, @ref{1d3,,Stdcall Calling Convention}).
@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1f0}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1f1}
+@anchor{gnat_ugn/platform_specific_information stdcall-calling-convention}@anchor{1d3}@anchor{gnat_ugn/platform_specific_information id16}@anchor{1d4}
@subsubsection @code{Stdcall} Calling Convention
will be handled as a @code{C} calling convention on non-Windows platforms.
@node Win32 Calling Convention,DLL Calling Convention,Stdcall Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1f2}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1f3}
+@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{1d5}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1d6}
@subsubsection @code{Win32} Calling Convention
@code{Stdcall} calling convention described above.
@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information id18}@anchor{1f4}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1f5}
+@anchor{gnat_ugn/platform_specific_information id18}@anchor{1d7}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{1d8}
@subsubsection @code{DLL} Calling Convention
@code{Stdcall} calling convention described above.
@node Introduction to Dynamic Link Libraries DLLs,Using DLLs with GNAT,Windows Calling Conventions,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id19}@anchor{1f6}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1f7}
+@anchor{gnat_ugn/platform_specific_information id19}@anchor{1d9}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1da}
@subsubsection Introduction to Dynamic Link Libraries (DLLs)
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{1f8,,The Definition File}).
+a definition file (see @ref{1db,,The Definition File}).
@node Using DLLs with GNAT,Building DLLs with GNAT Project files,Introduction to Dynamic Link Libraries DLLs,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id20}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1ea}
+@anchor{gnat_ugn/platform_specific_information id20}@anchor{1dc}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1cd}
@subsubsection Using DLLs with GNAT
@end menu
@node Creating an Ada Spec for the DLL Services,Creating an Import Library,,Using DLLs with GNAT
-@anchor{gnat_ugn/platform_specific_information id21}@anchor{1fa}@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1fb}
+@anchor{gnat_ugn/platform_specific_information id21}@anchor{1dd}@anchor{gnat_ugn/platform_specific_information creating-an-ada-spec-for-the-dll-services}@anchor{1de}
@subsubsection Creating an Ada Spec for the DLL Services
@end quotation
@node Creating an Import Library,,Creating an Ada Spec for the DLL Services,Using DLLs with GNAT
-@anchor{gnat_ugn/platform_specific_information id22}@anchor{1fc}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1fd}
+@anchor{gnat_ugn/platform_specific_information id22}@anchor{1df}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1e0}
@subsubsection Creating an Import Library
DLL. Otherwise read on.
@geindex Definition file
-@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1f8}
+@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1db}
@subsubheading The Definition File
@end table
Note that you must specify the correct suffix (@code{@@@emph{nn}})
-(see @ref{1ec,,Windows Calling Conventions}) for a Stdcall
+(see @ref{1cf,,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.
-@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{1fe}
+@anchor{gnat_ugn/platform_specific_information create-def-file-automatically}@anchor{1e1}
@subsubheading Creating a Definition File Automatically
You can automatically create the definition file @code{API.def}
-(see @ref{1f8,,The Definition File}) from a DLL.
+(see @ref{1db,,The Definition File}) from a DLL.
For that use the @code{dlltool} program as follows:
@quotation
@end example
Note that if some routines in the DLL have the @code{Stdcall} convention
-(@ref{1ec,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}}
+(@ref{1cf,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}}
suffix then you'll have to edit @code{api.def} to add it, and specify
@code{-k} to @code{gnatdll} when creating the import library.
definition file and add the right suffix.
@end itemize
@end quotation
-@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1ff}
+@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1e2}
@subsubheading GNAT-Style Import Library
To create a static import library from @code{API.dll} with the GNAT tools
you should create the .def file, then use @code{gnatdll} tool
-(see @ref{200,,Using gnatdll}) as follows:
+(see @ref{1e3,,Using gnatdll}) as follows:
@quotation
be @code{libxyz.a}. Note that in the previous example option
@code{-e} could have been removed because the name of the definition
file (before the @code{.def} suffix) is the same as the name of the
-DLL (@ref{200,,Using gnatdll} for more information about @code{gnatdll}).
+DLL (@ref{1e3,,Using gnatdll} for more information about @code{gnatdll}).
@end quotation
-@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{201}
+@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1e4}
@subsubheading 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{1e9,,Mixed-Language Programming on Windows}).
+tools (@ref{1cc,,Mixed-Language Programming on Windows}).
To create a Microsoft-style import library for @code{API.dll} you
should create the .def file, then build the actual import library using
@end quotation
@node Building DLLs with GNAT Project files,Building DLLs with GNAT,Using DLLs with GNAT,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id23}@anchor{202}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1eb}
+@anchor{gnat_ugn/platform_specific_information id23}@anchor{1e5}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1ce}
@subsubsection Building DLLs with GNAT Project files
of shared libraries, so it is not possible to have library level tasks in SALs.
@node Building DLLs with GNAT,Building DLLs with gnatdll,Building DLLs with GNAT Project files,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{203}@anchor{gnat_ugn/platform_specific_information id24}@anchor{204}
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat}@anchor{1e6}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1e7}
@subsubsection Building DLLs with GNAT
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 @code{gcc} a definition
-file (see @ref{1f8,,The Definition File}).
+file (see @ref{1db,,The Definition File}).
For example:
@example
@end quotation
@node Building DLLs with gnatdll,Ada DLLs and Finalization,Building DLLs with GNAT,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{205}@anchor{gnat_ugn/platform_specific_information id25}@anchor{206}
+@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnatdll}@anchor{1e8}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1e9}
@subsubsection Building DLLs with gnatdll
@geindex building
Note that it is preferred to use GNAT Project files
-(@ref{1eb,,Building DLLs with GNAT Project files}) or the built-in GNAT
-DLL support (@ref{203,,Building DLLs with GNAT}) or to build DLLs.
+(@ref{1ce,,Building DLLs with GNAT Project files}) or the built-in GNAT
+DLL support (@ref{1e6,,Building DLLs with GNAT}) or to build DLLs.
This section explains how to build DLLs containing Ada code using
@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
You need to mark each Ada entity exported by the DLL with a @code{C} or
@code{Stdcall} calling convention to avoid any Ada name mangling for the
entities exported by the DLL
-(see @ref{207,,Exporting Ada Entities}). You can
+(see @ref{1ea,,Exporting Ada Entities}). You can
skip this step if you plan to use the Ada DLL only from Ada applications.
@item
Your Ada code must export an initialization routine which calls the routine
@code{adainit} generated by @code{gnatbind} to perform the elaboration of
-the Ada code in the DLL (@ref{208,,Ada DLLs and Elaboration}). The initialization
+the Ada code in the DLL (@ref{1eb,,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.
@item
When useful, the DLL should also export a finalization routine which calls
routine @code{adafinal} generated by @code{gnatbind} to perform the
-finalization of the Ada code in the DLL (@ref{209,,Ada DLLs and Finalization}).
+finalization of the Ada code in the DLL (@ref{1ec,,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.
@item
You must provide a definition file listing the exported entities
-(@ref{1f8,,The Definition File}).
+(@ref{1db,,The Definition File}).
@item
Finally you must use @code{gnatdll} to produce the DLL and the import
-library (@ref{200,,Using gnatdll}).
+library (@ref{1e3,,Using gnatdll}).
@end itemize
Note that a relocatable DLL stripped using the @code{strip}
@end menu
@node Limitations When Using Ada DLLs from Ada,Exporting Ada Entities,,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{20a}
+@anchor{gnat_ugn/platform_specific_information limitations-when-using-ada-dlls-from-ada}@anchor{1ed}
@subsubsection Limitations When Using Ada DLLs from Ada
Windows object handles, etc.
@node Exporting Ada Entities,Ada DLLs and Elaboration,Limitations When Using Ada DLLs from Ada,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{207}@anchor{gnat_ugn/platform_specific_information id26}@anchor{20b}
+@anchor{gnat_ugn/platform_specific_information exporting-ada-entities}@anchor{1ea}@anchor{gnat_ugn/platform_specific_information id26}@anchor{1ee}
@subsubsection Exporting Ada Entities
Note that if you do not export the Ada entities with a @code{C} or
@code{Stdcall} convention you will have to provide the mangled Ada names
in the definition file of the Ada DLL
-(@ref{20c,,Creating the Definition File}).
+(@ref{1ef,,Creating the Definition File}).
@node Ada DLLs and Elaboration,,Exporting Ada Entities,Building DLLs with gnatdll
-@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{208}@anchor{gnat_ugn/platform_specific_information id27}@anchor{20d}
+@anchor{gnat_ugn/platform_specific_information ada-dlls-and-elaboration}@anchor{1eb}@anchor{gnat_ugn/platform_specific_information id27}@anchor{1f0}
@subsubsection Ada DLLs and Elaboration
(@code{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 @code{adainit} generated by the GNAT binder
-(@ref{b4,,Binding with Non-Ada Main Programs}). See the body of
+(@ref{a0,,Binding with Non-Ada Main Programs}). See the body of
@code{Initialize_Api} for an example. Note that the GNAT binder is
automatically invoked during the DLL build process by the @code{gnatdll}
-tool (@ref{200,,Using gnatdll}).
+tool (@ref{1e3,,Using gnatdll}).
When a DLL is loaded, Windows systematically invokes a routine called
@code{DllMain}. It would therefore be possible to call @code{adainit}
newly created task to complete its initialization.
@node Ada DLLs and Finalization,Creating a Spec for Ada DLLs,Building DLLs with gnatdll,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id28}@anchor{20e}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{209}
+@anchor{gnat_ugn/platform_specific_information id28}@anchor{1f1}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{1ec}
@subsubsection Ada DLLs and 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 @code{adafinal} generated by the GNAT binder
-(@ref{b4,,Binding with Non-Ada Main Programs}).
+(@ref{a0,,Binding with Non-Ada Main Programs}).
See the body of @code{Finalize_Api} for an
example. As already pointed out the GNAT binder is automatically invoked
during the DLL build process by the @code{gnatdll} tool
-(@ref{200,,Using gnatdll}).
+(@ref{1e3,,Using gnatdll}).
@node Creating a Spec for Ada DLLs,GNAT and Windows Resources,Ada DLLs and Finalization,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id29}@anchor{20f}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{210}
+@anchor{gnat_ugn/platform_specific_information id29}@anchor{1f2}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{1f3}
@subsubsection Creating a Spec for Ada DLLs
@end menu
@node Creating the Definition File,Using gnatdll,,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{20c}@anchor{gnat_ugn/platform_specific_information id30}@anchor{211}
+@anchor{gnat_ugn/platform_specific_information creating-the-definition-file}@anchor{1ef}@anchor{gnat_ugn/platform_specific_information id30}@anchor{1f4}
@subsubsection Creating the Definition File
@end quotation
@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{200}@anchor{gnat_ugn/platform_specific_information id31}@anchor{212}
+@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1e3}@anchor{gnat_ugn/platform_specific_information id31}@anchor{1f5}
@subsubsection Using @code{gnatdll}
Direct @code{gnatdll} to search the @code{dir} directory for source and
object files needed to build the DLL.
-(@ref{89,,Search Paths and the Run-Time Library (RTL)}).
+(@ref{73,,Search Paths and the Run-Time Library (RTL)}).
@geindex -k (gnatdll)
is loaded into memory.
@item
-@code{gnatdll} uses @code{dlltool} (see @ref{213,,Using dlltool}) to build the
+@code{gnatdll} uses @code{dlltool} (see @ref{1f6,,Using dlltool}) to build the
export table (@code{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.
$ gnatlink api api.exp -o api.dll -mdll
@end example
@end itemize
-@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{213}
+@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{1f6}
@subsubheading Using @code{dlltool}
@item @code{-k}
Kill @code{@@@emph{nn}} from exported names
-(@ref{1ec,,Windows Calling Conventions}
+(@ref{1cf,,Windows Calling Conventions}
for a discussion about @code{Stdcall}-style symbols.
@end table
@end table
@node GNAT and Windows Resources,Using GNAT DLLs from Microsoft Visual Studio Applications,Creating a Spec for Ada DLLs,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{214}@anchor{gnat_ugn/platform_specific_information id32}@anchor{215}
+@anchor{gnat_ugn/platform_specific_information gnat-and-windows-resources}@anchor{1f7}@anchor{gnat_ugn/platform_specific_information id32}@anchor{1f8}
@subsubsection GNAT and Windows Resources
@end menu
@node Building Resources,Compiling Resources,,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{216}@anchor{gnat_ugn/platform_specific_information id33}@anchor{217}
+@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information id33}@anchor{1fa}
@subsubsection Building Resources
Microsoft documentation.
@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{218}@anchor{gnat_ugn/platform_specific_information id34}@anchor{219}
+@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information id34}@anchor{1fc}
@subsubsection Compiling Resources
@end quotation
@node Using Resources,,Compiling Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{21a}@anchor{gnat_ugn/platform_specific_information id35}@anchor{21b}
+@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{1fd}@anchor{gnat_ugn/platform_specific_information id35}@anchor{1fe}
@subsubsection Using Resources
@end quotation
@node Using GNAT DLLs from Microsoft Visual Studio Applications,Debugging a DLL,GNAT and Windows Resources,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{21c}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{21d}
+@anchor{gnat_ugn/platform_specific_information using-gnat-dll-from-msvs}@anchor{1ff}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{200}
@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications
@item
Produce a .def file for the symbols you need to interface with, either by
hand or automatically with possibly some manual adjustments
-(see @ref{1fe,,Creating Definition File Automatically}):
+(see @ref{1e1,,Creating Definition File Automatically}):
@end enumerate
@quotation
Make sure that MSVS command-line tools are accessible on the path.
@item
-Create the Microsoft-style import library (see @ref{201,,MSVS-Style Import Library}):
+Create the Microsoft-style import library (see @ref{1e4,,MSVS-Style Import Library}):
@end enumerate
@quotation
@end enumerate
@node Debugging a DLL,Setting Stack Size from gnatlink,Using GNAT DLLs from Microsoft Visual Studio Applications,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information id36}@anchor{21e}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{21f}
+@anchor{gnat_ugn/platform_specific_information id36}@anchor{201}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{202}
@subsubsection Debugging a DLL
@end menu
@node Program and DLL Both Built with GCC/GNAT,Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Debugging a DLL
-@anchor{gnat_ugn/platform_specific_information id37}@anchor{220}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{221}
+@anchor{gnat_ugn/platform_specific_information id37}@anchor{203}@anchor{gnat_ugn/platform_specific_information program-and-dll-both-built-with-gcc-gnat}@anchor{204}
@subsubsection Program and DLL Both Built with GCC/GNAT
@code{ada_main} and that in the DLL there is an entry point named
@code{ada_dll}.
-The DLL (@ref{1f7,,Introduction to Dynamic Link Libraries (DLLs)}) and
+The DLL (@ref{1da,,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:
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{24,,Running and Debugging Ada Programs}).
+(@ref{14d,,Running and Debugging Ada Programs}).
@node Program Built with Foreign Tools and DLL Built with GCC/GNAT,,Program and DLL Both Built with GCC/GNAT,Debugging a DLL
-@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{222}@anchor{gnat_ugn/platform_specific_information id38}@anchor{223}
+@anchor{gnat_ugn/platform_specific_information program-built-with-foreign-tools-and-dll-built-with-gcc-gnat}@anchor{205}@anchor{gnat_ugn/platform_specific_information id38}@anchor{206}
@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT
DLL named @code{test.dll} containing an Ada entry point named
@code{ada_dll}.
-The DLL (see @ref{1f7,,Introduction to Dynamic Link Libraries (DLLs)}) must have
+The DLL (see @ref{1da,,Introduction to Dynamic Link Libraries (DLLs)}) must have
been built with debugging information (see the GNAT @code{-g} option).
@subsubheading Debugging the DLL Directly
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{24,,Running and Debugging Ada Programs}).
+as described in (@ref{14d,,Running and Debugging Ada Programs}).
@end itemize
It is also possible to debug the DLL by attaching to a running process.
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{24,,Running and Debugging Ada Programs}.
+@ref{14d,,Running and Debugging Ada Programs}.
@node Setting Stack Size from gnatlink,Setting Heap Size from gnatlink,Debugging a DLL,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{136}@anchor{gnat_ugn/platform_specific_information id39}@anchor{224}
+@anchor{gnat_ugn/platform_specific_information setting-stack-size-from-gnatlink}@anchor{127}@anchor{gnat_ugn/platform_specific_information id39}@anchor{207}
@subsubsection Setting Stack Size from @code{gnatlink}
@end itemize
@node Setting Heap Size from gnatlink,,Setting Stack Size from gnatlink,Mixed-Language Programming on Windows
-@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{137}@anchor{gnat_ugn/platform_specific_information id40}@anchor{225}
+@anchor{gnat_ugn/platform_specific_information setting-heap-size-from-gnatlink}@anchor{128}@anchor{gnat_ugn/platform_specific_information id40}@anchor{208}
@subsubsection Setting Heap Size from @code{gnatlink}
@end itemize
@node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{226}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{227}
+@anchor{gnat_ugn/platform_specific_information windows-specific-add-ons}@anchor{209}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{20a}
@subsection Windows Specific Add-Ons
@end menu
@node Win32Ada,wPOSIX,,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{228}@anchor{gnat_ugn/platform_specific_information id41}@anchor{229}
+@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{20b}@anchor{gnat_ugn/platform_specific_information id41}@anchor{20c}
@subsubsection Win32Ada
@end quotation
@node wPOSIX,,Win32Ada,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information id42}@anchor{22a}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{22b}
+@anchor{gnat_ugn/platform_specific_information id42}@anchor{20d}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{20e}
@subsubsection wPOSIX
@end quotation
@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{2d}@anchor{gnat_ugn/platform_specific_information id43}@anchor{22c}
+@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{20f}@anchor{gnat_ugn/platform_specific_information id43}@anchor{210}
@section Mac OS Topics
@end menu
@node Codesigning the Debugger,,,Mac OS Topics
-@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{22d}
+@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{211}
@subsection Codesigning the Debugger
in the Unix group @code{_developer}.
@node Example of Binder Output File,Elaboration Order Handling in GNAT,Platform-Specific Information,Top
-@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{22e}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{22f}
+@anchor{gnat_ugn/example_of_binder_output example-of-binder-output-file}@anchor{e}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{212}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{213}
@chapter Example of Binder Output File
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
@node Elaboration Order Handling in GNAT,Inline Assembler,Example of Binder Output File,Top
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{230}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{231}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order-handling-in-gnat}@anchor{f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{214}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{215}
@chapter Elaboration Order Handling in GNAT
* Checking the Elaboration Order::
* Controlling the Elaboration Order in Ada::
* Controlling the Elaboration Order in GNAT::
-* Common Elaboration-model Traits::
-* Dynamic Elaboration Model in GNAT::
-* Static Elaboration Model in GNAT::
-* SPARK Elaboration Model in GNAT::
-* Legacy Elaboration Model in GNAT::
* Mixing Elaboration Models::
+* ABE Diagnostics::
+* SPARK Diagnostics::
* Elaboration Circularities::
* Resolving Elaboration Circularities::
-* Resolving Task Issues::
* Elaboration-related Compiler Switches::
* Summary of Procedures for Elaboration Control::
* Inspecting the Chosen Elaboration Order::
@end menu
@node Elaboration Code,Elaboration Order,,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{232}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{233}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{216}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{217}
@section Elaboration Code
@itemize *
+@item
+@emph{Invocation}
+
+The act of calling a subprogram, instantiating a generic, or activating a
+task.
+
@item
@emph{Scenario}
-A construct that is elaborated or executed by elaboration code is referred to
+A construct that is elaborated or invoked by elaboration code is referred to
as an @emph{elaboration scenario} or simply a @strong{scenario}. GNAT recognizes the
following scenarios:
In the example above, the call to @code{Server.Func} is an elaboration scenario
because it appears at the library level of package @code{Client}. Note that the
declaration of package @code{Nested} is ignored according to the definition
-given above. As a result, the call to @code{Server.Func} will be executed when
+given above. As a result, the call to @code{Server.Func} will be invoked when
the spec of unit @code{Client} is elaborated.
@item
In the example above, the call to @code{Proc} is an elaboration scenario because
it appears within the statement sequence of package body @code{Client}. As a
-result, the call to @code{Proc} will be executed when the body of @code{Client} is
+result, the call to @code{Proc} will be invoked when the body of @code{Client} is
elaborated.
@end itemize
@node Elaboration Order,Checking the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order}@anchor{234}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{235}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-order}@anchor{218}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{219}
@section Elaboration Order
Within a single unit, elaboration code is executed in sequential order.
+@quotation
+
@example
package body Client is
Result : ... := Server.Func;
Proc;
end Client;
@end example
+@end quotation
In the example above, the elaboration order within package body @code{Client} is
as follows:
@item
@emph{with}ed units
+@item
+parent units
+
@item
purity of units
preelaborability of units
@item
-presence of elaboration control pragmas
+presence of elaboration-control pragmas
+
+@item
+invocations performed in elaboration code
@end itemize
A program may have several elaboration orders depending on its structure.
+@quotation
+
@example
package Server is
function Func (Index : Integer) return Integer;
with Client;
procedure Main is begin null; end Main;
@end example
+@end quotation
The following elaboration order exhibits a fundamental problem referred to as
@emph{access-before-elaboration} or simply @strong{ABE}.
+@quotation
+
@example
spec of Server
spec of Client
body of Server
body of Main
@end example
+@end quotation
The elaboration of @code{Server}'s spec materializes function @code{Func}, making it
callable. The elaboration of @code{Client}'s spec elaborates the declaration of
The following elaboration order avoids the ABE problem and the program can be
successfully elaborated.
+@quotation
+
@example
spec of Server
body of Server
spec of Client
body of Main
@end example
+@end quotation
Ada states that a total elaboration order must exist, but it does not define
what this order is. A compiler is thus tasked with choosing a suitable
elaboration order which satisfies the dependencies imposed by @emph{with} clauses,
-unit categorization, and elaboration control pragmas. Ideally an order which
-avoids ABE problems should be chosen, however a compiler may not always find
-such an order due to complications with respect to control and data flow.
+unit categorization, elaboration-control pragmas, and invocations performed in
+elaboration code. Ideally an order that avoids ABE problems should be chosen,
+however a compiler may not always find such an order due to complications with
+respect to control and data flow.
@node Checking the Elaboration Order,Controlling the Elaboration Order in Ada,Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{236}@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{237}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{21a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{21b}
@section Checking the Elaboration Order
-To avoid placing the entire elaboration order burden on the programmer, Ada
+To avoid placing the entire elaboration-order burden on the programmer, Ada
provides three lines of defense:
@emph{Dynamic semantics}
Dynamic checks are performed at run time, to ensure that a target is
-elaborated prior to a scenario that executes it, thus avoiding ABE problems.
+elaborated prior to a scenario that invokes it, thus avoiding ABE problems.
A failed run-time check raises exception @code{Program_Error}. The following
restrictions apply:
The restrictions above can be summarized by the following rule:
@emph{If a target has a body, then this body must be elaborated prior to the
-execution of the scenario that invokes, instantiates, or activates the
-target.}
+scenario that invokes the target.}
@item
@emph{Elaboration control}
@end itemize
@node Controlling the Elaboration Order in Ada,Controlling the Elaboration Order in GNAT,Checking the Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-ada}@anchor{238}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{239}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-ada}@anchor{21c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{21d}
@section Controlling the Elaboration Order in Ada
Pragma @code{Elaborate_Body} requires that the body of a unit is elaborated
immediately after its spec. This restriction guarantees that no client
-scenario can execute a server target before the target body has been
+scenario can invoke a server target before the target body has been
elaborated because the spec and body are effectively "glued" together.
@example
be elaborated prior to @code{Client}.
Removing pragma @code{Elaborate_All} could result in the following incorrect
-elaboration order
+elaboration order:
@example
spec of Math
is that the program continues to stay in the last state (one or more correct
orders exist) even if maintenance changes the bodies of targets.
-@node Controlling the Elaboration Order in GNAT,Common Elaboration-model Traits,Controlling the Elaboration Order in Ada,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{23a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-gnat}@anchor{23b}
+@node Controlling the Elaboration Order in GNAT,Mixing Elaboration Models,Controlling the Elaboration Order in Ada,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{21e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order-in-gnat}@anchor{21f}
@section Controlling the Elaboration Order in GNAT
@item
@emph{Dynamic elaboration model}
-This is the most permissive of the three elaboration models. When the
-dynamic model is in effect, GNAT assumes that all code within all units in
-a partition is elaboration code. GNAT performs very few diagnostics and
-generates run-time checks to verify the elaboration order of a program. This
-behavior is identical to that specified by the Ada Reference Manual. The
-dynamic model is enabled with compiler switch @code{-gnatE}.
-@end itemize
-
-@geindex Static elaboration model
+This is the most permissive of the three elaboration models and emulates the
+behavior specified by the Ada Reference Manual. When the dynamic model is in
+effect, GNAT makes the following assumptions:
-@itemize *
+@itemize -
@item
-@emph{Static elaboration model}
+All code within all units in a partition is considered to be elaboration
+code.
-This is the middle ground of the three models. When the static model is in
-effect, GNAT performs extensive diagnostics on a unit-by-unit basis for all
-scenarios that elaborate or execute internal targets. GNAT also generates
-run-time checks for all external targets and for all scenarios that may
-exhibit ABE problems. Finally, GNAT installs implicit @code{Elaborate} and
-@code{Elaborate_All} pragmas for server units based on the dependencies of
-client units. The static model is the default model in GNAT.
+@item
+Some of the invocations in elaboration code may not take place at run time
+due to conditional execution.
@end itemize
-@geindex SPARK elaboration model
-
-
-@itemize *
+GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
+that invoke internal targets. In addition, GNAT generates run-time checks for
+all external targets and for all scenarios that may exhibit ABE problems.
-@item
-@emph{SPARK elaboration model}
+The elaboration order is obtained by honoring all @emph{with} clauses, purity and
+preelaborability of units, and elaboration-control pragmas. The dynamic model
+attempts to take all invocations in elaboration code into account. If an
+invocation leads to a circularity, GNAT ignores the invocation based on the
+assumptions stated above. An order obtained using the dynamic model may fail
+an ABE check at run time when GNAT ignored an invocation.
-This is the most conservative of the three models and enforces the SPARK
-rules of elaboration as defined in the SPARK Reference Manual, section 7.7.
-The SPARK model is in effect only when a scenario and a target reside in a
-region subject to SPARK_Mode On, otherwise the dynamic or static model is in
-effect.
+The dynamic model is enabled with compiler switch @code{-gnatE}.
@end itemize
-@geindex Legacy elaboration model
+@geindex Static elaboration model
@itemize *
@item
-@emph{Legacy elaboration model}
-
-In addition to the three elaboration models outlined above, GNAT provides the
-elaboration model of pre-18.x versions referred to as @cite{legacy elaboration model}. The legacy elaboration model is enabled with compiler switch
-@code{-gnatH}.
-@end itemize
-
-@geindex Relaxed elaboration mode
-
-The dynamic, legacy, and static models can be relaxed using compiler switch
-@code{-gnatJ}, making them more permissive. Note that in this mode, GNAT
-may not diagnose certain elaboration issues or install run-time checks.
-
-@node Common Elaboration-model Traits,Dynamic Elaboration Model in GNAT,Controlling the Elaboration Order in GNAT,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat common-elaboration-model-traits}@anchor{23c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{23d}
-@section Common Elaboration-model Traits
-
+@emph{Static elaboration model}
-All three GNAT models are able to detect elaboration problems related to
-dispatching calls and a particular kind of ABE referred to as @emph{guaranteed ABE}.
+This is the middle ground of the three models. When the static model is in
+effect, GNAT makes the following assumptions:
-@itemize *
+@itemize -
@item
-@emph{Dispatching calls}
-
-GNAT installs run-time checks for each primitive subprogram of each tagged
-type defined in a partition on the assumption that a dispatching call
-invoked at elaboration time will execute one of these primitives. As a
-result, a dispatching call that executes a primitive whose body has not
-been elaborated yet will raise exception @code{Program_Error} at run time. The
-checks can be suppressed using pragma @code{Suppress (Elaboration_Check)}.
+Only code at the library level and in package body statements within all
+units in a partition is considered to be elaboration code.
@item
-@emph{Guaranteed ABE}
-
-A guaranteed ABE arises when the body of a target is not elaborated early
-enough, and causes all scenarios that directly execute the target to fail.
-
-@example
-package body Guaranteed_ABE is
- function ABE return Integer;
-
- Val : constant Integer := ABE;
-
- function ABE return Integer is
- begin
- ...
- end ABE;
-end Guaranteed_ABE;
-@end example
-
-In the example above, the elaboration of @code{Guaranteed_ABE}'s body elaborates
-the declaration of @code{Val}. This invokes function @code{ABE}, however the body
-of @code{ABE} has not been elaborated yet. GNAT emits similar diagnostics in all
-three models:
-
-@example
-1. package body Guaranteed_ABE is
-2. function ABE return Integer;
-3.
-4. Val : constant Integer := ABE;
- |
- >>> warning: cannot call "ABE" before body seen
- >>> warning: Program_Error will be raised at run time
-
-5.
-6. function ABE return Integer is
-7. begin
-8. ...
-9. end ABE;
-10. end Guaranteed_ABE;
-@end example
+All invocations in elaboration will take place at run time, regardless of
+conditional execution.
@end itemize
-Note that GNAT emits warnings rather than hard errors whenever it encounters an
-elaboration problem. This is because the elaboration model in effect may be too
-conservative, or a particular scenario may not be elaborated or executed due to
-data and control flow. The warnings can be suppressed selectively with @code{pragma
-Warnigns (Off)} or globally with compiler switch @code{-gnatwL}.
-
-@node Dynamic Elaboration Model in GNAT,Static Elaboration Model in GNAT,Common Elaboration-model Traits,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat dynamic-elaboration-model-in-gnat}@anchor{23e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{23f}
-@section Dynamic Elaboration Model in GNAT
-
-
-The dynamic model assumes that all code within all units in a partition is
-elaboration code. As a result, run-time checks are installed for each scenario
-regardless of whether the target is internal or external. The checks can be
-suppressed using pragma @code{Suppress (Elaboration_Check)}. This behavior is
-identical to that specified by the Ada Reference Manual. The following example
-showcases run-time checks installed by GNAT to verify the elaboration state of
-package @code{Dynamic_Model}.
-
-@example
-with Server;
-package body Dynamic_Model is
- procedure API is
- begin
- ...
- end API;
+GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
+that invoke internal targets. In addition, GNAT generates run-time checks for
+all external targets and for all scenarios that may exhibit ABE problems.
- <check that the body of Server.Gen is elaborated>
- package Inst is new Server.Gen;
+The elaboration order is obtained by honoring all @emph{with} clauses, purity and
+preelaborability of units, presence of elaboration-control pragmas, and all
+invocations in elaboration code. An order obtained using the static model is
+guaranteed to be ABE problem-free, excluding dispatching calls and
+access-to-subprogram types.
- T : Server.Task_Type;
+The static model is the default model in GNAT.
+@end itemize
-begin
- <check that the body of Server.Task_Type is elaborated>
+@geindex SPARK elaboration model
- <check that the body of Server.Proc is elaborated>
- Server.Proc;
-end Dynamic_Model;
-@end example
-The checks verify that the body of a target has been successfully elaborated
-before a scenario activates, calls, or instantiates a target.
+@itemize *
-Note that no scenario within package @code{Dynamic_Model} calls procedure @code{API}.
-In fact, procedure @code{API} may not be invoked by elaboration code within the
-partition, however the dynamic model assumes that this can happen.
+@item
+@emph{SPARK elaboration model}
-The dynamic model emits very few diagnostics, but can make suggestions on
-missing @code{Elaborate} and @code{Elaborate_All} pragmas for library-level
-scenarios. This information is available when compiler switch @code{-gnatel}
+This is the most conservative of the three models and enforces the SPARK
+rules of elaboration as defined in the SPARK Reference Manual, section 7.7.
+The SPARK model is in effect only when a scenario and a target reside in a
+region subject to @code{SPARK_Mode On}, otherwise the dynamic or static model
is in effect.
-@example
-1. with Server;
-2. package body Dynamic_Model is
-3. Val : constant Integer := Server.Func;
- |
- >>> info: call to "Func" during elaboration
- >>> info: missing pragma "Elaborate_All" for unit "Server"
-
-4. end Dynamic_Model;
-@end example
-
-@node Static Elaboration Model in GNAT,SPARK Elaboration Model in GNAT,Dynamic Elaboration Model in GNAT,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat static-elaboration-model-in-gnat}@anchor{240}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{241}
-@section Static Elaboration Model in GNAT
-
+The SPARK model is enabled with compiler switch @code{-gnatd.v}.
+@end itemize
-In contrast to the dynamic model, the static model is more precise in its
-analysis of elaboration code. The model makes a clear distinction between
-internal and external targets, and resorts to different diagnostics and
-run-time checks based on the nature of the target.
+@geindex Legacy elaboration models
@itemize *
@item
-@emph{Internal targets}
+@emph{Legacy elaboration models}
-The static model performs extensive diagnostics on scenarios which elaborate
-or execute internal targets. The warnings resulting from these diagnostics
-are enabled by default, but can be suppressed selectively with @code{pragma
-Warnings (Off)} or globally with compiler switch @code{-gnatwL}.
+In addition to the three elaboration models outlined above, GNAT provides the
+following legacy models:
-@example
- 1. package body Static_Model is
- 2. generic
- 3. with function Func return Integer;
- 4. package Gen is
- 5. Val : constant Integer := Func;
- 6. end Gen;
- 7.
- 8. function ABE return Integer;
- 9.
-10. function Cause_ABE return Boolean is
-11. package Inst is new Gen (ABE);
- |
- >>> warning: in instantiation at line 5
- >>> warning: cannot call "ABE" before body seen
- >>> warning: Program_Error may be raised at run time
- >>> warning: body of unit "Static_Model" elaborated
- >>> warning: function "Cause_ABE" called at line 16
- >>> warning: function "ABE" called at line 5, instance at line 11
-
-12. begin
-13. ...
-14. end Cause_ABE;
-15.
-16. Val : constant Boolean := Cause_ABE;
-17.
-18. function ABE return Integer is
-19. begin
-20. ...
-21. end ABE;
-22. end Static_Model;
-@end example
-The example above illustrates an ABE problem within package @code{Static_Model},
-which is hidden by several layers of indirection. The elaboration of package
-body @code{Static_Model} elaborates the declaration of @code{Val}. This invokes
-function @code{Cause_ABE}, which instantiates generic unit @code{Gen} as @code{Inst}.
-The elaboration of @code{Inst} invokes function @code{ABE}, however the body of
-@code{ABE} has not been elaborated yet.
+@itemize -
@item
-@emph{External targets}
-
-The static model installs run-time checks to verify the elaboration status
-of server targets only when the scenario that elaborates or executes that
-target is part of the elaboration code of the client unit. The checks can be
-suppressed using pragma @code{Suppress (Elaboration_Check)}.
-
-@example
-with Server;
-package body Static_Model is
- generic
- with function Func return Integer;
- package Gen is
- Val : constant Integer := Func;
- end Gen;
-
- function Call_Func return Boolean is
- <check that the body of Server.Func is elaborated>
- package Inst is new Gen (Server.Func);
- begin
- ...
- end Call_Func;
-
- Val : constant Boolean := Call_Func;
-end Static_Model;
-@end example
-
-In the example above, the elaboration of package body @code{Static_Model}
-elaborates the declaration of @code{Val}. This invokes function @code{Call_Func},
-which instantiates generic unit @code{Gen} as @code{Inst}. The elaboration of
-@code{Inst} invokes function @code{Server.Func}. Since @code{Server.Func} is an
-external target, GNAT installs a run-time check to verify that its body has
-been elaborated.
-
-In addition to checks, the static model installs implicit @code{Elaborate} and
-@code{Elaborate_All} pragmas to guarantee safe elaboration use of server units.
-This information is available when compiler switch @code{-gnatel} is in
-effect.
-
-@example
- 1. with Server;
- 2. package body Static_Model is
- 3. generic
- 4. with function Func return Integer;
- 5. package Gen is
- 6. Val : constant Integer := Func;
- 7. end Gen;
- 8.
- 9. function Call_Func return Boolean is
-10. package Inst is new Gen (Server.Func);
- |
- >>> info: instantiation of "Gen" during elaboration
- >>> info: in instantiation at line 6
- >>> info: call to "Func" during elaboration
- >>> info: in instantiation at line 6
- >>> info: implicit pragma "Elaborate_All" generated for unit "Server"
- >>> info: body of unit "Static_Model" elaborated
- >>> info: function "Call_Func" called at line 15
- >>> info: function "Func" called at line 6, instance at line 10
-
-11. begin
-12. ...
-13. end Call_Func;
-14.
-15. Val : constant Boolean := Call_Func;
- |
- >>> info: call to "Call_Func" during elaboration
-
-16. end Static_Model;
-@end example
+@cite{Legacy elaboration-checking model} available in pre-18.x versions of GNAT.
+This model is enabled with compiler switch @code{-gnatH}.
-In the example above, the elaboration of package body @code{Static_Model}
-elaborates the declaration of @code{Val}. This invokes function @code{Call_Func},
-which instantiates generic unit @code{Gen} as @code{Inst}. The elaboration of
-@code{Inst} invokes function @code{Server.Func}. Since @code{Server.Func} is an
-external target, GNAT installs an implicit @code{Elaborate_All} pragma for unit
-@code{Server}. The pragma guarantees that both the spec and body of @code{Server},
-along with any additional dependencies that @code{Server} may require, are
-elaborated prior to the body of @code{Static_Model}.
+@item
+@cite{Legacy elaboration-order model} available in pre-20.x versions of GNAT.
+This model is enabled with binder switch @code{-H}.
+@end itemize
@end itemize
-@node SPARK Elaboration Model in GNAT,Legacy Elaboration Model in GNAT,Static Elaboration Model in GNAT,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{242}@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-elaboration-model-in-gnat}@anchor{243}
-@section SPARK Elaboration Model in GNAT
-
-
-The SPARK model is identical to the static model in its handling of internal
-targets. The SPARK model, however, requires explicit @code{Elaborate} or
-@code{Elaborate_All} pragmas to be present in the program when a target is
-external, and compiler switch @code{-gnatd.v} is in effect.
-
-@example
-1. with Server;
-2. package body SPARK_Model with SPARK_Mode is
-3. Val : constant Integer := Server.Func;
- |
- >>> call to "Func" during elaboration in SPARK
- >>> unit "SPARK_Model" requires pragma "Elaborate_All" for "Server"
- >>> body of unit "SPARK_Model" elaborated
- >>> function "Func" called at line 3
-
-4. end SPARK_Model;
-@end example
-
-@node Legacy Elaboration Model in GNAT,Mixing Elaboration Models,SPARK Elaboration Model in GNAT,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat legacy-elaboration-model-in-gnat}@anchor{244}
-@section Legacy Elaboration Model in GNAT
-
+@geindex Relaxed elaboration mode
-The legacy elaboration model is provided for compatibility with code bases
-developed with pre-18.x versions of GNAT. It is similar in functionality to
-the dynamic and static models of post-18.x version of GNAT, but may differ
-in terms of diagnostics and run-time checks. The legacy elaboration model is
-enabled with compiler switch @code{-gnatH}.
+The dynamic, legacy, and static models can be relaxed using compiler switch
+@code{-gnatJ}, making them more permissive. Note that in this mode, GNAT
+may not diagnose certain elaboration issues or install run-time checks.
-@node Mixing Elaboration Models,Elaboration Circularities,Legacy Elaboration Model in GNAT,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{245}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{246}
+@node Mixing Elaboration Models,ABE Diagnostics,Controlling the Elaboration Order in GNAT,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{220}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{221}
@section Mixing Elaboration Models
The server unit is compiled with the dynamic model.
@item
-The server unit is a GNAT implementation unit from the Ada, GNAT,
-Interfaces, or System hierarchies.
+The server unit is a GNAT implementation unit from the @code{Ada}, @code{GNAT},
+@code{Interfaces}, or @code{System} hierarchies.
@item
The server unit has pragma @code{Pure} or @code{Preelaborate}.
These rules ensure that elaboration checks are not omitted. If the rules are
violated, the binder emits a warning:
+@quotation
+
@example
warning: "x.ads" has dynamic elaboration checks and with's
warning: "y.ads" which has static elaboration checks
@end example
+@end quotation
The warnings can be suppressed by binder switch @code{-ws}.
-@node Elaboration Circularities,Resolving Elaboration Circularities,Mixing Elaboration Models,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{247}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{248}
-@section Elaboration Circularities
+@node ABE Diagnostics,SPARK Diagnostics,Mixing Elaboration Models,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat abe-diagnostics}@anchor{222}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{223}
+@section ABE Diagnostics
+
+
+GNAT performs extensive diagnostics on a unit-by-unit basis for all scenarios
+that invoke internal targets, regardless of whether the dynamic, SPARK, or
+static model is in effect.
+
+Note that GNAT emits warnings rather than hard errors whenever it encounters an
+elaboration problem. This is because the elaboration model in effect may be too
+conservative, or a particular scenario may not be invoked due conditional
+execution. The warnings can be suppressed selectively with @code{pragma Warnings
+(Off)} or globally with compiler switch @code{-gnatwL}.
+A @emph{guaranteed ABE} arises when the body of a target is not elaborated early
+enough, and causes @emph{all} scenarios that directly invoke the target to fail.
-If the binder cannot find an acceptable elaboration order, it outputs detailed
-diagnostics describing an @strong{elaboration circularity}.
+@quotation
@example
-package Server is
- function Func return Integer;
-end Server;
+package body Guaranteed_ABE is
+ function ABE return Integer;
+
+ Val : constant Integer := ABE;
+
+ function ABE return Integer is
+ begin
+ ...
+ end ABE;
+end Guaranteed_ABE;
@end example
+@end quotation
+
+In the example above, the elaboration of @code{Guaranteed_ABE}'s body elaborates
+the declaration of @code{Val}. This invokes function @code{ABE}, however the body of
+@code{ABE} has not been elaborated yet. GNAT emits the following diagnostic:
+
+@quotation
@example
-with Client;
-package body Server is
- function Func return Integer is
- begin
- ...
- end Func;
-end Server;
+4. Val : constant Integer := ABE;
+ |
+ >>> warning: cannot call "ABE" before body seen
+ >>> warning: Program_Error will be raised at run time
@end example
+@end quotation
+
+A @emph{conditional ABE} arises when the body of a target is not elaborated early
+enough, and causes @emph{some} scenarios that directly invoke the target to fail.
+
+@quotation
@example
-with Server;
-package Client is
- Val : constant Integer := Server.Func;
-end Client;
+ 1. package body Conditional_ABE is
+ 2. procedure Force_Body is null;
+ 3.
+ 4. generic
+ 5. with function Func return Integer;
+ 6. package Gen is
+ 7. Val : constant Integer := Func;
+ 8. end Gen;
+ 9.
+10. function ABE return Integer;
+11.
+12. function Cause_ABE return Boolean is
+13. package Inst is new Gen (ABE);
+14. begin
+15. ...
+16. end Cause_ABE;
+17.
+18. Val : constant Boolean := Cause_ABE;
+19.
+20. function ABE return Integer is
+21. begin
+22. ...
+23. end ABE;
+24.
+25. Safe : constant Boolean := Cause_ABE;
+26. end Conditional_ABE;
@end example
+@end quotation
+
+In the example above, the elaboration of package body @code{Conditional_ABE}
+elaborates the declaration of @code{Val}. This invokes function @code{Cause_ABE},
+which instantiates generic unit @code{Gen} as @code{Inst}. The elaboration of
+@code{Inst} invokes function @code{ABE}, however the body of @code{ABE} has not been
+elaborated yet. GNAT emits the following diagnostic:
+
+@quotation
@example
-with Client;
-procedure Main is begin null; end Main;
+13. package Inst is new Gen (ABE);
+ |
+ >>> warning: in instantiation at line 7
+ >>> warning: cannot call "ABE" before body seen
+ >>> warning: Program_Error may be raised at run time
+ >>> warning: body of unit "Conditional_ABE" elaborated
+ >>> warning: function "Cause_ABE" called at line 18
+ >>> warning: function "ABE" called at line 7, instance at line 13
@end example
+@end quotation
+
+Note that the same ABE problem does not occur with the elaboration of
+declaration @code{Safe} because the body of function @code{ABE} has already been
+elaborated at that point.
+
+@node SPARK Diagnostics,Elaboration Circularities,ABE Diagnostics,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat spark-diagnostics}@anchor{224}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{225}
+@section SPARK Diagnostics
+
+
+GNAT enforces the SPARK rules of elaboration as defined in the SPARK Reference
+Manual section 7.7 when compiler switch @code{-gnatd.v} is in effect. Note
+that GNAT emits hard errors whenever it encounters a violation of the SPARK
+rules.
+
+@quotation
@example
-error: elaboration circularity detected
-info: "server (body)" must be elaborated before "client (spec)"
-info: reason: implicit Elaborate_All in unit "client (spec)"
-info: recompile "client (spec)" with -gnatel for full details
-info: "server (body)"
-info: must be elaborated along with its spec:
-info: "server (spec)"
-info: which is withed by:
-info: "client (spec)"
-info: "client (spec)" must be elaborated before "server (body)"
-info: reason: with clause
+1. with Server;
+2. package body SPARK_Diagnostics with SPARK_Mode is
+3. Val : constant Integer := Server.Func;
+ |
+ >>> call to "Func" during elaboration in SPARK
+ >>> unit "SPARK_Diagnostics" requires pragma "Elaborate_All" for "Server"
+ >>> body of unit "SPARK_Model" elaborated
+ >>> function "Func" called at line 3
+
+4. end SPARK_Diagnostics;
@end example
+@end quotation
-In the example above, @code{Client} must be elaborated prior to @code{Main} by virtue
-of a @emph{with} clause. The elaboration of @code{Client} invokes @code{Server.Func}, and
-static model generates an implicit @code{Elaborate_All} pragma for @code{Server}. The
-pragma implies that both the spec and body of @code{Server}, along with any units
-they @emph{with}, must be elaborated prior to @code{Client}. However, @code{Server}'s body
-@emph{with}s @code{Client}, implying that @code{Client} must be elaborated prior to
-@code{Server}. The end result is that @code{Client} must be elaborated prior to
-@code{Client}, and this leads to a circularity.
+@node Elaboration Circularities,Resolving Elaboration Circularities,SPARK Diagnostics,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{226}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-circularities}@anchor{227}
+@section Elaboration Circularities
-@node Resolving Elaboration Circularities,Resolving Task Issues,Elaboration Circularities,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{249}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{24a}
-@section Resolving Elaboration Circularities
+An @strong{elaboration circularity} occurs whenever the elaboration of a set of
+units enters a deadlocked state, where each unit is waiting for another unit
+to be elaborated. This situation may be the result of improper use of @emph{with}
+clauses, elaboration-control pragmas, or invocations in elaboration code.
-When faced with an elaboration circularity, a programmer has several options
-available.
+The following example exhibits an elaboration circularity.
+@quotation
-@itemize *
+@example
+with B; pragma Elaborate (B);
+package A is
+end A;
+@end example
-@item
-@emph{Fix the program}
+@example
+package B is
+ procedure Force_Body;
+end B;
+@end example
-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
-invoked 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.
+@example
+with C;
+package body B is
+ procedure Force_Body is null;
-@item
-@emph{Switch to more permissive elaboration model}
+ Elab : constant Integer := C.Func;
+end B;
+@end example
-If the compilation was performed using the static model, enable the dynamic
-model with compiler switch @code{-gnatE}. GNAT will no longer generate
-implicit @code{Elaborate} and @code{Elaborate_All} pragmas, resulting in a behavior
-identical to that specified by the Ada Reference Manual. The binder will
-generate an executable program that may or may not raise @code{Program_Error},
-and it is the programmer's responsibility to ensure that it does not raise
-@code{Program_Error}.
+@example
+package C is
+ function Func return Integer;
+end C;
+@end example
+
+@example
+with A;
+package body C is
+ function Func return Integer is
+ begin
+ ...
+ end Func;
+end C;
+@end example
+@end quotation
-If the compilation was performed using a post-18.x version of GNAT, consider
-using the legacy elaboration model, in the following order:
+The binder emits the following diagnostic:
+@quotation
-@itemize -
+@example
+error: Elaboration circularity detected
+info:
+info: Reason:
+info:
+info: unit "a (spec)" depends on its own elaboration
+info:
+info: Circularity:
+info:
+info: unit "a (spec)" has with clause and pragma Elaborate for unit "b (spec)"
+info: unit "b (body)" is in the closure of pragma Elaborate
+info: unit "b (body)" invokes a construct of unit "c (body)" at elaboration time
+info: unit "c (body)" has with clause for unit "a (spec)"
+info:
+info: Suggestions:
+info:
+info: remove pragma Elaborate for unit "b (body)" in unit "a (spec)"
+info: use the dynamic elaboration model (compiler switch -gnatE)
+@end example
+@end quotation
-@item
-Use the legacy static elaboration model, with compiler switch
-@code{-gnatH}.
+The diagnostic consist of the following sections:
+
+
+@itemize *
@item
-Use the legacy dynamic elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatE}.
+Reason
+
+This section provides a short explanation describing why the set of units
+could not be ordered.
@item
-Use the relaxed legacy static elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ}.
+Circularity
+
+This section enumerates the units comprising the deadlocked set, along with
+their interdependencies.
@item
-Use the relaxed legacy dynamic elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ} @code{-gnatE}.
+Suggestions
+
+This section enumerates various tactics for eliminating the circularity.
@end itemize
-@item
-@emph{Suppress all elaboration checks}
+@node Resolving Elaboration Circularities,Elaboration-related Compiler Switches,Elaboration Circularities,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{228}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-elaboration-circularities}@anchor{229}
+@section Resolving Elaboration Circularities
-The drawback of run-time checks is that they generate overhead at run time,
-both in space and time. If the programmer is absolutely sure that a program
-will not raise an elaboration-related @code{Program_Error}, then using the
-pragma @code{Suppress (Elaboration_Check)} globally (as a configuration pragma)
-will eliminate all run-time checks.
-@item
-@emph{Suppress elaboration checks selectively}
+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 invoked
+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.
-If a scenario cannot possibly lead to an elaboration @code{Program_Error},
-and the binder nevertheless complains about implicit @code{Elaborate} and
-@code{Elaborate_All} pragmas that lead to elaboration circularities, it
-is possible to suppress the generation of implicit @code{Elaborate} and
-@code{Elaborate_All} pragmas, as well as run-time checks. Clearly this can
-be unsafe, and it is the responsibility of the programmer to make sure
-that the resulting program has no elaboration anomalies. Pragma
-@code{Suppress (Elaboration_Check)} can be used with different levels of
-granularity to achieve these effects.
+When faced with an elaboration circularity, the programmer should also consider
+the tactics given in the suggestions section of the circularity diagnostic.
+Depending on the units involved in the circularity, their @emph{with} clauses,
+purity, preelaborability, presence of elaboration-control pragmas and
+invocations at elaboration time, the binder may suggest one or more of the
+following tactics to eliminate the circularity:
-@itemize -
+@itemize *
@item
-@emph{Target suppression}
-
-When the pragma is placed in a declarative part, without a second argument
-naming an entity, it will suppress implicit @code{Elaborate} and
-@code{Elaborate_All} pragma generation, as well as run-time checks, on all
-targets within the region.
+Pragma Elaborate elimination
@example
-package Range_Suppress is
- pragma Suppress (Elaboration_Check);
+remove pragma Elaborate for unit "..." in unit "..."
+@end example
- function Func return Integer;
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate}:
- generic
- procedure Gen;
- pragma Unsuppress (Elaboration_Check);
+@itemize -
- task type Tsk;
-end Range_Suppress;
-@end example
+@item
+Prevents a set of units from being elaborated.
-In the example above, a pair of Suppress/Unsuppress pragmas define a region
-of suppression within package @code{Range_Suppress}. As a result, no implicit
-@code{Elaborate} and @code{Elaborate_All} pragmas, nor any run-time checks, will
-be generated by callers of @code{Func} and instantiators of @code{Gen}. Note that
-task type @code{Tsk} is not within this region.
+@item
+The removal of the pragma will not eliminate the semantic effects of the
+pragma. In other words, the argument of the pragma will still be elaborated
+prior to the unit containing the pragma.
-An alternative to the region-based suppression is to use multiple
-@code{Suppress} pragmas with arguments naming specific entities for which
-elaboration checks should be suppressed:
+@item
+The removal of the pragma will enable the successful ordering of the units.
+@end itemize
-@example
-package Range_Suppress is
- function Func return Integer;
- pragma Suppress (Elaboration_Check, Func);
+The programmer should remove the pragma as advised, and rebuild the program.
- generic
- procedure Gen;
- pragma Suppress (Elaboration_Check, Gen);
+@item
+Pragma Elaborate_All elimination
- task type Tsk;
-end Range_Suppress;
+@example
+remove pragma Elaborate_All for unit "..." in unit "..."
@end example
-@item
-@emph{Scenario suppression}
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate_All}:
-When the pragma @code{Suppress} is placed in a declarative or statement
-part, without an entity argument, it will suppress implicit @code{Elaborate}
-and @code{Elaborate_All} pragma generation, as well as run-time checks, on
-all scenarios within the region.
-@example
-with Server;
-package body Range_Suppress is
- pragma Suppress (Elaboration_Check);
+@itemize -
- function Func return Integer is
- begin
- return Server.Func;
- end Func;
+@item
+Prevents a set of units from being elaborated.
- procedure Gen is
- begin
- Server.Proc;
- end Gen;
+@item
+The removal of the pragma will not eliminate the semantic effects of the
+pragma. In other words, the argument of the pragma along with its @emph{with}
+closure will still be elaborated prior to the unit containing the pragma.
- pragma Unsuppress (Elaboration_Check);
+@item
+The removal of the pragma will enable the successful ordering of the units.
+@end itemize
- task body Tsk is
- begin
- Server.Proc;
- end Tsk;
-end Range_Suppress;
+The programmer should remove the pragma as advised, and rebuild the program.
+
+@item
+Pragma Elaborate_All downgrade
+
+@example
+change pragma Elaborate_All for unit "..." to Elaborate in unit "..."
@end example
-In the example above, a pair of Suppress/Unsuppress pragmas define a region
-of suppression within package body @code{Range_Suppress}. As a result, the
-calls to @code{Server.Func} in @code{Func} and @code{Server.Proc} in @code{Gen} will
-not generate any implicit @code{Elaborate} and @code{Elaborate_All} pragmas or
-run-time checks.
-@end itemize
-@end itemize
+This tactic is always suggested with the pragma @code{Elaborate_All} elimination
+tactic. It offers a different alernative of guaranteeing that the argument of
+the pragma will still be elaborated prior to the unit containing the pragma.
-@node Resolving Task Issues,Elaboration-related Compiler Switches,Resolving Elaboration Circularities,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{24b}@anchor{gnat_ugn/elaboration_order_handling_in_gnat resolving-task-issues}@anchor{24c}
-@section Resolving Task Issues
+The programmer should update the pragma as advised, and rebuild the program.
+@item
+Pragma Elaborate_Body elimination
-The model of execution in Ada dictates that elaboration must first take place,
-and only then can the main program be started. Tasks which are activated during
-elaboration violate this model and may lead to serious concurrent problems at
-elaboration time.
+@example
+remove pragma Elaborate_Body in unit "..."
+@end example
-A task can be activated in two different ways:
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate_Body}:
-@itemize *
+@itemize -
@item
-The task is created by an allocator in which case it is activated immediately
-after the allocator is evaluated.
+Prevents a set of units from being elaborated.
@item
-The task is declared at the library level or within some nested master in
-which case it is activated before starting execution of the statement
-sequence of the master defining the task.
+The removal of the pragma will enable the successful ordering of the units.
@end itemize
-Since the elaboration of a partition is performed by the environment task
-servicing that partition, any tasks activated during elaboration may be in
-a race with the environment task, and lead to unpredictable state and behavior.
-The static model seeks to avoid such interactions by assuming that all code in
-the task body is executed at elaboration time, if the task was activated by
-elaboration code.
+Note that the binder cannot determine whether the pragma is required for
+other purposes, such as guaranteeing the initialization of a variable
+declared in the spec by elaboration code in the body.
-@example
-package Decls is
- task Lib_Task is
- entry Start;
- end Lib_Task;
+The programmer should remove the pragma as advised, and rebuild the program.
- type My_Int is new Integer;
+@item
+Use of pragma Restrictions
- function Ident (M : My_Int) return My_Int;
-end Decls;
+@example
+use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code)
@end example
-@example
-with Utils;
-package body Decls is
- task body Lib_Task is
- begin
- accept Start;
- Utils.Put_Val (2);
- end Lib_Task;
+This tactic is suggested when the binder has determined that a task
+activation at elaboration time:
- function Ident (M : My_Int) return My_Int is
- begin
- return M;
- end Ident;
-end Decls;
-@end example
-@example
-with Decls;
-package Utils is
- procedure Put_Val (Arg : Decls.My_Int);
-end Utils;
-@end example
+@itemize -
-@example
-with Ada.Text_IO; use Ada.Text_IO;
-package body Utils is
- procedure Put_Val (Arg : Decls.My_Int) is
- begin
- Put_Line (Arg'Img);
- end Put_Val;
-end Utils;
-@end example
+@item
+Prevents a set of units from being elaborated.
+@end itemize
-@example
-with Decls;
-procedure Main is
-begin
- Decls.Lib_Task.Start;
-end Main;
-@end example
+Note that the binder cannot determine with certainty whether the task will
+block at elaboration time.
-When the above example is compiled with the static model, an elaboration
-circularity arises:
+The programmer should create a configuration file, place the pragma within,
+update the general compilation arguments, and rebuild the program.
+
+@item
+Use of dynamic elaboration model
@example
-error: elaboration circularity detected
-info: "decls (body)" must be elaborated before "decls (body)"
-info: reason: implicit Elaborate_All in unit "decls (body)"
-info: recompile "decls (body)" with -gnatel for full details
-info: "decls (body)"
-info: must be elaborated along with its spec:
-info: "decls (spec)"
-info: which is withed by:
-info: "utils (spec)"
-info: which is withed by:
-info: "decls (body)"
+use the dynamic elaboration model (compiler switch -gnatE)
@end example
-In the above example, @code{Decls} must be elaborated prior to @code{Main} by virtue
-of a with clause. The elaboration of @code{Decls} activates task @code{Lib_Task}. The
-static model conservatibely assumes that all code within the body of
-@code{Lib_Task} is executed, and generates an implicit @code{Elaborate_All} pragma
-for @code{Units} due to the call to @code{Utils.Put_Val}. The pragma implies that
-both the spec and body of @code{Utils}, along with any units they @emph{with},
-must be elaborated prior to @code{Decls}. However, @code{Utils}'s spec @emph{with}s
-@code{Decls}, implying that @code{Decls} must be elaborated before @code{Utils}. The end
-result is that @code{Utils} must be elaborated prior to @code{Utils}, and this
-leads to a circularity.
+This tactic is suggested when the binder has determined that an invocation at
+elaboration time:
-In reality, the example above will not exhibit an ABE problem at run time.
-When the body of task @code{Lib_Task} is activated, execution will wait for entry
-@code{Start} to be accepted, and the call to @code{Utils.Put_Val} will not take place
-at elaboration time. Task @code{Lib_Task} will resume its execution after the main
-program is executed because @code{Main} performs a rendezvous with
-@code{Lib_Task.Start}, and at that point all units have already been elaborated.
-As a result, the static model may seem overly conservative, partly because it
-does not take control and data flow into account.
-
-When faced with a task elaboration circularity, a programmer has several
-options available:
+@itemize -
-@itemize *
+@item
+Prevents a set of units from being elaborated.
@item
-@emph{Use the dynamic model}
+The use of the dynamic model will enable the successful ordering of the
+units.
+@end itemize
-The dynamic model does not generate implicit @code{Elaborate} and
-@code{Elaborate_All} pragmas. Instead, it will install checks prior to every
-call in the example above, thus verifying the successful elaboration of
-@code{Utils.Put_Val} in case the call to it takes place at elaboration time.
-The dynamic model is enabled with compiler switch @code{-gnatE}.
+The programmer has two options:
+
+
+@itemize -
@item
-@emph{Isolate the tasks}
+Determine the units involved in the invocation using the detailed
+invocation information, and add compiler switch @code{-gnatE} to the
+compilation arguments of selected files only. This approach will yield
+safer elaboration orders compared to the other option because it will
+minimize the opportunities presented to the dynamic model for ignoring
+invocations.
-Relocating tasks in their own separate package could decouple them from
-dependencies that would otherwise cause an elaboration circularity. The
-example above can be rewritten as follows:
+@item
+Add compiler switch @code{-gnatE} to the general compilation arguments.
+@end itemize
-@example
-package Decls1 is -- new
- task Lib_Task is
- entry Start;
- end Lib_Task;
-end Decls1;
-@end example
+@item
+Use of detailed invocation information
@example
-with Utils;
-package body Decls1 is -- new
- task body Lib_Task is
- begin
- accept Start;
- Utils.Put_Val (2);
- end Lib_Task;
-end Decls1;
+use detailed invocation information (compiler switch -gnatd_F)
@end example
-@example
-package Decls2 is -- new
- type My_Int is new Integer;
- function Ident (M : My_Int) return My_Int;
-end Decls2;
-@end example
+This tactic is always suggested with the use of the dynamic model tactic. It
+causes the circularity section of the circularity diagnostic to describe the
+flow of elaboration code from a unit to a unit, enumerating all such paths in
+the process.
-@example
-with Utils;
-package body Decls2 is -- new
- function Ident (M : My_Int) return My_Int is
- begin
- return M;
- end Ident;
-end Decls2;
-@end example
+The programmer should analyze this information to determine which units
+should be compiled with the dynamic model.
-@example
-with Decls2;
-package Utils is
- procedure Put_Val (Arg : Decls2.My_Int);
-end Utils;
-@end example
+@item
+Forced-dependency elimination
@example
-with Ada.Text_IO; use Ada.Text_IO;
-package body Utils is
- procedure Put_Val (Arg : Decls2.My_Int) is
- begin
- Put_Line (Arg'Img);
- end Put_Val;
-end Utils;
+remove the dependency of unit "..." on unit "..." from the argument of switch -f
@end example
-@example
-with Decls1;
-procedure Main is
-begin
- Decls1.Lib_Task.Start;
-end Main;
-@end example
+This tactic is suggested when the binder has determined that a dependency
+present in the forced-elaboration-order file indicated by binder switch
+@code{-f}:
+
+
+@itemize -
@item
-@emph{Declare the tasks}
+Prevents a set of units from being elaborated.
-The original example uses a single task declaration for @code{Lib_Task}. An
-explicit task type declaration and a properly placed task object could avoid
-the dependencies that would otherwise cause an elaboration circularity. The
-example can be rewritten as follows:
+@item
+The removal of the dependency will enable the successful ordering of the
+units.
+@end itemize
-@example
-package Decls is
- task type Lib_Task is -- new
- entry Start;
- end Lib_Task;
+The programmer should edit the forced-elaboration-order file, remove the
+dependency, and rebind the program.
- type My_Int is new Integer;
+@item
+All forced-dependency elimination
- function Ident (M : My_Int) return My_Int;
-end Decls;
+@example
+remove switch -f
@end example
-@example
-with Utils;
-package body Decls is
- task body Lib_Task is
- begin
- accept Start;
- Utils.Put_Val (2);
- end Lib_Task;
+This tactic is suggested in case editing the forced-elaboration-order file is
+not an option.
- function Ident (M : My_Int) return My_Int is
- begin
- return M;
- end Ident;
-end Decls;
-@end example
+The programmer should remove binder switch @code{-f} from the binder
+arguments, and rebind.
-@example
-with Decls;
-package Utils is
- procedure Put_Val (Arg : Decls.My_Int);
-end Utils;
-@end example
+@item
+Multiple-circularities diagnostic
@example
-with Ada.Text_IO; use Ada.Text_IO;
-package body Utils is
- procedure Put_Val (Arg : Decls.My_Int) is
- begin
- Put_Line (Arg'Img);
- end Put_Val;
-end Utils;
+diagnose all circularities (binder switch -d_C)
@end example
-@example
-with Decls;
-package Obj_Decls is -- new
- Task_Obj : Decls.Lib_Task;
-end Obj_Decls;
-@end example
+By default, the binder will diagnose only the highest-precedence circularity.
+If the program contains multiple circularities, the binder will suggest the
+use of binder switch @code{-d_C} in order to obtain the diagnostics of all
+circularities.
-@example
-with Obj_Decls;
-procedure Main is
-begin
- Obj_Decls.Task_Obj.Start; -- new
-end Main;
-@end example
+The programmer should add binder switch @code{-d_C} to the binder
+arguments, and rebind.
+@end itemize
-@item
-@emph{Use restriction No_Entry_Calls_In_Elaboration_Code}
+If none of the tactics suggested by the binder eliminate the elaboration
+circularity, the programmer should consider using one of the legacy elaboration
+models, in the following order:
-The issue exhibited in the original example under this section revolves
-around the body of @code{Lib_Task} blocking on an accept statement. There is
-no rule to prevent elaboration code from performing entry calls, however in
-practice this is highly unusual. In addition, the pattern of starting tasks
-at elaboration time and then immediately blocking on accept or select
-statements is quite common.
-If a programmer knows that elaboration code will not perform any entry
-calls, then the programmer can indicate that the static model should not
-process the remainder of a task body once an accept or select statement has
-been encountered. This behavior can be specified by a configuration pragma:
+@itemize *
-@example
-pragma Restrictions (No_Entry_Calls_In_Elaboration_Code);
-@end example
+@item
+Use the pre-20.x legacy elaboration-order model, with binder switch
+@code{-H}.
-In addition to the change in behavior with respect to task bodies, the
-static model will verify that no entry calls take place at elaboration time.
+@item
+Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
+switch @code{-gnatH} and binder switch @code{-H}.
+
+@item
+Use the relaxed static-elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
+
+@item
+Use the relaxed dynamic-elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
+@code{-H}.
@end itemize
-@node Elaboration-related Compiler Switches,Summary of Procedures for Elaboration Control,Resolving Task Issues,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-related-compiler-switches}@anchor{24d}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id15}@anchor{24e}
+@node Elaboration-related Compiler Switches,Summary of Procedures for Elaboration Control,Resolving Elaboration Circularities,Elaboration Order Handling in GNAT
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{22a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-related-compiler-switches}@anchor{22b}
@section Elaboration-related Compiler Switches
Dynamic elaboration checking mode enabled
-When this switch is in effect, GNAT activates the dynamic elaboration model.
+When this switch is in effect, GNAT activates the dynamic model.
@end table
@geindex -gnatel (gnat)
Turn on info messages on generated Elaborate[_All] pragmas
+This switch is only applicable to the pre-20.x legacy elaboration models.
+The post-20.x elaboration model no longer relies on implicitly generated
+@code{Elaborate} and @code{Elaborate_All} pragmas to order units.
+
When this switch is in effect, GNAT will emit the following supplementary
information depending on the elaboration model in effect.
@item
@emph{Static model}
-GNAT will indicate all scenarios executed during elaboration. In addition,
+GNAT will indicate all scenarios invoked during elaboration. In addition,
it will provide detailed traceback when an implicit @code{Elaborate} or
@code{Elaborate_All} pragma is generated.
@end table
@node Summary of Procedures for Elaboration Control,Inspecting the Chosen Elaboration Order,Elaboration-related Compiler Switches,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{24f}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id16}@anchor{250}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{22c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{22d}
@section Summary of Procedures for Elaboration Control
@code{-gnatwl}.
@item
-Use switch @code{-gnatel} to obtain messages on generated implicit
-@code{Elaborate} and @code{Elaborate_All} pragmas. The trace information could
-indicate why a server unit must be elaborated prior to a client unit.
-
-@item
-If the warnings produced by the static model indicate that a task is
-involved, consider the options in section @ref{24b,,Resolving Task Issues}.
+Cosider the tactics given in the suggestions section of the circularity
+diagnostic.
@item
If none of the steps outlined above resolve the circularity, use a more
@itemize -
@item
-Use the dynamic elaboration model, with compiler switch @code{-gnatE}.
+Use the pre-20.x legacy elaboration-order model, with binder switch
+@code{-H}.
@item
-Use the legacy static elaboration model, with compiler switch
-@code{-gnatH}.
+Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
+switch @code{-gnatH} and binder switch @code{-H}.
@item
-Use the legacy dynamic elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatE}.
+Use the relaxed static elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
@item
-Use the relaxed legacy static elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ}.
-
-@item
-Use the relaxed legacy dynamic elaboration model, with compiler switches
-@code{-gnatH} @code{-gnatJ} @code{-gnatE}.
+Use the relaxed dynamic elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
+@code{-H}.
@end itemize
@end itemize
@node Inspecting the Chosen Elaboration Order,,Summary of Procedures for Elaboration Control,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{251}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id17}@anchor{252}
+@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{22f}
@section Inspecting the Chosen Elaboration Order
@code{Elab_Spec}, interspersed with assignments to @cite{Exxx} which indicates that a
particular unit is elaborated. For example:
+@quotation
+
@example
System.Soft_Links'Elab_Body;
E14 := True;
Ada.Text_Io'Elab_Body;
E07 := True;
@end example
+@end quotation
Note also binder switch @code{-l}, which outputs the chosen elaboration
order and provides a more readable form of the above:
+@quotation
+
@example
ada (spec)
interfaces (spec)
text_io (spec)
gdbstr (body)
@end example
+@end quotation
@node Inline Assembler,GNU Free Documentation License,Elaboration Order Handling in GNAT,Top
-@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}@anchor{gnat_ugn/inline_assembler doc}@anchor{253}@anchor{gnat_ugn/inline_assembler id1}@anchor{254}
+@anchor{gnat_ugn/inline_assembler inline-assembler}@anchor{10}@anchor{gnat_ugn/inline_assembler doc}@anchor{230}@anchor{gnat_ugn/inline_assembler id1}@anchor{231}
@chapter Inline Assembler
@end menu
@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id2}@anchor{255}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{256}
+@anchor{gnat_ugn/inline_assembler id2}@anchor{232}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{233}
@section Basic Assembler Syntax
@node A Simple Example of Inline Assembler,Output Variables in Inline Assembler,Basic Assembler Syntax,Inline Assembler
-@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{257}@anchor{gnat_ugn/inline_assembler id3}@anchor{258}
+@anchor{gnat_ugn/inline_assembler a-simple-example-of-inline-assembler}@anchor{234}@anchor{gnat_ugn/inline_assembler id3}@anchor{235}
@section A Simple Example of Inline Assembler
@code{nothing.out}.
@node Output Variables in Inline Assembler,Input Variables in Inline Assembler,A Simple Example of Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id4}@anchor{259}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{25a}
+@anchor{gnat_ugn/inline_assembler id4}@anchor{236}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{237}
@section Output Variables in Inline Assembler
@end quotation
@node Input Variables in Inline Assembler,Inlining Inline Assembler Code,Output Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id5}@anchor{25b}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{25c}
+@anchor{gnat_ugn/inline_assembler id5}@anchor{238}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{239}
@section Input Variables in Inline Assembler
@end quotation
@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id6}@anchor{25d}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{25e}
+@anchor{gnat_ugn/inline_assembler id6}@anchor{23a}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{23b}
@section Inlining Inline Assembler Code
thus saving the overhead of stack frame setup and an out-of-line call.
@node Other Asm Functionality,,Inlining Inline Assembler Code,Inline Assembler
-@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{25f}@anchor{gnat_ugn/inline_assembler id7}@anchor{260}
+@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{23c}@anchor{gnat_ugn/inline_assembler id7}@anchor{23d}
@section Other @code{Asm} Functionality
@end menu
@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{261}@anchor{gnat_ugn/inline_assembler id8}@anchor{262}
+@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{23e}@anchor{gnat_ugn/inline_assembler id8}@anchor{23f}
@subsection The @code{Clobber} Parameter
@end itemize
@node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{263}@anchor{gnat_ugn/inline_assembler id9}@anchor{264}
+@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{240}@anchor{gnat_ugn/inline_assembler id9}@anchor{241}
@subsection The @code{Volatile} Parameter
problems.
@node GNU Free Documentation License,Index,Inline Assembler,Top
-@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{265}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{266}
+@anchor{share/gnu_free_documentation_license gnu-fdl}@anchor{1}@anchor{share/gnu_free_documentation_license doc}@anchor{242}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{243}
@chapter GNU Free Documentation License
@printindex ge
-@anchor{de}@w{ }
@anchor{gnat_ugn/gnat_utility_programs switches-related-to-project-files}@w{ }
+@anchor{cf}@w{ }
@c %**end of body
@bye
projects / gcc.git / blobdiff