@setfilename gnat_ugn.info
@documentencoding UTF-8
@ifinfo
-@*Generated by Sphinx 1.3b2.@*
+@*Generated by Sphinx 1.4.6.@*
@end ifinfo
@settitle GNAT User's Guide for Native Platforms
@defindex ge
@copying
@quotation
-GNAT User's Guide for Native Platforms , November 13, 2015
+GNAT User's Guide for Native Platforms , Dec 11, 2020
AdaCore
-Copyright @copyright{} 2008-2015, Free Software Foundation
+Copyright @copyright{} 2008-2021, Free Software Foundation
@end quotation
@end copying
* Getting Started with GNAT::
* The GNAT Compilation Model::
* Building Executable Programs with GNAT::
-* GNAT Project Manager::
-* Tools Supporting Project Files::
* GNAT Utility Programs::
* GNAT and Program Execution::
* Platform-Specific Information::
* 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
* Calling Conventions::
* Building Mixed Ada and C++ Programs::
* Generating Ada Bindings for C and C++ headers::
+* Generating C Headers for Ada Specifications::
Building Mixed Ada and C++ Programs
Generating Ada Bindings for C and C++ headers
-* Running the binding generator::
-* Generating bindings for C++ headers::
+* Running the Binding Generator::
+* Generating Bindings for C++ Headers::
* Switches::
+Generating C Headers for Ada Specifications
+
+* Running the C Header Generator::
+
GNAT and Other Compilation Models
* Comparison between GNAT and C/C++ Compilation Models::
* Building with gnatmake::
* Compiling with gcc::
* Compiler Switches::
+* Linker Switches::
* Binding with gnatbind::
* Linking with gnatlink::
* Using the GNU make Utility::
* Generating the Command Line Switches::
* Overcoming Command Line Length Limits::
-GNAT Project Manager
-
-* Introduction::
-* Building With Projects::
-* Organizing Projects into Subsystems::
-* Scenarios in Projects::
-* Library Projects::
-* Project Extension::
-* Aggregate Projects::
-* Aggregate Library Projects::
-* Project File Reference::
-
-Building With Projects
-
-* Source Files and Directories::
-* Duplicate Sources in Projects::
-* Object and Exec Directory::
-* Main Subprograms::
-* Tools Options in Project Files::
-* Compiling with Project Files::
-* Executable File Names::
-* Avoid Duplication With Variables::
-* Naming Schemes::
-* Installation::
-* Distributed support::
-
-Organizing Projects into Subsystems
-
-* Project Dependencies::
-* Cyclic Project Dependencies::
-* Sharing Between Projects::
-* Global Attributes::
-
-Library Projects
-
-* Building Libraries::
-* Using Library Projects::
-* Stand-alone Library Projects::
-* Installing a library with project files::
-
-Project Extension
-
-* Project Hierarchy Extension::
-
-Aggregate Projects
-
-* Building all main programs from a single project tree::
-* Building a set of projects with a single command::
-* Define a build environment::
-* Performance improvements in builder::
-* Syntax of aggregate projects::
-* package Builder in aggregate projects::
-
-Aggregate Library Projects
-
-* Building aggregate library projects::
-* Syntax of aggregate library projects::
-
-Project File Reference
-
-* Project Declaration::
-* Qualified Projects::
-* Declarations::
-* Packages::
-* Expressions::
-* External Values::
-* Typed String Declaration::
-* Variables::
-* Case Constructions::
-* Attributes::
-
-Attributes
-
-* Project Level Attributes::
-* Package Binder Attributes::
-* Package Builder Attributes::
-* Package Clean Attributes::
-* Package Compiler Attributes::
-* Package Cross_Reference Attributes::
-* Package Finder Attributes::
-* Package gnatls Attributes::
-* Package IDE Attributes::
-* Package Install Attributes::
-* Package Linker Attributes::
-* Package Naming Attributes::
-* Package Remote Attributes::
-* Package Stack Attributes::
-* Package Synchronize Attributes::
-
-Tools Supporting Project Files
-
-* gnatmake and Project Files::
-* The GNAT Driver and Project Files::
-
-gnatmake and Project Files
-
-* Switches Related to Project Files::
-* Switches and Project Files::
-* Specifying Configuration Pragmas::
-* Project Files and Main Subprograms::
-* Library Project Files::
-
GNAT Utility Programs
* 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::
-* Project 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::
* Naming Conventions for GNAT Source Files::
* Getting Internal Debugging Information::
* Stack Traceback::
+* Pretty-Printers for the GNAT runtime::
Stack Traceback
* 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::
Overflow Check Handling in GNAT
* Background::
-* Overflow Checking Modes in GNAT::
+* Management of Overflows in GNAT::
* Specifying the Desired Mode::
* Default Settings::
* Implementation Notes::
* Run-Time Libraries::
* Specifying a Run-Time Library::
+* GNU/Linux Topics::
* Microsoft Windows Topics::
* Mac OS Topics::
Specifying a Run-Time Library
* Choosing the Scheduling Policy::
-* Solaris-Specific Considerations::
-* Solaris Threads Issues::
-* AIX-Specific Considerations::
+
+GNU/Linux Topics
+
+* Required Packages on GNU/Linux::
Microsoft Windows Topics
* 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::
Elaboration Order Handling in GNAT
* Elaboration Code::
+* Elaboration Order::
* Checking the Elaboration Order::
-* Controlling the Elaboration Order::
-* Controlling Elaboration in GNAT - Internal Calls::
-* Controlling Elaboration in GNAT - External Calls::
-* Default Behavior in GNAT - Ensuring Safety::
-* Treatment of Pragma Elaborate::
-* Elaboration Issues for Library Tasks::
+* Controlling the Elaboration Order in Ada::
+* Controlling the Elaboration Order in GNAT::
* Mixing Elaboration Models::
-* What to Do If the Default Elaboration Behavior Fails::
-* Elaboration for Indirect Calls::
+* ABE Diagnostics::
+* SPARK Diagnostics::
+* Elaboration Circularities::
+* Resolving Elaboration Circularities::
+* Elaboration-related Compiler Switches::
* Summary of Procedures for Elaboration Control::
-* Other Elaboration Order Considerations::
-* Determining the Chosen Elaboration Order::
+* Inspecting the Chosen Elaboration Order::
Inline Assembler
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
using the GNU make utility with GNAT.
@item
-@ref{b,,GNAT Project Manager} describes how to use project files
-to organize large projects.
-
-@item
-@ref{c,,Tools Supporting Project Files} described how to use the project
-facility in conjunction with various GNAT tools.
-
-@item
-@ref{d,,GNAT Utility Programs} explains the various utility programs that
+@ref{b,,GNAT Utility Programs} explains the various utility programs that
are included in the GNAT environment
@item
-@ref{e,,GNAT and Program Execution} covers a number of topics related to
+@ref{c,,GNAT and Program Execution} covers a number of topics related to
running, debugging, and tuning the performace of programs developed
with GNAT
@end itemize
@itemize *
@item
-@ref{f,,Platform-Specific Information} describes the different run-time
+@ref{d,,Platform-Specific Information} describes the different run-time
library implementations and also presents information on how to use
GNAT on several specific platforms
@item
-@ref{10,,Example of Binder Output File} shows the source code for the binder
+@ref{e,,Example of Binder Output File} shows the source code for the binder
output file for a sample program.
@item
-@ref{11,,Elaboration Order Handling in GNAT} describes how GNAT helps
+@ref{f,,Elaboration Order Handling in GNAT} describes how GNAT helps
you deal with elaboration order issues.
@item
-@ref{12,,Inline Assembler} shows how to use the inline assembly facility
+@ref{10,,Inline Assembler} shows how to use the inline assembly facility
in an Ada program.
@end itemize
@node What You Should Know before Reading This Guide,Related Information,What This Guide Contains,About This Guide
-@anchor{gnat_ugn/about_this_guide what-you-should-know-before-reading-this-guide}@anchor{13}
+@anchor{gnat_ugn/about_this_guide what-you-should-know-before-reading-this-guide}@anchor{11}
@section What You Should Know before Reading This Guide
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
-@anchor{gnat_ugn/about_this_guide related-information}@anchor{14}
+@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{15}
-@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 @cite{gnatname}, @cite{gnatkr}, and @cite{gnatchop} tools
-
-@item
-@ref{16,,Configuration Pragmas}
-
-@item
-@ref{17,,GNAT and Libraries}
-
-@item
-@ref{18,,Conditional Compilation} including @ref{19,,Preprocessing with gnatprep}
-and @ref{1a,,Integrated Preprocessing}
-
-@item
-@ref{1b,,Generating Ada Bindings for C and C++ headers}
-
-@item
-@ref{1c,,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{1d,,Building with gnatmake}
-
-@item
-@ref{1e,,Compiling with gcc}
-
-@item
-@ref{1f,,Binding with gnatbind}
-
-@item
-@ref{20,,Linking with gnatlink}
-
-@item
-@ref{21,,Using the GNU make Utility}
-@end itemize
-
-@item
-@ref{d,,GNAT Utility Programs} is a new chapter consolidating the information about several
-GNAT tools:
-
-
-
-@itemize -
-
-@item
-@ref{22,,The File Cleanup Utility gnatclean}
-
-@item
-@ref{23,,The GNAT Library Browser gnatls}
-
-@item
-@ref{24,,The Cross-Referencing Tools gnatxref and gnatfind}
-
-@item
-@ref{25,,The Ada to HTML Converter gnathtml}
-@end itemize
-
-@item
-@ref{e,,GNAT and Program Execution} is a new chapter consolidating the following:
-
-
-@itemize -
-
-@item
-@ref{26,,Running and Debugging Ada Programs}
-
-@item
-@ref{27,,Code Coverage and Profiling}
-
-@item
-@ref{28,,Improving Performance}
-
-@item
-@ref{29,,Overflow Check Handling in GNAT}
-
-@item
-@ref{2a,,Performing Dimensionality Analysis in GNAT}
-
-@item
-@ref{2b,,Stack Related Facilities}
-
-@item
-@ref{2c,,Memory Management Issues}
-@end itemize
-
-@item
-@ref{f,,Platform-Specific Information} is a new appendix consolidating the following:
-
-
-@itemize -
-
-@item
-@ref{2d,,Run-Time Libraries}
-
-@item
-@ref{2e,,Microsoft Windows Topics}
-
-@item
-@ref{2f,,Mac OS Topics}
-@end itemize
-
-@item
-The @cite{Compatibility and Porting Guide} appendix has been moved to the
-@cite{GNAT Reference Manual}. It now includes a section
-@cite{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{30}
+@node Conventions,,Related Information,About This Guide
+@anchor{gnat_ugn/about_this_guide conventions}@anchor{13}
@section Conventions
@itemize *
@item
-@cite{Functions}, @cite{utility program names}, @cite{standard names},
-and @cite{classes}.
+@code{Functions}, @code{utility program names}, @code{standard names},
+and @code{classes}.
@item
-@cite{Option flags}
+@code{Option flags}
@item
@code{File names}
@item
-@cite{Variables}
+@code{Variables}
@item
@emph{Emphasis}
@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{31}@anchor{gnat_ugn/getting_started_with_gnat id1}@anchor{32}
+@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{33}@anchor{gnat_ugn/getting_started_with_gnat id2}@anchor{34}
+@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
All appropriate object files must be linked to produce an executable.
@end itemize
-All three steps are most commonly handled by using the @emph{gnatmake}
+All three steps are most commonly handled by using the @code{gnatmake}
utility program that, given the name of the main program, automatically
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{35}@anchor{gnat_ugn/getting_started_with_gnat id3}@anchor{36}
+@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
extension is @code{ads} for a
spec and @code{adb} for a body.
You can override this default file naming convention by use of the
-special pragma @cite{Source_File_Name} (for further information please
-see @ref{37,,Using Other File Names}).
+special pragma @code{Source_File_Name} (for further information please
+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 @cite{gnatchop} utility
+for all your compilations, then the @code{gnatchop} utility
can be used to generate correctly-named source files
-(see @ref{38,,Renaming Files with gnatchop}).
+(see @ref{1d,,Renaming Files with gnatchop}).
-You can compile the program using the following command (@cite{$} is used
+You can compile the program using the following command (@code{$} is used
as the command prompt in the examples in this document):
@example
$ gcc -c hello.adb
@end example
-@emph{gcc} is the command used to run the compiler. This compiler is
+@code{gcc} is the command used to run the compiler. This compiler is
capable of compiling programs in several languages, including Ada and
C. It assumes that you have given it an Ada program if the file extension is
either @code{.ads} or @code{.adb}, and it will then call
the GNAT compiler to compile the specified file.
-The @code{-c} switch is required. It tells @emph{gcc} to only do a
-compilation. (For C programs, @emph{gcc} can also do linking, but this
+The @code{-c} switch is required. It tells @code{gcc} to only do a
+compilation. (For C programs, @code{gcc} can also do linking, but this
capability is not used directly for Ada programs, so the @code{-c}
switch must always be present.)
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 @cite{gnatbind} to bind the program
-and @emph{gnatlink} to link it. The
-argument to both @cite{gnatbind} and @emph{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 @emph{gnatmake},
-a master program that invokes all the required
-compilation, binding and linking tools in the correct order. In particular,
-@emph{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 *gnatmake*)
+@geindex Version skew (avoided by `@w{`}gnatmake`@w{`})
@example
$ gnatmake hello.adb
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{39}@anchor{gnat_ugn/getting_started_with_gnat running-a-program-with-multiple-units}@anchor{3a}
+@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
@item @emph{greetings.ads}
-spec of package @cite{Greetings}
+spec of package @code{Greetings}
@item @emph{greetings.adb}
-body of package @cite{Greetings}
+body of package @code{Greetings}
@item @emph{gmain.adb}
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 @emph{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 @emph{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{3b}@anchor{gnat_ugn/getting_started_with_gnat id5}@anchor{3c}
-@section Using the @emph{gnatmake} Utility
-
-
-If you work on a program by compiling single components at a time using
-@emph{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}.
-
-@emph{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 @emph{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. @emph{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 @emph{gnatmake}, because working out by hand
-what needs to be recompiled can be difficult.
-
-Note that @emph{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, @emph{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. @emph{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{3d}@anchor{gnat_ugn/the_gnat_compilation_model the-gnat-compilation-model}@anchor{9}@anchor{gnat_ugn/the_gnat_compilation_model id1}@anchor{3e}
+@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{3f,,Source Representation}
+@ref{22,,Source Representation}
@item
-@ref{40,,Foreign Language Representation}
+@ref{23,,Foreign Language Representation}
@item
-@ref{41,,File Naming Topics and Utilities}
+@ref{24,,File Naming Topics and Utilities}
@end itemize
@item
-@ref{16,,Configuration Pragmas}
+@ref{25,,Configuration Pragmas}
@item
-@ref{42,,Generating Object Files}
+@ref{26,,Generating Object Files}
@item
-@ref{43,,Source Dependencies}
+@ref{27,,Source Dependencies}
@item
-@ref{44,,The Ada Library Information Files}
+@ref{28,,The Ada Library Information Files}
@item
-@ref{45,,Binding an Ada Program}
+@ref{29,,Binding an Ada Program}
@item
-@ref{17,,GNAT and Libraries}
+@ref{2a,,GNAT and Libraries}
@item
-@ref{18,,Conditional Compilation}
+@ref{2b,,Conditional Compilation}
@item
-@ref{46,,Mixed Language Programming}
+@ref{2c,,Mixed Language Programming}
@item
-@ref{47,,GNAT and Other Compilation Models}
+@ref{2d,,GNAT and Other Compilation Models}
@item
-@ref{1c,,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{3f}@anchor{gnat_ugn/the_gnat_compilation_model id2}@anchor{48}
+@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{40,,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:
@quotation
-@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxx}
+@multitable {xxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxx}
@item
Character
@tab
-@cite{16#0B#}
+@code{16#0B#}
@item
@tab
-@cite{16#09#}
+@code{16#09#}
@item
@tab
-@cite{16#0D#}
+@code{16#0D#}
@item
@tab
-@cite{16#0A#}
+@code{16#0A#}
@item
@tab
-@cite{16#0C#}
+@code{16#0C#}
@end multitable
Source files are in standard text file format. In addition, GNAT will
recognize a wide variety of stream formats, in which the end of
physical lines is marked by any of the following sequences:
-@cite{LF}, @cite{CR}, @cite{CR-LF}, or @cite{LF-CR}. This is useful
+@code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful
in accommodating files that are imported from other operating systems.
@geindex End of source file; Source file@comma{} end
@geindex SUB (control character)
The end of a source file is normally represented by the physical end of
-file. However, the control character @cite{16#1A#} (@code{SUB}) is also
+file. However, the control character @code{16#1A#} (@code{SUB}) is also
recognized as signalling the end of the source file. Again, this is
provided for compatibility with other operating systems where this
code is used to represent the end of file.
Each file contains a single Ada compilation unit, including any pragmas
associated with the unit. For example, this means you must place a
-package declaration (a package @cite{spec}) and the corresponding body in
-separate files. An Ada @cite{compilation} (which is a sequence of
+package declaration (a package @emph{spec}) and the corresponding body in
+separate files. An Ada @emph{compilation} (which is a sequence of
compilation units) is represented using a sequence of files. Similarly,
you will place each subunit or child unit in a separate file.
@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{40}@anchor{gnat_ugn/the_gnat_compilation_model id3}@anchor{49}
+@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{4a,,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{4b}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{4c}
+@anchor{gnat_ugn/the_gnat_compilation_model id4}@anchor{32}@anchor{gnat_ugn/the_gnat_compilation_model latin-1}@anchor{33}
@subsection Latin-1
@geindex Latin-1
The basic character set is Latin-1. This character set is defined by ISO
-standard 8859, part 1. The lower half (character codes @cite{16#00#}
-... @cite{16#7F#)} is identical to standard ASCII coding, but the upper
+standard 8859, part 1. The lower half (character codes @code{16#00#}
+... @code{16#7F#)} is identical to standard ASCII coding, but the upper
half is used to represent additional characters. These include extended letters
used by European languages, such as French accents, the vowels with umlauts
used in German, and the extra letter A-ring used in Swedish.
@geindex Ada.Characters.Latin_1
For a complete list of Latin-1 codes and their encodings, see the source
-file of library unit @cite{Ada.Characters.Latin_1} in file
+file of library unit @code{Ada.Characters.Latin_1} in file
@code{a-chlat1.ads}.
You may use any of these extended characters freely in character or
string literals. In addition, the extended characters that represent
letters can be used in identifiers.
@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{4d}@anchor{gnat_ugn/the_gnat_compilation_model id5}@anchor{4e}
+@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{4f}@anchor{gnat_ugn/the_gnat_compilation_model wide-character-encodings}@anchor{50}
+@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
ESC a b c d
@end example
-where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ESC A345 is used to represent the wide character with code
-@cite{16#A345#}.
+@code{16#A345#}.
This scheme is compatible with use of the full Wide_Character set.
@item @emph{Upper-Half Coding}
@geindex Upper-Half Coding
-The wide character with encoding @cite{16#abcd#} where the upper bit is on
+The wide character with encoding @code{16#abcd#} where the upper bit is on
(in other words, 'a' is in the range 8-F) is represented as two bytes,
-@cite{16#ab#} and @cite{16#cd#}. The second byte cannot be a format control
+@code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control
character, but is not required to be in the upper half. This method can
be also used for shift-JIS or EUC, where the internal coding matches the
external coding.
@geindex Shift JIS Coding
A wide character is represented by a two-character sequence,
-@cite{16#ab#} and
-@cite{16#cd#}, with the restrictions described for upper-half encoding as
+@code{16#ab#} and
+@code{16#cd#}, with the restrictions described for upper-half encoding as
described above. The internal character code is the corresponding JIS
character according to the standard algorithm for Shift-JIS
conversion. Only characters defined in the JIS code set table can be
@geindex EUC Coding
A wide character is represented by a two-character sequence
-@cite{16#ab#} and
-@cite{16#cd#}, with both characters being in the upper half. The internal
+@code{16#ab#} and
+@code{16#cd#}, with both characters being in the upper half. The internal
character code is the corresponding JIS character according to the EUC
encoding algorithm. Only characters defined in the JIS code set table
can be used with this encoding method.
is a one, two, or three byte sequence:
@example
-16#0000#-16#007f#: 2#0`xxxxxxx`#
-16#0080#-16#07ff#: 2#110`xxxxx`# 2#10`xxxxxx`#
-16#0800#-16#ffff#: 2#1110`xxxx`# 2#10`xxxxxx`# 2#10`xxxxxx`#
+16#0000#-16#007f#: 2#0xxxxxxx#
+16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
+16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
@end example
-where the @cite{xxx} bits correspond to the left-padded bits of the
+where the @code{xxx} bits correspond to the left-padded bits of the
16-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
[ " a b c d " ]
@end example
-where @cite{a}, @cite{b}, @cite{c}, @cite{d} are the four hexadecimal
+where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ['A345'] is used to represent the wide character with code
-@cite{16#A345#}. It is also possible (though not required) to use the
+@code{16#A345#}. It is also possible (though not required) to use the
Brackets coding for upper half characters. For example, the code
-@cite{16#A3#} can be represented as @cite{['A3']}.
+@code{16#A3#} can be represented as @code{['A3']}.
This scheme is compatible with use of the full Wide_Character set,
and is also the method used for wide character encoding in some standard
@end cartouche
@node Wide_Wide_Character Encodings,,Wide_Character Encodings,Foreign Language Representation
-@anchor{gnat_ugn/the_gnat_compilation_model id7}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model wide-wide-character-encodings}@anchor{52}
+@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
10xxxxxx 10xxxxxx 10xxxxxx
@end example
-where the @cite{xxx} bits correspond to the left-padded bits of the
+where the @code{xxx} bits correspond to the left-padded bits of the
32-bit character value.
@item @emph{Brackets Coding}
[ " a b c d e f g h " ]
@end example
-where @cite{a-h} are the six or eight hexadecimal
+where @code{a-h} are the six or eight hexadecimal
characters (using uppercase letters) of the wide wide character code. For
example, ["1F4567"] is used to represent the wide wide character with code
-@cite{16#001F_4567#}.
+@code{16#001F_4567#}.
This scheme is compatible with use of the full Wide_Wide_Character set,
and is also the method used for wide wide character encoding in some standard
@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{53}@anchor{gnat_ugn/the_gnat_compilation_model file-naming-topics-and-utilities}@anchor{41}
+@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{54}@anchor{gnat_ugn/the_gnat_compilation_model id9}@anchor{55}
+@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
An exception arises if the file name generated by the above rules starts
with one of the characters
-@cite{a}, @cite{g}, @cite{i}, or @cite{s}, and the second character is a
+@code{a}, @code{g}, @code{i}, or @code{s}, and the second character is a
minus. In this case, the character tilde is used in place
of the minus. The reason for this special rule is to avoid clashes with
the standard names for child units of the packages System, Ada,
Interfaces, and GNAT, which use the prefixes
-@cite{s-}, @cite{a-}, @cite{i-}, and @cite{g-},
+@code{s-}, @code{a-}, @code{i-}, and @code{g-},
respectively.
The file extension is @code{.ads} for a spec and
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{56,,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{38,,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 @cite{Windows} if the canonical name is
-@cite{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead.
+significant. So for example on Windows if the canonical name is
+@code{main-sub.adb}, you can use the file name @code{Main-Sub.adb} instead.
However, case is significant for other operating systems, so for example,
if you want to use other than canonically cased file names on a Unix system,
you need to follow the procedures described in the next section.
@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{57}@anchor{gnat_ugn/the_gnat_compilation_model using-other-file-names}@anchor{37}
+@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{58,,Handling of Configuration Pragmas}.
+see @ref{3f,,Handling of Configuration Pragmas}.
@geindex gnat.adc
source file name pragma. However, if the file name specified has an
extension other than @code{.ads} or @code{.adb} it is necessary to use
a special syntax when compiling the file. The name in this case must be
-preceded by the special sequence @emph{-x} followed by a space and the name
-of the language, here @cite{ada}, as in:
+preceded by the special sequence @code{-x} followed by a space and the name
+of the language, here @code{ada}, as in:
@example
$ gcc -c -x ada peculiar_file_name.sim
@end example
-@cite{gnatmake} handles non-standard file names in the usual manner (the
+@code{gnatmake} handles non-standard file names in the usual manner (the
non-standard file name for the main program is simply used as the
argument to gnatmake). Note that if the extension is also non-standard,
-then it must be included in the @cite{gnatmake} command, it may not
+then it must be included in the @code{gnatmake} command, it may not
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{59}@anchor{gnat_ugn/the_gnat_compilation_model alternative-file-naming-schemes}@anchor{5a}
+@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 File names
-The previous section described the use of the @cite{Source_File_Name}
+The previous section described the use of the @code{Source_File_Name}
pragma to allow arbitrary names to be assigned to individual source files.
However, this approach requires one pragma for each file, and especially in
large systems can result in very long @code{gnat.adc} files, and also create
GNAT also provides a facility for specifying systematic file naming schemes
other than the standard default naming scheme previously described. An
alternative scheme for naming is specified by the use of
-@cite{Source_File_Name} pragmas having the following format:
+@code{Source_File_Name} pragmas having the following format:
@example
pragma Source_File_Name (
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
@end example
-The @cite{FILE_NAME_PATTERN} string shows how the file name is constructed.
+The @code{FILE_NAME_PATTERN} string shows how the file name is constructed.
It contains a single asterisk character, and the unit name is substituted
systematically for this asterisk. The optional parameter
-@cite{Casing} indicates
+@code{Casing} indicates
whether the unit name is to be all upper-case letters, all lower-case letters,
or mixed-case. If no
-@cite{Casing} parameter is used, then the default is all
+@code{Casing} parameter is used, then the default is all
lower-case.
-The optional @cite{Dot_Replacement} string is used to replace any periods
-that occur in subunit or child unit names. If no @cite{Dot_Replacement}
+The optional @code{Dot_Replacement} string is used to replace any periods
+that occur in subunit or child unit names. If no @code{Dot_Replacement}
argument is used then separating dots appear unchanged in the resulting
file name.
Although the above syntax indicates that the
-@cite{Casing} argument must appear
-before the @cite{Dot_Replacement} argument, but it
+@code{Casing} argument must appear
+before the @code{Dot_Replacement} argument, but it
is also permissible to write these arguments in the opposite order.
As indicated, it is possible to specify different naming schemes for
bodies, specs, and subunits. Quite often the rule for subunits is the
same as the rule for bodies, in which case, there is no need to give
-a separate @cite{Subunit_File_Name} rule, and in this case the
-@cite{Body_File_name} rule is used for subunits as well.
+a separate @code{Subunit_File_Name} rule, and in this case the
+@code{Body_File_name} rule is used for subunits as well.
The separate rule for subunits can also be used to implement the rather
unusual case of a compilation environment (e.g., a single directory) which
@itemize *
@item
-If there is a specific @cite{Source_File_Name} pragma for the given unit,
+If there is a specific @code{Source_File_Name} pragma for the given unit,
then this is always used, and any general pattern rules are ignored.
@item
-If there is a pattern type @cite{Source_File_Name} pragma that applies to
+If there is a pattern type @code{Source_File_Name} pragma that applies to
the unit, then the resulting file name will be used if the file exists. If
more than one pattern matches, the latest one will be tried first, and the
first attempt resulting in a reference to a file that exists will be used.
@item
-If no pattern type @cite{Source_File_Name} pragma that applies to the unit
+If no pattern type @code{Source_File_Name} pragma that applies to the unit
for which the corresponding file exists, then the standard GNAT default
naming rules are used.
@end itemize
@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{5b}@anchor{gnat_ugn/the_gnat_compilation_model id12}@anchor{5c}
-@subsection Handling Arbitrary File Naming Conventions with @cite{gnatname}
+@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}
@geindex File Naming Conventions
@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{5d}@anchor{gnat_ugn/the_gnat_compilation_model id13}@anchor{5e}
+@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
The GNAT compiler must be able to know the source file name of a compilation
unit. When using the standard GNAT default file naming conventions
-(@cite{.ads} for specs, @cite{.adb} for bodies), the GNAT compiler
+(@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler
does not need additional information.
When the source file names do not follow the standard GNAT default file naming
conventions, the GNAT compiler must be given additional information through
-a configuration pragmas file (@ref{16,,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 @cite{Source_File_Name} specifying a naming pattern
-(@ref{5a,,Alternative File Naming Schemes}) may be sufficient. However,
+a small number of pragmas @code{Source_File_Name} specifying a naming pattern
+(@ref{41,,Alternative File Naming Schemes}) may be sufficient. However,
if the file naming conventions are irregular or arbitrary, a number
-of pragma @cite{Source_File_Name} for individual compilation units
+of pragma @code{Source_File_Name} for individual compilation units
must be defined.
To help maintain the correspondence between compilation unit names and
source file names within the compiler,
-GNAT provides a tool @cite{gnatname} to generate the required pragmas for a
+GNAT provides a tool @code{gnatname} to generate the required pragmas for a
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{5f}@anchor{gnat_ugn/the_gnat_compilation_model id14}@anchor{60}
-@subsubsection Running @cite{gnatname}
+@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}
-The usual form of the @cite{gnatname} command is:
+The usual form of the @code{gnatname} command is:
@example
-$ gnatname [`switches`] `naming_pattern` [`naming_patterns`]
- [--and [`switches`] `naming_pattern` [`naming_patterns`]]
+$ gnatname [ switches ] naming_pattern [ naming_patterns ]
+ [--and [ switches ] naming_pattern [ naming_patterns ]]
@end example
All of the arguments are optional. If invoked without any argument,
-@cite{gnatname} will display its usage.
+@code{gnatname} will display its usage.
-When used with at least one naming pattern, @cite{gnatname} will attempt to
+When used with at least one naming pattern, @code{gnatname} will attempt to
find all the compilation units in files that follow at least one of the
naming patterns. To find these compilation units,
-@cite{gnatname} will use the GNAT compiler in syntax-check-only mode on all
+@code{gnatname} will use the GNAT compiler in syntax-check-only mode on all
regular files.
-One or several Naming Patterns may be given as arguments to @cite{gnatname}.
+One or several Naming Patterns may be given as arguments to @code{gnatname}.
Each Naming Pattern is enclosed between double quotes (or single
quotes on Windows).
A Naming Pattern is a regular expression similar to the wildcard patterns
used in file names by the Unix shells or the DOS prompt.
-@cite{gnatname} may be called with several sections of directories/patterns.
-Sections are separated by switch @cite{--and}. In each section, there must be
+@code{gnatname} may be called with several sections of directories/patterns.
+Sections are separated by the switch @code{--and}. In each section, there must be
at least one pattern. If no directory is specified in a section, the current
-directory (or the project directory is @cite{-P} is used) is implied.
+directory (or the project directory if @code{-P} is used) is implied.
The options other that the directory switches and the patterns apply globally
even if they are in different sections.
see the second kind of regular expressions described in @code{g-regexp.ads}
(the 'Glob' regular expressions).
-When invoked with no switch @cite{-P}, @cite{gnatname} will create a
+When invoked without the switch @code{-P}, @code{gnatname} will create a
configuration pragmas file @code{gnat.adc} in the current working directory,
-with pragmas @cite{Source_File_Name} for each file that contains a valid Ada
+with pragmas @code{Source_File_Name} for each file that contains a valid Ada
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{61}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-gnatname}@anchor{62}
-@subsubsection Switches for @cite{gnatname}
+@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}
-Switches for @cite{gnatname} must precede any specified Naming Pattern.
+Switches for @code{gnatname} must precede any specified Naming Pattern.
-You may specify any of the following switches to @cite{gnatname}:
+You may specify any of the following switches to @code{gnatname}:
@geindex --version (gnatname)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@item @code{--subdirs=@emph{dir}}
Create a configuration pragmas file @code{filename} (instead of the default
@code{gnat.adc}).
-There may be zero, one or more space between @emph{-c} and
+There may be zero, one or more space between @code{-c} and
@code{filename}.
@code{filename} may include directory information. @code{filename} must be
-writable. There may be only one switch @emph{-c}.
-When a switch @emph{-c} is
-specified, no switch @emph{-P} may be specified (see below).
+writable. There may be only one switch @code{-c}.
+When a switch @code{-c} is
+specified, no switch @code{-P} may be specified (see below).
@end table
@geindex -d (gnatname)
@item @code{-d@emph{dir}}
Look for source files in directory @code{dir}. There may be zero, one or more
-spaces between @emph{-d} and @code{dir}.
-@code{dir} may end with @cite{/**}, that is it may be of the form
-@cite{root_dir/**}. In this case, the directory @cite{root_dir} and all of its
+spaces between @code{-d} and @code{dir}.
+@code{dir} may end with @code{/**}, that is it may be of the form
+@code{root_dir/**}. In this case, the directory @code{root_dir} and all of its
subdirectories, recursively, have to be searched for sources.
-When a switch @emph{-d}
+When a switch @code{-d}
is specified, the current working directory will not be searched for source
-files, unless it is explicitly specified with a @emph{-d}
-or @emph{-D} switch.
-Several switches @emph{-d} may be specified.
+files, unless it is explicitly specified with a @code{-d}
+or @code{-D} switch.
+Several switches @code{-d} may be specified.
If @code{dir} is a relative path, it is relative to the directory of
the configuration pragmas file specified with switch
-@emph{-c},
+@code{-c},
or to the directory of the project file specified with switch
-@emph{-P} or,
-if neither switch @emph{-c}
-nor switch @emph{-P} are specified, it is relative to the
+@code{-P} or,
+if neither switch @code{-c}
+nor switch @code{-P} are specified, it is relative to the
current working directory. The directory
-specified with switch @emph{-d} must exist and be readable.
+specified with switch @code{-d} must exist and be readable.
@end table
@geindex -D (gnatname)
@item @code{-D@emph{filename}}
Look for source files in all directories listed in text file @code{filename}.
-There may be zero, one or more spaces between @emph{-D}
+There may be zero, one or more spaces between @code{-D}
and @code{filename}.
@code{filename} must be an existing, readable text file.
Each nonempty line in @code{filename} must be a directory.
-Specifying switch @emph{-D} is equivalent to specifying as many
-switches @emph{-d} as there are nonempty lines in
+Specifying switch @code{-D} is equivalent to specifying as many
+switches @code{-d} as there are nonempty lines in
@code{file}.
@item @code{-eL}
@item @code{-P@emph{proj}}
Create or update project file @code{proj}. There may be zero, one or more space
-between @emph{-P} and @code{proj}. @code{proj} may include directory
+between @code{-P} and @code{proj}. @code{proj} may include directory
information. @code{proj} must be writable.
-There may be only one switch @emph{-P}.
-When a switch @emph{-P} is specified,
-no switch @emph{-c} may be specified.
-On all platforms, except on VMS, when @cite{gnatname} is invoked for an
+There may be only one switch @code{-P}.
+When a switch @code{-P} is specified,
+no switch @code{-c} may be specified.
+On all platforms, except on VMS, when @code{gnatname} is invoked for an
existing project file <proj>.gpr, a backup copy of the project file is created
in the project directory with file name <proj>.gpr.saved_x. 'x' is the first
non negative number that makes this backup copy a new file.
@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{63}@anchor{gnat_ugn/the_gnat_compilation_model id16}@anchor{64}
-@subsubsection Examples of @cite{gnatname} Usage
+@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
@example
In this example, the directory @code{/home/me} must already exist
and be writable. In addition, the directory
@code{/home/me/sources} (specified by
-@emph{-d sources}) must exist and be readable.
+@code{-d sources}) must exist and be readable.
-Note the optional spaces after @emph{-c} and @emph{-d}.
+Note the optional spaces after @code{-c} and @code{-d}.
@example
$ gnatname -P/home/me/proj -x "*_nt_body.ada"
-dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*"
@end example
-Note that several switches @emph{-d} may be used,
+Note that several switches @code{-d} may be used,
even in conjunction with one or several switches
-@emph{-D}. Several Naming Patterns and one excluded pattern
+@code{-D}. Several Naming Patterns and one excluded pattern
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{65}@anchor{gnat_ugn/the_gnat_compilation_model id17}@anchor{66}
-@subsection File Name Krunching with @cite{gnatkr}
+@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}
@geindex gnatkr
-This chapter discusses the method used by the compiler to shorten
+This section discusses the method used by the compiler to shorten
the default file names chosen for Ada units so that they do not
exceed the maximum length permitted. It also describes the
-@cite{gnatkr} utility that can be used to determine the result of
+@code{gnatkr} utility that can be used to determine the result of
applying this shortening.
@menu
@end menu
@node About gnatkr,Using gnatkr,,File Name Krunching with gnatkr
-@anchor{gnat_ugn/the_gnat_compilation_model id18}@anchor{67}@anchor{gnat_ugn/the_gnat_compilation_model about-gnatkr}@anchor{68}
-@subsubsection About @cite{gnatkr}
+@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}
The default file naming rule in GNAT
circuit that limits file names to nn characters (where nn is a decimal
integer).
-The @cite{gnatkr} utility can be used to determine the krunched name for
+The @code{gnatkr} utility can be used to determine the krunched name for
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{69}@anchor{gnat_ugn/the_gnat_compilation_model using-gnatkr}@anchor{56}
-@subsubsection Using @cite{gnatkr}
+@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}
-The @cite{gnatkr} command has the form:
+The @code{gnatkr} command has the form:
@example
-$ gnatkr `name` [`length`]
+$ gnatkr name [ length ]
@end example
-@cite{name} is the uncrunched file name, derived from the name of the unit
+@code{name} is the uncrunched file name, derived from the name of the unit
in the standard manner described in the previous section (i.e., in particular
all dots are replaced by hyphens). The file name may or may not have an
extension (defined as a suffix of the form period followed by arbitrary
be preserved in the output. For example, when krunching @code{hellofile.ads}
to eight characters, the result will be hellofil.ads.
-Note: for compatibility with previous versions of @cite{gnatkr} dots may
+Note: for compatibility with previous versions of @code{gnatkr} dots may
appear in the name instead of hyphens, but the last dot will always be
-taken as the start of an extension. So if @cite{gnatkr} is given an argument
+taken as the start of an extension. So if @code{gnatkr} is given an argument
such as @code{Hello.World.adb} it will be treated exactly as if the first
period had been a hyphen, and for example krunching to eight characters
gives the result @code{hellworl.adb}.
Note that the result is always all lower case.
Characters of the other case are folded as required.
-@cite{length} represents the length of the krunched name. The default
+@code{length} represents the length of the krunched name. The default
when no argument is given is 8 characters. A length of zero stands for
unlimited, in other words do not chop except for system files where the
implied crunching length is always eight characters.
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{6a}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{6b}
+@anchor{gnat_ugn/the_gnat_compilation_model id20}@anchor{51}@anchor{gnat_ugn/the_gnat_compilation_model krunching-method}@anchor{52}
@subsubsection Krunching Method
for all letters, except that a hyphen in the second character position is
replaced by a tilde if the first character is
@code{a}, @code{i}, @code{g}, or @code{s}.
-The extension is @cite{.ads} for a
-spec and @cite{.adb} for a body.
+The extension is @code{.ads} for a
+spec and @code{.adb} for a body.
Krunching does not affect the extension, but the file name is shortened to
the specified length by following these rules:
Of course no file shortening algorithm can guarantee uniqueness over all
possible unit names, and if file name krunching is used then it is your
responsibility to ensure that no name clashes occur. The utility
-program @cite{gnatkr} is supplied for conveniently determining the
+program @code{gnatkr} is supplied for conveniently determining the
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{6c}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatkr-usage}@anchor{6d}
-@subsubsection Examples of @cite{gnatkr} Usage
+@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
@example
@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{6e}@anchor{gnat_ugn/the_gnat_compilation_model renaming-files-with-gnatchop}@anchor{38}
-@subsection Renaming Files with @cite{gnatchop}
+@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}
@geindex gnatchop
-This chapter discusses how to handle files with multiple units by using
-the @cite{gnatchop} utility. This utility is also useful in renaming
+This section discusses how to handle files with multiple units by using
+the @code{gnatchop} utility. This utility is also useful in renaming
files to meet the standard GNAT default file naming conventions.
@menu
@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{6f}@anchor{gnat_ugn/the_gnat_compilation_model handling-files-with-multiple-units}@anchor{70}
+@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 @cite{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. @cite{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 @emph{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 @emph{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{71}@anchor{gnat_ugn/the_gnat_compilation_model id24}@anchor{72}
+@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
-The basic function of @cite{gnatchop} is to take a file with multiple units
+The basic function of @code{gnatchop} is to take a file with multiple units
and split it into separate files. The boundary between files is reasonably
clear, except for the issue of comments and pragmas. In default mode, the
rule is that any pragmas between units belong to the previous unit, except
the split point without needing to mark it explicitly and most users will
find this default to be what they want. In this default mode it is incorrect to
submit a file containing only configuration pragmas, or one that ends in
-configuration pragmas, to @cite{gnatchop}.
+configuration pragmas, to @code{gnatchop}.
However, using a special option to activate 'compilation mode',
-@cite{gnatchop}
+@code{gnatchop}
can perform another function, which is to provide exactly the semantics
required by the RM for handling of configuration pragmas in a compilation.
In the absence of configuration pragmas (at the main file level), this
option has no effect, but it causes such configuration pragmas to be handled
in a quite different manner.
-First, in compilation mode, if @cite{gnatchop} is given a file that consists of
+First, in compilation mode, if @code{gnatchop} is given a file that consists of
only configuration pragmas, then this file is appended to the
@code{gnat.adc} file in the current directory. This behavior provides
the required behavior described in the RM for the actions to be taken
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{58,,Handling of Configuration Pragmas}.
+@code{gnat.adc} file, see @ref{3f,,Handling of Configuration Pragmas}.
-Second, in compilation mode, if @cite{gnatchop}
+Second, in compilation mode, if @code{gnatchop}
is given a file that starts with
configuration pragmas, and contains one or more units, then these
configuration pragmas are prepended to each of the chopped files. This
pragmas other than those preceding the first compilation unit of a
compilation.
-For most purposes, @cite{gnatchop} will be used in default mode. The
+For most purposes, @code{gnatchop} will be used in default mode. The
compilation mode described above is used only if you need exactly
accurate behavior with respect to compilations, and you have files
that contain multiple units and configuration pragmas. In this
-circumstance the use of @cite{gnatchop} with the compilation mode
+circumstance the use of @code{gnatchop} with the compilation mode
switch provides the required behavior, and is for example the mode
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{73}@anchor{gnat_ugn/the_gnat_compilation_model command-line-for-gnatchop}@anchor{74}
-@subsubsection Command Line for @cite{gnatchop}
+@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}
-The @cite{gnatchop} command has the form:
+The @code{gnatchop} command has the form:
@example
$ gnatchop switches file_name [file_name ...]
contains one or more Ada units, in normal GNAT format, concatenated
together. As shown, more than one file may be presented to be chopped.
-When run in default mode, @cite{gnatchop} generates one output file in
+When run in default mode, @code{gnatchop} generates one output file in
the current directory for each unit in each of the files.
-@cite{directory}, if specified, gives the name of the directory to which
+@code{directory}, if specified, gives the name of the directory to which
the output files will be written. If it is not specified, all files are
written to the current directory.
@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{75}@anchor{gnat_ugn/the_gnat_compilation_model id26}@anchor{76}
-@subsubsection Switches for @cite{gnatchop}
+@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}
-@emph{gnatchop} recognizes the following switches:
+@code{gnatchop} recognizes the following switches:
@geindex --version (gnatchop)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-c}
-Causes @cite{gnatchop} to operate in compilation mode, in which
+Causes @code{gnatchop} to operate in compilation mode, in which
configuration pragmas are handled according to strict RM rules. See
previous section for a full description of this mode.
@item @code{-gnat@emph{xxx}}
-This passes the given @emph{-gnat`xxx*` switch to `gnat` which is
-used to parse the given file. Not all `xxx` options make sense,
-but for example, the use of *-gnati2} allows @cite{gnatchop} to
+This passes the given @code{-gnat@emph{xxx}} switch to @code{gnat} which is
+used to parse the given file. Not all @emph{xxx} options make sense,
+but for example, the use of @code{-gnati2} allows @code{gnatchop} to
process a source file that uses Latin-2 coding for identifiers.
@item @code{-h}
-Causes @cite{gnatchop} to generate a brief help summary to the standard
+Causes @code{gnatchop} to generate a brief help summary to the standard
output file showing usage information.
@end table
@item @code{-k@emph{mm}}
-Limit generated file names to the specified number @cite{mm}
+Limit generated file names to the specified number @code{mm}
of characters.
This is useful if the
resulting set of files is required to be interoperable with systems
which limit the length of file names.
-No space is allowed between the @emph{-k} and the numeric value. The numeric
-value may be omitted in which case a default of @emph{-k8},
+No space is allowed between the @code{-k} and the numeric value. The numeric
+value may be omitted in which case a default of @code{-k8},
suitable for use
-with DOS-like file systems, is used. If no @emph{-k} switch
+with DOS-like file systems, is used. If no @code{-k} switch
is present then
there is no limit on the length of file names.
@end table
Causes the file modification time stamp of the input file to be
preserved and used for the time stamp of the output file(s). This may be
useful for preserving coherency of time stamps in an environment where
-@cite{gnatchop} is used as part of a standard build process.
+@code{gnatchop} is used as part of a standard build process.
@end table
@geindex -q (gnatchop)
@item @code{-r}
-Generate @cite{Source_Reference} pragmas. Use this switch if the output
+Generate @code{Source_Reference} pragmas. Use this switch if the output
files are regarded as temporary and development is to be done in terms
of the original unchopped file. This switch causes
-@cite{Source_Reference} pragmas to be inserted into each of the
+@code{Source_Reference} pragmas to be inserted into each of the
generated files to refers back to the original file name and line number.
The result is that all error messages refer back to the original
unchopped file.
In addition, the debugging information placed into the object file (when
-the @emph{-g} switch of @emph{gcc} or @emph{gnatmake} is
+the @code{-g} switch of @code{gcc} or @code{gnatmake} is
specified)
also refers back to this original file so that tools like profilers and
debuggers will give information in terms of the original unchopped file.
If the original file to be chopped itself contains
-a @cite{Source_Reference}
+a @code{Source_Reference}
pragma referencing a third file, then gnatchop respects
-this pragma, and the generated @cite{Source_Reference} pragmas
+this pragma, and the generated @code{Source_Reference} pragmas
in the chopped file refer to the original file, with appropriate
-line numbers. This is particularly useful when @cite{gnatchop}
-is used in conjunction with @cite{gnatprep} to compile files that
+line numbers. This is particularly useful when @code{gnatchop}
+is used in conjunction with @code{gnatprep} to compile files that
contain preprocessing statements and multiple units.
@end table
@item @code{-v}
-Causes @cite{gnatchop} to operate in verbose mode. The version
+Causes @code{gnatchop} to operate in verbose mode. The version
number and copyright notice are output, as well as exact copies of
the gnat1 commands spawned to obtain the chop control information.
@end table
@item @code{-w}
-Overwrite existing file names. Normally @cite{gnatchop} regards it as a
+Overwrite existing file names. Normally @code{gnatchop} regards it as a
fatal error if there is already a file with the same name as a
file it would otherwise output, in other words if the files to be
chopped contain duplicated units. This switch bypasses this
@end table
@node Examples of gnatchop Usage,,Switches for gnatchop,Renaming Files with gnatchop
-@anchor{gnat_ugn/the_gnat_compilation_model id27}@anchor{77}@anchor{gnat_ugn/the_gnat_compilation_model examples-of-gnatchop-usage}@anchor{78}
-@subsubsection Examples of @cite{gnatchop} Usage
+@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
@example
Chops the source file @code{archive}
into the current directory. One
-useful application of @cite{gnatchop} is in sending sets of sources
+useful application of @code{gnatchop} is in sending sets of sources
around, for example in email messages. The required sources are simply
-concatenated (for example, using a Unix @cite{cat}
+concatenated (for example, using a Unix @code{cat}
command), and then
-@emph{gnatchop} is used at the other end to reconstitute the original
+@code{gnatchop} is used at the other end to reconstitute the original
file names.
@example
the resulting files in the directory @code{direc}. Note that if any units
occur more than once anywhere within this set of files, an error message
is generated, and no files are written. To override this check, use the
-@emph{-w} switch,
+@code{-w} switch,
in which case the last occurrence in the last file will
be the one that is output, and earlier duplicate occurrences for a given
unit will be skipped.
@node Configuration Pragmas,Generating Object Files,File Naming Topics and Utilities,The GNAT Compilation Model
-@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{79}@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{16}
+@anchor{gnat_ugn/the_gnat_compilation_model id28}@anchor{60}@anchor{gnat_ugn/the_gnat_compilation_model configuration-pragmas}@anchor{25}
@section Configuration Pragmas
Configuration pragmas include those pragmas described as
such in the Ada Reference Manual, as well as
implementation-dependent pragmas that are configuration pragmas.
-See the @cite{Implementation_Defined_Pragmas} chapter in the
+See the @code{Implementation_Defined_Pragmas} chapter in the
@cite{GNAT_Reference_Manual} for details on these
additional GNAT-specific configuration pragmas.
-Most notably, the pragma @cite{Source_File_Name}, which allows
+Most notably, the pragma @code{Source_File_Name}, which allows
specifying non-default names for source files, is a configuration
pragma. The following is a complete list of configuration pragmas
recognized by GNAT:
Assertion_Policy
Assume_No_Invalid_Values
C_Pass_By_Copy
+Check_Float_Overflow
Check_Name
Check_Policy
Compile_Time_Error
Compile_Time_Warning
Compiler_Unit
+Compiler_Unit_Warning
Component_Alignment
Convention_Identifier
Debug_Policy
Detect_Blocking
+Default_Scalar_Storage_Order
Default_Storage_Pool
+Disable_Atomic_Synchronization
Discard_Names
Elaboration_Checks
Eliminate
+Enable_Atomic_Synchronization
Extend_System
Extensions_Allowed
External_Name_Casing
Fast_Math
Favor_Top_Level
-Float_Representation
+Ignore_Pragma
Implicit_Packing
Initialize_Scalars
Interrupt_State
License
Locking_Policy
-Long_Float
+No_Component_Reordering
+No_Heap_Finalization
No_Run_Time
No_Strict_Aliasing
Normalize_Scalars
Optimize_Alignment
+Overflow_Mode
+Overriding_Renamings
+Partition_Elaboration_Policy
Persistent_BSS
-Polling
+Prefix_Exception_Messages
Priority_Specific_Dispatching
Profile
Profile_Warnings
Propagate_Exceptions
Queuing_Policy
+Rational
Ravenscar
+Rename_Pragma
Restricted_Run_Time
Restrictions
Restrictions_Warnings
Reviewable
Short_Circuit_And_Or
+Short_Descriptors
Source_File_Name
Source_File_Name_Project
SPARK_Mode
Suppress
Suppress_Exception_Locations
Task_Dispatching_Policy
+Unevaluated_Use_Of_Old
Universal_Data
Unsuppress
Use_VADS_Size
Validity_Checks
+Warning_As_Error
Warnings
Wide_Character_Encoding
@end example
@end menu
@node Handling of Configuration Pragmas,The Configuration Pragmas Files,,Configuration Pragmas
-@anchor{gnat_ugn/the_gnat_compilation_model id29}@anchor{7a}@anchor{gnat_ugn/the_gnat_compilation_model handling-of-configuration-pragmas}@anchor{58}
+@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
unit, or they can appear in a configuration pragma file to apply to
all compilations performed in a given compilation environment.
-GNAT also provides the @cite{gnatchop} utility to provide an automatic
+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{71,,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.
-In the case of @cite{Restrictions} pragmas appearing as configuration
+In the case of @code{Restrictions} pragmas appearing as configuration
pragmas in individual compilation units, the exact handling depends on
the type of restriction.
Restrictions that require partition-wide consistency (like
-@cite{No_Tasking}) are
+@code{No_Tasking}) are
recognized wherever they appear
and can be freely inherited, e.g. from a @emph{with}ed unit to the @emph{with}ing
unit. This makes sense since the binder will in any case insist on seeing
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{7b}@anchor{gnat_ugn/the_gnat_compilation_model id30}@anchor{7c}
+@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
directory is searched for a file whose name is @code{gnat.adc}. If
this file is present, it is expected to contain one or more
configuration pragmas that will be applied to the current compilation.
-However, if the switch @emph{-gnatA} is used, @code{gnat.adc} is not
+However, if the switch @code{-gnatA} is used, @code{gnat.adc} is not
considered. When taken into account, @code{gnat.adc} is added to the
dependencies, so that if @code{gnat.adc} is modified later, an invocation of
-@emph{gnatmake} will recompile the source.
+@code{gnatmake} will recompile the source.
Configuration pragmas may be entered into the @code{gnat.adc} file
-either by running @cite{gnatchop} on a source file that consists only of
+either by running @code{gnatchop} on a source file that consists only of
configuration pragmas, or more conveniently by direct editing of the
@code{gnat.adc} file, which is a standard format source file.
Besides @code{gnat.adc}, additional files containing configuration
pragmas may be applied to the current compilation using the switch
-@code{-gnatec=@emph{path}} where @cite{path} must designate an existing file that
+@code{-gnatec=@emph{path}} where @code{path} must designate an existing file that
contains only configuration pragmas. These configuration pragmas are
in addition to those found in @code{gnat.adc} (provided @code{gnat.adc}
-is present and switch @emph{-gnatA} is not used).
+is present and switch @code{-gnatA} is not used).
-It is allowable to specify several switches @emph{-gnatec=}, all of which
+It is allowable to specify several switches @code{-gnatec=}, all of which
will be taken into account.
Files containing configuration pragmas specified with switches
-@emph{-gnatec=} are added to the dependencies, unless they are
+@code{-gnatec=} are added to the dependencies, unless they are
temporary files. A file is considered temporary if its name ends in
@code{.tmp} or @code{.TMP}. Certain tools follow this naming
-convention because they pass information to @emph{gcc} via
+convention because they pass information to @code{gcc} via
temporary files that are immediately deleted; it doesn't make sense to
depend on a file that no longer exists. Such tools include
-@emph{gprbuild}, @emph{gnatmake}, and @emph{gnatcheck}.
+@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, see @ref{7d,,Specifying Configuration Pragmas} for more
-details.
+project attributes.
+
+@c --Comment
+@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{42}@anchor{gnat_ugn/the_gnat_compilation_model id31}@anchor{7e}
+@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
GNAT provides an option for compiling such files purely for the
purposes of checking correctness; such compilations are not required as
part of the process of building a program. To compile a file in this
-checking mode, use the @emph{-gnatc} switch.
+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{7f}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{43}
+@anchor{gnat_ugn/the_gnat_compilation_model id32}@anchor{65}@anchor{gnat_ugn/the_gnat_compilation_model source-dependencies}@anchor{27}
@section Source Dependencies
A given object file clearly depends on the source file which is compiled
to produce it. Here we are using "depends" in the sense of a typical
-@cite{make} utility; in other words, an object file depends on a source
+@code{make} utility; in other words, an object file depends on a source
file if changes to the source file require the object file to be
recompiled.
In addition to this basic dependency, a given object may depend on
@itemize *
@item
-If a file being compiled @emph{with}s a unit @cite{X}, the object file
-depends on the file containing the spec of unit @cite{X}. This includes
+If a file being compiled @emph{with}s a unit @code{X}, the object file
+depends on the file containing the spec of unit @code{X}. This includes
files that are @emph{with}ed implicitly either because they are parents
of @emph{with}ed child units or they are run-time units required by the
language constructs used in a particular unit.
@item
If a file being compiled contains a call to a subprogram for which
-pragma @cite{Inline} applies and inlining is activated with the
-@emph{-gnatn} switch, the object file depends on the file containing the
+pragma @code{Inline} applies and inlining is activated with the
+@code{-gnatn} switch, the object file depends on the file containing the
body of this subprogram as well as on the file containing the spec. Note
that for inlining to actually occur as a result of the use of this switch,
it is necessary to compile in optimizing mode.
@geindex -gnatN switch
-The use of @emph{-gnatN} activates inlining optimization
+The use of @code{-gnatN} activates inlining optimization
that is performed by the front end of the compiler. This inlining does
-not require that the code generation be optimized. Like @emph{-gnatn},
+not require that the code generation be optimized. Like @code{-gnatn},
the use of this switch generates additional dependencies.
When using a gcc-based back end (in practice this means using any version
of GNAT other than for the JVM, .NET or GNAAMP platforms), then the use of
-@emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred.
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
The previous two rules meant that for purposes of computing dependencies and
recompilation, a body and all its subunits are treated as an indivisible whole.
-These rules are applied transitively: if unit @cite{A} @emph{with}s
-unit @cite{B}, whose elaboration calls an inlined procedure in package
-@cite{C}, the object file for unit @cite{A} will depend on the body of
-@cite{C}, in file @code{c.adb}.
+These rules are applied transitively: if unit @code{A} @emph{with}s
+unit @code{B}, whose elaboration calls an inlined procedure in package
+@code{C}, the object file for unit @code{A} will depend on the body of
+@code{C}, in file @code{c.adb}.
The set of dependent files described by these rules includes all the
files on which the unit is semantically dependent, as dictated by the
An object file must be recreated by recompiling the corresponding source
file if any of the source files on which it depends are modified. For
-example, if the @cite{make} utility is used to control compilation,
+example, if the @code{make} utility is used to control compilation,
the rule for an Ada object file must mention all the source files on
which the object file depends, according to the above definition.
The determination of the necessary
-recompilations is done automatically when one uses @emph{gnatmake}.
+recompilations is done automatically when one uses @code{gnatmake}.
@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{80}@anchor{gnat_ugn/the_gnat_compilation_model the-ada-library-information-files}@anchor{44}
+@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
as well as the wide character encoding used during compilation).
@item
-List of arguments used in the @emph{gcc} command for the compilation
+List of arguments used in the @code{gcc} command for the compilation
@item
Attributes of the unit, including configuration pragmas used, an indication
checking.
@item
-Categorization information (e.g., use of pragma @cite{Pure}).
+Categorization information (e.g., use of pragma @code{Pure}).
@item
Information on all @emph{with}ed units, including presence of
-Elaborate` or @cite{Elaborate_All} pragmas.
+@code{Elaborate} or @code{Elaborate_All} pragmas.
@item
-Information from any @cite{Linker_Options} pragmas used in the unit
+Information from any @code{Linker_Options} pragmas used in the unit
@item
-Information on the use of @cite{Body_Version} or @cite{Version}
+Information on the use of @code{Body_Version} or @code{Version}
attributes in the unit.
@item
@item
Cross-reference data. Contains information on all entities referenced
-in the unit. Used by tools like @cite{gnatxref} and @cite{gnatfind} to
+in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to
provide cross-reference information.
@end itemize
For a full detailed description of the format of the @code{ALI} file,
-see the source of the body of unit @cite{Lib.Writ}, contained in file
+see the source of the body of unit @code{Lib.Writ}, contained in file
@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{81}@anchor{gnat_ugn/the_gnat_compilation_model binding-an-ada-program}@anchor{45}
+@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
a call to the main program. This Ada program is compiled to generate the
object file for the main program. The name of
the Ada file is @code{b~xxx}.adb` (with the corresponding spec
-@code{b~xxx}.ads`) where @cite{xxx} is the name of the
+@code{b~xxx}.ads`) where @code{xxx} is the name of the
main program unit.
Finally, the linker is used to build the resulting executable 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{17}@anchor{gnat_ugn/the_gnat_compilation_model id35}@anchor{82}
+@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
@geindex Library building and using
-This chapter describes how to build and use libraries with GNAT, and also shows
+This section describes how to build and use libraries with GNAT, and also shows
how to recompile the GNAT run-time library. You should be familiar with the
-Project Manager facility (@ref{b,,GNAT Project Manager}) before reading this
-chapter.
+Project Manager facility (see the @emph{GNAT_Project_Manager} chapter of the
+@emph{GPRbuild User's Guide}) before reading this chapter.
@menu
* Introduction to Libraries in GNAT::
@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{83}@anchor{gnat_ugn/the_gnat_compilation_model id36}@anchor{84}
+@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{44,,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{85,,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{86}@anchor{gnat_ugn/the_gnat_compilation_model id37}@anchor{87}
+@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{88}@anchor{gnat_ugn/the_gnat_compilation_model id38}@anchor{89}
+@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
The easiest way to build a library is to use the Project Manager,
which supports a special type of project called a @emph{Library Project}
-(see @ref{8a,,Library Projects}).
+(see the @emph{Library Projects} section in the @emph{GNAT Project Manager}
+chapter of the @emph{GPRbuild User's Guide}).
A project is considered a library project, when two project-level attributes
-are defined in it: @cite{Library_Name} and @cite{Library_Dir}. In order to
+are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to
control different aspects of library configuration, additional optional
project-level attributes can be specified:
@table @asis
-@item @emph{Library_Kind}
+@item @code{Library_Kind}
This attribute controls whether the library is to be static or dynamic
@end table
@table @asis
-@item @emph{Library_Version}
+@item @code{Library_Version}
This attribute specifies the library version; this value is used
during dynamic linking of shared libraries to determine if the currently
@end table
@item
-@emph{Library_Options}
+@code{Library_Options}
@item
@table @asis
-@item @emph{Library_GCC}
+@item @code{Library_GCC}
These attributes specify additional low-level options to be used during
library generation, and redefine the actual application used to generate
steps are discussed below.
There are various possibilities for compiling the units that make up the
-library: for example with a Makefile (@ref{21,,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
-@emph{gnatmake}, which will ensure that all necessary objects are built.
+@code{gnatmake}, which will ensure that all necessary objects are built.
After this task is accomplished, you should follow the standard procedure
of the underlying operating system to produce the static or shared library.
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{8b}@anchor{gnat_ugn/the_gnat_compilation_model id39}@anchor{8c}
+@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
@geindex GPR_PROJECT_PATH
If you use project files, library installation is part of the library build
-process (@ref{8d,,Installing a library with project files}).
+process (see the @emph{Installing a Library with Project Files} section of the
+@emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}).
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{8e,,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
be @code{adalib}).
You can also specify a new default path to the run-time library at compilation
-time with the switch @emph{--RTS=rts-path}. You can thus choose / change
+time with the switch @code{--RTS=rts-path}. You can thus choose / change
the run-time library you want your program to be compiled with. This switch is
-recognized by @emph{gcc}, @emph{gnatmake}, @emph{gnatbind},
-@emph{gnatls}, @emph{gnatfind} and @emph{gnatxref}.
+recognized by @code{gcc}, @code{gnatmake}, @code{gnatbind},
+@code{gnatls}, @code{gnatfind} and @code{gnatxref}.
It is possible to install a library before or after the standard GNAT
library, by reordering the lines in the configuration files. In general, a
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{8f}@anchor{gnat_ugn/the_gnat_compilation_model id40}@anchor{90}
+@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
Once again, the project facility greatly simplifies the use of
libraries. In this context, using a library is just a matter of adding a
@emph{with} clause in the user project. For instance, to make use of the
-library @cite{My_Lib} shown in examples in earlier sections, you can
+library @code{My_Lib} shown in examples in earlier sections, you can
write:
@example
end Liba;
@end example
-This is an alternative to the use of @cite{pragma Linker_Options}. It is
+This is an alternative to the use of @code{pragma Linker_Options}. It is
especially interesting in the context of systems with several interdependent
static libraries where finding a proper linker order is not easy and best be
left to the tools having visibility over project dependence information.
In order to use an Ada library manually, you need to make sure that this
library is on both your source and object path
-(see @ref{8e,,Search Paths and the Run-Time Library (RTL)}
-and @ref{91,,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.
@code{ada_object_path}
@item
-a pragma @cite{Linker_Options} has been added to one of the sources.
+a pragma @code{Linker_Options} has been added to one of the sources.
For example:
@example
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{85}@anchor{gnat_ugn/the_gnat_compilation_model id41}@anchor{92}
+@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{93}@anchor{gnat_ugn/the_gnat_compilation_model id42}@anchor{94}
+@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
applications when a new version of the library is installed. Specifically,
if the interface sources have not changed, client applications do not need to
be recompiled. If, furthermore, a SAL is provided in the shared form and its
-version, controlled by @cite{Library_Version} attribute, is not changed,
+version, controlled by @code{Library_Version} attribute, is not changed,
then the clients do not need to be relinked.
SALs also allow the library providers to minimize the amount of library source
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{95}@anchor{gnat_ugn/the_gnat_compilation_model building-a-stand-alone-library}@anchor{96}
+@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
GNAT's Project facility provides a simple way of building and installing
-stand-alone libraries; see @ref{97,,Stand-alone Library Projects}.
+stand-alone libraries; see the @emph{Stand-alone Library Projects} section
+in the @emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}.
To be a Stand-alone Library Project, in addition to the two attributes
-that make a project a Library Project (@cite{Library_Name} and
-@cite{Library_Dir}; see @ref{8a,,Library Projects}), the attribute
-@cite{Library_Interface} must be defined. For example:
+that make a project a Library Project (@code{Library_Name} and
+@code{Library_Dir}; see the @emph{Library Projects} section in the
+@emph{GNAT Project Manager} chapter of the @emph{GPRbuild User's Guide}),
+the attribute @code{Library_Interface} must be defined. For example:
@example
for Library_Dir use "lib_dir";
for Library_Interface use ("int1", "int1.child");
@end example
-Attribute @cite{Library_Interface} has a non-empty string list value,
+Attribute @code{Library_Interface} has a non-empty string list value,
each string in the list designating a unit contained in an immediate source
of the project file.
(@code{b~dummy.ads/b} in the example above).
This binder-generated package includes initialization and
finalization procedures whose
-names depend on the library name (@cite{dummyinit} and @cite{dummyfinal}
+names depend on the library name (@code{dummyinit} and @code{dummyfinal}
in the example
above). The object corresponding to this package is included in the library.
You must ensure timely (e.g., prior to any use of interfaces in the SAL)
calling of these procedures if a static SAL is built, or if a shared SAL
is built
-with the project-level attribute @cite{Library_Auto_Init} set to
-@cite{"false"}.
+with the project-level attribute @code{Library_Auto_Init} set to
+@code{"false"}.
For a Stand-Alone Library, only the @code{ALI} files of the Interface Units
-(those that are listed in attribute @cite{Library_Interface}) are copied to
+(those that are listed in attribute @code{Library_Interface}) are copied to
the Library Directory. As a consequence, only the Interface Units may be
imported from Ada units outside of the library. If other units are imported,
the binding phase will fail.
libraries. So an encapsulated library only depends on system
libraries, all other code, including the GNAT runtime, is embedded. To
build an encapsulated library the attribute
-@cite{Library_Standalone} must be set to @cite{encapsulated}:
+@code{Library_Standalone} must be set to @code{encapsulated}:
@example
for Library_Dir use "lib_dir";
for Library_Standalone use "encapsulated";
@end example
-The default value for this attribute is @cite{standard} in which case
+The default value for this attribute is @code{standard} in which case
a stand-alone library is built.
-The attribute @cite{Library_Src_Dir} may be specified for a
-Stand-Alone Library. @cite{Library_Src_Dir} is a simple attribute that has a
+The attribute @code{Library_Src_Dir} may be specified for a
+Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
single string value. Its value must be the path (absolute or relative to the
project directory) of an existing directory. This directory cannot be the
object directory or one of the source directories, but it can be the same as
Units of the library that are needed by an Ada client of the library will be
copied to the designated directory, called the Interface Copy directory.
These sources include the specs of the Interface Units, but they may also
-include bodies and subunits, when pragmas @cite{Inline} or @cite{Inline_Always}
+include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
are used, or when there is a generic unit in the spec. Before the sources
are copied to the Interface Copy directory, an attempt is made to delete all
files in the Interface Copy directory.
Compile all library sources.
@item
-Invoke the binder with the switch @emph{-n} (No Ada main program),
+Invoke the binder with the switch @code{-n} (No Ada main program),
with all the @code{ALI} files of the interfaces, and
-with the switch @emph{-L} to give specific names to the @cite{init}
-and @cite{final} procedures. For example:
+with the switch @code{-L} to give specific names to the @code{init}
+and @code{final} procedures. For example:
@example
$ gnatbind -n int1.ali int2.ali -Lsal1
@item
Link the dynamic library with all the necessary object files,
-indicating to the linker the names of the @cite{init} (and possibly
-@cite{final}) procedures for automatic initialization (and finalization).
+indicating to the linker the names of the @code{init} (and possibly
+@code{final}) procedures for automatic initialization (and finalization).
The built library should be placed in a directory different from
the object directory.
@item
-Copy the @cite{ALI} files of the interface to the library directory,
+Copy the @code{ALI} files of the interface to the library directory,
add in this copy an indication that it is an interface to a SAL
-(i.e., add a word @emph{SL} on the line in the @code{ALI} file that starts
+(i.e., add a word @code{SL} on the line in the @code{ALI} file that starts
with letter 'P') and make the modified copy of the @code{ALI} file
read-only.
@end itemize
Using SALs is not different from using other libraries
-(see @ref{8f,,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{98}@anchor{gnat_ugn/the_gnat_compilation_model id44}@anchor{99}
+@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
a non-Ada context.
The only extra step required is to ensure that library interface subprograms
-are compatible with the main program, by means of @cite{pragma Export}
-or @cite{pragma Convention}.
+are compatible with the main program, by means of @code{pragma Export}
+or @code{pragma Convention}.
Here is an example of simple library interface for use with C main program:
library interface; remember that it should contain elaboration routines in
addition to interface subprograms.
-The example below shows the content of @cite{mylib_interface.h} (note
+The example below shows the content of @code{mylib_interface.h} (note
that there is no rule for the naming of this file, any name can be used)
@example
@end example
Libraries built as explained above can be used from any program, provided
-that the elaboration procedures (named @cite{mylibinit} in the previous
+that the elaboration procedures (named @code{mylibinit} in the previous
example) are called before the library services are used. Any number of
libraries can be used simultaneously, as long as the elaboration
procedure of each library is called.
-Below is an example of a C program that uses the @cite{mylib} library.
+Below is an example of a C program that uses the @code{mylib} library.
@example
#include "mylib_interface.h"
@end example
Note that invoking any library finalization procedure generated by
-@cite{gnatbind} shuts down the Ada run-time environment.
+@code{gnatbind} shuts down the Ada run-time environment.
Consequently, the
finalization of all Ada libraries must be performed at the end of the program.
No call to these libraries or to the Ada run-time library should be made
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{9a}@anchor{gnat_ugn/the_gnat_compilation_model restrictions-in-stand-alone-libraries}@anchor{9b}
+@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
@itemize *
@item
-pragma @cite{Locking_Policy}
+pragma @code{Locking_Policy}
@item
-pragma @cite{Partition_Elaboration_Policy}
+pragma @code{Partition_Elaboration_Policy}
@item
-pragma @cite{Queuing_Policy}
+pragma @code{Queuing_Policy}
@item
-pragma @cite{Task_Dispatching_Policy}
+pragma @code{Task_Dispatching_Policy}
@item
-pragma @cite{Unreserve_All_Interrupts}
+pragma @code{Unreserve_All_Interrupts}
@end itemize
When using a library that contains such pragmas, the user must make sure
that all libraries use the same pragmas with the same values. Otherwise,
-@cite{Program_Error} will
+@code{Program_Error} will
be raised during the elaboration of the conflicting
libraries. The usage of these pragmas and its consequences for the user
should therefore be well documented.
Otherwise, Program_Error will be raised during the elaboration of the
conflicting libraries.
-If the @cite{Version} or @cite{Body_Version}
+If the @code{Version} or @code{Body_Version}
attributes are used inside a library, then you need to
-perform a @cite{gnatbind} step that specifies all @code{ALI} files in all
+perform a @code{gnatbind} step that specifies all @code{ALI} files in all
libraries, so that version identifiers can be properly computed.
In practice these attributes are rarely used, so this is unlikely
to be a consideration.
@node Rebuilding the GNAT Run-Time Library,,Stand-alone Ada Libraries,GNAT and Libraries
-@anchor{gnat_ugn/the_gnat_compilation_model id46}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model rebuilding-the-gnat-run-time-library}@anchor{9d}
+@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 @cite{Normalize_Scalars}. A special Makefile called
-@cite{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{9e}@anchor{gnat_ugn/the_gnat_compilation_model conditional-compilation}@anchor{18}
+@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{9f}@anchor{gnat_ugn/the_gnat_compilation_model id48}@anchor{a0}
+@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{a1}@anchor{gnat_ugn/the_gnat_compilation_model use-of-boolean-constants}@anchor{a2}
+@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
end if;
@end example
-Not only will the code inside the @cite{if} statement not be executed if
-the constant Boolean is @cite{False}, but it will also be completely
+Not only will the code inside the @code{if} statement not be executed if
+the constant Boolean is @code{False}, but it will also be completely
deleted from the program.
-However, the code is only deleted after the @cite{if} statement
+However, the code is only deleted after the @code{if} statement
has been checked for syntactic and semantic correctness.
(In contrast, with preprocessors the code is deleted before the
compiler ever gets to see it, so it is not checked until the switch
end Config;
@end example
-The @cite{Config} package exists in multiple forms for the various targets,
-with an appropriate script selecting the version of @cite{Config} needed.
+The @code{Config} package exists in multiple forms for the various targets,
+with an appropriate script selecting the version of @code{Config} needed.
Then any other unit requiring conditional compilation can do a @emph{with}
-of @cite{Config} to make the constants visible.
+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{a3}@anchor{gnat_ugn/the_gnat_compilation_model id50}@anchor{a4}
+@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
Since this is a common case, there are special features to deal with
this in a convenient manner. For the case of tests, Ada 2005 has added
-a pragma @cite{Assert} that can be used for such tests. This pragma is modeled
-on the @cite{Assert} pragma that has always been available in GNAT, so this
+a pragma @code{Assert} that can be used for such tests. This pragma is modeled
+on the @code{Assert} pragma that has always been available in GNAT, so this
feature may be used with GNAT even if you are not using Ada 2005 features.
-The use of pragma @cite{Assert} is described in the
+The use of pragma @code{Assert} is described in the
@cite{GNAT_Reference_Manual}, but as an
example, the last test could be written:
@end example
In both cases, if assertions are active and the temperature is excessive,
-the exception @cite{Assert_Failure} will be raised, with the given string in
+the exception @code{Assert_Failure} will be raised, with the given string in
the first case or a string indicating the location of the pragma in the second
case used as the exception message.
@geindex pragma Assertion_Policy
-You can turn assertions on and off by using the @cite{Assertion_Policy}
+You can turn assertions on and off by using the @code{Assertion_Policy}
pragma.
@geindex -gnata switch
This is an Ada 2005 pragma which is implemented in all modes by
-GNAT. Alternatively, you can use the @emph{-gnata} switch
+GNAT. Alternatively, you can use the @code{-gnata} switch
to enable assertions from the command line, which applies to
all versions of Ada.
@geindex pragma Debug
-For the example above with the @cite{Put_Line}, the GNAT-specific pragma
-@cite{Debug} can be used:
+For the example above with the @code{Put_Line}, the GNAT-specific pragma
+@code{Debug} can be used:
@example
pragma Debug (Put_Line ("got to the first stage!"));
@end example
If debug pragmas are enabled, the argument, which must be of the form of
-a procedure call, is executed (in this case, @cite{Put_Line} will be called).
+a procedure call, is executed (in this case, @code{Put_Line} will be called).
Only one call can be present, but of course a special debugging procedure
containing any code you like can be included in the program and then
-called in a pragma @cite{Debug} argument as needed.
+called in a pragma @code{Debug} argument as needed.
-One advantage of pragma @cite{Debug} over the @cite{if Debugging then}
-construct is that pragma @cite{Debug} can appear in declarative contexts,
+One advantage of pragma @code{Debug} over the @code{if Debugging then}
+construct is that pragma @code{Debug} can appear in declarative contexts,
such as at the very beginning of a procedure, before local declarations have
been elaborated.
@geindex pragma Debug_Policy
-Debug pragmas are enabled using either the @emph{-gnata} switch that also
+Debug pragmas are enabled using either the @code{-gnata} switch that also
controls assertions, or with a separate Debug_Policy pragma.
The latter pragma is new in the Ada 2005 versions of GNAT (but it can be used
in Ada 95 and Ada 83 programs as well), and is analogous to
-pragma @cite{Assertion_Policy} to control assertions.
+pragma @code{Assertion_Policy} to control assertions.
-@cite{Assertion_Policy} and @cite{Debug_Policy} are configuration pragmas,
+@code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas,
and thus they can appear in @code{gnat.adc} if you are not using a
project file, or in the file designated to contain configuration pragmas
in a project file.
They then apply to all subsequent compilations. In practice the use of
-the @emph{-gnata} switch is often the most convenient method of controlling
+the @code{-gnata} switch is often the most convenient method of controlling
the status of these pragmas.
Note that a pragma is not a statement, so in contexts where a statement
sequence is required, you can't just write a pragma on its own. You have
-to add a @cite{null} statement.
+to add a @code{null} statement.
@example
if ... then
@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{a5}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{a6}
+@anchor{gnat_ugn/the_gnat_compilation_model conditionalizing-declarations}@anchor{89}@anchor{gnat_ugn/the_gnat_compilation_model id51}@anchor{8a}
@subsubsection Conditionalizing Declarations
compiler so this can only be used where both declarations are legal,
even though one of them will not be used.
-Another approach is to define integer constants, e.g., @cite{Bits_Per_Word},
-or Boolean constants, e.g., @cite{Little_Endian}, and then write declarations
+Another approach is to define integer constants, e.g., @code{Bits_Per_Word},
+or Boolean constants, e.g., @code{Little_Endian}, and then write declarations
that are parameterized by these constants. For example
@example
end record;
@end example
-If @cite{Bits_Per_Word} is set to 32, this generates either
+If @code{Bits_Per_Word} is set to 32, this generates either
@example
for Rec use
notation is usable for creating static constants, clever use of this
feature can often solve quite difficult problems in conditionalizing
compilation (note incidentally that in Ada 95, the little endian
-constant was introduced as @cite{System.Default_Bit_Order}, so you do not
+constant was introduced as @code{System.Default_Bit_Order}, so you do not
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{a7}@anchor{gnat_ugn/the_gnat_compilation_model id52}@anchor{a8}
+@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
end if;
@end example
-where @cite{Ada_2005} is a Boolean constant.
+where @code{Ada_2005} is a Boolean constant.
-But this won't work when @cite{Ada_2005} is set to @cite{False},
-since the @cite{then} clause will be illegal for an Ada 95 compiler.
+But this won't work when @code{Ada_2005} is set to @code{False},
+since the @code{then} clause will be illegal for an Ada 95 compiler.
(Recall that although such unreachable code would eventually be deleted
by the compiler, it still needs to be legal. If it uses features
introduced in Ada 2005, it will be illegal in Ada 95.)
procedure Insert is separate;
@end example
-Then we have two files for the subunit @cite{Insert}, with the two sets of
+Then we have two files for the subunit @code{Insert}, with the two sets of
code.
-If the package containing this is called @cite{File_Queries}, then we might
+If the package containing this is called @code{File_Queries}, then we might
have two files
Another style for arranging alternative implementations is through Ada's
access-to-subprogram facility.
In case some functionality is to be conditionally included,
-you can declare an access-to-procedure variable @cite{Ref} that is initialized
-to designate a 'do nothing' procedure, and then invoke @cite{Ref.all}
+you can declare an access-to-procedure variable @code{Ref} that is initialized
+to designate a 'do nothing' procedure, and then invoke @code{Ref.all}
when appropriate.
-In some library package, set @cite{Ref} to @cite{Proc'Access} for some
-procedure @cite{Proc} that performs the relevant processing.
+In some library package, set @code{Ref} to @code{Proc'Access} for some
+procedure @code{Proc} that performs the relevant processing.
The initialization only occurs if the library package is included in the
program.
The same idea can also be implemented using tagged types and dispatching
calls.
@node Preprocessing,,Use of Alternative Implementations,Modeling Conditional Compilation in Ada
-@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{a9}@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{aa}
+@anchor{gnat_ugn/the_gnat_compilation_model preprocessing}@anchor{8d}@anchor{gnat_ugn/the_gnat_compilation_model id53}@anchor{8e}
@subsubsection Preprocessing
The preprocessor may be used in two separate modes. It can be used quite
separately from the compiler, to generate a separate output source file
that is then fed to the compiler as a separate step. This is the
-@cite{gnatprep} utility, whose use is fully described in
-@ref{19,,Preprocessing with gnatprep}.
+@code{gnatprep} utility, whose use is fully described in
+@ref{8f,,Preprocessing with gnatprep}.
The preprocessing language allows such constructs as
@example
#if DEBUG or else (PRIORITY > 4) then
- bunch of declarations
+ sequence of declarations
#else
- completely different bunch of declarations
+ completely different sequence of declarations
#end if;
@end example
-The values of the symbols @cite{DEBUG} and @cite{PRIORITY} can be
+The values of the symbols @code{DEBUG} and @code{PRIORITY} can be
defined either on the command line or in a separate file.
The other way of running the preprocessor is even closer to the C style and
often more convenient. In this approach the preprocessing is integrated into
-the compilation process. The compiler is fed the preprocessor input which
-includes @cite{#if} lines etc, and then the compiler carries out the
+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{1a,,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{ab}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-with-gnatprep}@anchor{19}
-@subsection Preprocessing with @cite{gnatprep}
+@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}
@geindex gnatprep
@geindex Preprocessing (gnatprep)
-This section discusses how to use GNAT's @cite{gnatprep} utility for simple
+This section discusses how to use GNAT's @code{gnatprep} utility for simple
preprocessing.
-Although designed for use with GNAT, @cite{gnatprep} does not depend on any
+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{18,,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{ac}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{ad}
+@anchor{gnat_ugn/the_gnat_compilation_model id55}@anchor{92}@anchor{gnat_ugn/the_gnat_compilation_model preprocessing-symbols}@anchor{93}
@subsubsection Preprocessing Symbols
-Preprocessing symbols are defined in definition files and referred to in
-sources to be preprocessed. A Preprocessing symbol is an identifier, following
+Preprocessing symbols are defined in @emph{definition files} and referenced in the
+sources to be preprocessed. A preprocessing symbol is an identifier, following
normal Ada (case-insensitive) rules for its syntax, with the restriction that
all characters need to be in the ASCII set (no accented letters).
@node Using gnatprep,Switches for gnatprep,Preprocessing Symbols,Preprocessing with gnatprep
-@anchor{gnat_ugn/the_gnat_compilation_model using-gnatprep}@anchor{ae}@anchor{gnat_ugn/the_gnat_compilation_model id56}@anchor{af}
-@subsubsection Using @cite{gnatprep}
+@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}
-To call @cite{gnatprep} use:
+To call @code{gnatprep} use:
@example
-$ gnatprep [`switches`] `infile` `outfile` [`deffile`]
+$ gnatprep [ switches ] infile outfile [ deffile ]
@end example
where
is the full name of the output file, which is an Ada source
in standard Ada form. When used with GNAT, this file name will
-normally have an ads or adb suffix.
+normally have an @code{ads} or @code{adb} suffix.
@end table
@item
@table @asis
-@item @emph{deffile}
+@item @code{deffile}
is the full name of a text file containing definitions of
preprocessing symbols to be referenced by the preprocessor. This argument is
-optional, and can be replaced by the use of the @emph{-D} switch.
+optional, and can be replaced by the use of the @code{-D} switch.
@end table
@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{b0}@anchor{gnat_ugn/the_gnat_compilation_model id57}@anchor{b1}
-@subsubsection Switches for @cite{gnatprep}
+@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}
+
+
+@geindex --version (gnatprep)
+
+
+@table @asis
+
+@item @code{--version}
+
+Display Copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatprep)
+@table @asis
+
+@item @code{--help}
+
+If @code{--version} was not used, display usage and then exit disregarding
+all other options.
+@end table
+
@geindex -b (gnatprep)
Causes both preprocessor lines and the lines deleted
by preprocessing to be retained in the output source as comments marked
-with the special string @cite{"--! "}. This option will result in line numbers
+with the special string @code{"--! "}. This option will result in line numbers
being preserved in the output file.
@end table
Causes comments to be scanned. Normally comments are ignored by gnatprep.
If this option is specified, then comments are scanned and any $symbol
substitutions performed as in program text. This is particularly useful
-when structured comments are used (e.g., when writing programs in the
-SPARK dialect of Ada). Note that this switch is not available when
-doing integrated preprocessing (it would be useless in this context
-since comments are ignored by the compiler in any case).
+when structured comments are used (e.g., for programs written in a
+pre-2014 version of the SPARK Ada subset). Note that this switch is not
+available when doing integrated preprocessing (it would be useless in
+this context since comments are ignored by the compiler in any case).
@end table
@geindex -D (gnatprep)
@table @asis
-@item @code{-D@emph{symbol}=@emph{value}}
+@item @code{-D@emph{symbol}[=@emph{value}]}
-Defines a new preprocessing symbol, associated with value. If no value is given
-on the command line, then symbol is considered to be @cite{True}. This switch
+Defines a new preprocessing symbol with the specified value. If no value is given
+on the command line, then symbol is considered to be @code{True}. This switch
can be used in place of a definition file.
@end table
@item @code{-r}
-Causes a @cite{Source_Reference} pragma to be generated that
+Causes a @code{Source_Reference} pragma to be generated that
references the original input file, so that error messages will use
the file name of this original file. The use of this switch implies
that preprocessor lines are not to be removed from the file, so its
-use will force @emph{-b} mode if @emph{-c}
+use will force @code{-b} mode if @code{-c}
has not been specified explicitly.
Note that if the file to be preprocessed contains multiple units, then
-it will be necessary to @cite{gnatchop} the output file from
-@cite{gnatprep}. If a @cite{Source_Reference} pragma is present
+it will be necessary to @code{gnatchop} the output file from
+@code{gnatprep}. If a @code{Source_Reference} pragma is present
in the preprocessed file, it will be respected by
-@cite{gnatchop -r}
+@code{gnatchop -r}
so that the final chopped files will correctly refer to the original
-input source file for @cite{gnatprep}.
+input source file for @code{gnatprep}.
@end table
@geindex -s (gnatprep)
listed on the standard output file.
@end table
+@geindex -T (gnatprep)
+
+
+@table @asis
+
+@item @code{-T}
+
+Use LF as line terminators when writing files. By default the line terminator
+of the host (LF under unix, CR/LF under Windows) is used.
+@end table
+
@geindex -u (gnatprep)
Causes undefined symbols to be treated as having the value FALSE in the context
of a preprocessor test. In the absence of this option, an undefined symbol in
-a @cite{#if} or @cite{#elsif} test will be treated as an error.
+a @code{#if} or @code{#elsif} test will be treated as an error.
+@end table
+
+@geindex -v (gnatprep)
+
+
+@table @asis
+
+@item @code{-v}
+
+Verbose mode: generates more output about work done.
@end table
-Note: if neither @emph{-b} nor @emph{-c} is present,
+Note: if neither @code{-b} nor @code{-c} is present,
then preprocessor lines and
deleted lines are completely removed from the output, unless -r is
specified, in which case -b is assumed.
@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{b2}@anchor{gnat_ugn/the_gnat_compilation_model id58}@anchor{b3}
+@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
symbol := value
@end example
-where @cite{symbol} is a preprocessing symbol, and @cite{value} is one of the following:
+where @code{symbol} is a preprocessing symbol, and @code{value} is one of the following:
@itemize *
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{b4}@anchor{gnat_ugn/the_gnat_compilation_model form-of-input-text-for-gnatprep}@anchor{b5}
-@subsubsection Form of Input Text for @cite{gnatprep}
+@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}
The input text may contain preprocessor conditional inclusion lines,
For the first test (<expression> ::= <symbol>) the symbol must have
either the value true or false, that is to say the right-hand of the
symbol definition must be one of the (case-insensitive) literals
-@cite{True} or @cite{False}. If the value is true, then the
+@code{True} or @code{False}. If the value is true, then the
corresponding lines are included, and if the value is false, they are
excluded.
in the range 0 .. 2**31-1 are supported.
The test (<expression> ::= <symbol>'Defined) is true only if
-the symbol has been defined in the definition file or by a @emph{-D}
+the symbol has been defined in the definition file or by a @code{-D}
switch on the command line. Otherwise, the test is false.
The equality tests are case insensitive, as are all the preprocessor lines.
If the symbol referenced is not defined in the symbol definitions file,
-then the effect depends on whether or not switch @emph{-u}
+then the effect depends on whether or not switch @code{-u}
is specified. If so, then the symbol is treated as if it had the value
false and the test fails. If this switch is not specified, then
it is an error to reference an undefined symbol. It is also an error to
-reference a symbol that is defined with a value other than @cite{True}
-or @cite{False}.
+reference a symbol that is defined with a value other than @code{True}
+or @code{False}.
-The use of the @cite{not} operator inverts the sense of this logical test.
-The @cite{not} operator cannot be combined with the @cite{or} or @cite{and}
+The use of the @code{not} operator inverts the sense of this logical test.
+The @code{not} operator cannot be combined with the @code{or} or @code{and}
operators, without parentheses. For example, "if not X or Y then" is not
allowed, but "if (not X) or Y then" and "if not (X or Y) then" are.
-The @cite{then} keyword is optional as shown
+The @code{then} keyword is optional as shown
-The @cite{#} must be the first non-blank character on a line, but
+The @code{#} must be the first non-blank character on a line, but
otherwise the format is free form. Spaces or tabs may appear between
-the @cite{#} and the keyword. The keywords and the symbols are case
+the @code{#} and the keyword. The keywords and the symbols are case
insensitive as in normal Ada code. Comments may be used on a
preprocessor line, but other than that, no other tokens may appear on a
-preprocessor line. Any number of @cite{elsif} clauses can be present,
-including none at all. The @cite{else} is optional, as in Ada.
+preprocessor line. Any number of @code{elsif} clauses can be present,
+including none at all. The @code{else} is optional, as in Ada.
-The @cite{#} marking the start of a preprocessor line must be the first
+The @code{#} marking the start of a preprocessor line must be the first
non-blank character on the line, i.e., it must be preceded only by
spaces or horizontal tabs.
anywhere within a source line, except in a comment or within a
string literal. The identifier
-following the @cite{$} must match one of the symbols defined in the symbol
+following the @code{$} must match one of the symbols defined in the symbol
definition file, and the result is to substitute the value of the
-symbol in place of @cite{$symbol} in the output file.
+symbol in place of @code{$symbol} in the output file.
Note that although the substitution of strings within a string literal
is not possible, it is possible to have a symbol whose defined value is
-a string literal. So instead of setting XYZ to @cite{hello} and writing:
+a string literal. So instead of setting XYZ to @code{hello} and writing:
@example
Header : String := "$XYZ";
@end example
-you should set XYZ to @cite{"hello"} and write:
+you should set XYZ to @code{"hello"} and write:
@example
Header : String := $XYZ;
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{b6}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{1a}
+@anchor{gnat_ugn/the_gnat_compilation_model id60}@anchor{9c}@anchor{gnat_ugn/the_gnat_compilation_model integrated-preprocessing}@anchor{90}
@subsection Integrated Preprocessing
-GNAT sources may be preprocessed immediately before compilation.
-In this case, the actual
-text of the source is not the text of the source file, but is derived from it
-through a process called preprocessing. Integrated preprocessing is specified
-through switches @emph{-gnatep} and/or @emph{-gnateD}. @emph{-gnatep}
-indicates, through a text file, the preprocessing data to be used.
-@code{-gnateD} specifies or modifies the values of preprocessing symbol.
-Note that integrated preprocessing applies only to Ada source files, it is
+As noted above, a file to be preprocessed consists of Ada source code
+in which preprocessing lines have been inserted. However,
+instead of using @code{gnatprep} to explicitly preprocess a file as a separate
+step before compilation, you can carry out the preprocessing implicitly
+as part of compilation. Such @emph{integrated preprocessing}, which is the common
+style with C, is performed when either or both of the following switches
+are passed to the compiler:
+
+@quotation
+
+
+@itemize *
+
+@item
+@code{-gnatep}, which specifies the @emph{preprocessor data file}.
+This file dictates how the source files will be preprocessed (e.g., which
+symbol definition files apply to which sources).
+
+@item
+@code{-gnateD}, which defines values for preprocessing symbols.
+@end itemize
+@end quotation
+
+Integrated preprocessing applies only to Ada source files, it is
not available for configuration pragma files.
-Note that when integrated preprocessing is used, the output from the
-preprocessor is not written to any external file. Instead it is passed
-internally to the compiler. If you need to preserve the result of
-preprocessing in a file, then you should use @emph{gnatprep}
-to perform the desired preprocessing in stand-alone mode.
+With integrated preprocessing, the output from the preprocessor is not,
+by default, written to any external file. Instead it is passed
+internally to the compiler. To preserve the result of
+preprocessing in a file, either run @code{gnatprep}
+in standalone mode or else supply the @code{-gnateG} switch
+(described below) to the compiler.
+
+When using project files:
+
+@quotation
+
+
+@itemize *
+
+@item
+the builder switch @code{-x} should be used if any Ada source is
+compiled with @code{gnatep=}, so that the compiler finds the
+@emph{preprocessor data file}.
-It is recommended that @emph{gnatmake} switch -s should be
-used when Integrated Preprocessing is used. The reason is that preprocessing
-with another Preprocessing Data file without changing the sources will
-not trigger recompilation without this switch.
+@item
+the preprocessing data file and the symbol definition files should be
+located in the source directories of the project.
+@end itemize
+@end quotation
-Note that @emph{gnatmake} switch -m will almost
+Note that the @code{gnatmake} switch @code{-m} will almost
always trigger recompilation for sources that are preprocessed,
-because @emph{gnatmake} cannot compute the checksum of the source after
+because @code{gnatmake} cannot compute the checksum of the source after
preprocessing.
-The actual preprocessing function is described in detail in section
-@ref{19,,Preprocessing with gnatprep}. This section only describes how integrated
-preprocessing is triggered and parameterized.
+The actual preprocessing function is described in detail in
+@ref{8f,,Preprocessing with gnatprep}. This section explains the switches
+that relate to integrated preprocessing.
@geindex -gnatep (gcc)
@table @asis
-@item @code{-gnatep=@emph{file}}
+@item @code{-gnatep=@emph{preprocessor_data_file}}
+
+This switch specifies the file name (without directory
+information) of the preprocessor data file. Either place this file
+in one of the source directories, or, when using project
+files, reference the project file's directory via the
+@code{project_name'Project_Dir} project attribute; e.g:
+
+@quotation
+
+@example
+project Prj is
+ package Compiler is
+ for Switches ("Ada") use
+ ("-gnatep=" & Prj'Project_Dir & "prep.def");
+ end Compiler;
+end Prj;
+@end example
+@end quotation
+
+A preprocessor data file is a text file that contains @emph{preprocessor
+control lines}. A preprocessor control line directs the preprocessing of
+either a particular source file, or, analogous to @code{others} in Ada,
+all sources not specified elsewhere in the preprocessor data file.
+A preprocessor control line
+can optionally identify a @emph{definition file} that assigns values to
+preprocessor symbols, as well as a list of switches that relate to
+preprocessing.
+Empty lines and comments (using Ada syntax) are also permitted, with no
+semantic effect.
+
+Here's an example of a preprocessor data file:
+
+@quotation
+
+@example
+"toto.adb" "prep.def" -u
+-- Preprocess toto.adb, using definition file prep.def
+-- Undefined symbols are treated as False
+
+* -c -DVERSION=V101
+-- Preprocess all other sources without using a definition file
+-- Suppressed lined are commented
+-- Symbol VERSION has the value V101
+
+"tata.adb" "prep2.def" -s
+-- Preprocess tata.adb, using definition file prep2.def
+-- List all symbols with their values
+@end example
+@end quotation
+
+A preprocessor control line has the following syntax:
+
+@quotation
+
+@example
+<preprocessor_control_line> ::=
+ <preprocessor_input> [ <definition_file_name> ] @{ <switch> @}
+
+<preprocessor_input> ::= <source_file_name> | '*'
+
+<definition_file_name> ::= <string_literal>
+
+<source_file_name> := <string_literal>
+
+<switch> := (See below for list)
+@end example
+@end quotation
+
+Thus each preprocessor control line starts with either a literal string or
+the character '*':
-This switch indicates to the compiler the file name (without directory
-information) of the preprocessor data file to use. The preprocessor data file
-should be found in the source directories. Note that when the compiler is
-called by a builder such as (@emph{gnatmake} with a project
-file, if the object directory is not also a source directory, the builder needs
-to be called with @emph{-x}.
-A preprocessing data file is a text file with significant lines indicating
-how should be preprocessed either a specific source or all sources not
-mentioned in other lines. A significant line is a nonempty, non-comment line.
-Comments are similar to Ada comments.
+@itemize *
-Each significant line starts with either a literal string or the character '*'.
+@item
A literal string is the file name (without directory information) of the source
-to preprocess. A character '*' indicates the preprocessing for all the sources
-that are not specified explicitly on other lines (order of the lines is not
-significant). It is an error to have two lines with the same file name or two
+file that will be input to the preprocessor.
+
+@item
+The character '*' is a wild-card indicator; the additional parameters on the line
+indicate the preprocessing for all the sources
+that are not specified explicitly on other lines (the order of the lines is not
+significant).
+@end itemize
+
+It is an error to have two lines with the same file name or two
lines starting with the character '*'.
-After the file name or the character '*', another optional literal string
-indicating the file name of the definition file to be used for preprocessing
-(@ref{b2,,Form of Definitions File}). The definition files are found by the
+After the file name or '*', an optional literal string specifies the name of
+the definition file to be used for preprocessing
+(@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
-directory as a source directory through switch -I., otherwise
+directory as a source directory through the @code{-I} switch; otherwise
the compiler would not find the definition file.
-Then, optionally, switches similar to those of @cite{gnatprep} may
-be found. Those switches are:
+Finally, switches similar to those of @code{gnatprep} may optionally appear:
@table @asis
Causes both preprocessor lines and the lines deleted by
preprocessing to be replaced by blank lines, preserving the line number.
-This switch is always implied; however, if specified after @emph{-c}
-it cancels the effect of @emph{-c}.
+This switch is always implied; however, if specified after @code{-c}
+it cancels the effect of @code{-c}.
@item @code{-c}
by preprocessing to be retained as comments marked
with the special string '@cite{--!}'.
-@item @code{-Dsymbol=@emph{value}}
+@item @code{-D@emph{symbol}=@emph{new_value}}
-Define or redefine a symbol, associated with value. A symbol is an Ada
-identifier, or an Ada reserved word, with the exception of @cite{if},
-@cite{else}, @cite{elsif}, @cite{end}, @cite{and}, @cite{or} and @cite{then}.
-@cite{value} is either a literal string, an Ada identifier or any Ada reserved
+Define or redefine @code{symbol} to have @code{new_value} as its value.
+The permitted form for @code{symbol} is either an Ada identifier, or any Ada reserved word
+aside from @code{if},
+@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
+The permitted form for @code{new_value} is a literal string, an Ada identifier or any Ada reserved
word. A symbol declared with this switch replaces a symbol with the
same name defined in a definition file.
@item @code{-u}
-Causes undefined symbols to be treated as having the value @cite{FALSE}
+Causes undefined symbols to be treated as having the value @code{FALSE}
in the context
of a preprocessor test. In the absence of this option, an undefined symbol in
-a @cite{#if} or @cite{#elsif} test will be treated as an error.
+a @code{#if} or @code{#elsif} test will be treated as an error.
@end table
-
-Examples of valid lines in a preprocessor data file:
-
-@example
-"toto.adb" "prep.def" -u
--- preprocess "toto.adb", using definition file "prep.def",
--- undefined symbol are False.
-
-* -c -DVERSION=V101
--- preprocess all other sources without a definition file;
--- suppressed lined are commented; symbol VERSION has the value V101.
-
-"titi.adb" "prep2.def" -s
--- preprocess "titi.adb", using definition file "prep2.def";
--- list all symbols with their values.
-@end example
@end table
@geindex -gnateD (gcc)
@table @asis
-@item @code{-gnateDsymbol[=value]}
+@item @code{-gnateD@emph{symbol}[=@emph{new_value}]}
-Define or redefine a preprocessing symbol, associated with value. If no value
-is given on the command line, then the value of the symbol is @cite{True}.
-A symbol is an identifier, following normal Ada (case-insensitive)
-rules for its syntax, and value is either an arbitrary string between double
+Define or redefine @code{symbol} to have @code{new_value} as its value. If no value
+is supplied, then the value of @code{symbol} is @code{True}.
+The form of @code{symbol} is an identifier, following normal Ada (case-insensitive)
+rules for its syntax, and @code{new_value} is either an arbitrary string between double
quotes or any sequence (including an empty sequence) of characters from the
set (letters, digits, period, underline).
-Ada reserved words may be used as symbols, with the exceptions of @cite{if},
-@cite{else}, @cite{elsif}, @cite{end}, @cite{and}, @cite{or} and @cite{then}.
+Ada reserved words may be used as symbols, with the exceptions of @code{if},
+@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}.
Examples:
+@quotation
+
@example
--gnateDToto=Titi
+-gnateDToto=Tata
-gnateDFoo
-gnateDFoo=\"Foo-Bar\"
@end example
+@end quotation
A symbol declared with this switch on the command line replaces a
symbol with the same name either in a definition file or specified with a
-switch -D in the preprocessor data file.
+switch @code{-D} in the preprocessor data file.
-This switch is similar to switch @emph{-D} of @cite{gnatprep}.
+This switch is similar to switch @code{-D} of @code{gnatprep}.
@item @code{-gnateG}
-When integrated preprocessing is performed and the preprocessor modifies
-the source text, write the result of this preprocessing into a file
-<source>.prep.
+When integrated preprocessing is performed on source file @code{filename.extension},
+create or overwrite @code{filename.extension.prep} to contain
+the result of the preprocessing.
+For example if the source file is @code{foo.adb} then
+the output file will be @code{foo.adb.prep}.
@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{46}@anchor{gnat_ugn/the_gnat_compilation_model id61}@anchor{b7}
+@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
* Calling Conventions::
* Building Mixed Ada and C++ Programs::
* Generating Ada Bindings for C and C++ headers::
+* Generating C Headers for Ada Specifications::
@end menu
@node Interfacing to C,Calling Conventions,,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model interfacing-to-c}@anchor{b8}@anchor{gnat_ugn/the_gnat_compilation_model id62}@anchor{b9}
+@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
Interfacing Ada with a foreign language such as C involves using
compiler directives to import and/or export entity definitions in each
-language -- using @cite{extern} statements in C, for instance, and the
-@cite{Import}, @cite{Export}, and @cite{Convention} pragmas in Ada.
+language -- using @code{extern} statements in C, for instance, and the
+@code{Import}, @code{Export}, and @code{Convention} pragmas in Ada.
A full treatment of these topics is provided in Appendix B, section 1
of the Ada Reference Manual.
-- Declare an Ada procedure spec for Print_Num, then use
-- C function print_num for the implementation.
procedure Print_Num (Num : Integer);
- pragma Import (C, Print_Num, "print_num";
+ pragma Import (C, Print_Num, "print_num");
begin
Print_Num (Get_Num);
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{ba,,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
@end itemize
Depending on the circumstances (for example when your non-Ada main object
-does not provide symbol @cite{main}), you may also need to instruct the
+does not provide symbol @code{main}), you may also need to instruct the
GNAT linker not to include the standard startup objects by passing the
-@code{-nostartfiles} switch to @cite{gnatlink}.
+@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{bb}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{bc}
+@anchor{gnat_ugn/the_gnat_compilation_model calling-conventions}@anchor{a1}@anchor{gnat_ugn/the_gnat_compilation_model id63}@anchor{a2}
@subsection Calling Conventions
@table @asis
-@item @emph{Ada}
+@item @code{Ada}
This indicates that the standard Ada calling sequence will be
used and all Ada data items may be passed without any limitations in the
@table @asis
-@item @emph{Assembler}
+@item @code{Assembler}
Specifies assembler as the convention. In practice this has the
same effect as convention Ada (but is not equivalent in the sense of being
@table @asis
-@item @emph{Asm}
+@item @code{Asm}
Equivalent to Assembler.
@table @asis
-@item @emph{COBOL}
+@item @code{COBOL}
Data will be passed according to the conventions described
in section B.4 of the Ada Reference Manual.
@table @asis
-@item @emph{C}
+@item @code{C}
Data will be passed according to the conventions described
in section B.3 of the Ada Reference Manual.
@geindex varargs function interfaces
-In C, @cite{varargs} allows a function to take a variable number of
+In C, @code{varargs} allows a function to take a variable number of
arguments. There is no direct equivalent in this to Ada. One
approach that can be used is to create a C wrapper for each
different profile and then interface to this C wrapper. For
-example, to print an @cite{int} value using @cite{printf},
-create a C function @cite{printfi} that takes two arguments, a
-pointer to a string and an int, and calls @cite{printf}.
-Then in the Ada program, use pragma @cite{Import} to
-interface to @cite{printfi}.
+example, to print an @code{int} value using @code{printf},
+create a C function @code{printfi} that takes two arguments, a
+pointer to a string and an int, and calls @code{printf}.
+Then in the Ada program, use pragma @code{Import} to
+interface to @code{printfi}.
It may work on some platforms to directly interface to
-a @cite{varargs} function by providing a specific Ada profile
+a @code{varargs} function by providing a specific Ada profile
for a particular call. However, this does not work on
all platforms, since there is no guarantee that the
calling sequence for a two argument normal C function
-is the same as for calling a @cite{varargs} C function with
+is the same as for calling a @code{varargs} C function with
the same two arguments.
@end quotation
@end table
@table @asis
-@item @emph{Default}
+@item @code{Default}
Equivalent to C.
@end table
@table @asis
-@item @emph{External}
+@item @code{External}
Equivalent to C.
@end table
@table @asis
-@item @emph{C_Plus_Plus (or CPP)}
+@item @code{C_Plus_Plus} (or @code{CPP})
This stands for C++. For most purposes this is identical to C.
See the separate description of the specialized GNAT pragmas relating to
@table @asis
-@item @emph{Fortran}
+@item @code{Fortran}
Data will be passed according to the conventions described
in section B.5 of the Ada Reference Manual.
-@item @emph{Intrinsic}
+@item @code{Intrinsic}
This applies to an intrinsic operation, as defined in the Ada
Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
General subprogram entities. This is used to bind an Ada subprogram
declaration to
a compiler builtin by name with back-ends where such interfaces are
-available. A typical example is the set of @cite{__builtin} functions
+available. A typical example is the set of @code{__builtin} functions
exposed by the GCC back-end, as in the following example:
@example
@table @asis
-@item @emph{Stdcall}
+@item @code{Stdcall}
This is relevant only to Windows implementations of GNAT,
-and specifies that the @cite{Stdcall} calling sequence will be used,
+and specifies that the @code{Stdcall} calling sequence will be used,
as defined by the NT API. Nevertheless, to ease building
-cross-platform bindings this convention will be handled as a @cite{C} calling
+cross-platform bindings this convention will be handled as a @code{C} calling
convention on non-Windows platforms.
@end table
@table @asis
-@item @emph{DLL}
+@item @code{DLL}
-This is equivalent to @cite{Stdcall}.
+This is equivalent to @code{Stdcall}.
@end table
@geindex Win32
@table @asis
-@item @emph{Win32}
+@item @code{Win32}
-This is equivalent to @cite{Stdcall}.
+This is equivalent to @code{Stdcall}.
@end table
@geindex Stubbed
@table @asis
-@item @emph{Stubbed}
+@item @code{Stubbed}
This is a special convention that indicates that the compiler
-should provide a stub body that raises @cite{Program_Error}.
+should provide a stub body that raises @code{Program_Error}.
@end table
-GNAT additionally provides a useful pragma @cite{Convention_Identifier}
+GNAT additionally provides a useful pragma @code{Convention_Identifier}
that can be used to parameterize conventions and allow additional synonyms
to be specified. For example if you have legacy code in which the convention
identifier Fortran77 was used for Fortran, you can use the configuration
@end example
And from now on the identifier Fortran77 may be used as a convention
-identifier (for example in an @cite{Import} pragma) with the same
+identifier (for example in an @code{Import} pragma) with the same
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{bd}@anchor{gnat_ugn/the_gnat_compilation_model building-mixed-ada-and-c-programs}@anchor{be}
+@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{bf}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{c0}
+@anchor{gnat_ugn/the_gnat_compilation_model id65}@anchor{a5}@anchor{gnat_ugn/the_gnat_compilation_model id66}@anchor{a6}
@subsubsection Interfacing to C++
Interface ---see @indicateurl{http://www.codesourcery.com/archives/cxx-abi}).
Interfacing can be done at 3 levels: simple data, subprograms, and
-classes. In the first two cases, GNAT offers a specific @cite{Convention C_Plus_Plus}
-(or @cite{CPP}) that behaves exactly like @cite{Convention 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{1b,,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:
@item
by modifying the C++ code in order to force a C convention using
-the @cite{extern "C"} syntax.
+the @code{extern "C"} syntax.
@item
-by figuring out the mangled name (using e.g. @emph{nm}) and using it as the
+by figuring out the mangled name (using e.g. @code{nm}) and using it as the
Link_Name argument of the pragma import.
@end itemize
Interfacing at the class level can be achieved by using the GNAT specific
-pragmas such as @cite{CPP_Constructor}. See the @cite{GNAT_Reference_Manual} for additional information.
+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{c1}@anchor{gnat_ugn/the_gnat_compilation_model linking-a-mixed-c-and-ada-program}@anchor{c2}
+@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
@item
Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
The C++ linker can simply be called by using the C++ specific driver
-called @cite{g++}.
+called @code{g++}.
Note that if the C++ code uses inline functions, you will need to
-compile your C++ code with the @cite{-fkeep-inline-functions} switch in
+compile your C++ code with the @code{-fkeep-inline-functions} switch in
order to provide an existing function implementation that the Ada code can
link with.
improperly if set during invocation of the wrong compiler. It is also
very important that the linker uses the proper @code{libgcc.a} GCC
library -- that is, the one from the C++ compiler installation. The
-implicit link command as suggested in the @cite{gnatmake} command
+implicit link command as suggested in the @code{gnatmake} command
from the former example can be replaced by an explicit link command with
the full-verbosity option in order to verify which library is used:
a few more parameters to the link command line, depending on the exception
mechanism used.
-If the @cite{setjmp/longjmp} exception mechanism is used, only the paths
-to the libgcc libraries are required:
+If the @code{setjmp} / @code{longjmp} exception mechanism is used, only the paths
+to the @code{libgcc} libraries are required:
@example
$ cat ./my_script
#!/bin/sh
-CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a`
+CC $* gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
@end example
where CC is the name of the non-GNU C++ compiler.
-If the @cite{zero cost} exception mechanism is used, and the platform
+If the "zero cost" exception mechanism is used, and the platform
supports automatic registration of exception tables (e.g., Solaris),
paths to more objects are required:
@example
$ cat ./my_script
#!/bin/sh
-CC `gcc -print-file-name=crtbegin.o` $* \\
-`gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \\
-`gcc -print-file-name=crtend.o`
+CC gcc -print-file-name=crtbegin.o $* \\
+gcc -print-file-name=libgcc.a gcc -print-file-name=libgcc_eh.a \\
+gcc -print-file-name=crtend.o
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
@end example
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{c3}@anchor{gnat_ugn/the_gnat_compilation_model a-simple-example}@anchor{c4}
+@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{c5}@anchor{gnat_ugn/the_gnat_compilation_model interfacing-with-c-constructors}@anchor{c6}
+@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
In order to interface with C++ constructors GNAT provides the
-@cite{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual}
+@code{pragma CPP_Constructor} (see the @cite{GNAT_Reference_Manual}
for additional information).
In this section we present some common uses of C++ constructors
in mixed-languages programs in GNAT.
For this purpose we can write the following package spec (further
information on how to build this spec is available in
-@ref{c7,,Interfacing with C++ at the Class Level} and
-@ref{1b,,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;
@itemize *
@item
-On the right side of an initialization of an object of type @cite{T}.
+On the right side of an initialization of an object of type @code{T}.
@item
-On the right side of an initialization of a record component of type @cite{T}.
+On the right side of an initialization of a record component of type @code{T}.
@item
In an Ada 2005 limited aggregate.
The first two declarations are equivalent: in both cases the default C++
constructor is invoked (in the former case the call to the constructor is
implicit, and in the latter case the call is explicit in the object
-declaration). @cite{Obj3} is initialized by the C++ non-default constructor
-that takes an integer argument, and @cite{Obj4} is initialized by the
+declaration). @code{Obj3} is initialized by the C++ non-default constructor
+that takes an integer argument, and @code{Obj4} is initialized by the
non-default C++ constructor that takes two integers.
Let us derive the imported C++ class in the Ada side. For example:
Obj7 : DT := (Constructor (30,40) with C_Value => 50);
@end example
-The declaration of @cite{Obj5} invokes the default constructors: the
+The declaration of @code{Obj5} invokes the default constructors: the
C++ default constructor of the parent type takes care of the initialization
of the components inherited from Root, and GNAT takes care of the default
initialization of the additional Ada components of type DT (that is,
-@cite{C_Value} is initialized to value 2009). The order of invocation of
+@code{C_Value} is initialized to value 2009). The order of invocation of
the constructors is consistent with the order of elaboration required by
Ada and C++. That is, the constructor of the parent type is always called
before the constructor of the derived type.
end record;
@end example
-The initialization of an object of type @cite{Rec2} will call the
+The initialization of an object of type @code{Rec2} will call the
non-default C++ constructors specified for the imported components.
For example:
@end example
The above declaration uses an Ada 2005 limited aggregate to
-initialize @cite{Obj9}, and the C++ constructor that has two integer
-arguments is invoked to initialize the @cite{Data1} component instead
-of the constructor specified in the declaration of type @cite{Rec1}. In
+initialize @code{Obj9}, and the C++ constructor that has two integer
+arguments is invoked to initialize the @code{Data1} component instead
+of the constructor specified in the declaration of type @code{Rec1}. In
Ada 2005 the box in the aggregate indicates that unspecified components
are initialized using the expression (if any) available in the component
-declaration. That is, in this case discriminant @cite{D} is initialized
-to value @cite{20}, @cite{Value} is initialized to value 1000, and the
+declaration. That is, in this case discriminant @code{D} is initialized
+to value @code{20}, @code{Value} is initialized to value 1000, and the
non-default C++ constructor that handles two integers takes care of
-initializing component @cite{Data2} with values @cite{20@comma{}30}.
+initializing component @code{Data2} with values @code{20,30}.
In Ada 2005 we can use the extended return statement to build the Ada
equivalent to C++ non-default constructors. For example:
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{c7}@anchor{gnat_ugn/the_gnat_compilation_model id69}@anchor{c8}
+@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
constructors are defined on the C++ side and imported from the Ada
side, and latter the reverse case.
-The root of our derivation will be the @cite{Animal} class, with a
-single private attribute (the @cite{Age} of the animal), a constructor,
+The root of our derivation will be the @code{Animal} class, with a
+single private attribute (the @code{Age} of the animal), a constructor,
and two public primitives to set and get the value of this attribute.
@example
Abstract interface types are defined in C++ by means of classes with pure
virtual functions and no data members. In our example we will use two
-interfaces that provide support for the common management of @cite{Carnivore}
-and @cite{Domestic} animals:
+interfaces that provide support for the common management of @code{Carnivore}
+and @code{Domestic} animals:
@example
class Carnivore @{
@};
@end example
-Using these declarations, we can now say that a @cite{Dog} is an animal that is
+Using these declarations, we can now say that a @code{Dog} is an animal that is
both Carnivore and Domestic, that is:
@example
@end example
In the following examples we will assume that the previous declarations are
-located in a file named @cite{animals.h}. The following package demonstrates
+located in a file named @code{animals.h}. The following package demonstrates
how to import these C++ declarations from the Ada side:
@example
type Dog is new Animal and Carnivore and Domestic with record
Tooth_Count : Natural;
- Owner : String (1 .. 30);
+ Owner : Chars_Ptr;
end record;
pragma Import (C_Plus_Plus, Dog);
the two languages.
Regarding the abstract interfaces, we must indicate to the GNAT compiler by
-means of a @cite{pragma Convention (C_Plus_Plus)}, the convention used to pass
+means of a @code{pragma Convention (C_Plus_Plus)}, the convention used to pass
the arguments to the called primitives will be the same as for C++. For the
-imported classes we use @cite{pragma Import} with convention @cite{C_Plus_Plus}
+imported classes we use @code{pragma Import} with convention @code{C_Plus_Plus}
to indicate that they have been defined on the C++ side; this is required
because the dispatch table associated with these tagged types will be built
in the C++ side and therefore will not contain the predefined Ada primitives
associated with each subprogram because it is assumed that all the calls to
these primitives will be dispatching calls. The only exception is the
constructor, which must be registered with the compiler by means of
-@cite{pragma CPP_Constructor} and needs to provide its associated C++
+@code{pragma CPP_Constructor} and needs to provide its associated C++
mangled name because the Ada compiler generates direct calls to it.
With the above packages we can now declare objects of type Dog on the Ada side
@end example
Compared with our previous example the only differences are the use of
-@cite{pragma Convention} (instead of @cite{pragma Import}), and the use of
-@cite{pragma Export} to indicate to the GNAT compiler that the primitives will
+@code{pragma Convention} (instead of @code{pragma Import}), and the use of
+@code{pragma Export} to indicate to the GNAT compiler that the primitives will
be available to C++. Thanks to the ABI compatibility, on the C++ side there is
nothing else to be done; as explained above, the only requirement is that all
the primitives and components are declared in exactly the same order.
For completeness, let us see a brief C++ main program that uses the
-declarations available in @cite{animals.h} (presented in our first example) to
+declarations available in @code{animals.h} (presented in our first example) to
import and use the declarations from the Ada side, properly initializing and
finalizing the Ada run-time system along the way:
@}
@end example
-@node Generating Ada Bindings for C and C++ headers,,Building Mixed Ada and C++ Programs,Mixed Language Programming
-@anchor{gnat_ugn/the_gnat_compilation_model id70}@anchor{c9}@anchor{gnat_ugn/the_gnat_compilation_model generating-ada-bindings-for-c-and-c-headers}@anchor{1b}
+@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{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
@item
identifiers with identical name (except casing) will generate compilation
-errors (e.g. @cite{shm_get} vs @cite{SHM_GET}).
+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::
-* Generating bindings for C++ headers::
+* Running the Binding Generator::
+* Generating Bindings for C++ Headers::
* Switches::
@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{ca}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{cb}
-@subsubsection Running the binding generator
+@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{b1}@anchor{gnat_ugn/the_gnat_compilation_model running-the-binding-generator}@anchor{b2}
+@subsubsection Running the Binding Generator
-The binding generator is part of the @emph{gcc} compiler and can be
-invoked via the @emph{-fdump-ada-spec} switch, which will generate Ada
+The binding generator is part of the @code{gcc} compiler and can be
+invoked via the @code{-fdump-ada-spec} switch, which will generate Ada
spec files for the header files specified on the command line, and all
header files needed by these files transitively. For example:
@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},
@code{bits_time_h.ads}, @code{stddef_h.ads}, @code{bits_types_h.ads} which
correspond to the files @code{/usr/include/time.h},
-@code{/usr/include/bits/time.h}, etc..., and will then compile in Ada 2005
-mode these Ada specs.
+@code{/usr/include/bits/time.h}, etc..., and will then compile these Ada specs
+in Ada 2005 mode.
-The @cite{-C} switch tells @emph{gcc} to extract comments from headers,
+The @code{-C} switch tells @code{gcc} to extract comments from headers,
and will attempt to generate corresponding Ada comments.
If you want to generate a single Ada file and not the transitive closure, you
-can use instead the @emph{-fdump-ada-spec-slim} switch.
+can use instead the @code{-fdump-ada-spec-slim} switch.
You can optionally specify a parent unit, of which all generated units will
-be children, using @cite{-fada-spec-parent=<unit>}.
+be children, using @code{-fada-spec-parent=@emph{unit}}.
Note that we recommend when possible to use the @emph{g++} driver to
generate bindings, even for most C headers, since this will in general
mandatory to use the @emph{g++} command, or @emph{gcc -x c++} which
is equivalent in this case. If @emph{g++} cannot work on your C headers
because of incompatibilities between C and C++, then you can fallback to
-@emph{gcc} instead.
+@code{gcc} instead.
For an example of better bindings generated from the C++ front-end,
the name of the parameters (when available) are actually ignored by the C
extern void foo (int variable);
@end example
-with the C front-end, @cite{variable} is ignored, and the above is handled as:
+with the C front-end, @code{variable} is ignored, and the above is handled as:
@example
extern void foo (int);
@end example
In some cases, the generated bindings will be more complete or more meaningful
-when defining some macros, which you can do via the @emph{-D} switch. This
+when defining some macros, which you can do via the @code{-D} switch. This
is for example the case with @code{Xlib.h} under GNU/Linux:
@example
@end example
The above will generate more complete bindings than a straight call without
-the @emph{-DXLIB_ILLEGAL_ACCESS} switch.
+the @code{-DXLIB_ILLEGAL_ACCESS} switch.
In other cases, it is not possible to parse a header file in a stand-alone
manner, because other include files need to be included first. In this
case, the solution is to create a small header file including the needed
-@cite{#include} and possible @cite{#define} directives. For example, to
+@code{#include} and possible @code{#define} directives. For example, to
generate Ada bindings for @code{readline/readline.h}, you need to first
include @code{stdio.h}, so you can create a file with the following two
lines in e.g. @code{readline1.h}:
$ g++ -c -fdump-ada-spec readline1.h
@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{cc}@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{cd}
-@subsubsection Generating bindings for C++ headers
+@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{b3}@anchor{gnat_ugn/the_gnat_compilation_model generating-bindings-for-c-headers}@anchor{b4}
+@subsubsection Generating Bindings for C++ Headers
Generating bindings for C++ headers is done using the same options, always
bindings by hand more extensively when using C++ headers.
In this mode, C++ classes will be mapped to Ada tagged types, constructors
-will be mapped using the @cite{CPP_Constructor} pragma, and when possible,
+will be mapped using the @code{CPP_Constructor} pragma, and when possible,
multiple inheritance of abstract classes will be mapped to Ada interfaces
(see the @emph{Interfacing to C++} section in the @cite{GNAT Reference Manual}
for additional information on interfacing to C++).
use Class_Dog;
@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{ce}@anchor{gnat_ugn/the_gnat_compilation_model switches-for-ada-binding-generation}@anchor{cf}
+@node Switches,,Generating Bindings for C++ Headers,Generating Ada Bindings for C and C++ headers
+@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
@item @code{-fada-spec-parent=@emph{unit}}
-Specifies that all files generated by @emph{-fdump-ada-spec*} are
+Specifies that all files generated by @code{-fdump-ada-spec} are
to be child units of the specified parent unit.
@end table
Extract comments from headers and generate Ada comments in the Ada spec files.
@end table
-@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 id73}@anchor{d0}@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{47}
-@section GNAT and Other Compilation Models
+@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{b7}@anchor{gnat_ugn/the_gnat_compilation_model id73}@anchor{b8}
+@subsection Generating C Headers for Ada Specifications
-This section compares the GNAT model with the approaches taken in
-other environents, first the C/C++ model and then the mechanism that
-has been used in other Ada systems, in particular those traditionally
-used for Ada 83.
+@geindex Binding generation (for Ada specs)
-@menu
-* Comparison between GNAT and C/C++ Compilation Models::
-* Comparison between GNAT and Conventional Ada Library Models::
+@geindex C headers (binding generation)
-@end menu
+GNAT includes a C header generator for Ada specifications which supports
+Ada types that have a direct mapping to C types. This includes in particular
+support for:
-@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{d1}@anchor{gnat_ugn/the_gnat_compilation_model id74}@anchor{d2}
+
+@itemize *
+
+@item
+Scalar types
+
+@item
+Constrained arrays
+
+@item
+Records (untagged)
+
+@item
+Composition of the above types
+
+@item
+Constant declarations
+
+@item
+Object declarations
+
+@item
+Subprogram declarations
+@end itemize
+
+@menu
+* Running the C Header Generator::
+
+@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{b9}
+@subsubsection Running the C Header Generator
+
+
+The C header generator is part of the GNAT compiler and can be invoked via
+the @code{-gnatceg} combination of switches, which will generate a @code{.h}
+file corresponding to the given input file (Ada spec or body). Note that
+only spec files are processed in any case, so giving a spec or a body file
+as input is equivalent. For example:
+
+@example
+$ gcc -c -gnatceg pack1.ads
+@end example
+
+will generate a self-contained file called @code{pack1.h} including
+common definitions from the Ada Standard package, followed by the
+definitions included in @code{pack1.ads}, as well as all the other units
+withed by this file.
+
+For instance, given the following Ada files:
+
+@example
+package Pack2 is
+ type Int is range 1 .. 10;
+end Pack2;
+@end example
+
+@example
+with Pack2;
+
+package Pack1 is
+ type Rec is record
+ Field1, Field2 : Pack2.Int;
+ end record;
+
+ Global : Rec := (1, 2);
+
+ procedure Proc1 (R : Rec);
+ procedure Proc2 (R : in out Rec);
+end Pack1;
+@end example
+
+The above @code{gcc} command will generate the following @code{pack1.h} file:
+
+@example
+/* Standard definitions skipped */
+#ifndef PACK2_ADS
+#define PACK2_ADS
+typedef short_short_integer pack2__TintB;
+typedef pack2__TintB pack2__int;
+#endif /* PACK2_ADS */
+
+#ifndef PACK1_ADS
+#define PACK1_ADS
+typedef struct _pack1__rec @{
+ pack2__int field1;
+ pack2__int field2;
+@} pack1__rec;
+extern pack1__rec pack1__global;
+extern void pack1__proc1(const pack1__rec r);
+extern void pack1__proc2(pack1__rec *r);
+#endif /* PACK1_ADS */
+@end example
+
+You can then @code{include} @code{pack1.h} from a C source file and use the types,
+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{ba}@anchor{gnat_ugn/the_gnat_compilation_model gnat-and-other-compilation-models}@anchor{2d}
+@section GNAT and Other Compilation Models
+
+
+This section compares the GNAT model with the approaches taken in
+other environents, first the C/C++ model and then the mechanism that
+has been used in other Ada systems, in particular those traditionally
+used for Ada 83.
+
+@menu
+* Comparison between GNAT and C/C++ Compilation Models::
+* Comparison between GNAT and Conventional Ada Library 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{bb}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{bc}
@subsection Comparison between GNAT and C/C++ Compilation Models
The GNAT model of compilation is close to the C and C++ models. You can
think of Ada specs as corresponding to header files in C. As in C, you
don't need to compile specs; they are compiled when they are used. The
-Ada @emph{with} is similar in effect to the @cite{#include} of a C
+Ada @emph{with} is similar in effect to the @code{#include} of a C
header.
One notable difference is that, in Ada, you may compile specs separately
issues. There are also elaboration issues in C++ that are handled
automatically. This automatic handling has the advantage of being
simpler to use, but the C++ programmer has no control over elaboration.
-Where @cite{gnatbind} might complain there was no valid order of
+Where @code{gnatbind} might complain there was no valid order of
elaboration, a C++ compiler would simply construct a program that
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{d3}@anchor{gnat_ugn/the_gnat_compilation_model id75}@anchor{d4}
+@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{1c}@anchor{gnat_ugn/the_gnat_compilation_model id76}@anchor{d5}
+@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{d6}@anchor{gnat_ugn/the_gnat_compilation_model id77}@anchor{d7}
+@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{d8}@anchor{gnat_ugn/the_gnat_compilation_model id78}@anchor{d9}
+@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
@geindex pragma Export
-The variable @cite{MN} has a full expanded Ada name of @cite{QRS.MN}, so
-the corresponding link name is @cite{qrs__mn}.
-Of course if a @cite{pragma Export} is used this may be overridden:
+The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so
+the corresponding link name is @code{qrs__mn}.
+Of course if a @code{pragma Export} is used this may be overridden:
@example
package Exports is
end Exports;
@end example
-In this case, the link name for @cite{Var1} is whatever link name the
-C compiler would assign for the C function @cite{var1_name}. This typically
-would be either @cite{var1_name} or @cite{_var1_name}, depending on operating
+In this case, the link name for @code{Var1} is whatever link name the
+C compiler would assign for the C function @code{var1_name}. This typically
+would be either @code{var1_name} or @code{_var1_name}, depending on operating
system conventions, but other possibilities exist. The link name for
-@cite{Var2} is @cite{var2_link_name}, and this is not operating system
+@code{Var2} is @code{var2_link_name}, and this is not operating system
dependent.
One exception occurs for library level procedures. A potential ambiguity
-arises between the required name @cite{_main} for the C main program,
+arises between the required name @code{_main} for the C main program,
and the name we would otherwise assign to an Ada library level procedure
-called @cite{Main} (which might well not be the main program).
+called @code{Main} (which might well not be the main program).
-To avoid this ambiguity, we attach the prefix @cite{_ada_} to such
+To avoid this ambiguity, we attach the prefix @code{_ada_} to such
names. So if we have a library level procedure such as:
@example
procedure Hello (S : String);
@end example
-the external name of this procedure will be @cite{_ada_hello}.
+the external name of this procedure will be @code{_ada_hello}.
@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-@node Building Executable Programs with GNAT,GNAT Project Manager,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{da}@anchor{gnat_ugn/building_executable_programs_with_gnat id1}@anchor{db}
+@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{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{1d,,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{1e,,Compiling with gcc}),
-binder (gnatbind, see @ref{1f,,Binding with gnatbind}),
-and linker (gnatlink, see @ref{20,,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{21,,Using the GNU make Utility}).
+in a GNAT context (see @ref{70,,Using the GNU make Utility}).
+
@menu
* Building with gnatmake::
* Compiling with gcc::
* Compiler Switches::
+* Linker Switches::
* Binding with gnatbind::
* Linking with gnatlink::
* Using the GNU make Utility::
@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{1d}@anchor{gnat_ugn/building_executable_programs_with_gnat building-with-gnatmake}@anchor{dc}
-@section Building with @emph{gnatmake}
+@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}
@geindex gnatmake
The third step in particular can be tricky, because not only do the modified
files have to be compiled, but any files depending on these files must also be
recompiled. The dependency rules in Ada can be quite complex, especially
-in the presence of overloading, @cite{use} clauses, generics and inlined
+in the presence of overloading, @code{use} clauses, generics and inlined
subprograms.
-@emph{gnatmake} automatically takes care of the third and fourth steps
+@code{gnatmake} automatically takes care of the third and fourth steps
of this process. It determines which sources need to be compiled,
compiles them, and binds and links the resulting object files.
the GNAT compilation model makes this possible. This means that if
changes to the source program cause corresponding changes in
dependencies, they will always be tracked exactly correctly by
-@emph{gnatmake}.
+@code{gnatmake}.
-Note that for advanced description of project structure, we recommend creating
-a project file as explained in @ref{b,,GNAT Project Manager} and use the
-@emph{gprbuild} tool which supports building with project files and works similarly
-to @emph{gnatmake}.
+Note that for advanced forms of project structure, we recommend creating
+a project file as explained in the @emph{GNAT_Project_Manager} chapter in the
+@emph{GPRbuild User's Guide}, and using the
+@code{gprbuild} tool which supports building with project files and works similarly
+to @code{gnatmake}.
@menu
* Running gnatmake::
@end menu
@node Running gnatmake,Switches for gnatmake,,Building with gnatmake
-@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatmake}@anchor{dd}@anchor{gnat_ugn/building_executable_programs_with_gnat id2}@anchor{de}
-@subsection Running @emph{gnatmake}
+@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}
-The usual form of the @emph{gnatmake} command is
+The usual form of the @code{gnatmake} command is
@example
$ gnatmake [<switches>] <file_name> [<file_names>] [<mode_switches>]
@end example
-The only required argument is one @cite{file_name}, which specifies
-a compilation unit that is a main program. Several @cite{file_names} can be
+The only required argument is one @code{file_name}, which specifies
+a compilation unit that is a main program. Several @code{file_names} can be
specified: this will result in several executables being built.
-If @cite{switches} are present, they can be placed before the first
-@cite{file_name}, between @cite{file_names} or after the last @cite{file_name}.
-If @cite{mode_switches} are present, they must always be placed after
-the last @cite{file_name} and all @cite{switches}.
+If @code{switches} are present, they can be placed before the first
+@code{file_name}, between @code{file_names} or after the last @code{file_name}.
+If @code{mode_switches} are present, they must always be placed after
+the last @code{file_name} and all @code{switches}.
If you are using standard file extensions (@code{.adb} and
@code{.ads}), then the
-extension may be omitted from the @cite{file_name} arguments. However, if
+extension may be omitted from the @code{file_name} arguments. However, if
you are using non-standard extensions, then it is required that the
extension be given. A relative or absolute directory path can be
-specified in a @cite{file_name}, in which case, the input source file will
+specified in a @code{file_name}, in which case, the input source file will
be searched for in the specified directory only. Otherwise, the input
source file will first be searched in the directory where
-@emph{gnatmake} was invoked and if it is not found, it will be search on
+@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{8e,,Search Paths and the Run-Time Library (RTL)}.
+@ref{73,,Search Paths and the Run-Time Library (RTL)}.
-All @emph{gnatmake} output (except when you specify @emph{-M}) is sent to
+All @code{gnatmake} output (except when you specify @code{-M}) is sent to
@code{stderr}. The output produced by the
-@emph{-M} switch is sent to @code{stdout}.
+@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{df}@anchor{gnat_ugn/building_executable_programs_with_gnat id3}@anchor{e0}
-@subsection Switches for @emph{gnatmake}
+@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}
-You may specify any of the following switches to @emph{gnatmake}:
+You may specify any of the following switches to @code{gnatmake}:
@geindex --version (gnatmake)
@item @code{--GCC=@emph{compiler_name}}
Program used for compiling. The default is @code{gcc}. You need to use
-quotes around @cite{compiler_name} if @cite{compiler_name} contains
+quotes around @code{compiler_name} if @code{compiler_name} contains
spaces or other separator characters.
As an example @code{--GCC="foo -x -y"}
-will instruct @emph{gnatmake} to use @code{foo -x -y} as your
+will instruct @code{gnatmake} to use @code{foo -x -y} as your
compiler. A limitation of this syntax is that the name and path name of
the executable itself must not include any embedded spaces. Note that
switch @code{-c} is always inserted after your command name. Thus in the
-above example the compiler command that will be used by @emph{gnatmake}
+above example the compiler command that will be used by @code{gnatmake}
will be @code{foo -c -x -y}. If several @code{--GCC=compiler_name} are
-used, only the last @cite{compiler_name} is taken into account. However,
+used, only the last @code{compiler_name} is taken into account. However,
all the additional switches are also taken into account. Thus,
@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
@code{--GCC="bar -x -y -z -t"}.
@item @code{--GNATBIND=@emph{binder_name}}
Program used for binding. The default is @code{gnatbind}. You need to
-use quotes around @cite{binder_name} if @cite{binder_name} contains spaces
+use quotes around @code{binder_name} if @code{binder_name} contains spaces
or other separator characters.
As an example @code{--GNATBIND="bar -x -y"}
-will instruct @emph{gnatmake} to use @cite{bar -x -y} as your
-binder. Binder switches that are normally appended by @emph{gnatmake}
-to @code{gnatbind} are now appended to the end of @cite{bar -x -y}.
+will instruct @code{gnatmake} to use @code{bar -x -y} as your
+binder. Binder switches that are normally appended by @code{gnatmake}
+to @code{gnatbind} are now appended to the end of @code{bar -x -y}.
A limitation of this syntax is that the name and path name of the executable
itself must not include any embedded spaces.
@end table
@item @code{--GNATLINK=@emph{linker_name}}
Program used for linking. The default is @code{gnatlink}. You need to
-use quotes around @cite{linker_name} if @cite{linker_name} contains spaces
+use quotes around @code{linker_name} if @code{linker_name} contains spaces
or other separator characters.
As an example @code{--GNATLINK="lan -x -y"}
-will instruct @emph{gnatmake} to use @code{lan -x -y} as your
+will instruct @code{gnatmake} to use @code{lan -x -y} as your
linker. Linker switches that are normally appended by @code{gnatmake} to
@code{gnatlink} are now appended to the end of @code{lan -x -y}.
A limitation of this syntax is that the name and path name of the executable
long time. If the source info file exists but cannot be parsed successfully,
the Project Manager will attempt to recreate it. If the Project Manager fails
to create the source info file, a message is issued, but gnatmake does not
-fail. @emph{gnatmake} "trusts" the source info file. This means that
+fail. @code{gnatmake} "trusts" the source info file. This means that
if the source files have changed (addition, deletion, moving to a different
source directory), then the source info file need to be deleted and recreated.
@end table
files (for example, the predefined Ada library files), as well as any
locked files. Locked files are files whose ALI file is write-protected.
By default,
-@emph{gnatmake} does not check these files,
+@code{gnatmake} does not check these files,
because the assumption is that the GNAT internal files are properly up
to date, and also that any write protected ALI files have been properly
installed. Note that if there is an installation problem, such that one
in conjunction with @code{-f}
if you need to recompile an entire application,
including run-time files, using special configuration pragmas,
-such as a @cite{Normalize_Scalars} pragma.
+such as a @code{Normalize_Scalars} pragma.
By default
@code{gnatmake -a} compiles all GNAT
@item @code{-b}
-Bind only. Can be combined with @emph{-c} to do
+Bind only. Can be combined with @code{-c} to do
compilation and binding, but no link.
-Can be combined with @emph{-l}
+Can be combined with @code{-l}
to do binding and linking. When not combined with
-@emph{-c}
+@code{-c}
all the units in the closure of the main program must have been previously
-compiled and must be up to date. The root unit specified by @cite{file_name}
+compiled and must be up to date. The root unit specified by @code{file_name}
may be given without extension, with the source extension or, if no GNAT
Project File is specified, with the ALI file extension.
@end table
@item @code{-c}
-Compile only. Do not perform binding, except when @emph{-b}
+Compile only. Do not perform binding, except when @code{-b}
is also specified. Do not perform linking, except if both
-@emph{-b} and
-@emph{-l} are also specified.
-If the root unit specified by @cite{file_name} is not a main unit, this is the
-default. Otherwise @emph{gnatmake} will attempt binding and linking
+@code{-b} and
+@code{-l} are also specified.
+If the root unit specified by @code{file_name} is not a main unit, this is the
+default. Otherwise @code{gnatmake} will attempt binding and linking
unless all objects are up to date and the executable is more recent than
the objects.
@end table
full directory information). A mapping file can make the compiler's
file searches faster, especially if there are many source directories,
or the sources are read over a slow network connection. If
-@emph{-P} is used, a mapping file is always used, so
-@emph{-C} is unnecessary; in this case the mapping file
+@code{-P} is used, a mapping file is always used, so
+@code{-C} is unnecessary; in this case the mapping file
is initially populated based on the project file. If
-@emph{-C} is used without
-@emph{-P},
+@code{-C} is used without
+@code{-P},
the mapping file is initially empty. Each invocation of the compiler
will add any newly accessed sources to the mapping file.
@end table
@item @code{-D @emph{dir}}
-Put all object files and ALI file in directory @cite{dir}.
-If the @emph{-D} switch is not used, all object files
+Put all object files and ALI file in directory @code{dir}.
+If the @code{-D} switch is not used, all object files
and ALI files go in the current working directory.
This switch cannot be used when using a project file.
Indicates that the main source is a multi-unit source and the rank of the unit
in the source file is nnn. nnn needs to be a positive number and a valid
-index in the source. This switch cannot be used when @emph{gnatmake} is
+index in the source. This switch cannot be used when @code{gnatmake} is
invoked for several mains.
@end table
Force recompilations. Recompile all sources, even though some object
files may be up to date, but don't recompile predefined or GNAT internal
files or locked files (files with a write-protected ALI file),
-unless the @emph{-a} switch is also specified.
+unless the @code{-a} switch is also specified.
@end table
@geindex -F (gnatmake)
@item @code{-i}
-In normal mode, @emph{gnatmake} compiles all object files and ALI files
-into the current directory. If the @emph{-i} switch is used,
+In normal mode, @code{gnatmake} compiles all object files and ALI files
+into the current directory. If the @code{-i} switch is used,
then instead object files and ALI files that already exist are overwritten
in place. This means that once a large project is organized into separate
-directories in the desired manner, then @emph{gnatmake} will automatically
+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{8e,,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,
a useful technique is to create dummy ALI files in the desired directories.
-When detecting such a dummy file, @emph{gnatmake} will be forced to
+When detecting such a dummy file, @code{gnatmake} will be forced to
recompile the corresponding source file, and it will be put the resulting
object and ALI files in the directory where it found the dummy file.
@end table
@item @code{-j@emph{n}}
-Use @cite{n} processes to carry out the (re)compilations. On a multiprocessor
-machine compilations will occur in parallel. If @cite{n} is 0, then the
+Use @code{n} processes to carry out the (re)compilations. On a multiprocessor
+machine compilations will occur in parallel. If @code{n} is 0, then the
maximum number of parallel compilations is the number of core processors
on the platform. In the event of compilation errors, messages from various
-compilations might get interspersed (but @emph{gnatmake} will give you the
+compilations might get interspersed (but @code{gnatmake} will give you the
full ordered list of failing compiles at the end). If this is problematic,
rerun the make process with n set to 1 to get a clean list of messages.
@end table
Keep going. Continue as much as possible after a compilation error. To
ease the programmer's task in case of compilation errors, the list of
-sources for which the compile fails is given when @emph{gnatmake}
+sources for which the compile fails is given when @code{gnatmake}
terminates.
-If @emph{gnatmake} is invoked with several @code{file_names} and with this
+If @code{gnatmake} is invoked with several @code{file_names} and with this
switch, if there are compilation errors when building an executable,
-@emph{gnatmake} will not attempt to build the following executables.
+@code{gnatmake} will not attempt to build the following executables.
@end table
@geindex -l (gnatmake)
@item @code{-l}
-Link only. Can be combined with @emph{-b} to binding
+Link only. Can be combined with @code{-b} to binding
and linking. Linking will not be performed if combined with
-@emph{-c}
-but not with @emph{-b}.
-When not combined with @emph{-b}
+@code{-c}
+but not with @code{-b}.
+When not combined with @code{-b}
all the units in the closure of the main program must have been previously
compiled and must be up to date, and the main program needs to have been bound.
-The root unit specified by @cite{file_name}
+The root unit specified by @code{file_name}
may be given without extension, with the source extension or, if no GNAT
Project File is specified, with the ALI file extension.
@end table
@item @code{-m}
Specify that the minimum necessary amount of recompilations
-be performed. In this mode @emph{gnatmake} ignores time
+be performed. In this mode @code{gnatmake} ignores time
stamp differences when the only
modifications to a source file consist in adding/removing comments,
empty lines, spaces or tabs. This means that if you have changed the
comments in a source file or have simply reformatted it, using this
-switch will tell @emph{gnatmake} not to recompile files that depend on it
+switch will tell @code{gnatmake} not to recompile files that depend on it
(provided other sources on which these files depend have undergone no
semantic modifications). Note that the debugging information may be
-out of date with respect to the sources if the @emph{-m} switch causes
+out of date with respect to the sources if the @code{-m} switch causes
a compilation to be switched, so the use of this switch represents a
trade-off between compilation time and accurate debugging information.
@end table
dependences to @code{stdout} in a form that can be directly exploited in
a @code{Makefile}. By default, each source file is prefixed with its
(relative or absolute) directory name. This name is whatever you
-specified in the various @emph{-aI}
-and @emph{-I} switches. If you use
-@cite{gnatmake -M} @emph{-q}
+specified in the various @code{-aI}
+and @code{-I} switches. If you use
+@code{gnatmake -M} @code{-q}
(see below), only the source file names,
-without relative paths, are output. If you just specify the @emph{-M}
+without relative paths, are output. If you just specify the @code{-M}
switch, dependencies of the GNAT internal system files are omitted. This
is typically what you want. If you also specify
-the @emph{-a} switch,
+the @code{-a} switch,
dependencies of the GNAT internal files are also listed. Note that
dependencies of the objects in external Ada libraries (see
switch @code{-aL@emph{dir}} in the following list)
@item @code{-o @emph{exec_name}}
Output executable name. The name of the final executable program will be
-@cite{exec_name}. If the @emph{-o} switch is omitted the default
+@code{exec_name}. If the @code{-o} switch is omitted the default
name for the executable will be the name of the input file in appropriate form
for an executable file on the host system.
-This switch cannot be used when invoking @emph{gnatmake} with several
+This switch cannot be used when invoking @code{gnatmake} with several
@code{file_names}.
@end table
@item @code{-P@emph{project}}
-Use project file @cite{project}. Only one such switch can be used.
-@ref{e1,,gnatmake and Project Files}.
+Use project file @code{project}. Only one such switch can be used.
@end table
+@c -- Comment:
+@c :ref:`gnatmake_and_Project_Files`.
+
@geindex -q (gnatmake)
@item @code{-q}
Quiet. When this flag is not set, the commands carried out by
-@emph{gnatmake} are displayed.
+@code{gnatmake} are displayed.
@end table
@geindex -s (gnatmake)
following way:
orders between different 'first letter' switches are ignored, but
orders between same switches are taken into account. For example,
-@emph{-O -O2} is different than @emph{-O2 -O}, but @emph{-g -O}
-is equivalent to @emph{-O -g}.
+@code{-O -O2} is different than @code{-O2 -O}, but @code{-g -O}
+is equivalent to @code{-O -g}.
This switch is recommended when Integrated Preprocessing is used.
@end table
Unique. Recompile at most the main files. It implies -c. Combined with
-f, it is equivalent to calling the compiler directly. Note that using
--u with a project file and no main has a special meaning
-(@ref{e2,,Project Files and Main Subprograms}).
+-u with a project file and no main has a special meaning.
@end table
+@c --Comment
+@c (See :ref:`Project_Files_and_Main_Subprograms`.)
+
@geindex -U (gnatmake)
@item @code{-v}
-Verbose. Display the reason for all recompilations @emph{gnatmake}
+Verbose. Display the reason for all recompilations @code{gnatmake}
decides are necessary, with the highest verbosity level.
@end table
@item @code{-vP@emph{x}}
Indicate the verbosity of the parsing of GNAT project files.
-See @ref{e3,,Switches Related to Project Files}.
+See @ref{cf,,Switches Related to Project Files}.
@end table
@geindex -x (gnatmake)
Files may be compiled. The ALI file and the object file will be put in the
object directory of the main Project. The compilation switches used will only
be those specified on the command line. Even when
-@emph{-x} is used, mains specified on the
+@code{-x} is used, mains specified on the
command line need to be sources of a project file.
@item @code{-X@emph{name}=@emph{value}}
-Indicate that external variable @cite{name} has the value @cite{value}.
+Indicate that external variable @code{name} has the value @code{value}.
The Project Manager will use this value for occurrences of
-@cite{external(name)} when parsing the project file.
-@ref{e3,,Switches Related to Project Files}.
+@code{external(name)} when parsing the project file.
+@ref{cf,,Switches Related to Project Files}.
@end table
@geindex -z (gnatmake)
@subsubheading GCC switches
-Any uppercase or multi-character switch that is not a @emph{gnatmake} switch
-is passed to @emph{gcc} (e.g., @emph{-O}, @emph{-gnato,} etc.)
+Any uppercase or multi-character switch that is not a @code{gnatmake} switch
+is passed to @code{gcc} (e.g., @code{-O}, @code{-gnato,} etc.)
@subsubheading Source and library search path switches
@item @code{-aI@emph{dir}}
-When looking for source files also look in directory @cite{dir}.
+When looking for source files also look in directory @code{dir}.
The order in which source files search is undertaken is
-described in @ref{8e,,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)
@item @code{-aL@emph{dir}}
-Consider @cite{dir} as being an externally provided Ada library.
-Instructs @emph{gnatmake} to skip compilation units whose @code{.ALI}
-files have been located in directory @cite{dir}. This allows you to have
-missing bodies for the units in @cite{dir} and to ignore out of date bodies
+Consider @code{dir} as being an externally provided Ada library.
+Instructs @code{gnatmake} to skip compilation units whose @code{.ALI}
+files have been located in directory @code{dir}. This allows you to have
+missing bodies for the units in @code{dir} and to ignore out of date bodies
for the same units. You still need to specify
the location of the specs for these units by using the switches
@code{-aI@emph{dir}} or @code{-I@emph{dir}}.
Note: this switch is provided for compatibility with previous versions
-of @emph{gnatmake}. The easier method of causing standard libraries
+of @code{gnatmake}. The easier method of causing standard libraries
to be excluded from consideration is to write-protect the corresponding
ALI files.
@end table
@item @code{-aO@emph{dir}}
When searching for library and object files, look in directory
-@cite{dir}. The order in which library files are searched is described in
-@ref{91,,Search Paths for gnatbind}.
+@code{dir}. The order in which library files are searched is described in
+@ref{76,,Search Paths for gnatbind}.
@end table
@geindex Search paths
Do not look for source files in the directory containing the source
file named in the command line.
Do not look for ALI or object files in the directory
-where @emph{gnatmake} was invoked.
+where @code{gnatmake} was invoked.
@end table
@geindex -L (gnatmake)
@item @code{-L@emph{dir}}
-Add directory @cite{dir} to the list of directories in which the linker
+Add directory @code{dir} to the list of directories in which the linker
will search for libraries. This is equivalent to
@code{-largs} @code{-L@emph{dir}}.
Furthermore, under Windows, the sources pointed to by the libraries path
@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{e4}@anchor{gnat_ugn/building_executable_programs_with_gnat mode-switches-for-gnatmake}@anchor{e5}
-@subsection Mode Switches for @emph{gnatmake}
+@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}
-The mode switches (referred to as @cite{mode_switches}) allow the
+The mode switches (referred to as @code{mode_switches}) allow the
inclusion of switches that are to be passed to the compiler itself, the
binder or the linker. The effect of a mode switch is to cause all
subsequent switches up to the end of the switch list, or up to the next
@item @code{-cargs @emph{switches}}
-Compiler switches. Here @cite{switches} is a list of switches
-that are valid switches for @emph{gcc}. They will be passed on to
-all compile steps performed by @emph{gnatmake}.
+Compiler switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gcc}. They will be passed on to
+all compile steps performed by @code{gnatmake}.
@end table
@geindex -bargs (gnatmake)
@item @code{-bargs @emph{switches}}
-Binder switches. Here @cite{switches} is a list of switches
-that are valid switches for @cite{gnatbind}. They will be passed on to
-all bind steps performed by @emph{gnatmake}.
+Binder switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gnatbind}. They will be passed on to
+all bind steps performed by @code{gnatmake}.
@end table
@geindex -largs (gnatmake)
@item @code{-largs @emph{switches}}
-Linker switches. Here @cite{switches} is a list of switches
-that are valid switches for @emph{gnatlink}. They will be passed on to
-all link steps performed by @emph{gnatmake}.
+Linker switches. Here @code{switches} is a list of switches
+that are valid switches for @code{gnatlink}. They will be passed on to
+all link steps performed by @code{gnatmake}.
@end table
@geindex -margs (gnatmake)
@item @code{-margs @emph{switches}}
-Make switches. The switches are directly interpreted by @emph{gnatmake},
-regardless of any previous occurrence of @emph{-cargs}, @emph{-bargs}
-or @emph{-largs}.
+Make switches. The switches are directly interpreted by @code{gnatmake},
+regardless of any previous occurrence of @code{-cargs}, @code{-bargs}
+or @code{-largs}.
@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{e6}@anchor{gnat_ugn/building_executable_programs_with_gnat notes-on-the-command-line}@anchor{e7}
+@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
This section contains some additional useful notes on the operation
-of the @emph{gnatmake} command.
+of the @code{gnatmake} command.
@geindex Recompilation (by gnatmake)
@itemize *
@item
-If @emph{gnatmake} finds no ALI files, it recompiles the main program
+If @code{gnatmake} finds no ALI files, it recompiles the main program
and all other units required by the main program.
-This means that @emph{gnatmake}
+This means that @code{gnatmake}
can be used for the initial compile, as well as during subsequent steps of
the development cycle.
@item
If you enter @code{gnatmake foo.adb}, where @code{foo}
-is a subunit or body of a generic unit, @emph{gnatmake} recompiles
+is a subunit or body of a generic unit, @code{gnatmake} recompiles
@code{foo.adb} (because it finds no ALI) and stops, issuing a
warning.
@item
-In @emph{gnatmake} the switch @emph{-I}
+In @code{gnatmake} the switch @code{-I}
is used to specify both source and
-library file paths. Use @emph{-aI}
+library file paths. Use @code{-aI}
instead if you just want to specify
-source paths only and @emph{-aO}
+source paths only and @code{-aO}
if you want to specify library paths
only.
@item
-@emph{gnatmake} will ignore any files whose ALI file is write-protected.
+@code{gnatmake} will ignore any files whose ALI file is write-protected.
This may conveniently be used to exclude standard libraries from
consideration and in particular it means that the use of the
-@emph{-f} switch will not recompile these files
-unless @emph{-a} is also specified.
+@code{-f} switch will not recompile these files
+unless @code{-a} is also specified.
@item
-@emph{gnatmake} has been designed to make the use of Ada libraries
+@code{gnatmake} has been designed to make the use of Ada libraries
particularly convenient. Assume you have an Ada library organized
as follows: @emph{obj-dir} contains the objects and ALI files for
of your Ada compilation units,
whereas @emph{include-dir} contains the
specs of these units, but no bodies. Then to compile a unit
-stored in @cite{main.adb}, which uses this Ada library you would just type:
+stored in @code{main.adb}, which uses this Ada library you would just type:
@example
$ gnatmake -aI`include-dir` -aL`obj-dir` main
@end example
@item
-Using @emph{gnatmake} along with the @emph{-m (minimal recompilation)}
+Using @code{gnatmake} along with the @code{-m (minimal recompilation)}
switch provides a mechanism for avoiding unnecessary recompilations. Using
this switch,
you can update the comments/format of your
@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{e8}@anchor{gnat_ugn/building_executable_programs_with_gnat how-gnatmake-works}@anchor{e9}
-@subsection How @emph{gnatmake} Works
+@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
-Generally @emph{gnatmake} automatically performs all necessary
+Generally @code{gnatmake} automatically performs all necessary
recompilations and you don't need to worry about how it works. However,
-it may be useful to have some basic understanding of the @emph{gnatmake}
+it may be useful to have some basic understanding of the @code{gnatmake}
approach and in particular to understand how it uses the results of
previous compilations without incorrectly depending on them.
files that it depends on have been modified, and hence there is no need
to recompile this file.
-@emph{gnatmake} works by first checking if the specified main unit is up
+@code{gnatmake} works by first checking if the specified main unit is up
to date. If so, no compilations are required for the main unit. If not,
-@emph{gnatmake} compiles the main program to build a new ALI file that
+@code{gnatmake} compiles the main program to build a new ALI file that
reflects the latest sources. Then the ALI file of the main unit is
examined to find all the source files on which the main program depends,
-and @emph{gnatmake} recursively applies the above procedure on all these
+and @code{gnatmake} recursively applies the above procedure on all these
files.
-This process ensures that @emph{gnatmake} only trusts the dependencies
+This process ensures that @code{gnatmake} only trusts the dependencies
in an existing ALI file if they are known to be correct. Otherwise it
always recompiles to determine a new, guaranteed accurate set of
dependencies. As a result the program is compiled 'upside down' from what may
systems. In particular, clients are compiled before the units on which
they depend. The ability of GNAT to compile in any order is critical in
allowing an order of compilation to be chosen that guarantees that
-@emph{gnatmake} will recompute a correct set of new dependencies if
+@code{gnatmake} will recompute a correct set of new dependencies if
necessary.
-When invoking @emph{gnatmake} with several @cite{file_names}, if a unit is
+When invoking @code{gnatmake} with several @code{file_names}, if a unit is
imported by several of the executables, it will be recompiled at most once.
Note: when using non-standard naming conventions
-(@ref{37,,Using Other File Names}), changing through a configuration pragmas
-file the version of a source and invoking @emph{gnatmake} to recompile may
+(@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 @emph{gnatmake}. It may be necessary to use the switch
+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{ea}@anchor{gnat_ugn/building_executable_programs_with_gnat id7}@anchor{eb}
-@subsection Examples of @emph{gnatmake} Usage
+@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
@item @emph{gnatmake hello.adb}
Compile all files necessary to bind and link the main program
-@code{hello.adb} (containing unit @cite{Hello}) and bind and link the
+@code{hello.adb} (containing unit @code{Hello}) and bind and link the
resulting object files to generate an executable file @code{hello}.
@item @emph{gnatmake main1 main2 main3}
Compile all files necessary to bind and link the main programs
-@code{main1.adb} (containing unit @cite{Main1}), @code{main2.adb}
-(containing unit @cite{Main2}) and @code{main3.adb}
-(containing unit @cite{Main3}) and bind and link the resulting object files
+@code{main1.adb} (containing unit @code{Main1}), @code{main2.adb}
+(containing unit @code{Main2}) and @code{main3.adb}
+(containing unit @code{Main3}) and bind and link the resulting object files
to generate three executable files @code{main1},
@code{main2} and @code{main3}.
@item @emph{gnatmake -q Main_Unit -cargs -O2 -bargs -l}
Compile all files necessary to bind and link the main program unit
-@cite{Main_Unit} (from file @code{main_unit.adb}). All compilations will
+@code{Main_Unit} (from file @code{main_unit.adb}). All compilations will
be done with optimization level 2 and the order of elaboration will be
-listed by the binder. @emph{gnatmake} will operate in quiet mode, not
+listed by the binder. @code{gnatmake} will operate in quiet mode, not
displaying commands it is executing.
@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{1e}@anchor{gnat_ugn/building_executable_programs_with_gnat id8}@anchor{ec}
-@section Compiling with @emph{gcc}
+@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}
-This section discusses how to compile Ada programs using the @emph{gcc}
+This section discusses how to compile Ada programs using the @code{gcc}
command. It also describes the set of switches
that can be used to control the behavior of the compiler.
@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{ed}@anchor{gnat_ugn/building_executable_programs_with_gnat id9}@anchor{ee}
+@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 first step in creating an executable program is to compile the units
-of the program using the @emph{gcc} command. You must compile the
+of the program using the @code{gcc} command. You must compile the
following files:
@geindex cannot generate code
If you attempt to compile any of these files, you will get one of the
-following error messages (where @cite{fff} is the name of the file you
+following error messages (where @code{fff} is the name of the file you
compiled):
@quotation
@example
-cannot generate code for file `fff` (package spec)
+cannot generate code for file `@w{`}fff`@w{`} (package spec)
to check package spec, use -gnatc
-cannot generate code for file `fff` (missing subunits)
+cannot generate code for file `@w{`}fff`@w{`} (missing subunits)
to check parent unit, use -gnatc
-cannot generate code for file `fff` (subprogram spec)
+cannot generate code for file `@w{`}fff`@w{`} (subprogram spec)
to check subprogram spec, use -gnatc
-cannot generate code for file `fff` (subunit)
+cannot generate code for file `@w{`}fff`@w{`} (subunit)
to check subunit, use -gnatc
@end example
@end quotation
As indicated by the above error messages, if you want to submit
one of these files to the compiler to check for correct semantics
-without generating code, then use the @emph{-gnatc} switch.
+without generating code, then use the @code{-gnatc} switch.
The basic command for compiling a file containing an Ada unit is:
$ gcc -c [switches] <file name>
@end example
-where @cite{file name} is the name of the Ada file (usually
+where @code{file name} is the name of the Ada file (usually
having an extension @code{.ads} for a spec or @code{.adb} for a body).
You specify the
-@code{-c} switch to tell @emph{gcc} to compile, but not link, the file.
+@code{-c} switch to tell @code{gcc} to compile, but not link, the file.
The result of a successful compilation is an object file, which has the
same name as the source file but an extension of @code{.o} and an Ada
Library Information (ALI) file, which also has the same name as the
file in any directory using an absolute or relative path specification
containing the directory information.
+TESTING: the @code{--foobar@emph{NN}} switch
+
@geindex gnat1
-@emph{gcc} is actually a driver program that looks at the extensions of
+@code{gcc} is actually a driver program that looks at the extensions of
the file arguments and loads the appropriate compiler. For example, the
GNU C compiler is @code{cc1}, and the Ada compiler is @code{gnat1}.
These programs are in directories known to the driver program (in some
configurations via environment variables you set), but need not be in
-your path. The @emph{gcc} driver also calls the assembler and any other
+your path. The @code{gcc} driver also calls the assembler and any other
utilities needed to complete the generation of the required object
files.
-It is possible to supply several file names on the same @emph{gcc}
-command. This causes @emph{gcc} to call the appropriate compiler for
+It is possible to supply several file names on the same @code{gcc}
+command. This causes @code{gcc} to call the appropriate compiler for
each file. For example, the following command lists two separate
files to be compiled:
$ gcc -c x.adb y.adb
@end example
-calls @cite{gnat1} (the Ada compiler) twice to compile @code{x.adb} and
+calls @code{gnat1} (the Ada compiler) twice to compile @code{x.adb} and
@code{y.adb}.
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{ef,,Compiler Switches} for a
-list of available @emph{gcc} switches.
+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{f0}@anchor{gnat_ugn/building_executable_programs_with_gnat search-paths-and-the-run-time-library-rtl}@anchor{8e}
+@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 file name on the command line).
@item
-Each directory named by an @emph{-I} switch given on the @emph{gcc}
+Each directory named by an @code{-I} switch given on the @code{gcc}
command line, in the order given.
@geindex ADA_PRJ_INCLUDE_FILE
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{8b,,Installing a library}
+@ref{71,,Installing a library}
@end itemize
-Specifying the switch @emph{-I-}
+Specifying the switch @code{-I-}
inhibits the use of the directory
containing the source file named in the command line. You can still
have this directory on your search path, but in this case it must be
-explicitly requested with a @emph{-I} switch.
+explicitly requested with a @code{-I} switch.
-Specifying the switch @emph{-nostdinc}
+Specifying the switch @code{-nostdinc}
inhibits the search of the default location for the GNAT Run Time
Library (RTL) source files.
The compiler outputs its object files and ALI files in the current
working directory.
-Caution: The object file can be redirected with the @emph{-o} switch;
-however, @emph{gcc} and @cite{gnat1} have not been coordinated on this
+Caution: The object file can be redirected with the @code{-o} switch;
+however, @code{gcc} and @code{gnat1} have not been coordinated on this
so the @code{ALI} file will not go to the right place. Therefore, you should
-avoid using the @emph{-o} switch.
+avoid using the @code{-o} switch.
@geindex System.IO
-The packages @cite{Ada}, @cite{System}, and @cite{Interfaces} and their
-children make up the GNAT RTL, together with the simple @cite{System.IO}
-package used in the @cite{"Hello World"} example. The sources for these units
+The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
+children make up the GNAT RTL, together with the simple @code{System.IO}
+package used in the @code{"Hello World"} example. The sources for these units
are needed by the compiler and are kept together in one directory. Not
all of the bodies are needed, but all of the sources are kept together
anyway. In a normal installation, you need not specify these directory
names when compiling or binding. Either the environment variables or
the built-in defaults cause these files to be found.
-In addition to the language-defined hierarchies (@cite{System}, @cite{Ada} and
-@cite{Interfaces}), the GNAT distribution provides a fourth hierarchy,
-consisting of child units of @cite{GNAT}. This is a collection of generally
+In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
+@code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
+consisting of child units of @code{GNAT}. This is a collection of generally
useful types, subprograms, etc. See the @cite{GNAT_Reference_Manual}
for further details.
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{f1}@anchor{gnat_ugn/building_executable_programs_with_gnat order-of-compilation-issues}@anchor{f2}
+@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
-If, in our earlier example, there was a spec for the @cite{hello}
+If, in our earlier example, there was a spec for the @code{hello}
procedure, it would be contained in the file @code{hello.ads}; yet this
file would not have to be explicitly compiled. This is the result of the
model we chose to implement library management. Some of the consequences
@item
There is no library as such, apart from the ALI files
-(@ref{44,,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{f3}@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{f4}
+@anchor{gnat_ugn/building_executable_programs_with_gnat id12}@anchor{df}@anchor{gnat_ugn/building_executable_programs_with_gnat examples}@anchor{e0}
@subsection Examples
@end example
Compile the child unit package in file @code{xyz-def.adb} with extensive
-optimizations, and pragma @cite{Assert}/@cite{Debug} statements
+optimizations, and pragma @code{Assert}/@cite{Debug} statements
enabled.
@example
Compile the subunit in file @code{abc-def.adb} in semantic-checking-only
mode.
-@node Compiler Switches,Binding with gnatbind,Compiling with gcc,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat compiler-switches}@anchor{f5}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gcc}@anchor{ef}
+@node Compiler Switches,Linker Switches,Compiling with gcc,Building Executable Programs with GNAT
+@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
-The @emph{gcc} command accepts switches that control the
+The @code{gcc} command accepts switches that control the
compilation process. These switches are fully described in this section:
first an alphabetical listing of all switches with a brief description,
and then functionally grouped sets of switches with more detailed
@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{f6}@anchor{gnat_ugn/building_executable_programs_with_gnat alphabetical-list-of-all-switches}@anchor{f7}
+@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
@item @code{-b @emph{target}}
-Compile your program to run on @cite{target}, which is the name of a
+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
-@cite{target} is not the same as your host system.
+@code{target} is not the same as your host system.
@end table
@geindex -B (gcc)
@item @code{-B@emph{dir}}
-Load compiler executables (for example, @cite{gnat1}, the Ada compiler)
-from @cite{dir} instead of the default location. Only use this switch
+Load compiler executables (for example, @code{gnat1}, the Ada compiler)
+from @code{dir} instead of the default location. Only use this switch
when multiple versions of the GNAT compiler are available.
See the "Options for Directory Search" section in the
@cite{Using the GNU Compiler Collection (GCC)} manual for further details.
-You would normally use the @emph{-b} or @emph{-V} switch instead.
+You would normally use the @code{-b} or @code{-V} switch instead.
@end table
@geindex -c (gcc)
Compile. Always use this switch when compiling Ada programs.
-Note: for some other languages when using @emph{gcc}, notably in
+Note: for some other languages when using @code{gcc}, notably in
the case of C and C++, it is possible to use
-use @emph{gcc} without a @emph{-c} switch to
+use @code{gcc} without a @code{-c} switch to
compile and link in one step. In the case of GNAT, you
cannot use this approach, because the binder must be run
-and @emph{gcc} cannot be used to run the GNAT binder.
+and @code{gcc} cannot be used to run the GNAT binder.
@end table
@geindex -fcallgraph-info (gcc)
per-file basis. The information is generated in the VCG format. It can
be decorated with additional, per-node and/or per-edge information, if a
list of comma-separated markers is additionally specified. When the
-@cite{su} marker is specified, the callgraph is decorated with stack usage
-information; it is equivalent to @emph{-fstack-usage}. When the @cite{da}
+@code{su} marker is specified, the callgraph is decorated with stack usage
+information; it is equivalent to @code{-fstack-usage}. When the @code{da}
marker is specified, the callgraph is decorated with information about
dynamically allocated objects.
@end table
@code{scos.adb}.
@end table
-@geindex -fdump-xref (gcc)
+@geindex -fgnat-encodings (gcc)
@table @asis
-@item @code{-fdump-xref}
+@item @code{-fgnat-encodings=[all|gdb|minimal]}
-Generates cross reference information in GLI files for C and C++ sources.
-The GLI files have the same syntax as the ALI files for Ada, and can be used
-for source navigation in IDEs and on the command line using e.g. gnatxref
-and the @emph{--ext=gli} switch.
+This switch controls the balance between GNAT encodings and standard DWARF
+emitted in the debug information.
@end table
@geindex -flto (gcc)
@item @code{-flto[=@emph{n}]}
Enables Link Time Optimization. This switch must be used in conjunction
-with the traditional @emph{-Ox} switches and instructs the compiler to
-defer most optimizations until the link stage. The advantage of this
+with the @code{-Ox} switches (but not with the @code{-gnatn} switch
+since it is a full replacement for the latter) and instructs the compiler
+to defer most optimizations until the link stage. The advantage of this
approach is that the compiler can do a whole-program analysis and choose
the best interprocedural optimization strategy based on a complete view
of the program, instead of a fragmentary view with the usual approach.
This can also speed up the compilation of big programs and reduce the
size of the executable, compared with a traditional per-unit compilation
-with inlining across modules enabled by the @emph{-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 @emph{-Ox} switches, must be
+The switch, as well as the accompanying @code{-Ox} switches, must be
specified both for the compilation and the link phases.
-If the @cite{n} parameter is specified, the optimization and final code
-generation at link time are executed using @cite{n} parallel jobs by
-means of an installed @emph{make} program.
+If the @code{n} parameter is specified, the optimization and final code
+generation at link time are executed using @code{n} parallel jobs by
+means of an installed @code{make} program.
@end table
@geindex -fno-inline (gcc)
@item @code{-fno-inline}
-Suppresses all inlining, unless requested with pragma @cite{Inline_Always}. The
+Suppresses all inlining, unless requested with pragma @code{Inline_Always}. The
effect is enforced regardless of other optimization or inlining switches.
Note that inlining can also be suppressed on a finer-grained basis with
-pragma @cite{No_Inline}.
+pragma @code{No_Inline}.
@end table
@geindex -fno-inline-functions (gcc)
@item @code{-fno-inline-functions}
Suppresses automatic inlining of subprograms, which is enabled
-if @emph{-O3} is used.
+if @code{-O3} is used.
@end table
@geindex -fno-inline-small-functions (gcc)
@item @code{-fno-inline-small-functions}
Suppresses automatic inlining of small subprograms, which is enabled
-if @emph{-O2} is used.
+if @code{-O2} is used.
@end table
@geindex -fno-inline-functions-called-once (gcc)
@item @code{-fno-inline-functions-called-once}
Suppresses inlining of subprograms local to the unit and called once
-from within it, which is enabled if @emph{-O1} is used.
+from within it, which is enabled if @code{-O1} is used.
@end table
@geindex -fno-ivopts (gcc)
@item @code{-fno-ivopts}
Suppresses high-level loop induction variable optimizations, which are
-enabled if @emph{-O1} is used. These optimizations are generally
+enabled if @code{-O1} is used. These optimizations are generally
profitable but, for some specific cases of loops with numerous uses
of the iteration variable that follow a common pattern, they may end
up destroying the regularity that could be exploited at a lower level
Causes the compiler to avoid assumptions regarding non-aliasing
of objects of different types. See
-@ref{f8,,Optimization and Strict Aliasing} for details.
+@ref{e4,,Optimization and Strict Aliasing} for details.
+@end table
+
+@geindex -fno-strict-overflow (gcc)
+
+
+@table @asis
+
+@item @code{-fno-strict-overflow}
+
+Causes the compiler to avoid assumptions regarding the rules of signed
+integer overflow. These rules specify that signed integer overflow will
+result in a Constraint_Error exception at run time and are enforced in
+default mode by the compiler, so this switch should not be necessary in
+normal operating mode. It might be useful in conjunction with @code{-gnato0}
+for very peculiar cases of low-level programming.
@end table
@geindex -fstack-check (gcc)
@item @code{-fstack-check}
Activates stack checking.
-See @ref{f9,,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{fa,,Static Stack Usage Analysis} for details.
+per-subprogram basis. See @ref{e6,,Static Stack Usage Analysis} for details.
@end table
@geindex -g (gcc)
Generate debugging information. This information is stored in the object
file and copied from there to the final executable file by the linker,
where it can be read by the debugger. You must use the
-@emph{-g} switch if you plan on using the debugger.
+@code{-g} switch if you plan on using the debugger.
@end table
@geindex -gnat05 (gcc)
@item @code{-gnat2005}
-Allow full Ada 2005 features (same as @emph{-gnat05})
+Allow full Ada 2005 features (same as @code{-gnat05})
@end table
@geindex -gnat2012 (gcc)
@item @code{-gnat2012}
-Allow full Ada 2012 features (same as @emph{-gnat12})
+Allow full Ada 2012 features (same as @code{-gnat12})
@item @code{-gnat83}
Enforce Ada 95 restrictions.
Note: for compatibility with some Ada 95 compilers which support only
-the @cite{overriding} keyword of Ada 2005, the @emph{-gnatd.D} switch can
-be used along with @emph{-gnat95} to achieve a similar effect with GNAT.
+the @code{overriding} keyword of Ada 2005, the @code{-gnatd.D} switch can
+be used along with @code{-gnat95} to achieve a similar effect with GNAT.
-@emph{-gnatd.D} instructs GNAT to consider @cite{overriding} as a keyword
+@code{-gnatd.D} instructs GNAT to consider @code{overriding} as a keyword
and handle its associated semantic checks, even in Ada 95 mode.
@end table
@item @code{-gnata}
-Assertions enabled. @cite{Pragma Assert} and @cite{pragma Debug} to be
+Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
activated. Note that these pragmas can also be controlled using the
-configuration pragmas @cite{Assertion_Policy} and @cite{Debug_Policy}.
-It also activates pragmas @cite{Check}, @cite{Precondition}, and
-@cite{Postcondition}. Note that these pragmas can also be controlled
-using the configuration pragma @cite{Check_Policy}. In Ada 2012, it
+configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
+It also activates pragmas @code{Check}, @code{Precondition}, and
+@code{Postcondition}. Note that these pragmas can also be controlled
+using the configuration pragma @code{Check_Policy}. In Ada 2012, it
also activates all assertions defined in the RM as aspects: preconditions,
postconditions, type invariants and (sub)type predicates. In all Ada modes,
corresponding pragmas for type invariants and (sub)type predicates are
@item @code{-gnatB}
Assume no invalid (bad) values except for 'Valid attribute use
-(@ref{fb,,Validity Checking}).
+(@ref{e7,,Validity Checking}).
@end table
@geindex -gnatc (gcc)
@item @code{-gnatc}
Check syntax and semantics only (no code generation attempted). When the
-compiler is invoked by @emph{gnatmake}, if the switch @emph{-gnatc} is
-only given to the compiler (after @emph{-cargs} or in package Compiler of
-the project file, @emph{gnatmake} will fail because it will not find the
-object file after compilation. If @emph{gnatmake} is called with
-@emph{-gnatc} as a builder switch (before @emph{-cargs} or in package
-Builder of the project file) then @emph{gnatmake} will not fail because
+compiler is invoked by @code{gnatmake}, if the switch @code{-gnatc} is
+only given to the compiler (after @code{-cargs} or in package Compiler of
+the project file, @code{gnatmake} will fail because it will not find the
+object file after compilation. If @code{gnatmake} is called with
+@code{-gnatc} as a builder switch (before @code{-cargs} or in package
+Builder of the project file) then @code{gnatmake} will not fail because
it will not look for the object files after compilation, and it will not try
-to build and link. This switch may not be given if a previous @cite{-gnatR}
-switch has been given, since @cite{-gnatR} requires that the code generator
-be called to complete determination of representation information.
+to build and link.
@end table
@geindex -gnatC (gcc)
@item @code{-gnatd}
Specify debug options for the compiler. The string of characters after
-the @emph{-gnatd} specify the specific debug options. The possible
+the @code{-gnatd} specify the specific debug options. The possible
characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
compiler source file @code{debug.adb} for details of the implemented
debug options. Certain debug options are relevant to applications
@item @code{-gnatD}
Create expanded source files for source level debugging. This switch
-also suppress generation of cross-reference information
-(see @emph{-gnatx}). Note that this switch is not allowed if a previous
+also suppresses generation of cross-reference information
+(see @code{-gnatx}). Note that this switch is not allowed if a previous
-gnatR switch has been given, since these two switches are not compatible.
@end table
Detect_Aliasing (Obj, Self (Obj));
@end example
-In the example above, the first call to @cite{Detect_Aliasing} fails with a
-@cite{Program_Error} at runtime because the actuals for @cite{Val_1} and
-@cite{Val_2} denote the same object. The second call executes without raising
-an exception because @cite{Self(Obj)} produces an anonymous object which does
-not share the memory location of @cite{Obj}.
+In the example above, the first call to @code{Detect_Aliasing} fails with a
+@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{7b,,The Configuration Pragmas Files}).
+(@ref{62,,The Configuration Pragmas Files}).
@end table
@geindex -gnateC (gcc)
@item @code{-gnateC}
Generate CodePeer messages in a compiler-like format. This switch is only
-effective if @emph{-gnatcC} is also specified and requires an installation
+effective if @code{-gnatcC} is also specified and requires an installation
of CodePeer.
@end table
@item @code{-gnateDsymbol[=@emph{value}]}
-Defines a symbol, associated with @cite{value}, for preprocessing.
-(@ref{1a,,Integrated Preprocessing}).
+Defines a symbol, associated with @code{value}, for preprocessing.
+(@ref{90,,Integrated Preprocessing}).
@end table
@geindex -gnateE (gcc)
Check for overflow on all floating-point operations, including those
for unconstrained predefined types. See description of pragma
-@cite{Check_Float_Overflow} in GNAT RM.
+@code{Check_Float_Overflow} in GNAT RM.
@end table
+@geindex -gnateg (gcc)
+
+@code{-gnateg}
+@code{-gnatceg}
+
+@quotation
+
+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{b7,,Generating C Headers for Ada Specifications} for more
+information.
+@end quotation
+
@geindex -gnateG (gcc)
@item @code{-gnatei@emph{nnn}}
Set maximum number of instantiations during compilation of a single unit to
-@cite{nnn}. This may be useful in increasing the default maximum of 8000 for
+@code{nnn}. This may be useful in increasing the default maximum of 8000 for
the rare case when a single unit legitimately exceeds this limit.
@end table
@item @code{-gnateI@emph{nnn}}
Indicates that the source is a multi-unit source and that the index of the
-unit to compile is @cite{nnn}. @cite{nnn} needs to be a positive number and need
+unit to compile is @code{nnn}. @code{nnn} needs to be a positive number and need
to be a valid index in the multi-unit source.
@end table
This switch can be used with the static elaboration model to issue info
messages showing
-where implicit @cite{pragma Elaborate} and @cite{pragma Elaborate_All}
+where implicit @code{pragma Elaborate} and @code{pragma Elaborate_All}
are generated. This is useful in diagnosing elaboration circularities
caused by these implicit pragmas when using the static elaboration
model. See See the section in this guide on elaboration checking for
Specify a mapping file
(the equal sign is optional)
-(@ref{fc,,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{1a,,Integrated Preprocessing}).
+(@ref{90,,Integrated Preprocessing}).
@end table
@geindex -gnateP (gcc)
@item @code{-gnateS}
-Synonym of @emph{-fdump-scos}, kept for backwards compatibility.
+Synonym of @code{-fdump-scos}, kept for backwards compatibility.
@end table
@geindex -gnatet=file (gcc)
@item @code{-gnatet=@emph{path}}
Generate target dependent information. The format of the output file is
-described in the section about switch @emph{-gnateT}.
+described in the section about switch @code{-gnateT}.
@end table
@geindex -gnateT (gcc)
the machine on which the tool is run.
The following target dependent values should be defined,
-where @cite{Nat} denotes a natural integer value, @cite{Pos} denotes a
+where @code{Nat} denotes a natural integer value, @code{Pos} denotes a
positive integer value, and fields marked with a question mark are
boolean fields, where a value of 0 is False, and a value of 1 is True:
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:
name value
@end example
-where @cite{name} is the name of the parameter, spelled out in full,
-and cased as in the above list, and @cite{value} is an unsigned decimal
+where @code{name} is the name of the parameter, spelled out in full,
+and cased as in the above list, and @code{value} is an unsigned decimal
integer. Two or more blanks separates the name from the value.
All the variables must be present, in alphabetical order (i.e. the
name digs float_rep size alignment
@end example
-where @cite{name} is the string name of the type (which can have
-single spaces embedded in the name (e.g. long double), @cite{digs} is
-the number of digits for the floating-point type, @cite{float_rep} is
+where @code{name} is the string name of the type (which can have
+single spaces embedded in the name (e.g. long double), @code{digs} is
+the number of digits for the floating-point type, @code{float_rep} is
the float representation (I/V/A for IEEE-754-Binary, Vax_Native,
-AAMP), @cite{size} is the size in bits, @cite{alignment} is the
+AAMP), @code{size} is the size in bits, @code{alignment} is the
alignment in bits. The name is followed by at least two blanks, fields
are separated by at least one blank, and a LF character immediately
follows the alignment field.
@item @code{-gnateV}
Check that all actual parameters of a subprogram call are valid according to
-the rules of validity checking (@ref{fb,,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 @emph{-gnatg} implies
-@emph{-gnatw.ge} and
-@emph{-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)
@item @code{-gnati@emph{c}}
-Identifier character set (@cite{c} = 1/2/3/4/8/9/p/f/n/w).
-For details of the possible selections for @cite{c},
-see @ref{4a,,Character Set Control}.
+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{31,,Character Set Control}.
@end table
@geindex -gnatI (gcc)
are: enumeration_representation_clause, record_representation_clause,
and attribute_definition_clause for the following attributes:
Address, Alignment, Bit_Order, Component_Size, Machine_Radix,
-Object_Size, Size, Small, Stream_Size, and Value_Size.
+Object_Size, Scalar_Storage_Order, Size, Small, Stream_Size,
+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 @cite{-gnatct} is used to generate trees for input
-into @cite{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)
@item @code{-gnatj@emph{nn}}
-Reformat error messages to fit on @cite{nn} character lines
+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{-gnatk=@emph{n}}
-Limit file names to @cite{n} (1-999) characters (@cite{k} = krunch).
+Limit file names to @code{n} (1-999) characters (@code{k} = krunch).
@end table
@geindex -gnatl (gcc)
@item @code{-gnatm=@emph{n}}
-Limit number of detected error or warning messages to @cite{n}
-where @cite{n} is in the range 1..999999. The default setting if
+Limit number of detected error or warning messages to @code{n}
+where @code{n} is in the range 1..999999. The default setting if
no switch is given is 9999. If the number of warnings reaches this
limit, then a message is output and further warnings are suppressed,
but the compilation is continued. If the number of error messages
@item @code{-gnatn[12]}
-Activate inlining for subprograms for which pragma @cite{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,
+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 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
@item @code{-gnatN}
Activate front end inlining for subprograms for which
-pragma @cite{Inline} is specified. This inlining is performed
+pragma @code{Inline} is specified. This inlining is performed
by the front end and will be visible in the
-@emph{-gnatG} output.
+@code{-gnatG} output.
When using a gcc-based back end (in practice this means using any version
of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
-@emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred.
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
@end table
Suppresses overflow checking. This causes the behavior of the compiler to
match the default for older versions where overflow checking was suppressed
by default. This is equivalent to having
-@cite{pragma Suppress (Overflow_Mode)} in a configuration pragma file.
+@code{pragma Suppress (Overflow_Check)} in a configuration pragma file.
@end table
@geindex -gnato?? (gcc)
@item @code{-gnato??}
Set default mode for handling generation of code to avoid intermediate
-arithmetic overflow. Here @cite{??} is two digits, a
-single digit, or nothing. Each digit is one of the digits @cite{1}
-through @cite{3}:
+arithmetic overflow. Here @code{??} is two digits, a
+single digit, or nothing. Each digit is one of the digits @code{1}
+through @code{3}:
-@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@multitable {xxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item
Digit
@tab
-All intermediate overflows checked against base type (@cite{STRICT})
+All intermediate overflows checked against base type (@code{STRICT})
@item
@tab
-Minimize intermediate overflows (@cite{MINIMIZED})
+Minimize intermediate overflows (@code{MINIMIZED})
@item
@tab
-Eliminate intermediate overflows (@cite{ELIMINATED})
+Eliminate intermediate overflows (@code{ELIMINATED})
@end multitable
assertions, pre/postconditions, and type invariants, and the second
applies within assertions, pre/postconditions, and type invariants.
-If no digits follow the @emph{-gnato}, then it is equivalent to
-@emph{-gnato11},
+If no digits follow the @code{-gnato}, then it is equivalent to
+@code{-gnato11},
causing all intermediate overflows to be handled in strict
mode.
This switch also causes arithmetic overflow checking to be performed
-(as though @cite{pragma Unsuppress (Overflow_Mode)} had been specified).
+(as though @code{pragma Unsuppress (Overflow_Check)} had been specified).
-The default if no option @emph{-gnato} is given is that overflow handling
-is in @cite{STRICT} mode (computations done using the base type), and that
+The default if no option @code{-gnato} is given is that overflow handling
+is in @code{STRICT} mode (computations done using the base type), and that
overflow checking is enabled.
Note that division by zero is a separate check that is not
controlled by this switch (divide-by-zero checking is on by default).
-See also @ref{fd,,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{fe,,Run-Time Checks} for details. This switch
-has no effect if cancelled by a subsequent @emph{-gnat-p} 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
@geindex -gnat-p (gcc)
@item @code{-gnat-p}
-Cancel effect of previous @emph{-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 @cite{Pragma_Polling} in the @cite{GNAT_Reference_Manual} for full
-details.
+Cancel effect of previous @code{-gnatp} switch.
@end table
@geindex -gnatq (gcc)
Don't quit. Generate @code{ALI} and tree files even if illegalities.
Note that code generation is still suppressed in the presence of any
-errors, so even with @emph{-gnatQ} no object file is generated.
+errors, so even with @code{-gnatQ} no object file is generated.
@end table
@geindex -gnatr (gcc)
@table @asis
-@item @code{-gnatR[0/1/2/3[s]]}
-
-Output representation information for declared types and objects.
-Note that this switch is not allowed if a previous @cite{-gnatD} switch has
-been given, since these two switches are not compatible.
+@item @code{-gnatR[0|1|2|3|4][e][j][m][s]}
-@item @code{-gnatRm[s]}
-
-Output convention and parameter passing mechanisms for all subprograms.
+Output representation information for declared types, objects and
+subprograms. Note that this switch is not allowed if a previous
+@code{-gnatD} switch has been given, since these two switches
+are not compatible.
@end table
@geindex -gnats (gcc)
Print package Standard.
@end table
-@geindex -gnatt (gcc)
-
-
-@table @asis
-
-@item @code{-gnatt}
-
-Generate tree output file.
-@end table
-
@geindex -gnatT (gcc)
@item @code{-gnatT@emph{nnn}}
-All compiler tables start at @cite{nnn} times usual starting size.
+All compiler tables start at @code{nnn} times usual starting size.
@end table
@geindex -gnatu (gcc)
@item @code{-gnatV}
-Control level of validity checking (@ref{fb,,Validity Checking}).
+Control level of validity checking (@ref{e7,,Validity Checking}).
@end table
@geindex -gnatw (gcc)
@item @code{-gnatw@emph{xxx}}
Warning mode where
-@cite{xxx} is a string of option letters that denotes
+@code{xxx} is a string of option letters that denotes
the exact warnings that
-are enabled or disabled (@ref{ff,,Warning Message Control}).
+are enabled or disabled (@ref{eb,,Warning Message Control}).
@end table
@geindex -gnatW (gcc)
@item @code{-gnatW@emph{e}}
Wide character encoding method
-(@cite{e}=n/h/u/s/e/8).
+(@code{e}=n/h/u/s/e/8).
@end table
@geindex -gnatx (gcc)
@item @code{-gnaty}
-Enable built-in style checks (@ref{100,,Style Checking}).
+Enable built-in style checks (@ref{ec,,Style Checking}).
@end table
@geindex -gnatz (gcc)
@item @code{-gnatz@emph{m}}
Distribution stub generation and compilation
-(@cite{m}=r/c for receiver/caller stubs).
+(@code{m}=r/c for receiver/caller stubs).
@end table
@geindex -I (gcc)
@geindex RTL
-Direct GNAT to search the @cite{dir} directory for source files needed by
+Direct GNAT to search the @code{dir} directory for source files needed by
the current compilation
-(see @ref{8e,,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{8e,,Search Paths and the Run-Time Library (RTL)}).
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}).
@end table
@geindex -o (gcc)
@item @code{-o @emph{file}}
-This switch is used in @emph{gcc} to redirect the generated object file
+This switch is used in @code{gcc} to redirect the generated object file
and its associated ALI file. Beware of this switch with GNAT, because it may
cause the object file and ALI file to have different names which in turn
may confuse the binder and the linker.
@item @code{-O[@emph{n}]}
-@cite{n} controls the optimization level:
+@code{n} controls the optimization level:
-@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@multitable {xxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
@item
@emph{n}
@tab
-No optimization, the default setting if no @emph{-O} appears
+No optimization, the default setting if no @code{-O} appears
@item
@tab
-Normal optimization, the default if you specify @emph{-O} without an
+Normal optimization, the default if you specify @code{-O} without an
operand. A good compromise between code quality and compilation
time.
@tab
-Same as @emph{-O2}, and also includes inline expansion for small
+Same as @code{-O2}, and also includes inline expansion for small
subprograms in the same unit.
@item
@end multitable
-See also @ref{101,,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 @emph{gnatmake} flag (@ref{df,,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 @code{-S}
-Used in place of @emph{-c} to
+Used in place of @code{-c} to
cause the assembler source file to be
generated, using @code{.s} as the extension,
instead of the object file.
@item @code{-fverbose-asm}
-Used in conjunction with @emph{-S}
+Used in conjunction with @code{-S}
to cause the generated assembly code file to be annotated with variable
names, making it significantly easier to follow.
@end table
@item @code{-v}
-Show commands generated by the @emph{gcc} driver. Normally used only for
+Show commands generated by the @code{gcc} driver. Normally used only for
debugging purposes or if you need to be sure what version of the
compiler you are executing.
@end table
@item @code{-V @emph{ver}}
-Execute @cite{ver} version of the compiler. This is the @emph{gcc}
+Execute @code{ver} version of the compiler. This is the @code{gcc}
version, not the GNAT version.
@end table
Turn off warnings generated by the back end of the compiler. Use of
this switch also causes the default for front end warnings to be set
-to suppress (as though @emph{-gnatws} had appeared at the start of
+to suppress (as though @code{-gnatws} had appeared at the start of
the options).
@end table
@itemize *
@item
-The switch @emph{-gnatc} if combined with other switches must come
+The switch @code{-gnatc} if combined with other switches must come
first in the string.
@item
-The switch @emph{-gnats} if combined with other switches must come
+The switch @code{-gnats} if combined with other switches must come
first in the string.
@item
The switches
-@emph{-gnatzc} and @emph{-gnatzr} may not be combined with any other
+@code{-gnatzc} and @code{-gnatzr} may not be combined with any other
switches, and only one of them may appear in the command line.
@item
-The switch @emph{-gnat-p} may not be combined with any other switch.
+The switch @code{-gnat-p} may not be combined with any other switch.
@item
-Once a 'y' appears in the string (that is a use of the @emph{-gnaty}
+Once a 'y' appears in the string (that is a use of the @code{-gnaty}
switch), then all further characters in the switch are interpreted
-as style modifiers (see description of @emph{-gnaty}).
+as style modifiers (see description of @code{-gnaty}).
@item
-Once a 'd' appears in the string (that is a use of the @emph{-gnatd}
+Once a 'd' appears in the string (that is a use of the @code{-gnatd}
switch), then all further characters in the switch are interpreted
-as debug flags (see description of @emph{-gnatd}).
+as debug flags (see description of @code{-gnatd}).
@item
-Once a 'w' appears in the string (that is a use of the @emph{-gnatw}
+Once a 'w' appears in the string (that is a use of the @code{-gnatw}
switch), then all further characters in the switch are interpreted
-as warning mode modifiers (see description of @emph{-gnatw}).
+as warning mode modifiers (see description of @code{-gnatw}).
@item
-Once a 'V' appears in the string (that is a use of the @emph{-gnatV}
+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{fb,,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{102}@anchor{gnat_ugn/building_executable_programs_with_gnat output-and-error-message-control}@anchor{103}
+@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.
-@cite{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:
@item @code{-gnatv}
-The @cite{v} stands for verbose.
+The @code{v} stands for verbose.
The effect of this setting is to write long-format error
messages to @code{stdout} (the standard output file.
The same program compiled with the
-@emph{-gnatv} switch would generate:
+@code{-gnatv} switch would generate:
@example
3. funcion X (Q : Integer)
@item @code{-gnatl}
-The @cite{l} stands for list.
+The @code{l} stands for list.
This switch causes a full listing of
the file to be generated. In the case where a body is
compiled, the corresponding spec is also listed, along
5. end;
@end example
-When you specify the @emph{-gnatv} or @emph{-gnatl} switches and
+When you specify the @code{-gnatv} or @code{-gnatl} switches and
standard output is redirected, a brief summary is written to
@code{stderr} (standard error) giving the number of error messages and
warning messages generated.
@item @code{-gnatl=@emph{fname}}
-This has the same effect as @emph{-gnatl} except that the output is
+This has the same effect as @code{-gnatl} except that the output is
written to a file instead of to standard output. If the given name
@code{fname} does not start with a period, then it is the full name
of the file to be written. If @code{fname} is an extension, it is
appended to the name of the file being compiled. For example, if
-file @code{xyz.adb} is compiled with @emph{-gnatl=.lst},
+file @code{xyz.adb} is compiled with @code{-gnatl=.lst},
then the output is written to file xyz.adb.lst.
@end table
@item @code{-gnatb}
-The @cite{b} stands for brief.
+The @code{b} stands for brief.
This switch causes GNAT to generate the
brief format error messages to @code{stderr} (the standard error
file) as well as the verbose
@item @code{-gnatm=@emph{n}}
-The @cite{m} stands for maximum.
-@cite{n} is a decimal integer in the
+The @code{m} stands for maximum.
+@code{n} is a decimal integer in the
range of 1 to 999999 and limits the number of error or warning
messages to be generated. For example, using
-@emph{-gnatm2} might yield
+@code{-gnatm2} might yield
@example
e.adb:3:04: Incorrect spelling of keyword "function"
is abandoned. A value of zero means that no limit applies.
Note that the equal sign is optional, so the switches
-@emph{-gnatm2} and @emph{-gnatm=2} are equivalent.
+@code{-gnatm2} and @code{-gnatm=2} are equivalent.
@end table
@geindex -gnatf (gcc)
@geindex Error messages
@geindex suppressing
-The @cite{f} stands for full.
+The @code{f} stands for full.
Normally, the compiler suppresses error messages that are likely to be
redundant. This switch causes all error
messages to be generated. In particular, in the case of
@end example
where the parenthetical comment warns that there are additional
-references to the variable @cite{V}. Compiling the same program with the
-@emph{-gnatf} switch yields
+references to the variable @code{V}. Compiling the same program with the
+@code{-gnatf} switch yields
@example
e.adb:7:07: "V" is undefined
e.adb:9:12: "V" is undefined
@end example
-The @emph{-gnatf} switch also generates additional information for
+The @code{-gnatf} switch also generates additional information for
some error messages. Some examples are:
@item @code{-gnatjnn}
-In normal operation mode (or if @emph{-gnatj0} is used), then error messages
+In normal operation mode (or if @code{-gnatj0} is used), then error messages
with continuation lines are treated as though the continuation lines were
separate messages (and so a warning with two continuation lines counts as
three warnings, and is listed as three separate messages).
-If the @emph{-gnatjnn} switch is used with a positive value for nn, then
+If the @code{-gnatjnn} switch is used with a positive value for nn, then
messages are output in a different manner. A message and all its continuation
lines are treated as a unit, and count as only one warning or message in the
statistics totals. Furthermore, the message is reformatted so that no line
@item @code{-gnatq}
-The @cite{q} stands for quit (really 'don't quit').
+The @code{q} stands for quit (really 'don't quit').
In normal operation mode, the compiler first parses the program and
determines if there are any syntax errors. If there are, appropriate
error messages are generated and compilation is immediately terminated.
@item @code{-gnatQ}
In normal operation mode, the @code{ALI} file is not generated if any
-illegalities are detected in the program. The use of @emph{-gnatQ} forces
+illegalities are detected in the program. The use of @code{-gnatQ} forces
generation of the @code{ALI} file. This file is marked as being in
error, so it cannot be used for binding purposes, but it does contain
reasonably complete cross-reference information, and thus may be useful
for use by tools (e.g., semantic browsing tools or integrated development
environments) that are driven from the @code{ALI} file. This switch
-implies @emph{-gnatq}, since the semantic phase must be run to get a
+implies @code{-gnatq}, since the semantic phase must be run to get a
meaningful ALI file.
-In addition, if @emph{-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 @emph{-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 @emph{-gnatQ} is used and the generated @code{ALI} file is marked as
-being in error, @emph{gnatmake} will attempt to recompile the source when it
-finds such an @code{ALI} file, including with switch @emph{-gnatc}.
+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}.
-Note that @emph{-gnatQ} has no effect if @emph{-gnats} is specified,
-since ALI files are never generated if @emph{-gnats} is set.
+Note that @code{-gnatQ} has no effect if @code{-gnats} is specified,
+since ALI files are never generated if @code{-gnats} is set.
@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{ff}@anchor{gnat_ugn/building_executable_programs_with_gnat id15}@anchor{104}
+@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
for the generation of warning messages. As always, warnings are not
definite indications of errors. For example, if you do an out-of-range
assignment with the deliberate intention of raising a
-@cite{Constraint_Error} exception, then the warning that may be
+@code{Constraint_Error} exception, then the warning that may be
issued does not indicate an error. Some of the situations for which GNAT
issues warnings (at least some of the time) are given in the following
list. This list is not complete, and new warnings are often added to
Variables that are referenced before being initialized
@item
-Task entries with no corresponding @cite{accept} statement
+Task entries with no corresponding @code{accept} statement
@item
-Duplicate accepts for the same task entry in a @cite{select}
+Duplicate accepts for the same task entry in a @code{select}
@item
Objects that take too much storage
Unchecked conversion between types of differing sizes
@item
-Missing @cite{return} statement along some execution path in a function
+Missing @code{return} statement along some execution path in a function
@item
Incorrect (unrecognized) pragmas
Unused @emph{with} clauses
@item
-@cite{Bit_Order} usage that does not have any effect
+@code{Bit_Order} usage that does not have any effect
@item
-@cite{Standard.Duration} used to resolve universal fixed expression
+@code{Standard.Duration} used to resolve universal fixed expression
@item
Dereference of possibly null value
@item
Unreferenced or unmodified variables. Note that a special
exemption applies to variables which contain any of the substrings
-@cite{DISCARD@comma{} DUMMY@comma{} IGNORE@comma{} JUNK@comma{} UNUSED}, in any casing. Such variables
+@code{DISCARD, DUMMY, IGNORE, JUNK, UNUSED}, in any casing. Such variables
are considered likely to be intentionally used in a situation where
otherwise a warning would be given, so warnings of this kind are
always suppressed for such variables.
Access before elaboration detected at compile time
@item
-A range in a @cite{for} loop that is known to be null or might be null
+A range in a @code{for} loop that is known to be null or might be null
@end itemize
The following section lists compiler switches that are available
@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.h} (holes in record layouts)
+@item
+@code{-gnatw.j} (late primitives of tagged types)
+
@item
@code{-gnatw.k} (redefinition of names in standard)
@item
@code{-gnatw.o} (values set by out parameters ignored)
+@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)
This switch suppresses all optional warning messages, see remaining list
in this section for details on optional warning messages that can be
-individually controlled. Note that unlike switch @emph{-gnatws}, the
-use of switch @emph{-gnatwA} does not suppress warnings that are
+individually controlled. Note that unlike switch @code{-gnatws}, the
+use of switch @code{-gnatwA} does not suppress warnings that are
normally given unconditionally and cannot be individually controlled
(for example, the warning about a missing exit path in a function).
-Also, again unlike switch @emph{-gnatws}, warnings suppressed by
-the use of switch @emph{-gnatwA} can be individually turned back
-on. For example the use of switch @emph{-gnatwA} followed by
-switch @emph{-gnatwd} will suppress all optional warnings except
+Also, again unlike switch @code{-gnatws}, warnings suppressed by
+the use of switch @code{-gnatwA} can be individually turned back
+on. For example the use of switch @code{-gnatwA} followed by
+switch @code{-gnatwd} will suppress all optional warnings except
the warnings for implicit dereferencing.
@end table
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)
If the compiler can tell that only the equality condition is possible,
then it will warn that the '>' or '<' part of the test
is useless and that the operator could be replaced by '='.
-An example would be comparing a @cite{Natural} variable <= 0.
+An example would be comparing a @code{Natural} variable <= 0.
This warning option also generates warnings if
one or both tests is optimized away in a membership test for integer
enumeration types are not included, since it is common for such tests
to include an end point.
-This warning can also be turned on using @emph{-gnatwa}.
+This warning can also be turned on using @code{-gnatwa}.
@end table
@geindex -gnatwC (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)
If this switch is set, then the use of a prefix of an access type
in an indexed component, slice, or selected component without an
-explicit @cite{.all} will generate a warning. With this warning
+explicit @code{.all} will generate a warning. With this warning
enabled, access checks occur only at points where an explicit
-@cite{.all} appears in the source code (assuming no warnings are
+@code{.all} appears in the source code (assuming no warnings are
generated as a result of this switch). The default is that such
warnings are not generated.
@end table
@item
@emph{[-gnatw?]}
-Used to tag warnings controlled by the switch @emph{-gnatwx} where x
+Used to tag warnings controlled by the switch @code{-gnatwx} where x
is a letter a-z.
@item
@emph{[-gnatw.?]}
-Used to tag warnings controlled by the switch @emph{-gnatw.x} where x
+Used to tag warnings controlled by the switch @code{-gnatw.x} where x
is a letter a-z.
@item
@emph{[-gnatel]}
Used to tag elaboration information (info) messages generated when the
-static model of elaboration is used and the @emph{-gnatel} switch is set.
+static model of elaboration is used and the @code{-gnatel} switch is set.
@item
@emph{[restriction warning]}
Used to tag warning messages for restriction violations, activated by use
-of the pragma @emph{Restriction_Warnings}.
+of the pragma @code{Restriction_Warnings}.
@item
@emph{[warning-as-error]}
@emph{[enabled by default]}
Used to tag all other warnings that are always given by default, unless
warnings are completely suppressed using pragma @emph{Warnings(Off)} or
-the switch @emph{-gnatws}.
+the switch @code{-gnatws}.
@end itemize
@end quotation
@end table
If this switch is set, then warning messages return to the default
mode in which warnings and info messages are not tagged as described above for
-@cite{-gnatw.d}.
+@code{-gnatw.d}.
@end table
@geindex -gnatwe (gcc)
@geindex activate every optional warning
This switch activates all optional warnings, including those which
-are not activated by @cite{-gnatwa}. The use of this switch is not
+are not activated by @code{-gnatwa}. The use of this switch is not
recommended for normal use. If you turn this switch on, it is almost
certain that you will get large numbers of useless warnings. The
-warnings that are excluded from @cite{-gnatwa} are typically highly
+warnings that are excluded from @code{-gnatwa} are typically highly
specialized warnings that are suitable for use only in code that has
been specifically designed according to specialized coding rules.
@end table
+@geindex -gnatwE (gcc)
+
+@geindex Warnings
+@geindex treat as error
+
+
+@table @asis
+
+@item @code{-gnatwE}
+
+@emph{Treat all run-time exception warnings as errors.}
+
+This switch causes warning messages regarding errors that will be raised
+during run-time execution to be treated as errors.
+@end table
+
@geindex -gnatwf (gcc)
This switch causes a warning to be generated if a formal parameter
is not referenced in the body of the subprogram. This warning can
-also be turned on using @emph{-gnatwu}. The
+also be turned on using @code{-gnatwu}. The
default is that these warnings are not generated.
@end table
This switch suppresses warnings for unreferenced formal
parameters. Note that the
-combination @emph{-gnatwu} followed by @emph{-gnatwF} has the
+combination @code{-gnatwu} followed by @code{-gnatwF} has the
effect of warning on unreferenced entities other than subprogram
formals.
@end table
This switch sets the warning categories that are used by the standard
GNAT style. Currently this is equivalent to
-@emph{-gnatwAao.sI.C.V.X}
+@code{-gnatwAao.q.s.CI.V.X.Z}
but more warnings may be added in the future without advanced notice.
@end table
@geindex Hiding of Declarations
-This switch activates warnings on hiding declarations.
-A declaration is considered hiding
-if it is for a non-overloadable entity, and it declares an entity with the
-same name as some other entity that is directly or use-visible. The default
-is that such warnings are not generated.
+This switch activates warnings on hiding declarations that are considered
+potentially confusing. Not all cases of hiding cause warnings; for example an
+overriding declaration hides an implicit declaration, which is just normal
+code. The default is that warnings on hiding are not generated.
@end table
@geindex -gnatwH (gcc)
@emph{Activate warnings on implementation units.}
This switch activates warnings for a @emph{with} of an internal GNAT
-implementation unit, defined as any unit from the @cite{Ada},
-@cite{Interfaces}, @cite{GNAT},
-or @cite{System}
+implementation unit, defined as any unit from the @code{Ada},
+@code{Interfaces}, @code{GNAT},
+or @code{System}
hierarchies that is not
documented in either the Ada Reference Manual or the GNAT
Programmer's Reference Manual. Such units are intended only
@geindex Obsolescent features
If this warning option is activated, then warnings are generated for
-calls to subprograms marked with @cite{pragma Obsolescent} and
+calls to subprograms marked with @code{pragma Obsolescent} and
for use of features in Annex J of the Ada Reference Manual. In the
case of Annex J, not all features are flagged. In particular use
-of the renamed packages (like @cite{Text_IO}) and use of package
-@cite{ASCII} are not flagged, since these are very common and
+of the renamed packages (like @code{Text_IO}) and use of package
+@code{ASCII} are not flagged, since these are very common and
would generate many annoying positive warnings. The default is that
such warnings are not generated.
In addition to the above cases, warnings are also generated for
GNAT features that have been provided in past versions but which
have been superseded (typically by features in the new Ada standard).
-For example, @cite{pragma Ravenscar} will be flagged since its
-function is replaced by @cite{pragma Profile(Ravenscar)}, and
-@cite{pragma Interface_Name} will be flagged since its function
-is replaced by @cite{pragma Import}.
+For example, @code{pragma Ravenscar} will be flagged since its
+function is replaced by @code{pragma Profile(Ravenscar)}, and
+@code{pragma Interface_Name} will be flagged since its function
+is replaced by @code{pragma Import}.
Note that this warning option functions differently from the
-restriction @cite{No_Obsolescent_Features} in two respects.
+restriction @code{No_Obsolescent_Features} in two respects.
First, the restriction applies only to annex J features.
-Second, the restriction does flag uses of package @cite{ASCII}.
+Second, the restriction does flag uses of package @code{ASCII}.
@end table
@geindex -gnatwJ (gcc)
This switch disables warnings on use of obsolescent features.
@end table
+@geindex -gnatw.j (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.j}
+
+@emph{Activate warnings on late declarations of tagged type primitives.}
+
+This switch activates warnings on visible primitives added to a
+tagged type after deriving a private extension from it.
+@end table
+
+@geindex -gnatw.J (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.J}
+
+@emph{Suppress warnings on late declarations of tagged type primitives.}
+
+This switch suppresses warnings on visible primitives added to a
+tagged type after deriving a private extension from it.
+@end table
+
@geindex -gnatwk (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
This switch activates warnings for possible elaboration problems,
including suspicious use
-of @cite{Elaborate} pragmas, when using the static elaboration model, and
-possible situations that may raise @cite{Program_Error} when using the
+of @code{Elaborate} pragmas, when using the static elaboration model, and
+possible situations that may raise @code{Program_Error} when using the
dynamic elaboration model.
See the section in this guide on elaboration checking for further details.
The default is that such warnings
This switch sets normal warning mode, in which enabled warnings are
issued and treated as warnings rather than errors. This is the default
-mode. the switch @emph{-gnatwn} can be used to cancel the effect of
-an explicit @emph{-gnatws} or
-@emph{-gnatwe}. It also cancels the effect of the
-implicit @emph{-gnatwe} that is activated by the
-use of @emph{-gnatg}.
+mode. the switch @code{-gnatwn} can be used to cancel the effect of
+an explicit @code{-gnatws} or
+@code{-gnatwe}. It also cancels the effect of the
+implicit @code{-gnatwe} that is activated by the
+use of @code{-gnatg}.
@end table
@geindex -gnatw.n (gcc)
@emph{Activate warnings on ineffective pragma Inlines.}
This switch activates warnings for failure of front end inlining
-(activated by @emph{-gnatN}) to inline a particular call. There are
+(activated by @code{-gnatN}) to inline a particular call. There are
many reasons for not being able to inline a call, including most
commonly that the call is too complex to inline. The default is
that such warnings are not given.
clear and the use of parentheses is preferred.
@end table
-@geindex -gnatwr (gcc)
+@geindex -gnatw.q (gcc)
+
+@geindex Layout
+@geindex warnings
@table @asis
-@item @code{-gnatwr}
+@item @code{-gnatw.q}
-@emph{Activate warnings on redundant constructs.}
+@emph{Activate warnings on questionable layout of record types.}
-This switch activates warnings for redundant constructs. The following
-is the current list of constructs regarded as redundant:
+This switch activates warnings for cases where the default layout of
+a record type, that is to say the layout of its components in textual
+order of the source code, would very likely cause inefficiencies in
+the code generated by the compiler, both in terms of space and speed
+during execution. One warning is issued for each problematic component
+without representation clause in the nonvariant part and then in each
+variant recursively, if any.
+
+The purpose of these warnings is neither to prescribe an optimal layout
+nor to force the use of representation clauses, but rather to get rid of
+the most blatant inefficiencies in the layout. Therefore, the default
+layout is matched against the following synthetic ordered layout and
+the deviations are flagged on a component-by-component basis:
@itemize *
@item
-Assignment of an item to itself.
+first all components or groups of components whose length is fixed
+and a multiple of the storage unit,
@item
-Type conversion that converts an expression to its own type.
+then the remaining components whose length is fixed and not a multiple
+of the storage unit,
@item
-Use of the attribute @cite{Base} where @cite{typ'Base} is the same
-as @cite{typ}.
+then the remaining components whose length doesn't depend on discriminants
+(that is to say, with variable but uniform length for all objects),
@item
-Use of pragma @cite{Pack} when all components are placed by a record
-representation clause.
+then all components whose length depends on discriminants,
@item
-Exception handler containing only a reraise statement (raise with no
-operand) which has no effect.
+finally the variant part (if any),
+@end itemize
-@item
-Use of the operator abs on an operand that is known at compile time
-to be non-negative
+for the nonvariant part and for each variant recursively, if any.
-@item
-Comparison of boolean expressions to an explicit True value.
-@end itemize
+The exact wording of the warning depends on whether the compiler is allowed
+to reorder the components in the record type or precluded from doing it by
+means of pragma @code{No_Component_Reordering}.
-The default is that warnings for redundant constructs are not given.
+The default is that these warnings are not given.
@end table
-@geindex -gnatwR (gcc)
+@geindex -gnatw.Q (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw.Q}
+
+@emph{Suppress warnings on questionable layout of record types.}
+
+This switch suppresses warnings for cases where the default layout of
+a record type would very likely cause inefficiencies.
+@end table
+
+@geindex -gnatwr (gcc)
+
+
+@table @asis
+
+@item @code{-gnatwr}
+
+@emph{Activate warnings on redundant constructs.}
+
+This switch activates warnings for redundant constructs. The following
+is the current list of constructs regarded as redundant:
+
+
+@itemize *
+
+@item
+Assignment of an item to itself.
+
+@item
+Type conversion that converts an expression to its own type.
+
+@item
+Use of the attribute @code{Base} where @code{typ'Base} is the same
+as @code{typ}.
+
+@item
+Use of pragma @code{Pack} when all components are placed by a record
+representation clause.
+
+@item
+Exception handler containing only a reraise statement (raise with no
+operand) which has no effect.
+
+@item
+Use of the operator abs on an operand that is known at compile time
+to be non-negative
+
+@item
+Comparison of an object or (unary or binary) operation of boolean type to
+an explicit True value.
+@end itemize
+
+The default is that warnings for redundant constructs are not given.
+@end table
+
+@geindex -gnatwR (gcc)
@table @asis
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 -gnatw_r (gcc)
+
+
+@table @asis
+
+@item @code{-gnatw_r}
+
+@emph{Activate warnings for out-of-order record representation clauses.}
+
+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
+
+@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)
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 @emph{-gnatwn}.
+use of the switch @code{-gnatwn}.
-Note that switch @emph{-gnatws} does not suppress
-warnings from the @emph{gcc} back end.
-To suppress these back end warnings as well, use the switch @emph{-w}
-in addition to @emph{-gnatws}. Also this switch has no effect on the
+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
handling of style check messages.
@end table
@emph{Activate warnings on suspicious contracts.}
This switch activates warnings on suspicious contracts. This includes
-warnings on suspicious postconditions (whether a pragma @cite{Postcondition} or a
-@cite{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect
-@cite{Contract_Cases}). A function postcondition or contract case is suspicious
+warnings on suspicious postconditions (whether a pragma @code{Postcondition} or a
+@code{Post} aspect in Ada 2012) and suspicious contract cases (pragma or aspect
+@code{Contract_Cases}). A function postcondition or contract case is suspicious
when no postcondition or contract case for this function mentions the result
of the function. A procedure postcondition or contract case is suspicious
when it only refers to the pre-state of the procedure, because in that case
and not
referenced. In the case of packages, a warning is also generated if
no entities in the package are referenced. This means that if a with'ed
-package is referenced but the only references are in @cite{use}
-clauses or @cite{renames}
+package is referenced but the only references are in @code{use}
+clauses or @code{renames}
declarations, a warning is still generated. A warning is also generated
for a generic package that is @emph{with}ed but never instantiated.
In the case where a package or subprogram body is compiled, and there
@emph{with} can be moved to the body. The default is that
such warnings are not generated.
This switch also activates warnings on unreferenced formals
-(it includes the effect of @emph{-gnatwf}).
+(it includes the effect of @code{-gnatwf}).
@end table
@geindex -gnatwU (gcc)
This switch suppresses warnings for unused entities and packages.
It also turns off warnings on unreferenced formals (and thus includes
-the effect of @emph{-gnatwF}).
+the effect of @code{-gnatwF}).
@end table
@geindex -gnatw.u (gcc)
@emph{Activate warnings on unordered enumeration types.}
This switch causes enumeration types to be considered as conceptually
-unordered, unless an explicit pragma @cite{Ordered} is given for the type.
+unordered, unless an explicit pragma @code{Ordered} is given for the type.
The effect is to generate warnings in clients that use explicit comparisons
or subranges, since these constructs both treat objects of the type as
ordered. (A @emph{client} is defined as a unit that is other than the unit in
which the type is declared, or its body or subunits.) Please refer to
-the description of pragma @cite{Ordered} in the
+the description of pragma @code{Ordered} in the
@cite{GNAT Reference Manual} for further details.
The default is that such warnings are not generated.
@end table
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 on Warnings Off pragmas.}
-This switch activates warnings for use of @cite{pragma Warnings (Off@comma{} entity)}
+This switch activates warnings for use of @code{pragma Warnings (Off, entity)}
where either the pragma is entirely useless (because it suppresses no
-warnings), or it could be replaced by @cite{pragma Unreferenced} or
-@cite{pragma Unmodified}.
+warnings), or it could be replaced by @code{pragma Unreferenced} or
+@code{pragma Unmodified}.
Also activates warnings for the case of
Warnings (Off, String), where either there is no matching
Warnings (On, String), or the Warnings (Off) did not suppress any warning.
@emph{Suppress warnings on unnecessary Warnings Off pragmas.}
-This switch suppresses warnings for use of @cite{pragma Warnings (Off@comma{} ...)}.
+This switch suppresses warnings for use of @code{pragma Warnings (Off, ...)}.
@end table
@geindex -gnatwx (gcc)
This switch activates warnings for exception usage when pragma Restrictions
(No_Exception_Propagation) is in effect. Warnings are given for implicit or
explicit exception raises which are not covered by a local handler, and for
-exception handlers which do not cover a local raise. The default is that these
-warnings are not given.
+exception handlers which do not cover a local raise. The default is that
+these warnings are given for units that contain exception handlers.
@item @code{-gnatw.X}
with older versions. For example, Ada 2005 programs will almost
always work when compiled as Ada 2012.
However there are some exceptions (for example the fact that
-@cite{some} is now a reserved word in Ada 2012). This
+@code{some} is now a reserved word in Ada 2012). This
switch activates several warnings to help in identifying
and correcting such incompatibilities. The default is that
these warnings are generated. Note that at one point Ada 2005
@emph{Activate warnings for size not a multiple of alignment.}
-This switch activates warnings for cases of record types with
-specified @cite{Size} and @cite{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 @cite{Size} and @cite{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 @cite{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{-Wunused}
-The warnings controlled by the @emph{-gnatw} switch are generated by
-the front end of the compiler. The @emph{GCC} back end can provide
-additional warnings and they are controlled by the @emph{-W} switch.
-For example, @emph{-Wunused} activates back end
+The warnings controlled by the @code{-gnatw} switch are generated by
+the front end of the compiler. The GCC back end can provide
+additional warnings and they are controlled by the @code{-W} switch.
+For example, @code{-Wunused} activates back end
warnings for entities that are declared but not referenced.
@end table
@item @code{-Wuninitialized}
-Similarly, @emph{-Wuninitialized} activates
+Similarly, @code{-Wuninitialized} activates
the back end warning for uninitialized variables. This switch must be
used in conjunction with an optimization level greater than zero.
@end table
@item @code{-Wstack-usage=@emph{len}}
-Warn if the stack usage of a subprogram might be larger than @cite{len} bytes.
-See @ref{fa,,Static Stack Usage Analysis} for details.
+Warn if the stack usage of a subprogram might be larger than @code{len} bytes.
+See @ref{e6,,Static Stack Usage Analysis} for details.
@end table
@geindex -Wall (gcc)
@item @code{-Wall}
-This switch enables most warnings from the @emph{GCC} back end.
+This switch enables most warnings from the GCC back end.
The code generator detects a number of warning situations that are missed
-by the @emph{GNAT} front end, and this switch can be used to activate them.
+by the GNAT front end, and this switch can be used to activate them.
The use of this switch also sets the default front end warning mode to
-@emph{-gnatwa}, that is, most front end warnings activated as well.
+@code{-gnatwa}, that is, most front end warnings activated as well.
@end table
@geindex -w (gcc)
@item @code{-w}
-Conversely, this switch suppresses warnings from the @emph{GCC} back end.
+Conversely, this switch suppresses warnings from the GCC back end.
The use of this switch also sets the default front end warning mode to
-@emph{-gnatws}, that is, front end warnings suppressed as well.
+@code{-gnatws}, that is, front end warnings suppressed as well.
@end table
@geindex -Werror (gcc)
@item @code{-Werror}
-This switch causes warnings from the @emph{GCC} back end to be treated as
+This switch causes warnings from the GCC back end to be treated as
errors. The warning string still appears, but the warning messages are
counted as errors, and prevent the generation of an object file.
@end table
will turn on all optional warnings except for unrecognized pragma warnings,
and also specify that warnings should be treated as errors.
-When no switch @emph{-gnatw} is used, this is equivalent to:
+When no switch @code{-gnatw} is used, this is equivalent to:
@quotation
@item
@code{-gnatwD}
+@item
+@code{-gnatw.D}
+
@item
@code{-gnatwF}
+@item
+@code{-gnatw.F}
+
@item
@code{-gnatwg}
@code{-gnatwH}
@item
-@code{-gnatwi}
+@code{-gnatw.H}
@item
-@code{-gnatw.I}
+@code{-gnatwi}
@item
@code{-gnatwJ}
+@item
+@code{-gnatw.J}
+
@item
@code{-gnatwK}
+@item
+@code{-gnatw.K}
+
@item
@code{-gnatwL}
@item
@code{-gnatwn}
+@item
+@code{-gnatw.N}
+
@item
@code{-gnatwo}
@item
@code{-gnatwq}
+@item
+@code{-gnatw.Q}
+
@item
@code{-gnatwR}
@code{-gnatwT}
@item
-@code{-gnatw.T}
+@code{-gnatw.t}
@item
@code{-gnatwU}
+@item
+@code{-gnatw.U}
+
@item
@code{-gnatwv}
+@item
+@code{-gnatw.v}
+
@item
@code{-gnatww}
@item
@code{-gnatwy}
+@item
+@code{-gnatw.Y}
+
@item
@code{-gnatwz}
+
+@item
+@code{-gnatw.z}
@end itemize
@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{105}@anchor{gnat_ugn/building_executable_programs_with_gnat id16}@anchor{106}
+@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
@geindex Subtype predicates
-The @cite{-gnata} option is equivalent to the following Assertion_Policy pragma:
+The @code{-gnata} option is equivalent to the following @code{Assertion_Policy} pragma:
@example
pragma Assertion_Policy (Check);
Type_Invariant'Class => Check);
@end example
-The pragmas @cite{Assert} and @cite{Debug} normally have no effect and
-are ignored. This switch, where @code{a} stands for assert, causes
-pragmas @cite{Assert} and @cite{Debug} to be activated. This switch also
+The pragmas @code{Assert} and @code{Debug} normally have no effect and
+are ignored. This switch, where @code{a} stands for 'assert', causes
+pragmas @code{Assert} and @code{Debug} to be activated. This switch also
causes preconditions, postconditions, subtype predicates, and
type invariants to be activated.
=> <Boolean-expression>;
@end example
-The @cite{Assert} pragma causes @cite{Boolean-expression} to be tested.
-If the result is @cite{True}, the pragma has no effect (other than
+The @code{Assert} pragma causes @code{Boolean-expression} to be tested.
+If the result is @code{True}, the pragma has no effect (other than
possible side effects from evaluating the expression). If the result is
-@cite{False}, the exception @cite{Assert_Failure} declared in the package
-@cite{System.Assertions} is raised (passing @cite{static-string-expression}, if
+@code{False}, the exception @code{Assert_Failure} declared in the package
+@code{System.Assertions} is raised (passing @code{static-string-expression}, if
present, as the message associated with the exception). If no string
expression is given, the default is a string containing the file name and
line number of the pragma.
-The @cite{Debug} pragma causes @cite{procedure} to be called. Note that
-@cite{pragma Debug} may appear within a declaration sequence, allowing
+The @code{Debug} pragma causes @code{procedure} to be called. Note that
+@code{pragma Debug} may appear within a declaration sequence, allowing
debugging procedures to be called between declarations.
-For the aspect specification, the @cite{<Boolean-expression>} is evaluated.
-If the result is @cite{True}, the aspect has no effect. If the result
-is @cite{False}, the exception @cite{Assert_Failure} is raised.
+For the aspect specification, the @code{Boolean-expression} is evaluated.
+If the result is @code{True}, the aspect has no effect. If the result
+is @code{False}, the exception @code{Assert_Failure} is raised.
@end table
@node Validity Checking,Style Checking,Debugging and Assertion Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat validity-checking}@anchor{fb}@anchor{gnat_ugn/building_executable_programs_with_gnat id17}@anchor{107}
+@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
It is an error to read an invalid value, but the RM does not require
run-time checks to detect such errors, except for some minimal
checking to prevent erroneous execution (i.e. unpredictable
-behavior). This corresponds to the @emph{-gnatVd} switch below,
+behavior). This corresponds to the @code{-gnatVd} switch below,
which is the default. For example, by default, if the expression of a
case statement is invalid, it will raise Constraint_Error rather than
causing a wild jump, and if an array index on the left-hand side of an
assignment is invalid, it will raise Constraint_Error rather than
overwriting an arbitrary memory location.
-The @emph{-gnatVa} may be used to enable additional validity checks,
+The @code{-gnatVa} may be used to enable additional validity checks,
which are not required by the RM. These checks are often very
expensive (which is why the RM does not require them). These checks
are useful in tracking down uninitialized variables, but they are
If performance is a consideration, leading to the need to optimize,
then the validity checking options should not be used.
-The other @emph{-gnatV}@code{x} switches below allow finer-grained
+The other @code{-gnatV@emph{x}} switches below allow finer-grained
control; you can enable whichever validity checks you desire. However,
-for most debugging purposes, @emph{-gnatVa} is sufficient, and the
-default @emph{-gnatVd} (i.e. standard Ada behavior) is usually
+for most debugging purposes, @code{-gnatVa} is sufficient, and the
+default @code{-gnatVd} (i.e. standard Ada behavior) is usually
sufficient for non-debugging use.
-The @emph{-gnatB} switch tells the compiler to assume that all
+The @code{-gnatB} switch tells the compiler to assume that all
values are valid (that is, within their declared subtype range)
except in the context of a use of the Valid attribute. This means
the compiler can generate more efficient code, since the range
of values is better known at compile time. However, an uninitialized
variable can cause wild jumps and memory corruption in this mode.
-The @emph{-gnatV}@code{x} switch allows control over the validity
+The @code{-gnatV@emph{x}} switch allows control over the validity
checking mode as described below.
The @code{x} argument is a string of letters that
indicate validity checks that are performed or not performed in addition
@emph{All validity checks.}
All validity checks are turned on.
-That is, @emph{-gnatVa} is
-equivalent to @emph{gnatVcdfimorst}.
+That is, @code{-gnatVa} is
+equivalent to @code{gnatVcdfimoprst}.
@end table
@geindex -gnatVc (gcc)
of the subtype. If it is not, Constraint_Error is raised.
For assignments to array components, a check is done that the expression used
as index is within the range. If it is not, Constraint_Error is raised.
-Both these validity checks may be turned off using switch @emph{-gnatVD}.
-They are turned on by default. If @emph{-gnatVD} is specified, a subsequent
-switch @emph{-gnatVd} will leave the checks turned on.
-Switch @emph{-gnatVD} should be used only if you are sure that all such
+Both these validity checks may be turned off using switch @code{-gnatVD}.
+They are turned on by default. If @code{-gnatVD} is specified, a subsequent
+switch @code{-gnatVd} will leave the checks turned on.
+Switch @code{-gnatVD} should be used only if you are sure that all such
expressions have valid values. If you use this switch and invalid values
are present, then the program is erroneous, and wild jumps or memory
overwriting may occur.
In the absence of this switch, assignments to record or array components are
not validity checked, even if validity checks for assignments generally
-(@emph{-gnatVc}) are turned on. In Ada, assignment of composite values do not
+(@code{-gnatVc}) are turned on. In Ada, assignment of composite values do not
require valid data, but assignment of individual components does. So for
example, there is a difference between copying the elements of an array with a
slice assignment, compared to assigning element by element in a loop. This
@emph{Validity checks for floating-point values.}
In the absence of this switch, validity checking occurs only for discrete
-values. If @emph{-gnatVf} is specified, then validity checking also applies
+values. If @code{-gnatVf} is specified, then validity checking also applies
for floating-point values, and NaNs and infinities are considered invalid,
as well as out of range values for constrained types. Note that this means
that standard IEEE infinity mode is not allowed. The exact contexts
in which floating-point values are checked depends on the setting of other
-options. For example, @emph{-gnatVif} or @emph{-gnatVfi}
+options. For example, @code{-gnatVif} or @code{-gnatVfi}
(the order does not matter) specifies that floating-point parameters of mode
-@cite{in} should be validity checked.
+@code{in} should be validity checked.
@end table
@geindex -gnatVi (gcc)
@item @code{-gnatVi}
-@emph{Validity checks for `in` mode parameters.}
+@emph{Validity checks for `@w{`}in`@w{`} mode parameters.}
-Arguments for parameters of mode @cite{in} are validity checked in function
+Arguments for parameters of mode @code{in} are validity checked in function
and procedure calls at the point of call.
@end table
@item @code{-gnatVm}
-@emph{Validity checks for `in out` mode parameters.}
+@emph{Validity checks for `@w{`}in out`@w{`} mode parameters.}
-Arguments for parameters of mode @cite{in out} are validity checked in
-procedure calls at the point of call. The @cite{'m'} here stands for
+Arguments for parameters of mode @code{in out} are validity checked in
+procedure calls at the point of call. The @code{'m'} here stands for
modify, since this concerns parameters that can be modified by the call.
-Note that there is no specific option to test @cite{out} parameters,
+Note that there is no specific option to test @code{out} parameters,
but any reference within the subprogram will be tested in the usual
manner, and if an invalid value is copied back, any reference to it
will be subject to validity checking.
This switch turns off all validity checking, including the default checking
for case statements and left hand side subscripts. Note that the use of
-the switch @emph{-gnatp} suppresses all run-time checks, including
-validity checks, and thus implies @emph{-gnatVn}. When this switch
-is used, it cancels any other @emph{-gnatV} previously issued.
+the switch @code{-gnatp} suppresses all run-time checks, including
+validity checks, and thus implies @code{-gnatVn}. When this switch
+is used, it cancels any other @code{-gnatV} previously issued.
@end table
@geindex -gnatVo (gcc)
@emph{Validity checks for operator and attribute operands.}
Arguments for predefined operators and attributes are validity checked.
-This includes all operators in package @cite{Standard},
-the shift operators defined as intrinsic in package @cite{Interfaces}
-and operands for attributes such as @cite{Pos}. Checks are also made
+This includes all operators in package @code{Standard},
+the shift operators defined as intrinsic in package @code{Interfaces}
+and operands for attributes such as @code{Pos}. Checks are also made
on individual component values for composite comparisons, and on the
expressions in type conversions and qualified expressions. Checks are
also made on explicit ranges using @code{..} (e.g., slices, loops etc).
@emph{Validity checks for parameters.}
This controls the treatment of parameters within a subprogram (as opposed
-to @emph{-gnatVi} and @emph{-gnatVm} which control validity testing
+to @code{-gnatVi} and @code{-gnatVm} which control validity testing
of parameters on a call. If either of these call options is used, then
normally an assumption is made within a subprogram that the input arguments
have been validity checking at the point of call, and do not need checking
-again within a subprogram). If @emph{-gnatVp} is set, then this assumption
+again within a subprogram). If @code{-gnatVp} is set, then this assumption
is not made, and parameters are not assumed to be valid, so their validity
will be checked (or rechecked) within the subprogram.
@end table
@emph{Validity checks for function returns.}
-The expression in @cite{return} statements in functions is validity
+The expression in @code{return} statements in functions is validity
checked.
@end table
@emph{Validity checks for tests.}
-Expressions used as conditions in @cite{if}, @cite{while} or @cite{exit}
+Expressions used as conditions in @code{if}, @code{while} or @code{exit}
statements are checked, as well as guard expressions in entry calls.
@end table
-The @emph{-gnatV} switch may be followed by a string of letters
+The @code{-gnatV} switch may be followed by a string of letters
to turn on a series of validity checking options.
For example, @code{-gnatVcr}
specifies that in addition to the default validity checking, copies and
function return expressions are to be validity checked.
In order to make it easier to specify the desired combination of effects,
-the upper case letters @cite{CDFIMORST} may
+the upper case letters @code{CDFIMORST} may
be used to turn off the corresponding lower case option.
Thus @code{-gnatVaM} turns on all validity checking options except for
-checking of @cite{**in out**} procedure arguments.
+checking of @code{in out} parameters.
The specification of additional validity checking generates extra code (and
-in the case of @emph{-gnatVa} the code expansion can be substantial).
+in the case of @code{-gnatVa} the code expansion can be substantial).
However, these additional checks can be very useful in detecting
uninitialized variables, incorrect use of unchecked conversion, and other
-errors leading to invalid values. The use of pragma @cite{Initialize_Scalars}
+errors leading to invalid values. The use of pragma @code{Initialize_Scalars}
is useful in conjunction with the extra validity checking, since this
ensures that wherever possible uninitialized variables have invalid values.
-See also the pragma @cite{Validity_Checks} which allows modification of
+See also the pragma @code{Validity_Checks} which allows modification of
the validity checking mode at the program source level, and also allows for
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{108}@anchor{gnat_ugn/building_executable_programs_with_gnat style-checking}@anchor{100}
+@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
@geindex -gnaty (gcc)
-The @emph{-gnatyx} switch causes the compiler to
+The @code{-gnatyx} switch causes the compiler to
enforce specified style rules. A limited set of style rules has been used
in writing the GNAT sources themselves. This switch allows user programs
to activate all or some of these checks. If the source program fails a
specified style check, an appropriate message is given, preceded by
the character sequence '(style)'. This message does not prevent
-successful compilation (unless the @emph{-gnatwe} switch is used).
+successful compilation (unless the @code{-gnatwe} switch is used).
Note that this is by no means intended to be a general facility for
checking arbitrary coding standards. It is simply an embedding of the
some subset of them.
-The string @cite{x} is a sequence of letters or digits
+The string @code{x} is a sequence of letters or digits
indicating the particular style
checks to be performed. The following checks are defined:
@emph{Specify indentation level.}
If a digit from 1-9 appears
-in the string after @emph{-gnaty}
+in the string after @code{-gnaty}
then proper indentation is checked, with the digit indicating the
indentation level required. A value of zero turns off this style check.
The general style of required indentation is as specified by
the examples in the Ada Reference Manual. Full line comments must be
-aligned with the @cite{--} starting on a column that is a multiple of
+aligned with the @code{--} starting on a column that is a multiple of
the alignment level, or they may be aligned the same way as the following
non-blank line (this is useful when full line comments appear in the middle
of a statement, or they may be aligned with the source line on the previous
@emph{Check attribute casing.}
-Attribute names, including the case of keywords such as @cite{digits}
+Attribute names, including the case of keywords such as @code{digits}
used as attributes names, must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
The use of AND/OR operators is not permitted except in the cases of modular
operands, array operands, and simple stand-alone boolean variables or
-boolean constants. In all other cases @cite{and then}/@cite{or else} are
+boolean constants. In all other cases @code{and then}/@cite{or else} are
required.
@end table
@itemize *
@item
-The '@cite{--}' that starts the column must either start in column one,
+The @code{--} that starts the column must either start in column one,
or else at least one blank must precede this sequence.
@item
Comments that follow other tokens on a line must have at least one blank
-following the '@cite{--}' at the start of the comment.
+following the @code{--} at the start of the comment.
@item
Full line comments must have at least two blanks following the
-'@cite{--}' that starts the comment, with the following exceptions.
+@code{--} that starts the comment, with the following exceptions.
@item
-A line consisting only of the '@cite{--}' characters, possibly preceded
+A line consisting only of the @code{--} characters, possibly preceded
by blanks is permitted.
@item
-A comment starting with '@cite{--x}' where @cite{x} is a special character
+A comment starting with @code{--x} where @code{x} is a special character
is permitted.
-This allows proper processing of the output generated by specialized tools
-including @emph{gnatprep} (where '@cite{--!}' is used) and the SPARK
+This allows proper processing of the output from specialized tools
+such as @code{gnatprep} (where @code{--!} is used) and in earlier versions of the SPARK
annotation
-language (where '@cite{--#}' is used). For the purposes of this rule, a
+language (where @code{--#} is used). For the purposes of this rule, a
special character is defined as being in one of the ASCII ranges
-@cite{16#21#...16#2F#} or @cite{16#3A#...16#3F#}.
+@code{16#21#...16#2F#} or @code{16#3A#...16#3F#}.
Note that this usage is not permitted
-in GNAT implementation units (i.e., when @emph{-gnatg} is used).
+in GNAT implementation units (i.e., when @code{-gnatg} is used).
@item
A line consisting entirely of minus signs, possibly preceded by blanks, is
signs are used to form the top and bottom of the box.
@item
-A comment that starts and ends with '@cite{--}' is permitted as long as at
-least one blank follows the initial '@cite{--}'. Together with the preceding
+A comment that starts and ends with @code{--} is permitted as long as at
+least one blank follows the initial @code{--}. Together with the preceding
rule, this allows the construction of box comments, as shown in the following
example:
@emph{Check comments, single space.}
-This is identical to @cite{c} except that only one space
-is required following the @cite{--} of a comment instead of two.
+This is identical to @code{c} except that only one space
+is required following the @code{--} of a comment instead of two.
@end table
@geindex -gnatyd (gcc)
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)
@emph{Check end/exit labels.}
-Optional labels on @cite{end} statements ending subprograms and on
-@cite{exit} statements exiting named loops, are required to be present.
+Optional labels on @code{end} statements ending subprograms and on
+@code{exit} statements exiting named loops, are required to be present.
@end table
@geindex -gnatyf (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 @emph{-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
@emph{Check if-then layout.}
-The keyword @cite{then} must appear either on the same
-line as corresponding @cite{if}, or on a line on its own, lined
-up under the @cite{if}.
+The keyword @code{then} must appear either on the same
+line as corresponding @code{if}, or on a line on its own, lined
+up under the @code{if}.
@end table
@geindex -gnatyI (gcc)
@emph{check mode IN keywords.}
-Mode @cite{in} (the default mode) is not
-allowed to be given explicitly. @cite{in out} is fine,
-but not @cite{in} on its own.
+Mode @code{in} (the default mode) is not
+allowed to be given explicitly. @code{in out} is fine,
+but not @code{in} on its own.
@end table
@geindex -gnatyk (gcc)
@emph{Check keyword casing.}
All keywords must be in lower case (with the exception of keywords
-such as @cite{digits} used as attribute names to which this check
-does not apply).
+such as @code{digits} used as attribute names to which this check
+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)
Layout of statement and declaration constructs must follow the
recommendations in the Ada Reference Manual, as indicated by the
-form of the syntax rules. For example an @cite{else} keyword must
-be lined up with the corresponding @cite{if} keyword.
+form of the syntax rules. For example an @code{else} keyword must
+be lined up with the corresponding @code{if} keyword.
There are two respects in which the style rule enforced by this check
option are more liberal than those in the Ada Reference Manual. First
in the case of record declarations, it is permissible to put the
-@cite{record} keyword on the same line as the @cite{type} keyword, and
-then the @cite{end} in @cite{end record} must line up under @cite{type}.
+@code{record} keyword on the same line as the @code{type} keyword, and
+then the @code{end} in @code{end record} must line up under @code{type}.
This is also permitted when the type declaration is split on two lines.
For example, any of the following three layouts is acceptable:
@end example
Second, in the case of a block statement, a permitted alternative
-is to put the block label on the same line as the @cite{declare} or
-@cite{begin} keyword, and then line the @cite{end} keyword up under
+is to put the block label on the same line as the @code{declare} or
+@code{begin} keyword, and then line the @code{end} keyword up under
the block label. For example both the following are permitted:
@example
Any identifier from Standard must be cased
to match the presentation in the Ada Reference Manual (for example,
-@cite{Integer} and @cite{ASCII.NUL}).
+@code{Integer} and @code{ASCII.NUL}).
@end table
@geindex -gnatyN (gcc)
@emph{Check no statements after then/else.}
No statements are allowed
-on the same line as a @cite{then} or @cite{else} keyword following the
-keyword in an @cite{if} statement. @cite{or else} and @cite{and then} are not
-affected, and a special exception allows a pragma to appear after @cite{else}.
+on the same line as a @code{then} or @code{else} keyword following the
+keyword in an @code{if} statement. @code{or else} and @code{and then} are not
+affected, and a special exception allows a pragma to appear after @code{else}.
@end table
@geindex -gnatyt (gcc)
@itemize *
@item
-The keywords @cite{abs} and @cite{not} must be followed by a space.
+The keywords @code{abs} and @code{not} must be followed by a space.
@item
-The token @cite{=>} must be surrounded by spaces.
+The token @code{=>} must be surrounded by spaces.
@item
-The token @cite{<>} must be preceded by a space or a left parenthesis.
+The token @code{<>} must be preceded by a space or a left parenthesis.
@item
-Binary operators other than @cite{**} must be surrounded by spaces.
-There is no restriction on the layout of the @cite{**} binary operator.
+Binary operators other than @code{**} must be surrounded by spaces.
+There is no restriction on the layout of the @code{**} binary operator.
@item
Colon must be surrounded by spaces.
@end itemize
Exactly one blank (and no other white space) must appear between
-a @cite{not} token and a following @cite{in} token.
+a @code{not} token and a following @code{in} token.
@end table
@geindex -gnatyu (gcc)
@emph{Check extra parentheses.}
Unnecessary extra level of parentheses (C-style) are not allowed
-around conditions in @cite{if} statements, @cite{while} statements and
-@cite{exit} statements.
+around conditions in @code{if} statements, @code{while} statements and
+@code{exit} statements.
@end table
@geindex -gnatyy (gcc)
@emph{Set all standard style check options.}
-This is equivalent to @cite{gnaty3aAbcefhiklmnprst}, that is all checking
-options enabled with the exception of @emph{-gnatyB}, @emph{-gnatyd},
-@emph{-gnatyI}, @emph{-gnatyLnnn}, @emph{-gnatyo}, @emph{-gnatyO},
-@emph{-gnatyS}, @emph{-gnatyu}, and @emph{-gnatyx}.
+This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
+options enabled with the exception of @code{-gnatyB}, @code{-gnatyd},
+@code{-gnatyI}, @code{-gnatyLnnn}, @code{-gnatyo}, @code{-gnatyO},
+@code{-gnatyS}, @code{-gnatyu}, and @code{-gnatyx}.
@end table
@geindex -gnaty- (gcc)
This causes any subsequent options in the string to act as canceling the
corresponding style check option. To cancel maximum nesting level control,
-use @emph{L} parameter witout any integer value after that, because any
-digit following @emph{-} in the parameter string of the @emph{-gnaty}
-option will be threated as canceling indentation check. The same is true
-for @emph{M} parameter. @emph{y} and @emph{N} parameters are not
+use the @code{L} parameter without any integer value after that, because any
+digit following @emph{-} in the parameter string of the @code{-gnaty}
+option will be treated as canceling the indentation check. The same is true
+for the @code{M} parameter. @code{y} and @code{N} parameters are not
allowed after @emph{-}.
@end table
@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,
details on the violation. The initial characters of such messages are
always '@cite{(style)}'. Note that these messages are treated as warning
messages, so they normally do not prevent the generation of an object
-file. The @emph{-gnatwe} switch can be used to treat warning messages,
+file. The @code{-gnatwe} switch can be used to treat warning messages,
including style messages, as fatal errors.
The switch @code{-gnaty} on its own (that is not
followed by any letters or digits) is equivalent
-to the use of @emph{-gnatyy} as described above, that is all
+to the use of @code{-gnatyy} as described above, that is all
built-in standard style check options are enabled.
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{fe}@anchor{gnat_ugn/building_executable_programs_with_gnat id19}@anchor{109}
+@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
By default, the following checks are suppressed: stack overflow
checks, and checks for access before elaboration on subprogram
calls. All other checks, including overflow checks, range checks and
-array bounds checks, are turned on by default. The following @emph{gcc}
+array bounds checks, are turned on by default. The following @code{gcc}
switches refine this default behavior.
@geindex -gnatp (gcc)
@geindex suppressing
This switch causes the unit to be compiled
-as though @cite{pragma Suppress (All_checks)}
+as though @code{pragma Suppress (All_checks)}
had been present in the source. Validity checks are also eliminated (in
-other words @emph{-gnatp} also implies @emph{-gnatVn}.
+other words @code{-gnatp} also implies @code{-gnatVn}.
Use this switch to improve the performance
of the code at the expense of safety in the presence of invalid data or
program bugs.
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
execution if that assumption is wrong.
The checks subject to suppression include all the checks defined by the Ada
-standard, the additional implementation defined checks @cite{Alignment_Check},
-@cite{Duplicated_Tag_Check}, @cite{Predicate_Check}, Container_Checks, Tampering_Check,
-and @cite{Validity_Check}, as well as any checks introduced using @cite{pragma Check_Name}. Note that @cite{Atomic_Synchronization} is not automatically
-suppressed by use of this option.
+standard, the additional implementation defined checks @code{Alignment_Check},
+@code{Duplicated_Tag_Check}, @code{Predicate_Check}, @code{Container_Checks}, @code{Tampering_Check},
+and @code{Validity_Check}, as well as any checks introduced using @code{pragma Check_Name}.
+Note that @code{Atomic_Synchronization} is not automatically suppressed by use of this option.
If the code depends on certain checks being active, you can use
-pragma @cite{Unsuppress} either as a configuration pragma or as
+pragma @code{Unsuppress} either as a configuration pragma or as
a local pragma to make sure that a specified check is performed
-even if @emph{gnatp} is specified.
+even if @code{gnatp} is specified.
-The @emph{-gnatp} switch has no effect if a subsequent
-@emph{-gnat-p} switch appears.
+The @code{-gnatp} switch has no effect if a subsequent
+@code{-gnat-p} switch appears.
@end table
@geindex -gnat-p (gcc)
@item @code{-gnat-p}
-This switch cancels the effect of a previous @emph{gnatp} switch.
+This switch cancels the effect of a previous @code{gnatp} switch.
@end table
@geindex -gnato?? (gcc)
In MINIMIZED mode, overflows in intermediate operations are avoided
where possible by using a larger integer type for the computation
-(typically @cite{Long_Long_Integer}). Overflow checking ensures that
+(typically @code{Long_Long_Integer}). Overflow checking ensures that
the result fits in this larger integer type.
@item @emph{3 = ELIMINATED}
has no effect on intermediate operations (since overflow is impossible).
@end table
-If two digits are present after @emph{-gnato} then the first digit
+If two digits are present after @code{-gnato} then the first digit
sets the mode for expressions outside assertions, and the second digit
sets the mode for expressions within assertions. Here assertions is used
in the technical sense (which includes for example precondition and
If no digits are present, the default is to enable overflow checks
and set STRICT mode for both kinds of expressions. This is compatible
-with the use of @emph{-gnato} in previous versions of GNAT.
+with the use of @code{-gnato} in previous versions of GNAT.
@geindex Machine_Overflows
-Note that the @emph{-gnato??} switch does not affect the code generated
+Note that the @code{-gnato??} switch does not affect the code generated
for any floating-point operations; it applies only to integer semantics.
-For floating-point, GNAT has the @cite{Machine_Overflows}
-attribute set to @cite{False} and the normal mode of operation is to
+For floating-point, GNAT has the @code{Machine_Overflows}
+attribute set to @code{False} and the normal mode of operation is to
generate IEEE NaN and infinite values on overflow or invalid operations
(such as dividing 0.0 by 0.0).
checking is also quite expensive in time and space, since in general it
requires the use of double length arithmetic.
-Note again that the default is @emph{-gnato11} (equivalent to @emph{-gnato1}),
+Note again that the default is @code{-gnato11} (equivalent to @code{-gnato1}),
so overflow checking is performed in STRICT mode by default.
@end table
Enables dynamic checks for access-before-elaboration
on subprogram calls and generic instantiations.
-Note that @emph{-gnatE} is not necessary for safety, because in the
+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{1e,,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{f9,,Stack Overflow Checking}.
+this switch see @ref{e5,,Stack Overflow Checking}.
@end table
@geindex Unsuppress
The setting of these switches only controls the default setting of the
-checks. You may modify them using either @cite{Suppress} (to remove
-checks) or @cite{Unsuppress} (to add back suppressed checks) pragmas in
+checks. You may modify them using either @code{Suppress} (to remove
+checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in
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{10a}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-syntax-checking}@anchor{10b}
-@subsection Using @emph{gcc} for Syntax Checking
+@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
@geindex -gnats (gcc)
@item @code{-gnats}
-The @cite{s} stands for 'syntax'.
+The @code{s} stands for 'syntax'.
Run GNAT in syntax checking only mode. For
example, the command
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.
-Note that you must specify the @emph{-c} (compile
-only) flag in addition to the @emph{-gnats} flag.
+, 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.
-You may use other switches in conjunction with @emph{-gnats}. In
-particular, @emph{-gnatl} and @emph{-gnatv} are useful to control the
+You may use other switches in conjunction with @code{-gnats}. In
+particular, @code{-gnatl} and @code{-gnatv} are useful to control the
format of any generated error messages.
When the source file is empty or contains only empty lines and/or comments,
Otherwise, the output is simply the error messages, if any. No object file or
ALI file is generated by a syntax-only compilation. Also, no units other
-than the one specified are accessed. For example, if a unit @cite{X}
-@emph{with}s a unit @cite{Y}, compiling unit @cite{X} in syntax
+than the one specified are accessed. For example, if a unit @code{X}
+@emph{with}s a unit @code{Y}, compiling unit @code{X} in syntax
check only mode does not access the source file containing unit
-@cite{Y}.
+@code{Y}.
@geindex Multiple units
@geindex syntax checking
Normally, GNAT allows only a single unit in a source file. However, this
restriction does not apply in syntax-check-only mode, and it is possible
to check a file containing multiple compilation units concatenated
-together. This is primarily used by the @cite{gnatchop} utility
-(@ref{38,,Renaming Files with gnatchop}).
+together. This is primarily used by the @code{gnatchop} utility
+(@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{10c}@anchor{gnat_ugn/building_executable_programs_with_gnat using-gcc-for-semantic-checking}@anchor{10d}
-@subsection Using @emph{gcc} for Semantic Checking
+@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
@geindex -gnatc (gcc)
@item @code{-gnatc}
-The @cite{c} stands for 'check'.
+The @code{c} stands for 'check'.
Causes the compiler to operate in semantic check mode,
with full checking for all illegalities specified in the
Ada Reference Manual, but without generation of any object code
@item
The needed source files must be accessible
-(see @ref{8e,,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{54,,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{10e}
+@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
Although GNAT is primarily an Ada 95 / Ada 2005 compiler, this switch
specifies that the program is to be compiled in Ada 83 mode. With
-@emph{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83
+@code{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83
semantics where this can be done easily.
It is not possible to guarantee this switch does a perfect
job; some subtle tests, such as are
where, due to contractual reasons, existing code needs to be maintained
using only Ada 83 features.
-With few exceptions (most notably the need to use @cite{<>} on
+With few exceptions (most notably the need to use @code{<>} on
unconstrained
@geindex Generic formal parameters
generic formal parameters,
the use of the new Ada 95 / Ada 2005
reserved words, and the use of packages
with optional bodies), it is not necessary to specify the
-@emph{-gnat83} switch when compiling Ada 83 programs, because, with rare
+@code{-gnat83} switch when compiling Ada 83 programs, because, with rare
exceptions, Ada 95 and Ada 2005 are upwardly compatible with Ada 83. Thus
a correct Ada 83 program is usually also a correct program
in these later versions of the language standard. For further information
-please refer to the @cite{Compatibility_and_Porting_Guide} chapter in the
+please refer to the @emph{Compatibility and Porting Guide} chapter in the
@cite{GNAT Reference Manual}.
@end table
language.
Since Ada 95 is almost completely upwards
compatible with Ada 83, Ada 83 programs may generally be compiled using
-this switch (see the description of the @emph{-gnat83} switch for further
+this switch (see the description of the @code{-gnat83} switch for further
information about Ada 83 mode).
If an Ada 2005 program is compiled in Ada 95 mode,
uses of the new Ada 2005 features will cause error
messages or warnings.
This switch also can be used to cancel the effect of a previous
-@emph{-gnat83}, @emph{-gnat05/2005}, or @emph{-gnat12/2012}
+@code{-gnat83}, @code{-gnat05/2005}, or @code{-gnat12/2012}
switch earlier in the command line.
@end table
Since Ada 2005 is almost completely upwards
compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs
may generally be compiled using this switch (see the description of the
-@emph{-gnat83} and @emph{-gnat95} switches for further
+@code{-gnat83} and @code{-gnat95} switches for further
information).
@end table
compatible with Ada 2005 (and thus also with Ada 83, and Ada 95),
Ada 83 and Ada 95 programs
may generally be compiled using this switch (see the description of the
-@emph{-gnat83}, @emph{-gnat95}, and @emph{-gnat05/2005} switches
+@code{-gnat83}, @code{-gnat95}, and @code{-gnat05/2005} switches
for further information).
@end table
@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{10f}@anchor{gnat_ugn/building_executable_programs_with_gnat character-set-control}@anchor{4a}
+@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
Normally GNAT recognizes the Latin-1 character set in source program
identifiers, as described in the Ada Reference Manual.
This switch causes
-GNAT to recognize alternate character sets in identifiers. @cite{c} is a
+GNAT to recognize alternate character sets in identifiers. @code{c} is a
single character indicating the character set, as follows:
@end multitable
-See @ref{40,,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
@item @code{-gnatW@emph{e}}
Specify the method of encoding for wide characters.
-@cite{e} is one of the following:
+@code{e} is one of the following:
@multitable {xxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
For full details on these encoding
-methods see @ref{50,,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 @emph{-gnatW8} specifies that both
+options is specified, so for example @code{-gnatW8} specifies that both
brackets and UTF-8 encodings will be recognized. The units that are
with'ed directly or indirectly will be scanned using the specified
representation scheme, and so if one of the non-brackets scheme is
brackets are considered to be normal graphic characters, and bracket sequences
are never recognized as wide characters.
-If no @emph{-gnatW?} parameter is present, then the default
+If no @code{-gnatW?} parameter is present, then the default
representation is normally Brackets encoding only. However, if the
first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
byte order mark or BOM for UTF-8), then these three characters are
parameter.
@end table
-When no @emph{-gnatW?} is specified, then characters (other than wide
+When no @code{-gnatW?} is specified, then characters (other than wide
characters represented using brackets notation) are treated as 8-bit
Latin-1 codes. The codes recognized are the Latin-1 graphic characters,
and ASCII format effectors (CR, LF, HT, VT). Other lower half control
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{110}@anchor{gnat_ugn/building_executable_programs_with_gnat id24}@anchor{111}
+@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
@item @code{-gnatk@emph{n}}
-Activates file name 'krunching'. @cite{n}, a decimal integer in the range
+Activates file name 'krunching'. @code{n}, a decimal integer in the range
1-999, indicates the maximum allowable length of a file name (not
including the @code{.ads} or @code{.adb} extension). The default is not
to enable file name krunching.
-For the source file naming rules, @ref{54,,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{112}@anchor{gnat_ugn/building_executable_programs_with_gnat id25}@anchor{113}
+@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
@item @code{-gnatn[12]}
-The @cite{n} here is intended to suggest the first syllable of the
-word 'inline'.
-GNAT recognizes and processes @cite{Inline} pragmas. However, for the
-inlining to actually occur, optimization must be enabled and, in order
-to enable inlining of subprograms specified by pragma @cite{Inline},
+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 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 and does not need to access the bodies of
-subprograms for which @cite{pragma Inline} is specified if they are not
-in the current unit.
+
+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 @emph{-O1}, @emph{-O2} or
-@emph{-Os} and 2 for @emph{-O3}.
+pick it based on the optimization level: 1 for @code{-O1}, @code{-O2} or
+@code{-Os} and 2 for @code{-O3}.
If you specify this switch the compiler will access these bodies,
creating an extra source dependency for the resulting object file, and
where possible, the call will be inlined.
For further details on when inlining is possible
-see @ref{114,,Inlining of Subprograms}.
+see @ref{100,,Inlining of Subprograms}.
@end table
@geindex -gnatN (gcc)
When using a gcc-based back end (in practice this means using any version
of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
-@emph{-gnatN} is deprecated, and the use of @emph{-gnatn} is preferred.
+@code{-gnatN} is deprecated, and the use of @code{-gnatn} is preferred.
Historically front end inlining was more extensive than the gcc back end
inlining, but that is no longer the case.
@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{115}@anchor{gnat_ugn/building_executable_programs_with_gnat id26}@anchor{116}
+@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 @emph{-gnatct}
-generates a tree in the form required by ASIS applications.
-@end table
-
@geindex -gnatu (gcc)
@item @code{-pass-exit-codes}
-If this switch is not used, the exit code returned by @emph{gcc} when
+If this switch is not used, the exit code returned by @code{gcc} when
compiling multiple files indicates whether all source files have
been successfully used to generate object files or not.
-When @emph{-pass-exit-codes} is used, @emph{gcc} exits with an extended
+When @code{-pass-exit-codes} is used, @code{gcc} exits with an extended
exit status and allows an integrated development environment to better
react to a compilation failure. Those exit status are:
@end table
@node Debugging Control,Exception Handling Control,Auxiliary Output Control,Compiler Switches
-@anchor{gnat_ugn/building_executable_programs_with_gnat debugging-control}@anchor{117}@anchor{gnat_ugn/building_executable_programs_with_gnat id27}@anchor{118}
+@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
@item @code{-gnatd@emph{x}}
-Activate internal debugging switches. @cite{x} is a letter or digit, or
+Activate internal debugging switches. @code{x} is a letter or digit, or
string of letters or digits, which specifies the type of debugging
outputs desired. Normally these are used only for internal development
or system debugging purposes. You can find full documentation for these
-switches in the body of the @cite{Debug} unit in the compiler source
+switches in the body of the @code{Debug} unit in the compiler source
file @code{debug.adb}.
@end table
This is very useful in understanding the implications of various Ada
usage on the efficiency of the generated code. There are many cases in
Ada (e.g., the use of controlled types), where simple Ada statements can
-generate a lot of run-time code. By using @emph{-gnatG} you can identify
+generate a lot of run-time code. By using @code{-gnatG} you can identify
these cases, and consider whether it may be desirable to modify the coding
approach to improve efficiency.
-The optional parameter @cite{nn} if present after -gnatG specifies an
+The optional parameter @code{nn} if present after -gnatG specifies an
alternative maximum line length that overrides the normal default of 72.
This value is in the range 40-999999, values less than 40 being silently
reset to 40. The equal sign is optional.
additions correspond to low level features used in the generated code that
do not have any exact analogies in pure Ada source form. The following
is a partial list of these special constructions. See the spec
-of package @cite{Sprint} in file @code{sprint.ads} for a full list.
+of package @code{Sprint} in file @code{sprint.ads} for a full list.
@geindex -gnatL (gcc)
-If the switch @emph{-gnatL} is used in conjunction with
-@emph{-gnatG}, then the original source lines are interspersed
+If the switch @code{-gnatL} is used in conjunction with
+@code{-gnatG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
@item @code{(if @emph{expr} then @emph{expr} else @emph{expr})}
-Conditional expression equivalent to the @cite{x?y:z} construction in C.
+Conditional expression equivalent to the @code{x?y:z} construction in C.
@item @code{@emph{target}^(@emph{source})}
@item @code{free @emph{expr} [storage_pool = @emph{xxx}]}
-Shows the storage pool associated with a @cite{free} statement.
+Shows the storage pool associated with a @code{free} statement.
@item @code{[subtype or type declaration]}
@item @code{freeze @emph{type-name} [@emph{actions}]}
-Shows the point at which @cite{type-name} is frozen, with possible
+Shows the point at which @code{type-name} is frozen, with possible
associated actions to be performed at the freeze point.
@item @code{reference @emph{itype}}
-Reference (and hence definition) to internal type @cite{itype}.
+Reference (and hence definition) to internal type @code{itype}.
@item @code{@emph{function-name}! (@emph{arg}, @emph{arg}, @emph{arg})}
@item @code{@emph{label-name} : label}
-Declaration of label @cite{labelname}.
+Declaration of label @code{labelname}.
@item @code{#$ @emph{subprogram-name}}
@item @code{@emph{expr} && @emph{expr} && @emph{expr} ... && @emph{expr}}
-A multiple concatenation (same effect as @cite{expr} & @cite{expr} &
-@cite{expr}, but handled more efficiently).
+A multiple concatenation (same effect as @code{expr} & @code{expr} &
+@code{expr}, but handled more efficiently).
@item @code{[constraint_error]}
-Raise the @cite{Constraint_Error} exception.
+Raise the @code{Constraint_Error} exception.
@item @code{@emph{expression}'reference}
@item @code{@emph{target-type}!(@emph{source-expression})}
-An unchecked conversion of @cite{source-expression} to @cite{target-type}.
+An unchecked conversion of @code{source-expression} to @code{target-type}.
@item @code{[@emph{numerator}/@emph{denominator}]}
@item @code{-gnatD[=nn]}
-When used in conjunction with @emph{-gnatG}, this switch causes
+When used in conjunction with @code{-gnatG}, this switch causes
the expanded source, as described above for
-@emph{-gnatG} to be written to files with names
+@code{-gnatG} to be written to files with names
@code{xxx.dg}, where @code{xxx} is the normal file name,
instead of to the standard output file. For
example, if the source file name is @code{hello.adb}, then a file
@code{hello.adb.dg} will be written. The debugging
-information generated by the @emph{gcc} @emph{-g} switch
+information generated by the @code{gcc} @code{-g} switch
will refer to the generated @code{xxx.dg} file. This allows
you to do source level debugging using the generated code which is
sometimes useful for complex code, for example to find out exactly
which part of a complex construction raised an exception. This switch
-also suppress generation of cross-reference information (see
-@emph{-gnatx}) since otherwise the cross-reference information
+also suppresses generation of cross-reference information (see
+@code{-gnatx}) since otherwise the cross-reference information
would refer to the @code{.dg} file, which would cause
confusion since this is not the original source file.
-Note that @emph{-gnatD} actually implies @emph{-gnatG}
+Note that @code{-gnatD} actually implies @code{-gnatG}
automatically, so it is not necessary to give both options.
-In other words @emph{-gnatD} is equivalent to @emph{-gnatDG}).
+In other words @code{-gnatD} is equivalent to @code{-gnatDG}).
@geindex -gnatL (gcc)
-If the switch @emph{-gnatL} is used in conjunction with
-@emph{-gnatDG}, then the original source lines are interspersed
+If the switch @code{-gnatL} is used in conjunction with
+@code{-gnatDG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
-The optional parameter @cite{nn} if present after -gnatD specifies an
+The optional parameter @code{nn} if present after -gnatD specifies an
alternative maximum line length that overrides the normal default of 72.
This value is in the range 40-999999, values less than 40 being silently
reset to 40. The equal sign is optional.
@table @asis
-@item @code{-gnatR[0|1|2|3[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 and objects. For
-@emph{-gnatR0}, no information is output (equivalent to omitting
-the @emph{-gnatR} switch). For @emph{-gnatR1} (which is the default,
-so @emph{-gnatR} with no parameter has the same effect), size and alignment
-information is listed for declared array and record types. For
-@emph{-gnatR2}, size and alignment information is listed for all
-declared types and objects. The @cite{Linker_Section} is also listed for any
-entity for which the @cite{Linker_Section} is set explicitly or implicitly (the
-latter case occurs for objects of a type for which a @cite{Linker_Section}
+representation information for declared types, objects and subprograms.
+For @code{-gnatR0}, no information is output (equivalent to omitting
+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
+latter case occurs for objects of a type for which a @code{Linker_Section}
is set).
-Finally @emph{-gnatR3} includes symbolic
-expressions for values that are computed at run time for
-variant records. These symbolic expressions have a mostly obvious
-format with #n being used to represent the value of the n'th
-discriminant. See source files @code{repinfo.ads/adb} in the
-@cite{GNAT} sources for full details on the format of @emph{-gnatR3}
-output. If the switch is followed by an s (e.g., @emph{-gnatR2s}), then
-the output is to a file with the name @code{file.rep} where
-file is the name of the corresponding source file.
+For @code{-gnatR3}, symbolic expressions for values that are computed
+at run time for records are included. These symbolic expressions have
+a mostly obvious format with #n being used to represent the value of 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
+is included.
-@item @code{-gnatRm[s]}
+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.
-This form of the switch controls output of subprogram conventions
-and parameter passing mechanisms for all subprograms. A following
-@cite{s} means output to a file as described above.
+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 @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
-Ada syntax, for example @cite{at 0 range 0 .. -1}.
-
-Representation information requires that code be generated (since it is the
-code generator that lays out complex data structures). If an attempt is made
-to output representation information when no code is generated, for example
-when a subunit is compiled on its own, then no information can be generated
-and the compiler outputs a message to this effect.
+Ada syntax, for example @code{at 0 range 0 .. -1}.
@end table
@geindex -gnatS (gcc)
@item @code{-gnatS}
-The use of the switch @emph{-gnatS} for an
+The use of the switch @code{-gnatS} for an
Ada compilation will cause the compiler to output a
representation of package Standard in a form very
close to standard Ada. It is not quite possible to
Normally the compiler generates full cross-referencing information in
the @code{ALI} file. This information is used by a number of tools,
-including @cite{gnatfind} and @cite{gnatxref}. The @emph{-gnatx} switch
+including @code{gnatfind} and @code{gnatxref}. The @code{-gnatx} switch
suppresses this information. This saves some space and may slightly
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{119}@anchor{gnat_ugn/building_executable_programs_with_gnat exception-handling-control}@anchor{11a}
+@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
-@cite{setjmp/longjmp} method saves the context when entering
+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
need for tracing stack frames. This method provides very fast
exception handlers if no exception is raised. Note that in this
mode and in the context of mixed Ada and C/C++ programming,
to propagate an exception through a C/C++ code, the C/C++ code
-must be compiled with the @emph{-funwind-tables} GCC's
+must be compiled with the @code{-funwind-tables} GCC's
option.
The following switches may be used to control which of the
is available for the target in use, otherwise it will generate an error.
@end table
-The same option @emph{--RTS} must be used both for @emph{gcc}
-and @emph{gnatbind}. Passing this option to @emph{gnatmake}
-(@ref{df,,Switches for gnatmake}) will ensure the required consistency
+The same option @code{--RTS} must be used both for @code{gcc}
+and @code{gnatbind}. Passing this option to @code{gnatmake}
+(@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{11b}@anchor{gnat_ugn/building_executable_programs_with_gnat units-to-sources-mapping-files}@anchor{fc}
+@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
compiler, but mapping files can improve efficiency, particularly when
sources are read over a slow network connection. In normal operation,
you need not be concerned with the format or use of mapping files,
-and the @emph{-gnatem} switch is not a switch that you would use
+and the @code{-gnatem} switch is not a switch that you would use
explicitly. It is intended primarily for use by automatic tools such as
-@emph{gnatmake} running under the project file facility. The
+@code{gnatmake} running under the project file facility. The
description here of the format of mapping files is provided
for completeness and for possible use by other tools.
A mapping file is a sequence of sets of three lines. In each set, the
-first line is the unit name, in lower case, with @cite{%s} appended
-for specs and @cite{%b} appended for bodies; the second line is the
+first line is the unit name, in lower case, with @code{%s} appended
+for specs and @code{%b} appended for bodies; the second line is the
file name; and the third line is the path name.
Example:
/gnat/project1/sources/main.2.ada
@end example
-When the switch @emph{-gnatem} is specified, the compiler will
+When the switch @code{-gnatem} is specified, the compiler will
create in memory the two mappings from the specified file. If there is
any problem (nonexistent file, truncated file or duplicate entries),
no mapping will be created.
-Several @emph{-gnatem} switches may be specified; however, only the
+Several @code{-gnatem} switches may be specified; however, only the
last one on the command line will be taken into account.
-When using a project file, @emph{gnatmake} creates a temporary
+When using a project file, @code{gnatmake} creates a temporary
mapping file and communicates it to the compiler using this switch.
@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{11c}@anchor{gnat_ugn/building_executable_programs_with_gnat id30}@anchor{11d}
+@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
architectures. This includes variations in instruction sets (e.g.,
different members of the power pc family), and different requirements
for optimal arrangement of instructions (e.g., different members of
-the x86 family). The list of available @emph{-m} switches may be
+the x86 family). The list of available @code{-m} switches may be
found in the GCC documentation.
-Use of these @emph{-m} switches may in some cases result in improved
+Use of these @code{-m} switches may in some cases result in improved
code performance.
The GNAT technology is tested and qualified without any
successfully with GNAT, and many customers have reported successful
use of these options.
-Our general advice is to avoid the use of @emph{-m} switches unless
+Our general advice is to avoid the use of @code{-m} switches unless
special needs lead to requirements in this area. In particular,
-there is no point in using @emph{-m} switches to improve performance
+there is no point in using @code{-m} switches to improve performance
unless you actually see a performance improvement.
-@node Binding with gnatbind,Linking with gnatlink,Compiler Switches,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat binding-with-gnatbind}@anchor{1f}@anchor{gnat_ugn/building_executable_programs_with_gnat id31}@anchor{11e}
-@section Binding with @cite{gnatbind}
+@node Linker Switches,Binding with gnatbind,Compiler Switches,Building Executable Programs with GNAT
+@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
+
+
+Linker switches can be specified after @code{-largs} builder switch.
+
+@geindex -fuse-ld=name
+
+
+@table @asis
+
+@item @code{-fuse-ld=@emph{name}}
+
+Linker to be used. The default is @code{bfd} for @code{ld.bfd},
+the alternative being @code{gold} for @code{ld.gold}. The later is
+a more recent and faster linker, but only available on GNU/Linux
+platforms.
+@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{c8}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{10c}
+@section Binding with @code{gnatbind}
@geindex gnatbind
-This chapter describes the GNAT binder, @cite{gnatbind}, which is used
+This chapter describes the GNAT binder, @code{gnatbind}, which is used
to bind compiled GNAT objects.
-Note: to invoke @cite{gnatbind} with a project file, use the @cite{gnat}
-driver (see @ref{11f,,The GNAT Driver and Project Files}).
-
-The @cite{gnatbind} program performs four separate functions:
+The @code{gnatbind} program performs four separate functions:
@itemize *
This program is a small Ada package (body and spec) that
must be subsequently compiled
using the GNAT compiler. The necessary compilation step is usually
-performed automatically by @emph{gnatlink}. The two most important
+performed automatically by @code{gnatlink}. The two most important
functions of this program
are to call the elaboration routines of units in an appropriate order
and to call the main program.
@item
Determines the set of object files required by the given main program.
This information is output in the forms of comments in the generated program,
-to be read by the @emph{gnatlink} utility used to link the Ada application.
+to be read by the @code{gnatlink} utility used to link the Ada application.
@end itemize
@menu
@end menu
@node Running gnatbind,Switches for gnatbind,,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatbind}@anchor{120}@anchor{gnat_ugn/building_executable_programs_with_gnat id32}@anchor{121}
-@subsection Running @cite{gnatbind}
+@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}
-The form of the @cite{gnatbind} command is
+The form of the @code{gnatbind} command is
@example
-$ gnatbind [`switches`] `mainprog`[.ali] [`switches`]
+$ gnatbind [ switches ] mainprog[.ali] [ switches ]
@end example
where @code{mainprog.adb} is the Ada file containing the main program
-unit body. @cite{gnatbind} constructs an Ada
+unit body. @code{gnatbind} constructs an Ada
package in two files whose names are
@code{b~mainprog.ads}, and @code{b~mainprog.adb}.
For example, if given the
When doing consistency checking, the binder takes into consideration
any source files it can locate. For example, if the binder determines
-that the given main program requires the package @cite{Pack}, whose
+that the given main program requires the package @code{Pack}, whose
@code{.ALI}
file is @code{pack.ali} and whose corresponding source spec file is
@code{pack.ads}, it attempts to locate the source file @code{pack.ads}
(using the same search path conventions as previously described for the
-@emph{gcc} command). If it can locate this source file, it checks that
+@code{gcc} command). If it can locate this source file, it checks that
the time stamps
or source checksums of the source and its references to in @code{ALI} files
match. In other words, any @code{ALI} files that mentions this spec must have
error messages to be generated by the binder.
For example, suppose you have a main program @code{hello.adb} and a
-package @cite{P}, from file @code{p.ads} and you perform the following
+package @code{P}, from file @code{p.ads} and you perform the following
steps:
@itemize *
@item
-Enter @cite{gcc -c hello.adb} to compile the main program.
+Enter @code{gcc -c hello.adb} to compile the main program.
@item
-Enter @cite{gcc -c p.ads} to compile package @cite{P}.
+Enter @code{gcc -c p.ads} to compile package @code{P}.
@item
Edit file @code{p.ads}.
@item
-Enter @cite{gnatbind hello}.
+Enter @code{gnatbind hello}.
@end itemize
At this point, the file @code{p.ali} contains an out-of-date time stamp
Now both files must be recompiled as indicated, and then the bind can
succeed, generating a main program. You need not normally be concerned
with the contents of this file, but for reference purposes a sample
-binder output file is given in @ref{10,,Example of Binder Output File}.
+binder output file is given in @ref{e,,Example of Binder Output File}.
-In most normal usage, the default mode of @emph{gnatbind} which is to
+In most normal usage, the default mode of @code{gnatbind} which is to
generate the main package in Ada, as described in the previous section.
In particular, this means that any Ada programmer can read and understand
the generated main program. It can also be debugged just like any other
-Ada code provided the @emph{-g} switch is used for
-@emph{gnatbind} and @emph{gnatlink}.
+Ada code provided the @code{-g} switch is used for
+@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 id33}@anchor{122}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatbind}@anchor{123}
-@subsection Switches for @emph{gnatbind}
+@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}
-The following switches are available with @cite{gnatbind}; details will
+The following switches are available with @code{gnatbind}; details will
be presented in subsequent sections.
@geindex --version (gnatbind)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-d@emph{nn}[k|m]}
This switch can be used to change the default task stack size value
-to a specified size @cite{nn}, which is expressed in bytes by default, or
-in kilobytes when suffixed with @cite{k} or in megabytes when suffixed
-with @cite{m}.
+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}.
In the absence of a @code{[k|m]} suffix, this switch is equivalent,
in effect, to completing all task specs with
@item @code{-D@emph{nn}[k|m]}
-This switch can be used to change the default secondary stack size value
-to a specified size @cite{nn}, which is expressed in bytes by default, or
-in kilobytes when suffixed with @cite{k} or in megabytes when suffixed
-with @cite{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 is growing on demand and is allocated
-as a chain of blocks in the heap. The -D option is not very
-relevant. It only give some control over the size of the allocated
-blocks (whose size is the minimum of the default secondary stack size value,
-and the actual size needed for the current allocation request).
+For 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,
-the secondary stack is allocated by carving off a fixed ratio chunk of the
-primary task stack. The -D option is used to define the
-size of the environment task's secondary stack.
+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)
The "a" is for "address"; tracebacks will contain hexadecimal addresses,
unless symbolic tracebacks are enabled.
-See also the packages @cite{GNAT.Traceback} and
-@cite{GNAT.Traceback.Symbolic} for more information.
-Note that on x86 ports, you must not use @emph{-fomit-frame-pointer}
-@emph{gcc} option.
+See also the packages @code{GNAT.Traceback} and
+@code{GNAT.Traceback.Symbolic} for more information.
+Note that on x86 ports, you must not use @code{-fomit-frame-pointer}
+@code{gcc} option.
@end table
@geindex -Es (gnatbind)
@item @code{-E}
-Currently the same as @cite{-Ea}.
+Currently the same as @code{-Ea}.
+@end table
+
+@geindex -f (gnatbind)
+
+
+@table @asis
+
+@item @code{-f@emph{elab-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{-F}
-Force the checks of elaboration flags. @emph{gnatbind} does not normally
+Force the checks of elaboration flags. @code{gnatbind} does not normally
generate checks of elaboration flags for the main executable, except when
a Stand-Alone Library is used. However, there are cases when this cannot be
detected by gnatbind. An example is importing an interface of a Stand-Alone
@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 @cite{__gnat_malloc} (and thus for access types).
-For further details see @ref{124,,Dynamic Allocation Control}.
+Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types).
+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 @cite{__gnat_malloc} (and thus for access types).
-For further details see @ref{124,,Dynamic Allocation Control}.
+Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types).
+For further details see @ref{112,,Dynamic Allocation Control}.
@geindex -I (gnatbind)
@item @code{-I-}
-Do not look for sources in the current directory where @cite{gnatbind} was
+Do not look for sources in the current directory where @code{gnatbind} was
invoked, and do not look for ALI files in the directory containing the
-ALI file named in the @cite{gnatbind} command line.
+ALI file named in the @code{gnatbind} command line.
@geindex -l (gnatbind)
@item @code{-L@emph{xxx}}
-Bind the units for library building. In this case the adainit and
-adafinal procedures (@ref{ba,,Binding with Non-Ada Main Programs})
-are renamed to @cite{xxx`init and `xxx`final. Implies -n. (:ref:`GNAT_and_Libraries}, for more details.)
+Bind the units for library building. In this case the @code{adainit} and
+@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{2a,,GNAT and Libraries}, for more details.)
@geindex -M (gnatbind)
@item @code{-m@emph{n}}
-Limit number of detected errors or warnings to @cite{n}, where @cite{n} is
+Limit number of detected errors or warnings to @code{n}, where @code{n} is
in the range 1..999999. The default value if no switch is
given is 9999. If the number of warnings reaches this limit, then a
message is output and further warnings are suppressed, the bind
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 @emph{gnatmake} flag (@ref{df,,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{-o @emph{file}}
-Name the output file @cite{file} (default is @code{b~`xxx}.adb`).
+Name the output file @code{file} (default is @code{b~`xxx}.adb`).
Note that if this option is used, then linking must be done manually,
gnatlink cannot be used.
@item @code{-Ra}
-Like @emph{-R} but the list includes run-time units.
+Like @code{-R} but the list includes run-time units.
@geindex -s (gnatbind)
Specifies the value to be used when detecting uninitialized scalar
objects with pragma Initialize_Scalars.
-The @cite{xxx} string specified with the switch is one of:
+The @code{xxx} string specified with the switch is one of:
@itemize *
(see body of package System.Scalar_Values for exact values).
@item
-@cite{xx} for hex value (two hex digits).
+@code{xx} for hex value (two hex digits).
The underlying scalar is set to a value consisting of repeated bytes, whose
value corresponds to the given value. For example if @code{BF} is given,
@geindex GNAT_INIT_SCALARS
-In addition, you can specify @emph{-Sev} to indicate that the value is
+In addition, you can specify @code{-Sev} to indicate that the value is
to be set at run time. In this case, the program will look for an environment
-variable of the form @code{GNAT_INIT_SCALARS=@emph{yy}}, where @cite{yy} is one
-of @emph{in/lo/hi/`xx*` with the same meanings as above.
+variable of the form @code{GNAT_INIT_SCALARS=@emph{yy}}, where @code{yy} is one
+of @code{in/lo/hi/@emph{xx}} with the same meanings as above.
If no environment variable is found, or if it does not have a valid value,
-then the default is *in} (invalid values).
+then the default is @code{in} (invalid values).
@end table
@geindex -static (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)
@item @code{-T@emph{n}}
-Set the time slice value to @cite{n} milliseconds. If the system supports
+Set the time slice value to @code{n} milliseconds. If the system supports
the specification of a specific time slice value, then the indicated value
is used. If the system does not support specific time slice values, but
does support some general notion of round-robin scheduling, then any
nonzero value will activate round-robin scheduling.
A value of zero is treated specially. It turns off time
-slicing, and in addition, indicates to the tasking run time that the
+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 @cite{FIFO_Within_Priorities}.
+scheduling policy to @code{FIFO_Within_Priorities}.
@geindex -u (gnatbind)
@item @code{-u@emph{n}}
-Enable dynamic stack usage, with @cite{n} results stored and displayed
+Enable dynamic stack usage, with @code{n} results stored and displayed
at program termination. A result is generated when a task
terminates. Results that can't be stored are displayed on the fly, at
task termination. This option is currently not supported on Itanium
-platforms. (See @ref{125,,Dynamic Stack Usage Analysis} for details.)
+platforms. (See @ref{113,,Dynamic Stack Usage Analysis} for details.)
@geindex -v (gnatbind)
@item @code{-V@emph{key}=@emph{value}}
-Store the given association of @cite{key} to @cite{value} in the bind environment.
+Store the given association of @code{key} to @code{value} in the bind environment.
Values stored this way can be retrieved at run time using
-@cite{GNAT.Bind_Environment}.
+@code{GNAT.Bind_Environment}.
@geindex -w (gnatbind)
@item @code{-w@emph{x}}
-Warning mode; @cite{x} = s/e for suppress/treat as error.
+Warning mode; @code{x} = s/e for suppress/treat as error.
@geindex -Wx (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}}
@item @code{-y}
-Enable leap seconds support in @cite{Ada.Calendar} and its children.
+Enable leap seconds support in @code{Ada.Calendar} and its children.
@geindex -z (gnatbind)
No main subprogram.
@end table
-You may obtain this listing of switches by running @cite{gnatbind} with
+You may obtain this listing of switches by running @code{gnatbind} with
no arguments.
@menu
@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{126}@anchor{gnat_ugn/building_executable_programs_with_gnat id34}@anchor{127}
+@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
-As described earlier, by default @cite{gnatbind} checks
+As described earlier, by default @code{gnatbind} checks
that object files are consistent with one another and are consistent
with any source files it can locate. The following switches control binder
access to sources.
Normally the default wide character encoding method used for standard
[Wide_[Wide_]]Text_IO files is taken from the encoding specified for
the main source input (see description of switch
-@emph{-gnatWx} for the compiler). The
+@code{-gnatWx} for the compiler). The
use of this switch for the binder (which has the same set of
possible arguments) overrides this default as specified.
If a source file has been edited since it was last compiled, and you
specify this switch, the binder will not detect that the object
file is out of date with respect to the source file. Note that this is the
-mode that is automatically used by @emph{gnatmake} because in this
+mode that is automatically used by @code{gnatmake} because in this
case the checking against sources has already been performed by
-@emph{gnatmake} in the course of compilation (i.e., before binding).
+@code{gnatmake} in the course of compilation (i.e., before binding).
@end table
@node Binder Error Message Control,Elaboration Control,Consistency-Checking Modes,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id35}@anchor{128}@anchor{gnat_ugn/building_executable_programs_with_gnat binder-error-message-control}@anchor{129}
+@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
Generate brief error messages to @code{stderr} even if verbose mode is
specified. This is relevant only when used with the
-@emph{-v} switch.
+@code{-v} switch.
@geindex -m (gnatbind)
@item @code{-m@emph{n}}
-Limits the number of error messages to @cite{n}, a decimal integer in the
+Limits the number of error messages to @code{n}, a decimal integer in the
range 1-999. The binder terminates immediately if this limit is reached.
@geindex -M (gnatbind)
@item @code{-M@emph{xxx}}
-Renames the generated main program from @cite{main} to @cite{xxx}.
+Renames the generated main program from @code{main} to @code{xxx}.
This is useful in the case of some cross-building environments, where
the actual main program is separate from the one generated
-by @cite{gnatbind}.
+by @code{gnatbind}.
@geindex -ws (gnatbind)
Check that checksums of a given source unit are consistent
@item
-Check that consistent versions of @cite{GNAT} were used for compilation
+Check that consistent versions of @code{GNAT} were used for compilation
@item
Check consistency of configuration pragmas as required
generated which abort the binder and prevent the output of a binder
file and subsequent link to obtain an executable.
-The @emph{-t} switch converts these error messages
+The @code{-t} switch converts these error messages
into warnings, so that
binding and linking can continue to completion even in the presence of such
errors. The result may be a failed link (due to missing symbols), or a
@cartouche
@quotation Note
-This means that @emph{-t} should be used only in unusual situations,
+This means that @code{-t} should be used only in unusual situations,
with extreme care.
@end quotation
@end cartouche
@end table
@node Elaboration Control,Output Control,Binder Error Message Control,Switches for gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id36}@anchor{12a}@anchor{gnat_ugn/building_executable_programs_with_gnat elaboration-control}@anchor{12b}
+@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{11,,Elaboration Order Handling in GNAT}.
+order. For further details see @ref{f,,Elaboration Order Handling in GNAT}.
-@quotation
+@geindex -f (gnatbind)
+
+
+@table @asis
+
+@item @code{-f@emph{elab-order}}
+
+Force elaboration order.
+
+@code{elab-order} should be the name of a "forced elaboration order file", that
+is, a text file containing library item names, one per line. A name of the
+form "some.unit%s" or "some.unit (spec)" denotes the spec of Some.Unit. A
+name of the form "some.unit%b" or "some.unit (body)" denotes the body of
+Some.Unit. Each pair of lines is taken to mean that there is an elaboration
+dependence of the second line on the first. For example, if the file
+contains:
+
+@example
+this (spec)
+this (body)
+that (spec)
+that (body)
+@end example
+
+then the spec of This will be elaborated before the body of This, and the
+body of This will be elaborated before the spec of That, and the spec of That
+will be elaborated before the body of That. The first and last of these three
+dependences are already required by Ada rules, so this file is really just
+forcing the body of This to be elaborated before the spec of That.
+
+The given order must be consistent with Ada rules, or else @code{gnatbind} will
+give elaboration cycle errors. For example, if you say x (body) should be
+elaborated before x (spec), there will be a cycle, because Ada rules require
+x (spec) to be elaborated before x (body); you can't have the spec and body
+both elaborated before each other.
+
+If you later add "with That;" to the body of This, there will be a cycle, in
+which case you should erase either "this (body)" or "that (spec)" from the
+above forced elaboration order file.
+
+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)
-@end quotation
@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 @cite{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 @emph{-p}
-switch if dynamic
-elaboration checking is used (@emph{-gnatE} switch used for compilation).
+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
+elaboration checking is used (@code{-gnatE} switch used for compilation).
This is because in the default static elaboration mode, all necessary
-@cite{Elaborate} and @cite{Elaborate_All} pragmas are implicitly inserted.
-These implicit pragmas are still respected by the binder in
-@emph{-p} mode, so a
-safe elaboration order is assured.
+@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.
-Note that @emph{-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{12c}@anchor{gnat_ugn/building_executable_programs_with_gnat id37}@anchor{12d}
+@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
Output linker options to @code{stdout}. Includes library search paths,
contents of pragmas Ident and Linker_Options, and libraries added
-by @cite{gnatbind}.
+by @code{gnatbind}.
@geindex -l (gnatbind)
@item @code{-o @emph{file}}
-Set name of output file to @cite{file} instead of the normal
-@code{b~`mainprog}.adb` default. Note that @cite{file} denote the Ada
+Set name of output file to @code{file} instead of the normal
+@code{b~`mainprog}.adb` default. Note that @code{file} denote the Ada
binder generated body filename.
Note that if this option is used, then linking must be done manually.
It is not possible to use gnatlink in this case, since it cannot locate
@item @code{-r}
-Generate list of @cite{pragma Restrictions} that could be applied to
+Generate list of @code{pragma Restrictions} that could be applied to
the current unit. This is useful for code audit purposes, and also may
be used to improve code generation in some cases.
@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{124}@anchor{gnat_ugn/building_executable_programs_with_gnat id38}@anchor{12e}
+@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
-The heap control switches -- @emph{-H32} and @emph{-H64} --
+The heap control switches -- @code{-H32} and @code{-H64} --
determine whether dynamic allocation uses 32-bit or 64-bit memory.
-They only affect compiler-generated allocations via @cite{__gnat_malloc};
-explicit calls to @cite{malloc} and related functions from the C
+They only affect compiler-generated allocations via @code{__gnat_malloc};
+explicit calls to @code{malloc} and related functions from the C
run-time library are unaffected.
@item @code{-H64}
Allocate memory on 64-bit heap. This is the default
-unless explicitly overridden by a @cite{'Size} clause on the access type.
+unless explicitly overridden by a @code{'Size} clause on the access type.
@end table
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{ba}@anchor{gnat_ugn/building_executable_programs_with_gnat id39}@anchor{12f}
+@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
The description so far has assumed that the main
program is in Ada, and that the task of the binder is to generate a
-corresponding function @cite{main} that invokes this Ada main
+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{46,,Mixed Language Programming}).
+written in Ada and compiled using GNAT (@ref{2c,,Mixed Language Programming}).
The following switch is used in this situation:
@quotation
@table @asis
-@item @emph{adainit}
+@item @code{adainit}
You must call this routine to initialize the Ada part of the program by
-calling the necessary elaboration routines. A call to @cite{adainit} is
+calling the necessary elaboration routines. A call to @code{adainit} is
required before the first call to an Ada subprogram.
Note that it is assumed that the basic execution environment must be setup
@table @asis
-@item @emph{adafinal}
+@item @code{adafinal}
You must call this routine to perform any library-level finalization
-required by the Ada subprograms. A call to @cite{adafinal} is required
+required by the Ada subprograms. A call to @code{adafinal} is required
after the last call to an Ada subprogram, and before the program
terminates.
@end table
@geindex Binder
@geindex multiple input files
-If the @emph{-n} switch
+If the @code{-n} switch
is given, more than one ALI file may appear on
-the command line for @cite{gnatbind}. The normal @emph{closure}
+the command line for @code{gnatbind}. The normal @code{closure}
calculation is performed for each of the specified units. Calculating
the closure means finding out the set of units involved by tracing
@emph{with} references. The reason it is necessary to be able to
more quite separate groups of Ada units.
The binder takes the name of its output file from the last specified ALI
-file, unless overridden by the use of the @emph{-o file}.
+file, unless overridden by the use of the @code{-o file}.
@geindex -o (gnatbind)
The output is an Ada unit in source form that can be compiled with GNAT.
-This compilation occurs automatically as part of the @emph{gnatlink}
+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{130}@anchor{gnat_ugn/building_executable_programs_with_gnat id40}@anchor{131}
+@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
that the default wide character encoding method for standard Text_IO
files is always set to Brackets if this switch is set (you can use
the binder switch
-@emph{-Wx} to override this default).
+@code{-Wx} to override this default).
@end table
@node Command-Line Access,Search Paths for gnatbind,Switches for gnatbind,Binding with gnatbind
-@anchor{gnat_ugn/building_executable_programs_with_gnat id41}@anchor{132}@anchor{gnat_ugn/building_executable_programs_with_gnat command-line-access}@anchor{133}
+@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
-The package @cite{Ada.Command_Line} provides access to the command-line
+The package @code{Ada.Command_Line} provides access to the command-line
arguments and program name. In order for this interface to operate
correctly, the two variables
@geindex gnat_argc
are declared in one of the GNAT library routines. These variables must
-be set from the actual @cite{argc} and @cite{argv} values passed to the
-main program. With no @emph{n} present, @cite{gnatbind}
+be set from the actual @code{argc} and @code{argv} values passed to the
+main program. With no @emph{n} present, @code{gnatbind}
generates the C main program to automatically set these variables.
If the @emph{n} switch is used, there is no automatic way to
set these variables. If they are not set, the procedures in
-@cite{Ada.Command_Line} will not be available, and any attempt to use
-them will raise @cite{Constraint_Error}. If command line access is
-required, your main program must set @cite{gnat_argc} and
-@cite{gnat_argv} from the @cite{argc} and @cite{argv} values passed to
+@code{Ada.Command_Line} will not be available, and any attempt to use
+them will raise @code{Constraint_Error}. If command line access is
+required, your main program must set @code{gnat_argc} and
+@code{gnat_argv} from the @code{argc} and @code{argv} values passed to
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{91}@anchor{gnat_ugn/building_executable_programs_with_gnat id42}@anchor{134}
-@subsection Search Paths for @cite{gnatbind}
+@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}
The binder takes the name of an ALI file as its argument and needs to
locate source files as well as other ALI files to verify object consistency.
-For source files, it follows exactly the same search rules as @emph{gcc}
-(see @ref{8e,,Search Paths and the Run-Time Library (RTL)}). For ALI files the
+For source files, it follows exactly the same search rules as @code{gcc}
+(see @ref{73,,Search Paths and the Run-Time Library (RTL)}). For ALI files the
directories searched are:
@item
The directory containing the ALI file named in the command line, unless
-the switch @emph{-I-} is specified.
+the switch @code{-I-} is specified.
@item
-All directories specified by @emph{-I}
-switches on the @cite{gnatbind}
+All directories specified by @code{-I}
+switches on the @code{gnatbind}
command line, in the order given.
@geindex ADA_PRJ_OBJECTS_FILE
@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 @emph{-nostdlib} is
-specified. See @ref{8b,,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)
@geindex -aO (gnatbind)
-In the binder the switch @emph{-I}
+In the binder the switch @code{-I}
is used to specify both source and
-library file paths. Use @emph{-aI}
+library file paths. Use @code{-aI}
instead if you want to specify
-source paths only, and @emph{-aO}
+source paths only, and @code{-aO}
if you want to specify library paths
only. This means that for the binder
@code{-I@emph{dir}} is equivalent to
@geindex GNAT
-The packages @cite{Ada}, @cite{System}, and @cite{Interfaces} and their
+The packages @code{Ada}, @code{System}, and @code{Interfaces} and their
children make up the GNAT Run-Time Library, together with the package
GNAT and its children, which contain a set of useful additional
library functions provided by GNAT. The sources for these units are
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 examples-of-gnatbind-usage}@anchor{135}@anchor{gnat_ugn/building_executable_programs_with_gnat id43}@anchor{136}
-@subsection Examples of @cite{gnatbind} Usage
+@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
-Here are some examples of @cite{gnatbind} invovations:
+Here are some examples of @code{gnatbind} invovations:
@quotation
gnatbind hello
@end example
-The main program @cite{Hello} (source program in @code{hello.adb}) is
+The main program @code{Hello} (source program in @code{hello.adb}) is
bound using the standard switch settings. The generated main program is
@code{b~hello.adb}. This is the normal, default use of the binder.
gnatbind hello -o mainprog.adb
@end example
-The main program @cite{Hello} (source program in @code{hello.adb}) is
+The main program @code{Hello} (source program in @code{hello.adb}) is
bound using the standard switch settings. The generated main program is
@code{mainprog.adb} with the associated spec in
@code{mainprog.ads}. Note that you must specify the body here not the
@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 id44}@anchor{137}@anchor{gnat_ugn/building_executable_programs_with_gnat linking-with-gnatlink}@anchor{20}
-@section Linking with @emph{gnatlink}
+@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}
@geindex gnatlink
-This chapter discusses @emph{gnatlink}, a tool that links
+This chapter discusses @code{gnatlink}, a tool that links
an Ada program and builds an executable file. This utility
-invokes the system linker (via the @emph{gcc} command)
+invokes the system linker (via the @code{gcc} command)
with a correct list of object files and library references.
-@emph{gnatlink} automatically determines the list of files and
+@code{gnatlink} automatically determines the list of files and
references for the Ada part of a program. It uses the binder file
-generated by the @emph{gnatbind} to determine this list.
-
-Note: to invoke @cite{gnatlink} with a project file, use the @cite{gnat}
-driver (see @ref{11f,,The GNAT Driver and Project Files}).
+generated by the @code{gnatbind} to determine this list.
@menu
* Running gnatlink::
@end menu
@node Running gnatlink,Switches for gnatlink,,Linking with gnatlink
-@anchor{gnat_ugn/building_executable_programs_with_gnat id45}@anchor{138}@anchor{gnat_ugn/building_executable_programs_with_gnat running-gnatlink}@anchor{139}
-@subsection Running @emph{gnatlink}
+@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}
-The form of the @emph{gnatlink} command is
+The form of the @code{gnatlink} command is
@example
-$ gnatlink [`switches`] `mainprog`[.ali]
- [`non-Ada objects`] [`linker options`]
+$ gnatlink [ switches ] mainprog [.ali]
+ [ non-Ada objects ] [ linker options ]
@end example
-The arguments of @emph{gnatlink} (switches, main @code{ALI} file,
+The arguments of @code{gnatlink} (switches, main @code{ALI} file,
non-Ada objects
or linker options) may be in any order, provided that no non-Ada object may
be mistaken for a main @code{ALI} file.
@code{mainprog.ali} references the ALI file of the main program.
The @code{.ali} extension of this file can be omitted. From this
-reference, @emph{gnatlink} locates the corresponding binder file
+reference, @code{gnatlink} locates the corresponding binder file
@code{b~mainprog.adb} and, using the information in this file along
with the list of non-Ada objects and linker options, constructs a
linker command file to create the executable.
-The arguments other than the @emph{gnatlink} switches and the main
+The arguments other than the @code{gnatlink} switches and the main
@code{ALI} file are passed to the linker uninterpreted.
They typically include the names of
object files for units written in other languages than Ada and any library
references required to resolve references in any of these foreign language
-units, or in @cite{Import} pragmas in any Ada units.
+units, or in @code{Import} pragmas in any Ada units.
-@cite{linker options} is an optional list of linker specific
+@code{linker options} is an optional list of linker specific
switches.
-The default linker called by gnatlink is @emph{gcc} which in
+The default linker called by gnatlink is @code{gcc} which in
turn calls the appropriate system linker.
-One useful option for the linker is @emph{-s}: it reduces the size of the
+One useful option for the linker is @code{-s}: it reduces the size of the
executable by removing all symbol table and relocation information from the
executable.
-Standard options for the linker such as @emph{-lmy_lib} or
-@emph{-Ldir} can be added as is.
+Standard options for the linker such as @code{-lmy_lib} or
+@code{-Ldir} can be added as is.
For options that are not recognized by
-@emph{gcc} as linker options, use the @emph{gcc} switches
-@emph{-Xlinker} or @emph{-Wl,}.
+@code{gcc} as linker options, use the @code{gcc} switches
+@code{-Xlinker} or @code{-Wl,}.
Refer to the GCC documentation for
details.
$ gnatlink my_prog -Wl,-Map,MAPFILE
@end example
-Using @cite{linker options} it is possible to set the program stack and
+Using @code{linker options} it is possible to set the program stack and
heap size.
-See @ref{13a,,Setting Stack Size from gnatlink} and
-@ref{13b,,Setting Heap Size from gnatlink}.
+See @ref{127,,Setting Stack Size from gnatlink} and
+@ref{128,,Setting Heap Size from gnatlink}.
-@emph{gnatlink} determines the list of objects required by the Ada
+@code{gnatlink} determines the list of objects required by the Ada
program and prepends them to the list of objects passed to the linker.
-@emph{gnatlink} also gathers any arguments set by the use of
-@cite{pragma Linker_Options} and adds them to the list of arguments
+@code{gnatlink} also gathers any arguments set by the use of
+@code{pragma Linker_Options} and adds them to the list of arguments
presented to the linker.
@node Switches for gnatlink,,Running gnatlink,Linking with gnatlink
-@anchor{gnat_ugn/building_executable_programs_with_gnat id46}@anchor{13c}@anchor{gnat_ugn/building_executable_programs_with_gnat switches-for-gnatlink}@anchor{13d}
-@subsection Switches for @emph{gnatlink}
+@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}
-The following switches are available with the @emph{gnatlink} utility:
+The following switches are available with the @code{gnatlink} utility:
@geindex --version (gnatlink)
@item @code{--help}
-If @emph{--version} was not used, display usage, then exit disregarding
+If @code{--version} was not used, display usage, then exit disregarding
all other options.
@end table
@item @code{-f}
-On some targets, the command line length is limited, and @emph{gnatlink}
+On some targets, the command line length is limited, and @code{gnatlink}
will generate a separate file for the linker if the list of object files
is too long.
-The @emph{-f} switch forces this file
+The @code{-f} switch forces this file
to be generated even if
the limit is not exceeded. This is useful in some cases to deal with
special situations where the command line length is exceeded.
@item @code{-g}
The option to include debugging information causes the Ada bind file (in
-other words, @code{b~mainprog.adb}) to be compiled with @emph{-g}.
+other words, @code{b~mainprog.adb}) to be compiled with @code{-g}.
In addition, the binder does not delete the @code{b~mainprog.adb},
@code{b~mainprog.o} and @code{b~mainprog.ali} files.
-Without @emph{-g}, the binder removes these files by default.
+Without @code{-g}, the binder removes these files by default.
@end table
@geindex -n (gnatlink)
@item @code{-o @emph{exec-name}}
-@cite{exec-name} specifies an alternate name for the generated
+@code{exec-name} specifies an alternate name for the generated
executable program. If this switch is omitted, the executable has the same
-name as the main unit. For example, @cite{gnatlink try.ali} creates
+name as the main unit. For example, @code{gnatlink try.ali} creates
an executable called @code{try}.
@end table
-@geindex -b (gnatlink)
-
-
-@table @asis
-
-@item @code{-b @emph{target}}
-
-Compile your program to run on @cite{target}, which is the name of a
-system configuration. You must have a GNAT cross-compiler built if
-@cite{target} is not the same as your host system.
-@end table
-
@geindex -B (gnatlink)
@item @code{-B@emph{dir}}
-Load compiler executables (for example, @cite{gnat1}, the Ada compiler)
-from @cite{dir} instead of the default location. Only use this switch
+Load compiler executables (for example, @code{gnat1}, the Ada compiler)
+from @code{dir} instead of the default location. Only use this switch
when multiple versions of the GNAT compiler are available.
-See the @cite{Directory Options} section in @cite{The_GNU_Compiler_Collection}
-for further details. You would normally use the @emph{-b} or
-@emph{-V} switch instead.
+See the @code{Directory Options} section in @cite{The_GNU_Compiler_Collection}
+for further details. You would normally use the @code{-b} or
+@code{-V} switch instead.
@end table
@geindex -M (gnatlink)
@item @code{-M=@emph{mapfile}}
When linking an executable, create a map file. The name of the map file is
-@cite{mapfile}.
+@code{mapfile}.
@end table
@geindex --GCC=compiler_name (gnatlink)
@item @code{--GCC=@emph{compiler_name}}
Program used for compiling the binder file. The default is
-@code{gcc}. You need to use quotes around @cite{compiler_name} if
-@cite{compiler_name} contains spaces or other separator characters.
-As an example @code{--GCC="foo -x -y"} will instruct @emph{gnatlink} to
+@code{gcc}. You need to use quotes around @code{compiler_name} if
+@code{compiler_name} contains spaces or other separator characters.
+As an example @code{--GCC="foo -x -y"} will instruct @code{gnatlink} to
use @code{foo -x -y} as your compiler. Note that switch @code{-c} is always
inserted after your command name. Thus in the above example the compiler
-command that will be used by @emph{gnatlink} will be @code{foo -c -x -y}.
+command that will be used by @code{gnatlink} will be @code{foo -c -x -y}.
A limitation of this syntax is that the name and path name of the executable
itself must not include any embedded spaces. If the compiler executable is
different from the default one (gcc or <prefix>-gcc), then the back-end
switches in the ALI file are not used to compile the binder generated source.
For example, this is the case with @code{--GCC="foo -x -y"}. But the back end
switches will be used for @code{--GCC="gcc -gnatv"}. If several
-@code{--GCC=compiler_name} are used, only the last @cite{compiler_name}
+@code{--GCC=compiler_name} are used, only the last @code{compiler_name}
is taken into account. However, all the additional switches are also taken
into account. Thus,
@code{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to
@item @code{--LINK=@emph{name}}
-@cite{name} is the name of the linker to be invoked. This is especially
+@code{name} is the name of the linker to be invoked. This is especially
useful in mixed language programs since languages such as C++ require
their own linker to be used. When this switch is omitted, the default
-name for the linker is @emph{gcc}. When this switch is used, the
-specified linker is called instead of @emph{gcc} with exactly the same
-parameters that would have been passed to @emph{gcc} so if the desired
+name for the linker is @code{gcc}. When this switch is used, the
+specified linker is called instead of @code{gcc} with exactly the same
+parameters that would have been passed to @code{gcc} so if the desired
linker requires different parameters it is necessary to use a wrapper
script that massages the parameters before invoking the real linker. It
may be useful to control the exact invocation by using the verbose
@end table
@node Using the GNU make Utility,,Linking with gnatlink,Building Executable Programs with GNAT
-@anchor{gnat_ugn/building_executable_programs_with_gnat id47}@anchor{13e}@anchor{gnat_ugn/building_executable_programs_with_gnat using-the-gnu-make-utility}@anchor{21}
-@section Using the GNU @cite{make} Utility
+@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
@geindex make (GNU)
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
-@emph{gnatmake} utility (@ref{1d,,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 @emph{make} is a standard utility, and the basic language
+make. Although @code{make} is a standard utility, and the basic language
is the same, these examples use some advanced features found only in
-@cite{GNU make}.
+@code{GNU make}.
@menu
* Using gnatmake in a Makefile::
@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{13f}@anchor{gnat_ugn/building_executable_programs_with_gnat id48}@anchor{140}
+@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
each step of the build process.
The list of dependencies are handled automatically by
-@emph{gnatmake}. The Makefile is simply used to call gnatmake in each of
+@code{gnatmake}. The Makefile is simply used to call gnatmake in each of
the appropriate directories.
Note that you should also read the example on how to automatically
create the list of directories
-(@ref{141,,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 automatically-creating-a-list-of-directories}@anchor{141}@anchor{gnat_ugn/building_executable_programs_with_gnat id49}@anchor{142}
+@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
The example below presents two methods. The first one, although less
general, gives you more control over the list. It involves wildcard
-characters, that are automatically expanded by @emph{make}. Its
+characters, that are automatically expanded by @code{make}. Its
shortcoming is that you need to explicitly specify some of the
organization of your project, such as for instance the directory tree
depth, whether some directories are found in a separate tree, etc.
The second method is the most general one. It requires an external
-program, called @emph{find}, which is standard on all Unix systems. All
+program, called @code{find}, which is standard on all Unix systems. All
the directories found under a given root directory will be added to the
list.
# Note that the argument(s) to wildcard below should end with a '/'.
# Since wildcards also return file names, we have to filter them out
# to avoid duplicate directory names.
-# We thus use make's `dir` and `sort` functions.
+# We thus use make's `@w{`}dir`@w{`} and `@w{`}sort`@w{`} functions.
# It sets DIRs to the following value (note that the directories aaa and baa
# are not given, unless you change the arguments to wildcard).
# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/
@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 id50}@anchor{143}@anchor{gnat_ugn/building_executable_programs_with_gnat generating-the-command-line-switches}@anchor{144}
+@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{141,,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{145}@anchor{gnat_ugn/building_executable_programs_with_gnat id51}@anchor{146}
+@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
gnatmake the list of source and object directories.
This example shows how you can set up environment variables, which will
-make @emph{gnatmake} behave exactly as if the directories had been
+make @code{gnatmake} behave exactly as if the directories had been
specified on the command line, but have a much higher length limit (or
even none on most systems).
It assumes that you have created a list of directories in your Makefile,
using one of the methods presented in
-@ref{141,,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.
Note a small trick in the Makefile below: for efficiency reasons, we
create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are
-expanded immediately by @cite{make}. This way we overcome the standard
+expanded immediately by @code{make}. This way we overcome the standard
make behavior which is to expand the variables only when they are
actually used.
gnatmake main_unit
@end example
-@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-
-@node GNAT Project Manager,Tools Supporting Project Files,Building Executable Programs with GNAT,Top
-@anchor{gnat_ugn/gnat_project_manager doc}@anchor{147}@anchor{gnat_ugn/gnat_project_manager gnat-project-manager}@anchor{b}@anchor{gnat_ugn/gnat_project_manager id1}@anchor{148}
-@chapter GNAT Project Manager
-
-
-@menu
-* Introduction::
-* Building With Projects::
-* Organizing Projects into Subsystems::
-* Scenarios in Projects::
-* Library Projects::
-* Project Extension::
-* Aggregate Projects::
-* Aggregate Library Projects::
-* Project File Reference::
-
-@end menu
+@node GNAT Utility Programs,GNAT and Program Execution,Building Executable Programs with GNAT,Top
+@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
-@node Introduction,Building With Projects,,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager introduction}@anchor{149}@anchor{gnat_ugn/gnat_project_manager gnat-project-manager-introduction}@anchor{14a}
-@section Introduction
+This chapter describes a number of utility programs:
-This chapter describes GNAT's @emph{Project Manager}, a facility that allows
-you to manage complex builds involving a number of source files, directories,
-and options for different system configurations. In particular,
-project files allow you to specify:
@itemize *
@item
-The directory or set of directories containing the source files, and/or the
-names of the specific source files themselves
+@ref{136,,The File Cleanup Utility gnatclean}
@item
-The directory in which the compiler's output
-(@code{ALI} files, object files, tree files, etc.) is to be placed
+@ref{137,,The GNAT Library Browser gnatls}
+@end itemize
-@item
-The directory in which the executable programs are to be placed
+Other GNAT utilities are described elsewhere in this manual:
-@item
-Switch settings for any of the project-enabled tools;
-you can apply these settings either globally or to individual compilation units.
-@item
-The source files containing the main subprogram(s) to be built
+@itemize *
@item
-The source programming language(s)
+@ref{42,,Handling Arbitrary File Naming Conventions with gnatname}
@item
-Source file naming conventions; you can specify these either globally or for
-individual compilation units (see @ref{14b,,Naming Schemes}).
+@ref{4c,,File Name Krunching with gnatkr}
@item
-Change any of the above settings depending on external values, thus enabling
-the reuse of the projects in various @strong{scenarios} (see @ref{14c,,Scenarios in Projects}).
+@ref{1d,,Renaming Files with gnatchop}
@item
-Automatically build libraries as part of the build process
-(see @ref{8a,,Library Projects}).
+@ref{8f,,Preprocessing with gnatprep}
@end itemize
-Project files are written in a syntax close to that of Ada, using familiar
-notions such as packages, context clauses, declarations, default values,
-assignments, and inheritance (see @ref{14d,,Project File Reference}).
+@menu
+* The File Cleanup Utility gnatclean::
+* The GNAT Library Browser gnatls::
-Project files can be built hierarchically from other project files, simplifying
-complex system integration and project reuse (see @ref{14e,,Organizing Projects into Subsystems}).
+@end menu
+@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs
+@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}
-@itemize *
-@item
-One project can import other projects containing needed source files.
-More generally, the Project Manager lets you structure large development
-efforts into hierarchical subsystems, where build decisions are delegated
-to the subsystem level, and thus different compilation environments
-(switch settings) used for different subsystems.
+@geindex File cleanup tool
-@item
-You can organize GNAT projects in a hierarchy: a child project
-can extend a parent project, inheriting the parent's source files and
-optionally overriding any of them with alternative versions
-(see @ref{14f,,Project Extension}).
-@end itemize
+@geindex gnatclean
-Several tools support project files, generally in addition to specifying
-the information on the command line itself). They share common switches
-to control the loading of the project (in particular
-@code{-P@emph{projectfile}} and
-@code{-X@emph{vbl}=@emph{value}}).
+@code{gnatclean} is a tool that allows the deletion of files produced by the
+compiler, binder and linker, including ALI files, object files, tree files,
+expanded source files, library files, interface copy source files, binder
+generated files and executable files.
-The Project Manager supports a wide range of development strategies,
-for systems of all sizes. Here are some typical practices that are
-easily handled:
+@menu
+* Running gnatclean::
+* Switches for gnatclean::
+@end menu
-@itemize *
+@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean
+@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{139}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{13a}
+@subsection Running @code{gnatclean}
-@item
-Using a common set of source files and generating object files in different
-directories via different switch settings. It can be used for instance, for
-generating separate sets of object files for debugging and for production.
-@item
-Using a mostly-shared set of source files with different versions of
-some units or subunits. It can be used for instance, for grouping and hiding
-all OS dependencies in a small number of implementation units.
-@end itemize
+The @code{gnatclean} command has the form:
+
+@quotation
+
+@example
+$ gnatclean switches names
+@end example
+@end quotation
-Project files can be used to achieve some of the effects of a source
-versioning system (for example, defining separate projects for
-the different sets of sources that comprise different releases) but the
-Project Manager is independent of any source configuration management tool
-that might be used by the developers.
+where @code{names} is a list of source file names. Suffixes @code{.ads} and
+@code{adb} may be omitted. If a project file is specified using switch
+@code{-P}, then @code{names} may be completely omitted.
-The various sections below introduce the different concepts related to
-projects. Each section starts with examples and use cases, and then goes into
-the details of related project file capabilities.
+In normal mode, @code{gnatclean} delete the files produced by the compiler and,
+if switch @code{-c} is not specified, by the binder and
+the linker. In informative-only mode, specified by switch
+@code{-n}, the list of files that would have been deleted in
+normal mode is listed, but no file is actually deleted.
-@node Building With Projects,Organizing Projects into Subsystems,Introduction,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager building-with-projects}@anchor{150}@anchor{gnat_ugn/gnat_project_manager id2}@anchor{151}
-@section Building With Projects
+@node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean
+@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}
-In its simplest form, a unique project is used to build a single executable.
-This section concentrates on such a simple setup. Later sections will extend
-this basic model to more complex setups.
+@code{gnatclean} recognizes the following switches:
-The following concepts are the foundation of project files, and will be further
-detailed later in this documentation. They are summarized here as a reference.
+@geindex --version (gnatclean)
@table @asis
-@item @strong{Project file}:
+@item @code{--version}
+
+Display copyright and version, then exit disregarding all other options.
+@end table
+
+@geindex --help (gnatclean)
+
+
+@table @asis
-A text file using an Ada-like syntax, generally using the @code{.gpr}
-extension. It defines build-related characteristics of an application.
-The characteristics include the list of sources, the location of those
-sources, the location for the generated object files, the name of
-the main program, and the options for the various tools involved in the
-build process.
+@item @code{--help}
-@item @strong{Project attribute}:
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
-A specific project characteristic is defined by an attribute clause. Its
-value is a string or a sequence of strings. All settings in a project
-are defined through a list of predefined attributes with precise
-semantics. See @ref{152,,Attributes}.
+@item @code{--subdirs=@emph{subdir}}
-@item @strong{Package in a project}:
+Actual object directory of each project file is the subdirectory subdir of the
+object directory specified or defaulted in the project file.
-Global attributes are defined at the top level of a project.
-Attributes affecting specific tools are grouped in a
-package whose name is related to tool's function. The most common
-packages are @cite{Builder}, @cite{Compiler}, @cite{Binder},
-and @cite{Linker}. See @ref{153,,Packages}.
+@item @code{--unchecked-shared-lib-imports}
-@item @strong{Project variables}:
+By default, shared library projects are not allowed to import static library
+projects. When this switch is used on the command line, this restriction is
+relaxed.
+@end table
-In addition to attributes, a project can use variables to store intermediate
-values and avoid duplication in complex expressions. It can be initialized
-with a value coming from the environment.
-A frequent use of variables is to define scenarios.
-See @ref{154,,External Values}, @ref{14c,,Scenarios in Projects}, and @ref{155,,Variables}.
+@geindex -c (gnatclean)
-@item @strong{Source files} and @strong{source directories}:
-A source file is associated with a language through a naming convention. For
-instance, @cite{foo.c} is typically the name of a C source file;
-@cite{bar.ads} or @cite{bar.1.ada} are two common naming conventions for a
-file containing an Ada spec. A compilation unit is often composed of a main
-source file and potentially several auxiliary ones, such as header files in C.
-The naming conventions can be user defined @ref{14b,,Naming Schemes}, and will
-drive the builder to call the appropriate compiler for the given source file.
-Source files are searched for in the source directories associated with the
-project through the @strong{Source_Dirs} attribute. By default, all the files (in
-these source directories) following the naming conventions associated with the
-declared languages are considered to be part of the project. It is also
-possible to limit the list of source files using the @strong{Source_Files} or
-@strong{Source_List_File} attributes. Note that those last two attributes only
-accept basenames with no directory information.
+@table @asis
-@item @strong{Object files} and @strong{object directory}:
+@item @code{-c}
-An object file is an intermediate file produced by the compiler from a
-compilation unit. It is used by post-compilation tools to produce
-final executables or libraries. Object files produced in the context of
-a given project are stored in a single directory that can be specified by the
-@strong{Object_Dir} attribute. In order to store objects in
-two or more object directories, the system must be split into
-distinct subsystems with their own project file.
+Only attempt to delete the files produced by the compiler, not those produced
+by the binder or the linker. The files that are not to be deleted are library
+files, interface copy files, binder generated files and executable files.
@end table
-The following subsections introduce gradually all the attributes of interest
-for simple build needs. Here is the simple setup that will be used in the
-following examples.
+@geindex -D (gnatclean)
-The Ada source files @code{pack.ads}, @code{pack.adb}, and @code{proc.adb} are in
-the @code{common/} directory. The file @code{proc.adb} contains an Ada main
-subprogram @cite{Proc} that @emph{with}s package @cite{Pack}. We want to compile
-these source files with the switch
-@emph{-O2}, and put the resulting files in
-the directory @code{obj/}.
-@example
-common/
- pack.ads
- pack.adb
- proc.adb
-common/obj/
- proc.ali, proc.o pack.ali, pack.o
-@end example
+@table @asis
-Our project is to be called @emph{Build}. The name of the
-file is the name of the project (case-insensitive) with the
-@code{.gpr} extension, therefore the project file name is @code{build.gpr}. This
-is not mandatory, but a warning is issued when this convention is not followed.
+@item @code{-D @emph{dir}}
-This is a very simple example, and as stated above, a single project
-file is enough for it. We will thus create a new file, that for now
-should contain the following code:
+Indicate that ALI and object files should normally be found in directory @code{dir}.
+@end table
-@example
-project Build is
-end Build;
-@end example
+@geindex -F (gnatclean)
-@menu
-* Source Files and Directories::
-* Duplicate Sources in Projects::
-* Object and Exec Directory::
-* Main Subprograms::
-* Tools Options in Project Files::
-* Compiling with Project Files::
-* Executable File Names::
-* Avoid Duplication With Variables::
-* Naming Schemes::
-* Installation::
-* Distributed support::
-@end menu
+@table @asis
-@node Source Files and Directories,Duplicate Sources in Projects,,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager id3}@anchor{156}@anchor{gnat_ugn/gnat_project_manager source-files-and-directories}@anchor{157}
-@subsection Source Files and Directories
+@item @code{-F}
+When using project files, if some errors or warnings are detected during
+parsing and verbose mode is not in effect (no use of switch
+-v), then error lines start with the full path name of the project
+file, rather than its simple file name.
+@end table
-When you create a new project, the first thing to describe is how to find the
-corresponding source files. These are the only settings that are needed by all
-the tools that will use this project (builder, compiler, binder and linker for
-the compilation, IDEs to edit the source files,...).
+@geindex -h (gnatclean)
-@geindex Source directories (GNAT Project Manager)
-The first step is to declare the source directories, which are the directories
-to be searched to find source files. In the case of the example,
-the @code{common} directory is the only source directory.
+@table @asis
-@geindex Source_Dirs (GNAT Project Manager)
+@item @code{-h}
-There are several ways of defining source directories:
+Output a message explaining the usage of @code{gnatclean}.
+@end table
+@geindex -n (gnatclean)
-@itemize *
-@item
-When the attribute @strong{Source_Dirs} is not used, a project contains a
-single source directory which is the one where the project file itself
-resides. In our example, if @code{build.gpr} is placed in the @code{common}
-directory, the project has the needed implicit source directory.
+@table @asis
-@item
-The attribute @strong{Source_Dirs} can be set to a list of path names, one
-for each of the source directories. Such paths can either be absolute
-names (for instance @code{"/usr/local/common/"} on UNIX), or relative to the
-directory in which the project file resides (for instance "." if
-@code{build.gpr} is inside @code{common/}, or "common" if it is one level up).
-Each of the source directories must exist and be readable.
+@item @code{-n}
-@geindex portability of path names (GNAT Project Manager)
+Informative-only mode. Do not delete any files. Output the list of the files
+that would have been deleted if this switch was not specified.
+@end table
-The syntax for directories is platform specific. For portability, however,
-the project manager will always properly translate UNIX-like path names to
-the native format of the specific platform. For instance, when the same
-project file is to be used both on Unix and Windows, "/" should be used as
-the directory separator rather than "\".
+@geindex -P (gnatclean)
-@item
-The attribute @strong{Source_Dirs} can automatically include subdirectories
-using a special syntax inspired by some UNIX shells. If any of the paths in
-the list ends with "@code{**}", then that path and all its subdirectories
-(recursively) are included in the list of source directories. For instance,
-@code{**} and @code{./**} represent the complete directory tree rooted at
-the directory in which the project file resides.
-@geindex Source directories (GNAT Project Manager)
+@table @asis
-@geindex Excluded_Source_Dirs (GNAT Project Manager)
+@item @code{-P@emph{project}}
-When using that construct, it can sometimes be convenient to also use the
-attribute @strong{Excluded_Source_Dirs}, which is also a list of paths. Each entry
-specifies a directory whose immediate content, not including subdirs, is to
-be excluded. It is also possible to exclude a complete directory subtree
-using the "**" notation.
+Use project file @code{project}. Only one such switch can be used.
+When cleaning a project file, the files produced by the compilation of the
+immediate sources or inherited sources of the project files are to be
+deleted. This is not depending on the presence or not of executable names
+on the command line.
+@end table
-@geindex Ignore_Source_Sub_Dirs (GNAT Project Manager)
+@geindex -q (gnatclean)
-It is often desirable to remove, from the source directories, directory
-subtrees rooted at some subdirectories. An example is the subdirectories
-created by a Version Control System such as Subversion that creates directory
-subtrees rooted at subdirectories ".svn". To do that, attribute
-@strong{Ignore_Source_Sub_Dirs} can be used. It specifies the list of simple
-file names for the roots of these undesirable directory subtrees.
-@example
-for Source_Dirs use ("./**");
-for Ignore_Source_Sub_Dirs use (".svn");
-@end example
-@end itemize
+@table @asis
-When applied to the simple example, and because we generally prefer to have
-the project file at the toplevel directory rather than mixed with the sources,
-we will create the following file
+@item @code{-q}
-@example
-build.gpr
-project Build is
- for Source_Dirs use ("common"); -- <<<<
-end Build;
-@end example
+Quiet output. If there are no errors, do not output anything, except in
+verbose mode (switch -v) or in informative-only mode
+(switch -n).
+@end table
-Once source directories have been specified, one may need to indicate
-source files of interest. By default, all source files present in the source
-directories are considered by the project manager. When this is not desired,
-it is possible to specify the list of sources to consider explicitly.
-In such a case, only source file base names are indicated and not
-their absolute or relative path names. The project manager is in charge of
-locating the specified source files in the specified source directories.
+@geindex -r (gnatclean)
-@itemize *
+@table @asis
-@item
-By default, the project manager searches for all source files of all
-specified languages in all the source directories.
+@item @code{-r}
+
+When a project file is specified (using switch -P),
+clean all imported and extended project files, recursively. If this switch
+is not specified, only the files related to the main project file are to be
+deleted. This switch has no effect if no project file is specified.
+@end table
-Since the project manager was initially developed for Ada environments, the
-default language is usually Ada and the above project file is complete: it
-defines without ambiguity the sources composing the project: that is to say,
-all the sources in subdirectory "common" for the default language (Ada) using
-the default naming convention.
+@geindex -v (gnatclean)
-@geindex Languages (GNAT Project Manager)
-However, when compiling a multi-language application, or a pure C
-application, the project manager must be told which languages are of
-interest, which is done by setting the @strong{Languages} attribute to a list of
-strings, each of which is the name of a language.
+@table @asis
-@geindex Naming scheme (GNAT Project Manager)
+@item @code{-v}
-Even when using only Ada, the default naming might not be suitable. Indeed,
-how does the project manager recognizes an "Ada file" from any other
-file? Project files can describe the naming scheme used for source files,
-and override the default (see @ref{14b,,Naming Schemes}). The default is the
-standard GNAT extension (@code{.adb} for bodies and @code{.ads} for
-specs), which is what is used in our example, explaining why no naming scheme
-is explicitly specified.
-See @ref{14b,,Naming Schemes}.
+Verbose mode.
+@end table
-@geindex Source_Files (GNAT Project Manager)
+@geindex -vP (gnatclean)
-@item
-@cite{Source_Files}.
-In some cases, source directories might contain files that should not be
-included in a project. One can specify the explicit list of file names to
-be considered through the @strong{Source_Files} attribute.
-When this attribute is defined, instead of looking at every file in the
-source directories, the project manager takes only those names into
-consideration reports errors if they cannot be found in the source
-directories or does not correspond to the naming scheme.
-@item
-For various reasons, it is sometimes useful to have a project with no
-sources (most of the time because the attributes defined in the project
-file will be reused in other projects, as explained in
-@ref{14e,,Organizing Projects into Subsystems}. To do this, the attribute
-@emph{Source_Files} is set to the empty list, i.e. @cite{()}. Alternatively,
-@emph{Source_Dirs} can be set to the empty list, with the same
-result.
+@table @asis
-@geindex Source_List_File (GNAT Project Manager)
+@item @code{-vP@emph{x}}
-@item
-@cite{Source_List_File}.
-If there is a great number of files, it might be more convenient to use
-the attribute @strong{Source_List_File}, which specifies the full path of a file.
-This file must contain a list of source file names (one per line, no
-directory information) that are searched as if they had been defined
-through @emph{Source_Files}. Such a file can easily be created through
-external tools.
+Indicates the verbosity of the parsing of GNAT project files.
+@ref{cf,,Switches Related to Project Files}.
+@end table
-A warning is issued if both attributes @cite{Source_Files} and
-@cite{Source_List_File} are given explicit values. In this case, the
-attribute @cite{Source_Files} prevails.
+@geindex -X (gnatclean)
-@geindex Excluded_Source_Files (GNAT Project Manager)
-@geindex Locally_Removed_Files (GNAT Project Manager)
+@table @asis
-@geindex Excluded_Source_List_File (GNAT Project Manager)
+@item @code{-X@emph{name}=@emph{value}}
-@item
-@cite{Excluded_Source_Files}.
-Specifying an explicit list of files is not always convenient.It might be
-more convenient to use the default search rules with specific exceptions.
-This can be done thanks to the attribute @strong{Excluded_Source_Files}
-(or its synonym @strong{Locally_Removed_Files}).
-Its value is the list of file names that should not be taken into account.
-This attribute is often used when extending a project,
-see @ref{14f,,Project Extension}. A similar attribute
-@strong{Excluded_Source_List_File} plays the same
-role but takes the name of file containing file names similarly to
-@cite{Source_List_File}.
-@end itemize
+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{cf,,Switches Related to Project Files}.
+@end table
+
+@geindex -aO (gnatclean)
-In most simple cases, such as the above example, the default source file search
-behavior provides the expected result, and we do not need to add anything after
-setting @cite{Source_Dirs}. The project manager automatically finds
-@code{pack.ads}, @code{pack.adb}, and @code{proc.adb} as source files of the
-project.
-Note that by default a warning is issued when a project has no sources attached
-to it and this is not explicitly indicated in the project file.
+@table @asis
-@node Duplicate Sources in Projects,Object and Exec Directory,Source Files and Directories,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager duplicate-sources-in-projects}@anchor{158}@anchor{gnat_ugn/gnat_project_manager id4}@anchor{159}
-@subsection Duplicate Sources in Projects
+@item @code{-aO@emph{dir}}
+When searching for ALI and object files, look in directory @code{dir}.
+@end table
-If the order of the source directories is known statically, that is if
-@cite{"/**"} is not used in the string list @cite{Source_Dirs}, then there may
-be several files with the same name sitting in different directories of the
-project. In this case, only the file in the first directory is considered as a
-source of the project and the others are hidden. If @cite{"/**"} is used in the
-string list @cite{Source_Dirs}, it is an error to have several files with the
-same name in the same directory @cite{"/**"} subtree, since there would be an
-ambiguity as to which one should be used. However, two files with the same name
-may exist in two single directories or directory subtrees. In this case, the
-one in the first directory or directory subtree is a source of the project.
+@geindex -I (gnatclean)
-If there are two sources in different directories of the same @cite{"/**"}
-subtree, one way to resolve the problem is to exclude the directory of the
-file that should not be used as a source of the project.
-@node Object and Exec Directory,Main Subprograms,Duplicate Sources in Projects,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager object-and-exec-directory}@anchor{15a}@anchor{gnat_ugn/gnat_project_manager id5}@anchor{15b}
-@subsection Object and Exec Directory
+@table @asis
+@item @code{-I@emph{dir}}
-The next step when writing a project is to indicate where the compiler should
-put the object files. In fact, the compiler and other tools might create
-several different kind of files (for GNAT, there is the object file and the ALI
-file for instance). One of the important concepts in projects is that most
-tools may consider source directories as read-only and do not attempt to create
-new or temporary files there. Instead, all files are created in the object
-directory. It is of course not true for project-aware IDEs, whose purpose it is
-to create the source files.
+Equivalent to @code{-aO@emph{dir}}.
+@end table
-@geindex Object_Dir (GNAT Project Manager)
+@geindex -I- (gnatclean)
-The object directory is specified through the @strong{Object_Dir} attribute.
-Its value is the path to the object directory, either absolute or
-relative to the directory containing the project file. This
-directory must already exist and be readable and writable, although
-some tools have a switch to create the directory if needed (See
-the switch @cite{-p} for @emph{gprbuild}).
+@geindex Source files
+@geindex suppressing search
-If the attribute @cite{Object_Dir} is not specified, it defaults to
-the project directory, that is the directory containing the project file.
-For our example, we can specify the object dir in this way:
+@table @asis
-@example
-project Build is
- for Source_Dirs use ("common");
- for Object_Dir use "obj"; -- <<<<
-end Build;
-@end example
+@item @code{-I-}
-As mentioned earlier, there is a single object directory per project. As a
-result, if you have an existing system where the object files are spread across
-several directories, you can either move all of them into the same directory if
-you want to build it with a single project file, or study the section on
-subsystems (see @ref{14e,,Organizing Projects into Subsystems}) to see how each
-separate object directory can be associated with one of the subsystems
-constituting the application.
+Do not look for ALI or object files in the directory
+where @code{gnatclean} was invoked.
+@end table
-When the @emph{linker} is called, it usually creates an executable. By
-default, this executable is placed in the object directory of the project. It
-might be convenient to store it in its own directory.
+@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}
-@geindex Exec_Dir (GNAT Project Manager)
-This can be done through the @cite{Exec_Dir} attribute, which, like
-@emph{Object_Dir} contains a single absolute or relative path and must point to
-an existing and writable directory, unless you ask the tool to create it on
-your behalf. When not specified, It defaults to the object directory and
-therefore to the project file's directory if neither @emph{Object_Dir} nor
-@emph{Exec_Dir} was specified.
+@geindex Library browser
-In the case of the example, let's place the executable in the root
-of the hierarchy, ie the same directory as @code{build.gpr}. Hence
-the project file is now
+@geindex gnatls
-@example
-project Build is
- for Source_Dirs use ("common");
- for Object_Dir use "obj";
- for Exec_Dir use "."; -- <<<<
-end Build;
-@end example
+@code{gnatls} is a tool that outputs information about compiled
+units. It gives the relationship between objects, unit names and source
+files. It can also be used to check the source dependencies of a unit
+as well as various characteristics.
-@node Main Subprograms,Tools Options in Project Files,Object and Exec Directory,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager id6}@anchor{15c}@anchor{gnat_ugn/gnat_project_manager main-subprograms}@anchor{15d}
-@subsection Main Subprograms
+@menu
+* Running gnatls::
+* Switches for gnatls::
+* Example of gnatls Usage::
+@end menu
-In the previous section, executables were mentioned. The project manager needs
-to be taught what they are. In a project file, an executable is indicated by
-pointing to the source file of a main subprogram. In C this is the file that
-contains the @cite{main} function, and in Ada the file that contains the main
-unit.
+@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls
+@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{13e}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{13f}
+@subsection Running @code{gnatls}
-There can be any number of such main files within a given project, and thus
-several executables can be built in the context of a single project file. Of
-course, one given executable might not (and in fact will not) need all the
-source files referenced by the project. As opposed to other build environments
-such as @emph{makefile}, one does not need to specify the list of
-dependencies of each executable, the project-aware builder knows enough of the
-semantics of the languages to build and link only the necessary elements.
-@geindex Main (GNAT Project Manager)
+The @code{gnatls} command has the form
-The list of main files is specified via the @strong{Main} attribute. It contains
-a list of file names (no directories). If a project defines this
-attribute, it is not necessary to identify main files on the
-command line when invoking a builder, and editors like
-@emph{GPS} will be able to create extra menus to spawn or debug the
-corresponding executables.
+@quotation
@example
-project Build is
- for Source_Dirs use ("common");
- for Object_Dir use "obj";
- for Exec_Dir use ".";
- for Main use ("proc.adb"); -- <<<<
-end Build;
+$ gnatls switches object_or_ali_file
@end example
+@end quotation
+
+The main argument is the list of object or @code{ali} files
+(see @ref{28,,The Ada Library Information Files})
+for which information is requested.
+
+In normal mode, without additional option, @code{gnatls} produces a
+four-column listing. Each line represents information for a specific
+object. The first column gives the full path of the object, the second
+column gives the name of the principal unit in this object, the third
+column gives the status of the source and the fourth column gives the
+full path of the source representing this unit.
+Here is a simple example of use:
-If this attribute is defined in the project, then spawning the builder
-with a command such as
+@quotation
@example
-gprbuild -Pbuild
+$ gnatls *.o
+./demo1.o demo1 DIF demo1.adb
+./demo2.o demo2 OK demo2.adb
+./hello.o h1 OK hello.adb
+./instr-child.o instr.child MOK instr-child.adb
+./instr.o instr OK instr.adb
+./tef.o tef DIF tef.adb
+./text_io_example.o text_io_example OK text_io_example.adb
+./tgef.o tgef DIF tgef.adb
@end example
+@end quotation
-automatically builds all the executables corresponding to the files
-listed in the @emph{Main} attribute. It is possible to specify one
-or more executables on the command line to build a subset of them.
+The first line can be interpreted as follows: the main unit which is
+contained in
+object file @code{demo1.o} is demo1, whose main source is in
+@code{demo1.adb}. Furthermore, the version of the source used for the
+compilation of demo1 has been modified (DIF). Each source file has a status
+qualifier which can be:
-@node Tools Options in Project Files,Compiling with Project Files,Main Subprograms,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager tools-options-in-project-files}@anchor{15e}@anchor{gnat_ugn/gnat_project_manager id7}@anchor{15f}
-@subsection Tools Options in Project Files
+@table @asis
-We now have a project file that fully describes our environment, and can be
-used to build the application with a simple @emph{gprbuild} command as seen
-in the previous section. In fact, the empty project we showed immediately at
-the beginning (with no attribute at all) could already fulfill that need if it
-was put in the @code{common} directory.
+@item @emph{OK (unchanged)}
-Of course, we might want more control. This section shows you how to specify
-the compilation switches that the various tools involved in the building of the
-executable should use.
+The version of the source file used for the compilation of the
+specified unit corresponds exactly to the actual source file.
-@geindex command line length (GNAT Project Manager)
+@item @emph{MOK (slightly modified)}
-Since source names and locations are described in the project file, it is not
-necessary to use switches on the command line for this purpose (switches such
-as -I for gcc). This removes a major source of command line length overflow.
-Clearly, the builders will have to communicate this information one way or
-another to the underlying compilers and tools they call but they usually use
-response files for this and thus are not subject to command line overflows.
+The version of the source file used for the compilation of the
+specified unit differs from the actual source file but not enough to
+require recompilation. If you use gnatmake with the option
+@code{-m} (minimal recompilation), a file marked
+MOK will not be recompiled.
-Several tools participate to the creation of an executable: the compiler
-produces object files from the source files; the binder (in the Ada case)
-creates a "source" file that takes care, among other things, of elaboration
-issues and global variable initialization; and the linker gathers everything
-into a single executable that users can execute. All these tools are known to
-the project manager and will be called with user defined switches from the
-project files. However, we need to introduce a new project file concept to
-express the switches to be used for any of the tools involved in the build.
+@item @emph{DIF (modified)}
-@geindex project file packages (GNAT Project Manager)
+No version of the source found on the path corresponds to the source
+used to build this object.
-A project file is subdivided into zero or more @strong{packages}, each of which
-contains the attributes specific to one tool (or one set of tools). Project
-files use an Ada-like syntax for packages. Package names permitted in project
-files are restricted to a predefined set (see @ref{153,,Packages}), and the contents
-of packages are limited to a small set of constructs and attributes
-(see @ref{152,,Attributes}).
+@item @emph{??? (file not found)}
-Our example project file can be extended with the following empty packages. At
-this stage, they could all be omitted since they are empty, but they show which
-packages would be involved in the build process.
+No source file was found for this unit.
-@example
-project Build is
- for Source_Dirs use ("common");
- for Object_Dir use "obj";
- for Exec_Dir use ".";
- for Main use ("proc.adb");
+@item @emph{HID (hidden, unchanged version not first on PATH)}
- package Builder is --<<< for gprbuild
- end Builder;
+The version of the source that corresponds exactly to the source used
+for compilation has been found on the path but it is hidden by another
+version of the same source that has been modified.
+@end table
- package Compiler is --<<< for the compiler
- end Compiler;
+@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls
+@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}
- package Binder is --<<< for the binder
- end Binder;
- package Linker is --<<< for the linker
- end Linker;
-end Build;
-@end example
+@code{gnatls} recognizes the following switches:
-Let's first examine the compiler switches. As stated in the initial description
-of the example, we want to compile all files with @emph{-O2}. This is a
-compiler switch, although it is usual, on the command line, to pass it to the
-builder which then passes it to the compiler. It is recommended to use directly
-the right package, which will make the setup easier to understand for other
-people.
+@geindex --version (gnatls)
-Several attributes can be used to specify the switches:
-@geindex Default_Switches (GNAT Project Manager)
+@table @asis
-@strong{Default_Switches}:
+@item @code{--version}
-@quotation
+Display copyright and version, then exit disregarding all other options.
+@end table
-This is the first mention in this manual of an @strong{indexed attribute}. When
-this attribute is defined, one must supply an @emph{index} in the form of a
-literal string.
-In the case of @emph{Default_Switches}, the index is the name of the
-language to which the switches apply (since a different compiler will
-likely be used for each language, and each compiler has its own set of
-switches). The value of the attribute is a list of switches.
+@geindex --help (gnatls)
-In this example, we want to compile all Ada source files with the switch
-@emph{-O2}, and the resulting project file is as follows
-(only the @cite{Compiler} package is shown):
-@example
-package Compiler is
- for Default_Switches ("Ada") use ("-O2");
-end Compiler;
-@end example
-@end quotation
+@table @asis
-@geindex Switches (GNAT Project Manager)
+@item @code{--help}
-@strong{Switches}:
+If @code{--version} was not used, display usage, then exit disregarding
+all other options.
+@end table
-@quotation
+@geindex -a (gnatls)
-In some cases, we might want to use specific switches
-for one or more files. For instance, compiling @code{proc.adb} might not be
-possible at high level of optimization because of a compiler issue.
-In such a case, the @emph{Switches}
-attribute (indexed on the file name) can be used and will override the
-switches defined by @emph{Default_Switches}. Our project file would
-become:
-@example
-package Compiler is
- for Default_Switches ("Ada")
- use ("-O2");
- for Switches ("proc.adb")
- use ("-O0");
-end Compiler;
-@end example
+@table @asis
-@cite{Switches} may take a pattern as an index, such as in:
+@item @code{-a}
-@example
-package Compiler is
- for Default_Switches ("Ada")
- use ("-O2");
- for Switches ("pkg*")
- use ("-O0");
-end Compiler;
-@end example
+Consider all units, including those of the predefined Ada library.
+Especially useful with @code{-d}.
+@end table
-Sources @code{pkg.adb} and @code{pkg-child.adb} would be compiled with -O0,
-not -O2.
+@geindex -d (gnatls)
-@cite{Switches} can also be given a language name as index instead of a file
-name in which case it has the same semantics as @emph{Default_Switches}.
-However, indexes with wild cards are never valid for language name.
-@end quotation
-@geindex Local_Configuration_Pragmas (GNAT Project Manager)
+@table @asis
-@strong{Local_Configuration_Pragmas}:
+@item @code{-d}
-@quotation
+List sources from which specified units depend on.
+@end table
-This attribute may specify the path
-of a file containing configuration pragmas for use by the Ada compiler,
-such as @cite{pragma Restrictions (No_Tasking)}. These pragmas will be
-used for all the sources of the project.
-@end quotation
+@geindex -h (gnatls)
-The switches for the other tools are defined in a similar manner through the
-@strong{Default_Switches} and @strong{Switches} attributes, respectively in the
-@emph{Builder} package (for @emph{gprbuild}),
-the @emph{Binder} package (binding Ada executables) and the @emph{Linker}
-package (for linking executables).
-@node Compiling with Project Files,Executable File Names,Tools Options in Project Files,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager compiling-with-project-files}@anchor{160}@anchor{gnat_ugn/gnat_project_manager id8}@anchor{161}
-@subsection Compiling with Project Files
+@table @asis
+@item @code{-h}
-Now that our project files are written, let's build our executable.
-Here is the command we would use from the command line:
+Output the list of options.
+@end table
-@example
-gprbuild -Pbuild
-@end example
+@geindex -o (gnatls)
-This will automatically build the executables specified through the
-@emph{Main} attribute: for each, it will compile or recompile the
-sources for which the object file does not exist or is not up-to-date; it
-will then run the binder; and finally run the linker to create the
-executable itself.
-The @emph{gprbuild} builder, can automatically manage C files the
-same way: create the file @code{utils.c} in the @code{common} directory,
-set the attribute @emph{Languages} to @cite{"(Ada@comma{} C)"}, and re-run
+@table @asis
-@example
-gprbuild -Pbuild
-@end example
+@item @code{-o}
-Gprbuild knows how to recompile the C files and will
-recompile them only if one of their dependencies has changed. No direct
-indication on how to build the various elements is given in the
-project file, which describes the project properties rather than a
-set of actions to be executed. Here is the invocation of
-@emph{gprbuild} when building a multi-language program:
+Only output information about object files.
+@end table
-@example
-$ gprbuild -Pbuild
-gcc -c proc.adb
-gcc -c pack.adb
-gcc -c utils.c
-gprbind proc
-...
-gcc proc.o -o proc
-@end example
+@geindex -s (gnatls)
-Notice the three steps described earlier:
+@table @asis
-@itemize *
-
-@item
-The first three gcc commands correspond to the compilation phase.
-
-@item
-The gprbind command corresponds to the post-compilation phase.
-
-@item
-The last gcc command corresponds to the final link.
-@end itemize
-
-@geindex -v option (for GPRbuild)
-
-The default output of GPRbuild's execution is kept reasonably simple and easy
-to understand. In particular, some of the less frequently used commands are not
-shown, and some parameters are abbreviated. So it is not possible to rerun the
-effect of the @emph{gprbuild} command by cut-and-pasting its output.
-GPRbuild's option @cite{-v} provides a much more verbose output which includes,
-among other information, more complete compilation, post-compilation and link
-commands.
-
-@node Executable File Names,Avoid Duplication With Variables,Compiling with Project Files,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager executable-file-names}@anchor{162}@anchor{gnat_ugn/gnat_project_manager id9}@anchor{163}
-@subsection Executable File Names
+@item @code{-s}
+Only output information about source files.
+@end table
-@geindex Executable (GNAT Project Manager)
+@geindex -u (gnatls)
-By default, the executable name corresponding to a main file is
-computed from the main source file name. Through the attribute
-@strong{Builder.Executable}, it is possible to change this default.
-For instance, instead of building @emph{proc} (or @emph{proc.exe}
-on Windows), we could configure our project file to build "proc1"
-(resp proc1.exe) with the following addition:
+@table @asis
-@example
-project Build is
- ... -- same as before
- package Builder is
- for Executable ("proc.adb") use "proc1";
- end Builder
-end Build;
-@end example
+@item @code{-u}
-@geindex Executable_Suffix (GNAT Project Manager)
+Only output information about compilation units.
+@end table
-Attribute @strong{Executable_Suffix}, when specified, may change the suffix
-of the executable files, when no attribute @cite{Executable} applies:
-its value replaces the platform-specific executable suffix.
-The default executable suffix is empty on UNIX and ".exe" on Windows.
+@geindex -files (gnatls)
-It is also possible to change the name of the produced executable by using the
-command line switch @emph{-o}. When several mains are defined in the project,
-it is not possible to use the @emph{-o} switch and the only way to change the
-names of the executable is provided by Attributes @cite{Executable} and
-@cite{Executable_Suffix}.
-@node Avoid Duplication With Variables,Naming Schemes,Executable File Names,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager id10}@anchor{164}@anchor{gnat_ugn/gnat_project_manager avoid-duplication-with-variables}@anchor{165}
-@subsection Avoid Duplication With Variables
+@table @asis
+@item @code{-files=@emph{file}}
-To illustrate some other project capabilities, here is a slightly more complex
-project using similar sources and a main program in C:
+Take as arguments the files listed in text file @code{file}.
+Text file @code{file} may contain empty lines that are ignored.
+Each nonempty line should contain the name of an existing file.
+Several such switches may be specified simultaneously.
+@end table
-@example
-project C_Main is
- for Languages use ("Ada", "C");
- for Source_Dirs use ("common");
- for Object_Dir use "obj";
- for Main use ("main.c");
- package Compiler is
- C_Switches := ("-pedantic");
- for Default_Switches ("C") use C_Switches;
- for Default_Switches ("Ada") use ("-gnaty");
- for Switches ("main.c") use C_Switches & ("-g");
- end Compiler;
-end C_Main;
-@end example
+@geindex -aO (gnatls)
-This project has many similarities with the previous one.
-As expected, its @cite{Main} attribute now refers to a C source.
-The attribute @emph{Exec_Dir} is now omitted, thus the resulting
-executable will be put in the directory @code{obj}.
+@geindex -aI (gnatls)
-The most noticeable difference is the use of a variable in the
-@emph{Compiler} package to store settings used in several attributes.
-This avoids text duplication, and eases maintenance (a single place to
-modify if we want to add new switches for C files). We will revisit
-the use of variables in the context of scenarios (see @ref{14c,,Scenarios in Projects}).
+@geindex -I (gnatls)
-In this example, we see how the file @code{main.c} can be compiled with
-the switches used for all the other C files, plus @emph{-g}.
-In this specific situation the use of a variable could have been
-replaced by a reference to the @cite{Default_Switches} attribute:
+@geindex -I- (gnatls)
-@example
-for Switches ("c_main.c") use Compiler'Default_Switches ("C") & ("-g");
-@end example
-Note the tick (@emph{'}) used to refer to attributes defined in a package.
+@table @asis
-Here is the output of the GPRbuild command using this project:
+@item @code{-aO@emph{dir}}, @code{-aI@emph{dir}}, @code{-I@emph{dir}}, @code{-I-}, @code{-nostdinc}
-@example
-$ gprbuild -Pc_main
-gcc -c -pedantic -g main.c
-gcc -c -gnaty proc.adb
-gcc -c -gnaty pack.adb
-gcc -c -pedantic utils.c
-gprbind main.bexch
-...
-gcc main.o -o main
-@end example
+Source path manipulation. Same meaning as the equivalent @code{gnatmake}
+flags (@ref{cd,,Switches for gnatmake}).
+@end table
-The default switches for Ada sources,
-the default switches for C sources (in the compilation of @code{lib.c}),
-and the specific switches for @code{main.c} have all been taken into
-account.
+@geindex -aP (gnatls)
-@node Naming Schemes,Installation,Avoid Duplication With Variables,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager id11}@anchor{166}@anchor{gnat_ugn/gnat_project_manager naming-schemes}@anchor{14b}
-@subsection Naming Schemes
+@table @asis
-Sometimes an Ada software system is ported from one compilation environment to
-another (say GNAT), and the file are not named using the default GNAT
-conventions. Instead of changing all the file names, which for a variety of
-reasons might not be possible, you can define the relevant file naming scheme
-in the @strong{Naming} package of your project file.
+@item @code{-aP@emph{dir}}
-The naming scheme has two distinct goals for the project manager: it
-allows finding of source files when searching in the source
-directories, and given a source file name it makes it possible to guess
-the associated language, and thus the compiler to use.
+Add @code{dir} at the beginning of the project search dir.
+@end table
-Note that the use by the Ada compiler of pragmas Source_File_Name is not
-supported when using project files. You must use the features described in this
-paragraph. You can however specify other configuration pragmas.
+@geindex --RTS (gnatls)
-The following attributes can be defined in package @cite{Naming}:
-@geindex Casing (GNAT Project Manager)
+@table @asis
-@strong{Casing}:
+@item @code{--RTS=@emph{rts-path}}
-@quotation
+Specifies the default location of the runtime library. Same meaning as the
+equivalent @code{gnatmake} flag (@ref{cd,,Switches for gnatmake}).
+@end table
-Its value must be one of @cite{"lowercase"} (the default if
-unspecified), @cite{"uppercase"} or @cite{"mixedcase"}. It describes the
-casing of file names with regards to the Ada unit name. Given an Ada unit
-My_Unit, the file name will respectively be @code{my_unit.adb} (lowercase),
-@code{MY_UNIT.ADB} (uppercase) or @code{My_Unit.adb} (mixedcase).
-On Windows, file names are case insensitive, so this attribute is
-irrelevant.
-@end quotation
+@geindex -v (gnatls)
-@geindex Dot_Replacement (GNAT Project Manager)
-@strong{Dot_Replacement}:
+@table @asis
-@quotation
+@item @code{-v}
-This attribute specifies the string that should replace the "." in unit
-names. Its default value is @cite{"-"} so that a unit
-@cite{Parent.Child} is expected to be found in the file
-@code{parent-child.adb}. The replacement string must satisfy the following
-requirements to avoid ambiguities in the naming scheme:
+Verbose mode. Output the complete source, object and project paths. Do not use
+the default column layout but instead use long format giving as much as
+information possible on each requested units, including special
+characteristics such as:
@itemize *
@item
-It must not be empty
+@emph{Preelaborable}: The unit is preelaborable in the Ada sense.
@item
-It cannot start or end with an alphanumeric character
+@emph{No_Elab_Code}: No elaboration code has been produced by the compiler for this unit.
@item
-It cannot be a single underscore
+@emph{Pure}: The unit is pure in the Ada sense.
@item
-It cannot start with an underscore followed by an alphanumeric
+@emph{Elaborate_Body}: The unit contains a pragma Elaborate_Body.
@item
-It cannot contain a dot @cite{'.'} except if the entire string is @cite{"."}
-@end itemize
-@end quotation
-
-@geindex Spec_Suffix (GNAT Project Manager)
-
-@geindex Specification_Suffix (GNAT Project Manager)
-
-@strong{Spec_Suffix} and @strong{Specification_Suffix}:
-
-@quotation
-
-For Ada, these attributes give the suffix used in file names that contain
-specifications. For other languages, they give the extension for files
-that contain declaration (header files in C for instance). The attribute
-is indexed on the language.
-The two attributes are equivalent, but the latter is obsolescent.
-
-If the value of the attribute is the empty string, it indicates to the
-Project Manager that the only specifications/header files for the language
-are those specified with attributes @cite{Spec} or
-@cite{Specification_Exceptions}.
-
-If @cite{Spec_Suffix ("Ada")} is not specified, then the default is
-@cite{".ads"}.
-
-A non empty value must satisfy the following requirements:
-
+@emph{Remote_Types}: The unit contains a pragma Remote_Types.
-@itemize *
+@item
+@emph{Shared_Passive}: The unit contains a pragma Shared_Passive.
@item
-It must include at least one dot
+@emph{Predefined}: This unit is part of the predefined environment and cannot be modified
+by the user.
@item
-If @cite{Dot_Replacement} is a single dot, then it cannot include
-more than one dot.
+@emph{Remote_Call_Interface}: The unit contains a pragma Remote_Call_Interface.
@end itemize
-@end quotation
+@end table
-@geindex Body_Suffix (GNAT Project Manager)
+@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls
+@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
-@geindex Implementation_Suffix (GNAT Project Manager)
-@strong{Body_Suffix} and @strong{Implementation_Suffix}:
+Example of using the verbose switch. Note how the source and
+object paths are affected by the -I switch.
@quotation
-These attributes give the extension used for file names that contain
-code (bodies in Ada). They are indexed on the language. The second
-version is obsolescent and fully replaced by the first attribute.
-
-For each language of a project, one of these two attributes need to be
-specified, either in the project itself or in the configuration project file.
-
-If the value of the attribute is the empty string, it indicates to the
-Project Manager that the only source files for the language
-are those specified with attributes @cite{Body} or
-@cite{Implementation_Exceptions}.
-
-These attributes must satisfy the same requirements as @cite{Spec_Suffix}.
-In addition, they must be different from any of the values in
-@cite{Spec_Suffix}.
-If @cite{Body_Suffix ("Ada")} is not specified, then the default is
-@cite{".adb"}.
-
-If @cite{Body_Suffix ("Ada")} and @cite{Spec_Suffix ("Ada")} end with the
-same string, then a file name that ends with the longest of these two
-suffixes will be a body if the longest suffix is @cite{Body_Suffix ("Ada")}
-or a spec if the longest suffix is @cite{Spec_Suffix ("Ada")}.
-
-If the suffix does not start with a '.', a file with a name exactly equal to
-the suffix will also be part of the project (for instance if you define the
-suffix as @cite{Makefile.in}, a file called @code{Makefile.in} will be part
-of the project. This capability is usually not interesting when building.
-However, it might become useful when a project is also used to
-find the list of source files in an editor, like the GNAT Programming System
-(GPS).
-@end quotation
-
-@geindex Separate_Suffix (GNAT Project Manager)
+@example
+$ gnatls -v -I.. demo1.o
-@strong{Separate_Suffix}:
+GNATLS 5.03w (20041123-34)
+Copyright 1997-2004 Free Software Foundation, Inc.
-@quotation
+Source Search Path:
+ <Current_Directory>
+ ../
+ /home/comar/local/adainclude/
-This attribute is specific to Ada. It denotes the suffix used in file names
-that contain separate bodies. If it is not specified, then it defaults to
-same value as @cite{Body_Suffix ("Ada")}.
+Object Search Path:
+ <Current_Directory>
+ ../
+ /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
-The value of this attribute cannot be the empty string.
+Project Search Path:
+ <Current_Directory>
+ /home/comar/local/lib/gnat/
-Otherwise, the same rules apply as for the
-@cite{Body_Suffix} attribute. The only accepted index is "Ada".
+./demo1.o
+ Unit =>
+ Name => demo1
+ Kind => subprogram body
+ Flags => No_Elab_Code
+ Source => demo1.adb modified
+@end example
@end quotation
-@strong{Spec} or @strong{Specification}:
+The following is an example of use of the dependency list.
+Note the use of the -s switch
+which gives a straight list of source files. This can be useful for
+building specialized scripts.
@quotation
-@geindex Spec (GNAT Project Manager)
-
-@geindex Specification (GNAT Project Manager)
-
-This attribute @cite{Spec} can be used to define the source file name for a
-given Ada compilation unit's spec. The index is the literal name of the Ada
-unit (case insensitive). The value is the literal base name of the file that
-contains this unit's spec (case sensitive or insensitive depending on the
-operating system). This attribute allows the definition of exceptions to the
-general naming scheme, in case some files do not follow the usual
-convention.
-
-When a source file contains several units, the relative position of the unit
-can be indicated. The first unit in the file is at position 1
-
@example
-for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
-for Spec ("top") use "foo.a" at 1;
-for Spec ("foo") use "foo.a" at 2;
+$ gnatls -d demo2.o
+./demo2.o demo2 OK demo2.adb
+ OK gen_list.ads
+ OK gen_list.adb
+ OK instr.ads
+ OK instr-child.ads
+
+$ gnatls -d -s -a demo1.o
+demo1.adb
+/home/comar/local/adainclude/ada.ads
+/home/comar/local/adainclude/a-finali.ads
+/home/comar/local/adainclude/a-filico.ads
+/home/comar/local/adainclude/a-stream.ads
+/home/comar/local/adainclude/a-tags.ads
+gen_list.ads
+gen_list.adb
+/home/comar/local/adainclude/gnat.ads
+/home/comar/local/adainclude/g-io.ads
+instr.ads
+/home/comar/local/adainclude/system.ads
+/home/comar/local/adainclude/s-exctab.ads
+/home/comar/local/adainclude/s-finimp.ads
+/home/comar/local/adainclude/s-finroo.ads
+/home/comar/local/adainclude/s-secsta.ads
+/home/comar/local/adainclude/s-stalib.ads
+/home/comar/local/adainclude/s-stoele.ads
+/home/comar/local/adainclude/s-stratt.ads
+/home/comar/local/adainclude/s-tasoli.ads
+/home/comar/local/adainclude/s-unstyp.ads
+/home/comar/local/adainclude/unchconv.ads
@end example
@end quotation
-@geindex Body (GNAT Project Manager)
-@geindex Implementation (GNAT Project Manager)
-@strong{Body} or @strong{Implementation}:
-@quotation
-These attribute play the same role as @emph{Spec} for Ada bodies.
-@end quotation
-@geindex Specification_Exceptions (GNAT Project Manager)
-@geindex Implementation_Exceptions (GNAT Project Manager)
-@strong{Specification_Exceptions} and @strong{Implementation_Exceptions}:
+@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
-@quotation
+@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
-These attributes define exceptions to the naming scheme for languages
-other than Ada. They are indexed on the language name, and contain
-a list of file names respectively for headers and source code.
-@end quotation
-For example, the following package models the Apex file naming rules:
+This chapter covers several topics:
-@example
-package Naming is
- for Casing use "lowercase";
- for Dot_Replacement use ".";
- for Spec_Suffix ("Ada") use ".1.ada";
- for Body_Suffix ("Ada") use ".2.ada";
-end Naming;
-@end example
-@node Installation,Distributed support,Naming Schemes,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager id12}@anchor{167}@anchor{gnat_ugn/gnat_project_manager installation}@anchor{168}
-@subsection Installation
+@itemize *
+@item
+@ref{146,,Running and Debugging Ada Programs}
-After building an application or a library it is often required to
-install it into the development environment. For instance this step is
-required if the library is to be used by another application.
-The @emph{gprinstall} tool provides an easy way to install
-libraries, executable or object code generated during the build. The
-@strong{Install} package can be used to change the default locations.
+@item
+@ref{147,,Profiling}
-The following attributes can be defined in package @cite{Install}:
+@item
+@ref{148,,Improving Performance}
-@geindex Active (GNAT Project Manager)
+@item
+@ref{149,,Overflow Check Handling in GNAT}
+@item
+@ref{14a,,Performing Dimensionality Analysis in GNAT}
-@table @asis
+@item
+@ref{14b,,Stack Related Facilities}
-@item @strong{Active}
+@item
+@ref{14c,,Memory Management Issues}
+@end itemize
-Whether the project is to be installed, values are @cite{true}
-(default) or @cite{false}.
-@end table
+@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::
-@geindex Artifacts (GNAT Project Manager)
+@end menu
-@strong{Artifacts}
+@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
-@quotation
-An array attribute to declare a set of files not part of the sources
-to be installed. The array discriminant is the directory where the
-file is to be installed. If a relative directory then Prefix (see
-below) is prepended. Note also that if the same file name occurs
-multiple time in the attribute list, the last one will be the one
-installed.
-@end quotation
+@geindex Debugging
-@geindex Prefix (GNAT Project Manager)
+This section discusses how to debug Ada programs.
-@strong{Prefix}:
+An incorrect Ada program may be handled in three ways by the GNAT compiler:
-@quotation
-Root directory for the installation.
-@end quotation
+@itemize *
-@strong{Exec_Subdir}
+@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.
-@quotation
+@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.
-Subdirectory of @strong{Prefix} where executables are to be
-installed. Default is @strong{bin}.
-@end quotation
+@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
-@strong{Lib_Subdir}
+@geindex Debugger
-@quotation
+@geindex gdb
-Subdirectory of @strong{Prefix} where directory with the library or object
-files is to be installed. Default is @strong{lib}.
-@end quotation
+@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::
-@strong{Sources_Subdir}
+@end menu
-@quotation
+@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
-Subdirectory of @strong{Prefix} where directory with sources is to be
-installed. Default is @strong{include}.
-@end quotation
-@strong{Project_Subdir}
+@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.
-@quotation
+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}.
-Subdirectory of @strong{Prefix} where the generated project file is to be
-installed. Default is @strong{share/gpr}.
-@end quotation
+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.
-@strong{Mode}
+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.
-@quotation
+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.
-The installation mode, it is either @strong{dev} (default) or @strong{usage}.
-See @strong{gprbuild} user's guide for details.
-@end quotation
+However, if the program is run under control of @code{GDB}, the
+debugger is activated. The image of the program is loaded, at which
+point it is ready to run. If a run command is given, then the program
+will run exactly as it would have if @code{GDB} were not present. This
+is a crucial part of the @code{GDB} design philosophy. @code{GDB} is
+entirely non-intrusive until a breakpoint is encountered. If no
+breakpoint is ever hit, the program will run exactly as it would if no
+debugger were present. When a breakpoint is hit, @code{GDB} accesses
+the debugging information and can respond to user commands to inspect
+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{150}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{151}
+@subsection Running GDB
+
+
+This section describes how to initiate the debugger.
-@strong{Install_Name}
+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{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
@quotation
-Specify the name to use for recording the installation. The default is
-the project name without the extension.
+@example
+$ gdb program
+@end example
@end quotation
-@node Distributed support,,Installation,Building With Projects
-@anchor{gnat_ugn/gnat_project_manager id13}@anchor{169}@anchor{gnat_ugn/gnat_project_manager distributed-support}@anchor{16a}
-@subsection Distributed support
+where @code{program} is the name of the executable file. This
+activates the debugger and results in a prompt for debugger commands.
+The simplest command is simply @code{run}, which causes the program to run
+exactly as if the debugger were not present. The following section
+describes some of the additional commands that can be given to @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{152}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{153}
+@subsection Introduction to GDB Commands
-For large projects the compilation time can become a limitation in
-the development cycle. To cope with that, GPRbuild supports
-distributed compilation.
+@code{GDB} contains a large repertoire of commands.
+See @cite{Debugging with GDB} for extensive documentation on the use
+of these commands, together with examples of their use. Furthermore,
+the command @emph{help} invoked from within GDB activates a simple help
+facility which summarizes the available commands and their options.
+In this section we summarize a few of the most commonly
+used commands to give an idea of what @code{GDB} is about. You should create
+a simple program with debugging information and experiment with the use of
+these @code{GDB} commands on the program as you read through the
+following section.
-The following attributes can be defined in package @cite{Remote}:
-@geindex Root_Dir (GNAT Project Manager)
+@itemize *
-@strong{Root_Dir}:
+@item
-@quotation
+@table @asis
-Root directory of the project's sources. The default value is the
-project's directory.
-@end quotation
+@item @code{set args @emph{arguments}}
-@node Organizing Projects into Subsystems,Scenarios in Projects,Building With Projects,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager organizing-projects-into-subsystems}@anchor{14e}@anchor{gnat_ugn/gnat_project_manager id14}@anchor{16b}
-@section Organizing Projects into Subsystems
+The @emph{arguments} list above is a list of arguments to be passed to
+the program on a subsequent run command, just as though the arguments
+had been entered on a normal invocation of the program. The @code{set args}
+command is not needed if the program does not require arguments.
+@end table
+@item
-A @strong{subsystem} is a coherent part of the complete system to be built. It is
-represented by a set of sources and one single object directory. A system can
-be composed of a single subsystem when it is simple as we have seen in the
-first section. Complex systems are usually composed of several interdependent
-subsystems. A subsystem is dependent on another subsystem if knowledge of the
-other one is required to build it, and in particular if visibility on some of
-the sources of this other subsystem is required. Each subsystem is usually
-represented by its own project file.
+@table @asis
-In this section, the previous example is being extended. Let's assume some
-sources of our @cite{Build} project depend on other sources.
-For instance, when building a graphical interface, it is usual to depend upon
-a graphical library toolkit such as GtkAda. Furthermore, we also need
-sources from a logging module we had previously written.
+@item @code{run}
-@menu
-* Project Dependencies::
-* Cyclic Project Dependencies::
-* Sharing Between Projects::
-* Global Attributes::
+The @code{run} command causes execution of the program to start from
+the beginning. If the program is already running, that is to say if
+you are currently positioned at a breakpoint, then a prompt will ask
+for confirmation that you want to abandon the current execution and
+restart.
+@end table
-@end menu
+@item
-@node Project Dependencies,Cyclic Project Dependencies,,Organizing Projects into Subsystems
-@anchor{gnat_ugn/gnat_project_manager project-dependencies}@anchor{16c}@anchor{gnat_ugn/gnat_project_manager id15}@anchor{16d}
-@subsection Project Dependencies
+@table @asis
+@item @code{breakpoint @emph{location}}
-GtkAda comes with its own project file (appropriately called
-@code{gtkada.gpr}), and we will assume we have already built a project
-called @code{logging.gpr} for the logging module. With the information provided
-so far in @code{build.gpr}, building the application would fail with an error
-indicating that the gtkada and logging units that are relied upon by the sources
-of this project cannot be found.
+The breakpoint command sets a breakpoint, that is to say a point at which
+execution will halt and @code{GDB} will await further
+commands. @emph{location} is
+either a line number within a file, given in the format @code{file:linenumber},
+or it is the name of a subprogram. If you request that a breakpoint be set on
+a subprogram that is overloaded, a prompt will ask you to specify on which of
+those subprograms you want to breakpoint. You can also
+specify that all of them should be breakpointed. If the program is run
+and execution encounters the breakpoint, then the program
+stops and @code{GDB} signals that the breakpoint was encountered by
+printing the line of code before which the program is halted.
+@end table
-This is solved by adding the following @strong{with} clauses at the beginning of our
-project:
+@item
-@example
-with "gtkada.gpr";
-with "a/b/logging.gpr";
-project Build is
- ... -- as before
-end Build;
-@end example
+@table @asis
-@geindex Externally_Built (GNAT Project Manager)
+@item @code{catch exception @emph{name}}
-When such a project is compiled, @emph{gprbuild} will automatically check
-the other projects and recompile their sources when needed. It will also
-recompile the sources from @cite{Build} when needed, and finally create the
-executable. In some cases, the implementation units needed to recompile a
-project are not available, or come from some third party and you do not want to
-recompile it yourself. In this case, set the attribute @strong{Externally_Built} to
-"true", indicating to the builder that this project can be assumed to be
-up-to-date, and should not be considered for recompilation. In Ada, if the
-sources of this externally built project were compiled with another version of
-the compiler or with incompatible options, the binder will issue an error.
+This command causes the program execution to stop whenever exception
+@code{name} is raised. If @code{name} is omitted, then the execution is
+suspended when any exception is raised.
+@end table
-The project's @emph{with} clause has several effects. It provides source
-visibility between projects during the compilation process. It also guarantees
-that the necessary object files from @cite{Logging} and @cite{GtkAda} are
-available when linking @cite{Build}.
+@item
-As can be seen in this example, the syntax for importing projects is similar
-to the syntax for importing compilation units in Ada. However, project files
-use literal strings instead of names, and the @emph{with} clause identifies
-project files rather than packages.
+@table @asis
-Each literal string after @emph{with} is the path
-(absolute or relative) to a project file. The @cite{.gpr} extension is
-optional, although we recommend adding it. If no extension is specified,
-and no project file with the @code{.gpr} extension is found, then
-the file is searched for exactly as written in the @emph{with} clause,
-that is with no extension.
+@item @code{print @emph{expression}}
-As mentioned above, the path after a @emph{with} has to be a literal
-string, and you cannot use concatenation, or lookup the value of external
-variables to change the directories from which a project is loaded.
-A solution if you need something like this is to use aggregate projects
-(see @ref{16e,,Aggregate Projects}).
+This will print the value of the given expression. Most simple
+Ada expression formats are properly handled by @code{GDB}, so the expression
+can contain function calls, variables, operators, and attribute references.
+@end table
-@geindex project path (GNAT Project Manager)
+@item
-When a relative path or a base name is used, the
-project files are searched relative to each of the directories in the
-@strong{project path}. This path includes all the directories found with the
-following algorithm, in this order; the first matching file is used:
+@table @asis
+@item @code{continue}
-@itemize *
+Continues execution following a breakpoint, until the next breakpoint or the
+termination of the program.
+@end table
@item
-First, the file is searched relative to the directory that contains the
-current project file.
-@geindex GPR_PROJECT_PATH_FILE (GNAT Project Manager)
+@table @asis
-@geindex GPR_PROJECT_PATH (GNAT Project Manager)
+@item @code{step}
-@geindex ADA_PROJECT_PATH (GNAT Project Manager)
+Executes a single line after a breakpoint. If the next statement
+is a subprogram call, execution continues into (the first statement of)
+the called subprogram.
+@end table
@item
-Then it is searched relative to all the directories specified in the
-environment variables @strong{GPR_PROJECT_PATH_FILE},
-@strong{GPR_PROJECT_PATH} and @strong{ADA_PROJECT_PATH} (in that order) if they exist.
-The value of @strong{GPR_PROJECT_PATH_FILE}, when defined, is the path name of
-a text file that contains project directory path names, one per line.
-@strong{GPR_PROJECT_PATH} and @strong{ADA_PROJECT_PATH}, when defined, contain
-project directory path names separated by directory separators.
-@strong{ADA_PROJECT_PATH} is used for compatibility, it is recommended to
-use @strong{GPR_PROJECT_PATH_FILE} or @strong{GPR_PROJECT_PATH}.
-@item
-Finally, it is searched relative to the default project directories.
-Such directories depend on the tool used. The locations searched in the
-specified order are:
+@table @asis
+@item @code{next}
-@itemize *
+Executes a single line. If this line is a subprogram call, executes and
+returns from the call.
+@end table
@item
-@code{<prefix>/<target>/lib/gnat} if option @emph{--target} is specified
-@item
-@code{<prefix>/<target>/share/gpr} if option @emph{--target} is specified
+@table @asis
-@item
-@code{<prefix>/share/gpr/}
+@item @code{list}
+
+Lists a few lines around the current source location. In practice, it
+is usually more convenient to have a separate edit window open with the
+relevant source file displayed. Successive applications of this command
+print subsequent lines. The command can be given an argument which is a
+line number, in which case it displays a few lines around the specified one.
+@end table
@item
-@code{<prefix>/lib/gnat/}
-@end itemize
-In our example, @code{gtkada.gpr} is found in the predefined directory if
-it was installed at the same root as GNAT.
-@end itemize
+@table @asis
-Some tools also support extending the project path from the command line,
-generally through the @emph{-aP}. You can see the value of the project
-path by using the @emph{gnatls -v} command.
+@item @code{backtrace}
-Any symbolic link will be fully resolved in the directory of the
-importing project file before the imported project file is examined.
+Displays a backtrace of the call chain. This command is typically
+used after a breakpoint has occurred, to examine the sequence of calls that
+leads to the current breakpoint. The display includes one line for each
+activation record (frame) corresponding to an active subprogram.
+@end table
-Any source file in the imported project can be used by the sources of the
-importing project, transitively.
-Thus if @cite{A} imports @cite{B}, which imports @cite{C}, the sources of
-@cite{A} may depend on the sources of @cite{C}, even if @cite{A} does not
-import @cite{C} explicitly. However, this is not recommended, because if
-and when @cite{B} ceases to import @cite{C}, some sources in @cite{A} will
-no longer compile. @emph{gprbuild} has a switch @emph{--no-indirect-imports}
-that will report such indirect dependencies.
+@item
-@cartouche
-@quotation Note
-One very important aspect of a project hierarchy is that
-@strong{a given source can only belong to one project} (otherwise the project manager
-would not know which settings apply to it and when to recompile it). It means
-that different project files do not usually share source directories or
-when they do, they need to specify precisely which project owns which sources
-using attribute @cite{Source_Files} or equivalent. By contrast, 2 projects
-can each own a source with the same base file name as long as they live in
-different directories. The latter is not true for Ada Sources because of the
-correlation between source files and Ada units.
-@end quotation
-@end cartouche
+@table @asis
-@node Cyclic Project Dependencies,Sharing Between Projects,Project Dependencies,Organizing Projects into Subsystems
-@anchor{gnat_ugn/gnat_project_manager id16}@anchor{16f}@anchor{gnat_ugn/gnat_project_manager cyclic-project-dependencies}@anchor{170}
-@subsection Cyclic Project Dependencies
+@item @code{up}
+At a breakpoint, @code{GDB} can display the values of variables local
+to the current frame. The command @code{up} can be used to
+examine the contents of other active frames, by moving the focus up
+the stack, that is to say from callee to caller, one frame at a time.
+@end table
-Cyclic dependencies are mostly forbidden:
-if @cite{A} imports @cite{B} (directly or indirectly) then @cite{B}
-is not allowed to import @cite{A}. However, there are cases when cyclic
-dependencies would be beneficial. For these cases, another form of import
-between projects exists: the @strong{limited with}. A project @cite{A} that
-imports a project @cite{B} with a straight @emph{with} may also be imported,
-directly or indirectly, by @cite{B} through a @cite{limited with}.
+@item
-The difference between straight @emph{with} and @cite{limited with} is that
-the name of a project imported with a @cite{limited with} cannot be used in the
-project importing it. In particular, its packages cannot be renamed and
-its variables cannot be referred to.
+@table @asis
-@example
-with "b.gpr";
-with "c.gpr";
-project A is
- for Exec_Dir use B'Exec_Dir; -- ok
-end A;
+@item @code{down}
-limited with "a.gpr"; -- Cyclic dependency: A -> B -> A
-project B is
- for Exec_Dir use A'Exec_Dir; -- not ok
-end B;
+Moves the focus of @code{GDB} down from the frame currently being
+examined to the frame of its callee (the reverse of the previous command),
+@end table
-with "d.gpr";
-project C is
-end C;
+@item
-limited with "a.gpr"; -- Cyclic dependency: A -> C -> D -> A
-project D is
- for Exec_Dir use A'Exec_Dir; -- not ok
-end D;
-@end example
+@table @asis
-@node Sharing Between Projects,Global Attributes,Cyclic Project Dependencies,Organizing Projects into Subsystems
-@anchor{gnat_ugn/gnat_project_manager sharing-between-projects}@anchor{171}@anchor{gnat_ugn/gnat_project_manager id17}@anchor{172}
-@subsection Sharing Between Projects
+@item @code{frame @emph{n}}
+
+Inspect the frame with the given number. The value 0 denotes the frame
+of the current breakpoint, that is to say the top of the call stack.
+@end table
+@item
-When building an application, it is common to have similar needs in several of
-the projects corresponding to the subsystems under construction. For instance,
-they will all have the same compilation switches.
+@table @asis
-As seen before (see @ref{15e,,Tools Options in Project Files}), setting compilation
-switches for all sources of a subsystem is simple: it is just a matter of
-adding a @cite{Compiler.Default_Switches} attribute to each project files with
-the same value. Of course, that means duplication of data, and both places need
-to be changed in order to recompile the whole application with different
-switches. It can become a real problem if there are many subsystems and thus
-many project files to edit.
+@item @code{kill}
-There are two main approaches to avoiding this duplication:
+Kills the child process in which the program is running under GDB.
+This may be useful for several purposes:
@itemize *
@item
-Since @code{build.gpr} imports @code{logging.gpr}, we could change it
-to reference the attribute in Logging, either through a package renaming,
-or by referencing the attribute. The following example shows both cases:
-
-@example
-project Logging is
- package Compiler is
- for Switches ("Ada")
- use ("-O2");
- end Compiler;
- package Binder is
- for Switches ("Ada")
- use ("-E");
- end Binder;
-end Logging;
-
-with "logging.gpr";
-project Build is
- package Compiler renames Logging.Compiler;
- package Binder is
- for Switches ("Ada") use Logging.Binder'Switches ("Ada");
- end Binder;
-end Build;
-@end example
-
-The solution used for @cite{Compiler} gets the same value for all
-attributes of the package, but you cannot modify anything from the
-package (adding extra switches or some exceptions). The second
-version is more flexible, but more verbose.
-
-If you need to refer to the value of a variable in an imported
-project, rather than an attribute, the syntax is similar but uses
-a "." rather than an apostrophe. For instance:
-
-@example
-with "imported";
-project Main is
- Var1 := Imported.Var;
-end Main;
-@end example
+It allows you to recompile and relink your program, since on many systems
+you cannot regenerate an executable file while it is running in a process.
@item
-The second approach is to define the switches in a third project.
-That project is set up without any sources (so that, as opposed to
-the first example, none of the project plays a special role), and
-will only be used to define the attributes. Such a project is
-typically called @code{shared.gpr}.
+You can run your program outside the debugger, on systems that do not
+permit executing a program outside GDB while breakpoints are set
+within GDB.
-@example
-abstract project Shared is
- for Source_Files use (); -- no sources
- package Compiler is
- for Switches ("Ada")
- use ("-O2");
- end Compiler;
-end Shared;
+@item
+It allows you to debug a core dump rather than a running process.
+@end itemize
+@end table
+@end itemize
-with "shared.gpr";
-project Logging is
- package Compiler renames Shared.Compiler;
-end Logging;
+The above list is a very short introduction to the commands that
+@code{GDB} provides. Important additional capabilities, including conditional
+breakpoints, the ability to execute command sequences on a breakpoint,
+the ability to debug at the machine instruction level and many other
+features are described in detail in @cite{Debugging with GDB}.
+Note that most commands can be abbreviated
+(for example, c for continue, bt for backtrace).
-with "shared.gpr";
-project Build is
- package Compiler renames Shared.Compiler;
-end Build;
-@end example
+@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{154}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{155}
+@subsection Using Ada Expressions
-As for the first example, we could have chosen to set the attributes
-one by one rather than to rename a package. The reason we explicitly
-indicate that @cite{Shared} has no sources is so that it can be created
-in any directory and we are sure it shares no sources with @cite{Build}
-or @cite{Logging}, which of course would be invalid.
-@geindex project qualifier (GNAT Project Manager)
+@geindex Ada expressions (in gdb)
-Note the additional use of the @strong{abstract} qualifier in @code{shared.gpr}.
-This qualifier is optional, but helps convey the message that we do not
-intend this project to have sources (see @ref{173,,Qualified Projects} for
-more qualifiers).
-@end itemize
+@code{GDB} supports a fairly large subset of Ada expression syntax, with some
+extensions. The philosophy behind the design of this subset is
-@node Global Attributes,,Sharing Between Projects,Organizing Projects into Subsystems
-@anchor{gnat_ugn/gnat_project_manager global-attributes}@anchor{174}@anchor{gnat_ugn/gnat_project_manager id18}@anchor{175}
-@subsection Global Attributes
+@quotation
-We have already seen many examples of attributes used to specify a special
-option of one of the tools involved in the build process. Most of those
-attributes are project specific. That it to say, they only affect the invocation
-of tools on the sources of the project where they are defined.
+@itemize *
-There are a few additional attributes that apply to all projects in a
-hierarchy as long as they are defined on the "main" project.
-The main project is the project explicitly mentioned on the command-line.
-The project hierarchy is the "with"-closure of the main project.
+@item
+That @code{GDB} should provide basic literals and access to operations for
+arithmetic, dereferencing, field selection, indexing, and subprogram calls,
+leaving more sophisticated computations to subprograms written into the
+program (which therefore may be called from @code{GDB}).
-Here is a list of commonly used global attributes:
+@item
+That type safety and strict adherence to Ada language restrictions
+are not particularly relevant in a debugging context.
-@geindex Global_Configuration_Pragmas (GNAT Project Manager)
+@item
+That brevity is important to the @code{GDB} user.
+@end itemize
+@end quotation
-@strong{Builder.Global_Configuration_Pragmas}:
+Thus, for brevity, the debugger acts as if there were
+implicit @code{with} and @code{use} clauses in effect for all user-written
+packages, thus making it unnecessary to fully qualify most names with
+their packages, regardless of context. Where this causes ambiguity,
+@code{GDB} asks the user's intent.
-@quotation
+For details on the supported Ada syntax, see @cite{Debugging with GDB}.
-This attribute points to a file that contains configuration pragmas
-to use when building executables. These pragmas apply for all
-executables built from this project hierarchy. As we have seen before,
-additional pragmas can be specified on a per-project basis by setting the
-@cite{Compiler.Local_Configuration_Pragmas} attribute.
-@end quotation
+@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{156}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{157}
+@subsection Calling User-Defined Subprograms
-@geindex Global_Compilation_Switches (GNAT Project Manager)
-@strong{Builder.Global_Compilation_Switches}:
+An important capability of @code{GDB} is the ability to call user-defined
+subprograms while debugging. This is achieved simply by entering
+a subprogram call statement in the form:
@quotation
-This attribute is a list of compiler switches to use when compiling any
-source file in the project hierarchy. These switches are used in addition
-to the ones defined in the @cite{Compiler} package, which only apply to
-the sources of the corresponding project. This attribute is indexed on
-the name of the language.
+@example
+call subprogram-name (parameters)
+@end example
@end quotation
-Using such global capabilities is convenient. It can also lead to unexpected
-behavior. Especially when several subsystems are shared among different main
-projects and the different global attributes are not
-compatible. Note that using aggregate projects can be a safer and more powerful
-replacement to global attributes.
-
-@node Scenarios in Projects,Library Projects,Organizing Projects into Subsystems,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager id19}@anchor{176}@anchor{gnat_ugn/gnat_project_manager scenarios-in-projects}@anchor{14c}
-@section Scenarios in Projects
+The keyword @code{call} can be omitted in the normal case where the
+@code{subprogram-name} does not coincide with any of the predefined
+@code{GDB} commands.
+The effect is to invoke the given subprogram, passing it the
+list of parameters that is supplied. The parameters can be expressions and
+can include variables from the program being debugged. The
+subprogram must be defined
+at the library level within your program, and @code{GDB} will call the
+subprogram within the environment of your program execution (which
+means that the subprogram is free to access or even modify variables
+within your program).
-Various aspects of the projects can be modified based on @strong{scenarios}. These
-are user-defined modes that change the behavior of a project. Typical
-examples are the setup of platform-specific compiler options, or the use of
-a debug and a release mode (the former would activate the generation of debug
-information, while the second will focus on improving code optimization).
+The most important use of this facility is in allowing the inclusion of
+debugging routines that are tailored to particular data structures
+in your program. Such debugging routines can be written to provide a suitably
+high-level description of an abstract type, rather than a low-level dump
+of its physical layout. After all, the standard
+@code{GDB print} command only knows the physical layout of your
+types, not their abstract meaning. Debugging routines can provide information
+at the desired semantic level and are thus enormously useful.
-Let's enhance our example to support debug and release modes. The issue is to
-let the user choose what kind of system he is building: use @emph{-g} as
-compiler switches in debug mode and @emph{-O2} in release mode. We will also
-set up the projects so that we do not share the same object directory in both
-modes; otherwise switching from one to the other might trigger more
-recompilations than needed or mix objects from the two modes.
+For example, when debugging GNAT itself, it is crucial to have access to
+the contents of the tree nodes used to represent the program internally.
+But tree nodes are represented simply by an integer value (which in turn
+is an index into a table of nodes).
+Using the @code{print} command on a tree node would simply print this integer
+value, which is not very useful. But the PN routine (defined in file
+treepr.adb in the GNAT sources) takes a tree node as input, and displays
+a useful high level representation of the tree node, which includes the
+syntactic category of the node, its position in the source, the integers
+that denote descendant nodes and parent node, as well as varied
+semantic information. To study this example in more detail, you might want to
+look at the body of the PN procedure in the stated file.
-One naive approach is to create two different project files, say
-@code{build_debug.gpr} and @code{build_release.gpr}, that set the appropriate
-attributes as explained in previous sections. This solution does not scale
-well, because in the presence of multiple projects depending on each other, you
-will also have to duplicate the complete hierarchy and adapt the project files
-to point to the right copies.
+Another useful application of this capability is to deal with situations of
+complex data which are not handled suitably by GDB. For example, if you specify
+Convention Fortran for a multi-dimensional array, GDB does not know that
+the ordering of array elements has been switched and will not properly
+address the array elements. In such a case, instead of trying to print the
+elements directly from GDB, you can write a callable procedure that prints
+the elements in the desired format.
-@geindex scenarios (GNAT Project Manager)
+@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{158}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{159}
+@subsection Using the @emph{next} Command in a Function
-Instead, project files support the notion of scenarios controlled
-by external values. Such values can come from several sources (in decreasing
-order of priority):
-@geindex -X (usage with GNAT Project Manager)
+When you use the @code{next} command in a function, the current source
+location will advance to the next statement as usual. A special case
+arises in the case of a @code{return} statement.
+Part of the code for a return statement is the 'epilogue' of the function.
+This is the code that returns to the caller. There is only one copy of
+this epilogue code, and it is typically associated with the last return
+statement in the function if there is more than one return. In some
+implementations, this epilogue is associated with the first statement
+of the function.
-@table @asis
+The result is that if you use the @code{next} command from a return
+statement that is not the last return statement of the function you
+may see a strange apparent jump to the last return statement or to
+the start of the function. You should simply ignore this odd jump.
+The value returned is always that from the first return statement
+that was stepped through.
-@item @strong{Command line}:
+@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{15a}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{15b}
+@subsection Stopping When Ada Exceptions Are Raised
-When launching @emph{gprbuild}, the user can pass
-extra @emph{-X} switches to define the external value. In
-our case, the command line might look like
-@example
-gprbuild -Pbuild.gpr -Xmode=release
-@end example
+@geindex Exceptions (in gdb)
-@item @strong{Environment variables}:
+You can set catchpoints that stop the program execution when your program
+raises selected exceptions.
-When the external value does not come from the command line, it can come from
-the value of environment variables of the appropriate name.
-In our case, if an environment variable called "mode"
-exists, its value will be taken into account.
-@end table
-@geindex external (GNAT Project Manager)
+@itemize *
-@strong{External function second parameter}.
+@item
-We now need to get that value in the project. The general form is to use
-the predefined function @strong{external} which returns the current value of
-the external. For instance, we could set up the object directory to point to
-either @code{obj/debug} or @code{obj/release} by changing our project to
+@table @asis
-@example
-project Build is
- for Object_Dir use "obj/" & external ("mode", "debug");
- ... -- as before
-end Build;
-@end example
+@item @code{catch exception}
-The second parameter to @cite{external} is optional, and is the default
-value to use if "mode" is not set from the command line or the environment.
-
-In order to set the switches according to the different scenarios, other
-constructs have to be introduced such as typed variables and case constructions.
+Set a catchpoint that stops execution whenever (any task in the) program
+raises any exception.
+@end table
-@geindex typed variable (GNAT Project Manager)
+@item
-@geindex case construction (GNAT Project Manager)
+@table @asis
-A @strong{typed variable} is a variable that
-can take only a limited number of values, similar to an enumeration in Ada.
-Such a variable can then be used in a @strong{case construction} and create conditional
-sections in the project. The following example shows how this can be done:
+@item @code{catch exception @emph{name}}
-@example
-project Build is
- type Mode_Type is ("debug", "release"); -- all possible values
- Mode : Mode_Type := external ("mode", "debug"); -- a typed variable
+Set a catchpoint that stops execution whenever (any task in the) program
+raises the exception @emph{name}.
+@end table
- package Compiler is
- case Mode is
- when "debug" =>
- for Switches ("Ada")
- use ("-g");
- when "release" =>
- for Switches ("Ada")
- use ("-O2");
- end case;
- end Compiler;
-end Build;
-@end example
+@item
-The project has suddenly grown in size, but has become much more flexible.
-@cite{Mode_Type} defines the only valid values for the @cite{mode} variable. If
-any other value is read from the environment, an error is reported and the
-project is considered as invalid.
+@table @asis
-The @cite{Mode} variable is initialized with an external value
-defaulting to @cite{"debug"}. This default could be omitted and that would
-force the user to define the value. Finally, we can use a case construction to set the
-switches depending on the scenario the user has chosen.
+@item @code{catch exception unhandled}
-Most aspects of the projects can depend on scenarios. The notable exception
-are project dependencies (@emph{with} clauses), which cannot depend on a scenario.
+Set a catchpoint that stops executing whenever (any task in the) program
+raises an exception for which there is no handler.
+@end table
-Scenarios work the same way with @strong{project hierarchies}: you can either
-duplicate a variable similar to @cite{Mode} in each of the project (as long
-as the first argument to @cite{external} is always the same and the type is
-the same), or simply set the variable in the @code{shared.gpr} project
-(see @ref{171,,Sharing Between Projects}).
+@item
-@node Library Projects,Project Extension,Scenarios in Projects,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager library-projects}@anchor{8a}@anchor{gnat_ugn/gnat_project_manager id20}@anchor{177}
-@section Library Projects
+@table @asis
+@item @code{info exceptions}, @code{info exceptions @emph{regexp}}
-So far, we have seen examples of projects that create executables. However,
-it is also possible to create libraries instead. A @strong{library} is a specific
-type of subsystem where, for convenience, objects are grouped together
-using system-specific means such as archives or windows DLLs.
+The @code{info exceptions} command permits the user to examine all defined
+exceptions within Ada programs. With a regular expression, @emph{regexp}, as
+argument, prints out only those exceptions whose name matches @emph{regexp}.
+@end table
+@end itemize
-Library projects provide a system- and language-independent way of building
-both @strong{static} and @strong{dynamic} libraries. They also support the concept of
-@strong{standalone libraries} (SAL) which offer two significant properties: the
-elaboration (e.g. initialization) of the library is either automatic or
-very simple; a change in the
-implementation part of the library implies minimal post-compilation actions on
-the complete system and potentially no action at all for the rest of the
-system in the case of dynamic SALs.
+@geindex Tasks (in gdb)
-There is a restriction on shared library projects: by default, they are only
-allowed to import other shared library projects. They are not allowed to
-import non library projects or static library projects.
+@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{15c}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{15d}
+@subsection Ada Tasks
-The GNAT Project Manager takes complete care of the library build, rebuild and
-installation tasks, including recompilation of the source files for which
-objects do not exist or are not up to date, assembly of the library archive, and
-installation of the library (i.e., copying associated source, object and
-@code{ALI} files to the specified location).
-@menu
-* Building Libraries::
-* Using Library Projects::
-* Stand-alone Library Projects::
-* Installing a library with project files::
+@code{GDB} allows the following task-related commands:
-@end menu
-@node Building Libraries,Using Library Projects,,Library Projects
-@anchor{gnat_ugn/gnat_project_manager id21}@anchor{178}@anchor{gnat_ugn/gnat_project_manager building-libraries}@anchor{179}
-@subsection Building Libraries
+@itemize *
+@item
-Let's enhance our example and transform the @cite{logging} subsystem into a
-library. In order to do so, a few changes need to be made to
-@code{logging.gpr}. Some attributes need to be defined: at least
-@cite{Library_Name} and @cite{Library_Dir}; in addition, some other attributes
-can be used to specify specific aspects of the library. For readability, it is
-also recommended (although not mandatory), to use the qualifier @cite{library}
-in front of the @cite{project} keyword.
+@table @asis
-@geindex Library_Name (GNAT Project Manager)
+@item @code{info tasks}
-@strong{Library_Name}:
+This command shows a list of current Ada tasks, as in the following example:
-@quotation
+@example
+(gdb) info tasks
+ ID TID P-ID Thread Pri State Name
+ 1 8088000 0 807e000 15 Child Activation Wait main_task
+ 2 80a4000 1 80ae000 15 Accept/Select Wait b
+ 3 809a800 1 80a4800 15 Child Activation Wait a
+* 4 80ae800 3 80b8000 15 Running c
+@end example
-This attribute is the name of the library to be built. There is no
-restriction on the name of a library imposed by the project manager, except
-for stand-alone libraries whose names must follow the syntax of Ada
-identifiers; however, there may be system-specific restrictions on the name.
-In general, it is recommended to stick to alphanumeric characters (and
-possibly single underscores) to help portability.
-@end quotation
+In this listing, the asterisk before the first task indicates it to be the
+currently running task. The first column lists the task ID that is used
+to refer to tasks in the following commands.
+@end table
+@end itemize
-@geindex Library_Dir (GNAT Project Manager)
+@geindex Breakpoints and tasks
-@strong{Library_Dir}:
-@quotation
+@itemize *
-This attribute is the path (absolute or relative) of the directory where
-the library is to be installed. In the process of building a library,
-the sources are compiled, the object files end up in the explicit or
-implicit @cite{Object_Dir} directory. When all sources of a library
-are compiled, some of the compilation artifacts, including the library itself,
-are copied to the library_dir directory. This directory must exist and be
-writable. It must also be different from the object directory so that cleanup
-activities in the Library_Dir do not affect recompilation needs.
-@end quotation
+@item
+@code{break`@w{`}*linespec* `@w{`}task} @emph{taskid}, @code{break} @emph{linespec} @code{task} @emph{taskid} @code{if} ...
-Here is the new version of @code{logging.gpr} that makes it a library:
+@quotation
-@example
-library project Logging is -- "library" is optional
- for Library_Name use "logging"; -- will create "liblogging.a" on Unix
- for Object_Dir use "obj";
- for Library_Dir use "lib"; -- different from object_dir
-end Logging;
-@end example
+These commands are like the @code{break ... thread ...}.
+@emph{linespec} specifies source lines.
-Once the above two attributes are defined, the library project is valid and
-is enough for building a library with default characteristics.
-Other library-related attributes can be used to change the defaults:
+Use the qualifier @code{task @emph{taskid}} with a breakpoint command
+to specify that you only want @code{GDB} to stop the program when a
+particular Ada task reaches this breakpoint. @emph{taskid} is one of the
+numeric task identifiers assigned by @code{GDB}, shown in the first
+column of the @code{info tasks} display.
-@geindex Library_Kind (GNAT Project Manager)
+If you do not specify @code{task @emph{taskid}} when you set a
+breakpoint, the breakpoint applies to @emph{all} tasks of your
+program.
-@strong{Library_Kind}:
+You can use the @code{task} qualifier on conditional breakpoints as
+well; in this case, place @code{task @emph{taskid}} before the
+breakpoint condition (before the @code{if}).
+@end quotation
+@end itemize
-@quotation
+@geindex Task switching (in gdb)
-The value of this attribute must be either @cite{"static"}, @cite{"dynamic"} or
-@cite{"relocatable"} (the latter is a synonym for dynamic). It indicates
-which kind of library should be built (the default is to build a
-static library, that is an archive of object files that can potentially
-be linked into a static executable). When the library is set to be dynamic,
-a separate image is created that will be loaded independently, usually
-at the start of the main program execution. Support for dynamic libraries is
-very platform specific, for instance on Windows it takes the form of a DLL
-while on GNU/Linux, it is a dynamic elf image whose suffix is usually
-@code{.so}. Library project files, on the other hand, can be written in
-a platform independent way so that the same project file can be used to build
-a library on different operating systems.
-
-If you need to build both a static and a dynamic library, it is recommended
-to use two different object directories, since in some cases some extra code
-needs to be generated for the latter. For such cases, one can either define
-two different project files, or a single one that uses scenarios to indicate
-the various kinds of library to be built and their corresponding object_dir.
-@end quotation
-@geindex Library_ALI_Dir (GNAT Project Manager)
+@itemize *
-@strong{Library_ALI_Dir}:
+@item
+@code{task @emph{taskno}}
@quotation
-This attribute may be specified to indicate the directory where the ALI
-files of the library are installed. By default, they are copied into the
-@cite{Library_Dir} directory, but as for the executables where we have a
-separate @cite{Exec_Dir} attribute, you might want to put them in a separate
-directory since there can be hundreds of them. The same restrictions as for
-the @cite{Library_Dir} attribute apply.
+This command allows switching to the task referred by @emph{taskno}. In
+particular, this allows browsing of the backtrace of the specified
+task. It is advisable to switch back to the original task before
+continuing execution otherwise the scheduling of the program may be
+perturbed.
@end quotation
+@end itemize
-@geindex Library_Version (GNAT Project Manager)
-
-@strong{Library_Version}:
+For more detailed information on the tasking support,
+see @cite{Debugging with GDB}.
-@quotation
+@geindex Debugging Generic Units
-This attribute is platform dependent, and has no effect on Windows.
-On Unix, it is used only for dynamic libraries as the internal
-name of the library (the @cite{"soname"}). If the library file name (built
-from the @cite{Library_Name}) is different from the @cite{Library_Version},
-then the library file will be a symbolic link to the actual file whose name
-will be @cite{Library_Version}. This follows the usual installation schemes
-for dynamic libraries on many Unix systems.
+@geindex Generics
-@example
-project Logging is
- Version := "1";
- for Library_Dir use "lib";
- for Library_Name use "logging";
- for Library_Kind use "dynamic";
- for Library_Version use "liblogging.so." & Version;
-end Logging;
-@end example
+@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{15e}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{15f}
+@subsection Debugging Generic Units
-After the compilation, the directory @code{lib} will contain both a
-@code{libdummy.so.1} library and a symbolic link to it called
-@code{libdummy.so}.
-@end quotation
-@geindex Library_GCC (GNAT Project Manager)
+GNAT always uses code expansion for generic instantiation. This means that
+each time an instantiation occurs, a complete copy of the original code is
+made, with appropriate substitutions of formals by actuals.
-@strong{Library_GCC}:
+It is not possible to refer to the original generic entities in
+@code{GDB}, but it is always possible to debug a particular instance of
+a generic, by using the appropriate expanded names. For example, if we have
@quotation
-This attribute is the name of the tool to use instead of "gcc" to link shared
-libraries. A common use of this attribute is to define a wrapper script that
-accomplishes specific actions before calling gcc (which itself calls the
-linker to build the library image).
-@end quotation
+@example
+procedure g is
-@geindex Library_Options (GNAT Project Manager)
+ generic package k is
+ procedure kp (v1 : in out integer);
+ end k;
-@strong{Library_Options}:
+ package body k is
+ procedure kp (v1 : in out integer) is
+ begin
+ v1 := v1 + 1;
+ end kp;
+ end k;
-@quotation
+ package k1 is new k;
+ package k2 is new k;
-This attribute may be used to specify additional switches (last switches)
-when linking a shared library.
+ var : integer := 1;
-It may also be used to add foreign object files to a static library.
-Each string in Library_Options is an absolute or relative path of an object
-file. When a relative path, it is relative to the object directory.
+begin
+ k1.kp (var);
+ k2.kp (var);
+ k1.kp (var);
+ k2.kp (var);
+end;
+@end example
@end quotation
-@geindex Leading_Library_Options (GNAT Project Manager)
-
-@strong{Leading_Library_Options}:
+Then to break on a call to procedure kp in the k2 instance, simply
+use the command:
@quotation
-This attribute, that is taken into account only by @emph{gprbuild}, may be
-used to specified leading options (first switches) when linking a shared
-library.
+@example
+(gdb) break g.k2.kp
+@end example
@end quotation
-@geindex Linker_Options (GNAT Project Manager)
+When the breakpoint occurs, you can step through the code of the
+instance in the normal manner and examine the values of local variables, as for
+other units.
+
+@geindex Remote Debugging with gdbserver
-@strong{Linker.Linker_Options}:
+@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{160}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{161}
+@subsection Remote Debugging with gdbserver
-@quotation
-This attribute specifies additional switches to be given to the linker when
-linking an executable. It is ignored when defined in the main project and
-taken into account in all other projects that are imported directly or
-indirectly. These switches complement the @cite{Linker.Switches}
-defined in the main project. This is useful when a particular subsystem
-depends on an external library: adding this dependency as a
-@cite{Linker_Options} in the project of the subsystem is more convenient than
-adding it to all the @cite{Linker.Switches} of the main projects that depend
-upon this subsystem.
-@end quotation
+On platforms where gdbserver is supported, it is possible to use this tool
+to debug your application remotely. This can be useful in situations
+where the program needs to be run on a target host that is different
+from the host used for development, particularly when the target has
+a limited amount of resources (either CPU and/or memory).
-@node Using Library Projects,Stand-alone Library Projects,Building Libraries,Library Projects
-@anchor{gnat_ugn/gnat_project_manager id22}@anchor{17a}@anchor{gnat_ugn/gnat_project_manager using-library-projects}@anchor{17b}
-@subsection Using Library Projects
-
-
-When the builder detects that a project file is a library project file, it
-recompiles all sources of the project that need recompilation and rebuild the
-library if any of the sources have been recompiled. It then groups all object
-files into a single file, which is a shared or a static library. This library
-can later on be linked with multiple executables. Note that the use
-of shard libraries reduces the size of the final executable and can also reduce
-the memory footprint at execution time when the library is shared among several
-executables.
-
-@emph{gprbuild also allows to build **multi-language libraries*} when specifying
-sources from multiple languages.
-
-A non-library project can import a library project. When the builder is invoked
-on the former, the library of the latter is only rebuilt when absolutely
-necessary. For instance, if a unit of the library is not up-to-date but none of
-the executables need this unit, then the unit is not recompiled and the library
-is not reassembled. For instance, let's assume in our example that logging has
-the following sources: @code{log1.ads}, @code{log1.adb}, @code{log2.ads} and
-@code{log2.adb}. If @code{log1.adb} has been modified, then the library
-@code{liblogging} will be rebuilt when compiling all the sources of
-@cite{Build} only if @code{proc.ads}, @code{pack.ads} or @code{pack.adb}
-include a @cite{"with Log1"}.
-
-To ensure that all the sources in the @cite{Logging} library are
-up to date, and that all the sources of @cite{Build} are also up to date,
-the following two commands need to be used:
-
-@example
-gprbuild -Plogging.gpr
-gprbuild -Pbuild.gpr
-@end example
-
-All @code{ALI} files will also be copied from the object directory to the
-library directory. To build executables, @emph{gprbuild} will use the
-library rather than the individual object files.
-
-Library projects can also be useful to describe a library that needs to be used
-but, for some reason, cannot be rebuilt. For instance, it is the case when some
-of the library sources are not available. Such library projects need to use the
-@cite{Externally_Built} attribute as in the example below:
-
-@example
-library project Extern_Lib is
- for Languages use ("Ada", "C");
- for Source_Dirs use ("lib_src");
- for Library_Dir use "lib2";
- for Library_Kind use "dynamic";
- for Library_Name use "l2";
- for Externally_Built use "true"; -- <<<<
-end Extern_Lib;
-@end example
-
-In the case of externally built libraries, the @cite{Object_Dir}
-attribute does not need to be specified because it will never be
-used.
-
-The main effect of using such an externally built library project is mostly to
-affect the linker command in order to reference the desired library. It can
-also be achieved by using @cite{Linker.Linker_Options} or @cite{Linker.Switches}
-in the project corresponding to the subsystem needing this external library.
-This latter method is more straightforward in simple cases but when several
-subsystems depend upon the same external library, finding the proper place
-for the @cite{Linker.Linker_Options} might not be easy and if it is
-not placed properly, the final link command is likely to present ordering issues.
-In such a situation, it is better to use the externally built library project
-so that all other subsystems depending on it can declare this dependency thanks
-to a project @emph{with} clause, which in turn will trigger the builder to find
-the proper order of libraries in the final link command.
-
-@node Stand-alone Library Projects,Installing a library with project files,Using Library Projects,Library Projects
-@anchor{gnat_ugn/gnat_project_manager id23}@anchor{17c}@anchor{gnat_ugn/gnat_project_manager stand-alone-library-projects}@anchor{97}
-@subsection Stand-alone Library Projects
-
-
-@geindex standalone libraries (usage with GNAT Project Manager)
-
-A @strong{stand-alone library} is a library that contains the necessary code to
-elaborate the Ada units that are included in the library. A stand-alone
-library is a convenient way to add an Ada subsystem to a more global system
-whose main is not in Ada since it makes the elaboration of the Ada part mostly
-transparent. However, stand-alone libraries are also useful when the main is in
-Ada: they provide a means for minimizing relinking & redeployment of complex
-systems when localized changes are made.
-
-The name of a stand-alone library, specified with attribute
-@cite{Library_Name}, must have the syntax of an Ada identifier.
-
-The most prominent characteristic of a stand-alone library is that it offers a
-distinction between interface units and implementation units. Only the former
-are visible to units outside the library. A stand-alone library project is thus
-characterised by a third attribute, usually @strong{Library_Interface}, in addition
-to the two attributes that make a project a Library Project
-(@cite{Library_Name} and @cite{Library_Dir}). This third attribute may also be
-@strong{Interfaces}. @strong{Library_Interface} only works when the interface is in Ada
-and takes a list of units as parameter. @strong{Interfaces} works for any supported
-language and takes a list of sources as parameter.
-
-@geindex Library_Interface (GNAT Project Manager)
-
-@strong{Library_Interface}:
+To do so, start your program using gdbserver on the target machine.
+gdbserver then automatically suspends the execution of your program
+at its entry point, waiting for a debugger to connect to it. The
+following commands starts an application and tells gdbserver to
+wait for a connection with the debugger on localhost port 4444.
@quotation
-This attribute defines an explicit subset of the units of the project. Units
-from projects importing this library project may only "with" units whose
-sources are listed in the @cite{Library_Interface}. Other sources are
-considered implementation units.
-
@example
-for Library_Dir use "lib";
-for Library_Name use "logging";
-for Library_Interface use ("lib1", "lib2"); -- unit names
+$ gdbserver localhost:4444 program
+Process program created; pid = 5685
+Listening on port 4444
@end example
@end quotation
-@strong{Interfaces}
-
-@quotation
-
-This attribute defines an explicit subset of the source files of a project.
-Sources from projects importing this project, can only depend on sources from
-this subset. This attribute can be used on non library projects. It can also
-be used as a replacement for attribute @cite{Library_Interface}, in which
-case, units have to be replaced by source files. For multi-language library
-projects, it is the only way to make the project a Stand-Alone Library project
-whose interface is not purely Ada.
-@end quotation
-
-@geindex Library_Standalone (GNAT Project Manager)
-
-@strong{Library_Standalone}:
+Once gdbserver has started listening, we can tell the debugger to establish
+a connection with this gdbserver, and then start the same debugging session
+as if the program was being debugged on the same host, directly under
+the control of GDB.
@quotation
-This attribute defines the kind of standalone library to
-build. Values are either @cite{standard} (the default), @cite{no} or
-@cite{encapsulated}. When @cite{standard} is used the code to elaborate and
-finalize the library is embedded, when @cite{encapsulated} is used the
-library can furthermore depend only on static libraries (including
-the GNAT runtime). This attribute can be set to @cite{no} to make it clear
-that the library should not be standalone in which case the
-@cite{Library_Interface} should not defined. Note that this attribute
-only applies to shared libraries, so @cite{Library_Kind} must be set
-to @cite{dynamic}.
-
@example
-for Library_Dir use "lib";
-for Library_Name use "logging";
-for Library_Kind use "dynamic";
-for Library_Interface use ("lib1", "lib2"); -- unit names
-for Library_Standalone use "encapsulated";
+$ gdb program
+(gdb) target remote targethost:4444
+Remote debugging using targethost:4444
+0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so.
+(gdb) b foo.adb:3
+Breakpoint 1 at 0x401f0c: file foo.adb, line 3.
+(gdb) continue
+Continuing.
+
+Breakpoint 1, foo () at foo.adb:4
+4 end foo;
@end example
@end quotation
-In order to include the elaboration code in the stand-alone library, the binder
-is invoked on the closure of the library units creating a package whose name
-depends on the library name (b~logging.ads/b in the example).
-This binder-generated package includes @strong{initialization} and @strong{finalization}
-procedures whose names depend on the library name (@cite{logginginit} and
-@cite{loggingfinal} in the example). The object corresponding to this package is
-included in the library.
+It is also possible to use gdbserver to attach to an already running
+program, in which case the execution of that program is simply suspended
+until the connection between the debugger and gdbserver is established.
-@geindex Library_Auto_Init (GNAT Project Manager)
+For more information on how to use gdbserver, see the @emph{Using the gdbserver Program}
+section in @cite{Debugging with GDB}.
+GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux.
-@strong{Library_Auto_Init}:
+@geindex Abnormal Termination or Failure to Terminate
-@quotation
+@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{162}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{163}
+@subsection GNAT Abnormal Termination or Failure to Terminate
-A dynamic stand-alone Library is automatically initialized
-if automatic initialization of Stand-alone Libraries is supported on the
-platform and if attribute @strong{Library_Auto_Init} is not specified or
-is specified with the value "true". A static Stand-alone Library is never
-automatically initialized. Specifying "false" for this attribute
-prevents automatic initialization.
-
-When a non-automatically initialized stand-alone library is used in an
-executable, its initialization procedure must be called before any service of
-the library is used. When the main subprogram is in Ada, it may mean that the
-initialization procedure has to be called during elaboration of another
-package.
-@end quotation
-@geindex Library_Dir (GNAT Project Manager)
+When presented with programs that contain serious errors in syntax
+or semantics,
+GNAT may on rare occasions experience problems in operation, such
+as aborting with a
+segmentation fault or illegal memory access, raising an internal
+exception, terminating abnormally, or failing to terminate at all.
+In such cases, you can activate
+various features of GNAT that can help you pinpoint the construct in your
+program that is the likely source of the problem.
-@strong{Library_Dir}:
+The following strategies are presented in increasing order of
+difficulty, corresponding to your experience in using GNAT and your
+familiarity with compiler internals.
-@quotation
-For a stand-alone library, only the @code{ALI} files of the interface units
-(those that are listed in attribute @cite{Library_Interface}) are copied to
-the library directory. As a consequence, only the interface units may be
-imported from Ada units outside of the library. If other units are imported,
-the binding phase will fail.
-@end quotation
+@itemize *
-@strong{Binder.Default_Switches}:
+@item
+Run @code{gcc} with the @code{-gnatf}. This first
+switch causes all errors on a given line to be reported. In its absence,
+only the first error on a line is displayed.
-@quotation
+The @code{-gnatdO} switch causes errors to be displayed as soon as they
+are encountered, rather than after compilation is terminated. If GNAT
+terminates prematurely or goes into an infinite loop, the last error
+message displayed may help to pinpoint the culprit.
-When a stand-alone library is bound, the switches that are specified in
-the attribute @strong{Binder.Default_Switches ("Ada")} are
-used in the call to @emph{gnatbind}.
-@end quotation
+@item
+Run @code{gcc} with the @code{-v} (verbose) switch. In this
+mode, @code{gcc} produces ongoing information about the progress of the
+compilation and provides the name of each procedure as code is
+generated. This switch allows you to find which Ada procedure was being
+compiled when it encountered a code generation problem.
+@end itemize
-@geindex Library_Src_Dir (GNAT Project Manager)
+@geindex -gnatdc switch
-@strong{Library_Src_Dir}:
-@quotation
+@itemize *
-This attribute defines the location (absolute or relative to the project
-directory) where the sources of the interface units are copied at
-installation time.
-These sources includes the specs of the interface units along with the
-closure of sources necessary to compile them successfully. That may include
-bodies and subunits, when pragmas @cite{Inline} are used, or when there are
-generic units in specs. This directory cannot point to the object directory
-or one of the source directories, but it can point to the library directory,
-which is the default value for this attribute.
-@end quotation
+@item
+Run @code{gcc} with the @code{-gnatdc} switch. This is a GNAT specific
+switch that does for the front-end what @code{-v} does
+for the back end. The system prints the name of each unit,
+either a compilation unit or nested unit, as it is being analyzed.
-@geindex Library_Symbol_Policy (GNAT Project Manager)
+@item
+Finally, you can start
+@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{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
+which the execution stopped, and @code{input_file name} indicates the name of
+the source file.
+@end itemize
-@strong{Library_Symbol_Policy}:
+@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{164}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{165}
+@subsection Naming Conventions for GNAT Source Files
-@quotation
-This attribute controls the export of symbols and, on some platforms (like
-VMS) that have the notions of major and minor IDs built in the library
-files, it controls the setting of these IDs. It is not supported on all
-platforms (where it will just have no effect). It may have one of the
-following values:
+In order to examine the workings of the GNAT system, the following
+brief description of its organization may be helpful:
@itemize *
@item
-@cite{"autonomous"} or @cite{"default"}: exported symbols are not controlled
+Files with prefix @code{sc} contain the lexical scanner.
@item
-@cite{"compliant"}: if attribute @strong{Library_Reference_Symbol_File}
-is not defined, then it is equivalent to policy "autonomous". If there
-are exported symbols in the reference symbol file that are not in the
-object files of the interfaces, the major ID of the library is increased.
-If there are symbols in the object files of the interfaces that are not
-in the reference symbol file, these symbols are put at the end of the list
-in the newly created symbol file and the minor ID is increased.
+All files prefixed with @code{par} are components of the parser. The
+numbers correspond to chapters of the Ada Reference Manual. For example,
+parsing of select statements can be found in @code{par-ch9.adb}.
@item
-@cite{"controlled"}: the attribute @strong{Library_Reference_Symbol_File} must be
-defined. The library will fail to build if the exported symbols in the
-object files of the interfaces do not match exactly the symbol in the
-symbol file.
+All files prefixed with @code{sem} perform semantic analysis. The
+numbers correspond to chapters of the Ada standard. For example, all
+issues involving context clauses can be found in @code{sem_ch10.adb}. In
+addition, some features of the language require sufficient special processing
+to justify their own semantic files: sem_aggr for aggregates, sem_disp for
+dynamic dispatching, etc.
@item
-@cite{"restricted"}: The attribute @strong{Library_Symbol_File} must be defined.
-The library will fail to build if there are symbols in the symbol file that
-are not in the exported symbols of the object files of the interfaces.
-Additional symbols in the object files are not added to the symbol file.
+All files prefixed with @code{exp} perform normalization and
+expansion of the intermediate representation (abstract syntax tree, or AST).
+these files use the same numbering scheme as the parser and semantics files.
+For example, the construction of record initialization procedures is done in
+@code{exp_ch3.adb}.
@item
-@cite{"direct"}: The attribute @strong{Library_Symbol_File} must be defined and
-must designate an existing file in the object directory. This symbol file
-is passed directly to the underlying linker without any symbol processing.
-@end itemize
-@end quotation
-
-@geindex Library_Reference_Symbol_File (GNAT Project Manager)
-
-@strong{Library_Reference_Symbol_File}
+The files prefixed with @code{bind} implement the binder, which
+verifies the consistency of the compilation, determines an order of
+elaboration, and generates the bind file.
-@quotation
+@item
+The files @code{atree.ads} and @code{atree.adb} detail the low-level
+data structures used by the front-end.
-This attribute may define the path name of a reference symbol file that is
-read when the symbol policy is either "compliant" or "controlled", on
-platforms that support symbol control, such as VMS, when building a
-stand-alone library. The path may be an absolute path or a path relative
-to the project directory.
-@end quotation
+@item
+The files @code{sinfo.ads} and @code{sinfo.adb} detail the structure of
+the abstract syntax tree as produced by the parser.
-@geindex Library_Symbol_File (GNAT Project Manager)
+@item
+The files @code{einfo.ads} and @code{einfo.adb} detail the attributes of
+all entities, computed during semantic analysis.
-@strong{Library_Symbol_File}
-
-@quotation
-
-This attribute may define the name of the symbol file to be created when
-building a stand-alone library when the symbol policy is either "compliant",
-"controlled" or "restricted", on platforms that support symbol control,
-such as VMS. When symbol policy is "direct", then a file with this name
-must exist in the object directory.
-@end quotation
+@item
+Library management issues are dealt with in files with prefix
+@code{lib}.
-@node Installing a library with project files,,Stand-alone Library Projects,Library Projects
-@anchor{gnat_ugn/gnat_project_manager installing-a-library-with-project-files}@anchor{8d}@anchor{gnat_ugn/gnat_project_manager id24}@anchor{17d}
-@subsection Installing a library with project files
-
-
-When using project files, a usable version of the library is created in the
-directory specified by the @cite{Library_Dir} attribute of the library
-project file. Thus no further action is needed in order to make use of
-the libraries that are built as part of the general application build.
-
-You may want to install a library in a context different from where the library
-is built. This situation arises with third party suppliers, who may want
-to distribute a library in binary form where the user is not expected to be
-able to recompile the library. The simplest option in this case is to provide
-a project file slightly different from the one used to build the library, by
-using the @cite{externally_built} attribute. See @ref{17b,,Using Library Projects}
-
-Another option is to use @emph{gprinstall} to install the library in a
-different context than the build location. @emph{gprinstall} automatically
-generates a project to use this library, and also copies the minimum set of
-sources needed to use the library to the install location.
-@ref{168,,Installation}
-
-@node Project Extension,Aggregate Projects,Library Projects,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager id25}@anchor{17e}@anchor{gnat_ugn/gnat_project_manager project-extension}@anchor{14f}
-@section Project Extension
-
-
-During development of a large system, it is sometimes necessary to use
-modified versions of some of the source files, without changing the original
-sources. This can be achieved through the @strong{project extension} facility.
-
-Suppose for instance that our example @cite{Build} project is built every night
-for the whole team, in some shared directory. A developer usually needs to work
-on a small part of the system, and might not want to have a copy of all the
-sources and all the object files (mostly because that would require too much
-disk space, time to recompile everything). He prefers to be able to override
-some of the source files in his directory, while taking advantage of all the
-object files generated at night.
-
-Another example can be taken from large software systems, where it is common to have
-multiple implementations of a common interface; in Ada terms, multiple
-versions of a package body for the same spec. For example, one implementation
-might be safe for use in tasking programs, while another might be used only
-in sequential applications. This can be modeled in GNAT using the concept
-of @emph{project extension}. If one project (the 'child') @emph{extends}
-another project (the 'parent') then by default all source files of the
-parent project are inherited by the child, but the child project can
-override any of the parent's source files with new versions, and can also
-add new files or remove unnecessary ones.
-This facility is the project analog of a type extension in
-object-oriented programming. Project hierarchies are permitted (an extending
-project may itself be extended), and a project that
-extends a project can also import other projects.
-
-A third example is that of using project extensions to provide different
-versions of the same system. For instance, assume that a @cite{Common}
-project is used by two development branches. One of the branches has now
-been frozen, and no further change can be done to it or to @cite{Common}.
-However, the other development branch still needs evolution of @cite{Common}.
-Project extensions provide a flexible solution to create a new version
-of a subsystem while sharing and reusing as much as possible from the original
-one.
-
-A project extension implicitly inherits all the sources and objects from the
-project it extends. It is possible to create a new version of some of the
-sources in one of the additional source directories of the extending
-project. Those new versions hide the original versions. Adding new sources or
-removing existing ones is also possible. Here is an example on how to extend
-the project @cite{Build} from previous examples:
-
-@example
-project Work extends "../bld/build.gpr" is
-end Work;
-@end example
-
-The project after @strong{extends} is the one being extended. As usual, it can be
-specified using an absolute path, or a path relative to any of the directories
-in the project path (see @ref{16c,,Project Dependencies}). This project does not
-specify source or object directories, so the default values for these
-attributes will be used that is to say the current directory (where project
-@cite{Work} is placed). We can compile that project with
-
-@example
-gprbuild -Pwork
-@end example
-
-If no sources have been placed in the current directory, this command
-won't do anything, since this project does not change the
-sources it inherited from @cite{Build}, therefore all the object files
-in @cite{Build} and its dependencies are still valid and are reused
-automatically.
+@geindex Annex A (in Ada Reference Manual)
-Suppose we now want to supply an alternate version of @code{pack.adb} but use
-the existing versions of @code{pack.ads} and @code{proc.adb}. We can create
-the new file in Work's current directory (likely by copying the one from the
-@cite{Build} project and making changes to it. If new packages are needed at
-the same time, we simply create new files in the source directory of the
-extending project.
-
-When we recompile, @emph{gprbuild} will now automatically recompile
-this file (thus creating @code{pack.o} in the current directory) and
-any file that depends on it (thus creating @code{proc.o}). Finally, the
-executable is also linked locally.
-
-Note that we could have obtained the desired behavior using project import
-rather than project inheritance. A @cite{base} project would contain the
-sources for @code{pack.ads} and @code{proc.adb}, and @cite{Work} would
-import @cite{base} and add @code{pack.adb}. In this scenario, @cite{base}
-cannot contain the original version of @code{pack.adb} otherwise there would be
-2 versions of the same unit in the closure of the project and this is not
-allowed. Generally speaking, it is not recommended to put the spec and the
-body of a unit in different projects since this affects their autonomy and
-reusability.
-
-In a project file that extends another project, it is possible to
-indicate that an inherited source is @strong{not part} of the sources of the
-extending project. This is necessary sometimes when a package spec has
-been overridden and no longer requires a body: in this case, it is
-necessary to indicate that the inherited body is not part of the sources
-of the project, otherwise there will be a compilation error
-when compiling the spec.
-
-@geindex Excluded_Source_Files (GNAT Project Manager)
-
-@geindex Excluded_Source_List_File (GNAT Project Manager)
-
-For that purpose, the attribute @strong{Excluded_Source_Files} is used.
-Its value is a list of file names.
-It is also possible to use attribute @cite{Excluded_Source_List_File}.
-Its value is the path of a text file containing one file name per
-line.
-
-@example
-project Work extends "../bld/build.gpr" is
- for Source_Files use ("pack.ads");
- -- New spec of Pkg does not need a completion
- for Excluded_Source_Files use ("pack.adb");
-end Work;
-@end example
-
-All packages that are not declared in the extending project are inherited from
-the project being extended, with their attributes, with the exception of
-@cite{Linker'Linker_Options} which is never inherited. In particular, an
-extending project retains all the switches specified in the project being
-extended.
-
-At the project level, if they are not declared in the extending project, some
-attributes are inherited from the project being extended. They are:
-@cite{Languages}, @cite{Main} (for a root non library project) and
-@cite{Library_Name} (for a project extending a library project).
+@item
+Ada files with the prefix @code{a-} are children of @code{Ada}, as
+defined in Annex A.
-@menu
-* Project Hierarchy Extension::
+@geindex Annex B (in Ada reference Manual)
-@end menu
+@item
+Files with prefix @code{i-} are children of @code{Interfaces}, as
+defined in Annex B.
-@node Project Hierarchy Extension,,,Project Extension
-@anchor{gnat_ugn/gnat_project_manager project-hierarchy-extension}@anchor{17f}@anchor{gnat_ugn/gnat_project_manager id26}@anchor{180}
-@subsection Project Hierarchy Extension
+@geindex System (package in Ada Reference Manual)
+@item
+Files with prefix @code{s-} are children of @code{System}. This includes
+both language-defined children and GNAT run-time routines.
-One of the fundamental restrictions in project extension is the following:
-@strong{A project is not allowed to import directly or indirectly at the same time an extending project and one of its ancestors}.
+@geindex GNAT (package)
-For example, consider the following hierarchy of projects.
+@item
+Files with prefix @code{g-} are children of @code{GNAT}. These are useful
+general-purpose packages, fully documented in their specs. All
+the other @code{.c} files are modifications of common @code{gcc} files.
+@end itemize
-@example
-a.gpr contains package A1
-b.gpr, imports a.gpr and contains B1, which depends on A1
-c.gpr, imports b.gpr and contains C1, which depends on B1
-@end example
+@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{166}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{167}
+@subsection Getting Internal Debugging Information
-If we want to locally extend the packages @cite{A1} and @cite{C1}, we need to
-create several extending projects:
-@example
-a_ext.gpr which extends a.gpr, and overrides A1
-b_ext.gpr which extends b.gpr and imports a_ext.gpr
-c_ext.gpr which extends c.gpr, imports b_ext.gpr and overrides C1
-@end example
+Most compilers have internal debugging switches and modes. GNAT
+does also, except GNAT internal debugging switches and modes are not
+secret. A summary and full description of all the compiler and binder
+debug flags are in the file @code{debug.adb}. You must obtain the
+sources of the compiler to see the full detailed effects of these flags.
-@example
-project A_Ext extends "a.gpr" is
- for Source_Files use ("a1.adb", "a1.ads");
-end A_Ext;
+The switches that print the source of the program (reconstructed from
+the internal tree) are of general interest for user programs, as are the
+options to print
+the full internal tree, and the entity table (the symbol table
+information). The reconstructed source provides a readable version of the
+program after the front-end has completed analysis and expansion,
+and is useful when studying the performance of specific constructs.
+For example, constraint checks are indicated, complex aggregates
+are replaced with loops and assignments, and tasking primitives
+are replaced with run-time calls.
-with "a_ext.gpr";
-project B_Ext extends "b.gpr" is
-end B_Ext;
+@geindex traceback
-with "b_ext.gpr";
-project C_Ext extends "c.gpr" is
- for Source_Files use ("c1.adb");
-end C_Ext;
-@end example
+@geindex stack traceback
-The extension @code{b_ext.gpr} is required, even though we are not overriding
-any of the sources of @code{b.gpr} because otherwise @code{c_expr.gpr} would
-import @code{b.gpr} which itself knows nothing about @code{a_ext.gpr}.
+@geindex stack unwinding
-@geindex extends all (GNAT Project Manager)
+@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{168}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{169}
+@subsection Stack Traceback
-When extending a large system spanning multiple projects, it is often
-inconvenient to extend every project in the hierarchy that is impacted by a
-small change introduced in a low layer. In such cases, it is possible to create
-an @strong{implicit extension} of an entire hierarchy using @strong{extends all}
-relationship.
-When the project is extended using @cite{extends all} inheritance, all projects
-that are imported by it, both directly and indirectly, are considered virtually
-extended. That is, the project manager creates implicit projects
-that extend every project in the hierarchy; all these implicit projects do not
-control sources on their own and use the object directory of
-the "extending all" project.
+Traceback is a mechanism to display the sequence of subprogram calls that
+leads to a specified execution point in a program. Often (but not always)
+the execution point is an instruction at which an exception has been raised.
+This mechanism is also known as @emph{stack unwinding} because it obtains
+its information by scanning the run-time stack and recovering the activation
+records of all active subprograms. Stack unwinding is one of the most
+important tools for program debugging.
-It is possible to explicitly extend one or more projects in the hierarchy
-in order to modify the sources. These extending projects must be imported by
-the "extending all" project, which will replace the corresponding virtual
-projects with the explicit ones.
+The first entry stored in traceback corresponds to the deepest calling level,
+that is to say the subprogram currently executing the instruction
+from which we want to obtain the traceback.
-When building such a project hierarchy extension, the project manager will
-ensure that both modified sources and sources in implicit extending projects
-that depend on them are recompiled.
+Note that there is no runtime performance penalty when stack traceback
+is enabled, and no exception is raised during program execution.
-Thus, in our example we could create the following projects instead:
+@geindex traceback
+@geindex non-symbolic
-@example
-a_ext.gpr, extends a.gpr and overrides A1
-c_ext.gpr, "extends all" c.gpr, imports a_ext.gpr and overrides C1
-@end example
+@menu
+* Non-Symbolic Traceback::
+* Symbolic Traceback::
-@example
-project A_Ext extends "a.gpr" is
- for Source_Files use ("a1.adb", "a1.ads");
-end A_Ext;
+@end menu
-with "a_ext.gpr";
-project C_Ext extends all "c.gpr" is
- for Source_Files use ("c1.adb");
-end C_Ext;
-@end example
+@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback
+@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
-When building project @code{c_ext.gpr}, the entire modified project space is
-considered for recompilation, including the sources of @code{b.gpr} that are
-impacted by the changes in @cite{A1} and @cite{C1}.
-@node Aggregate Projects,Aggregate Library Projects,Project Extension,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager aggregate-projects}@anchor{16e}@anchor{gnat_ugn/gnat_project_manager id27}@anchor{181}
-@section Aggregate Projects
+Note: this feature is not supported on all platforms. See
+@code{GNAT.Traceback} spec in @code{g-traceb.ads}
+for a complete list of supported platforms.
+@subsubheading Tracebacks From an Unhandled Exception
-Aggregate projects are an extension of the project paradigm, and are
-meant to solve a few specific use cases that cannot be solved directly
-using standard projects. This section will go over a few of these use
-cases to try to explain what you can use aggregate projects for.
-@menu
-* Building all main programs from a single project tree::
-* Building a set of projects with a single command::
-* Define a build environment::
-* Performance improvements in builder::
-* Syntax of aggregate projects::
-* package Builder in aggregate projects::
+A runtime non-symbolic traceback is a list of addresses of call instructions.
+To enable this feature you must use the @code{-E}
+@code{gnatbind} option. With this option a stack traceback is stored as part
+of exception information. You can retrieve this information using the
+@code{addr2line} tool.
-@end menu
+Here is a simple example:
-@node Building all main programs from a single project tree,Building a set of projects with a single command,,Aggregate Projects
-@anchor{gnat_ugn/gnat_project_manager id28}@anchor{182}@anchor{gnat_ugn/gnat_project_manager building-all-main-programs-from-a-single-project-tree}@anchor{183}
-@subsection Building all main programs from a single project tree
+@quotation
+@example
+procedure STB is
-Most often, an application is organized into modules and submodules,
-which are very conveniently represented as a project tree or graph
-(the root project A @emph{with}s the projects for each modules (say B and C),
-which in turn @emph{with} projects for submodules.
+ procedure P1 is
+ begin
+ raise Constraint_Error;
+ end P1;
-Very often, modules will build their own executables (for testing
-purposes for instance), or libraries (for easier reuse in various
-contexts).
+ procedure P2 is
+ begin
+ P1;
+ end P2;
-However, if you build your project through @emph{gprbuild}, using a syntax similar to
+begin
+ P2;
+end STB;
+@end example
@example
-gprbuild -PA.gpr
-@end example
+$ gnatmake stb -bargs -E
+$ stb
-this will only rebuild the main programs of project A, not those of the
-imported projects B and C. Therefore you have to spawn several
-@emph{gprbuild} commands, one per project, to build all executables.
-This is a little inconvenient, but more importantly is inefficient
-because @emph{gprbuild} needs to do duplicate work to ensure that sources are
-up-to-date, and cannot easily compile things in parallel when using
-the -j switch.
+Execution terminated by unhandled exception
+Exception name: CONSTRAINT_ERROR
+Message: stb.adb:5
+Call stack traceback locations:
+0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
+@end example
+@end quotation
-Also libraries are always rebuilt when building a project.
+As we see the traceback lists a sequence of addresses for the unhandled
+exception @code{CONSTRAINT_ERROR} raised in procedure P1. It is easy to
+guess that this exception come from procedure P1. To translate these
+addresses into the source lines where the calls appear, the
+@code{addr2line} tool, described below, is invaluable. The use of this tool
+requires the program to be compiled with debug information.
-You could therefore define an aggregate project Agg that groups A, B
-and C. Then, when you build with
+@quotation
@example
-gprbuild -PAgg.gpr
-@end example
+$ gnatmake -g stb -bargs -E
+$ stb
-this will build all mains from A, B and C.
+Execution terminated by unhandled exception
+Exception name: CONSTRAINT_ERROR
+Message: stb.adb:5
+Call stack traceback locations:
+0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
-@example
-aggregate project Agg is
- for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
-end Agg;
-@end example
+$ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4
+ 0x4011f1 0x77e892a4
-If B or C do not define any main program (through their Main
-attribute), all their sources are built. When you do not group them
-in the aggregate project, only those sources that are needed by A
-will be built.
+00401373 at d:/stb/stb.adb:5
+0040138B at d:/stb/stb.adb:10
+0040139C at d:/stb/stb.adb:14
+00401335 at d:/stb/b~stb.adb:104
+004011C4 at /build/.../crt1.c:200
+004011F1 at /build/.../crt1.c:222
+77E892A4 in ?? at ??:0
+@end example
+@end quotation
-If you add a main to a project P not already explicitly referenced in the
-aggregate project, you will need to add "p.gpr" in the list of project
-files for the aggregate project, or the main will not be built when
-building the aggregate project.
+The @code{addr2line} tool has several other useful options:
-@node Building a set of projects with a single command,Define a build environment,Building all main programs from a single project tree,Aggregate Projects
-@anchor{gnat_ugn/gnat_project_manager building-a-set-of-projects-with-a-single-command}@anchor{184}@anchor{gnat_ugn/gnat_project_manager id29}@anchor{185}
-@subsection Building a set of projects with a single command
+@quotation
-One other case is when you have multiple applications and libraries
-that are built independently from each other (but can be built in
-parallel). For instance, you have a project tree rooted at A, and
-another one (which might share some subprojects) rooted at B.
+@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
-Using only @emph{gprbuild}, you could do
+@code{--functions}
-@example
-gprbuild -PA.gpr
-gprbuild -PB.gpr
-@end example
+@tab
-to build both. But again, @emph{gprbuild} has to do some duplicate work for
-those files that are shared between the two, and cannot truly build
-things in parallel efficiently.
+to get the function name corresponding to any location
-If the two projects are really independent, share no sources other
-than through a common subproject, and have no source files with a
-common basename, you could create a project C that imports A and
-B. But these restrictions are often too strong, and one has to build
-them independently. An aggregate project does not have these
-limitations and can aggregate two project trees that have common
-sources.
+@item
-This scenario is particularly useful in environments like VxWorks 653
-where the applications running in the multiple partitions can be built
-in parallel through a single @emph{gprbuild} command. This also works nicely
-with Annex E.
+@code{--demangle=gnat}
-@node Define a build environment,Performance improvements in builder,Building a set of projects with a single command,Aggregate Projects
-@anchor{gnat_ugn/gnat_project_manager id30}@anchor{186}@anchor{gnat_ugn/gnat_project_manager define-a-build-environment}@anchor{187}
-@subsection Define a build environment
+@tab
+to use the gnat decoding mode for the function names.
+Note that for binutils version 2.9.x the option is
+simply @code{--demangle}.
-The environment variables at the time you launch @emph{gprbuild}
-will influence the view these tools have of the project
-(PATH to find the compiler, ADA_PROJECT_PATH or GPR_PROJECT_PATH to find the
-projects, environment variables that are referenced in project files
-through the "external" built-in function, ...). Several command line switches
-can be used to override those (-X or -aP), but on some systems and
-with some projects, this might make the command line too long, and on
-all systems often make it hard to read.
+@end multitable
-An aggregate project can be used to set the environment for all
-projects built through that aggregate. One of the nice aspects is that
-you can put the aggregate project under configuration management, and
-make sure all your user have a consistent environment when
-building. The syntax looks like
@example
-aggregate project Agg is
- for Project_Files use ("A.gpr", "B.gpr");
- for Project_Path use ("../dir1", "../dir1/dir2");
- for External ("BUILD") use "PRODUCTION";
+$ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b
+ 0x40139c 0x401335 0x4011c4 0x4011f1
- package Builder is
- for Switches ("Ada") use ("-q");
- end Builder;
-end Agg;
+00401373 in stb.p1 at d:/stb/stb.adb:5
+0040138B in stb.p2 at d:/stb/stb.adb:10
+0040139C in stb at d:/stb/stb.adb:14
+00401335 in main at d:/stb/b~stb.adb:104
+004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200
+004011F1 in <mainCRTStartup> at /build/.../crt1.c:222
@end example
+@end quotation
-One of the often requested features in projects is to be able to
-reference external variables in @emph{with} declarations, as in
+From this traceback we can see that the exception was raised in
+@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{10d,,Running gnatbind}. The remaining entries are assorted runtime routines,
+and the output will vary from platform to platform.
-@example
-with external("SETUP") & "path/prj.gpr"; -- ILLEGAL
-project MyProject is
- ...
-end MyProject;
-@end example
+It is also possible to use @code{GDB} with these traceback addresses to debug
+the program. For example, we can break at a given code location, as reported
+in the stack traceback:
-For various reasons, this is not allowed. But using aggregate projects provide
-an elegant solution. For instance, you could use a project file like:
+@quotation
@example
-aggregate project Agg is
- for Project_Path use (external("SETUP") & "path");
- for Project_Files use ("myproject.gpr");
-end Agg;
-
-with "prj.gpr"; -- searched on Agg'Project_Path
-project MyProject is
- ...
-end MyProject;
+$ gdb -nw stb
@end example
+@end quotation
-@node Performance improvements in builder,Syntax of aggregate projects,Define a build environment,Aggregate Projects
-@anchor{gnat_ugn/gnat_project_manager performance-improvements-in-builder}@anchor{188}@anchor{gnat_ugn/gnat_project_manager id31}@anchor{189}
-@subsection Performance improvements in builder
-
+Furthermore, this feature is not implemented inside Windows DLL. Only
+the non-symbolic traceback is reported in this case.
-The loading of aggregate projects is optimized in @emph{gprbuild},
-so that all files are searched for only once on the disk
-(thus reducing the number of system calls and contributing to faster
-compilation times, especially on systems with sources on remote
-servers). As part of the loading, @emph{gprbuild}
-computes how and where a source file should be compiled, and even if it is
-found several times in the aggregated projects it will be compiled only
-once.
+@quotation
-Since there is no ambiguity as to which switches should be used, files
-can be compiled in parallel (through the usual -j switch) and this can
-be done while maximizing the use of CPUs (compared to launching
-multiple @emph{gprbuild} commands in parallel).
+@example
+(gdb) break *0x401373
+Breakpoint 1 at 0x401373: file stb.adb, line 5.
+@end example
+@end quotation
-@node Syntax of aggregate projects,package Builder in aggregate projects,Performance improvements in builder,Aggregate Projects
-@anchor{gnat_ugn/gnat_project_manager id32}@anchor{18a}@anchor{gnat_ugn/gnat_project_manager syntax-of-aggregate-projects}@anchor{18b}
-@subsection Syntax of aggregate projects
+It is important to note that the stack traceback addresses
+do not change when debug information is included. This is particularly useful
+because it makes it possible to release software without debug information (to
+minimize object size), get a field report that includes a stack traceback
+whenever an internal bug occurs, and then be able to retrieve the sequence
+of calls with the same program compiled with debug information.
+@subsubheading Tracebacks From Exception Occurrences
-An aggregate project follows the general syntax of project files. The
-recommended extension is still @code{.gpr}. However, a special
-@cite{aggregate} qualifier must be put before the keyword
-@cite{project}.
-An aggregate project cannot @emph{with} any other project (standard or
-aggregate), except an abstract project which can be used to share attribute
-values. Also, aggregate projects cannot be extended or imported though a
-@emph{with} clause by any other project. Building other aggregate projects from
-an aggregate project is done through the Project_Files attribute (see below).
+Non-symbolic tracebacks are obtained by using the @code{-E} binder argument.
+The stack traceback is attached to the exception information string, and can
+be retrieved in an exception handler within the Ada program, by means of the
+Ada facilities defined in @code{Ada.Exceptions}. Here is a simple example:
-An aggregate project does not have any source files directly (only
-through other standard projects). Therefore a number of the standard
-attributes and packages are forbidden in an aggregate project. Here is the
-(non exhaustive) list:
+@quotation
+@example
+with Ada.Text_IO;
+with Ada.Exceptions;
-@itemize *
+procedure STB is
-@item
-Languages
+ use Ada;
+ use Ada.Exceptions;
-@item
-Source_Files, Source_List_File and other attributes dealing with
-list of sources.
+ procedure P1 is
+ K : Positive := 1;
+ begin
+ K := K - 1;
+ exception
+ when E : others =>
+ Text_IO.Put_Line (Exception_Information (E));
+ end P1;
-@item
-Source_Dirs, Exec_Dir and Object_Dir
+ procedure P2 is
+ begin
+ P1;
+ end P2;
-@item
-Library_Dir, Library_Name and other library-related attributes
+begin
+ P2;
+end STB;
+@end example
+@end quotation
-@item
-Main
+This program will output:
-@item
-Roots
+@quotation
-@item
-Externally_Built
+@example
+$ stb
-@item
-Inherit_Source_Path
+Exception name: CONSTRAINT_ERROR
+Message: stb.adb:12
+Call stack traceback locations:
+0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4
+@end example
+@end quotation
-@item
-Excluded_Source_Dirs
+@subsubheading Tracebacks From Anywhere in a Program
-@item
-Locally_Removed_Files
-@item
-Excluded_Source_Files
+It is also possible to retrieve a stack traceback from anywhere in a
+program. For this you need to
+use the @code{GNAT.Traceback} API. This package includes a procedure called
+@code{Call_Chain} that computes a complete stack traceback, as well as useful
+display procedures described below. It is not necessary to use the
+@code{-E} @code{gnatbind} option in this case, because the stack traceback mechanism
+is invoked explicitly.
-@item
-Excluded_Source_List_File
+In the following example we compute a traceback at a specific location in
+the program, and we display it using @code{GNAT.Debug_Utilities.Image} to
+convert addresses to strings:
-@item
-Interfaces
-@end itemize
+@quotation
-The only package that is authorized (albeit optional) is
-Builder. Other packages (in particular Compiler, Binder and Linker)
-are forbidden.
+@example
+with Ada.Text_IO;
+with GNAT.Traceback;
+with GNAT.Debug_Utilities;
-The following three attributes can be used only in an aggregate project:
+procedure STB is
-@geindex Project_Files (GNAT Project Manager)
+ use Ada;
+ use GNAT;
+ use GNAT.Traceback;
-@strong{Project_Files}:
-
-@quotation
-
-This attribute is compulsory (or else we are not aggregating any project,
-and thus not doing anything). It specifies a list of @code{.gpr} files
-that are grouped in the aggregate. The list may be empty. The project
-files can be either other aggregate projects, or standard projects. When
-grouping standard projects, you can have both the root of a project tree
-(and you do not need to specify all its imported projects), and any project
-within the tree.
-
-Basically, the idea is to specify all those projects that have
-main programs you want to build and link, or libraries you want to
-build. You can even specify projects that do not use the Main
-attribute nor the @cite{Library_*} attributes, and the result will be to
-build all their source files (not just the ones needed by other
-projects).
-
-The file can include paths (absolute or relative). Paths are relative to
-the location of the aggregate project file itself (if you use a base name,
-we expect to find the .gpr file in the same directory as the aggregate
-project file). The environment variables @cite{ADA_PROJECT_PATH},
-@cite{GPR_PROJECT_PATH} and @cite{GPR_PROJECT_PATH_FILE} are not used to find
-the project files. The extension @code{.gpr} is mandatory, since this attribute
-contains file names, not project names.
-
-Paths can also include the @cite{"*"} and @cite{"**"} globbing patterns. The
-latter indicates that any subdirectory (recursively) will be
-searched for matching files. The latter (@cite{"**"}) can only occur at the
-last position in the directory part (ie @cite{"a/**/*.gpr"} is supported, but
-not @cite{"**/a/*.gpr"}). Starting the pattern with @cite{"**"} is equivalent
-to starting with @cite{"./**"}.
-
-For now, the pattern @cite{"*"} is only allowed in the filename part, not
-in the directory part. This is mostly for efficiency reasons to limit the
-number of system calls that are needed.
-
-Here are a few valid examples:
-
-@example
-for Project_Files use ("a.gpr", "subdir/b.gpr");
--- two specific projects relative to the directory of agg.gpr
-
-for Project_Files use ("/.gpr");
--- all projects recursively
-@end example
-@end quotation
-
-@geindex Project_Path (GNAT Project Manager)
-
-@strong{Project_Path}:
-
-@quotation
+ procedure P1 is
+ TB : Tracebacks_Array (1 .. 10);
+ -- We are asking for a maximum of 10 stack frames.
+ Len : Natural;
+ -- Len will receive the actual number of stack frames returned.
+ begin
+ Call_Chain (TB, Len);
-This attribute can be used to specify a list of directories in
-which to look for project files in @emph{with} declarations.
+ Text_IO.Put ("In STB.P1 : ");
-When you specify a project in Project_Files (say @cite{x/y/a.gpr}), and
-@cite{a.gpr} imports a project @cite{b.gpr}, only @cite{b.gpr} is searched in
-the project path. @cite{a.gpr} must be exactly at
-@cite{<dir of the aggregate>/x/y/a.gpr}.
+ for K in 1 .. Len loop
+ Text_IO.Put (Debug_Utilities.Image (TB (K)));
+ Text_IO.Put (' ');
+ end loop;
-This attribute, however, does not affect the search for the aggregated
-project files specified with @cite{Project_Files}.
+ Text_IO.New_Line;
+ end P1;
-Each aggregate project has its own @cite{Project_Path} (that is if
-@cite{agg1.gpr} includes @cite{agg2.gpr}, they can potentially both have a
-different @cite{Project_Path}).
+ procedure P2 is
+ begin
+ P1;
+ end P2;
-This project path is defined as the concatenation, in that order, of:
+begin
+ P2;
+end STB;
+@end example
+@example
+$ gnatmake -g stb
+$ stb
-@itemize *
+In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C#
+16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4#
+@end example
+@end quotation
-@item
-the current directory;
+You can then get further information by invoking the @code{addr2line}
+tool as described earlier (note that the hexadecimal addresses
+need to be specified in C format, with a leading '0x').
-@item
-followed by the command line -aP switches;
+@geindex traceback
+@geindex symbolic
-@item
-then the directories from the GPR_PROJECT_PATH and ADA_PROJECT_PATH environment
-variables;
+@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback
+@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{16c}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{16d}
+@subsubsection Symbolic Traceback
-@item
-then the directories from the Project_Path attribute;
-@item
-and finally the predefined directories.
-@end itemize
+A symbolic traceback is a stack traceback in which procedure names are
+associated with each code location.
-In the example above, agg2.gpr's project path is not influenced by
-the attribute agg1'Project_Path, nor is agg1 influenced by
-agg2'Project_Path.
-
-This can potentially lead to errors. Consider the following example:
-
-@example
---
--- +---------------+ +----------------+
--- | Agg1.gpr |-=--includes--=-->| Agg2.gpr |
--- | 'project_path| | 'project_path |
--- | | | |
--- +---------------+ +----------------+
--- : :
--- includes includes
--- : :
--- v v
--- +-------+ +---------+
--- | P.gpr |<---------- withs --------| Q.gpr |
--- +-------+---------\ +---------+
--- | |
--- withs |
--- | |
--- v v
--- +-------+ +---------+
--- | R.gpr | | R'.gpr |
--- +-------+ +---------+
-@end example
-
-When looking for p.gpr, both aggregates find the same physical file on
-the disk. However, it might happen that with their different project
-paths, both aggregate projects would in fact find a different r.gpr.
-Since we have a common project (p.gpr) "with"ing two different r.gpr,
-this will be reported as an error by the builder.
-
-Directories are relative to the location of the aggregate project file.
+Note that this feature is not supported on all platforms. See
+@code{GNAT.Traceback.Symbolic} spec in @code{g-trasym.ads} for a complete
+list of currently supported platforms.
-Example:
+Note that the symbolic traceback requires that the program be compiled
+with debug information. If it is not compiled with debug information
+only the non-symbolic information will be valid.
-@example
-for Project_Path use ("/usr/local/gpr", "gpr/");
-@end example
-@end quotation
+@subsubheading Tracebacks From Exception Occurrences
-@geindex External (GNAT Project Manager)
-@strong{External}:
+Here is an example:
@quotation
-This attribute can be used to set the value of environment
-variables as retrieved through the @cite{external} function
-in projects. It does not affect the environment variables
-themselves (so for instance you cannot use it to change the value
-of your PATH as seen from the spawned compiler).
-
-This attribute affects the external values as seen in the rest of
-the aggregate project, and in the aggregated projects.
+@example
+with Ada.Text_IO;
+with GNAT.Traceback.Symbolic;
-The exact value of external a variable comes from one of three
-sources (each level overrides the previous levels):
+procedure STB is
+ procedure P1 is
+ begin
+ raise Constraint_Error;
+ end P1;
-@itemize *
+ procedure P2 is
+ begin
+ P1;
+ end P2;
-@item
-An External attribute in aggregate project, for instance
-@cite{for External ("BUILD_MODE") use "DEBUG"};
+ procedure P3 is
+ begin
+ P2;
+ end P3;
-@item
-Environment variables.
-These override the value given by the attribute, so that
-users can override the value set in the (presumably shared
-with others team members) aggregate project.
+begin
+ P3;
+exception
+ when E : others =>
+ Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E));
+end STB;
+@end example
-@item
-The -X command line switch to @emph{gprbuild}.
-This always takes precedence.
-@end itemize
+@example
+$ gnatmake -g .\stb -bargs -E
+$ stb
-This attribute is only taken into account in the main aggregate
-project (i.e. the one specified on the command line to @emph{gprbuild}),
-and ignored in other aggregate projects. It is invalid
-in standard projects.
-The goal is to have a consistent value in all
-projects that are built through the aggregate, which would not
-be the case in the diamond case: A groups the aggregate
-projects B and C, which both (either directly or indirectly)
-build the project P. If B and C could set different values for
-the environment variables, we would have two different views of
-P, which in particular might impact the list of source files in P.
+0040149F in stb.p1 at stb.adb:8
+004014B7 in stb.p2 at stb.adb:13
+004014CF in stb.p3 at stb.adb:18
+004015DD in ada.stb at stb.adb:22
+00401461 in main at b~stb.adb:168
+004011C4 in __mingw_CRTStartup at crt1.c:200
+004011F1 in mainCRTStartup at crt1.c:222
+77E892A4 in ?? at ??:0
+@end example
@end quotation
-@node package Builder in aggregate projects,,Syntax of aggregate projects,Aggregate Projects
-@anchor{gnat_ugn/gnat_project_manager package-builder-in-aggregate-projects}@anchor{18c}@anchor{gnat_ugn/gnat_project_manager id33}@anchor{18d}
-@subsection package Builder in aggregate projects
-
+In the above example the @code{.\} syntax in the @code{gnatmake} command
+is currently required by @code{addr2line} for files that are in
+the current working directory.
+Moreover, the exact sequence of linker options may vary from platform
+to platform.
+The above @code{-largs} section is for Windows platforms. By contrast,
+under Unix there is no need for the @code{-largs} section.
+Differences across platforms are due to details of linker implementation.
-As mentioned above, only the package Builder can be specified in
-an aggregate project. In this package, only the following attributes
-are valid:
+@subsubheading Tracebacks From Anywhere in a Program
-@geindex Switches (GNAT Project Manager)
-@strong{Switches}:
+It is possible to get a symbolic stack traceback
+from anywhere in a program, just as for non-symbolic tracebacks.
+The first step is to obtain a non-symbolic
+traceback, and then call @code{Symbolic_Traceback} to compute the symbolic
+information. Here is an example:
@quotation
-This attribute gives the list of switches to use for @emph{gprbuild}.
-Because no mains can be specified for aggregate projects, the only possible
-index for attribute @cite{Switches} is @cite{others}. All other indexes will
-be ignored.
-
-Example:
-
@example
-for Switches (others) use ("-v", "-k", "-j8");
-@end example
-
-These switches are only read from the main aggregate project (the
-one passed on the command line), and ignored in all other aggregate
-projects or projects.
-
-It can only contain builder switches, not compiler switches.
-@end quotation
+with Ada.Text_IO;
+with GNAT.Traceback;
+with GNAT.Traceback.Symbolic;
-@geindex Global_Compilation_Switches (GNAT Project Manager)
+procedure STB is
-@strong{Global_Compilation_Switches}
+ use Ada;
+ use GNAT.Traceback;
+ use GNAT.Traceback.Symbolic;
-@quotation
+ procedure P1 is
+ TB : Tracebacks_Array (1 .. 10);
+ -- We are asking for a maximum of 10 stack frames.
+ Len : Natural;
+ -- Len will receive the actual number of stack frames returned.
+ begin
+ Call_Chain (TB, Len);
+ Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len)));
+ end P1;
-This attribute gives the list of compiler switches for the various
-languages. For instance,
+ procedure P2 is
+ begin
+ P1;
+ end P2;
-@example
-for Global_Compilation_Switches ("Ada") use ("O1", "-g");
-for Global_Compilation_Switches ("C") use ("-O2");
+begin
+ P2;
+end STB;
@end example
+@end quotation
-This attribute is only taken into account in the aggregate project
-specified on the command line, not in other aggregate projects.
-
-In the projects grouped by that aggregate, the attribute
-Builder.Global_Compilation_Switches is also ignored. However, the
-attribute Compiler.Default_Switches will be taken into account (but
-that of the aggregate have higher priority). The attribute
-Compiler.Switches is also taken into account and can be used to
-override the switches for a specific file. As a result, it always
-has priority.
-
-The rules are meant to avoid ambiguities when compiling. For
-instance, aggregate project Agg groups the projects A and B, that
-both depend on C. Here is an extra for all of these projects:
-
-@example
-aggregate project Agg is
- for Project_Files use ("a.gpr", "b.gpr");
- package Builder is
- for Global_Compilation_Switches ("Ada") use ("-O2");
- end Builder;
-end Agg;
-
-with "c.gpr";
-project A is
- package Builder is
- for Global_Compilation_Switches ("Ada") use ("-O1");
- -- ignored
- end Builder;
+@subsubheading Automatic Symbolic Tracebacks
- package Compiler is
- for Default_Switches ("Ada")
- use ("-O1", "-g");
- for Switches ("a_file1.adb")
- use ("-O0");
- end Compiler;
-end A;
-with "c.gpr";
-project B is
- package Compiler is
- for Default_Switches ("Ada") use ("-O0");
- end Compiler;
-end B;
+Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as
+in @code{gprbuild -g ... -bargs -Es}).
+This will cause the Exception_Information to contain a symbolic traceback,
+which will also be printed if an unhandled exception terminates the
+program.
-project C is
- package Compiler is
- for Default_Switches ("Ada")
- use ("-O3",
- "-gnatn");
- for Switches ("c_file1.adb")
- use ("-O0", "-g");
- end Compiler;
-end C;
-@end example
+@node Pretty-Printers for the GNAT runtime,,Stack Traceback,Running and Debugging Ada Programs
+@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
-then the following switches are used:
+As discussed in @cite{Calling User-Defined Subprograms}, GDB's
+@code{print} command only knows about the physical layout of program data
+structures and therefore normally displays only low-level dumps, which
+are often hard to understand.
-@itemize *
+An example of this is when trying to display the contents of an Ada
+standard container, such as @code{Ada.Containers.Ordered_Maps.Map}:
-@item
-all files from project A except a_file1.adb are compiled
-with "-O2 -g", since the aggregate project has priority.
+@quotation
-@item
-the file a_file1.adb is compiled with
-"-O0", since the Compiler.Switches has priority
+@example
+with Ada.Containers.Ordered_Maps;
-@item
-all files from project B are compiled with
-"-O2", since the aggregate project has priority
+procedure PP is
+ package Int_To_Nat is
+ new Ada.Containers.Ordered_Maps (Integer, Natural);
-@item
-all files from C are compiled with "-O2 -gnatn", except for
-c_file1.adb which is compiled with "-O0 -g"
-@end itemize
+ Map : Int_To_Nat.Map;
+begin
+ Map.Insert (1, 10);
+ Map.Insert (2, 20);
+ Map.Insert (3, 30);
-Even though C is seen through two paths (through A and through
-B), the switches used by the compiler are unambiguous.
+ Map.Clear; -- BREAK HERE
+end PP;
+@end example
@end quotation
-@geindex Global_Configuration_Pragmas (GNAT Project Manager)
-
-@strong{Global_Configuration_Pragmas}
+When this program is built with debugging information and run under
+GDB up to the @code{Map.Clear} statement, trying to print @code{Map} will
+yield information that is only relevant to the developers of our standard
+containers:
@quotation
-This attribute can be used to specify a file containing
-configuration pragmas, to be passed to the Ada compiler. Since we
-ignore the package Builder in other aggregate projects and projects,
-only those pragmas defined in the main aggregate project will be
-taken into account.
-
-Projects can locally add to those by using the
-@cite{Compiler.Local_Configuration_Pragmas} attribute if they need.
+@example
+(gdb) print map
+$1 = (
+ tree => (
+ first => 0x64e010,
+ last => 0x64e070,
+ root => 0x64e040,
+ length => 3,
+ tc => (
+ busy => 0,
+ lock => 0
+ )
+ )
+)
+@end example
@end quotation
-@geindex Global_Config_File (GNAT Project Manager)
-
-@strong{Global_Config_File}
+Fortunately, GDB has a feature called pretty-printers@footnote{http://docs.adacore.com/gdb-docs/html/gdb.html#Pretty_002dPrinter-Introduction},
+which allows customizing how GDB displays data structures. The GDB
+shipped with GNAT embeds such pretty-printers for the most common
+containers in the standard library. To enable them, either run the
+following command manually under GDB or add it to your @code{.gdbinit} file:
@quotation
-This attribute, indexed with a language name, can be used to specify a config
-when compiling sources of the language. For Ada, these files are configuration
-pragmas files.
+@example
+python import gnatdbg; gnatdbg.setup()
+@end example
@end quotation
-For projects that are built through the aggregate, the package Builder
-is ignored, except for the Executable attribute which specifies the
-name of the executables resulting from the link of the main programs, and
-for the Executable_Suffix.
-
-@node Aggregate Library Projects,Project File Reference,Aggregate Projects,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager id34}@anchor{18e}@anchor{gnat_ugn/gnat_project_manager aggregate-library-projects}@anchor{18f}
-@section Aggregate Library Projects
-
-
-Aggregate library projects make it possible to build a single library
-using object files built using other standard or library
-projects. This gives the flexibility to describe an application as
-having multiple modules (a GUI, database access, ...) using different
-project files (so possibly built with different compiler options) and
-yet create a single library (static or relocatable) out of the
-corresponding object files.
-
-@menu
-* Building aggregate library projects::
-* Syntax of aggregate library projects::
-
-@end menu
-
-@node Building aggregate library projects,Syntax of aggregate library projects,,Aggregate Library Projects
-@anchor{gnat_ugn/gnat_project_manager building-aggregate-library-projects}@anchor{190}@anchor{gnat_ugn/gnat_project_manager id35}@anchor{191}
-@subsection Building aggregate library projects
+Once this is done, GDB's @code{print} command will automatically use
+these pretty-printers when appropriate. Using the previous example:
-
-For example, we can define an aggregate project Agg that groups A, B
-and C:
+@quotation
@example
-aggregate library project Agg is
- for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
- for Library_Name use ("agg");
- for Library_Dir use ("lagg");
-end Agg;
+(gdb) print map
+$1 = pp.int_to_nat.map of length 3 = @{
+ [1] = 10,
+ [2] = 20,
+ [3] = 30
+@}
@end example
+@end quotation
-Then, when you build with:
+Pretty-printers are invoked each time GDB tries to display a value,
+including when displaying the arguments of a called subprogram (in
+GDB's @code{backtrace} command) or when printing the value returned by a
+function (in GDB's @code{finish} command).
+
+To display a value without involving pretty-printers, @code{print} can be
+invoked with its @code{/r} option:
+
+@quotation
@example
-gprbuild agg.gpr
+(gdb) print/r map
+$1 = (
+ tree => (...
@end example
+@end quotation
-This will build all units from projects A, B and C and will create a
-static library named @code{libagg.a} in the @code{lagg}
-directory. An aggregate library project has the same set of
-restriction as a standard library project.
+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.
-Note that a shared aggregate library project cannot aggregate a
-static library project. In platforms where a compiler option is
-required to create relocatable object files, a Builder package in the
-aggregate library project may be used:
+@geindex Profiling
-@example
-aggregate library project Agg is
- for Project_Files use ("a.gpr", "b.gpr", "c.gpr");
- for Library_Name use ("agg");
- for Library_Dir use ("lagg");
- for Library_Kind use "relocatable";
+@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
- package Builder is
- for Global_Compilation_Switches ("Ada") use ("-fPIC");
- end Builder;
-end Agg;
-@end example
-With the above aggregate library Builder package, the @cite{-fPIC}
-option will be passed to the compiler when building any source code
-from projects @code{a.gpr}, @code{b.gpr} and @code{c.gpr}.
+This section describes how to use the @code{gprof} profiler tool on Ada programs.
-@node Syntax of aggregate library projects,,Building aggregate library projects,Aggregate Library Projects
-@anchor{gnat_ugn/gnat_project_manager syntax-of-aggregate-library-projects}@anchor{192}@anchor{gnat_ugn/gnat_project_manager id36}@anchor{193}
-@subsection Syntax of aggregate library projects
+@geindex gprof
+@geindex Profiling
-An aggregate library project follows the general syntax of project
-files. The recommended extension is still @code{.gpr}. However, a special
-@cite{aggregate library} qualifier must be put before the keyword
-@cite{project}.
+@menu
+* Profiling an Ada Program with gprof::
-An aggregate library project cannot @emph{with} any other project
-(standard or aggregate), except an abstract project which can be used
-to share attribute values.
+@end menu
-An aggregate library project does not have any source files directly (only
-through other standard projects). Therefore a number of the standard
-attributes and packages are forbidden in an aggregate library
-project. Here is the (non exhaustive) list:
+@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
-@itemize *
+This section is not meant to be an exhaustive documentation of @code{gprof}.
+Full documentation for it can be found in the @cite{GNU Profiler User's Guide}
+documentation that is part of this GNAT distribution.
-@item
-Languages
+Profiling a program helps determine the parts of a program that are executed
+most often, and are therefore the most time-consuming.
-@item
-Source_Files, Source_List_File and other attributes dealing with
-list of sources.
+@code{gprof} is the standard GNU profiling tool; it has been enhanced to
+better handle Ada programs and multitasking.
+It is currently supported on the following platforms
-@item
-Source_Dirs, Exec_Dir and Object_Dir
-@item
-Main
+@itemize *
@item
-Roots
+linux x86/x86_64
@item
-Externally_Built
+windows x86
+@end itemize
-@item
-Inherit_Source_Path
+In order to profile a program using @code{gprof}, several steps are needed:
-@item
-Excluded_Source_Dirs
-@item
-Locally_Removed_Files
+@enumerate
@item
-Excluded_Source_Files
+Instrument the code, which requires a full recompilation of the project with the
+proper switches.
@item
-Excluded_Source_List_File
+Execute the program under the analysis conditions, i.e. with the desired
+input.
@item
-Interfaces
-@end itemize
-
-The only package that is authorized (albeit optional) is Builder.
-
-The Project_Files attribute (See @ref{16e,,Aggregate Projects}) is used to
-described the aggregated projects whose object files have to be
-included into the aggregate library. The environment variables
-@cite{ADA_PROJECT_PATH}, @cite{GPR_PROJECT_PATH} and
-@cite{GPR_PROJECT_PATH_FILE} are not used to find the project files.
-
-@node Project File Reference,,Aggregate Library Projects,GNAT Project Manager
-@anchor{gnat_ugn/gnat_project_manager id37}@anchor{194}@anchor{gnat_ugn/gnat_project_manager project-file-reference}@anchor{14d}
-@section Project File Reference
-
+Analyze the results using the @code{gprof} tool.
+@end enumerate
-This section describes the syntactic structure of project files, the various
-constructs that can be used. Finally, it ends with a summary of all available
-attributes.
+The following sections detail the different steps, and indicate how
+to interpret the results.
@menu
-* Project Declaration::
-* Qualified Projects::
-* Declarations::
-* Packages::
-* Expressions::
-* External Values::
-* Typed String Declaration::
-* Variables::
-* Case Constructions::
-* Attributes::
+* Compilation for profiling::
+* Program execution::
+* Running gprof::
+* Interpretation of profiling results::
@end menu
-@node Project Declaration,Qualified Projects,,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager id38}@anchor{195}@anchor{gnat_ugn/gnat_project_manager project-declaration}@anchor{196}
-@subsection Project Declaration
+@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof
+@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
-Project files have an Ada-like syntax. The minimal project file is:
+@geindex -pg (gcc)
+@geindex for profiling
-@example
-project Empty is
-end Empty;
-@end example
+@geindex -pg (gnatlink)
+@geindex for profiling
-The identifier @cite{Empty} is the name of the project.
-This project name must be present after the reserved
-word @cite{end} at the end of the project file, followed by a semi-colon.
+In order to profile a program the first step is to tell the compiler
+to generate the necessary profiling information. The compiler switch to be used
+is @code{-pg}, which must be added to other compilation switches. This
+switch needs to be specified both during compilation and link stages, and can
+be specified once when using gnatmake:
-@strong{Identifiers} (i.e., the user-defined names such as project or variable names)
-have the same syntax as Ada identifiers: they must start with a letter,
-and be followed by zero or more letters, digits or underscore characters;
-it is also illegal to have two underscores next to each other. Identifiers
-are always case-insensitive ("Name" is the same as "name").
+@quotation
@example
-simple_name ::= identifier
-name ::= simple_name @{ . simple_name @}
+$ gnatmake -f -pg -P my_project
@end example
+@end quotation
-@strong{Strings} are used for values of attributes or as indexes for these
-attributes. They are in general case sensitive, except when noted
-otherwise (in particular, strings representing file names will be case
-insensitive on some systems, so that "file.adb" and "File.adb" both
-represent the same file).
-
-@strong{Reserved words} are the same as for standard Ada 95, and cannot
-be used for identifiers. In particular, the following words are currently
-used in project files, but others could be added later on. In bold are the
-extra reserved words in project files:
-@code{all}, @code{at}, @code{case}, @code{end}, @code{for}, @code{is}, @code{limited},
-@code{null}, @code{others}, @code{package}, @code{renames}, @code{type}, @code{use}, @code{when},
-@code{with}, @strong{extends}, @strong{external}, @strong{project}.
+Note that only the objects that were compiled with the @code{-pg} switch will
+be profiled; if you need to profile your whole project, use the @code{-f}
+gnatmake switch to force full recompilation.
-@strong{Comments} in project files have the same syntax as in Ada, two consecutive
-hyphens through the end of the line.
+@node Program execution,Running gprof,Compilation for profiling,Profiling an Ada Program with gprof
+@anchor{gnat_ugn/gnat_and_program_execution program-execution}@anchor{175}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{176}
+@subsubsection Program execution
-A project may be an @strong{independent project}, entirely defined by a single
-project file. Any source file in an independent project depends only
-on the predefined library and other source files in the same project.
-But a project may also depend on other projects, either by importing them
-through @strong{with clauses}, or by @strong{extending} at most one other project. Both
-types of dependency can be used in the same project.
-A path name denotes a project file. It can be absolute or relative.
-An absolute path name includes a sequence of directories, in the syntax of
-the host operating system, that identifies uniquely the project file in the
-file system. A relative path name identifies the project file, relative
-to the directory that contains the current project, or relative to a
-directory listed in the environment variables ADA_PROJECT_PATH and
-GPR_PROJECT_PATH. Path names are case sensitive if file names in the host
-operating system are case sensitive. As a special case, the directory
-separator can always be "/" even on Windows systems, so that project files
-can be made portable across architectures.
-The syntax of the environment variables ADA_PROJECT_PATH and
-GPR_PROJECT_PATH is a list of directory names separated by colons on UNIX and
-semicolons on Windows.
+Once the program has been compiled for profiling, you can run it as usual.
-A given project name can appear only once in a context clause.
+The only constraint imposed by profiling is that the program must terminate
+normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
+properly analyzed.
-It is illegal for a project imported by a context clause to refer, directly
-or indirectly, to the project in which this context clause appears (the
-dependency graph cannot contain cycles), except when one of the with clauses
-in the cycle is a @strong{limited with}.
+Once the program completes execution, a data file called @code{gmon.out} is
+generated in the directory where the program was launched from. If this file
+already exists, it will be overwritten.
-@example
-with "other_project.gpr";
-project My_Project extends "extended.gpr" is
-end My_Project;
-@end example
+@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{177}@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{178}
+@subsubsection Running gprof
-These dependencies form a @strong{directed graph}, potentially cyclic when using
-@strong{limited with}. The subgraph reflecting the @strong{extends} relations is a tree.
-A project's @strong{immediate sources} are the source files directly defined by
-that project, either implicitly by residing in the project source directories,
-or explicitly through any of the source-related attributes.
-More generally, a project's @strong{sources} are the immediate sources of the
-project together with the immediate sources (unless overridden) of any project
-on which it depends directly or indirectly.
+The @code{gprof} tool is called as follow:
-A @strong{project hierarchy} can be created, where projects are children of
-other projects. The name of such a child project must be @cite{Parent.Child},
-where @cite{Parent} is the name of the parent project. In particular, this
-makes all @emph{with} clauses of the parent project automatically visible
-in the child project.
+@quotation
@example
-project ::= context_clause project_declaration
-
-context_clause ::= @{with_clause@}
-with_clause ::= *with* path_name @{ , path_name @} ;
-path_name ::= string_literal
-
-project_declaration ::= simple_project_declaration | project_extension
-simple_project_declaration ::=
- project <project_>name is
- @{declarative_item@}
- end <project_>simple_name;
+$ gprof my_prog gmon.out
@end example
+@end quotation
-@node Qualified Projects,Declarations,Project Declaration,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager qualified-projects}@anchor{173}@anchor{gnat_ugn/gnat_project_manager id39}@anchor{197}
-@subsection Qualified Projects
-
-
-Before the reserved @cite{project}, there may be one or two @strong{qualifiers}, that
-is identifiers or reserved words, to qualify the project.
-The current list of qualifiers is:
-
-
-@table @asis
-
-@item @strong{abstract}:
-
-Qualifies a project with no sources.
-Such a project must either have no declaration of attributes @cite{Source_Dirs},
-@cite{Source_Files}, @cite{Languages} or @cite{Source_List_File}, or one of
-@cite{Source_Dirs}, @cite{Source_Files}, or @cite{Languages} must be declared
-as empty. If it extends another project, the project it extends must also be a
-qualified abstract project.
-
-@item @strong{standard}:
-
-A standard project is a non library project with sources.
-This is the default (implicit) qualifier.
-
-@item @strong{aggregate}:
-
-A project whose sources are aggregated from other project files.
-
-@item @strong{aggregate library}:
-
-A library whose sources are aggregated from other project
-or library project files.
-
-@item @strong{library}:
-
-A library project must declare both attributes
-Library_Name` and @cite{Library_Dir}.
-
-@item @strong{configuration}:
+or simply:
-A configuration project cannot be in a project tree.
-It describes compilers and other tools to @emph{gprbuild}.
-@end table
+@quotation
-@node Declarations,Packages,Qualified Projects,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager declarations}@anchor{198}@anchor{gnat_ugn/gnat_project_manager id40}@anchor{199}
-@subsection Declarations
+@example
+$ gprof my_prog
+@end example
+@end quotation
+The complete form of the gprof command line is the following:
-Declarations introduce new entities that denote types, variables, attributes,
-and packages. Some declarations can only appear immediately within a project
-declaration. Others can appear within a project or within a package.
+@quotation
@example
-declarative_item ::= simple_declarative_item
- | typed_string_declaration
- | package_declaration
-
-simple_declarative_item ::= variable_declaration
- | typed_variable_declaration
- | attribute_declaration
- | case_construction
- | empty_declaration
-
-empty_declaration ::= *null* ;
+$ gprof [switches] [executable [data-file]]
@end example
+@end quotation
-An empty declaration is allowed anywhere a declaration is allowed. It has
-no effect.
-
-@node Packages,Expressions,Declarations,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager packages}@anchor{153}@anchor{gnat_ugn/gnat_project_manager id41}@anchor{19a}
-@subsection Packages
-
+@code{gprof} supports numerous switches. The order of these
+switch does not matter. The full list of options can be found in
+the GNU Profiler User's Guide documentation that comes with this documentation.
-A project file may contain @strong{packages}, that group attributes (typically
-all the attributes that are used by one of the GNAT tools).
+The following is the subset of those switches that is most relevant:
-A package with a given name may only appear once in a project file.
-The following packages are currently supported in project files
-(See @ref{152,,Attributes} for the list of attributes that each can contain).
+@geindex --demangle (gprof)
@table @asis
-@item @emph{Binder}
-
-This package specifies characteristics useful when invoking the binder either
-directly via the @emph{gnat} driver or when using @emph{gprbuild}.
-See @ref{15d,,Main Subprograms}.
-
-@item @emph{Builder}
+@item @code{--demangle[=@emph{style}]}, @code{--no-demangle}
-This package specifies the compilation options used when building an
-executable or a library for a project. Most of the options should be
-set in one of @cite{Compiler}, @cite{Binder} or @cite{Linker} packages,
-but there are some general options that should be defined in this
-package. See @ref{15d,,Main Subprograms}, and @ref{162,,Executable File Names} in
-particular.
+These options control whether symbol names should be demangled when
+printing output. The default is to demangle C++ symbols. The
+@code{--no-demangle} option may be used to turn off demangling. Different
+compilers have different mangling styles. The optional demangling style
+argument can be used to choose an appropriate demangling style for your
+compiler, in particular Ada symbols generated by GNAT can be demangled using
+@code{--demangle=gnat}.
@end table
+@geindex -e (gprof)
@table @asis
-@item @emph{Clean}
-
-This package specifies the options used when cleaning a project or a project
-tree using the tools @emph{gnatclean} or @emph{gprclean}.
-
-@item @emph{Compiler}
-
-This package specifies the compilation options used by the compiler for
-each languages. See @ref{15e,,Tools Options in Project Files}.
-
-@item @emph{Cross_Reference}
+@item @code{-e @emph{function_name}}
-This package specifies the options used when calling the library tool
-@emph{gnatxref} via the @emph{gnat} driver. Its attributes
-@strong{Default_Switches} and @strong{Switches} have the same semantics as for the
-package @cite{Builder}.
+The @code{-e @emph{function}} option tells @code{gprof} not to print
+information about the function @code{function_name} (and its
+children...) in the call graph. The function will still be listed
+as a child of any functions that call it, but its index number will be
+shown as @code{[not printed]}. More than one @code{-e} option may be
+given; only one @code{function_name} may be indicated with each @code{-e}
+option.
@end table
+@geindex -E (gprof)
@table @asis
-@item @emph{Finder}
-
-This package specifies the options used when calling the search tool
-@emph{gnatfind} via the @emph{gnat} driver. Its attributes
-@strong{Default_Switches} and @strong{Switches} have the same semantics as for the
-package @cite{Builder}.
-
-@item @emph{Gnatls}
+@item @code{-E @emph{function_name}}
-This package specifies the options to use when invoking @emph{gnatls}
-via the @emph{gnat} driver.
+The @code{-E @emph{function}} option works like the @code{-e} option, but
+execution time spent in the function (and children who were not called from
+anywhere else), will not be used to compute the percentages-of-time for
+the call graph. More than one @code{-E} option may be given; only one
+@code{function_name} may be indicated with each @code{-E`} option.
@end table
+@geindex -f (gprof)
@table @asis
-@item @emph{IDE}
-
-This package specifies the options used when starting an integrated
-development environment, for instance @emph{GPS} or @emph{Gnatbench}.
-
-@item @emph{Install}
-
-This package specifies the options used when installing a project
-with @emph{gprinstall}. See @ref{168,,Installation}.
-
-@item @emph{Linker}
+@item @code{-f @emph{function_name}}
-This package specifies the options used by the linker.
-See @ref{15d,,Main Subprograms}.
+The @code{-f @emph{function}} option causes @code{gprof} to limit the
+call graph to the function @code{function_name} and its children (and
+their children...). More than one @code{-f} option may be given;
+only one @code{function_name} may be indicated with each @code{-f}
+option.
@end table
+@geindex -F (gprof)
@table @asis
-@item @emph{Naming}
-
-@quotation
-
-This package specifies the naming conventions that apply
-to the source files in a project. In particular, these conventions are
-used to automatically find all source files in the source directories,
-or given a file name to find out its language for proper processing.
-See @ref{14b,,Naming Schemes}.
-@end quotation
-
-
-@item @emph{Remote}
-
-This package is used by @emph{gprbuild} to describe how distributed
-compilation should be done.
+@item @code{-F @emph{function_name}}
-@item @emph{Stack}
+The @code{-F @emph{function}} option works like the @code{-f} option, but
+only time spent in the function and its children (and their
+children...) will be used to determine total-time and
+percentages-of-time for the call graph. More than one @code{-F} option
+may be given; only one @code{function_name} may be indicated with each
+@code{-F} option. The @code{-F} option overrides the @code{-E} option.
+@end table
-This package specifies the options used when calling the tool
-@emph{gnatstack} via the @emph{gnat} driver. Its attributes
-@strong{Default_Switches} and @strong{Switches} have the same semantics as for the
-package @cite{Builder}.
+@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof
+@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
-@item @emph{Synchronize}
-This package specifies the options used when calling the tool
-@emph{gnatsync} via the @emph{gnat} driver.
-@end table
+The results of the profiling analysis are represented by two arrays: the
+'flat profile' and the 'call graph'. Full documentation of those outputs
+can be found in the GNU Profiler User's Guide.
-In its simplest form, a package may be empty:
+The flat profile shows the time spent in each function of the program, and how
+many time it has been called. This allows you to locate easily the most
+time-consuming functions.
-@example
-project Simple is
- package Builder is
- end Builder;
-end Simple;
-@end example
+The call graph shows, for each subprogram, the subprograms that call it,
+and the subprograms that it calls. It also provides an estimate of the time
+spent in each of those callers/called subprograms.
-A package may contain @strong{attribute declarations},
-@strong{variable declarations} and @strong{case constructions}, as will be
-described below.
+@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
-When there is ambiguity between a project name and a package name,
-the name always designates the project. To avoid possible confusion, it is
-always a good idea to avoid naming a project with one of the
-names allowed for packages or any name that starts with @cite{gnat}.
-A package can also be defined by a @strong{renaming declaration}. The new package
-renames a package declared in a different project file, and has the same
-attributes as the package it renames. The name of the renamed package
-must be the same as the name of the renaming package. The project must
-contain a package declaration with this name, and the project
-must appear in the context clause of the current project, or be its parent
-project. It is not possible to add or override attributes to the renaming
-project. If you need to do so, you should use an @strong{extending declaration}
-(see below).
+@geindex Improving performance
-Packages that are renamed in other project files often come from project files
-that have no sources: they are just used as templates. Any modification in the
-template will be reflected automatically in all the project files that rename
-a package from the template. This is a very common way to share settings
-between projects.
+This section presents several topics related to program performance.
+It first describes some of the tradeoffs that need to be considered
+and some of the techniques for making your program run faster.
-Finally, a package can also be defined by an @strong{extending declaration}. This is
-similar to a @strong{renaming declaration}, except that it is possible to add or
-override attributes.
+It then documents the unused subprogram/data elimination feature,
+which can reduce the size of program executables.
-@example
-package_declaration ::= package_spec | package_renaming | package_extension
-package_spec ::=
- package <package_>simple_name is
- @{simple_declarative_item@}
- end package_identifier ;
-package_renaming ::==
- package <package_>simple_name renames <project_>simple_name.package_identifier ;
-package_extension ::==
- package <package_>simple_name extends <project_>simple_name.package_identifier is
- @{simple_declarative_item@}
- end package_identifier ;
-@end example
+@menu
+* Performance Considerations::
+* Text_IO Suggestions::
+* Reducing Size of Executables with Unused Subprogram/Data Elimination::
-@node Expressions,External Values,Packages,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager expressions}@anchor{19b}@anchor{gnat_ugn/gnat_project_manager id42}@anchor{19c}
-@subsection Expressions
+@end menu
+@node Performance Considerations,Text_IO Suggestions,,Improving Performance
+@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{17c}@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{17d}
+@subsection Performance Considerations
-An expression is any value that can be assigned to an attribute or a
-variable. It is either a literal value, or a construct requiring runtime
-computation by the project manager. In a project file, the computed value of
-an expression is either a string or a list of strings.
-A string value is one of:
+The GNAT system provides a number of options that allow a trade-off
+between
@itemize *
@item
-A literal string, for instance @cite{"comm/my_proj.gpr"}
-
-@item
-The name of a variable that evaluates to a string (see @ref{155,,Variables})
+performance of the generated code
@item
-The name of an attribute that evaluates to a string (see @ref{152,,Attributes})
+speed of compilation
@item
-An external reference (see @ref{154,,External Values})
+minimization of dependences and recompilation
@item
-A concatenation of the above, as in @cite{"prefix_" & Var}.
+the degree of run-time checking.
@end itemize
-A list of strings is one of the following:
+The defaults (if no options are selected) aim at improving the speed
+of compilation and minimizing dependences, at the expense of performance
+of the generated code:
@itemize *
@item
-A parenthesized comma-separated list of zero or more string expressions, for
-instance @cite{(File_Name@comma{} "gnat.adc"@comma{} File_Name & ".orig")} or @cite{()}.
+no optimization
@item
-The name of a variable that evaluates to a list of strings
+no inlining of subprogram calls
@item
-The name of an attribute that evaluates to a list of strings
+all run-time checks enabled except overflow and elaboration checks
+@end itemize
-@item
-A concatenation of a list of strings and a string (as defined above), for
-instance @cite{("A"@comma{} "B") & "C"}
+These options are suitable for most program development purposes. This
+section describes how you can modify these choices, and also provides
+some guidelines on debugging optimized code.
-@item
-A concatenation of two lists of strings
-@end itemize
+@menu
+* Controlling Run-Time Checks::
+* Use of Restrictions::
+* Optimization Levels::
+* Debugging Optimized Code::
+* Inlining of Subprograms::
+* Floating Point Operations::
+* Vectorization of loops::
+* Other Optimization Switches::
+* Optimization and Strict Aliasing::
+* Aliased Variables and Optimization::
+* Atomic Variables and Optimization::
+* Passive Task Optimization::
-The following is the grammar for expressions
+@end menu
-@example
-string_literal ::= "@{string_element@}" -- Same as Ada
-string_expression ::= string_literal
- | *variable_*name
- | external_value
- | attribute_reference
- | ( string_expression @{ & string_expression @} )
-string_list ::= ( string_expression @{ , string_expression @} )
- | *string_variable*_name
- | *string_*attribute_reference
-term ::= string_expression | string_list
-expression ::= term @{ & term @} -- Concatenation
-@end example
+@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations
+@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
-Concatenation involves strings and list of strings. As soon as a list of
-strings is involved, the result of the concatenation is a list of strings. The
-following Ada declarations show the existing operators:
-@example
-function "&" (X : String; Y : String) return String;
-function "&" (X : String_List; Y : String) return String_List;
-function "&" (X : String_List; Y : String_List) return String_List;
-@end example
+By default, GNAT generates all run-time checks, except stack overflow
+checks, and checks for access before elaboration on subprogram
+calls. The latter are not required in default mode, because all
+necessary checking is done at compile time.
-Here are some specific examples:
+@geindex -gnatp (gcc)
-@example
-List := () & File_Name; -- One string in this list
-List2 := List & (File_Name & ".orig"); -- Two strings
-Big_List := List & Lists2; -- Three strings
-Illegal := "gnat.adc" & List2; -- Illegal, must start with list
-@end example
+@geindex -gnato (gcc)
-@node External Values,Typed String Declaration,Expressions,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager external-values}@anchor{154}@anchor{gnat_ugn/gnat_project_manager id43}@anchor{19d}
-@subsection External Values
+The gnat switch, @code{-gnatp} allows this default to be modified. See
+@ref{ea,,Run-Time Checks}.
+
+Our experience is that the default is suitable for most development
+purposes.
+Elaboration checks are off by default, and also not needed by default, since
+GNAT uses a static elaboration analysis approach that avoids the need for
+run-time checking. This manual contains a full chapter discussing the issue
+of elaboration checks, and if the default is not satisfactory for your use,
+you should read this chapter.
-An external value is an expression whose value is obtained from the command
-that invoked the processing of the current project file (typically a
-@emph{gprbuild} command).
+For validity checks, the minimal checks required by the Ada Reference
+Manual (for case statements and assignments to array elements) are on
+by default. These can be suppressed by use of the @code{-gnatVn} switch.
+Note that in Ada 83, there were no validity checks, so if the Ada 83 mode
+is acceptable (or when comparing GNAT performance with an Ada 83 compiler),
+it may be reasonable to routinely use @code{-gnatVn}. Validity checks
+are also suppressed entirely if @code{-gnatp} is used.
-There are two kinds of external values, one that returns a single string, and
-one that returns a string list.
+@geindex Overflow checks
-The syntax of a single string external value is:
+@geindex Checks
+@geindex overflow
-@example
-external_value ::= *external* ( string_literal [, string_literal] )
-@end example
+@geindex Suppress
-The first string_literal is the string to be used on the command line or
-in the environment to specify the external value. The second string_literal,
-if present, is the default to use if there is no specification for this
-external value either on the command line or in the environment.
+@geindex Unsuppress
-Typically, the external value will either exist in the
-environment variables
-or be specified on the command line through the
-@code{-X@emph{vbl}=@emph{value}} switch. If both
-are specified, then the command line value is used, so that a user can more
-easily override the value.
+@geindex pragma Suppress
-The function @cite{external} always returns a string. It is an error if the
-value was not found in the environment and no default was specified in the
-call to @cite{external}.
+@geindex pragma Unsuppress
-An external reference may be part of a string expression or of a string
-list expression, and can therefore appear in a variable declaration or
-an attribute declaration.
+Note that the setting of the switches controls the default setting of
+the checks. They may be modified using either @code{pragma Suppress} (to
+remove checks) or @code{pragma Unsuppress} (to add back suppressed
+checks) in the program source.
-Most of the time, this construct is used to initialize typed variables, which
-are then used in @strong{case} constructions to control the value assigned to
-attributes in various scenarios. Thus such variables are often called
-@strong{scenario variables}.
+@node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations
+@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
-The syntax for a string list external value is:
-@example
-external_value ::= *external_as_list* ( string_literal , string_literal )
-@end example
+The use of pragma Restrictions allows you to control which features are
+permitted in your program. Apart from the obvious point that if you avoid
+relatively expensive features like finalization (enforceable by the use
+of pragma Restrictions (No_Finalization), the use of this pragma does not
+affect the generated code in most cases.
-The first string_literal is the string to be used on the command line or
-in the environment to specify the external value. The second string_literal is
-the separator between each component of the string list.
+One notable exception to this rule is that the possibility of task abort
+results in some distributed overhead, particularly if finalization or
+exception handlers are used. The reason is that certain sections of code
+have to be marked as non-abortable.
-If the external value does not exist in the environment or on the command line,
-the result is an empty list. This is also the case, if the separator is an
-empty string or if the external value is only one separator.
+If you use neither the @code{abort} statement, nor asynchronous transfer
+of control (@code{select ... then abort}), then this distributed overhead
+is removed, which may have a general positive effect in improving
+overall performance. Especially code involving frequent use of tasking
+constructs and controlled types will show much improved performance.
+The relevant restrictions pragmas are
-Any separator at the beginning or at the end of the external value is
-discarded. Then, if there is no separator in the external value, the result is
-a string list with only one string. Otherwise, any string between the beginning
-and the first separator, between two consecutive separators and between the
-last separator and the end are components of the string list.
+@quotation
@example
-*external_as_list* ("SWITCHES", ",")
+pragma Restrictions (No_Abort_Statements);
+pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);
@end example
+@end quotation
-If the external value is "-O2,-g",
-the result is ("-O2", "-g").
+It is recommended that these restriction pragmas be used if possible. Note
+that this also means that you can write code without worrying about the
+possibility of an immediate abort at any point.
-If the external value is ",-O2,-g,",
-the result is also ("-O2", "-g").
+@node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations
+@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{182}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{ed}
+@subsubsection Optimization Levels
-if the external value is "-gnatv",
-the result is ("-gnatv").
-If the external value is ",,", the result is ("").
+@geindex -O (gcc)
-If the external value is ",", the result is (), the empty string list.
+Without any optimization option,
+the compiler's goal is to reduce the cost of
+compilation and to make debugging produce the expected results.
+Statements are independent: if you stop the program with a breakpoint between
+statements, you can then assign a new value to any variable or change
+the program counter to any other statement in the subprogram and get exactly
+the results you would expect from the source code.
-@node Typed String Declaration,Variables,External Values,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager id44}@anchor{19e}@anchor{gnat_ugn/gnat_project_manager typed-string-declaration}@anchor{19f}
-@subsection Typed String Declaration
+Turning on optimization makes the compiler attempt to improve the
+performance and/or code size at the expense of compilation time and
+possibly the ability to debug the program.
+If you use multiple
+-O options, with or without level numbers,
+the last such option is the one that is effective.
-A @strong{type declaration} introduces a discrete set of string literals.
-If a string variable is declared to have this type, its value
-is restricted to the given set of literals. These are the only named
-types in project files. A string type may only be declared at the project
-level, not inside a package.
+The default is optimization off. This results in the fastest compile
+times, but GNAT makes absolutely no attempt to optimize, and the
+generated programs are considerably larger and slower than when
+optimization is enabled. You can use the
+@code{-O} switch (the permitted forms are @code{-O0}, @code{-O1}
+@code{-O2}, @code{-O3}, and @code{-Os})
+to @code{gcc} to control the optimization level:
-@example
-typed_string_declaration ::=
- *type* *<typed_string_>*_simple_name *is* ( string_literal @{, string_literal@} );
-@end example
-The string literals in the list are case sensitive and must all be different.
-They may include any graphic characters allowed in Ada, including spaces.
-Here is an example of a string type declaration:
+@itemize *
-@example
-type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS");
-@end example
-
-Variables of a string type are called @strong{typed variables}; all other
-variables are called @strong{untyped variables}. Typed variables are
-particularly useful in @cite{case} constructions, to support conditional
-attribute declarations. (See @ref{1a0,,Case Constructions}).
-
-A string type may be referenced by its name if it has been declared in the same
-project file, or by an expanded name whose prefix is the name of the project
-in which it is declared.
-
-@node Variables,Case Constructions,Typed String Declaration,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager variables}@anchor{155}@anchor{gnat_ugn/gnat_project_manager id45}@anchor{1a1}
-@subsection Variables
-
-
-@strong{Variables} store values (strings or list of strings) and can appear
-as part of an expression. The declaration of a variable creates the
-variable and assigns the value of the expression to it. The name of the
-variable is available immediately after the assignment symbol, if you
-need to reuse its old value to compute the new value. Before the completion
-of its first declaration, the value of a variable defaults to the empty
-string ("").
-
-A @strong{typed} variable can be used as part of a @strong{case} expression to
-compute the value, but it can only be declared once in the project file,
-so that all case constructions see the same value for the variable. This
-provides more consistency and makes the project easier to understand.
-The syntax for its declaration is identical to the Ada syntax for an
-object declaration. In effect, a typed variable acts as a constant.
+@item
-An @strong{untyped} variable can be declared and overridden multiple times
-within the same project. It is declared implicitly through an Ada
-assignment. The first declaration establishes the kind of the variable
-(string or list of strings) and successive declarations must respect
-the initial kind. Assignments are executed in the order in which they
-appear, so the new value replaces the old one and any subsequent reference
-to the variable uses the new value.
+@table @asis
-A variable may be declared at the project file level, or within a package.
+@item @code{-O0}
-@example
-typed_variable_declaration ::=
- *<typed_variable_>*simple_name : *<typed_string_>*name := string_expression;
+No optimization (the default);
+generates unoptimized code but has
+the fastest compilation time.
-variable_declaration ::= *<variable_>*simple_name := expression;
-@end example
+Note that many other compilers do substantial optimization even
+if 'no optimization' is specified. With gcc, it is very unusual
+to use @code{-O0} for production if execution time is of any concern,
+since @code{-O0} means (almost) no optimization. This difference
+between gcc and other compilers should be kept in mind when
+doing performance comparisons.
+@end table
-Here are some examples of variable declarations:
+@item
-@example
-This_OS : OS := external ("OS"); -- a typed variable declaration
-That_OS := "GNU/Linux"; -- an untyped variable declaration
+@table @asis
-Name := "readme.txt";
-Save_Name := Name & ".saved";
+@item @code{-O1}
-Empty_List := ();
-List_With_One_Element := ("-gnaty");
-List_With_Two_Elements := List_With_One_Element & "-gnatg";
-Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada");
-@end example
+Moderate optimization;
+optimizes reasonably well but does not
+degrade compilation time significantly.
+@end table
-A @strong{variable reference} may take several forms:
+@item
+@table @asis
-@itemize *
+@item @code{-O2}
-@item
-The simple variable name, for a variable in the current package (if any)
-or in the current project
+Full optimization;
+generates highly optimized code and has
+the slowest compilation time.
+@end table
@item
-An expanded name, whose prefix is a context name.
-@end itemize
-A @strong{context} may be one of the following:
+@table @asis
+@item @code{-O3}
-@itemize *
+Full optimization as in @code{-O2};
+also uses more aggressive automatic inlining of subprograms within a unit
+(@ref{100,,Inlining of Subprograms}) and attempts to vectorize loops.
+@end table
@item
-The name of an existing package in the current project
-@item
-The name of an imported project of the current project
+@table @asis
-@item
-The name of an ancestor project (i.e., a project extended by the current
-project, either directly or indirectly)
+@item @code{-Os}
-@item
-An expanded name whose prefix is an imported/parent project name, and
-whose selector is a package name in that project.
+Optimize space usage (code and data) of resulting program.
+@end table
@end itemize
-@node Case Constructions,Attributes,Variables,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager id46}@anchor{1a2}@anchor{gnat_ugn/gnat_project_manager case-constructions}@anchor{1a0}
-@subsection Case Constructions
-
-
-A @strong{case} construction is used in a project file to effect conditional
-behavior. Through this construction, you can set the value of attributes
-and variables depending on the value previously assigned to a typed
-variable.
-
-All choices in a choice list must be distinct. Unlike Ada, the choice
-lists of all alternatives do not need to include all values of the type.
-An @cite{others} choice must appear last in the list of alternatives.
-
-The syntax of a @cite{case} construction is based on the Ada case construction
-(although the @cite{null} declaration for empty alternatives is optional).
-
-The case expression must be a string variable, either typed or not, whose value
-is often given by an external reference (see @ref{154,,External Values}).
-
-Each alternative starts with the reserved word @cite{when}, either a list of
-literal strings separated by the @cite{"|"} character or the reserved word
-@cite{others}, and the @cite{"=>"} token.
-When the case expression is a typed string variable, each literal string must
-belong to the string type that is the type of the case variable.
-After each @cite{=>}, there are zero or more declarations. The only
-declarations allowed in a case construction are other case constructions,
-attribute declarations and variable declarations. String type declarations and
-package declarations are not allowed. Variable declarations are restricted to
-variables that have already been declared before the case construction.
-
-@example
-case_construction ::=
- *case* *<variable_>*name *is* @{case_item@} *end case* ;
-
-case_item ::=
- *when* discrete_choice_list =>
- @{case_declaration
- | attribute_declaration
- | variable_declaration
- | empty_declaration@}
-
-discrete_choice_list ::= string_literal @{| string_literal@} | *others*
-@end example
-
-Here is a typical example, with a typed string variable:
-
-@example
-project MyProj is
- type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS");
- OS : OS_Type := external ("OS", "GNU/Linux");
-
- package Compiler is
- case OS is
- when "GNU/Linux" | "Unix" =>
- for Switches ("Ada")
- use ("-gnath");
- when "NT" =>
- for Switches ("Ada")
- use ("-gnatP");
- when others =>
- null;
- end case;
- end Compiler;
-end MyProj;
-@end example
-
-@node Attributes,,Case Constructions,Project File Reference
-@anchor{gnat_ugn/gnat_project_manager id47}@anchor{1a3}@anchor{gnat_ugn/gnat_project_manager attributes}@anchor{152}
-@subsection Attributes
-
-
-A project (and its packages) may have @strong{attributes} that define
-the project's properties. Some attributes have values that are strings;
-others have values that are string lists.
-
-@example
-attribute_declaration ::=
- simple_attribute_declaration | indexed_attribute_declaration
+Higher optimization levels perform more global transformations on the
+program and apply more expensive analysis algorithms in order to generate
+faster and more compact code. The price in compilation time, and the
+resulting improvement in execution time,
+both depend on the particular application and the hardware environment.
+You should experiment to find the best level for your application.
-simple_attribute_declaration ::= *for* attribute_designator *use* expression ;
+Since the precise set of optimizations done at each level will vary from
+release to release (and sometime from target to target), it is best to think
+of the optimization settings in general terms.
+See the @emph{Options That Control Optimization} section in
+@cite{Using the GNU Compiler Collection (GCC)}
+for details about
+the @code{-O} settings and a number of @code{-f} options that
+individually enable or disable specific optimizations.
-indexed_attribute_declaration ::=
- *for* *<indexed_attribute_>*simple_name ( string_literal) *use* expression ;
+Unlike some other compilation systems, @code{gcc} has
+been tested extensively at all optimization levels. There are some bugs
+which appear only with optimization turned on, but there have also been
+bugs which show up only in @emph{unoptimized} code. Selecting a lower
+level of optimization does not improve the reliability of the code
+generator, which in practice is highly reliable at all optimization
+levels.
-attribute_designator ::=
- *<simple_attribute_>*simple_name
- | *<indexed_attribute_>*simple_name ( string_literal )
-@end example
+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{100,,Inlining of Subprograms}.
-There are two categories of attributes: @strong{simple attributes}
-and @strong{indexed attributes}.
-Each simple attribute has a default value: the empty string (for string
-attributes) and the empty list (for string list attributes).
-An attribute declaration defines a new value for an attribute, and overrides
-the previous value. The syntax of a simple attribute declaration is similar to
-that of an attribute definition clause in Ada.
+@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations
+@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
-Some attributes are indexed. These attributes are mappings whose
-domain is a set of strings. They are declared one association
-at a time, by specifying a point in the domain and the corresponding image
-of the attribute.
-Like untyped variables and simple attributes, indexed attributes
-may be declared several times. Each declaration supplies a new value for the
-attribute, and replaces the previous setting.
-Here are some examples of attribute declarations:
+@geindex Debugging optimized code
-@example
--- simple attributes
-for Object_Dir use "objects";
-for Source_Dirs use ("units", "test/drivers");
+@geindex Optimization and debugging
--- indexed attributes
-for Body ("main") use "Main.ada";
-for Switches ("main.ada")
- use ("-v", "-gnatv");
-for Switches ("main.ada") use Builder'Switches ("main.ada") & "-g";
+Although it is possible to do a reasonable amount of debugging at
+nonzero optimization levels,
+the higher the level the more likely that
+source-level constructs will have been eliminated by optimization.
+For example, if a loop is strength-reduced, the loop
+control variable may be completely eliminated and thus cannot be
+displayed in the debugger.
+This can only happen at @code{-O2} or @code{-O3}.
+Explicit temporary variables that you code might be eliminated at
+level @code{-O1} or higher.
--- indexed attributes copy (from package Builder in project Default)
--- The package name must always be specified, even if it is the current
--- package.
-for Default_Switches use Default.Builder'Default_Switches;
-@end example
+@geindex -g (gcc)
-Attributes references may appear anywhere in expressions, and are used
-to retrieve the value previously assigned to the attribute. If an attribute
-has not been set in a given package or project, its value defaults to the
-empty string or the empty list, with some exceptions.
+The use of the @code{-g} switch,
+which is needed for source-level debugging,
+affects the size of the program executable on disk,
+and indeed the debugging information can be quite large.
+However, it has no effect on the generated code (and thus does not
+degrade performance)
-@example
-attribute_reference ::=
- attribute_prefix ' *<simple_attribute>_*simple_name [ (string_literal) ]
-attribute_prefix ::= *project*
- | *<project_>*simple_name
- | package_identifier
- | *<project_>*simple_name . package_identifier
-@end example
+Since the compiler generates debugging tables for a compilation unit before
+it performs optimizations, the optimizing transformations may invalidate some
+of the debugging data. You therefore need to anticipate certain
+anomalous situations that may arise while debugging optimized code.
+These are the most common cases:
-Examples are:
-@example
-<project>'Object_Dir
-Naming'Dot_Replacement
-Imported_Project'Source_Dirs
-Imported_Project.Naming'Casing
-Builder'Default_Switches ("Ada")
-@end example
+@itemize *
-The exceptions to the empty defaults are:
+@item
+@emph{The 'hopping Program Counter':} Repeated @code{step} or @code{next}
+commands show
+the PC bouncing back and forth in the code. This may result from any of
+the following optimizations:
-@itemize *
+@itemize -
@item
-Object_Dir: default is "."
+@emph{Common subexpression elimination:} using a single instance of code for a
+quantity that the source computes several times. As a result you
+may not be able to stop on what looks like a statement.
@item
-Exec_Dir: default is 'Object_Dir, that is the value of attribute
-Object_Dir in the same project, declared or defaulted.
+@emph{Invariant code motion:} moving an expression that does not change within a
+loop, to the beginning of the loop.
@item
-Source_Dirs: default is (".")
+@emph{Instruction scheduling:} moving instructions so as to
+overlap loads and stores (typically) with other code, or in
+general to move computations of values closer to their uses. Often
+this causes you to pass an assignment statement without the assignment
+happening and then later bounce back to the statement when the
+value is actually needed. Placing a breakpoint on a line of code
+and then stepping over it may, therefore, not always cause all the
+expected side-effects.
@end itemize
-The prefix of an attribute may be:
+@item
+@emph{The 'big leap':} More commonly known as @emph{cross-jumping}, in which
+two identical pieces of code are merged and the program counter suddenly
+jumps to a statement that is not supposed to be executed, simply because
+it (and the code following) translates to the same thing as the code
+that @emph{was} supposed to be executed. This effect is typically seen in
+sequences that end in a jump, such as a @code{goto}, a @code{return}, or
+a @code{break} in a C @code{switch} statement.
+
+@item
+@emph{The 'roving variable':} The symptom is an unexpected value in a variable.
+There are various reasons for this effect:
-@itemize *
+@itemize -
@item
-@cite{project} for an attribute of the current project
+In a subprogram prologue, a parameter may not yet have been moved to its
+'home'.
@item
-The name of an existing package of the current project
+A variable may be dead, and its register re-used. This is
+probably the most common cause.
@item
-The name of an imported project
+As mentioned above, the assignment of a value to a variable may
+have been moved.
@item
-The name of a parent project that is extended by the current project
+A variable may be eliminated entirely by value propagation or
+other means. In this case, GCC may incorrectly generate debugging
+information for the variable
+@end itemize
-@item
-An expanded name whose prefix is imported/parent project name,
-and whose selector is a package name
+In general, when an unexpected value appears for a local variable or parameter
+you should first ascertain if that value was actually computed by
+your program, as opposed to being incorrectly reported by the debugger.
+Record fields or
+array elements in an object designated by an access value
+are generally less of a problem, once you have ascertained that the access
+value is sensible.
+Typically, this means checking variables in the preceding code and in the
+calling subprogram to verify that the value observed is explainable from other
+values (one must apply the procedure recursively to those
+other values); or re-running the code and stopping a little earlier
+(perhaps before the call) and stepping to better see how the variable obtained
+the value in question; or continuing to step @emph{from} the point of the
+strange value to see if code motion had simply moved the variable's
+assignments later.
@end itemize
-In the following sections, all predefined attributes are succinctly described,
-first the project level attributes, that is those attributes that are not in a
-package, then the attributes in the different packages.
+In light of such anomalies, a recommended technique is to use @code{-O0}
+early in the software development cycle, when extensive debugging capabilities
+are most needed, and then move to @code{-O1} and later @code{-O2} as
+the debugger becomes less critical.
+Whether to use the @code{-g} switch in the release version is
+a release management issue.
+Note that if you use @code{-g} you can then use the @code{strip} program
+on the resulting executable,
+which removes both debugging information and global symbols.
-It is possible for different tools to dynamically create new packages with
-attributes, or new attributes in predefined packages. These attributes are
-not documented here.
+@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
-The attributes under Configuration headings are usually found only in
-configuration project files.
-The characteristics of each attribute are indicated as follows:
+A call to a subprogram in the current unit is inlined if all the
+following conditions are met:
@itemize *
@item
-@strong{Type of value}
-
-The value of an attribute may be a single string, indicated by the word
-"single", or a string list, indicated by the word "list".
+The optimization level is at least @code{-O1}.
@item
-@strong{Read-only}
-
-When the attribute is read-only, that is when it is not allowed to declare
-the attribute, this is indicated by the words "read-only".
+The called subprogram is suitable for inlining: It must be small enough
+and not contain something that @code{gcc} cannot support in inlined
+subprograms.
-@item
-@strong{Optional index}
+@geindex pragma Inline
-If it is allowed in the value of the attribute (both single and list) to have
-an optional index, this is indicated by the words "optional index".
+@geindex Inline
@item
-@strong{Indexed attribute}
+Any one of the following applies: @code{pragma Inline} is applied to the
+subprogram; the subprogram is local to the unit and called once from
+within it; the subprogram is small and optimization level @code{-O2} is
+specified; optimization level @code{-O3} is specified.
+@end itemize
-When it is an indexed attribute, this is indicated by the word "indexed".
+Calls to subprograms in @emph{with}ed units are normally not inlined.
+To achieve actual inlining (that is, replacement of the call by the code
+in the body of the subprogram), the following conditions must all be true:
-@item
-@strong{Case-sensitivity of the index}
-For an indexed attribute, if the index is case-insensitive, this is indicated
-by the words "case-insensitive index".
+@itemize *
@item
-@strong{File name index}
-
-For an indexed attribute, when the index is a file name, this is indicated by
-the words "file name index". The index may or may not be case-sensitive,
-depending on the platform.
+The optimization level is at least @code{-O1}.
@item
-@strong{others allowed in index}
+The called subprogram is suitable for inlining: It must be small enough
+and not contain something that @code{gcc} cannot support in inlined
+subprograms.
-For an indexed attribute, if it is allowed to use @strong{others} as the index,
-this is indicated by the words "others allowed".
+@item
+There is a @code{pragma Inline} for the subprogram.
-When @strong{others} is used as the index of an indexed attribute, the value of
-the attribute indexed by @strong{others} is used when no other index would apply.
+@item
+The @code{-gnatn} switch is used on the command line.
@end itemize
-@menu
-* Project Level Attributes::
-* Package Binder Attributes::
-* Package Builder Attributes::
-* Package Clean Attributes::
-* Package Compiler Attributes::
-* Package Cross_Reference Attributes::
-* Package Finder Attributes::
-* Package gnatls Attributes::
-* Package IDE Attributes::
-* Package Install Attributes::
-* Package Linker Attributes::
-* Package Naming Attributes::
-* Package Remote Attributes::
-* Package Stack Attributes::
-* Package Synchronize Attributes::
-
-@end menu
-
-@node Project Level Attributes,Package Binder Attributes,,Attributes
-@anchor{gnat_ugn/gnat_project_manager project-level-attributes}@anchor{1a4}@anchor{gnat_ugn/gnat_project_manager id48}@anchor{1a5}
-@subsubsection Project Level Attributes
-
-
-
-@itemize *
+Even if all these conditions are met, it may not be possible for
+the compiler to inline the call, due to the length of the body,
+or features in the body that make it impossible for the compiler
+to do the inlining.
-@item
-@strong{General}
+Note that specifying the @code{-gnatn} switch causes additional
+compilation dependencies. Consider the following:
+@quotation
-@itemize *
+@example
+package R is
+ procedure Q;
+ pragma Inline (Q);
+end R;
+package body R is
+ ...
+end R;
-@item
-@strong{Name}: single, read-only
+with R;
+procedure Main is
+begin
+ ...
+ R.Q;
+end Main;
+@end example
+@end quotation
-The name of the project.
+With the default behavior (no @code{-gnatn} switch specified), the
+compilation of the @code{Main} procedure depends only on its own source,
+@code{main.adb}, and the spec of the package in file @code{r.ads}. This
+means that editing the body of @code{R} does not require recompiling
+@code{Main}.
-@item
-@strong{Project_Dir}: single, read-only
+On the other hand, the call @code{R.Q} is not inlined under these
+circumstances. If the @code{-gnatn} switch is present when @code{Main}
+is compiled, the call will be inlined if the body of @code{Q} is small
+enough, but now @code{Main} depends on the body of @code{R} in
+@code{r.adb} as well as on the spec. This means that if this body is edited,
+the main program must be recompiled. Note that this extra dependency
+occurs whether or not the call is in fact inlined by @code{gcc}.
-The path name of the project directory.
+The use of front end inlining with @code{-gnatN} generates similar
+additional dependencies.
-@item
-@strong{Main}: list, optional index
+@geindex -fno-inline (gcc)
-The list of main sources for the executables.
+Note: The @code{-fno-inline} switch overrides all other conditions and ensures that
+no inlining occurs, unless requested with pragma Inline_Always for @code{gcc}
+back-ends. The extra dependences resulting from @code{-gnatn} will still be active,
+even if this switch is used to suppress the resulting inlining actions.
-@item
-@strong{Languages}: list
+@geindex -fno-inline-functions (gcc)
-The list of languages of the sources of the project.
+Note: The @code{-fno-inline-functions} switch can be used to prevent
+automatic inlining of subprograms if @code{-O3} is used.
-@item
-@strong{Roots}: list, indexed, file name index
+@geindex -fno-inline-small-functions (gcc)
-The index is the file name of an executable source. Indicates the list of units
-from the main project that need to be bound and linked with their closures
-with the executable. The index is either a file name, a language name or "*".
-The roots for an executable source are those in @strong{Roots} with an index that
-is the executable source file name, if declared. Otherwise, they are those in
-@strong{Roots} with an index that is the language name of the executable source,
-if present. Otherwise, they are those in @strong{Roots ("*")}, if declared. If none
-of these three possibilities are declared, then there are no roots for the
-executable source.
+Note: The @code{-fno-inline-small-functions} switch can be used to prevent
+automatic inlining of small subprograms if @code{-O2} is used.
-@item
-@strong{Externally_Built}: single
+@geindex -fno-inline-functions-called-once (gcc)
-Indicates if the project is externally built.
-Only case-insensitive values allowed are "true" and "false", the default.
-@end itemize
+Note: The @code{-fno-inline-functions-called-once} switch
+can be used to prevent inlining of subprograms local to the unit
+and called once from within it if @code{-O1} is used.
+
+Note regarding the use of @code{-O3}: @code{-gnatn} is made up of two
+sub-switches @code{-gnatn1} and @code{-gnatn2} that can be directly
+specified in lieu of it, @code{-gnatn} being translated into one of them
+based on the optimization level. With @code{-O2} or below, @code{-gnatn}
+is equivalent to @code{-gnatn1} which activates pragma @code{Inline} with
+moderate inlining across modules. With @code{-O3}, @code{-gnatn} is
+equivalent to @code{-gnatn2} which activates pragma @code{Inline} with
+full inlining across modules. If you have used pragma @code{Inline} in
+appropriate cases, then it is usually much better to use @code{-O2}
+and @code{-gnatn} and avoid the use of @code{-O3} which has the additional
+effect of inlining subprograms you did not think should be inlined. We have
+found that the use of @code{-O3} may slow down the compilation and increase
+the code size by performing excessive inlining, leading to increased
+instruction cache pressure from the increased code size and thus minor
+performance improvements. So the bottom line here is that you should not
+automatically assume that @code{-O3} is better than @code{-O2}, and
+indeed you should use @code{-O3} only if tests show that it actually
+improves performance for your program.
-@item
-@strong{Directories}
+@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
-@itemize *
+@geindex Floating-Point Operations
-@item
-@strong{Object_Dir}: single
-
-Indicates the object directory for the project.
+On almost all targets, GNAT maps Float and Long_Float to the 32-bit and
+64-bit standard IEEE floating-point representations, and operations will
+use standard IEEE arithmetic as provided by the processor. On most, but
+not all, architectures, the attribute Machine_Overflows is False for these
+types, meaning that the semantics of overflow is implementation-defined.
+In the case of GNAT, these semantics correspond to the normal IEEE
+treatment of infinities and NaN (not a number) values. For example,
+1.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By
+avoiding explicit overflow checks, the performance is greatly improved
+on many targets. However, if required, floating-point overflow can be
+enabled by the use of the pragma Check_Float_Overflow.
-@item
-@strong{Exec_Dir}: single
+Another consideration that applies specifically to x86 32-bit
+architectures is which form of floating-point arithmetic is used.
+By default the operations use the old style x86 floating-point,
+which implements an 80-bit extended precision form (on these
+architectures the type Long_Long_Float corresponds to that form).
+In addition, generation of efficient code in this mode means that
+the extended precision form will be used for intermediate results.
+This may be helpful in improving the final precision of a complex
+expression. However it means that the results obtained on the x86
+will be different from those on other architectures, and for some
+algorithms, the extra intermediate precision can be detrimental.
-Indicates the exec directory for the project, that is the directory where the
-executables are.
+In addition to this old-style floating-point, all modern x86 chips
+implement an alternative floating-point operation model referred
+to as SSE2. In this model there is no extended form, and furthermore
+execution performance is significantly enhanced. To force GNAT to use
+this more modern form, use both of the switches:
-@item
-@strong{Source_Dirs}: list
+@quotation
-The list of source directories of the project.
+-msse2 -mfpmath=sse
+@end quotation
-@item
-@strong{Inherit_Source_Path}: list, indexed, case-insensitive index
+A unit compiled with these switches will automatically use the more
+efficient SSE2 instruction set for Float and Long_Float operations.
+Note that the ABI has the same form for both floating-point models,
+so it is permissible to mix units compiled with and without these
+switches.
-Index is a language name. Value is a list of language names. Indicates that
-in the source search path of the index language the source directories of
-the languages in the list should be included.
+@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
-Example:
-@example
-for Inherit_Source_Path ("C++") use ("C");
-@end example
+@geindex Optimization Switches
-@item
-@strong{Exclude_Source_Dirs}: list
+You can take advantage of the auto-vectorizer present in the @code{gcc}
+back end to vectorize loops with GNAT. The corresponding command line switch
+is @code{-ftree-vectorize} but, as it is enabled by default at @code{-O3}
+and other aggressive optimizations helpful for vectorization also are enabled
+by default at this level, using @code{-O3} directly is recommended.
-The list of directories that are included in Source_Dirs but are not source
-directories of the project.
+You also need to make sure that the target architecture features a supported
+SIMD instruction set. For example, for the x86 architecture, you should at
+least specify @code{-msse2} to get significant vectorization (but you don't
+need to specify it for x86-64 as it is part of the base 64-bit architecture).
+Similarly, for the PowerPC architecture, you should specify @code{-maltivec}.
-@item
-@strong{Ignore_Source_Sub_Dirs}: list
+The preferred loop form for vectorization is the @code{for} iteration scheme.
+Loops with a @code{while} iteration scheme can also be vectorized if they are
+very simple, but the vectorizer will quickly give up otherwise. With either
+iteration scheme, the flow of control must be straight, in particular no
+@code{exit} statement may appear in the loop body. The loop may however
+contain a single nested loop, if it can be vectorized when considered alone:
-Value is a list of simple names for subdirectories that are removed from the
-list of source directories, including theur subdirectories.
-@end itemize
+@quotation
-@item
-@strong{Source Files}
+@example
+A : array (1..4, 1..4) of Long_Float;
+S : array (1..4) of Long_Float;
+procedure Sum is
+begin
+ for I in A'Range(1) loop
+ for J in A'Range(2) loop
+ S (I) := S (I) + A (I, J);
+ end loop;
+ end loop;
+end Sum;
+@end example
+@end quotation
-@itemize *
+The vectorizable operations depend on the targeted SIMD instruction set, but
+the adding and some of the multiplying operators are generally supported, as
+well as the logical operators for modular types. Note that compiling
+with @code{-gnatp} might well reveal cases where some checks do thwart
+vectorization.
-@item
-@strong{Source_Files}: list
+Type conversions may also prevent vectorization if they involve semantics that
+are not directly supported by the code generator or the SIMD instruction set.
+A typical example is direct conversion from floating-point to integer types.
+The solution in this case is to use the following idiom:
-Value is a list of source file simple names.
+@quotation
-@item
-@strong{Locally_Removed_Files}: list
+@example
+Integer (S'Truncation (F))
+@end example
+@end quotation
-Obsolescent. Equivalent to Excluded_Source_Files.
+if @code{S} is the subtype of floating-point object @code{F}.
-@item
-@strong{Excluded_Source_Files}: list
+In most cases, the vectorizable loops are loops that iterate over arrays.
+All kinds of array types are supported, i.e. constrained array types with
+static bounds:
-Value is a list of simple file names that are not sources of the project.
-Allows to remove sources that are inherited or found in the source directories
-and that match the naming scheme.
+@quotation
-@item
-@strong{Source_List_File}: single
+@example
+type Array_Type is array (1 .. 4) of Long_Float;
+@end example
+@end quotation
-Value is a text file name that contains a list of source file simple names,
-one on each line.
+constrained array types with dynamic bounds:
-@item
-@strong{Excluded_Source_List_File}: single
+@quotation
-Value is a text file name that contains a list of file simple names that
-are not sources of the project.
+@example
+type Array_Type is array (1 .. Q.N) of Long_Float;
-@item
-@strong{Interfaces}: list
+type Array_Type is array (Q.K .. 4) of Long_Float;
-Value is a list of file names that constitutes the interfaces of the project.
-@end itemize
+type Array_Type is array (Q.K .. Q.N) of Long_Float;
+@end example
+@end quotation
-@item
-@strong{Aggregate Projects}
+or unconstrained array types:
+@quotation
-@itemize *
+@example
+type Array_Type is array (Positive range <>) of Long_Float;
+@end example
+@end quotation
-@item
-@strong{Project_Files}: list
+The quality of the generated code decreases when the dynamic aspect of the
+array type increases, the worst code being generated for unconstrained array
+types. This is so because, the less information the compiler has about the
+bounds of the array, the more fallback code it needs to generate in order to
+fix things up at run time.
-Value is the list of aggregated projects.
+It is possible to specify that a given loop should be subject to vectorization
+preferably to other optimizations by means of pragma @code{Loop_Optimize}:
-@item
-@strong{Project_Path}: list
+@quotation
-Value is a list of directories that are added to the project search path when
-looking for the aggregated projects.
+@example
+pragma Loop_Optimize (Vector);
+@end example
+@end quotation
-@item
-@strong{External}: single, indexed
+placed immediately within the loop will convey the appropriate hint to the
+compiler for this loop.
-Index is the name of an external reference. Value is the value of the
-external reference to be used when parsing the aggregated projects.
-@end itemize
+It is also possible to help the compiler generate better vectorized code
+for a given loop by asserting that there are no loop-carried dependencies
+in the loop. Consider for example the procedure:
-@item
-@strong{Libraries}
+@quotation
+@example
+type Arr is array (1 .. 4) of Long_Float;
-@itemize *
+procedure Add (X, Y : not null access Arr; R : not null access Arr) is
+begin
+ for I in Arr'Range loop
+ R(I) := X(I) + Y(I);
+ end loop;
+end;
+@end example
+@end quotation
-@item
-@strong{Library_Dir}: single
+By default, the compiler cannot unconditionally vectorize the loop because
+assigning to a component of the array designated by R in one iteration could
+change the value read from the components of the array designated by X or Y
+in a later iteration. As a result, the compiler will generate two versions
+of the loop in the object code, one vectorized and the other not vectorized,
+as well as a test to select the appropriate version at run time. This can
+be overcome by another hint:
-Value is the name of the library directory. This attribute needs to be
-declared for each library project.
+@quotation
-@item
-@strong{Library_Name}: single
+@example
+pragma Loop_Optimize (Ivdep);
+@end example
+@end quotation
-Value is the name of the library. This attribute needs to be declared or
-inherited for each library project.
+placed immediately within the loop will tell the compiler that it can safely
+omit the non-vectorized version of the loop as well as the run-time test.
-@item
-@strong{Library_Kind}: single
+@node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations
+@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
-Specifies the kind of library: static library (archive) or shared library.
-Case-insensitive values must be one of "static" for archives (the default) or
-"dynamic" or "relocatable" for shared libraries.
-@item
-@strong{Library_Version}: single
+@geindex Optimization Switches
-Value is the name of the library file.
+Since GNAT uses the @code{gcc} back end, all the specialized
+@code{gcc} optimization switches are potentially usable. These switches
+have not been extensively tested with GNAT but can generally be expected
+to work. Examples of switches in this category are @code{-funroll-loops}
+and the various target-specific @code{-m} options (in particular, it has
+been observed that @code{-march=xxx} can significantly improve performance
+on appropriate machines). For full details of these switches, see
+the @emph{Submodel Options} section in the @emph{Hardware Models and Configurations}
+chapter of @cite{Using the GNU Compiler Collection (GCC)}.
-@item
-@strong{Library_Interface}: list
+@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{e4}@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{18c}
+@subsubsection Optimization and Strict Aliasing
-Value is the list of unit names that constitutes the interfaces
-of a Stand-Alone Library project.
-@item
-@strong{Library_Standalone}: single
+@geindex Aliasing
-Specifies if a Stand-Alone Library (SAL) is encapsulated or not.
-Only authorized case-insensitive values are "standard" for non encapsulated
-SALs, "encapsulated" for encapsulated SALs or "no" for non SAL library project.
+@geindex Strict Aliasing
-@item
-@strong{Library_Encapsulated_Options}: list
+@geindex No_Strict_Aliasing
-Value is a list of options that need to be used when linking an encapsulated
-Stand-Alone Library.
+The strong typing capabilities of Ada allow an optimizer to generate
+efficient code in situations where other languages would be forced to
+make worst case assumptions preventing such optimizations. Consider
+the following example:
-@item
-@strong{Library_Encapsulated_Supported}: single
+@quotation
-Indicates if encapsulated Stand-Alone Libraries are supported. Only
-authorized case-insensitive values are "true" and "false" (the default).
+@example
+procedure R is
+ type Int1 is new Integer;
+ type Int2 is new Integer;
+ type Int1A is access Int1;
+ type Int2A is access Int2;
+ Int1V : Int1A;
+ Int2V : Int2A;
+ ...
-@item
-@strong{Library_Auto_Init}: single
+begin
+ ...
+ for J in Data'Range loop
+ if Data (J) = Int1V.all then
+ Int2V.all := Int2V.all + 1;
+ end if;
+ end loop;
+ ...
+end R;
+@end example
+@end quotation
-Indicates if a Stand-Alone Library is auto-initialized. Only authorized
-case-insentive values are "true" and "false".
+In this example, since the variable @code{Int1V} can only access objects
+of type @code{Int1}, and @code{Int2V} can only access objects of type
+@code{Int2}, there is no possibility that the assignment to
+@code{Int2V.all} affects the value of @code{Int1V.all}. This means that
+the compiler optimizer can "know" that the value @code{Int1V.all} is constant
+for all iterations of the loop and avoid the extra memory reference
+required to dereference it each time through the loop.
-@item
-@strong{Leading_Library_Options}: list
+This kind of optimization, called strict aliasing analysis, is
+triggered by specifying an optimization level of @code{-O2} or
+higher or @code{-Os} and allows GNAT to generate more efficient code
+when access values are involved.
-Value is a list of options that are to be used at the beginning of
-the command line when linking a shared library.
+However, although this optimization is always correct in terms of
+the formal semantics of the Ada Reference Manual, difficulties can
+arise if features like @code{Unchecked_Conversion} are used to break
+the typing system. Consider the following complete program example:
-@item
-@strong{Library_Options}: list
+@quotation
-Value is a list of options that are to be used when linking a shared library.
+@example
+package p1 is
+ type int1 is new integer;
+ type int2 is new integer;
+ type a1 is access int1;
+ type a2 is access int2;
+end p1;
-@item
-@strong{Library_Rpath_Options}: list, indexed, case-insensitive index
+with p1; use p1;
+package p2 is
+ function to_a2 (Input : a1) return a2;
+end p2;
-Index is a language name. Value is a list of options for an invocation of the
-compiler of the language. This invocation is done for a shared library project
-with sources of the language. The output of the invocation is the path name
-of a shared library file. The directory name is to be put in the run path
-option switch when linking the shared library for the project.
+with Unchecked_Conversion;
+package body p2 is
+ function to_a2 (Input : a1) return a2 is
+ function to_a2u is
+ new Unchecked_Conversion (a1, a2);
+ begin
+ return to_a2u (Input);
+ end to_a2;
+end p2;
-@item
-@strong{Library_Src_Dir}: single
+with p2; use p2;
+with p1; use p1;
+with Text_IO; use Text_IO;
+procedure m is
+ v1 : a1 := new int1;
+ v2 : a2 := to_a2 (v1);
+begin
+ v1.all := 1;
+ v2.all := 0;
+ put_line (int1'image (v1.all));
+end;
+@end example
+@end quotation
-Value is the name of the directory where copies of the sources of the
-interfaces of a Stand-Alone Library are to be copied.
+This program prints out 0 in @code{-O0} or @code{-O1}
+mode, but it prints out 1 in @code{-O2} mode. That's
+because in strict aliasing mode, the compiler can and
+does assume that the assignment to @code{v2.all} could not
+affect the value of @code{v1.all}, since different types
+are involved.
-@item
-@strong{Library_ALI_Dir}: single
-
-Value is the name of the directory where the ALI files of the interfaces
-of a Stand-Alone Library are to be copied. When this attribute is not declared,
-the directory is the library directory.
+This behavior is not a case of non-conformance with the standard, since
+the Ada RM specifies that an unchecked conversion where the resulting
+bit pattern is not a correct value of the target type can result in an
+abnormal value and attempting to reference an abnormal value makes the
+execution of a program erroneous. That's the case here since the result
+does not point to an object of type @code{int2}. This means that the
+effect is entirely unpredictable.
-@item
-@strong{Library_gcc}: single
+However, although that explanation may satisfy a language
+lawyer, in practice an applications programmer expects an
+unchecked conversion involving pointers to create true
+aliases and the behavior of printing 1 seems plain wrong.
+In this case, the strict aliasing optimization is unwelcome.
-Obsolescent attribute. Specify the linker driver used to link a shared library.
-Use instead attribute Linker'Driver.
+Indeed the compiler recognizes this possibility, and the
+unchecked conversion generates a warning:
-@item
-@strong{Library_Symbol_File}: single
+@quotation
-Value is the name of the library symbol file.
+@example
+p2.adb:5:07: warning: possible aliasing problem with type "a2"
+p2.adb:5:07: warning: use -fno-strict-aliasing switch for references
+p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);"
+@end example
+@end quotation
-@item
-@strong{Library_Symbol_Policy}: single
+Unfortunately the problem is recognized when compiling the body of
+package @code{p2}, but the actual "bad" code is generated while
+compiling the body of @code{m} and this latter compilation does not see
+the suspicious @code{Unchecked_Conversion}.
-Indicates the symbol policy kind. Only authorized case-insensitive values are
-"autonomous", "default", "compliant", "controlled" or "direct".
+As implied by the warning message, there are approaches you can use to
+avoid the unwanted strict aliasing optimization in a case like this.
-@item
-@strong{Library_Reference_Symbol_File}: single
+One possibility is to simply avoid the use of @code{-O2}, but
+that is a bit drastic, since it throws away a number of useful
+optimizations that do not involve strict aliasing assumptions.
-Value is the name of the reference symbol file.
-@end itemize
+A less drastic approach is to compile the program using the
+option @code{-fno-strict-aliasing}. Actually it is only the
+unit containing the dereferencing of the suspicious pointer
+that needs to be compiled. So in this case, if we compile
+unit @code{m} with this switch, then we get the expected
+value of zero printed. Analyzing which units might need
+the switch can be painful, so a more reasonable approach
+is to compile the entire program with options @code{-O2}
+and @code{-fno-strict-aliasing}. If the performance is
+satisfactory with this combination of options, then the
+advantage is that the entire issue of possible "wrong"
+optimization due to strict aliasing is avoided.
-@item
-@strong{Configuration - General}
+To avoid the use of compiler switches, the configuration
+pragma @code{No_Strict_Aliasing} with no parameters may be
+used to specify that for all access types, the strict
+aliasing optimization should be suppressed.
+However, these approaches are still overkill, in that they causes
+all manipulations of all access values to be deoptimized. A more
+refined approach is to concentrate attention on the specific
+access type identified as problematic.
-@itemize *
+First, if a careful analysis of uses of the pointer shows
+that there are no possible problematic references, then
+the warning can be suppressed by bracketing the
+instantiation of @code{Unchecked_Conversion} to turn
+the warning off:
-@item
-@strong{Default_Language}: single
+@quotation
-Value is the case-insensitive name of the language of a project when attribute
-Languages is not specified.
+@example
+pragma Warnings (Off);
+function to_a2u is
+ new Unchecked_Conversion (a1, a2);
+pragma Warnings (On);
+@end example
+@end quotation
-@item
-@strong{Run_Path_Option}: list
+Of course that approach is not appropriate for this particular
+example, since indeed there is a problematic reference. In this
+case we can take one of two other approaches.
-Value is the list of switches to be used when specifying the run path option
-in an executable.
+The first possibility is to move the instantiation of unchecked
+conversion to the unit in which the type is declared. In
+this example, we would move the instantiation of
+@code{Unchecked_Conversion} from the body of package
+@code{p2} to the spec of package @code{p1}. Now the
+warning disappears. That's because any use of the
+access type knows there is a suspicious unchecked
+conversion, and the strict aliasing optimization
+is automatically suppressed for the type.
-@item
-@strong{Run_Path_Origin}: single
+If it is not practical to move the unchecked conversion to the same unit
+in which the destination access type is declared (perhaps because the
+source type is not visible in that unit), you may use pragma
+@code{No_Strict_Aliasing} for the type. This pragma must occur in the
+same declarative sequence as the declaration of the access type:
-Value is the the string that may replace the path name of the executable
-directory in the run path options.
+@quotation
-@item
-@strong{Separate_Run_Path_Options}: single
+@example
+type a2 is access int2;
+pragma No_Strict_Aliasing (a2);
+@end example
+@end quotation
-Indicates if there may be several run path options specified when linking an
-executable. Only authorized case-insensitive values are "true" or "false" (the
-default).
+Here again, the compiler now knows that the strict aliasing optimization
+should be suppressed for any reference to type @code{a2} and the
+expected behavior is obtained.
-@item
-@strong{Toolchain_Version}: single, indexed, case-insensitive index
+Finally, note that although the compiler can generate warnings for
+simple cases of unchecked conversions, there are tricker and more
+indirect ways of creating type incorrect aliases which the compiler
+cannot detect. Examples are the use of address overlays and unchecked
+conversions involving composite types containing access types as
+components. In such cases, no warnings are generated, but there can
+still be aliasing problems. One safe coding practice is to forbid the
+use of address clauses for type overlaying, and to allow unchecked
+conversion only for primitive types. This is not really a significant
+restriction since any possible desired effect can be achieved by
+unchecked conversion of access values.
-Index is a language name. Specify the version of a toolchain for a language.
+The aliasing analysis done in strict aliasing mode can certainly
+have significant benefits. We have seen cases of large scale
+application code where the time is increased by up to 5% by turning
+this optimization off. If you have code that includes significant
+usage of unchecked conversion, you might want to just stick with
+@code{-O1} and avoid the entire issue. If you get adequate
+performance at this level of optimization level, that's probably
+the safest approach. If tests show that you really need higher
+levels of optimization, then you can experiment with @code{-O2}
+and @code{-O2 -fno-strict-aliasing} to see how much effect this
+has on size and speed of the code. If you really need to use
+@code{-O2} with strict aliasing in effect, then you should
+review any uses of unchecked conversion of access types,
+particularly if you are getting the warnings described above.
-@item
-@strong{Toolchain_Description}: single, indexed, case-insensitive index
+@node Aliased Variables and Optimization,Atomic Variables and Optimization,Optimization and Strict Aliasing,Performance Considerations
+@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
-Obsolescent. No longer used.
-@item
-@strong{Object_Generated}: single, indexed, case-insensitive index
+@geindex Aliasing
-Index is a language name. Indicates if invoking the compiler for a language
-produces an object file. Only authorized case-insensitive values are "false"
-and "true" (the default).
+There are scenarios in which programs may
+use low level techniques to modify variables
+that otherwise might be considered to be unassigned. For example,
+a variable can be passed to a procedure by reference, which takes
+the address of the parameter and uses the address to modify the
+variable's value, even though it is passed as an IN parameter.
+Consider the following example:
-@item
-@strong{Objects_Linked}: single, indexed, case-insensitive index
+@quotation
-Index is a language name. Indicates if the object files created by the compiler
-for a language need to be linked in the executable. Only authorized
-case-insensitive values are "false" and "true" (the default).
+@example
+procedure P is
+ Max_Length : constant Natural := 16;
+ type Char_Ptr is access all Character;
-@item
-@strong{Target}: single
+ procedure Get_String(Buffer: Char_Ptr; Size : Integer);
+ pragma Import (C, Get_String, "get_string");
-Value is the name of the target platform. Taken into account only in the main
-project.
+ Name : aliased String (1 .. Max_Length) := (others => ' ');
+ Temp : Char_Ptr;
-Note that when the target is specified on the command line (usually with
-a switch --target=), the value of attribute reference 'Target is the one
-specified on the command line.
+ function Addr (S : String) return Char_Ptr is
+ function To_Char_Ptr is
+ new Ada.Unchecked_Conversion (System.Address, Char_Ptr);
+ begin
+ return To_Char_Ptr (S (S'First)'Address);
+ end;
-@item
-@strong{Runtime}: single, indexed, case-insensitive index
+begin
+ Temp := Addr (Name);
+ Get_String (Temp, Max_Length);
+end;
+@end example
+@end quotation
-Index is a language name. Indicates the runtime directory that is to be used
-when using the compiler of the language. Taken into account only in the main
-project.
+where Get_String is a C function that uses the address in Temp to
+modify the variable @code{Name}. This code is dubious, and arguably
+erroneous, and the compiler would be entitled to assume that
+@code{Name} is never modified, and generate code accordingly.
-Note that when the runtime is specified for a language on the command line
-(usually with a switch --RTS), the value of attribute reference 'Runtime
-for this language is the one specified on the command line.
-@end itemize
+However, in practice, this would cause some existing code that
+seems to work with no optimization to start failing at high
+levels of optimzization.
-@item
-@strong{Configuration - Libraries}
+What the compiler does for such cases is to assume that marking
+a variable as aliased indicates that some "funny business" may
+be going on. The optimizer recognizes the aliased keyword and
+inhibits optimizations that assume the value cannot be assigned.
+This means that the above example will in fact "work" reliably,
+that is, it will produce the expected results.
+@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{18f}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{190}
+@subsubsection Atomic Variables and Optimization
-@itemize *
-@item
-@strong{Library_Builder}: single
+@geindex Atomic
-Value is the path name of the application that is to be used to build
-libraries. Usually the path name of "gprlib".
+There are two considerations with regard to performance when
+atomic variables are used.
-@item
-@strong{Library_Support}: single
+First, the RM only guarantees that access to atomic variables
+be atomic, it has nothing to say about how this is achieved,
+though there is a strong implication that this should not be
+achieved by explicit locking code. Indeed GNAT will never
+generate any locking code for atomic variable access (it will
+simply reject any attempt to make a variable or type atomic
+if the atomic access cannot be achieved without such locking code).
-Indicates the level of support of libraries. Only authorized case-insensitive
-values are "static_only", "full" or "none" (the default).
-@end itemize
+That being said, it is important to understand that you cannot
+assume that the entire variable will always be accessed. Consider
+this example:
-@item
-@strong{Configuration - Archives}
+@quotation
+@example
+type R is record
+ A,B,C,D : Character;
+end record;
+for R'Size use 32;
+for R'Alignment use 4;
-@itemize *
+RV : R;
+pragma Atomic (RV);
+X : Character;
+...
+X := RV.B;
+@end example
+@end quotation
-@item
-@strong{Archive_Builder}: list
+You cannot assume that the reference to @code{RV.B}
+will read the entire 32-bit
+variable with a single load instruction. It is perfectly legitimate if
+the hardware allows it to do a byte read of just the B field. This read
+is still atomic, which is all the RM requires. GNAT can and does take
+advantage of this, depending on the architecture and optimization level.
+Any assumption to the contrary is non-portable and risky. Even if you
+examine the assembly language and see a full 32-bit load, this might
+change in a future version of the compiler.
-Value is the name of the application to be used to create a static library
-(archive), followed by the options to be used.
+If your application requires that all accesses to @code{RV} in this
+example be full 32-bit loads, you need to make a copy for the access
+as in:
-@item
-@strong{Archive_Builder_Append_Option}: list
+@quotation
-Value is the list of options to be used when invoking the archive builder
-to add project files into an archive.
+@example
+declare
+ RV_Copy : constant R := RV;
+begin
+ X := RV_Copy.B;
+end;
+@end example
+@end quotation
-@item
-@strong{Archive_Indexer}: list
+Now the reference to RV must read the whole variable.
+Actually one can imagine some compiler which figures
+out that the whole copy is not required (because only
+the B field is actually accessed), but GNAT
+certainly won't do that, and we don't know of any
+compiler that would not handle this right, and the
+above code will in practice work portably across
+all architectures (that permit the Atomic declaration).
-Value is the name of the archive indexer, followed by the required options.
+The second issue with atomic variables has to do with
+the possible requirement of generating synchronization
+code. For more details on this, consult the sections on
+the pragmas Enable/Disable_Atomic_Synchronization in the
+GNAT Reference Manual. If performance is critical, and
+such synchronization code is not required, it may be
+useful to disable it.
-@item
-@strong{Archive_Suffix}: single
+@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations
+@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
-Value is the extension of archives. When not declared, the extension is ".a".
-@item
-@strong{Library_Partial_Linker}: list
+@geindex Passive Task
-Value is the name of the partial linker executable, followed by the required
-options.
-@end itemize
+A passive task is one which is sufficiently simple that
+in theory a compiler could recognize it an implement it
+efficiently without creating a new thread. The original design
+of Ada 83 had in mind this kind of passive task optimization, but
+only a few Ada 83 compilers attempted it. The problem was that
+it was difficult to determine the exact conditions under which
+the optimization was possible. The result is a very fragile
+optimization where a very minor change in the program can
+suddenly silently make a task non-optimizable.
-@item
-@strong{Configuration - Shared Libraries}
+With the revisiting of this issue in Ada 95, there was general
+agreement that this approach was fundamentally flawed, and the
+notion of protected types was introduced. When using protected
+types, the restrictions are well defined, and you KNOW that the
+operations will be optimized, and furthermore this optimized
+performance is fully portable.
+Although it would theoretically be possible for GNAT to attempt to
+do this optimization, but it really doesn't make sense in the
+context of Ada 95, and none of the Ada 95 compilers implement
+this optimization as far as we know. In particular GNAT never
+attempts to perform this optimization.
-@itemize *
-
-@item
-@strong{Shared_Library_Prefix}: single
+In any new Ada 95 code that is written, you should always
+use protected types in place of tasks that might be able to
+be optimized in this manner.
+Of course this does not help if you have legacy Ada 83 code
+that depends on this optimization, but it is unusual to encounter
+a case where the performance gains from this optimization
+are significant.
-Value is the prefix in the name of shared library files. When not declared,
-the prefix is "lib".
+Your program should work correctly without this optimization. If
+you have performance problems, then the most practical
+approach is to figure out exactly where these performance problems
+arise, and update those particular tasks to be protected types. Note
+that typically clients of the tasks who call entries, will not have
+to be modified, only the task definition itself.
-@item
-@strong{Shared_Library_Suffix}: single
+@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{193}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{194}
+@subsection @code{Text_IO} Suggestions
-Value is the the extension of the name of shared library files. When not
-declared, the extension is ".so".
-@item
-@strong{Symbolic_Link_Supported}: single
+@geindex Text_IO and performance
-Indicates if symbolic links are supported on the platform. Only authorized
-case-insensitive values are "true" and "false" (the default).
+The @code{Ada.Text_IO} package has fairly high overheads due in part to
+the requirement of maintaining page and line counts. If performance
+is critical, a recommendation is to use @code{Stream_IO} instead of
+@code{Text_IO} for volume output, since this package has less overhead.
-@item
-@strong{Library_Major_Minor_Id_Supported}: single
+If @code{Text_IO} must be used, note that by default output to the standard
+output and standard error files is unbuffered (this provides better
+behavior when output statements are used for debugging, or if the
+progress of a program is observed by tracking the output, e.g. by
+using the Unix @emph{tail -f} command to watch redirected output.
-Indicates if major and minor ids for shared library names are supported on
-the platform. Only authorized case-insensitive values are "true" and "false"
-(the default).
+If you are generating large volumes of output with @code{Text_IO} and
+performance is an important factor, use a designated file instead
+of the standard output file, or change the standard output file to
+be buffered using @code{Interfaces.C_Streams.setvbuf}.
-@item
-@strong{Library_Auto_Init_Supported}: single
+@node Reducing Size of Executables with Unused Subprogram/Data Elimination,,Text_IO Suggestions,Improving Performance
+@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
-Indicates if auto-initialization of Stand-Alone Libraries is supported. Only
-authorized case-insensitive values are "true" and "false" (the default).
-@item
-@strong{Shared_Library_Minimum_Switches}: list
+@geindex Uunused subprogram/data elimination
-Value is the list of required switches when linking a shared library.
+This section describes how you can eliminate unused subprograms and data from
+your executable just by setting options at compilation time.
-@item
-@strong{Library_Version_Switches}: list
+@menu
+* About unused subprogram/data elimination::
+* Compilation options::
+* Example of unused subprogram/data elimination::
-Value is the list of switches to specify a internal name for a shared library.
+@end menu
-@item
-@strong{Library_Install_Name_Option}: single
+@node About unused subprogram/data elimination,Compilation options,,Reducing Size of Executables with Unused Subprogram/Data Elimination
+@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
-Value is the name of the option that needs to be used, concatenated with the
-path name of the library file, when linking a shared library.
-@item
-@strong{Runtime_Library_Dir}: single, indexed, case-insensitive index
+By default, an executable contains all code and data of its composing objects
+(directly linked or coming from statically linked libraries), even data or code
+never used by this executable.
-Index is a language name. Value is the path name of the directory where the
-runtime libraries are located.
+This feature will allow you to eliminate such unused code from your
+executable, making it smaller (in disk and in memory).
-@item
-@strong{Runtime_Source_Dir}: single, indexed, case-insensitive index
+This functionality is available on all Linux platforms except for the IA-64
+architecture and on all cross platforms using the ELF binary file format.
+In both cases GNU binutils version 2.16 or later are required to enable it.
-Index is a language name. Value is the path name of the directory where the
-sources of runtime libraries are located.
-@end itemize
-@end itemize
+@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 id43}@anchor{199}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{19a}
+@subsubsection Compilation options
-@node Package Binder Attributes,Package Builder Attributes,Project Level Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-binder-attributes}@anchor{1a6}@anchor{gnat_ugn/gnat_project_manager id49}@anchor{1a7}
-@subsubsection Package Binder Attributes
+The operation of eliminating the unused code and data from the final executable
+is directly performed by the linker.
+@geindex -ffunction-sections (gcc)
-@itemize *
+@geindex -fdata-sections (gcc)
-@item
-@strong{General}
+In order to do this, it has to work with objects compiled with the
+following options:
+@code{-ffunction-sections} @code{-fdata-sections}.
+These options are usable with C and Ada files.
+They will place respectively each
+function or data in a separate section in the resulting object file.
-@itemize *
+Once the objects and static libraries are created with these options, the
+linker can perform the dead code elimination. You can do this by setting
+the @code{-Wl,--gc-sections} option to gcc command or in the
+@code{-largs} section of @code{gnatmake}. This will perform a
+garbage collection of code and data never referenced.
-@item
-@strong{Default_Switches}: list, indexed, case-insensitive index
+If the linker performs a partial link (@code{-r} linker option), then you
+will need to provide the entry point using the @code{-e} / @code{--entry}
+linker option.
-Index is a language name. Value is the list of switches to be used when binding
-code of the language, if there is no applicable attribute Switches.
+Note that objects compiled without the @code{-ffunction-sections} and
+@code{-fdata-sections} options can still be linked with the executable.
+However, no dead code elimination will be performed on those objects (they will
+be linked as is).
-@item
-@strong{Switches}: list, optional index, indexed,
-case-insensitive index, others allowed
+The GNAT static library is now compiled with -ffunction-sections and
+-fdata-sections on some platforms. This allows you to eliminate the unused code
+and data of the GNAT library from your executable.
-Index is either a language name or a source file name. Value is the list of
-switches to be used when binding code. Index is either the source file name
-of the executable to be bound or the language name of the code to be bound.
-@end itemize
+@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 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
-@item
-@strong{Configuration - Binding}
+Here is a simple example:
-@itemize *
+@quotation
-@item
-@strong{Driver}: single, indexed, case-insensitive index
+@example
+with Aux;
-Index is a language name. Value is the name of the application to be used when
-binding code of the language.
+procedure Test is
+begin
+ Aux.Used (10);
+end Test;
-@item
-@strong{Required_Switches}: list, indexed, case-insensitive index
+package Aux is
+ Used_Data : Integer;
+ Unused_Data : Integer;
-Index is a language name. Value is the list of the required switches to be
-used when binding code of the language.
+ procedure Used (Data : Integer);
+ procedure Unused (Data : Integer);
+end Aux;
-@item
-@strong{Prefix}: single, indexed, case-insensitive index
+package body Aux is
+ procedure Used (Data : Integer) is
+ begin
+ Used_Data := Data;
+ end Used;
-Index is a language name. Value is a prefix to be used for the binder exchange
-file name for the language. Used to have different binder exchange file names
-when binding different languages.
+ procedure Unused (Data : Integer) is
+ begin
+ Unused_Data := Data;
+ end Unused;
+end Aux;
+@end example
+@end quotation
-@item
-@strong{Objects_Path}: single,indexed, case-insensitive index
+@code{Unused} and @code{Unused_Data} are never referenced in this code
+excerpt, and hence they may be safely removed from the final executable.
-Index is a language name. Value is the name of the environment variable that
-contains the path for the object directories.
+@quotation
-@item
-@strong{Object_Path_File}: single,indexed, case-insensitive index
+@example
+$ gnatmake test
-Index is a language name. Value is the name of the environment variable. The
-value of the environment variable is the path name of a text file that
-contains the list of object directories.
-@end itemize
-@end itemize
+$ nm test | grep used
+020015f0 T aux__unused
+02005d88 B aux__unused_data
+020015cc T aux__used
+02005d84 B aux__used_data
-@node Package Builder Attributes,Package Clean Attributes,Package Binder Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-builder-attributes}@anchor{1a8}@anchor{gnat_ugn/gnat_project_manager id50}@anchor{1a9}
-@subsubsection Package Builder Attributes
+$ gnatmake test -cargs -fdata-sections -ffunction-sections \\
+ -largs -Wl,--gc-sections
+$ nm test | grep used
+02005350 T aux__used
+0201ffe0 B aux__used_data
+@end example
+@end quotation
+It can be observed that the procedure @code{Unused} and the object
+@code{Unused_Data} are removed by the linker when using the
+appropriate options.
-@itemize *
+@geindex Overflow checks
-@item
-@strong{Default_Switches}: list, indexed, case-insensitive index
+@geindex Checks (overflow)
-Index is a language name. Value is the list of builder switches to be used when
-building an executable of the language, if there is no applicable attribute
-Switches.
+@node Overflow Check Handling in GNAT,Performing Dimensionality Analysis in GNAT,Improving Performance,GNAT and Program Execution
+@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
-@item
-@strong{Switches}: list, optional index, indexed, case-insensitive index,
-others allowed
-Index is either a language name or a source file name. Value is the list of
-builder switches to be used when building an executable. Index is either the
-source file name of the executable to be built or its language name.
+This section explains how to control the handling of overflow checks.
-@item
-@strong{Global_Compilation_Switches}: list, optional index, indexed,
-case-insensitive index
+@menu
+* Background::
+* Management of Overflows in GNAT::
+* Specifying the Desired Mode::
+* Default Settings::
+* Implementation Notes::
-Index is either a language name or a source file name. Value is the list of
-compilation switches to be used when building an executable. Index is either
-the source file name of the executable to be built or its language name.
+@end menu
-@item
-@strong{Executable}: single, indexed, case-insensitive index
+@node Background,Management of Overflows in GNAT,,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution id46}@anchor{19e}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{19f}
+@subsection Background
-Index is an executable source file name. Value is the simple file name of the
-executable to be built.
-@item
-@strong{Executable_Suffix}: single
+Overflow checks are checks that the compiler may make to ensure
+that intermediate results are not out of range. For example:
-Value is the extension of the file names of executable. When not specified,
-the extension is the default extension of executables on the platform.
+@quotation
-@item
-@strong{Global_Configuration_Pragmas}: single
+@example
+A : Integer;
+...
+A := A + 1;
+@end example
+@end quotation
-Value is the file name of a configuration pragmas file that is specified to
-the Ada compiler when compiling any Ada source in the project tree.
+If @code{A} has the value @code{Integer'Last}, then the addition may cause
+overflow since the result is out of range of the type @code{Integer}.
+In this case @code{Constraint_Error} will be raised if checks are
+enabled.
-@item
-@strong{Global_Config_File}: single, indexed, case-insensitive index
+A trickier situation arises in examples like the following:
-Index is a language name. Value is the file name of a configuration file that
-is specified to the compiler when compiling any source of the language in the
-project tree.
-@end itemize
+@quotation
+@example
+A, C : Integer;
+...
+A := (A + 1) + C;
+@end example
+@end quotation
-@node Package Clean Attributes,Package Compiler Attributes,Package Builder Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-clean-attributes}@anchor{1aa}@anchor{gnat_ugn/gnat_project_manager id52}@anchor{1ab}
-@subsubsection Package Clean Attributes
+where @code{A} is @code{Integer'Last} and @code{C} is @code{-1}.
+Now the final result of the expression on the right hand side is
+@code{Integer'Last} which is in range, but the question arises whether the
+intermediate addition of @code{(A + 1)} raises an overflow error.
+The (perhaps surprising) answer is that the Ada language
+definition does not answer this question. Instead it leaves
+it up to the implementation to do one of two things if overflow
+checks are enabled.
@itemize *
@item
-@strong{Switches}: list
-
-Value is a list of switches to be used by the cleaning application.
+raise an exception (@code{Constraint_Error}), or
@item
-@strong{Source_Artifact_Extensions}: list, indexed, case-insensitive index
+yield the correct mathematical result which is then used in
+subsequent operations.
+@end itemize
-Index is a language names. Value is the list of extensions for file names
-derived from object file names that need to be cleaned in the object
-directory of the project.
+If the compiler chooses the first approach, then the assignment of this
+example will indeed raise @code{Constraint_Error} if overflow checking is
+enabled, or result in erroneous execution if overflow checks are suppressed.
-@item
-@strong{Object_Artifact_Extensions}: list, indexed, case-insensitive index
+But if the compiler
+chooses the second approach, then it can perform both additions yielding
+the correct mathematical result, which is in range, so no exception
+will be raised, and the right result is obtained, regardless of whether
+overflow checks are suppressed.
-Index is a language names. Value is the list of extensions for file names
-derived from source file names that need to be cleaned in the object
-directory of the project.
+Note that in the first example an
+exception will be raised in either case, since if the compiler
+gives the correct mathematical result for the addition, it will
+be out of range of the target type of the assignment, and thus
+fails the range check.
-@item
-@strong{Artifacts_In_Object_Dir}: single
+This lack of specified behavior in the handling of overflow for
+intermediate results is a source of non-portability, and can thus
+be problematic when programs are ported. Most typically this arises
+in a situation where the original compiler did not raise an exception,
+and then the application is moved to a compiler where the check is
+performed on the intermediate result and an unexpected exception is
+raised.
-Value is a list of file names expressed as regular expressions that are to be
-deleted by gprclean in the object directory of the project.
+Furthermore, when using Ada 2012's preconditions and other
+assertion forms, another issue arises. Consider:
-@item
-@strong{Artifacts_In_Exec_Dir}: single
+@quotation
-Value is list of file names expressed as regular expressions that are to be
-deleted by gprclean in the exec directory of the main project.
-@end itemize
+@example
+procedure P (A, B : Integer) with
+ Pre => A + B <= Integer'Last;
+@end example
+@end quotation
-@node Package Compiler Attributes,Package Cross_Reference Attributes,Package Clean Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager id53}@anchor{1ac}@anchor{gnat_ugn/gnat_project_manager package-compiler-attributes}@anchor{1ad}
-@subsubsection Package Compiler Attributes
+One often wants to regard arithmetic in a context like this from
+a mathematical point of view. So for example, if the two actual parameters
+for a call to @code{P} are both @code{Integer'Last}, then
+the precondition should be regarded as False. If we are executing
+in a mode with run-time checks enabled for preconditions, then we would
+like this precondition to fail, rather than raising an exception
+because of the intermediate overflow.
+However, the language definition leaves the specification of
+whether the above condition fails (raising @code{Assert_Error}) or
+causes an intermediate overflow (raising @code{Constraint_Error})
+up to the implementation.
+The situation is worse in a case such as the following:
-@itemize *
+@quotation
-@item
-@strong{General}
+@example
+procedure Q (A, B, C : Integer) with
+ Pre => A + B + C <= Integer'Last;
+@end example
+@end quotation
+Consider the call
-@itemize *
+@quotation
-@item
-@strong{Default_Switches}: list, indexed, case-insensitive index
+@example
+Q (A => Integer'Last, B => 1, C => -1);
+@end example
+@end quotation
-Index is a language name. Value is a list of switches to be used when invoking
-the compiler for the language for a source of the project, if there is no
-applicable attribute Switches.
+From a mathematical point of view the precondition
+is True, but at run time we may (but are not guaranteed to) get an
+exception raised because of the intermediate overflow (and we really
+would prefer this precondition to be considered True at run time).
-@item
-@strong{Switches}: list, optional index, indexed, case-insensitive index,
-others allowed
+@node Management of Overflows in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT
+@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
-Index is a source file name or a language name. Value is the list of switches
-to be used when invoking the compiler for the source or for its language.
-@item
-@strong{Local_Configuration_Pragmas}: single
+To deal with the portability issue, and with the problem of
+mathematical versus run-time interpretation of the expressions in
+assertions, GNAT provides comprehensive control over the handling
+of intermediate overflow. GNAT can operate in three modes, and
+furthemore, permits separate selection of operating modes for
+the expressions within assertions (here the term 'assertions'
+is used in the technical sense, which includes preconditions and so forth)
+and for expressions appearing outside assertions.
-Value is the file name of a configuration pragmas file that is specified to
-the Ada compiler when compiling any Ada source in the project.
-
-@item
-@strong{Local_Config_File}: single, indexed, case-insensitive index
-
-Index is a language name. Value is the file name of a configuration file that
-is specified to the compiler when compiling any source of the language in the
-project.
-@end itemize
-
-@item
-@strong{Configuration - Compiling}
+The three modes are:
@itemize *
@item
-@strong{Driver}: single, indexed, case-insensitive index
-
-Index is a language name. Value is the name of the executable for the compiler
-of the language.
-
-@item
-@strong{Language_Kind}: single, indexed, case-insensitive index
+@emph{Use base type for intermediate operations} (@code{STRICT})
-Index is a language name. Indicates the kind of the language, either file based
-or unit based. Only authorized case-insensitive values are "unit_based" and
-"file_based" (the default).
-
-@item
-@strong{Dependency_Kind}: single, indexed, case-insensitive index
-
-Index is a language name. Indicates how the dependencies are handled for the
-language. Only authorized case-insensitive values are "makefile", "ali_file",
-"ali_closure" or "none" (the default).
+In this mode, all intermediate results for predefined arithmetic
+operators are computed using the base type, and the result must
+be in range of the base type. If this is not the
+case then either an exception is raised (if overflow checks are
+enabled) or the execution is erroneous (if overflow checks are suppressed).
+This is the normal default mode.
@item
-@strong{Required_Switches}: list, indexed, case-insensitive index
+@emph{Most intermediate overflows avoided} (@code{MINIMIZED})
-Equivalent to attribute Leading_Required_Switches.
+In this mode, the compiler attempts to avoid intermediate overflows by
+using a larger integer type, typically @code{Long_Long_Integer},
+as the type in which arithmetic is
+performed for predefined arithmetic operators. This may be slightly more
+expensive at
+run time (compared to suppressing intermediate overflow checks), though
+the cost is negligible on modern 64-bit machines. For the examples given
+earlier, no intermediate overflows would have resulted in exceptions,
+since the intermediate results are all in the range of
+@code{Long_Long_Integer} (typically 64-bits on nearly all implementations
+of GNAT). In addition, if checks are enabled, this reduces the number of
+checks that must be made, so this choice may actually result in an
+improvement in space and time behavior.
-@item
-@strong{Leading_Required_Switches}: list, indexed, case-insensitive index
+However, there are cases where @code{Long_Long_Integer} is not large
+enough, consider the following example:
-Index is a language name. Value is the list of the minimum switches to be used
-at the beginning of the command line when invoking the compiler for the
-language.
+@quotation
-@item
-@strong{Trailing_Required_Switches}: list, indexed, case-insensitive index
+@example
+procedure R (A, B, C, D : Integer) with
+ Pre => (A**2 * B**2) / (C**2 * D**2) <= 10;
+@end example
+@end quotation
-Index is a language name. Value is the list of the minimum switches to be used
-at the end of the command line when invoking the compiler for the language.
+where @code{A} = @code{B} = @code{C} = @code{D} = @code{Integer'Last}.
+Now the intermediate results are
+out of the range of @code{Long_Long_Integer} even though the final result
+is in range and the precondition is True (from a mathematical point
+of view). In such a case, operating in this mode, an overflow occurs
+for the intermediate computation (which is why this mode
+says @emph{most} intermediate overflows are avoided). In this case,
+an exception is raised if overflow checks are enabled, and the
+execution is erroneous if overflow checks are suppressed.
@item
-@strong{PIC_Option}: list, indexed, case-insensitive index
+@emph{All intermediate overflows avoided} (@code{ELIMINATED})
-Index is a language name. Value is the list of switches to be used when
-compiling a source of the language when the project is a shared library
-project.
+In this mode, the compiler avoids all intermediate overflows
+by using arbitrary precision arithmetic as required. In this
+mode, the above example with @code{A**2 * B**2} would
+not cause intermediate overflow, because the intermediate result
+would be evaluated using sufficient precision, and the result
+of evaluating the precondition would be True.
-@item
-@strong{Path_Syntax}: single, indexed, case-insensitive index
+This mode has the advantage of avoiding any intermediate
+overflows, but at the expense of significant run-time overhead,
+including the use of a library (included automatically in this
+mode) for multiple-precision arithmetic.
-Index is a language name. Value is the kind of path syntax to be used when
-invoking the compiler for the language. Only authorized case-insensitive
-values are "canonical" and "host" (the default).
+This mode provides cleaner semantics for assertions, since now
+the run-time behavior emulates true arithmetic behavior for the
+predefined arithmetic operators, meaning that there is never a
+conflict between the mathematical view of the assertion, and its
+run-time behavior.
-@item
-@strong{Source_File_Switches}: single, indexed, case-insensitive index
+Note that in this mode, the behavior is unaffected by whether or
+not overflow checks are suppressed, since overflow does not occur.
+It is possible for gigantic intermediate expressions to raise
+@code{Storage_Error} as a result of attempting to compute the
+results of such expressions (e.g. @code{Integer'Last ** Integer'Last})
+but overflow is impossible.
+@end itemize
-Index is a language name. Value is a list of switches to be used just before
-the path name of the source to compile when invoking the compiler for a source
-of the language.
+Note that these modes apply only to the evaluation of predefined
+arithmetic, membership, and comparison operators for signed integer
+arithmetic.
-@item
-@strong{Object_File_Suffix}: single, indexed, case-insensitive index
+For fixed-point arithmetic, checks can be suppressed. But if checks
+are enabled
+then fixed-point values are always checked for overflow against the
+base type for intermediate expressions (that is such checks always
+operate in the equivalent of @code{STRICT} mode).
-Index is a language name. Value is the extension of the object files created
-by the compiler of the language. When not specified, the extension is the
-default one for the platform.
+For floating-point, on nearly all architectures, @code{Machine_Overflows}
+is False, and IEEE infinities are generated, so overflow exceptions
+are never raised. If you want to avoid infinities, and check that
+final results of expressions are in range, then you can declare a
+constrained floating-point type, and range checks will be carried
+out in the normal manner (with infinite values always failing all
+range checks).
-@item
-@strong{Object_File_Switches}: list, indexed, case-insensitive index
+@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{e9}@anchor{gnat_ugn/gnat_and_program_execution id48}@anchor{1a2}
+@subsection Specifying the Desired Mode
-Index is a language name. Value is the list of switches to be used by the
-compiler of the language to specify the path name of the object file. When not
-specified, the switch used is "-o".
-@item
-@strong{Multi_Unit_Switches}: list, indexed, case-insensitive index
+@geindex pragma Overflow_Mode
-Index is a language name. Value is the list of switches to be used to compile
-a unit in a multi unit source of the language. The index of the unit in the
-source is concatenated with the last switches in the list.
+The desired mode of for handling intermediate overflow can be specified using
+either the @code{Overflow_Mode} pragma or an equivalent compiler switch.
+The pragma has the form
-@item
-@strong{Multi_Unit_Object_Separator}: single, indexed, case-insensitive index
+@quotation
-Index is a language name. Value is the string to be used in the object file
-name before the index of the unit, when compiling a unit in a multi unit source
-of the language.
-@end itemize
+@example
+pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]);
+@end example
+@end quotation
-@item
-@strong{Configuration - Mapping Files}
+where @code{MODE} is one of
@itemize *
@item
-@strong{Mapping_File_Switches}: list, indexed, case-insensitive index
-
-Index is a language name. Value is the list of switches to be used to specify
-a mapping file when invoking the compiler for a source of the language.
+@code{STRICT}: intermediate overflows checked (using base type)
@item
-@strong{Mapping_Spec_Suffix}: single, indexed, case-insensitive index
-
-Index is a language name. Value is the suffix to be used in a mapping file
-to indicate that the source is a spec.
+@code{MINIMIZED}: minimize intermediate overflows
@item
-@strong{Mapping_Body_Suffix}: single, indexed, case-insensitive index
-
-Index is a language name. Value is the suffix to be used in a mapping file
-to indicate that the source is a body.
+@code{ELIMINATED}: eliminate intermediate overflows
@end itemize
-@item
-@strong{Configuration - Config Files}
-
-
-@itemize *
+The case is ignored, so @code{MINIMIZED}, @code{Minimized} and
+@code{minimized} all have the same effect.
-@item
-@strong{Config_File_Switches}: list: single, indexed, case-insensitive index
-
-Index is a language name. Value is the list of switches to specify to the
-compiler of the language a configuration file.
+If only the @code{General} parameter is present, then the given @code{MODE} applies
+to expressions both within and outside assertions. If both arguments
+are present, then @code{General} applies to expressions outside assertions,
+and @code{Assertions} applies to expressions within assertions. For example:
-@item
-@strong{Config_Body_File_Name}: single, indexed, case-insensitive index
+@quotation
-Index is a language name. Value is the template to be used to indicate a
-configuration specific to a body of the language in a configuration
-file.
+@example
+pragma Overflow_Mode
+ (General => Minimized, Assertions => Eliminated);
+@end example
+@end quotation
-@item
-@strong{Config_Body_File_Name_Index}: single, indexed, case-insensitive index
+specifies that general expressions outside assertions be evaluated
+in 'minimize intermediate overflows' mode, and expressions within
+assertions be evaluated in 'eliminate intermediate overflows' mode.
+This is often a reasonable choice, avoiding excessive overhead
+outside assertions, but assuring a high degree of portability
+when importing code from another compiler, while incurring
+the extra overhead for assertion expressions to ensure that
+the behavior at run time matches the expected mathematical
+behavior.
-Index is a language name. Value is the template to be used to indicate a
-configuration specific to the body a unit in a multi unit source of the
-language in a configuration file.
+The @code{Overflow_Mode} pragma has the same scoping and placement
+rules as pragma @code{Suppress}, so it can occur either as a
+configuration pragma, specifying a default for the whole
+program, or in a declarative scope, where it applies to the
+remaining declarations and statements in that scope.
-@item
-@strong{Config_Body_File_Name_Pattern}: single, indexed,
-case-insensitive index
+Note that pragma @code{Overflow_Mode} does not affect whether
+overflow checks are enabled or suppressed. It only controls the
+method used to compute intermediate values. To control whether
+overflow checking is enabled or suppressed, use pragma @code{Suppress}
+or @code{Unsuppress} in the usual manner.
-Index is a language name. Value is the template to be used to indicate a
-configuration for all bodies of the languages in a configuration file.
+@geindex -gnato? (gcc)
-@item
-@strong{Config_Spec_File_Name}: single, indexed, case-insensitive index
+@geindex -gnato?? (gcc)
-Index is a language name. Value is the template to be used to indicate a
-configuration specific to a spec of the language in a configuration
-file.
+Additionally, a compiler switch @code{-gnato?} or @code{-gnato??}
+can be used to control the checking mode default (which can be subsequently
+overridden using pragmas).
-@item
-@strong{Config_Spec_File_Name_Index}: single, indexed, case-insensitive index
+Here @code{?} is one of the digits @code{1} through @code{3}:
-Index is a language name. Value is the template to be used to indicate a
-configuration specific to the spec a unit in a multi unit source of the
-language in a configuration file.
+@quotation
-@item
-@strong{Config_Spec_File_Name_Pattern}: single, indexed,
-case-insensitive index
-Index is a language name. Value is the template to be used to indicate a
-configuration for all specs of the languages in a configuration file.
+@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
+@item
-@item
-@strong{Config_File_Unique}: single, indexed, case-insensitive index
+@code{1}
-Index is a language name. Indicates if there should be only one configuration
-file specified to the compiler of the language. Only authorized
-case-insensitive values are "true" and "false" (the default).
-@end itemize
+@tab
-@item
-@strong{Configuration - Dependencies}
+use base type for intermediate operations (@code{STRICT})
+@item
-@itemize *
+@code{2}
-@item
-@strong{Dependency_Switches}: list, indexed, case-insensitive index
+@tab
-Index is a language name. Value is the list of switches to be used to specify
-to the compiler the dependency file when the dependency kind of the language is
-file based, and when Dependency_Driver is not specified for the language.
+minimize intermediate overflows (@code{MINIMIZED})
-@item
-@strong{Dependency_Driver}: list, indexed, case-insensitive index
+@item
-Index is a language name. Value is the name of the executable to be used to
-create the dependency file for a source of the language, followed by the
-required switches.
-@end itemize
+@code{3}
-@item
-@strong{Configuration - Search Paths}
+@tab
+eliminate intermediate overflows (@code{ELIMINATED})
-@itemize *
+@end multitable
-@item
-@strong{Include_Switches}: list, indexed, case-insensitive index
+@end quotation
-Index is a language name. Value is the list of switches to specify to the
-compiler of the language to indicate a directory to look for sources.
+As with the pragma, if only one digit appears then it applies to all
+cases; if two digits are given, then the first applies outside
+assertions, and the second within assertions. Thus the equivalent
+of the example pragma above would be
+@code{-gnato23}.
-@item
-@strong{Include_Path}: single, indexed, case-insensitive index
+If no digits follow the @code{-gnato}, then it is equivalent to
+@code{-gnato11},
+causing all intermediate operations to be computed using the base
+type (@code{STRICT} mode).
-Index is a language name. Value is the name of an environment variable that
-contains the path of all the directories that the compiler of the language
-may search for sources.
+@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution id49}@anchor{1a3}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{1a4}
+@subsection Default Settings
-@item
-@strong{Include_Path_File}: single, indexed, case-insensitive index
-Index is a language name. Value is the name of an environment variable the
-value of which is the path name of a text file that contains the directories
-that the compiler of the language may search for sources.
+The default mode for overflow checks is
-@item
-@strong{Object_Path_Switches}: list, indexed, case-insensitive index
+@quotation
-Index is a language name. Value is the list of switches to specify to the
-compiler of the language the name of a text file that contains the list of
-object directories. When this attribute is not declared, the text file is
-not created.
-@end itemize
-@end itemize
+@example
+General => Strict
+@end example
+@end quotation
-@node Package Cross_Reference Attributes,Package Finder Attributes,Package Compiler Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager id54}@anchor{1ae}@anchor{gnat_ugn/gnat_project_manager package-cross-reference-attributes}@anchor{1af}
-@subsubsection Package Cross_Reference Attributes
+which causes all computations both inside and outside assertions to use
+the base type.
+This retains compatibility with previous versions of
+GNAT which suppressed overflow checks by default and always
+used the base type for computation of intermediate results.
+@c Sphinx allows no emphasis within :index: role. As a workaround we
+@c point the index to "switch" and use emphasis for "-gnato".
-@itemize *
+The
+@geindex -gnato (gcc)
+switch @code{-gnato} (with no digits following)
+is equivalent to
-@item
-@strong{Default_Switches}: list, indexed, case-insensitive index
+@quotation
-Index is a language name. Value is a list of switches to be used when invoking
-@cite{gnatxref} for a source of the language, if there is no applicable
-attribute Switches.
+@example
+General => Strict
+@end example
+@end quotation
-@item
-@strong{Switches}: list, optional index, indexed, case-insensitive index,
-others allowed
+which causes overflow checking of all intermediate overflows
+both inside and outside assertions against the base type.
-Index is a source file name. Value is the list of switches to be used when
-invoking @cite{gnatxref} for the source.
-@end itemize
+The pragma @code{Suppress (Overflow_Check)} disables overflow
+checking, but it has no effect on the method used for computing
+intermediate results.
+The pragma @code{Unsuppress (Overflow_Check)} enables overflow
+checking, but it has no effect on the method used for computing
+intermediate results.
-@node Package Finder Attributes,Package gnatls Attributes,Package Cross_Reference Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager id56}@anchor{1b0}@anchor{gnat_ugn/gnat_project_manager package-finder-attributes}@anchor{1b1}
-@subsubsection Package Finder Attributes
+@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT
+@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{1a5}@anchor{gnat_ugn/gnat_and_program_execution id50}@anchor{1a6}
+@subsection Implementation Notes
+In practice on typical 64-bit machines, the @code{MINIMIZED} mode is
+reasonably efficient, and can be generally used. It also helps
+to ensure compatibility with code imported from some other
+compiler to GNAT.
-@itemize *
+Setting all intermediate overflows checking (@code{CHECKED} mode)
+makes sense if you want to
+make sure that your code is compatible with any other possible
+Ada implementation. This may be useful in ensuring portability
+for code that is to be exported to some other compiler than GNAT.
-@item
-@strong{Default_Switches}: list, indexed, case-insensitive index
+The Ada standard allows the reassociation of expressions at
+the same precedence level if no parentheses are present. For
+example, @code{A+B+C} parses as though it were @code{(A+B)+C}, but
+the compiler can reintepret this as @code{A+(B+C)}, possibly
+introducing or eliminating an overflow exception. The GNAT
+compiler never takes advantage of this freedom, and the
+expression @code{A+B+C} will be evaluated as @code{(A+B)+C}.
+If you need the other order, you can write the parentheses
+explicitly @code{A+(B+C)} and GNAT will respect this order.
-Index is a language name. Value is a list of switches to be used when invoking
-@cite{gnatfind} for a source of the language, if there is no applicable
-attribute Switches.
+The use of @code{ELIMINATED} mode will cause the compiler to
+automatically include an appropriate arbitrary precision
+integer arithmetic package. The compiler will make calls
+to this package, though only in cases where it cannot be
+sure that @code{Long_Long_Integer} is sufficient to guard against
+intermediate overflows. This package does not use dynamic
+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).
-@item
-@strong{Switches}: list, optional index, indexed, case-insensitive index,
-others allowed
+Although @code{ELIMINATED} mode causes expressions to use arbitrary
+precision arithmetic, avoiding overflow, the final result
+must be in an appropriate range. This is true even if the
+final result is of type @code{[Long_[Long_]]Integer'Base}, which
+still has the same bounds as its associated constrained
+type at run-time.
-Index is a source file name. Value is the list of switches to be used when
-invoking @cite{gnatfind} for the source.
-@end itemize
+Currently, the @code{ELIMINATED} mode is only available on target
+platforms for which @code{Long_Long_Integer} is 64-bits (nearly all GNAT
+platforms).
-@node Package gnatls Attributes,Package IDE Attributes,Package Finder Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-gnatls-attributes}@anchor{1b2}@anchor{gnat_ugn/gnat_project_manager id57}@anchor{1b3}
-@subsubsection Package gnatls Attributes
+@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 performing-dimensionality-analysis-in-gnat}@anchor{1a7}@anchor{gnat_ugn/gnat_and_program_execution id51}@anchor{14a}
+@section Performing Dimensionality Analysis in GNAT
+@geindex Dimensionality analysis
-@itemize *
+The GNAT compiler supports dimensionality checking. The user can
+specify physical units for objects, and the compiler will verify that uses
+of these objects are compatible with their dimensions, in a fashion that is
+familiar to engineering practice. The dimensions of algebraic expressions
+(including powers with static exponents) are computed from their constituents.
-@item
-@strong{Switches}: list
+@geindex Dimension_System aspect
-Value is a list of switches to be used when invoking @cite{gnatls}.
-@end itemize
+@geindex Dimension aspect
+This feature depends on Ada 2012 aspect specifications, and is available from
+version 7.0.1 of GNAT onwards.
+The GNAT-specific aspect @code{Dimension_System}
+allows you to define a system of units; the aspect @code{Dimension}
+then allows the user to declare dimensioned quantities within a given system.
+(These aspects are described in the @emph{Implementation Defined Aspects}
+chapter of the @emph{GNAT Reference Manual}).
-@node Package IDE Attributes,Package Install Attributes,Package gnatls Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager id58}@anchor{1b4}@anchor{gnat_ugn/gnat_project_manager package-ide-attributes}@anchor{1b5}
-@subsubsection Package IDE Attributes
+The major advantage of this model is that it does not require the declaration of
+multiple operators for all possible combinations of types: it is only necessary
+to use the proper subtypes in object declarations.
+@geindex System.Dim.Mks package (GNAT library)
+@geindex MKS_Type type
-@itemize *
+The simplest way to impose dimensionality checking on a computation is to make
+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}.
-@item
-@strong{Default_Switches}: list, indexed
+@quotation
-Index is the name of an external tool that the GNAT Programming System (GPS)
-is supporting. Value is a list of switches to use when invoking that tool.
+@geindex s-digemk.ads file
-@item
-@strong{Remote_Host}: single
+@example
+type Mks_Type is new Float_Type
+ with
+ Dimension_System => (
+ (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
+ (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
+ (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
+ (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
+ (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"),
+ (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
+ (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
+@end example
+@end quotation
-Value is a string that designates the remote host in a cross-compilation
-environment, to be used for remote compilation and debugging. This attribute
-should not be specified when running on the local machine.
+The package then defines a series of subtypes that correspond to these
+conventional units. For example:
-@item
-@strong{Program_Host}: single
+@quotation
-Value is a string that specifies the name of IP address of the embedded target
-in a cross-compilation environment, on which the program should execute.
+@example
+subtype Length is Mks_Type
+ with
+ Dimension => (Symbol => 'm', Meter => 1, others => 0);
+@end example
+@end quotation
-@item
-@strong{Communication_Protocol}: single
+and similarly for @code{Mass}, @code{Time}, @code{Electric_Current},
+@code{Thermodynamic_Temperature}, @code{Amount_Of_Substance}, and
+@code{Luminous_Intensity} (the standard set of units of the SI system).
-Value is the name of the protocol to use to communicate with the target
-in a cross-compilation environment, for example @cite{"wtx"} or
-@cite{"vxworks"}.
+The package also defines conventional names for values of each unit, for
+example:
-@item
-@strong{Compiler_Command}: single, indexed, case-insensitive index
+@quotation
-Index is a language Name. Value is a string that denotes the command to be
-used to invoke the compiler. For historical reasons, the value of
-@cite{Compiler_Command ("Ada")} is expected to be a reference to @emph{gnatmake} or
-@emph{cross-gnatmake}.
+@example
+m : constant Length := 1.0;
+kg : constant Mass := 1.0;
+s : constant Time := 1.0;
+A : constant Electric_Current := 1.0;
+@end example
+@end quotation
-@item
-@strong{Debugger_Command}: single
+as well as useful multiples of these units:
-Value is a string that specifies the name of the debugger to be used, such as
-gdb, powerpc-wrs-vxworks-gdb or gdb-4.
+@quotation
-@item
-@strong{gnatlist}: single
+@example
+ cm : constant Length := 1.0E-02;
+ g : constant Mass := 1.0E-03;
+ min : constant Time := 60.0;
+ day : constant Time := 60.0 * 24.0 * min;
+...
+@end example
+@end quotation
-Value is a string that specifies the name of the @emph{gnatls} utility
-to be used to retrieve information about the predefined path; for example,
-@cite{"gnatls"}, @cite{"powerpc-wrs-vxworks-gnatls"}.
+There are three instantiations of @code{System.Dim.Generic_Mks} defined in the
+GNAT library:
-@item
-@strong{VCS_Kind}: single
-Value is a string used to specify the Version Control System (VCS) to be used
-for this project, for example "Subversion", "ClearCase". If the
-value is set to "Auto", the IDE will try to detect the actual VCS used
-on the list of supported ones.
+@itemize *
@item
-@strong{VCS_File_Check}: single
-
-Value is a string that specifies the command used by the VCS to check
-the validity of a file, either when the user explicitly asks for a check,
-or as a sanity check before doing the check-in.
+@code{System.Dim.Float_Mks} based on @code{Float} defined in @code{s-diflmk.ads}.
@item
-@strong{VCS_Log_Check}: single
-
-Value is a string that specifies the command used by the VCS to check
-the validity of a log file.
+@code{System.Dim.Long_Mks} based on @code{Long_Float} defined in @code{s-dilomk.ads}.
@item
-@strong{Documentation_Dir}: single
-
-Value is the directory used to generate the documentation of source code.
+@code{System.Dim.Mks} based on @code{Long_Long_Float} defined in @code{s-dimmks.ads}.
@end itemize
-@node Package Install Attributes,Package Linker Attributes,Package IDE Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-install-attributes}@anchor{1b6}@anchor{gnat_ugn/gnat_project_manager id59}@anchor{1b7}
-@subsubsection Package Install Attributes
-
+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
-@itemize *
+@example
+subtype Acceleration is Mks_Type
+ with Dimension => ("m/sec^2",
+ Meter => 1,
+ Second => -2,
+ others => 0);
+@end example
+@end quotation
-@item
-@strong{Artifacts}: list, indexed
+Here is a complete example of use:
-An array attribute to declare a set of files not part of the sources
-to be installed. The array discriminant is the directory where the
-file is to be installed. If a relative directory then Prefix (see
-below) is prepended. Note also that if the same file name occurs
-multiple time in the attribute list, the last one will be the one
-installed.
+@quotation
-@item
-@strong{Prefix}: single
+@example
+with System.Dim.MKS; use System.Dim.Mks;
+with System.Dim.Mks_IO; use System.Dim.Mks_IO;
+with Text_IO; use Text_IO;
+procedure Free_Fall is
+ subtype Acceleration is Mks_Type
+ with Dimension => ("m/sec^2", 1, 0, -2, others => 0);
+ G : constant acceleration := 9.81 * m / (s ** 2);
+ T : Time := 10.0*s;
+ Distance : Length;
-Value is the install destination directory.
+begin
+ Put ("Gravitational constant: ");
+ Put (G, Aft => 2, Exp => 0); Put_Line ("");
+ Distance := 0.5 * G * T ** 2;
+ Put ("distance travelled in 10 seconds of free fall ");
+ Put (Distance, Aft => 2, Exp => 0);
+ Put_Line ("");
+end Free_Fall;
+@end example
+@end quotation
-@item
-@strong{Sources_Subdir}: single
+Execution of this program yields:
-Value is the sources directory or subdirectory of Prefix.
+@quotation
-@item
-@strong{Exec_Subdir}: single
+@example
+Gravitational constant: 9.81 m/sec^2
+distance travelled in 10 seconds of free fall 490.50 m
+@end example
+@end quotation
-Value is the executables directory or subdirectory of Prefix.
+However, incorrect assignments such as:
-@item
-@strong{Lib_Subdir}: single
+@quotation
-Value is library directory or subdirectory of Prefix.
+@example
+Distance := 5.0;
+Distance := 5.0 * kg;
+@end example
+@end quotation
-@item
-@strong{Project_Subdir}: single
+are rejected with the following diagnoses:
-Value is the project directory or subdirectory of Prefix.
+@quotation
-@item
-@strong{Active}: single
+@example
+Distance := 5.0;
+ >>> dimensions mismatch in assignment
+ >>> left-hand side has dimension [L]
+ >>> right-hand side is dimensionless
-Indicates that the project is to be installed or not. Case-insensitive value
-"false" means that the project is not to be installed, all other values mean
-that the project is to be installed.
+Distance := 5.0 * kg:
+ >>> dimensions mismatch in assignment
+ >>> left-hand side has dimension [L]
+ >>> right-hand side has dimension [M]
+@end example
+@end quotation
-@item
-@strong{Mode}: single
+The dimensions of an expression are properly displayed, even if there is
+no explicit subtype for it. If we add to the program:
-Value is the installation mode, it is either @strong{dev} (default) or @strong{usage}.
+@quotation
-@item
-@strong{Install_Name}: single
+@example
+Put ("Final velocity: ");
+Put (G * T, Aft =>2, Exp =>0);
+Put_Line ("");
+@end example
+@end quotation
-Specify the name to use for recording the installation. The default is
-the project name without the extension.
-@end itemize
+then the output includes:
-@node Package Linker Attributes,Package Naming Attributes,Package Install Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager id60}@anchor{1b8}@anchor{gnat_ugn/gnat_project_manager package-linker-attributes}@anchor{1b9}
-@subsubsection Package Linker Attributes
+@quotation
+@example
+Final velocity: 98.10 m.s**(-1)
+@end example
+@geindex Dimensionable type
-@itemize *
+@geindex Dimensioned subtype
+@end quotation
-@item
-@strong{General}
+The type @code{Mks_Type} is said to be a @emph{dimensionable type} since it has a
+@code{Dimension_System} aspect, and the subtypes @code{Length}, @code{Mass}, etc.,
+are said to be @emph{dimensioned subtypes} since each one has a @code{Dimension}
+aspect.
+@quotation
-@itemize *
+@geindex Dimension Vector (for a dimensioned subtype)
-@item
-@strong{Required_Switches}: list
+@geindex Dimension aspect
-Value is a list of switches that are required when invoking the linker to link
-an executable.
+@geindex Dimension_System aspect
+@end quotation
-@item
-@strong{Default_Switches}: list, indexed, case-insensitive index
+The @code{Dimension} aspect of a dimensioned subtype @code{S} defines a mapping
+from the base type's Unit_Names to integer (or, more generally, rational)
+values. This mapping is the @emph{dimension vector} (also referred to as the
+@emph{dimensionality}) for that subtype, denoted by @code{DV(S)}, and thus for each
+object of that subtype. Intuitively, the value specified for each
+@code{Unit_Name} is the exponent associated with that unit; a zero value
+means that the unit is not used. For example:
-Index is a language name. Value is a list of switches for the linker when
-linking an executable for a main source of the language, when there is no
-applicable Switches.
+@quotation
-@item
-@strong{Leading_Switches}: list, optional index, indexed,
-case-insensitive index, others allowed
+@example
+declare
+ Acc : Acceleration;
+ ...
+begin
+ ...
+end;
+@end example
+@end quotation
-Index is a source file name or a language name. Value is the list of switches
-to be used at the beginning of the command line when invoking the linker to
-build an executable for the source or for its language.
+Here @code{DV(Acc)} = @code{DV(Acceleration)} =
+@code{(Meter=>1, Kilogram=>0, Second=>-2, Ampere=>0, Kelvin=>0, Mole=>0, Candela=>0)}.
+Symbolically, we can express this as @code{Meter / Second**2}.
-@item
-@strong{Switches}: list, optional index, indexed, case-insensitive index,
-others allowed
+The dimension vector of an arithmetic expression is synthesized from the
+dimension vectors of its components, with compile-time dimensionality checks
+that help prevent mismatches such as using an @code{Acceleration} where a
+@code{Length} is required.
-Index is a source file name or a language name. Value is the list of switches
-to be used when invoking the linker to build an executable for the source or
-for its language.
+The dimension vector of the result of an arithmetic expression @emph{expr}, or
+@code{DV(@emph{expr})}, is defined as follows, assuming conventional
+mathematical definitions for the vector operations that are used:
-@item
-@strong{Trailing_Switches}: list, optional index, indexed,
-case-insensitive index, others allowed
-Index is a source file name or a language name. Value is the list of switches
-to be used at the end of the command line when invoking the linker to
-build an executable for the source or for its language. These switches may
-override the Required_Switches.
+@itemize *
@item
-@strong{Linker_Options}: list
-
-Value is a list of switches/options that are to be added when linking an
-executable from a project importing the current project directly or indirectly.
-Linker_Options are not used when linking an executable from the current
-project.
+If @emph{expr} is of the type @emph{universal_real}, or is not of a dimensioned subtype,
+then @emph{expr} is dimensionless; @code{DV(@emph{expr})} is the empty vector.
@item
-@strong{Map_File_Option}: single
-
-Value is the switch to specify the map file name that the linker needs to
-create.
-@end itemize
+@code{DV(@emph{op expr})}, where @emph{op} is a unary operator, is @code{DV(@emph{expr})}
@item
-@strong{Configuration - Linking}
-
-
-@itemize *
+@code{DV(@emph{expr1 op expr2})} where @emph{op} is "+" or "-" is @code{DV(@emph{expr1})}
+provided that @code{DV(@emph{expr1})} = @code{DV(@emph{expr2})}.
+If this condition is not met then the construct is illegal.
@item
-@strong{Driver}: single
+@code{DV(@emph{expr1} * @emph{expr2})} is @code{DV(@emph{expr1})} + @code{DV(@emph{expr2})},
+and @code{DV(@emph{expr1} / @emph{expr2})} = @code{DV(@emph{expr1})} - @code{DV(@emph{expr2})}.
+In this context if one of the @emph{expr}s is dimensionless then its empty
+dimension vector is treated as @code{(others => 0)}.
-Value is the name of the linker executable.
+@item
+@code{DV(@emph{expr} ** @emph{power})} is @emph{power} * @code{DV(@emph{expr})},
+provided that @emph{power} is a static rational value. If this condition is not
+met then the construct is illegal.
@end itemize
-@item
-@strong{Configuration - Response Files}
+Note that, by the above rules, it is illegal to use binary "+" or "-" to
+combine a dimensioned and dimensionless value. Thus an expression such as
+@code{acc-10.0} is illegal, where @code{acc} is an object of subtype
+@code{Acceleration}.
+The dimensionality checks for relationals use the same rules as
+for "+" and "-", except when comparing to a literal; thus
-@itemize *
+@quotation
-@item
-@strong{Max_Command_Line_Length}: single
+@example
+acc > len
+@end example
+@end quotation
-Value is the maximum number of character in the command line when invoking
-the linker to link an executable.
+is equivalent to
-@item
-@strong{Response_File_Format}: single
+@quotation
-Indicates the kind of response file to create when the length of the linking
-command line is too large. Only authorized case-insensitive values are "none",
-"gnu", "object_list", "gcc_gnu", "gcc_option_list" and "gcc_object_list".
+@example
+acc-len > 0.0
+@end example
+@end quotation
-@item
-@strong{Response_File_Switches}: list
+and is thus illegal, but
-Value is the list of switches to specify a response file to the linker.
-@end itemize
-@end itemize
+@quotation
+
+@example
+acc > 10.0
+@end example
+@end quotation
-@c only PRO or GPL
-@c
-@c .. _Package_Metrics_Attribute:
-@c
-@c Package Metrics Attribute
-@c ^^^^^^^^^^^^^^^^^^^^^^^^^
-@c
-@c * **Default_Switches**: list, indexed, case-insensitive index
-@c
-@c Index is a language name. Value is a list of switches to be used when invoking
-@c `gnatmetric` for a source of the language, if there is no applicable
-@c attribute Switches.
-@c
-@c * **Switches**: list, optional index, indexed, case-insensitive index,
-@c others allowed
-@c
-@c Index is a source file name. Value is the list of switches to be used when
-@c invoking `gnatmetric` for the source.
-
-@node Package Naming Attributes,Package Remote Attributes,Package Linker Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-naming-attributes}@anchor{1ba}@anchor{gnat_ugn/gnat_project_manager id61}@anchor{1bb}
-@subsubsection Package Naming Attributes
+is accepted with a warning. Analogously a conditional expression requires the
+same dimension vector for each branch (with no exception for literals).
+The dimension vector of a type conversion @code{T(@emph{expr})} is defined
+as follows, based on the nature of @code{T}:
@itemize *
@item
-@strong{Specification_Suffix}: single, indexed, case-insensitive index
+If @code{T} is a dimensioned subtype then @code{DV(T(@emph{expr}))} is @code{DV(T)}
+provided that either @emph{expr} is dimensionless or
+@code{DV(T)} = @code{DV(@emph{expr})}. The conversion is illegal
+if @emph{expr} is dimensioned and @code{DV(@emph{expr})} /= @code{DV(T)}.
+Note that vector equality does not require that the corresponding
+Unit_Names be the same.
-Equivalent to attribute Spec_Suffix.
+As a consequence of the above rule, it is possible to convert between
+different dimension systems that follow the same international system
+of units, with the seven physical components given in the standard order
+(length, mass, time, etc.). Thus a length in meters can be converted to
+a length in inches (with a suitable conversion factor) but cannot be
+converted, for example, to a mass in pounds.
@item
-@strong{Spec_Suffix}: single, indexed, case-insensitive index
+If @code{T} is the base type for @emph{expr} (and the dimensionless root type of
+the dimension system), then @code{DV(T(@emph{expr}))} is @code{DV(expr)}.
+Thus, if @emph{expr} is of a dimensioned subtype of @code{T}, the conversion may
+be regarded as a "view conversion" that preserves dimensionality.
-Index is a language name. Value is the extension of file names for specs of
-the language.
+This rule makes it possible to write generic code that can be instantiated
+with compatible dimensioned subtypes. The generic unit will contain
+conversions that will consequently be present in instantiations, but
+conversions to the base type will preserve dimensionality and make it
+possible to write generic code that is correct with respect to
+dimensionality.
@item
-@strong{Implementation_Suffix}: single, indexed, case-insensitive index
+Otherwise (i.e., @code{T} is neither a dimensioned subtype nor a dimensionable
+base type), @code{DV(T(@emph{expr}))} is the empty vector. Thus a dimensioned
+value can be explicitly converted to a non-dimensioned subtype, which
+of course then escapes dimensionality analysis.
+@end itemize
-Equivalent to attribute Body_Suffix.
+The dimension vector for a type qualification @code{T'(@emph{expr})} is the same
+as for the type conversion @code{T(@emph{expr})}.
-@item
-@strong{Body_Suffix}: single, indexed, case-insensitive index
+An assignment statement
-Index is a language name. Value is the extension of file names for bodies of
-the language.
+@quotation
-@item
-@strong{Separate_Suffix}: single
+@example
+Source := Target;
+@end example
+@end quotation
-Value is the extension of file names for subunits of Ada.
+requires @code{DV(Source)} = @code{DV(Target)}, and analogously for parameter
+passing (the dimension vector for the actual parameter must be equal to the
+dimension vector for the formal parameter).
-@item
-@strong{Casing}: single
+@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{1a8}@anchor{gnat_ugn/gnat_and_program_execution id52}@anchor{14b}
+@section Stack Related Facilities
-Indicates the casing of sources of the Ada language. Only authorized
-case-insensitive values are "lowercase", "uppercase" and "mixedcase".
-@item
-@strong{Dot_Replacement}: single
+This section describes some useful tools associated with stack
+checking and analysis. In
+particular, it deals with dynamic and static stack usage measurements.
-Value is the string that replace the dot of unit names in the source file names
-of the Ada language.
+@menu
+* Stack Overflow Checking::
+* Static Stack Usage Analysis::
+* Dynamic Stack Usage Analysis::
-@item
-@strong{Specification}: single, optional index, indexed,
-case-insensitive index
+@end menu
-Equivalent to attribute Spec.
+@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities
+@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
-@item
-@strong{Spec}: single, optional index, indexed, case-insensitive index
-Index is a unit name. Value is the file name of the spec of the unit.
+@geindex Stack Overflow Checking
-@item
-@strong{Implementation}: single, optional index, indexed,
-case-insensitive index
+@geindex -fstack-check (gcc)
-Equivalent to attribute Body.
+For most operating systems, @code{gcc} does not perform stack overflow
+checking by default. This means that if the main environment task or
+some other task exceeds the available stack space, then unpredictable
+behavior will occur. Most native systems offer some level of protection by
+adding a guard page at the end of each task stack. This mechanism is usually
+not enough for dealing properly with stack overflow situations because
+a large local variable could "jump" above the guard page.
+Furthermore, when the
+guard page is hit, there may not be any space left on the stack for executing
+the exception propagation code. Enabling stack checking avoids
+such situations.
-@item
-@strong{Body}: single, optional index, indexed, case-insensitive index
+To activate stack checking, compile all units with the @code{gcc} option
+@code{-fstack-check}. For example:
-Index is a unit name. Value is the file name of the body of the unit.
+@quotation
-@item
-@strong{Specification_Exceptions}: list, indexed, case-insensitive index
+@example
+$ gcc -c -fstack-check package1.adb
+@end example
+@end quotation
-Index is a language name. Value is a list of specs for the language that do not
-necessarily follow the naming scheme for the language and that may or may not
-be found in the source directories of the project.
+Units compiled with this option will generate extra instructions to check
+that any use of the stack (for procedure calls or for declaring local
+variables in declare blocks) does not exceed the available stack space.
+If the space is exceeded, then a @code{Storage_Error} exception is raised.
-@item
-@strong{Implementation_Exceptions}: list, indexed, case-insensitive index
+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{110,,Switches for gnatbind}). Task specific stack sizes may be set using the
+@code{Storage_Size} pragma.
-Index is a language name. Value is a list of bodies for the language that do not
-necessarily follow the naming scheme for the language and that may or may not
-be found in the source directories of the project.
-@end itemize
+For the environment task, the stack size is determined by the operating system.
+Consequently, to modify the size of the environment task please refer to your
+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 id54}@anchor{1aa}@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{e6}
+@subsection Static Stack Usage Analysis
-@node Package Remote Attributes,Package Stack Attributes,Package Naming Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-remote-attributes}@anchor{1bc}@anchor{gnat_ugn/gnat_project_manager id63}@anchor{1bd}
-@subsubsection Package Remote Attributes
+@geindex Static Stack Usage Analysis
+@geindex -fstack-usage
-@itemize *
+A unit compiled with @code{-fstack-usage} will generate an extra file
+that specifies
+the maximum amount of stack used, on a per-function basis.
+The file has the same
+basename as the target object file with a @code{.su} extension.
+Each line of this file is made up of three fields:
-@item
-@strong{Included_Patterns}: list
-If this attribute is defined it sets the patterns to
-synchronized from the master to the slaves. It is exclusive
-with Excluded_Patterns, that is it is an error to define
-both.
+@itemize *
@item
-@strong{Included_Artifact_Patterns}: list
-
-If this attribute is defined it sets the patterns of compilation
-artifacts to synchronized from the slaves to the build master.
-This attribute replace the default hard-coded patterns.
+The name of the function.
@item
-@strong{Excluded_Patterns}: list
-
-Set of patterns to ignore when synchronizing sources from the build
-master to the slaves. A set of predefined patterns are supported
-(e.g. *.o, *.ali, *.exe, etc.), this attributes make it possible to
-add some more patterns.
+A number of bytes.
@item
-@strong{Root_Dir}: single
-
-Value is the root directory used by the slave machines.
+One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}.
@end itemize
-@node Package Stack Attributes,Package Synchronize Attributes,Package Remote Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager id64}@anchor{1be}@anchor{gnat_ugn/gnat_project_manager package-stack-attributes}@anchor{1bf}
-@subsubsection Package Stack Attributes
-
-
+The second field corresponds to the size of the known part of the function
+frame.
-@itemize *
+The qualifier @code{static} means that the function frame size
+is purely static.
+It usually means that all local variables have a static size.
+In this case, the second field is a reliable measure of the function stack
+utilization.
-@item
-@strong{Switches}: list
-
-Value is the list of switches to be used when invoking @cite{gnatstack}.
-@end itemize
-
-@node Package Synchronize Attributes,,Package Stack Attributes,Attributes
-@anchor{gnat_ugn/gnat_project_manager package-synchronize-attributes}@anchor{1c0}
-@subsubsection Package Synchronize Attributes
-
-
-
-@itemize *
-
-@item
-@strong{Default_Switches}: list, indexed, case-insensitive index
-
-Index is a language name. Value is a list of switches to be used when invoking
-@cite{gnatsync} for a source of the language, if there is no applicable
-attribute Switches.
-
-@item
-@strong{Switches}: list, optional index, indexed, case-insensitive index,
-others allowed
-
-Index is a source file name. Value is the list of switches to be used when
-invoking @cite{gnatsync} for the source.
-@end itemize
-
-@node Tools Supporting Project Files,GNAT Utility Programs,GNAT Project Manager,Top
-@anchor{gnat_ugn/tools_supporting_project_files doc}@anchor{1c1}@anchor{gnat_ugn/tools_supporting_project_files tools-supporting-project-files}@anchor{c}@anchor{gnat_ugn/tools_supporting_project_files id1}@anchor{1c2}
-@chapter Tools Supporting Project Files
-
-
-This section describes how project files can be used in conjunction with a number of
-GNAT tools.
-
-@menu
-* gnatmake and Project Files::
-* The GNAT Driver and Project Files::
-
-@end menu
-
-@node gnatmake and Project Files,The GNAT Driver and Project Files,,Tools Supporting Project Files
-@anchor{gnat_ugn/tools_supporting_project_files id2}@anchor{1c3}@anchor{gnat_ugn/tools_supporting_project_files gnatmake-and-project-files}@anchor{e1}
-@section gnatmake and Project Files
-
-
-This section covers several topics related to @emph{gnatmake} and
-project files: defining switches for @emph{gnatmake}
-and for the tools that it invokes; specifying configuration pragmas;
-the use of the @cite{Main} attribute; building and rebuilding library project
-files.
-
-@menu
-* Switches Related to Project Files::
-* Switches and Project Files::
-* Specifying Configuration Pragmas::
-* Project Files and Main Subprograms::
-* Library Project Files::
+The qualifier @code{dynamic} means that the function frame size is not static.
+It happens mainly when some local variables have a dynamic size. When this
+qualifier appears alone, the second field is not a reliable measure
+of the function stack analysis. When it is qualified with @code{bounded}, it
+means that the second field is a reliable maximum of the function stack
+utilization.
-@end menu
+A unit compiled with @code{-Wstack-usage} will issue a warning for each
+subprogram whose stack usage might be larger than the specified amount of
+bytes. The wording is in keeping with the qualifier documented above.
-@node Switches Related to Project Files,Switches and Project Files,,gnatmake and Project Files
-@anchor{gnat_ugn/tools_supporting_project_files switches-related-to-project-files}@anchor{e3}@anchor{gnat_ugn/tools_supporting_project_files id3}@anchor{1c4}
-@subsection Switches Related to Project Files
+@node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities
+@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
-The following switches are used by GNAT tools that support project files:
+It is possible to measure the maximum amount of stack used by a task, by
+adding a switch to @code{gnatbind}, as:
@quotation
-@geindex -P (any project-aware tool)
-@end quotation
-
-
-@table @asis
-
-@item @code{-P@emph{project}}
-
-Indicates the name of a project file. This project file will be parsed with
-the verbosity indicated by @emph{-vP*x*},
-if any, and using the external references indicated
-by @emph{-X} switches, if any.
-There may zero, one or more spaces between @emph{-P} and @cite{project}.
-
-There must be only one @emph{-P} switch on the command line.
-
-Since the Project Manager parses the project file only after all the switches
-on the command line are checked, the order of the switches
-@emph{-P},
-@emph{-vP*x*}
-or @emph{-X} is not significant.
-
-@geindex -X (any project-aware tool)
-
-@item @code{-X@emph{name}=@emph{value}}
-
-Indicates that external variable @cite{name} has the value @cite{value}.
-The Project Manager will use this value for occurrences of
-@cite{external(name)} when parsing the project file.
-
-If @cite{name} or @cite{value} includes a space, then @cite{name=value} should be
-put between quotes.
-
@example
--XOS=NT
--X"user=John Doe"
+$ gnatbind -u0 file
@end example
+@end quotation
-Several @emph{-X} switches can be used simultaneously.
-If several @emph{-X} switches specify the same
-@cite{name}, only the last one is used.
-
-An external variable specified with a @emph{-X} switch
-takes precedence over the value of the same name in the environment.
-
-@geindex -vP (any project-aware tool)
-
-@item @code{-vP@emph{x}}
-
-Indicates the verbosity of the parsing of GNAT project files.
-
-@emph{-vP0} means Default;
-@emph{-vP1} means Medium;
-@emph{-vP2} means High.
-
-The default is Default: no output for syntactically correct
-project files.
-If several @emph{-vP*x*} switches are present,
-only the last one is used.
-
-@geindex -aP (any project-aware tool)
-
-@item @code{-aP@emph{dir}}
-
-Add directory @cite{dir} at the beginning of the project search path, in order,
-after the current working directory.
-
-@geindex -eL (any project-aware tool)
-
-@item @code{-eL}
-
-Follow all symbolic links when processing project files.
-
-@geindex --subdirs= (gnatmake and gnatclean)
-
-@item @code{--subdirs=@emph{subdir}}
-
-This switch is recognized by @emph{gnatmake} and @emph{gnatclean}. It
-indicate that the real directories (except the source directories) are the
-subdirectories @cite{subdir} of the directories specified in the project files.
-This applies in particular to object directories, library directories and
-exec directories. If the subdirectories do not exist, they are created
-automatically.
-@end table
-
-@node Switches and Project Files,Specifying Configuration Pragmas,Switches Related to Project Files,gnatmake and Project Files
-@anchor{gnat_ugn/tools_supporting_project_files id4}@anchor{1c5}@anchor{gnat_ugn/tools_supporting_project_files switches-and-project-files}@anchor{1c6}
-@subsection Switches and Project Files
-
-
-For each of the packages @cite{Builder}, @cite{Compiler}, @cite{Binder}, and
-@cite{Linker}, you can specify a @cite{Default_Switches}
-attribute, a @cite{Switches} attribute, or both;
-as their names imply, these switch-related
-attributes affect the switches that are used for each of these GNAT
-components when
-@emph{gnatmake} is invoked. As will be explained below, these
-component-specific switches precede
-the switches provided on the @emph{gnatmake} command line.
+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.
-The @cite{Default_Switches} attribute is an attribute
-indexed by language name (case insensitive) whose value is a string list.
-For example:
+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
+@code{-u} option. For instance:
@quotation
@example
-package Compiler is
- for Default_Switches ("Ada")
- use ("-gnaty",
- "-v");
-end Compiler;
+$ gnatbind -u100 file
@end example
@end quotation
-The @cite{Switches} attribute is indexed on a file name (which may or may
-not be case sensitive, depending
-on the operating system) whose value is a string list. For example:
+will buffer the stack usage information of the first 100 tasks to terminate and
+output this info at program termination. Results are displayed in four
+columns:
@quotation
@example
-package Builder is
- for Switches ("main1.adb")
- use ("-O2");
- for Switches ("main2.adb")
- use ("-g");
-end Builder;
+Index | Task Name | Stack Size | Stack Usage
@end example
@end quotation
-For the @cite{Builder} package, the file names must designate source files
-for main subprograms. For the @cite{Binder} and @cite{Linker} packages, the
-file names must designate @code{ALI} or source files for main subprograms.
-In each case just the file name without an explicit extension is acceptable.
-
-For each tool used in a program build (@emph{gnatmake}, the compiler, the
-binder, and the linker), the corresponding package @@dfn@{contributes@} a set of
-switches for each file on which the tool is invoked, based on the
-switch-related attributes defined in the package.
-In particular, the switches
-that each of these packages contributes for a given file @cite{f} comprise:
+where:
@itemize *
@item
-the value of attribute @cite{Switches (`f})`,
-if it is specified in the package for the given file,
-
-@item
-otherwise, the value of @cite{Default_Switches ("Ada")},
-if it is specified in the package.
-@end itemize
-
-If neither of these attributes is defined in the package, then the package does
-not contribute any switches for the given file.
-
-When @emph{gnatmake} is invoked on a file, the switches comprise
-two sets, in the following order: those contributed for the file
-by the @cite{Builder} package;
-and the switches passed on the command line.
-
-When @emph{gnatmake} invokes a tool (compiler, binder, linker) on a file,
-the switches passed to the tool comprise three sets,
-in the following order:
-
-
-@itemize *
+@emph{Index} is a number associated with each task.
@item
-the applicable switches contributed for the file
-by the @cite{Builder} package in the project file supplied on the command line;
+@emph{Task Name} is the name of the task analyzed.
@item
-those contributed for the file by the package (in the relevant project file --
-see below) corresponding to the tool; and
+@emph{Stack Size} is the maximum size for the stack.
@item
-the applicable switches passed on the command line.
+@emph{Stack Usage} is the measure done by the stack analyzer.
+In order to prevent overflow, the stack
+is not entirely analyzed, and it's not possible to know exactly how
+much has actually been used.
@end itemize
-The term @emph{applicable switches} reflects the fact that
-@emph{gnatmake} switches may or may not be passed to individual
-tools, depending on the individual switch.
-
-@emph{gnatmake} may invoke the compiler on source files from different
-projects. The Project Manager will use the appropriate project file to
-determine the @cite{Compiler} package for each source file being compiled.
-Likewise for the @cite{Binder} and @cite{Linker} packages.
-
-As an example, consider the following package in a project file:
+By default the environment task stack, the stack that contains the main unit,
+is not processed. To enable processing of the environment task stack, the
+environment variable GNAT_STACK_LIMIT needs to be set to the maximum size of
+the environment task stack. This amount is given in kilobytes. For example:
@quotation
@example
-project Proj1 is
- package Compiler is
- for Default_Switches ("Ada")
- use ("-g");
- for Switches ("a.adb")
- use ("-O1");
- for Switches ("b.adb")
- use ("-O2",
- "-gnaty");
- end Compiler;
-end Proj1;
+$ set GNAT_STACK_LIMIT 1600
@end example
@end quotation
-If @emph{gnatmake} is invoked with this project file, and it needs to
-compile, say, the files @code{a.adb}, @code{b.adb}, and @code{c.adb}, then
-@code{a.adb} will be compiled with the switch @emph{-O1},
-@code{b.adb} with switches @emph{-O2} and @emph{-gnaty},
-and @code{c.adb} with @emph{-g}.
+would specify to the analyzer that the environment task stack has a limit
+of 1.6 megabytes. Any stack usage beyond this will be ignored by the analysis.
-The following example illustrates the ordering of the switches
-contributed by different packages:
-
-@quotation
-
-@example
-project Proj2 is
- package Builder is
- for Switches ("main.adb")
- use ("-g",
- "-O1",
- "-f");
- end Builder;
+The package @code{GNAT.Task_Stack_Usage} provides facilities to get
+stack-usage reports at run time. See its body for the details.
- package Compiler is
- for Switches ("main.adb")
- use ("-O2");
- end Compiler;
-end Proj2;
-@end example
-@end quotation
+@node Memory Management Issues,,Stack Related Facilities,GNAT and Program Execution
+@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
-If you issue the command:
-@quotation
+This section describes some useful memory pools provided in the GNAT library
+and in particular the GNAT Debug Pool facility, which can be used to detect
+incorrect uses of access values (including 'dangling references').
-@example
-$ gnatmake -Pproj2 -O0 main
-@end example
-@end quotation
-then the compiler will be invoked on @code{main.adb} with the following
-sequence of switches
+@menu
+* Some Useful Memory Pools::
+* The GNAT Debug Pool Facility::
-@quotation
+@end menu
-@example
--g -O1 -O2 -O0
-@end example
-@end quotation
+@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues
+@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
-with the last @emph{-O}
-switch having precedence over the earlier ones;
-several other switches
-(such as @emph{-c}) are added implicitly.
-The switches @emph{-g}
-and @emph{-O1} are contributed by package
-@cite{Builder}, @emph{-O2} is contributed
-by the package @cite{Compiler}
-and @emph{-O0} comes from the command line.
+@geindex Memory Pool
-The @emph{-g} switch will also be passed in the invocation of
-@emph{Gnatlink.}
+@geindex storage
+@geindex pool
-A final example illustrates switch contributions from packages in different
-project files:
+The @code{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
+storage pool. Allocations use the standard system call @code{malloc} while
+deallocations use the standard system call @code{free}. No reclamation is
+performed when the pool goes out of scope. For performance reasons, the
+standard default Ada allocators/deallocators do not use any explicit storage
+pools but if they did, they could use this storage pool without any change in
+behavior. That is why this storage pool is used when the user
+manages to make the default implicit allocator explicit as in this example:
@quotation
@example
-project Proj3 is
- for Source_Files use ("pack.ads", "pack.adb");
- package Compiler is
- for Default_Switches ("Ada")
- use ("-gnata");
- end Compiler;
-end Proj3;
-
-with "Proj3";
-project Proj4 is
- for Source_Files use ("foo_main.adb", "bar_main.adb");
- package Builder is
- for Switches ("foo_main.adb")
- use ("-s",
- "-g");
- end Builder;
-end Proj4;
-@end example
+type T1 is access Something;
+ -- no Storage pool is defined for T2
-@example
--- Ada source file:
-with Pack;
-procedure Foo_Main is
- ...
-end Foo_Main;
+type T2 is access Something_Else;
+for T2'Storage_Pool use T1'Storage_Pool;
+-- the above is equivalent to
+for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
@end example
@end quotation
-If the command is
+The @code{System.Pool_Local} package offers the @code{Unbounded_Reclaim_Pool} storage
+pool. The allocation strategy is similar to @code{Pool_Local}
+except that the all
+storage allocated with this pool is reclaimed when the pool object goes out of
+scope. This pool provides a explicit mechanism similar to the implicit one
+provided by several Ada 83 compilers for allocations performed through a local
+access type and whose purpose was to reclaim memory when exiting the
+scope of a given local access. As an example, the following program does not
+leak memory even though it does not perform explicit deallocation:
@quotation
@example
-$ gnatmake -PProj4 foo_main.adb -cargs -gnato
+with System.Pool_Local;
+procedure Pooloc1 is
+ procedure Internal is
+ type A is access Integer;
+ X : System.Pool_Local.Unbounded_Reclaim_Pool;
+ for A'Storage_Pool use X;
+ v : A;
+ begin
+ for I in 1 .. 50 loop
+ v := new Integer;
+ end loop;
+ end Internal;
+begin
+ for I in 1 .. 100 loop
+ Internal;
+ end loop;
+end Pooloc1;
@end example
@end quotation
-then the switches passed to the compiler for @code{foo_main.adb} are
-@emph{-g} (contributed by the package @cite{Proj4.Builder}) and
-@emph{-gnato} (passed on the command line).
-When the imported package @cite{Pack} is compiled, the switches used
-are @emph{-g} from @cite{Proj4.Builder},
-@emph{-gnata} (contributed from package @cite{Proj3.Compiler},
-and @emph{-gnato} from the command line.
-
-When using @emph{gnatmake} with project files, some switches or
-arguments may be expressed as relative paths. As the working directory where
-compilation occurs may change, these relative paths are converted to absolute
-paths. For the switches found in a project file, the relative paths
-are relative to the project file directory, for the switches on the command
-line, they are relative to the directory where @emph{gnatmake} is invoked.
-The switches for which this occurs are:
--I,
--A,
--L,
--aO,
--aL,
--aI, as well as all arguments that are not switches (arguments to
-switch
--o, object files specified in package @cite{Linker} or after
--largs on the command line). The exception to this rule is the switch
---RTS= for which a relative path argument is never converted.
-
-@node Specifying Configuration Pragmas,Project Files and Main Subprograms,Switches and Project Files,gnatmake and Project Files
-@anchor{gnat_ugn/tools_supporting_project_files id5}@anchor{1c7}@anchor{gnat_ugn/tools_supporting_project_files specifying-configuration-pragmas}@anchor{7d}
-@subsection Specifying Configuration Pragmas
-
-
-When using @emph{gnatmake} with project files, if there exists a file
-@code{gnat.adc} that contains configuration pragmas, this file will be
-ignored.
-
-Configuration pragmas can be defined by means of the following attributes in
-project files: @cite{Global_Configuration_Pragmas} in package @cite{Builder}
-and @cite{Local_Configuration_Pragmas} in package @cite{Compiler}.
-
-Both these attributes are single string attributes. Their values is the path
-name of a file containing configuration pragmas. If a path name is relative,
-then it is relative to the project directory of the project file where the
-attribute is defined.
-
-When compiling a source, the configuration pragmas used are, in order,
-those listed in the file designated by attribute
-@cite{Global_Configuration_Pragmas} in package @cite{Builder} of the main
-project file, if it is specified, and those listed in the file designated by
-attribute @cite{Local_Configuration_Pragmas} in package @cite{Compiler} of
-the project file of the source, if it exists.
-
-@node Project Files and Main Subprograms,Library Project Files,Specifying Configuration Pragmas,gnatmake and Project Files
-@anchor{gnat_ugn/tools_supporting_project_files id6}@anchor{1c8}@anchor{gnat_ugn/tools_supporting_project_files project-files-and-main-subprograms}@anchor{e2}
-@subsection Project Files and Main Subprograms
-
-
-When using a project file, you can invoke @emph{gnatmake}
-with one or several main subprograms, by specifying their source files on the
-command line.
+The @code{System.Pool_Size} package implements the @code{Stack_Bounded_Pool} used when
+@code{Storage_Size} is specified for an access type.
+The whole storage for the pool is
+allocated at once, usually on the stack at the point where the access type is
+elaborated. It is automatically reclaimed when exiting the scope where the
+access type is defined. This package is not intended to be used directly by the
+user and it is implicitly used for each such declaration:
@quotation
@example
-$ gnatmake -Pprj main1.adb main2.adb main3.adb
+type T1 is access Something;
+for T1'Storage_Size use 10_000;
@end example
@end quotation
-Each of these needs to be a source file of the same project, except
-when the switch @cite{-u} is used.
+@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues
+@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
-When @cite{-u} is not used, all the mains need to be sources of the
-same project, one of the project in the tree rooted at the project specified
-on the command line. The package @cite{Builder} of this common project, the
-"main project" is the one that is considered by @emph{gnatmake}.
-When @cite{-u} is used, the specified source files may be in projects
-imported directly or indirectly by the project specified on the command line.
-Note that if such a source file is not part of the project specified on the
-command line, the switches found in package @cite{Builder} of the
-project specified on the command line, if any, that are transmitted
-to the compiler will still be used, not those found in the project file of
-the source file.
+@geindex Debug Pool
-When using a project file, you can also invoke @emph{gnatmake} without
-explicitly specifying any main, and the effect depends on whether you have
-defined the @cite{Main} attribute. This attribute has a string list value,
-where each element in the list is the name of a source file (the file
-extension is optional) that contains a unit that can be a main subprogram.
+@geindex storage
+@geindex pool
+@geindex memory corruption
-If the @cite{Main} attribute is defined in a project file as a non-empty
-string list and the switch @emph{-u} is not used on the command
-line, then invoking @emph{gnatmake} with this project file but without any
-main on the command line is equivalent to invoking @emph{gnatmake} with all
-the file names in the @cite{Main} attribute on the command line.
+The use of unchecked deallocation and unchecked conversion can easily
+lead to incorrect memory references. The problems generated by such
+references are usually difficult to tackle because the symptoms can be
+very remote from the origin of the problem. In such cases, it is
+very helpful to detect the problem as early as possible. This is the
+purpose of the Storage Pool provided by @code{GNAT.Debug_Pools}.
-Example:
+In order to use the GNAT specific debugging pool, the user must
+associate a debug pool object with each of the access types that may be
+related to suspected memory problems. See Ada Reference Manual 13.11.
@quotation
@example
-project Prj is
- for Main use ("main1.adb", "main2.adb", "main3.adb");
-end Prj;
+type Ptr is access Some_Type;
+Pool : GNAT.Debug_Pools.Debug_Pool;
+for Ptr'Storage_Pool use Pool;
@end example
@end quotation
-With this project file, @cite{"gnatmake -Pprj"}
-is equivalent to
-@cite{"gnatmake -Pprj main1.adb main2.adb main3.adb"}.
-
-When the project attribute @cite{Main} is not specified, or is specified
-as an empty string list, or when the switch @emph{-u} is used on the command
-line, then invoking @emph{gnatmake} with no main on the command line will
-result in all immediate sources of the project file being checked, and
-potentially recompiled. Depending on the presence of the switch @emph{-u},
-sources from other project files on which the immediate sources of the main
-project file depend are also checked and potentially recompiled. In other
-words, the @emph{-u} switch is applied to all of the immediate sources of the
-main project file.
-
-When no main is specified on the command line and attribute @cite{Main} exists
-and includes several mains, or when several mains are specified on the
-command line, the default switches in package @cite{Builder} will
-be used for all mains, even if there are specific switches
-specified for one or several mains.
-
-But the switches from package @cite{Binder} or @cite{Linker} will be
-the specific switches for each main, if they are specified.
-
-@node Library Project Files,,Project Files and Main Subprograms,gnatmake and Project Files
-@anchor{gnat_ugn/tools_supporting_project_files id7}@anchor{1c9}@anchor{gnat_ugn/tools_supporting_project_files library-project-files}@anchor{1ca}
-@subsection Library Project Files
-
-
-When @emph{gnatmake} is invoked with a main project file that is a library
-project file, it is not allowed to specify one or more mains on the command
-line.
+@code{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
+pool: the @code{Checked_Pool}. Such pools, like standard Ada storage pools,
+allow the user to redefine allocation and deallocation strategies. They
+also provide a checkpoint for each dereference, through the use of
+the primitive operation @code{Dereference} which is implicitly called at
+each dereference of an access value.
-When a library project file is specified, switches @cite{-b} and
-@cite{-l} have special meanings.
+Once an access type has been associated with a debug pool, operations on
+values of the type may raise four distinct exceptions,
+which correspond to four potential kinds of memory corruption:
@itemize *
@item
-@cite{-b} is only allowed for stand-alone libraries. It indicates
-to @emph{gnatmake} that @emph{gnatbind} should be invoked for the
-library.
+@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
@item
-@cite{-l} may be used for all library projects. It indicates
-to @emph{gnatmake} that the binder generated file should be compiled
-(in the case of a stand-alone library) and that the library should be built.
-@end itemize
-
-@node The GNAT Driver and Project Files,,gnatmake and Project Files,Tools Supporting Project Files
-@anchor{gnat_ugn/tools_supporting_project_files id8}@anchor{1cb}@anchor{gnat_ugn/tools_supporting_project_files the-gnat-driver-and-project-files}@anchor{11f}
-@section The GNAT Driver and Project Files
-
-
-A number of GNAT tools beyond @emph{gnatmake}
-can benefit from project files:
-
-
-
-@itemize *
+@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
@item
-@emph{gnatbind}
+@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
@item
-@emph{gnatclean}
+@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage}
+@end itemize
-@item
-@emph{gnatfind}
+For types associated with a Debug_Pool, dynamic allocation is performed using
+the standard GNAT allocation routine. References to all allocated chunks of
+memory are kept in an internal dictionary. Several deallocation strategies are
+provided, whereupon the user can choose to release the memory to the system,
+keep it allocated for further invalid access checks, or fill it with an easily
+recognizable pattern for debug sessions. The memory pattern is the old IBM
+hexadecimal convention: @code{16#DEADBEEF#}.
-@item
-@emph{gnatlink}
+See the documentation in the file g-debpoo.ads for more information on the
+various strategies.
-@item
-@emph{gnatls}
+Upon each dereference, a check is made that the access value denotes a
+properly allocated memory location. Here is a complete example of use of
+@code{Debug_Pools}, that includes typical instances of memory corruption:
-@item
-@emph{gnatxref}
-@end itemize
+@quotation
-However, none of these tools can be invoked
-directly with a project file switch (@emph{-P}).
-They must be invoked through the @emph{gnat} driver.
+@example
+with Gnat.Io; use Gnat.Io;
+with Unchecked_Deallocation;
+with Unchecked_Conversion;
+with GNAT.Debug_Pools;
+with System.Storage_Elements;
+with Ada.Exceptions; use Ada.Exceptions;
+procedure Debug_Pool_Test is
-The @emph{gnat} driver is a wrapper that accepts a number of commands and
-calls the corresponding tool. It was designed initially for VMS platforms (to
-convert VMS qualifiers to Unix-style switches), but it is now available on all
-GNAT platforms.
+ type T is access Integer;
+ type U is access all T;
-On non-VMS platforms, the @emph{gnat} driver accepts the following commands
-(case insensitive):
+ P : GNAT.Debug_Pools.Debug_Pool;
+ for T'Storage_Pool use P;
+ procedure Free is new Unchecked_Deallocation (Integer, T);
+ function UC is new Unchecked_Conversion (U, T);
+ A, B : aliased T;
+ procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
-@itemize *
+begin
+ Info (P);
+ A := new Integer;
+ B := new Integer;
+ B := A;
+ Info (P);
+ Free (A);
+ begin
+ Put_Line (Integer'Image(B.all));
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ begin
+ Free (B);
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ B := UC(A'Access);
+ begin
+ Put_Line (Integer'Image(B.all));
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ begin
+ Free (B);
+ exception
+ when E : others => Put_Line ("raised: " & Exception_Name (E));
+ end;
+ Info (P);
+end Debug_Pool_Test;
+@end example
+@end quotation
-@item
-BIND to invoke @emph{gnatbind}
+The debug pool mechanism provides the following precise diagnostics on the
+execution of this erroneous program:
-@item
-CHOP to invoke @emph{gnatchop}
+@quotation
-@item
-CLEAN to invoke @emph{gnatclean}
+@example
+Debug Pool info:
+ Total allocated bytes : 0
+ Total deallocated bytes : 0
+ Current Water Mark: 0
+ High Water Mark: 0
-@item
-COMP or COMPILE to invoke the compiler
+Debug Pool info:
+ Total allocated bytes : 8
+ Total deallocated bytes : 0
+ Current Water Mark: 8
+ High Water Mark: 8
-@item
-FIND to invoke @emph{gnatfind}
+raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE
+raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE
+Debug Pool info:
+ Total allocated bytes : 8
+ Total deallocated bytes : 4
+ Current Water Mark: 4
+ High Water Mark: 8
+@end example
+@end quotation
-@item
-KR or KRUNCH to invoke @emph{gnatkr}
-@item
-LINK to invoke @emph{gnatlink}
+@c -- Non-breaking space in running text
+@c -- E.g. Ada |nbsp| 95
-@item
-LS or LIST to invoke @emph{gnatls}
+@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{1b1}@anchor{gnat_ugn/platform_specific_information id1}@anchor{1b2}
+@chapter Platform-Specific Information
-@item
-MAKE to invoke @emph{gnatmake}
-@item
-NAME to invoke @emph{gnatname}
+This appendix contains information relating to the implementation
+of run-time libraries on various platforms and also covers
+topics related to the GNAT implementation on Windows and Mac OS.
-@item
-PREP or PREPROCESS to invoke @emph{gnatprep}
+@menu
+* Run-Time Libraries::
+* Specifying a Run-Time Library::
+* GNU/Linux Topics::
+* Microsoft Windows Topics::
+* Mac OS Topics::
-@item
-XREF to invoke @emph{gnatxref}
-@end itemize
+@end menu
-Note that the command
-@emph{gnatmake -c -f -u} is used to invoke the compiler.
+@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information id2}@anchor{1b3}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{1b4}
+@section Run-Time Libraries
-On non-VMS platforms, between @emph{gnat} and the command, two
-special switches may be used:
+@geindex Tasking and threads libraries
-@itemize *
+@geindex Threads libraries and tasking
-@item
-@emph{-v} to display the invocation of the tool.
+@geindex Run-time libraries (platform-specific information)
-@item
-@emph{-dn} to prevent the @emph{gnat} driver from removing
-the temporary files it has created. These temporary files are
-configuration files and temporary file list files.
-@end itemize
+The GNAT run-time implementation may vary with respect to both the
+underlying threads library and the exception-handling scheme.
+For threads support, the default run-time will bind to the thread
+package of the underlying operating system.
-The command may be followed by switches and arguments for the invoked
-tool.
+For exception handling, either or both of two models are supplied:
@quotation
-@example
-$ gnat bind -C main.ali
-$ gnat ls -a main
-$ gnat chop foo.txt
-@end example
-@end quotation
-
-Switches may also be put in text files, one switch per line, and the text
-files may be specified with their path name preceded by '@@'.
-
-@quotation
+@geindex Zero-Cost Exceptions
-@example
-$ gnat bind @@args.txt main.ali
-@end example
+@geindex ZCX (Zero-Cost Exceptions)
@end quotation
-In addition, for the following commands the project file related switches
-(@emph{-P}, @emph{-X} and @emph{-vPx}) may be used in addition to
-the switches of the invoking tool:
-
-
@itemize *
@item
-BIND
-
-@item
-COMP or COMPILE
-
-@item
-FIND
+@strong{Zero-Cost Exceptions} ("ZCX"),
+which uses binder-generated tables that
+are interrogated at run time to locate a handler.
-@item
-LS or LIST
+@geindex setjmp/longjmp Exception Model
-@item
-LINK
+@geindex SJLJ (setjmp/longjmp Exception Model)
@item
-XREF
+@strong{setjmp / longjmp} ('SJLJ'),
+which uses dynamically-set data to establish
+the set of handlers
@end itemize
+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.
+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}.
-For each of the following commands, there is optionally a corresponding
-package in the main project.
+This section summarizes which combinations of threads and exception support
+are supplied on various GNAT platforms.
+@menu
+* Summary of Run-Time Configurations::
+@end menu
-@itemize *
+@node Summary of Run-Time Configurations,,,Run-Time Libraries
+@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
-@item
-package @cite{Binder} for command BIND (invoking @cite{gnatbind})
-@item
-package @cite{Compiler} for command COMP or COMPILE (invoking the compiler)
-@item
-package @cite{Cross_Reference} for command XREF (invoking @cite{gnatxref})
+@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
+@headitem
-@item
-package @cite{Finder} for command FIND (invoking @cite{gnatfind})
+Platform
-@item
-package @cite{Gnatls} for command LS or LIST (invoking @cite{gnatls})
+@tab
-@item
-package @cite{Linker} for command LINK (invoking @cite{gnatlink})
-@end itemize
+Run-Time
-Package @cite{Gnatls} has a unique attribute @cite{Switches},
-a simple variable with a string list value. It contains switches
-for the invocation of @cite{gnatls}.
+@tab
-@quotation
+Tasking
-@example
-project Proj1 is
- package gnatls is
- for Switches
- use ("-a",
- "-v");
- end gnatls;
-end Proj1;
-@end example
-@end quotation
+@tab
-All other packages have two attribute @cite{Switches} and
-@cite{Default_Switches}.
+Exceptions
-@cite{Switches} is an indexed attribute, indexed by the
-source file name, that has a string list value: the switches to be
-used when the tool corresponding to the package is invoked for the specific
-source file.
+@item
-@cite{Default_Switches} is an attribute,
-indexed by the programming language that has a string list value.
-@cite{Default_Switches ("Ada")} contains the
-switches for the invocation of the tool corresponding
-to the package, except if a specific @cite{Switches} attribute
-is specified for the source file.
+GNU/Linux
-@quotation
+@tab
-@example
-project Proj is
+rts-native
+(default)
- for Source_Dirs use ("");
+@tab
- package gnatls is
- for Switches use
- ("-a",
- "-v");
- end gnatls;
+pthread library
- package Compiler is
- for Default_Switches ("Ada")
- use ("-gnatv",
- "-gnatwa");
- end Binder;
-
- package Binder is
- for Default_Switches ("Ada")
- use ("-C",
- "-e");
- end Binder;
-
- package Linker is
- for Default_Switches ("Ada")
- use ("-C");
- for Switches ("main.adb")
- use ("-C",
- "-v",
- "-v");
- end Linker;
-
- package Finder is
- for Default_Switches ("Ada")
- use ("-a",
- "-f");
- end Finder;
-
- package Cross_Reference is
- for Default_Switches ("Ada")
- use ("-a",
- "-f",
- "-d",
- "-u");
- end Cross_Reference;
-end Proj;
-@end example
-@end quotation
+@tab
-With the above project file, commands such as
+ZCX
-@quotation
+@item
-@example
-$ gnat comp -Pproj main
-$ gnat ls -Pproj main
-$ gnat xref -Pproj main
-$ gnat bind -Pproj main.ali
-$ gnat link -Pproj main.ali
-@end example
-@end quotation
+rts-sjlj
-will set up the environment properly and invoke the tool with the switches
-found in the package corresponding to the tool:
-@cite{Default_Switches ("Ada")} for all tools,
-except @cite{Switches ("main.adb")}
-for @cite{gnatlink}.
+@tab
+pthread library
-@node GNAT Utility Programs,GNAT and Program Execution,Tools Supporting Project Files,Top
-@anchor{gnat_ugn/gnat_utility_programs doc}@anchor{1cc}@anchor{gnat_ugn/gnat_utility_programs gnat-utility-programs}@anchor{d}@anchor{gnat_ugn/gnat_utility_programs id1}@anchor{1cd}
-@chapter GNAT Utility Programs
+@tab
+SJLJ
-This chapter describes a number of utility programs:
+@item
+Windows
+@tab
-@itemize *
+rts-native
+(default)
-@item
-@ref{22,,The File Cleanup Utility gnatclean}
+@tab
-@item
-@ref{23,,The GNAT Library Browser gnatls}
+native Win32 threads
-@item
-@ref{24,,The Cross-Referencing Tools gnatxref and gnatfind}
+@tab
-@item
-@ref{25,,The Ada to HTML Converter gnathtml}
-@end itemize
+ZCX
-Other GNAT utilities are described elsewhere in this manual:
+@item
+rts-sjlj
-@itemize *
+@tab
-@item
-@ref{5b,,Handling Arbitrary File Naming Conventions with gnatname}
+native Win32 threads
-@item
-@ref{65,,File Name Krunching with gnatkr}
+@tab
-@item
-@ref{38,,Renaming Files with gnatchop}
+SJLJ
-@item
-@ref{19,,Preprocessing with gnatprep}
-@end itemize
+@item
-@menu
-* The File Cleanup Utility gnatclean::
-* The GNAT Library Browser gnatls::
-* The Cross-Referencing Tools gnatxref and gnatfind::
-* The Ada to HTML Converter gnathtml::
+Mac OS
-@end menu
+@tab
-@node The File Cleanup Utility gnatclean,The GNAT Library Browser gnatls,,GNAT Utility Programs
-@anchor{gnat_ugn/gnat_utility_programs id2}@anchor{1ce}@anchor{gnat_ugn/gnat_utility_programs the-file-cleanup-utility-gnatclean}@anchor{22}
-@section The File Cleanup Utility @emph{gnatclean}
+rts-native
+@tab
-@geindex File cleanup tool
+pthread library
-@geindex gnatclean
+@tab
-@cite{gnatclean} is a tool that allows the deletion of files produced by the
-compiler, binder and linker, including ALI files, object files, tree files,
-expanded source files, library files, interface copy source files, binder
-generated files and executable files.
+ZCX
-@menu
-* Running gnatclean::
-* Switches for gnatclean::
+@end multitable
-@end menu
-@node Running gnatclean,Switches for gnatclean,,The File Cleanup Utility gnatclean
-@anchor{gnat_ugn/gnat_utility_programs running-gnatclean}@anchor{1cf}@anchor{gnat_ugn/gnat_utility_programs id3}@anchor{1d0}
-@subsection Running @cite{gnatclean}
+@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{1b7}@anchor{gnat_ugn/platform_specific_information id4}@anchor{1b8}
+@section Specifying a Run-Time Library
-The @cite{gnatclean} command has the form:
+The @code{adainclude} subdirectory containing the sources of the GNAT
+run-time library, and the @code{adalib} subdirectory containing the
+@code{ALI} files and the static and/or shared GNAT library, are located
+in the gcc target-dependent area:
@quotation
@example
-$ gnatclean switches `names`
+target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/
@end example
@end quotation
-where @cite{names} is a list of source file names. Suffixes @code{.ads} and
-@code{adb} may be omitted. If a project file is specified using switch
-@code{-P}, then @cite{names} may be completely omitted.
-
-In normal mode, @cite{gnatclean} delete the files produced by the compiler and,
-if switch @cite{-c} is not specified, by the binder and
-the linker. In informative-only mode, specified by switch
-@cite{-n}, the list of files that would have been deleted in
-normal mode is listed, but no file is actually deleted.
+As indicated above, on some platforms several run-time libraries are supplied.
+These libraries are installed in the target dependent area and
+contain a complete source and binary subdirectory. The detailed description
+below explains the differences between the different libraries in terms of
+their thread support.
-@node Switches for gnatclean,,Running gnatclean,The File Cleanup Utility gnatclean
-@anchor{gnat_ugn/gnat_utility_programs id4}@anchor{1d1}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatclean}@anchor{1d2}
-@subsection Switches for @cite{gnatclean}
+The default run-time library (when GNAT is installed) is @emph{rts-native}.
+This default run-time is selected by the means of soft links.
+For example on x86-linux:
+@c --
+@c -- $(target-dir)
+@c -- |
+@c -- +--- adainclude----------+
+@c -- | |
+@c -- +--- adalib-----------+ |
+@c -- | | |
+@c -- +--- rts-native | |
+@c -- | | | |
+@c -- | +--- adainclude <---+
+@c -- | | |
+@c -- | +--- adalib <----+
+@c -- |
+@c -- +--- rts-sjlj
+@c -- |
+@c -- +--- adainclude
+@c -- |
+@c -- +--- adalib
+
+
+@example
+ $(target-dir)
+ __/ / \ \___
+ _______/ / \ \_________________
+ / / \ \
+ / / \ \
+ADAINCLUDE ADALIB rts-native rts-sjlj
+ : : / \ / \
+ : : / \ / \
+ : : / \ / \
+ : : / \ / \
+ +-------------> adainclude adalib adainclude adalib
+ : ^
+ : :
+ +---------------------+
+
+ Run-Time Library Directory Structure
+ (Upper-case names and dotted/dashed arrows represent soft links)
+@end example
-@cite{gnatclean} recognizes the following switches:
+If the @emph{rts-sjlj} library is to be selected on a permanent basis,
+these soft links can be modified with the following commands:
-@geindex --version (gnatclean)
+@quotation
+@example
+$ cd $target
+$ rm -f adainclude adalib
+$ ln -s rts-sjlj/adainclude adainclude
+$ ln -s rts-sjlj/adalib adalib
+@end example
+@end quotation
-@table @asis
+Alternatively, you can specify @code{rts-sjlj/adainclude} in the file
+@code{$target/ada_source_path} and @code{rts-sjlj/adalib} in
+@code{$target/ada_object_path}.
-@item @code{--version}
+@geindex --RTS option
-Display Copyright and version, then exit disregarding all other options.
-@end table
+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{1b9}
+@geindex SCHED_FIFO scheduling policy
-@geindex --help (gnatclean)
+@geindex SCHED_RR scheduling policy
+@geindex SCHED_OTHER scheduling policy
-@table @asis
+@menu
+* Choosing the Scheduling Policy::
-@item @code{--help}
+@end menu
-If @emph{--version} was not used, display usage, then exit disregarding
-all other options.
+@node Choosing the Scheduling Policy,,,Specifying a Run-Time Library
+@anchor{gnat_ugn/platform_specific_information id5}@anchor{1ba}
+@subsection Choosing the Scheduling Policy
-@item @code{--subdirs=@emph{subdir}}
-Actual object directory of each project file is the subdirectory subdir of the
-object directory specified or defaulted in the project file.
+When using a POSIX threads implementation, you have a choice of several
+scheduling policies: @code{SCHED_FIFO}, @code{SCHED_RR} and @code{SCHED_OTHER}.
-@item @code{--unchecked-shared-lib-imports}
+Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO}
+or @code{SCHED_RR} requires special (e.g., root) privileges.
-By default, shared library projects are not allowed to import static library
-projects. When this switch is used on the command line, this restriction is
-relaxed.
-@end table
+@geindex pragma Time_Slice
-@geindex -c (gnatclean)
+@geindex -T0 option
+@geindex pragma Task_Dispatching_Policy
-@table @asis
+By default, GNAT uses the @code{SCHED_OTHER} policy. To specify
+@code{SCHED_FIFO},
+you can use one of the following:
-@item @code{-c}
-Only attempt to delete the files produced by the compiler, not those produced
-by the binder or the linker. The files that are not to be deleted are library
-files, interface copy files, binder generated files and executable files.
-@end table
+@itemize *
-@geindex -D (gnatclean)
+@item
+@code{pragma Time_Slice (0.0)}
+@item
+the corresponding binder option @code{-T0}
-@table @asis
+@item
+@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
+@end itemize
-@item @code{-D @emph{dir}}
+To specify @code{SCHED_RR},
+you should use @code{pragma Time_Slice} with a
+value greater than 0.0, or else use the corresponding @code{-T}
+binder option.
-Indicate that ALI and object files should normally be found in directory @cite{dir}.
-@end table
+To make sure a program is running as root, you can put something like
+this in a library package body in your application:
-@geindex -F (gnatclean)
+@quotation
+@example
+function geteuid return Integer;
+pragma Import (C, geteuid, "geteuid");
+Ignore : constant Boolean :=
+ (if geteuid = 0 then True else raise Program_Error with "must be root");
+@end example
+@end quotation
-@table @asis
+It gets the effective user id, and if it's not 0 (i.e. root), it raises
+Program_Error.
-@item @code{-F}
+@geindex Linux
-When using project files, if some errors or warnings are detected during
-parsing and verbose mode is not in effect (no use of switch
--v), then error lines start with the full path name of the project
-file, rather than its simple file name.
-@end table
+@geindex GNU/Linux
-@geindex -h (gnatclean)
+@node GNU/Linux Topics,Microsoft Windows Topics,Specifying a Run-Time Library,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information id6}@anchor{1bb}@anchor{gnat_ugn/platform_specific_information gnu-linux-topics}@anchor{1bc}
+@section GNU/Linux Topics
-@table @asis
+This section describes topics that are specific to GNU/Linux platforms.
-@item @code{-h}
+@menu
+* Required Packages on GNU/Linux::
-Output a message explaining the usage of @cite{gnatclean}.
-@end table
+@end menu
-@geindex -n (gnatclean)
+@node Required Packages on GNU/Linux,,,GNU/Linux Topics
+@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
-@table @asis
+GNAT requires the C library developer's package to be installed.
+The name of of that package depends on your GNU/Linux distribution:
-@item @code{-n}
-Informative-only mode. Do not delete any files. Output the list of the files
-that would have been deleted if this switch was not specified.
-@end table
+@itemize *
-@geindex -P (gnatclean)
+@item
+RedHat, SUSE: @code{glibc-devel};
+@item
+Debian, Ubuntu: @code{libc6-dev} (normally installed by default).
+@end itemize
-@table @asis
+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 following packages:
-@item @code{-P@emph{project}}
-Use project file @cite{project}. Only one such switch can be used.
-When cleaning a project file, the files produced by the compilation of the
-immediate sources or inherited sources of the project files are to be
-deleted. This is not depending on the presence or not of executable names
-on the command line.
-@end table
+@itemize *
-@geindex -q (gnatclean)
+@item
+RedHat, SUSE: @code{glibc.i686}, @code{glibc-devel.i686}, @code{ncurses-libs.i686}
+@item
+Debian, Ubuntu: @code{libc6:i386}, @code{libc6-dev:i386}, @code{lib32ncursesw5}
+@end itemize
-@table @asis
+Other GNU/Linux distributions might be choosing a different name
+for those packages.
-@item @code{-q}
+@geindex Windows
-Quiet output. If there are no errors, do not output anything, except in
-verbose mode (switch -v) or in informative-only mode
-(switch -n).
-@end table
+@node Microsoft Windows Topics,Mac OS Topics,GNU/Linux Topics,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{1bf}@anchor{gnat_ugn/platform_specific_information id8}@anchor{1c0}
+@section Microsoft Windows Topics
-@geindex -r (gnatclean)
+This section describes topics that are specific to the Microsoft Windows
+platforms.
-@table @asis
-@item @code{-r}
+@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::
-When a project file is specified (using switch -P),
-clean all imported and extended project files, recursively. If this switch
-is not specified, only the files related to the main project file are to be
-deleted. This switch has no effect if no project file is specified.
-@end table
+@end menu
-@geindex -v (gnatclean)
+@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{1c1}@anchor{gnat_ugn/platform_specific_information id9}@anchor{1c2}
+@subsection Using GNAT on Windows
-@table @asis
+One of the strengths of the GNAT technology is that its tool set
+(@code{gcc}, @code{gnatbind}, @code{gnatlink}, @code{gnatmake}, the
+@code{gdb} debugger, etc.) is used in the same way regardless of the
+platform.
-@item @code{-v}
+On Windows this tool set is complemented by a number of Microsoft-specific
+tools that have been provided to facilitate interoperability with Windows
+when this is required. With these tools:
-Verbose mode.
-@end table
-@geindex -vP (gnatclean)
+@itemize *
+@item
+You can build applications using the @code{CONSOLE} or @code{WINDOWS}
+subsystems.
-@table @asis
+@item
+You can use any Dynamically Linked Library (DLL) in your Ada code (both
+relocatable and non-relocatable DLLs are supported).
-@item @code{-vP@emph{x}}
+@item
+You can build Ada DLLs for use in other applications. These applications
+can be written in a language other than Ada (e.g., C, C++, etc). Again both
+relocatable and non-relocatable Ada DLLs are supported.
-Indicates the verbosity of the parsing of GNAT project files.
-@ref{e3,,Switches Related to Project Files}.
-@end table
+@item
+You can include Windows resources in your Ada application.
-@geindex -X (gnatclean)
+@item
+You can use or create COM/DCOM objects.
+@end itemize
+Immediately below are listed all known general GNAT-for-Windows restrictions.
+Other restrictions about specific features like Windows Resources and DLLs
+are listed in separate sections below.
-@table @asis
-@item @code{-X@emph{name}=@emph{value}}
+@itemize *
-Indicates that external variable @cite{name} has the value @cite{value}.
-The Project Manager will use this value for occurrences of
-@cite{external(name)} when parsing the project file.
-@ref{e3,,Switches Related to Project Files}.
-@end table
+@item
+It is not possible to use @code{GetLastError} and @code{SetLastError}
+when tasking, protected records, or exceptions are used. In these
+cases, in order to implement Ada semantics, the GNAT run-time system
+calls certain Win32 routines that set the last error variable to 0 upon
+success. It should be possible to use @code{GetLastError} and
+@code{SetLastError} when tasking, protected record, and exception
+features are not used, but it is not guaranteed to work.
-@geindex -aO (gnatclean)
+@item
+It is not possible to link against Microsoft C++ libraries except for
+import libraries. Interfacing must be done by the mean of DLLs.
+@item
+It is possible to link against Microsoft C libraries. Yet the preferred
+solution is to use C/C++ compiler that comes with GNAT, since it
+doesn't require having two different development environments and makes the
+inter-language debugging experience smoother.
-@table @asis
+@item
+When the compilation environment is located on FAT32 drives, users may
+experience recompilations of the source files that have not changed if
+Daylight Saving Time (DST) state has changed since the last time files
+were compiled. NTFS drives do not have this problem.
-@item @code{-aO@emph{dir}}
+@item
+No components of the GNAT toolset use any entries in the Windows
+registry. The only entries that can be created are file associations and
+PATH settings, provided the user has chosen to create them at installation
+time, as well as some minimal book-keeping information needed to correctly
+uninstall or integrate different GNAT products.
+@end itemize
-When searching for ALI and object files, look in directory @cite{dir}.
-@end table
+@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{1c3}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{1c4}
+@subsection Using a network installation of GNAT
-@geindex -I (gnatclean)
+Make sure the system on which GNAT is installed is accessible from the
+current machine, i.e., the install location is shared over the network.
+Shared resources are accessed on Windows by means of UNC paths, which
+have the format @code{\\\\server\\sharename\\path}
-@table @asis
+In order to use such a network installation, simply add the UNC path of the
+@code{bin} directory of your GNAT installation in front of your PATH. For
+example, if GNAT is installed in @code{\GNAT} directory of a share location
+called @code{c-drive} on a machine @code{LOKI}, the following command will
+make it available:
-@item @code{-I@emph{dir}}
+@quotation
-Equivalent to @code{-aO@emph{dir}}.
-@end table
+@example
+$ path \\loki\c-drive\gnat\bin;%path%`
+@end example
+@end quotation
-@geindex -I- (gnatclean)
+Be aware that every compilation using the network installation results in the
+transfer of large amounts of data across the network and will likely cause
+serious performance penalty.
-@geindex Source files
-@geindex suppressing search
+@node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics
+@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
-@table @asis
+@geindex CONSOLE Subsystem
-@item @code{-I-}
+@geindex WINDOWS Subsystem
-Do not look for ALI or object files in the directory
-where @cite{gnatclean} was invoked.
-@end table
+@geindex -mwindows
-@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{23}@anchor{gnat_ugn/gnat_utility_programs id5}@anchor{1d3}
-@section The GNAT Library Browser @cite{gnatls}
+There are two main subsystems under Windows. The @code{CONSOLE} subsystem
+(which is the default subsystem) will always create a console when
+launching the application. This is not something desirable when the
+application has a Windows GUI. To get rid of this console the
+application must be using the @code{WINDOWS} subsystem. To do so
+the @code{-mwindows} linker option must be specified.
+@quotation
-@geindex Library browser
+@example
+$ gnatmake winprog -largs -mwindows
+@end example
+@end quotation
-@geindex gnatls
+@node Temporary Files,Disabling Command Line Argument Expansion,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics
+@anchor{gnat_ugn/platform_specific_information id12}@anchor{1c7}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{1c8}
+@subsection Temporary Files
-@cite{gnatls} is a tool that outputs information about compiled
-units. It gives the relationship between objects, unit names and source
-files. It can also be used to check the source dependencies of a unit
-as well as various characteristics.
-Note: to invoke @cite{gnatls} with a project file, use the @cite{gnat}
-driver (see @ref{11f,,The GNAT Driver and Project Files}).
+@geindex Temporary files
-@menu
-* Running gnatls::
-* Switches for gnatls::
-* Example of gnatls Usage::
+It is possible to control where temporary files gets created by setting
+the
+@geindex TMP
+@geindex environment variable; TMP
+@code{TMP} environment variable. The file will be created:
-@end menu
-@node Running gnatls,Switches for gnatls,,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id6}@anchor{1d4}@anchor{gnat_ugn/gnat_utility_programs running-gnatls}@anchor{1d5}
-@subsection Running @cite{gnatls}
+@itemize *
+@item
+Under the directory pointed to by the
+@geindex TMP
+@geindex environment variable; TMP
+@code{TMP} environment variable if
+this directory exists.
-The @cite{gnatls} command has the form
+@item
+Under @code{c:\temp}, if the
+@geindex TMP
+@geindex environment variable; TMP
+@code{TMP} environment variable is not
+set (or not pointing to a directory) and if this directory exists.
-@quotation
+@item
+Under the current working directory otherwise.
+@end itemize
-@example
-$ gnatls switches `object_or_ali_file`
-@end example
-@end quotation
+This allows you to determine exactly where the temporary
+file will be created. This is particularly useful in networked
+environments where you may not have write access to some
+directories.
-The main argument is the list of object or @code{ali} files
-(see @ref{44,,The Ada Library Information Files})
-for which information is requested.
+@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
-In normal mode, without additional option, @cite{gnatls} produces a
-four-column listing. Each line represents information for a specific
-object. The first column gives the full path of the object, the second
-column gives the name of the principal unit in this object, the third
-column gives the status of the source and the fourth column gives the
-full path of the source representing this unit.
-Here is a simple example of use:
-@quotation
+@geindex Command Line Argument Expansion
-@example
-$ gnatls *.o
-./demo1.o demo1 DIF demo1.adb
-./demo2.o demo2 OK demo2.adb
-./hello.o h1 OK hello.adb
-./instr-child.o instr.child MOK instr-child.adb
-./instr.o instr OK instr.adb
-./tef.o tef DIF tef.adb
-./text_io_example.o text_io_example OK text_io_example.adb
-./tgef.o tgef DIF tgef.adb
-@end example
-@end quotation
+By default, an executable compiled for the Windows platform will do
+the following postprocessing on the arguments passed on the command
+line:
-The first line can be interpreted as follows: the main unit which is
-contained in
-object file @code{demo1.o} is demo1, whose main source is in
-@code{demo1.adb}. Furthermore, the version of the source used for the
-compilation of demo1 has been modified (DIF). Each source file has a status
-qualifier which can be:
+@itemize *
-@table @asis
+@item
+If the argument contains the characters @code{*} and/or @code{?}, then
+file expansion will be attempted. For example, if the current directory
+contains @code{a.txt} and @code{b.txt}, then when calling:
-@item @emph{OK (unchanged)}
+@example
+$ my_ada_program *.txt
+@end example
-The version of the source file used for the compilation of the
-specified unit corresponds exactly to the actual source file.
+The following arguments will effectively be passed to the main program
+(for example when using @code{Ada.Command_Line.Argument}):
-@item @emph{MOK (slightly modified)}
+@example
+Ada.Command_Line.Argument (1) -> "a.txt"
+Ada.Command_Line.Argument (2) -> "b.txt"
+@end example
-The version of the source file used for the compilation of the
-specified unit differs from the actual source file but not enough to
-require recompilation. If you use gnatmake with the qualifier
-@emph{-m (minimal recompilation)}, a file marked
-MOK will not be recompiled.
+@item
+Filename expansion can be disabled for a given argument by using single
+quotes. Thus, calling:
-@item @emph{DIF (modified)}
+@example
+$ my_ada_program '*.txt'
+@end example
-No version of the source found on the path corresponds to the source
-used to build this object.
+will result in:
-@item @emph{??? (file not found)}
+@example
+Ada.Command_Line.Argument (1) -> "*.txt"
+@end example
+@end itemize
-No source file was found for this unit.
+Note that if the program is launched from a shell such as Cygwin Bash
+then quote removal might be performed by the shell.
-@item @emph{HID (hidden, unchanged version not first on PATH)}
+In some contexts it might be useful to disable this feature (for example if
+the program performs its own argument expansion). In order to do this, a C
+symbol needs to be defined and set to @code{0}. You can do this by
+adding the following code fragment in one of your Ada units:
-The version of the source that corresponds exactly to the source used
-for compilation has been found on the path but it is hidden by another
-version of the same source that has been modified.
-@end table
+@example
+Do_Argv_Expansion : Integer := 0;
+pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion");
+@end example
-@node Switches for gnatls,Example of gnatls Usage,Running gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id7}@anchor{1d6}@anchor{gnat_ugn/gnat_utility_programs switches-for-gnatls}@anchor{1d7}
-@subsection Switches for @cite{gnatls}
+The results of previous examples will be respectively:
+@example
+Ada.Command_Line.Argument (1) -> "*.txt"
+@end example
-@cite{gnatls} recognizes the following switches:
+and:
-@geindex --version (gnatls)
+@example
+Ada.Command_Line.Argument (1) -> "'*.txt'"
+@end example
+@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
-@table @asis
-@item @code{--version}
+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:
-Display Copyright and version, then exit disregarding all other options.
-@end table
+@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
-@geindex --help (gnatls)
+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
-@table @asis
-@item @code{*--help}
+Developing pure Ada applications on Windows is no different than on
+other GNAT-supported platforms. However, when developing or porting an
+application that contains a mix of Ada and C/C++, the choice of your
+Windows C/C++ development environment conditions your overall
+interoperability strategy.
-If @emph{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
+If you use @code{gcc} or Microsoft C to compile the non-Ada part of
+your application, there are no Windows-specific restrictions that
+affect the overall interoperability with your Ada code. If you do want
+to use the Microsoft tools for your C++ code, you have two choices:
-@geindex -a (gnatls)
+@itemize *
-@table @asis
+@item
+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{1cd,,Using DLLs with GNAT}).
-@item @code{-a}
+@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{1ce,,Building DLLs with GNAT Project files}) and use the Microsoft
+or whatever environment to build your executable.
+@end itemize
-Consider all units, including those of the predefined Ada library.
-Especially useful with @emph{-d}.
-@end table
+In addition to the description about C main in
+@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:
-@geindex -d (gnatls)
+@quotation
+@example
+/* main.c */
+extern void adainit (void);
+extern void adafinal (void);
+extern void __gnat_initialize(void*);
+extern void call_to_ada (void);
-@table @asis
+int main (int argc, char *argv[])
+@{
+ int SEH [2];
-@item @code{-d}
+ /* Initialize the SEH context */
+ __gnat_initialize (&SEH);
-List sources from which specified units depend on.
-@end table
+ adainit();
-@geindex -h (gnatls)
+ /* Then call Ada services in the stand-alone library */
+ call_to_ada();
-@table @asis
+ adafinal();
+@}
+@end example
+@end quotation
-@item @code{-h}
+Note that this is not needed on x86_64-windows where the Windows
+native SEH support is used.
-Output the list of options.
-@end table
+@menu
+* Windows Calling Conventions::
+* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs.
+* Using DLLs with GNAT::
+* Building DLLs with GNAT Project files::
+* Building DLLs with GNAT::
+* Building DLLs with gnatdll::
+* Ada DLLs and Finalization::
+* Creating a Spec for Ada DLLs::
+* GNAT and Windows Resources::
+* Using GNAT DLLs from Microsoft Visual Studio Applications::
+* Debugging a DLL::
+* Setting Stack Size from gnatlink::
+* Setting Heap Size from gnatlink::
-@geindex -o (gnatls)
+@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{1cf}@anchor{gnat_ugn/platform_specific_information id14}@anchor{1d0}
+@subsubsection Windows Calling Conventions
-@table @asis
-@item @code{-o}
+@geindex Stdcall
-Only output information about object files.
-@end table
+@geindex APIENTRY
-@geindex -s (gnatls)
+This section pertain only to Win32. On Win64 there is a single native
+calling convention. All convention specifiers are ignored on this
+platform.
+When a subprogram @code{F} (caller) calls a subprogram @code{G}
+(callee), there are several ways to push @code{G}'s parameters on the
+stack and there are several possible scenarios to clean up the stack
+upon @code{G}'s return. A calling convention is an agreed upon software
+protocol whereby the responsibilities between the caller (@code{F}) and
+the callee (@code{G}) are clearly defined. Several calling conventions
+are available for Windows:
-@table @asis
-@item @code{-s}
+@itemize *
-Only output information about source files.
-@end table
+@item
+@code{C} (Microsoft defined)
-@geindex -u (gnatls)
+@item
+@code{Stdcall} (Microsoft defined)
+@item
+@code{Win32} (GNAT specific)
-@table @asis
+@item
+@code{DLL} (GNAT specific)
+@end itemize
-@item @code{-u}
+@menu
+* C Calling Convention::
+* Stdcall Calling Convention::
+* Win32 Calling Convention::
+* DLL Calling Convention::
-Only output information about compilation units.
-@end table
+@end menu
-@geindex -files (gnatls)
+@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions
+@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
-@table @asis
+This is the default calling convention used when interfacing to C/C++
+routines compiled with either @code{gcc} or Microsoft Visual C++.
-@item @code{-files=@emph{file}}
+In the @code{C} calling convention subprogram parameters are pushed on the
+stack by the caller from right to left. The caller itself is in charge of
+cleaning up the stack after the call. In addition, the name of a routine
+with @code{C} calling convention is mangled by adding a leading underscore.
-Take as arguments the files listed in text file @cite{file}.
-Text file @cite{file} may contain empty lines that are ignored.
-Each nonempty line should contain the name of an existing file.
-Several such switches may be specified simultaneously.
-@end table
+The name to use on the Ada side when importing (or exporting) a routine
+with @code{C} calling convention is the name of the routine. For
+instance the C function:
-@geindex -aO (gnatls)
+@quotation
-@geindex -aI (gnatls)
+@example
+int get_val (long);
+@end example
+@end quotation
-@geindex -I (gnatls)
+should be imported from Ada as follows:
-@geindex -I- (gnatls)
+@quotation
+@example
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (C, Get_Val, External_Name => "get_val");
+@end example
+@end quotation
-@table @asis
+Note that in this particular case the @code{External_Name} parameter could
+have been omitted since, when missing, this parameter is taken to be the
+name of the Ada entity in lower case. When the @code{Link_Name} parameter
+is missing, as in the above example, this parameter is set to be the
+@code{External_Name} with a leading underscore.
-@item @code{-aO@emph{dir}}, @code{-aI@emph{dir}}, @code{-I@emph{dir}}, @code{-I-}, @code{-nostdinc}
+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{1d3,,Stdcall Calling Convention}).
-Source path manipulation. Same meaning as the equivalent @emph{gnatmake}
-flags (@ref{df,,Switches for gnatmake}).
-@end table
+@node Stdcall Calling Convention,Win32 Calling Convention,C Calling Convention,Windows Calling Conventions
+@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
-@geindex -aP (gnatls)
-
-
-@table @asis
-
-@item @code{-aP@emph{dir}}
-
-Add @cite{dir} at the beginning of the project search dir.
-@end table
-
-@geindex --RTS (gnatls)
-
-
-@table @asis
-
-@item @code{--RTS=@emph{rts-path}`}
-
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{df,,Switches for gnatmake}).
-@end table
-
-@geindex -v (gnatls)
-
-
-@table @asis
-
-@item @code{-v}
-
-Verbose mode. Output the complete source, object and project paths. Do not use
-the default column layout but instead use long format giving as much as
-information possible on each requested units, including special
-characteristics such as:
-
-
-@itemize *
-@item
-@emph{Preelaborable}: The unit is preelaborable in the Ada sense.
-
-@item
-@emph{No_Elab_Code}: No elaboration code has been produced by the compiler for this unit.
-
-@item
-@emph{Pure}: The unit is pure in the Ada sense.
-
-@item
-@emph{Elaborate_Body}: The unit contains a pragma Elaborate_Body.
-
-@item
-@emph{Remote_Types}: The unit contains a pragma Remote_Types.
-
-@item
-@emph{Shared_Passive}: The unit contains a pragma Shared_Passive.
-
-@item
-@emph{Predefined}: This unit is part of the predefined environment and cannot be modified
-by the user.
-
-@item
-@emph{Remote_Call_Interface}: The unit contains a pragma Remote_Call_Interface.
-@end itemize
-@end table
-
-@node Example of gnatls Usage,,Switches for gnatls,The GNAT Library Browser gnatls
-@anchor{gnat_ugn/gnat_utility_programs id8}@anchor{1d8}@anchor{gnat_ugn/gnat_utility_programs example-of-gnatls-usage}@anchor{1d9}
-@subsection Example of @cite{gnatls} Usage
+This convention, which was the calling convention used for Pascal
+programs, is used by Microsoft for all the routines in the Win32 API for
+efficiency reasons. It must be used to import any routine for which this
+convention was specified.
+In the @code{Stdcall} calling convention subprogram parameters are pushed
+on the stack by the caller from right to left. The callee (and not the
+caller) is in charge of cleaning the stack on routine exit. In addition,
+the name of a routine with @code{Stdcall} calling convention is mangled by
+adding a leading underscore (as for the @code{C} calling convention) and a
+trailing @code{@@@emph{nn}}, where @code{nn} is the overall size (in
+bytes) of the parameters passed to the routine.
-Example of using the verbose switch. Note how the source and
-object paths are affected by the -I switch.
+The name to use on the Ada side when importing a C routine with a
+@code{Stdcall} calling convention is the name of the C routine. The leading
+underscore and trailing @code{@@@emph{nn}} are added automatically by
+the compiler. For instance the Win32 function:
@quotation
@example
-$ gnatls -v -I.. demo1.o
-
-GNATLS 5.03w (20041123-34)
-Copyright 1997-2004 Free Software Foundation, Inc.
-
-Source Search Path:
- <Current_Directory>
- ../
- /home/comar/local/adainclude/
-
-Object Search Path:
- <Current_Directory>
- ../
- /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/
-
-Project Search Path:
- <Current_Directory>
- /home/comar/local/lib/gnat/
-
-./demo1.o
- Unit =>
- Name => demo1
- Kind => subprogram body
- Flags => No_Elab_Code
- Source => demo1.adb modified
+APIENTRY int get_val (long);
@end example
@end quotation
-The following is an example of use of the dependency list.
-Note the use of the -s switch
-which gives a straight list of source files. This can be useful for
-building specialized scripts.
+should be imported from Ada as follows:
@quotation
@example
-$ gnatls -d demo2.o
-./demo2.o demo2 OK demo2.adb
- OK gen_list.ads
- OK gen_list.adb
- OK instr.ads
- OK instr-child.ads
-
-$ gnatls -d -s -a demo1.o
-demo1.adb
-/home/comar/local/adainclude/ada.ads
-/home/comar/local/adainclude/a-finali.ads
-/home/comar/local/adainclude/a-filico.ads
-/home/comar/local/adainclude/a-stream.ads
-/home/comar/local/adainclude/a-tags.ads
-gen_list.ads
-gen_list.adb
-/home/comar/local/adainclude/gnat.ads
-/home/comar/local/adainclude/g-io.ads
-instr.ads
-/home/comar/local/adainclude/system.ads
-/home/comar/local/adainclude/s-exctab.ads
-/home/comar/local/adainclude/s-finimp.ads
-/home/comar/local/adainclude/s-finroo.ads
-/home/comar/local/adainclude/s-secsta.ads
-/home/comar/local/adainclude/s-stalib.ads
-/home/comar/local/adainclude/s-stoele.ads
-/home/comar/local/adainclude/s-stratt.ads
-/home/comar/local/adainclude/s-tasoli.ads
-/home/comar/local/adainclude/s-unstyp.ads
-/home/comar/local/adainclude/unchconv.ads
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (Stdcall, Get_Val);
+-- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4"
@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{24}@anchor{gnat_ugn/gnat_utility_programs id9}@anchor{1da}
-@section The Cross-Referencing Tools @cite{gnatxref} and @cite{gnatfind}
-
-
-@geindex gnatxref
+As for the @code{C} calling convention, when the @code{External_Name}
+parameter is missing, it is taken to be the name of the Ada entity in lower
+case. If instead of writing the above import pragma you write:
-@geindex gnatfind
+@quotation
-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.
+@example
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");
+@end example
+@end quotation
-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.
+then the imported routine is @code{_retrieve_val@@4}. However, if instead
+of specifying the @code{External_Name} parameter you specify the
+@code{Link_Name} as in the following example:
-The two tools @cite{gnatxref} and @cite{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 @cite{gnatfind} is intended for locating
-definitions and/or references to a specified entity or entities, whereas
-@cite{gnatxref} is oriented to generating a full report of all
-cross-references.
+@quotation
-To use these tools, you must not compile your application using the
-@emph{-gnatx} switch on the @emph{gnatmake} command line
-(see @ref{1d,,Building with gnatmake}). Otherwise, cross-referencing
-information will not be generated.
+@example
+function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
+pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
+@end example
+@end quotation
-Note: to invoke @cite{gnatxref} or @cite{gnatfind} with a project file,
-use the @cite{gnat} driver (see @ref{11f,,The GNAT Driver and Project Files}).
+then the imported routine is @code{retrieve_val}, that is, there is no
+decoration at all. No leading underscore and no Stdcall suffix
+@code{@@@emph{nn}}.
-@menu
-* gnatxref Switches::
-* gnatfind Switches::
-* Project Files for gnatxref and gnatfind::
-* Regular Expressions in gnatfind and gnatxref::
-* Examples of gnatxref Usage::
-* Examples of gnatfind Usage::
+This is especially important as in some special cases a DLL's entry
+point name lacks a trailing @code{@@@emph{nn}} while the exported
+name generated for a call has it.
-@end menu
+It is also possible to import variables defined in a DLL by using an
+import pragma for a variable. As an example, if a DLL contains a
+variable defined as:
-@node gnatxref Switches,gnatfind Switches,,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id10}@anchor{1db}@anchor{gnat_ugn/gnat_utility_programs gnatxref-switches}@anchor{1dc}
-@subsection @cite{gnatxref} Switches
+@quotation
+@example
+int my_var;
+@end example
+@end quotation
-The command invocation for @cite{gnatxref} is:
+then, to access this variable from Ada you should write:
@quotation
@example
-$ gnatxref [`switches`] `sourcefile1` [`sourcefile2` ...]
+My_Var : Interfaces.C.int;
+pragma Import (Stdcall, My_Var);
@end example
@end quotation
-where
+Note that to ease building cross-platform bindings this 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{1d5}@anchor{gnat_ugn/platform_specific_information id17}@anchor{1d6}
+@subsubsection @code{Win32} Calling Convention
-@table @asis
-@item @emph{sourcefile1} [, @emph{sourcefile2} ...]
+This convention, which is GNAT-specific is fully equivalent to the
+@code{Stdcall} calling convention described above.
-identify the source files for which a report is to be generated. The
-'with'ed units will be processed too. You must provide at least one file.
+@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions
+@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
-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}.
-You shouldn't specify any directory name, just base names. @emph{gnatxref}
-and @emph{gnatfind} will be able to locate these files by themselves using
-the source path. If you specify directories, no result is produced.
-@end table
+This convention, which is GNAT-specific is fully equivalent to the
+@code{Stdcall} calling convention described above.
-The following switches are available for @emph{gnatxref}:
+@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{1d9}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{1da}
+@subsubsection Introduction to Dynamic Link Libraries (DLLs)
-@geindex --version (gnatxref)
+@geindex DLL
-@table @asis
+A Dynamically Linked Library (DLL) is a library that can be shared by
+several applications running under Windows. A DLL can contain any number of
+routines and variables.
-@item @code{-version}
+One advantage of DLLs is that you can change and enhance them without
+forcing all the applications that depend on them to be relinked or
+recompiled. However, you should be aware than all calls to DLL routines are
+slower since, as you will understand below, such calls are indirect.
-Display Copyright and version, then exit disregarding all other options.
-@end table
+To illustrate the remainder of this section, suppose that an application
+wants to use the services of a DLL @code{API.dll}. To use the services
+provided by @code{API.dll} you must statically link against the DLL or
+an import library which contains a jump table with an entry for each
+routine and variable exported by the DLL. In the Microsoft world this
+import library is called @code{API.lib}. When using GNAT this import
+library is called either @code{libAPI.dll.a}, @code{libapi.dll.a},
+@code{libAPI.a} or @code{libapi.a} (names are case insensitive).
-@geindex --help (gnatxref)
+After you have linked your application with the DLL or the import library
+and you run your application, here is what happens:
-@table @asis
+@itemize *
-@item @code{-help}
+@item
+Your application is loaded into memory.
-If @emph{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
+@item
+The DLL @code{API.dll} is mapped into the address space of your
+application. This means that:
-@geindex -a (gnatxref)
+@itemize -
-@table @asis
+@item
+The DLL will use the stack of the calling thread.
-@item @code{a}
+@item
+The DLL will use the virtual address space of the calling process.
-If this switch is present, @cite{gnatfind} and @cite{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 @cite{gnatfind} and @cite{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
+@item
+The DLL will allocate memory from the virtual address space of the calling
+process.
-@geindex -aIDIR (gnatxref)
+@item
+Handles (pointers) can be safely exchanged between routines in the DLL
+routines and routines in the application using the DLL.
+@end itemize
+@item
+The entries in the jump table (from the import library @code{libAPI.dll.a}
+or @code{API.lib} or automatically created when linking against a DLL)
+which is part of your application are initialized with the addresses
+of the routines and variables in @code{API.dll}.
-@table @asis
+@item
+If present in @code{API.dll}, routines @code{DllMain} or
+@code{DllMainCRTStartup} are invoked. These routines typically contain
+the initialization code needed for the well-being of the routines and
+variables exported by the DLL.
+@end itemize
-@item @code{aI@emph{DIR}}
+There is an additional point which is worth mentioning. In the Windows
+world there are two kind of DLLs: relocatable and non-relocatable
+DLLs. Non-relocatable DLLs can only be loaded at a very specific address
+in the target application address space. If the addresses of two
+non-relocatable DLLs overlap and these happen to be used by the same
+application, a conflict will occur and the application will run
+incorrectly. Hence, when possible, it is always preferable to use and
+build relocatable DLLs. Both relocatable and non-relocatable DLLs are
+supported by GNAT. Note that the @code{-s} linker option (see GNU Linker
+User's Guide) removes the debugging symbols from the DLL but the DLL can
+still be relocated.
-When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @emph{gnatmake}.
-@end table
+As a side note, an interesting difference between Microsoft DLLs and
+Unix shared libraries, is the fact that on most Unix systems all public
+routines are exported by default in a Unix shared library, while under
+Windows it is possible (but not required) to list exported routines in
+a definition file (see @ref{1db,,The Definition File}).
-@geindex -aODIR (gnatxref)
+@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{1dc}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{1cd}
+@subsubsection Using DLLs with GNAT
-@table @asis
+To use the services of a DLL, say @code{API.dll}, in your Ada application
+you must have:
-@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
-@emph{gnatmake}.
-@end table
+@itemize *
-@geindex -nostdinc (gnatxref)
+@item
+The Ada spec for the routines and/or variables you want to access in
+@code{API.dll}. If not available this Ada spec must be built from the C/C++
+header files provided with the DLL.
+@item
+The import library (@code{libAPI.dll.a} or @code{API.lib}). As previously
+mentioned an import library is a statically linked library containing the
+import table which will be filled at load time to point to the actual
+@code{API.dll} routines. Sometimes you don't have an import library for the
+DLL you want to use. The following sections will explain how to build
+one. Note that this is optional.
-@table @asis
+@item
+The actual DLL, @code{API.dll}.
+@end itemize
-@item @code{nostdinc}
+Once you have all the above, to compile an Ada application that uses the
+services of @code{API.dll} and whose main subprogram is @code{My_Ada_App},
+you simply issue the command
-Do not look for sources in the system default directory.
-@end table
+@quotation
-@geindex -nostdlib (gnatxref)
+@example
+$ gnatmake my_ada_app -largs -lAPI
+@end example
+@end quotation
+The argument @code{-largs -lAPI} at the end of the @code{gnatmake} command
+tells the GNAT linker to look for an import library. The linker will
+look for a library name in this specific order:
-@table @asis
-@item @code{nostdlib}
+@itemize *
-Do not look for library files in the system default directory.
-@end table
+@item
+@code{libAPI.dll.a}
-@geindex --ext (gnatxref)
+@item
+@code{API.dll.a}
+@item
+@code{libAPI.a}
-@table @asis
+@item
+@code{API.lib}
-@item @code{-ext=@emph{extension}}
+@item
+@code{libAPI.dll}
-Specify an alternate ali file extension. The default is @cite{ali} and other
-extensions (e.g. @cite{gli} for C/C++ sources when using @emph{-fdump-xref})
-may be specified via this switch. Note that if this switch overrides the
-default, which means that only the new extension will be considered.
-@end table
+@item
+@code{API.dll}
+@end itemize
+
+The first three are the GNU style import libraries. The third is the
+Microsoft style import libraries. The last two are the actual DLL names.
-@geindex --RTS (gnatxref)
+Note that if the Ada package spec for @code{API.dll} contains the
+following pragma
+@quotation
-@table @asis
+@example
+pragma Linker_Options ("-lAPI");
+@end example
+@end quotation
-@item @code{-RTS=@emph{rts-path}}
+you do not have to add @code{-largs -lAPI} at the end of the
+@code{gnatmake} command.
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{df,,Switches for gnatmake}).
-@end table
+If any one of the items above is missing you will have to create it
+yourself. The following sections explain how to do so using as an
+example a fictitious DLL called @code{API.dll}.
-@geindex -d (gnatxref)
+@menu
+* Creating an Ada Spec for the DLL Services::
+* Creating an Import Library::
+@end menu
-@table @asis
+@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{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
-@item @code{d}
-If this switch is set @cite{gnatxref} will output the parent type
-reference for each matching derived types.
-@end table
+A DLL typically comes with a C/C++ header file which provides the
+definitions of the routines and variables exported by the DLL. The Ada
+equivalent of this header file is a package spec that contains definitions
+for the imported entities. If the DLL you intend to use does not come with
+an Ada spec you have to generate one such spec yourself. For example if
+the header file of @code{API.dll} is a file @code{api.h} containing the
+following two definitions:
-@geindex -f (gnatxref)
+@quotation
+@example
+int some_var;
+int get (char *);
+@end example
+@end quotation
-@table @asis
+then the equivalent Ada spec could be:
-@item @code{f}
+@quotation
-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
+@example
+with Interfaces.C.Strings;
+package API is
+ use Interfaces;
-@geindex -g (gnatxref)
+ Some_Var : C.int;
+ function Get (Str : C.Strings.Chars_Ptr) return C.int;
+private
+ pragma Import (C, Get);
+ pragma Import (DLL, Some_Var);
+end API;
+@end example
+@end quotation
-@table @asis
+@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{1df}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{1e0}
+@subsubsection Creating an Import Library
-@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
-@cite{gnatfind} and @cite{gnatxref}.
-@end table
+@geindex Import library
-@geindex -IDIR (gnatxref)
+If a Microsoft-style import library @code{API.lib} or a GNAT-style
+import library @code{libAPI.dll.a} or @code{libAPI.a} is available
+with @code{API.dll} you can skip this section. You can also skip this
+section if @code{API.dll} or @code{libAPI.dll} is built with GNU tools
+as in this case it is possible to link directly against the
+DLL. Otherwise read on.
+@geindex Definition file
+@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{1db}
+@subsubheading The Definition File
-@table @asis
-@item @code{I@emph{DIR}}
+As previously mentioned, and unlike Unix systems, the list of symbols
+that are exported from a DLL must be provided explicitly in Windows.
+The main goal of a definition file is precisely that: list the symbols
+exported by a DLL. A definition file (usually a file with a @code{.def}
+suffix) has the following structure:
-Equivalent to @code{-aODIR -aIDIR}.
-@end table
+@quotation
-@geindex -pFILE (gnatxref)
+@example
+[LIBRARY `@w{`}name`@w{`}]
+[DESCRIPTION `@w{`}string`@w{`}]
+EXPORTS
+ `@w{`}symbol1`@w{`}
+ `@w{`}symbol2`@w{`}
+ ...
+@end example
+@end quotation
@table @asis
-@item @code{p@emph{FILE}}
-
-Specify a project file to use @ref{b,,GNAT Project Manager}.
-If you need to use the @code{.gpr}
-project files, you should use gnatxref through the GNAT driver
-(@emph{gnat xref -Pproject}).
+@item @emph{LIBRARY name}
-By default, @cite{gnatxref} and @cite{gnatfind} will try to locate a
-project file in the current directory.
+This section, which is optional, gives the name of the DLL.
-If a project file is either specified or found by the tools, then the content
-of the source directory and object directory lines are added as if they
-had been specified respectively by @code{-aI}
-and @code{-aO}.
+@item @emph{DESCRIPTION string}
-@item @code{u}
+This section, which is optional, gives a description string that will be
+embedded in the import library.
-Output only unused symbols. This may be really useful if you give your
-main compilation unit on the command line, as @cite{gnatxref} will then
-display every unused entity and 'with'ed package.
+@item @emph{EXPORTS}
-@item @code{v}
+This section gives the list of exported symbols (procedures, functions or
+variables). For instance in the case of @code{API.dll} the @code{EXPORTS}
+section of @code{API.def} looks like:
-Instead of producing the default output, @cite{gnatxref} will generate a
-@code{tags} file that can be used by vi. For examples how to use this
-feature, see @ref{1dd,,Examples of gnatxref Usage}. The tags file is output
-to the standard output, thus you will have to redirect it to a file.
+@example
+EXPORTS
+ some_var
+ get
+@end example
@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}.
+Note that you must specify the correct suffix (@code{@@@emph{nn}})
+(see @ref{1cf,,Windows Calling Conventions}) for a Stdcall
+calling convention function in the exported symbols list.
-@node gnatfind Switches,Project Files for gnatxref and gnatfind,gnatxref Switches,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id11}@anchor{1de}@anchor{gnat_ugn/gnat_utility_programs gnatfind-switches}@anchor{1df}
-@subsection @cite{gnatfind} Switches
+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{1e1}
+@subsubheading Creating a Definition File Automatically
-The command invocation for @cite{gnatfind} is:
+You can automatically create the definition file @code{API.def}
+(see @ref{1db,,The Definition File}) from a DLL.
+For that use the @code{dlltool} program as follows:
@quotation
@example
-$ gnatfind [`switches`] `pattern`[:`sourcefile`[:`line`[:`column`]]]
- [`file1` `file2` ...]
+$ dlltool API.dll -z API.def --export-all-symbols
@end example
-@end quotation
-with the following iterpretation of the command arguments:
+Note that if some routines in the DLL have the @code{Stdcall} convention
+(@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.
+Here are some hints to find the right @code{@@@emph{nn}} suffix.
-@table @asis
-@item @emph{pattern}
+@itemize -
-An entity will be output only if it matches the regular expression found
-in @cite{pattern}, see @ref{1e0,,Regular Expressions in gnatfind and gnatxref}.
+@item
+If you have the Microsoft import library (.lib), it is possible to get
+the right symbols by using Microsoft @code{dumpbin} tool (see the
+corresponding Microsoft documentation for further details).
-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.
+@example
+$ dumpbin /exports api.lib
+@end example
-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
+If you have a message about a missing symbol at link time the compiler
+tells you what symbol is expected. You just have to go back to the
+definition file and add the right suffix.
+@end itemize
+@end quotation
+@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{1e2}
+@subsubheading GNAT-Style Import Library
-@item @emph{sourcefile}
-@cite{gnatfind} will look for references, bodies or declarations
-of symbols referenced in @code{sourcefile}, at line @cite{line}
-and column @cite{column}. See @ref{1e1,,Examples of gnatfind Usage}
-for syntax examples.
+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{1e3,,Using gnatdll}) as follows:
-@item @emph{line}
+@quotation
-A decimal integer identifying the line number containing
-the reference to the entity (or entities) to be located.
+@example
+$ gnatdll -e API.def -d API.dll
+@end example
-@item @emph{column}
+@code{gnatdll} takes as input a definition file @code{API.def} and the
+name of the DLL containing the services listed in the definition file
+@code{API.dll}. The name of the static import library generated is
+computed from the name of the definition file as follows: if the
+definition file name is @code{xyz.def}, the import library name will
+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{1e3,,Using gnatdll} for more information about @code{gnatdll}).
+@end quotation
+@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{1e4}
+@subsubheading Microsoft-Style Import Library
-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 ...}
+A Microsoft import library is needed only if you plan to make an
+Ada DLL available to applications developed with Microsoft
+tools (@ref{1cc,,Mixed-Language Programming on Windows}).
-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.
+To create a Microsoft-style import library for @code{API.dll} you
+should create the .def file, then build the actual import library using
+Microsoft's @code{lib} utility:
-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}.
+@quotation
-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.
+@example
+$ lib -machine:IX86 -def:API.def -out:API.lib
+@end example
-Note that if you specify at least one file in this part, @cite{gnatfind} may
-sometimes not be able to find the body of the subprograms.
-@end table
+If you use the above command the definition file @code{API.def} must
+contain a line giving the name of the DLL:
-At least one of 'sourcefile' or 'pattern' has to be present on
-the command line.
+@example
+LIBRARY "API"
+@end example
-The following switches are available:
+See the Microsoft documentation for further details about the usage of
+@code{lib}.
+@end quotation
-@geindex --version (gnatfind)
+@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{1e5}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{1ce}
+@subsubsection Building DLLs with GNAT Project files
-@table @asis
+@geindex DLLs
+@geindex building
-@item @code{--version}
+There is nothing specific to Windows in the build process.
+See the @emph{Library Projects} section in the @emph{GNAT Project Manager}
+chapter of the @emph{GPRbuild User's Guide}.
-Display Copyright and version, then exit disregarding all other options.
-@end table
+Due to a system limitation, it is not possible under Windows to create threads
+when inside the @code{DllMain} routine which is used for auto-initialization
+of shared libraries, so it is not possible to have library level tasks in SALs.
-@geindex --help (gnatfind)
+@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{1e6}@anchor{gnat_ugn/platform_specific_information id24}@anchor{1e7}
+@subsubsection Building DLLs with GNAT
-@table @asis
+@geindex DLLs
+@geindex building
-@item @code{-help}
+This section explain how to build DLLs using the GNAT built-in DLL
+support. With the following procedure it is straight forward to build
+and use DLLs with GNAT.
-If @emph{--version} was not used, display usage, then exit disregarding
-all other options.
-@end table
-@geindex -a (gnatfind)
+@itemize *
+@item
+Building object files.
+The first step is to build all objects files that are to be included
+into the DLL. This is done by using the standard @code{gnatmake} tool.
-@table @asis
+@item
+Building the DLL.
+To build the DLL you must use the @code{gcc} @code{-shared} and
+@code{-shared-libgcc} options. It is quite simple to use this method:
-@item @code{a}
+@example
+$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ...
+@end example
-If this switch is present, @cite{gnatfind} and @cite{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 @cite{gnatfind} and @cite{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
+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{1db,,The Definition File}).
+For example:
-@geindex -aIDIR (gnatfind)
+@example
+$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ...
+@end example
+If you use a definition file you must export the elaboration procedures
+for every package that required one. Elaboration procedures are named
+using the package name followed by "_E".
-@table @asis
+@item
+Preparing DLL to be used.
+For the DLL to be used by client programs the bodies must be hidden
+from it and the .ali set with read-only attribute. This is very important
+otherwise GNAT will recompile all packages and will not actually use
+the code in the DLL. For example:
-@item @code{aI@emph{DIR}}
+@example
+$ mkdir apilib
+$ copy *.ads *.ali api.dll apilib
+$ attrib +R apilib\\*.ali
+@end example
+@end itemize
-When looking for source files also look in directory DIR. The order in which
-source file search is undertaken is the same as for @emph{gnatmake}.
-@end table
+At this point it is possible to use the DLL by directly linking
+against it. Note that you must use the GNAT shared runtime when using
+GNAT shared libraries. This is achieved by using the @code{-shared} binder
+option.
-@geindex -aODIR (gnatfind)
+@quotation
+@example
+$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
+@end example
+@end quotation
-@table @asis
+@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{1e8}@anchor{gnat_ugn/platform_specific_information id25}@anchor{1e9}
+@subsubsection Building DLLs with gnatdll
-@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
-@emph{gnatmake}.
-@end table
-
-@geindex -nostdinc (gnatfind)
+@geindex DLLs
+@geindex building
+Note that it is preferred to use GNAT Project files
+(@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.
-@table @asis
+This section explains how to build DLLs containing Ada code using
+@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
+remainder of this section.
-@item @code{nostdinc}
+The steps required to build an Ada DLL that is to be used by Ada as well as
+non-Ada applications are as follows:
-Do not look for sources in the system default directory.
-@end table
-@geindex -nostdlib (gnatfind)
+@itemize *
+@item
+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{1ea,,Exporting Ada Entities}). You can
+skip this step if you plan to use the Ada DLL only from Ada applications.
-@table @asis
+@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{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 @code{nostdlib}
+@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{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.
-Do not look for library files in the system default directory.
-@end table
+@item
+You must provide a spec for the services exported by the Ada DLL in each
+of the programming languages to which you plan to make the DLL available.
-@geindex --ext (gnatfind)
+@item
+You must provide a definition file listing the exported entities
+(@ref{1db,,The Definition File}).
+@item
+Finally you must use @code{gnatdll} to produce the DLL and the import
+library (@ref{1e3,,Using gnatdll}).
+@end itemize
-@table @asis
+Note that a relocatable DLL stripped using the @code{strip}
+binutils tool will not be relocatable anymore. To build a DLL without
+debug information pass @code{-largs -s} to @code{gnatdll}. This
+restriction does not apply to a DLL built using a Library Project.
+See the @emph{Library Projects} section in the @emph{GNAT Project Manager}
+chapter of the @emph{GPRbuild User's Guide}.
-@item @code{-ext=@emph{extension}}
+@c Limitations_When_Using_Ada_DLLs_from Ada:
-Specify an alternate ali file extension. The default is @cite{ali} and other
-extensions (e.g. @cite{gli} for C/C++ sources when using @emph{-fdump-xref})
-may be specified via this switch. Note that if this switch overrides the
-default, which means that only the new extension will be considered.
-@end table
+@menu
+* Limitations When Using Ada DLLs from Ada::
+* Exporting Ada Entities::
+* Ada DLLs and Elaboration::
-@geindex --RTS (gnatfind)
+@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{1ed}
+@subsubsection Limitations When Using Ada DLLs from Ada
-@table @asis
-@item @code{-RTS=@emph{rts-path}}
+When using Ada DLLs from Ada applications there is a limitation users
+should be aware of. Because on Windows the GNAT run-time is not in a DLL of
+its own, each Ada DLL includes a part of the GNAT run-time. Specifically,
+each Ada DLL includes the services of the GNAT run-time that are necessary
+to the Ada code inside the DLL. As a result, when an Ada program uses an
+Ada DLL there are two independent GNAT run-times: one in the Ada DLL and
+one in the main program.
-Specifies the default location of the runtime library. Same meaning as the
-equivalent @emph{gnatmake} flag (@ref{df,,Switches for gnatmake}).
-@end table
+It is therefore not possible to exchange GNAT run-time objects between the
+Ada DLL and the main Ada program. Example of GNAT run-time objects are file
+handles (e.g., @code{Text_IO.File_Type}), tasks types, protected objects
+types, etc.
-@geindex -d (gnatfind)
+It is completely safe to exchange plain elementary, array or record types,
+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{1ea}@anchor{gnat_ugn/platform_specific_information id26}@anchor{1ee}
+@subsubsection Exporting Ada Entities
-@table @asis
-@item @code{d}
+@geindex Export table
-If this switch is set, then @cite{gnatfind} will output the parent type
-reference for each matching derived types.
-@end table
+Building a DLL is a way to encapsulate a set of services usable from any
+application. As a result, the Ada entities exported by a DLL should be
+exported with the @code{C} or @code{Stdcall} calling conventions to avoid
+any Ada name mangling. As an example here is an Ada package
+@code{API}, spec and body, exporting two procedures, a function, and a
+variable:
-@geindex -e (gnatfind)
+@quotation
+@example
+with Interfaces.C; use Interfaces;
+package API is
+ Count : C.int := 0;
+ function Factorial (Val : C.int) return C.int;
-@table @asis
+ procedure Initialize_API;
+ procedure Finalize_API;
+ -- Initialization & Finalization routines. More in the next section.
+private
+ pragma Export (C, Initialize_API);
+ pragma Export (C, Finalize_API);
+ pragma Export (C, Count);
+ pragma Export (C, Factorial);
+end API;
+@end example
-@item @code{e}
+@example
+package body API is
+ function Factorial (Val : C.int) return C.int is
+ Fact : C.int := 1;
+ begin
+ Count := Count + 1;
+ for K in 1 .. Val loop
+ Fact := Fact * K;
+ end loop;
+ return Fact;
+ end Factorial;
-By default, @cite{gnatfind} accept the simple regular expression set for
-@cite{pattern}. If this switch is set, then the pattern will be
-considered as full Unix-style regular expression.
-@end table
+ procedure Initialize_API is
+ procedure Adainit;
+ pragma Import (C, Adainit);
+ begin
+ Adainit;
+ end Initialize_API;
-@geindex -f (gnatfind)
+ procedure Finalize_API is
+ procedure Adafinal;
+ pragma Import (C, Adafinal);
+ begin
+ Adafinal;
+ end Finalize_API;
+end API;
+@end example
+@end quotation
+If the Ada DLL you are building will only be used by Ada applications
+you do not have to export Ada entities with a @code{C} or @code{Stdcall}
+convention. As an example, the previous package could be written as
+follows:
-@table @asis
+@quotation
-@item @code{f}
+@example
+package API is
+ Count : Integer := 0;
+ function Factorial (Val : Integer) return Integer;
-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
+ procedure Initialize_API;
+ procedure Finalize_API;
+ -- Initialization and Finalization routines.
+end API;
+@end example
-@geindex -g (gnatfind)
+@example
+package body API is
+ function Factorial (Val : Integer) return Integer is
+ Fact : Integer := 1;
+ begin
+ Count := Count + 1;
+ for K in 1 .. Val loop
+ Fact := Fact * K;
+ end loop;
+ return Fact;
+ end Factorial;
+ ...
+ -- The remainder of this package body is unchanged.
+end API;
+@end example
+@end quotation
-@table @asis
+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{1ef,,Creating the Definition File}).
-@item @code{g}
+@node Ada DLLs and Elaboration,,Exporting Ada Entities,Building DLLs with gnatdll
+@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
-If this switch is set, information is output only for library-level
-entities, ignoring local entities. The use of this switch may accelerate
-@cite{gnatfind} and @cite{gnatxref}.
-@end table
-@geindex -IDIR (gnatfind)
+@geindex DLLs and elaboration
+The DLL that you are building contains your Ada code as well as all the
+routines in the Ada library that are needed by it. The first thing a
+user of your DLL must do is elaborate the Ada code
+(@ref{f,,Elaboration Order Handling in GNAT}).
-@table @asis
+To achieve this you must export an initialization routine
+(@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{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{1e3,,Using gnatdll}).
-@item @code{I@emph{DIR}}
+When a DLL is loaded, Windows systematically invokes a routine called
+@code{DllMain}. It would therefore be possible to call @code{adainit}
+directly from @code{DllMain} without having to provide an explicit
+initialization routine. Unfortunately, it is not possible to call
+@code{adainit} from the @code{DllMain} if your program has library level
+tasks because access to the @code{DllMain} entry point is serialized by
+the system (that is, only a single thread can execute 'through' it at a
+time), which means that the GNAT run-time will deadlock waiting for the
+newly created task to complete its initialization.
-Equivalent to @code{-aODIR -aIDIR}.
-@end table
+@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{1f1}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{1ec}
+@subsubsection Ada DLLs and Finalization
-@geindex -pFILE (gnatfind)
+@geindex DLLs and finalization
-@table @asis
+When the services of an Ada DLL are no longer needed, the client code should
+invoke the DLL finalization routine, if available. The DLL finalization
+routine is in charge of releasing all resources acquired by the DLL. In the
+case of the Ada code contained in the DLL, this is achieved by calling
+routine @code{adafinal} generated by the GNAT binder
+(@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{1e3,,Using gnatdll}).
-@item @code{p@emph{FILE}}
+@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{1f2}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{1f3}
+@subsubsection Creating a Spec for Ada DLLs
-Specify a project file (@ref{b,,GNAT Project Manager}) to use.
-By default, @cite{gnatxref} and @cite{gnatfind} will try to locate a
-project file in the current directory.
-If a project file is either specified or found by the tools, then the content
-of the source directory and object directory lines are added as if they
-had been specified respectively by @code{-aI} and
-@code{-aO}.
-@end table
+To use the services exported by the Ada DLL from another programming
+language (e.g., C), you have to translate the specs of the exported Ada
+entities in that language. For instance in the case of @code{API.dll},
+the corresponding C header file could look like:
-@geindex -r (gnatfind)
+@quotation
+@example
+extern int *_imp__count;
+#define count (*_imp__count)
+int factorial (int);
+@end example
+@end quotation
-@table @asis
+It is important to understand that when building an Ada DLL to be used by
+other Ada applications, you need two different specs for the packages
+contained in the DLL: one for building the DLL and the other for using
+the DLL. This is because the @code{DLL} calling convention is needed to
+use a variable defined in a DLL, but when building the DLL, the variable
+must have either the @code{Ada} or @code{C} calling convention. As an
+example consider a DLL comprising the following package @code{API}:
-@item @code{r}
+@quotation
-By default, @cite{gnatfind} will output only the information about the
-declaration, body or type completion of the entities. If this switch is
-set, the @cite{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
+@example
+package API is
+ Count : Integer := 0;
+ ...
+ -- Remainder of the package omitted.
+end API;
+@end example
+@end quotation
-@geindex -s (gnatfind)
+After producing a DLL containing package @code{API}, the spec that
+must be used to import @code{API.Count} from Ada code outside of the
+DLL is:
+@quotation
-@table @asis
+@example
+package API is
+ Count : Integer;
+ pragma Import (DLL, Count);
+end API;
+@end example
+@end quotation
-@item @code{s}
+@menu
+* Creating the Definition File::
+* Using gnatdll::
-If this switch is set, then @cite{gnatfind} will output the content
-of the Ada source file lines were the entity was found.
-@end table
+@end menu
-@geindex -t (gnatfind)
+@node Creating the Definition File,Using gnatdll,,Creating a Spec for Ada DLLs
+@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
-@table @asis
+The definition file is the last file needed to build the DLL. It lists
+the exported symbols. As an example, the definition file for a DLL
+containing only package @code{API} (where all the entities are exported
+with a @code{C} calling convention) is:
-@item @code{t}
+@quotation
-If this switch is set, then @cite{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
+@example
+EXPORTS
+ count
+ factorial
+ finalize_api
+ initialize_api
+@end example
+@end quotation
-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}.
+If the @code{C} calling convention is missing from package @code{API},
+then the definition file contains the mangled Ada names of the above
+entities, which in this case are:
-As stated previously, gnatfind will search in every directory in the
-search path. You can force it to look only in the current directory if
-you specify @cite{*} at the end of the command line.
+@quotation
-@node Project 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 project-files-for-gnatxref-and-gnatfind}@anchor{1e2}@anchor{gnat_ugn/gnat_utility_programs id12}@anchor{1e3}
-@subsection Project Files for @emph{gnatxref} and @emph{gnatfind}
+@example
+EXPORTS
+ api__count
+ api__factorial
+ api__finalize_api
+ api__initialize_api
+@end example
+@end quotation
+@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs
+@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{1e3}@anchor{gnat_ugn/platform_specific_information id31}@anchor{1f5}
+@subsubsection Using @code{gnatdll}
-Project files allow a programmer to specify how to compile its
-application, where to find sources, etc. These files are used
-primarily by GPS, but they can also be used
-by the two tools @cite{gnatxref} and @cite{gnatfind}.
-A project file name must end with @code{.gpr}. If a single one is
-present in the current directory, then @cite{gnatxref} and @cite{gnatfind} will
-extract the information from it. If multiple project files are found, none of
-them is read, and you have to use the @code{-p} switch to specify the one
-you want to use.
+@geindex gnatdll
-The following lines can be included, even though most of them have default
-values which can be used in most cases.
-The lines can be entered in any order in the file.
-Except for @code{src_dir} and @code{obj_dir}, you can only have one instance of
-each line. If you have multiple instances, only the last one is taken into
-account.
+@code{gnatdll} is a tool to automate the DLL build process once all the Ada
+and non-Ada sources that make up your DLL have been compiled.
+@code{gnatdll} is actually in charge of two distinct tasks: build the
+static import library for the DLL and the actual DLL. The form of the
+@code{gnatdll} command is
+@quotation
-@itemize *
+@example
+$ gnatdll [ switches ] list-of-files [ -largs opts ]
+@end example
+@end quotation
-@item
+where @code{list-of-files} is a list of ALI and object files. The object
+file list must be the exact list of objects corresponding to the non-Ada
+sources whose services are to be included in the DLL. The ALI file list
+must be the exact list of ALI files for the corresponding Ada sources
+whose services are to be included in the DLL. If @code{list-of-files} is
+missing, only the static import library is generated.
-@table @asis
+You may specify any of the following switches to @code{gnatdll}:
-@item @emph{src_dir=DIR}
+@quotation
-[default: @cite{"./"}].
-Specifies a directory where to look for source files. Multiple @cite{src_dir}
-lines can be specified and they will be searched in the order they
-are specified.
-@end table
+@geindex -a (gnatdll)
+@end quotation
-@item
@table @asis
-@item @emph{obj_dir=DIR}
-
-[default: @cite{"./"}].
-Specifies a directory where to look for object and library files. Multiple
-@cite{obj_dir} lines can be specified, and they will be searched in the order
-they are specified
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{comp_opt=SWITCHES}
-
-[default: @cite{""}].
-Creates a variable which can be referred to subsequently by using
-the @cite{$@{comp_opt@}} notation. This is intended to store the default
-switches given to @emph{gnatmake} and @emph{gcc}.
-@end table
+@item @code{-a[@emph{address}]}
-@item
+Build a non-relocatable DLL at @code{address}. If @code{address} is not
+specified the default address @code{0x11000000} will be used. By default,
+when this switch is missing, @code{gnatdll} builds relocatable DLL. We
+advise the reader to build relocatable DLL.
-@table @asis
+@geindex -b (gnatdll)
-@item @emph{bind_opt=SWITCHES}
+@item @code{-b @emph{address}}
-[default: @cite{""}].
-Creates a variable which can be referred to subsequently by using
-the @code{$@emph{bind_opt}} notation. This is intended to store the default
-switches given to @emph{gnatbind}.
-@end table
+Set the relocatable DLL base address. By default the address is
+@code{0x11000000}.
-@item
+@geindex -bargs (gnatdll)
-@table @asis
+@item @code{-bargs @emph{opts}}
-@item @emph{link_opt=SWITCHES}
+Binder options. Pass @code{opts} to the binder.
-[default: @cite{""}].
-Creates a variable which can be referred to subsequently by using
-the @code{$@emph{link_opt}} notation. This is intended to store the default
-switches given to @emph{gnatlink}.
-@end table
+@geindex -d (gnatdll)
-@item
+@item @code{-d @emph{dllfile}}
-@table @asis
+@code{dllfile} is the name of the DLL. This switch must be present for
+@code{gnatdll} to do anything. The name of the generated import library is
+obtained algorithmically from @code{dllfile} as shown in the following
+example: if @code{dllfile} is @code{xyz.dll}, the import library name is
+@code{libxyz.dll.a}. The name of the definition file to use (if not specified
+by option @code{-e}) is obtained algorithmically from @code{dllfile}
+as shown in the following example:
+if @code{dllfile} is @code{xyz.dll}, the definition
+file used is @code{xyz.def}.
-@item @emph{main=EXECUTABLE}
+@geindex -e (gnatdll)
-[default: @cite{""}].
-Specifies the name of the executable for the application. This variable can
-be referred to in the following lines by using the @code{@emph{$@{main}} notation.
-@end table
+@item @code{-e @emph{deffile}}
-@item
+@code{deffile} is the name of the definition file.
-@table @asis
+@geindex -g (gnatdll)
-@item @emph{comp_cmd=COMMAND}
+@item @code{-g}
-[default: @cite{"gcc -c -I$@{src_dir@} -g -gnatq"}].
-Specifies the command used to compile a single file in the application.
-@end table
+Generate debugging information. This information is stored in the object
+file and copied from there to the final DLL file by the linker,
+where it can be read by the debugger. You must use the
+@code{-g} switch if you plan on using the debugger or the symbolic
+stack traceback.
-@item
+@geindex -h (gnatdll)
-@table @asis
+@item @code{-h}
-@item @emph{make_cmd=COMMAND}
+Help mode. Displays @code{gnatdll} switch usage information.
-[default: @cite{"gnatmake $@{main@} -aI$@{src_dir@} -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} -bargs $@{bind_opt@} -largs $@{link_opt@}"}].
-Specifies the command used to recompile the whole application.
-@end table
+@geindex -I (gnatdll)
-@item
+@item @code{-I@emph{dir}}
-@table @asis
+Direct @code{gnatdll} to search the @code{dir} directory for source and
+object files needed to build the DLL.
+(@ref{73,,Search Paths and the Run-Time Library (RTL)}).
-@item @emph{run_cmd=COMMAND}
+@geindex -k (gnatdll)
-[default: @cite{"$@{main@}"}].
-Specifies the command used to run the application.
-@end table
+@item @code{-k}
-@item
+Removes the @code{@@@emph{nn}} suffix from the import library's exported
+names, but keeps them for the link names. You must specify this
+option if you want to use a @code{Stdcall} function in a DLL for which
+the @code{@@@emph{nn}} suffix has been removed. This is the case for most
+of the Windows NT DLL for example. This option has no effect when
+@code{-n} option is specified.
-@table @asis
+@geindex -l (gnatdll)
-@item @emph{debug_cmd=COMMAND}
+@item @code{-l @emph{file}}
-[default: @cite{"gdb $@{main@}"}].
-Specifies the command used to debug the application
-@end table
-@end itemize
+The list of ALI and object files used to build the DLL are listed in
+@code{file}, instead of being given in the command line. Each line in
+@code{file} contains the name of an ALI or object file.
-@emph{gnatxref} and @emph{gnatfind} only take into account the
-@cite{src_dir} and @cite{obj_dir} lines, and ignore the others.
+@geindex -n (gnatdll)
-@node Regular Expressions in gnatfind and gnatxref,Examples of gnatxref Usage,Project Files for gnatxref and gnatfind,The Cross-Referencing Tools gnatxref and gnatfind
-@anchor{gnat_ugn/gnat_utility_programs id13}@anchor{1e4}@anchor{gnat_ugn/gnat_utility_programs regular-expressions-in-gnatfind-and-gnatxref}@anchor{1e0}
-@subsection Regular Expressions in @cite{gnatfind} and @cite{gnatxref}
+@item @code{-n}
+No Import. Do not create the import library.
-As specified in the section about @emph{gnatfind}, the pattern can be a
-regular expression. Two kinds of regular expressions
-are recognized:
+@geindex -q (gnatdll)
+@item @code{-q}
-@itemize *
+Quiet mode. Do not display unnecessary messages.
-@item
+@geindex -v (gnatdll)
-@table @asis
+@item @code{-v}
-@item @emph{Globbing pattern}
+Verbose mode. Display extra information.
-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.
+@geindex -largs (gnatdll)
-Here is a more formal grammar:
+@item @code{-largs @emph{opts}}
-@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
+Linker options. Pass @code{opts} to the linker.
@end table
-@item
-
-@table @asis
+@subsubheading @code{gnatdll} Example
-@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}.
+As an example the command to build a relocatable DLL from @code{api.adb}
+once @code{api.adb} has been compiled and @code{api.def} created is
-The following is the form of a regular expression, expressed in same BNF
-style as is found in the Ada Reference Manual:
+@quotation
@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 ()[].*+?^
+$ gnatdll -d api.dll api.ali
@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{1dd}@anchor{gnat_ugn/gnat_utility_programs id14}@anchor{1e5}
-@subsection Examples of @cite{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{1e6}
-@subsubsection General Usage
-
-For the following examples, we will consider the following units:
+The above command creates two files: @code{libapi.dll.a} (the import
+library) and @code{api.dll} (the actual DLL). If you want to create
+only the DLL, just type:
@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;
+$ gnatdll -d api.dll -n api.ali
@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}
-@cite{gnatxref} generates cross-reference information for main.adb
-and every unit 'with'ed by main.adb.
-
-The output would be:
+Alternatively if you want to create just the import library, type:
@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
+$ gnatdll -d api.dll
@end example
@end quotation
-This shows that the entity @cite{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.
+@subsubheading @code{gnatdll} behind the Scenes
-The entity @cite{Print} is declared in bar.ads, line 2, column 15 and it
-is referenced in main.adb, line 6 column 12 and line 7 column 12.
-@item
-@code{gnatxref package1.adb package2.ads}
-@cite{gnatxref} will generates cross-reference information for
-package1.adb, package2.ads and any other package 'with'ed by any
-of these.
-@end itemize
-@end quotation
+This section details the steps involved in creating a DLL. @code{gnatdll}
+does these steps for you. Unless you are interested in understanding what
+goes on behind the scenes, you should skip this section.
-@node Using gnatxref with vi,,General Usage,Examples of gnatxref Usage
-@anchor{gnat_ugn/gnat_utility_programs using-gnatxref-with-vi}@anchor{1e7}
-@subsubsection Using gnatxref with vi
+We use the previous example of a DLL containing the Ada package @code{API},
+to illustrate the steps necessary to build a DLL. The starting point is a
+set of objects that will make up the DLL and the corresponding ALI
+files. In the case of this example this means that @code{api.o} and
+@code{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does
+the following:
-@cite{gnatxref} can generate a tags file output, which can be used
-directly from @emph{vi}. Note that the standard version of @emph{vi}
-will not work properly with overloaded symbols. Consider using another
-free implementation of @emph{vi}, such as @emph{vim}.
+@itemize *
-@quotation
+@item
+@code{gnatdll} builds the base file (@code{api.base}). A base file gives
+the information necessary to generate relocation information for the
+DLL.
@example
-$ gnatxref -v gnatfind.adb > tags
+$ gnatbind -n api
+$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
@end example
-@end quotation
-The following command will generate the tags file for @cite{gnatfind} itself
-(if the sources are in the search path!):
+In addition to the base file, the @code{gnatlink} command generates an
+output file @code{api.jnk} which can be discarded. The @code{-mdll} switch
+asks @code{gnatlink} to generate the routines @code{DllMain} and
+@code{DllMainCRTStartup} that are called by the Windows loader when the DLL
+is loaded into memory.
-@quotation
+@item
+@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.
@example
-$ gnatxref -v gnatfind.adb > tags
+$ dlltool --dllname api.dll --def api.def --base-file api.base \\
+ --output-exp api.exp
@end example
-@end quotation
-
-From @emph{vi}, you can then use the command @code{:tag @emph{entity}}
-(replacing @cite{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{1e8}@anchor{gnat_ugn/gnat_utility_programs examples-of-gnatfind-usage}@anchor{1e1}
-@subsection Examples of @cite{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
+@code{gnatdll} builds the base file using the new export table. Note that
+@code{gnatbind} must be called once again since the binder generated file
+has been deleted during the previous call to @code{gnatlink}.
@example
-directory/main.ads:106:14: xyz <= declaration
-directory/main.adb:24:10: xyz <= body
-directory/foo.ads:45:23: xyz <= declaration
+$ gnatbind -n api
+$ gnatlink api -o api.jnk api.exp -mdll
+ -Wl,--base-file,api.base
@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 @cite{gnatfind} will
-display the content of the Ada source file lines.
-
-The output will look like:
+@code{gnatdll} builds the new export table using the new base file and
+generates the DLL import library @code{libAPI.dll.a}.
@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;
+$ dlltool --dllname api.dll --def api.def --base-file api.base \\
+ --output-exp api.exp --output-lib libAPI.a
@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.
+Finally @code{gnatdll} builds the relocatable DLL using the final export
+table.
-The column has to be the beginning of the identifier, and should not
-point to any character in the middle of the identifier.
+@example
+$ gnatbind -n api
+$ gnatlink api api.exp -o api.dll -mdll
+@end example
@end itemize
+@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{1f6}
+@subsubheading Using @code{dlltool}
-@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{25}@anchor{gnat_ugn/gnat_utility_programs id16}@anchor{1e9}
-@section The Ada to HTML Converter @cite{gnathtml}
-
-
-@geindex gnathtml
-
-@emph{gnathtml} is a Perl script that allows Ada source files to be browsed using
-standard Web browsers. For installation information, see @ref{1ea,,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 @emph{-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{1eb}@anchor{gnat_ugn/gnat_utility_programs id17}@anchor{1ec}
-@subsection Invoking @emph{gnathtml}
-
-The command line is as follows:
+@code{dlltool} is the low-level tool used by @code{gnatdll} to build
+DLLs and static import libraries. This section summarizes the most
+common @code{dlltool} switches. The form of the @code{dlltool} command
+is
@quotation
@example
-$ perl gnathtml.pl [`switches`] `ada-files`
+$ dlltool [`switches`]
@end example
@end quotation
-You can specify as many Ada files as you want. @cite{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.
+@code{dlltool} switches include:
-The following switches are available:
-
-@geindex -83 (gnathtml)
+@geindex --base-file (dlltool)
@table @asis
-@item @code{83}
+@item @code{--base-file @emph{basefile}}
-Only the Ada 83 subset of keywords will be highlighted.
+Read the base file @code{basefile} generated by the linker. This switch
+is used to create a relocatable DLL.
@end table
-@geindex -cc (gnathtml)
+@geindex --def (dlltool)
@table @asis
-@item @code{cc @emph{color}}
+@item @code{--def @emph{deffile}}
-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.
+Read the definition file.
@end table
-@geindex -d (gnathtml)
+@geindex --dllname (dlltool)
@table @asis
-@item @code{d}
+@item @code{--dllname @emph{name}}
-If the Ada files depend on some other files (for instance through
-@cite{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.
+Gives the name of the DLL. This switch is used to embed the name of the
+DLL in the static import library generated by @code{dlltool} with switch
+@code{--output-lib}.
@end table
-@geindex -D (gnathtml)
+@geindex -k (dlltool)
@table @asis
-@item @code{D}
+@item @code{-k}
-This command is the same as @emph{-d} above, but @emph{gnathtml} will
-also look for files in the run-time library, and generate html files for them.
+Kill @code{@@@emph{nn}} from exported names
+(@ref{1cf,,Windows Calling Conventions}
+for a discussion about @code{Stdcall}-style symbols.
@end table
-@geindex -ext (gnathtml)
+@geindex --help (dlltool)
@table @asis
-@item @code{ext @emph{extension}}
+@item @code{--help}
-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}.
+Prints the @code{dlltool} switches with a concise description.
@end table
-@geindex -f (gnathtml)
+@geindex --output-exp (dlltool)
@table @asis
-@item @code{f}
+@item @code{--output-exp @emph{exportfile}}
-By default, gnathtml will generate html links only for global entities
-('with'ed units, global variables and types,...). If you specify
-@emph{-f} on the command line, then links will be generated for local
-entities too.
+Generate an export file @code{exportfile}. The export file contains the
+export table (list of symbols in the DLL) and is used to create the DLL.
@end table
-@geindex -l (gnathtml)
+@geindex --output-lib (dlltool)
@table @asis
-@item @code{l @emph{number}}
+@item @code{--output-lib @emph{libfile}}
-If this switch is provided and @cite{number} is not 0, then
-@cite{gnathtml} will number the html files every @cite{number} line.
+Generate a static import library @code{libfile}.
@end table
-@geindex -I (gnathtml)
+@geindex -v (dlltool)
@table @asis
-@item @code{I @emph{dir}}
+@item @code{-v}
-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.
+Verbose mode.
@end table
-@geindex -o (gnathtml)
+@geindex --as (dlltool)
@table @asis
-@item @code{o @emph{dir}}
+@item @code{--as @emph{assembler-name}}
-Specify the output directory for html files. By default, gnathtml will
-saved the generated html files in a subdirectory named @code{html/}.
+Use @code{assembler-name} as the assembler. The default is @code{as}.
@end table
-@geindex -p (gnathtml)
-
+@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{1f7}@anchor{gnat_ugn/platform_specific_information id32}@anchor{1f8}
+@subsubsection GNAT and Windows Resources
-@table @asis
-@item @code{p @emph{file}}
+@geindex Resources
+@geindex windows
-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.
+Resources are an easy way to add Windows specific objects to your
+application. The objects that can be added as resources include:
-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)
+@itemize *
+@item
+menus
-@table @asis
+@item
+accelerators
-@item @code{sc @emph{color}}
+@item
+dialog boxes
-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
+@item
+string tables
-@geindex -t (gnathtml)
+@item
+bitmaps
+@item
+cursors
-@table @asis
+@item
+icons
-@item @code{t @emph{file}}
+@item
+fonts
-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
+@item
+version information
+@end itemize
-@node Installing gnathtml,,Invoking gnathtml,The Ada to HTML Converter gnathtml
-@anchor{gnat_ugn/gnat_utility_programs installing-gnathtml}@anchor{1ea}@anchor{gnat_ugn/gnat_utility_programs id18}@anchor{1ed}
-@subsection Installing @cite{gnathtml}
+For example, a version information resource can be defined as follow and
+embedded into an executable or DLL:
-
-@cite{Perl} needs to be installed on your machine to run this script.
-@cite{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
-@cite{gnathtml}, to explicitly specify where Perl
-is located. The syntax of this line is:
+A version information resource can be used to embed information into an
+executable or a DLL. These information can be viewed using the file properties
+from the Windows Explorer. Here is an example of a version information
+resource:
@quotation
@example
-#!full_path_name_to_perl
-@end example
-@end quotation
-
-Alternatively, you may run the script using the following command line:
-
-@quotation
+1 VERSIONINFO
+FILEVERSION 1,0,0,0
+PRODUCTVERSION 1,0,0,0
+BEGIN
+ BLOCK "StringFileInfo"
+ BEGIN
+ BLOCK "080904E4"
+ BEGIN
+ VALUE "CompanyName", "My Company Name"
+ VALUE "FileDescription", "My application"
+ VALUE "FileVersion", "1.0"
+ VALUE "InternalName", "my_app"
+ VALUE "LegalCopyright", "My Name"
+ VALUE "OriginalFilename", "my_app.exe"
+ VALUE "ProductName", "My App"
+ VALUE "ProductVersion", "1.0"
+ END
+ END
-@example
-$ perl gnathtml.pl [`switches`] `files`
+ BLOCK "VarFileInfo"
+ BEGIN
+ VALUE "Translation", 0x809, 1252
+ END
+END
@end example
@end quotation
-@c -- +---------------------------------------------------------------------+
+The value @code{0809} (langID) is for the U.K English language and
+@code{04E4} (charsetID), which is equal to @code{1252} decimal, for
+multilingual.
-@c -- | The following sections are present only in the PRO and GPL editions |
+This section explains how to build, compile and use resources. Note that this
+section does not cover all resource objects, for a complete description see
+the corresponding Microsoft documentation.
-@c -- +---------------------------------------------------------------------+
+@menu
+* Building Resources::
+* Compiling Resources::
+* Using Resources::
+@end menu
+@node Building Resources,Compiling Resources,,GNAT and Windows Resources
+@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{1f9}@anchor{gnat_ugn/platform_specific_information id33}@anchor{1fa}
+@subsubsection Building Resources
+@geindex Resources
+@geindex building
+A resource file is an ASCII file. By convention resource files have an
+@code{.rc} extension.
+The easiest way to build a resource file is to use Microsoft tools
+such as @code{imagedit.exe} to build bitmaps, icons and cursors and
+@code{dlgedit.exe} to build dialogs.
+It is always possible to build an @code{.rc} file yourself by writing a
+resource script.
+It is not our objective to explain how to write a resource file. A
+complete description of the resource script language can be found in the
+Microsoft documentation.
-@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
+@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources
+@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{1fb}@anchor{gnat_ugn/platform_specific_information id34}@anchor{1fc}
+@subsubsection Compiling Resources
-@node GNAT and Program Execution,Platform-Specific Information,GNAT Utility Programs,Top
-@anchor{gnat_ugn/gnat_and_program_execution gnat-and-program-execution}@anchor{e}@anchor{gnat_ugn/gnat_and_program_execution doc}@anchor{1ee}@anchor{gnat_ugn/gnat_and_program_execution id1}@anchor{1ef}
-@chapter GNAT and Program Execution
+@geindex rc
-This chapter covers several topics:
+@geindex windres
+@geindex Resources
+@geindex compiling
-@itemize *
+This section describes how to build a GNAT-compatible (COFF) object file
+containing the resources. This is done using the Resource Compiler
+@code{windres} as follows:
-@item
-@ref{1f0,,Running and Debugging Ada Programs}
+@quotation
-@item
-@ref{1f1,,Code Coverage and Profiling}
+@example
+$ windres -i myres.rc -o myres.o
+@end example
+@end quotation
-@item
-@ref{1f2,,Improving Performance}
+By default @code{windres} will run @code{gcc} to preprocess the @code{.rc}
+file. You can specify an alternate preprocessor (usually named
+@code{cpp.exe}) using the @code{windres} @code{--preprocessor}
+parameter. A list of all possible options may be obtained by entering
+the command @code{windres} @code{--help}.
-@item
-@ref{1f3,,Overflow Check Handling in GNAT}
+It is also possible to use the Microsoft resource compiler @code{rc.exe}
+to produce a @code{.res} file (binary resource file). See the
+corresponding Microsoft documentation for further details. In this case
+you need to use @code{windres} to translate the @code{.res} file to a
+GNAT-compatible object file as follows:
-@item
-@ref{1f4,,Performing Dimensionality Analysis in GNAT}
+@quotation
-@item
-@ref{1f5,,Stack Related Facilities}
+@example
+$ windres -i myres.res -o myres.o
+@end example
+@end quotation
-@item
-@ref{1f6,,Memory Management Issues}
-@end itemize
+@node Using Resources,,Compiling Resources,GNAT and Windows Resources
+@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{1fd}@anchor{gnat_ugn/platform_specific_information id35}@anchor{1fe}
+@subsubsection Using Resources
-@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
+@geindex Resources
+@geindex using
-@node Running and Debugging Ada Programs,Code Coverage and Profiling,,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id2}@anchor{1f0}@anchor{gnat_ugn/gnat_and_program_execution running-and-debugging-ada-programs}@anchor{26}
-@section Running and Debugging Ada Programs
+To include the resource file in your program just add the
+GNAT-compatible object file for the resource(s) to the linker
+arguments. With @code{gnatmake} this is done by using the @code{-largs}
+option:
+@quotation
-@geindex Debugging
+@example
+$ gnatmake myprog -largs myres.o
+@end example
+@end quotation
-This section discusses how to debug Ada programs.
+@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{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
-An incorrect Ada program may be handled in three ways by the GNAT compiler:
+@geindex Microsoft Visual Studio
+@geindex use with GNAT DLLs
-@itemize *
+This section describes a common case of mixed GNAT/Microsoft Visual Studio
+application development, where the main program is developed using MSVS, and
+is linked with a DLL developed using GNAT. Such a mixed application should
+be developed following the general guidelines outlined above; below is the
+cookbook-style sequence of steps to follow:
-@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.
+@enumerate
@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::
+First develop and build the GNAT shared library using a library project
+(let's assume the project is @code{mylib.gpr}, producing the library @code{libmylib.dll}):
+@end enumerate
-@end menu
+@quotation
-@node The GNAT Debugger GDB,Running GDB,,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debugger-gdb}@anchor{1f7}@anchor{gnat_ugn/gnat_and_program_execution id3}@anchor{1f8}
-@subsection The GNAT Debugger GDB
+@example
+$ gprbuild -p mylib.gpr
+@end example
+@end quotation
-@cite{GDB} is a general purpose, platform-independent debugger that
-can be used to debug mixed-language programs compiled with @emph{gcc},
-and in particular is capable of debugging Ada programs compiled with
-GNAT. The latest versions of @cite{GDB} are Ada-aware and can handle
-complex Ada data structures.
+@enumerate 2
-See @cite{Debugging with GDB},
-for full details on the usage of @cite{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 @cite{GDB}.
+@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{1e1,,Creating Definition File Automatically}):
+@end enumerate
-When GNAT programs are compiled, the compiler optionally writes debugging
-information into the generated object file, including information on
-line numbers, and on declared types and variables. This information is
-separate from the generated code. It makes the object files considerably
-larger, but it does not add to the size of the actual executable that
-will be loaded into memory, and has no impact on run-time performance. The
-generation of debug information is triggered by the use of the
--g switch in the @emph{gcc} or @emph{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.
+@quotation
-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 @cite{GDB} automatically performs the necessary decoding.
+@example
+$ dlltool libmylib.dll -z libmylib.def --export-all-symbols
+@end example
+@end quotation
-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 @cite{GDB}, the
-debugger is activated. The image of the program is loaded, at which
-point it is ready to run. If a run command is given, then the program
-will run exactly as it would have if @cite{GDB} were not present. This
-is a crucial part of the @cite{GDB} design philosophy. @cite{GDB} is
-entirely non-intrusive until a breakpoint is encountered. If no
-breakpoint is ever hit, the program will run exactly as it would if no
-debugger were present. When a breakpoint is hit, @cite{GDB} accesses
-the debugging information and can respond to user commands to inspect
-variables, and more generally to report on the state of execution.
+@enumerate 3
-@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{1f9}@anchor{gnat_ugn/gnat_and_program_execution running-gdb}@anchor{1fa}
-@subsection Running GDB
+@item
+Make sure that MSVS command-line tools are accessible on the path.
+@item
+Create the Microsoft-style import library (see @ref{1e4,,MSVS-Style Import Library}):
+@end enumerate
-This section describes how to initiate the debugger.
+@quotation
-The debugger can be launched from a @cite{GPS} menu or
-directly from the command line. The description below covers the latter use.
-All the commands shown can be used in the @cite{GPS} debug console window,
-but there are usually more GUI-based ways to achieve the same effect.
+@example
+$ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib
+@end example
+@end quotation
-The command to run @cite{GDB} is
+If you are using a 64-bit toolchain, the above becomes...
@quotation
@example
-$ gdb program
+$ lib -machine:X64 -def:libmylib.def -out:libmylib.lib
@end example
@end quotation
-where @cite{program} is the name of the executable file. This
-activates the debugger and results in a prompt for debugger commands.
-The simplest command is simply @cite{run}, which causes the program to run
-exactly as if the debugger were not present. The following section
-describes some of the additional commands that can be given to @cite{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{1fb}@anchor{gnat_ugn/gnat_and_program_execution id5}@anchor{1fc}
-@subsection Introduction to GDB Commands
+@enumerate 5
+@item
+Build the C main
+@end enumerate
-@cite{GDB} contains a large repertoire of commands.
-See @cite{Debugging with GDB} for extensive documentation on the use
-of these commands, together with examples of their use. Furthermore,
-the command @emph{help} invoked from within GDB activates a simple help
-facility which summarizes the available commands and their options.
-In this section we summarize a few of the most commonly
-used commands to give an idea of what @cite{GDB} is about. You should create
-a simple program with debugging information and experiment with the use of
-these @cite{GDB} commands on the program as you read through the
-following section.
+@quotation
+@example
+$ cl /O2 /MD main.c libmylib.lib
+@end example
+@end quotation
-@itemize *
-@item
+@enumerate 6
-@table @asis
+@item
+Before running the executable, make sure you have set the PATH to the DLL,
+or copy the DLL into into the directory containing the .exe.
+@end enumerate
-@item @emph{set args `arguments`}
+@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{201}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{202}
+@subsubsection Debugging a DLL
-The @cite{arguments} list above is a list of arguments to be passed to
-the program on a subsequent run command, just as though the arguments
-had been entered on a normal invocation of the program. The @cite{set args}
-command is not needed if the program does not require arguments.
-@end table
-@item
+@geindex DLL debugging
-@table @asis
+Debugging a DLL is similar to debugging a standard program. But
+we have to deal with two different executable parts: the DLL and the
+program that uses it. We have the following four possibilities:
-@item @emph{run}
-The @cite{run} command causes execution of the program to start from
-the beginning. If the program is already running, that is to say if
-you are currently positioned at a breakpoint, then a prompt will ask
-for confirmation that you want to abandon the current execution and
-restart.
-@end table
+@itemize *
@item
+The program and the DLL are built with GCC/GNAT.
-@table @asis
-
-@item @emph{breakpoint `location`}
-
-The breakpoint command sets a breakpoint, that is to say a point at which
-execution will halt and @cite{GDB} will await further
-commands. @cite{location} is
-either a line number within a file, given in the format @cite{file:linenumber},
-or it is the name of a subprogram. If you request that a breakpoint be set on
-a subprogram that is overloaded, a prompt will ask you to specify on which of
-those subprograms you want to breakpoint. You can also
-specify that all of them should be breakpointed. If the program is run
-and execution encounters the breakpoint, then the program
-stops and @cite{GDB} signals that the breakpoint was encountered by
-printing the line of code before which the program is halted.
-@end table
+@item
+The program is built with foreign tools and the DLL is built with
+GCC/GNAT.
@item
+The program is built with GCC/GNAT and the DLL is built with
+foreign tools.
+@end itemize
-@table @asis
+In this section we address only cases one and two above.
+There is no point in trying to debug
+a DLL with GNU/GDB, if there is no GDB-compatible debugging
+information in it. To do so you must use a debugger compatible with the
+tools suite used to build the DLL.
-@item @emph{catch exception `name`}
+@menu
+* Program and DLL Both Built with GCC/GNAT::
+* Program Built with Foreign Tools and DLL Built with GCC/GNAT::
-This command causes the program execution to stop whenever exception
-@cite{name} is raised. If @cite{name} is omitted, then the execution is
-suspended when any exception is raised.
-@end table
+@end menu
-@item
+@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{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
-@table @asis
-@item @emph{print `expression`}
+This is the simplest case. Both the DLL and the program have @code{GDB}
+compatible debugging information. It is then possible to break anywhere in
+the process. Let's suppose here that the main procedure is named
+@code{ada_main} and that in the DLL there is an entry point named
+@code{ada_dll}.
-This will print the value of the given expression. Most simple
-Ada expression formats are properly handled by @cite{GDB}, so the expression
-can contain function calls, variables, operators, and attribute references.
-@end table
+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:
-@item
-@table @asis
+@itemize *
-@item @emph{continue}
+@item
+Launch @code{GDB} on the main program.
-Continues execution following a breakpoint, until the next breakpoint or the
-termination of the program.
-@end table
+@example
+$ gdb -nw ada_main
+@end example
@item
+Start the program and stop at the beginning of the main procedure
-@table @asis
-
-@item @emph{step}
+@example
+(gdb) start
+@end example
-Executes a single line after a breakpoint. If the next statement
-is a subprogram call, execution continues into (the first statement of)
-the called subprogram.
-@end table
+This step is required to be able to set a breakpoint inside the DLL. As long
+as the program is not run, the DLL is not loaded. This has the
+consequence that the DLL debugging information is also not loaded, so it is not
+possible to set a breakpoint in the DLL.
@item
+Set a breakpoint inside the DLL
-@table @asis
+@example
+(gdb) break ada_dll
+(gdb) cont
+@end example
+@end itemize
-@item @emph{next}
+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{14d,,Running and Debugging Ada Programs}).
-Executes a single line. If this line is a subprogram call, executes and
-returns from the call.
-@end table
+@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{205}@anchor{gnat_ugn/platform_specific_information id38}@anchor{206}
+@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT
-@item
-@table @asis
+In this case things are slightly more complex because it is not possible to
+start the main program and then break at the beginning to load the DLL and the
+associated DLL debugging information. It is not possible to break at the
+beginning of the program because there is no @code{GDB} debugging information,
+and therefore there is no direct way of getting initial control. This
+section addresses this issue by describing some methods that can be used
+to break somewhere in the DLL to debug it.
-@item @emph{list}
+First suppose that the main procedure is named @code{main} (this is for
+example some C code built with Microsoft Visual C) and that there is a
+DLL named @code{test.dll} containing an Ada entry point named
+@code{ada_dll}.
-Lists a few lines around the current source location. In practice, it
-is usually more convenient to have a separate edit window open with the
-relevant source file displayed. Successive applications of this command
-print subsequent lines. The command can be given an argument which is a
-line number, in which case it displays a few lines around the specified one.
-@end table
+The DLL (see @ref{1da,,Introduction to Dynamic Link Libraries (DLLs)}) must have
+been built with debugging information (see the GNAT @code{-g} option).
-@item
+@subsubheading Debugging the DLL Directly
-@table @asis
-@item @emph{backtrace}
-Displays a backtrace of the call chain. This command is typically
-used after a breakpoint has occurred, to examine the sequence of calls that
-leads to the current breakpoint. The display includes one line for each
-activation record (frame) corresponding to an active subprogram.
-@end table
+@itemize *
@item
+Find out the executable starting address
-@table @asis
+@example
+$ objdump --file-header main.exe
+@end example
-@item @emph{up}
+The starting address is reported on the last line. For example:
-At a breakpoint, @cite{GDB} can display the values of variables local
-to the current frame. The command @cite{up} can be used to
-examine the contents of other active frames, by moving the focus up
-the stack, that is to say from callee to caller, one frame at a time.
-@end table
+@example
+main.exe: file format pei-i386
+architecture: i386, flags 0x0000010a:
+EXEC_P, HAS_DEBUG, D_PAGED
+start address 0x00401010
+@end example
@item
+Launch the debugger on the executable.
-@table @asis
-
-@item @emph{down}
-
-Moves the focus of @cite{GDB} down from the frame currently being
-examined to the frame of its callee (the reverse of the previous command),
-@end table
+@example
+$ gdb main.exe
+@end example
@item
+Set a breakpoint at the starting address, and launch the program.
-@table @asis
-
-@item @emph{frame `n`}
+@example
+$ (gdb) break *0x00401010
+$ (gdb) run
+@end example
-Inspect the frame with the given number. The value 0 denotes the frame
-of the current breakpoint, that is to say the top of the call stack.
-@end table
+The program will stop at the given address.
@item
+Set a breakpoint on a DLL subroutine.
-@table @asis
-
-@item @emph{kill}
-
-Kills the child process in which the program is running under GDB.
-This may be useful for several purposes:
+@example
+(gdb) break ada_dll.adb:45
+@end example
+Or if you want to break using a symbol on the DLL, you need first to
+select the Ada language (language used by the DLL).
-@itemize *
+@example
+(gdb) set language ada
+(gdb) break ada_dll
+@end example
@item
-It allows you to recompile and relink your program, since on many systems
-you cannot regenerate an executable file while it is running in a process.
+Continue the program.
-@item
-You can run your program outside the debugger, on systems that do not
-permit executing a program outside GDB while breakpoints are set
-within GDB.
+@example
+(gdb) cont
+@end example
-@item
-It allows you to debug a core dump rather than a running process.
-@end itemize
-@end table
+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{14d,,Running and Debugging Ada Programs}).
@end itemize
-The above list is a very short introduction to the commands that
-@cite{GDB} provides. Important additional capabilities, including conditional
-breakpoints, the ability to execute command sequences on a breakpoint,
-the ability to debug at the machine instruction level and many other
-features are described in detail in @cite{Debugging with GDB}.
-Note that most commands can be abbreviated
-(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{1fd}@anchor{gnat_ugn/gnat_and_program_execution using-ada-expressions}@anchor{1fe}
-@subsection Using Ada Expressions
+It is also possible to debug the DLL by attaching to a running process.
+@subsubheading Attaching to a Running Process
-@geindex Ada expressions (in gdb)
-@cite{GDB} supports a fairly large subset of Ada expression syntax, with some
-extensions. The philosophy behind the design of this subset is
+@geindex DLL debugging
+@geindex attach to process
-@quotation
+With @code{GDB} it is always possible to debug a running process by
+attaching to it. It is possible to debug a DLL this way. The limitation
+of this approach is that the DLL must run long enough to perform the
+attach operation. It may be useful for instance to insert a time wasting
+loop in the code of the DLL to meet this criterion.
@itemize *
@item
-That @cite{GDB} should provide basic literals and access to operations for
-arithmetic, dereferencing, field selection, indexing, and subprogram calls,
-leaving more sophisticated computations to subprograms written into the
-program (which therefore may be called from @cite{GDB}).
+Launch the main program @code{main.exe}.
+
+@example
+$ main
+@end example
@item
-That type safety and strict adherence to Ada language restrictions
-are not particularly relevant in a debugging context.
+Use the Windows @emph{Task Manager} to find the process ID. Let's say
+that the process PID for @code{main.exe} is 208.
@item
-That brevity is important to the @cite{GDB} user.
-@end itemize
-@end quotation
+Launch gdb.
-Thus, for brevity, the debugger acts as if there were
-implicit @cite{with} and @cite{use} clauses in effect for all user-written
-packages, thus making it unnecessary to fully qualify most names with
-their packages, regardless of context. Where this causes ambiguity,
-@cite{GDB} asks the user's intent.
+@example
+$ gdb
+@end example
-For details on the supported Ada syntax, see @cite{Debugging with GDB}.
+@item
+Attach to the running process to be debugged.
-@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{1ff}@anchor{gnat_ugn/gnat_and_program_execution calling-user-defined-subprograms}@anchor{200}
-@subsection Calling User-Defined Subprograms
+@example
+(gdb) attach 208
+@end example
+@item
+Load the process debugging information.
-An important capability of @cite{GDB} is the ability to call user-defined
-subprograms while debugging. This is achieved simply by entering
-a subprogram call statement in the form:
+@example
+(gdb) symbol-file main.exe
+@end example
-@quotation
+@item
+Break somewhere in the DLL.
@example
-call subprogram-name (parameters)
+(gdb) break ada_dll
@end example
-@end quotation
-The keyword @cite{call} can be omitted in the normal case where the
-@cite{subprogram-name} does not coincide with any of the predefined
-@cite{GDB} commands.
+@item
+Continue process execution.
-The effect is to invoke the given subprogram, passing it the
-list of parameters that is supplied. The parameters can be expressions and
-can include variables from the program being debugged. The
-subprogram must be defined
-at the library level within your program, and @cite{GDB} will call the
-subprogram within the environment of your program execution (which
-means that the subprogram is free to access or even modify variables
-within your program).
-
-The most important use of this facility is in allowing the inclusion of
-debugging routines that are tailored to particular data structures
-in your program. Such debugging routines can be written to provide a suitably
-high-level description of an abstract type, rather than a low-level dump
-of its physical layout. After all, the standard
-@cite{GDB print} command only knows the physical layout of your
-types, not their abstract meaning. Debugging routines can provide information
-at the desired semantic level and are thus enormously useful.
-
-For example, when debugging GNAT itself, it is crucial to have access to
-the contents of the tree nodes used to represent the program internally.
-But tree nodes are represented simply by an integer value (which in turn
-is an index into a table of nodes).
-Using the @cite{print} command on a tree node would simply print this integer
-value, which is not very useful. But the PN routine (defined in file
-treepr.adb in the GNAT sources) takes a tree node as input, and displays
-a useful high level representation of the tree node, which includes the
-syntactic category of the node, its position in the source, the integers
-that denote descendant nodes and parent node, as well as varied
-semantic information. To study this example in more detail, you might want to
-look at the body of the PN procedure in the stated file.
-
-Another useful application of this capability is to deal with situations of
-complex data which are not handled suitably by GDB. For example, if you specify
-Convention Fortran for a multi-dimensional array, GDB does not know that
-the ordering of array elements has been switched and will not properly
-address the array elements. In such a case, instead of trying to print the
-elements directly from GDB, you can write a callable procedure that prints
-the elements in the desired format.
-
-@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{201}@anchor{gnat_ugn/gnat_and_program_execution id8}@anchor{202}
-@subsection Using the @emph{next} Command in a Function
-
-
-When you use the @cite{next} command in a function, the current source
-location will advance to the next statement as usual. A special case
-arises in the case of a @cite{return} statement.
+@example
+(gdb) cont
+@end example
+@end itemize
-Part of the code for a return statement is the 'epilogue' of the function.
-This is the code that returns to the caller. There is only one copy of
-this epilogue code, and it is typically associated with the last return
-statement in the function if there is more than one return. In some
-implementations, this epilogue is associated with the first statement
-of the function.
+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{14d,,Running and Debugging Ada Programs}.
-The result is that if you use the @cite{next} command from a return
-statement that is not the last return statement of the function you
-may see a strange apparent jump to the last return statement or to
-the start of the function. You should simply ignore this odd jump.
-The value returned is always that from the first return statement
-that was stepped through.
+@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{127}@anchor{gnat_ugn/platform_specific_information id39}@anchor{207}
+@subsubsection Setting Stack Size from @code{gnatlink}
-@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{203}@anchor{gnat_ugn/gnat_and_program_execution id9}@anchor{204}
-@subsection Stopping When Ada Exceptions Are Raised
+It is possible to specify the program stack size at link time. On modern
+versions of Windows, starting with XP, this is mostly useful to set the size of
+the main stack (environment task). The other task stacks are set with pragma
+Storage_Size or with the @emph{gnatbind -d} command.
-@geindex Exceptions (in gdb)
+Since older versions of Windows (2000, NT4, etc.) do not allow setting the
+reserve size of individual tasks, the link-time stack size applies to all
+tasks, and pragma Storage_Size has no effect.
+In particular, Stack Overflow checks are made against this
+link-time specified size.
-You can set catchpoints that stop the program execution when your program
-raises selected exceptions.
+This setting can be done with @code{gnatlink} using either of the following:
@itemize *
@item
+@code{-Xlinker} linker option
-@table @asis
-
-@item @emph{catch exception}
-
-Set a catchpoint that stops execution whenever (any task in the) program
-raises any exception.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{catch exception `name`}
-
-Set a catchpoint that stops execution whenever (any task in the) program
-raises the exception @cite{name}.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{catch exception unhandled}
+@example
+$ gnatlink hello -Xlinker --stack=0x10000,0x1000
+@end example
-Set a catchpoint that stops executing whenever (any task in the) program
-raises an exception for which there is no handler.
-@end table
+This sets the stack reserve size to 0x10000 bytes and the stack commit
+size to 0x1000 bytes.
@item
+@code{-Wl} linker option
-@table @asis
-
-@item @emph{info exceptions}, @emph{info exceptions `regexp`}
+@example
+$ gnatlink hello -Wl,--stack=0x1000000
+@end example
-The @cite{info exceptions} command permits the user to examine all defined
-exceptions within Ada programs. With a regular expression, @cite{regexp}, as
-argument, prints out only those exceptions whose name matches @cite{regexp}.
-@end table
+This sets the stack reserve size to 0x1000000 bytes. Note that with
+@code{-Wl} option it is not possible to set the stack commit size
+because the comma is a separator for this option.
@end itemize
-@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{205}@anchor{gnat_ugn/gnat_and_program_execution id10}@anchor{206}
-@subsection Ada Tasks
+@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{128}@anchor{gnat_ugn/platform_specific_information id40}@anchor{208}
+@subsubsection Setting Heap Size from @code{gnatlink}
-@cite{GDB} allows the following task-related commands:
+Under Windows systems, it is possible to specify the program heap size from
+@code{gnatlink} using either of the following:
@itemize *
@item
+@code{-Xlinker} linker option
-@table @asis
+@example
+$ gnatlink hello -Xlinker --heap=0x10000,0x1000
+@end example
-@item @emph{info tasks}
+This sets the heap reserve size to 0x10000 bytes and the heap commit
+size to 0x1000 bytes.
-This command shows a list of current Ada tasks, as in the following example:
+@item
+@code{-Wl} linker option
@example
-(gdb) info tasks
- ID TID P-ID Thread Pri State Name
- 1 8088000 0 807e000 15 Child Activation Wait main_task
- 2 80a4000 1 80ae000 15 Accept/Select Wait b
- 3 809a800 1 80a4800 15 Child Activation Wait a
-* 4 80ae800 3 80b8000 15 Running c
+$ gnatlink hello -Wl,--heap=0x1000000
@end example
-In this listing, the asterisk before the first task indicates it to be the
-currently running task. The first column lists the task ID that is used
-to refer to tasks in the following commands.
-@end table
+This sets the heap reserve size to 0x1000000 bytes. Note that with
+@code{-Wl} option it is not possible to set the heap commit size
+because the comma is a separator for this option.
@end itemize
-@geindex Breakpoints and tasks
-
-
-@itemize *
-
-@item
-@emph{break `linespec` task `taskid`}, @emph{break `linespec` task `taskid` if ...}
-
-@quotation
-
-These commands are like the @cite{break ... thread ...}.
-@cite{linespec} specifies source lines.
+@node Windows Specific Add-Ons,,Mixed-Language Programming on Windows,Microsoft Windows Topics
+@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
-Use the qualifier @code{task @emph{taskid}} with a breakpoint command
-to specify that you only want @cite{GDB} to stop the program when a
-particular Ada task reaches this breakpoint. @cite{taskid} is one of the
-numeric task identifiers assigned by @cite{GDB}, shown in the first
-column of the @code{info tasks} display.
-If you do not specify @code{task @emph{taskid}} when you set a
-breakpoint, the breakpoint applies to @emph{all} tasks of your
-program.
+This section describes the Windows specific add-ons.
-You can use the @cite{task} qualifier on conditional breakpoints as
-well; in this case, place @code{task @emph{taskid}} before the
-breakpoint condition (before the @cite{if}).
-@end quotation
-@end itemize
+@menu
+* Win32Ada::
+* wPOSIX::
-@geindex Task switching (in gdb)
+@end menu
+@node Win32Ada,wPOSIX,,Windows Specific Add-Ons
+@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{20b}@anchor{gnat_ugn/platform_specific_information id41}@anchor{20c}
+@subsubsection Win32Ada
-@itemize *
-@item
-@emph{task `taskno`}
+Win32Ada is a binding for the Microsoft Win32 API. This binding can be
+easily installed from the provided installer. To use the Win32Ada
+binding you need to use a project file, and adding a single with_clause
+will give you full access to the Win32Ada binding sources and ensure
+that the proper libraries are passed to the linker.
@quotation
-This command allows switching to the task referred by @cite{taskno}. In
-particular, this allows browsing of the backtrace of the specified
-task. It is advisable to switch back to the original task before
-continuing execution otherwise the scheduling of the program may be
-perturbed.
+@example
+with "win32ada";
+project P is
+ for Sources use ...;
+end P;
+@end example
@end quotation
-@end itemize
-For more detailed information on the tasking support,
-see @cite{Debugging with GDB}.
+To build the application you just need to call gprbuild for the
+application's project, here p.gpr:
-@geindex Debugging Generic Units
+@quotation
-@geindex Generics
+@example
+gprbuild p.gpr
+@end example
+@end quotation
-@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{207}@anchor{gnat_ugn/gnat_and_program_execution id11}@anchor{208}
-@subsection Debugging Generic Units
+@node wPOSIX,,Win32Ada,Windows Specific Add-Ons
+@anchor{gnat_ugn/platform_specific_information id42}@anchor{20d}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{20e}
+@subsubsection wPOSIX
-GNAT always uses code expansion for generic instantiation. This means that
-each time an instantiation occurs, a complete copy of the original code is
-made, with appropriate substitutions of formals by actuals.
+wPOSIX is a minimal POSIX binding whose goal is to help with building
+cross-platforms applications. This binding is not complete though, as
+the Win32 API does not provide the necessary support for all POSIX APIs.
-It is not possible to refer to the original generic entities in
-@cite{GDB}, but it is always possible to debug a particular instance of
-a generic, by using the appropriate expanded names. For example, if we have
+To use the wPOSIX binding you need to use a project file, and adding
+a single with_clause will give you full access to the wPOSIX binding
+sources and ensure that the proper libraries are passed to the linker.
@quotation
@example
-procedure g is
-
- generic package k is
- procedure kp (v1 : in out integer);
- end k;
-
- package body k is
- procedure kp (v1 : in out integer) is
- begin
- v1 := v1 + 1;
- end kp;
- end k;
-
- package k1 is new k;
- package k2 is new k;
-
- var : integer := 1;
-
-begin
- k1.kp (var);
- k2.kp (var);
- k1.kp (var);
- k2.kp (var);
-end;
+with "wposix";
+project P is
+ for Sources use ...;
+end P;
@end example
@end quotation
-Then to break on a call to procedure kp in the k2 instance, simply
-use the command:
+To build the application you just need to call gprbuild for the
+application's project, here p.gpr:
@quotation
@example
-(gdb) break g.k2.kp
+gprbuild p.gpr
@end example
@end quotation
-When the breakpoint occurs, you can step through the code of the
-instance in the normal manner and examine the values of local variables, as for
-other units.
+@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information
+@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{20f}@anchor{gnat_ugn/platform_specific_information id43}@anchor{210}
+@section Mac OS Topics
-@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{209}@anchor{gnat_ugn/gnat_and_program_execution id12}@anchor{20a}
-@subsection Remote Debugging with gdbserver
+@geindex OS X
+This section describes topics that are specific to Apple's OS X
+platform.
-On platforms where gdbserver is supported, it is possible to use this tool
-to debug your application remotely. This can be useful in situations
-where the program needs to be run on a target host that is different
-from the host used for development, particularly when the target has
-a limited amount of resources (either CPU and/or memory).
+@menu
+* Codesigning the Debugger::
-To do so, start your program using gdbserver on the target machine.
-gdbserver then automatically suspends the execution of your program
-at its entry point, waiting for a debugger to connect to it. The
-following commands starts an application and tells gdbserver to
-wait for a connection with the debugger on localhost port 4444.
-
-@quotation
+@end menu
-@example
-$ gdbserver localhost:4444 program
-Process program created; pid = 5685
-Listening on port 4444
-@end example
-@end quotation
+@node Codesigning the Debugger,,,Mac OS Topics
+@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{211}
+@subsection Codesigning the Debugger
-Once gdbserver has started listening, we can tell the debugger to establish
-a connection with this gdbserver, and then start the same debugging session
-as if the program was being debugged on the same host, directly under
-the control of GDB.
-@quotation
+The Darwin Kernel requires the debugger to have special permissions
+before it is allowed to control other processes. These permissions
+are granted by codesigning the GDB executable. Without these
+permissions, the debugger will report error messages such as:
@example
-$ gdb program
-(gdb) target remote targethost:4444
-Remote debugging using targethost:4444
-0x00007f29936d0af0 in ?? () from /lib64/ld-linux-x86-64.so.
-(gdb) b foo.adb:3
-Breakpoint 1 at 0x401f0c: file foo.adb, line 3.
-(gdb) continue
-Continuing.
-
-Breakpoint 1, foo () at foo.adb:4
-4 end foo;
+Starting program: /x/y/foo
+Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5).
+(please check gdb is codesigned - see taskgated(8))
@end example
-@end quotation
-
-It is also possible to use gdbserver to attach to an already running
-program, in which case the execution of that program is simply suspended
-until the connection between the debugger and gdbserver is established.
-
-For more information on how to use gdbserver, see the @emph{Using the gdbserver Program}
-section in @cite{Debugging with GDB}.
-GNAT provides support for gdbserver on x86-linux, x86-windows and x86_64-linux.
-
-@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{20b}@anchor{gnat_ugn/gnat_and_program_execution id13}@anchor{20c}
-@subsection GNAT Abnormal Termination or Failure to Terminate
-
-
-When presented with programs that contain serious errors in syntax
-or semantics,
-GNAT may on rare occasions experience problems in operation, such
-as aborting with a
-segmentation fault or illegal memory access, raising an internal
-exception, terminating abnormally, or failing to terminate at all.
-In such cases, you can activate
-various features of GNAT that can help you pinpoint the construct in your
-program that is the likely source of the problem.
-The following strategies are presented in increasing order of
-difficulty, corresponding to your experience in using GNAT and your
-familiarity with compiler internals.
+Codesigning requires a certificate. The following procedure explains
+how to create one:
@itemize *
@item
-Run @emph{gcc} with the @emph{-gnatf}. This first
-switch causes all errors on a given line to be reported. In its absence,
-only the first error on a line is displayed.
-
-The @emph{-gnatdO} switch causes errors to be displayed as soon as they
-are encountered, rather than after compilation is terminated. If GNAT
-terminates prematurely or goes into an infinite loop, the last error
-message displayed may help to pinpoint the culprit.
-
-@item
-Run @emph{gcc} with the @emph{-v (verbose)} switch. In this
-mode, @emph{gcc} produces ongoing information about the progress of the
-compilation and provides the name of each procedure as code is
-generated. This switch allows you to find which Ada procedure was being
-compiled when it encountered a code generation problem.
-@end itemize
-
-@geindex -gnatdc switch
-
-
-@itemize *
+Start the Keychain Access application (in
+/Applications/Utilities/Keychain Access.app)
@item
-Run @emph{gcc} with the @emph{-gnatdc} switch. This is a GNAT specific
-switch that does for the front-end what @emph{-v} does
-for the back end. The system prints the name of each unit,
-either a compilation unit or nested unit, as it is being analyzed.
+Select the Keychain Access -> Certificate Assistant ->
+Create a Certificate... menu
@item
-Finally, you can start
-@cite{gdb} directly on the @cite{gnat1} executable. @cite{gnat1} is the
-front-end of GNAT, and can be run independently (normally it is just
-called from @emph{gcc}). You can use @cite{gdb} on @cite{gnat1} as you
-would on a C program (but @ref{1f7,,The GNAT Debugger GDB} for caveats). The
-@cite{where} command is the first line of attack; the variable
-@cite{lineno} (seen by @cite{print lineno}), used by the second phase of
-@cite{gnat1} and by the @emph{gcc} backend, indicates the source line at
-which the execution stopped, and @cite{input_file name} indicates the name of
-the source file.
-@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{20d}@anchor{gnat_ugn/gnat_and_program_execution id14}@anchor{20e}
-@subsection Naming Conventions for GNAT Source Files
-
-
-In order to examine the workings of the GNAT system, the following
-brief description of its organization may be helpful:
+Then:
@itemize *
@item
-Files with prefix @code{sc} contain the lexical scanner.
-
-@item
-All files prefixed with @code{par} are components of the parser. The
-numbers correspond to chapters of the Ada Reference Manual. For example,
-parsing of select statements can be found in @code{par-ch9.adb}.
+Choose a name for the new certificate (this procedure will use
+"gdb-cert" as an example)
@item
-All files prefixed with @code{sem} perform semantic analysis. The
-numbers correspond to chapters of the Ada standard. For example, all
-issues involving context clauses can be found in @code{sem_ch10.adb}. In
-addition, some features of the language require sufficient special processing
-to justify their own semantic files: sem_aggr for aggregates, sem_disp for
-dynamic dispatching, etc.
+Set "Identity Type" to "Self Signed Root"
@item
-All files prefixed with @code{exp} perform normalization and
-expansion of the intermediate representation (abstract syntax tree, or AST).
-these files use the same numbering scheme as the parser and semantics files.
-For example, the construction of record initialization procedures is done in
-@code{exp_ch3.adb}.
+Set "Certificate Type" to "Code Signing"
@item
-The files prefixed with @code{bind} implement the binder, which
-verifies the consistency of the compilation, determines an order of
-elaboration, and generates the bind file.
+Activate the "Let me override defaults" option
+@end itemize
@item
-The files @code{atree.ads} and @code{atree.adb} detail the low-level
-data structures used by the front-end.
+Click several times on "Continue" until the "Specify a Location
+For The Certificate" screen appears, then set "Keychain" to "System"
@item
-The files @code{sinfo.ads} and @code{sinfo.adb} detail the structure of
-the abstract syntax tree as produced by the parser.
+Click on "Continue" until the certificate is created
@item
-The files @code{einfo.ads} and @code{einfo.adb} detail the attributes of
-all entities, computed during semantic analysis.
+Finally, in the view, double-click on the new certificate,
+and set "When using this certificate" to "Always Trust"
@item
-Library management issues are dealt with in files with prefix
-@code{lib}.
+Exit the Keychain Access application and restart the computer
+(this is unfortunately required)
+@end itemize
-@geindex Annex A (in Ada Reference Manual)
+Once a certificate has been created, the debugger can be codesigned
+as follow. In a Terminal, run the following command:
-@item
-Ada files with the prefix @code{a-} are children of @cite{Ada}, as
-defined in Annex A.
+@quotation
-@geindex Annex B (in Ada reference Manual)
+@example
+$ codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb
+@end example
+@end quotation
-@item
-Files with prefix @code{i-} are children of @cite{Interfaces}, as
-defined in Annex B.
+where "gdb-cert" should be replaced by the actual certificate
+name chosen above, and <gnat_install_prefix> should be replaced by
+the location where you installed GNAT. Also, be sure that users are
+in the Unix group @code{_developer}.
-@geindex System (package in Ada Reference Manual)
+@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{212}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{213}
+@chapter Example of Binder Output File
-@item
-Files with prefix @code{s-} are children of @cite{System}. This includes
-both language-defined children and GNAT run-time routines.
-@geindex GNAT (package)
+@geindex Binder output (example)
-@item
-Files with prefix @code{g-} are children of @cite{GNAT}. These are useful
-general-purpose packages, fully documented in their specs. All
-the other @code{.c} files are modifications of common @emph{gcc} files.
-@end itemize
+This Appendix displays the source code for the output file
+generated by @emph{gnatbind} for a simple 'Hello World' program.
+Comments have been added for clarification purposes.
-@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{20f}@anchor{gnat_ugn/gnat_and_program_execution getting-internal-debugging-information}@anchor{210}
-@subsection Getting Internal Debugging Information
+@example
+-- The package is called Ada_Main unless this name is actually used
+-- as a unit name in the partition, in which case some other unique
+-- name is used.
+pragma Ada_95;
+with System;
+package ada_main is
+ pragma Warnings (Off);
-Most compilers have internal debugging switches and modes. GNAT
-does also, except GNAT internal debugging switches and modes are not
-secret. A summary and full description of all the compiler and binder
-debug flags are in the file @code{debug.adb}. You must obtain the
-sources of the compiler to see the full detailed effects of these flags.
+ -- The main program saves the parameters (argument count,
+ -- argument values, environment pointer) in global variables
+ -- for later access by other units including
+ -- Ada.Command_Line.
-The switches that print the source of the program (reconstructed from
-the internal tree) are of general interest for user programs, as are the
-options to print
-the full internal tree, and the entity table (the symbol table
-information). The reconstructed source provides a readable version of the
-program after the front-end has completed analysis and expansion,
-and is useful when studying the performance of specific constructs.
-For example, constraint checks are indicated, complex aggregates
-are replaced with loops and assignments, and tasking primitives
-are replaced with run-time calls.
+ gnat_argc : Integer;
+ gnat_argv : System.Address;
+ gnat_envp : System.Address;
-@geindex traceback
+ -- The actual variables are stored in a library routine. This
+ -- is useful for some shared library situations, where there
+ -- are problems if variables are not in the library.
-@geindex stack traceback
+ pragma Import (C, gnat_argc);
+ pragma Import (C, gnat_argv);
+ pragma Import (C, gnat_envp);
-@geindex stack unwinding
+ -- The exit status is similarly an external location
-@node Stack Traceback,,Getting Internal Debugging Information,Running and Debugging Ada Programs
-@anchor{gnat_ugn/gnat_and_program_execution stack-traceback}@anchor{211}@anchor{gnat_ugn/gnat_and_program_execution id16}@anchor{212}
-@subsection Stack Traceback
+ gnat_exit_status : Integer;
+ pragma Import (C, gnat_exit_status);
+ GNAT_Version : constant String :=
+ "GNAT Version: Pro 7.4.0w (20141119-49)" & ASCII.NUL;
+ pragma Export (C, GNAT_Version, "__gnat_version");
-Traceback is a mechanism to display the sequence of subprogram calls that
-leads to a specified execution point in a program. Often (but not always)
-the execution point is an instruction at which an exception has been raised.
-This mechanism is also known as @emph{stack unwinding} because it obtains
-its information by scanning the run-time stack and recovering the activation
-records of all active subprograms. Stack unwinding is one of the most
-important tools for program debugging.
+ Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL;
+ pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name");
-The first entry stored in traceback corresponds to the deepest calling level,
-that is to say the subprogram currently executing the instruction
-from which we want to obtain the traceback.
+ -- This is the generated adainit routine that performs
+ -- initialization at the start of execution. In the case
+ -- where Ada is the main program, this main program makes
+ -- a call to adainit at program startup.
-Note that there is no runtime performance penalty when stack traceback
-is enabled, and no exception is raised during program execution.
+ procedure adainit;
+ pragma Export (C, adainit, "adainit");
-@geindex traceback
-@geindex non-symbolic
+ -- This is the generated adafinal routine that performs
+ -- finalization at the end of execution. In the case where
+ -- Ada is the main program, this main program makes a call
+ -- to adafinal at program termination.
-@menu
-* Non-Symbolic Traceback::
-* Symbolic Traceback::
+ procedure adafinal;
+ pragma Export (C, adafinal, "adafinal");
-@end menu
+ -- This routine is called at the start of execution. It is
+ -- a dummy routine that is used by the debugger to breakpoint
+ -- at the start of execution.
-@node Non-Symbolic Traceback,Symbolic Traceback,,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution non-symbolic-traceback}@anchor{213}@anchor{gnat_ugn/gnat_and_program_execution id17}@anchor{214}
-@subsubsection Non-Symbolic Traceback
-
-
-Note: this feature is not supported on all platforms. See
-@code{GNAT.Traceback} spec in @code{g-traceb.ads}
-for a complete list of supported platforms.
-
-@subsubheading Tracebacks From an Unhandled Exception
-
-
-A runtime non-symbolic traceback is a list of addresses of call instructions.
-To enable this feature you must use the @emph{-E}
-@cite{gnatbind}'s option. With this option a stack traceback is stored as part
-of exception information. You can retrieve this information using the
-@cite{addr2line} tool.
-
-Here is a simple example:
-
-@quotation
-
-@example
-procedure STB is
-
- procedure P1 is
- begin
- raise Constraint_Error;
- end P1;
-
- procedure P2 is
- begin
- P1;
- end P2;
+ -- This is the actual generated main program (it would be
+ -- suppressed if the no main program switch were used). As
+ -- required by standard system conventions, this program has
+ -- the external name main.
-begin
- P2;
-end STB;
-@end example
+ function main
+ (argc : Integer;
+ argv : System.Address;
+ envp : System.Address)
+ return Integer;
+ pragma Export (C, main, "main");
-@example
-$ gnatmake stb -bargs -E
-$ stb
+ -- The following set of constants give the version
+ -- identification values for every unit in the bound
+ -- partition. This identification is computed from all
+ -- dependent semantic units, and corresponds to the
+ -- string that would be returned by use of the
+ -- Body_Version or Version attributes.
-Execution terminated by unhandled exception
-Exception name: CONSTRAINT_ERROR
-Message: stb.adb:5
-Call stack traceback locations:
-0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
-@end example
-@end quotation
+ -- The following Export pragmas export the version numbers
+ -- with symbolic names ending in B (for body) or S
+ -- (for spec) so that they can be located in a link. The
+ -- information provided here is sufficient to track down
+ -- the exact versions of units used in a given build.
-As we see the traceback lists a sequence of addresses for the unhandled
-exception @cite{CONSTRAINT_ERROR} raised in procedure P1. It is easy to
-guess that this exception come from procedure P1. To translate these
-addresses into the source lines where the calls appear, the
-@cite{addr2line} tool, described below, is invaluable. The use of this tool
-requires the program to be compiled with debug information.
+ type Version_32 is mod 2 ** 32;
+ u00001 : constant Version_32 := 16#8ad6e54a#;
+ pragma Export (C, u00001, "helloB");
+ u00002 : constant Version_32 := 16#fbff4c67#;
+ pragma Export (C, u00002, "system__standard_libraryB");
+ u00003 : constant Version_32 := 16#1ec6fd90#;
+ pragma Export (C, u00003, "system__standard_libraryS");
+ u00004 : constant Version_32 := 16#3ffc8e18#;
+ pragma Export (C, u00004, "adaS");
+ u00005 : constant Version_32 := 16#28f088c2#;
+ pragma Export (C, u00005, "ada__text_ioB");
+ u00006 : constant Version_32 := 16#f372c8ac#;
+ pragma Export (C, u00006, "ada__text_ioS");
+ u00007 : constant Version_32 := 16#2c143749#;
+ pragma Export (C, u00007, "ada__exceptionsB");
+ u00008 : constant Version_32 := 16#f4f0cce8#;
+ pragma Export (C, u00008, "ada__exceptionsS");
+ u00009 : constant Version_32 := 16#a46739c0#;
+ pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB");
+ u00010 : constant Version_32 := 16#3aac8c92#;
+ pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS");
+ u00011 : constant Version_32 := 16#1d274481#;
+ pragma Export (C, u00011, "systemS");
+ u00012 : constant Version_32 := 16#a207fefe#;
+ pragma Export (C, u00012, "system__soft_linksB");
+ u00013 : constant Version_32 := 16#467d9556#;
+ pragma Export (C, u00013, "system__soft_linksS");
+ u00014 : constant Version_32 := 16#b01dad17#;
+ pragma Export (C, u00014, "system__parametersB");
+ u00015 : constant Version_32 := 16#630d49fe#;
+ pragma Export (C, u00015, "system__parametersS");
+ u00016 : constant Version_32 := 16#b19b6653#;
+ pragma Export (C, u00016, "system__secondary_stackB");
+ u00017 : constant Version_32 := 16#b6468be8#;
+ pragma Export (C, u00017, "system__secondary_stackS");
+ u00018 : constant Version_32 := 16#39a03df9#;
+ pragma Export (C, u00018, "system__storage_elementsB");
+ u00019 : constant Version_32 := 16#30e40e85#;
+ pragma Export (C, u00019, "system__storage_elementsS");
+ u00020 : constant Version_32 := 16#41837d1e#;
+ pragma Export (C, u00020, "system__stack_checkingB");
+ u00021 : constant Version_32 := 16#93982f69#;
+ pragma Export (C, u00021, "system__stack_checkingS");
+ u00022 : constant Version_32 := 16#393398c1#;
+ pragma Export (C, u00022, "system__exception_tableB");
+ u00023 : constant Version_32 := 16#b33e2294#;
+ pragma Export (C, u00023, "system__exception_tableS");
+ u00024 : constant Version_32 := 16#ce4af020#;
+ pragma Export (C, u00024, "system__exceptionsB");
+ u00025 : constant Version_32 := 16#75442977#;
+ pragma Export (C, u00025, "system__exceptionsS");
+ u00026 : constant Version_32 := 16#37d758f1#;
+ pragma Export (C, u00026, "system__exceptions__machineS");
+ u00027 : constant Version_32 := 16#b895431d#;
+ pragma Export (C, u00027, "system__exceptions_debugB");
+ u00028 : constant Version_32 := 16#aec55d3f#;
+ pragma Export (C, u00028, "system__exceptions_debugS");
+ u00029 : constant Version_32 := 16#570325c8#;
+ pragma Export (C, u00029, "system__img_intB");
+ u00030 : constant Version_32 := 16#1ffca443#;
+ pragma Export (C, u00030, "system__img_intS");
+ u00031 : constant Version_32 := 16#b98c3e16#;
+ pragma Export (C, u00031, "system__tracebackB");
+ u00032 : constant Version_32 := 16#831a9d5a#;
+ pragma Export (C, u00032, "system__tracebackS");
+ u00033 : constant Version_32 := 16#9ed49525#;
+ pragma Export (C, u00033, "system__traceback_entriesB");
+ u00034 : constant Version_32 := 16#1d7cb2f1#;
+ pragma Export (C, u00034, "system__traceback_entriesS");
+ u00035 : constant Version_32 := 16#8c33a517#;
+ pragma Export (C, u00035, "system__wch_conB");
+ u00036 : constant Version_32 := 16#065a6653#;
+ pragma Export (C, u00036, "system__wch_conS");
+ u00037 : constant Version_32 := 16#9721e840#;
+ pragma Export (C, u00037, "system__wch_stwB");
+ u00038 : constant Version_32 := 16#2b4b4a52#;
+ pragma Export (C, u00038, "system__wch_stwS");
+ u00039 : constant Version_32 := 16#92b797cb#;
+ pragma Export (C, u00039, "system__wch_cnvB");
+ u00040 : constant Version_32 := 16#09eddca0#;
+ pragma Export (C, u00040, "system__wch_cnvS");
+ u00041 : constant Version_32 := 16#6033a23f#;
+ pragma Export (C, u00041, "interfacesS");
+ u00042 : constant Version_32 := 16#ece6fdb6#;
+ pragma Export (C, u00042, "system__wch_jisB");
+ u00043 : constant Version_32 := 16#899dc581#;
+ pragma Export (C, u00043, "system__wch_jisS");
+ u00044 : constant Version_32 := 16#10558b11#;
+ pragma Export (C, u00044, "ada__streamsB");
+ u00045 : constant Version_32 := 16#2e6701ab#;
+ pragma Export (C, u00045, "ada__streamsS");
+ u00046 : constant Version_32 := 16#db5c917c#;
+ pragma Export (C, u00046, "ada__io_exceptionsS");
+ u00047 : constant Version_32 := 16#12c8cd7d#;
+ pragma Export (C, u00047, "ada__tagsB");
+ u00048 : constant Version_32 := 16#ce72c228#;
+ pragma Export (C, u00048, "ada__tagsS");
+ u00049 : constant Version_32 := 16#c3335bfd#;
+ pragma Export (C, u00049, "system__htableB");
+ u00050 : constant Version_32 := 16#99e5f76b#;
+ pragma Export (C, u00050, "system__htableS");
+ u00051 : constant Version_32 := 16#089f5cd0#;
+ pragma Export (C, u00051, "system__string_hashB");
+ u00052 : constant Version_32 := 16#3bbb9c15#;
+ pragma Export (C, u00052, "system__string_hashS");
+ u00053 : constant Version_32 := 16#807fe041#;
+ pragma Export (C, u00053, "system__unsigned_typesS");
+ u00054 : constant Version_32 := 16#d27be59e#;
+ pragma Export (C, u00054, "system__val_lluB");
+ u00055 : constant Version_32 := 16#fa8db733#;
+ pragma Export (C, u00055, "system__val_lluS");
+ u00056 : constant Version_32 := 16#27b600b2#;
+ pragma Export (C, u00056, "system__val_utilB");
+ u00057 : constant Version_32 := 16#b187f27f#;
+ pragma Export (C, u00057, "system__val_utilS");
+ u00058 : constant Version_32 := 16#d1060688#;
+ pragma Export (C, u00058, "system__case_utilB");
+ u00059 : constant Version_32 := 16#392e2d56#;
+ pragma Export (C, u00059, "system__case_utilS");
+ u00060 : constant Version_32 := 16#84a27f0d#;
+ pragma Export (C, u00060, "interfaces__c_streamsB");
+ u00061 : constant Version_32 := 16#8bb5f2c0#;
+ pragma Export (C, u00061, "interfaces__c_streamsS");
+ u00062 : constant Version_32 := 16#6db6928f#;
+ pragma Export (C, u00062, "system__crtlS");
+ u00063 : constant Version_32 := 16#4e6a342b#;
+ pragma Export (C, u00063, "system__file_ioB");
+ u00064 : constant Version_32 := 16#ba56a5e4#;
+ pragma Export (C, u00064, "system__file_ioS");
+ u00065 : constant Version_32 := 16#b7ab275c#;
+ pragma Export (C, u00065, "ada__finalizationB");
+ u00066 : constant Version_32 := 16#19f764ca#;
+ pragma Export (C, u00066, "ada__finalizationS");
+ u00067 : constant Version_32 := 16#95817ed8#;
+ pragma Export (C, u00067, "system__finalization_rootB");
+ u00068 : constant Version_32 := 16#52d53711#;
+ pragma Export (C, u00068, "system__finalization_rootS");
+ u00069 : constant Version_32 := 16#769e25e6#;
+ pragma Export (C, u00069, "interfaces__cB");
+ u00070 : constant Version_32 := 16#4a38bedb#;
+ pragma Export (C, u00070, "interfaces__cS");
+ u00071 : constant Version_32 := 16#07e6ee66#;
+ pragma Export (C, u00071, "system__os_libB");
+ u00072 : constant Version_32 := 16#d7b69782#;
+ pragma Export (C, u00072, "system__os_libS");
+ u00073 : constant Version_32 := 16#1a817b8e#;
+ pragma Export (C, u00073, "system__stringsB");
+ u00074 : constant Version_32 := 16#639855e7#;
+ pragma Export (C, u00074, "system__stringsS");
+ u00075 : constant Version_32 := 16#e0b8de29#;
+ pragma Export (C, u00075, "system__file_control_blockS");
+ u00076 : constant Version_32 := 16#b5b2aca1#;
+ pragma Export (C, u00076, "system__finalization_mastersB");
+ u00077 : constant Version_32 := 16#69316dc1#;
+ pragma Export (C, u00077, "system__finalization_mastersS");
+ u00078 : constant Version_32 := 16#57a37a42#;
+ pragma Export (C, u00078, "system__address_imageB");
+ u00079 : constant Version_32 := 16#bccbd9bb#;
+ pragma Export (C, u00079, "system__address_imageS");
+ u00080 : constant Version_32 := 16#7268f812#;
+ pragma Export (C, u00080, "system__img_boolB");
+ u00081 : constant Version_32 := 16#e8fe356a#;
+ pragma Export (C, u00081, "system__img_boolS");
+ u00082 : constant Version_32 := 16#d7aac20c#;
+ pragma Export (C, u00082, "system__ioB");
+ u00083 : constant Version_32 := 16#8365b3ce#;
+ pragma Export (C, u00083, "system__ioS");
+ u00084 : constant Version_32 := 16#6d4d969a#;
+ pragma Export (C, u00084, "system__storage_poolsB");
+ u00085 : constant Version_32 := 16#e87cc305#;
+ pragma Export (C, u00085, "system__storage_poolsS");
+ u00086 : constant Version_32 := 16#e34550ca#;
+ pragma Export (C, u00086, "system__pool_globalB");
+ u00087 : constant Version_32 := 16#c88d2d16#;
+ pragma Export (C, u00087, "system__pool_globalS");
+ u00088 : constant Version_32 := 16#9d39c675#;
+ pragma Export (C, u00088, "system__memoryB");
+ u00089 : constant Version_32 := 16#445a22b5#;
+ pragma Export (C, u00089, "system__memoryS");
+ u00090 : constant Version_32 := 16#6a859064#;
+ pragma Export (C, u00090, "system__storage_pools__subpoolsB");
+ u00091 : constant Version_32 := 16#e3b008dc#;
+ pragma Export (C, u00091, "system__storage_pools__subpoolsS");
+ u00092 : constant Version_32 := 16#63f11652#;
+ pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB");
+ u00093 : constant Version_32 := 16#fe2f4b3a#;
+ pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS");
-@quotation
+ -- BEGIN ELABORATION ORDER
+ -- ada%s
+ -- interfaces%s
+ -- system%s
+ -- system.case_util%s
+ -- system.case_util%b
+ -- system.htable%s
+ -- system.img_bool%s
+ -- system.img_bool%b
+ -- system.img_int%s
+ -- system.img_int%b
+ -- system.io%s
+ -- system.io%b
+ -- system.parameters%s
+ -- system.parameters%b
+ -- system.crtl%s
+ -- interfaces.c_streams%s
+ -- interfaces.c_streams%b
+ -- system.standard_library%s
+ -- system.exceptions_debug%s
+ -- system.exceptions_debug%b
+ -- system.storage_elements%s
+ -- system.storage_elements%b
+ -- system.stack_checking%s
+ -- system.stack_checking%b
+ -- system.string_hash%s
+ -- system.string_hash%b
+ -- system.htable%b
+ -- system.strings%s
+ -- system.strings%b
+ -- system.os_lib%s
+ -- system.traceback_entries%s
+ -- system.traceback_entries%b
+ -- ada.exceptions%s
+ -- system.soft_links%s
+ -- system.unsigned_types%s
+ -- system.val_llu%s
+ -- system.val_util%s
+ -- system.val_util%b
+ -- system.val_llu%b
+ -- system.wch_con%s
+ -- system.wch_con%b
+ -- system.wch_cnv%s
+ -- system.wch_jis%s
+ -- system.wch_jis%b
+ -- system.wch_cnv%b
+ -- system.wch_stw%s
+ -- system.wch_stw%b
+ -- ada.exceptions.last_chance_handler%s
+ -- ada.exceptions.last_chance_handler%b
+ -- system.address_image%s
+ -- system.exception_table%s
+ -- system.exception_table%b
+ -- ada.io_exceptions%s
+ -- ada.tags%s
+ -- ada.streams%s
+ -- ada.streams%b
+ -- interfaces.c%s
+ -- system.exceptions%s
+ -- system.exceptions%b
+ -- system.exceptions.machine%s
+ -- system.finalization_root%s
+ -- system.finalization_root%b
+ -- ada.finalization%s
+ -- ada.finalization%b
+ -- system.storage_pools%s
+ -- system.storage_pools%b
+ -- system.finalization_masters%s
+ -- system.storage_pools.subpools%s
+ -- system.storage_pools.subpools.finalization%s
+ -- system.storage_pools.subpools.finalization%b
+ -- system.memory%s
+ -- system.memory%b
+ -- system.standard_library%b
+ -- system.pool_global%s
+ -- system.pool_global%b
+ -- system.file_control_block%s
+ -- system.file_io%s
+ -- system.secondary_stack%s
+ -- system.file_io%b
+ -- system.storage_pools.subpools%b
+ -- system.finalization_masters%b
+ -- interfaces.c%b
+ -- ada.tags%b
+ -- system.soft_links%b
+ -- system.os_lib%b
+ -- system.secondary_stack%b
+ -- system.address_image%b
+ -- system.traceback%s
+ -- ada.exceptions%b
+ -- system.traceback%b
+ -- ada.text_io%s
+ -- ada.text_io%b
+ -- hello%b
+ -- END ELABORATION ORDER
+
+end ada_main;
+@end example
@example
-$ gnatmake -g stb -bargs -E
-$ stb
+pragma Ada_95;
+-- The following source file name pragmas allow the generated file
+-- names to be unique for different main programs. They are needed
+-- since the package name will always be Ada_Main.
-Execution terminated by unhandled exception
-Exception name: CONSTRAINT_ERROR
-Message: stb.adb:5
-Call stack traceback locations:
-0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4
+pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads");
+pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb");
-$ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4
- 0x4011f1 0x77e892a4
+pragma Suppress (Overflow_Check);
+with Ada.Exceptions;
-00401373 at d:/stb/stb.adb:5
-0040138B at d:/stb/stb.adb:10
-0040139C at d:/stb/stb.adb:14
-00401335 at d:/stb/b~stb.adb:104
-004011C4 at /build/.../crt1.c:200
-004011F1 at /build/.../crt1.c:222
-77E892A4 in ?? at ??:0
-@end example
-@end quotation
+-- Generated package body for Ada_Main starts here
-The @cite{addr2line} tool has several other useful options:
+package body ada_main is
+ pragma Warnings (Off);
-@quotation
+ -- These values are reference counter associated to units which have
+ -- been elaborated. It is also used to avoid elaborating the
+ -- same unit twice.
+ E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E");
+ E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E");
+ E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E");
+ E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E");
+ E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E");
+ E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E");
+ E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E");
+ E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E");
+ E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E");
+ E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E");
+ E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E");
+ E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E");
+ E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E");
+ E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E");
+ E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E");
+ E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E");
+ E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E");
+ E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E");
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
-@item
+ Local_Priority_Specific_Dispatching : constant String := "";
+ Local_Interrupt_States : constant String := "";
-@code{--functions}
+ Is_Elaborated : Boolean := False;
-@tab
+ procedure finalize_library is
+ begin
+ E06 := E06 - 1;
+ declare
+ procedure F1;
+ pragma Import (Ada, F1, "ada__text_io__finalize_spec");
+ begin
+ F1;
+ end;
+ E77 := E77 - 1;
+ E91 := E91 - 1;
+ declare
+ procedure F2;
+ pragma Import (Ada, F2, "system__file_io__finalize_body");
+ begin
+ E64 := E64 - 1;
+ F2;
+ end;
+ declare
+ procedure F3;
+ pragma Import (Ada, F3, "system__file_control_block__finalize_spec");
+ begin
+ E75 := E75 - 1;
+ F3;
+ end;
+ E87 := E87 - 1;
+ declare
+ procedure F4;
+ pragma Import (Ada, F4, "system__pool_global__finalize_spec");
+ begin
+ F4;
+ end;
+ declare
+ procedure F5;
+ pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec");
+ begin
+ F5;
+ end;
+ declare
+ procedure F6;
+ pragma Import (Ada, F6, "system__finalization_masters__finalize_spec");
+ begin
+ F6;
+ end;
+ declare
+ procedure Reraise_Library_Exception_If_Any;
+ pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any");
+ begin
+ Reraise_Library_Exception_If_Any;
+ end;
+ end finalize_library;
-to get the function name corresponding to any location
+ -------------
+ -- adainit --
+ -------------
-@item
+ procedure adainit is
-@code{--demangle=gnat}
+ Main_Priority : Integer;
+ pragma Import (C, Main_Priority, "__gl_main_priority");
+ Time_Slice_Value : Integer;
+ pragma Import (C, Time_Slice_Value, "__gl_time_slice_val");
+ WC_Encoding : Character;
+ pragma Import (C, WC_Encoding, "__gl_wc_encoding");
+ Locking_Policy : Character;
+ pragma Import (C, Locking_Policy, "__gl_locking_policy");
+ Queuing_Policy : Character;
+ pragma Import (C, Queuing_Policy, "__gl_queuing_policy");
+ Task_Dispatching_Policy : Character;
+ pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy");
+ Priority_Specific_Dispatching : System.Address;
+ pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching");
+ Num_Specific_Dispatching : Integer;
+ pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching");
+ Main_CPU : Integer;
+ pragma Import (C, Main_CPU, "__gl_main_cpu");
+ Interrupt_States : System.Address;
+ pragma Import (C, Interrupt_States, "__gl_interrupt_states");
+ Num_Interrupt_States : Integer;
+ pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states");
+ Unreserve_All_Interrupts : Integer;
+ pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts");
+ Detect_Blocking : Integer;
+ pragma Import (C, Detect_Blocking, "__gl_detect_blocking");
+ Default_Stack_Size : Integer;
+ pragma Import (C, Default_Stack_Size, "__gl_default_stack_size");
+ Leap_Seconds_Support : Integer;
+ pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support");
-@tab
+ procedure Runtime_Initialize;
+ pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize");
-to use the gnat decoding mode for the function names.
-Note that for binutils version 2.9.x the option is
-simply @code{--demangle}.
+ Finalize_Library_Objects : No_Param_Proc;
+ pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects");
-@end multitable
+ -- Start of processing for adainit
+ begin
-@example
-$ addr2line --exe=stb --functions --demangle=gnat 0x401373 0x40138b
- 0x40139c 0x401335 0x4011c4 0x4011f1
-
-00401373 in stb.p1 at d:/stb/stb.adb:5
-0040138B in stb.p2 at d:/stb/stb.adb:10
-0040139C in stb at d:/stb/stb.adb:14
-00401335 in main at d:/stb/b~stb.adb:104
-004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200
-004011F1 in <mainCRTStartup> at /build/.../crt1.c:222
-@end example
-@end quotation
-
-From this traceback we can see that the exception was raised in
-@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{120,,Running gnatbind}. The remaining entries are assorted runtime routines,
-and the output will vary from platform to platform.
-
-It is also possible to use @cite{GDB} with these traceback addresses to debug
-the program. For example, we can break at a given code location, as reported
-in the stack traceback:
-
-@quotation
-
-@example
-$ gdb -nw stb
-@end example
-@end quotation
-
-Furthermore, this feature is not implemented inside Windows DLL. Only
-the non-symbolic traceback is reported in this case.
-
-@quotation
-
-@example
-(gdb) break *0x401373
-Breakpoint 1 at 0x401373: file stb.adb, line 5.
-@end example
-@end quotation
-
-It is important to note that the stack traceback addresses
-do not change when debug information is included. This is particularly useful
-because it makes it possible to release software without debug information (to
-minimize object size), get a field report that includes a stack traceback
-whenever an internal bug occurs, and then be able to retrieve the sequence
-of calls with the same program compiled with debug information.
-
-@subsubheading Tracebacks From Exception Occurrences
-
-
-Non-symbolic tracebacks are obtained by using the @emph{-E} binder argument.
-The stack traceback is attached to the exception information string, and can
-be retrieved in an exception handler within the Ada program, by means of the
-Ada facilities defined in @cite{Ada.Exceptions}. Here is a simple example:
-
-@quotation
-
-@example
-with Ada.Text_IO;
-with Ada.Exceptions;
-
-procedure STB is
-
- use Ada;
- use Ada.Exceptions;
-
- procedure P1 is
- K : Positive := 1;
- begin
- K := K - 1;
- exception
- when E : others =>
- Text_IO.Put_Line (Exception_Information (E));
- end P1;
-
- procedure P2 is
- begin
- P1;
- end P2;
-
-begin
- P2;
-end STB;
-@end example
-@end quotation
-
-This program will output:
-
-@quotation
-
-@example
-$ stb
-
-Exception name: CONSTRAINT_ERROR
-Message: stb.adb:12
-Call stack traceback locations:
-0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4
-@end example
-@end quotation
+ -- Record various information for this partition. The values
+ -- are derived by the binder from information stored in the ali
+ -- files by the compiler.
-@subsubheading Tracebacks From Anywhere in a Program
+ if Is_Elaborated then
+ return;
+ end if;
+ Is_Elaborated := True;
+ Main_Priority := -1;
+ Time_Slice_Value := -1;
+ WC_Encoding := 'b';
+ Locking_Policy := ' ';
+ Queuing_Policy := ' ';
+ Task_Dispatching_Policy := ' ';
+ Priority_Specific_Dispatching :=
+ Local_Priority_Specific_Dispatching'Address;
+ Num_Specific_Dispatching := 0;
+ Main_CPU := -1;
+ Interrupt_States := Local_Interrupt_States'Address;
+ Num_Interrupt_States := 0;
+ Unreserve_All_Interrupts := 0;
+ Detect_Blocking := 0;
+ Default_Stack_Size := -1;
+ Leap_Seconds_Support := 0;
+ Runtime_Initialize;
-It is also possible to retrieve a stack traceback from anywhere in a
-program. For this you need to
-use the @cite{GNAT.Traceback} API. This package includes a procedure called
-@cite{Call_Chain} that computes a complete stack traceback, as well as useful
-display procedures described below. It is not necessary to use the
-@emph{-E gnatbind} option in this case, because the stack traceback mechanism
-is invoked explicitly.
+ Finalize_Library_Objects := finalize_library'access;
-In the following example we compute a traceback at a specific location in
-the program, and we display it using @cite{GNAT.Debug_Utilities.Image} to
-convert addresses to strings:
+ -- Now we have the elaboration calls for all units in the partition.
+ -- The Elab_Spec and Elab_Body attributes generate references to the
+ -- implicit elaboration procedures generated by the compiler for
+ -- each unit that requires elaboration. Increment a counter of
+ -- reference for each unit.
-@quotation
+ System.Soft_Links'Elab_Spec;
+ System.Exception_Table'Elab_Body;
+ E23 := E23 + 1;
+ Ada.Io_Exceptions'Elab_Spec;
+ E46 := E46 + 1;
+ Ada.Tags'Elab_Spec;
+ Ada.Streams'Elab_Spec;
+ E45 := E45 + 1;
+ Interfaces.C'Elab_Spec;
+ System.Exceptions'Elab_Spec;
+ E25 := E25 + 1;
+ System.Finalization_Root'Elab_Spec;
+ E68 := E68 + 1;
+ Ada.Finalization'Elab_Spec;
+ E66 := E66 + 1;
+ System.Storage_Pools'Elab_Spec;
+ E85 := E85 + 1;
+ System.Finalization_Masters'Elab_Spec;
+ System.Storage_Pools.Subpools'Elab_Spec;
+ System.Pool_Global'Elab_Spec;
+ E87 := E87 + 1;
+ System.File_Control_Block'Elab_Spec;
+ E75 := E75 + 1;
+ System.File_Io'Elab_Body;
+ E64 := E64 + 1;
+ E91 := E91 + 1;
+ System.Finalization_Masters'Elab_Body;
+ E77 := E77 + 1;
+ E70 := E70 + 1;
+ Ada.Tags'Elab_Body;
+ E48 := E48 + 1;
+ System.Soft_Links'Elab_Body;
+ E13 := E13 + 1;
+ System.Os_Lib'Elab_Body;
+ E72 := E72 + 1;
+ System.Secondary_Stack'Elab_Body;
+ E17 := E17 + 1;
+ Ada.Text_Io'Elab_Spec;
+ Ada.Text_Io'Elab_Body;
+ E06 := E06 + 1;
+ end adainit;
-@example
-with Ada.Text_IO;
-with GNAT.Traceback;
-with GNAT.Debug_Utilities;
+ --------------
+ -- adafinal --
+ --------------
-procedure STB is
+ procedure adafinal is
+ procedure s_stalib_adafinal;
+ pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal");
- use Ada;
- use GNAT;
- use GNAT.Traceback;
+ procedure Runtime_Finalize;
+ pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize");
- procedure P1 is
- TB : Tracebacks_Array (1 .. 10);
- -- We are asking for a maximum of 10 stack frames.
- Len : Natural;
- -- Len will receive the actual number of stack frames returned.
begin
- Call_Chain (TB, Len);
-
- Text_IO.Put ("In STB.P1 : ");
+ if not Is_Elaborated then
+ return;
+ end if;
+ Is_Elaborated := False;
+ Runtime_Finalize;
+ s_stalib_adafinal;
+ end adafinal;
- for K in 1 .. Len loop
- Text_IO.Put (Debug_Utilities.Image (TB (K)));
- Text_IO.Put (' ');
- end loop;
+ -- We get to the main program of the partition by using
+ -- pragma Import because if we try to with the unit and
+ -- call it Ada style, then not only do we waste time
+ -- recompiling it, but also, we don't really know the right
+ -- switches (e.g.@@: identifier character set) to be used
+ -- to compile it.
- Text_IO.New_Line;
- end P1;
+ procedure Ada_Main_Program;
+ pragma Import (Ada, Ada_Main_Program, "_ada_hello");
- procedure P2 is
- begin
- P1;
- end P2;
+ ----------
+ -- main --
+ ----------
-begin
- P2;
-end STB;
-@end example
+ -- main is actually a function, as in the ANSI C standard,
+ -- defined to return the exit status. The three parameters
+ -- are the argument count, argument values and environment
+ -- pointer.
-@example
-$ gnatmake -g stb
-$ stb
+ function main
+ (argc : Integer;
+ argv : System.Address;
+ envp : System.Address)
+ return Integer
+ is
+ -- The initialize routine performs low level system
+ -- initialization using a standard library routine which
+ -- sets up signal handling and performs any other
+ -- required setup. The routine can be found in file
+ -- a-init.c.
-In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C#
-16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4#
-@end example
-@end quotation
+ procedure initialize;
+ pragma Import (C, initialize, "__gnat_initialize");
-You can then get further information by invoking the @cite{addr2line}
-tool as described earlier (note that the hexadecimal addresses
-need to be specified in C format, with a leading '0x').
-
-@geindex traceback
-@geindex symbolic
-
-@node Symbolic Traceback,,Non-Symbolic Traceback,Stack Traceback
-@anchor{gnat_ugn/gnat_and_program_execution id18}@anchor{215}@anchor{gnat_ugn/gnat_and_program_execution symbolic-traceback}@anchor{216}
-@subsubsection Symbolic Traceback
-
-
-A symbolic traceback is a stack traceback in which procedure names are
-associated with each code location.
-
-Note that this feature is not supported on all platforms. See
-@code{GNAT.Traceback.Symbolic} spec in @code{g-trasym.ads} for a complete
-list of currently supported platforms.
-
-Note that the symbolic traceback requires that the program be compiled
-with debug information. If it is not compiled with debug information
-only the non-symbolic information will be valid.
-
-@subsubheading Tracebacks From Exception Occurrences
-
-
-Here is an example:
-
-@quotation
-
-@example
-with Ada.Text_IO;
-with GNAT.Traceback.Symbolic;
-
-procedure STB is
-
- procedure P1 is
- begin
- raise Constraint_Error;
- end P1;
-
- procedure P2 is
- begin
- P1;
- end P2;
-
- procedure P3 is
- begin
- P2;
- end P3;
-
-begin
- P3;
-exception
- when E : others =>
- Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E));
-end STB;
-@end example
-
-@example
-$ gnatmake -g .\stb -bargs -E
-$ stb
-
-0040149F in stb.p1 at stb.adb:8
-004014B7 in stb.p2 at stb.adb:13
-004014CF in stb.p3 at stb.adb:18
-004015DD in ada.stb at stb.adb:22
-00401461 in main at b~stb.adb:168
-004011C4 in __mingw_CRTStartup at crt1.c:200
-004011F1 in mainCRTStartup at crt1.c:222
-77E892A4 in ?? at ??:0
-@end example
-@end quotation
-
-In the above example the @code{.\} syntax in the @emph{gnatmake} command
-is currently required by @emph{addr2line} for files that are in
-the current working directory.
-Moreover, the exact sequence of linker options may vary from platform
-to platform.
-The above @emph{-largs} section is for Windows platforms. By contrast,
-under Unix there is no need for the @emph{-largs} section.
-Differences across platforms are due to details of linker implementation.
-
-@subsubheading Tracebacks From Anywhere in a Program
-
-
-It is possible to get a symbolic stack traceback
-from anywhere in a program, just as for non-symbolic tracebacks.
-The first step is to obtain a non-symbolic
-traceback, and then call @cite{Symbolic_Traceback} to compute the symbolic
-information. Here is an example:
-
-@quotation
-
-@example
-with Ada.Text_IO;
-with GNAT.Traceback;
-with GNAT.Traceback.Symbolic;
-
-procedure STB is
-
- use Ada;
- use GNAT.Traceback;
- use GNAT.Traceback.Symbolic;
-
- procedure P1 is
- TB : Tracebacks_Array (1 .. 10);
- -- We are asking for a maximum of 10 stack frames.
- Len : Natural;
- -- Len will receive the actual number of stack frames returned.
- begin
- Call_Chain (TB, Len);
- Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len)));
- end P1;
-
- procedure P2 is
- begin
- P1;
- end P2;
-
-begin
- P2;
-end STB;
-@end example
-@end quotation
-
-@subsubheading Automatic Symbolic Tracebacks
-
-
-Symbolic tracebacks may also be enabled by using the -Es switch to gnatbind (as
-in @cite{gprbuild -g ... -bargs -Es}).
-This will cause the Exception_Information to contain a symbolic traceback,
-which will also be printed if an unhandled exception terminates the
-program.
-
-@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 id19}@anchor{1f1}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-and-profiling}@anchor{27}
-@section Code Coverage and Profiling
-
-
-This section describes how to use the @cite{gcov} coverage testing tool and
-the @cite{gprof} profiler tool on Ada programs.
-
-@geindex gcov
-
-@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 id20}@anchor{217}@anchor{gnat_ugn/gnat_and_program_execution code-coverage-of-ada-programs-with-gcov}@anchor{218}
-@subsection Code Coverage of Ada Programs with gcov
-
-
-@cite{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.
-
-@cite{gcov} is part of the GCC suite, and is described in detail in the GCC
-User's Guide. You can refer to this documentation for a more complete
-description.
-
-This chapter provides a quick startup guide, and
-details some GNAT-specific features.
-
-@menu
-* Quick startup guide::
-* GNAT specifics::
-
-@end menu
-
-@node Quick startup guide,GNAT specifics,,Code Coverage of Ada Programs with gcov
-@anchor{gnat_ugn/gnat_and_program_execution id21}@anchor{219}@anchor{gnat_ugn/gnat_and_program_execution quick-startup-guide}@anchor{21a}
-@subsubsection Quick startup guide
-
-
-In order to perform coverage analysis of a program using @cite{gcov}, several
-steps are needed:
-
-
-@enumerate
-
-@item
-Instrument the code during the compilation process,
-
-@item
-Execute the instrumented program, and
-
-@item
-Invoke the @cite{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
-@cite{-fprofile-arcs} and @cite{-ftest-coverage}, and link it using
-@cite{-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 @cite{gcov} tool. The different options of
-@cite{gcov} are described in the GCC User's Guide, section '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{21b}@anchor{gnat_ugn/gnat_and_program_execution id22}@anchor{21c}
-@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 @cite{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 @cite{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 @cite{-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{21d}@anchor{gnat_ugn/gnat_and_program_execution id23}@anchor{21e}
-@subsection Profiling an Ada Program with gprof
-
-
-This section is not meant to be an exhaustive documentation of @cite{gprof}.
-Full documentation for it can be found in the @cite{GNU Profiler User's Guide}
-documentation that is part of this GNAT distribution.
-
-Profiling a program helps determine the parts of a program that are executed
-most often, and are therefore the most time-consuming.
-
-@cite{gprof} is the standard GNU profiling tool; it has been enhanced to
-better handle Ada programs and multitasking.
-It is currently supported on the following platforms
-
-
-@itemize *
-
-@item
-linux x86/x86_64
-
-@item
-solaris sparc/sparc64/x86
-
-@item
-windows x86
-@end itemize
-
-In order to profile a program using @cite{gprof}, several steps are needed:
-
-
-@enumerate
-
-@item
-Instrument the code, which requires a full recompilation of the project with the
-proper switches.
-
-@item
-Execute the program under the analysis conditions, i.e. with the desired
-input.
-
-@item
-Analyze the results using the @cite{gprof} tool.
-@end enumerate
-
-The following sections detail the different steps, and indicate how
-to interpret the results.
-
-@menu
-* Compilation for profiling::
-* Program execution::
-* Running gprof::
-* Interpretation of profiling results::
-
-@end menu
-
-@node Compilation for profiling,Program execution,,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id24}@anchor{21f}@anchor{gnat_ugn/gnat_and_program_execution compilation-for-profiling}@anchor{220}
-@subsubsection Compilation for profiling
-
-
-@geindex -pg (gcc)
-@geindex for profiling
-
-@geindex -pg (gnatlink)
-@geindex for profiling
-
-In order to profile a program the first step is to tell the compiler
-to generate the necessary profiling information. The compiler switch to be used
-is @code{-pg}, which must be added to other compilation switches. This
-switch needs to be specified both during compilation and link stages, and can
-be specified once when using gnatmake:
-
-@quotation
-
-@example
-$ gnatmake -f -pg -P my_project
-@end example
-@end quotation
-
-Note that only the objects that were compiled with the @code{-pg} switch will
-be profiled; if you need to profile your whole project, use the @code{-f}
-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{221}@anchor{gnat_ugn/gnat_and_program_execution id25}@anchor{222}
-@subsubsection Program execution
-
-
-Once the program has been compiled for profiling, you can run it as usual.
-
-The only constraint imposed by profiling is that the program must terminate
-normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
-properly analyzed.
-
-Once the program completes execution, a data file called @code{gmon.out} is
-generated in the directory where the program was launched from. If this file
-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{223}@anchor{gnat_ugn/gnat_and_program_execution id26}@anchor{224}
-@subsubsection Running gprof
-
-
-The @cite{gprof} tool is called as follow:
-
-@quotation
-
-@example
-$ gprof my_prog gmon.out
-@end example
-@end quotation
-
-or simply:
-
-@quotation
-
-@example
-$ gprof my_prog
-@end example
-@end quotation
-
-The complete form of the gprof command line is the following:
-
-@quotation
-
-@example
-$ gprof [switches] [executable [data-file]]
-@end example
-@end quotation
-
-@cite{gprof} supports numerous switches. The order of these
-switch does not matter. The full list of options can be found in
-the GNU Profiler User's Guide documentation that comes with this documentation.
-
-The following is the subset of those switches that is most relevant:
-
-@geindex --demangle (gprof)
-
-
-@table @asis
-
-@item @code{--demangle[=@emph{style}]}, @code{--no-demangle}
-
-These options control whether symbol names should be demangled when
-printing output. The default is to demangle C++ symbols. The
-@code{--no-demangle} option may be used to turn off demangling. Different
-compilers have different mangling styles. The optional demangling style
-argument can be used to choose an appropriate demangling style for your
-compiler, in particular Ada symbols generated by GNAT can be demangled using
-@code{--demangle=gnat}.
-@end table
-
-@geindex -e (gprof)
-
-
-@table @asis
-
-@item @code{-e @emph{function_name}}
-
-The @code{-e @emph{function}} option tells @cite{gprof} not to print
-information about the function @cite{function_name} (and its
-children...) in the call graph. The function will still be listed
-as a child of any functions that call it, but its index number will be
-shown as @code{[not printed]}. More than one @code{-e} option may be
-given; only one @cite{function_name} may be indicated with each @code{-e}
-option.
-@end table
-
-@geindex -E (gprof)
-
-
-@table @asis
-
-@item @code{-E @emph{function_name}}
-
-The @code{-E @emph{function}} option works like the @code{-e} option, but
-execution time spent in the function (and children who were not called from
-anywhere else), will not be used to compute the percentages-of-time for
-the call graph. More than one @code{-E} option may be given; only one
-@cite{function_name} may be indicated with each @code{-E} option.
-@end table
-
-@geindex -f (gprof)
-
-
-@table @asis
-
-@item @code{-f @emph{function_name}}
-
-The @code{-f @emph{function}} option causes @cite{gprof} to limit the
-call graph to the function @cite{function_name} and its children (and
-their children...). More than one @code{-f} option may be given;
-only one @cite{function_name} may be indicated with each @code{-f}
-option.
-@end table
-
-@geindex -F (gprof)
-
-
-@table @asis
-
-@item @code{-F @emph{function_name}}
-
-The @code{-F @emph{function}} option works like the @code{-f} option, but
-only time spent in the function and its children (and their
-children...) will be used to determine total-time and
-percentages-of-time for the call graph. More than one @code{-F} option
-may be given; only one @cite{function_name} may be indicated with each
-@code{-F} option. The @code{-F} option overrides the @code{-E} option.
-@end table
-
-@node Interpretation of profiling results,,Running gprof,Profiling an Ada Program with gprof
-@anchor{gnat_ugn/gnat_and_program_execution id27}@anchor{225}@anchor{gnat_ugn/gnat_and_program_execution interpretation-of-profiling-results}@anchor{226}
-@subsubsection Interpretation of profiling results
-
-
-The results of the profiling analysis are represented by two arrays: the
-'flat profile' and the 'call graph'. Full documentation of those outputs
-can be found in the GNU Profiler User's Guide.
-
-The flat profile shows the time spent in each function of the program, and how
-many time it has been called. This allows you to locate easily the most
-time-consuming functions.
-
-The call graph shows, for each subprogram, the subprograms that call it,
-and the subprograms that it calls. It also provides an estimate of the time
-spent in each of those callers/called subprograms.
-
-@node Improving Performance,Overflow Check Handling in GNAT,Code Coverage and Profiling,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution improving-performance}@anchor{28}@anchor{gnat_ugn/gnat_and_program_execution id28}@anchor{1f2}
-@section Improving Performance
-
-
-@geindex Improving performance
-
-This section presents several topics related to program performance.
-It first describes some of the tradeoffs that need to be considered
-and some of the techniques for making your program run faster.
-
-
-It then documents the unused subprogram/data elimination feature,
-which can reduce the size of program executables.
-
-@menu
-* Performance Considerations::
-* Text_IO Suggestions::
-* Reducing Size of Executables with Unused Subprogram/Data Elimination::
-
-@end menu
-
-@node Performance Considerations,Text_IO Suggestions,,Improving Performance
-@anchor{gnat_ugn/gnat_and_program_execution id29}@anchor{227}@anchor{gnat_ugn/gnat_and_program_execution performance-considerations}@anchor{228}
-@subsection Performance Considerations
-
-
-The GNAT system provides a number of options that allow a trade-off
-between
-
-
-@itemize *
-
-@item
-performance of the generated code
-
-@item
-speed of compilation
-
-@item
-minimization of dependences and recompilation
-
-@item
-the degree of run-time checking.
-@end itemize
-
-The defaults (if no options are selected) aim at improving the speed
-of compilation and minimizing dependences, at the expense of performance
-of the generated code:
-
-
-@itemize *
-
-@item
-no optimization
-
-@item
-no inlining of subprogram calls
-
-@item
-all run-time checks enabled except overflow and elaboration checks
-@end itemize
-
-These options are suitable for most program development purposes. This
-section describes how you can modify these choices, and also provides
-some guidelines on debugging optimized code.
-
-@menu
-* Controlling Run-Time Checks::
-* Use of Restrictions::
-* Optimization Levels::
-* Debugging Optimized Code::
-* Inlining of Subprograms::
-* Floating_Point_Operations::
-* Vectorization of loops::
-* Other Optimization Switches::
-* Optimization and Strict Aliasing::
-* Aliased Variables and Optimization::
-* Atomic Variables and Optimization::
-* Passive Task Optimization::
-
-@end menu
-
-@node Controlling Run-Time Checks,Use of Restrictions,,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution controlling-run-time-checks}@anchor{229}@anchor{gnat_ugn/gnat_and_program_execution id30}@anchor{22a}
-@subsubsection Controlling Run-Time Checks
-
-
-By default, GNAT generates all run-time checks, except stack overflow
-checks, and checks for access before elaboration on subprogram
-calls. The latter are not required in default mode, because all
-necessary checking is done at compile time.
-
-@geindex -gnatp (gcc)
-
-@geindex -gnato (gcc)
-
-The gnat switch, @emph{-gnatp} allows this default to be modified. See
-@ref{fe,,Run-Time Checks}.
-
-Our experience is that the default is suitable for most development
-purposes.
-
-Elaboration checks are off by default, and also not needed by default, since
-GNAT uses a static elaboration analysis approach that avoids the need for
-run-time checking. This manual contains a full chapter discussing the issue
-of elaboration checks, and if the default is not satisfactory for your use,
-you should read this chapter.
-
-For validity checks, the minimal checks required by the Ada Reference
-Manual (for case statements and assignments to array elements) are on
-by default. These can be suppressed by use of the @emph{-gnatVn} switch.
-Note that in Ada 83, there were no validity checks, so if the Ada 83 mode
-is acceptable (or when comparing GNAT performance with an Ada 83 compiler),
-it may be reasonable to routinely use @emph{-gnatVn}. Validity checks
-are also suppressed entirely if @emph{-gnatp} is used.
-
-@geindex Overflow checks
-
-@geindex Checks
-@geindex overflow
-
-@geindex Suppress
-
-@geindex Unsuppress
-
-@geindex pragma Suppress
-
-@geindex pragma Unsuppress
-
-Note that the setting of the switches controls the default setting of
-the checks. They may be modified using either @cite{pragma Suppress} (to
-remove checks) or @cite{pragma Unsuppress} (to add back suppressed
-checks) in the program source.
-
-@node Use of Restrictions,Optimization Levels,Controlling Run-Time Checks,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution use-of-restrictions}@anchor{22b}@anchor{gnat_ugn/gnat_and_program_execution id31}@anchor{22c}
-@subsubsection Use of Restrictions
-
-
-The use of pragma Restrictions allows you to control which features are
-permitted in your program. Apart from the obvious point that if you avoid
-relatively expensive features like finalization (enforceable by the use
-of pragma Restrictions (No_Finalization), the use of this pragma does not
-affect the generated code in most cases.
-
-One notable exception to this rule is that the possibility of task abort
-results in some distributed overhead, particularly if finalization or
-exception handlers are used. The reason is that certain sections of code
-have to be marked as non-abortable.
-
-If you use neither the @cite{abort} statement, nor asynchronous transfer
-of control (@cite{select ... then abort}), then this distributed overhead
-is removed, which may have a general positive effect in improving
-overall performance. Especially code involving frequent use of tasking
-constructs and controlled types will show much improved performance.
-The relevant restrictions pragmas are
-
-@quotation
-
-@example
-pragma Restrictions (No_Abort_Statements);
-pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);
-@end example
-@end quotation
-
-It is recommended that these restriction pragmas be used if possible. Note
-that this also means that you can write code without worrying about the
-possibility of an immediate abort at any point.
-
-@node Optimization Levels,Debugging Optimized Code,Use of Restrictions,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id32}@anchor{22d}@anchor{gnat_ugn/gnat_and_program_execution optimization-levels}@anchor{101}
-@subsubsection Optimization Levels
-
-
-@geindex -O (gcc)
-
-Without any optimization option,
-the compiler's goal is to reduce the cost of
-compilation and to make debugging produce the expected results.
-Statements are independent: if you stop the program with a breakpoint between
-statements, you can then assign a new value to any variable or change
-the program counter to any other statement in the subprogram and get exactly
-the results you would expect from the source code.
-
-Turning on optimization makes the compiler attempt to improve the
-performance and/or code size at the expense of compilation time and
-possibly the ability to debug the program.
-
-If you use multiple
--O options, with or without level numbers,
-the last such option is the one that is effective.
-
-The default is optimization off. This results in the fastest compile
-times, but GNAT makes absolutely no attempt to optimize, and the
-generated programs are considerably larger and slower than when
-optimization is enabled. You can use the
-@emph{-O} switch (the permitted forms are @emph{-O0}, @emph{-O1}
-@emph{-O2}, @emph{-O3}, and @emph{-Os})
-to @emph{gcc} to control the optimization level:
-
-
-@itemize *
-
-@item
-
-@table @asis
-
-@item @emph{-O0}
-
-No optimization (the default);
-generates unoptimized code but has
-the fastest compilation time.
-
-Note that many other compilers do fairly extensive optimization
-even if 'no optimization' is specified. With gcc, it is
-very unusual to use -O0 for production if
-execution time is of any concern, since -O0
-really does mean no optimization at all. This difference between
-gcc and other compilers should be kept in mind when doing
-performance comparisons.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{-O1}
-
-Moderate optimization;
-optimizes reasonably well but does not
-degrade compilation time significantly.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{-O2}
-
-Full optimization;
-generates highly optimized code and has
-the slowest compilation time.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{-O3}
-
-Full optimization as in @emph{-O2};
-also uses more aggressive automatic inlining of subprograms within a unit
-(@ref{114,,Inlining of Subprograms}) and attempts to vectorize loops.
-@end table
-
-@item
-
-@table @asis
-
-@item @emph{-Os}
-
-Optimize space usage (code and data) of resulting program.
-@end table
-@end itemize
-
-Higher optimization levels perform more global transformations on the
-program and apply more expensive analysis algorithms in order to generate
-faster and more compact code. The price in compilation time, and the
-resulting improvement in execution time,
-both depend on the particular application and the hardware environment.
-You should experiment to find the best level for your application.
-
-Since the precise set of optimizations done at each level will vary from
-release to release (and sometime from target to target), it is best to think
-of the optimization settings in general terms.
-See the @emph{Options That Control Optimization} section in
-@cite{Using the GNU Compiler Collection (GCC)}
-for details about
-the @emph{-O} settings and a number of @emph{-f} options that
-individually enable or disable specific optimizations.
-
-Unlike some other compilation systems, @emph{gcc} has
-been tested extensively at all optimization levels. There are some bugs
-which appear only with optimization turned on, but there have also been
-bugs which show up only in @emph{unoptimized} code. Selecting a lower
-level of optimization does not improve the reliability of the code
-generator, which in practice is highly reliable at all optimization
-levels.
-
-Note regarding the use of @emph{-O3}: The use of this optimization level
-is generally discouraged with GNAT, since it often results in larger
-executables which may run more slowly. See further discussion of this point
-in @ref{114,,Inlining of Subprograms}.
-
-@node Debugging Optimized Code,Inlining of Subprograms,Optimization Levels,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id33}@anchor{22e}@anchor{gnat_ugn/gnat_and_program_execution debugging-optimized-code}@anchor{22f}
-@subsubsection Debugging Optimized Code
-
-
-@geindex Debugging optimized code
-
-@geindex Optimization and debugging
-
-Although it is possible to do a reasonable amount of debugging at
-nonzero optimization levels,
-the higher the level the more likely that
-source-level constructs will have been eliminated by optimization.
-For example, if a loop is strength-reduced, the loop
-control variable may be completely eliminated and thus cannot be
-displayed in the debugger.
-This can only happen at @emph{-O2} or @emph{-O3}.
-Explicit temporary variables that you code might be eliminated at
-level @emph{-O1} or higher.
-
-@geindex -g (gcc)
-
-The use of the @emph{-g} switch,
-which is needed for source-level debugging,
-affects the size of the program executable on disk,
-and indeed the debugging information can be quite large.
-However, it has no effect on the generated code (and thus does not
-degrade performance)
-
-Since the compiler generates debugging tables for a compilation unit before
-it performs optimizations, the optimizing transformations may invalidate some
-of the debugging data. You therefore need to anticipate certain
-anomalous situations that may arise while debugging optimized code.
-These are the most common cases:
-
-
-@itemize *
-
-@item
-@emph{The 'hopping Program Counter':} Repeated @cite{step} or @cite{next}
-commands show
-the PC bouncing back and forth in the code. This may result from any of
-the following optimizations:
-
-
-@itemize -
-
-@item
-@emph{Common subexpression elimination:} using a single instance of code for a
-quantity that the source computes several times. As a result you
-may not be able to stop on what looks like a statement.
-
-@item
-@emph{Invariant code motion:} moving an expression that does not change within a
-loop, to the beginning of the loop.
-
-@item
-@emph{Instruction scheduling:} moving instructions so as to
-overlap loads and stores (typically) with other code, or in
-general to move computations of values closer to their uses. Often
-this causes you to pass an assignment statement without the assignment
-happening and then later bounce back to the statement when the
-value is actually needed. Placing a breakpoint on a line of code
-and then stepping over it may, therefore, not always cause all the
-expected side-effects.
-@end itemize
-
-@item
-@emph{The 'big leap':} More commonly known as @emph{cross-jumping}, in which
-two identical pieces of code are merged and the program counter suddenly
-jumps to a statement that is not supposed to be executed, simply because
-it (and the code following) translates to the same thing as the code
-that @emph{was} supposed to be executed. This effect is typically seen in
-sequences that end in a jump, such as a @cite{goto}, a @cite{return}, or
-a @cite{break} in a C @cite{switch} statement.
-
-@item
-@emph{The 'roving variable':} The symptom is an unexpected value in a variable.
-There are various reasons for this effect:
-
-
-@itemize -
-
-@item
-In a subprogram prologue, a parameter may not yet have been moved to its
-'home'.
-
-@item
-A variable may be dead, and its register re-used. This is
-probably the most common cause.
-
-@item
-As mentioned above, the assignment of a value to a variable may
-have been moved.
-
-@item
-A variable may be eliminated entirely by value propagation or
-other means. In this case, GCC may incorrectly generate debugging
-information for the variable
-@end itemize
-
-In general, when an unexpected value appears for a local variable or parameter
-you should first ascertain if that value was actually computed by
-your program, as opposed to being incorrectly reported by the debugger.
-Record fields or
-array elements in an object designated by an access value
-are generally less of a problem, once you have ascertained that the access
-value is sensible.
-Typically, this means checking variables in the preceding code and in the
-calling subprogram to verify that the value observed is explainable from other
-values (one must apply the procedure recursively to those
-other values); or re-running the code and stopping a little earlier
-(perhaps before the call) and stepping to better see how the variable obtained
-the value in question; or continuing to step @emph{from} the point of the
-strange value to see if code motion had simply moved the variable's
-assignments later.
-@end itemize
-
-In light of such anomalies, a recommended technique is to use @emph{-O0}
-early in the software development cycle, when extensive debugging capabilities
-are most needed, and then move to @emph{-O1} and later @emph{-O2} as
-the debugger becomes less critical.
-Whether to use the @emph{-g} switch in the release version is
-a release management issue.
-Note that if you use @emph{-g} you can then use the @emph{strip} program
-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 id34}@anchor{230}@anchor{gnat_ugn/gnat_and_program_execution inlining-of-subprograms}@anchor{114}
-@subsubsection Inlining of Subprograms
-
-
-A call to a subprogram in the current unit is inlined if all the
-following conditions are met:
-
-
-@itemize *
-
-@item
-The optimization level is at least @emph{-O1}.
-
-@item
-The called subprogram is suitable for inlining: It must be small enough
-and not contain something that @emph{gcc} cannot support in inlined
-subprograms.
-
-@geindex pragma Inline
-
-@geindex Inline
-
-@item
-Any one of the following applies: @cite{pragma Inline} is applied to the
-subprogram and the @emph{-gnatn} switch is specified; the
-subprogram is local to the unit and called once from within it; the
-subprogram is small and optimization level @emph{-O2} is specified;
-optimization level @emph{-O3} is specified.
-@end itemize
-
-Calls to subprograms in @emph{with}ed units are normally not inlined.
-To achieve actual inlining (that is, replacement of the call by the code
-in the body of the subprogram), the following conditions must all be true:
-
-
-@itemize *
-
-@item
-The optimization level is at least @emph{-O1}.
-
-@item
-The called subprogram is suitable for inlining: It must be small enough
-and not contain something that @emph{gcc} cannot support in inlined
-subprograms.
-
-@item
-The call appears in a body (not in a package spec).
-
-@item
-There is a @cite{pragma Inline} for the subprogram.
-
-@item
-The @emph{-gnatn} switch is used on the command line.
-@end itemize
-
-Even if all these conditions are met, it may not be possible for
-the compiler to inline the call, due to the length of the body,
-or features in the body that make it impossible for the compiler
-to do the inlining.
-
-Note that specifying the @emph{-gnatn} switch causes additional
-compilation dependencies. Consider the following:
-
-@quotation
-
-@example
-package R is
- procedure Q;
- pragma Inline (Q);
-end R;
-package body R is
- ...
-end R;
-
-with R;
-procedure Main is
-begin
- ...
- R.Q;
-end Main;
-@end example
-@end quotation
-
-With the default behavior (no @emph{-gnatn} switch specified), the
-compilation of the @cite{Main} procedure depends only on its own source,
-@code{main.adb}, and the spec of the package in file @code{r.ads}. This
-means that editing the body of @cite{R} does not require recompiling
-@cite{Main}.
-
-On the other hand, the call @cite{R.Q} is not inlined under these
-circumstances. If the @emph{-gnatn} switch is present when @cite{Main}
-is compiled, the call will be inlined if the body of @cite{Q} is small
-enough, but now @cite{Main} depends on the body of @cite{R} in
-@code{r.adb} as well as on the spec. This means that if this body is edited,
-the main program must be recompiled. Note that this extra dependency
-occurs whether or not the call is in fact inlined by @emph{gcc}.
-
-The use of front end inlining with @emph{-gnatN} generates similar
-additional dependencies.
-
-@geindex -fno-inline (gcc)
-
-Note: The @emph{-fno-inline} switch overrides all other conditions and ensures that
-no inlining occurs, unless requested with pragma Inline_Always for gcc
-back-ends. The extra dependences resulting from @emph{-gnatn} will still be active,
-even if this switch is used to suppress the resulting inlining actions.
-
-@geindex -fno-inline-functions (gcc)
-
-Note: The @emph{-fno-inline-functions} switch can be used to prevent
-automatic inlining of subprograms if @emph{-O3} is used.
-
-@geindex -fno-inline-small-functions (gcc)
-
-Note: The @emph{-fno-inline-small-functions} switch can be used to prevent
-automatic inlining of small subprograms if @emph{-O2} is used.
-
-@geindex -fno-inline-functions-called-once (gcc)
-
-Note: The @emph{-fno-inline-functions-called-once} switch
-can be used to prevent inlining of subprograms local to the unit
-and called once from within it if @emph{-O1} is used.
-
-Note regarding the use of @emph{-O3}: @emph{-gnatn} is made up of two
-sub-switches @emph{-gnatn1} and @emph{-gnatn2} that can be directly
-specified in lieu of it, @emph{-gnatn} being translated into one of them
-based on the optimization level. With @emph{-O2} or below, @emph{-gnatn}
-is equivalent to @emph{-gnatn1} which activates pragma @cite{Inline} with
-moderate inlining across modules. With @emph{-O3}, @emph{-gnatn} is
-equivalent to @emph{-gnatn2} which activates pragma @cite{Inline} with
-full inlining across modules. If you have used pragma @cite{Inline} in
-appropriate cases, then it is usually much better to use @emph{-O2}
-and @emph{-gnatn} and avoid the use of @emph{-O3} which has the additional
-effect of inlining subprograms you did not think should be inlined. We have
-found that the use of @emph{-O3} may slow down the compilation and increase
-the code size by performing excessive inlining, leading to increased
-instruction cache pressure from the increased code size and thus minor
-performance improvements. So the bottom line here is that you should not
-automatically assume that @emph{-O3} is better than @emph{-O2}, and
-indeed you should use @emph{-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 floating-point-operations}@anchor{231}@anchor{gnat_ugn/gnat_and_program_execution id35}@anchor{232}
-@subsubsection Floating_Point_Operations
-
-
-@geindex Floating-Point Operations
-
-On almost all targets, GNAT maps Float and Long_Float to the 32-bit and
-64-bit standard IEEE floating-point representations, and operations will
-use standard IEEE arithmetic as provided by the processor. On most, but
-not all, architectures, the attribute Machine_Overflows is False for these
-types, meaning that the semantics of overflow is implementation-defined.
-In the case of GNAT, these semantics correspond to the normal IEEE
-treatment of infinities and NaN (not a number) values. For example,
-1.0 / 0.0 yields plus infinitiy and 0.0 / 0.0 yields a NaN. By
-avoiding explicit overflow checks, the performance is greatly improved
-on many targets. However, if required, floating-point overflow can be
-enabled by the use of the pragma Check_Float_Overflow.
-
-Another consideration that applies specifically to x86 32-bit
-architectures is which form of floating-point arithmetic is used.
-By default the operations use the old style x86 floating-point,
-which implements an 80-bit extended precision form (on these
-architectures the type Long_Long_Float corresponds to that form).
-In addition, generation of efficient code in this mode means that
-the extended precision form will be used for intermediate results.
-This may be helpful in improving the final precision of a complex
-expression. However it means that the results obtained on the x86
-will be different from those on other architectures, and for some
-algorithms, the extra intermediate precision can be detrimental.
-
-In addition to this old-style floating-point, all modern x86 chips
-implement an alternative floating-point operation model referred
-to as SSE2. In this model there is no extended form, and furthermore
-execution performance is significantly enhanced. To force GNAT to use
-this more modern form, use both of the switches:
-
-@quotation
-
--msse2 -mfpmath=sse
-@end quotation
-
-A unit compiled with these switches will automatically use the more
-efficient SSE2 instruction set for Float and Long_Float operations.
-Note that the ABI has the same form for both floating-point models,
-so it is permissible to mix units compiled with and without these
-switches.
-
-@node Vectorization of loops,Other Optimization Switches,Floating_Point_Operations,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id36}@anchor{233}@anchor{gnat_ugn/gnat_and_program_execution vectorization-of-loops}@anchor{234}
-@subsubsection Vectorization of loops
-
-
-@geindex Optimization Switches
-
-You can take advantage of the auto-vectorizer present in the @emph{gcc}
-back end to vectorize loops with GNAT. The corresponding command line switch
-is @emph{-ftree-vectorize} but, as it is enabled by default at @emph{-O3}
-and other aggressive optimizations helpful for vectorization also are enabled
-by default at this level, using @emph{-O3} directly is recommended.
-
-You also need to make sure that the target architecture features a supported
-SIMD instruction set. For example, for the x86 architecture, you should at
-least specify @emph{-msse2} to get significant vectorization (but you don't
-need to specify it for x86-64 as it is part of the base 64-bit architecture).
-Similarly, for the PowerPC architecture, you should specify @emph{-maltivec}.
-
-The preferred loop form for vectorization is the @cite{for} iteration scheme.
-Loops with a @cite{while} iteration scheme can also be vectorized if they are
-very simple, but the vectorizer will quickly give up otherwise. With either
-iteration scheme, the flow of control must be straight, in particular no
-@cite{exit} statement may appear in the loop body. The loop may however
-contain a single nested loop, if it can be vectorized when considered alone:
-
-@quotation
-
-@example
-A : array (1..4, 1..4) of Long_Float;
-S : array (1..4) of Long_Float;
-
-procedure Sum is
-begin
- for I in A'Range(1) loop
- for J in A'Range(2) loop
- S (I) := S (I) + A (I, J);
- end loop;
- end loop;
-end Sum;
-@end example
-@end quotation
-
-The vectorizable operations depend on the targeted SIMD instruction set, but
-the adding and some of the multiplying operators are generally supported, as
-well as the logical operators for modular types. Note that compiling
-with @emph{-gnatp} might well reveal cases where some checks do thwart
-vectorization.
-
-Type conversions may also prevent vectorization if they involve semantics that
-are not directly supported by the code generator or the SIMD instruction set.
-A typical example is direct conversion from floating-point to integer types.
-The solution in this case is to use the following idiom:
-
-@quotation
-
-@example
-Integer (S'Truncation (F))
-@end example
-@end quotation
-
-if @cite{S} is the subtype of floating-point object @cite{F}.
-
-In most cases, the vectorizable loops are loops that iterate over arrays.
-All kinds of array types are supported, i.e. constrained array types with
-static bounds:
-
-@quotation
-
-@example
-type Array_Type is array (1 .. 4) of Long_Float;
-@end example
-@end quotation
-
-constrained array types with dynamic bounds:
-
-@quotation
-
-@example
-type Array_Type is array (1 .. Q.N) of Long_Float;
-
-type Array_Type is array (Q.K .. 4) of Long_Float;
-
-type Array_Type is array (Q.K .. Q.N) of Long_Float;
-@end example
-@end quotation
-
-or unconstrained array types:
-
-@quotation
-
-@example
-type Array_Type is array (Positive range <>) of Long_Float;
-@end example
-@end quotation
-
-The quality of the generated code decreases when the dynamic aspect of the
-array type increases, the worst code being generated for unconstrained array
-types. This is so because, the less information the compiler has about the
-bounds of the array, the more fallback code it needs to generate in order to
-fix things up at run time.
-
-It is possible to specify that a given loop should be subject to vectorization
-preferably to other optimizations by means of pragma @cite{Loop_Optimize}:
-
-@quotation
-
-@example
-pragma Loop_Optimize (Vector);
-@end example
-@end quotation
-
-placed immediately within the loop will convey the appropriate hint to the
-compiler for this loop.
-
-It is also possible to help the compiler generate better vectorized code
-for a given loop by asserting that there are no loop-carried dependencies
-in the loop. Consider for example the procedure:
-
-@quotation
-
-@example
-type Arr is array (1 .. 4) of Long_Float;
-
-procedure Add (X, Y : not null access Arr; R : not null access Arr) is
-begin
- for I in Arr'Range loop
- R(I) := X(I) + Y(I);
- end loop;
-end;
-@end example
-@end quotation
-
-By default, the compiler cannot unconditionally vectorize the loop because
-assigning to a component of the array designated by R in one iteration could
-change the value read from the components of the array designated by X or Y
-in a later iteration. As a result, the compiler will generate two versions
-of the loop in the object code, one vectorized and the other not vectorized,
-as well as a test to select the appropriate version at run time. This can
-be overcome by another hint:
-
-@quotation
-
-@example
-pragma Loop_Optimize (Ivdep);
-@end example
-@end quotation
-
-placed immediately within the loop will tell the compiler that it can safely
-omit the non-vectorized version of the loop as well as the run-time test.
-
-@node Other Optimization Switches,Optimization and Strict Aliasing,Vectorization of loops,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id37}@anchor{235}@anchor{gnat_ugn/gnat_and_program_execution other-optimization-switches}@anchor{236}
-@subsubsection Other Optimization Switches
-
-
-@geindex Optimization Switches
-
-Since @cite{GNAT} uses the @emph{gcc} back end, all the specialized
-@emph{gcc} optimization switches are potentially usable. These switches
-have not been extensively tested with GNAT but can generally be expected
-to work. Examples of switches in this category are @emph{-funroll-loops}
-and the various target-specific @emph{-m} options (in particular, it has
-been observed that @emph{-march=xxx} can significantly improve performance
-on appropriate machines). For full details of these switches, see
-the @cite{Submodel Options} section in the @cite{Hardware Models and Configurations}
-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{f8}@anchor{gnat_ugn/gnat_and_program_execution id38}@anchor{237}
-@subsubsection Optimization and Strict Aliasing
-
-
-@geindex Aliasing
-
-@geindex Strict Aliasing
-
-@geindex No_Strict_Aliasing
-
-The strong typing capabilities of Ada allow an optimizer to generate
-efficient code in situations where other languages would be forced to
-make worst case assumptions preventing such optimizations. Consider
-the following example:
-
-@quotation
-
-@example
-procedure R is
- type Int1 is new Integer;
- type Int2 is new Integer;
- type Int1A is access Int1;
- type Int2A is access Int2;
- Int1V : Int1A;
- Int2V : Int2A;
- ...
-
-begin
- ...
- for J in Data'Range loop
- if Data (J) = Int1V.all then
- Int2V.all := Int2V.all + 1;
- end if;
- end loop;
- ...
-end R;
-@end example
-@end quotation
-
-In this example, since the variable @cite{Int1V} can only access objects
-of type @cite{Int1}, and @cite{Int2V} can only access objects of type
-@cite{Int2}, there is no possibility that the assignment to
-@cite{Int2V.all} affects the value of @cite{Int1V.all}. This means that
-the compiler optimizer can "know" that the value @cite{Int1V.all} is constant
-for all iterations of the loop and avoid the extra memory reference
-required to dereference it each time through the loop.
-
-This kind of optimization, called strict aliasing analysis, is
-triggered by specifying an optimization level of @emph{-O2} or
-higher or @emph{-Os} and allows @cite{GNAT} to generate more efficient code
-when access values are involved.
-
-However, although this optimization is always correct in terms of
-the formal semantics of the Ada Reference Manual, difficulties can
-arise if features like @cite{Unchecked_Conversion} are used to break
-the typing system. Consider the following complete program example:
-
-@quotation
-
-@example
-package p1 is
- type int1 is new integer;
- type int2 is new integer;
- type a1 is access int1;
- type a2 is access int2;
-end p1;
-
-with p1; use p1;
-package p2 is
- function to_a2 (Input : a1) return a2;
-end p2;
-
-with Unchecked_Conversion;
-package body p2 is
- function to_a2 (Input : a1) return a2 is
- function to_a2u is
- new Unchecked_Conversion (a1, a2);
- begin
- return to_a2u (Input);
- end to_a2;
-end p2;
-
-with p2; use p2;
-with p1; use p1;
-with Text_IO; use Text_IO;
-procedure m is
- v1 : a1 := new int1;
- v2 : a2 := to_a2 (v1);
-begin
- v1.all := 1;
- v2.all := 0;
- put_line (int1'image (v1.all));
-end;
-@end example
-@end quotation
-
-This program prints out 0 in @emph{-O0} or @emph{-O1}
-mode, but it prints out 1 in @emph{-O2} mode. That's
-because in strict aliasing mode, the compiler can and
-does assume that the assignment to @cite{v2.all} could not
-affect the value of @cite{v1.all}, since different types
-are involved.
-
-This behavior is not a case of non-conformance with the standard, since
-the Ada RM specifies that an unchecked conversion where the resulting
-bit pattern is not a correct value of the target type can result in an
-abnormal value and attempting to reference an abnormal value makes the
-execution of a program erroneous. That's the case here since the result
-does not point to an object of type @cite{int2}. This means that the
-effect is entirely unpredictable.
-
-However, although that explanation may satisfy a language
-lawyer, in practice an applications programmer expects an
-unchecked conversion involving pointers to create true
-aliases and the behavior of printing 1 seems plain wrong.
-In this case, the strict aliasing optimization is unwelcome.
-
-Indeed the compiler recognizes this possibility, and the
-unchecked conversion generates a warning:
-
-@quotation
-
-@example
-p2.adb:5:07: warning: possible aliasing problem with type "a2"
-p2.adb:5:07: warning: use -fno-strict-aliasing switch for references
-p2.adb:5:07: warning: or use "pragma No_Strict_Aliasing (a2);"
-@end example
-@end quotation
-
-Unfortunately the problem is recognized when compiling the body of
-package @cite{p2}, but the actual "bad" code is generated while
-compiling the body of @cite{m} and this latter compilation does not see
-the suspicious @cite{Unchecked_Conversion}.
-
-As implied by the warning message, there are approaches you can use to
-avoid the unwanted strict aliasing optimization in a case like this.
-
-One possibility is to simply avoid the use of @emph{-O2}, but
-that is a bit drastic, since it throws away a number of useful
-optimizations that do not involve strict aliasing assumptions.
-
-A less drastic approach is to compile the program using the
-option @emph{-fno-strict-aliasing}. Actually it is only the
-unit containing the dereferencing of the suspicious pointer
-that needs to be compiled. So in this case, if we compile
-unit @cite{m} with this switch, then we get the expected
-value of zero printed. Analyzing which units might need
-the switch can be painful, so a more reasonable approach
-is to compile the entire program with options @emph{-O2}
-and @emph{-fno-strict-aliasing}. If the performance is
-satisfactory with this combination of options, then the
-advantage is that the entire issue of possible "wrong"
-optimization due to strict aliasing is avoided.
-
-To avoid the use of compiler switches, the configuration
-pragma @cite{No_Strict_Aliasing} with no parameters may be
-used to specify that for all access types, the strict
-aliasing optimization should be suppressed.
-
-However, these approaches are still overkill, in that they causes
-all manipulations of all access values to be deoptimized. A more
-refined approach is to concentrate attention on the specific
-access type identified as problematic.
-
-First, if a careful analysis of uses of the pointer shows
-that there are no possible problematic references, then
-the warning can be suppressed by bracketing the
-instantiation of @cite{Unchecked_Conversion} to turn
-the warning off:
-
-@quotation
-
-@example
-pragma Warnings (Off);
-function to_a2u is
- new Unchecked_Conversion (a1, a2);
-pragma Warnings (On);
-@end example
-@end quotation
-
-Of course that approach is not appropriate for this particular
-example, since indeed there is a problematic reference. In this
-case we can take one of two other approaches.
-
-The first possibility is to move the instantiation of unchecked
-conversion to the unit in which the type is declared. In
-this example, we would move the instantiation of
-@cite{Unchecked_Conversion} from the body of package
-@cite{p2} to the spec of package @cite{p1}. Now the
-warning disappears. That's because any use of the
-access type knows there is a suspicious unchecked
-conversion, and the strict aliasing optimization
-is automatically suppressed for the type.
-
-If it is not practical to move the unchecked conversion to the same unit
-in which the destination access type is declared (perhaps because the
-source type is not visible in that unit), you may use pragma
-@cite{No_Strict_Aliasing} for the type. This pragma must occur in the
-same declarative sequence as the declaration of the access type:
-
-@quotation
-
-@example
-type a2 is access int2;
-pragma No_Strict_Aliasing (a2);
-@end example
-@end quotation
-
-Here again, the compiler now knows that the strict aliasing optimization
-should be suppressed for any reference to type @cite{a2} and the
-expected behavior is obtained.
-
-Finally, note that although the compiler can generate warnings for
-simple cases of unchecked conversions, there are tricker and more
-indirect ways of creating type incorrect aliases which the compiler
-cannot detect. Examples are the use of address overlays and unchecked
-conversions involving composite types containing access types as
-components. In such cases, no warnings are generated, but there can
-still be aliasing problems. One safe coding practice is to forbid the
-use of address clauses for type overlaying, and to allow unchecked
-conversion only for primitive types. This is not really a significant
-restriction since any possible desired effect can be achieved by
-unchecked conversion of access values.
-
-The aliasing analysis done in strict aliasing mode can certainly
-have significant benefits. We have seen cases of large scale
-application code where the time is increased by up to 5% by turning
-this optimization off. If you have code that includes significant
-usage of unchecked conversion, you might want to just stick with
-@emph{-O1} and avoid the entire issue. If you get adequate
-performance at this level of optimization level, that's probably
-the safest approach. If tests show that you really need higher
-levels of optimization, then you can experiment with @emph{-O2}
-and @emph{-O2 -fno-strict-aliasing} to see how much effect this
-has on size and speed of the code. If you really need to use
-@emph{-O2} with strict aliasing in effect, then you should
-review any uses of unchecked conversion of access types,
-particularly if you are getting the warnings described above.
-
-@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{238}@anchor{gnat_ugn/gnat_and_program_execution id39}@anchor{239}
-@subsubsection Aliased Variables and Optimization
-
-
-@geindex Aliasing
-
-There are scenarios in which programs may
-use low level techniques to modify variables
-that otherwise might be considered to be unassigned. For example,
-a variable can be passed to a procedure by reference, which takes
-the address of the parameter and uses the address to modify the
-variable's value, even though it is passed as an IN parameter.
-Consider the following example:
-
-@quotation
-
-@example
-procedure P is
- Max_Length : constant Natural := 16;
- type Char_Ptr is access all Character;
-
- procedure Get_String(Buffer: Char_Ptr; Size : Integer);
- pragma Import (C, Get_String, "get_string");
-
- Name : aliased String (1 .. Max_Length) := (others => ' ');
- Temp : Char_Ptr;
-
- function Addr (S : String) return Char_Ptr is
- function To_Char_Ptr is
- new Ada.Unchecked_Conversion (System.Address, Char_Ptr);
- begin
- return To_Char_Ptr (S (S'First)'Address);
- end;
-
-begin
- Temp := Addr (Name);
- Get_String (Temp, Max_Length);
-end;
-@end example
-@end quotation
-
-where Get_String is a C function that uses the address in Temp to
-modify the variable @cite{Name}. This code is dubious, and arguably
-erroneous, and the compiler would be entitled to assume that
-@cite{Name} is never modified, and generate code accordingly.
-
-However, in practice, this would cause some existing code that
-seems to work with no optimization to start failing at high
-levels of optimzization.
-
-What the compiler does for such cases is to assume that marking
-a variable as aliased indicates that some "funny business" may
-be going on. The optimizer recognizes the aliased keyword and
-inhibits optimizations that assume the value cannot be assigned.
-This means that the above example will in fact "work" reliably,
-that is, it will produce the expected results.
-
-@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{23a}@anchor{gnat_ugn/gnat_and_program_execution id40}@anchor{23b}
-@subsubsection Atomic Variables and Optimization
-
-
-@geindex Atomic
-
-There are two considerations with regard to performance when
-atomic variables are used.
-
-First, the RM only guarantees that access to atomic variables
-be atomic, it has nothing to say about how this is achieved,
-though there is a strong implication that this should not be
-achieved by explicit locking code. Indeed GNAT will never
-generate any locking code for atomic variable access (it will
-simply reject any attempt to make a variable or type atomic
-if the atomic access cannot be achieved without such locking code).
-
-That being said, it is important to understand that you cannot
-assume that the entire variable will always be accessed. Consider
-this example:
-
-@quotation
-
-@example
-type R is record
- A,B,C,D : Character;
-end record;
-for R'Size use 32;
-for R'Alignment use 4;
-
-RV : R;
-pragma Atomic (RV);
-X : Character;
-...
-X := RV.B;
-@end example
-@end quotation
-
-You cannot assume that the reference to @cite{RV.B}
-will read the entire 32-bit
-variable with a single load instruction. It is perfectly legitimate if
-the hardware allows it to do a byte read of just the B field. This read
-is still atomic, which is all the RM requires. GNAT can and does take
-advantage of this, depending on the architecture and optimization level.
-Any assumption to the contrary is non-portable and risky. Even if you
-examine the assembly language and see a full 32-bit load, this might
-change in a future version of the compiler.
-
-If your application requires that all accesses to @cite{RV} in this
-example be full 32-bit loads, you need to make a copy for the access
-as in:
-
-@quotation
-
-@example
-declare
- RV_Copy : constant R := RV;
-begin
- X := RV_Copy.B;
-end;
-@end example
-@end quotation
-
-Now the reference to RV must read the whole variable.
-Actually one can imagine some compiler which figures
-out that the whole copy is not required (because only
-the B field is actually accessed), but GNAT
-certainly won't do that, and we don't know of any
-compiler that would not handle this right, and the
-above code will in practice work portably across
-all architectures (that permit the Atomic declaration).
-
-The second issue with atomic variables has to do with
-the possible requirement of generating synchronization
-code. For more details on this, consult the sections on
-the pragmas Enable/Disable_Atomic_Synchronization in the
-GNAT Reference Manual. If performance is critical, and
-such synchronization code is not required, it may be
-useful to disable it.
-
-@node Passive Task Optimization,,Atomic Variables and Optimization,Performance Considerations
-@anchor{gnat_ugn/gnat_and_program_execution id41}@anchor{23c}@anchor{gnat_ugn/gnat_and_program_execution passive-task-optimization}@anchor{23d}
-@subsubsection Passive Task Optimization
-
-
-@geindex Passive Task
-
-A passive task is one which is sufficiently simple that
-in theory a compiler could recognize it an implement it
-efficiently without creating a new thread. The original design
-of Ada 83 had in mind this kind of passive task optimization, but
-only a few Ada 83 compilers attempted it. The problem was that
-it was difficult to determine the exact conditions under which
-the optimization was possible. The result is a very fragile
-optimization where a very minor change in the program can
-suddenly silently make a task non-optimizable.
-
-With the revisiting of this issue in Ada 95, there was general
-agreement that this approach was fundamentally flawed, and the
-notion of protected types was introduced. When using protected
-types, the restrictions are well defined, and you KNOW that the
-operations will be optimized, and furthermore this optimized
-performance is fully portable.
-
-Although it would theoretically be possible for GNAT to attempt to
-do this optimization, but it really doesn't make sense in the
-context of Ada 95, and none of the Ada 95 compilers implement
-this optimization as far as we know. In particular GNAT never
-attempts to perform this optimization.
-
-In any new Ada 95 code that is written, you should always
-use protected types in place of tasks that might be able to
-be optimized in this manner.
-Of course this does not help if you have legacy Ada 83 code
-that depends on this optimization, but it is unusual to encounter
-a case where the performance gains from this optimization
-are significant.
-
-Your program should work correctly without this optimization. If
-you have performance problems, then the most practical
-approach is to figure out exactly where these performance problems
-arise, and update those particular tasks to be protected types. Note
-that typically clients of the tasks who call entries, will not have
-to be modified, only the task definition itself.
-
-@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{23e}@anchor{gnat_ugn/gnat_and_program_execution id42}@anchor{23f}
-@subsection @cite{Text_IO} Suggestions
-
-
-@geindex Text_IO and performance
-
-The @cite{Ada.Text_IO} package has fairly high overheads due in part to
-the requirement of maintaining page and line counts. If performance
-is critical, a recommendation is to use @cite{Stream_IO} instead of
-@cite{Text_IO} for volume output, since this package has less overhead.
-
-If @cite{Text_IO} must be used, note that by default output to the standard
-output and standard error files is unbuffered (this provides better
-behavior when output statements are used for debugging, or if the
-progress of a program is observed by tracking the output, e.g. by
-using the Unix @emph{tail -f} command to watch redirected output.
-
-If you are generating large volumes of output with @cite{Text_IO} and
-performance is an important factor, use a designated file instead
-of the standard output file, or change the standard output file to
-be buffered using @cite{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 id43}@anchor{240}@anchor{gnat_ugn/gnat_and_program_execution reducing-size-of-executables-with-unused-subprogram-data-elimination}@anchor{241}
-@subsection Reducing Size of Executables with Unused Subprogram/Data Elimination
-
-
-@geindex Uunused subprogram/data elimination
-
-This section describes how you can eliminate unused subprograms and data from
-your executable just by setting options at compilation time.
-
-@menu
-* About unused subprogram/data elimination::
-* Compilation options::
-* Example of 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 id44}@anchor{242}@anchor{gnat_ugn/gnat_and_program_execution about-unused-subprogram-data-elimination}@anchor{243}
-@subsubsection About unused subprogram/data elimination
-
-
-By default, an executable contains all code and data of its composing objects
-(directly linked or coming from statically linked libraries), even data or code
-never used by this executable.
-
-This feature will allow you to eliminate such unused code from your
-executable, making it smaller (in disk and in memory).
-
-This functionality is available on all Linux platforms except for the IA-64
-architecture and on all cross platforms using the ELF binary file format.
-In both cases GNU binutils version 2.16 or later are required to enable it.
-
-@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 id45}@anchor{244}@anchor{gnat_ugn/gnat_and_program_execution compilation-options}@anchor{245}
-@subsubsection Compilation options
-
-
-The operation of eliminating the unused code and data from the final executable
-is directly performed by the linker.
-
-@geindex -ffunction-sections (gcc)
-
-@geindex -fdata-sections (gcc)
-
-In order to do this, it has to work with objects compiled with the
-following options:
-@emph{-ffunction-sections} @emph{-fdata-sections}.
-
-These options are usable with C and Ada files.
-They will place respectively each
-function or data in a separate section in the resulting object file.
-
-Once the objects and static libraries are created with these options, the
-linker can perform the dead code elimination. You can do this by setting
-the @emph{-Wl,--gc-sections} option to gcc command or in the
-@emph{-largs} section of @emph{gnatmake}. This will perform a
-garbage collection of code and data never referenced.
-
-If the linker performs a partial link (@emph{-r} linker option), then you
-will need to provide the entry point using the @emph{-e} / @emph{--entry}
-linker option.
-
-Note that objects compiled without the @emph{-ffunction-sections} and
-@emph{-fdata-sections} options can still be linked with the executable.
-However, no dead code elimination will be performed on those objects (they will
-be linked as is).
-
-The GNAT static library is now compiled with -ffunction-sections and
--fdata-sections on some platforms. This allows you to eliminate the unused code
-and data of the GNAT library from your executable.
-
-@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 id46}@anchor{246}@anchor{gnat_ugn/gnat_and_program_execution example-of-unused-subprogram-data-elimination}@anchor{247}
-@subsubsection Example of unused subprogram/data elimination
-
-
-Here is a simple example:
-
-@quotation
-
-@example
-with Aux;
-
-procedure Test is
-begin
- Aux.Used (10);
-end Test;
-
-package Aux is
- Used_Data : Integer;
- Unused_Data : Integer;
-
- procedure Used (Data : Integer);
- procedure Unused (Data : Integer);
-end Aux;
-
-package body Aux is
- procedure Used (Data : Integer) is
- begin
- Used_Data := Data;
- end Used;
-
- procedure Unused (Data : Integer) is
- begin
- Unused_Data := Data;
- end Unused;
-end Aux;
-@end example
-@end quotation
-
-@cite{Unused} and @cite{Unused_Data} are never referenced in this code
-excerpt, and hence they may be safely removed from the final executable.
-
-@quotation
-
-@example
-$ gnatmake test
-
-$ nm test | grep used
-020015f0 T aux__unused
-02005d88 B aux__unused_data
-020015cc T aux__used
-02005d84 B aux__used_data
-
-$ gnatmake test -cargs -fdata-sections -ffunction-sections \\
- -largs -Wl,--gc-sections
-
-$ nm test | grep used
-02005350 T aux__used
-0201ffe0 B aux__used_data
-@end example
-@end quotation
-
-It can be observed that the procedure @cite{Unused} and the object
-@cite{Unused_Data} are removed by the linker when using the
-appropriate options.
-
-@geindex Overflow checks
-
-@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 id54}@anchor{1f3}@anchor{gnat_ugn/gnat_and_program_execution overflow-check-handling-in-gnat}@anchor{29}
-@section Overflow Check Handling in GNAT
-
-
-This section explains how to control the handling of overflow checks.
-
-@menu
-* Background::
-* Overflow Checking Modes in GNAT::
-* Specifying the Desired Mode::
-* Default Settings::
-* Implementation Notes::
-
-@end menu
-
-@node Background,Overflow Checking Modes in GNAT,,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id55}@anchor{248}@anchor{gnat_ugn/gnat_and_program_execution background}@anchor{249}
-@subsection Background
-
-
-Overflow checks are checks that the compiler may make to ensure
-that intermediate results are not out of range. For example:
-
-@quotation
-
-@example
-A : Integer;
-...
-A := A + 1;
-@end example
-@end quotation
-
-If @cite{A} has the value @cite{Integer'Last}, then the addition may cause
-overflow since the result is out of range of the type @cite{Integer}.
-In this case @cite{Constraint_Error} will be raised if checks are
-enabled.
-
-A trickier situation arises in examples like the following:
-
-@quotation
-
-@example
-A, C : Integer;
-...
-A := (A + 1) + C;
-@end example
-@end quotation
-
-where @cite{A} is @cite{Integer'Last} and @cite{C} is @cite{-1}.
-Now the final result of the expression on the right hand side is
-@cite{Integer'Last} which is in range, but the question arises whether the
-intermediate addition of @cite{(A + 1)} raises an overflow error.
-
-The (perhaps surprising) answer is that the Ada language
-definition does not answer this question. Instead it leaves
-it up to the implementation to do one of two things if overflow
-checks are enabled.
-
-
-@itemize *
-
-@item
-raise an exception (@cite{Constraint_Error}), or
-
-@item
-yield the correct mathematical result which is then used in
-subsequent operations.
-@end itemize
-
-If the compiler chooses the first approach, then the assignment of this
-example will indeed raise @cite{Constraint_Error} if overflow checking is
-enabled, or result in erroneous execution if overflow checks are suppressed.
-
-But if the compiler
-chooses the second approach, then it can perform both additions yielding
-the correct mathematical result, which is in range, so no exception
-will be raised, and the right result is obtained, regardless of whether
-overflow checks are suppressed.
-
-Note that in the first example an
-exception will be raised in either case, since if the compiler
-gives the correct mathematical result for the addition, it will
-be out of range of the target type of the assignment, and thus
-fails the range check.
-
-This lack of specified behavior in the handling of overflow for
-intermediate results is a source of non-portability, and can thus
-be problematic when programs are ported. Most typically this arises
-in a situation where the original compiler did not raise an exception,
-and then the application is moved to a compiler where the check is
-performed on the intermediate result and an unexpected exception is
-raised.
-
-Furthermore, when using Ada 2012's preconditions and other
-assertion forms, another issue arises. Consider:
-
-@quotation
-
-@example
-procedure P (A, B : Integer) with
- Pre => A + B <= Integer'Last;
-@end example
-@end quotation
-
-One often wants to regard arithmetic in a context like this from
-a mathematical point of view. So for example, if the two actual parameters
-for a call to @cite{P} are both @cite{Integer'Last}, then
-the precondition should be regarded as False. If we are executing
-in a mode with run-time checks enabled for preconditions, then we would
-like this precondition to fail, rather than raising an exception
-because of the intermediate overflow.
-
-However, the language definition leaves the specification of
-whether the above condition fails (raising @cite{Assert_Error}) or
-causes an intermediate overflow (raising @cite{Constraint_Error})
-up to the implementation.
-
-The situation is worse in a case such as the following:
-
-@quotation
-
-@example
-procedure Q (A, B, C : Integer) with
- Pre => A + B + C <= Integer'Last;
-@end example
-@end quotation
-
-Consider the call
-
-@quotation
-
-@example
-Q (A => Integer'Last, B => 1, C => -1);
-@end example
-@end quotation
-
-From a mathematical point of view the precondition
-is True, but at run time we may (but are not guaranteed to) get an
-exception raised because of the intermediate overflow (and we really
-would prefer this precondition to be considered True at run time).
-
-@node Overflow Checking Modes in GNAT,Specifying the Desired Mode,Background,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id56}@anchor{24a}@anchor{gnat_ugn/gnat_and_program_execution overflow-checking-modes-in-gnat}@anchor{24b}
-@subsection Overflow Checking Modes in GNAT
-
-
-To deal with the portability issue, and with the problem of
-mathematical versus run-time interpretation of the expressions in
-assertions, GNAT provides comprehensive control over the handling
-of intermediate overflow. GNAT can operate in three modes, and
-furthemore, permits separate selection of operating modes for
-the expressions within assertions (here the term 'assertions'
-is used in the technical sense, which includes preconditions and so forth)
-and for expressions appearing outside assertions.
-
-The three modes are:
-
-
-@itemize *
-
-@item
-@emph{Use base type for intermediate operations} (@cite{STRICT})
-
-In this mode, all intermediate results for predefined arithmetic
-operators are computed using the base type, and the result must
-be in range of the base type. If this is not the
-case then either an exception is raised (if overflow checks are
-enabled) or the execution is erroneous (if overflow checks are suppressed).
-This is the normal default mode.
-
-@item
-@emph{Most intermediate overflows avoided} (@cite{MINIMIZED})
-
-In this mode, the compiler attempts to avoid intermediate overflows by
-using a larger integer type, typically @cite{Long_Long_Integer},
-as the type in which arithmetic is
-performed for predefined arithmetic operators. This may be slightly more
-expensive at
-run time (compared to suppressing intermediate overflow checks), though
-the cost is negligible on modern 64-bit machines. For the examples given
-earlier, no intermediate overflows would have resulted in exceptions,
-since the intermediate results are all in the range of
-@cite{Long_Long_Integer} (typically 64-bits on nearly all implementations
-of GNAT). In addition, if checks are enabled, this reduces the number of
-checks that must be made, so this choice may actually result in an
-improvement in space and time behavior.
-
-However, there are cases where @cite{Long_Long_Integer} is not large
-enough, consider the following example:
-
-@quotation
-
-@example
-procedure R (A, B, C, D : Integer) with
- Pre => (A**2 * B**2) / (C**2 * D**2) <= 10;
-@end example
-@end quotation
-
-where @cite{A} = @cite{B} = @cite{C} = @cite{D} = @cite{Integer'Last}.
-Now the intermediate results are
-out of the range of @cite{Long_Long_Integer} even though the final result
-is in range and the precondition is True (from a mathematical point
-of view). In such a case, operating in this mode, an overflow occurs
-for the intermediate computation (which is why this mode
-says @emph{most} intermediate overflows are avoided). In this case,
-an exception is raised if overflow checks are enabled, and the
-execution is erroneous if overflow checks are suppressed.
-
-@item
-@emph{All intermediate overflows avoided} (@cite{ELIMINATED})
-
-In this mode, the compiler avoids all intermediate overflows
-by using arbitrary precision arithmetic as required. In this
-mode, the above example with @cite{A**2 * B**2} would
-not cause intermediate overflow, because the intermediate result
-would be evaluated using sufficient precision, and the result
-of evaluating the precondition would be True.
-
-This mode has the advantage of avoiding any intermediate
-overflows, but at the expense of significant run-time overhead,
-including the use of a library (included automatically in this
-mode) for multiple-precision arithmetic.
-
-This mode provides cleaner semantics for assertions, since now
-the run-time behavior emulates true arithmetic behavior for the
-predefined arithmetic operators, meaning that there is never a
-conflict between the mathematical view of the assertion, and its
-run-time behavior.
-
-Note that in this mode, the behavior is unaffected by whether or
-not overflow checks are suppressed, since overflow does not occur.
-It is possible for gigantic intermediate expressions to raise
-@cite{Storage_Error} as a result of attempting to compute the
-results of such expressions (e.g. @cite{Integer'Last ** Integer'Last})
-but overflow is impossible.
-@end itemize
-
-Note that these modes apply only to the evaluation of predefined
-arithmetic, membership, and comparison operators for signed integer
-aritmetic.
-
-For fixed-point arithmetic, checks can be suppressed. But if checks
-are enabled
-then fixed-point values are always checked for overflow against the
-base type for intermediate expressions (that is such checks always
-operate in the equivalent of @cite{STRICT} mode).
-
-For floating-point, on nearly all architectures, @cite{Machine_Overflows}
-is False, and IEEE infinities are generated, so overflow exceptions
-are never raised. If you want to avoid infinities, and check that
-final results of expressions are in range, then you can declare a
-constrained floating-point type, and range checks will be carried
-out in the normal manner (with infinite values always failing all
-range checks).
-
-@node Specifying the Desired Mode,Default Settings,Overflow Checking Modes in GNAT,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution specifying-the-desired-mode}@anchor{fd}@anchor{gnat_ugn/gnat_and_program_execution id57}@anchor{24c}
-@subsection Specifying the Desired Mode
-
-
-@geindex pragma Overflow_Mode
-
-The desired mode of for handling intermediate overflow can be specified using
-either the @cite{Overflow_Mode} pragma or an equivalent compiler switch.
-The pragma has the form
-
-@quotation
-
-@example
-pragma Overflow_Mode ([General =>] MODE [, [Assertions =>] MODE]);
-@end example
-@end quotation
-
-where @cite{MODE} is one of
-
-
-@itemize *
-
-@item
-@cite{STRICT}: intermediate overflows checked (using base type)
-
-@item
-@cite{MINIMIZED}: minimize intermediate overflows
-
-@item
-@cite{ELIMINATED}: eliminate intermediate overflows
-@end itemize
-
-The case is ignored, so @cite{MINIMIZED}, @cite{Minimized} and
-@cite{minimized} all have the same effect.
-
-If only the @cite{General} parameter is present, then the given @cite{MODE}
-applies
-to expressions both within and outside assertions. If both arguments
-are present, then @cite{General} applies to expressions outside assertions,
-and @cite{Assertions} applies to expressions within assertions. For example:
-
-@quotation
-
-@example
-pragma Overflow_Mode
- (General => Minimized, Assertions => Eliminated);
-@end example
-@end quotation
-
-specifies that general expressions outside assertions be evaluated
-in 'minimize intermediate overflows' mode, and expressions within
-assertions be evaluated in 'eliminate intermediate overflows' mode.
-This is often a reasonable choice, avoiding excessive overhead
-outside assertions, but assuring a high degree of portability
-when importing code from another compiler, while incurring
-the extra overhead for assertion expressions to ensure that
-the behavior at run time matches the expected mathematical
-behavior.
-
-The @cite{Overflow_Mode} pragma has the same scoping and placement
-rules as pragma @cite{Suppress}, so it can occur either as a
-configuration pragma, specifying a default for the whole
-program, or in a declarative scope, where it applies to the
-remaining declarations and statements in that scope.
-
-Note that pragma @cite{Overflow_Mode} does not affect whether
-overflow checks are enabled or suppressed. It only controls the
-method used to compute intermediate values. To control whether
-overflow checking is enabled or suppressed, use pragma @cite{Suppress}
-or @cite{Unsuppress} in the usual manner
-
-@geindex -gnato? (gcc)
-
-@geindex -gnato?? (gcc)
-
-Additionally, a compiler switch @emph{-gnato?} or @emph{-gnato??}
-can be used to control the checking mode default (which can be subsequently
-overridden using pragmas).
-
-Here @code{?} is one of the digits @code{1} through @code{3}:
-
-@quotation
-
-
-@multitable {xxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
-@item
-
-@code{1}
-
-@tab
-
-use base type for intermediate operations (@cite{STRICT})
-
-@item
-
-@code{2}
-
-@tab
-
-minimize intermediate overflows (@cite{MINIMIZED})
-
-@item
-
-@code{3}
-
-@tab
-
-eliminate intermediate overflows (@cite{ELIMINATED})
-
-@end multitable
-
-@end quotation
-
-As with the pragma, if only one digit appears then it applies to all
-cases; if two digits are given, then the first applies outside
-assertions, and the second within assertions. Thus the equivalent
-of the example pragma above would be
-@emph{-gnato23}.
-
-If no digits follow the @emph{-gnato}, then it is equivalent to
-@emph{-gnato11},
-causing all intermediate operations to be computed using the base
-type (@cite{STRICT} mode).
-
-@node Default Settings,Implementation Notes,Specifying the Desired Mode,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution id58}@anchor{24d}@anchor{gnat_ugn/gnat_and_program_execution default-settings}@anchor{24e}
-@subsection Default Settings
-
-
-The default mode for overflow checks is
-
-@quotation
-
-@example
-General => Strict
-@end example
-@end quotation
-
-which causes all computations both inside and outside assertions to use
-the base type. In addition overflow checks are suppressed.
-
-This retains compatibility with previous versions of
-GNAT which suppressed overflow checks by default and always
-used the base type for computation of intermediate results.
-
-@c Sphinx allows no emphasis within :index: role. As a workaround we
-@c point the index to "switch" and use emphasis for "-gnato".
-
-The
-@geindex -gnato (gcc)
-switch @emph{-gnato} (with no digits following)
-is equivalent to
-
-@quotation
-
-@example
-General => Strict
-@end example
-@end quotation
-
-which causes overflow checking of all intermediate overflows
-both inside and outside assertions against the base type.
-This provides compatibility
-with this switch as implemented in previous versions of GNAT.
-
-The pragma @cite{Suppress (Overflow_Check)} disables overflow
-checking, but it has no effect on the method used for computing
-intermediate results.
-
-The pragma @cite{Unsuppress (Overflow_Check)} enables overflow
-checking, but it has no effect on the method used for computing
-intermediate results.
-
-@node Implementation Notes,,Default Settings,Overflow Check Handling in GNAT
-@anchor{gnat_ugn/gnat_and_program_execution implementation-notes}@anchor{24f}@anchor{gnat_ugn/gnat_and_program_execution id59}@anchor{250}
-@subsection Implementation Notes
-
-
-In practice on typical 64-bit machines, the @cite{MINIMIZED} mode is
-reasonably efficient, and can be generally used. It also helps
-to ensure compatibility with code imported from some other
-compiler to GNAT.
-
-Setting all intermediate overflows checking (@cite{CHECKED} mode)
-makes sense if you want to
-make sure that your code is compatible with any other possible
-Ada implementation. This may be useful in ensuring portability
-for code that is to be exported to some other compiler than GNAT.
-
-The Ada standard allows the reassociation of expressions at
-the same precedence level if no parentheses are present. For
-example, @cite{A+B+C} parses as though it were @cite{(A+B)+C}, but
-the compiler can reintepret this as @cite{A+(B+C)}, possibly
-introducing or eliminating an overflow exception. The GNAT
-compiler never takes advantage of this freedom, and the
-expression @cite{A+B+C} will be evaluated as @cite{(A+B)+C}.
-If you need the other order, you can write the parentheses
-explicitly @cite{A+(B+C)} and GNAT will respect this order.
-
-The use of @cite{ELIMINATED} mode will cause the compiler to
-automatically include an appropriate arbitrary precision
-integer arithmetic package. The compiler will make calls
-to this package, though only in cases where it cannot be
-sure that @cite{Long_Long_Integer} is sufficient to guard against
-intermediate overflows. This package does not use dynamic
-alllocation, but it does use the secondary stack, so an
-appropriate secondary stack package must be present (this
-is always true for standard full Ada, but may require
-specific steps for restricted run times such as ZFP).
-
-Although @cite{ELIMINATED} mode causes expressions to use arbitrary
-precision arithmetic, avoiding overflow, the final result
-must be in an appropriate range. This is true even if the
-final result is of type @cite{[Long_[Long_]]Integer'Base}, which
-still has the same bounds as its associated constrained
-type at run-time.
-
-Currently, the @cite{ELIMINATED} mode is only available on target
-platforms for which @cite{Long_Long_Integer} is 64-bits (nearly all GNAT
-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 performing-dimensionality-analysis-in-gnat}@anchor{2a}@anchor{gnat_ugn/gnat_and_program_execution id60}@anchor{1f4}
-@section Performing Dimensionality Analysis in GNAT
-
-
-@geindex Dimensionality analysis
-
-The GNAT compiler supports dimensionality checking. The user can
-specify physical units for objects, and the compiler will verify that uses
-of these objects are compatible with their dimensions, in a fashion that is
-familiar to engineering practice. The dimensions of algebraic expressions
-(including powers with static exponents) are computed from their constituents.
-
-@geindex Dimension_System aspect
-
-@geindex Dimension aspect
-
-This feature depends on Ada 2012 aspect specifications, and is available from
-version 7.0.1 of GNAT onwards.
-The GNAT-specific aspect @cite{Dimension_System}
-allows you to define a system of units; the aspect @cite{Dimension}
-then allows the user to declare dimensioned quantities within a given system.
-(These aspects are described in the @emph{Implementation Defined Aspects}
-chapter of the @emph{GNAT Reference Manual}).
-
-The major advantage of this model is that it does not require the declaration of
-multiple operators for all possible combinations of types: it is only necessary
-to use the proper subtypes in object declarations.
-
-@geindex System.Dim.Mks package (GNAT library)
-
-@geindex MKS_Type type
-
-The simplest way to impose dimensionality checking on a computation is to make
-use of the package @cite{System.Dim.Mks},
-which is part of the GNAT library. This
-package defines a floating-point type @cite{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}.
-
-@quotation
-
-@geindex s-dimmks.ads file
-
-@example
-type Mks_Type is new Long_Long_Float
- with
- Dimension_System => (
- (Unit_Name => Meter, Unit_Symbol => 'm', Dim_Symbol => 'L'),
- (Unit_Name => Kilogram, Unit_Symbol => "kg", Dim_Symbol => 'M'),
- (Unit_Name => Second, Unit_Symbol => 's', Dim_Symbol => 'T'),
- (Unit_Name => Ampere, Unit_Symbol => 'A', Dim_Symbol => 'I'),
- (Unit_Name => Kelvin, Unit_Symbol => 'K', Dim_Symbol => "Theta"),
- (Unit_Name => Mole, Unit_Symbol => "mol", Dim_Symbol => 'N'),
- (Unit_Name => Candela, Unit_Symbol => "cd", Dim_Symbol => 'J'));
-@end example
-@end quotation
-
-The package then defines a series of subtypes that correspond to these
-conventional units. For example:
-
-@quotation
-
-@example
-subtype Length is Mks_Type
- with
- Dimension => (Symbol => 'm', Meter => 1, others => 0);
-@end example
-@end quotation
-
-and similarly for @cite{Mass}, @cite{Time}, @cite{Electric_Current},
-@cite{Thermodynamic_Temperature}, @cite{Amount_Of_Substance}, and
-@cite{Luminous_Intensity} (the standard set of units of the SI system).
-
-The package also defines conventional names for values of each unit, for
-example:
-
-@quotation
-
-@c code-block":: ada
-@c
-@c m : constant Length := 1.0;
-@c kg : constant Mass := 1.0;
-@c s : constant Time := 1.0;
-@c A : constant Electric_Current := 1.0;
-@end quotation
-
-as well as useful multiples of these units:
-
-@quotation
-
-@example
- cm : constant Length := 1.0E-02;
- g : constant Mass := 1.0E-03;
- min : constant Time := 60.0;
- day : constant Time := 60.0 * 24.0 * min;
-...
-@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:
-
-@quotation
-
-@example
-subtype Acceleration is Mks_Type
- with Dimension => ("m/sec^2",
- Meter => 1,
- Second => -2,
- others => 0);
-@end example
-@end quotation
-
-Here is a complete example of use:
-
-@quotation
-
-@example
-with System.Dim.MKS; use System.Dim.Mks;
-with System.Dim.Mks_IO; use System.Dim.Mks_IO;
-with Text_IO; use Text_IO;
-procedure Free_Fall is
- subtype Acceleration is Mks_Type
- with Dimension => ("m/sec^2", 1, 0, -2, others => 0);
- G : constant acceleration := 9.81 * m / (s ** 2);
- T : Time := 10.0*s;
- Distance : Length;
-
-begin
- Put ("Gravitational constant: ");
- Put (G, Aft => 2, Exp => 0); Put_Line ("");
- Distance := 0.5 * G * T ** 2;
- Put ("distance travelled in 10 seconds of free fall ");
- Put (Distance, Aft => 2, Exp => 0);
- Put_Line ("");
-end Free_Fall;
-@end example
-@end quotation
-
-Execution of this program yields:
-
-@quotation
-
-@example
-Gravitational constant: 9.81 m/sec^2
-distance travelled in 10 seconds of free fall 490.50 m
-@end example
-@end quotation
-
-However, incorrect assignments such as:
-
-@quotation
-
-@example
-Distance := 5.0;
-Distance := 5.0 * kg:
-@end example
-@end quotation
-
-are rejected with the following diagnoses:
-
-@quotation
-
-@example
-Distance := 5.0;
- >>> dimensions mismatch in assignment
- >>> left-hand side has dimension [L]
- >>> right-hand side is dimensionless
-
-Distance := 5.0 * kg:
- >>> dimensions mismatch in assignment
- >>> left-hand side has dimension [L]
- >>> right-hand side has dimension [M]
-@end example
-@end quotation
-
-The dimensions of an expression are properly displayed, even if there is
-no explicit subtype for it. If we add to the program:
-
-@quotation
-
-@example
-Put ("Final velocity: ");
-Put (G * T, Aft =>2, Exp =>0);
-Put_Line ("");
-@end example
-@end quotation
-
-then the output includes:
-
-@quotation
-
-@example
-Final velocity: 98.10 m.s**(-1)
-@end example
-@end quotation
-
-@node Stack Related Facilities,Memory Management Issues,Performing Dimensionality Analysis in GNAT,GNAT and Program Execution
-@anchor{gnat_ugn/gnat_and_program_execution id61}@anchor{1f5}@anchor{gnat_ugn/gnat_and_program_execution stack-related-facilities}@anchor{2b}
-@section Stack Related Facilities
-
-
-This section describes some useful tools associated with stack
-checking and analysis. In
-particular, it deals with dynamic and static stack usage measurements.
-
-@menu
-* Stack Overflow Checking::
-* Static Stack Usage Analysis::
-* Dynamic Stack Usage Analysis::
-
-@end menu
-
-@node Stack Overflow Checking,Static Stack Usage Analysis,,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id62}@anchor{251}@anchor{gnat_ugn/gnat_and_program_execution stack-overflow-checking}@anchor{f9}
-@subsection Stack Overflow Checking
-
-
-@geindex Stack Overflow Checking
-
-@geindex -fstack-check (gcc)
-
-For most operating systems, @emph{gcc} does not perform stack overflow
-checking by default. This means that if the main environment task or
-some other task exceeds the available stack space, then unpredictable
-behavior will occur. Most native systems offer some level of protection by
-adding a guard page at the end of each task stack. This mechanism is usually
-not enough for dealing properly with stack overflow situations because
-a large local variable could "jump" above the guard page.
-Furthermore, when the
-guard page is hit, there may not be any space left on the stack for executing
-the exception propagation code. Enabling stack checking avoids
-such situations.
-
-To activate stack checking, compile all units with the gcc option
-@cite{-fstack-check}. For example:
-
-@quotation
-
-@example
-$ gcc -c -fstack-check package1.adb
-@end example
-@end quotation
-
-Units compiled with this option will generate extra instructions to check
-that any use of the stack (for procedure calls or for declaring local
-variables in declare blocks) does not exceed the available stack space.
-If the space is exceeded, then a @cite{Storage_Error} exception is raised.
-
-For declared tasks, the stack size is controlled by the size
-given in an applicable @cite{Storage_Size} pragma or by the value specified
-at bind time with @code{-d} (@ref{123,,Switches for gnatbind}) or is set to
-the default size as defined in the GNAT runtime otherwise.
-
-@geindex GNAT_STACK_LIMIT
-
-For the environment task, the stack size depends on
-system defaults and is unknown to the compiler. Stack checking
-may still work correctly if a fixed
-size stack is allocated, but this cannot be guaranteed.
-To ensure that a clean exception is signalled for stack
-overflow, set the environment variable
-@geindex GNAT_STACK_LIMIT
-@geindex environment variable; GNAT_STACK_LIMIT
-@code{GNAT_STACK_LIMIT} to indicate the maximum
-stack area that can be used, as in:
-
-@quotation
-
-@example
-$ SET GNAT_STACK_LIMIT 1600
-@end example
-@end quotation
-
-The limit is given in kilobytes, so the above declaration would
-set the stack limit of the environment task to 1.6 megabytes.
-Note that the only purpose of this usage is to limit the amount
-of stack used by the environment task. If it is necessary to
-increase the amount of stack for the environment task, then this
-is an operating systems issue, and must be addressed with the
-appropriate operating systems commands.
-
-@node Static Stack Usage Analysis,Dynamic Stack Usage Analysis,Stack Overflow Checking,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution static-stack-usage-analysis}@anchor{fa}@anchor{gnat_ugn/gnat_and_program_execution id63}@anchor{252}
-@subsection Static Stack Usage Analysis
-
-
-@geindex Static Stack Usage Analysis
-
-@geindex -fstack-usage
-
-A unit compiled with @code{-fstack-usage} will generate an extra file
-that specifies
-the maximum amount of stack used, on a per-function basis.
-The file has the same
-basename as the target object file with a @code{.su} extension.
-Each line of this file is made up of three fields:
-
-
-@itemize *
-
-@item
-The name of the function.
-
-@item
-A number of bytes.
-
-@item
-One or more qualifiers: @cite{static}, @cite{dynamic}, @cite{bounded}.
-@end itemize
-
-The second field corresponds to the size of the known part of the function
-frame.
-
-The qualifier @cite{static} means that the function frame size
-is purely static.
-It usually means that all local variables have a static size.
-In this case, the second field is a reliable measure of the function stack
-utilization.
-
-The qualifier @cite{dynamic} means that the function frame size is not static.
-It happens mainly when some local variables have a dynamic size. When this
-qualifier appears alone, the second field is not a reliable measure
-of the function stack analysis. When it is qualified with @cite{bounded}, it
-means that the second field is a reliable maximum of the function stack
-utilization.
-
-A unit compiled with @code{-Wstack-usage} will issue a warning for each
-subprogram whose stack usage might be larger than the specified amount of
-bytes. The wording is in keeping with the qualifier documented above.
-
-@node Dynamic Stack Usage Analysis,,Static Stack Usage Analysis,Stack Related Facilities
-@anchor{gnat_ugn/gnat_and_program_execution id64}@anchor{253}@anchor{gnat_ugn/gnat_and_program_execution dynamic-stack-usage-analysis}@anchor{125}
-@subsection Dynamic Stack Usage Analysis
-
-
-It is possible to measure the maximum amount of stack used by a task, by
-adding a switch to @emph{gnatbind}, as:
-
-@quotation
-
-@example
-$ gnatbind -u0 file
-@end example
-@end quotation
-
-With this option, at each task termination, its stack usage is output on
-@code{stderr}.
-It is not always convenient to output the stack usage when the program
-is still running. Hence, it is possible to delay this output until program
-termination. for a given number of tasks specified as the argument of the
-@code{-u} option. For instance:
-
-@quotation
-
-@example
-$ gnatbind -u100 file
-@end example
-@end quotation
-
-will buffer the stack usage information of the first 100 tasks to terminate and
-output this info at program termination. Results are displayed in four
-columns:
-
-@quotation
-
-@example
-Index | Task Name | Stack Size | Stack Usage
-@end example
-@end quotation
-
-where:
-
-
-@itemize *
-
-@item
-@emph{Index} is a number associated with each task.
-
-@item
-@emph{Task Name} is the name of the task analyzed.
-
-@item
-@emph{Stack Size} is the maximum size for the stack.
-
-@item
-@emph{Stack Usage} is the measure done by the stack analyzer.
-In order to prevent overflow, the stack
-is not entirely analyzed, and it's not possible to know exactly how
-much has actually been used.
-@end itemize
-
-The environment task stack, e.g., the stack that contains the main unit, is
-only processed when the environment variable GNAT_STACK_LIMIT is set.
-
-The package @cite{GNAT.Task_Stack_Usage} provides facilities to get
-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 id65}@anchor{1f6}@anchor{gnat_ugn/gnat_and_program_execution memory-management-issues}@anchor{2c}
-@section Memory Management Issues
-
-
-This section describes some useful memory pools provided in the GNAT library
-and in particular the GNAT Debug Pool facility, which can be used to detect
-incorrect uses of access values (including 'dangling references').
-
-
-@menu
-* Some Useful Memory Pools::
-* The GNAT Debug Pool Facility::
-
-@end menu
-
-@node Some Useful Memory Pools,The GNAT Debug Pool Facility,,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id66}@anchor{254}@anchor{gnat_ugn/gnat_and_program_execution some-useful-memory-pools}@anchor{255}
-@subsection Some Useful Memory Pools
-
-
-@geindex Memory Pool
-
-@geindex storage
-@geindex pool
-
-The @cite{System.Pool_Global} package offers the Unbounded_No_Reclaim_Pool
-storage pool. Allocations use the standard system call @cite{malloc} while
-deallocations use the standard system call @cite{free}. No reclamation is
-performed when the pool goes out of scope. For performance reasons, the
-standard default Ada allocators/deallocators do not use any explicit storage
-pools but if they did, they could use this storage pool without any change in
-behavior. That is why this storage pool is used when the user
-manages to make the default implicit allocator explicit as in this example:
-
-@quotation
-
-@example
-type T1 is access Something;
- -- no Storage pool is defined for T2
-
-type T2 is access Something_Else;
-for T2'Storage_Pool use T1'Storage_Pool;
--- the above is equivalent to
-for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object;
-@end example
-@end quotation
-
-The @cite{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage
-pool. The allocation strategy is similar to @cite{Pool_Local}'s
-except that the all
-storage allocated with this pool is reclaimed when the pool object goes out of
-scope. This pool provides a explicit mechanism similar to the implicit one
-provided by several Ada 83 compilers for allocations performed through a local
-access type and whose purpose was to reclaim memory when exiting the
-scope of a given local access. As an example, the following program does not
-leak memory even though it does not perform explicit deallocation:
-
-@quotation
-
-@example
-with System.Pool_Local;
-procedure Pooloc1 is
- procedure Internal is
- type A is access Integer;
- X : System.Pool_Local.Unbounded_Reclaim_Pool;
- for A'Storage_Pool use X;
- v : A;
- begin
- for I in 1 .. 50 loop
- v := new Integer;
- end loop;
- end Internal;
-begin
- for I in 1 .. 100 loop
- Internal;
- end loop;
-end Pooloc1;
-@end example
-@end quotation
-
-The @cite{System.Pool_Size} package implements the Stack_Bounded_Pool used when
-@cite{Storage_Size} is specified for an access type.
-The whole storage for the pool is
-allocated at once, usually on the stack at the point where the access type is
-elaborated. It is automatically reclaimed when exiting the scope where the
-access type is defined. This package is not intended to be used directly by the
-user and it is implicitly used for each such declaration:
-
-@quotation
-
-@example
-type T1 is access Something;
-for T1'Storage_Size use 10_000;
-@end example
-@end quotation
-
-@node The GNAT Debug Pool Facility,,Some Useful Memory Pools,Memory Management Issues
-@anchor{gnat_ugn/gnat_and_program_execution id67}@anchor{256}@anchor{gnat_ugn/gnat_and_program_execution the-gnat-debug-pool-facility}@anchor{257}
-@subsection The GNAT Debug Pool Facility
-
-
-@geindex Debug Pool
-
-@geindex storage
-@geindex pool
-@geindex memory corruption
-
-The use of unchecked deallocation and unchecked conversion can easily
-lead to incorrect memory references. The problems generated by such
-references are usually difficult to tackle because the symptoms can be
-very remote from the origin of the problem. In such cases, it is
-very helpful to detect the problem as early as possible. This is the
-purpose of the Storage Pool provided by @cite{GNAT.Debug_Pools}.
-
-In order to use the GNAT specific debugging pool, the user must
-associate a debug pool object with each of the access types that may be
-related to suspected memory problems. See Ada Reference Manual 13.11.
-
-@quotation
-
-@example
-type Ptr is access Some_Type;
-Pool : GNAT.Debug_Pools.Debug_Pool;
-for Ptr'Storage_Pool use Pool;
-@end example
-@end quotation
-
-@cite{GNAT.Debug_Pools} is derived from a GNAT-specific kind of
-pool: the @cite{Checked_Pool}. Such pools, like standard Ada storage pools,
-allow the user to redefine allocation and deallocation strategies. They
-also provide a checkpoint for each dereference, through the use of
-the primitive operation @cite{Dereference} which is implicitly called at
-each dereference of an access value.
-
-Once an access type has been associated with a debug pool, operations on
-values of the type may raise four distinct exceptions,
-which correspond to four potential kinds of memory corruption:
-
-
-@itemize *
-
-@item
-@cite{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
-
-@item
-@cite{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
-
-@item
-@cite{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
-
-@item
-@cite{GNAT.Debug_Pools.Freeing_Deallocated_Storage}
-@end itemize
-
-For types associated with a Debug_Pool, dynamic allocation is performed using
-the standard GNAT allocation routine. References to all allocated chunks of
-memory are kept in an internal dictionary. Several deallocation strategies are
-provided, whereupon the user can choose to release the memory to the system,
-keep it allocated for further invalid access checks, or fill it with an easily
-recognizable pattern for debug sessions. The memory pattern is the old IBM
-hexadecimal convention: @cite{16#DEADBEEF#}.
-
-See the documentation in the file g-debpoo.ads for more information on the
-various strategies.
-
-Upon each dereference, a check is made that the access value denotes a
-properly allocated memory location. Here is a complete example of use of
-@cite{Debug_Pools}, that includes typical instances of memory corruption:
-
-@quotation
-
-@example
-with Gnat.Io; use Gnat.Io;
-with Unchecked_Deallocation;
-with Unchecked_Conversion;
-with GNAT.Debug_Pools;
-with System.Storage_Elements;
-with Ada.Exceptions; use Ada.Exceptions;
-procedure Debug_Pool_Test is
-
- type T is access Integer;
- type U is access all T;
-
- P : GNAT.Debug_Pools.Debug_Pool;
- for T'Storage_Pool use P;
-
- procedure Free is new Unchecked_Deallocation (Integer, T);
- function UC is new Unchecked_Conversion (U, T);
- A, B : aliased T;
-
- procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
-
-begin
- Info (P);
- A := new Integer;
- B := new Integer;
- B := A;
- Info (P);
- Free (A);
- begin
- Put_Line (Integer'Image(B.all));
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- begin
- Free (B);
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- B := UC(A'Access);
- begin
- Put_Line (Integer'Image(B.all));
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- begin
- Free (B);
- exception
- when E : others => Put_Line ("raised: " & Exception_Name (E));
- end;
- Info (P);
-end Debug_Pool_Test;
-@end example
-@end quotation
-
-The debug pool mechanism provides the following precise diagnostics on the
-execution of this erroneous program:
-
-@quotation
-
-@example
-Debug Pool info:
- Total allocated bytes : 0
- Total deallocated bytes : 0
- Current Water Mark: 0
- High Water Mark: 0
-
-Debug Pool info:
- Total allocated bytes : 8
- Total deallocated bytes : 0
- Current Water Mark: 8
- High Water Mark: 8
-
-raised: GNAT.DEBUG_POOLS.ACCESSING_DEALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.FREEING_DEALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.ACCESSING_NOT_ALLOCATED_STORAGE
-raised: GNAT.DEBUG_POOLS.FREEING_NOT_ALLOCATED_STORAGE
-Debug Pool info:
- Total allocated bytes : 8
- Total deallocated bytes : 4
- Current Water Mark: 4
- High Water Mark: 8
-@end example
-@end quotation
-
-
-@c -- Non-breaking space in running text
-@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{f}@anchor{gnat_ugn/platform_specific_information doc}@anchor{258}@anchor{gnat_ugn/platform_specific_information id1}@anchor{259}
-@chapter Platform-Specific Information
-
-
-This appendix contains information relating to the implementation
-of run-time libraries on various platforms and also covers
-topics related to the GNAT implementation on Windows and Mac OS.
-
-@menu
-* Run-Time Libraries::
-* Specifying a Run-Time Library::
-* Microsoft Windows Topics::
-* Mac OS Topics::
-
-@end menu
-
-@node Run-Time Libraries,Specifying a Run-Time Library,,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information id2}@anchor{25a}@anchor{gnat_ugn/platform_specific_information run-time-libraries}@anchor{2d}
-@section Run-Time Libraries
-
-
-@geindex Tasking and threads libraries
-
-@geindex Threads libraries and tasking
-
-@geindex Run-time libraries (platform-specific information)
-
-The GNAT run-time implementation may vary with respect to both the
-underlying threads library and the exception handling scheme.
-For threads support, one or more of the following are supplied:
-
-
-@itemize *
-
-@item
-@strong{native threads library}, a binding to the thread package from
-the underlying operating system
-
-@item
-@strong{pthreads library} (Sparc Solaris only), a binding to the Solaris
-POSIX thread package
-@end itemize
-
-For exception handling, either or both of two models are supplied:
-
-@quotation
-
-@geindex Zero-Cost Exceptions
-
-@geindex ZCX (Zero-Cost Exceptions)
-@end quotation
-
-
-@itemize *
-
-@item
-@strong{Zero-Cost Exceptions} ("ZCX"),
-which uses binder-generated tables that
-are interrogated at run time to locate a handler.
-
-@geindex setjmp/longjmp Exception Model
-
-@geindex SJLJ (setjmp/longjmp Exception Model)
-
-@item
-@strong{setjmp / longjmp} ('SJLJ'),
-which uses dynamically-set data to establish
-the set of handlers
-@end itemize
-
-Most programs should experience a substantial speed improvement by
-being compiled with a ZCX run-time.
-This is especially true for
-tasking applications or applications with many exception handlers.@}
-
-This section summarizes which combinations of threads and exception support
-are supplied on various GNAT platforms.
-It then shows how to select a particular library either
-permanently or temporarily,
-explains the properties of (and tradeoffs among) the various threads
-libraries, and provides some additional
-information about several specific platforms.
-
-@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{25b}@anchor{gnat_ugn/platform_specific_information id3}@anchor{25c}
-@subsection Summary of Run-Time Configurations
-
-
-
-@multitable {xxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxx}
-@headitem
-
-Platform
-
-@tab
-
-Run-Time
-
-@tab
-
-Tasking
-
-@tab
-
-Exceptions
-
-@item
-
-ppc-aix
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-native AIX threads
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-native AIX threads
-
-@tab
-
-SJLJ
-
-@item
-
-sparc-solaris
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-native Solaris
-threads library
-
-@tab
-
-ZCX
-
-@item
-
-rts-pthread
-
-@tab
-
-pthread library
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-native Solaris
-threads library
-
-@tab
-
-SJLJ
-
-@item
-
-sparc64-solaris
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-native Solaris
-threads library
-
-@tab
-
-ZCX
-
-@item
-
-x86-linux
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-pthread library
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-pthread library
-
-@tab
-
-SJLJ
-
-@item
-
-x86-lynx
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-native LynxOS threads
-
-@tab
-
-SJLJ
-
-@item
-
-x86-solaris
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-native Solaris
-threads library
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-native Solaris
-threads library
-
-@tab
-
-SJLJ
-
-@item
-
-x86-windows
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-native Win32 threads
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-native Win32 threads
-
-@tab
-
-SJLJ
-
-@item
-
-x86_64-linux
-
-@tab
-
-rts-native
-(default)
-
-@tab
-
-pthread library
-
-@tab
-
-ZCX
-
-@item
-
-rts-sjlj
-
-@tab
-
-pthread library
-
-@tab
-
-SJLJ
-
-@end multitable
-
-
-@node Specifying a Run-Time Library,Microsoft Windows Topics,Run-Time Libraries,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information specifying-a-run-time-library}@anchor{25d}@anchor{gnat_ugn/platform_specific_information id4}@anchor{25e}
-@section Specifying a Run-Time Library
-
-
-The @code{adainclude} subdirectory containing the sources of the GNAT
-run-time library, and the @code{adalib} subdirectory containing the
-@code{ALI} files and the static and/or shared GNAT library, are located
-in the gcc target-dependent area:
-
-@quotation
-
-@example
-target=$prefix/lib/gcc/gcc-*dumpmachine*/gcc-*dumpversion*/
-@end example
-@end quotation
-
-As indicated above, on some platforms several run-time libraries are supplied.
-These libraries are installed in the target dependent area and
-contain a complete source and binary subdirectory. The detailed description
-below explains the differences between the different libraries in terms of
-their thread support.
-
-The default run-time library (when GNAT is installed) is @emph{rts-native}.
-This default run time is selected by the means of soft links.
-For example on x86-linux:
-
-@example
---
--- $(target-dir)
--- |
--- +--- adainclude----------+
--- | |
--- +--- adalib-----------+ |
--- | | |
--- +--- rts-native | |
--- | | | |
--- | +--- adainclude <---+
--- | | |
--- | +--- adalib <----+
--- |
--- +--- rts-sjlj
--- |
--- +--- adainclude
--- |
--- +--- adalib
-@end example
-
-If the @emph{rts-sjlj} library is to be selected on a permanent basis,
-these soft links can be modified with the following commands:
-
-@quotation
-
-@example
-$ cd $target
-$ rm -f adainclude adalib
-$ ln -s rts-sjlj/adainclude adainclude
-$ ln -s rts-sjlj/adalib adalib
-@end example
-@end quotation
-
-Alternatively, you can specify @code{rts-sjlj/adainclude} in the file
-@code{$target/ada_source_path} and @code{rts-sjlj/adalib} in
-@code{$target/ada_object_path}.
-
-@geindex --RTS option
-
-Selecting another run-time library temporarily can be
-achieved by using the @emph{--RTS} switch, e.g., @emph{--RTS=sjlj}
-@anchor{gnat_ugn/platform_specific_information choosing-the-scheduling-policy}@anchor{25f}
-@geindex SCHED_FIFO scheduling policy
-
-@geindex SCHED_RR scheduling policy
-
-@geindex SCHED_OTHER scheduling policy
-
-@menu
-* Choosing the Scheduling Policy::
-* Solaris-Specific Considerations::
-* Solaris Threads Issues::
-* AIX-Specific Considerations::
-
-@end menu
-
-@node Choosing the Scheduling Policy,Solaris-Specific Considerations,,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id5}@anchor{260}
-@subsection Choosing the Scheduling Policy
-
-
-When using a POSIX threads implementation, you have a choice of several
-scheduling policies: @cite{SCHED_FIFO}, @cite{SCHED_RR} and @cite{SCHED_OTHER}.
-
-Typically, the default is @cite{SCHED_OTHER}, while using @cite{SCHED_FIFO}
-or @cite{SCHED_RR} requires special (e.g., root) privileges.
-
-@geindex pragma Time_Slice
-
-@geindex -T0 option
-
-@geindex pragma Task_Dispatching_Policy
-
-By default, GNAT uses the @cite{SCHED_OTHER} policy. To specify
-@cite{SCHED_FIFO},
-you can use one of the following:
-
-
-@itemize *
-
-@item
-@cite{pragma Time_Slice (0.0)}
-
-@item
-the corresponding binder option @emph{-T0}
-
-@item
-@cite{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)}
-@end itemize
-
-To specify @cite{SCHED_RR},
-you should use @cite{pragma Time_Slice} with a
-value greater than 0.0, or else use the corresponding @emph{-T}
-binder option.
-
-@geindex Solaris Sparc threads libraries
-
-@node Solaris-Specific Considerations,Solaris Threads Issues,Choosing the Scheduling Policy,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id6}@anchor{261}@anchor{gnat_ugn/platform_specific_information solaris-specific-considerations}@anchor{262}
-@subsection Solaris-Specific Considerations
-
-
-This section addresses some topics related to the various threads libraries
-on Sparc Solaris.
-
-@geindex rts-pthread threads library
-
-@node Solaris Threads Issues,AIX-Specific Considerations,Solaris-Specific Considerations,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information id7}@anchor{263}@anchor{gnat_ugn/platform_specific_information solaris-threads-issues}@anchor{264}
-@subsection Solaris Threads Issues
-
-
-GNAT under Solaris/Sparc 32 bits comes with an alternate tasking run-time
-library based on POSIX threads --- @emph{rts-pthread}.
-
-@geindex PTHREAD_PRIO_INHERIT policy (under rts-pthread)
-
-@geindex PTHREAD_PRIO_PROTECT policy (under rts-pthread)
-
-@geindex pragma Locking_Policy (under rts-pthread)
-
-@geindex Inheritance_Locking (under rts-pthread)
-
-@geindex Ceiling_Locking (under rts-pthread)
-
-This run-time library has the advantage of being mostly shared across all
-POSIX-compliant thread implementations, and it also provides under
-Solaris 8 the @cite{PTHREAD_PRIO_INHERIT}
-and @cite{PTHREAD_PRIO_PROTECT}
-semantics that can be selected using the predefined pragma
-@cite{Locking_Policy}
-with respectively
-@cite{Inheritance_Locking} and @cite{Ceiling_Locking} as the policy.
-
-As explained above, the native run-time library is based on the Solaris thread
-library (@cite{libthread}) and is the default library.
-
-@geindex GNAT_PROCESSOR environment variable (on Sparc Solaris)
-
-When the Solaris threads library is used (this is the default), programs
-compiled with GNAT can automatically take advantage of
-and can thus execute on multiple processors.
-The user can alternatively specify a processor on which the program should run
-to emulate a single-processor system. The multiprocessor / uniprocessor choice
-is made by
-setting the environment variable
-@geindex GNAT_PROCESSOR
-@geindex environment variable; GNAT_PROCESSOR
-@code{GNAT_PROCESSOR}
-to one of the following:
-
-@quotation
-
-
-@multitable {xxxxxxxxxxxxxxxxxxxxxxxxxxx} {xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx}
-@headitem
-
-@code{GNAT_PROCESSOR} Value
-
-@tab
-
-Effect
-
-@item
-
-@emph{-2}
-
-@tab
-
-Use the default configuration (run the program on all
-available processors) - this is the same as having @cite{GNAT_PROCESSOR}
-unset
-
-@item
-
-@emph{-1}
-
-@tab
-
-Let the run-time implementation choose one processor and run the
-program on that processor
-
-@item
-
-@emph{0 .. Last_Proc}
-
-@tab
-
-Run the program on the specified processor.
-@cite{Last_Proc} is equal to @cite{_SC_NPROCESSORS_CONF - 1}
-(where @cite{_SC_NPROCESSORS_CONF} is a system variable).
-
-@end multitable
-
-@end quotation
-
-@node AIX-Specific Considerations,,Solaris Threads Issues,Specifying a Run-Time Library
-@anchor{gnat_ugn/platform_specific_information aix-specific-considerations}@anchor{265}@anchor{gnat_ugn/platform_specific_information id8}@anchor{266}
-@subsection AIX-Specific Considerations
-
-
-@geindex AIX resolver library
-
-On AIX, the resolver library initializes some internal structure on
-the first call to @cite{get*by*} functions, which are used to implement
-@cite{GNAT.Sockets.Get_Host_By_Name} and
-@cite{GNAT.Sockets.Get_Host_By_Address}.
-If such initialization occurs within an Ada task, and the stack size for
-the task is the default size, a stack overflow may occur.
-
-To avoid this overflow, the user should either ensure that the first call
-to @cite{GNAT.Sockets.Get_Host_By_Name} or
-@cite{GNAT.Sockets.Get_Host_By_Addrss}
-occurs in the environment task, or use @cite{pragma Storage_Size} to
-specify a sufficiently large size for the stack of the task that contains
-this call.
-
-@geindex Windows NT
-
-@geindex Windows 95
-
-@geindex Windows 98
-
-@node Microsoft Windows Topics,Mac OS Topics,Specifying a Run-Time Library,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information microsoft-windows-topics}@anchor{2e}@anchor{gnat_ugn/platform_specific_information id9}@anchor{267}
-@section Microsoft Windows Topics
-
-
-This section describes topics that are specific to the Microsoft Windows
-platforms.
-
-
-
-
-
-@menu
-* Using GNAT on Windows::
-* Using a network installation of GNAT::
-* CONSOLE and WINDOWS subsystems::
-* Temporary Files::
-* 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{268}@anchor{gnat_ugn/platform_specific_information id10}@anchor{269}
-@subsection Using GNAT on Windows
-
-
-One of the strengths of the GNAT technology is that its tool set
-(@emph{gcc}, @emph{gnatbind}, @emph{gnatlink}, @emph{gnatmake}, the
-@cite{gdb} debugger, etc.) is used in the same way regardless of the
-platform.
-
-On Windows this tool set is complemented by a number of Microsoft-specific
-tools that have been provided to facilitate interoperability with Windows
-when this is required. With these tools:
-
-
-@itemize *
-
-@item
-You can build applications using the @cite{CONSOLE} or @cite{WINDOWS}
-subsystems.
-
-@item
-You can use any Dynamically Linked Library (DLL) in your Ada code (both
-relocatable and non-relocatable DLLs are supported).
-
-@item
-You can build Ada DLLs for use in other applications. These applications
-can be written in a language other than Ada (e.g., C, C++, etc). Again both
-relocatable and non-relocatable Ada DLLs are supported.
-
-@item
-You can include Windows resources in your Ada application.
-
-@item
-You can use or create COM/DCOM objects.
-@end itemize
-
-Immediately below are listed all known general GNAT-for-Windows restrictions.
-Other restrictions about specific features like Windows Resources and DLLs
-are listed in separate sections below.
-
-
-@itemize *
-
-@item
-It is not possible to use @cite{GetLastError} and @cite{SetLastError}
-when tasking, protected records, or exceptions are used. In these
-cases, in order to implement Ada semantics, the GNAT run-time system
-calls certain Win32 routines that set the last error variable to 0 upon
-success. It should be possible to use @cite{GetLastError} and
-@cite{SetLastError} when tasking, protected record, and exception
-features are not used, but it is not guaranteed to work.
-
-@item
-It is not possible to link against Microsoft C++ libraries except for
-import libraries. Interfacing must be done by the mean of DLLs.
-
-@item
-It is possible to link against Microsoft C libraries. Yet the preferred
-solution is to use C/C++ compiler that comes with GNAT, since it
-doesn't require having two different development environments and makes the
-inter-language debugging experience smoother.
-
-@item
-When the compilation environment is located on FAT32 drives, users may
-experience recompilations of the source files that have not changed if
-Daylight Saving Time (DST) state has changed since the last time files
-were compiled. NTFS drives do not have this problem.
-
-@item
-No components of the GNAT toolset use any entries in the Windows
-registry. The only entries that can be created are file associations and
-PATH settings, provided the user has chosen to create them at installation
-time, as well as some minimal book-keeping information needed to correctly
-uninstall or integrate different GNAT products.
-@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 id11}@anchor{26a}@anchor{gnat_ugn/platform_specific_information using-a-network-installation-of-gnat}@anchor{26b}
-@subsection Using a network installation of GNAT
-
-
-Make sure the system on which GNAT is installed is accessible from the
-current machine, i.e., the install location is shared over the network.
-Shared resources are accessed on Windows by means of UNC paths, which
-have the format @cite{\\server\sharename\path}
-
-In order to use such a network installation, simply add the UNC path of the
-@code{bin} directory of your GNAT installation in front of your PATH. For
-example, if GNAT is installed in @code{\GNAT} directory of a share location
-called @code{c-drive} on a machine @code{LOKI}, the following command will
-make it available:
-
-@quotation
-
-@example
-$ path \\loki\c-drive\gnat\bin;%path%`
-@end example
-@end quotation
-
-Be aware that every compilation using the network installation results in the
-transfer of large amounts of data across the network and will likely cause
-serious performance penalty.
-
-@node CONSOLE and WINDOWS subsystems,Temporary Files,Using a network installation of GNAT,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id12}@anchor{26c}@anchor{gnat_ugn/platform_specific_information console-and-windows-subsystems}@anchor{26d}
-@subsection CONSOLE and WINDOWS subsystems
-
-
-@geindex CONSOLE Subsystem
-
-@geindex WINDOWS Subsystem
-
-@geindex -mwindows
-
-There are two main subsystems under Windows. The @cite{CONSOLE} subsystem
-(which is the default subsystem) will always create a console when
-launching the application. This is not something desirable when the
-application has a Windows GUI. To get rid of this console the
-application must be using the @cite{WINDOWS} subsystem. To do so
-the @emph{-mwindows} linker option must be specified.
-
-@quotation
-
-@example
-$ gnatmake winprog -largs -mwindows
-@end example
-@end quotation
-
-@node Temporary Files,Mixed-Language Programming on Windows,CONSOLE and WINDOWS subsystems,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information id13}@anchor{26e}@anchor{gnat_ugn/platform_specific_information temporary-files}@anchor{26f}
-@subsection Temporary Files
-
-
-@geindex Temporary files
-
-It is possible to control where temporary files gets created by setting
-the
-@geindex TMP
-@geindex environment variable; TMP
-@code{TMP} environment variable. The file will be created:
-
-
-@itemize *
-
-@item
-Under the directory pointed to by the
-@geindex TMP
-@geindex environment variable; TMP
-@code{TMP} environment variable if
-this directory exists.
-
-@item
-Under @code{c:\temp}, if the
-@geindex TMP
-@geindex environment variable; TMP
-@code{TMP} environment variable is not
-set (or not pointing to a directory) and if this directory exists.
-
-@item
-Under the current working directory otherwise.
-@end itemize
-
-This allows you to determine exactly where the temporary
-file will be created. This is particularly useful in networked
-environments where you may not have write access to some
-directories.
-
-@node Mixed-Language Programming on Windows,Windows Specific Add-Ons,Temporary Files,Microsoft Windows Topics
-@anchor{gnat_ugn/platform_specific_information mixed-language-programming-on-windows}@anchor{270}@anchor{gnat_ugn/platform_specific_information id14}@anchor{271}
-@subsection Mixed-Language Programming on Windows
-
-
-Developing pure Ada applications on Windows is no different than on
-other GNAT-supported platforms. However, when developing or porting an
-application that contains a mix of Ada and C/C++, the choice of your
-Windows C/C++ development environment conditions your overall
-interoperability strategy.
-
-If you use @emph{gcc} or Microsoft C to compile the non-Ada part of
-your application, there are no Windows-specific restrictions that
-affect the overall interoperability with your Ada code. If you do want
-to use the Microsoft tools for your C++ code, you have two choices:
-
-
-@itemize *
-
-@item
-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{272,,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{273,,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{46,,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:
-
-@quotation
-
-@example
-/* main.c */
-extern void adainit (void);
-extern void adafinal (void);
-extern void __gnat_initialize(void*);
-extern void call_to_ada (void);
-
-int main (int argc, char *argv[])
-@{
- int SEH [2];
-
- /* Initialize the SEH context */
- __gnat_initialize (&SEH);
-
- adainit();
-
- /* Then call Ada services in the stand-alone library */
-
- call_to_ada();
-
- adafinal();
-@}
-@end example
-@end quotation
-
-Note that this is not needed on x86_64-windows where the Windows
-native SEH support is used.
-
-@menu
-* Windows Calling Conventions::
-* Introduction to Dynamic Link Libraries (DLLs): Introduction to Dynamic Link Libraries DLLs.
-* Using DLLs with GNAT::
-* Building DLLs with GNAT Project files::
-* Building DLLs with GNAT::
-* Building DLLs with gnatdll::
-* Ada DLLs and Finalization::
-* Creating a Spec for Ada DLLs::
-* GNAT and Windows Resources::
-* Using GNAT DLLs from Microsoft Visual Studio Applications::
-* Debugging a DLL::
-* Setting Stack Size from gnatlink::
-* Setting Heap Size from gnatlink::
-
-@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{274}@anchor{gnat_ugn/platform_specific_information id15}@anchor{275}
-@subsubsection Windows Calling Conventions
-
-
-@geindex Stdcall
-
-@geindex APIENTRY
-
-This section pertain only to Win32. On Win64 there is a single native
-calling convention. All convention specifiers are ignored on this
-platform.
-
-When a subprogram @cite{F} (caller) calls a subprogram @cite{G}
-(callee), there are several ways to push @cite{G}'s parameters on the
-stack and there are several possible scenarios to clean up the stack
-upon @cite{G}'s return. A calling convention is an agreed upon software
-protocol whereby the responsibilities between the caller (@cite{F}) and
-the callee (@cite{G}) are clearly defined. Several calling conventions
-are available for Windows:
-
-
-@itemize *
-
-@item
-@cite{C} (Microsoft defined)
-
-@item
-@cite{Stdcall} (Microsoft defined)
-
-@item
-@cite{Win32} (GNAT specific)
-
-@item
-@cite{DLL} (GNAT specific)
-@end itemize
-
-@menu
-* C Calling Convention::
-* Stdcall Calling Convention::
-* Win32 Calling Convention::
-* DLL Calling Convention::
-
-@end menu
-
-@node C Calling Convention,Stdcall Calling Convention,,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information c-calling-convention}@anchor{276}@anchor{gnat_ugn/platform_specific_information id16}@anchor{277}
-@subsubsection @cite{C} Calling Convention
-
-
-This is the default calling convention used when interfacing to C/C++
-routines compiled with either @emph{gcc} or Microsoft Visual C++.
-
-In the @cite{C} calling convention subprogram parameters are pushed on the
-stack by the caller from right to left. The caller itself is in charge of
-cleaning up the stack after the call. In addition, the name of a routine
-with @cite{C} calling convention is mangled by adding a leading underscore.
-
-The name to use on the Ada side when importing (or exporting) a routine
-with @cite{C} calling convention is the name of the routine. For
-instance the C function:
-
-@quotation
-
-@example
-int get_val (long);
-@end example
-@end quotation
-
-should be imported from Ada as follows:
-
-@quotation
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (C, Get_Val, External_Name => "get_val");
-@end example
-@end quotation
-
-Note that in this particular case the @cite{External_Name} parameter could
-have been omitted since, when missing, this parameter is taken to be the
-name of the Ada entity in lower case. When the @cite{Link_Name} parameter
-is missing, as in the above example, this parameter is set to be the
-@cite{External_Name} with a leading underscore.
-
-When importing a variable defined in C, you should always use the @cite{C}
-calling convention unless the object containing the variable is part of a
-DLL (in which case you should use the @cite{Stdcall} calling
-convention, @ref{278,,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{278}@anchor{gnat_ugn/platform_specific_information id17}@anchor{279}
-@subsubsection @cite{Stdcall} Calling Convention
-
-
-This convention, which was the calling convention used for Pascal
-programs, is used by Microsoft for all the routines in the Win32 API for
-efficiency reasons. It must be used to import any routine for which this
-convention was specified.
-
-In the @cite{Stdcall} calling convention subprogram parameters are pushed
-on the stack by the caller from right to left. The callee (and not the
-caller) is in charge of cleaning the stack on routine exit. In addition,
-the name of a routine with @cite{Stdcall} calling convention is mangled by
-adding a leading underscore (as for the @cite{C} calling convention) and a
-trailing @code{@@@emph{nn}}, where @cite{nn} is the overall size (in
-bytes) of the parameters passed to the routine.
-
-The name to use on the Ada side when importing a C routine with a
-@cite{Stdcall} calling convention is the name of the C routine. The leading
-underscore and trailing @code{@@@emph{nn}} are added automatically by
-the compiler. For instance the Win32 function:
-
-@quotation
-
-@example
-APIENTRY int get_val (long);
-@end example
-@end quotation
-
-should be imported from Ada as follows:
-
-@quotation
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (Stdcall, Get_Val);
--- On the x86 a long is 4 bytes, so the Link_Name is "_get_val@@4"
-@end example
-@end quotation
-
-As for the @cite{C} calling convention, when the @cite{External_Name}
-parameter is missing, it is taken to be the name of the Ada entity in lower
-case. If instead of writing the above import pragma you write:
-
-@quotation
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val");
-@end example
-@end quotation
-
-then the imported routine is @cite{_retrieve_val@@4}. However, if instead
-of specifying the @cite{External_Name} parameter you specify the
-@cite{Link_Name} as in the following example:
-
-@quotation
-
-@example
-function Get_Val (V : Interfaces.C.long) return Interfaces.C.int;
-pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val");
-@end example
-@end quotation
-
-then the imported routine is @cite{retrieve_val}, that is, there is no
-decoration at all. No leading underscore and no Stdcall suffix
-@code{@@@emph{nn}}.
-
-This is especially important as in some special cases a DLL's entry
-point name lacks a trailing @code{@@@emph{nn}} while the exported
-name generated for a call has it.
-
-It is also possible to import variables defined in a DLL by using an
-import pragma for a variable. As an example, if a DLL contains a
-variable defined as:
-
-@quotation
-
-@example
-int my_var;
-@end example
-@end quotation
-
-then, to access this variable from Ada you should write:
-
-@quotation
-
-@example
-My_Var : Interfaces.C.int;
-pragma Import (Stdcall, My_Var);
-@end example
-@end quotation
-
-Note that to ease building cross-platform bindings this convention
-will be handled as a @cite{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 id18}@anchor{27a}@anchor{gnat_ugn/platform_specific_information win32-calling-convention}@anchor{27b}
-@subsubsection @cite{Win32} Calling Convention
-
-
-This convention, which is GNAT-specific is fully equivalent to the
-@cite{Stdcall} calling convention described above.
-
-@node DLL Calling Convention,,Win32 Calling Convention,Windows Calling Conventions
-@anchor{gnat_ugn/platform_specific_information id19}@anchor{27c}@anchor{gnat_ugn/platform_specific_information dll-calling-convention}@anchor{27d}
-@subsubsection @cite{DLL} Calling Convention
-
-
-This convention, which is GNAT-specific is fully equivalent to the
-@cite{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 id20}@anchor{27e}@anchor{gnat_ugn/platform_specific_information introduction-to-dynamic-link-libraries-dlls}@anchor{27f}
-@subsubsection Introduction to Dynamic Link Libraries (DLLs)
-
-
-@geindex DLL
-
-A Dynamically Linked Library (DLL) is a library that can be shared by
-several applications running under Windows. A DLL can contain any number of
-routines and variables.
-
-One advantage of DLLs is that you can change and enhance them without
-forcing all the applications that depend on them to be relinked or
-recompiled. However, you should be aware than all calls to DLL routines are
-slower since, as you will understand below, such calls are indirect.
-
-To illustrate the remainder of this section, suppose that an application
-wants to use the services of a DLL @code{API.dll}. To use the services
-provided by @code{API.dll} you must statically link against the DLL or
-an import library which contains a jump table with an entry for each
-routine and variable exported by the DLL. In the Microsoft world this
-import library is called @code{API.lib}. When using GNAT this import
-library is called either @code{libAPI.dll.a}, @code{libapi.dll.a},
-@code{libAPI.a} or @code{libapi.a} (names are case insensitive).
-
-After you have linked your application with the DLL or the import library
-and you run your application, here is what happens:
-
-
-@itemize *
-
-@item
-Your application is loaded into memory.
-
-@item
-The DLL @code{API.dll} is mapped into the address space of your
-application. This means that:
-
-
-@itemize -
-
-@item
-The DLL will use the stack of the calling thread.
-
-@item
-The DLL will use the virtual address space of the calling process.
-
-@item
-The DLL will allocate memory from the virtual address space of the calling
-process.
-
-@item
-Handles (pointers) can be safely exchanged between routines in the DLL
-routines and routines in the application using the DLL.
-@end itemize
-
-@item
-The entries in the jump table (from the import library @code{libAPI.dll.a}
-or @code{API.lib} or automatically created when linking against a DLL)
-which is part of your application are initialized with the addresses
-of the routines and variables in @code{API.dll}.
-
-@item
-If present in @code{API.dll}, routines @cite{DllMain} or
-@cite{DllMainCRTStartup} are invoked. These routines typically contain
-the initialization code needed for the well-being of the routines and
-variables exported by the DLL.
-@end itemize
-
-There is an additional point which is worth mentioning. In the Windows
-world there are two kind of DLLs: relocatable and non-relocatable
-DLLs. Non-relocatable DLLs can only be loaded at a very specific address
-in the target application address space. If the addresses of two
-non-relocatable DLLs overlap and these happen to be used by the same
-application, a conflict will occur and the application will run
-incorrectly. Hence, when possible, it is always preferable to use and
-build relocatable DLLs. Both relocatable and non-relocatable DLLs are
-supported by GNAT. Note that the @emph{-s} linker option (see GNU Linker
-User's Guide) removes the debugging symbols from the DLL but the DLL can
-still be relocated.
-
-As a side note, an interesting difference between Microsoft DLLs and
-Unix shared libraries, is the fact that on most Unix systems all public
-routines are exported by default in a Unix shared library, while under
-Windows it is possible (but not required) to list exported routines in
-a definition file (see @ref{280,,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 id21}@anchor{281}@anchor{gnat_ugn/platform_specific_information using-dlls-with-gnat}@anchor{272}
-@subsubsection Using DLLs with GNAT
-
-
-To use the services of a DLL, say @code{API.dll}, in your Ada application
-you must have:
-
-
-@itemize *
-
-@item
-The Ada spec for the routines and/or variables you want to access in
-@code{API.dll}. If not available this Ada spec must be built from the C/C++
-header files provided with the DLL.
-
-@item
-The import library (@code{libAPI.dll.a} or @code{API.lib}). As previously
-mentioned an import library is a statically linked library containing the
-import table which will be filled at load time to point to the actual
-@code{API.dll} routines. Sometimes you don't have an import library for the
-DLL you want to use. The following sections will explain how to build
-one. Note that this is optional.
-
-@item
-The actual DLL, @code{API.dll}.
-@end itemize
-
-Once you have all the above, to compile an Ada application that uses the
-services of @code{API.dll} and whose main subprogram is @cite{My_Ada_App},
-you simply issue the command
-
-@quotation
-
-@example
-$ gnatmake my_ada_app -largs -lAPI
-@end example
-@end quotation
-
-The argument @emph{-largs -lAPI} at the end of the @emph{gnatmake} command
-tells the GNAT linker to look for an import library. The linker will
-look for a library name in this specific order:
-
-
-@itemize *
-
-@item
-@code{libAPI.dll.a}
-
-@item
-@code{API.dll.a}
-
-@item
-@code{libAPI.a}
-
-@item
-@code{API.lib}
-
-@item
-@code{libAPI.dll}
-
-@item
-@code{API.dll}
-@end itemize
-
-The first three are the GNU style import libraries. The third is the
-Microsoft style import libraries. The last two are the actual DLL names.
-
-Note that if the Ada package spec for @code{API.dll} contains the
-following pragma
-
-@quotation
-
-@example
-pragma Linker_Options ("-lAPI");
-@end example
-@end quotation
-
-you do not have to add @emph{-largs -lAPI} at the end of the
-@emph{gnatmake} command.
-
-If any one of the items above is missing you will have to create it
-yourself. The following sections explain how to do so using as an
-example a fictitious DLL called @code{API.dll}.
-
-@menu
-* Creating an Ada Spec for the DLL Services::
-* Creating an Import Library::
-
-@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 creating-an-ada-spec-for-the-dll-services}@anchor{282}@anchor{gnat_ugn/platform_specific_information id22}@anchor{283}
-@subsubsection Creating an Ada Spec for the DLL Services
-
-
-A DLL typically comes with a C/C++ header file which provides the
-definitions of the routines and variables exported by the DLL. The Ada
-equivalent of this header file is a package spec that contains definitions
-for the imported entities. If the DLL you intend to use does not come with
-an Ada spec you have to generate one such spec yourself. For example if
-the header file of @code{API.dll} is a file @code{api.h} containing the
-following two definitions:
-
-@quotation
-
-@example
-int some_var;
-int get (char *);
-@end example
-@end quotation
-
-then the equivalent Ada spec could be:
-
-@quotation
-
-@example
-with Interfaces.C.Strings;
-package API is
- use Interfaces;
-
- Some_Var : C.int;
- function Get (Str : C.Strings.Chars_Ptr) return C.int;
-
-private
- pragma Import (C, Get);
- pragma Import (DLL, Some_Var);
-end API;
-@end example
-@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 id23}@anchor{284}@anchor{gnat_ugn/platform_specific_information creating-an-import-library}@anchor{285}
-@subsubsection Creating an Import Library
-
-
-@geindex Import library
-
-If a Microsoft-style import library @code{API.lib} or a GNAT-style
-import library @code{libAPI.dll.a} or @code{libAPI.a} is available
-with @code{API.dll} you can skip this section. You can also skip this
-section if @code{API.dll} or @code{libAPI.dll} is built with GNU tools
-as in this case it is possible to link directly against the
-DLL. Otherwise read on.
-
-@geindex Definition file
-@anchor{gnat_ugn/platform_specific_information the-definition-file}@anchor{280}
-@subsubheading The Definition File
-
-
-As previously mentioned, and unlike Unix systems, the list of symbols
-that are exported from a DLL must be provided explicitly in Windows.
-The main goal of a definition file is precisely that: list the symbols
-exported by a DLL. A definition file (usually a file with a @cite{.def}
-suffix) has the following structure:
-
-@quotation
-
-@example
-[LIBRARY `name`]
-[DESCRIPTION `string`]
-EXPORTS
- `symbol1`
- `symbol2`
- ...
-@end example
-@end quotation
-
-
-@table @asis
-
-@item @emph{LIBRARY `name`}
-
-This section, which is optional, gives the name of the DLL.
-
-@item @emph{DESCRIPTION `string`}
-
-This section, which is optional, gives a description string that will be
-embedded in the import library.
-
-@item @emph{EXPORTS}
-
-This section gives the list of exported symbols (procedures, functions or
-variables). For instance in the case of @code{API.dll} the @cite{EXPORTS}
-section of @code{API.def} looks like:
-
-@example
-EXPORTS
- some_var
- get
-@end example
-@end table
-
-Note that you must specify the correct suffix (@code{@@@emph{nn}})
-(see @ref{274,,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{286}
-@subsubheading Creating a Definition File Automatically
-
-
-You can automatically create the definition file @code{API.def}
-(see @ref{280,,The Definition File}) from a DLL.
-For that use the @cite{dlltool} program as follows:
-
-@quotation
-
-@example
-$ dlltool API.dll -z API.def --export-all-symbols
-@end example
-
-Note that if some routines in the DLL have the @cite{Stdcall} convention
-(@ref{274,,Windows Calling Conventions}) with stripped @code{@@@emph{nn}}
-suffix then you'll have to edit @code{api.def} to add it, and specify
-@emph{-k} to @emph{gnatdll} when creating the import library.
-
-Here are some hints to find the right @code{@@@emph{nn}} suffix.
-
-
-@itemize -
-
-@item
-If you have the Microsoft import library (.lib), it is possible to get
-the right symbols by using Microsoft @cite{dumpbin} tool (see the
-corresponding Microsoft documentation for further details).
-
-@example
-$ dumpbin /exports api.lib
-@end example
-
-@item
-If you have a message about a missing symbol at link time the compiler
-tells you what symbol is expected. You just have to go back to the
-definition file and add the right suffix.
-@end itemize
-@end quotation
-@anchor{gnat_ugn/platform_specific_information gnat-style-import-library}@anchor{287}
-@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 @cite{gnatdll} tool
-(see @ref{288,,Using gnatdll}) as follows:
-
-@quotation
-
-@example
-$ gnatdll -e API.def -d API.dll
-@end example
-
-@cite{gnatdll} takes as input a definition file @code{API.def} and the
-name of the DLL containing the services listed in the definition file
-@code{API.dll}. The name of the static import library generated is
-computed from the name of the definition file as follows: if the
-definition file name is @cite{xyz`}.def`, the import library name will
-be @cite{lib`@w{`}xyz`}.a`. Note that in the previous example option
-@emph{-e} could have been removed because the name of the definition
-file (before the '@cite{.def}' suffix) is the same as the name of the
-DLL (@ref{288,,Using gnatdll} for more information about @cite{gnatdll}).
-@end quotation
-@anchor{gnat_ugn/platform_specific_information msvs-style-import-library}@anchor{289}
-@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{270,,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
-Microsoft's @cite{lib} utility:
-
-@quotation
-
-@example
-$ lib -machine:IX86 -def:API.def -out:API.lib
-@end example
-
-If you use the above command the definition file @code{API.def} must
-contain a line giving the name of the DLL:
-
-@example
-LIBRARY "API"
-@end example
-
-See the Microsoft documentation for further details about the usage of
-@cite{lib}.
-@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 id24}@anchor{28a}@anchor{gnat_ugn/platform_specific_information building-dlls-with-gnat-project-files}@anchor{273}
-@subsubsection Building DLLs with GNAT Project files
-
-
-@geindex DLLs
-@geindex building
-
-There is nothing specific to Windows in the build process.
-@ref{8a,,Library Projects}.
-
-Due to a system limitation, it is not possible under Windows to create threads
-when inside the @cite{DllMain} routine which is used for auto-initialization
-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{28b}@anchor{gnat_ugn/platform_specific_information id25}@anchor{28c}
-@subsubsection Building DLLs with GNAT
-
-
-@geindex DLLs
-@geindex building
-
-This section explain how to build DLLs using the GNAT built-in DLL
-support. With the following procedure it is straight forward to build
-and use DLLs with GNAT.
-
-
-@itemize *
-
-@item
-Building object files.
-The first step is to build all objects files that are to be included
-into the DLL. This is done by using the standard @emph{gnatmake} tool.
-
-@item
-Building the DLL.
-To build the DLL you must use @emph{gcc}'s @emph{-shared} and
-@emph{-shared-libgcc} options. It is quite simple to use this method:
-
-@example
-$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o ...
-@end example
-
-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 @emph{gcc} a definition
-file (see @ref{280,,The Definition File}).
-For example:
-
-@example
-$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o ...
-@end example
-
-If you use a definition file you must export the elaboration procedures
-for every package that required one. Elaboration procedures are named
-using the package name followed by "_E".
-
-@item
-Preparing DLL to be used.
-For the DLL to be used by client programs the bodies must be hidden
-from it and the .ali set with read-only attribute. This is very important
-otherwise GNAT will recompile all packages and will not actually use
-the code in the DLL. For example:
-
-@example
-$ mkdir apilib
-$ copy *.ads *.ali api.dll apilib
-$ attrib +R apilib\\*.ali
-@end example
-@end itemize
-
-At this point it is possible to use the DLL by directly linking
-against it. Note that you must use the GNAT shared runtime when using
-GNAT shared libraries. This is achieved by using @emph{-shared} binder's
-option.
-
-@quotation
-
-@example
-$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
-@end 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{28d}@anchor{gnat_ugn/platform_specific_information id26}@anchor{28e}
-@subsubsection Building DLLs with gnatdll
-
-
-@geindex DLLs
-@geindex building
-
-Note that it is preferred to use GNAT Project files
-(@ref{273,,Building DLLs with GNAT Project files}) or the built-in GNAT
-DLL support (@ref{28b,,Building DLLs with GNAT}) or to build DLLs.
-
-This section explains how to build DLLs containing Ada code using
-@cite{gnatdll}. These DLLs will be referred to as Ada DLLs in the
-remainder of this section.
-
-The steps required to build an Ada DLL that is to be used by Ada as well as
-non-Ada applications are as follows:
-
-
-@itemize *
-
-@item
-You need to mark each Ada @emph{entity} exported by the DLL with a @cite{C} or
-@cite{Stdcall} calling convention to avoid any Ada name mangling for the
-entities exported by the DLL
-(see @ref{28f,,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
-@cite{adainit} generated by @emph{gnatbind} to perform the elaboration of
-the Ada code in the DLL (@ref{290,,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 @cite{adafinal} generated by @emph{gnatbind} to perform the
-finalization of the Ada code in the DLL (@ref{291,,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 spec for the services exported by the Ada DLL in each
-of the programming languages to which you plan to make the DLL available.
-
-@item
-You must provide a definition file listing the exported entities
-(@ref{280,,The Definition File}).
-
-@item
-Finally you must use @cite{gnatdll} to produce the DLL and the import
-library (@ref{288,,Using gnatdll}).
-@end itemize
-
-Note that a relocatable DLL stripped using the @cite{strip}
-binutils tool will not be relocatable anymore. To build a DLL without
-debug information pass @cite{-largs -s} to @cite{gnatdll}. This
-restriction does not apply to a DLL built using a Library Project.
-See @ref{8a,,Library Projects}.
-
-@c Limitations_When_Using_Ada_DLLs_from Ada:
-
-@menu
-* Limitations When Using Ada DLLs from Ada::
-* Exporting Ada Entities::
-* Ada DLLs and Elaboration::
-
-@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{292}
-@subsubsection Limitations When Using Ada DLLs from Ada
-
-
-When using Ada DLLs from Ada applications there is a limitation users
-should be aware of. Because on Windows the GNAT run time is not in a DLL of
-its own, each Ada DLL includes a part of the GNAT run time. Specifically,
-each Ada DLL includes the services of the GNAT run time that are necessary
-to the Ada code inside the DLL. As a result, when an Ada program uses an
-Ada DLL there are two independent GNAT run times: one in the Ada DLL and
-one in the main program.
-
-It is therefore not possible to exchange GNAT run-time objects between the
-Ada DLL and the main Ada program. Example of GNAT run-time objects are file
-handles (e.g., @cite{Text_IO.File_Type}), tasks types, protected objects
-types, etc.
-
-It is completely safe to exchange plain elementary, array or record types,
-Windows object handles, etc.
-
-@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{28f}@anchor{gnat_ugn/platform_specific_information id27}@anchor{293}
-@subsubsection Exporting Ada Entities
-
-
-@geindex Export table
-
-Building a DLL is a way to encapsulate a set of services usable from any
-application. As a result, the Ada entities exported by a DLL should be
-exported with the @cite{C} or @cite{Stdcall} calling conventions to avoid
-any Ada name mangling. As an example here is an Ada package
-@cite{API}, spec and body, exporting two procedures, a function, and a
-variable:
-
-@quotation
-
-@example
-with Interfaces.C; use Interfaces;
-package API is
- Count : C.int := 0;
- function Factorial (Val : C.int) return C.int;
-
- procedure Initialize_API;
- procedure Finalize_API;
- -- Initialization & Finalization routines. More in the next section.
-private
- pragma Export (C, Initialize_API);
- pragma Export (C, Finalize_API);
- pragma Export (C, Count);
- pragma Export (C, Factorial);
-end API;
-@end example
-
-@example
-package body API is
- function Factorial (Val : C.int) return C.int is
- Fact : C.int := 1;
- begin
- Count := Count + 1;
- for K in 1 .. Val loop
- Fact := Fact * K;
- end loop;
- return Fact;
- end Factorial;
-
- procedure Initialize_API is
- procedure Adainit;
- pragma Import (C, Adainit);
- begin
- Adainit;
- end Initialize_API;
-
- procedure Finalize_API is
- procedure Adafinal;
- pragma Import (C, Adafinal);
- begin
- Adafinal;
- end Finalize_API;
-end API;
-@end example
-@end quotation
-
-If the Ada DLL you are building will only be used by Ada applications
-you do not have to export Ada entities with a @cite{C} or @cite{Stdcall}
-convention. As an example, the previous package could be written as
-follows:
-
-@quotation
-
-@example
-package API is
- Count : Integer := 0;
- function Factorial (Val : Integer) return Integer;
-
- procedure Initialize_API;
- procedure Finalize_API;
- -- Initialization and Finalization routines.
-end API;
-@end example
-
-@example
-package body API is
- function Factorial (Val : Integer) return Integer is
- Fact : Integer := 1;
- begin
- Count := Count + 1;
- for K in 1 .. Val loop
- Fact := Fact * K;
- end loop;
- return Fact;
- end Factorial;
-
- ...
- -- The remainder of this package body is unchanged.
-end API;
-@end example
-@end quotation
-
-Note that if you do not export the Ada entities with a @cite{C} or
-@cite{Stdcall} convention you will have to provide the mangled Ada names
-in the definition file of the Ada DLL
-(@ref{294,,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{290}@anchor{gnat_ugn/platform_specific_information id28}@anchor{295}
-@subsubsection Ada DLLs and Elaboration
-
-
-@geindex DLLs and elaboration
-
-The DLL that you are building contains your Ada code as well as all the
-routines in the Ada library that are needed by it. The first thing a
-user of your DLL must do is elaborate the Ada code
-(@ref{11,,Elaboration Order Handling in GNAT}).
-
-To achieve this you must export an initialization routine
-(@cite{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 @cite{adainit} generated by the GNAT binder
-(@ref{ba,,Binding with Non-Ada Main Programs}). See the body of
-@cite{Initialize_Api} for an example. Note that the GNAT binder is
-automatically invoked during the DLL build process by the @cite{gnatdll}
-tool (@ref{288,,Using gnatdll}).
-
-When a DLL is loaded, Windows systematically invokes a routine called
-@cite{DllMain}. It would therefore be possible to call @cite{adainit}
-directly from @cite{DllMain} without having to provide an explicit
-initialization routine. Unfortunately, it is not possible to call
-@cite{adainit} from the @cite{DllMain} if your program has library level
-tasks because access to the @cite{DllMain} entry point is serialized by
-the system (that is, only a single thread can execute 'through' it at a
-time), which means that the GNAT run time will deadlock waiting for the
-newly created task to complete its initialization.
-
-@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 id29}@anchor{296}@anchor{gnat_ugn/platform_specific_information ada-dlls-and-finalization}@anchor{291}
-@subsubsection Ada DLLs and Finalization
-
-
-@geindex DLLs and finalization
-
-When the services of an Ada DLL are no longer needed, the client code should
-invoke the DLL finalization routine, if available. The DLL finalization
-routine is in charge of releasing all resources acquired by the DLL. In the
-case of the Ada code contained in the DLL, this is achieved by calling
-routine @cite{adafinal} generated by the GNAT binder
-(@ref{ba,,Binding with Non-Ada Main Programs}).
-See the body of @cite{Finalize_Api} for an
-example. As already pointed out the GNAT binder is automatically invoked
-during the DLL build process by the @cite{gnatdll} tool
-(@ref{288,,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 id30}@anchor{297}@anchor{gnat_ugn/platform_specific_information creating-a-spec-for-ada-dlls}@anchor{298}
-@subsubsection Creating a Spec for Ada DLLs
-
-
-To use the services exported by the Ada DLL from another programming
-language (e.g., C), you have to translate the specs of the exported Ada
-entities in that language. For instance in the case of @cite{API.dll},
-the corresponding C header file could look like:
-
-@quotation
-
-@example
-extern int *_imp__count;
-#define count (*_imp__count)
-int factorial (int);
-@end example
-@end quotation
-
-It is important to understand that when building an Ada DLL to be used by
-other Ada applications, you need two different specs for the packages
-contained in the DLL: one for building the DLL and the other for using
-the DLL. This is because the @cite{DLL} calling convention is needed to
-use a variable defined in a DLL, but when building the DLL, the variable
-must have either the @cite{Ada} or @cite{C} calling convention. As an
-example consider a DLL comprising the following package @cite{API}:
-
-@quotation
-
-@example
-package API is
- Count : Integer := 0;
- ...
- -- Remainder of the package omitted.
-end API;
-@end example
-@end quotation
-
-After producing a DLL containing package @cite{API}, the spec that
-must be used to import @cite{API.Count} from Ada code outside of the
-DLL is:
-
-@quotation
-
-@example
-package API is
- Count : Integer;
- pragma Import (DLL, Count);
-end API;
-@end example
-@end quotation
-
-@menu
-* Creating the Definition File::
-* Using gnatdll::
-
-@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{294}@anchor{gnat_ugn/platform_specific_information id31}@anchor{299}
-@subsubsection Creating the Definition File
-
-
-The definition file is the last file needed to build the DLL. It lists
-the exported symbols. As an example, the definition file for a DLL
-containing only package @cite{API} (where all the entities are exported
-with a @cite{C} calling convention) is:
-
-@quotation
-
-@example
-EXPORTS
- count
- factorial
- finalize_api
- initialize_api
-@end example
-@end quotation
-
-If the @cite{C} calling convention is missing from package @cite{API},
-then the definition file contains the mangled Ada names of the above
-entities, which in this case are:
-
-@quotation
-
-@example
-EXPORTS
- api__count
- api__factorial
- api__finalize_api
- api__initialize_api
-@end example
-@end quotation
-
-@node Using gnatdll,,Creating the Definition File,Creating a Spec for Ada DLLs
-@anchor{gnat_ugn/platform_specific_information using-gnatdll}@anchor{288}@anchor{gnat_ugn/platform_specific_information id32}@anchor{29a}
-@subsubsection Using @cite{gnatdll}
-
-
-@geindex gnatdll
-
-@cite{gnatdll} is a tool to automate the DLL build process once all the Ada
-and non-Ada sources that make up your DLL have been compiled.
-@cite{gnatdll} is actually in charge of two distinct tasks: build the
-static import library for the DLL and the actual DLL. The form of the
-@cite{gnatdll} command is
-
-@quotation
-
-@example
-$ gnatdll [`switches`] `list-of-files` [-largs `opts`]
-@end example
-@end quotation
-
-where @cite{list-of-files} is a list of ALI and object files. The object
-file list must be the exact list of objects corresponding to the non-Ada
-sources whose services are to be included in the DLL. The ALI file list
-must be the exact list of ALI files for the corresponding Ada sources
-whose services are to be included in the DLL. If @cite{list-of-files} is
-missing, only the static import library is generated.
-
-You may specify any of the following switches to @cite{gnatdll}:
-
-@quotation
-
-@geindex -a (gnatdll)
-@end quotation
-
-
-@table @asis
-
-@item @code{-a[@emph{address}]}
-
-Build a non-relocatable DLL at @cite{address}. If @cite{address} is not
-specified the default address @cite{0x11000000} will be used. By default,
-when this switch is missing, @cite{gnatdll} builds relocatable DLL. We
-advise the reader to build relocatable DLL.
-
-@geindex -b (gnatdll)
-
-@item @code{-b @emph{address}}
-
-Set the relocatable DLL base address. By default the address is
-@cite{0x11000000}.
-
-@geindex -bargs (gnatdll)
-
-@item @code{-bargs @emph{opts}}
-
-Binder options. Pass @cite{opts} to the binder.
-
-@geindex -d (gnatdll)
-
-@item @code{-d @emph{dllfile}}
-
-@cite{dllfile} is the name of the DLL. This switch must be present for
-@cite{gnatdll} to do anything. The name of the generated import library is
-obtained algorithmically from @cite{dllfile} as shown in the following
-example: if @cite{dllfile} is @cite{xyz.dll}, the import library name is
-@cite{libxyz.dll.a}. The name of the definition file to use (if not specified
-by option @emph{-e}) is obtained algorithmically from @cite{dllfile}
-as shown in the following example:
-if @cite{dllfile} is @cite{xyz.dll}, the definition
-file used is @cite{xyz.def}.
-
-@geindex -e (gnatdll)
-
-@item @code{-e @emph{deffile}}
-
-@cite{deffile} is the name of the definition file.
-
-@geindex -g (gnatdll)
-
-@item @code{-g}
-
-Generate debugging information. This information is stored in the object
-file and copied from there to the final DLL file by the linker,
-where it can be read by the debugger. You must use the
-@emph{-g} switch if you plan on using the debugger or the symbolic
-stack traceback.
-
-@geindex -h (gnatdll)
-
-@item @code{-h}
-
-Help mode. Displays @cite{gnatdll} switch usage information.
-
-@geindex -I (gnatdll)
-
-@item @code{-I@emph{dir}}
-
-Direct @cite{gnatdll} to search the @cite{dir} directory for source and
-object files needed to build the DLL.
-(@ref{8e,,Search Paths and the Run-Time Library (RTL)}).
-
-@geindex -k (gnatdll)
-
-@item @code{-k}
-
-Removes the @code{@@@emph{nn}} suffix from the import library's exported
-names, but keeps them for the link names. You must specify this
-option if you want to use a @cite{Stdcall} function in a DLL for which
-the @code{@@@emph{nn}} suffix has been removed. This is the case for most
-of the Windows NT DLL for example. This option has no effect when
-@emph{-n} option is specified.
-
-@geindex -l (gnatdll)
-
-@item @code{-l @emph{file}}
-
-The list of ALI and object files used to build the DLL are listed in
-@cite{file}, instead of being given in the command line. Each line in
-@cite{file} contains the name of an ALI or object file.
-
-@geindex -n (gnatdll)
-
-@item @code{-n}
-
-No Import. Do not create the import library.
-
-@geindex -q (gnatdll)
-
-@item @code{-q}
-
-Quiet mode. Do not display unnecessary messages.
-
-@geindex -v (gnatdll)
-
-@item @code{-v}
-
-Verbose mode. Display extra information.
-
-@geindex -largs (gnatdll)
-
-@item @code{-largs @emph{opts}}
-
-Linker options. Pass @cite{opts} to the linker.
-@end table
-
-@subsubheading @cite{gnatdll} Example
-
-
-As an example the command to build a relocatable DLL from @code{api.adb}
-once @code{api.adb} has been compiled and @code{api.def} created is
-
-@quotation
-
-@example
-$ gnatdll -d api.dll api.ali
-@end example
-@end quotation
-
-The above command creates two files: @code{libapi.dll.a} (the import
-library) and @code{api.dll} (the actual DLL). If you want to create
-only the DLL, just type:
-
-@quotation
-
-@example
-$ gnatdll -d api.dll -n api.ali
-@end example
-@end quotation
-
-Alternatively if you want to create just the import library, type:
-
-@quotation
-
-@example
-$ gnatdll -d api.dll
-@end example
-@end quotation
-
-@subsubheading @cite{gnatdll} behind the Scenes
-
-
-This section details the steps involved in creating a DLL. @cite{gnatdll}
-does these steps for you. Unless you are interested in understanding what
-goes on behind the scenes, you should skip this section.
-
-We use the previous example of a DLL containing the Ada package @cite{API},
-to illustrate the steps necessary to build a DLL. The starting point is a
-set of objects that will make up the DLL and the corresponding ALI
-files. In the case of this example this means that @code{api.o} and
-@code{api.ali} are available. To build a relocatable DLL, @cite{gnatdll} does
-the following:
-
-
-@itemize *
-
-@item
-@cite{gnatdll} builds the base file (@code{api.base}). A base file gives
-the information necessary to generate relocation information for the
-DLL.
-
-@example
-$ gnatbind -n api
-$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base
-@end example
-
-In addition to the base file, the @emph{gnatlink} command generates an
-output file @code{api.jnk} which can be discarded. The @emph{-mdll} switch
-asks @emph{gnatlink} to generate the routines @cite{DllMain} and
-@cite{DllMainCRTStartup} that are called by the Windows loader when the DLL
-is loaded into memory.
-
-@item
-@cite{gnatdll} uses @cite{dlltool} (see @ref{29b,,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.
-
-@example
-$ dlltool --dllname api.dll --def api.def --base-file api.base \\
- --output-exp api.exp
-@end example
-
-@item
-@cite{gnatdll} builds the base file using the new export table. Note that
-@emph{gnatbind} must be called once again since the binder generated file
-has been deleted during the previous call to @emph{gnatlink}.
-
-@example
-$ gnatbind -n api
-$ gnatlink api -o api.jnk api.exp -mdll
- -Wl,--base-file,api.base
-@end example
-
-@item
-@cite{gnatdll} builds the new export table using the new base file and
-generates the DLL import library @code{libAPI.dll.a}.
-
-@example
-$ dlltool --dllname api.dll --def api.def --base-file api.base \\
- --output-exp api.exp --output-lib libAPI.a
-@end example
-
-@item
-Finally @cite{gnatdll} builds the relocatable DLL using the final export
-table.
-
-@example
-$ gnatbind -n api
-$ gnatlink api api.exp -o api.dll -mdll
-@end example
-@end itemize
-@anchor{gnat_ugn/platform_specific_information using-dlltool}@anchor{29b}
-@subsubheading Using @cite{dlltool}
-
-
-@cite{dlltool} is the low-level tool used by @cite{gnatdll} to build
-DLLs and static import libraries. This section summarizes the most
-common @cite{dlltool} switches. The form of the @cite{dlltool} command
-is
-
-@quotation
-
-@example
-$ dlltool [`switches`]
-@end example
-@end quotation
-
-@cite{dlltool} switches include:
-
-@geindex --base-file (dlltool)
-
-
-@table @asis
-
-@item @code{--base-file @emph{basefile}}
-
-Read the base file @cite{basefile} generated by the linker. This switch
-is used to create a relocatable DLL.
-@end table
-
-@geindex --def (dlltool)
-
-
-@table @asis
-
-@item @code{--def @emph{deffile}}
-
-Read the definition file.
-@end table
-
-@geindex --dllname (dlltool)
-
-
-@table @asis
-
-@item @code{--dllname @emph{name}}
-
-Gives the name of the DLL. This switch is used to embed the name of the
-DLL in the static import library generated by @cite{dlltool} with switch
-@emph{--output-lib}.
-@end table
-
-@geindex -k (dlltool)
-
-
-@table @asis
-
-@item @code{-k}
-
-Kill @code{@@@emph{nn}} from exported names
-(@ref{274,,Windows Calling Conventions}
-for a discussion about @cite{Stdcall}-style symbols.
-@end table
-
-@geindex --help (dlltool)
-
-
-@table @asis
-
-@item @code{--help}
-
-Prints the @cite{dlltool} switches with a concise description.
-@end table
-
-@geindex --output-exp (dlltool)
-
-
-@table @asis
-
-@item @code{--output-exp @emph{exportfile}}
-
-Generate an export file @cite{exportfile}. The export file contains the
-export table (list of symbols in the DLL) and is used to create the DLL.
-@end table
-
-@geindex --output-lib (dlltool)
-
-
-@table @asis
-
-@item @code{--output-lib @emph{libfile}}
-
-Generate a static import library @cite{libfile}.
-@end table
-
-@geindex -v (dlltool)
-
-
-@table @asis
-
-@item @code{-v}
-
-Verbose mode.
-@end table
-
-@geindex --as (dlltool)
-
-
-@table @asis
-
-@item @code{--as @emph{assembler-name}}
-
-Use @cite{assembler-name} as the assembler. The default is @cite{as}.
-@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{29c}@anchor{gnat_ugn/platform_specific_information id33}@anchor{29d}
-@subsubsection GNAT and Windows Resources
-
-
-@geindex Resources
-@geindex windows
-
-Resources are an easy way to add Windows specific objects to your
-application. The objects that can be added as resources include:
-
-
-@itemize *
-
-@item
-menus
-
-@item
-accelerators
-
-@item
-dialog boxes
-
-@item
-string tables
-
-@item
-bitmaps
-
-@item
-cursors
-
-@item
-icons
-
-@item
-fonts
-
-@item
-version information
-@end itemize
-
-For example, a version information resource can be defined as follow and
-embedded into an executable or DLL:
-
-A version information resource can be used to embed information into an
-executable or a DLL. These information can be viewed using the file properties
-from the Windows Explorer. Here is an example of a version information
-resource:
-
-@quotation
-
-@example
-1 VERSIONINFO
-FILEVERSION 1,0,0,0
-PRODUCTVERSION 1,0,0,0
-BEGIN
- BLOCK "StringFileInfo"
- BEGIN
- BLOCK "080904E4"
- BEGIN
- VALUE "CompanyName", "My Company Name"
- VALUE "FileDescription", "My application"
- VALUE "FileVersion", "1.0"
- VALUE "InternalName", "my_app"
- VALUE "LegalCopyright", "My Name"
- VALUE "OriginalFilename", "my_app.exe"
- VALUE "ProductName", "My App"
- VALUE "ProductVersion", "1.0"
- END
- END
-
- BLOCK "VarFileInfo"
- BEGIN
- VALUE "Translation", 0x809, 1252
- END
-END
-@end example
-@end quotation
-
-The value @cite{0809} (langID) is for the U.K English language and
-@cite{04E4} (charsetID), which is equal to @cite{1252} decimal, for
-multilingual.
-
-This section explains how to build, compile and use resources. Note that this
-section does not cover all resource objects, for a complete description see
-the corresponding Microsoft documentation.
-
-@menu
-* Building Resources::
-* Compiling Resources::
-* Using Resources::
-
-@end menu
-
-@node Building Resources,Compiling Resources,,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information building-resources}@anchor{29e}@anchor{gnat_ugn/platform_specific_information id34}@anchor{29f}
-@subsubsection Building Resources
-
-
-@geindex Resources
-@geindex building
-
-A resource file is an ASCII file. By convention resource files have an
-@code{.rc} extension.
-The easiest way to build a resource file is to use Microsoft tools
-such as @cite{imagedit.exe} to build bitmaps, icons and cursors and
-@cite{dlgedit.exe} to build dialogs.
-It is always possible to build an @code{.rc} file yourself by writing a
-resource script.
-
-It is not our objective to explain how to write a resource file. A
-complete description of the resource script language can be found in the
-Microsoft documentation.
-
-@node Compiling Resources,Using Resources,Building Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information compiling-resources}@anchor{2a0}@anchor{gnat_ugn/platform_specific_information id35}@anchor{2a1}
-@subsubsection Compiling Resources
-
-
-@geindex rc
-
-@geindex windres
-
-@geindex Resources
-@geindex compiling
-
-This section describes how to build a GNAT-compatible (COFF) object file
-containing the resources. This is done using the Resource Compiler
-@cite{windres} as follows:
-
-@quotation
-
-@example
-$ windres -i myres.rc -o myres.o
-@end example
-@end quotation
-
-By default @cite{windres} will run @emph{gcc} to preprocess the @code{.rc}
-file. You can specify an alternate preprocessor (usually named
-@code{cpp.exe}) using the @cite{windres} @emph{--preprocessor}
-parameter. A list of all possible options may be obtained by entering
-the command @cite{windres} @emph{--help}.
-
-It is also possible to use the Microsoft resource compiler @cite{rc.exe}
-to produce a @code{.res} file (binary resource file). See the
-corresponding Microsoft documentation for further details. In this case
-you need to use @cite{windres} to translate the @code{.res} file to a
-GNAT-compatible object file as follows:
-
-@quotation
-
-@example
-$ windres -i myres.res -o myres.o
-@end example
-@end quotation
-
-@node Using Resources,,Compiling Resources,GNAT and Windows Resources
-@anchor{gnat_ugn/platform_specific_information id36}@anchor{2a2}@anchor{gnat_ugn/platform_specific_information using-resources}@anchor{2a3}
-@subsubsection Using Resources
-
-
-@geindex Resources
-@geindex using
-
-To include the resource file in your program just add the
-GNAT-compatible object file for the resource(s) to the linker
-arguments. With @emph{gnatmake} this is done by using the @emph{-largs}
-option:
-
-@quotation
-
-@example
-$ gnatmake myprog -largs myres.o
-@end example
-@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{2a4}@anchor{gnat_ugn/platform_specific_information using-gnat-dlls-from-microsoft-visual-studio-applications}@anchor{2a5}
-@subsubsection Using GNAT DLLs from Microsoft Visual Studio Applications
-
-
-@geindex Microsoft Visual Studio
-@geindex use with GNAT DLLs
-
-This section describes a common case of mixed GNAT/Microsoft Visual Studio
-application development, where the main program is developed using MSVS, and
-is linked with a DLL developed using GNAT. Such a mixed application should
-be developed following the general guidelines outlined above; below is the
-cookbook-style sequence of steps to follow:
-
-
-@enumerate
-
-@item
-First develop and build the GNAT shared library using a library project
-(let's assume the project is @cite{mylib.gpr}, producing the library @cite{libmylib.dll}):
-@end enumerate
-
-@quotation
-
-@example
-$ gprbuild -p mylib.gpr
-@end example
-@end quotation
-
-
-@enumerate 2
-
-@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{286,,Creating Definition File Automatically}):
-@end enumerate
-
-@quotation
-
-@example
-$ dlltool libmylib.dll -z libmylib.def --export-all-symbols
-@end example
-@end quotation
-
-
-@enumerate 3
-
-@item
-Make sure that MSVS command-line tools are accessible on the path.
-
-@item
-Create the Microsoft-style import library (see @ref{289,,MSVS-Style Import Library}):
-@end enumerate
-
-@quotation
-
-@example
-$ lib -machine:IX86 -def:libmylib.def -out:libmylib.lib
-@end example
-@end quotation
-
-If you are using a 64-bit toolchain, the above becomes...
-
-@quotation
-
-@example
-$ lib -machine:X64 -def:libmylib.def -out:libmylib.lib
-@end example
-@end quotation
-
-
-@enumerate 5
-
-@item
-Build the C main
-@end enumerate
-
-@quotation
-
-@example
-$ cl /O2 /MD main.c libmylib.lib
-@end example
-@end quotation
-
-
-@enumerate 6
-
-@item
-Before running the executable, make sure you have set the PATH to the DLL,
-or copy the DLL into into the directory containing the .exe.
-@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 id37}@anchor{2a6}@anchor{gnat_ugn/platform_specific_information debugging-a-dll}@anchor{2a7}
-@subsubsection Debugging a DLL
-
-
-@geindex DLL debugging
-
-Debugging a DLL is similar to debugging a standard program. But
-we have to deal with two different executable parts: the DLL and the
-program that uses it. We have the following four possibilities:
-
-
-@itemize *
-
-@item
-The program and the DLL are built with @cite{GCC/GNAT}.
-
-@item
-The program is built with foreign tools and the DLL is built with
-@cite{GCC/GNAT}.
-
-@item
-The program is built with @cite{GCC/GNAT} and the DLL is built with
-foreign tools.
-@end itemize
-
-In this section we address only cases one and two above.
-There is no point in trying to debug
-a DLL with @cite{GNU/GDB}, if there is no GDB-compatible debugging
-information in it. To do so you must use a debugger compatible with the
-tools suite used to build the DLL.
-
-@menu
-* Program and DLL Both Built with GCC/GNAT::
-* Program Built with Foreign Tools and DLL Built with GCC/GNAT::
-
-@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 program-and-dll-both-built-with-gcc-gnat}@anchor{2a8}@anchor{gnat_ugn/platform_specific_information id38}@anchor{2a9}
-@subsubsection Program and DLL Both Built with GCC/GNAT
-
-
-This is the simplest case. Both the DLL and the program have @cite{GDB}
-compatible debugging information. It is then possible to break anywhere in
-the process. Let's suppose here that the main procedure is named
-@cite{ada_main} and that in the DLL there is an entry point named
-@cite{ada_dll}.
-
-The DLL (@ref{27f,,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:
-
-
-@itemize *
-
-@item
-Launch @cite{GDB} on the main program.
-
-@example
-$ gdb -nw ada_main
-@end example
-
-@item
-Start the program and stop at the beginning of the main procedure
-
-@example
-(gdb) start
-@end example
-
-This step is required to be able to set a breakpoint inside the DLL. As long
-as the program is not run, the DLL is not loaded. This has the
-consequence that the DLL debugging information is also not loaded, so it is not
-possible to set a breakpoint in the DLL.
-
-@item
-Set a breakpoint inside the DLL
-
-@example
-(gdb) break ada_dll
-(gdb) cont
-@end example
-@end itemize
-
-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{26,,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{2aa}@anchor{gnat_ugn/platform_specific_information id39}@anchor{2ab}
-@subsubsection Program Built with Foreign Tools and DLL Built with GCC/GNAT
-
-
-In this case things are slightly more complex because it is not possible to
-start the main program and then break at the beginning to load the DLL and the
-associated DLL debugging information. It is not possible to break at the
-beginning of the program because there is no @cite{GDB} debugging information,
-and therefore there is no direct way of getting initial control. This
-section addresses this issue by describing some methods that can be used
-to break somewhere in the DLL to debug it.
-
-First suppose that the main procedure is named @cite{main} (this is for
-example some C code built with Microsoft Visual C) and that there is a
-DLL named @cite{test.dll} containing an Ada entry point named
-@cite{ada_dll}.
-
-The DLL (see @ref{27f,,Introduction to Dynamic Link Libraries (DLLs)}) must have
-been built with debugging information (see GNAT @cite{-g} option).
-
-@subsubheading Debugging the DLL Directly
-
-
-
-@itemize *
-
-@item
-Find out the executable starting address
-
-@example
-$ objdump --file-header main.exe
-@end example
-
-The starting address is reported on the last line. For example:
-
-@example
-main.exe: file format pei-i386
-architecture: i386, flags 0x0000010a:
-EXEC_P, HAS_DEBUG, D_PAGED
-start address 0x00401010
-@end example
-
-@item
-Launch the debugger on the executable.
-
-@example
-$ gdb main.exe
-@end example
-
-@item
-Set a breakpoint at the starting address, and launch the program.
-
-@example
-$ (gdb) break *0x00401010
-$ (gdb) run
-@end example
-
-The program will stop at the given address.
-
-@item
-Set a breakpoint on a DLL subroutine.
-
-@example
-(gdb) break ada_dll.adb:45
-@end example
-
-Or if you want to break using a symbol on the DLL, you need first to
-select the Ada language (language used by the DLL).
-
-@example
-(gdb) set language ada
-(gdb) break ada_dll
-@end example
-
-@item
-Continue the program.
-
-@example
-(gdb) cont
-@end example
-
-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{26,,Running and Debugging Ada Programs}).
-@end itemize
-
-It is also possible to debug the DLL by attaching to a running process.
-
-@subsubheading Attaching to a Running Process
-
-
-@geindex DLL debugging
-@geindex attach to process
-
-With @cite{GDB} it is always possible to debug a running process by
-attaching to it. It is possible to debug a DLL this way. The limitation
-of this approach is that the DLL must run long enough to perform the
-attach operation. It may be useful for instance to insert a time wasting
-loop in the code of the DLL to meet this criterion.
-
-
-@itemize *
-
-@item
-Launch the main program @code{main.exe}.
-
-@example
-$ main
-@end example
-
-@item
-Use the Windows @emph{Task Manager} to find the process ID. Let's say
-that the process PID for @code{main.exe} is 208.
-
-@item
-Launch gdb.
-
-@example
-$ gdb
-@end example
-
-@item
-Attach to the running process to be debugged.
-
-@example
-(gdb) attach 208
-@end example
-
-@item
-Load the process debugging information.
-
-@example
-(gdb) symbol-file main.exe
-@end example
-
-@item
-Break somewhere in the DLL.
-
-@example
-(gdb) break ada_dll
-@end example
-
-@item
-Continue process execution.
-
-@example
-(gdb) cont
-@end example
-@end itemize
-
-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{26,,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{13a}@anchor{gnat_ugn/platform_specific_information id40}@anchor{2ac}
-@subsubsection Setting Stack Size from @emph{gnatlink}
-
-
-It is possible to specify the program stack size at link time. On modern
-versions of Windows, starting with XP, this is mostly useful to set the size of
-the main stack (environment task). The other task stacks are set with pragma
-Storage_Size or with the @emph{gnatbind -d} command.
-
-Since older versions of Windows (2000, NT4, etc.) do not allow setting the
-reserve size of individual tasks, the link-time stack size applies to all
-tasks, and pragma Storage_Size has no effect.
-In particular, Stack Overflow checks are made against this
-link-time specified size.
-
-This setting can be done with @emph{gnatlink} using either of the following:
-
-
-@itemize *
-
-@item
-@emph{-Xlinker} linker option
-
-@example
-$ gnatlink hello -Xlinker --stack=0x10000,0x1000
-@end example
-
-This sets the stack reserve size to 0x10000 bytes and the stack commit
-size to 0x1000 bytes.
-
-@item
-@emph{-Wl} linker option
-
-@example
-$ gnatlink hello -Wl,--stack=0x1000000
-@end example
-
-This sets the stack reserve size to 0x1000000 bytes. Note that with
-@emph{-Wl} option it is not possible to set the stack commit size
-because the coma is a separator for this option.
-@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{13b}@anchor{gnat_ugn/platform_specific_information id41}@anchor{2ad}
-@subsubsection Setting Heap Size from @emph{gnatlink}
-
-
-Under Windows systems, it is possible to specify the program heap size from
-@emph{gnatlink} using either of the following:
-
-
-@itemize *
-
-@item
-@emph{-Xlinker} linker option
-
-@example
-$ gnatlink hello -Xlinker --heap=0x10000,0x1000
-@end example
-
-This sets the heap reserve size to 0x10000 bytes and the heap commit
-size to 0x1000 bytes.
-
-@item
-@emph{-Wl} linker option
-
-@example
-$ gnatlink hello -Wl,--heap=0x1000000
-@end example
-
-This sets the heap reserve size to 0x1000000 bytes. Note that with
-@emph{-Wl} option it is not possible to set the heap commit size
-because the coma is a separator for this option.
-@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{2ae}@anchor{gnat_ugn/platform_specific_information win32-specific-addons}@anchor{2af}
-@subsection Windows Specific Add-Ons
-
-
-This section describes the Windows specific add-ons.
-
-@menu
-* Win32Ada::
-* wPOSIX::
-
-@end menu
-
-@node Win32Ada,wPOSIX,,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information win32ada}@anchor{2b0}@anchor{gnat_ugn/platform_specific_information id42}@anchor{2b1}
-@subsubsection Win32Ada
-
-
-Win32Ada is a binding for the Microsoft Win32 API. This binding can be
-easily installed from the provided installer. To use the Win32Ada
-binding you need to use a project file, and adding a single with_clause
-will give you full access to the Win32Ada binding sources and ensure
-that the proper libraries are passed to the linker.
-
-@quotation
-
-@example
-with "win32ada";
-project P is
- for Sources use ...;
-end P;
-@end example
-@end quotation
-
-To build the application you just need to call gprbuild for the
-application's project, here p.gpr:
-
-@quotation
-
-@example
-gprbuild p.gpr
-@end example
-@end quotation
-
-@node wPOSIX,,Win32Ada,Windows Specific Add-Ons
-@anchor{gnat_ugn/platform_specific_information id43}@anchor{2b2}@anchor{gnat_ugn/platform_specific_information wposix}@anchor{2b3}
-@subsubsection wPOSIX
-
-
-wPOSIX is a minimal POSIX binding whose goal is to help with building
-cross-platforms applications. This binding is not complete though, as
-the Win32 API does not provide the necessary support for all POSIX APIs.
-
-To use the wPOSIX binding you need to use a project file, and adding
-a single with_clause will give you full access to the wPOSIX binding
-sources and ensure that the proper libraries are passed to the linker.
-
-@quotation
-
-@example
-with "wposix";
-project P is
- for Sources use ...;
-end P;
-@end example
-@end quotation
-
-To build the application you just need to call gprbuild for the
-application's project, here p.gpr:
-
-@quotation
-
-@example
-gprbuild p.gpr
-@end example
-@end quotation
-
-@node Mac OS Topics,,Microsoft Windows Topics,Platform-Specific Information
-@anchor{gnat_ugn/platform_specific_information mac-os-topics}@anchor{2f}@anchor{gnat_ugn/platform_specific_information id44}@anchor{2b4}
-@section Mac OS Topics
-
-
-@geindex OS X
-
-This section describes topics that are specific to Apple's OS X
-platform.
-
-@menu
-* Codesigning the Debugger::
-
-@end menu
-
-@node Codesigning the Debugger,,,Mac OS Topics
-@anchor{gnat_ugn/platform_specific_information codesigning-the-debugger}@anchor{2b5}
-@subsection Codesigning the Debugger
-
-
-The Darwin Kernel requires the debugger to have special permissions
-before it is allowed to control other processes. These permissions
-are granted by codesigning the GDB executable. Without these
-permissions, the debugger will report error messages such as:
-
-@example
-Starting program: /x/y/foo
-Unable to find Mach task port for process-id 28885: (os/kern) failure (0x5).
-(please check gdb is codesigned - see taskgated(8))
-@end example
-
-Codesigning requires a certificate. The following procedure explains
-how to create one:
-
-
-@itemize *
-
-@item
-Start the Keychain Access application (in
-/Applications/Utilities/Keychain Access.app)
-
-@item
-Select the Keychain Access -> Certificate Assistant ->
-Create a Certificate... menu
-
-@item
-Then:
-
-
-@itemize *
-
-@item
-Choose a name for the new certificate (this procedure will use
-"gdb-cert" as an example)
-
-@item
-Set "Identity Type" to "Self Signed Root"
-
-@item
-Set "Certificate Type" to "Code Signing"
-
-@item
-Activate the "Let me override defaults" option
-@end itemize
-
-@item
-Click several times on "Continue" until the "Specify a Location
-For The Certificate" screen appears, then set "Keychain" to "System"
-
-@item
-Click on "Continue" until the certificate is created
-
-@item
-Finally, in the view, double-click on the new certificate,
-and set "When using this certificate" to "Always Trust"
-
-@item
-Exit the Keychain Access application and restart the computer
-(this is unfortunately required)
-@end itemize
-
-Once a certificate has been created, the debugger can be codesigned
-as follow. In a Terminal, run the following command:
-
-@quotation
-
-@example
-$ codesign -f -s "gdb-cert" <gnat_install_prefix>/bin/gdb
-@end example
-@end quotation
-
-where "gdb-cert" should be replaced by the actual certificate
-name chosen above, and <gnat_install_prefix> should be replaced by
-the location where you installed GNAT. Also, be sure that users are
-in the Unix group @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{10}@anchor{gnat_ugn/example_of_binder_output doc}@anchor{2b6}@anchor{gnat_ugn/example_of_binder_output id1}@anchor{2b7}
-@chapter Example of Binder Output File
-
-
-@geindex Binder output (example)
-
-This Appendix displays the source code for the output file
-generated by @emph{gnatbind} for a simple 'Hello World' program.
-Comments have been added for clarification purposes.
-
-@example
--- The package is called Ada_Main unless this name is actually used
--- as a unit name in the partition, in which case some other unique
--- name is used.
-
-pragma Ada_95;
-with System;
-package ada_main is
- pragma Warnings (Off);
-
- -- The main program saves the parameters (argument count,
- -- argument values, environment pointer) in global variables
- -- for later access by other units including
- -- Ada.Command_Line.
-
- gnat_argc : Integer;
- gnat_argv : System.Address;
- gnat_envp : System.Address;
-
- -- The actual variables are stored in a library routine. This
- -- is useful for some shared library situations, where there
- -- are problems if variables are not in the library.
-
- pragma Import (C, gnat_argc);
- pragma Import (C, gnat_argv);
- pragma Import (C, gnat_envp);
-
- -- The exit status is similarly an external location
-
- gnat_exit_status : Integer;
- pragma Import (C, gnat_exit_status);
-
- GNAT_Version : constant String :=
- "GNAT Version: Pro 7.4.0w (20141119-49)" & ASCII.NUL;
- pragma Export (C, GNAT_Version, "__gnat_version");
-
- Ada_Main_Program_Name : constant String := "_ada_hello" & ASCII.NUL;
- pragma Export (C, Ada_Main_Program_Name, "__gnat_ada_main_program_name");
-
- -- This is the generated adainit routine that performs
- -- initialization at the start of execution. In the case
- -- where Ada is the main program, this main program makes
- -- a call to adainit at program startup.
-
- procedure adainit;
- pragma Export (C, adainit, "adainit");
-
- -- This is the generated adafinal routine that performs
- -- finalization at the end of execution. In the case where
- -- Ada is the main program, this main program makes a call
- -- to adafinal at program termination.
-
- procedure adafinal;
- pragma Export (C, adafinal, "adafinal");
-
- -- This routine is called at the start of execution. It is
- -- a dummy routine that is used by the debugger to breakpoint
- -- at the start of execution.
-
- -- This is the actual generated main program (it would be
- -- suppressed if the no main program switch were used). As
- -- required by standard system conventions, this program has
- -- the external name main.
-
- function main
- (argc : Integer;
- argv : System.Address;
- envp : System.Address)
- return Integer;
- pragma Export (C, main, "main");
-
- -- The following set of constants give the version
- -- identification values for every unit in the bound
- -- partition. This identification is computed from all
- -- dependent semantic units, and corresponds to the
- -- string that would be returned by use of the
- -- Body_Version or Version attributes.
-
- -- The following Export pragmas export the version numbers
- -- with symbolic names ending in B (for body) or S
- -- (for spec) so that they can be located in a link. The
- -- information provided here is sufficient to track down
- -- the exact versions of units used in a given build.
-
- type Version_32 is mod 2 ** 32;
- u00001 : constant Version_32 := 16#8ad6e54a#;
- pragma Export (C, u00001, "helloB");
- u00002 : constant Version_32 := 16#fbff4c67#;
- pragma Export (C, u00002, "system__standard_libraryB");
- u00003 : constant Version_32 := 16#1ec6fd90#;
- pragma Export (C, u00003, "system__standard_libraryS");
- u00004 : constant Version_32 := 16#3ffc8e18#;
- pragma Export (C, u00004, "adaS");
- u00005 : constant Version_32 := 16#28f088c2#;
- pragma Export (C, u00005, "ada__text_ioB");
- u00006 : constant Version_32 := 16#f372c8ac#;
- pragma Export (C, u00006, "ada__text_ioS");
- u00007 : constant Version_32 := 16#2c143749#;
- pragma Export (C, u00007, "ada__exceptionsB");
- u00008 : constant Version_32 := 16#f4f0cce8#;
- pragma Export (C, u00008, "ada__exceptionsS");
- u00009 : constant Version_32 := 16#a46739c0#;
- pragma Export (C, u00009, "ada__exceptions__last_chance_handlerB");
- u00010 : constant Version_32 := 16#3aac8c92#;
- pragma Export (C, u00010, "ada__exceptions__last_chance_handlerS");
- u00011 : constant Version_32 := 16#1d274481#;
- pragma Export (C, u00011, "systemS");
- u00012 : constant Version_32 := 16#a207fefe#;
- pragma Export (C, u00012, "system__soft_linksB");
- u00013 : constant Version_32 := 16#467d9556#;
- pragma Export (C, u00013, "system__soft_linksS");
- u00014 : constant Version_32 := 16#b01dad17#;
- pragma Export (C, u00014, "system__parametersB");
- u00015 : constant Version_32 := 16#630d49fe#;
- pragma Export (C, u00015, "system__parametersS");
- u00016 : constant Version_32 := 16#b19b6653#;
- pragma Export (C, u00016, "system__secondary_stackB");
- u00017 : constant Version_32 := 16#b6468be8#;
- pragma Export (C, u00017, "system__secondary_stackS");
- u00018 : constant Version_32 := 16#39a03df9#;
- pragma Export (C, u00018, "system__storage_elementsB");
- u00019 : constant Version_32 := 16#30e40e85#;
- pragma Export (C, u00019, "system__storage_elementsS");
- u00020 : constant Version_32 := 16#41837d1e#;
- pragma Export (C, u00020, "system__stack_checkingB");
- u00021 : constant Version_32 := 16#93982f69#;
- pragma Export (C, u00021, "system__stack_checkingS");
- u00022 : constant Version_32 := 16#393398c1#;
- pragma Export (C, u00022, "system__exception_tableB");
- u00023 : constant Version_32 := 16#b33e2294#;
- pragma Export (C, u00023, "system__exception_tableS");
- u00024 : constant Version_32 := 16#ce4af020#;
- pragma Export (C, u00024, "system__exceptionsB");
- u00025 : constant Version_32 := 16#75442977#;
- pragma Export (C, u00025, "system__exceptionsS");
- u00026 : constant Version_32 := 16#37d758f1#;
- pragma Export (C, u00026, "system__exceptions__machineS");
- u00027 : constant Version_32 := 16#b895431d#;
- pragma Export (C, u00027, "system__exceptions_debugB");
- u00028 : constant Version_32 := 16#aec55d3f#;
- pragma Export (C, u00028, "system__exceptions_debugS");
- u00029 : constant Version_32 := 16#570325c8#;
- pragma Export (C, u00029, "system__img_intB");
- u00030 : constant Version_32 := 16#1ffca443#;
- pragma Export (C, u00030, "system__img_intS");
- u00031 : constant Version_32 := 16#b98c3e16#;
- pragma Export (C, u00031, "system__tracebackB");
- u00032 : constant Version_32 := 16#831a9d5a#;
- pragma Export (C, u00032, "system__tracebackS");
- u00033 : constant Version_32 := 16#9ed49525#;
- pragma Export (C, u00033, "system__traceback_entriesB");
- u00034 : constant Version_32 := 16#1d7cb2f1#;
- pragma Export (C, u00034, "system__traceback_entriesS");
- u00035 : constant Version_32 := 16#8c33a517#;
- pragma Export (C, u00035, "system__wch_conB");
- u00036 : constant Version_32 := 16#065a6653#;
- pragma Export (C, u00036, "system__wch_conS");
- u00037 : constant Version_32 := 16#9721e840#;
- pragma Export (C, u00037, "system__wch_stwB");
- u00038 : constant Version_32 := 16#2b4b4a52#;
- pragma Export (C, u00038, "system__wch_stwS");
- u00039 : constant Version_32 := 16#92b797cb#;
- pragma Export (C, u00039, "system__wch_cnvB");
- u00040 : constant Version_32 := 16#09eddca0#;
- pragma Export (C, u00040, "system__wch_cnvS");
- u00041 : constant Version_32 := 16#6033a23f#;
- pragma Export (C, u00041, "interfacesS");
- u00042 : constant Version_32 := 16#ece6fdb6#;
- pragma Export (C, u00042, "system__wch_jisB");
- u00043 : constant Version_32 := 16#899dc581#;
- pragma Export (C, u00043, "system__wch_jisS");
- u00044 : constant Version_32 := 16#10558b11#;
- pragma Export (C, u00044, "ada__streamsB");
- u00045 : constant Version_32 := 16#2e6701ab#;
- pragma Export (C, u00045, "ada__streamsS");
- u00046 : constant Version_32 := 16#db5c917c#;
- pragma Export (C, u00046, "ada__io_exceptionsS");
- u00047 : constant Version_32 := 16#12c8cd7d#;
- pragma Export (C, u00047, "ada__tagsB");
- u00048 : constant Version_32 := 16#ce72c228#;
- pragma Export (C, u00048, "ada__tagsS");
- u00049 : constant Version_32 := 16#c3335bfd#;
- pragma Export (C, u00049, "system__htableB");
- u00050 : constant Version_32 := 16#99e5f76b#;
- pragma Export (C, u00050, "system__htableS");
- u00051 : constant Version_32 := 16#089f5cd0#;
- pragma Export (C, u00051, "system__string_hashB");
- u00052 : constant Version_32 := 16#3bbb9c15#;
- pragma Export (C, u00052, "system__string_hashS");
- u00053 : constant Version_32 := 16#807fe041#;
- pragma Export (C, u00053, "system__unsigned_typesS");
- u00054 : constant Version_32 := 16#d27be59e#;
- pragma Export (C, u00054, "system__val_lluB");
- u00055 : constant Version_32 := 16#fa8db733#;
- pragma Export (C, u00055, "system__val_lluS");
- u00056 : constant Version_32 := 16#27b600b2#;
- pragma Export (C, u00056, "system__val_utilB");
- u00057 : constant Version_32 := 16#b187f27f#;
- pragma Export (C, u00057, "system__val_utilS");
- u00058 : constant Version_32 := 16#d1060688#;
- pragma Export (C, u00058, "system__case_utilB");
- u00059 : constant Version_32 := 16#392e2d56#;
- pragma Export (C, u00059, "system__case_utilS");
- u00060 : constant Version_32 := 16#84a27f0d#;
- pragma Export (C, u00060, "interfaces__c_streamsB");
- u00061 : constant Version_32 := 16#8bb5f2c0#;
- pragma Export (C, u00061, "interfaces__c_streamsS");
- u00062 : constant Version_32 := 16#6db6928f#;
- pragma Export (C, u00062, "system__crtlS");
- u00063 : constant Version_32 := 16#4e6a342b#;
- pragma Export (C, u00063, "system__file_ioB");
- u00064 : constant Version_32 := 16#ba56a5e4#;
- pragma Export (C, u00064, "system__file_ioS");
- u00065 : constant Version_32 := 16#b7ab275c#;
- pragma Export (C, u00065, "ada__finalizationB");
- u00066 : constant Version_32 := 16#19f764ca#;
- pragma Export (C, u00066, "ada__finalizationS");
- u00067 : constant Version_32 := 16#95817ed8#;
- pragma Export (C, u00067, "system__finalization_rootB");
- u00068 : constant Version_32 := 16#52d53711#;
- pragma Export (C, u00068, "system__finalization_rootS");
- u00069 : constant Version_32 := 16#769e25e6#;
- pragma Export (C, u00069, "interfaces__cB");
- u00070 : constant Version_32 := 16#4a38bedb#;
- pragma Export (C, u00070, "interfaces__cS");
- u00071 : constant Version_32 := 16#07e6ee66#;
- pragma Export (C, u00071, "system__os_libB");
- u00072 : constant Version_32 := 16#d7b69782#;
- pragma Export (C, u00072, "system__os_libS");
- u00073 : constant Version_32 := 16#1a817b8e#;
- pragma Export (C, u00073, "system__stringsB");
- u00074 : constant Version_32 := 16#639855e7#;
- pragma Export (C, u00074, "system__stringsS");
- u00075 : constant Version_32 := 16#e0b8de29#;
- pragma Export (C, u00075, "system__file_control_blockS");
- u00076 : constant Version_32 := 16#b5b2aca1#;
- pragma Export (C, u00076, "system__finalization_mastersB");
- u00077 : constant Version_32 := 16#69316dc1#;
- pragma Export (C, u00077, "system__finalization_mastersS");
- u00078 : constant Version_32 := 16#57a37a42#;
- pragma Export (C, u00078, "system__address_imageB");
- u00079 : constant Version_32 := 16#bccbd9bb#;
- pragma Export (C, u00079, "system__address_imageS");
- u00080 : constant Version_32 := 16#7268f812#;
- pragma Export (C, u00080, "system__img_boolB");
- u00081 : constant Version_32 := 16#e8fe356a#;
- pragma Export (C, u00081, "system__img_boolS");
- u00082 : constant Version_32 := 16#d7aac20c#;
- pragma Export (C, u00082, "system__ioB");
- u00083 : constant Version_32 := 16#8365b3ce#;
- pragma Export (C, u00083, "system__ioS");
- u00084 : constant Version_32 := 16#6d4d969a#;
- pragma Export (C, u00084, "system__storage_poolsB");
- u00085 : constant Version_32 := 16#e87cc305#;
- pragma Export (C, u00085, "system__storage_poolsS");
- u00086 : constant Version_32 := 16#e34550ca#;
- pragma Export (C, u00086, "system__pool_globalB");
- u00087 : constant Version_32 := 16#c88d2d16#;
- pragma Export (C, u00087, "system__pool_globalS");
- u00088 : constant Version_32 := 16#9d39c675#;
- pragma Export (C, u00088, "system__memoryB");
- u00089 : constant Version_32 := 16#445a22b5#;
- pragma Export (C, u00089, "system__memoryS");
- u00090 : constant Version_32 := 16#6a859064#;
- pragma Export (C, u00090, "system__storage_pools__subpoolsB");
- u00091 : constant Version_32 := 16#e3b008dc#;
- pragma Export (C, u00091, "system__storage_pools__subpoolsS");
- u00092 : constant Version_32 := 16#63f11652#;
- pragma Export (C, u00092, "system__storage_pools__subpools__finalizationB");
- u00093 : constant Version_32 := 16#fe2f4b3a#;
- pragma Export (C, u00093, "system__storage_pools__subpools__finalizationS");
-
- -- BEGIN ELABORATION ORDER
- -- ada%s
- -- interfaces%s
- -- system%s
- -- system.case_util%s
- -- system.case_util%b
- -- system.htable%s
- -- system.img_bool%s
- -- system.img_bool%b
- -- system.img_int%s
- -- system.img_int%b
- -- system.io%s
- -- system.io%b
- -- system.parameters%s
- -- system.parameters%b
- -- system.crtl%s
- -- interfaces.c_streams%s
- -- interfaces.c_streams%b
- -- system.standard_library%s
- -- system.exceptions_debug%s
- -- system.exceptions_debug%b
- -- system.storage_elements%s
- -- system.storage_elements%b
- -- system.stack_checking%s
- -- system.stack_checking%b
- -- system.string_hash%s
- -- system.string_hash%b
- -- system.htable%b
- -- system.strings%s
- -- system.strings%b
- -- system.os_lib%s
- -- system.traceback_entries%s
- -- system.traceback_entries%b
- -- ada.exceptions%s
- -- system.soft_links%s
- -- system.unsigned_types%s
- -- system.val_llu%s
- -- system.val_util%s
- -- system.val_util%b
- -- system.val_llu%b
- -- system.wch_con%s
- -- system.wch_con%b
- -- system.wch_cnv%s
- -- system.wch_jis%s
- -- system.wch_jis%b
- -- system.wch_cnv%b
- -- system.wch_stw%s
- -- system.wch_stw%b
- -- ada.exceptions.last_chance_handler%s
- -- ada.exceptions.last_chance_handler%b
- -- system.address_image%s
- -- system.exception_table%s
- -- system.exception_table%b
- -- ada.io_exceptions%s
- -- ada.tags%s
- -- ada.streams%s
- -- ada.streams%b
- -- interfaces.c%s
- -- system.exceptions%s
- -- system.exceptions%b
- -- system.exceptions.machine%s
- -- system.finalization_root%s
- -- system.finalization_root%b
- -- ada.finalization%s
- -- ada.finalization%b
- -- system.storage_pools%s
- -- system.storage_pools%b
- -- system.finalization_masters%s
- -- system.storage_pools.subpools%s
- -- system.storage_pools.subpools.finalization%s
- -- system.storage_pools.subpools.finalization%b
- -- system.memory%s
- -- system.memory%b
- -- system.standard_library%b
- -- system.pool_global%s
- -- system.pool_global%b
- -- system.file_control_block%s
- -- system.file_io%s
- -- system.secondary_stack%s
- -- system.file_io%b
- -- system.storage_pools.subpools%b
- -- system.finalization_masters%b
- -- interfaces.c%b
- -- ada.tags%b
- -- system.soft_links%b
- -- system.os_lib%b
- -- system.secondary_stack%b
- -- system.address_image%b
- -- system.traceback%s
- -- ada.exceptions%b
- -- system.traceback%b
- -- ada.text_io%s
- -- ada.text_io%b
- -- hello%b
- -- END ELABORATION ORDER
+ -- The finalize routine performs low level system
+ -- finalization using a standard library routine. The
+ -- routine is found in file a-final.c and in the standard
+ -- distribution is a dummy routine that does nothing, so
+ -- really this is a hook for special user finalization.
+
+ procedure finalize;
+ pragma Import (C, finalize, "__gnat_finalize");
+
+ -- The following is to initialize the SEH exceptions
+
+ SEH : aliased array (1 .. 2) of Integer;
+
+ Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address;
+ pragma Volatile (Ensure_Reference);
+
+ -- Start of processing for main
+
+ begin
+ -- Save global variables
+
+ gnat_argc := argc;
+ gnat_argv := argv;
+ gnat_envp := envp;
+
+ -- Call low level system initialization
+
+ Initialize (SEH'Address);
+
+ -- Call our generated Ada initialization routine
+
+ adainit;
+
+ -- Now we call the main program of the partition
+
+ Ada_Main_Program;
+
+ -- Perform Ada finalization
+
+ adafinal;
+
+ -- Perform low level system finalization
+
+ Finalize;
+
+ -- Return the proper exit status
+ return (gnat_exit_status);
+ end;
+
+-- This section is entirely comments, so it has no effect on the
+-- compilation of the Ada_Main package. It provides the list of
+-- object files and linker options, as well as some standard
+-- libraries needed for the link. The gnatlink utility parses
+-- this b~hello.adb file to read these comment lines to generate
+-- the appropriate command line arguments for the call to the
+-- system linker. The BEGIN/END lines are used for sentinels for
+-- this parsing operation.
+
+-- The exact file names will of course depend on the environment,
+-- host/target and location of files on the host system.
+
+-- BEGIN Object file/option list
+ -- ./hello.o
+ -- -L./
+ -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/
+ -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a
+-- END Object file/option list
end ada_main;
@end example
+The Ada code in the above example is exactly what is generated by the
+binder. We have added comments to more clearly indicate the function
+of each part of the generated @code{Ada_Main} package.
+
+The code is standard Ada in all respects, and can be processed by any
+tools that handle Ada. In particular, it is possible to use the debugger
+in Ada mode to debug the generated @code{Ada_Main} package. For example,
+suppose that for reasons that you do not understand, your program is crashing
+during elaboration of the body of @code{Ada.Text_IO}. To locate this bug,
+you can place a breakpoint on the call:
+
+@quotation
+
@example
-pragma Ada_95;
--- The following source file name pragmas allow the generated file
--- names to be unique for different main programs. They are needed
--- since the package name will always be Ada_Main.
+Ada.Text_Io'Elab_Body;
+@end example
+@end quotation
-pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads");
-pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb");
+and trace the elaboration routine for this package to find out where
+the problem might be (more usually of course you would be debugging
+elaboration code in your own application).
-pragma Suppress (Overflow_Check);
-with Ada.Exceptions;
+@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
--- Generated package body for Ada_Main starts here
+@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{214}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{215}
+@chapter Elaboration Order Handling in GNAT
-package body ada_main is
- pragma Warnings (Off);
- -- These values are reference counter associated to units which have
- -- been elaborated. It is also used to avoid elaborating the
- -- same unit twice.
+@geindex Order of elaboration
- E72 : Short_Integer; pragma Import (Ada, E72, "system__os_lib_E");
- E13 : Short_Integer; pragma Import (Ada, E13, "system__soft_links_E");
- E23 : Short_Integer; pragma Import (Ada, E23, "system__exception_table_E");
- E46 : Short_Integer; pragma Import (Ada, E46, "ada__io_exceptions_E");
- E48 : Short_Integer; pragma Import (Ada, E48, "ada__tags_E");
- E45 : Short_Integer; pragma Import (Ada, E45, "ada__streams_E");
- E70 : Short_Integer; pragma Import (Ada, E70, "interfaces__c_E");
- E25 : Short_Integer; pragma Import (Ada, E25, "system__exceptions_E");
- E68 : Short_Integer; pragma Import (Ada, E68, "system__finalization_root_E");
- E66 : Short_Integer; pragma Import (Ada, E66, "ada__finalization_E");
- E85 : Short_Integer; pragma Import (Ada, E85, "system__storage_pools_E");
- E77 : Short_Integer; pragma Import (Ada, E77, "system__finalization_masters_E");
- E91 : Short_Integer; pragma Import (Ada, E91, "system__storage_pools__subpools_E");
- E87 : Short_Integer; pragma Import (Ada, E87, "system__pool_global_E");
- E75 : Short_Integer; pragma Import (Ada, E75, "system__file_control_block_E");
- E64 : Short_Integer; pragma Import (Ada, E64, "system__file_io_E");
- E17 : Short_Integer; pragma Import (Ada, E17, "system__secondary_stack_E");
- E06 : Short_Integer; pragma Import (Ada, E06, "ada__text_io_E");
+@geindex Elaboration control
+
+This appendix describes the handling of elaboration code in Ada and GNAT, and
+discusses how the order of elaboration of program units can be controlled in
+GNAT, either automatically or with explicit programming features.
+
+@menu
+* Elaboration Code::
+* Elaboration Order::
+* Checking the Elaboration Order::
+* Controlling the Elaboration Order in Ada::
+* Controlling the Elaboration Order in GNAT::
+* Mixing Elaboration Models::
+* ABE Diagnostics::
+* SPARK Diagnostics::
+* Elaboration Circularities::
+* Resolving Elaboration Circularities::
+* 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{216}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{217}
+@section Elaboration Code
+
+
+Ada defines the term @emph{execution} as the process by which a construct achieves
+its run-time effect. This process is also referred to as @strong{elaboration} for
+declarations and @emph{evaluation} for expressions.
+
+The execution model in Ada allows for certain sections of an Ada program to be
+executed prior to execution of the program itself, primarily with the intent of
+initializing data. These sections are referred to as @strong{elaboration code}.
+Elaboration code is executed as follows:
+
+
+@itemize *
+
+@item
+All partitions of an Ada program are executed in parallel with one another,
+possibly in a separate address space, and possibly on a separate computer.
+
+@item
+The execution of a partition involves running the environment task for that
+partition.
+
+@item
+The environment task executes all elaboration code (if available) for all
+units within that partition. This code is said to be executed at
+@strong{elaboration time}.
+
+@item
+The environment task executes the Ada program (if available) for that
+partition.
+@end itemize
+
+In addition to the Ada terminology, this appendix defines the following terms:
+
+
+@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 invoked by elaboration code is referred to
+as an @emph{elaboration scenario} or simply a @strong{scenario}. GNAT recognizes the
+following scenarios:
+
+
+@itemize -
+
+@item
+@code{'Access} of entries, operators, and subprograms
+
+@item
+Activation of tasks
+
+@item
+Calls to entries, operators, and subprograms
+
+@item
+Instantiations of generic templates
+@end itemize
+
+@item
+@emph{Target}
+
+A construct elaborated by a scenario is referred to as @emph{elaboration target}
+or simply @strong{target}. GNAT recognizes the following targets:
+
+
+@itemize -
+
+@item
+For @code{'Access} of entries, operators, and subprograms, the target is the
+entry, operator, or subprogram being aliased.
+
+@item
+For activation of tasks, the target is the task body
+
+@item
+For calls to entries, operators, and subprograms, the target is the entry,
+operator, or subprogram being invoked.
+
+@item
+For instantiations of generic templates, the target is the generic template
+being instantiated.
+@end itemize
+@end itemize
+
+Elaboration code may appear in two distinct contexts:
+
+
+@itemize *
+
+@item
+@emph{Library level}
+
+A scenario appears at the library level when it is encapsulated by a package
+[body] compilation unit, ignoring any other package [body] declarations in
+between.
+
+@example
+with Server;
+package Client is
+ procedure Proc;
+
+ package Nested is
+ Val : ... := Server.Func;
+ end Nested;
+end Client;
+@end example
+
+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 invoked when
+the spec of unit @code{Client} is elaborated.
+
+@item
+@emph{Package body statements}
+
+A scenario appears within the statement sequence of a package body when it is
+bounded by the region starting from the @code{begin} keyword of the package body
+and ending at the @code{end} keyword of the package body.
+
+@example
+package body Client is
+ procedure Proc is
+ begin
+ ...
+ end Proc;
+begin
+ Proc;
+end Client;
+@end example
+
+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 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{218}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{219}
+@section Elaboration Order
+
+
+The sequence by which the elaboration code of all units within a partition is
+executed is referred to as @strong{elaboration order}.
+
+Within a single unit, elaboration code is executed in sequential order.
+
+@quotation
+
+@example
+package body Client is
+ Result : ... := Server.Func;
+
+ procedure Proc is
+ package Inst is new Server.Gen;
+ begin
+ Inst.Eval (Result);
+ end Proc;
+begin
+ Proc;
+end Client;
+@end example
+@end quotation
+
+In the example above, the elaboration order within package body @code{Client} is
+as follows:
+
+
+@enumerate
+
+@item
+The object declaration of @code{Result} is elaborated.
+
+
+@itemize *
+
+@item
+Function @code{Server.Func} is invoked.
+@end itemize
+
+@item
+The subprogram body of @code{Proc} is elaborated.
+
+@item
+Procedure @code{Proc} is invoked.
+
+
+@itemize *
+
+@item
+Generic unit @code{Server.Gen} is instantiated as @code{Inst}.
+
+@item
+Instance @code{Inst} is elaborated.
+
+@item
+Procedure @code{Inst.Eval} is invoked.
+@end itemize
+@end enumerate
+
+The elaboration order of all units within a partition depends on the following
+factors:
+
+
+@itemize *
+
+@item
+@emph{with}ed units
+
+@item
+parent units
+
+@item
+purity of units
- Local_Priority_Specific_Dispatching : constant String := "";
- Local_Interrupt_States : constant String := "";
+@item
+preelaborability of units
- Is_Elaborated : Boolean := False;
+@item
+presence of elaboration-control pragmas
- procedure finalize_library is
+@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;
+end Server;
+@end example
+
+@example
+package body Server is
+ Results : array (1 .. 5) of Integer := (1, 2, 3, 4, 5);
+
+ function Func (Index : Integer) return Integer is
begin
- E06 := E06 - 1;
- declare
- procedure F1;
- pragma Import (Ada, F1, "ada__text_io__finalize_spec");
- begin
- F1;
- end;
- E77 := E77 - 1;
- E91 := E91 - 1;
- declare
- procedure F2;
- pragma Import (Ada, F2, "system__file_io__finalize_body");
- begin
- E64 := E64 - 1;
- F2;
- end;
- declare
- procedure F3;
- pragma Import (Ada, F3, "system__file_control_block__finalize_spec");
- begin
- E75 := E75 - 1;
- F3;
- end;
- E87 := E87 - 1;
- declare
- procedure F4;
- pragma Import (Ada, F4, "system__pool_global__finalize_spec");
- begin
- F4;
- end;
- declare
- procedure F5;
- pragma Import (Ada, F5, "system__storage_pools__subpools__finalize_spec");
- begin
- F5;
- end;
- declare
- procedure F6;
- pragma Import (Ada, F6, "system__finalization_masters__finalize_spec");
- begin
- F6;
- end;
- declare
- procedure Reraise_Library_Exception_If_Any;
- pragma Import (Ada, Reraise_Library_Exception_If_Any, "__gnat_reraise_library_exception_if_any");
- begin
- Reraise_Library_Exception_If_Any;
- end;
- end finalize_library;
+ return Results (Index);
+ end Func;
+end Server;
+@end example
- -------------
- -- adainit --
- -------------
+@example
+with Server;
+package Client is
+ Val : constant Integer := Server.Func (3);
+end Client;
+@end example
- procedure adainit is
+@example
+with Client;
+procedure Main is begin null; end Main;
+@end example
+@end quotation
- Main_Priority : Integer;
- pragma Import (C, Main_Priority, "__gl_main_priority");
- Time_Slice_Value : Integer;
- pragma Import (C, Time_Slice_Value, "__gl_time_slice_val");
- WC_Encoding : Character;
- pragma Import (C, WC_Encoding, "__gl_wc_encoding");
- Locking_Policy : Character;
- pragma Import (C, Locking_Policy, "__gl_locking_policy");
- Queuing_Policy : Character;
- pragma Import (C, Queuing_Policy, "__gl_queuing_policy");
- Task_Dispatching_Policy : Character;
- pragma Import (C, Task_Dispatching_Policy, "__gl_task_dispatching_policy");
- Priority_Specific_Dispatching : System.Address;
- pragma Import (C, Priority_Specific_Dispatching, "__gl_priority_specific_dispatching");
- Num_Specific_Dispatching : Integer;
- pragma Import (C, Num_Specific_Dispatching, "__gl_num_specific_dispatching");
- Main_CPU : Integer;
- pragma Import (C, Main_CPU, "__gl_main_cpu");
- Interrupt_States : System.Address;
- pragma Import (C, Interrupt_States, "__gl_interrupt_states");
- Num_Interrupt_States : Integer;
- pragma Import (C, Num_Interrupt_States, "__gl_num_interrupt_states");
- Unreserve_All_Interrupts : Integer;
- pragma Import (C, Unreserve_All_Interrupts, "__gl_unreserve_all_interrupts");
- Detect_Blocking : Integer;
- pragma Import (C, Detect_Blocking, "__gl_detect_blocking");
- Default_Stack_Size : Integer;
- pragma Import (C, Default_Stack_Size, "__gl_default_stack_size");
- Leap_Seconds_Support : Integer;
- pragma Import (C, Leap_Seconds_Support, "__gl_leap_seconds_support");
+The following elaboration order exhibits a fundamental problem referred to as
+@emph{access-before-elaboration} or simply @strong{ABE}.
- procedure Runtime_Initialize;
- pragma Import (C, Runtime_Initialize, "__gnat_runtime_initialize");
+@quotation
- Finalize_Library_Objects : No_Param_Proc;
- pragma Import (C, Finalize_Library_Objects, "__gnat_finalize_library_objects");
+@example
+spec of Server
+spec of Client
+body of Server
+body of Main
+@end example
+@end quotation
- -- Start of processing for adainit
+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
+@code{Val}. This invokes function @code{Server.Func}, however the body of
+@code{Server.Func} has not been elaborated yet because @code{Server}'s body comes
+after @code{Client}'s spec in the elaboration order. As a result, the value of
+constant @code{Val} is now undefined.
- begin
+Without any guarantees from the language, an undetected ABE problem may hinder
+proper initialization of data, which in turn may lead to undefined behavior at
+run time. To prevent such ABE problems, Ada employs dynamic checks in the same
+vein as index or null exclusion checks. A failed ABE check raises exception
+@code{Program_Error}.
- -- Record various information for this partition. The values
- -- are derived by the binder from information stored in the ali
- -- files by the compiler.
+The following elaboration order avoids the ABE problem and the program can be
+successfully elaborated.
- if Is_Elaborated then
- return;
- end if;
- Is_Elaborated := True;
- Main_Priority := -1;
- Time_Slice_Value := -1;
- WC_Encoding := 'b';
- Locking_Policy := ' ';
- Queuing_Policy := ' ';
- Task_Dispatching_Policy := ' ';
- Priority_Specific_Dispatching :=
- Local_Priority_Specific_Dispatching'Address;
- Num_Specific_Dispatching := 0;
- Main_CPU := -1;
- Interrupt_States := Local_Interrupt_States'Address;
- Num_Interrupt_States := 0;
- Unreserve_All_Interrupts := 0;
- Detect_Blocking := 0;
- Default_Stack_Size := -1;
- Leap_Seconds_Support := 0;
+@quotation
- Runtime_Initialize;
+@example
+spec of Server
+body of Server
+spec of Client
+body of Main
+@end example
+@end quotation
- Finalize_Library_Objects := finalize_library'access;
+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, 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.
- -- Now we have the elaboration calls for all units in the partition.
- -- The Elab_Spec and Elab_Body attributes generate references to the
- -- implicit elaboration procedures generated by the compiler for
- -- each unit that requires elaboration. Increment a counter of
- -- reference for each unit.
+@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{21a}@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{21b}
+@section Checking the Elaboration Order
- System.Soft_Links'Elab_Spec;
- System.Exception_Table'Elab_Body;
- E23 := E23 + 1;
- Ada.Io_Exceptions'Elab_Spec;
- E46 := E46 + 1;
- Ada.Tags'Elab_Spec;
- Ada.Streams'Elab_Spec;
- E45 := E45 + 1;
- Interfaces.C'Elab_Spec;
- System.Exceptions'Elab_Spec;
- E25 := E25 + 1;
- System.Finalization_Root'Elab_Spec;
- E68 := E68 + 1;
- Ada.Finalization'Elab_Spec;
- E66 := E66 + 1;
- System.Storage_Pools'Elab_Spec;
- E85 := E85 + 1;
- System.Finalization_Masters'Elab_Spec;
- System.Storage_Pools.Subpools'Elab_Spec;
- System.Pool_Global'Elab_Spec;
- E87 := E87 + 1;
- System.File_Control_Block'Elab_Spec;
- E75 := E75 + 1;
- System.File_Io'Elab_Body;
- E64 := E64 + 1;
- E91 := E91 + 1;
- System.Finalization_Masters'Elab_Body;
- E77 := E77 + 1;
- E70 := E70 + 1;
- Ada.Tags'Elab_Body;
- E48 := E48 + 1;
- System.Soft_Links'Elab_Body;
- E13 := E13 + 1;
- System.Os_Lib'Elab_Body;
- E72 := E72 + 1;
- System.Secondary_Stack'Elab_Body;
- E17 := E17 + 1;
- Ada.Text_Io'Elab_Spec;
- Ada.Text_Io'Elab_Body;
- E06 := E06 + 1;
- end adainit;
- --------------
- -- adafinal --
- --------------
+To avoid placing the entire elaboration-order burden on the programmer, Ada
+provides three lines of defense:
- procedure adafinal is
- procedure s_stalib_adafinal;
- pragma Import (C, s_stalib_adafinal, "system__standard_library__adafinal");
- procedure Runtime_Finalize;
- pragma Import (C, Runtime_Finalize, "__gnat_runtime_finalize");
+@itemize *
- begin
- if not Is_Elaborated then
- return;
- end if;
- Is_Elaborated := False;
- Runtime_Finalize;
- s_stalib_adafinal;
- end adafinal;
+@item
+@emph{Static semantics}
- -- We get to the main program of the partition by using
- -- pragma Import because if we try to with the unit and
- -- call it Ada style, then not only do we waste time
- -- recompiling it, but also, we don't really know the right
- -- switches (e.g.@@: identifier character set) to be used
- -- to compile it.
+Static semantic rules restrict the possible choice of elaboration order. For
+instance, if unit Client @emph{with}s unit Server, then the spec of Server is
+always elaborated prior to Client. The same principle applies to child units
+- the spec of a parent unit is always elaborated prior to the child unit.
- procedure Ada_Main_Program;
- pragma Import (Ada, Ada_Main_Program, "_ada_hello");
+@item
+@emph{Dynamic semantics}
- ----------
- -- main --
- ----------
+Dynamic checks are performed at run time, to ensure that a target is
+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:
- -- main is actually a function, as in the ANSI C standard,
- -- defined to return the exit status. The three parameters
- -- are the argument count, argument values and environment
- -- pointer.
- function main
- (argc : Integer;
- argv : System.Address;
- envp : System.Address)
- return Integer
- is
- -- The initialize routine performs low level system
- -- initialization using a standard library routine which
- -- sets up signal handling and performs any other
- -- required setup. The routine can be found in file
- -- a-init.c.
+@itemize -
- procedure initialize;
- pragma Import (C, initialize, "__gnat_initialize");
+@item
+@emph{Restrictions on calls}
- -- The finalize routine performs low level system
- -- finalization using a standard library routine. The
- -- routine is found in file a-final.c and in the standard
- -- distribution is a dummy routine that does nothing, so
- -- really this is a hook for special user finalization.
+An entry, operator, or subprogram can be called from elaboration code only
+when the corresponding body has been elaborated.
+
+@item
+@emph{Restrictions on instantiations}
+
+A generic unit can be instantiated by elaboration code only when the
+corresponding body has been elaborated.
+
+@item
+@emph{Restrictions on task activation}
+
+A task can be activated by elaboration code only when the body of the
+associated task type has been elaborated.
+@end itemize
- procedure finalize;
- pragma Import (C, finalize, "__gnat_finalize");
+The restrictions above can be summarized by the following rule:
- -- The following is to initialize the SEH exceptions
+@emph{If a target has a body, then this body must be elaborated prior to the
+scenario that invokes the target.}
- SEH : aliased array (1 .. 2) of Integer;
+@item
+@emph{Elaboration control}
- Ensure_Reference : aliased System.Address := Ada_Main_Program_Name'Address;
- pragma Volatile (Ensure_Reference);
+Pragmas are provided for the programmer to specify the desired elaboration
+order.
+@end itemize
- -- Start of processing for main
+@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{21c}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{21d}
+@section Controlling the Elaboration Order in Ada
- begin
- -- Save global variables
- gnat_argc := argc;
- gnat_argv := argv;
- gnat_envp := envp;
+Ada provides several idioms and pragmas to aid the programmer with specifying
+the desired elaboration order and avoiding ABE problems altogether.
- -- Call low level system initialization
- Initialize (SEH'Address);
+@itemize *
- -- Call our generated Ada initialization routine
+@item
+@emph{Packages without a body}
- adainit;
+A library package which does not require a completing body does not suffer
+from ABE problems.
- -- Now we call the main program of the partition
+@example
+package Pack is
+ generic
+ type Element is private;
+ package Containers is
+ type Element_Array is array (1 .. 10) of Element;
+ end Containers;
+end Pack;
+@end example
- Ada_Main_Program;
+In the example above, package @code{Pack} does not require a body because it
+does not contain any constructs which require completion in a body. As a
+result, generic @code{Pack.Containers} can be instantiated without encountering
+any ABE problems.
+@end itemize
- -- Perform Ada finalization
+@geindex pragma Pure
- adafinal;
- -- Perform low level system finalization
+@itemize *
- Finalize;
+@item
+@emph{pragma Pure}
- -- Return the proper exit status
- return (gnat_exit_status);
- end;
+Pragma @code{Pure} places sufficient restrictions on a unit to guarantee that no
+scenario within the unit can result in an ABE problem.
+@end itemize
--- This section is entirely comments, so it has no effect on the
--- compilation of the Ada_Main package. It provides the list of
--- object files and linker options, as well as some standard
--- libraries needed for the link. The gnatlink utility parses
--- this b~hello.adb file to read these comment lines to generate
--- the appropriate command line arguments for the call to the
--- system linker. The BEGIN/END lines are used for sentinels for
--- this parsing operation.
+@geindex pragma Preelaborate
--- The exact file names will of course depend on the environment,
--- host/target and location of files on the host system.
--- BEGIN Object file/option list
- -- ./hello.o
- -- -L./
- -- -L/usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/
- -- /usr/local/gnat/lib/gcc-lib/i686-pc-linux-gnu/2.8.1/adalib/libgnat.a
--- END Object file/option list
+@itemize *
-end ada_main;
-@end example
+@item
+@emph{pragma Preelaborate}
-The Ada code in the above example is exactly what is generated by the
-binder. We have added comments to more clearly indicate the function
-of each part of the generated @cite{Ada_Main} package.
+Pragma @code{Preelaborate} is slightly less restrictive than pragma @code{Pure},
+but still strong enough to prevent ABE problems within a unit.
+@end itemize
-The code is standard Ada in all respects, and can be processed by any
-tools that handle Ada. In particular, it is possible to use the debugger
-in Ada mode to debug the generated @cite{Ada_Main} package. For example,
-suppose that for reasons that you do not understand, your program is crashing
-during elaboration of the body of @cite{Ada.Text_IO}. To locate this bug,
-you can place a breakpoint on the call:
+@geindex pragma Elaborate_Body
-@quotation
+
+@itemize *
+
+@item
+@emph{pragma Elaborate_Body}
+
+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 invoke a server target before the target body has been
+elaborated because the spec and body are effectively "glued" together.
@example
-Ada.Text_Io'Elab_Body;
-@end example
-@end quotation
+package Server is
+ pragma Elaborate_Body;
-and trace the elaboration routine for this package to find out where
-the problem might be (more usually of course you would be debugging
-elaboration code in your own application).
+ function Func return Integer;
+end Server;
+@end example
-@c -- Example: A |withing| unit has a |with| clause, it |withs| a |withed| unit
+@example
+package body Server is
+ function Func return Integer is
+ begin
+ ...
+ end Func;
+end Server;
+@end example
-@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{11}@anchor{gnat_ugn/elaboration_order_handling_in_gnat doc}@anchor{2b8}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id1}@anchor{2b9}
-@chapter Elaboration Order Handling in GNAT
+@example
+with Server;
+package Client is
+ Val : constant Integer := Server.Func;
+end Client;
+@end example
+In the example above, pragma @code{Elaborate_Body} guarantees the following
+elaboration order:
-@geindex Order of elaboration
+@example
+spec of Server
+body of Server
+spec of Client
+@end example
-@geindex Elaboration control
+because the spec of @code{Server} must be elaborated prior to @code{Client} by
+virtue of the @emph{with} clause, and in addition the body of @code{Server} must be
+elaborated immediately after the spec of @code{Server}.
-This appendix describes the handling of elaboration code in Ada and
-in GNAT, and discusses how the order of elaboration of program units can
-be controlled in GNAT, either automatically or with explicit programming
-features.
+Removing pragma @code{Elaborate_Body} could result in the following incorrect
+elaboration order:
-@menu
-* Elaboration Code::
-* Checking the Elaboration Order::
-* Controlling the Elaboration Order::
-* Controlling Elaboration in GNAT - Internal Calls::
-* Controlling Elaboration in GNAT - External Calls::
-* Default Behavior in GNAT - Ensuring Safety::
-* Treatment of Pragma Elaborate::
-* Elaboration Issues for Library Tasks::
-* Mixing Elaboration Models::
-* What to Do If the Default Elaboration Behavior Fails::
-* Elaboration for Indirect Calls::
-* Summary of Procedures for Elaboration Control::
-* Other Elaboration Order Considerations::
-* Determining the Chosen Elaboration Order::
+@example
+spec of Server
+spec of Client
+body of Server
+@end example
-@end menu
+where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func} has
+not been elaborated yet.
+@end itemize
-@node Elaboration Code,Checking the Elaboration Order,,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-code}@anchor{2ba}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id2}@anchor{2bb}
-@section Elaboration Code
+The pragmas outlined above allow a server unit to guarantee safe elaboration
+use by client units. Thus it is a good rule to mark units as @code{Pure} or
+@code{Preelaborate}, and if this is not possible, mark them as @code{Elaborate_Body}.
+There are however situations where @code{Pure}, @code{Preelaborate}, and
+@code{Elaborate_Body} are not applicable. Ada provides another set of pragmas for
+use by client units to help ensure the elaboration safety of server units they
+depend on.
-Ada provides rather general mechanisms for executing code at elaboration
-time, that is to say before the main program starts executing. Such code arises
-in three contexts:
+@geindex pragma Elaborate (Unit)
@itemize *
@item
-@emph{Initializers for variables}
+@emph{pragma Elaborate (Unit)}
-Variables declared at the library level, in package specs or bodies, can
-require initialization that is performed at elaboration time, as in:
+Pragma @code{Elaborate} can be placed in the context clauses of a unit, after a
+@emph{with} clause. It guarantees that both the spec and body of its argument will
+be elaborated prior to the unit with the pragma. Note that other unrelated
+units may be elaborated in between the spec and the body.
@example
-Sqrt_Half : Float := Sqrt (0.5);
+package Server is
+ function Func return Integer;
+end Server;
@end example
-@item
-@emph{Package initialization code}
-
-Code in a @cite{BEGIN-END} section at the outer level of a package body is
-executed as part of the package body elaboration code.
-
-@item
-@emph{Library level task allocators}
+@example
+package body Server is
+ function Func return Integer is
+ begin
+ ...
+ end Func;
+end Server;
+@end example
-Tasks that are declared using task allocators at the library level
-start executing immediately and hence can execute at elaboration time.
-@end itemize
+@example
+with Server;
+pragma Elaborate (Server);
+package Client is
+ Val : constant Integer := Server.Func;
+end Client;
+@end example
-Subprogram calls are possible in any of these contexts, which means that
-any arbitrary part of the program may be executed as part of the elaboration
-code. It is even possible to write a program which does all its work at
-elaboration time, with a null main program, although stylistically this
-would usually be considered an inappropriate way to structure
-a program.
+In the example above, pragma @code{Elaborate} guarantees the following
+elaboration order:
-An important concern arises in the context of elaboration code:
-we have to be sure that it is executed in an appropriate order. What we
-have is a series of elaboration code sections, potentially one section
-for each unit in the program. It is important that these execute
-in the correct order. Correctness here means that, taking the above
-example of the declaration of @cite{Sqrt_Half},
-if some other piece of
-elaboration code references @cite{Sqrt_Half},
-then it must run after the
-section of elaboration code that contains the declaration of
-@cite{Sqrt_Half}.
+@example
+spec of Server
+body of Server
+spec of Client
+@end example
-There would never be any order of elaboration problem if we made a rule
-that whenever you @emph{with} a unit, you must elaborate both the spec and body
-of that unit before elaborating the unit doing the @emph{with}ing:
+Removing pragma @code{Elaborate} could result in the following incorrect
+elaboration order:
@example
-with Unit_1;
-package Unit_2 is ...
+spec of Server
+spec of Client
+body of Server
@end example
-would require that both the body and spec of @cite{Unit_1} be elaborated
-before the spec of @cite{Unit_2}. However, a rule like that would be far too
-restrictive. In particular, it would make it impossible to have routines
-in separate packages that were mutually recursive.
+where @code{Client} invokes @code{Server.Func}, but the body of @code{Server.Func}
+has not been elaborated yet.
+@end itemize
+
+@geindex pragma Elaborate_All (Unit)
+
+
+@itemize *
-You might think that a clever enough compiler could look at the actual
-elaboration code and determine an appropriate correct order of elaboration,
-but in the general case, this is not possible. Consider the following
-example.
+@item
+@emph{pragma Elaborate_All (Unit)}
-In the body of @cite{Unit_1}, we have a procedure @cite{Func_1}
-that references
-the variable @cite{Sqrt_1}, which is declared in the elaboration code
-of the body of @cite{Unit_1}:
+Pragma @code{Elaborate_All} is placed in the context clauses of a unit, after
+a @emph{with} clause. It guarantees that both the spec and body of its argument
+will be elaborated prior to the unit with the pragma, as well as all units
+@emph{with}ed by the spec and body of the argument, recursively. Note that other
+unrelated units may be elaborated in between the spec and the body.
@example
-Sqrt_1 : Float := Sqrt (0.1);
+package Math is
+ function Factorial (Val : Natural) return Natural;
+end Math;
@end example
-The elaboration code of the body of @cite{Unit_1} also contains:
+@example
+package body Math is
+ function Factorial (Val : Natural) return Natural is
+ begin
+ ...;
+ end Factorial;
+end Math;
+@end example
@example
-if expression_1 = 1 then
- Q := Unit_2.Func_2;
-end if;
+package Computer is
+ type Operation_Kind is (None, Op_Factorial);
+
+ function Compute
+ (Val : Natural;
+ Op : Operation_Kind) return Natural;
+end Computer;
@end example
-@cite{Unit_2} is exactly parallel,
-it has a procedure @cite{Func_2} that references
-the variable @cite{Sqrt_2}, which is declared in the elaboration code of
-the body @cite{Unit_2}:
+@example
+with Math;
+package body Computer is
+ function Compute
+ (Val : Natural;
+ Op : Operation_Kind) return Natural
+ is
+ if Op = Op_Factorial then
+ return Math.Factorial (Val);
+ end if;
+
+ return 0;
+ end Compute;
+end Computer;
+@end example
@example
-Sqrt_2 : Float := Sqrt (0.1);
+with Computer;
+pragma Elaborate_All (Computer);
+package Client is
+ Val : constant Natural :=
+ Computer.Compute (123, Computer.Op_Factorial);
+end Client;
@end example
-The elaboration code of the body of @cite{Unit_2} also contains:
+In the example above, pragma @code{Elaborate_All} can result in the following
+elaboration order:
@example
-if expression_2 = 2 then
- Q := Unit_1.Func_1;
-end if;
+spec of Math
+body of Math
+spec of Computer
+body of Computer
+spec of Client
@end example
-Now the question is, which of the following orders of elaboration is
-acceptable:
+Note that there are several allowable suborders for the specs and bodies of
+@code{Math} and @code{Computer}, but the point is that these specs and bodies will
+be elaborated prior to @code{Client}.
+
+Removing pragma @code{Elaborate_All} could result in the following incorrect
+elaboration order:
@example
-Spec of Unit_1
-Spec of Unit_2
-Body of Unit_1
-Body of Unit_2
+spec of Math
+spec of Computer
+body of Computer
+spec of Client
+body of Math
@end example
-or
+where @code{Client} invokes @code{Computer.Compute}, which in turn invokes
+@code{Math.Factorial}, but the body of @code{Math.Factorial} has not been
+elaborated yet.
+@end itemize
-@example
-Spec of Unit_2
-Spec of Unit_1
-Body of Unit_2
-Body of Unit_1
-@end example
-
-If you carefully analyze the flow here, you will see that you cannot tell
-at compile time the answer to this question.
-If @cite{expression_1} is not equal to 1,
-and @cite{expression_2} is not equal to 2,
-then either order is acceptable, because neither of the function calls is
-executed. If both tests evaluate to true, then neither order is acceptable
-and in fact there is no correct order.
-
-If one of the two expressions is true, and the other is false, then one
-of the above orders is correct, and the other is incorrect. For example,
-if @cite{expression_1} /= 1 and @cite{expression_2} = 2,
-then the call to @cite{Func_1}
-will occur, but not the call to @cite{Func_2.}
-This means that it is essential
-to elaborate the body of @cite{Unit_1} before
-the body of @cite{Unit_2}, so the first
-order of elaboration is correct and the second is wrong.
-
-By making @cite{expression_1} and @cite{expression_2}
-depend on input data, or perhaps
-the time of day, we can make it impossible for the compiler or binder
-to figure out which of these expressions will be true, and hence it
-is impossible to guarantee a safe order of elaboration at run time.
-
-@node Checking the Elaboration Order,Controlling the Elaboration Order,Elaboration Code,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat checking-the-elaboration-order}@anchor{2bc}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id3}@anchor{2bd}
-@section Checking the Elaboration Order
+All pragmas shown above can be summarized by the following rule:
+@emph{If a client unit elaborates a server target directly or indirectly, then if
+the server unit requires a body and does not have pragma Pure, Preelaborate,
+or Elaborate_Body, then the client unit should have pragma Elaborate or
+Elaborate_All for the server unit.}
-In some languages that involve the same kind of elaboration problems,
-e.g., Java and C++, the programmer needs to take these
-ordering problems into account, and it is common to
-write a program in which an incorrect elaboration order gives
-surprising results, because it references variables before they
-are initialized.
-Ada is designed to be a safe language, and a programmer-beware approach is
-clearly not sufficient. Consequently, the language provides three lines
-of defense:
+If the rule outlined above is not followed, then a program may fall in one of
+the following states:
@itemize *
@item
-@emph{Standard rules}
+@emph{No elaboration order exists}
+
+In this case a compiler must diagnose the situation, and refuse to build an
+executable program.
+
+@item
+@emph{One or more incorrect elaboration orders exist}
+
+In this case a compiler can build an executable program, but
+@code{Program_Error} will be raised when the program is run.
+
+@item
+@emph{Several elaboration orders exist, some correct, some incorrect}
+
+In this case the programmer has not controlled the elaboration order. As a
+result, a compiler may or may not pick one of the correct orders, and the
+program may or may not raise @code{Program_Error} when it is run. This is the
+worst possible state because the program may fail on another compiler, or
+even another version of the same compiler.
+
+@item
+@emph{One or more correct orders exist}
-Some standard rules restrict the possible choice of elaboration
-order. In particular, if you @emph{with} a unit, then its spec is always
-elaborated before the unit doing the @emph{with}. Similarly, a parent
-spec is always elaborated before the child spec, and finally
-a spec is always elaborated before its corresponding body.
+In this case a compiler can build an executable program, and the program is
+run successfully. This state may be guaranteed by following the outlined
+rules, or may be the result of good program architecture.
@end itemize
-@geindex Elaboration checks
+Note that one additional advantage of using @code{Elaborate} and @code{Elaborate_All}
+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.
-@geindex Checks
-@geindex elaboration
+@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
+
+
+In addition to Ada semantics and rules synthesized from them, GNAT offers
+three elaboration models to aid the programmer with specifying the correct
+elaboration order and to diagnose elaboration problems.
+
+@geindex Dynamic elaboration model
@itemize *
@item
-@emph{Dynamic elaboration checks}
+@emph{Dynamic 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:
-Dynamic checks are made at run time, so that if some entity is accessed
-before it is elaborated (typically by means of a subprogram call)
-then the exception (@cite{Program_Error}) is raised.
+
+@itemize -
@item
-@emph{Elaboration control}
+All code within all units in a partition is considered to be elaboration
+code.
+
+@item
+Some of the invocations in elaboration code may not take place at run time
+due to conditional execution.
+@end 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.
-Facilities are provided for the programmer to specify the desired order
-of elaboration.
+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.
+
+The dynamic model is enabled with compiler switch @code{-gnatE}.
@end itemize
-Let's look at these facilities in more detail. First, the rules for
-dynamic checking. One possible rule would be simply to say that the
-exception is raised if you access a variable which has not yet been
-elaborated. The trouble with this approach is that it could require
-expensive checks on every variable reference. Instead Ada has two
-rules which are a little more restrictive, but easier to check, and
-easier to state:
+@geindex Static elaboration model
@itemize *
@item
-@emph{Restrictions on calls}
+@emph{Static elaboration model}
+
+This is the middle ground of the three models. When the static model is in
+effect, GNAT makes the following assumptions:
+
-A subprogram can only be called at elaboration time if its body
-has been elaborated. The rules for elaboration given above guarantee
-that the spec of the subprogram has been elaborated before the
-call, but not the body. If this rule is violated, then the
-exception @cite{Program_Error} is raised.
+@itemize -
@item
-@emph{Restrictions on instantiations}
+Only code at the library level and in package body statements within all
+units in a partition is considered to be elaboration code.
+
+@item
+All invocations in elaboration will take place at run time, regardless of
+conditional execution.
+@end 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.
-A generic unit can only be instantiated if the body of the generic
-unit has been elaborated. Again, the rules for elaboration given above
-guarantee that the spec of the generic unit has been elaborated
-before the instantiation, but not the body. If this rule is
-violated, then the exception @cite{Program_Error} is raised.
+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.
+
+The static model is the default model in GNAT.
@end itemize
-The idea is that if the body has been elaborated, then any variables
-it references must have been elaborated; by checking for the body being
-elaborated we guarantee that none of its references causes any
-trouble. As we noted above, this is a little too restrictive, because a
-subprogram that has no non-local references in its body may in fact be safe
-to call. However, it really would be unsafe to rely on this, because
-it would mean that the caller was aware of details of the implementation
-in the body. This goes against the basic tenets of Ada.
-
-A plausible implementation can be described as follows.
-A Boolean variable is associated with each subprogram
-and each generic unit. This variable is initialized to False, and is set to
-True at the point body is elaborated. Every call or instantiation checks the
-variable, and raises @cite{Program_Error} if the variable is False.
-
-Note that one might think that it would be good enough to have one Boolean
-variable for each package, but that would not deal with cases of trying
-to call a body in the same package as the call
-that has not been elaborated yet.
-Of course a compiler may be able to do enough analysis to optimize away
-some of the Boolean variables as unnecessary, and @cite{GNAT} indeed
-does such optimizations, but still the easiest conceptual model is to
-think of there being one variable per subprogram.
-
-@node Controlling the Elaboration Order,Controlling Elaboration in GNAT - Internal Calls,Checking the Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id4}@anchor{2be}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-the-elaboration-order}@anchor{2bf}
-@section Controlling the Elaboration Order
-
-
-In the previous section we discussed the rules in Ada which ensure
-that @cite{Program_Error} is raised if an incorrect elaboration order is
-chosen. This prevents erroneous executions, but we need mechanisms to
-specify a correct execution and avoid the exception altogether.
-To achieve this, Ada provides a number of features for controlling
-the order of elaboration. We discuss these features in this section.
-
-First, there are several ways of indicating to the compiler that a given
-unit has no elaboration problems:
+@geindex SPARK elaboration model
@itemize *
@item
-@emph{packages that do not require a body}
-
-A library package that does not require a body does not permit
-a body (this rule was introduced in Ada 95).
-Thus if we have a such a package, as in:
+@emph{SPARK elaboration model}
-@example
-package Definitions is
- generic
- type m is new integer;
- package Subp is
- type a is array (1 .. 10) of m;
- type b is array (1 .. 20) of m;
- end Subp;
-end Definitions;
-@end example
+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.
-A package that @emph{with}s @cite{Definitions} may safely instantiate
-@cite{Definitions.Subp} because the compiler can determine that there
-definitely is no package body to worry about in this case
+The SPARK model is enabled with compiler switch @code{-gnatd.v}.
@end itemize
-@geindex pragma Pure
+@geindex Legacy elaboration models
@itemize *
@item
-@emph{pragma Pure}
+@emph{Legacy elaboration models}
+
+In addition to the three elaboration models outlined above, GNAT provides the
+following legacy models:
+
+
+@itemize -
+
+@item
+@cite{Legacy elaboration-checking model} available in pre-18.x versions of GNAT.
+This model is enabled with compiler switch @code{-gnatH}.
-This pragma places sufficient restrictions on a unit to guarantee that
-no call to any subprogram in the unit can result in an
-elaboration problem. This means that the compiler does not need
-to worry about the point of elaboration of such units, and in
-particular, does not need to check any calls to any subprograms
-in this unit.
+@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
-@geindex pragma Preelaborate
+@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 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
+
+
+It is possible to mix units compiled with a different elaboration model,
+however the following rules must be observed:
@itemize *
@item
-@emph{pragma Preelaborate}
+A client unit compiled with the dynamic model can only @emph{with} a server unit
+that meets at least one of the following criteria:
-This pragma places slightly less stringent restrictions on a unit than
-does pragma Pure,
-but these restrictions are still sufficient to ensure that there
-are no elaboration problems with any calls to the unit.
+
+@itemize -
+
+@item
+The server unit is compiled with the dynamic model.
+
+@item
+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}.
+
+@item
+The client unit has an explicit @code{Elaborate_All} pragma for the server
+unit.
+@end itemize
@end itemize
-@geindex pragma Elaborate_Body
+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 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.
+
+@quotation
+
+@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
+@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
+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
+ 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
-@itemize *
+@example
+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
-@item
-@emph{pragma Elaborate_Body}
+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.
-This pragma requires that the body of a unit be elaborated immediately
-after its spec. Suppose a unit @cite{A} has such a pragma,
-and unit @cite{B} does
-a @emph{with} of unit @cite{A}. Recall that the standard rules require
-the spec of unit @cite{A}
-to be elaborated before the @emph{with}ing unit; given the pragma in
-@cite{A}, we also know that the body of @cite{A}
-will be elaborated before @cite{B}, so
-that calls to @cite{A} are safe and do not need a check.
-
-Note that, unlike pragma @cite{Pure} and pragma @cite{Preelaborate},
-the use of @cite{Elaborate_Body} does not guarantee that the program is
-free of elaboration problems, because it may not be possible
-to satisfy the requested elaboration order.
-Let's go back to the example with @cite{Unit_1} and @cite{Unit_2}.
-If a programmer marks @cite{Unit_1} as @cite{Elaborate_Body},
-and not @cite{Unit_2@comma{}} then the order of
-elaboration will be:
-
-@example
-Spec of Unit_2
-Spec of Unit_1
-Body of Unit_1
-Body of Unit_2
-@end example
-
-Now that means that the call to @cite{Func_1} in @cite{Unit_2}
-need not be checked,
-it must be safe. But the call to @cite{Func_2} in
-@cite{Unit_1} may still fail if
-@cite{Expression_1} is equal to 1,
-and the programmer must still take
-responsibility for this not being the case.
-
-If all units carry a pragma @cite{Elaborate_Body}, then all problems are
-eliminated, except for calls entirely within a body, which are
-in any case fully under programmer control. However, using the pragma
-everywhere is not always possible.
-In particular, for our @cite{Unit_1}/@cite{Unit_2} example, if
-we marked both of them as having pragma @cite{Elaborate_Body}, then
-clearly there would be no possible elaboration order.
-@end itemize
+@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
-The above pragmas allow a server to guarantee safe use by clients, and
-clearly this is the preferable approach. Consequently a good rule
-is to mark units as @cite{Pure} or @cite{Preelaborate} if possible,
-and if this is not possible,
-mark them as @cite{Elaborate_Body} if possible.
-As we have seen, there are situations where neither of these
-three pragmas can be used.
-So we also provide methods for clients to control the
-order of elaboration of the servers on which they depend:
-@geindex pragma Elaborate
+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
-@itemize *
+@example
+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
-@item
-@emph{pragma Elaborate (unit)}
+4. end SPARK_Diagnostics;
+@end example
+@end quotation
-This pragma is placed in the context clause, after a @emph{with} clause,
-and it requires that the body of the named unit be elaborated before
-the unit in which the pragma occurs. The idea is to use this pragma
-if the current unit calls at elaboration time, directly or indirectly,
-some subprogram in the named unit.
-@end itemize
+@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
-@geindex pragma Elaborate_All
+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.
-@itemize *
+The following example exhibits an elaboration circularity.
-@item
-@emph{pragma Elaborate_All (unit)}
+@quotation
-This is a stronger version of the Elaborate pragma. Consider the
-following example:
+@example
+with B; pragma Elaborate (B);
+package A is
+end A;
+@end example
@example
-Unit A |withs| unit B and calls B.Func in elab code
-Unit B |withs| unit C, and B.Func calls C.Func
+package B is
+ procedure Force_Body;
+end B;
@end example
-Now if we put a pragma @cite{Elaborate (B)}
-in unit @cite{A}, this ensures that the
-body of @cite{B} is elaborated before the call, but not the
-body of @cite{C}, so
-the call to @cite{C.Func} could still cause @cite{Program_Error} to
-be raised.
+@example
+with C;
+package body B is
+ procedure Force_Body is null;
-The effect of a pragma @cite{Elaborate_All} is stronger, it requires
-not only that the body of the named unit be elaborated before the
-unit doing the @emph{with}, but also the bodies of all units that the
-named unit uses, following @emph{with} links transitively. For example,
-if we put a pragma @cite{Elaborate_All (B)} in unit @cite{A},
-then it requires not only that the body of @cite{B} be elaborated before @cite{A},
-but also the body of @cite{C}, because @cite{B} @emph{with}s @cite{C}.
-@end itemize
+ Elab : constant Integer := C.Func;
+end B;
+@end example
-We are now in a position to give a usage rule in Ada for avoiding
-elaboration problems, at least if dynamic dispatching and access to
-subprogram values are not used. We will handle these cases separately
-later.
+@example
+package C is
+ function Func return Integer;
+end C;
+@end example
-The rule is simple:
+@example
+with A;
+package body C is
+ function Func return Integer is
+ begin
+ ...
+ end Func;
+end C;
+@end example
+@end quotation
-@emph{If a unit has elaboration code that can directly or
-indirectly make a call to a subprogram in a |withed| unit, or instantiate
-a generic package in a |withed| unit,
-then if the |withed| unit does not have
-pragma `Pure` or `Preelaborate`, then the client should have
-a pragma `Elaborate_All`for the |withed| unit.*}
+The binder emits the following diagnostic:
-By following this rule a client is
-assured that calls can be made without risk of an exception.
+@quotation
-For generic subprogram instantiations, the rule can be relaxed to
-require only a pragma @cite{Elaborate} since elaborating the body
-of a subprogram cannot cause any transitive elaboration (we are
-not calling the subprogram in this case, just elaborating its
-declaration).
+@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
-If this rule is not followed, then a program may be in one of four
-states:
+The diagnostic consist of the following sections:
@itemize *
@item
-@emph{No order exists}
+Reason
-No order of elaboration exists which follows the rules, taking into
-account any @cite{Elaborate}, @cite{Elaborate_All},
-or @cite{Elaborate_Body} pragmas. In
-this case, an Ada compiler must diagnose the situation at bind
-time, and refuse to build an executable program.
+This section provides a short explanation describing why the set of units
+could not be ordered.
@item
-@emph{One or more orders exist, all incorrect}
+Circularity
-One or more acceptable elaboration orders exist, and all of them
-generate an elaboration order problem. In this case, the binder
-can build an executable program, but @cite{Program_Error} will be raised
-when the program is run.
+This section enumerates the units comprising the deadlocked set, along with
+their interdependencies.
@item
-@emph{Several orders exist, some right, some incorrect}
+Suggestions
-One or more acceptable elaboration orders exists, and some of them
-work, and some do not. The programmer has not controlled
-the order of elaboration, so the binder may or may not pick one of
-the correct orders, and the program may or may not raise an
-exception when it is run. This is the worst case, because it means
-that the program may fail when moved to another compiler, or even
-another version of the same compiler.
+This section enumerates various tactics for eliminating the circularity.
+@end itemize
-@item
-@emph{One or more orders exists, all correct}
+@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
-One ore more acceptable elaboration orders exist, and all of them
-work. In this case the program runs successfully. This state of
-affairs can be guaranteed by following the rule we gave above, but
-may be true even if the rule is not followed.
-@end itemize
-Note that one additional advantage of following our rules on the use
-of @cite{Elaborate} and @cite{Elaborate_All}
-is that the program continues to stay in the ideal (all orders OK) state
-even if maintenance
-changes some bodies of some units. Conversely, if a program that does
-not follow this rule happens to be safe at some point, this state of affairs
-may deteriorate silently as a result of maintenance changes.
+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.
-You may have noticed that the above discussion did not mention
-the use of @cite{Elaborate_Body}. This was a deliberate omission. If you
-@emph{with} an @cite{Elaborate_Body} unit, it still may be the case that
-code in the body makes calls to some other unit, so it is still necessary
-to use @cite{Elaborate_All} on such units.
+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:
-@node Controlling Elaboration in GNAT - Internal Calls,Controlling Elaboration in GNAT - External Calls,Controlling the Elaboration Order,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id5}@anchor{2c0}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-internal-calls}@anchor{2c1}
-@section Controlling Elaboration in GNAT - Internal Calls
+@itemize *
-In the case of internal calls, i.e., calls within a single package, the
-programmer has full control over the order of elaboration, and it is up
-to the programmer to elaborate declarations in an appropriate order. For
-example writing:
+@item
+Pragma Elaborate elimination
@example
-function One return Float;
+remove pragma Elaborate for unit "..." in unit "..."
+@end example
-Q : Float := One;
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate}:
-function One return Float is
-begin
- return 1.0;
-end One;
-@end example
-will obviously raise @cite{Program_Error} at run time, because function
-One will be called before its body is elaborated. In this case GNAT will
-generate a warning that the call will raise @cite{Program_Error}:
+@itemize -
-@example
- 1. procedure y is
- 2. function One return Float;
- 3.
- 4. Q : Float := One;
- |
- >>> warning: cannot call "One" before body is elaborated
- >>> warning: Program_Error will be raised at run time
+@item
+Prevents a set of units from being elaborated.
- 5.
- 6. function One return Float is
- 7. begin
- 8. return 1.0;
- 9. end One;
-10.
-11. begin
-12. null;
-13. end;
-@end example
+@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.
-Note that in this particular case, it is likely that the call is safe, because
-the function @cite{One} does not access any global variables.
-Nevertheless in Ada, we do not want the validity of the check to depend on
-the contents of the body (think about the separate compilation case), so this
-is still wrong, as we discussed in the previous sections.
+@item
+The removal of the pragma will enable the successful ordering of the units.
+@end itemize
-The error is easily corrected by rearranging the declarations so that the
-body of @cite{One} appears before the declaration containing the call
-(note that in Ada 95 as well as later versions of the Ada standard,
-declarations can appear in any order, so there is no restriction that
-would prevent this reordering, and if we write:
+The programmer should remove the pragma as advised, and rebuild the program.
+
+@item
+Pragma Elaborate_All elimination
@example
-function One return Float;
+remove pragma Elaborate_All for unit "..." in unit "..."
+@end example
-function One return Float is
-begin
- return 1.0;
-end One;
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate_All}:
-Q : Float := One;
-@end example
-then all is well, no warning is generated, and no
-@cite{Program_Error} exception
-will be raised.
-Things are more complicated when a chain of subprograms is executed:
+@itemize -
-@example
-function A return Integer;
-function B return Integer;
-function C return Integer;
+@item
+Prevents a set of units from being elaborated.
-function B return Integer is begin return A; end;
-function C return Integer is begin return B; end;
+@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.
-X : Integer := C;
+@item
+The removal of the pragma will enable the successful ordering of the units.
+@end itemize
-function A return Integer is begin return 1; end;
-@end example
+The programmer should remove the pragma as advised, and rebuild the program.
-Now the call to @cite{C}
-at elaboration time in the declaration of @cite{X} is correct, because
-the body of @cite{C} is already elaborated,
-and the call to @cite{B} within the body of
-@cite{C} is correct, but the call
-to @cite{A} within the body of @cite{B} is incorrect, because the body
-of @cite{A} has not been elaborated, so @cite{Program_Error}
-will be raised on the call to @cite{A}.
-In this case GNAT will generate a
-warning that @cite{Program_Error} may be
-raised at the point of the call. Let's look at the warning:
+@item
+Pragma Elaborate_All downgrade
@example
- 1. procedure x is
- 2. function A return Integer;
- 3. function B return Integer;
- 4. function C return Integer;
- 5.
- 6. function B return Integer is begin return A; end;
- |
- >>> warning: call to "A" before body is elaborated may
- raise Program_Error
- >>> warning: "B" called at line 7
- >>> warning: "C" called at line 9
-
- 7. function C return Integer is begin return B; end;
- 8.
- 9. X : Integer := C;
-10.
-11. function A return Integer is begin return 1; end;
-12.
-13. begin
-14. null;
-15. end;
-@end example
-
-Note that the message here says 'may raise', instead of the direct case,
-where the message says 'will be raised'. That's because whether
-@cite{A} is
-actually called depends in general on run-time flow of control.
-For example, if the body of @cite{B} said
-
-@example
-function B return Integer is
-begin
- if some-condition-depending-on-input-data then
- return A;
- else
- return 1;
- end if;
-end B;
+change pragma Elaborate_All for unit "..." to Elaborate in unit "..."
@end example
-then we could not know until run time whether the incorrect call to A would
-actually occur, so @cite{Program_Error} might
-or might not be raised. It is possible for a compiler to
-do a better job of analyzing bodies, to
-determine whether or not @cite{Program_Error}
-might be raised, but it certainly
-couldn't do a perfect job (that would require solving the halting problem
-and is provably impossible), and because this is a warning anyway, it does
-not seem worth the effort to do the analysis. Cases in which it
-would be relevant are rare.
+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.
-In practice, warnings of either of the forms given
-above will usually correspond to
-real errors, and should be examined carefully and eliminated.
-In the rare case where a warning is bogus, it can be suppressed by any of
-the following methods:
+The programmer should update the pragma as advised, and rebuild the program.
+@item
+Pragma Elaborate_Body elimination
-@itemize *
+@example
+remove pragma Elaborate_Body in unit "..."
+@end example
+
+This tactic is suggested when the binder has determined that pragma
+@code{Elaborate_Body}:
-@item
-Compile with the @emph{-gnatws} switch set
+
+@itemize -
@item
-Suppress @cite{Elaboration_Check} for the called subprogram
+Prevents a set of units from being elaborated.
@item
-Use pragma @cite{Warnings_Off} to turn warnings off for the call
+The removal of the pragma will enable the successful ordering of the units.
@end itemize
-For the internal elaboration check case,
-GNAT by default generates the
-necessary run-time checks to ensure
-that @cite{Program_Error} is raised if any
-call fails an elaboration check. Of course this can only happen if a
-warning has been issued as described above. The use of pragma
-@cite{Suppress (Elaboration_Check)} may (but is not guaranteed to) suppress
-some of these checks, meaning that it may be possible (but is not
-guaranteed) for a program to be able to call a subprogram whose body
-is not yet elaborated, without raising a @cite{Program_Error} exception.
+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.
-@node Controlling Elaboration in GNAT - External Calls,Default Behavior in GNAT - Ensuring Safety,Controlling Elaboration in GNAT - Internal Calls,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id6}@anchor{2c2}@anchor{gnat_ugn/elaboration_order_handling_in_gnat controlling-elaboration-in-gnat-external-calls}@anchor{2c3}
-@section Controlling Elaboration in GNAT - External Calls
+The programmer should remove the pragma as advised, and rebuild the program.
-
-The previous section discussed the case in which the execution of a
-particular thread of elaboration code occurred entirely within a
-single unit. This is the easy case to handle, because a programmer
-has direct and total control over the order of elaboration, and
-furthermore, checks need only be generated in cases which are rare
-and which the compiler can easily detect.
-The situation is more complex when separate compilation is taken into account.
-Consider the following:
+@item
+Use of pragma Restrictions
@example
-package Math is
- function Sqrt (Arg : Float) return Float;
-end Math;
+use pragma Restrictions (No_Entry_Calls_In_Elaboration_Code)
+@end example
-package body Math is
- function Sqrt (Arg : Float) return Float is
- begin
- ...
- end Sqrt;
-end Math;
+This tactic is suggested when the binder has determined that a task
+activation at elaboration time:
-with Math;
-package Stuff is
- X : Float := Math.Sqrt (0.5);
-end Stuff;
-with Stuff;
-procedure Main is
-begin
- ...
-end Main;
-@end example
+@itemize -
+
+@item
+Prevents a set of units from being elaborated.
+@end itemize
-where @cite{Main} is the main program. When this program is executed, the
-elaboration code must first be executed, and one of the jobs of the
-binder is to determine the order in which the units of a program are
-to be elaborated. In this case we have four units: the spec and body
-of @cite{Math},
-the spec of @cite{Stuff} and the body of @cite{Main}).
-In what order should the four separate sections of elaboration code
-be executed?
+Note that the binder cannot determine with certainty whether the task will
+block at elaboration time.
-There are some restrictions in the order of elaboration that the binder
-can choose. In particular, if unit U has a @emph{with}
-for a package @cite{X}, then you
-are assured that the spec of @cite{X}
-is elaborated before U , but you are
-not assured that the body of @cite{X}
-is elaborated before U.
-This means that in the above case, the binder is allowed to choose the
-order:
+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
-spec of Math
-spec of Stuff
-body of Math
-body of Main
+use the dynamic elaboration model (compiler switch -gnatE)
@end example
-but that's not good, because now the call to @cite{Math.Sqrt}
-that happens during
-the elaboration of the @cite{Stuff}
-spec happens before the body of @cite{Math.Sqrt} is
-elaborated, and hence causes @cite{Program_Error} exception to be raised.
-At first glance, one might say that the binder is misbehaving, because
-obviously you want to elaborate the body of something you @emph{with} first, but
-that is not a general rule that can be followed in all cases. Consider
-
-@example
-package X is ...
-
-package Y is ...
-
-with X;
-package body Y is ...
-
-with Y;
-package body X is ...
-@end example
-
-This is a common arrangement, and, apart from the order of elaboration
-problems that might arise in connection with elaboration code, this works fine.
-A rule that says that you must first elaborate the body of anything you
-@emph{with} cannot work in this case:
-the body of @cite{X} @emph{with}s @cite{Y},
-which means you would have to
-elaborate the body of @cite{Y} first, but that @emph{with}s @cite{X},
-which means
-you have to elaborate the body of @cite{X} first, but ... and we have a
-loop that cannot be broken.
-
-It is true that the binder can in many cases guess an order of elaboration
-that is unlikely to cause a @cite{Program_Error}
-exception to be raised, and it tries to do so (in the
-above example of @cite{Math/Stuff/Spec}, the GNAT binder will
-by default
-elaborate the body of @cite{Math} right after its spec, so all will be well).
-
-However, a program that blindly relies on the binder to be helpful can
-get into trouble, as we discussed in the previous sections, so GNAT
-provides a number of facilities for assisting the programmer in
-developing programs that are robust with respect to elaboration order.
-
-@node Default Behavior in GNAT - Ensuring Safety,Treatment of Pragma Elaborate,Controlling Elaboration in GNAT - External Calls,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id7}@anchor{2c4}@anchor{gnat_ugn/elaboration_order_handling_in_gnat default-behavior-in-gnat-ensuring-safety}@anchor{2c5}
-@section Default Behavior in GNAT - Ensuring Safety
-
-
-The default behavior in GNAT ensures elaboration safety. In its
-default mode GNAT implements the
-rule we previously described as the right approach. Let's restate it:
-
-@emph{If a unit has elaboration code that can directly or indirectly make a
-call to a subprogram in a |withed| unit, or instantiate a generic
-package in a |withed| unit, then if the |withed| unit
-does not have pragma `Pure` or `Preelaborate`, then the client should have an
-`Elaborate_All` pragma for the |withed| unit.}
-
-@emph{In the case of instantiating a generic subprogram, it is always
-sufficient to have only an `Elaborate` pragma for the
-|withed| unit.}
-
-By following this rule a client is assured that calls and instantiations
-can be made without risk of an exception.
-
-In this mode GNAT traces all calls that are potentially made from
-elaboration code, and puts in any missing implicit @cite{Elaborate}
-and @cite{Elaborate_All} pragmas.
-The advantage of this approach is that no elaboration problems
-are possible if the binder can find an elaboration order that is
-consistent with these implicit @cite{Elaborate} and
-@cite{Elaborate_All} pragmas. The
-disadvantage of this approach is that no such order may exist.
-
-If the binder does not generate any diagnostics, then it means that it has
-found an elaboration order that is guaranteed to be safe. However, the binder
-may still be relying on implicitly generated @cite{Elaborate} and
-@cite{Elaborate_All} pragmas so portability to other compilers than GNAT is not
-guaranteed.
-
-If it is important to guarantee portability, then the compilations should
-use the @emph{-gnatel}
-(info messages for elaboration pragmas) switch. This will cause info messages
-to be generated indicating the missing @cite{Elaborate} and
-@cite{Elaborate_All} pragmas.
-Consider the following source program:
-
-@example
-with k;
-package j is
- m : integer := k.r;
-end;
-@end example
+This tactic is suggested when the binder has determined that an invocation at
+elaboration time:
-where it is clear that there
-should be a pragma @cite{Elaborate_All}
-for unit @cite{k}. An implicit pragma will be generated, and it is
-likely that the binder will be able to honor it. However, if you want
-to port this program to some other Ada compiler than GNAT.
-it is safer to include the pragma explicitly in the source. If this
-unit is compiled with the @emph{-gnatel}
-switch, then the compiler outputs an information message:
-
-@example
-1. with k;
-2. package j is
-3. m : integer := k.r;
- |
- >>> info: call to "r" may raise Program_Error
- >>> info: missing pragma Elaborate_All for "k"
-
-4. end;
-@end example
-
-and these messages can be used as a guide for supplying manually
-the missing pragmas. It is usually a bad idea to use this
-option during development. That's because it will tell you when
-you need to put in a pragma, but cannot tell you when it is time
-to take it out. So the use of pragma @cite{Elaborate_All} may lead to
-unnecessary dependencies and even false circularities.
-
-This default mode is more restrictive than the Ada Reference
-Manual, and it is possible to construct programs which will compile
-using the dynamic model described there, but will run into a
-circularity using the safer static model we have described.
-
-Of course any Ada compiler must be able to operate in a mode
-consistent with the requirements of the Ada Reference Manual,
-and in particular must have the capability of implementing the
-standard dynamic model of elaboration with run-time checks.
-
-In GNAT, this standard mode can be achieved either by the use of
-the @emph{-gnatE} switch on the compiler (@emph{gcc} or
-@emph{gnatmake}) command, or by the use of the configuration pragma:
-
-@example
-pragma Elaboration_Checks (DYNAMIC);
-@end example
-
-Either approach will cause the unit affected to be compiled using the
-standard dynamic run-time elaboration checks described in the Ada
-Reference Manual. The static model is generally preferable, since it
-is clearly safer to rely on compile and link time checks rather than
-run-time checks. However, in the case of legacy code, it may be
-difficult to meet the requirements of the static model. This
-issue is further discussed in
-@ref{2c6,,What to Do If the Default Elaboration Behavior Fails}.
-
-Note that the static model provides a strict subset of the allowed
-behavior and programs of the Ada Reference Manual, so if you do
-adhere to the static model and no circularities exist,
-then you are assured that your program will
-work using the dynamic model, providing that you remove any
-pragma Elaborate statements from the source.
-
-@node Treatment of Pragma Elaborate,Elaboration Issues for Library Tasks,Default Behavior in GNAT - Ensuring Safety,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat treatment-of-pragma-elaborate}@anchor{2c7}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id8}@anchor{2c8}
-@section Treatment of Pragma Elaborate
-
-
-@geindex Pragma Elaborate
-
-The use of @cite{pragma Elaborate}
-should generally be avoided in Ada 95 and Ada 2005 programs,
-since there is no guarantee that transitive calls
-will be properly handled. Indeed at one point, this pragma was placed
-in Annex J (Obsolescent Features), on the grounds that it is never useful.
-
-Now that's a bit restrictive. In practice, the case in which
-@cite{pragma Elaborate} is useful is when the caller knows that there
-are no transitive calls, or that the called unit contains all necessary
-transitive @cite{pragma Elaborate} statements, and legacy code often
-contains such uses.
-
-Strictly speaking the static mode in GNAT should ignore such pragmas,
-since there is no assurance at compile time that the necessary safety
-conditions are met. In practice, this would cause GNAT to be incompatible
-with correctly written Ada 83 code that had all necessary
-@cite{pragma Elaborate} statements in place. Consequently, we made the
-decision that GNAT in its default mode will believe that if it encounters
-a @cite{pragma Elaborate} then the programmer knows what they are doing,
-and it will trust that no elaboration errors can occur.
-
-The result of this decision is two-fold. First to be safe using the
-static mode, you should remove all @cite{pragma Elaborate} statements.
-Second, when fixing circularities in existing code, you can selectively
-use @cite{pragma Elaborate} statements to convince the static mode of
-GNAT that it need not generate an implicit @cite{pragma Elaborate_All}
-statement.
-
-When using the static mode with @emph{-gnatwl}, any use of
-@cite{pragma Elaborate} will generate a warning about possible
-problems.
-@node Elaboration Issues for Library Tasks,Mixing Elaboration Models,Treatment of Pragma Elaborate,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-issues-for-library-tasks}@anchor{2c9}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id9}@anchor{2ca}
-@section Elaboration Issues for Library Tasks
-
-
-@geindex Library tasks
-@geindex elaboration issues
-
-@geindex Elaboration of library tasks
-
-In this section we examine special elaboration issues that arise for
-programs that declare library level tasks.
-
-Generally the model of execution of an Ada program is that all units are
-elaborated, and then execution of the program starts. However, the
-declaration of library tasks definitely does not fit this model. The
-reason for this is that library tasks start as soon as they are declared
-(more precisely, as soon as the statement part of the enclosing package
-body is reached), that is to say before elaboration
-of the program is complete. This means that if such a task calls a
-subprogram, or an entry in another task, the callee may or may not be
-elaborated yet, and in the standard
-Reference Manual model of dynamic elaboration checks, you can even
-get timing dependent Program_Error exceptions, since there can be
-a race between the elaboration code and the task code.
-
-The static model of elaboration in GNAT seeks to avoid all such
-dynamic behavior, by being conservative, and the conservative
-approach in this particular case is to assume that all the code
-in a task body is potentially executed at elaboration time if
-a task is declared at the library level.
-
-This can definitely result in unexpected circularities. Consider
-the following example
-
-@example
-package Decls is
- task Lib_Task is
- entry Start;
- end Lib_Task;
-
- type My_Int is new Integer;
-
- function Ident (M : My_Int) return My_Int;
-end Decls;
-
-with Utils;
-package body Decls is
- task body Lib_Task is
- begin
- accept Start;
- Utils.Put_Val (2);
- end Lib_Task;
-
- function Ident (M : My_Int) return My_Int is
- begin
- return M;
- end Ident;
-end Decls;
-
-with Decls;
-package Utils is
- procedure Put_Val (Arg : Decls.My_Int);
-end Utils;
-
-with Text_IO;
-package body Utils is
- procedure Put_Val (Arg : Decls.My_Int) is
- begin
- Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg)));
- end Put_Val;
-end Utils;
-
-with Decls;
-procedure Main is
-begin
- Decls.Lib_Task.Start;
-end;
-@end example
+@itemize -
-If the above example is compiled in the default static elaboration
-mode, then a circularity occurs. The circularity comes from the call
-@cite{Utils.Put_Val} in the task body of @cite{Decls.Lib_Task}. Since
-this call occurs in elaboration code, we need an implicit pragma
-@cite{Elaborate_All} for @cite{Utils}. This means that not only must
-the spec and body of @cite{Utils} be elaborated before the body
-of @cite{Decls}, but also the spec and body of any unit that is
-@emph{with}ed by the body of @cite{Utils} must also be elaborated before
-the body of @cite{Decls}. This is the transitive implication of
-pragma @cite{Elaborate_All} and it makes sense, because in general
-the body of @cite{Put_Val} might have a call to something in a
-@emph{with}ed unit.
+@item
+Prevents a set of units from being elaborated.
-In this case, the body of Utils (actually its spec) @emph{with}s
-@cite{Decls}. Unfortunately this means that the body of @cite{Decls}
-must be elaborated before itself, in case there is a call from the
-body of @cite{Utils}.
+@item
+The use of the dynamic model will enable the successful ordering of the
+units.
+@end itemize
-Here is the exact chain of events we are worrying about:
+The programmer has two options:
-@itemize *
+@itemize -
@item
-In the body of @cite{Decls} a call is made from within the body of a library
-task to a subprogram in the package @cite{Utils}. Since this call may
-occur at elaboration time (given that the task is activated at elaboration
-time), we have to assume the worst, i.e., that the
-call does happen at elaboration time.
+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.
@item
-This means that the body and spec of @cite{Util} must be elaborated before
-the body of @cite{Decls} so that this call does not cause an access before
-elaboration.
+Add compiler switch @code{-gnatE} to the general compilation arguments.
+@end itemize
@item
-Within the body of @cite{Util}, specifically within the body of
-@cite{Util.Put_Val} there may be calls to any unit @emph{with}ed
-by this package.
+Use of detailed invocation information
-@item
-One such @emph{with}ed package is package @cite{Decls}, so there
-might be a call to a subprogram in @cite{Decls} in @cite{Put_Val}.
-In fact there is such a call in this example, but we would have to
-assume that there was such a call even if it were not there, since
-we are not supposed to write the body of @cite{Decls} knowing what
-is in the body of @cite{Utils}; certainly in the case of the
-static elaboration model, the compiler does not know what is in
-other bodies and must assume the worst.
+@example
+use detailed invocation information (compiler switch -gnatd_F)
+@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.
+
+The programmer should analyze this information to determine which units
+should be compiled with the dynamic model.
@item
-This means that the spec and body of @cite{Decls} must also be
-elaborated before we elaborate the unit containing the call, but
-that unit is @cite{Decls}! This means that the body of @cite{Decls}
-must be elaborated before itself, and that's a circularity.
-@end itemize
+Forced-dependency elimination
-Indeed, if you add an explicit pragma @cite{Elaborate_All} for @cite{Utils} in
-the body of @cite{Decls} you will get a true Ada Reference Manual
-circularity that makes the program illegal.
+@example
+remove the dependency of unit "..." on unit "..." from the argument of switch -f
+@end example
-In practice, we have found that problems with the static model of
-elaboration in existing code often arise from library tasks, so
-we must address this particular situation.
+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}:
-Note that if we compile and run the program above, using the dynamic model of
-elaboration (that is to say use the @emph{-gnatE} switch),
-then it compiles, binds,
-links, and runs, printing the expected result of 2. Therefore in some sense
-the circularity here is only apparent, and we need to capture
-the properties of this program that distinguish it from other library-level
-tasks that have real elaboration problems.
-We have four possible answers to this question:
+@itemize -
+@item
+Prevents a set of units from being elaborated.
-@itemize *
+@item
+The removal of the dependency will enable the successful ordering of the
+units.
+@end itemize
+
+The programmer should edit the forced-elaboration-order file, remove the
+dependency, and rebind the program.
@item
-Use the dynamic model of elaboration.
-
-If we use the @emph{-gnatE} switch, then as noted above, the program works.
-Why is this? If we examine the task body, it is apparent that the task cannot
-proceed past the
-@cite{accept} statement until after elaboration has been completed, because
-the corresponding entry call comes from the main program, not earlier.
-This is why the dynamic model works here. But that's really giving
-up on a precise analysis, and we prefer to take this approach only if we cannot
-solve the
-problem in any other manner. So let us examine two ways to reorganize
-the program to avoid the potential elaboration problem.
-
-@item
-Split library tasks into separate packages.
-
-Write separate packages, so that library tasks are isolated from
-other declarations as much as possible. Let us look at a variation on
-the above program.
-
-@example
-package Decls1 is
- task Lib_Task is
- entry Start;
- end Lib_Task;
-end Decls1;
-
-with Utils;
-package body Decls1 is
- task body Lib_Task is
- begin
- accept Start;
- Utils.Put_Val (2);
- end Lib_Task;
-end Decls1;
-
-package Decls2 is
- type My_Int is new Integer;
- function Ident (M : My_Int) return My_Int;
-end Decls2;
-
-with Utils;
-package body Decls2 is
- function Ident (M : My_Int) return My_Int is
- begin
- return M;
- end Ident;
-end Decls2;
-
-with Decls2;
-package Utils is
- procedure Put_Val (Arg : Decls2.My_Int);
-end Utils;
-
-with Text_IO;
-package body Utils is
- procedure Put_Val (Arg : Decls2.My_Int) is
- begin
- Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg)));
- end Put_Val;
-end Utils;
-
-with Decls1;
-procedure Main is
-begin
- Decls1.Lib_Task.Start;
-end;
+All forced-dependency elimination
+
+@example
+remove switch -f
@end example
-All we have done is to split @cite{Decls} into two packages, one
-containing the library task, and one containing everything else. Now
-there is no cycle, and the program compiles, binds, links and executes
-using the default static model of elaboration.
+This tactic is suggested in case editing the forced-elaboration-order file is
+not an option.
-@item
-Declare separate task types.
+The programmer should remove binder switch @code{-f} from the binder
+arguments, and rebind.
-A significant part of the problem arises because of the use of the
-single task declaration form. This means that the elaboration of
-the task type, and the elaboration of the task itself (i.e., the
-creation of the task) happen at the same time. A good rule
-of style in Ada is to always create explicit task types. By
-following the additional step of placing task objects in separate
-packages from the task type declaration, many elaboration problems
-are avoided. Here is another modified example of the example program:
+@item
+Multiple-circularities diagnostic
@example
-package Decls is
- task type Lib_Task_Type is
- entry Start;
- end Lib_Task_Type;
+diagnose all circularities (binder switch -d_C)
+@end example
- type My_Int is new Integer;
+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.
- function Ident (M : My_Int) return My_Int;
-end Decls;
+The programmer should add binder switch @code{-d_C} to the binder
+arguments, and rebind.
+@end itemize
-with Utils;
-package body Decls is
- task body Lib_Task_Type is
- begin
- accept Start;
- Utils.Put_Val (2);
- end Lib_Task_Type;
+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:
- function Ident (M : My_Int) return My_Int is
- begin
- return M;
- end Ident;
-end Decls;
-with Decls;
-package Utils is
- procedure Put_Val (Arg : Decls.My_Int);
-end Utils;
+@itemize *
-with Text_IO;
-package body Utils is
- procedure Put_Val (Arg : Decls.My_Int) is
- begin
- Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg)));
- end Put_Val;
-end Utils;
+@item
+Use the pre-20.x legacy elaboration-order model, with binder switch
+@code{-H}.
-with Decls;
-package Declst is
- Lib_Task : Decls.Lib_Task_Type;
-end Declst;
+@item
+Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
+switch @code{-gnatH} and binder switch @code{-H}.
-with Declst;
-procedure Main is
-begin
- Declst.Lib_Task.Start;
-end;
-@end example
+@item
+Use the relaxed static-elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
-What we have done here is to replace the @cite{task} declaration in
-package @cite{Decls} with a @cite{task type} declaration. Then we
-introduce a separate package @cite{Declst} to contain the actual
-task object. This separates the elaboration issues for
-the @cite{task type}
-declaration, which causes no trouble, from the elaboration issues
-of the task object, which is also unproblematic, since it is now independent
-of the elaboration of @cite{Utils}.
-This separation of concerns also corresponds to
-a generally sound engineering principle of separating declarations
-from instances. This version of the program also compiles, binds, links,
-and executes, generating the expected output.
+@item
+Use the relaxed dynamic-elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
+@code{-H}.
@end itemize
-@geindex No_Entry_Calls_In_Elaboration_Code restriction
+@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
-@itemize *
+GNAT has several switches that affect the elaboration model and consequently
+the elaboration order chosen by the binder.
-@item
-Use No_Entry_Calls_In_Elaboration_Code restriction.
+@geindex -gnatE (gnat)
-The previous two approaches described how a program can be restructured
-to avoid the special problems caused by library task bodies. in practice,
-however, such restructuring may be difficult to apply to existing legacy code,
-so we must consider solutions that do not require massive rewriting.
-Let us consider more carefully why our original sample program works
-under the dynamic model of elaboration. The reason is that the code
-in the task body blocks immediately on the @cite{accept}
-statement. Now of course there is nothing to prohibit elaboration
-code from making entry calls (for example from another library level task),
-so we cannot tell in isolation that
-the task will not execute the accept statement during elaboration.
+@table @asis
-However, in practice it is very unusual to see elaboration code
-make any entry calls, and the pattern of tasks starting
-at elaboration time and then immediately blocking on @cite{accept} or
-@cite{select} statements is very common. What this means is that
-the compiler is being too pessimistic when it analyzes the
-whole package body as though it might be executed at elaboration
-time.
+@item @code{-gnatE}
-If we know that the elaboration code contains no entry calls, (a very safe
-assumption most of the time, that could almost be made the default
-behavior), then we can compile all units of the program under control
-of the following configuration pragma:
+Dynamic elaboration checking mode enabled
-@example
-pragma Restrictions (No_Entry_Calls_In_Elaboration_Code);
-@end example
+When this switch is in effect, GNAT activates the dynamic model.
+@end table
-This pragma can be placed in the @code{gnat.adc} file in the usual
-manner. If we take our original unmodified program and compile it
-in the presence of a @code{gnat.adc} containing the above pragma,
-then once again, we can compile, bind, link, and execute, obtaining
-the expected result. In the presence of this pragma, the compiler does
-not trace calls in a task body, that appear after the first @cite{accept}
-or @cite{select} statement, and therefore does not report a potential
-circularity in the original program.
+@geindex -gnatel (gnat)
-The compiler will check to the extent it can that the above
-restriction is not violated, but it is not always possible to do a
-complete check at compile time, so it is important to use this
-pragma only if the stated restriction is in fact met, that is to say
-no task receives an entry call before elaboration of all units is completed.
-@end itemize
-@node Mixing Elaboration Models,What to Do If the Default Elaboration Behavior Fails,Elaboration Issues for Library Tasks,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id10}@anchor{2cb}@anchor{gnat_ugn/elaboration_order_handling_in_gnat mixing-elaboration-models}@anchor{2cc}
-@section Mixing Elaboration Models
+@table @asis
+@item @code{-gnatel}
-So far, we have assumed that the entire program is either compiled
-using the dynamic model or static model, ensuring consistency. It
-is possible to mix the two models, but rules have to be followed
-if this mixing is done to ensure that elaboration checks are not
-omitted.
+Turn on info messages on generated Elaborate[_All] pragmas
-The basic rule is that
-@strong{a unit compiled with the static model cannot
-be |withed| by a unit compiled with the dynamic model}.
-The reason for this is that in the static model, a unit assumes that
-its clients guarantee to use (the equivalent of) pragma
-@cite{Elaborate_All} so that no elaboration checks are required
-in inner subprograms, and this assumption is violated if the
-client is compiled with dynamic checks.
+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.
-The precise rule is as follows. A unit that is compiled with dynamic
-checks can only @emph{with} a unit that meets at least one of the
-following criteria:
+When this switch is in effect, GNAT will emit the following supplementary
+information depending on the elaboration model in effect.
-@itemize *
+@itemize -
@item
-The @emph{with}ed unit is itself compiled with dynamic elaboration
-checks (that is with the @emph{-gnatE} switch.
+@emph{Dynamic model}
-@item
-The @emph{with}ed unit is an internal GNAT implementation unit from
-the System, Interfaces, Ada, or GNAT hierarchies.
+GNAT will indicate missing @code{Elaborate} and @code{Elaborate_All} pragmas for
+all library-level scenarios within the partition.
@item
-The @emph{with}ed unit has pragma Preelaborate or pragma Pure.
+@emph{Static model}
+
+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.
@item
-The @emph{with}ing unit (that is the client) has an explicit pragma
-@cite{Elaborate_All} for the @emph{with}ed unit.
-@end itemize
+@emph{SPARK model}
-If this rule is violated, that is if a unit with dynamic elaboration
-checks @emph{with}s a unit that does not meet one of the above four
-criteria, then the binder (@cite{gnatbind}) will issue a warning
-similar to that in the following example:
+GNAT will indicate how an elaboration requirement is met by the context of
+a unit. This diagnostic requires compiler switch @code{-gnatd.v}.
@example
-warning: "x.ads" has dynamic elaboration checks and with's
-warning: "y.ads" which has static elaboration checks
-@end example
+1. with Server; pragma Elaborate_All (Server);
+2. package Client with SPARK_Mode is
+3. Val : constant Integer := Server.Func;
+ |
+ >>> info: call to "Func" during elaboration in SPARK
+ >>> info: "Elaborate_All" requirement for unit "Server" met by pragma at line 1
-These warnings indicate that the rule has been violated, and that as a result
-elaboration checks may be missed in the resulting executable file.
-This warning may be suppressed using the @emph{-ws} binder switch
-in the usual manner.
+4. end Client;
+@end example
+@end itemize
+@end table
-One useful application of this mixing rule is in the case of a subsystem
-which does not itself @emph{with} units from the remainder of the
-application. In this case, the entire subsystem can be compiled with
-dynamic checks to resolve a circularity in the subsystem, while
-allowing the main application that uses this subsystem to be compiled
-using the more reliable default static model.
+@geindex -gnatH (gnat)
-@node What to Do If the Default Elaboration Behavior Fails,Elaboration for Indirect Calls,Mixing Elaboration Models,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id11}@anchor{2cd}@anchor{gnat_ugn/elaboration_order_handling_in_gnat what-to-do-if-the-default-elaboration-behavior-fails}@anchor{2c6}
-@section What to Do If the Default Elaboration Behavior Fails
+@table @asis
-If the binder cannot find an acceptable order, it outputs detailed
-diagnostics. For example:
+@item @code{-gnatH}
-@example
-error: elaboration circularity detected
-info: "proc (body)" must be elaborated before "pack (body)"
-info: reason: Elaborate_All probably needed in unit "pack (body)"
-info: recompile "pack (body)" with -gnatel
-info: for full details
-info: "proc (body)"
-info: is needed by its spec:
-info: "proc (spec)"
-info: which is withed by:
-info: "pack (body)"
-info: "pack (body)" must be elaborated before "proc (body)"
-info: reason: pragma Elaborate in unit "proc (body)"
-@end example
+Legacy elaboration checking mode enabled
-In this case we have a cycle that the binder cannot break. On the one
-hand, there is an explicit pragma Elaborate in @cite{proc} for
-@cite{pack}. This means that the body of @cite{pack} must be elaborated
-before the body of @cite{proc}. On the other hand, there is elaboration
-code in @cite{pack} that calls a subprogram in @cite{proc}. This means
-that for maximum safety, there should really be a pragma
-Elaborate_All in @cite{pack} for @cite{proc} which would require that
-the body of @cite{proc} be elaborated before the body of
-@cite{pack}. Clearly both requirements cannot be satisfied.
-Faced with a circularity of this kind, you have three different options.
+When this switch is in effect, GNAT will utilize the pre-18.x elaboration
+model.
+@end table
+@geindex -gnatJ (gnat)
-@itemize *
-@item
-@emph{Fix the program}
+@table @asis
-The most desirable option from the point of view of long-term maintenance
-is to rearrange the program so that the elaboration problems are avoided.
-One useful technique is to place the elaboration code into separate
-child packages. Another is to move some of the initialization code to
-explicitly called subprograms, where the program controls the order
-of initialization explicitly. Although this is the most desirable option,
-it may be impractical and involve too much modification, especially in
-the case of complex legacy code.
+@item @code{-gnatJ}
-@item
-@emph{Perform dynamic checks}
+Relaxed elaboration checking mode enabled
-If the compilations are done using the @emph{-gnatE}
-(dynamic elaboration check) switch, then GNAT behaves in a quite different
-manner. Dynamic checks are generated for all calls that could possibly result
-in raising an exception. With this switch, the compiler does not generate
-implicit @cite{Elaborate} or @cite{Elaborate_All} pragmas. The behavior then is
-exactly as specified in the @cite{Ada Reference Manual}.
-The binder will generate
-an executable program that may or may not raise @cite{Program_Error}, and then
-it is the programmer's job to ensure that it does not raise an exception. Note
-that it is important to compile all units with the switch, it cannot be used
-selectively.
+When this switch is in effect, GNAT will not process certain scenarios,
+resulting in a more permissive elaboration model. Note that this may
+eliminate some diagnostics and run-time checks.
+@end table
-@item
-@emph{Suppress checks}
+@geindex -gnatw.f (gnat)
-The drawback of dynamic checks is that they generate a
-significant overhead at run time, both in space and time. If you
-are absolutely sure that your program cannot raise any elaboration
-exceptions, and you still want to use the dynamic elaboration model,
-then you can use the configuration pragma
-@cite{Suppress (Elaboration_Check)} to suppress all such checks. For
-example this pragma could be placed in the @code{gnat.adc} file.
-@item
-@emph{Suppress checks selectively}
+@table @asis
-When you know that certain calls or instantiations in elaboration code cannot
-possibly lead to an elaboration error, and the binder nevertheless complains
-about implicit @cite{Elaborate} and @cite{Elaborate_All} pragmas that lead to
-elaboration circularities, it is possible to remove those warnings locally and
-obtain a program that will bind. Clearly this can be unsafe, and it is the
-responsibility of the programmer to make sure that the resulting program has no
-elaboration anomalies. The pragma @cite{Suppress (Elaboration_Check)} can be
-used with different granularity to suppress warnings and break elaboration
-circularities:
+@item @code{-gnatw.f}
+Turn on warnings for suspicious Subp'Access
-@itemize *
+When this switch is in effect, GNAT will treat @code{'Access} of an entry,
+operator, or subprogram as a potential call to the target and issue warnings:
-@item
-Place the pragma that names the called subprogram in the declarative part
-that contains the call.
+@example
+ 1. package body Attribute_Call is
+ 2. function Func return Integer;
+ 3. type Func_Ptr is access function return Integer;
+ 4.
+ 5. Ptr : constant Func_Ptr := Func'Access;
+ |
+ >>> warning: "Access" attribute of "Func" before body seen
+ >>> warning: possible Program_Error on later references
+ >>> warning: body of unit "Attribute_Call" elaborated
+ >>> warning: "Access" of "Func" taken at line 5
-@item
-Place the pragma in the declarative part, without naming an entity. This
-disables warnings on all calls in the corresponding declarative region.
+ 6.
+ 7. function Func return Integer is
+ 8. begin
+ 9. ...
+10. end Func;
+11. end Attribute_Call;
+@end example
-@item
-Place the pragma in the package spec that declares the called subprogram,
-and name the subprogram. This disables warnings on all elaboration calls to
-that subprogram.
+In the example above, the elaboration of declaration @code{Ptr} is assigned
+@code{Func'Access} before the body of @code{Func} has been elaborated.
+@end table
-@item
-Place the pragma in the package spec that declares the called subprogram,
-without naming any entity. This disables warnings on all elaboration calls to
-all subprograms declared in this spec.
+@geindex -gnatwl (gnat)
-@item
-Use Pragma Elaborate.
-As previously described in section @ref{2c7,,Treatment of Pragma Elaborate},
-GNAT in static mode assumes that a @cite{pragma} Elaborate indicates correctly
-that no elaboration checks are required on calls to the designated unit.
-There may be cases in which the caller knows that no transitive calls
-can occur, so that a @cite{pragma Elaborate} will be sufficient in a
-case where @cite{pragma Elaborate_All} would cause a circularity.
-@end itemize
+@table @asis
-These five cases are listed in order of decreasing safety, and therefore
-require increasing programmer care in their application. Consider the
-following program:
+@item @code{-gnatwl}
-@example
-package Pack1 is
- function F1 return Integer;
- X1 : Integer;
-end Pack1;
+Turn on warnings for elaboration problems
-package Pack2 is
- function F2 return Integer;
- function Pure (x : integer) return integer;
- -- pragma Suppress (Elaboration_Check, On => Pure); -- (3)
- -- pragma Suppress (Elaboration_Check); -- (4)
-end Pack2;
+When this switch is in effect, GNAT emits diagnostics in the form of warnings
+concerning various elaboration problems. The warnings are enabled by default.
+The switch is provided in case all warnings are suppressed, but elaboration
+warnings are still desired.
-with Pack2;
-package body Pack1 is
- function F1 return Integer is
- begin
- return 100;
- end F1;
- Val : integer := Pack2.Pure (11); -- Elab. call (1)
-begin
- declare
- -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1)
- -- pragma Suppress(Elaboration_Check); -- (2)
- begin
- X1 := Pack2.F2 + 1; -- Elab. call (2)
- end;
-end Pack1;
+@item @code{-gnatwL}
-with Pack1;
-package body Pack2 is
- function F2 return Integer is
- begin
- return Pack1.F1;
- end F2;
- function Pure (x : integer) return integer is
- begin
- return x ** 3 - 3 * x;
- end;
-end Pack2;
+Turn off warnings for elaboration problems
-with Pack1, Ada.Text_IO;
-procedure Proc3 is
-begin
- Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101
-end Proc3;
-@end example
-
-In the absence of any pragmas, an attempt to bind this program produces
-the following diagnostics:
-
-@example
-error: elaboration circularity detected
-info: "pack1 (body)" must be elaborated before "pack1 (body)"
-info: reason: Elaborate_All probably needed in unit "pack1 (body)"
-info: recompile "pack1 (body)" with -gnatel for full details
-info: "pack1 (body)"
-info: must be elaborated along with its spec:
-info: "pack1 (spec)"
-info: which is withed by:
-info: "pack2 (body)"
-info: which must be elaborated along with its spec:
-info: "pack2 (spec)"
-info: which is withed by:
-info: "pack1 (body)"
-@end example
-
-The sources of the circularity are the two calls to @cite{Pack2.Pure} and
-@cite{Pack2.F2} in the body of @cite{Pack1}. We can see that the call to
-F2 is safe, even though F2 calls F1, because the call appears after the
-elaboration of the body of F1. Therefore the pragma (1) is safe, and will
-remove the warning on the call. It is also possible to use pragma (2)
-because there are no other potentially unsafe calls in the block.
-
-The call to @cite{Pure} is safe because this function does not depend on the
-state of @cite{Pack2}. Therefore any call to this function is safe, and it
-is correct to place pragma (3) in the corresponding package spec.
-
-Finally, we could place pragma (4) in the spec of @cite{Pack2} to disable
-warnings on all calls to functions declared therein. Note that this is not
-necessarily safe, and requires more detailed examination of the subprogram
-bodies involved. In particular, a call to @cite{F2} requires that @cite{F1}
-be already elaborated.
-@end itemize
+When this switch is in effect, GNAT no longer emits any diagnostics in the
+form of warnings. Selective suppression of elaboration problems is possible
+using @code{pragma Warnings (Off)}.
-It is hard to generalize on which of these four approaches should be
-taken. Obviously if it is possible to fix the program so that the default
-treatment works, this is preferable, but this may not always be practical.
-It is certainly simple enough to use @emph{-gnatE}
-but the danger in this case is that, even if the GNAT binder
-finds a correct elaboration order, it may not always do so,
-and certainly a binder from another Ada compiler might not. A
-combination of testing and analysis (for which the
-information messages generated with the @emph{-gnatel}
-switch can be useful) must be used to ensure that the program is free
-of errors. One switch that is useful in this testing is the
-@emph{-p (pessimistic elaboration order)} switch for @cite{gnatbind}.
-Normally the binder tries to find an order that has the best chance
-of avoiding elaboration problems. However, if this switch is used, the binder
-plays a devil's advocate role, and tries to choose the order that
-has the best chance of failing. If your program works even with this
-switch, then it has a better chance of being error free, but this is still
-not a guarantee.
-
-For an example of this approach in action, consider the C-tests (executable
-tests) from the ACATS suite. If these are compiled and run with the default
-treatment, then all but one of them succeed without generating any error
-diagnostics from the binder. However, there is one test that fails, and
-this is not surprising, because the whole point of this test is to ensure
-that the compiler can handle cases where it is impossible to determine
-a correct order statically, and it checks that an exception is indeed
-raised at run time.
-
-This one test must be compiled and run using the @emph{-gnatE}
-switch, and then it passes. Alternatively, the entire suite can
-be run using this switch. It is never wrong to run with the dynamic
-elaboration switch if your code is correct, and we assume that the
-C-tests are indeed correct (it is less efficient, but efficiency is
-not a factor in running the ACATS tests.)
-
-@node Elaboration for Indirect Calls,Summary of Procedures for Elaboration Control,What to Do If the Default Elaboration Behavior Fails,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id12}@anchor{2ce}@anchor{gnat_ugn/elaboration_order_handling_in_gnat elaboration-for-indirect-calls}@anchor{2cf}
-@section Elaboration for Indirect Calls
-
-
-@geindex Dispatching calls
-
-@geindex Indirect calls
-
-In rare cases, the static elaboration model fails to prevent
-dispatching calls to not-yet-elaborated subprograms. In such cases, we
-fall back to run-time checks; premature calls to any primitive
-operation of a tagged type before the body of the operation has been
-elaborated will raise @cite{Program_Error}.
-
-Access-to-subprogram types, however, are handled conservatively, and
-do not require run-time checks. This was not true in earlier versions
-of the compiler; you can use the @emph{-gnatd.U} debug switch to
-revert to the old behavior if the new conservative behavior causes
-elaboration cycles. Here, 'conservative' means that if you do
-@cite{P'Access} during elaboration, the compiler will assume that you
-might call @cite{P} indirectly during elaboration, so it adds an
-implicit @cite{pragma Elaborate_All} on the library unit containing
-@cite{P}. The @emph{-gnatd.U} switch is safe if you know there are
-no such calls. If the program worked before, it will continue to work
-with @emph{-gnatd.U}. But beware that code modifications such as
-adding an indirect call can cause erroneous behavior in the presence
-of @emph{-gnatd.U}.
-
-@node Summary of Procedures for Elaboration Control,Other Elaboration Order Considerations,Elaboration for Indirect Calls,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id13}@anchor{2d0}@anchor{gnat_ugn/elaboration_order_handling_in_gnat summary-of-procedures-for-elaboration-control}@anchor{2d1}
-@section Summary of Procedures for Elaboration Control
+@example
+ 1. package body Selective_Suppression is
+ 2. function ABE return Integer;
+ 3.
+ 4. Val_1 : constant Integer := ABE;
+ |
+ >>> warning: cannot call "ABE" before body seen
+ >>> warning: Program_Error will be raised at run time
+ 5.
+ 6. pragma Warnings (Off);
+ 7. Val_2 : constant Integer := ABE;
+ 8. pragma Warnings (On);
+ 9.
+10. function ABE return Integer is
+11. begin
+12. ...
+13. end ABE;
+14. end Selective_Suppression;
+@end example
-@geindex Elaboration control
+Note that suppressing elaboration warnings does not eliminate run-time
+checks. The example above will still fail at run time with an ABE.
+@end table
-First, compile your program with the default options, using none of
-the special elaboration control switches. If the binder successfully
-binds your program, then you can be confident that, apart from issues
-raised by the use of access-to-subprogram types and dynamic dispatching,
-the program is free of elaboration errors. If it is important that the
-program be portable to other compilers than GNAT, then use the
-@emph{-gnatel}
-switch to generate messages about missing @cite{Elaborate} or
-@cite{Elaborate_All} pragmas, and supply the missing pragmas.
-
-If the program fails to bind using the default static elaboration
-handling, then you can fix the program to eliminate the binder
-message, or recompile the entire program with the
-@emph{-gnatE} switch to generate dynamic elaboration checks,
-and, if you are sure there really are no elaboration problems,
-use a global pragma @cite{Suppress (Elaboration_Check)}.
-
-@node Other Elaboration Order Considerations,Determining the Chosen Elaboration Order,Summary of Procedures for Elaboration Control,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat id14}@anchor{2d2}@anchor{gnat_ugn/elaboration_order_handling_in_gnat other-elaboration-order-considerations}@anchor{2d3}
-@section Other Elaboration Order Considerations
-
-
-This section has been entirely concerned with the issue of finding a valid
-elaboration order, as defined by the Ada Reference Manual. In a case
-where several elaboration orders are valid, the task is to find one
-of the possible valid elaboration orders (and the static model in GNAT
-will ensure that this is achieved).
-
-The purpose of the elaboration rules in the Ada Reference Manual is to
-make sure that no entity is accessed before it has been elaborated. For
-a subprogram, this means that the spec and body must have been elaborated
-before the subprogram is called. For an object, this means that the object
-must have been elaborated before its value is read or written. A violation
-of either of these two requirements is an access before elaboration order,
-and this section has been all about avoiding such errors.
-
-In the case where more than one order of elaboration is possible, in the
-sense that access before elaboration errors are avoided, then any one of
-the orders is 'correct' in the sense that it meets the requirements of
-the Ada Reference Manual, and no such error occurs.
-
-However, it may be the case for a given program, that there are
-constraints on the order of elaboration that come not from consideration
-of avoiding elaboration errors, but rather from extra-lingual logic
-requirements. Consider this example:
-
-@example
-with Init_Constants;
-package Constants is
- X : Integer := 0;
- Y : Integer := 0;
-end Constants;
-
-package Init_Constants is
- procedure P; --* require a body*
-end Init_Constants;
-
-with Constants;
-package body Init_Constants is
- procedure P is begin null; end;
-begin
- Constants.X := 3;
- Constants.Y := 4;
-end Init_Constants;
+@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 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
-with Constants;
-package Calc is
- Z : Integer := Constants.X + Constants.Y;
-end Calc;
-with Calc;
-with Text_IO; use Text_IO;
-procedure Main is
-begin
- Put_Line (Calc.Z'Img);
-end Main;
-@end example
+A programmer should first compile the program with the default options, using
+none of the binder or compiler switches. If the binder succeeds in finding an
+elaboration order, then apart from possible cases involing dispatching calls
+and access-to-subprogram types, the program is free of elaboration errors.
-In this example, there is more than one valid order of elaboration. For
-example both the following are correct orders:
+If it is important for the program to be portable to compilers other than GNAT,
+then the programmer should use compiler switch @code{-gnatel} and consider
+the messages about missing or implicitly created @code{Elaborate} and
+@code{Elaborate_All} pragmas.
-@example
-Init_Constants spec
-Constants spec
-Calc spec
-Init_Constants body
-Main body
-@end example
+If the binder reports an elaboration circularity, the programmer has several
+options:
-and
-@example
-Init_Constants spec
-Init_Constants body
-Constants spec
-Calc spec
-Main body
-@end example
+@itemize *
-There is no language rule to prefer one or the other, both are correct
-from an order of elaboration point of view. But the programmatic effects
-of the two orders are very different. In the first, the elaboration routine
-of @cite{Calc} initializes @cite{Z} to zero, and then the main program
-runs with this value of zero. But in the second order, the elaboration
-routine of @cite{Calc} runs after the body of Init_Constants has set
-@cite{X} and @cite{Y} and thus @cite{Z} is set to 7 before @cite{Main} runs.
+@item
+Ensure that elaboration warnings are enabled. This will allow the static
+model to output trace information of elaboration issues. The trace
+information could shed light on previously unforeseen dependencies, as well
+as their origins. Elaboration warnings are enabled with compiler switch
+@code{-gnatwl}.
-One could perhaps by applying pretty clever non-artificial intelligence
-to the situation guess that it is more likely that the second order of
-elaboration is the one desired, but there is no formal linguistic reason
-to prefer one over the other. In fact in this particular case, GNAT will
-prefer the second order, because of the rule that bodies are elaborated
-as soon as possible, but it's just luck that this is what was wanted
-(if indeed the second order was preferred).
+@item
+Cosider the tactics given in the suggestions section of the circularity
+diagnostic.
-If the program cares about the order of elaboration routines in a case like
-this, it is important to specify the order required. In this particular
-case, that could have been achieved by adding to the spec of Calc:
+@item
+If none of the steps outlined above resolve the circularity, use a more
+permissive elaboration model, in the following order:
-@example
-pragma Elaborate_All (Constants);
-@end example
-which requires that the body (if any) and spec of @cite{Constants},
-as well as the body and spec of any unit @emph{with}ed by
-@cite{Constants} be elaborated before @cite{Calc} is elaborated.
+@itemize -
-Clearly no automatic method can always guess which alternative you require,
-and if you are working with legacy code that had constraints of this kind
-which were not properly specified by adding @cite{Elaborate} or
-@cite{Elaborate_All} pragmas, then indeed it is possible that two different
-compilers can choose different orders.
+@item
+Use the pre-20.x legacy elaboration-order model, with binder switch
+@code{-H}.
-However, GNAT does attempt to diagnose the common situation where there
-are uninitialized variables in the visible part of a package spec, and the
-corresponding package body has an elaboration block that directly or
-indirectly initialized one or more of these variables. This is the situation
-in which a pragma Elaborate_Body is usually desirable, and GNAT will generate
-a warning that suggests this addition if it detects this situation.
+@item
+Use both pre-18.x and pre-20.x legacy elaboration models, with compiler
+switch @code{-gnatH} and binder switch @code{-H}.
-The @cite{gnatbind} @emph{-p} switch may be useful in smoking
-out problems. This switch causes bodies to be elaborated as late as possible
-instead of as early as possible. In the example above, it would have forced
-the choice of the first elaboration order. If you get different results
-when using this switch, and particularly if one set of results is right,
-and one is wrong as far as you are concerned, it shows that you have some
-missing @cite{Elaborate} pragmas. For the example above, we have the
-following output:
+@item
+Use the relaxed static elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} and binder switch @code{-H}.
-@example
-$ gnatmake -f -q main
-$ main
- 7
-$ gnatmake -f -q main -bargs -p
-$ main
- 0
-@end example
+@item
+Use the relaxed dynamic elaboration model, with compiler switches
+@code{-gnatH} @code{-gnatJ} @code{-gnatE} and binder switch
+@code{-H}.
+@end itemize
+@end itemize
-It is of course quite unlikely that both these results are correct, so
-it is up to you in a case like this to investigate the source of the
-difference, by looking at the two elaboration orders that are chosen,
-and figuring out which is correct, and then adding the necessary
-@cite{Elaborate} or @cite{Elaborate_All} pragmas to ensure the desired order.
+@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 id14}@anchor{22e}@anchor{gnat_ugn/elaboration_order_handling_in_gnat inspecting-the-chosen-elaboration-order}@anchor{22f}
+@section Inspecting the Chosen Elaboration Order
-@node Determining the Chosen Elaboration Order,,Other Elaboration Order Considerations,Elaboration Order Handling in GNAT
-@anchor{gnat_ugn/elaboration_order_handling_in_gnat determining-the-chosen-elaboration-order}@anchor{2d4}@anchor{gnat_ugn/elaboration_order_handling_in_gnat id15}@anchor{2d5}
-@section Determining the Chosen Elaboration Order
+To see the elaboration order chosen by the binder, inspect the contents of file
+@cite{b~xxx.adb}. On certain targets, this file appears as @cite{b_xxx.adb}. The
+elaboration order appears as a sequence of calls to @code{Elab_Body} and
+@code{Elab_Spec}, interspersed with assignments to @cite{Exxx} which indicates that a
+particular unit is elaborated. For example:
-To see the elaboration order that the binder chooses, you can look at
-the last part of the file:@cite{b~xxx.adb} binder output file. Here is an example:
+@quotation
@example
System.Soft_Links'Elab_Body;
Ada.Text_Io'Elab_Body;
E07 := True;
@end example
+@end quotation
-Here Elab_Spec elaborates the spec
-and Elab_Body elaborates the body. The assignments to the @code{E@emph{xx}} flags
-flag that the corresponding body is now elaborated.
+Note also binder switch @code{-l}, which outputs the chosen elaboration
+order and provides a more readable form of the above:
-You can also ask the binder to generate a more
-readable list of the elaboration order using the
-@cite{-l} switch when invoking the binder. Here is
-an example of the output generated by this switch:
+@quotation
@example
ada (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{12}@anchor{gnat_ugn/inline_assembler doc}@anchor{2d6}@anchor{gnat_ugn/inline_assembler id1}@anchor{2d7}
+@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
supported by GNAT. However, for small sections of code it may be simpler
or more efficient to include assembly language statements directly
in your Ada source program, using the facilities of the implementation-defined
-package @cite{System.Machine_Code}, which incorporates the gcc
+package @code{System.Machine_Code}, which incorporates the gcc
Inline Assembler. The Inline Assembler approach offers a number of advantages,
including the following:
@end menu
@node Basic Assembler Syntax,A Simple Example of Inline Assembler,,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id2}@anchor{2d8}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{2d9}
+@anchor{gnat_ugn/inline_assembler id2}@anchor{232}@anchor{gnat_ugn/inline_assembler basic-assembler-syntax}@anchor{233}
@section Basic Assembler Syntax
The assembler used by GNAT and gcc is based not on the Intel assembly
language, but rather on a language that descends from the AT&T Unix
-assembler @emph{as} (and which is often referred to as 'AT&T syntax').
-The following table summarizes the main features of @emph{as} syntax
+assembler @code{as} (and which is often referred to as 'AT&T syntax').
+The following table summarizes the main features of @code{as} syntax
and points out the differences from the Intel conventions.
-See the gcc @emph{as} and @emph{gas} (an @emph{as} macro
+See the gcc @code{as} and @code{gas} (an @code{as} macro
pre-processor) documentation for further information.
@display
@emph{Register names}@w{ }
@display
-gcc / @emph{as}: Prefix with '%'; for example @cite{%eax}@w{ }
-Intel: No extra punctuation; for example @cite{eax}@w{ }
+gcc / @code{as}: Prefix with '%'; for example @code{%eax}@w{ }
+Intel: No extra punctuation; for example @code{eax}@w{ }
@end display
@end display
@display
@emph{Immediate operand}@w{ }
@display
-gcc / @emph{as}: Prefix with '$'; for example @cite{$4}@w{ }
-Intel: No extra punctuation; for example @cite{4}@w{ }
+gcc / @code{as}: Prefix with '$'; for example @code{$4}@w{ }
+Intel: No extra punctuation; for example @code{4}@w{ }
@end display
@end display
@display
@emph{Address}@w{ }
@display
-gcc / @emph{as}: Prefix with '$'; for example @cite{$loc}@w{ }
-Intel: No extra punctuation; for example @cite{loc}@w{ }
+gcc / @code{as}: Prefix with '$'; for example @code{$loc}@w{ }
+Intel: No extra punctuation; for example @code{loc}@w{ }
@end display
@end display
@display
@emph{Memory contents}@w{ }
@display
-gcc / @emph{as}: No extra punctuation; for example @cite{loc}@w{ }
-Intel: Square brackets; for example @cite{[loc]}@w{ }
+gcc / @code{as}: No extra punctuation; for example @code{loc}@w{ }
+Intel: Square brackets; for example @code{[loc]}@w{ }
@end display
@end display
@display
@emph{Register contents}@w{ }
@display
-gcc / @emph{as}: Parentheses; for example @cite{(%eax)}@w{ }
-Intel: Square brackets; for example @cite{[eax]}@w{ }
+gcc / @code{as}: Parentheses; for example @code{(%eax)}@w{ }
+Intel: Square brackets; for example @code{[eax]}@w{ }
@end display
@end display
@display
@emph{Hexadecimal numbers}@w{ }
@display
-gcc / @emph{as}: Leading '0x' (C language syntax); for example @cite{0xA0}@w{ }
-Intel: Trailing 'h'; for example @cite{A0h}@w{ }
+gcc / @code{as}: Leading '0x' (C language syntax); for example @code{0xA0}@w{ }
+Intel: Trailing 'h'; for example @code{A0h}@w{ }
@end display
@end display
@display
@emph{Operand size}@w{ }
@display
-gcc / @emph{as}: Explicit in op code; for example @cite{movw} to move a 16-bit word@w{ }
-Intel: Implicit, deduced by assembler; for example @cite{mov}@w{ }
+gcc / @code{as}: Explicit in op code; for example @code{movw} to move a 16-bit word@w{ }
+Intel: Implicit, deduced by assembler; for example @code{mov}@w{ }
@end display
@end display
@display
@emph{Instruction repetition}@w{ }
@display
-gcc / @emph{as}: Split into two lines; for example@w{ }
+gcc / @code{as}: Split into two lines; for example@w{ }
@display
-@cite{rep}@w{ }
-@cite{stosl}@w{ }
+@code{rep}@w{ }
+@code{stosl}@w{ }
@end display
-Intel: Keep on one line; for example @cite{rep stosl}@w{ }
+Intel: Keep on one line; for example @code{rep stosl}@w{ }
@end display
@end display
@display
@emph{Order of operands}@w{ }
@display
-gcc / @emph{as}: Source first; for example @cite{movw $4@comma{} %eax}@w{ }
-Intel: Destination first; for example @cite{mov eax@comma{} 4}@w{ }
+gcc / @code{as}: Source first; for example @code{movw $4, %eax}@w{ }
+Intel: Destination first; for example @code{mov eax, 4}@w{ }
@end display
@end display
@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{2da}@anchor{gnat_ugn/inline_assembler id3}@anchor{2db}
+@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
The following example will generate a single assembly language statement,
-@cite{nop}, which does nothing. Despite its lack of run-time effect,
+@code{nop}, which does nothing. Despite its lack of run-time effect,
the example will be useful in illustrating the basics of
the Inline Assembler facility.
@end example
@end quotation
-@cite{Asm} is a procedure declared in package @cite{System.Machine_Code};
+@code{Asm} is a procedure declared in package @code{System.Machine_Code};
here it takes one parameter, a @emph{template string} that must be a static
expression and that will form the generated instruction.
-@cite{Asm} may be regarded as a compile-time procedure that parses
+@code{Asm} may be regarded as a compile-time procedure that parses
the template string and additional parameters (none here),
from which it generates a sequence of assembly language instructions.
The examples in this chapter will illustrate several of the forms
-for invoking @cite{Asm}; a complete specification of the syntax
-is found in the @cite{Machine_Code_Insertions} section of the
+for invoking @code{Asm}; a complete specification of the syntax
+is found in the @code{Machine_Code_Insertions} section of the
@cite{GNAT Reference Manual}.
-Under the standard GNAT conventions, the @cite{Nothing} procedure
+Under the standard GNAT conventions, the @code{Nothing} procedure
should be in a file named @code{nothing.adb}.
You can build the executable in the usual way:
@end itemize
This gives a human-readable assembler version of the code. The resulting
-file will have the same name as the Ada source file, but with a @cite{.s}
+file will have the same name as the Ada source file, but with a @code{.s}
extension. In our example, the file @code{nothing.s} has the following
contents:
@end quotation
The assembly code you included is clearly indicated by
-the compiler, between the @cite{#APP} and @cite{#NO_APP}
+the compiler, between the @code{#APP} and @code{#NO_APP}
delimiters. The character before the 'APP' and 'NOAPP'
can differ on different targets. For example, GNU/Linux uses '#APP' while
on NT you will see '/APP'.
will report this error in a temporary file, which will be deleted when
the compilation is finished. Generating an assembler file will help
in such cases, since you can assemble this file separately using the
-@emph{as} assembler that comes with gcc.
+@code{as} assembler that comes with gcc.
Assembling the file using the command
will give you error messages whose lines correspond to the assembler
input file, so you can easily find and correct any mistakes you made.
-If there are no errors, @emph{as} will generate an object file
+If there are no errors, @code{as} will generate an object file
@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{2dc}@anchor{gnat_ugn/inline_assembler output-variables-in-inline-assembler}@anchor{2dd}
+@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
When writing Inline Assembler instructions, you need to precede each register
and variable name with a percent sign. Since the assembler already requires
a percent sign at the beginning of a register name, you need two consecutive
-percent signs for such names in the Asm template string, thus @cite{%%eax}.
+percent signs for such names in the Asm template string, thus @code{%%eax}.
In the generated assembly code, one of the percent signs will be stripped off.
-Names such as @cite{%0}, @cite{%1}, @cite{%2}, etc., denote input or output
-variables: operands you later define using @cite{Input} or @cite{Output}
-parameters to @cite{Asm}.
+Names such as @code{%0}, @code{%1}, @code{%2}, etc., denote input or output
+variables: operands you later define using @code{Input} or @code{Output}
+parameters to @code{Asm}.
An output variable is illustrated in
the third statement in the Asm template string:
@end quotation
The intent is to store the contents of the eax register in a variable that can
-be accessed in Ada. Simply writing @cite{movl %%eax@comma{} Flags} would not
+be accessed in Ada. Simply writing @code{movl %%eax, Flags} would not
necessarily work, since the compiler might optimize by using a register
-to hold Flags, and the expansion of the @cite{movl} instruction would not be
+to hold Flags, and the expansion of the @code{movl} instruction would not be
aware of this optimization. The solution is not to store the result directly
but rather to advise the compiler to choose the correct operand form;
-that is the purpose of the @cite{%0} output variable.
+that is the purpose of the @code{%0} output variable.
-Information about the output variable is supplied in the @cite{Outputs}
-parameter to @cite{Asm}:
+Information about the output variable is supplied in the @code{Outputs}
+parameter to @code{Asm}:
@quotation
@end example
@end quotation
-The output is defined by the @cite{Asm_Output} attribute of the target type;
+The output is defined by the @code{Asm_Output} attribute of the target type;
the general format is
@quotation
@end example
@end quotation
-the @cite{"m"} (memory) constraint tells the compiler that the variable
-@cite{Flags} should be stored in a memory variable, thus preventing
+the @code{"m"} (memory) constraint tells the compiler that the variable
+@code{Flags} should be stored in a memory variable, thus preventing
the optimizer from keeping it in a register. In contrast,
@quotation
@end example
@end quotation
-uses the @cite{"r"} (register) constraint, telling the compiler to
+uses the @code{"r"} (register) constraint, telling the compiler to
store the variable in a register.
If the constraint is preceded by the equal character '=', it tells
the compiler that the variable will be used to store data into it.
-In the @cite{Get_Flags} example, we used the @cite{"g"} (global) constraint,
+In the @code{Get_Flags} example, we used the @code{"g"} (global) constraint,
allowing the optimizer to choose whatever it deems best.
There are a fairly large number of constraints, but the ones that are
@end quotation
-The full set of constraints is described in the gcc and @emph{as}
+The full set of constraints is described in the gcc and @code{as}
documentation; note that it is possible to combine certain constraints
in one constraint string.
@end example
@end quotation
-@cite{%0} will be replaced in the expanded code by the appropriate operand,
+@code{%0} will be replaced in the expanded code by the appropriate operand,
whatever
-the compiler decided for the @cite{Flags} variable.
+the compiler decided for the @code{Flags} variable.
In general, you may have any number of output variables:
@itemize *
@item
-Count the operands starting at 0; thus @cite{%0}, @cite{%1}, etc.
+Count the operands starting at 0; thus @code{%0}, @code{%1}, etc.
@item
-Specify the @cite{Outputs} parameter as a parenthesized comma-separated list
-of @cite{Asm_Output} attributes
+Specify the @code{Outputs} parameter as a parenthesized comma-separated list
+of @code{Asm_Output} attributes
@end itemize
For example:
@end example
@end quotation
-where @cite{Var_A}, @cite{Var_B}, and @cite{Var_C} are variables
+where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables
in the Ada program.
-As a variation on the @cite{Get_Flags} example, we can use the constraints
-string to direct the compiler to store the eax register into the @cite{Flags}
+As a variation on the @code{Get_Flags} example, we can use the constraints
+string to direct the compiler to store the eax register into the @code{Flags}
variable, instead of including the store instruction explicitly in the
-@cite{Asm} template string:
+@code{Asm} template string:
@quotation
@end example
@end quotation
-The @cite{"a"} constraint tells the compiler that the @cite{Flags}
+The @code{"a"} constraint tells the compiler that the @code{Flags}
variable will come from the eax register. Here is the resulting code:
@quotation
@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{2de}@anchor{gnat_ugn/inline_assembler input-variables-in-inline-assembler}@anchor{2df}
+@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 example
@end quotation
-The @cite{Outputs} parameter to @cite{Asm} specifies
+The @code{Outputs} parameter to @code{Asm} specifies
that the result will be in the eax register and that it is to be stored
-in the @cite{Result} variable.
+in the @code{Result} variable.
-The @cite{Inputs} parameter looks much like the @cite{Outputs} parameter,
-but with an @cite{Asm_Input} attribute.
-The @cite{"="} constraint, indicating an output value, is not present.
+The @code{Inputs} parameter looks much like the @code{Outputs} parameter,
+but with an @code{Asm_Input} attribute.
+The @code{"="} constraint, indicating an output value, is not present.
You can have multiple input variables, in the same way that you can have more
than one output variable.
The parameter count (%0, %1) etc, still starts at the first output statement,
and continues with the input statements.
-Just as the @cite{Outputs} parameter causes the register to be stored into the
+Just as the @code{Outputs} parameter causes the register to be stored into the
target variable after execution of the assembler statements, so does the
-@cite{Inputs} parameter cause its variable to be loaded into the register
+@code{Inputs} parameter cause its variable to be loaded into the register
before execution of the assembler statements.
-Thus the effect of the @cite{Asm} invocation is:
+Thus the effect of the @code{Asm} invocation is:
@itemize *
@item
-load the 32-bit value of @cite{Value} into eax
+load the 32-bit value of @code{Value} into eax
@item
-execute the @cite{incl %eax} instruction
+execute the @code{incl %eax} instruction
@item
-store the contents of eax into the @cite{Result} variable
+store the contents of eax into the @code{Result} variable
@end itemize
-The resulting assembler file (with @emph{-O2} optimization) contains:
+The resulting assembler file (with @code{-O2} optimization) contains:
@quotation
@end quotation
@node Inlining Inline Assembler Code,Other Asm Functionality,Input Variables in Inline Assembler,Inline Assembler
-@anchor{gnat_ugn/inline_assembler id6}@anchor{2e0}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{2e1}
+@anchor{gnat_ugn/inline_assembler id6}@anchor{23a}@anchor{gnat_ugn/inline_assembler inlining-inline-assembler-code}@anchor{23b}
@section Inlining Inline Assembler Code
-For a short subprogram such as the @cite{Incr} function in the previous
+For a short subprogram such as the @code{Incr} function in the previous
section, the overhead of the call and return (creating / deleting the stack
frame) can be significant, compared to the amount of code in the subprogram
-body. A solution is to apply Ada's @cite{Inline} pragma to the subprogram,
+body. A solution is to apply Ada's @code{Inline} pragma to the subprogram,
which directs the compiler to expand invocations of the subprogram at the
point(s) of call, instead of setting up a stack frame for out-of-line calls.
Here is the resulting program:
@end example
@end quotation
-Compile the program with both optimization (@emph{-O2}) and inlining
-(@emph{-gnatn}) enabled.
+Compile the program with both optimization (@code{-O2}) and inlining
+(@code{-gnatn}) enabled.
-The @cite{Incr} function is still compiled as usual, but at the
-point in @cite{Increment} where our function used to be called:
+The @code{Incr} function is still compiled as usual, but at the
+point in @code{Increment} where our function used to be called:
@quotation
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{2e2}@anchor{gnat_ugn/inline_assembler id7}@anchor{2e3}
-@section Other @cite{Asm} Functionality
+@anchor{gnat_ugn/inline_assembler other-asm-functionality}@anchor{23c}@anchor{gnat_ugn/inline_assembler id7}@anchor{23d}
+@section Other @code{Asm} Functionality
-This section describes two important parameters to the @cite{Asm}
-procedure: @cite{Clobber}, which identifies register usage;
-and @cite{Volatile}, which inhibits unwanted optimizations.
+This section describes two important parameters to the @code{Asm}
+procedure: @code{Clobber}, which identifies register usage;
+and @code{Volatile}, which inhibits unwanted optimizations.
@menu
* The Clobber Parameter::
@end menu
@node The Clobber Parameter,The Volatile Parameter,,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{2e4}@anchor{gnat_ugn/inline_assembler id8}@anchor{2e5}
-@subsection The @cite{Clobber} Parameter
+@anchor{gnat_ugn/inline_assembler the-clobber-parameter}@anchor{23e}@anchor{gnat_ugn/inline_assembler id8}@anchor{23f}
+@subsection The @code{Clobber} Parameter
One of the dangers of intermixing assembly language and a compiled language
such as Ada is that the compiler needs to be aware of which registers are
being used by the assembly code. In some cases, such as the earlier examples,
the constraint string is sufficient to indicate register usage (e.g.,
-@cite{"a"} for
+@code{"a"} for
the eax register). But more generally, the compiler needs an explicit
identification of the registers that are used by the Inline Assembly
statements.
Using a register that the compiler doesn't know about
-could be a side effect of an instruction (like @cite{mull}
+could be a side effect of an instruction (like @code{mull}
storing its result in both eax and edx).
It can also arise from explicit register usage in your
assembly code; for example:
@end example
@end quotation
-where the compiler (since it does not analyze the @cite{Asm} template string)
+where the compiler (since it does not analyze the @code{Asm} template string)
does not know you are using the ebx register.
-In such cases you need to supply the @cite{Clobber} parameter to @cite{Asm},
+In such cases you need to supply the @code{Clobber} parameter to @code{Asm},
to identify the registers that will be used by your assembly code:
@quotation
The Clobber parameter is a static string expression specifying the
register(s) you are using. Note that register names are @emph{not} prefixed
by a percent sign. Also, if more than one register is used then their names
-are separated by commas; e.g., @cite{"eax@comma{} ebx"}
+are separated by commas; e.g., @code{"eax, ebx"}
-The @cite{Clobber} parameter has several additional uses:
+The @code{Clobber} parameter has several additional uses:
@itemize *
@item
-Use 'register' name @cite{cc} to indicate that flags might have changed
+Use 'register' name @code{cc} to indicate that flags might have changed
@item
-Use 'register' name @cite{memory} if you changed a memory location
+Use 'register' name @code{memory} if you changed a memory location
@end itemize
@node The Volatile Parameter,,The Clobber Parameter,Other Asm Functionality
-@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{2e6}@anchor{gnat_ugn/inline_assembler id9}@anchor{2e7}
-@subsection The @cite{Volatile} Parameter
+@anchor{gnat_ugn/inline_assembler the-volatile-parameter}@anchor{240}@anchor{gnat_ugn/inline_assembler id9}@anchor{241}
+@subsection The @code{Volatile} Parameter
@geindex Volatile parameter
Compiler optimizations in the presence of Inline Assembler may sometimes have
-unwanted effects. For example, when an @cite{Asm} invocation with an input
+unwanted effects. For example, when an @code{Asm} invocation with an input
variable is inside a loop, the compiler might move the loading of the input
variable outside the loop, regarding it as a one-time initialization.
If this effect is not desired, you can disable such optimizations by setting
-the @cite{Volatile} parameter to @cite{True}; for example:
+the @code{Volatile} parameter to @code{True}; for example:
@quotation
@end example
@end quotation
-By default, @cite{Volatile} is set to @cite{False} unless there is no
-@cite{Outputs} parameter.
+By default, @code{Volatile} is set to @code{False} unless there is no
+@code{Outputs} parameter.
-Although setting @cite{Volatile} to @cite{True} prevents unwanted
+Although setting @code{Volatile} to @code{True} prevents unwanted
optimizations, it will also disable other optimizations that might be
-important for efficiency. In general, you should set @cite{Volatile}
-to @cite{True} only if the compiler's optimizations have created
+important for efficiency. In general, you should set @code{Volatile}
+to @code{True} only if the compiler's optimizations have created
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{2e8}@anchor{share/gnu_free_documentation_license gnu-free-documentation-license}@anchor{2e9}
+@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{gnat_ugn/gnat_utility_programs switches-related-to-project-files}@w{ }
+@anchor{cf}@w{ }
@c %**end of body
@bye
projects / gcc.git / blobdiff