From 554fd8c5195424bdbcabf5de30fdc183aba391bd Mon Sep 17 00:00:00 2001 From: upstream source tree Date: Sun, 15 Mar 2015 20:14:05 -0400 Subject: obtained gcc-4.6.4.tar.bz2 from upstream website; verified gcc-4.6.4.tar.bz2.sig; imported gcc-4.6.4 source tree from verified upstream tarball. downloading a git-generated archive based on the 'upstream' tag should provide you with a source tree that is binary identical to the one extracted from the above tarball. if you have obtained the source via the command 'git clone', however, do note that line-endings of files in your working directory might differ from line-endings of the respective files in the upstream repository. --- gcc/ada/gnat_ugn.texi | 28265 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 28265 insertions(+) create mode 100644 gcc/ada/gnat_ugn.texi (limited to 'gcc/ada/gnat_ugn.texi') diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi new file mode 100644 index 000000000..d843106df --- /dev/null +++ b/gcc/ada/gnat_ugn.texi @@ -0,0 +1,28265 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header + +@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo +@c o +@c GNAT DOCUMENTATION o +@c o +@c G N A T _ U G N o +@c o +@c Copyright (C) 1992-2010, AdaCore o +@c o +@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo + +@setfilename gnat_ugn.info + +@copying +Copyright @copyright{} 1995-2009 Free Software Foundation, +Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts and with no Back-Cover +Texts. A copy of the license is included in the section entitled +``GNU Free Documentation License''. +@end copying + +@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo +@c +@c GNAT_UGN Style Guide +@c +@c 1. Always put a @noindent on the line before the first paragraph +@c after any of these commands: +@c +@c @chapter +@c @section +@c @subsection +@c @subsubsection +@c @subsubsubsection +@c +@c @end smallexample +@c @end itemize +@c @end enumerate +@c +@c 2. DO NOT use @example. Use @smallexample instead. +@c a) DO NOT use highlighting commands (@b{}, @i{}) inside an @smallexample +@c context. These can interfere with the readability of the texi +@c source file. Instead, use one of the following annotated +@c @smallexample commands, and preprocess the texi file with the +@c ada2texi tool (which generates appropriate highlighting): +@c @smallexample @c ada +@c @smallexample @c adanocomment +@c @smallexample @c projectfile +@c b) The "@c ada" markup will result in boldface for reserved words +@c and italics for comments +@c c) The "@c adanocomment" markup will result only in boldface for +@c reserved words (comments are left alone) +@c d) The "@c projectfile" markup is like "@c ada" except that the set +@c of reserved words include the new reserved words for project files +@c +@c 3. Each @chapter, @section, @subsection, @subsubsection, etc. +@c command must be preceded by two empty lines +@c +@c 4. The @item command should be on a line of its own if it is in an +@c @itemize or @enumerate command. +@c +@c 5. When talking about ALI files use "ALI" (all uppercase), not "Ali" +@c or "ali". +@c +@c 6. DO NOT put trailing spaces at the end of a line. Such spaces will +@c cause the document build to fail. +@c +@c 7. DO NOT use @cartouche for examples that are longer than around 10 lines. +@c This command inhibits page breaks, so long examples in a @cartouche can +@c lead to large, ugly patches of empty space on a page. +@c +@c NOTE: This file should be submitted to xgnatugn with either the vms flag +@c or the unw flag set. The unw flag covers topics for both Unix and +@c Windows. +@c +@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo + +@set NOW January 2007 +@c This flag is used where the text refers to conditions that exist when the +@c text was entered into the document but which may change over time. +@c Update the setting for the flag, and (if necessary) the text surrounding, +@c the references to the flag, on future doc revisions: +@c search for @value{NOW}. + +@set FSFEDITION +@set EDITION GNAT +@set DEFAULTLANGUAGEVERSION Ada 2005 +@set NONDEFAULTLANGUAGEVERSION Ada 95 + +@ifset unw +@set PLATFORM +@end ifset + +@ifset vms +@set PLATFORM OpenVMS +@end ifset + +@c @ovar(ARG) +@c ---------- +@c The ARG is an optional argument. To be used for macro arguments in +@c their documentation (@defmac). +@macro ovar{varname} +@r{[}@var{\varname\}@r{]}@c +@end macro +@c Status as of November 2009: +@c Unfortunately texi2pdf and texi2html treat the trailing "@c" +@c differently, and faulty output is produced by one or the other +@c depending on whether the "@c" is present or absent. +@c As a result, the @ovar macro is not used, and all invocations +@c of the @ovar macro have been expanded inline. + + +@settitle @value{EDITION} User's Guide @value{PLATFORM} +@dircategory GNU Ada tools +@direntry +* @value{EDITION} User's Guide: (gnat_ugn). @value{PLATFORM} +@end direntry + +@include gcc-common.texi + +@setchapternewpage odd +@syncodeindex fn cp +@c %**end of header + +@titlepage +@title @value{EDITION} User's Guide +@ifset vms +@sp 1 +@flushright +@titlefont{@i{@value{PLATFORM}}} +@end flushright +@end ifset + +@sp 2 + +@subtitle GNAT, The GNU Ada Compiler +@versionsubtitle +@author AdaCore + +@page +@vskip 0pt plus 1filll + +@insertcopying + +@end titlepage + +@ifnottex +@node Top, About This Guide, (dir), (dir) +@top @value{EDITION} User's Guide + +@noindent +@value{EDITION} User's Guide @value{PLATFORM} + +@noindent +GNAT, The GNU Ada Compiler@* +GCC version @value{version-GCC}@* + +@noindent +AdaCore@* + +@menu +* About This Guide:: +* Getting Started with GNAT:: +* The GNAT Compilation Model:: +* Compiling Using gcc:: +* Binding Using gnatbind:: +* Linking Using gnatlink:: +* The GNAT Make Program gnatmake:: +* Improving Performance:: +* Renaming Files Using gnatchop:: +* Configuration Pragmas:: +* Handling Arbitrary File Naming Conventions Using gnatname:: +* GNAT Project Manager:: +* Tools Supporting Project Files:: +* The Cross-Referencing Tools gnatxref and gnatfind:: +* The GNAT Pretty-Printer gnatpp:: +* The GNAT Metric Tool gnatmetric:: +* File Name Krunching Using gnatkr:: +* Preprocessing Using gnatprep:: +* The GNAT Library Browser gnatls:: +* Cleaning Up Using gnatclean:: +@ifclear vms +* GNAT and Libraries:: +* Using the GNU make Utility:: +@end ifclear +* Memory Management Issues:: +* Stack Related Facilities:: +* Verifying Properties Using gnatcheck:: +* Creating Sample Bodies Using gnatstub:: +* Generating Ada Bindings for C and C++ headers:: +* Other Utility Programs:: +* Running and Debugging Ada Programs:: +@ifclear vms +* Code Coverage and Profiling:: +@end ifclear +@ifset vms +* Compatibility with HP Ada:: +@end ifset +* Platform-Specific Information for the Run-Time Libraries:: +* Example of Binder Output File:: +* Elaboration Order Handling in GNAT:: +* Conditional Compilation:: +* Inline Assembler:: +* Compatibility and Porting Guide:: +@ifset unw +* Microsoft Windows Topics:: +@end ifset +* GNU Free Documentation License:: +* Index:: + + --- The Detailed Node Listing --- + +About This Guide + +* What This Guide Contains:: +* What You Should Know before Reading This Guide:: +* Related Information:: +* Conventions:: + +Getting Started with GNAT + +* Running GNAT:: +* Running a Simple Ada Program:: +* Running a Program with Multiple Units:: +* Using the gnatmake Utility:: +@ifset vms +* Editing with Emacs:: +@end ifset +@ifclear vms +* Introduction to GPS:: +@end ifclear + +The GNAT Compilation Model + +* Source Representation:: +* Foreign Language Representation:: +* File Naming Rules:: +* Using Other File Names:: +* Alternative File Naming Schemes:: +* Generating Object Files:: +* Source Dependencies:: +* The Ada Library Information Files:: +* Binding an Ada Program:: +* Mixed Language Programming:: +@ifclear vms +* Building Mixed Ada & C++ Programs:: +* Comparison between GNAT and C/C++ Compilation Models:: +@end ifclear +* Comparison between GNAT and Conventional Ada Library Models:: +@ifset vms +* Placement of temporary files:: +@end ifset + +Foreign Language Representation + +* Latin-1:: +* Other 8-Bit Codes:: +* Wide Character Encodings:: + +Compiling Ada Programs With gcc + +* Compiling Programs:: +* Switches for gcc:: +* Search Paths and the Run-Time Library (RTL):: +* Order of Compilation Issues:: +* Examples:: + +Switches for gcc + +* Output and Error Message Control:: +* Warning Message Control:: +* Debugging and Assertion Control:: +* Validity Checking:: +* Style Checking:: +* Run-Time Checks:: +* Using gcc for Syntax Checking:: +* Using gcc for Semantic Checking:: +* Compiling Different Versions of Ada:: +* Character Set Control:: +* File Naming Control:: +* Subprogram Inlining Control:: +* Auxiliary Output Control:: +* Debugging Control:: +* Exception Handling Control:: +* Units to Sources Mapping Files:: +* Integrated Preprocessing:: +@ifset vms +* Return Codes:: +@end ifset + +Binding Ada Programs With gnatbind + +* Running gnatbind:: +* Switches for gnatbind:: +* Command-Line Access:: +* Search Paths for gnatbind:: +* Examples of gnatbind Usage:: + +Switches for gnatbind + +* Consistency-Checking Modes:: +* Binder Error Message Control:: +* Elaboration Control:: +* Output Control:: +* Binding with Non-Ada Main Programs:: +* Binding Programs with No Main Subprogram:: + +Linking Using gnatlink + +* Running gnatlink:: +* Switches for gnatlink:: + +The GNAT Make Program gnatmake + +* Running gnatmake:: +* Switches for gnatmake:: +* Mode Switches for gnatmake:: +* Notes on the Command Line:: +* How gnatmake Works:: +* Examples of gnatmake Usage:: + +Improving Performance +* Performance Considerations:: +* Text_IO Suggestions:: +* Reducing Size of Ada Executables with gnatelim:: +* Reducing Size of Executables with unused subprogram/data elimination:: + +Performance Considerations +* Controlling Run-Time Checks:: +* Use of Restrictions:: +* Optimization Levels:: +* Debugging Optimized Code:: +* Inlining of Subprograms:: +* Other Optimization Switches:: +* Optimization and Strict Aliasing:: +@ifset vms +* Coverage Analysis:: +@end ifset + +Reducing Size of Ada Executables with gnatelim +* About gnatelim:: +* Running gnatelim:: +* Processing Precompiled Libraries:: +* Correcting the List of Eliminate Pragmas:: +* Making Your Executables Smaller:: +* Summary of the gnatelim Usage Cycle:: + +Reducing Size of Executables with unused subprogram/data elimination +* About unused subprogram/data elimination:: +* Compilation options:: + +Renaming Files Using gnatchop + +* Handling Files with Multiple Units:: +* Operating gnatchop in Compilation Mode:: +* Command Line for gnatchop:: +* Switches for gnatchop:: +* Examples of gnatchop Usage:: + +Configuration Pragmas + +* Handling of Configuration Pragmas:: +* The Configuration Pragmas Files:: + +Handling Arbitrary File Naming Conventions Using gnatname + +* Arbitrary File Naming Conventions:: +* Running gnatname:: +* Switches for gnatname:: +* Examples of gnatname Usage:: + +The Cross-Referencing Tools gnatxref and gnatfind + +* Switches for gnatxref:: +* Switches for gnatfind:: +* Project Files for gnatxref and gnatfind:: +* Regular Expressions in gnatfind and gnatxref:: +* Examples of gnatxref Usage:: +* Examples of gnatfind Usage:: + +The GNAT Pretty-Printer gnatpp + +* Switches for gnatpp:: +* Formatting Rules:: + +The GNAT Metrics Tool gnatmetric + +* Switches for gnatmetric:: + +File Name Krunching Using gnatkr + +* About gnatkr:: +* Using gnatkr:: +* Krunching Method:: +* Examples of gnatkr Usage:: + +Preprocessing Using gnatprep +* Preprocessing Symbols:: +* Using gnatprep:: +* Switches for gnatprep:: +* Form of Definitions File:: +* Form of Input Text for gnatprep:: + +The GNAT Library Browser gnatls + +* Running gnatls:: +* Switches for gnatls:: +* Examples of gnatls Usage:: + +Cleaning Up Using gnatclean + +* Running gnatclean:: +* Switches for gnatclean:: +@c * Examples of gnatclean Usage:: + +@ifclear vms + +GNAT and Libraries + +* Introduction to Libraries in GNAT:: +* General Ada Libraries:: +* Stand-alone Ada Libraries:: +* Rebuilding the GNAT Run-Time Library:: + +Using the GNU make Utility + +* Using gnatmake in a Makefile:: +* Automatically Creating a List of Directories:: +* Generating the Command Line Switches:: +* Overcoming Command Line Length Limits:: +@end ifclear + +Memory Management Issues + +* Some Useful Memory Pools:: +* The GNAT Debug Pool Facility:: +@ifclear vms +* The gnatmem Tool:: +@end ifclear + +Stack Related Facilities + +* Stack Overflow Checking:: +* Static Stack Usage Analysis:: +* Dynamic Stack Usage Analysis:: + +Some Useful Memory Pools + +The GNAT Debug Pool Facility + +@ifclear vms +The gnatmem Tool + +* Running gnatmem:: +* Switches for gnatmem:: +* Example of gnatmem Usage:: +@end ifclear + +Verifying Properties Using gnatcheck + +Sample Bodies Using gnatstub + +* Running gnatstub:: +* Switches for gnatstub:: + +Other Utility Programs + +* Using Other Utility Programs with GNAT:: +* The External Symbol Naming Scheme of GNAT:: +* Converting Ada Files to html with gnathtml:: + +@ifclear vms +Code Coverage and Profiling + +* Code Coverage of Ada Programs using gcov:: +* Profiling an Ada Program using gprof:: +@end ifclear + +Running and Debugging Ada Programs + +* The GNAT Debugger GDB:: +* Running GDB:: +* Introduction to GDB Commands:: +* Using Ada Expressions:: +* Calling User-Defined Subprograms:: +* Using the Next Command in a Function:: +* Ada Exceptions:: +* Ada Tasks:: +* Debugging Generic Units:: +* Remote Debugging using gdbserver:: +* GNAT Abnormal Termination or Failure to Terminate:: +* Naming Conventions for GNAT Source Files:: +* Getting Internal Debugging Information:: +* Stack Traceback:: + +@ifset vms +* LSE:: +@end ifset + +@ifset vms +Compatibility with HP Ada + +* Ada Language Compatibility:: +* Differences in the Definition of Package System:: +* Language-Related Features:: +* The Package STANDARD:: +* The Package SYSTEM:: +* Tasking and Task-Related Features:: +* Pragmas and Pragma-Related Features:: +* Library of Predefined Units:: +* Bindings:: +* Main Program Definition:: +* Implementation-Defined Attributes:: +* Compiler and Run-Time Interfacing:: +* Program Compilation and Library Management:: +* Input-Output:: +* Implementation Limits:: +* Tools and Utilities:: + +Language-Related Features + +* Integer Types and Representations:: +* Floating-Point Types and Representations:: +* Pragmas Float_Representation and Long_Float:: +* Fixed-Point Types and Representations:: +* Record and Array Component Alignment:: +* Address Clauses:: +* Other Representation Clauses:: + +Tasking and Task-Related Features + +* Implementation of Tasks in HP Ada for OpenVMS Alpha Systems:: +* Assigning Task IDs:: +* Task IDs and Delays:: +* Task-Related Pragmas:: +* Scheduling and Task Priority:: +* The Task Stack:: +* External Interrupts:: + +Pragmas and Pragma-Related Features + +* Restrictions on the Pragma INLINE:: +* Restrictions on the Pragma INTERFACE:: +* Restrictions on the Pragma SYSTEM_NAME:: + +Library of Predefined Units + +* Changes to DECLIB:: + +Bindings + +* Shared Libraries and Options Files:: +* Interfaces to C:: +@end ifset + +Platform-Specific Information for the Run-Time Libraries + +* Summary of Run-Time Configurations:: +* Specifying a Run-Time Library:: +* Choosing the Scheduling Policy:: +* Solaris-Specific Considerations:: +* Linux-Specific Considerations:: +* AIX-Specific Considerations:: +* Irix-Specific Considerations:: +* RTX-Specific Considerations:: +* HP-UX-Specific Considerations:: + +Example of Binder Output File + +Elaboration Order Handling in GNAT + +* 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 Access-to-Subprogram Values:: +* Summary of Procedures for Elaboration Control:: +* Other Elaboration Order Considerations:: + +Conditional Compilation +* Use of Boolean Constants:: +* Debugging - A Special Case:: +* Conditionalizing Declarations:: +* Use of Alternative Implementations:: +* Preprocessing:: + +Inline Assembler + +* Basic Assembler Syntax:: +* A Simple Example of Inline Assembler:: +* Output Variables in Inline Assembler:: +* Input Variables in Inline Assembler:: +* Inlining Inline Assembler Code:: +* Other Asm Functionality:: + +Compatibility and Porting Guide + +* Compatibility with Ada 83:: +* Compatibility between Ada 95 and Ada 2005:: +* Implementation-dependent characteristics:: +@ifclear vms +@c This brief section is only in the non-VMS version +@c The complete chapter on HP Ada issues is in the VMS version +* Compatibility with HP Ada 83:: +@end ifclear +* Compatibility with Other Ada Systems:: +* Representation Clauses:: +@ifset vms +* Transitioning to 64-Bit GNAT for OpenVMS:: +@end ifset + +@ifset unw +Microsoft Windows Topics + +* Using GNAT on Windows:: +* CONSOLE and WINDOWS subsystems:: +* Temporary Files:: +* Mixed-Language Programming on Windows:: +* Windows Calling Conventions:: +* Introduction to Dynamic Link Libraries (DLLs):: +* Using DLLs with GNAT:: +* Building DLLs with GNAT:: +* GNAT and Windows Resources:: +* Debugging a DLL:: +* Setting Stack Size from gnatlink:: +* Setting Heap Size from gnatlink:: +@end ifset + +* Index:: +@end menu +@end ifnottex + +@node About This Guide +@unnumbered About This Guide + +@noindent +@ifset vms +This guide describes the use of @value{EDITION}, +a compiler and software development toolset for the full Ada +programming language, implemented on OpenVMS for HP's Alpha and +Integrity server (I64) platforms. +@end ifset +@ifclear vms +This guide describes the use of @value{EDITION}, +a compiler and software development +toolset for the full Ada programming language. +@end ifclear +It documents the features of the compiler and tools, and explains +how to use them to build Ada applications. + +@value{EDITION} implements Ada 95 and Ada 2005, and it may also be invoked in +Ada 83 compatibility mode. +By default, @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION}, +but you can override with a compiler switch +(@pxref{Compiling Different Versions of Ada}) +to explicitly specify the language version. +Throughout this manual, references to ``Ada'' without a year suffix +apply to both the Ada 95 and Ada 2005 versions of the language. + + +@ifclear FSFEDITION +For ease of exposition, ``@value{EDITION}'' will be referred to simply as +``GNAT'' in the remainder of this document. +@end ifclear + + + + +@menu +* What This Guide Contains:: +* What You Should Know before Reading This Guide:: +* Related Information:: +* Conventions:: +@end menu + +@node What This Guide Contains +@unnumberedsec What This Guide Contains + +@noindent +This guide contains the following chapters: +@itemize @bullet + +@item +@ref{Getting Started with GNAT}, describes how to get started compiling +and running Ada programs with the GNAT Ada programming environment. +@item +@ref{The GNAT Compilation Model}, describes the compilation model used +by GNAT. + +@item +@ref{Compiling Using gcc}, describes how to compile +Ada programs with @command{gcc}, the Ada compiler. + +@item +@ref{Binding Using gnatbind}, describes how to +perform binding of Ada programs with @code{gnatbind}, the GNAT binding +utility. + +@item +@ref{Linking Using gnatlink}, +describes @command{gnatlink}, a +program that provides for linking using the GNAT run-time library to +construct a program. @command{gnatlink} can also incorporate foreign language +object units into the executable. + +@item +@ref{The GNAT Make Program gnatmake}, describes @command{gnatmake}, a +utility that automatically determines the set of sources +needed by an Ada compilation unit, and executes the necessary compilations +binding and link. + +@item +@ref{Improving Performance}, shows various techniques for making your +Ada program run faster or take less space. +It discusses the effect of the compiler's optimization switch and +also describes the @command{gnatelim} tool and unused subprogram/data +elimination. + +@item +@ref{Renaming Files Using gnatchop}, describes +@code{gnatchop}, a utility that allows you to preprocess a file that +contains Ada source code, and split it into one or more new files, one +for each compilation unit. + +@item +@ref{Configuration Pragmas}, describes the configuration pragmas +handled by GNAT. + +@item +@ref{Handling Arbitrary File Naming Conventions Using gnatname}, +shows how to override the default GNAT file naming conventions, +either for an individual unit or globally. + +@item +@ref{GNAT Project Manager}, describes how to use project files +to organize large projects. + +@item +@ref{The Cross-Referencing Tools gnatxref and gnatfind}, discusses +@code{gnatxref} and @code{gnatfind}, two tools that provide an easy +way to navigate through sources. + +@item +@ref{The GNAT Pretty-Printer gnatpp}, shows how to produce a reformatted +version of an Ada source file with control over casing, indentation, +comment placement, and other elements of program presentation style. + +@item +@ref{The GNAT Metric Tool gnatmetric}, shows how to compute various +metrics for an Ada source file, such as the number of types and subprograms, +and assorted complexity measures. + +@item +@ref{File Name Krunching Using gnatkr}, describes the @code{gnatkr} +file name krunching utility, used to handle shortened +file names on operating systems with a limit on the length of names. + +@item +@ref{Preprocessing Using gnatprep}, describes @code{gnatprep}, a +preprocessor utility that allows a single source file to be used to +generate multiple or parameterized source files by means of macro +substitution. + +@item +@ref{The GNAT Library Browser gnatls}, describes @code{gnatls}, a +utility that displays information about compiled units, including dependences +on the corresponding sources files, and consistency of compilations. + +@item +@ref{Cleaning Up Using gnatclean}, describes @code{gnatclean}, a utility +to delete files that are produced by the compiler, binder and linker. + +@ifclear vms +@item +@ref{GNAT and Libraries}, describes the process of creating and using +Libraries with GNAT. It also describes how to recompile the GNAT run-time +library. + +@item +@ref{Using the GNU make Utility}, describes some techniques for using +the GNAT toolset in Makefiles. +@end ifclear + +@item +@ref{Memory Management Issues}, describes some useful predefined storage pools +and in particular the GNAT Debug Pool facility, which helps detect incorrect +memory references. +@ifclear vms +It also describes @command{gnatmem}, a utility that monitors dynamic +allocation and deallocation and helps detect ``memory leaks''. +@end ifclear + +@item +@ref{Stack Related Facilities}, describes some useful tools associated with +stack checking and analysis. + +@item +@ref{Verifying Properties Using gnatcheck}, discusses @code{gnatcheck}, +a utility that checks Ada code against a set of rules. + +@item +@ref{Creating Sample Bodies Using gnatstub}, discusses @code{gnatstub}, +a utility that generates empty but compilable bodies for library units. + +@item +@ref{Generating Ada Bindings for C and C++ headers}, describes how to +generate automatically Ada bindings from C and C++ headers. + +@item +@ref{Other Utility Programs}, discusses several other GNAT utilities, +including @code{gnathtml}. + +@ifclear vms +@item +@ref{Code Coverage and Profiling}, describes how to perform a structural +coverage and profile the execution of Ada programs. +@end ifclear + +@item +@ref{Running and Debugging Ada Programs}, describes how to run and debug +Ada programs. + +@ifset vms +@item +@ref{Compatibility with HP Ada}, details the compatibility of GNAT with +HP Ada 83 @footnote{``HP Ada'' refers to the legacy product originally +developed by Digital Equipment Corporation and currently supported by HP.} +for OpenVMS Alpha. This product was formerly known as DEC Ada, +@cindex DEC Ada +and for +historical compatibility reasons, the relevant libraries still use the +DEC prefix. +@end ifset + +@item +@ref{Platform-Specific Information for the Run-Time Libraries}, +describes the various run-time +libraries supported by GNAT on various platforms and explains how to +choose a particular library. + +@item +@ref{Example of Binder Output File}, shows the source code for the binder +output file for a sample program. + +@item +@ref{Elaboration Order Handling in GNAT}, describes how GNAT helps +you deal with elaboration order issues. + +@item +@ref{Conditional Compilation}, describes how to model conditional compilation, +both with Ada in general and with GNAT facilities in particular. + +@item +@ref{Inline Assembler}, shows how to use the inline assembly facility +in an Ada program. + +@item +@ref{Compatibility and Porting Guide}, contains sections on compatibility +of GNAT with other Ada development environments (including Ada 83 systems), +to assist in porting code from those environments. + +@ifset unw +@item +@ref{Microsoft Windows Topics}, presents information relevant to the +Microsoft Windows platform. +@end ifset +@end itemize + +@c ************************************************* +@node What You Should Know before Reading This Guide +@c ************************************************* +@unnumberedsec What You Should Know before Reading This Guide + +@cindex Ada 95 Language Reference Manual +@cindex Ada 2005 Language Reference Manual +@noindent +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 new features introduced by Ada 2005, +(officially known as ISO/IEC 8652:1995 with Technical Corrigendum 1 +and Amendment 1). +Both reference manuals are included in the GNAT documentation +package. + +@node Related Information +@unnumberedsec Related Information + +@noindent +For further information about related tools, refer to the following +documents: + +@itemize @bullet +@item +@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT +Reference Manual}, which contains all reference material for the GNAT +implementation of Ada. + +@ifset unw +@item +@cite{Using the GNAT Programming Studio}, which describes the GPS +Integrated Development Environment. + +@item +@cite{GNAT Programming Studio Tutorial}, which introduces the +main GPS features through examples. +@end ifset + +@item +@cite{Ada 95 Reference Manual}, which contains reference +material for the Ada 95 programming language. + +@item +@cite{Ada 2005 Reference Manual}, which contains reference +material for the Ada 2005 programming language. + +@item +@xref{Top,, Debugging with GDB, gdb, Debugging with GDB}, +@ifset vms +in the GNU:[DOCS] directory, +@end ifset +for all details on the use of the GNU source-level debugger. + +@item +@xref{Top,, The extensible self-documenting text editor, emacs, +GNU Emacs Manual}, +@ifset vms +located in the GNU:[DOCS] directory if the EMACS kit is installed, +@end ifset +for full information on the extensible editor and programming +environment Emacs. + +@end itemize + +@c ************** +@node Conventions +@unnumberedsec Conventions +@cindex Conventions +@cindex Typographical conventions + +@noindent +Following are examples of the typographical and graphic conventions used +in this guide: + +@itemize @bullet +@item +@code{Functions}, @command{utility program names}, @code{standard names}, +and @code{classes}. + +@item +@option{Option flags} + +@item +@file{File names}, @samp{button names}, and @samp{field names}. + +@item +@code{Variables}, @env{environment variables}, and @var{metasyntactic +variables}. + +@item +@emph{Emphasis}. + +@item +@r{[}optional information or parameters@r{]} + +@item +Examples are described by text +@smallexample +and then shown this way. +@end smallexample +@end itemize + +@noindent +Commands that are entered by the user are preceded in this manual by the +characters @w{``@code{$ }''} (dollar sign followed by space). If your system +uses this sequence as a prompt, then the commands will appear exactly as +you see them in the manual. If your system uses some other prompt, then +the command will appear with the @code{$} replaced by whatever prompt +character you are using. + +@ifset unw +Full file names are shown with the ``@code{/}'' character +as the directory separator; e.g., @file{parent-dir/subdir/myfile.adb}. +If you are using GNAT on a Windows platform, please note that +the ``@code{\}'' character should be used instead. +@end ifset + +@c **************************** +@node Getting Started with GNAT +@chapter Getting Started with GNAT + +@noindent +This chapter describes some simple ways of using GNAT to build +executable Ada programs. +@ifset unw +@ref{Running GNAT}, through @ref{Using the gnatmake Utility}, +show how to use the command line environment. +@ref{Introduction to GPS}, provides a brief +introduction to the GNAT Programming Studio, a visually-oriented +Integrated Development Environment for GNAT. +GPS offers a graphical ``look and feel'', support for development in +other programming languages, comprehensive browsing features, and +many other capabilities. +For information on GPS please refer to +@cite{Using the GNAT Programming Studio}. +@end ifset + +@menu +* Running GNAT:: +* Running a Simple Ada Program:: +* Running a Program with Multiple Units:: +* Using the gnatmake Utility:: +@ifset vms +* Editing with Emacs:: +@end ifset +@ifclear vms +* Introduction to GPS:: +@end ifclear +@end menu + +@node Running GNAT +@section Running GNAT + +@noindent +Three steps are needed to create an executable file from an Ada source +file: + +@enumerate +@item +The source file(s) must be compiled. +@item +The file(s) must be bound using the GNAT binder. +@item +All appropriate object files must be linked to produce an executable. +@end enumerate + +@noindent +All three steps are most commonly handled by using the @command{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 +@section Running a Simple Ada Program + +@noindent +Any text editor may be used to prepare an Ada program. +(If @code{Emacs} is +used, the optional Ada mode may be helpful in laying out the program.) +The +program text is a normal text file. We will assume in our initial +example that you have used your editor to prepare the following +standard format text file: + +@smallexample @c ada +@cartouche +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello is +begin + Put_Line ("Hello WORLD!"); +end Hello; +@end cartouche +@end smallexample + +@noindent +This file should be named @file{hello.adb}. +With the normal default file naming conventions, GNAT requires +that each file +contain a single compilation unit whose file name is the +unit name, +with periods replaced by hyphens; the +extension is @file{ads} for a +spec and @file{adb} for a body. +You can override this default file naming convention by use of the +special pragma @code{Source_File_Name} (@pxref{Using Other File Names}). +Alternatively, if you want to rename your files according to this default +convention, which is probably more convenient if you will be using GNAT +for all your compilations, then the @code{gnatchop} utility +can be used to generate correctly-named source files +(@pxref{Renaming Files Using gnatchop}). + +You can compile the program using the following command (@code{$} is used +as the command prompt in the examples in this document): + +@smallexample +$ gcc -c hello.adb +@end smallexample + +@noindent +@command{gcc} is the command used to run the compiler. This compiler is +capable of compiling programs in several languages, including Ada and +C. It assumes that you have given it an Ada program if the file extension is +either @file{.ads} or @file{.adb}, and it will then call +the GNAT compiler to compile the specified file. + +@ifclear vms +The @option{-c} switch is required. It tells @command{gcc} to only do a +compilation. (For C programs, @command{gcc} can also do linking, but this +capability is not used directly for Ada programs, so the @option{-c} +switch must always be present.) +@end ifclear + +This compile command generates a file +@file{hello.o}, which is the object +file corresponding to your Ada program. It also generates +an ``Ada Library Information'' file @file{hello.ali}, +which contains additional information used to check +that an Ada program is consistent. +To build an executable file, +use @code{gnatbind} to bind the program +and @command{gnatlink} to link it. The +argument to both @code{gnatbind} and @command{gnatlink} is the name of the +@file{ALI} file, but the default extension of @file{.ali} can +be omitted. This means that in the most common case, the argument +is simply the name of the main program: + +@smallexample +$ gnatbind hello +$ gnatlink hello +@end smallexample + +@noindent +A simpler method of carrying out these steps is to use +@command{gnatmake}, +a master program that invokes all the required +compilation, binding and linking tools in the correct order. In particular, +@command{gnatmake} automatically recompiles any sources that have been +modified since they were last compiled, or sources that depend +on such modified sources, so that ``version skew'' is avoided. +@cindex Version skew (avoided by @command{gnatmake}) + +@smallexample +$ gnatmake hello.adb +@end smallexample + +@noindent +The result is an executable program called @file{hello}, which can be +run by entering: + +@smallexample +$ ^hello^RUN HELLO^ +@end smallexample + +@noindent +assuming that the current directory is on the search path +for executable programs. + +@noindent +and, if all has gone well, you will see + +@smallexample +Hello WORLD! +@end smallexample + +@noindent +appear in response to this command. + +@c **************************************** +@node Running a Program with Multiple Units +@section Running a Program with Multiple Units + +@noindent +Consider a slightly more complicated example that has three files: a +main program, and the spec and body of a package: + +@smallexample @c ada +@cartouche +@group +package Greetings is + procedure Hello; + procedure Goodbye; +end Greetings; + +with Ada.Text_IO; use Ada.Text_IO; +package body Greetings is + procedure Hello is + begin + Put_Line ("Hello WORLD!"); + end Hello; + + procedure Goodbye is + begin + Put_Line ("Goodbye WORLD!"); + end Goodbye; +end Greetings; +@end group + +@group +with Greetings; +procedure Gmain is +begin + Greetings.Hello; + Greetings.Goodbye; +end Gmain; +@end group +@end cartouche +@end smallexample + +@noindent +Following the one-unit-per-file rule, place this program in the +following three separate files: + +@table @file +@item greetings.ads +spec of package @code{Greetings} + +@item greetings.adb +body of package @code{Greetings} + +@item gmain.adb +body of main program +@end table + +@noindent +To build an executable version of +this program, we could use four separate steps to compile, bind, and link +the program, as follows: + +@smallexample +$ gcc -c gmain.adb +$ gcc -c greetings.adb +$ gnatbind gmain +$ gnatlink gmain +@end smallexample + +@noindent +Note that there is no required order of compilation when using GNAT. +In particular it is perfectly fine to compile the main program first. +Also, it is not necessary to compile package specs in the case where +there is an accompanying body; you only need to compile the body. If you want +to submit these files to the compiler for semantic checking and not code +generation, then use the +@option{-gnatc} switch: + +@smallexample +$ gcc -c greetings.ads -gnatc +@end smallexample + +@noindent +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 @command{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: + +@smallexample +$ gnatmake gmain.adb +@end smallexample + +@noindent +In the next section we discuss the advantages of using @command{gnatmake} in +more detail. + +@c ***************************** +@node Using the gnatmake Utility +@section Using the @command{gnatmake} Utility + +@noindent +If you work on a program by compiling single components at a time using +@command{gcc}, you typically keep track of the units you modify. In order to +build a consistent system, you compile not only these units, but also any +units that depend on the units you have modified. +For example, in the preceding case, +if you edit @file{gmain.adb}, you only need to recompile that file. But if +you edit @file{greetings.ads}, you must recompile both +@file{greetings.adb} and @file{gmain.adb}, because both files contain +units that depend on @file{greetings.ads}. + +@code{gnatbind} will warn you if you forget one of these compilation +steps, so that it is impossible to generate an inconsistent program as a +result of forgetting to do a compilation. Nevertheless it is tedious and +error-prone to keep track of dependencies among units. +One approach to handle the dependency-bookkeeping is to use a +makefile. However, makefiles present maintenance problems of their own: +if the dependencies change as you change the program, you must make +sure that the makefile is kept up-to-date manually, which is also an +error-prone process. + +The @command{gnatmake} utility takes care of these details automatically. +Invoke it using either one of the following forms: + +@smallexample +$ gnatmake gmain.adb +$ gnatmake ^gmain^GMAIN^ +@end smallexample + +@noindent +The argument is the name of the file containing the main program; +you may omit the extension. @command{gnatmake} +examines the environment, automatically recompiles any files that need +recompiling, and binds and links the resulting set of object files, +generating the executable file, @file{^gmain^GMAIN.EXE^}. +In a large program, it +can be extremely helpful to use @command{gnatmake}, because working out by hand +what needs to be recompiled can be difficult. + +Note that @command{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, @command{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. @command{gnatmake} determines the exact set of +dependencies from scratch each time it is run. + +@ifset vms +@node Editing with Emacs +@section Editing with Emacs +@cindex Emacs + +@noindent +Emacs is an extensible self-documenting text editor that is available in a +separate VMSINSTAL kit. + +Invoke Emacs by typing @kbd{Emacs} at the command prompt. To get started, +click on the Emacs Help menu and run the Emacs Tutorial. +In a character cell terminal, Emacs help is invoked with @kbd{Ctrl-h} (also +written as @kbd{C-h}), and the tutorial by @kbd{C-h t}. + +Documentation on Emacs and other tools is available in Emacs under the +pull-down menu button: @code{Help - Info}. After selecting @code{Info}, +use the middle mouse button to select a topic (e.g.@: Emacs). + +In a character cell terminal, do @kbd{C-h i} to invoke info, and then @kbd{m} +(stands for menu) followed by the menu item desired, as in @kbd{m Emacs}, to +get to the Emacs manual. +Help on Emacs is also available by typing @kbd{HELP EMACS} at the DCL command +prompt. + +The tutorial is highly recommended in order to learn the intricacies of Emacs, +which is sufficiently extensible to provide for a complete programming +environment and shell for the sophisticated user. +@end ifset + +@ifclear vms +@node Introduction to GPS +@section Introduction to GPS +@cindex GPS (GNAT Programming Studio) +@cindex GNAT Programming Studio (GPS) +@noindent +Although the command line interface (@command{gnatmake}, etc.) alone +is sufficient, a graphical Interactive Development +Environment can make it easier for you to compose, navigate, and debug +programs. This section describes the main features of GPS +(``GNAT Programming Studio''), the GNAT graphical IDE. +You will see how to use GPS to build and debug an executable, and +you will also learn some of the basics of the GNAT ``project'' facility. + +GPS enables you to do much more than is presented here; +e.g., you can produce a call graph, interface to a third-party +Version Control System, and inspect the generated assembly language +for a program. +Indeed, GPS also supports languages other than Ada. +Such additional information, and an explanation of all of the GPS menu +items. may be found in the on-line help, which includes +a user's guide and a tutorial (these are also accessible from the GNAT +startup menu). + +@menu +* Building a New Program with GPS:: +* Simple Debugging with GPS:: +@end menu + +@node Building a New Program with GPS +@subsection Building a New Program with GPS +@noindent +GPS invokes the GNAT compilation tools using information +contained in a @emph{project} (also known as a @emph{project file}): +a collection of properties such +as source directories, identities of main subprograms, tool switches, etc., +and their associated values. +See @ref{GNAT Project Manager} for details. +In order to run GPS, you will need to either create a new project +or else open an existing one. + +This section will explain how you can use GPS to create a project, +to associate Ada source files with a project, and to build and run +programs. + +@enumerate +@item @emph{Creating a project} + +Invoke GPS, either from the command line or the platform's IDE. +After it starts, GPS will display a ``Welcome'' screen with three +radio buttons: + +@itemize @bullet +@item +@code{Start with default project in directory} + +@item +@code{Create new project with wizard} + +@item +@code{Open existing project} +@end itemize + +@noindent +Select @code{Create new project with wizard} and press @code{OK}. +A new window will appear. In the text box labeled with +@code{Enter the name of the project to create}, type @file{sample} +as the project name. +In the next box, browse to choose the directory in which you +would like to create the project file. +After selecting an appropriate directory, press @code{Forward}. + +A window will appear with the title +@code{Version Control System Configuration}. +Simply press @code{Forward}. + +A window will appear with the title +@code{Please select the source directories for this project}. +The directory that you specified for the project file will be selected +by default as the one to use for sources; simply press @code{Forward}. + +A window will appear with the title +@code{Please select the build directory for this project}. +The directory that you specified for the project file will be selected +by default for object files and executables; +simply press @code{Forward}. + +A window will appear with the title +@code{Please select the main units for this project}. +You will supply this information later, after creating the source file. +Simply press @code{Forward} for now. + +A window will appear with the title +@code{Please select the switches to build the project}. +Press @code{Apply}. This will create a project file named +@file{sample.prj} in the directory that you had specified. + +@item @emph{Creating and saving the source file} + +After you create the new project, a GPS window will appear, which is +partitioned into two main sections: + +@itemize @bullet +@item +A @emph{Workspace area}, initially greyed out, which you will use for +creating and editing source files + +@item +Directly below, a @emph{Messages area}, which initially displays a +``Welcome'' message. +(If the Messages area is not visible, drag its border upward to expand it.) +@end itemize + +@noindent +Select @code{File} on the menu bar, and then the @code{New} command. +The Workspace area will become white, and you can now +enter the source program explicitly. +Type the following text + +@smallexample @c ada +@group +with Ada.Text_IO; use Ada.Text_IO; +procedure Hello is +begin + Put_Line("Hello from GPS!"); +end Hello; +@end group +@end smallexample + +@noindent +Select @code{File}, then @code{Save As}, and enter the source file name +@file{hello.adb}. +The file will be saved in the same directory you specified as the +location of the default project file. + +@item @emph{Updating the project file} + +You need to add the new source file to the project. +To do this, select +the @code{Project} menu and then @code{Edit project properties}. +Click the @code{Main files} tab on the left, and then the +@code{Add} button. +Choose @file{hello.adb} from the list, and press @code{Open}. +The project settings window will reflect this action. +Click @code{OK}. + +@item @emph{Building and running the program} + +In the main GPS window, now choose the @code{Build} menu, then @code{Make}, +and select @file{hello.adb}. +The Messages window will display the resulting invocations of @command{gcc}, +@command{gnatbind}, and @command{gnatlink} +(reflecting the default switch settings from the +project file that you created) and then a ``successful compilation/build'' +message. + +To run the program, choose the @code{Build} menu, then @code{Run}, and +select @command{hello}. +An @emph{Arguments Selection} window will appear. +There are no command line arguments, so just click @code{OK}. + +The Messages window will now display the program's output (the string +@code{Hello from GPS}), and at the bottom of the GPS window a status +update is displayed (@code{Run: hello}). +Close the GPS window (or select @code{File}, then @code{Exit}) to +terminate this GPS session. +@end enumerate + +@node Simple Debugging with GPS +@subsection Simple Debugging with GPS +@noindent +This section illustrates basic debugging techniques (setting breakpoints, +examining/modifying variables, single stepping). + +@enumerate +@item @emph{Opening a project} + +Start GPS and select @code{Open existing project}; browse to +specify the project file @file{sample.prj} that you had created in the +earlier example. + +@item @emph{Creating a source file} + +Select @code{File}, then @code{New}, and type in the following program: + +@smallexample @c ada +@group +with Ada.Text_IO; use Ada.Text_IO; +procedure Example is + Line : String (1..80); + N : Natural; +begin + Put_Line("Type a line of text at each prompt; an empty line to exit"); + loop + Put(": "); + Get_Line (Line, N); + Put_Line (Line (1..N) ); + exit when N=0; + end loop; +end Example; +@end group +@end smallexample + +@noindent +Select @code{File}, then @code{Save as}, and enter the file name +@file{example.adb}. + +@item @emph{Updating the project file} + +Add @code{Example} as a new main unit for the project: +@enumerate a +@item +Select @code{Project}, then @code{Edit Project Properties}. + +@item +Select the @code{Main files} tab, click @code{Add}, then +select the file @file{example.adb} from the list, and +click @code{Open}. +You will see the file name appear in the list of main units + +@item +Click @code{OK} +@end enumerate + +@item @emph{Building/running the executable} + +To build the executable +select @code{Build}, then @code{Make}, and then choose @file{example.adb}. + +Run the program to see its effect (in the Messages area). +Each line that you enter is displayed; an empty line will +cause the loop to exit and the program to terminate. + +@item @emph{Debugging the program} + +Note that the @option{-g} switches to @command{gcc} and @command{gnatlink}, +which are required for debugging, are on by default when you create +a new project. +Thus unless you intentionally remove these settings, you will be able +to debug any program that you develop using GPS. + +@enumerate a +@item @emph{Initializing} + +Select @code{Debug}, then @code{Initialize}, then @file{example} + +@item @emph{Setting a breakpoint} + +After performing the initialization step, you will observe a small +icon to the right of each line number. +This serves as a toggle for breakpoints; clicking the icon will +set a breakpoint at the corresponding line (the icon will change to +a red circle with an ``x''), and clicking it again +will remove the breakpoint / reset the icon. + +For purposes of this example, set a breakpoint at line 10 (the +statement @code{Put_Line@ (Line@ (1..N));} + +@item @emph{Starting program execution} + +Select @code{Debug}, then @code{Run}. When the +@code{Program Arguments} window appears, click @code{OK}. +A console window will appear; enter some line of text, +e.g.@: @code{abcde}, at the prompt. +The program will pause execution when it gets to the +breakpoint, and the corresponding line is highlighted. + +@item @emph{Examining a variable} + +Move the mouse over one of the occurrences of the variable @code{N}. +You will see the value (5) displayed, in ``tool tip'' fashion. +Right click on @code{N}, select @code{Debug}, then select @code{Display N}. +You will see information about @code{N} appear in the @code{Debugger Data} +pane, showing the value as 5. + +@item @emph{Assigning a new value to a variable} + +Right click on the @code{N} in the @code{Debugger Data} pane, and +select @code{Set value of N}. +When the input window appears, enter the value @code{4} and click +@code{OK}. +This value does not automatically appear in the @code{Debugger Data} +pane; to see it, right click again on the @code{N} in the +@code{Debugger Data} pane and select @code{Update value}. +The new value, 4, will appear in red. + +@item @emph{Single stepping} + +Select @code{Debug}, then @code{Next}. +This will cause the next statement to be executed, in this case the +call of @code{Put_Line} with the string slice. +Notice in the console window that the displayed string is simply +@code{abcd} and not @code{abcde} which you had entered. +This is because the upper bound of the slice is now 4 rather than 5. + +@item @emph{Removing a breakpoint} + +Toggle the breakpoint icon at line 10. + +@item @emph{Resuming execution from a breakpoint} + +Select @code{Debug}, then @code{Continue}. +The program will reach the next iteration of the loop, and +wait for input after displaying the prompt. +This time, just hit the @kbd{Enter} key. +The value of @code{N} will be 0, and the program will terminate. +The console window will disappear. +@end enumerate +@end enumerate +@end ifclear + +@node The GNAT Compilation Model +@chapter The GNAT Compilation Model +@cindex GNAT compilation model +@cindex Compilation model + +@menu +* Source Representation:: +* Foreign Language Representation:: +* File Naming Rules:: +* Using Other File Names:: +* Alternative File Naming Schemes:: +* Generating Object Files:: +* Source Dependencies:: +* The Ada Library Information Files:: +* Binding an Ada Program:: +* Mixed Language Programming:: +@ifclear vms +* Building Mixed Ada & C++ Programs:: +* Comparison between GNAT and C/C++ Compilation Models:: +@end ifclear +* Comparison between GNAT and Conventional Ada Library Models:: +@ifset vms +* Placement of temporary files:: +@end ifset +@end menu + +@noindent +This chapter describes the compilation model used by GNAT. Although +similar to that used by other languages, such as C and C++, this model +is substantially different from the traditional Ada compilation models, +which are based on a library. The model is initially described without +reference to the library-based model. If you have not previously used an +Ada compiler, you need only read the first part of this chapter. The +last section describes and discusses the differences between the GNAT +model and the traditional Ada compiler models. If you have used other +Ada compilers, this section will help you to understand those +differences, and the advantages of the GNAT model. + +@node Source Representation +@section Source Representation +@cindex Latin-1 + +@noindent +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 (@pxref{Foreign Language Representation} +for support of non-USA character sets). The format effector characters +are represented using their standard ASCII encodings, as follows: + +@table @code +@item VT +@findex VT +Vertical tab, @code{16#0B#} + +@item HT +@findex HT +Horizontal tab, @code{16#09#} + +@item CR +@findex CR +Carriage return, @code{16#0D#} + +@item LF +@findex LF +Line feed, @code{16#0A#} + +@item FF +@findex FF +Form feed, @code{16#0C#} +@end table + +@noindent +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: +@code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful +in accommodating files that are imported from other operating systems. + +@cindex End of source file +@cindex Source file, end +@findex SUB +The end of a source file is normally represented by the physical end of +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 @dfn{spec}) and the corresponding body in +separate files. An Ada @dfn{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 +@section Foreign Language Representation + +@noindent +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 (@pxref{Character Set Control}). +@menu +* Latin-1:: +* Other 8-Bit Codes:: +* Wide Character Encodings:: +@end menu + +@node Latin-1 +@subsection Latin-1 +@cindex Latin-1 + +@noindent +The basic character set is Latin-1. This character set is defined by ISO +standard 8859, part 1. The lower half (character codes @code{16#00#} +@dots{} @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. + +@findex Ada.Characters.Latin_1 +For a complete list of Latin-1 codes and their encodings, see the source +file of library unit @code{Ada.Characters.Latin_1} in file +@file{a-chlat1.ads}. +You may use any of these extended characters freely in character or +string literals. In addition, the extended characters that represent +letters can be used in identifiers. + +@node Other 8-Bit Codes +@subsection Other 8-Bit Codes + +@noindent +GNAT also supports several other 8-bit coding schemes: + +@table @asis +@item ISO 8859-2 (Latin-2) +@cindex Latin-2 +@cindex ISO 8859-2 +Latin-2 letters allowed in identifiers, with uppercase and lowercase +equivalence. + +@item ISO 8859-3 (Latin-3) +@cindex Latin-3 +@cindex ISO 8859-3 +Latin-3 letters allowed in identifiers, with uppercase and lowercase +equivalence. + +@item ISO 8859-4 (Latin-4) +@cindex Latin-4 +@cindex ISO 8859-4 +Latin-4 letters allowed in identifiers, with uppercase and lowercase +equivalence. + +@item ISO 8859-5 (Cyrillic) +@cindex ISO 8859-5 +@cindex Cyrillic +ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and +lowercase equivalence. + +@item ISO 8859-15 (Latin-9) +@cindex ISO 8859-15 +@cindex Latin-9 +ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and +lowercase equivalence + +@item IBM PC (code page 437) +@cindex code page 437 +This code page is the normal default for PCs in the U.S. It corresponds +to the original IBM PC character set. This set has some, but not all, of +the extended Latin-1 letters, but these letters do not have the same +encoding as Latin-1. In this mode, these letters are allowed in +identifiers with uppercase and lowercase equivalence. + +@item IBM PC (code page 850) +@cindex code page 850 +This code page is a modification of 437 extended to include all the +Latin-1 letters, but still not with the usual Latin-1 encoding. In this +mode, all these letters are allowed in identifiers with uppercase and +lowercase equivalence. + +@item Full Upper 8-bit +Any character in the range 80-FF allowed in identifiers, and all are +considered distinct. In other words, there are no uppercase and lowercase +equivalences in this range. This is useful in conjunction with +certain encoding schemes used for some foreign character sets (e.g., +the typical method of representing Chinese characters on the PC). + +@item No Upper-Half +No upper-half characters in the range 80-FF are allowed in identifiers. +This gives Ada 83 compatibility for identifier names. +@end table + +@noindent +For precise data on the encodings permitted, and the uppercase and lowercase +equivalences that are recognized, see the file @file{csets.adb} in +the GNAT compiler sources. You will need to obtain a full source release +of GNAT to obtain this file. + +@node Wide Character Encodings +@subsection Wide Character Encodings + +@noindent +GNAT allows wide character codes to appear in character and string +literals, and also optionally in identifiers, by means of the following +possible encoding schemes: + +@table @asis + +@item Hex Coding +In this encoding, a wide character is represented by the following five +character sequence: + +@smallexample +ESC a b c d +@end smallexample + +@noindent +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 +@code{16#A345#}. +This scheme is compatible with use of the full Wide_Character set. + +@item Upper-Half Coding +@cindex Upper-Half Coding +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, +@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. + +@item Shift JIS Coding +@cindex Shift JIS Coding +A wide character is represented by a two-character sequence, +@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 +used with this encoding method. + +@item EUC Coding +@cindex EUC Coding +A wide character is represented by a two-character sequence +@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. + +@item UTF-8 Coding +A wide character is represented using +UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO +10646-1/Am.2. Depending on the character value, the representation +is a one, two, or three byte sequence: +@smallexample +@iftex +@leftskip=.7cm +@end iftex +16#0000#-16#007f#: 2#0@var{xxxxxxx}# +16#0080#-16#07ff#: 2#110@var{xxxxx}# 2#10@var{xxxxxx}# +16#0800#-16#ffff#: 2#1110@var{xxxx}# 2#10@var{xxxxxx}# 2#10@var{xxxxxx}# + +@end smallexample + +@noindent +where the @var{xxx} bits correspond to the left-padded bits of the +16-bit character value. Note that all lower half ASCII characters +are represented as ASCII bytes and all upper half characters and +other wide characters are represented as sequences of upper-half +(The full UTF-8 scheme allows for encoding 31-bit characters as +6-byte sequences, but in this implementation, all UTF-8 sequences +of four or more bytes length will be treated as illegal). +@item Brackets Coding +In this encoding, a wide character is represented by the following eight +character sequence: + +@smallexample +[ " a b c d " ] +@end smallexample + +@noindent +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 +@code{16#A345#}. It is also possible (though not required) to use the +Brackets coding for upper half characters. For example, the code +@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 the standard +ACVC (Ada Compiler Validation Capability) test suite distributions. + +@end table + +@noindent +Note: Some of these coding schemes do not permit the full use of the +Ada character set. For example, neither Shift JIS, nor EUC allow the +use of the upper half of the Latin-1 set. + +@node File Naming Rules +@section File Naming Rules + +@noindent +The default file name is determined by the name of the unit that the +file contains. The name is formed by taking the full expanded name of +the unit and replacing the separating dots with hyphens and using +^lowercase^uppercase^ for all letters. + +An exception arises if the file name generated by the above rules starts +with one of the characters +@ifset vms +@samp{A}, @samp{G}, @samp{I}, or @samp{S}, +@end ifset +@ifclear vms +@samp{a}, @samp{g}, @samp{i}, or @samp{s}, +@end ifclear +and the second character is a +minus. In this case, the character ^tilde^dollar sign^ 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 +@ifset vms +@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-}, +@end ifset +@ifclear vms +@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-}, +@end ifclear +respectively. + +The file extension is @file{.ads} for a spec and +@file{.adb} for a body. The following list shows some +examples of these rules. + +@table @file +@item main.ads +Main (spec) +@item main.adb +Main (body) +@item arith_functions.ads +Arith_Functions (package spec) +@item arith_functions.adb +Arith_Functions (package body) +@item func-spec.ads +Func.Spec (child package spec) +@item func-spec.adb +Func.Spec (child package body) +@item main-sub.adb +Sub (subunit of Main) +@item ^a~bad.adb^A$BAD.ADB^ +A.Bad (child package body) +@end table + +@noindent +Following these rules can result in excessively long +file names if corresponding +unit names are long (for example, if child units or subunits are +heavily nested). An option is available to shorten such long file names +(called file name ``krunching''). This may be particularly useful when +programs being developed with GNAT are to be used on operating systems +with limited file name lengths. @xref{Using gnatkr}. + +Of course, no file shortening algorithm can guarantee uniqueness over +all possible unit names; if file name krunching is used, it is your +responsibility to ensure no name clashes occur. Alternatively you +can specify the exact file names that you want used, as described +in the next section. Finally, if your Ada programs are migrating from a +compiler with a different naming convention, you can use the gnatchop +utility to produce source files that follow the GNAT naming conventions. +(For details @pxref{Renaming Files Using gnatchop}.) + +Note: in the case of @code{Windows NT/XP} or @code{OpenVMS} operating +systems, case is not significant. So for example on @code{Windows XP} +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 +@section Using Other File Names +@cindex File names + +@noindent +In the previous section, we have described the default rules used by +GNAT to determine the file name in which a given unit resides. It is +often convenient to follow these default rules, and if you follow them, +the compiler knows without being explicitly told where to find all +the files it needs. + +However, in some cases, particularly when a program is imported from +another Ada compiler environment, it may be more convenient for the +programmer to specify which file names contain which units. GNAT allows +arbitrary file names to be used by means of the Source_File_Name pragma. +The form of this pragma is as shown in the following examples: +@cindex Source_File_Name pragma + +@smallexample @c ada +@cartouche +pragma Source_File_Name (My_Utilities.Stacks, + Spec_File_Name => "myutilst_a.ada"); +pragma Source_File_name (My_Utilities.Stacks, + Body_File_Name => "myutilst.ada"); +@end cartouche +@end smallexample + +@noindent +As shown in this example, the first argument for the pragma is the unit +name (in this example a child unit). The second argument has the form +of a named association. The identifier +indicates whether the file name is for a spec or a body; +the file name itself is given by a string literal. + +The source file name pragma is a configuration pragma, which means that +normally it will be placed in the @file{gnat.adc} +file used to hold configuration +pragmas that apply to a complete compilation environment. +For more details on how the @file{gnat.adc} file is created and used +see @ref{Handling of Configuration Pragmas}. +@cindex @file{gnat.adc} + +@ifclear vms +GNAT allows completely arbitrary file names to be specified using the +source file name pragma. However, if the file name specified has an +extension other than @file{.ads} or @file{.adb} it is necessary to use +a special syntax when compiling the file. The name in this case must be +preceded by the special sequence @option{-x} followed by a space and the name +of the language, here @code{ada}, as in: + +@smallexample +$ gcc -c -x ada peculiar_file_name.sim +@end smallexample +@end ifclear + +@noindent +@command{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 @command{gnatmake} command, it may not +be omitted. + +@node Alternative File Naming Schemes +@section Alternative File Naming Schemes +@cindex File naming schemes, alternative +@cindex File names + +In the previous section, we 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 @file{gnat.adc} files, and also create +a maintenance problem. + +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 +@code{Source_File_Name} pragmas having the following format: +@cindex Source_File_Name pragma + +@smallexample @c ada +pragma Source_File_Name ( + Spec_File_Name => FILE_NAME_PATTERN + @r{[},Casing => CASING_SPEC@r{]} + @r{[},Dot_Replacement => STRING_LITERAL@r{]}); + +pragma Source_File_Name ( + Body_File_Name => FILE_NAME_PATTERN + @r{[},Casing => CASING_SPEC@r{]} + @r{[},Dot_Replacement => STRING_LITERAL@r{]}); + +pragma Source_File_Name ( + Subunit_File_Name => FILE_NAME_PATTERN + @r{[},Casing => CASING_SPEC@r{]} + @r{[},Dot_Replacement => STRING_LITERAL@r{]}); + +FILE_NAME_PATTERN ::= STRING_LITERAL +CASING_SPEC ::= Lowercase | Uppercase | Mixedcase +@end smallexample + +@noindent +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 +@code{Casing} indicates +whether the unit name is to be all upper-case letters, all lower-case letters, +or mixed-case. If no +@code{Casing} parameter is used, then the default is all +^lower-case^upper-case^. + +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 +@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 @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 +contains a subunit and a child unit with the same unit name. Although +both units cannot appear in the same partition, the Ada Reference Manual +allows (but does not require) the possibility of the two units coexisting +in the same environment. + +The file name translation works in the following steps: + +@itemize @bullet + +@item +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 @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 @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 + +@noindent +As an example of the use of this mechanism, consider a commonly used scheme +in which file names are all lower case, with separating periods copied +unchanged to the resulting file name, and specs end with @file{.1.ada}, and +bodies end with @file{.2.ada}. GNAT will follow this scheme if the following +two pragmas appear: + +@smallexample @c ada +pragma Source_File_Name + (Spec_File_Name => "*.1.ada"); +pragma Source_File_Name + (Body_File_Name => "*.2.ada"); +@end smallexample + +@noindent +The default GNAT scheme is actually implemented by providing the following +default pragmas internally: + +@smallexample @c ada +pragma Source_File_Name + (Spec_File_Name => "*.ads", Dot_Replacement => "-"); +pragma Source_File_Name + (Body_File_Name => "*.adb", Dot_Replacement => "-"); +@end smallexample + +@noindent +Our final example implements a scheme typically used with one of the +Ada 83 compilers, where the separator character for subunits was ``__'' +(two underscores), specs were identified by adding @file{_.ADA}, bodies +by adding @file{.ADA}, and subunits by +adding @file{.SEP}. All file names were +upper case. Child units were not present of course since this was an +Ada 83 compiler, but it seems reasonable to extend this scheme to use +the same double underscore separator for child units. + +@smallexample @c ada +pragma Source_File_Name + (Spec_File_Name => "*_.ADA", + Dot_Replacement => "__", + Casing = Uppercase); +pragma Source_File_Name + (Body_File_Name => "*.ADA", + Dot_Replacement => "__", + Casing = Uppercase); +pragma Source_File_Name + (Subunit_File_Name => "*.SEP", + Dot_Replacement => "__", + Casing = Uppercase); +@end smallexample + +@node Generating Object Files +@section Generating Object Files + +@noindent +An Ada program consists of a set of source files, and the first step in +compiling the program is to generate the corresponding object files. +These are generated by compiling a subset of these source files. +The files you need to compile are the following: + +@itemize @bullet +@item +If a package spec has no body, compile the package spec to produce the +object file for the package. + +@item +If a package has both a spec and a body, compile the body to produce the +object file for the package. The source file for the package spec need +not be compiled in this case because there is only one object file, which +contains the code for both the spec and body of the package. + +@item +For a subprogram, compile the subprogram body to produce the object file +for the subprogram. The spec, if one is present, is as usual in a +separate file, and need not be compiled. + +@item +@cindex Subunits +In the case of subunits, only compile the parent unit. A single object +file is generated for the entire subunit tree, which includes all the +subunits. + +@item +Compile child units independently of their parent units +(though, of course, the spec of all the ancestor unit must be present in order +to compile a child unit). + +@item +@cindex Generics +Compile generic units in the same manner as any other units. The object +files in this case are small dummy files that contain at most the +flag used for elaboration checking. This is because GNAT always handles generic +instantiation by means of macro expansion. However, it is still necessary to +compile generic units, for dependency checking and elaboration purposes. +@end itemize + +@noindent +The preceding rules describe the set of files that must be compiled to +generate the object files for a program. Each object file has the same +name as the corresponding source file, except that the extension is +@file{.o} as usual. + +You may wish to compile other files for the purpose of checking their +syntactic and semantic correctness. For example, in the case where a +package has a separate spec and body, you would not normally compile the +spec. However, it is convenient in practice to compile the spec to make +sure it is error-free before compiling clients of this spec, because such +compilations will fail if there is an error in the spec. + +GNAT provides an option for compiling such files purely for the +purposes of checking correctness; such compilations are not required as +part of the process of building a program. To compile a file in this +checking mode, use the @option{-gnatc} switch. + +@node Source Dependencies +@section Source Dependencies + +@noindent +A given object file clearly depends on the source file which is compiled +to produce it. Here we are using @dfn{depends} in the sense of a typical +@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 +additional source files as follows: + +@itemize @bullet +@item +If a file being compiled @code{with}'s a unit @var{X}, the object file +depends on the file containing the spec of unit @var{X}. This includes +files that are @code{with}'ed implicitly either because they are parents +of @code{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 instantiates a library level generic unit, the +object file depends on both the spec and body files for this generic +unit. + +@item +If a file being compiled instantiates a generic unit defined within a +package, the object file depends on the body file for the package as +well as the spec file. + +@item +@findex Inline +@cindex @option{-gnatn} switch +If a file being compiled contains a call to a subprogram for which +pragma @code{Inline} applies and inlining is activated with the +@option{-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. + +@cindex @option{-gnatN} switch +The use of @option{-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 @option{-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 the JGNAT, .NET or GNAAMP versions), then the use of +@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred. +Historically front end inlining was more extensive than the gcc back end +inlining, but that is no longer the case. + +@item +If an object file @file{O} depends on the proper body of a subunit through +inlining or instantiation, it depends on the parent unit of the subunit. +This means that any modification of the parent unit or one of its subunits +affects the compilation of @file{O}. + +@item +The object file for a parent unit depends on all its subunit body files. + +@item +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. + +@noindent +These rules are applied transitively: if unit @code{A} @code{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 @file{c.adb}. + +The set of dependent files described by these rules includes all the +files on which the unit is semantically dependent, as dictated by the +Ada language standard. However, it is a superset of what the +standard describes, because it includes generic, inline, and subunit +dependencies. + +An object file must be recreated by recompiling the corresponding source +file if any of the source files on which it depends are modified. For +example, if the @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 @command{gnatmake}. +@end itemize + +@node The Ada Library Information Files +@section The Ada Library Information Files +@cindex Ada Library Information files +@cindex @file{ALI} files + +@noindent +Each compilation actually generates two output files. The first of these +is the normal object file that has a @file{.o} extension. The second is a +text file containing full dependency information. It has the same +name as the source file, but an @file{.ali} extension. +This file is known as the Ada Library Information (@file{ALI}) file. +The following information is contained in the @file{ALI} file. + +@itemize @bullet +@item +Version information (indicates which version of GNAT was used to compile +the unit(s) in question) + +@item +Main program information (including priority and time slice settings, +as well as the wide character encoding used during compilation). + +@item +List of arguments used in the @command{gcc} command for the compilation + +@item +Attributes of the unit, including configuration pragmas used, an indication +of whether the compilation was successful, exception model used etc. + +@item +A list of relevant restrictions applying to the unit (used for consistency) +checking. + +@item +Categorization information (e.g.@: use of pragma @code{Pure}). + +@item +Information on all @code{with}'ed units, including presence of +@code{Elaborate} or @code{Elaborate_All} pragmas. + +@item +Information from any @code{Linker_Options} pragmas used in the unit + +@item +Information on the use of @code{Body_Version} or @code{Version} +attributes in the unit. + +@item +Dependency information. This is a list of files, together with +time stamp and checksum information. These are files on which +the unit depends in the sense that recompilation is required +if any of these units are modified. + +@item +Cross-reference data. Contains information on all entities referenced +in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to +provide cross-reference information. + +@end itemize + +@noindent +For a full detailed description of the format of the @file{ALI} file, +see the source of the body of unit @code{Lib.Writ}, contained in file +@file{lib-writ.adb} in the GNAT compiler sources. + +@node Binding an Ada Program +@section Binding an Ada Program + +@noindent +When using languages such as C and C++, once the source files have been +compiled the only remaining step in building an executable program +is linking the object modules together. This means that it is possible to +link an inconsistent version of a program, in which two units have +included different versions of the same header. + +The rules of Ada do not permit such an inconsistent program to be built. +For example, if two clients have different versions of the same package, +it is illegal to build a program containing these two clients. +These rules are enforced by the GNAT binder, which also determines an +elaboration order consistent with the Ada rules. + +The GNAT binder is run after all the object files for a program have +been created. It is given the name of the main program unit, and from +this it determines the set of units required by the program, by reading the +corresponding ALI files. It generates error messages if the program is +inconsistent or if no valid order of elaboration exists. + +If no errors are detected, the binder produces a main program, in Ada by +default, that contains calls to the elaboration procedures of those +compilation unit that require them, followed by +a call to the main program. This Ada program is compiled to generate the +object file for the main program. The name of +the Ada file is @file{b~@var{xxx}.adb} (with the corresponding spec +@file{b~@var{xxx}.ads}) where @var{xxx} is the name of the +main program unit. + +Finally, the linker is used to build the resulting executable program, +using the object from the main program from the bind step as well as the +object files for the Ada units of the program. + +@node Mixed Language Programming +@section Mixed Language Programming +@cindex Mixed Language Programming + +@noindent +This section describes how to develop a mixed-language program, +specifically one that comprises units in both Ada and C. + +@menu +* Interfacing to C:: +* Calling Conventions:: +@end menu + +@node Interfacing to C +@subsection Interfacing to C +@noindent +Interfacing Ada with a foreign language such as C involves using +compiler directives to import and/or export entity definitions in each +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. + +There are two ways to build a program using GNAT that contains some Ada +sources and some foreign language sources, depending on whether or not +the main subprogram is written in Ada. Here is a source example with +the main subprogram in Ada: + +@smallexample +/* file1.c */ +#include + +void print_num (int num) +@{ + printf ("num is %d.\n", num); + return; +@} + +/* file2.c */ + +/* num_from_Ada is declared in my_main.adb */ +extern int num_from_Ada; + +int get_num (void) +@{ + return num_from_Ada; +@} +@end smallexample + +@smallexample @c ada +-- my_main.adb +procedure My_Main is + + -- Declare then export an Integer entity called num_from_Ada + My_Num : Integer := 10; + pragma Export (C, My_Num, "num_from_Ada"); + + -- Declare an Ada function spec for Get_Num, then use + -- C function get_num for the implementation. + function Get_Num return Integer; + pragma Import (C, Get_Num, "get_num"); + + -- Declare an Ada procedure spec for Print_Num, then use + -- C function print_num for the implementation. + procedure Print_Num (Num : Integer); + pragma Import (C, Print_Num, "print_num"); + +begin + Print_Num (Get_Num); +end My_Main; +@end smallexample + +@enumerate +@item +To build this example, first compile the foreign language files to +generate object files: +@smallexample +^gcc -c file1.c^gcc -c FILE1.C^ +^gcc -c file2.c^gcc -c FILE2.C^ +@end smallexample + +@item +Then, compile the Ada units to produce a set of object files and ALI +files: +@smallexample +gnatmake ^-c^/ACTIONS=COMPILE^ my_main.adb +@end smallexample + +@item +Run the Ada binder on the Ada main program: +@smallexample +gnatbind my_main.ali +@end smallexample + +@item +Link the Ada main program, the Ada objects and the other language +objects: +@smallexample +gnatlink my_main.ali file1.o file2.o +@end smallexample +@end enumerate + +The last three steps can be grouped in a single command: +@smallexample +gnatmake my_main.adb -largs file1.o file2.o +@end smallexample + +@cindex Binder output file +@noindent +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 (@pxref{Binding with Non-Ada Main Programs}). +Calls to the initialization and finalization routines must be inserted +in the main program, or some other appropriate point in the code. The +call to initialize the Ada units must occur before the first Ada +subprogram is called, and the call to finalize the Ada units must occur +after the last Ada subprogram returns. The binder will place the +initialization and finalization subprograms into the +@file{b~@var{xxx}.adb} file where they can be accessed by your C +sources. To illustrate, we have the following example: + +@smallexample +/* main.c */ +extern void adainit (void); +extern void adafinal (void); +extern int add (int, int); +extern int sub (int, int); + +int main (int argc, char *argv[]) +@{ + int a = 21, b = 7; + + adainit(); + + /* Should print "21 + 7 = 28" */ + printf ("%d + %d = %d\n", a, b, add (a, b)); + /* Should print "21 - 7 = 14" */ + printf ("%d - %d = %d\n", a, b, sub (a, b)); + + adafinal(); +@} +@end smallexample + +@smallexample @c ada +-- unit1.ads +package Unit1 is + function Add (A, B : Integer) return Integer; + pragma Export (C, Add, "add"); +end Unit1; + +-- unit1.adb +package body Unit1 is + function Add (A, B : Integer) return Integer is + begin + return A + B; + end Add; +end Unit1; + +-- unit2.ads +package Unit2 is + function Sub (A, B : Integer) return Integer; + pragma Export (C, Sub, "sub"); +end Unit2; + +-- unit2.adb +package body Unit2 is + function Sub (A, B : Integer) return Integer is + begin + return A - B; + end Sub; +end Unit2; +@end smallexample + +@enumerate +@item +The build procedure for this application is similar to the last +example's. First, compile the foreign language files to generate object +files: +@smallexample +^gcc -c main.c^gcc -c main.c^ +@end smallexample + +@item +Next, compile the Ada units to produce a set of object files and ALI +files: +@smallexample +gnatmake ^-c^/ACTIONS=COMPILE^ unit1.adb +gnatmake ^-c^/ACTIONS=COMPILE^ unit2.adb +@end smallexample + +@item +Run the Ada binder on every generated ALI file. Make sure to use the +@option{-n} option to specify a foreign main program: +@smallexample +gnatbind ^-n^/NOMAIN^ unit1.ali unit2.ali +@end smallexample + +@item +Link the Ada main program, the Ada objects and the foreign language +objects. You need only list the last ALI file here: +@smallexample +gnatlink unit2.ali main.o -o exec_file +@end smallexample + +This procedure yields a binary executable called @file{exec_file}. +@end enumerate + +@noindent +Depending on the circumstances (for example when your non-Ada main object +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 +@option{^-nostartfiles^/NOSTART_FILES^} switch to @command{gnatlink}. + +@node Calling Conventions +@subsection Calling Conventions +@cindex Foreign Languages +@cindex Calling Conventions +GNAT follows standard calling sequence conventions and will thus interface +to any other language that also follows these conventions. The following +Convention identifiers are recognized by GNAT: + +@table @code +@cindex Interfacing to Ada +@cindex Other Ada compilers +@cindex Convention Ada +@item Ada +This indicates that the standard Ada calling sequence will be +used and all Ada data items may be passed without any limitations in the +case where GNAT is used to generate both the caller and callee. It is also +possible to mix GNAT generated code and code generated by another Ada +compiler. In this case, the data types should be restricted to simple +cases, including primitive types. Whether complex data types can be passed +depends on the situation. Probably it is safe to pass simple arrays, such +as arrays of integers or floats. Records may or may not work, depending +on whether both compilers lay them out identically. Complex structures +involving variant records, access parameters, tasks, or protected types, +are unlikely to be able to be passed. + +Note that in the case of GNAT running +on a platform that supports HP Ada 83, a higher degree of compatibility +can be guaranteed, and in particular records are layed out in an identical +manner in the two compilers. Note also that if output from two different +compilers is mixed, the program is responsible for dealing with elaboration +issues. Probably the safest approach is to write the main program in the +version of Ada other than GNAT, so that it takes care of its own elaboration +requirements, and then call the GNAT-generated adainit procedure to ensure +elaboration of the GNAT components. Consult the documentation of the other +Ada compiler for further details on elaboration. + +However, it is not possible to mix the tasking run time of GNAT and +HP Ada 83, All the tasking operations must either be entirely within +GNAT compiled sections of the program, or entirely within HP Ada 83 +compiled sections of the program. + +@cindex Interfacing to Assembly +@cindex Convention Assembler +@item Assembler +Specifies assembler as the convention. In practice this has the +same effect as convention Ada (but is not equivalent in the sense of being +considered the same convention). + +@cindex Convention Asm +@findex Asm +@item Asm +Equivalent to Assembler. + +@cindex Interfacing to COBOL +@cindex Convention COBOL +@findex COBOL +@item COBOL +Data will be passed according to the conventions described +in section B.4 of the Ada Reference Manual. + +@findex C +@cindex Interfacing to C +@cindex Convention C +@item C +Data will be passed according to the conventions described +in section B.3 of the Ada Reference Manual. + +A note on interfacing to a C ``varargs'' function: +@findex C varargs function +@cindex Interfacing to C varargs function +@cindex varargs function interfaces + +@itemize @bullet +@item +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 @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}. + +@item +It may work on some platforms to directly interface to +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 @code{varargs} C function with +the same two arguments. +@end itemize + +@cindex Convention Default +@findex Default +@item Default +Equivalent to C. + +@cindex Convention External +@findex External +@item External +Equivalent to C. + +@ifclear vms +@findex C++ +@cindex Interfacing to C++ +@cindex Convention C++ +@item C_Plus_Plus (or CPP) +This stands for C++. For most purposes this is identical to C. +See the separate description of the specialized GNAT pragmas relating to +C++ interfacing for further details. +@end ifclear + +@findex Fortran +@cindex Interfacing to Fortran +@cindex Convention Fortran +@item Fortran +Data will be passed according to the conventions described +in section B.5 of the Ada Reference Manual. + +@item Intrinsic +This applies to an intrinsic operation, as defined in the Ada +Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram, +this means that the body of the subprogram is provided by the compiler itself, +usually by means of an efficient code sequence, and that the user does not +supply an explicit body for it. In an application program, the pragma may +be applied to the following sets of names: + +@itemize @bullet +@item +Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, +Shift_Right_Arithmetic. The corresponding subprogram declaration must have +two formal parameters. The +first one must be a signed integer type or a modular type with a binary +modulus, and the second parameter must be of type Natural. +The return type must be the same as the type of the first argument. The size +of this type can only be 8, 16, 32, or 64. + +@item +Binary arithmetic operators: ``+'', ``-'', ``*'', ``/'' +The corresponding operator declaration must have parameters and result type +that have the same root numeric type (for example, all three are long_float +types). This simplifies the definition of operations that use type checking +to perform dimensional checks: + +@smallexample @c ada +type Distance is new Long_Float; +type Time is new Long_Float; +type Velocity is new Long_Float; +function "/" (D : Distance; T : Time) + return Velocity; +pragma Import (Intrinsic, "/"); +@end smallexample + +@noindent +This common idiom is often programmed with a generic definition and an +explicit body. The pragma makes it simpler to introduce such declarations. +It incurs no overhead in compilation time or code size, because it is +implemented as a single machine instruction. + +@item +General subprogram entities, to bind an Ada subprogram declaration to +a compiler builtin by name with back-ends where such interfaces are +available. A typical example is the set of ``__builtin'' functions +exposed by the GCC back-end, as in the following example: + +@smallexample @c ada + function builtin_sqrt (F : Float) return Float; + pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf"); +@end smallexample + +Most of the GCC builtins are accessible this way, and as for other +import conventions (e.g. C), it is the user's responsibility to ensure +that the Ada subprogram profile matches the underlying builtin +expectations. +@end itemize + +@noindent + +@ifset unw +@findex Stdcall +@cindex Convention Stdcall +@item Stdcall +This is relevant only to Windows XP/2000/NT implementations of GNAT, +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 @code{C} calling +convention on non-Windows platforms. + +@findex DLL +@cindex Convention DLL +@item DLL +This is equivalent to @code{Stdcall}. + +@findex Win32 +@cindex Convention Win32 +@item Win32 +This is equivalent to @code{Stdcall}. +@end ifset + +@findex Stubbed +@cindex Convention Stubbed +@item Stubbed +This is a special convention that indicates that the compiler +should provide a stub body that raises @code{Program_Error}. +@end table + +@noindent +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 +pragma: + +@smallexample @c ada +pragma Convention_Identifier (Fortran77, Fortran); +@end smallexample + +@noindent +And from now on the identifier Fortran77 may be used as a convention +identifier (for example in an @code{Import} pragma) with the same +meaning as Fortran. + +@ifclear vms +@node Building Mixed Ada & C++ Programs +@section Building Mixed Ada and C++ Programs + +@noindent +A programmer inexperienced with mixed-language development may find that +building an application containing both Ada and C++ code can be a +challenge. This section gives a few +hints that should make this task easier. The first section addresses +the differences between interfacing with C and interfacing with C++. +The second section +looks into the delicate problem of linking the complete application from +its Ada and C++ parts. The last section gives some hints on how the GNAT +run-time library can be adapted in order to allow inter-language dispatching +with a new C++ compiler. + +@menu +* Interfacing to C++:: +* Linking a Mixed C++ & Ada Program:: +* A Simple Example:: +* Interfacing with C++ constructors:: +* Interfacing with C++ at the Class Level:: +@end menu + +@node Interfacing to C++ +@subsection Interfacing to C++ + +@noindent +GNAT supports interfacing with the G++ compiler (or any C++ compiler +generating code that is compatible with the G++ Application Binary +Interface ---see http://www.codesourcery.com/archives/cxx-abi). + +@noindent +Interfacing can be done at 3 levels: simple data, subprograms, and +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{Generating Ada Bindings for C and C++ headers}). +This problem can also be addressed manually in two ways: + +@itemize @bullet +@item +by modifying the C++ code in order to force a C convention using +the @code{extern "C"} syntax. + +@item +by figuring out the mangled name (using e.g. @command{nm}) and using it as the +Link_Name argument of the pragma import. +@end itemize + +@noindent +Interfacing at the class level can be achieved by using the GNAT specific +pragmas such as @code{CPP_Constructor}. @xref{Interfacing to C++,,, +gnat_rm, GNAT Reference Manual}, for additional information. + +@node Linking a Mixed C++ & Ada Program +@subsection Linking a Mixed C++ & Ada Program + +@noindent +Usually the linker of the C++ development system must be used to link +mixed applications because most C++ systems will resolve elaboration +issues (such as calling constructors on global class instances) +transparently during the link phase. GNAT has been adapted to ease the +use of a foreign linker for the last phase. Three cases can be +considered: +@enumerate + +@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 @code{g++}. + +Note that if the C++ code uses inline functions, you will need to +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. + +@smallexample +$ g++ -c -fkeep-inline-functions file1.C +$ g++ -c -fkeep-inline-functions file2.C +$ gnatmake ada_unit -largs file1.o file2.o --LINK=g++ +@end smallexample + +@item +Using GNAT and G++ from two different GCC installations: If both +compilers are on the @env{PATH}, the previous method may be used. It is +important to note that environment variables such as +@env{C_INCLUDE_PATH}, @env{GCC_EXEC_PREFIX}, @env{BINUTILS_ROOT}, and +@env{GCC_ROOT} will affect both compilers +at the same time and may make one of the two compilers operate +improperly if set during invocation of the wrong compiler. It is also +very important that the linker uses the proper @file{libgcc.a} GCC +library -- that is, the one from the C++ compiler installation. The +implicit link command as suggested in the @command{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: +@smallexample +$ gnatbind ada_unit +$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++ +@end smallexample +If there is a problem due to interfering environment variables, it can +be worked around by using an intermediate script. The following example +shows the proper script to use when GNAT has not been installed at its +default location and g++ has been installed at its default location: + +@smallexample +$ cat ./my_script +#!/bin/sh +unset BINUTILS_ROOT +unset GCC_ROOT +c++ $* +$ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script +@end smallexample + +@item +Using a non-GNU C++ compiler: The commands previously described can be +used to insure that the C++ linker is used. Nonetheless, you need to add +a few more parameters to the link command line, depending on the exception +mechanism used. + +If the @code{setjmp/longjmp} exception mechanism is used, only the paths +to the libgcc libraries are required: + +@smallexample +$ cat ./my_script +#!/bin/sh +CC $* `gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` +$ gnatlink ada_unit file1.o file2.o --LINK=./my_script +@end smallexample + +Where CC is the name of the non-GNU C++ compiler. + +If the @code{zero cost} exception mechanism is used, and the platform +supports automatic registration of exception tables (e.g.@: Solaris or IRIX), +paths to more objects are required: + +@smallexample +$ cat ./my_script +#!/bin/sh +CC `gcc -print-file-name=crtbegin.o` $* \ +`gcc -print-file-name=libgcc.a` `gcc -print-file-name=libgcc_eh.a` \ +`gcc -print-file-name=crtend.o` +$ gnatlink ada_unit file1.o file2.o --LINK=./my_script +@end smallexample + +If the @code{zero cost} exception mechanism is used, and the platform +doesn't support automatic registration of exception tables (e.g.@: HP-UX, +Tru64 or AIX), the simple approach described above will not work and +a pre-linking phase using GNAT will be necessary. + +@end enumerate + +Another alternative is to use the @command{gprbuild} multi-language builder +which has a large knowledge base and knows how to link Ada and C++ code +together automatically in most cases. + +@node A Simple Example +@subsection A Simple Example +@noindent +The following example, provided as part of the GNAT examples, shows how +to achieve procedural interfacing between Ada and C++ in both +directions. The C++ class A has two methods. The first method is exported +to Ada by the means of an extern C wrapper function. The second method +calls an Ada subprogram. On the Ada side, The C++ calls are modelled by +a limited record with a layout comparable to the C++ class. The Ada +subprogram, in turn, calls the C++ method. So, starting from the C++ +main program, the process passes back and forth between the two +languages. + +@noindent +Here are the compilation commands: +@smallexample +$ gnatmake -c simple_cpp_interface +$ g++ -c cpp_main.C +$ g++ -c ex7.C +$ gnatbind -n simple_cpp_interface +$ gnatlink simple_cpp_interface -o cpp_main --LINK=g++ + -lstdc++ ex7.o cpp_main.o +@end smallexample + +@noindent +Here are the corresponding sources: +@smallexample + +//cpp_main.C + +#include "ex7.h" + +extern "C" @{ + void adainit (void); + void adafinal (void); + void method1 (A *t); +@} + +void method1 (A *t) +@{ + t->method1 (); +@} + +int main () +@{ + A obj; + adainit (); + obj.method2 (3030); + adafinal (); +@} + +//ex7.h + +class Origin @{ + public: + int o_value; +@}; +class A : public Origin @{ + public: + void method1 (void); + void method2 (int v); + A(); + int a_value; +@}; + +//ex7.C + +#include "ex7.h" +#include + +extern "C" @{ void ada_method2 (A *t, int v);@} + +void A::method1 (void) +@{ + a_value = 2020; + printf ("in A::method1, a_value = %d \n",a_value); + +@} + +void A::method2 (int v) +@{ + ada_method2 (this, v); + printf ("in A::method2, a_value = %d \n",a_value); + +@} + +A::A(void) +@{ + a_value = 1010; + printf ("in A::A, a_value = %d \n",a_value); +@} +@end smallexample + +@smallexample @c ada +-- Ada sources +package body Simple_Cpp_Interface is + + procedure Ada_Method2 (This : in out A; V : Integer) is + begin + Method1 (This); + This.A_Value := V; + end Ada_Method2; + +end Simple_Cpp_Interface; + +with System; +package Simple_Cpp_Interface is + type A is limited + record + Vptr : System.Address; + O_Value : Integer; + A_Value : Integer; + end record; + pragma Convention (C, A); + + procedure Method1 (This : in out A); + pragma Import (C, Method1); + + procedure Ada_Method2 (This : in out A; V : Integer); + pragma Export (C, Ada_Method2); + +end Simple_Cpp_Interface; +@end smallexample + +@node Interfacing with C++ constructors +@subsection Interfacing with C++ constructors +@noindent + +In order to interface with C++ constructors GNAT provides the +@code{pragma CPP_Constructor} (@xref{Interfacing to C++,,, +gnat_rm, GNAT Reference Manual}, for additional information). +In this section we present some common uses of C++ constructors +in mixed-languages programs in GNAT. + +Let us assume that we need to interface with the following +C++ class: + +@smallexample +@b{class} Root @{ +@b{public}: + int a_value; + int b_value; + @b{virtual} int Get_Value (); + Root(); // Default constructor + Root(int v); // 1st non-default constructor + Root(int v, int w); // 2nd non-default constructor +@}; +@end smallexample + +For this purpose we can write the following package spec (further +information on how to build this spec is available in +@ref{Interfacing with C++ at the Class Level} and +@ref{Generating Ada Bindings for C and C++ headers}). + +@smallexample @c ada +with Interfaces.C; use Interfaces.C; +package Pkg_Root is + type Root is tagged limited record + A_Value : int; + B_Value : int; + end record; + pragma Import (CPP, Root); + + function Get_Value (Obj : Root) return int; + pragma Import (CPP, Get_Value); + + function Constructor return Root; + pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ev"); + + function Constructor (v : Integer) return Root; + pragma Cpp_Constructor (Constructor, "_ZN4RootC1Ei"); + + function Constructor (v, w : Integer) return Root; + pragma Cpp_Constructor (Constructor, "_ZN4RootC1Eii"); +end Pkg_Root; +@end smallexample + +On the Ada side the constructor is represented by a function (whose +name is arbitrary) that returns the classwide type corresponding to +the imported C++ class. Although the constructor is described as a +function, it is typically a procedure with an extra implicit argument +(the object being initialized) at the implementation level. GNAT +issues the appropriate call, whatever it is, to get the object +properly initialized. + +Constructors can only appear in the following contexts: + +@itemize @bullet +@item +On the right side of an initialization of an object of type @var{T}. +@item +On the right side of an initialization of a record component of type @var{T}. +@item +In an Ada 2005 limited aggregate. +@item +In an Ada 2005 nested limited aggregate. +@item +In an Ada 2005 limited aggregate that initializes an object built in +place by an extended return statement. +@end itemize + +@noindent +In a declaration of an object whose type is a class imported from C++, +either the default C++ constructor is implicitly called by GNAT, or +else the required C++ constructor must be explicitly called in the +expression that initializes the object. For example: + +@smallexample @c ada + Obj1 : Root; + Obj2 : Root := Constructor; + Obj3 : Root := Constructor (v => 10); + Obj4 : Root := Constructor (30, 40); +@end smallexample + +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). @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: + +@smallexample @c ada + type DT is new Root with record + C_Value : Natural := 2009; + end record; +@end smallexample + +In this case the components DT inherited from the C++ side must be +initialized by a C++ constructor, and the additional Ada components +of type DT are initialized by GNAT. The initialization of such an +object is done either by default, or by means of a function returning +an aggregate of type DT, or by means of an extension aggregate. + +@smallexample @c ada + Obj5 : DT; + Obj6 : DT := Function_Returning_DT (50); + Obj7 : DT := (Constructor (30,40) with C_Value => 50); +@end smallexample + +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, +@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. + +Let us now consider a record that has components whose type is imported +from C++. For example: + +@smallexample @c ada + type Rec1 is limited record + Data1 : Root := Constructor (10); + Value : Natural := 1000; + end record; + + type Rec2 (D : Integer := 20) is limited record + Rec : Rec1; + Data2 : Root := Constructor (D, 30); + end record; +@end smallexample + +The initialization of an object of type @code{Rec2} will call the +non-default C++ constructors specified for the imported components. +For example: + +@smallexample @c ada + Obj8 : Rec2 (40); +@end smallexample + +Using Ada 2005 we can use limited aggregates to initialize an object +invoking C++ constructors that differ from those specified in the type +declarations. For example: + +@smallexample @c ada + Obj9 : Rec2 := (Rec => (Data1 => Constructor (15, 16), + others => <>), + others => <>); +@end smallexample + +The above declaration uses an Ada 2005 limited aggregate to +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 @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 @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: + +@smallexample @c ada + function Constructor (V : Integer) return Rec2 is + begin + return Obj : Rec2 := (Rec => (Data1 => Constructor (V, 20), + others => <>), + others => <>) do + -- Further actions required for construction of + -- objects of type Rec2 + ... + end record; + end Constructor; +@end smallexample + +In this example the extended return statement construct is used to +build in place the returned object whose components are initialized +by means of a limited aggregate. Any further action associated with +the constructor can be placed inside the construct. + +@node Interfacing with C++ at the Class Level +@subsection Interfacing with C++ at the Class Level +@noindent +In this section we demonstrate the GNAT features for interfacing with +C++ by means of an example making use of Ada 2005 abstract interface +types. This example consists of a classification of animals; classes +have been used to model our main classification of animals, and +interfaces provide support for the management of secondary +classifications. We first demonstrate a case in which the types and +constructors are defined on the C++ side and imported from the Ada +side, and latter the reverse case. + +The root of our derivation will be the @code{Animal} class, with a +single private attribute (the @code{Age} of the animal) and two public +primitives to set and get the value of this attribute. + +@smallexample +@b{class} Animal @{ + @b{public}: + @b{virtual} void Set_Age (int New_Age); + @b{virtual} int Age (); + @b{private}: + int Age_Count; +@}; +@end smallexample + +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 @code{Carnivore} +and @code{Domestic} animals: + +@smallexample +@b{class} Carnivore @{ +@b{public}: + @b{virtual} int Number_Of_Teeth () = 0; +@}; + +@b{class} Domestic @{ +@b{public}: + @b{virtual void} Set_Owner (char* Name) = 0; +@}; +@end smallexample + +Using these declarations, we can now say that a @code{Dog} is an animal that is +both Carnivore and Domestic, that is: + +@smallexample +@b{class} Dog : Animal, Carnivore, Domestic @{ + @b{public}: + @b{virtual} int Number_Of_Teeth (); + @b{virtual} void Set_Owner (char* Name); + + Dog(); // Constructor + @b{private}: + int Tooth_Count; + char *Owner; +@}; +@end smallexample + +In the following examples we will assume that the previous declarations are +located in a file named @code{animals.h}. The following package demonstrates +how to import these C++ declarations from the Ada side: + +@smallexample @c ada +with Interfaces.C.Strings; use Interfaces.C.Strings; +package Animals is + type Carnivore is interface; + pragma Convention (C_Plus_Plus, Carnivore); + function Number_Of_Teeth (X : Carnivore) + return Natural is abstract; + + type Domestic is interface; + pragma Convention (C_Plus_Plus, Set_Owner); + procedure Set_Owner + (X : in out Domestic; + Name : Chars_Ptr) is abstract; + + type Animal is tagged record + Age : Natural := 0; + end record; + pragma Import (C_Plus_Plus, Animal); + + procedure Set_Age (X : in out Animal; Age : Integer); + pragma Import (C_Plus_Plus, Set_Age); + + function Age (X : Animal) return Integer; + pragma Import (C_Plus_Plus, Age); + + type Dog is new Animal and Carnivore and Domestic with record + Tooth_Count : Natural; + Owner : String (1 .. 30); + end record; + pragma Import (C_Plus_Plus, Dog); + + function Number_Of_Teeth (A : Dog) return Integer; + pragma Import (C_Plus_Plus, Number_Of_Teeth); + + procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); + pragma Import (C_Plus_Plus, Set_Owner); + + function New_Dog return Dog; + pragma CPP_Constructor (New_Dog); + pragma Import (CPP, New_Dog, "_ZN3DogC2Ev"); +end Animals; +@end smallexample + +Thanks to the compatibility between GNAT run-time structures and the C++ ABI, +interfacing with these C++ classes is easy. The only requirement is that all +the primitives and components must be declared exactly in the same order in +the two languages. + +Regarding the abstract interfaces, we must indicate to the GNAT compiler by +means of a @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 @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 +which Ada would otherwise expect. + +As the reader can see there is no need to indicate the C++ mangled names +associated with each subprogram because it is assumed that all the calls to +these primitives will be dispatching calls. The only exception is the +constructor, which must be registered with the compiler by means of +@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 +and dispatch calls to the corresponding subprograms on the C++ side. We can +also extend the tagged type Dog with further fields and primitives, and +override some of its C++ primitives on the Ada side. For example, here we have +a type derivation defined on the Ada side that inherits all the dispatching +primitives of the ancestor from the C++ side. + +@smallexample +@b{with} Animals; @b{use} Animals; +@b{package} Vaccinated_Animals @b{is} + @b{type} Vaccinated_Dog @b{is new} Dog @b{with null record}; + @b{function} Vaccination_Expired (A : Vaccinated_Dog) @b{return} Boolean; +@b{end} Vaccinated_Animals; +@end smallexample + +It is important to note that, because of the ABI compatibility, the programmer +does not need to add any further information to indicate either the object +layout or the dispatch table entry associated with each dispatching operation. + +Now let us define all the types and constructors on the Ada side and export +them to C++, using the same hierarchy of our previous example: + +@smallexample @c ada +with Interfaces.C.Strings; +use Interfaces.C.Strings; +package Animals is + type Carnivore is interface; + pragma Convention (C_Plus_Plus, Carnivore); + function Number_Of_Teeth (X : Carnivore) + return Natural is abstract; + + type Domestic is interface; + pragma Convention (C_Plus_Plus, Set_Owner); + procedure Set_Owner + (X : in out Domestic; + Name : Chars_Ptr) is abstract; + + type Animal is tagged record + Age : Natural := 0; + end record; + pragma Convention (C_Plus_Plus, Animal); + + procedure Set_Age (X : in out Animal; Age : Integer); + pragma Export (C_Plus_Plus, Set_Age); + + function Age (X : Animal) return Integer; + pragma Export (C_Plus_Plus, Age); + + type Dog is new Animal and Carnivore and Domestic with record + Tooth_Count : Natural; + Owner : String (1 .. 30); + end record; + pragma Convention (C_Plus_Plus, Dog); + + function Number_Of_Teeth (A : Dog) return Integer; + pragma Export (C_Plus_Plus, Number_Of_Teeth); + + procedure Set_Owner (A : in out Dog; Name : Chars_Ptr); + pragma Export (C_Plus_Plus, Set_Owner); + + function New_Dog return Dog'Class; + pragma Export (C_Plus_Plus, New_Dog); +end Animals; +@end smallexample + +Compared with our previous example the only difference is 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 @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: + +@smallexample +@b{#include} "animals.h" +@b{#include} +@b{using namespace} std; + +void Check_Carnivore (Carnivore *obj) @{@dots{}@} +void Check_Domestic (Domestic *obj) @{@dots{}@} +void Check_Animal (Animal *obj) @{@dots{}@} +void Check_Dog (Dog *obj) @{@dots{}@} + +@b{extern} "C" @{ + void adainit (void); + void adafinal (void); + Dog* new_dog (); +@} + +void test () +@{ + Dog *obj = new_dog(); // Ada constructor + Check_Carnivore (obj); // Check secondary DT + Check_Domestic (obj); // Check secondary DT + Check_Animal (obj); // Check primary DT + Check_Dog (obj); // Check primary DT +@} + +int main () +@{ + adainit (); test(); adafinal (); + return 0; +@} +@end smallexample + +@node Comparison between GNAT and C/C++ Compilation Models +@section Comparison between GNAT and C/C++ Compilation Models + +@noindent +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 @code{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 +to check them for semantic and syntactic accuracy. This is not always +possible with C headers because they are fragments of programs that have +less specific syntactic or semantic rules. + +The other major difference is the requirement for running the binder, +which performs two important functions. First, it checks for +consistency. In C or C++, the only defense against assembling +inconsistent programs lies outside the compiler, in a makefile, for +example. The binder satisfies the Ada requirement that it be impossible +to construct an inconsistent program when the compiler is used in normal +mode. + +@cindex Elaboration order control +The other important function of the binder is to deal with elaboration +issues. There are also elaboration issues in C++ that are handled +automatically. This automatic handling has the advantage of being +simpler to use, but the C++ programmer has no control over elaboration. +Where @code{gnatbind} might complain there was no valid order of +elaboration, a C++ compiler would simply construct a program that +malfunctioned at run time. +@end ifclear + +@node Comparison between GNAT and Conventional Ada Library Models +@section Comparison between GNAT and Conventional Ada Library Models + +@noindent +This section is intended for Ada programmers who have +used an Ada compiler implementing the traditional Ada library +model, as described in the Ada Reference Manual. + +@cindex GNAT library +In GNAT, there is no ``library'' in the normal sense. Instead, the set of +source files themselves acts as the library. Compiling Ada programs does +not generate any centralized information, but rather an object file and +a ALI file, which are of interest only to the binder and linker. +In a traditional system, the compiler reads information not only from +the source file being compiled, but also from the centralized library. +This means that the effect of a compilation depends on what has been +previously compiled. In particular: + +@itemize @bullet +@item +When a unit is @code{with}'ed, the unit seen by the compiler corresponds +to the version of the unit most recently compiled into the library. + +@item +Inlining is effective only if the necessary body has already been +compiled into the library. + +@item +Compiling a unit may obsolete other units in the library. +@end itemize + +@noindent +In GNAT, compiling one unit never affects the compilation of any other +units because the compiler reads only source files. Only changes to source +files can affect the results of a compilation. In particular: + +@itemize @bullet +@item +When a unit is @code{with}'ed, the unit seen by the compiler corresponds +to the source version of the unit that is currently accessible to the +compiler. + +@item +@cindex Inlining +Inlining requires the appropriate source files for the package or +subprogram bodies to be available to the compiler. Inlining is always +effective, independent of the order in which units are complied. + +@item +Compiling a unit never affects any other compilations. The editing of +sources may cause previous compilations to be out of date if they +depended on the source file being modified. +@end itemize + +@noindent +The most important result of these differences is that order of compilation +is never significant in GNAT. There is no situation in which one is +required to do one compilation before another. What shows up as order of +compilation requirements in the traditional Ada library becomes, in +GNAT, simple source dependencies; in other words, there is only a set +of rules saying what source files must be present when a file is +compiled. + +@ifset vms +@node Placement of temporary files +@section Placement of temporary files +@cindex Temporary files (user control over placement) + +@noindent +GNAT creates temporary files in the directory designated by the environment +variable @env{TMPDIR}. +(See the HP @emph{C RTL Reference Manual} on the function @code{getenv()} +for detailed information on how environment variables are resolved. +For most users the easiest way to make use of this feature is to simply +define @env{TMPDIR} as a job level logical name). +For example, if you wish to use a Ramdisk (assuming DECRAM is installed) +for compiler temporary files, then you can include something like the +following command in your @file{LOGIN.COM} file: + +@smallexample +$ define/job TMPDIR "/disk$scratchram/000000/temp/" +@end smallexample + +@noindent +If @env{TMPDIR} is not defined, then GNAT uses the directory designated by +@env{TMP}; if @env{TMP} is not defined, then GNAT uses the directory +designated by @env{TEMP}. +If none of these environment variables are defined then GNAT uses the +directory designated by the logical name @code{SYS$SCRATCH:} +(by default the user's home directory). If all else fails +GNAT uses the current directory for temporary files. +@end ifset + +@c ************************* +@node Compiling Using gcc +@chapter Compiling Using @command{gcc} + +@noindent +This chapter discusses how to compile Ada programs using the @command{gcc} +command. It also describes the set of switches +that can be used to control the behavior of the compiler. +@menu +* Compiling Programs:: +* Switches for gcc:: +* Search Paths and the Run-Time Library (RTL):: +* Order of Compilation Issues:: +* Examples:: +@end menu + +@node Compiling Programs +@section Compiling Programs + +@noindent +The first step in creating an executable program is to compile the units +of the program using the @command{gcc} command. You must compile the +following files: + +@itemize @bullet +@item +the body file (@file{.adb}) for a library level subprogram or generic +subprogram + +@item +the spec file (@file{.ads}) for a library level package or generic +package that has no body + +@item +the body file (@file{.adb}) for a library level package +or generic package that has a body + +@end itemize + +@noindent +You need @emph{not} compile the following files + +@itemize @bullet + +@item +the spec of a library unit which has a body + +@item +subunits +@end itemize + +@noindent +because they are compiled as part of compiling related units. GNAT +package specs +when the corresponding body is compiled, and subunits when the parent is +compiled. + +@cindex cannot generate code +If you attempt to compile any of these files, you will get one of the +following error messages (where @var{fff} is the name of the file you +compiled): + +@smallexample +cannot generate code for file @var{fff} (package spec) +to check package spec, use -gnatc + +cannot generate code for file @var{fff} (missing subunits) +to check parent unit, use -gnatc + +cannot generate code for file @var{fff} (subprogram spec) +to check subprogram spec, use -gnatc + +cannot generate code for file @var{fff} (subunit) +to check subunit, use -gnatc +@end smallexample + +@noindent +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 @option{-gnatc} switch. + +The basic command for compiling a file containing an Ada unit is + +@smallexample +@c $ gcc -c @ovar{switches} @file{file name} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gcc -c @r{[}@var{switches}@r{]} @file{file name} +@end smallexample + +@noindent +where @var{file name} is the name of the Ada file (usually +having an extension +@file{.ads} for a spec or @file{.adb} for a body). +@ifclear vms +You specify the +@option{-c} switch to tell @command{gcc} to compile, but not link, the file. +@end ifclear +The result of a successful compilation is an object file, which has the +same name as the source file but an extension of @file{.o} and an Ada +Library Information (ALI) file, which also has the same name as the +source file, but with @file{.ali} as the extension. GNAT creates these +two output files in the current directory, but you may specify a source +file in any directory using an absolute or relative path specification +containing the directory information. + +@findex gnat1 +@command{gcc} is actually a driver program that looks at the extensions of +the file arguments and loads the appropriate compiler. For example, the +GNU C compiler is @file{cc1}, and the Ada compiler is @file{gnat1}. +These programs are in directories known to the driver program (in some +configurations via environment variables you set), but need not be in +your path. The @command{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 @command{gcc} +command. This causes @command{gcc} to call the appropriate compiler for +each file. For example, the following command lists three separate +files to be compiled: + +@smallexample +$ gcc -c x.adb y.adb z.c +@end smallexample + +@noindent +calls @code{gnat1} (the Ada compiler) twice to compile @file{x.adb} and +@file{y.adb}, and @code{cc1} (the C compiler) once to compile @file{z.c}. +The compiler generates three object files @file{x.o}, @file{y.o} and +@file{z.o} and the two ALI files @file{x.ali} and @file{y.ali} from the +Ada compilations. Any switches apply to all the files ^listed,^listed.^ +@ifclear vms +except for +@option{-gnat@var{x}} switches, which apply only to Ada compilations. +@end ifclear + +@node Switches for gcc +@section Switches for @command{gcc} + +@noindent +The @command{gcc} command accepts switches that control the +compilation process. These switches are fully described in this section. +First we briefly list all the switches, in alphabetical order, then we +describe the switches in more detail in functionally grouped sections. + +More switches exist for GCC than those documented here, especially +for specific targets. However, their use is not recommended as +they may change code generation in ways that are incompatible with +the Ada run-time library, or can cause inconsistencies between +compilation units. + +@menu +* Output and Error Message Control:: +* Warning Message Control:: +* Debugging and Assertion Control:: +* Validity Checking:: +* Style Checking:: +* Run-Time Checks:: +* Using gcc for Syntax Checking:: +* Using gcc for Semantic Checking:: +* Compiling Different Versions of Ada:: +* Character Set Control:: +* File Naming Control:: +* Subprogram Inlining Control:: +* Auxiliary Output Control:: +* Debugging Control:: +* Exception Handling Control:: +* Units to Sources Mapping Files:: +* Integrated Preprocessing:: +* Code Generation Control:: +@ifset vms +* Return Codes:: +@end ifset +@end menu + +@table @option +@c !sort! +@ifclear vms +@cindex @option{-b} (@command{gcc}) +@item -b @var{target} +Compile your program to run on @var{target}, which is the name of a +system configuration. You must have a GNAT cross-compiler built if +@var{target} is not the same as your host system. + +@item -B@var{dir} +@cindex @option{-B} (@command{gcc}) +Load compiler executables (for example, @code{gnat1}, the Ada compiler) +from @var{dir} instead of the default location. Only use this switch +when multiple versions of the GNAT compiler are available. +@xref{Directory Options,, Options for Directory Search, gcc, Using the +GNU Compiler Collection (GCC)}, for further details. You would normally +use the @option{-b} or @option{-V} switch instead. + +@item -c +@cindex @option{-c} (@command{gcc}) +Compile. Always use this switch when compiling Ada programs. + +Note: for some other languages when using @command{gcc}, notably in +the case of C and C++, it is possible to use +use @command{gcc} without a @option{-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 @command{gcc} cannot be used to run the GNAT binder. +@end ifclear + +@item -fno-inline +@cindex @option{-fno-inline} (@command{gcc}) +Suppresses all back-end inlining, even if other optimization or inlining +switches are set. +This includes suppression of inlining that results +from the use of the pragma @code{Inline_Always}. +Any occurrences of pragma @code{Inline} or @code{Inline_Always} +are ignored, and @option{-gnatn} and @option{-gnatN} have no +effect if this switch is present. + +@item -fno-inline-functions +@cindex @option{-fno-inline-functions} (@command{gcc}) +Suppresses automatic inlining of subprograms, which is enabled +if @option{-O3} is used. + +@item -fno-inline-small-functions +@cindex @option{-fno-inline-small-functions} (@command{gcc}) +Suppresses automatic inlining of small subprograms, which is enabled +if @option{-O2} is used. + +@item -fno-inline-functions-called-once +@cindex @option{-fno-inline-functions-called-once} (@command{gcc}) +Suppresses inlining of subprograms local to the unit and called once +from within it, which is enabled if @option{-O1} is used. + +@item -fno-ivopts +@cindex @option{-fno-ivopts} (@command{gcc}) +Suppresses high-level loop induction variable optimizations, which are +enabled if @option{-O1} is used. These optimizations are generally +profitable but, for some specific cases of loops with numerous uses +of the iteration variable that follow a common pattern, they may end +up destroying the regularity that could be exploited at a lower level +and thus producing inferior code. + +@item -fno-strict-aliasing +@cindex @option{-fno-strict-aliasing} (@command{gcc}) +Causes the compiler to avoid assumptions regarding non-aliasing +of objects of different types. See +@ref{Optimization and Strict Aliasing} for details. + +@item -fstack-check +@cindex @option{-fstack-check} (@command{gcc}) +Activates stack checking. +See @ref{Stack Overflow Checking} for details. + +@item -fstack-usage +@cindex @option{-fstack-usage} (@command{gcc}) +Makes the compiler output stack usage information for the program, on a +per-function basis. See @ref{Static Stack Usage Analysis} for details. + +@item -fcallgraph-info@r{[}=su@r{]} +@cindex @option{-fcallgraph-info} (@command{gcc}) +Makes the compiler output callgraph information for the program, on a +per-file basis. The information is generated in the VCG format. It can +be decorated with stack-usage per-node information. + +@item ^-g^/DEBUG^ +@cindex @option{^-g^/DEBUG^} (@command{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 +@option{^-g^/DEBUG^} switch if you plan on using the debugger. + +@item -gnat83 +@cindex @option{-gnat83} (@command{gcc}) +Enforce Ada 83 restrictions. + +@item -gnat95 +@cindex @option{-gnat95} (@command{gcc}) +Enforce Ada 95 restrictions. + +@item -gnat05 +@cindex @option{-gnat05} (@command{gcc}) +Allow full Ada 2005 features. + +@item -gnat2005 +@cindex @option{-gnat2005} (@command{gcc}) +Allow full Ada 2005 features (same as @option{-gnat05}) + +@item -gnat12 +@cindex @option{-gnat12} (@command{gcc}) + +@item -gnat2012 +@cindex @option{-gnat2012} (@command{gcc}) +Allow full Ada 2012 features (same as @option{-gnat12}) + +@item -gnata +@cindex @option{-gnata} (@command{gcc}) +Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be +activated. Note that these pragmas can also be controlled using the +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}. + +@item -gnatA +@cindex @option{-gnatA} (@command{gcc}) +Avoid processing @file{gnat.adc}. If a @file{gnat.adc} file is present, +it will be ignored. + +@item -gnatb +@cindex @option{-gnatb} (@command{gcc}) +Generate brief messages to @file{stderr} even if verbose mode set. + +@item -gnatB +@cindex @option{-gnatB} (@command{gcc}) +Assume no invalid (bad) values except for 'Valid attribute use +(@pxref{Validity Checking}). + +@item -gnatc +@cindex @option{-gnatc} (@command{gcc}) +Check syntax and semantics only (no code generation attempted). + +@item -gnatC +@cindex @option{-gnatC} (@command{gcc}) +Generate CodePeer information (no code generation attempted). +This switch will generate an intermediate representation suitable for +use by CodePeer (@file{.scil} files). This switch is not compatible with +code generation (it will, among other things, disable some switches such +as -gnatn, and enable others such as -gnata). + +@item -gnatd +@cindex @option{-gnatd} (@command{gcc}) +Specify debug options for the compiler. The string of characters after +the @option{-gnatd} specify the specific debug options. The possible +characters are 0-9, a-z, A-Z, optionally preceded by a dot. See +compiler source file @file{debug.adb} for details of the implemented +debug options. Certain debug options are relevant to applications +programmers, and these are documented at appropriate points in this +users guide. + +@ifclear vms +@item -gnatD +@cindex @option{-gnatD[nn]} (@command{gcc}) +@end ifclear +@ifset vms +@item /XDEBUG /LXDEBUG=nnn +@end ifset +Create expanded source files for source level debugging. This switch +also suppress generation of cross-reference information +(see @option{-gnatx}). + +@item -gnatec=@var{path} +@cindex @option{-gnatec} (@command{gcc}) +Specify a configuration pragma file +@ifclear vms +(the equal sign is optional) +@end ifclear +(@pxref{The Configuration Pragmas Files}). + +@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=@var{value}@r{]} +@cindex @option{-gnateD} (@command{gcc}) +Defines a symbol, associated with @var{value}, for preprocessing. +(@pxref{Integrated Preprocessing}). + +@item -gnateE +@cindex @option{-gnateE} (@command{gcc}) +Generate extra information in exception messages, in particular display +extra column information and the value and range associated with index and +range check failures, and extra column information for access checks. + +@item -gnatef +@cindex @option{-gnatef} (@command{gcc}) +Display full source path name in brief error messages. + +@item -gnateG +@cindex @option{-gnateG} (@command{gcc}) +Save result of preprocessing in a text file. + +@item -gnatem=@var{path} +@cindex @option{-gnatem} (@command{gcc}) +Specify a mapping file +@ifclear vms +(the equal sign is optional) +@end ifclear +(@pxref{Units to Sources Mapping Files}). + +@item -gnatep=@var{file} +@cindex @option{-gnatep} (@command{gcc}) +Specify a preprocessing data file +@ifclear vms +(the equal sign is optional) +@end ifclear +(@pxref{Integrated Preprocessing}). + +@item -gnateP +@cindex @option{-gnateP} (@command{gcc}) +Turn categorization dependency errors into warnings. +Ada requires that units that WITH one another have compatible categories, for +example a Pure unit cannto WITH a Preelaborate unit. If this switch is used, +these errors become warnings (which can be ignored, or suppressed in the usual +manner). This can be useful in some specialized circumstances such as the +temporary use of special test software. +@item -gnateS +@cindex @option{-gnateS} (@command{gcc}) +Generate SCO (Source Coverage Obligation) information in the ALI +file. This information is used by advanced coverage tools. See +unit @file{SCOs} in the compiler sources for details in files +@file{scos.ads} and @file{scos.adb}. + +@item -gnatE +@cindex @option{-gnatE} (@command{gcc}) +Full dynamic elaboration checks. + +@item -gnatf +@cindex @option{-gnatf} (@command{gcc}) +Full errors. Multiple errors per line, all undefined references, do not +attempt to suppress cascaded errors. + +@item -gnatF +@cindex @option{-gnatF} (@command{gcc}) +Externals names are folded to all uppercase. + +@item ^-gnatg^/GNAT_INTERNAL^ +@cindex @option{^-gnatg^/GNAT_INTERNAL^} (@command{gcc}) +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 @option{^-gnatg^/GNAT_INTERNAL^} implies +@option{^-gnatwae^/WARNINGS=ALL,ERRORS^} and +@option{^-gnatyg^/STYLE_CHECKS=GNAT^} +so that all standard warnings and all standard style options are turned on. +All warnings and style messages are treated as errors. + +@ifclear vms +@item -gnatG=nn +@cindex @option{-gnatG[nn]} (@command{gcc}) +@end ifclear +@ifset vms +@item /EXPAND_SOURCE, /LEXPAND_SOURCE=nnn +@end ifset +List generated expanded code in source form. + +@item ^-gnath^/HELP^ +@cindex @option{^-gnath^/HELP^} (@command{gcc}) +Output usage information. The output is written to @file{stdout}. + +@item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c} +@cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@command{gcc}) +Identifier character set +@ifclear vms +(@var{c}=1/2/3/4/8/9/p/f/n/w). +@end ifclear +For details of the possible selections for @var{c}, +see @ref{Character Set Control}. + +@item ^-gnatI^/IGNORE_REP_CLAUSES^ +@cindex @option{^-gnatI^IGNORE_REP_CLAUSES^} (@command{gcc}) +Ignore representation clauses. When this switch is used, +representation clauses are treated as comments. This is useful +when initially porting code where you want to ignore rep clause +problems, and also for compiling foreign code (particularly +for use with ASIS). The representation clauses that are ignored +are: enumeration_representation_clause, record_representation_clause, +and attribute_definition_clause for the following attributes: +Address, Alignment, Bit_Order, Component_Size, Machine_Radix, +Object_Size, Size, Small, Stream_Size, and Value_Size. +Note that this option should be used only for compiling -- the +code is likely to malfunction at run time. + +@item -gnatjnn +@cindex @option{-gnatjnn} (@command{gcc}) +Reformat error messages to fit on nn character lines + +@item -gnatk=@var{n} +@cindex @option{-gnatk} (@command{gcc}) +Limit file names to @var{n} (1-999) characters ^(@code{k} = krunch)^^. + +@item -gnatl +@cindex @option{-gnatl} (@command{gcc}) +Output full source listing with embedded error messages. + +@item -gnatL +@cindex @option{-gnatL} (@command{gcc}) +Used in conjunction with -gnatG or -gnatD to intersperse original +source lines (as comment lines with line numbers) in the expanded +source output. + +@item -gnatm=@var{n} +@cindex @option{-gnatm} (@command{gcc}) +Limit number of detected error or warning messages to @var{n} +where @var{n} is in the range 1..999999. The default setting if +no switch is given is 9999. If the number of warnings reaches this +limit, then a message is output and further warnings are suppressed, +but the compilation is continued. If the number of error messages +reaches this limit, then a message is output and the compilation +is abandoned. The equal sign here is optional. A value of zero +means that no limit applies. + +@item -gnatn +@cindex @option{-gnatn} (@command{gcc}) +Activate inlining for subprograms for which +pragma @code{Inline} is specified. This inlining is performed +by the GCC back-end. + +@item -gnatN +@cindex @option{-gnatN} (@command{gcc}) +Activate front end inlining for subprograms for which +pragma @code{Inline} is specified. This inlining is performed +by the front end and will be visible in the +@option{-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 +@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred. +Historically front end inlining was more extensive than the gcc back end +inlining, but that is no longer the case. + +@item -gnato +@cindex @option{-gnato} (@command{gcc}) +Enable numeric overflow checking (which is not normally enabled by +default). Note that division by zero is a separate check that is not +controlled by this switch (division by zero checking is on by default). + +@item -gnatp +@cindex @option{-gnatp} (@command{gcc}) +Suppress all checks. See @ref{Run-Time Checks} for details. This switch +has no effect if cancelled by a subsequent @option{-gnat-p} switch. + +@item -gnat-p +@cindex @option{-gnat-p} (@command{gcc}) +Cancel effect of previous @option{-gnatp} switch. + +@item -gnatP +@cindex @option{-gnatP} (@command{gcc}) +Enable polling. This is required on some systems (notably Windows NT) to +obtain asynchronous abort and asynchronous transfer of control capability. +@xref{Pragma Polling,,, gnat_rm, GNAT Reference Manual}, for full +details. + +@item -gnatq +@cindex @option{-gnatq} (@command{gcc}) +Don't quit. Try semantics, even if parse errors. + +@item -gnatQ +@cindex @option{-gnatQ} (@command{gcc}) +Don't quit. Generate @file{ALI} and tree files even if illegalities. + +@item -gnatr +@cindex @option{-gnatr} (@command{gcc}) +Treat pragma Restrictions as Restriction_Warnings. + +@item ^-gnatR@r{[}0@r{/}1@r{/}2@r{/}3@r{[}s@r{]]}^/REPRESENTATION_INFO^ +@cindex @option{-gnatR} (@command{gcc}) +Output representation information for declared types and objects. + +@item -gnats +@cindex @option{-gnats} (@command{gcc}) +Syntax check only. + +@item -gnatS +@cindex @option{-gnatS} (@command{gcc}) +Print package Standard. + +@item -gnatt +@cindex @option{-gnatt} (@command{gcc}) +Generate tree output file. + +@item ^-gnatT^/TABLE_MULTIPLIER=^@var{nnn} +@cindex @option{^-gnatT^/TABLE_MULTIPLIER^} (@command{gcc}) +All compiler tables start at @var{nnn} times usual starting size. + +@item -gnatu +@cindex @option{-gnatu} (@command{gcc}) +List units for this compilation. + +@item -gnatU +@cindex @option{-gnatU} (@command{gcc}) +Tag all error messages with the unique string ``error:'' + +@item -gnatv +@cindex @option{-gnatv} (@command{gcc}) +Verbose mode. Full error output with source lines to @file{stdout}. + +@item -gnatV +@cindex @option{-gnatV} (@command{gcc}) +Control level of validity checking (@pxref{Validity Checking}). + +@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^ +@cindex @option{^-gnatw^/WARNINGS^} (@command{gcc}) +Warning mode where +^@var{xxx} is a string of option letters that^the list of options^ denotes +the exact warnings that +are enabled or disabled (@pxref{Warning Message Control}). + +@item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e} +@cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc}) +Wide character encoding method +@ifclear vms +(@var{e}=n/h/u/s/e/8). +@end ifclear +@ifset vms +(@var{e}=@code{BRACKETS, NONE, HEX, UPPER, SHIFT_JIS, EUC, UTF8}) +@end ifset + +@item -gnatx +@cindex @option{-gnatx} (@command{gcc}) +Suppress generation of cross-reference information. + +@item -gnatX +@cindex @option{-gnatX} (@command{gcc}) +Enable GNAT implementation extensions and latest Ada version. + +@item ^-gnaty^/STYLE_CHECKS=(option,option@dots{})^ +@cindex @option{^-gnaty^/STYLE_CHECKS^} (@command{gcc}) +Enable built-in style checks (@pxref{Style Checking}). + +@item ^-gnatz^/DISTRIBUTION_STUBS=^@var{m} +@cindex @option{^-gnatz^/DISTRIBUTION_STUBS^} (@command{gcc}) +Distribution stub generation and compilation +@ifclear vms +(@var{m}=r/c for receiver/caller stubs). +@end ifclear +@ifset vms +(@var{m}=@code{RECEIVER} or @code{CALLER} to specify the type of stubs +to be generated and compiled). +@end ifset + +@item ^-I^/SEARCH=^@var{dir} +@cindex @option{^-I^/SEARCH^} (@command{gcc}) +@cindex RTL +Direct GNAT to search the @var{dir} directory for source files needed by +the current compilation +(@pxref{Search Paths and the Run-Time Library (RTL)}). + +@item ^-I-^/NOCURRENT_DIRECTORY^ +@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gcc}) +@cindex RTL +Except for the source file named in the command line, do not look for source +files in the directory containing the source file named in the command line +(@pxref{Search Paths and the Run-Time Library (RTL)}). + +@ifclear vms +@item -mbig-switch +@cindex @option{-mbig-switch} (@command{gcc}) +@cindex @code{case} statement (effect of @option{-mbig-switch} option) +This standard gcc switch causes the compiler to use larger offsets in its +jump table representation for @code{case} statements. +This may result in less efficient code, but is sometimes necessary +(for example on HP-UX targets) +@cindex HP-UX and @option{-mbig-switch} option +in order to compile large and/or nested @code{case} statements. + +@item -o @var{file} +@cindex @option{-o} (@command{gcc}) +This switch is used in @command{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. +@end ifclear + +@item -nostdinc +@cindex @option{-nostdinc} (@command{gcc}) +Inhibit the search of the default location for the GNAT Run Time +Library (RTL) source files. + +@item -nostdlib +@cindex @option{-nostdlib} (@command{gcc}) +Inhibit the search of the default location for the GNAT Run Time +Library (RTL) ALI files. + +@ifclear vms +@c @item -O@ovar{n} +@c Expanding @ovar macro inline (explanation in macro def comments) +@item -O@r{[}@var{n}@r{]} +@cindex @option{-O} (@command{gcc}) +@var{n} controls the optimization level. + +@table @asis +@item n = 0 +No optimization, the default setting if no @option{-O} appears + +@item n = 1 +Normal optimization, the default if you specify @option{-O} without +an operand. A good compromise between code quality and compilation +time. + +@item n = 2 +Extensive optimization, may improve execution time, possibly at the cost of +substantially increased compilation time. + +@item n = 3 +Same as @option{-O2}, and also includes inline expansion for small subprograms +in the same unit. + +@item n = s +Optimize space usage +@end table + +@noindent +See also @ref{Optimization Levels}. +@end ifclear + +@ifset vms +@item /NOOPTIMIZE +@cindex @option{/NOOPTIMIZE} (@code{GNAT COMPILE}) +Equivalent to @option{/OPTIMIZE=NONE}. +This is the default behavior in the absence of an @option{/OPTIMIZE} +qualifier. + +@item /OPTIMIZE@r{[}=(keyword@r{[},@dots{}@r{]})@r{]} +@cindex @option{/OPTIMIZE} (@code{GNAT COMPILE}) +Selects the level of optimization for your program. The supported +keywords are as follows: +@table @code +@item ALL +Perform most optimizations, including those that +are expensive. +This is the default if the @option{/OPTIMIZE} qualifier is supplied +without keyword options. + +@item NONE +Do not do any optimizations. Same as @code{/NOOPTIMIZE}. + +@item SOME +Perform some optimizations, but omit ones that are costly. + +@item DEVELOPMENT +Same as @code{SOME}. + +@item INLINING +Full optimization as in @option{/OPTIMIZE=ALL}, and also attempts +automatic inlining of small subprograms within a unit + +@item UNROLL_LOOPS +Try to unroll loops. This keyword may be specified together with +any keyword above other than @code{NONE}. Loop unrolling +usually, but not always, improves the performance of programs. + +@item SPACE +Optimize space usage +@end table + +@noindent +See also @ref{Optimization Levels}. +@end ifset + +@ifclear vms +@item -pass-exit-codes +@cindex @option{-pass-exit-codes} (@command{gcc}) +Catch exit codes from the compiler and use the most meaningful as +exit status. +@end ifclear + +@item --RTS=@var{rts-path} +@cindex @option{--RTS} (@command{gcc}) +Specifies the default location of the runtime library. Same meaning as the +equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). + +@item ^-S^/ASM^ +@cindex @option{^-S^/ASM^} (@command{gcc}) +^Used in place of @option{-c} to^Used to^ +cause the assembler source file to be +generated, using @file{^.s^.S^} as the extension, +instead of the object file. +This may be useful if you need to examine the generated assembly code. + +@item ^-fverbose-asm^/VERBOSE_ASM^ +@cindex @option{^-fverbose-asm^/VERBOSE_ASM^} (@command{gcc}) +^Used in conjunction with @option{-S}^Used in place of @option{/ASM}^ +to cause the generated assembly code file to be annotated with variable +names, making it significantly easier to follow. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@command{gcc}) +Show commands generated by the @command{gcc} driver. Normally used only for +debugging purposes or if you need to be sure what version of the +compiler you are executing. + +@ifclear vms +@item -V @var{ver} +@cindex @option{-V} (@command{gcc}) +Execute @var{ver} version of the compiler. This is the @command{gcc} +version, not the GNAT version. +@end ifclear + +@item ^-w^/NO_BACK_END_WARNINGS^ +@cindex @option{-w} (@command{gcc}) +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 @option{-gnatws} had appeared at the start of +the options). + +@end table + +@ifclear vms +@c Combining qualifiers does not work on VMS +You may combine a sequence of GNAT switches into a single switch. For +example, the combined switch + +@cindex Combining GNAT switches +@smallexample +-gnatofi3 +@end smallexample + +@noindent +is equivalent to specifying the following sequence of switches: + +@smallexample +-gnato -gnatf -gnati3 +@end smallexample +@end ifclear + +@noindent +The following restrictions apply to the combination of switches +in this manner: + +@itemize @bullet +@item +The switch @option{-gnatc} if combined with other switches must come +first in the string. + +@item +The switch @option{-gnats} if combined with other switches must come +first in the string. + +@item +The switches +^^@option{/DISTRIBUTION_STUBS=},^ +@option{-gnatzc} and @option{-gnatzr} may not be combined with any other +switches, and only one of them may appear in the command line. + +@item +The switch @option{-gnat-p} may not be combined with any other switch. + +@ifclear vms +@item +Once a ``y'' appears in the string (that is a use of the @option{-gnaty} +switch), then all further characters in the switch are interpreted +as style modifiers (see description of @option{-gnaty}). + +@item +Once a ``d'' appears in the string (that is a use of the @option{-gnatd} +switch), then all further characters in the switch are interpreted +as debug flags (see description of @option{-gnatd}). + +@item +Once a ``w'' appears in the string (that is a use of the @option{-gnatw} +switch), then all further characters in the switch are interpreted +as warning mode modifiers (see description of @option{-gnatw}). + +@item +Once a ``V'' appears in the string (that is a use of the @option{-gnatV} +switch), then all further characters in the switch are interpreted +as validity checking options (@pxref{Validity Checking}). + +@item +Option ``em'', ``ec'', ``ep'', ``l='' and ``R'' must be the last options in +a combined list of options. +@end ifclear +@end itemize + +@node Output and Error Message Control +@subsection Output and Error Message Control +@findex stderr + +@noindent +The standard default format for error messages is called ``brief format''. +Brief format messages are written to @file{stderr} (the standard error +file) and have the following form: + +@smallexample +e.adb:3:04: Incorrect spelling of keyword "function" +e.adb:4:20: ";" should be "is" +@end smallexample + +@noindent +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. +@ifclear vms +@code{GPS} can parse the error messages +and point to the referenced character. +@end ifclear +The following switches provide control over the error message +format: + +@table @option +@c !sort! +@item -gnatv +@cindex @option{-gnatv} (@command{gcc}) +@findex stdout +@ifclear vms +The v stands for verbose. +@end ifclear +The effect of this setting is to write long-format error +messages to @file{stdout} (the standard output file. +The same program compiled with the +@option{-gnatv} switch would generate: + +@smallexample +@cartouche +3. funcion X (Q : Integer) + | +>>> Incorrect spelling of keyword "function" +4. return Integer; + | +>>> ";" should be "is" +@end cartouche +@end smallexample + +@noindent +The vertical bar indicates the location of the error, and the @samp{>>>} +prefix can be used to search for error messages. When this switch is +used the only source lines output are those with errors. + +@item -gnatl +@cindex @option{-gnatl} (@command{gcc}) +@ifclear vms +The @code{l} stands for list. +@end ifclear +This switch causes a full listing of +the file to be generated. In the case where a body is +compiled, the corresponding spec is also listed, along +with any subunits. Typical output from compiling a package +body @file{p.adb} might look like: + +@smallexample @c ada +@cartouche + Compiling: p.adb + + 1. package body p is + 2. procedure a; + 3. procedure a is separate; + 4. begin + 5. null + | + >>> missing ";" + + 6. end; + +Compiling: p.ads + + 1. package p is + 2. pragma Elaborate_Body + | + >>> missing ";" + + 3. end p; + +Compiling: p-a.adb + + 1. separate p + | + >>> missing "(" + + 2. procedure a is + 3. begin + 4. null + | + >>> missing ";" + + 5. end; +@end cartouche +@end smallexample + +@noindent +@findex stderr +When you specify the @option{-gnatv} or @option{-gnatl} switches and +standard output is redirected, a brief summary is written to +@file{stderr} (standard error) giving the number of error messages and +warning messages generated. + +@item ^-gnatl^/OUTPUT_FILE^=file +@cindex @option{^-gnatl^/OUTPUT_FILE^=fname} (@command{gcc}) +This has the same effect as @option{-gnatl} except that the output is +written to a file instead of to standard output. If the given name +@file{fname} does not start with a period, then it is the full name +of the file to be written. If @file{fname} is an extension, it is +appended to the name of the file being compiled. For example, if +file @file{xyz.adb} is compiled with @option{^-gnatl^/OUTPUT_FILE^=.lst}, +then the output is written to file ^xyz.adb.lst^xyz.adb_lst^. + +@item -gnatU +@cindex @option{-gnatU} (@command{gcc}) +This switch forces all error messages to be preceded by the unique +string ``error:''. This means that error messages take a few more +characters in space, but allows easy searching for and identification +of error messages. + +@item -gnatb +@cindex @option{-gnatb} (@command{gcc}) +@ifclear vms +The @code{b} stands for brief. +@end ifclear +This switch causes GNAT to generate the +brief format error messages to @file{stderr} (the standard error +file) as well as the verbose +format message or full listing (which as usual is written to +@file{stdout} (the standard output file). + +@item -gnatm=@var{n} +@cindex @option{-gnatm} (@command{gcc}) +@ifclear vms +The @code{m} stands for maximum. +@end ifclear +@var{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 +@option{-gnatm2} might yield + +@smallexample +e.adb:3:04: Incorrect spelling of keyword "function" +e.adb:5:35: missing ".." +fatal error: maximum number of errors detected +compilation abandoned +@end smallexample + +@noindent +The default setting if +no switch is given is 9999. If the number of warnings reaches this +limit, then a message is output and further warnings are suppressed, +but the compilation is continued. If the number of error messages +reaches this limit, then a message is output and the compilation +is abandoned. A value of zero means that no limit applies. + +@noindent +Note that the equal sign is optional, so the switches +@option{-gnatm2} and @option{-gnatm=2} are equivalent. + +@item -gnatf +@cindex @option{-gnatf} (@command{gcc}) +@cindex Error messages, suppressing +@ifclear vms +The @code{f} stands for full. +@end ifclear +Normally, the compiler suppresses error messages that are likely to be +redundant. This switch causes all error +messages to be generated. In particular, in the case of +references to undefined variables. If a given variable is referenced +several times, the normal format of messages is +@smallexample +e.adb:7:07: "V" is undefined (more references follow) +@end smallexample + +@noindent +where the parenthetical comment warns that there are additional +references to the variable @code{V}. Compiling the same program with the +@option{-gnatf} switch yields + +@smallexample +e.adb:7:07: "V" is undefined +e.adb:8:07: "V" is undefined +e.adb:8:12: "V" is undefined +e.adb:8:16: "V" is undefined +e.adb:9:07: "V" is undefined +e.adb:9:12: "V" is undefined +@end smallexample + +@noindent +The @option{-gnatf} switch also generates additional information for +some error messages. Some examples are: + +@itemize @bullet +@item +Details on possibly non-portable unchecked conversion +@item +List possible interpretations for ambiguous calls +@item +Additional details on incorrect parameters +@end itemize + +@item -gnatjnn +@cindex @option{-gnatjnn} (@command{gcc}) +In normal operation mode (or if @option{-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 @option{-gnatjnn} switch is used with a positive value for nn, then +messages are output in a different manner. A message and all its continuation +lines are treated as a unit, and count as only one warning or message in the +statistics totals. Furthermore, the message is reformatted so that no line +is longer than nn characters. + +@item -gnatq +@cindex @option{-gnatq} (@command{gcc}) +@ifclear vms +The @code{q} stands for quit (really ``don't quit''). +@end ifclear +In normal operation mode, the compiler first parses the program and +determines if there are any syntax errors. If there are, appropriate +error messages are generated and compilation is immediately terminated. +This switch tells +GNAT to continue with semantic analysis even if syntax errors have been +found. This may enable the detection of more errors in a single run. On +the other hand, the semantic analyzer is more likely to encounter some +internal fatal error when given a syntactically invalid tree. + +@item -gnatQ +@cindex @option{-gnatQ} (@command{gcc}) +In normal operation mode, the @file{ALI} file is not generated if any +illegalities are detected in the program. The use of @option{-gnatQ} forces +generation of the @file{ALI} file. This file is marked as being in +error, so it cannot be used for binding purposes, but it does contain +reasonably complete cross-reference information, and thus may be useful +for use by tools (e.g., semantic browsing tools or integrated development +environments) that are driven from the @file{ALI} file. This switch +implies @option{-gnatq}, since the semantic phase must be run to get a +meaningful ALI file. + +In addition, if @option{-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 @option{-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 @option{-gnatQ} is used and the generated @file{ALI} file is marked as +being in error, @command{gnatmake} will attempt to recompile the source when it +finds such an @file{ALI} file, including with switch @option{-gnatc}. + +Note that @option{-gnatQ} has no effect if @option{-gnats} is specified, +since ALI files are never generated if @option{-gnats} is set. + +@end table + +@node Warning Message Control +@subsection Warning Message Control +@cindex Warning messages +@noindent +In addition to error messages, which correspond to illegalities as defined +in the Ada Reference Manual, the compiler detects two kinds of warning +situations. + +First, the compiler considers some constructs suspicious and generates a +warning message to alert you to a possible error. Second, if the +compiler detects a situation that is sure to raise an exception at +run time, it generates a warning message. The following shows an example +of warning messages: +@smallexample +e.adb:4:24: warning: creation of object may raise Storage_Error +e.adb:10:17: warning: static value out of range +e.adb:10:17: warning: "Constraint_Error" will be raised at run time +@end smallexample + +@noindent +GNAT considers a large number of situations as appropriate +for the generation of warning messages. As always, warnings are not +definite indications of errors. For example, if you do an out-of-range +assignment with the deliberate intention of raising a +@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 +subsequent versions of GNAT. The list is intended to give a general idea +of the kinds of warnings that are generated. + +@itemize @bullet +@item +Possible infinitely recursive calls + +@item +Out-of-range values being assigned + +@item +Possible order of elaboration problems + +@item +Assertions (pragma Assert) that are sure to fail + +@item +Unreachable code + +@item +Address clauses with possibly unaligned values, or where an attempt is +made to overlay a smaller variable with a larger one. + +@item +Fixed-point type declarations with a null range + +@item +Direct_IO or Sequential_IO instantiated with a type that has access values + +@item +Variables that are never assigned a value + +@item +Variables that are referenced before being initialized + +@item +Task entries with no corresponding @code{accept} statement + +@item +Duplicate accepts for the same task entry in a @code{select} + +@item +Objects that take too much storage + +@item +Unchecked conversion between types of differing sizes + +@item +Missing @code{return} statement along some execution path in a function + +@item +Incorrect (unrecognized) pragmas + +@item +Incorrect external names + +@item +Allocation from empty storage pool + +@item +Potentially blocking operation in protected type + +@item +Suspicious parenthesization of expressions + +@item +Mismatching bounds in an aggregate + +@item +Attempt to return local value by reference + +@item +Premature instantiation of a generic body + +@item +Attempt to pack aliased components + +@item +Out of bounds array subscripts + +@item +Wrong length on string assignment + +@item +Violations of style rules if style checking is enabled + +@item +Unused @code{with} clauses + +@item +@code{Bit_Order} usage that does not have any effect + +@item +@code{Standard.Duration} used to resolve universal fixed expression + +@item +Dereference of possibly null value + +@item +Declaration that is likely to cause storage error + +@item +Internal GNAT unit @code{with}'ed by application unit + +@item +Values known to be out of range at compile time + +@item +Unreferenced labels and variables + +@item +Address overlays that could clobber memory + +@item +Unexpected initialization when address clause present + +@item +Bad alignment for address clause + +@item +Useless type conversions + +@item +Redundant assignment statements and other redundant constructs + +@item +Useless exception handlers + +@item +Accidental hiding of name by child unit + +@item +Access before elaboration detected at compile time + +@item +A range in a @code{for} loop that is known to be null or might be null + +@end itemize + +@noindent +The following section lists compiler switches that are available +to control the handling of warning messages. It is also possible +to exercise much finer control over what warnings are issued and +suppressed using the GNAT pragma Warnings, @xref{Pragma Warnings,,, +gnat_rm, GNAT Reference manual}. + +@table @option +@c !sort! +@item -gnatwa +@emph{Activate most optional warnings.} +@cindex @option{-gnatwa} (@command{gcc}) +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 +@option{-gnatwd} (implicit dereferencing), +@option{-gnatwh} (hiding), +@option{-gnatw.h} (holes (gaps) in record layouts) +@option{-gnatwl} (elaboration warnings), +@option{-gnatw.o} (warn on values set by out parameters ignored) +and @option{-gnatwt} (tracking of deleted conditional code). +All other optional warnings are turned on. + +@item -gnatwA +@emph{Suppress all optional errors.} +@cindex @option{-gnatwA} (@command{gcc}) +This switch suppresses all optional warning messages, see remaining list +in this section for details on optional warning messages that can be +individually controlled. + +@item -gnatw.a +@emph{Activate warnings on failing assertions.} +@cindex @option{-gnatw.a} (@command{gcc}) +@cindex Assert failures +This switch activates warnings for assertions where the compiler can tell at +compile time that the assertion will fail. Note that this warning is given +even if assertions are disabled. The default is that such warnings are +generated. + +@item -gnatw.A +@emph{Suppress warnings on failing assertions.} +@cindex @option{-gnatw.A} (@command{gcc}) +@cindex Assert failures +This switch suppresses warnings for assertions where the compiler can tell at +compile time that the assertion will fail. + +@item -gnatwb +@emph{Activate warnings on bad fixed values.} +@cindex @option{-gnatwb} (@command{gcc}) +@cindex Bad fixed values +@cindex Fixed-point Small value +@cindex Small value +This switch activates warnings for static fixed-point expressions whose +value is not an exact multiple of Small. Such values are implementation +dependent, since an implementation is free to choose either of the multiples +that surround the value. GNAT always chooses the closer one, but this is not +required behavior, and it is better to specify a value that is an exact +multiple, ensuring predictable execution. The default is that such warnings +are not generated. + +@item -gnatwB +@emph{Suppress warnings on bad fixed values.} +@cindex @option{-gnatwB} (@command{gcc}) +This switch suppresses warnings for static fixed-point expressions whose +value is not an exact multiple of Small. + +@item -gnatw.b +@emph{Activate warnings on biased representation.} +@cindex @option{-gnatw.b} (@command{gcc}) +@cindex Biased representation +This switch activates warnings when a size clause, value size clause, component +clause, or component size clause forces the use of biased representation for an +integer type (e.g. representing a range of 10..11 in a single bit by using 0/1 +to represent 10/11). The default is that such warnings are generated. + +@item -gnatw.B +@emph{Suppress warnings on biased representation.} +@cindex @option{-gnatwB} (@command{gcc}) +This switch suppresses warnings for representation clauses that force the use +of biased representation. + +@item -gnatwc +@emph{Activate warnings on conditionals.} +@cindex @option{-gnatwc} (@command{gcc}) +@cindex Conditionals, constant +This switch activates warnings for conditional expressions used in +tests that are known to be True or False at compile time. The default +is that such warnings are not generated. +Note that this warning does +not get issued for the use of boolean variables or constants whose +values are known at compile time, since this is a standard technique +for conditional compilation in Ada, and this would generate too many +false positive warnings. + +This warning option also activates a special test for comparisons using +the operators ``>='' and`` <=''. +If the compiler can tell that only the equality condition is possible, +then it will warn that the ``>'' or ``<'' part of the test +is useless and that the operator could be replaced by ``=''. +An example would be comparing a @code{Natural} variable <= 0. + +This warning option also generates warnings if +one or both tests is optimized away in a membership test for integer +values if the result can be determined at compile time. Range tests on +enumeration types are not included, since it is common for such tests +to include an end point. + +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwC +@emph{Suppress warnings on conditionals.} +@cindex @option{-gnatwC} (@command{gcc}) +This switch suppresses warnings for conditional expressions used in +tests that are known to be True or False at compile time. + +@item -gnatw.c +@emph{Activate warnings on missing component clauses.} +@cindex @option{-gnatw.c} (@command{gcc}) +@cindex Component clause, missing +This switch activates warnings for record components where a record +representation clause is present and has component clauses for the +majority, but not all, of the components. A warning is given for each +component for which no component clause is present. + +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatw.C +@emph{Suppress warnings on missing component clauses.} +@cindex @option{-gnatwC} (@command{gcc}) +This switch suppresses warnings for record components that are +missing a component clause in the situation described above. + +@item -gnatwd +@emph{Activate warnings on implicit dereferencing.} +@cindex @option{-gnatwd} (@command{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 @code{.all} will generate a warning. With this warning +enabled, access checks occur only at points where an explicit +@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. +Note that @option{-gnatwa} does not affect the setting of +this warning option. + +@item -gnatwD +@emph{Suppress warnings on implicit dereferencing.} +@cindex @option{-gnatwD} (@command{gcc}) +@cindex Implicit dereferencing +@cindex Dereferencing, implicit +This switch suppresses warnings for implicit dereferences in +indexed components, slices, and selected components. + +@item -gnatwe +@emph{Treat warnings and style checks as errors.} +@cindex @option{-gnatwe} (@command{gcc}) +@cindex Warnings, treat as error +This switch causes warning messages and style check messages to be +treated as errors. +The warning string still appears, but the warning messages are counted +as errors, and prevent the generation of an object file. Note that this +is the only -gnatw switch that affects the handling of style check messages. + +@item -gnatw.e +@emph{Activate every optional warning} +@cindex @option{-gnatw.e} (@command{gcc}) +@cindex Warnings, activate every optional warning +This switch activates all optional warnings, including those which +are not activated by @code{-gnatwa}. + +@item -gnatwf +@emph{Activate warnings on unreferenced formals.} +@cindex @option{-gnatwf} (@command{gcc}) +@cindex Formals, unreferenced +This switch causes a warning to be generated if a formal parameter +is not referenced in the body of the subprogram. This warning can +also be turned on using @option{-gnatwa} or @option{-gnatwu}. The +default is that these warnings are not generated. + +@item -gnatwF +@emph{Suppress warnings on unreferenced formals.} +@cindex @option{-gnatwF} (@command{gcc}) +This switch suppresses warnings for unreferenced formal +parameters. Note that the +combination @option{-gnatwu} followed by @option{-gnatwF} has the +effect of warning on unreferenced entities other than subprogram +formals. + +@item -gnatwg +@emph{Activate warnings on unrecognized pragmas.} +@cindex @option{-gnatwg} (@command{gcc}) +@cindex Pragmas, unrecognized +This switch causes a warning to be generated if an unrecognized +pragma is encountered. Apart from issuing this warning, the +pragma is ignored and has no effect. This warning can +also be turned on using @option{-gnatwa}. The default +is that such warnings are issued (satisfying the Ada Reference +Manual requirement that such warnings appear). + +@item -gnatwG +@emph{Suppress warnings on unrecognized pragmas.} +@cindex @option{-gnatwG} (@command{gcc}) +This switch suppresses warnings for unrecognized pragmas. + +@item -gnatwh +@emph{Activate warnings on hiding.} +@cindex @option{-gnatwh} (@command{gcc}) +@cindex 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. +Note that @option{-gnatwa} does not affect the setting of this warning option. + +@item -gnatwH +@emph{Suppress warnings on hiding.} +@cindex @option{-gnatwH} (@command{gcc}) +This switch suppresses warnings on hiding declarations. + +@item -gnatw.h +@emph{Activate warnings on holes/gaps in records.} +@cindex @option{-gnatw.h} (@command{gcc}) +@cindex Record Representation (gaps) +This switch activates warnings on component clauses in record +representation clauses that leave holes (gaps) in the record layout. +If this warning option is active, then record representation clauses +should specify a contiguous layout, adding unused fill fields if needed. +Note that @option{-gnatwa} does not affect the setting of this warning option. + +@item -gnatw.H +@emph{Suppress warnings on holes/gaps in records.} +@cindex @option{-gnatw.H} (@command{gcc}) +This switch suppresses warnings on component clauses in record +representation clauses that leave holes (haps) in the record layout. + +@item -gnatwi +@emph{Activate warnings on implementation units.} +@cindex @option{-gnatwi} (@command{gcc}) +This switch activates warnings for a @code{with} of an internal GNAT +implementation unit, defined as any unit from the @code{Ada}, +@code{Interfaces}, @code{GNAT}, +^^@code{DEC},^ 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 +for internal implementation purposes and should not be @code{with}'ed +by user programs. The default is that such warnings are generated +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwI +@emph{Disable warnings on implementation units.} +@cindex @option{-gnatwI} (@command{gcc}) +This switch disables warnings for a @code{with} of an internal GNAT +implementation unit. + +@item -gnatw.i +@emph{Activate warnings on overlapping actuals.} +@cindex @option{-gnatw.i} (@command{gcc}) +This switch enables a warning on statically detectable overlapping actuals in +a subprogram call, when one of the actuals is an in-out parameter, and the +types of the actuals are not by-copy types. The warning is off by default, +and is not included under -gnatwa. + +@item -gnatw.I +@emph{Disable warnings on overlapping actuals.} +@cindex @option{-gnatw.I} (@command{gcc}) +This switch disables warnings on overlapping actuals in a call.. + +@item -gnatwj +@emph{Activate warnings on obsolescent features (Annex J).} +@cindex @option{-gnatwj} (@command{gcc}) +@cindex Features, obsolescent +@cindex Obsolescent features +If this warning option is activated, then warnings are generated for +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 @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. This warning is also turned on by +the use of @option{-gnatwa}. + +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, @code{pragma Ravenscar} will be flagged since its +function is replaced by @code{pragma Profile(Ravenscar)}. + +Note that this warning option functions differently from the +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 @code{ASCII}. + +@item -gnatwJ +@emph{Suppress warnings on obsolescent features (Annex J).} +@cindex @option{-gnatwJ} (@command{gcc}) +This switch disables warnings on use of obsolescent features. + +@item -gnatwk +@emph{Activate warnings on variables that could be constants.} +@cindex @option{-gnatwk} (@command{gcc}) +This switch activates warnings for variables that are initialized but +never modified, and then could be declared constants. The default is that +such warnings are not given. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwK +@emph{Suppress warnings on variables that could be constants.} +@cindex @option{-gnatwK} (@command{gcc}) +This switch disables warnings on variables that could be declared constants. + +@item -gnatwl +@emph{Activate warnings for elaboration pragmas.} +@cindex @option{-gnatwl} (@command{gcc}) +@cindex Elaboration, warnings +This switch activates warnings on missing +@code{Elaborate_All} and @code{Elaborate} pragmas. +See the section in this guide on elaboration checking for details on +when such pragmas should be used. In dynamic elaboration mode, this switch +generations warnings about the need to add elaboration pragmas. Note however, +that if you blindly follow these warnings, and add @code{Elaborate_All} +warnings wherever they are recommended, you basically end up with the +equivalent of the static elaboration model, which may not be what you want for +legacy code for which the static model does not work. + +For the static model, the messages generated are labeled "info:" (for +information messages). They are not warnings to add elaboration pragmas, +merely informational messages showing what implicit elaboration pragmas +have been added, for use in analyzing elaboration circularity problems. + +Warnings are also generated if you +are using the static mode of elaboration, and a @code{pragma Elaborate} +is encountered. The default is that such warnings +are not generated. +This warning is not automatically turned on by the use of @option{-gnatwa}. + +@item -gnatwL +@emph{Suppress warnings for elaboration pragmas.} +@cindex @option{-gnatwL} (@command{gcc}) +This switch suppresses warnings on missing Elaborate and Elaborate_All pragmas. +See the section in this guide on elaboration checking for details on +when such pragmas should be used. + +@item -gnatwm +@emph{Activate warnings on modified but unreferenced variables.} +@cindex @option{-gnatwm} (@command{gcc}) +This switch activates warnings for variables that are assigned (using +an initialization value or with one or more assignment statements) but +whose value is never read. The warning is suppressed for volatile +variables and also for variables that are renamings of other variables +or for which an address clause is given. +This warning can also be turned on using @option{-gnatwa}. +The default is that these warnings are not given. + +@item -gnatwM +@emph{Disable warnings on modified but unreferenced variables.} +@cindex @option{-gnatwM} (@command{gcc}) +This switch disables warnings for variables that are assigned or +initialized, but never read. + +@item -gnatw.m +@emph{Activate warnings on suspicious modulus values.} +@cindex @option{-gnatw.m} (@command{gcc}) +This switch activates warnings for modulus values that seem suspicious. +The cases caught are where the size is the same as the modulus (e.g. +a modulus of 7 with a size of 7 bits), and modulus values of 32 or 64 +with no size clause. The guess in both cases is that 2**x was intended +rather than x. The default is that these warnings are given. + +@item -gnatw.M +@emph{Disable warnings on suspicious modulus values.} +@cindex @option{-gnatw.M} (@command{gcc}) +This switch disables warnings for suspicious modulus values. + +@item -gnatwn +@emph{Set normal warnings mode.} +@cindex @option{-gnatwn} (@command{gcc}) +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 @option{-gnatwn} can be used to cancel the effect of +an explicit @option{-gnatws} or +@option{-gnatwe}. It also cancels the effect of the +implicit @option{-gnatwe} that is activated by the +use of @option{-gnatg}. + +@item -gnatwo +@emph{Activate warnings on address clause overlays.} +@cindex @option{-gnatwo} (@command{gcc}) +@cindex Address Clauses, warnings +This switch activates warnings for possibly unintended initialization +effects of defining address clauses that cause one variable to overlap +another. The default is that such warnings are generated. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwO +@emph{Suppress warnings on address clause overlays.} +@cindex @option{-gnatwO} (@command{gcc}) +This switch suppresses warnings on possibly unintended initialization +effects of defining address clauses that cause one variable to overlap +another. + +@item -gnatw.o +@emph{Activate warnings on modified but unreferenced out parameters.} +@cindex @option{-gnatw.o} (@command{gcc}) +This switch activates warnings for variables that are modified by using +them as actuals for a call to a procedure with an out mode formal, where +the resulting assigned value is never read. It is applicable in the case +where there is more than one out mode formal. If there is only one out +mode formal, the warning is issued by default (controlled by -gnatwu). +The warning is suppressed for volatile +variables and also for variables that are renamings of other variables +or for which an address clause is given. +The default is that these warnings are not given. Note that this warning +is not included in -gnatwa, it must be activated explicitly. + +@item -gnatw.O +@emph{Disable warnings on modified but unreferenced out parameters.} +@cindex @option{-gnatw.O} (@command{gcc}) +This switch suppresses warnings for variables that are modified by using +them as actuals for a call to a procedure with an out mode formal, where +the resulting assigned value is never read. + +@item -gnatwp +@emph{Activate warnings on ineffective pragma Inlines.} +@cindex @option{-gnatwp} (@command{gcc}) +@cindex Inlining, warnings +This switch activates warnings for failure of front end inlining +(activated by @option{-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. +This warning can also be turned on using @option{-gnatwa}. +Warnings on ineffective inlining by the gcc back-end can be activated +separately, using the gcc switch -Winline. + +@item -gnatwP +@emph{Suppress warnings on ineffective pragma Inlines.} +@cindex @option{-gnatwP} (@command{gcc}) +This switch suppresses warnings on ineffective pragma Inlines. If the +inlining mechanism cannot inline a call, it will simply ignore the +request silently. + +@item -gnatw.p +@emph{Activate warnings on parameter ordering.} +@cindex @option{-gnatw.p} (@command{gcc}) +@cindex Parameter order, warnings +This switch activates warnings for cases of suspicious parameter +ordering when the list of arguments are all simple identifiers that +match the names of the formals, but are in a different order. The +warning is suppressed if any use of named parameter notation is used, +so this is the appropriate way to suppress a false positive (and +serves to emphasize that the "misordering" is deliberate). The +default is +that such warnings are not given. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatw.P +@emph{Suppress warnings on parameter ordering.} +@cindex @option{-gnatw.P} (@command{gcc}) +This switch suppresses warnings on cases of suspicious parameter +ordering. + +@item -gnatwq +@emph{Activate warnings on questionable missing parentheses.} +@cindex @option{-gnatwq} (@command{gcc}) +@cindex Parentheses, warnings +This switch activates warnings for cases where parentheses are not used and +the result is potential ambiguity from a readers point of view. For example +(not a > b) when a and b are modular means ((not a) > b) and very likely the +programmer intended (not (a > b)). Similarly (-x mod 5) means (-(x mod 5)) and +quite likely ((-x) mod 5) was intended. In such situations it seems best to +follow the rule of always parenthesizing to make the association clear, and +this warning switch warns if such parentheses are not present. The default +is that these warnings are given. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwQ +@emph{Suppress warnings on questionable missing parentheses.} +@cindex @option{-gnatwQ} (@command{gcc}) +This switch suppresses warnings for cases where the association is not +clear and the use of parentheses is preferred. + +@item -gnatwr +@emph{Activate warnings on redundant constructs.} +@cindex @option{-gnatwr} (@command{gcc}) +This switch activates warnings for redundant constructs. The following +is the current list of constructs regarded as redundant: + +@itemize @bullet +@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 boolean expressions to an explicit True value. +@end itemize + +This warning can also be turned on using @option{-gnatwa}. +The default is that warnings for redundant constructs are not given. + +@item -gnatwR +@emph{Suppress warnings on redundant constructs.} +@cindex @option{-gnatwR} (@command{gcc}) +This switch suppresses warnings for redundant constructs. + +@item -gnatw.r +@emph{Activate warnings for object renaming function.} +@cindex @option{-gnatw.r} (@command{gcc}) +This switch activates warnings for an object renaming that renames a +function call, which is equivalent to a constant declaration (as +opposed to renaming the function itself). The default is that these +warnings are given. This warning can also be turned on using +@option{-gnatwa}. + +@item -gnatw.R +@emph{Suppress warnings for object renaming function.} +@cindex @option{-gnatwT} (@command{gcc}) +This switch suppresses warnings for object renaming function. + +@item -gnatws +@emph{Suppress all warnings.} +@cindex @option{-gnatws} (@command{gcc}) +This switch completely suppresses the +output of all warning messages from the GNAT front end. +Note that it does not suppress warnings from the @command{gcc} back end. +To suppress these back end warnings as well, use the switch @option{-w} +in addition to @option{-gnatws}. Also this switch has no effect on the +handling of style check messages. + +@item -gnatw.s +@emph{Activate warnings on overridden size clauses.} +@cindex @option{-gnatw.s} (@command{gcc}) +@cindex Record Representation (component sizes) +This switch activates warnings on component clauses in record +representation clauses where the length given overrides that +specified by an explicit size clause for the component type. A +warning is similarly given in the array case if a specified +component size overrides an explicit size clause for the array +component type. +Note that @option{-gnatwa} does not affect the setting of this warning option. + +@item -gnatw.S +@emph{Suppress warnings on overridden size clauses.} +@cindex @option{-gnatw.S} (@command{gcc}) +This switch suppresses warnings on component clauses in record +representation clauses that override size clauses, and similar +warnings when an array component size overrides a size clause. + +@item -gnatwt +@emph{Activate warnings for tracking of deleted conditional code.} +@cindex @option{-gnatwt} (@command{gcc}) +@cindex Deactivated code, warnings +@cindex Deleted code, warnings +This switch activates warnings for tracking of code in conditionals (IF and +CASE statements) that is detected to be dead code which cannot be executed, and +which is removed by the front end. This warning is off by default, and is not +turned on by @option{-gnatwa}, it has to be turned on explicitly. This may be +useful for detecting deactivated code in certified applications. + +@item -gnatwT +@emph{Suppress warnings for tracking of deleted conditional code.} +@cindex @option{-gnatwT} (@command{gcc}) +This switch suppresses warnings for tracking of deleted conditional code. + +@item -gnatwu +@emph{Activate warnings on unused entities.} +@cindex @option{-gnatwu} (@command{gcc}) +This switch activates warnings to be generated for entities that +are declared but not referenced, and for units that are @code{with}'ed +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 the 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 @code{with}'ed but never instantiated. +In the case where a package or subprogram body is compiled, and there +is a @code{with} on the corresponding spec +that is only referenced in the body, +a warning is also generated, noting that the +@code{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 @option{-gnatwf}). +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwU +@emph{Suppress warnings on unused entities.} +@cindex @option{-gnatwU} (@command{gcc}) +This switch suppresses warnings for unused entities and packages. +It also turns off warnings on unreferenced formals (and thus includes +the effect of @option{-gnatwF}). + +@item -gnatw.u +@emph{Activate warnings on unordered enumeration types.} +@cindex @option{-gnatw.u} (@command{gcc}) +This switch causes enumeration types to be considered as conceptually +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 @code{Ordered} in the +@cite{@value{EDITION} Reference Manual} for further details. + +@item -gnatw.U +@emph{Deactivate warnings on unordered enumeration types.} +@cindex @option{-gnatw.U} (@command{gcc}) +This switch causes all enumeration types to be considered as ordered, so +that no warnings are given for comparisons or subranges for any type. + +@item -gnatwv +@emph{Activate warnings on unassigned variables.} +@cindex @option{-gnatwv} (@command{gcc}) +@cindex Unassigned variable warnings +This switch activates warnings for access to variables which +may not be properly initialized. The default is that +such warnings are generated. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwV +@emph{Suppress warnings on unassigned variables.} +@cindex @option{-gnatwV} (@command{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: + +@smallexample @c ada + Tab : Table := (others => <>); +@end smallexample + +will suppress warnings on subsequent statements that access components +of variable Tab. + +@item -gnatww +@emph{Activate warnings on wrong low bound assumption.} +@cindex @option{-gnatww} (@command{gcc}) +@cindex String indexing warnings +This switch activates warnings for indexing an unconstrained string parameter +with a literal or S'Length. This is a case where the code is assuming that the +low bound is one, which is in general not true (for example when a slice is +passed). The default is that such warnings are generated. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwW +@emph{Suppress warnings on wrong low bound assumption.} +@cindex @option{-gnatwW} (@command{gcc}) +This switch suppresses warnings for indexing an unconstrained string parameter +with a literal or S'Length. Note that this warning can also be suppressed +in a particular case by adding an +assertion that the lower bound is 1, +as shown in the following example. + +@smallexample @c ada + procedure K (S : String) is + pragma Assert (S'First = 1); + @dots{} +@end smallexample + +@item -gnatw.w +@emph{Activate warnings on unnecessary Warnings Off pragmas} +@cindex @option{-gnatw.w} (@command{gcc}) +@cindex Warnings Off control +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 @code{pragma Unreferenced} or +@code{pragma Unmodified}.The default is that these warnings are not given. +Note that this warning is not included in -gnatwa, it must be +activated explicitly. + +@item -gnatw.W +@emph{Suppress warnings on unnecessary Warnings Off pragmas} +@cindex @option{-gnatw.W} (@command{gcc}) +This switch suppresses warnings for use of @code{pragma Warnings (Off, entity}. + +@item -gnatwx +@emph{Activate warnings on Export/Import pragmas.} +@cindex @option{-gnatwx} (@command{gcc}) +@cindex Export/Import pragma warnings +This switch activates warnings on Export/Import pragmas when +the compiler detects a possible conflict between the Ada and +foreign language calling sequences. For example, the use of +default parameters in a convention C procedure is dubious +because the C compiler cannot supply the proper default, so +a warning is issued. The default is that such warnings are +generated. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwX +@emph{Suppress warnings on Export/Import pragmas.} +@cindex @option{-gnatwX} (@command{gcc}) +This switch suppresses warnings on Export/Import pragmas. +The sense of this is that you are telling the compiler that +you know what you are doing in writing the pragma, and it +should not complain at you. + +@item -gnatw.x +@emph{Activate warnings for No_Exception_Propagation mode.} +@cindex @option{-gnatwm} (@command{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. + +@item -gnatw.X +@emph{Disable warnings for No_Exception_Propagation mode.} +This switch disables warnings for exception usage when pragma Restrictions +(No_Exception_Propagation) is in effect. + +@item -gnatwy +@emph{Activate warnings for Ada 2005 compatibility issues.} +@cindex @option{-gnatwy} (@command{gcc}) +@cindex Ada 2005 compatibility issues warnings +For the most part Ada 2005 is upwards compatible with Ada 95, +but there are some exceptions (for example the fact that +@code{interface} is now a reserved word in Ada 2005). This +switch activates several warnings to help in identifying +and correcting such incompatibilities. The default is that +these warnings are generated. Note that at one point Ada 2005 +was called Ada 0Y, hence the choice of character. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwY +@emph{Disable warnings for Ada 2005 compatibility issues.} +@cindex @option{-gnatwY} (@command{gcc}) +@cindex Ada 2005 compatibility issues warnings +This switch suppresses several warnings intended to help in identifying +incompatibilities between Ada 95 and Ada 2005. + +@item -gnatwz +@emph{Activate warnings on unchecked conversions.} +@cindex @option{-gnatwz} (@command{gcc}) +@cindex Unchecked_Conversion warnings +This switch activates warnings for unchecked conversions +where the types are known at compile time to have different +sizes. The default +is that such warnings are generated. Warnings are also +generated for subprogram pointers with different conventions, +and, on VMS only, for data pointers with different conventions. +This warning can also be turned on using @option{-gnatwa}. + +@item -gnatwZ +@emph{Suppress warnings on unchecked conversions.} +@cindex @option{-gnatwZ} (@command{gcc}) +This switch suppresses warnings for unchecked conversions +where the types are known at compile time to have different +sizes or conventions. + +@item ^-Wunused^WARNINGS=UNUSED^ +@cindex @option{-Wunused} +The warnings controlled by the @option{-gnatw} switch are generated by +the front end of the compiler. The @option{GCC} back end can provide +additional warnings and they are controlled by the @option{-W} switch. +For example, @option{^-Wunused^WARNINGS=UNUSED^} activates back end +warnings for entities that are declared but not referenced. + +@item ^-Wuninitialized^WARNINGS=UNINITIALIZED^ +@cindex @option{-Wuninitialized} +Similarly, @option{^-Wuninitialized^WARNINGS=UNINITIALIZED^} activates +the back end warning for uninitialized variables. This switch must be +used in conjunction with an optimization level greater than zero. + +@item ^-Wall^/ALL_BACK_END_WARNINGS^ +@cindex @option{-Wall} +This switch enables all the above warnings from the @option{GCC} back end. +The code generator detects a number of warning situations that are missed +by the @option{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 +@option{-gnatwa}, that is, most front end warnings activated as well. + +@item ^-w^/NO_BACK_END_WARNINGS^ +@cindex @option{-w} +Conversely, this switch suppresses warnings from the @option{GCC} back end. +The use of this switch also sets the default front end warning mode to +@option{-gnatws}, that is, front end warnings suppressed as well. + +@end table + +@noindent +@ifclear vms +A string of warning parameters can be used in the same parameter. For example: + +@smallexample +-gnatwaLe +@end smallexample + +@noindent +will turn on all optional warnings except for elaboration pragma warnings, +and also specify that warnings should be treated as errors. +@end ifclear +When no switch @option{^-gnatw^/WARNINGS^} is used, this is equivalent to: + +@table @option +@c !sort! +@item -gnatwC +@item -gnatwD +@item -gnatwF +@item -gnatwg +@item -gnatwH +@item -gnatwi +@item -gnatwJ +@item -gnatwK +@item -gnatwL +@item -gnatwM +@item -gnatwn +@item -gnatwo +@item -gnatwP +@item -gnatwR +@item -gnatwU +@item -gnatwv +@item -gnatwz +@item -gnatwx + +@end table + +@node Debugging and Assertion Control +@subsection Debugging and Assertion Control + +@table @option +@item -gnata +@cindex @option{-gnata} (@command{gcc}) +@findex Assert +@findex Debug +@cindex Assertions + +@noindent +The pragmas @code{Assert} and @code{Debug} normally have no effect and +are ignored. This switch, where @samp{a} stands for assert, causes +@code{Assert} and @code{Debug} pragmas to be activated. + +The pragmas have the form: + +@smallexample +@cartouche + @b{pragma} Assert (@var{Boolean-expression} @r{[}, + @var{static-string-expression}@r{]}) + @b{pragma} Debug (@var{procedure call}) +@end cartouche +@end smallexample + +@noindent +The @code{Assert} pragma causes @var{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 +@code{False}, the exception @code{Assert_Failure} declared in the package +@code{System.Assertions} is +raised (passing @var{static-string-expression}, if present, as the +message associated with the exception). If no string expression is +given the default is a string giving the file name and line number +of the pragma. + +The @code{Debug} pragma causes @var{procedure} to be called. Note that +@code{pragma Debug} may appear within a declaration sequence, allowing +debugging procedures to be called between declarations. + +@ifset vms +@item /DEBUG@r{[}=debug-level@r{]} +@itemx /NODEBUG +Specifies how much debugging information is to be included in +the resulting object file where 'debug-level' is one of the following: +@table @code +@item TRACEBACK +Include both debugger symbol records and traceback +the object file. +This is the default setting. +@item ALL +Include both debugger symbol records and traceback in +object file. +@item NONE +Excludes both debugger symbol records and traceback +the object file. Same as /NODEBUG. +@item SYMBOLS +Includes only debugger symbol records in the object +file. Note that this doesn't include traceback information. +@end table +@end ifset +@end table + +@node Validity Checking +@subsection Validity Checking +@findex Validity Checking + +@noindent +The Ada Reference Manual defines the concept of invalid values (see +RM 13.9.1). The primary source of invalid values is uninitialized +variables. A scalar variable that is left uninitialized may contain +an invalid value; the concept of invalid does not apply to access or +composite types. + +It is an error to read an invalid value, but the RM does not require +run-time checks to detect such errors, except for some minimal +checking to prevent erroneous execution (i.e. unpredictable +behavior). This corresponds to the @option{-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 @option{-gnatVa} may be used to enable additional validity checks, +which are not required by the RM. These checks are often very +expensive (which is why the RM does not require them). These checks +are useful in tracking down uninitialized variables, but they are +not usually recommended for production builds. + +The other @option{-gnatV^@var{x}^^} switches below allow finer-grained +control; you can enable whichever validity checks you desire. However, +for most debugging purposes, @option{-gnatVa} is sufficient, and the +default @option{-gnatVd} (i.e. standard Ada behavior) is usually +sufficient for non-debugging use. + +The @option{-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 @option{-gnatV^@var{x}^^} switch allows control over the validity +checking mode as described below. +@ifclear vms +The @code{x} argument is a string of letters that +indicate validity checks that are performed or not performed in addition +to the default checks required by Ada as described above. +@end ifclear +@ifset vms +The options allowed for this qualifier +indicate validity checks that are performed or not performed in addition +to the default checks required by Ada as described above. +@end ifset + +@table @option +@c !sort! +@item -gnatVa +@emph{All validity checks.} +@cindex @option{-gnatVa} (@command{gcc}) +All validity checks are turned on. +@ifclear vms +That is, @option{-gnatVa} is +equivalent to @option{gnatVcdfimorst}. +@end ifclear + +@item -gnatVc +@emph{Validity checks for copies.} +@cindex @option{-gnatVc} (@command{gcc}) +The right hand side of assignments, and the initializing values of +object declarations are validity checked. + +@item -gnatVd +@emph{Default (RM) validity checks.} +@cindex @option{-gnatVd} (@command{gcc}) +Some validity checks are done by default following normal Ada semantics +(RM 13.9.1 (9-11)). +A check is done in case statements that the expression is within the range +of the subtype. If it is not, Constraint_Error is raised. +For assignments to array components, a check is done that the expression used +as index is within the range. If it is not, Constraint_Error is raised. +Both these validity checks may be turned off using switch @option{-gnatVD}. +They are turned on by default. If @option{-gnatVD} is specified, a subsequent +switch @option{-gnatVd} will leave the checks turned on. +Switch @option{-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. + +@item -gnatVe +@emph{Validity checks for elementary components.} +@cindex @option{-gnatVe} (@command{gcc}) +In the absence of this switch, assignments to record or array components are +not validity checked, even if validity checks for assignments generally +(@option{-gnatVc}) are turned on. In Ada, assignment of composite values do not +require valid data, but assignment of individual components does. So for +example, there is a difference between copying the elements of an array with a +slice assignment, compared to assigning element by element in a loop. This +switch allows you to turn off validity checking for components, even when they +are assigned component by component. + +@item -gnatVf +@emph{Validity checks for floating-point values.} +@cindex @option{-gnatVf} (@command{gcc}) +In the absence of this switch, validity checking occurs only for discrete +values. If @option{-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, +@option{^-gnatVif^VALIDITY_CHECKING=(IN_PARAMS,FLOATS)^} or +@option{^-gnatVfi^VALIDITY_CHECKING=(FLOATS,IN_PARAMS)^} +(the order does not matter) specifies that floating-point parameters of mode +@code{in} should be validity checked. + +@item -gnatVi +@emph{Validity checks for @code{in} mode parameters} +@cindex @option{-gnatVi} (@command{gcc}) +Arguments for parameters of mode @code{in} are validity checked in function +and procedure calls at the point of call. + +@item -gnatVm +@emph{Validity checks for @code{in out} mode parameters.} +@cindex @option{-gnatVm} (@command{gcc}) +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 @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. + +@item -gnatVn +@emph{No validity checks.} +@cindex @option{-gnatVn} (@command{gcc}) +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 @option{-gnatp} suppresses all run-time checks, including +validity checks, and thus implies @option{-gnatVn}. When this switch +is used, it cancels any other @option{-gnatV} previously issued. + +@item -gnatVo +@emph{Validity checks for operator and attribute operands.} +@cindex @option{-gnatVo} (@command{gcc}) +Arguments for predefined operators and attributes are validity checked. +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 @samp{..} (e.g.@: slices, loops etc). + +@item -gnatVp +@emph{Validity checks for parameters.} +@cindex @option{-gnatVp} (@command{gcc}) +This controls the treatment of parameters within a subprogram (as opposed +to @option{-gnatVi} and @option{-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 @option{-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. + +@item -gnatVr +@emph{Validity checks for function returns.} +@cindex @option{-gnatVr} (@command{gcc}) +The expression in @code{return} statements in functions is validity +checked. + +@item -gnatVs +@emph{Validity checks for subscripts.} +@cindex @option{-gnatVs} (@command{gcc}) +All subscripts expressions are checked for validity, whether they appear +on the right side or left side (in default mode only left side subscripts +are validity checked). + +@item -gnatVt +@emph{Validity checks for tests.} +@cindex @option{-gnatVt} (@command{gcc}) +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 + +@noindent +The @option{-gnatV} switch may be followed by +^a string of letters^a list of options^ +to turn on a series of validity checking options. +For example, +@option{^-gnatVcr^/VALIDITY_CHECKING=(COPIES, RETURNS)^} +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, +@ifclear vms +the upper case letters @code{CDFIMORST} may +be used to turn off the corresponding lower case option. +@end ifclear +@ifset vms +the prefix @code{NO} on an option turns off the corresponding validity +checking: +@itemize @bullet +@item @code{NOCOPIES} +@item @code{NODEFAULT} +@item @code{NOFLOATS} +@item @code{NOIN_PARAMS} +@item @code{NOMOD_PARAMS} +@item @code{NOOPERANDS} +@item @code{NORETURNS} +@item @code{NOSUBSCRIPTS} +@item @code{NOTESTS} +@end itemize +@end ifset +Thus +@option{^-gnatVaM^/VALIDITY_CHECKING=(ALL, NOMOD_PARAMS)^} +turns on all validity checking options except for +checking of @code{@b{in out}} procedure arguments. + +The specification of additional validity checking generates extra code (and +in the case of @option{-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 @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 @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 +@subsection Style Checking +@findex Style checking + +@noindent +The @option{-gnaty^x^(option,option,@dots{})^} switch +@cindex @option{-gnaty} (@command{gcc}) +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 @option{-gnatwe} switch is used). + +Note that this is by no means intended to be a general facility for +checking arbitrary coding standards. It is simply an embedding of the +style rules we have chosen for the GNAT sources. If you are starting +a project which does not have established style standards, you may +find it useful to adopt the entire set of GNAT coding standards, or +some subset of them. If you already have an established set of coding +standards, then it may be that selected style checking options do +indeed correspond to choices you have made, but for general checking +of an existing set of coding rules, you should look to the gnatcheck +tool, which is designed for that purpose. + +@ifset vms +@code{(option,option,@dots{})} is a sequence of keywords +@end ifset +@ifclear vms +The string @var{x} is a sequence of letters or digits +@end ifclear +indicating the particular style +checks to be performed. The following checks are defined: + +@table @option +@c !sort! +@item 0-9 +@emph{Specify indentation level.} +If a digit from 1-9 appears +^in the string after @option{-gnaty}^as an option for /STYLE_CHECKS^ +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 @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. + +@item ^a^ATTRIBUTE^ +@emph{Check attribute casing.} +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. + +@item ^A^ARRAY_INDEXES^ +@emph{Use of array index numbers in array attributes.} +When using the array attributes First, Last, Range, +or Length, the index number must be omitted for one-dimensional arrays +and is required for multi-dimensional arrays. + +@item ^b^BLANKS^ +@emph{Blanks not allowed at statement end.} +Trailing blanks are not allowed at the end of statements. The purpose of this +rule, together with h (no horizontal tabs), is to enforce a canonical format +for the use of blanks to separate source tokens. + +@item ^B^BOOLEAN_OPERATORS^ +@emph{Check Boolean operators.} +The use of AND/OR operators is not permitted except in the cases of modular +operands, array operands, and simple stand-alone boolean variables or +boolean constants. In all other cases AND THEN/OR ELSE are required. + +@item ^c^COMMENTS^ +@emph{Check comments.} +Comments must meet the following set of rules: + +@itemize @bullet + +@item +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 ``@code{--}'' at the start of the comment. + +@item +Full line comments must have at least two blanks following the +``@code{--}'' that starts the comment, with the following exceptions. + +@item +A line consisting only of the ``@code{--}'' characters, possibly preceded +by blanks is permitted. + +@item +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 @command{gnatprep} (where ``@code{--!}'' is used) and the SPARK +annotation +language (where ``@code{--#}'' is used). For the purposes of this rule, a +special character is defined as being in one of the ASCII ranges +@code{16#21#@dots{}16#2F#} or @code{16#3A#@dots{}16#3F#}. +Note that this usage is not permitted +in GNAT implementation units (i.e., when @option{-gnatg} is used). + +@item +A line consisting entirely of minus signs, possibly preceded by blanks, is +permitted. This allows the construction of box comments where lines of minus +signs are used to form the top and bottom of the box. + +@item +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: +@smallexample +--------------------------- +-- This is a box comment -- +-- with two text lines. -- +--------------------------- +@end smallexample +@end itemize + +@item ^d^DOS_LINE_ENDINGS^ +@emph{Check no DOS line terminators present.} +All lines must be terminated by a single ASCII.LF +character (in particular the DOS line terminator sequence CR/LF is not +allowed). + +@item ^e^END^ +@emph{Check end/exit labels.} +Optional labels on @code{end} statements ending subprograms and on +@code{exit} statements exiting named loops, are required to be present. + +@item ^f^VTABS^ +@emph{No form feeds or vertical tabs.} +Neither form feeds nor vertical tab characters are permitted +in the source text. + +@item ^g^GNAT^ +@emph{GNAT style mode} +The set of style check switches is set to match that used by the GNAT sources. +This may be useful when developing code that is eventually intended to be +incorporated into GNAT. For further details, see GNAT sources. + +@item ^h^HTABS^ +@emph{No horizontal tabs.} +Horizontal tab characters are not permitted in the source text. +Together with the b (no blanks at end of line) check, this +enforces a canonical form for the use of blanks to separate +source tokens. + +@item ^i^IF_THEN^ +@emph{Check if-then layout.} +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} with at least one non-blank line in between +containing all or part of the condition to be tested. + +@item ^I^IN_MODE^ +@emph{check mode IN keywords} +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. + +@item ^k^KEYWORD^ +@emph{Check keyword casing.} +All keywords must be in lower case (with the exception of keywords +such as @code{digits} used as attribute names to which this check +does not apply). + +@item ^l^LAYOUT^ +@emph{Check layout.} +Layout of statement and declaration constructs must follow the +recommendations in the Ada Reference Manual, as indicated by the +form of the syntax rules. For example an @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 +@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: + +@smallexample @c ada +@cartouche +type q is record + a : integer; + b : integer; +end record; + +type q is + record + a : integer; + b : integer; + end record; + +type q is + record + a : integer; + b : integer; +end record; + +@end cartouche +@end smallexample + +@noindent +Second, in the case of a block statement, a permitted alternative +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: + +@smallexample @c ada +@cartouche +Block : declare + A : Integer := 3; +begin + Proc (A, A); +end Block; + +Block : + declare + A : Integer := 3; + begin + Proc (A, A); + end Block; +@end cartouche +@end smallexample + +@noindent +The same alternative format is allowed for loops. For example, both of +the following are permitted: + +@smallexample @c ada +@cartouche +Clear : while J < 10 loop + A (J) := 0; +end loop Clear; + +Clear : + while J < 10 loop + A (J) := 0; + end loop Clear; +@end cartouche +@end smallexample + +@item ^Lnnn^MAX_NESTING=nnn^ +@emph{Set maximum nesting level} +The maximum level of nesting of constructs (including subprograms, loops, +blocks, packages, and conditionals) may not exceed the given value +@option{nnn}. A value of zero disconnects this style check. + +@item ^m^LINE_LENGTH^ +@emph{Check maximum line length.} +The length of source lines must not exceed 79 characters, including +any trailing blanks. The value of 79 allows convenient display on an +80 character wide device or window, allowing for possible special +treatment of 80 character lines. Note that this count is of +characters in the source text. This means that a tab character counts +as one character in this count but a wide character sequence counts as +a single character (however many bytes are needed in the encoding). + +@item ^Mnnn^MAX_LENGTH=nnn^ +@emph{Set maximum line length.} +The length of lines must not exceed the +given value @option{nnn}. The maximum value that can be specified is 32767. + +@item ^n^STANDARD_CASING^ +@emph{Check casing of entities in Standard.} +Any identifier from Standard must be cased +to match the presentation in the Ada Reference Manual (for example, +@code{Integer} and @code{ASCII.NUL}). + +@item ^N^NONE^ +@emph{Turn off all style checks} +All style check options are turned off. + +@item ^o^ORDERED_SUBPROGRAMS^ +@emph{Check order of subprogram bodies.} +All subprogram bodies in a given scope +(e.g.@: a package body) must be in alphabetical order. The ordering +rule uses normal Ada rules for comparing strings, ignoring casing +of letters, except that if there is a trailing numeric suffix, then +the value of this suffix is used in the ordering (e.g.@: Junk2 comes +before Junk10). + +@item ^O^OVERRIDING_INDICATORS^ +@emph{Check that overriding subprograms are explicitly marked as such.} +The declaration of a primitive operation of a type extension that overrides +an inherited operation must carry an overriding indicator. + +@item ^p^PRAGMA^ +@emph{Check pragma casing.} +Pragma names must be written in mixed case, that is, the +initial letter and any letter following an underscore must be uppercase. +All other letters must be lowercase. + +@item ^r^REFERENCES^ +@emph{Check references.} +All identifier references must be cased in the same way as the +corresponding declaration. No specific casing style is imposed on +identifiers. The only requirement is for consistency of references +with declarations. + +@item ^S^STATEMENTS_AFTER_THEN_ELSE^ +@emph{Check no statements after THEN/ELSE.} +No statements are allowed +on the same line as a THEN or ELSE keyword following the +keyword in an IF statement. OR ELSE and AND THEN are not affected, +and a special exception allows a pragma to appear after ELSE. + +@item ^s^SPECS^ +@emph{Check separate specs.} +Separate declarations (``specs'') are required for subprograms (a +body is not allowed to serve as its own declaration). The only +exception is that parameterless library level procedures are +not required to have a separate declaration. This exception covers +the most frequent form of main program procedures. + +@item ^t^TOKEN^ +@emph{Check token spacing.} +The following token spacing rules are enforced: + +@itemize @bullet + +@item +The keywords @code{@b{abs}} and @code{@b{not}} must be followed by a space. + +@item +The token @code{=>} must be surrounded by spaces. + +@item +The token @code{<>} must be preceded by a space or a left parenthesis. + +@item +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. + +@item +Colon-equal (assignment, initialization) must be surrounded by spaces. + +@item +Comma must be the first non-blank character on the line, or be +immediately preceded by a non-blank character, and must be followed +by a space. + +@item +If the token preceding a left parenthesis ends with a letter or digit, then +a space must separate the two tokens. + +@item +if the token following a right parenthesis starts with a letter or digit, then +a space must separate the two tokens. + +@item +A right parenthesis must either be the first non-blank character on +a line, or it must be preceded by a non-blank character. + +@item +A semicolon must not be preceded by a space, and must not be followed by +a non-blank character. + +@item +A unary plus or minus may not be followed by a space. + +@item +A vertical bar must be surrounded by spaces. +@end itemize + +@item ^u^UNNECESSARY_BLANK_LINES^ +@emph{Check unnecessary blank lines.} +Unnecessary blank lines are not allowed. A blank line is considered +unnecessary if it appears at the end of the file, or if more than +one blank line occurs in sequence. + +@item ^x^XTRA_PARENS^ +@emph{Check extra parentheses.} +Unnecessary extra level of parentheses (C-style) are not allowed +around conditions in @code{if} statements, @code{while} statements and +@code{exit} statements. + +@item ^y^ALL_BUILTIN^ +@emph{Set all standard style check options} +This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking +options enabled with the exception of @option{-gnatyo}, @option{-gnatyI}, +@option{-gnatyS}, @option{-gnatyLnnn}, +@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}. + +@ifclear vms +@item - +@emph{Remove style check options} +This causes any subsequent options in the string to act as canceling the +corresponding style check option. To cancel maximum nesting level control, +use @option{L} parameter witout any integer value after that, because any +digit following @option{-} in the parameter string of the @option{-gnaty} +option will be threated as canceling indentation check. The same is true +for @option{M} parameter. @option{y} and @option{N} parameters are not +allowed after @option{-}. + +@item + +This causes any subsequent options in the string to enable the corresponding +style check option. That is, it cancels the effect of a previous ^-^REMOVE^, +if any. +@end ifclear + +@ifset vms +@item NOxxx +@emph{Removing style check options} +If the name of a style check is preceded by @option{NO} then the corresponding +style check is turned off. For example @option{NOCOMMENTS} turns off style +checking for comments. +@end ifset +@end table + +@noindent +In the above rules, appearing in column one is always permitted, that is, +counts as meeting either a requirement for a required preceding space, +or as meeting a requirement for no preceding space. + +Appearing at the end of a line is also always permitted, that is, counts +as meeting either a requirement for a following space, or as meeting +a requirement for no following space. + +@noindent +If any of these style rules is violated, a message is generated giving +details on the violation. The initial characters of such messages are +always ``@code{(style)}''. Note that these messages are treated as warning +messages, so they normally do not prevent the generation of an object +file. The @option{-gnatwe} switch can be used to treat warning messages, +including style messages, as fatal errors. + +The switch +@ifclear vms +@option{-gnaty} on its own (that is not +followed by any letters or digits), then the effect is equivalent +to the use of @option{-gnatyy}, as described above, that is all +built-in standard style check options are enabled. + +@end ifclear +@ifset vms +/STYLE_CHECKS=ALL_BUILTIN enables all checking options with +the exception of ORDERED_SUBPROGRAMS, UNNECESSARY_BLANK_LINES, +XTRA_PARENS, and DOS_LINE_ENDINGS. In addition +@end ifset + +The switch +@ifclear vms +@option{-gnatyN} +@end ifclear +@ifset vms +/STYLE_CHECKS=NONE +@end ifset +clears any previously set style checks. + +@node Run-Time Checks +@subsection Run-Time Checks +@cindex Division by zero +@cindex Access before elaboration +@cindex Checks, division by zero +@cindex Checks, access before elaboration +@cindex Checks, stack overflow checking + +@noindent +By default, the following checks are suppressed: integer overflow +checks, stack overflow checks, and checks for access before +elaboration on subprogram calls. All other checks, including range +checks and array bounds checks, are turned on by default. The +following @command{gcc} switches refine this default behavior. + +@table @option +@c !sort! +@item -gnatp +@cindex @option{-gnatp} (@command{gcc}) +@cindex Suppressing checks +@cindex Checks, suppressing +@findex Suppress +This switch causes the unit to be compiled +as though @code{pragma Suppress (All_checks)} +had been present in the source. Validity checks are also eliminated (in +other words @option{-gnatp} also implies @option{-gnatVn}. +Use this switch to improve the performance +of the code at the expense of safety in the presence of invalid data or +program bugs. + +Note that when checks are suppressed, the compiler is allowed, but not +required, to omit the checking code. If the run-time cost of the +checking code is zero or near-zero, the compiler will generate it even +if checks are suppressed. In particular, if the compiler can prove +that a certain check will necessarily fail, it will generate code to +do an unconditional ``raise'', even if checks are suppressed. The +compiler warns in this case. Another case in which checks may not be +eliminated is when they are embedded in certain run time routines such +as math library routines. + +Of course, run-time checks are omitted whenever the compiler can prove +that they will not fail, whether or not checks are suppressed. + +Note that if you suppress a check that would have failed, program +execution is erroneous, which means the behavior is totally +unpredictable. The program might crash, or print wrong answers, or +do anything else. It might even do exactly what you wanted it to do +(and then it might start failing mysteriously next week or next +year). The compiler will generate code based on the assumption that +the condition being checked is true, which can result in disaster if +that assumption is wrong. + +The @option{-gnatp} switch has no effect if a subsequent +@option{-gnat-p} switch appears. + +@item -gnat-p +@cindex @option{-gnat-p} (@command{gcc}) +@cindex Suppressing checks +@cindex Checks, suppressing +@findex Suppress +This switch cancels the effect of a previous @option{gnatp} switch. + +@item -gnato +@cindex @option{-gnato} (@command{gcc}) +@cindex Overflow checks +@cindex Check, overflow +Enables overflow checking for integer operations. +This causes GNAT to generate slower and larger executable +programs by adding code to check for overflow (resulting in raising +@code{Constraint_Error} as required by standard Ada +semantics). These overflow checks correspond to situations in which +the true value of the result of an operation may be outside the base +range of the result type. The following example shows the distinction: + +@smallexample @c ada +X1 : Integer := "Integer'Last"; +X2 : Integer range 1 .. 5 := "5"; +X3 : Integer := "Integer'Last"; +X4 : Integer range 1 .. 5 := "5"; +F : Float := "2.0E+20"; +@dots{} +X1 := X1 + 1; +X2 := X2 + 1; +X3 := Integer (F); +X4 := Integer (F); +@end smallexample + +@noindent +Note that if explicit values are assigned at compile time, the +compiler may be able to detect overflow at compile time, in which case +no actual run-time checking code is required, and Constraint_Error +will be raised unconditionally, with or without +@option{-gnato}. That's why the assigned values in the above fragment +are in quotes, the meaning is "assign a value not known to the +compiler that happens to be equal to ...". The remaining discussion +assumes that the compiler cannot detect the values at compile time. + +Here the first addition results in a value that is outside the base range +of Integer, and hence requires an overflow check for detection of the +constraint error. Thus the first assignment to @code{X1} raises a +@code{Constraint_Error} exception only if @option{-gnato} is set. + +The second increment operation results in a violation of the explicit +range constraint; such range checks are performed by default, and are +unaffected by @option{-gnato}. + +The two conversions of @code{F} both result in values that are outside +the base range of type @code{Integer} and thus will raise +@code{Constraint_Error} exceptions only if @option{-gnato} is used. +The fact that the result of the second conversion is assigned to +variable @code{X4} with a restricted range is irrelevant, since the problem +is in the conversion, not the assignment. + +Basically the rule is that in the default mode (@option{-gnato} not +used), the generated code assures that all integer variables stay +within their declared ranges, or within the base range if there is +no declared range. This prevents any serious problems like indexes +out of range for array operations. + +What is not checked in default mode is an overflow that results in +an in-range, but incorrect value. In the above example, the assignments +to @code{X1}, @code{X2}, @code{X3} all give results that are within the +range of the target variable, but the result is wrong in the sense that +it is too large to be represented correctly. Typically the assignment +to @code{X1} will result in wrap around to the largest negative number. +The conversions of @code{F} will result in some @code{Integer} value +and if that integer value is out of the @code{X4} range then the +subsequent assignment would generate an exception. + +@findex Machine_Overflows +Note that the @option{-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 @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). + +The reason that we distinguish overflow checking from other kinds of +range constraint checking is that a failure of an overflow check, unlike +for example the failure of a range check, can result in an incorrect +value, but cannot cause random memory destruction (like an out of range +subscript), or a wild jump (from an out of range case value). Overflow +checking is also quite expensive in time and space, since in general it +requires the use of double length arithmetic. + +Note again that @option{-gnato} is off by default, so overflow checking is +not performed in default mode. This means that out of the box, with the +default settings, GNAT does not do all the checks expected from the +language description in the Ada Reference Manual. If you want all constraint +checks to be performed, as described in this Manual, then you must +explicitly use the -gnato switch either on the @command{gnatmake} or +@command{gcc} command. + +@item -gnatE +@cindex @option{-gnatE} (@command{gcc}) +@cindex Elaboration checks +@cindex Check, elaboration +Enables dynamic checks for access-before-elaboration +on subprogram calls and generic instantiations. +Note that @option{-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, +@xref{Compiling Using gcc}. + +@item -fstack-check +@cindex @option{-fstack-check} (@command{gcc}) +@cindex Stack Overflow Checking +@cindex Checks, stack overflow checking +Activates stack overflow checking. For full details of the effect and use of +this switch see @ref{Stack Overflow Checking}. +@end table + +@findex Unsuppress +@noindent +The setting of these switches only controls the default setting of the +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 +@subsection Using @command{gcc} for Syntax Checking +@table @option +@item -gnats +@cindex @option{-gnats} (@command{gcc}) +@ifclear vms + +@noindent +The @code{s} stands for ``syntax''. +@end ifclear + +Run GNAT in syntax checking only mode. For +example, the command + +@smallexample +$ gcc -c -gnats x.adb +@end smallexample + +@noindent +compiles file @file{x.adb} in syntax-check-only mode. You can check a +series of files in a single command +@ifclear vms +, and can use wild cards to specify such a group of files. +Note that you must specify the @option{-c} (compile +only) flag in addition to the @option{-gnats} flag. +@end ifclear +. +You may use other switches in conjunction with @option{-gnats}. In +particular, @option{-gnatl} and @option{-gnatv} are useful to control the +format of any generated error messages. + +When the source file is empty or contains only empty lines and/or comments, +the output is a warning: + +@smallexample +$ gcc -c -gnats -x ada toto.txt +toto.txt:1:01: warning: empty file, contains no compilation units +$ +@end smallexample + +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 @code{X} +@code{with}'s a unit @code{Y}, compiling unit @code{X} in syntax +check only mode does not access the source file containing unit +@code{Y}. + +@cindex Multiple units, syntax checking +Normally, GNAT allows only a single unit in a source file. However, this +restriction does not apply in syntax-check-only mode, and it is possible +to check a file containing multiple compilation units concatenated +together. This is primarily used by the @code{gnatchop} utility +(@pxref{Renaming Files Using gnatchop}). +@end table + +@node Using gcc for Semantic Checking +@subsection Using @command{gcc} for Semantic Checking +@table @option +@item -gnatc +@cindex @option{-gnatc} (@command{gcc}) + +@ifclear vms +@noindent +The @code{c} stands for ``check''. +@end ifclear +Causes the compiler to operate in semantic check mode, +with full checking for all illegalities specified in the +Ada Reference Manual, but without generation of any object code +(no object file is generated). + +Because dependent files must be accessed, you must follow the GNAT +semantic restrictions on file structuring to operate in this mode: + +@itemize @bullet +@item +The needed source files must be accessible +(@pxref{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 (@pxref{File Naming Rules}). +@end itemize + +The output consists of error messages as appropriate. No object file is +generated. An @file{ALI} file is generated for use in the context of +cross-reference tools, but this file is marked as not being suitable +for binding (since no object file is generated). +The checking corresponds exactly to the notion of +legality in the Ada Reference Manual. + +Any unit can be compiled in semantics-checking-only mode, including +units that would not normally be compiled (subunits, +and specifications where a separate body is present). +@end table + +@node Compiling Different Versions of Ada +@subsection Compiling Different Versions of Ada + +@noindent +The switches described in this section allow you to explicitly specify +the version of the Ada language that your programs are written in. +By default @value{EDITION} assumes @value{DEFAULTLANGUAGEVERSION}, +but you can also specify @value{NONDEFAULTLANGUAGEVERSION} or +indicate Ada 83 compatibility mode. + +@table @option +@cindex Compatibility with Ada 83 + +@item -gnat83 (Ada 83 Compatibility Mode) +@cindex @option{-gnat83} (@command{gcc}) +@cindex ACVC, Ada 83 tests +@cindex Ada 83 mode + +@noindent +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 +@option{-gnat83}, GNAT rejects most post-Ada 83 extensions and applies Ada 83 +semantics where this can be done easily. +It is not possible to guarantee this switch does a perfect +job; some subtle tests, such as are +found in earlier ACVC tests (and that have been removed from the ACATS suite +for Ada 95), might not compile correctly. +Nevertheless, this switch may be useful in some circumstances, for example +where, due to contractual reasons, existing code needs to be maintained +using only Ada 83 features. + +With few exceptions (most notably the need to use @code{<>} on +@cindex Generic formal parameters +unconstrained generic formal parameters, the use of the new Ada 95 / Ada 2005 +reserved words, and the use of packages +with optional bodies), it is not necessary to specify the +@option{-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 @ref{Compatibility and Porting Guide}. + +@item -gnat95 (Ada 95 mode) +@cindex @option{-gnat95} (@command{gcc}) +@cindex Ada 95 mode + +@noindent +This switch directs the compiler to implement the Ada 95 version of the +language. +Since Ada 95 is almost completely upwards +compatible with Ada 83, Ada 83 programs may generally be compiled using +this switch (see the description of the @option{-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 +@option{-gnat83}, @option{-gnat05/2005}, or @option{-gnat12/2012} +switch earlier in the command line. + +@item -gnat05 or -gnat2005 (Ada 2005 mode) +@cindex @option{-gnat05} (@command{gcc}) +@cindex @option{-gnat2005} (@command{gcc}) +@cindex Ada 2005 mode + +@noindent +This switch directs the compiler to implement the Ada 2005 version of the +language, as documented in the official Ada standards document. +Since Ada 2005 is almost completely upwards +compatible with Ada 95 (and thus also with Ada 83), Ada 83 and Ada 95 programs +may generally be compiled using this switch (see the description of the +@option{-gnat83} and @option{-gnat95} switches for further +information). + +@ifset PROEDITION +Note that even though Ada 2005 is the current official version of the +language, GNAT still compiles in Ada 95 mode by default, so if you are +using Ada 2005 features in your program, you must use this switch (or +the equivalent Ada_05 or Ada_2005 configuration pragmas). +@end ifset + +@item -gnat12 or -gnat2012 (Ada 2012 mode) +@cindex @option{-gnat12} (@command{gcc}) +@cindex @option{-gnat2012} (@command{gcc}) +@cindex Ada 2012 mode + +@noindent +This switch directs the compiler to implement the Ada 2012 version of the +language. +Since Ada 2012 is almost completely upwards +compatible with Ada 2005 (and thus also with Ada 83, and Ada 95), +Ada 83 and Ada 95 programs +may generally be compiled using this switch (see the description of the +@option{-gnat83}, @option{-gnat95}, and @option{-gnat05/2005} switches +for further information). + +For information about the approved ``Ada Issues'' that have been incorporated +into Ada 2012, see @url{http://www.ada-auth.org/ais.html}. +Included with GNAT releases is a file @file{features-ada12} that describes +the set of implemented Ada 2012 features. + +@item -gnatX (Enable GNAT Extensions) +@cindex @option{-gnatX} (@command{gcc}) +@cindex Ada language extensions +@cindex GNAT extensions + +@noindent +This switch directs the compiler to implement the latest version of the +language (currently Ada 2012) and also to enable certain GNAT implementation +extensions that are not part of any Ada standard. For a full list of these +extensions, see the GNAT reference manual. + +@end table + +@node Character Set Control +@subsection Character Set Control +@table @option +@item ^-gnati^/IDENTIFIER_CHARACTER_SET=^@var{c} +@cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@command{gcc}) + +@noindent +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. @var{c} is a +single character ^^or word^ indicating the character set, as follows: + +@table @code +@item 1 +ISO 8859-1 (Latin-1) identifiers + +@item 2 +ISO 8859-2 (Latin-2) letters allowed in identifiers + +@item 3 +ISO 8859-3 (Latin-3) letters allowed in identifiers + +@item 4 +ISO 8859-4 (Latin-4) letters allowed in identifiers + +@item 5 +ISO 8859-5 (Cyrillic) letters allowed in identifiers + +@item 9 +ISO 8859-15 (Latin-9) letters allowed in identifiers + +@item ^p^PC^ +IBM PC letters (code page 437) allowed in identifiers + +@item ^8^PC850^ +IBM PC letters (code page 850) allowed in identifiers + +@item ^f^FULL_UPPER^ +Full upper-half codes allowed in identifiers + +@item ^n^NO_UPPER^ +No upper-half codes allowed in identifiers + +@item ^w^WIDE^ +Wide-character codes (that is, codes greater than 255) +allowed in identifiers +@end table + +@xref{Foreign Language Representation}, for full details on the +implementation of these character sets. + +@item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e} +@cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc}) +Specify the method of encoding for wide characters. +@var{e} is one of the following: + +@table @code + +@item ^h^HEX^ +Hex encoding (brackets coding also recognized) + +@item ^u^UPPER^ +Upper half encoding (brackets encoding also recognized) + +@item ^s^SHIFT_JIS^ +Shift/JIS encoding (brackets encoding also recognized) + +@item ^e^EUC^ +EUC encoding (brackets encoding also recognized) + +@item ^8^UTF8^ +UTF-8 encoding (brackets encoding also recognized) + +@item ^b^BRACKETS^ +Brackets encoding only (default value) +@end table +For full details on these encoding +methods see @ref{Wide Character Encodings}. +Note that brackets coding is always accepted, even if one of the other +options is specified, so for example @option{-gnatW8} specifies that both +brackets and UTF-8 encodings will be recognized. The units that are +with'ed directly or indirectly will be scanned using the specified +representation scheme, and so if one of the non-brackets scheme is +used, it must be used consistently throughout the program. However, +since brackets encoding is always recognized, it may be conveniently +used in standard libraries, allowing these libraries to be used with +any of the available coding schemes. +scheme. + +If no @option{-gnatW?} parameter is present, then the default +representation is normally Brackets encoding only. However, if the +first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard +byte order mark or BOM for UTF-8), then these three characters are +skipped and the default representation for the file is set to UTF-8. + +Note that the wide character representation that is specified (explicitly +or by default) for the main program also acts as the default encoding used +for Wide_Text_IO files if not specifically overridden by a WCEM form +parameter. + +@end table +@node File Naming Control +@subsection File Naming Control + +@table @option +@item ^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{n} +@cindex @option{-gnatk} (@command{gcc}) +Activates file name ``krunching''. @var{n}, a decimal integer in the range +1-999, indicates the maximum allowable length of a file name (not +including the @file{.ads} or @file{.adb} extension). The default is not +to enable file name krunching. + +For the source file naming rules, @xref{File Naming Rules}. +@end table + +@node Subprogram Inlining Control +@subsection Subprogram Inlining Control + +@table @option +@c !sort! +@item -gnatn +@cindex @option{-gnatn} (@command{gcc}) +@ifclear vms +The @code{n} here is intended to suggest the first syllable of the +word ``inline''. +@end ifclear +GNAT recognizes and processes @code{Inline} pragmas. However, for the +inlining to actually occur, optimization must be enabled. To enable +inlining of subprograms specified by pragma @code{Inline}, +you must also specify this switch. +In the absence of this switch, GNAT does not attempt +inlining and does not need to access the bodies of +subprograms for which @code{pragma Inline} is specified if they are not +in the current unit. + +If you specify this switch the compiler will access these bodies, +creating an extra source dependency for the resulting object file, and +where possible, the call will be inlined. +For further details on when inlining is possible +see @ref{Inlining of Subprograms}. + +@item -gnatN +@cindex @option{-gnatN} (@command{gcc}) +This switch activates front-end inlining which also +generates additional dependencies. + +When using a gcc-based back end (in practice this means using any version +of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of +@option{-gnatN} is deprecated, and the use of @option{-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 +@subsection Auxiliary Output Control + +@table @option +@item -gnatt +@cindex @option{-gnatt} (@command{gcc}) +@cindex Writing internal trees +@cindex Internal trees, writing to file +Causes GNAT to write the internal tree for a unit to a file (with the +extension @file{.adt}. +This not normally required, but is used by separate analysis tools. +Typically +these tools do the necessary compilations automatically, so you should +not have to specify this switch in normal operation. +Note that the combination of switches @option{-gnatct} +generates a tree in the form required by ASIS applications. + +@item -gnatu +@cindex @option{-gnatu} (@command{gcc}) +Print a list of units required by this compilation on @file{stdout}. +The listing includes all units on which the unit being compiled depends +either directly or indirectly. + +@ifclear vms +@item -pass-exit-codes +@cindex @option{-pass-exit-codes} (@command{gcc}) +If this switch is not used, the exit code returned by @command{gcc} when +compiling multiple files indicates whether all source files have +been successfully used to generate object files or not. + +When @option{-pass-exit-codes} is used, @command{gcc} exits with an extended +exit status and allows an integrated development environment to better +react to a compilation failure. Those exit status are: + +@table @asis +@item 5 +There was an error in at least one source file. +@item 3 +At least one source file did not generate an object file. +@item 2 +The compiler died unexpectedly (internal error for example). +@item 0 +An object file has been generated for every source file. +@end table +@end ifclear +@end table + +@node Debugging Control +@subsection Debugging Control + +@table @option +@c !sort! +@cindex Debugging options +@ifclear vms +@item -gnatd@var{x} +@cindex @option{-gnatd} (@command{gcc}) +Activate internal debugging switches. @var{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 @code{Debug} unit in the compiler source +file @file{debug.adb}. +@end ifclear + +@item -gnatG[=nn] +@cindex @option{-gnatG} (@command{gcc}) +This switch causes the compiler to generate auxiliary output containing +a pseudo-source listing of the generated expanded code. Like most Ada +compilers, GNAT works by first transforming the high level Ada code into +lower level constructs. For example, tasking operations are transformed +into calls to the tasking run-time routines. A unique capability of GNAT +is to list this expanded code in a form very close to normal Ada source. +This is very useful in understanding the implications of various Ada +usage on the efficiency of the generated code. There are many cases in +Ada (e.g.@: the use of controlled types), where simple Ada statements can +generate a lot of run-time code. By using @option{-gnatG} you can identify +these cases, and consider whether it may be desirable to modify the coding +approach to improve efficiency. + +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. + +The format of the output is very similar to standard Ada source, and is +easily understood by an Ada programmer. The following special syntactic +additions correspond to low level features used in the generated code that +do not have any exact analogies in pure Ada source form. The following +is a partial list of these special constructions. See the spec +of package @code{Sprint} in file @file{sprint.ads} for a full list. + +If the switch @option{-gnatL} is used in conjunction with +@cindex @option{-gnatL} (@command{gcc}) +@option{-gnatG}, then the original source lines are interspersed +in the expanded source (as comment lines with the original line number). + +@table @code +@item new @var{xxx} @r{[}storage_pool = @var{yyy}@r{]} +Shows the storage pool being used for an allocator. + +@item at end @var{procedure-name}; +Shows the finalization (cleanup) procedure for a scope. + +@item (if @var{expr} then @var{expr} else @var{expr}) +Conditional expression equivalent to the @code{x?y:z} construction in C. + +@item @var{target}^^^(@var{source}) +A conversion with floating-point truncation instead of rounding. + +@item @var{target}?(@var{source}) +A conversion that bypasses normal Ada semantic checking. In particular +enumeration types and fixed-point types are treated simply as integers. + +@item @var{target}?^^^(@var{source}) +Combines the above two cases. + +@item @var{x} #/ @var{y} +@itemx @var{x} #mod @var{y} +@itemx @var{x} #* @var{y} +@itemx @var{x} #rem @var{y} +A division or multiplication of fixed-point values which are treated as +integers without any kind of scaling. + +@item free @var{expr} @r{[}storage_pool = @var{xxx}@r{]} +Shows the storage pool associated with a @code{free} statement. + +@item [subtype or type declaration] +Used to list an equivalent declaration for an internally generated +type that is referenced elsewhere in the listing. + +@c @item freeze @var{type-name} @ovar{actions} +@c Expanding @ovar macro inline (explanation in macro def comments) +@item freeze @var{type-name} @r{[}@var{actions}@r{]} +Shows the point at which @var{type-name} is frozen, with possible +associated actions to be performed at the freeze point. + +@item reference @var{itype} +Reference (and hence definition) to internal type @var{itype}. + +@item @var{function-name}! (@var{arg}, @var{arg}, @var{arg}) +Intrinsic function call. + +@item @var{label-name} : label +Declaration of label @var{labelname}. + +@item #$ @var{subprogram-name} +An implicit call to a run-time support routine +(to meet the requirement of H.3.1(9) in a +convenient manner). + +@item @var{expr} && @var{expr} && @var{expr} @dots{} && @var{expr} +A multiple concatenation (same effect as @var{expr} & @var{expr} & +@var{expr}, but handled more efficiently). + +@item [constraint_error] +Raise the @code{Constraint_Error} exception. + +@item @var{expression}'reference +A pointer to the result of evaluating @var{expression}. + +@item @var{target-type}!(@var{source-expression}) +An unchecked conversion of @var{source-expression} to @var{target-type}. + +@item [@var{numerator}/@var{denominator}] +Used to represent internal real literals (that) have no exact +representation in base 2-16 (for example, the result of compile time +evaluation of the expression 1.0/27.0). +@end table + +@item -gnatD[=nn] +@cindex @option{-gnatD} (@command{gcc}) +When used in conjunction with @option{-gnatG}, this switch causes +the expanded source, as described above for +@option{-gnatG} to be written to files with names +@file{^xxx.dg^XXX_DG^}, where @file{xxx} is the normal file name, +instead of to the standard output file. For +example, if the source file name is @file{hello.adb}, then a file +@file{^hello.adb.dg^HELLO.ADB_DG^} will be written. The debugging +information generated by the @command{gcc} @option{^-g^/DEBUG^} switch +will refer to the generated @file{^xxx.dg^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 +@option{-gnatx}) since otherwise the cross-reference information +would refer to the @file{^.dg^.DG^} file, which would cause +confusion since this is not the original source file. + +Note that @option{-gnatD} actually implies @option{-gnatG} +automatically, so it is not necessary to give both options. +In other words @option{-gnatD} is equivalent to @option{-gnatDG}). + +If the switch @option{-gnatL} is used in conjunction with +@cindex @option{-gnatL} (@command{gcc}) +@option{-gnatDG}, then the original source lines are interspersed +in the expanded source (as comment lines with the original line number). + +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. + +@item -gnatr +@cindex @option{-gnatr} (@command{gcc}) +@cindex pragma Restrictions +This switch causes pragma Restrictions to be treated as Restriction_Warnings +so that violation of restrictions causes warnings rather than illegalities. +This is useful during the development process when new restrictions are added +or investigated. The switch also causes pragma Profile to be treated as +Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set +restriction warnings rather than restrictions. + +@ifclear vms +@item -gnatR@r{[}0@r{|}1@r{|}2@r{|}3@r{[}s@r{]]} +@cindex @option{-gnatR} (@command{gcc}) +This switch controls output from the compiler of a listing showing +representation information for declared types and objects. For +@option{-gnatR0}, no information is output (equivalent to omitting +the @option{-gnatR} switch). For @option{-gnatR1} (which is the default, +so @option{-gnatR} with no parameter has the same effect), size and alignment +information is listed for declared array and record types. For +@option{-gnatR2}, size and alignment information is listed for all +declared types and objects. Finally @option{-gnatR3} includes symbolic +expressions for values that are computed at run time for +variant records. These symbolic expressions have a mostly obvious +format with #n being used to represent the value of the n'th +discriminant. See source files @file{repinfo.ads/adb} in the +@code{GNAT} sources for full details on the format of @option{-gnatR3} +output. If the switch is followed by an s (e.g.@: @option{-gnatR2s}), then +the output is to a file with the name @file{^file.rep^file_REP^} where +file is the name of the corresponding source file. +@end ifclear +@ifset vms +@item /REPRESENTATION_INFO +@cindex @option{/REPRESENTATION_INFO} (@command{gcc}) +This qualifier controls output from the compiler of a listing showing +representation information for declared types and objects. For +@option{/REPRESENTATION_INFO=NONE}, no information is output +(equivalent to omitting the @option{/REPRESENTATION_INFO} qualifier). +@option{/REPRESENTATION_INFO} without option is equivalent to +@option{/REPRESENTATION_INFO=ARRAYS}. +For @option{/REPRESENTATION_INFO=ARRAYS}, size and alignment +information is listed for declared array and record types. For +@option{/REPRESENTATION_INFO=OBJECTS}, size and alignment information +is listed for all expression information for values that are computed +at run time for variant records. These symbolic expressions have a mostly +obvious format with #n being used to represent the value of the n'th +discriminant. See source files @file{REPINFO.ADS/ADB} in the +@code{GNAT} sources for full details on the format of +@option{/REPRESENTATION_INFO=SYMBOLIC} output. +If _FILE is added at the end of an option +(e.g.@: @option{/REPRESENTATION_INFO=ARRAYS_FILE}), +then the output is to a file with the name @file{file_REP} where +file is the name of the corresponding source file. +@end ifset +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 @code{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. + +@item -gnatS +@cindex @option{-gnatS} (@command{gcc}) +The use of the switch @option{-gnatS} for an +Ada compilation will cause the compiler to output a +representation of package Standard in a form very +close to standard Ada. It is not quite possible to +do this entirely in standard Ada (since new +numeric base types cannot be created in standard +Ada), but the output is easily +readable to any Ada programmer, and is useful to +determine the characteristics of target dependent +types in package Standard. + +@item -gnatx +@cindex @option{-gnatx} (@command{gcc}) +Normally the compiler generates full cross-referencing information in +the @file{ALI} file. This information is used by a number of tools, +including @code{gnatfind} and @code{gnatxref}. The @option{-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 + +@node Exception Handling Control +@subsection Exception Handling Control + +@noindent +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 propagation, but introduces significant overhead for +the use of exception handlers, even if no exception is raised. + +The other approach is called ``zero cost'' exception handling. +With this method, the compiler builds static tables to describe +the exception ranges. No dynamic code is required when entering +a frame containing an exception handler. When an exception is +raised, the tables are used to control a back trace of the +subprogram invocation stack to locate the required exception +handler. This method has considerably poorer performance for +the propagation of exceptions, but there is no overhead for +exception handlers if no exception is raised. Note that in this +mode and in the context of mixed Ada and C/C++ programming, +to propagate an exception through a C/C++ code, the C/C++ code +must be compiled with the @option{-funwind-tables} GCC's +option. + +The following switches may be used to control which of the +two exception handling methods is used. + +@table @option +@c !sort! + +@item --RTS=sjlj +@cindex @option{--RTS=sjlj} (@command{gnatmake}) +This switch causes the setjmp/longjmp run-time (when available) to be used +for exception handling. If the default +mechanism for the target is zero cost exceptions, then +this switch can be used to modify this default, and must be +used for all units in the partition. +This option is rarely used. One case in which it may be +advantageous is if you have an application where exception +raising is common and the overall performance of the +application is improved by favoring exception propagation. + +@item --RTS=zcx +@cindex @option{--RTS=zcx} (@command{gnatmake}) +@cindex Zero Cost Exceptions +This switch causes the zero cost approach to be used +for exception handling. If this is the default mechanism for the +target (see below), then this switch is unneeded. If the default +mechanism for the target is setjmp/longjmp exceptions, then +this switch can be used to modify this default, and must be +used for all units in the partition. +This option can only be used if the zero cost approach +is available for the target in use, otherwise it will generate an error. +@end table + +@noindent +The same option @option{--RTS} must be used both for @command{gcc} +and @command{gnatbind}. Passing this option to @command{gnatmake} +(@pxref{Switches for gnatmake}) will ensure the required consistency +through the compilation and binding steps. + +@node Units to Sources Mapping Files +@subsection Units to Sources Mapping Files + +@table @option + +@item -gnatem=@var{path} +@cindex @option{-gnatem} (@command{gcc}) +A mapping file is a way to communicate to the compiler two mappings: +from unit names to file names (without any directory information) and from +file names to path names (with full directory information). These mappings +are used by the compiler to short-circuit the path search. + +The use of mapping files is not required for correct operation of the +compiler, but mapping files can improve efficiency, particularly when +sources are read over a slow network connection. In normal operation, +you need not be concerned with the format or use of mapping files, +and the @option{-gnatem} switch is not a switch that you would use +explicitly. It is intended primarily for use by automatic tools such as +@command{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 @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: +@smallexample + main%b + main.2.ada + /gnat/project1/sources/main.2.ada +@end smallexample + +When the switch @option{-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 @option{-gnatem} switches may be specified; however, only the +last one on the command line will be taken into account. + +When using a project file, @command{gnatmake} creates a temporary +mapping file and communicates it to the compiler using this switch. + +@end table + +@node Integrated Preprocessing +@subsection Integrated Preprocessing + +@noindent +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 @option{-gnatep} and/or @option{-gnateD}. @option{-gnatep} +indicates, through a text file, the preprocessing data to be used. +@option{-gnateD} specifies or modifies the values of preprocessing symbol. + +@noindent +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 @command{gnatprep} +to perform the desired preprocessing in stand-alone mode. + +@noindent +It is recommended that @command{gnatmake} switch ^-s^/SWITCH_CHECK^ 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. + +@noindent +Note that @command{gnatmake} switch ^-m^/MINIMAL_RECOMPILATION^ will almost +always trigger recompilation for sources that are preprocessed, +because @command{gnatmake} cannot compute the checksum of the source after +preprocessing. + +@noindent +The actual preprocessing function is described in details in section +@ref{Preprocessing Using gnatprep}. This section only describes how integrated +preprocessing is triggered and parameterized. + +@table @code + +@item -gnatep=@var{file} +@cindex @option{-gnatep} (@command{gcc}) +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. + +@noindent +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. + +@noindent +Each significant line starts with either a literal string or the character '*'. +A literal string is the file name (without directory information) of the source +to preprocess. A character '*' indicates the preprocessing for all the sources +that are not specified explicitly on other lines (order of the lines is not +significant). It is an error to have two lines with the same file name or two +lines starting with the character '*'. + +@noindent +After the file name or the character '*', another optional literal string +indicating the file name of the definition file to be used for preprocessing +(@pxref{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.^/SEARCH=[]^, otherwise +the compiler would not find the definition file. + +@noindent +Then, optionally, ^switches^switches^ similar to those of @code{gnatprep} may +be found. Those ^switches^switches^ are: + +@table @code + +@item -b +Causes both preprocessor lines and the lines deleted by +preprocessing to be replaced by blank lines, preserving the line number. +This ^switch^switch^ is always implied; however, if specified after @option{-c} +it cancels the effect of @option{-c}. + +@item -c +Causes both preprocessor lines and the lines deleted +by preprocessing to be retained as comments marked +with the special string ``@code{--! }''. + +@item -Dsymbol=value +Define or redefine a symbol, associated with value. A symbol is an Ada +identifier, or an Ada reserved word, with the exception of @code{if}, +@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. +@code{value} is either a literal string, an Ada identifier or any Ada reserved +word. A symbol declared with this ^switch^switch^ replaces a symbol with the +same name defined in a definition file. + +@item -s +Causes a sorted list of symbol names and values to be +listed on the standard output file. + +@item -u +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 @code{#if} or @code{#elsif} test will be treated as an error. + +@end table + +@noindent +Examples of valid lines in a preprocessor data file: + +@smallexample + "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 smallexample + +@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=value@r{]} +@cindex @option{-gnateD} (@command{gcc}) +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 @code{True}. +A symbol is an identifier, following normal Ada (case-insensitive) +rules for its syntax, and value is 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 @code{if}, +@code{else}, @code{elsif}, @code{end}, @code{and}, @code{or} and @code{then}. + +@noindent +A symbol declared with this ^switch^switch^ on the command line replaces a +symbol with the same name either in a definition file or specified with a +^switch^switch^ -D in the preprocessor data file. + +@noindent +This switch is similar to switch @option{^-D^/ASSOCIATE^} of @code{gnatprep}. + +@item -gnateG +When integrated preprocessing is performed and the preprocessor modifies +the source text, write the result of this preprocessing into a file +^.prep^_prep^. + +@end table + +@node Code Generation Control +@subsection Code Generation Control + +@noindent + +The GCC technology provides a wide range of target dependent +@option{-m} switches for controlling +details of code generation with respect to different versions of +architectures. This includes variations in instruction sets (e.g.@: +different members of the power pc family), and different requirements +for optimal arrangement of instructions (e.g.@: different members of +the x86 family). The list of available @option{-m} switches may be +found in the GCC documentation. + +Use of these @option{-m} switches may in some cases result in improved +code performance. + +The GNAT Pro technology is tested and qualified without any +@option{-m} switches, +so generally the most reliable approach is to avoid the use of these +switches. However, we generally expect most of these switches to work +successfully with GNAT Pro, and many customers have reported successful +use of these options. + +Our general advice is to avoid the use of @option{-m} switches unless +special needs lead to requirements in this area. In particular, +there is no point in using @option{-m} switches to improve performance +unless you actually see a performance improvement. + +@ifset vms +@node Return Codes +@subsection Return Codes +@cindex Return Codes +@cindex @option{/RETURN_CODES=VMS} + +@noindent +On VMS, GNAT compiled programs return POSIX-style codes by default, +e.g.@: @option{/RETURN_CODES=POSIX}. + +To enable VMS style return codes, use GNAT BIND and LINK with the option +@option{/RETURN_CODES=VMS}. For example: + +@smallexample +GNAT BIND MYMAIN.ALI /RETURN_CODES=VMS +GNAT LINK MYMAIN.ALI /RETURN_CODES=VMS +@end smallexample + +@noindent +Programs built with /RETURN_CODES=VMS are suitable to be called in +VMS DCL scripts. Programs compiled with the default /RETURN_CODES=POSIX +are suitable for spawning with appropriate GNAT RTL routines. + +@end ifset + +@node Search Paths and the Run-Time Library (RTL) +@section Search Paths and the Run-Time Library (RTL) + +@noindent +With the GNAT source-based library system, the compiler must be able to +find source files for units that are needed by the unit being compiled. +Search paths are used to guide this process. + +The compiler compiles one source file whose name must be given +explicitly on the command line. In other words, no searching is done +for this file. To find all other source files that are needed (the most +common being the specs of units), the compiler examines the following +directories, in the following order: + +@enumerate +@item +The directory containing the source file of the main unit being compiled +(the file name on the command line). + +@item +Each directory named by an @option{^-I^/SOURCE_SEARCH^} switch given on the +@command{gcc} command line, in the order given. + +@item +@findex ADA_PRJ_INCLUDE_FILE +Each of the directories listed in the text file whose name is given +by the @env{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^. + +@noindent +@env{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^ +driver when project files are used. It should not normally be set +by other means. + +@item +@findex ADA_INCLUDE_PATH +Each of the directories listed in the value of the +@env{ADA_INCLUDE_PATH} ^environment variable^logical name^. +@ifclear vms +Construct this value +exactly as the @env{PATH} environment variable: a list of directory +names separated by colons (semicolons when working with the NT version). +@end ifclear +@ifset vms +Normally, define this value as a logical name containing a comma separated +list of directory names. + +This variable can also be defined by means of an environment string +(an argument to the HP C exec* set of functions). + +Logical Name: +@smallexample +DEFINE ANOTHER_PATH FOO:[BAG] +DEFINE ADA_INCLUDE_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] +@end smallexample + +By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] +first, followed by the standard Ada +libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADAINCLUDE]. +If this is not redefined, the user will obtain the HP Ada 83 IO packages +(Text_IO, Sequential_IO, etc) +instead of the standard Ada packages. Thus, in order to get the standard Ada +packages by default, ADA_INCLUDE_PATH must be redefined. +@end ifset + +@item +The content of the @file{ada_source_path} file which is part of the GNAT +installation tree and is used to store standard libraries such as the +GNAT Run Time Library (RTL) source files. +@ifclear vms +@ref{Installing a library} +@end ifclear +@end enumerate + +@noindent +Specifying the switch @option{^-I-^/NOCURRENT_DIRECTORY^} +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 @option{^-I^/SOURCE_SEARCH^} switch. + +Specifying the switch @option{-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. +@ifclear vms +Caution: The object file can be redirected with the @option{-o} switch; +however, @command{gcc} and @code{gnat1} have not been coordinated on this +so the @file{ALI} file will not go to the right place. Therefore, you should +avoid using the @option{-o} switch. +@end ifclear + +@findex System.IO +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 (@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. @xref{Top, GNAT Reference Manual, About +This Guid, gnat_rm, GNAT Reference Manual}, for further details. + +Besides simplifying access to the RTL, a major use of search paths is +in compiling sources from multiple directories. This can make +development environments much more flexible. + +@node Order of Compilation Issues +@section Order of Compilation Issues + +@noindent +If, in our earlier example, there was a spec for the @code{hello} +procedure, it would be contained in the file @file{hello.ads}; yet this +file would not have to be explicitly compiled. This is the result of the +model we chose to implement library management. Some of the consequences +of this model are as follows: + +@itemize @bullet +@item +There is no point in compiling specs (except for package +specs with no bodies) because these are compiled as needed by clients. If +you attempt a useless compilation, you will receive an error message. +It is also useless to compile subunits because they are compiled as needed +by the parent. + +@item +There are no order of compilation requirements: performing a +compilation never obsoletes anything. The only way you can obsolete +something and require recompilations is to modify one of the +source files on which it depends. + +@item +There is no library as such, apart from the ALI files +(@pxref{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. + +@item +When you compile a unit, the source files for the specs of all units +that it @code{with}'s, all its subunits, and the bodies of any generics it +instantiates must be available (reachable by the search-paths mechanism +described above), or you will receive a fatal error message. +@end itemize + +@node Examples +@section Examples + +@noindent +The following are some typical Ada compilation command line examples: + +@table @code +@item $ gcc -c xyz.adb +Compile body in file @file{xyz.adb} with all default options. + +@ifclear vms +@item $ gcc -c -O2 -gnata xyz-def.adb +@end ifclear +@ifset vms +@item $ GNAT COMPILE /OPTIMIZE=ALL -gnata xyz-def.adb +@end ifset + +Compile the child unit package in file @file{xyz-def.adb} with extensive +optimizations, and pragma @code{Assert}/@code{Debug} statements +enabled. + +@item $ gcc -c -gnatc abc-def.adb +Compile the subunit in file @file{abc-def.adb} in semantic-checking-only +mode. +@end table + +@node Binding Using gnatbind +@chapter Binding Using @code{gnatbind} +@findex gnatbind + +@menu +* Running gnatbind:: +* Switches for gnatbind:: +* Command-Line Access:: +* Search Paths for gnatbind:: +* Examples of gnatbind Usage:: +@end menu + +@noindent +This chapter describes the GNAT binder, @code{gnatbind}, which is used +to bind compiled GNAT objects. + +Note: to invoke @code{gnatbind} with a project file, use the @code{gnat} +driver (see @ref{The GNAT Driver and Project Files}). + +The @code{gnatbind} program performs four separate functions: + +@enumerate +@item +Checks that a program is consistent, in accordance with the rules in +Chapter 10 of the Ada Reference Manual. In particular, error +messages are generated if a program uses inconsistent versions of a +given unit. + +@item +Checks that an acceptable order of elaboration exists for the program +and issues an error message if it cannot find an order of elaboration +that satisfies the rules in Chapter 10 of the Ada Language Manual. + +@item +Generates a main program incorporating the given elaboration order. +This program is a small Ada package (body and spec) that +must be subsequently compiled +using the GNAT compiler. The necessary compilation step is usually +performed automatically by @command{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 @command{gnatlink} utility used to link the Ada application. +@end enumerate + +@node Running gnatbind +@section Running @code{gnatbind} + +@noindent +The form of the @code{gnatbind} command is + +@smallexample +@c $ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatbind @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} @r{[}@var{switches}@r{]} +@end smallexample + +@noindent +where @file{@var{mainprog}.adb} is the Ada file containing the main program +unit body. @code{gnatbind} constructs an Ada +package in two files whose names are +@file{b~@var{mainprog}.ads}, and @file{b~@var{mainprog}.adb}. +For example, if given the +parameter @file{hello.ali}, for a main program contained in file +@file{hello.adb}, the binder output files would be @file{b~hello.ads} +and @file{b~hello.adb}. + +When doing consistency checking, the binder takes into consideration +any source files it can locate. For example, if the binder determines +that the given main program requires the package @code{Pack}, whose +@file{.ALI} +file is @file{pack.ali} and whose corresponding source spec file is +@file{pack.ads}, it attempts to locate the source file @file{pack.ads} +(using the same search path conventions as previously described for the +@command{gcc} command). If it can locate this source file, it checks that +the time stamps +or source checksums of the source and its references to in @file{ALI} files +match. In other words, any @file{ALI} files that mentions this spec must have +resulted from compiling this version of the source file (or in the case +where the source checksums match, a version close enough that the +difference does not matter). + +@cindex Source files, use by binder +The effect of this consistency checking, which includes source files, is +that the binder ensures that the program is consistent with the latest +version of the source files that can be located at bind time. Editing a +source file without compiling files that depend on the source file cause +error messages to be generated by the binder. + +For example, suppose you have a main program @file{hello.adb} and a +package @code{P}, from file @file{p.ads} and you perform the following +steps: + +@enumerate +@item +Enter @code{gcc -c hello.adb} to compile the main program. + +@item +Enter @code{gcc -c p.ads} to compile package @code{P}. + +@item +Edit file @file{p.ads}. + +@item +Enter @code{gnatbind hello}. +@end enumerate + +@noindent +At this point, the file @file{p.ali} contains an out-of-date time stamp +because the file @file{p.ads} has been edited. The attempt at binding +fails, and the binder generates the following error messages: + +@smallexample +error: "hello.adb" must be recompiled ("p.ads" has been modified) +error: "p.ads" has been modified and must be recompiled +@end smallexample + +@noindent +Now both files must be recompiled as indicated, and then the bind can +succeed, generating a main program. You need not normally be concerned +with the contents of this file, but for reference purposes a sample +binder output file is given in @ref{Example of Binder Output File}. + +In most normal usage, the default mode of @command{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 @option{^-g^/DEBUG^} switch is used for +@command{gnatbind} and @command{gnatlink}. + +@node Switches for gnatbind +@section Switches for @command{gnatbind} + +@noindent +The following switches are available with @code{gnatbind}; details will +be presented in subsequent sections. + +@menu +* Consistency-Checking Modes:: +* Binder Error Message Control:: +* Elaboration Control:: +* Output Control:: +* Dynamic Allocation Control:: +* Binding with Non-Ada Main Programs:: +* Binding Programs with No Main Subprogram:: +@end menu + +@table @option +@c !sort! + +@item --version +@cindex @option{--version} @command{gnatbind} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatbind} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item -a +@cindex @option{-a} @command{gnatbind} +Indicates that, if supported by the platform, the adainit procedure should +be treated as an initialisation routine by the linker (a constructor). This +is intended to be used by the Project Manager to automatically initialize +shared Stand-Alone Libraries. + +@item ^-aO^/OBJECT_SEARCH^ +@cindex @option{^-aO^/OBJECT_SEARCH^} (@command{gnatbind}) +Specify directory to be searched for ALI files. + +@item ^-aI^/SOURCE_SEARCH^ +@cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind}) +Specify directory to be searched for source file. + +@item ^-A^/ALI_LIST^@r{[=}@var{filename}@r{]} +@cindex @option{^-A^/ALI_LIST^} (@command{gnatbind}) +Output ALI list (to standard output or to the named file). + +@item ^-b^/REPORT_ERRORS=BRIEF^ +@cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@command{gnatbind}) +Generate brief messages to @file{stderr} even if verbose mode set. + +@item ^-c^/NOOUTPUT^ +@cindex @option{^-c^/NOOUTPUT^} (@command{gnatbind}) +Check only, no generation of binder output file. + +@item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]} +@cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}} (@command{gnatbind}) +This switch can be used to change the default task stack size value +to a specified size @var{nn}, which is expressed in bytes by default, or +in kilobytes when suffixed with @var{k} or in megabytes when suffixed +with @var{m}. +In the absence of a @samp{@r{[}k@r{|}m@r{]}} suffix, this switch is equivalent, +in effect, to completing all task specs with +@smallexample @c ada + pragma Storage_Size (nn); +@end smallexample +When they do not already have such a pragma. + +@item ^-D^/DEFAULT_SECONDARY_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]} +@cindex @option{^-D^/DEFAULT_SECONDARY_STACK_SIZE=nnnnn^} (@command{gnatbind}) +This switch can be used to change the default secondary stack size value +to a specified size @var{nn}, which is expressed in bytes by default, or +in kilobytes when suffixed with @var{k} or in megabytes when suffixed +with @var{m}. + +The secondary stack is used to deal with functions that return a variable +sized result, for example a function returning an unconstrained +String. There are two ways in which this secondary stack is allocated. + +For most targets, the secondary stack is growing on demand and is allocated +as a chain of blocks in the heap. The -D option is not very +relevant. It only give some control over the size of the allocated +blocks (whose size is the minimum of the default secondary stack size value, +and the actual size needed for the current allocation request). + +For certain targets, notably VxWorks 653, +the secondary stack is allocated by carving off a fixed ratio chunk of the +primary task stack. The -D option is used to define the +size of the environment task's secondary stack. + +@item ^-e^/ELABORATION_DEPENDENCIES^ +@cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@command{gnatbind}) +Output complete list of elaboration-order dependencies. + +@item ^-E^/STORE_TRACEBACKS^ +@cindex @option{^-E^/STORE_TRACEBACKS^} (@command{gnatbind}) +Store tracebacks in exception occurrences when the target supports it. +@ignore +@c The following may get moved to an appendix +This option is currently supported on the following targets: +all x86 ports, Solaris, Windows, HP-UX, AIX, PowerPC VxWorks and Alpha VxWorks. +@end ignore +See also the packages @code{GNAT.Traceback} and +@code{GNAT.Traceback.Symbolic} for more information. +@ifclear vms +Note that on x86 ports, you must not use @option{-fomit-frame-pointer} +@command{gcc} option. +@end ifclear + +@item ^-F^/FORCE_ELABS_FLAGS^ +@cindex @option{^-F^/FORCE_ELABS_FLAGS^} (@command{gnatbind}) +Force the checks of elaboration flags. @command{gnatbind} does not normally +generate checks of elaboration flags for the main executable, except when +a Stand-Alone Library is used. However, there are cases when this cannot be +detected by gnatbind. An example is importing an interface of a Stand-Alone +Library through a pragma Import and only specifying through a linker switch +this Stand-Alone Library. This switch is used to guarantee that elaboration +flag checks are generated. + +@item ^-h^/HELP^ +@cindex @option{^-h^/HELP^} (@command{gnatbind}) +Output usage (help) information + +@item ^-H32^/32_MALLOC^ +@cindex @option{^-H32^/32_MALLOC^} (@command{gnatbind}) +Use 32-bit allocations for @code{__gnat_malloc} (and thus for access types). +For further details see @ref{Dynamic Allocation Control}. + +@item ^-H64^/64_MALLOC^ +@cindex @option{^-H64^/64_MALLOC^} (@command{gnatbind}) +Use 64-bit allocations for @code{__gnat_malloc} (and thus for access types). +@cindex @code{__gnat_malloc} +For further details see @ref{Dynamic Allocation Control}. + +@item ^-I^/SEARCH^ +@cindex @option{^-I^/SEARCH^} (@command{gnatbind}) +Specify directory to be searched for source and ALI files. + +@item ^-I-^/NOCURRENT_DIRECTORY^ +@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatbind}) +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 @code{gnatbind} command line. + +@item ^-l^/ORDER_OF_ELABORATION^ +@cindex @option{^-l^/ORDER_OF_ELABORATION^} (@command{gnatbind}) +Output chosen elaboration order. + +@item ^-L@var{xxx}^/BUILD_LIBRARY=@var{xxx}^ +@cindex @option{^-L^/BUILD_LIBRARY^} (@command{gnatbind}) +Bind the units for library building. In this case the adainit and +adafinal procedures (@pxref{Binding with Non-Ada Main Programs}) +are renamed to ^@var{xxx}init^@var{XXX}INIT^ and +^@var{xxx}final^@var{XXX}FINAL^. +Implies ^-n^/NOCOMPILE^. +@ifclear vms +(@xref{GNAT and Libraries}, for more details.) +@end ifclear +@ifset vms +On OpenVMS, these init and final procedures are exported in uppercase +letters. For example if /BUILD_LIBRARY=toto is used, the exported name of +the init procedure will be "TOTOINIT" and the exported name of the final +procedure will be "TOTOFINAL". +@end ifset + +@item ^-Mxyz^/RENAME_MAIN=xyz^ +@cindex @option{^-M^/RENAME_MAIN^} (@command{gnatbind}) +Rename generated main program from main to xyz. This option is +supported on cross environments only. + +@item ^-m^/ERROR_LIMIT=^@var{n} +@cindex @option{^-m^/ERROR_LIMIT^} (@command{gnatbind}) +Limit number of detected errors or warnings to @var{n}, where @var{n} is +in the range 1..999999. The default value if no switch is +given is 9999. If the number of warnings reaches this limit, then a +message is output and further warnings are suppressed, the bind +continues in this case. If the number of errors reaches this +limit, then a message is output and the bind is abandoned. +A value of zero means that no limit is enforced. The equal +sign is optional. + +@ifset unw +Furthermore, under Windows, the sources pointed to by the libraries path +set in the registry are not searched for. +@end ifset + +@item ^-n^/NOMAIN^ +@cindex @option{^-n^/NOMAIN^} (@command{gnatbind}) +No main program. + +@item -nostdinc +@cindex @option{-nostdinc} (@command{gnatbind}) +Do not look for sources in the system default directory. + +@item -nostdlib +@cindex @option{-nostdlib} (@command{gnatbind}) +Do not look for library files in the system default directory. + +@item --RTS=@var{rts-path} +@cindex @option{--RTS} (@code{gnatbind}) +Specifies the default location of the runtime library. Same meaning as the +equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). + +@item ^-o ^/OUTPUT=^@var{file} +@cindex @option{^-o ^/OUTPUT^} (@command{gnatbind}) +Name the output file @var{file} (default is @file{b~@var{xxx}.adb}). +Note that if this option is used, then linking must be done manually, +gnatlink cannot be used. + +@item ^-O^/OBJECT_LIST^@r{[=}@var{filename}@r{]} +@cindex @option{^-O^/OBJECT_LIST^} (@command{gnatbind}) +Output object list (to standard output or to the named file). + +@item ^-p^/PESSIMISTIC_ELABORATION^ +@cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@command{gnatbind}) +Pessimistic (worst-case) elaboration order + +@item ^-R^-R^ +@cindex @option{^-R^-R^} (@command{gnatbind}) +Output closure source list. + +@item ^-s^/READ_SOURCES=ALL^ +@cindex @option{^-s^/READ_SOURCES=ALL^} (@command{gnatbind}) +Require all source files to be present. + +@item ^-S@var{xxx}^/INITIALIZE_SCALARS=@var{xxx}^ +@cindex @option{^-S^/INITIALIZE_SCALARS^} (@command{gnatbind}) +Specifies the value to be used when detecting uninitialized scalar +objects with pragma Initialize_Scalars. +The @var{xxx} ^string specified with the switch^option^ may be either +@itemize @bullet +@item ``@option{^in^INVALID^}'' requesting an invalid value where possible +@item ``@option{^lo^LOW^}'' for the lowest possible value +@item ``@option{^hi^HIGH^}'' for the highest possible value +@item ``@option{@var{xx}}'' for a value consisting of repeated bytes with the +value @code{16#@var{xx}#} (i.e., @var{xx} is a string of two hexadecimal digits). +@end itemize + +In addition, you can specify @option{-Sev} to indicate that the value is +to be set at run time. In this case, the program will look for an environment +@cindex GNAT_INIT_SCALARS +variable of the form @env{GNAT_INIT_SCALARS=@var{xx}}, where @var{xx} is one +of @option{in/lo/hi/@var{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 @option{in} (invalid values). + +@ifclear vms +@item -static +@cindex @option{-static} (@code{gnatbind}) +Link against a static GNAT run time. + +@item -shared +@cindex @option{-shared} (@code{gnatbind}) +Link against a shared GNAT run time when available. +@end ifclear + +@item ^-t^/NOTIME_STAMP_CHECK^ +@cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind}) +Tolerate time stamp and other consistency errors + +@item ^-T@var{n}^/TIME_SLICE=@var{n}^ +@cindex @option{^-T^/TIME_SLICE^} (@code{gnatbind}) +Set the time slice value to @var{n} milliseconds. If the system supports +the specification of a specific time slice value, then the indicated value +is used. If the system does not support specific time slice values, but +does support some general notion of round-robin scheduling, then any +nonzero value will activate round-robin scheduling. + +A value of zero is treated specially. It turns off time +slicing, and in addition, indicates to the tasking run time that the +semantics should match as closely as possible the Annex D +requirements of the Ada RM, and in particular sets the default +scheduling policy to @code{FIFO_Within_Priorities}. + +@item ^-u@var{n}^/DYNAMIC_STACK_USAGE=@var{n}^ +@cindex @option{^-u^/DYNAMIC_STACK_USAGE^} (@code{gnatbind}) +Enable dynamic stack usage, with @var{n} results stored and displayed +at program termination. A result is generated when a task +terminates. Results that can't be stored are displayed on the fly, at +task termination. This option is currently not supported on Itanium +platforms. (See @ref{Dynamic Stack Usage Analysis} for details.) + +@item ^-v^/REPORT_ERRORS=VERBOSE^ +@cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind}) +Verbose mode. Write error messages, header, summary output to +@file{stdout}. + +@ifclear vms +@item -w@var{x} +@cindex @option{-w} (@code{gnatbind}) +Warning mode (@var{x}=s/e for suppress/treat as error) +@end ifclear + +@ifset vms +@item /WARNINGS=NORMAL +@cindex @option{/WARNINGS} (@code{gnatbind}) +Normal warnings mode. Warnings are issued but ignored + +@item /WARNINGS=SUPPRESS +@cindex @option{/WARNINGS} (@code{gnatbind}) +All warning messages are suppressed + +@item /WARNINGS=ERROR +@cindex @option{/WARNINGS} (@code{gnatbind}) +Warning messages are treated as fatal errors +@end ifset + +@item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e} +@cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind}) +Override default wide character encoding for standard Text_IO files. + +@item ^-x^/READ_SOURCES=NONE^ +@cindex @option{^-x^/READ_SOURCES^} (@code{gnatbind}) +Exclude source files (check object consistency only). + +@ifset vms +@item /READ_SOURCES=AVAILABLE +@cindex @option{/READ_SOURCES} (@code{gnatbind}) +Default mode, in which sources are checked for consistency only if +they are available. +@end ifset + +@item ^-y^/ENABLE_LEAP_SECONDS^ +@cindex @option{^-y^/ENABLE_LEAP_SECONDS^} (@code{gnatbind}) +Enable leap seconds support in @code{Ada.Calendar} and its children. + +@item ^-z^/ZERO_MAIN^ +@cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind}) +No main subprogram. +@end table + +@ifclear vms +@noindent +You may obtain this listing of switches by running @code{gnatbind} with +no arguments. +@end ifclear + +@node Consistency-Checking Modes +@subsection Consistency-Checking Modes + +@noindent +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. + +@table @option +@c !sort! +@item ^-s^/READ_SOURCES=ALL^ +@cindex @option{^-s^/READ_SOURCES=ALL^} (@code{gnatbind}) +Require source files to be present. In this mode, the binder must be +able to locate all source files that are referenced, in order to check +their consistency. In normal mode, if a source file cannot be located it +is simply ignored. If you specify this switch, a missing source +file is an error. + +@item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e} +@cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind}) +Override default wide character encoding for standard Text_IO files. +Normally the default wide character encoding method used for standard +[Wide_[Wide_]]Text_IO files is taken from the encoding specified for +the main source input (see description of switch +@option{^-gnatWx^/WIDE_CHARACTER_ENCODING^} for the compiler). The +use of this switch for the binder (which has the same set of +possible arguments) overrides this default as specified. + +@item ^-x^/READ_SOURCES=NONE^ +@cindex @option{^-x^/READ_SOURCES=NONE^} (@code{gnatbind}) +Exclude source files. In this mode, the binder only checks that ALI +files are consistent with one another. Source files are not accessed. +The binder runs faster in this mode, and there is still a guarantee that +the resulting program is self-consistent. +If a source file has been edited since it was last compiled, and you +specify this switch, the binder will not detect that the object +file is out of date with respect to the source file. Note that this is the +mode that is automatically used by @command{gnatmake} because in this +case the checking against sources has already been performed by +@command{gnatmake} in the course of compilation (i.e.@: before binding). + +@ifset vms +@item /READ_SOURCES=AVAILABLE +@cindex @code{/READ_SOURCES=AVAILABLE} (@code{gnatbind}) +This is the default mode in which source files are checked if they are +available, and ignored if they are not available. +@end ifset +@end table + +@node Binder Error Message Control +@subsection Binder Error Message Control + +@noindent +The following switches provide control over the generation of error +messages from the binder: + +@table @option +@c !sort! +@item ^-v^/REPORT_ERRORS=VERBOSE^ +@cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind}) +Verbose mode. In the normal mode, brief error messages are generated to +@file{stderr}. If this switch is present, a header is written +to @file{stdout} and any error messages are directed to @file{stdout}. +All that is written to @file{stderr} is a brief summary message. + +@item ^-b^/REPORT_ERRORS=BRIEF^ +@cindex @option{^-b^/REPORT_ERRORS=BRIEF^} (@code{gnatbind}) +Generate brief error messages to @file{stderr} even if verbose mode is +specified. This is relevant only when used with the +@option{^-v^/REPORT_ERRORS=VERBOSE^} switch. + +@ifclear vms +@item -m@var{n} +@cindex @option{-m} (@code{gnatbind}) +Limits the number of error messages to @var{n}, a decimal integer in the +range 1-999. The binder terminates immediately if this limit is reached. + +@item -M@var{xxx} +@cindex @option{-M} (@code{gnatbind}) +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 @code{gnatbind}. +@end ifclear + +@item ^-ws^/WARNINGS=SUPPRESS^ +@cindex @option{^-ws^/WARNINGS=SUPPRESS^} (@code{gnatbind}) +@cindex Warnings +Suppress all warning messages. + +@item ^-we^/WARNINGS=ERROR^ +@cindex @option{^-we^/WARNINGS=ERROR^} (@code{gnatbind}) +Treat any warning messages as fatal errors. + +@ifset vms +@item /WARNINGS=NORMAL +Standard mode with warnings generated, but warnings do not get treated +as errors. +@end ifset + +@item ^-t^/NOTIME_STAMP_CHECK^ +@cindex @option{^-t^/NOTIME_STAMP_CHECK^} (@code{gnatbind}) +@cindex Time stamp checks, in binder +@cindex Binder consistency checks +@cindex Consistency checks, in binder +The binder performs a number of consistency checks including: + +@itemize @bullet +@item +Check that time stamps of a given source unit are consistent +@item +Check that checksums of a given source unit are consistent +@item +Check that consistent versions of @code{GNAT} were used for compilation +@item +Check consistency of configuration pragmas as required +@end itemize + +@noindent +Normally failure of such checks, in accordance with the consistency +requirements of the Ada Reference Manual, causes error messages to be +generated which abort the binder and prevent the output of a binder +file and subsequent link to obtain an executable. + +The @option{^-t^/NOTIME_STAMP_CHECK^} switch converts these error messages +into warnings, so that +binding and linking can continue to completion even in the presence of such +errors. The result may be a failed link (due to missing symbols), or a +non-functional executable which has undefined semantics. +@emph{This means that +@option{^-t^/NOTIME_STAMP_CHECK^} should be used only in unusual situations, +with extreme care.} +@end table + +@node Elaboration Control +@subsection Elaboration Control + +@noindent +The following switches provide additional control over the elaboration +order. For full details see @ref{Elaboration Order Handling in GNAT}. + +@table @option +@item ^-p^/PESSIMISTIC_ELABORATION^ +@cindex @option{^-p^/PESSIMISTIC_ELABORATION^} (@code{gnatbind}) +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 @option{^-p^/PESSIMISTIC_ELABORATION^} +switch if dynamic +elaboration checking is used (@option{-gnatE} switch used for compilation). +This is because in the default static elaboration mode, all necessary +@code{Elaborate} and @code{Elaborate_All} pragmas are implicitly inserted. +These implicit pragmas are still respected by the binder in +@option{^-p^/PESSIMISTIC_ELABORATION^} mode, so a +safe elaboration order is assured. +@end table + +@node Output Control +@subsection Output Control + +@noindent +The following switches allow additional control over the output +generated by the binder. + +@table @option +@c !sort! + +@item ^-c^/NOOUTPUT^ +@cindex @option{^-c^/NOOUTPUT^} (@code{gnatbind}) +Check only. Do not generate the binder output file. In this mode the +binder performs all error checks but does not generate an output file. + +@item ^-e^/ELABORATION_DEPENDENCIES^ +@cindex @option{^-e^/ELABORATION_DEPENDENCIES^} (@code{gnatbind}) +Output complete list of elaboration-order dependencies, showing the +reason for each dependency. This output can be rather extensive but may +be useful in diagnosing problems with elaboration order. The output is +written to @file{stdout}. + +@item ^-h^/HELP^ +@cindex @option{^-h^/HELP^} (@code{gnatbind}) +Output usage information. The output is written to @file{stdout}. + +@item ^-K^/LINKER_OPTION_LIST^ +@cindex @option{^-K^/LINKER_OPTION_LIST^} (@code{gnatbind}) +Output linker options to @file{stdout}. Includes library search paths, +contents of pragmas Ident and Linker_Options, and libraries added +by @code{gnatbind}. + +@item ^-l^/ORDER_OF_ELABORATION^ +@cindex @option{^-l^/ORDER_OF_ELABORATION^} (@code{gnatbind}) +Output chosen elaboration order. The output is written to @file{stdout}. + +@item ^-O^/OBJECT_LIST^ +@cindex @option{^-O^/OBJECT_LIST^} (@code{gnatbind}) +Output full names of all the object files that must be linked to provide +the Ada component of the program. The output is written to @file{stdout}. +This list includes the files explicitly supplied and referenced by the user +as well as implicitly referenced run-time unit files. The latter are +omitted if the corresponding units reside in shared libraries. The +directory names for the run-time units depend on the system configuration. + +@item ^-o ^/OUTPUT=^@var{file} +@cindex @option{^-o^/OUTPUT^} (@code{gnatbind}) +Set name of output file to @var{file} instead of the normal +@file{b~@var{mainprog}.adb} default. Note that @var{file} denote the Ada +binder generated body filename. +Note that if this option is used, then linking must be done manually. +It is not possible to use gnatlink in this case, since it cannot locate +the binder file. + +@item ^-r^/RESTRICTION_LIST^ +@cindex @option{^-r^/RESTRICTION_LIST^} (@code{gnatbind}) +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 +@subsection Dynamic Allocation Control + +@noindent +The heap control switches -- @option{-H32} and @option{-H64} -- +determine whether dynamic allocation uses 32-bit or 64-bit memory. +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. + +@table @option +@item -H32 +Allocate memory on 32-bit heap + +@item -H64 +Allocate memory on 64-bit heap. This is the default +unless explicitly overridden by a @code{'Size} clause on the access type. +@end table + +@ifset vms +@noindent +See also @ref{Access types and 32/64-bit allocation}. +@end ifset +@ifclear vms +@noindent +These switches are only effective on VMS platforms. +@end ifclear + + +@node Binding with Non-Ada Main Programs +@subsection Binding with Non-Ada Main Programs + +@noindent +In our description so far we have assumed that the main +program is in Ada, and that the task of the binder is to generate a +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 (@pxref{Mixed Language Programming}). +The following switch is used in this situation: + +@table @option +@item ^-n^/NOMAIN^ +@cindex @option{^-n^/NOMAIN^} (@code{gnatbind}) +No main program. The main program is not in Ada. +@end table + +@noindent +In this case, most of the functions of the binder are still required, +but instead of generating a main program, the binder generates a file +containing the following callable routines: + +@table @code +@item adainit +@findex adainit +You must call this routine to initialize the Ada part of the program by +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 +to be appropriate for Ada execution at the point where the first Ada +subprogram is called. In particular, if the Ada code will do any +floating-point operations, then the FPU must be setup in an appropriate +manner. For the case of the x86, for example, full precision mode is +required. The procedure GNAT.Float_Control.Reset may be used to ensure +that the FPU is in the right state. + +@item adafinal +@findex adafinal +You must call this routine to perform any library-level finalization +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 + +@noindent +If the @option{^-n^/NOMAIN^} switch +@cindex @option{^-n^/NOMAIN^} (@command{gnatbind}) +@cindex Binder, multiple input files +is given, more than one ALI file may appear on +the command line for @code{gnatbind}. The normal @dfn{closure} +calculation is performed for each of the specified units. Calculating +the closure means finding out the set of units involved by tracing +@code{with} references. The reason it is necessary to be able to +specify more than one ALI file is that a given program may invoke two or +more quite separate groups of Ada units. + +The binder takes the name of its output file from the last specified ALI +file, unless overridden by the use of the @option{^-o file^/OUTPUT=file^}. +@cindex @option{^-o^/OUTPUT^} (@command{gnatbind}) +The output is an Ada unit in source form that can be compiled with GNAT. +This compilation occurs automatically as part of the @command{gnatlink} +processing. + +Currently the GNAT run time requires a FPU using 80 bits mode +precision. Under targets where this is not the default it is required to +call GNAT.Float_Control.Reset before using floating point numbers (this +include float computation, float input and output) in the Ada code. A +side effect is that this could be the wrong mode for the foreign code +where floating point computation could be broken after this call. + +@node Binding Programs with No Main Subprogram +@subsection Binding Programs with No Main Subprogram + +@noindent +It is possible to have an Ada program which does not have a main +subprogram. This program will call the elaboration routines of all the +packages, then the finalization routines. + +The following switch is used to bind programs organized in this manner: + +@table @option +@item ^-z^/ZERO_MAIN^ +@cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind}) +Normally the binder checks that the unit name given on the command line +corresponds to a suitable main subprogram. When this switch is used, +a list of ALI files can be given, and the execution of the program +consists of elaboration of these units in an appropriate order. Note +that the default wide character encoding method for standard Text_IO +files is always set to Brackets if this switch is set (you can use +the binder switch +@option{^-Wx^WIDE_CHARACTER_ENCODING^} to override this default). +@end table + +@node Command-Line Access +@section Command-Line Access + +@noindent +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 + +@smallexample +@group +int gnat_argc; +char **gnat_argv; +@end group +@end smallexample + +@noindent +@findex gnat_argv +@findex gnat_argc +are declared in one of the GNAT library routines. These variables must +be set from the actual @code{argc} and @code{argv} values passed to the +main program. With no @option{^n^/NOMAIN^} present, @code{gnatbind} +generates the C main program to automatically set these variables. +If the @option{^n^/NOMAIN^} switch is used, there is no automatic way to +set these variables. If they are not set, the procedures in +@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 +@section Search Paths for @code{gnatbind} + +@noindent +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 @command{gcc} +(@pxref{Search Paths and the Run-Time Library (RTL)}). For ALI files the +directories searched are: + +@enumerate +@item +The directory containing the ALI file named in the command line, unless +the switch @option{^-I-^/NOCURRENT_DIRECTORY^} is specified. + +@item +All directories specified by @option{^-I^/SEARCH^} +switches on the @code{gnatbind} +command line, in the order given. + +@item +@findex ADA_PRJ_OBJECTS_FILE +Each of the directories listed in the text file whose name is given +by the @env{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^. + +@noindent +@env{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^ +driver when project files are used. It should not normally be set +by other means. + +@item +@findex ADA_OBJECTS_PATH +Each of the directories listed in the value of the +@env{ADA_OBJECTS_PATH} ^environment variable^logical name^. +@ifset unw +Construct this value +exactly as the @env{PATH} environment variable: a list of directory +names separated by colons (semicolons when working with the NT version +of GNAT). +@end ifset +@ifset vms +Normally, define this value as a logical name containing a comma separated +list of directory names. + +This variable can also be defined by means of an environment string +(an argument to the HP C exec* set of functions). + +Logical Name: +@smallexample +DEFINE ANOTHER_PATH FOO:[BAG] +DEFINE ADA_OBJECTS_PATH ANOTHER_PATH,FOO:[BAM],FOO:[BAR] +@end smallexample + +By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB] +first, followed by the standard Ada +libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB]. +If this is not redefined, the user will obtain the HP Ada 83 IO packages +(Text_IO, Sequential_IO, etc) +instead of the standard Ada packages. Thus, in order to get the standard Ada +packages by default, ADA_OBJECTS_PATH must be redefined. +@end ifset + +@item +The content of the @file{ada_object_path} file which is part of the GNAT +installation tree and is used to store standard libraries such as the +GNAT Run Time Library (RTL) unless the switch @option{-nostdlib} is +specified. +@ifclear vms +@ref{Installing a library} +@end ifclear +@end enumerate + +@noindent +In the binder the switch @option{^-I^/SEARCH^} +@cindex @option{^-I^/SEARCH^} (@command{gnatbind}) +is used to specify both source and +library file paths. Use @option{^-aI^/SOURCE_SEARCH^} +@cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatbind}) +instead if you want to specify +source paths only, and @option{^-aO^/LIBRARY_SEARCH^} +@cindex @option{^-aO^/LIBRARY_SEARCH^} (@command{gnatbind}) +if you want to specify library paths +only. This means that for the binder +@option{^-I^/SEARCH=^}@var{dir} is equivalent to +@option{^-aI^/SOURCE_SEARCH=^}@var{dir} +@option{^-aO^/OBJECT_SEARCH=^}@var{dir}. +The binder generates the bind file (a C language source file) in the +current working directory. + +@findex Ada +@findex System +@findex Interfaces +@findex GNAT +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 +needed by the compiler and are kept together in one directory. The ALI +files and object files generated by compiling the RTL are needed by the +binder and the linker and are kept together in one directory, typically +different from the directory containing the sources. In a normal +installation, you need not specify these directory names when compiling +or binding. Either the environment variables or the built-in defaults +cause these files to be found. + +Besides simplifying access to the RTL, a major use of search paths is +in compiling sources from multiple directories. This can make +development environments much more flexible. + +@node Examples of gnatbind Usage +@section Examples of @code{gnatbind} Usage + +@noindent +This section contains a number of examples of using the GNAT binding +utility @code{gnatbind}. + +@table @code +@item gnatbind hello +The main program @code{Hello} (source program in @file{hello.adb}) is +bound using the standard switch settings. The generated main program is +@file{b~hello.adb}. This is the normal, default use of the binder. + +@ifclear vms +@item gnatbind hello -o mainprog.adb +@end ifclear +@ifset vms +@item gnatbind HELLO.ALI /OUTPUT=Mainprog.ADB +@end ifset +The main program @code{Hello} (source program in @file{hello.adb}) is +bound using the standard switch settings. The generated main program is +@file{mainprog.adb} with the associated spec in +@file{mainprog.ads}. Note that you must specify the body here not the +spec. Note that if this option is used, then linking must be done manually, +since gnatlink will not be able to find the generated file. +@end table + +@c ------------------------------------ +@node Linking Using gnatlink +@chapter Linking Using @command{gnatlink} +@c ------------------------------------ +@findex gnatlink + +@noindent +This chapter discusses @command{gnatlink}, a tool that links +an Ada program and builds an executable file. This utility +invokes the system linker ^(via the @command{gcc} command)^^ +with a correct list of object files and library references. +@command{gnatlink} automatically determines the list of files and +references for the Ada part of a program. It uses the binder file +generated by the @command{gnatbind} to determine this list. + +Note: to invoke @code{gnatlink} with a project file, use the @code{gnat} +driver (see @ref{The GNAT Driver and Project Files}). + +@menu +* Running gnatlink:: +* Switches for gnatlink:: +@end menu + +@node Running gnatlink +@section Running @command{gnatlink} + +@noindent +The form of the @command{gnatlink} command is + +@smallexample +@c $ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]} +@c @ovar{non-Ada objects} @ovar{linker options} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatlink @r{[}@var{switches}@r{]} @var{mainprog}@r{[}.ali@r{]} + @r{[}@var{non-Ada objects}@r{]} @r{[}@var{linker options}@r{]} + +@end smallexample + +@noindent +The arguments of @command{gnatlink} (switches, main @file{ALI} file, +non-Ada objects +or linker options) may be in any order, provided that no non-Ada object may +be mistaken for a main @file{ALI} file. +Any file name @file{F} without the @file{.ali} +extension will be taken as the main @file{ALI} file if a file exists +whose name is the concatenation of @file{F} and @file{.ali}. + +@noindent +@file{@var{mainprog}.ali} references the ALI file of the main program. +The @file{.ali} extension of this file can be omitted. From this +reference, @command{gnatlink} locates the corresponding binder file +@file{b~@var{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 @command{gnatlink} switches and the main +@file{ALI} file are passed to the linker uninterpreted. +They typically include the names of +object files for units written in other languages than Ada and any library +references required to resolve references in any of these foreign language +units, or in @code{Import} pragmas in any Ada units. + +@var{linker options} is an optional list of linker specific +switches. +The default linker called by gnatlink is @command{gcc} which in +turn calls the appropriate system linker. + +One useful option for the linker is @option{-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 @option{-lmy_lib} or +@option{-Ldir} can be added as is. +For options that are not recognized by +@command{gcc} as linker options, use the @command{gcc} switches +@option{-Xlinker} or @option{-Wl,}. + +Refer to the GCC documentation for +details. + +Here is an example showing how to generate a linker map: + +@smallexample +$ ^gnatlink my_prog -Wl,-Map,MAPFILE^GNAT LINK my_prog.ali /MAP^ +@end smallexample + +Using @var{linker options} it is possible to set the program stack and +heap size. +@ifset unw +See @ref{Setting Stack Size from gnatlink} and +@ref{Setting Heap Size from gnatlink}. +@end ifset + +@command{gnatlink} determines the list of objects required by the Ada +program and prepends them to the list of objects passed to the linker. +@command{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. + +@ifset vms +@command{gnatlink} accepts the following types of extra files on the command +line: objects (@file{.OBJ}), libraries (@file{.OLB}), sharable images +(@file{.EXE}), and options files (@file{.OPT}). These are recognized and +handled according to their extension. +@end ifset + +@node Switches for gnatlink +@section Switches for @command{gnatlink} + +@noindent +The following switches are available with the @command{gnatlink} utility: + +@table @option +@c !sort! + +@item --version +@cindex @option{--version} @command{gnatlink} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatlink} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item ^-f^/FORCE_OBJECT_FILE_LIST^ +@cindex Command line length +@cindex @option{^-f^/FORCE_OBJECT_FILE_LIST^} (@command{gnatlink}) +On some targets, the command line length is limited, and @command{gnatlink} +will generate a separate file for the linker if the list of object files +is too long. +The @option{^-f^/FORCE_OBJECT_FILE_LIST^} 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 ^-g^/DEBUG^ +@cindex Debugging information, including +@cindex @option{^-g^/DEBUG^} (@command{gnatlink}) +The option to include debugging information causes the Ada bind file (in +other words, @file{b~@var{mainprog}.adb}) to be compiled with +@option{^-g^/DEBUG^}. +In addition, the binder does not delete the @file{b~@var{mainprog}.adb}, +@file{b~@var{mainprog}.o} and @file{b~@var{mainprog}.ali} files. +Without @option{^-g^/DEBUG^}, the binder removes these files by +default. The same procedure apply if a C bind file was generated using +@option{^-C^/BIND_FILE=C^} @code{gnatbind} option, in this case the filenames +are @file{b_@var{mainprog}.c} and @file{b_@var{mainprog}.o}. + +@item ^-n^/NOCOMPILE^ +@cindex @option{^-n^/NOCOMPILE^} (@command{gnatlink}) +Do not compile the file generated by the binder. This may be used when +a link is rerun with different options, but there is no need to recompile +the binder file. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@command{gnatlink}) +Causes additional information to be output, including a full list of the +included object files. This switch option is most useful when you want +to see what set of object files are being used in the link step. + +@item ^-v -v^/VERBOSE/VERBOSE^ +@cindex @option{^-v -v^/VERBOSE/VERBOSE^} (@command{gnatlink}) +Very verbose mode. Requests that the compiler operate in verbose mode when +it compiles the binder file, and that the system linker run in verbose mode. + +@item ^-o ^/EXECUTABLE=^@var{exec-name} +@cindex @option{^-o^/EXECUTABLE^} (@command{gnatlink}) +@var{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, @code{gnatlink try.ali} creates +an executable called @file{^try^TRY.EXE^}. + +@ifclear vms +@item -b @var{target} +@cindex @option{-b} (@command{gnatlink}) +Compile your program to run on @var{target}, which is the name of a +system configuration. You must have a GNAT cross-compiler built if +@var{target} is not the same as your host system. + +@item -B@var{dir} +@cindex @option{-B} (@command{gnatlink}) +Load compiler executables (for example, @code{gnat1}, the Ada compiler) +from @var{dir} instead of the default location. Only use this switch +when multiple versions of the GNAT compiler are available. +@xref{Directory Options,,, gcc, The GNU Compiler Collection}, +for further details. You would normally use the @option{-b} or +@option{-V} switch instead. + +@item --GCC=@var{compiler_name} +@cindex @option{--GCC=compiler_name} (@command{gnatlink}) +Program used for compiling the binder file. The default is +@command{gcc}. You need to use quotes around @var{compiler_name} if +@code{compiler_name} contains spaces or other separator characters. +As an example @option{--GCC="foo -x -y"} will instruct @command{gnatlink} to +use @code{foo -x -y} as your compiler. Note that switch @option{-c} is always +inserted after your command name. Thus in the above example the compiler +command that will be used by @command{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 -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 @option{--GCC="foo -x -y"}. But the back end +switches will be used for @option{--GCC="gcc -gnatv"}. If several +@option{--GCC=compiler_name} are used, only the last @var{compiler_name} +is taken into account. However, all the additional switches are also taken +into account. Thus, +@option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to +@option{--GCC="bar -x -y -z -t"}. + +@item --LINK=@var{name} +@cindex @option{--LINK=} (@command{gnatlink}) +@var{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 @command{gcc}. When this switch is used, the +specified linker is called instead of @command{gcc} with exactly the same +parameters that would have been passed to @command{gcc} so if the desired +linker requires different parameters it is necessary to use a wrapper +script that massages the parameters before invoking the real linker. It +may be useful to control the exact invocation by using the verbose +switch. + +@end ifclear + +@ifset vms +@item /DEBUG=TRACEBACK +@cindex @code{/DEBUG=TRACEBACK} (@command{gnatlink}) +This qualifier causes sufficient information to be included in the +executable file to allow a traceback, but does not include the full +symbol information needed by the debugger. + +@item /IDENTIFICATION="" +@code{""} specifies the string to be stored in the image file +identification field in the image header. +It overrides any pragma @code{Ident} specified string. + +@item /NOINHIBIT-EXEC +Generate the executable file even if there are linker warnings. + +@item /NOSTART_FILES +Don't link in the object file containing the ``main'' transfer address. +Used when linking with a foreign language main program compiled with an +HP compiler. + +@item /STATIC +Prefer linking with object libraries over sharable images, even without +/DEBUG. +@end ifset + +@end table + +@node The GNAT Make Program gnatmake +@chapter The GNAT Make Program @command{gnatmake} +@findex gnatmake + +@menu +* Running gnatmake:: +* Switches for gnatmake:: +* Mode Switches for gnatmake:: +* Notes on the Command Line:: +* How gnatmake Works:: +* Examples of gnatmake Usage:: +@end menu +@noindent +A typical development cycle when working on an Ada program consists of +the following steps: + +@enumerate +@item +Edit some sources to fix bugs. + +@item +Add enhancements. + +@item +Compile all sources affected. + +@item +Rebind and relink. + +@item +Test. +@end enumerate + +@noindent +The third step can be tricky, because not only do the modified files +@cindex Dependency rules +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, @code{use} clauses, generics and inlined +subprograms. + +@command{gnatmake} automatically takes care of the third and fourth steps +of this process. It determines which sources need to be compiled, +compiles them, and binds and links the resulting object files. + +Unlike some other Ada make programs, the dependencies are always +accurately recomputed from the new sources. The source based approach of +the GNAT compilation model makes this possible. This means that if +changes to the source program cause corresponding changes in +dependencies, they will always be tracked exactly correctly by +@command{gnatmake}. + +@node Running gnatmake +@section Running @command{gnatmake} + +@noindent +The usual form of the @command{gnatmake} command is + +@smallexample +@c $ gnatmake @ovar{switches} @var{file_name} +@c @ovar{file_names} @ovar{mode_switches} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatmake @r{[}@var{switches}@r{]} @var{file_name} + @r{[}@var{file_names}@r{]} @r{[}@var{mode_switches}@r{]} +@end smallexample + +@noindent +The only required argument is one @var{file_name}, which specifies +a compilation unit that is a main program. Several @var{file_names} can be +specified: this will result in several executables being built. +If @code{switches} are present, they can be placed before the first +@var{file_name}, between @var{file_names} or after the last @var{file_name}. +If @var{mode_switches} are present, they must always be placed after +the last @var{file_name} and all @code{switches}. + +If you are using standard file extensions (@file{.adb} and @file{.ads}), then the +extension may be omitted from the @var{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 @var{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 +@command{gnatmake} was invoked and if it is not found, it will be search on +the source path of the compiler as described in +@ref{Search Paths and the Run-Time Library (RTL)}. + +All @command{gnatmake} output (except when you specify +@option{^-M^/DEPENDENCIES_LIST^}) is to +@file{stderr}. The output produced by the +@option{^-M^/DEPENDENCIES_LIST^} switch is send to +@file{stdout}. + +@node Switches for gnatmake +@section Switches for @command{gnatmake} + +@noindent +You may specify any of the following switches to @command{gnatmake}: + +@table @option +@c !sort! + +@item --version +@cindex @option{--version} @command{gnatmake} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatmake} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@ifclear vms +@item --GCC=@var{compiler_name} +@cindex @option{--GCC=compiler_name} (@command{gnatmake}) +Program used for compiling. The default is `@command{gcc}'. You need to use +quotes around @var{compiler_name} if @code{compiler_name} contains +spaces or other separator characters. As an example @option{--GCC="foo -x +-y"} will instruct @command{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 @option{-c} is always inserted after your command name. Thus in the +above example the compiler command that will be used by @command{gnatmake} +will be @code{foo -c -x -y}. If several @option{--GCC=compiler_name} are +used, only the last @var{compiler_name} is taken into account. However, +all the additional switches are also taken into account. Thus, +@option{--GCC="foo -x -y" --GCC="bar -z -t"} is equivalent to +@option{--GCC="bar -x -y -z -t"}. + +@item --GNATBIND=@var{binder_name} +@cindex @option{--GNATBIND=binder_name} (@command{gnatmake}) +Program used for binding. The default is `@code{gnatbind}'. You need to +use quotes around @var{binder_name} if @var{binder_name} contains spaces +or other separator characters. As an example @option{--GNATBIND="bar -x +-y"} will instruct @command{gnatmake} to use @code{bar -x -y} as your +binder. Binder switches that are normally appended by @command{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. + +@item --GNATLINK=@var{linker_name} +@cindex @option{--GNATLINK=linker_name} (@command{gnatmake}) +Program used for linking. The default is `@command{gnatlink}'. You need to +use quotes around @var{linker_name} if @var{linker_name} contains spaces +or other separator characters. As an example @option{--GNATLINK="lan -x +-y"} will instruct @command{gnatmake} to use @code{lan -x -y} as your +linker. Linker switches that are normally appended by @command{gnatmake} to +`@command{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 +itself must not include any embedded spaces. + +@end ifclear + +@item ^--subdirs^/SUBDIRS^=subdir +Actual object directory of each project file is the subdirectory subdir of the +object directory specified or defaulted in the project file. + +@item ^--single-compile-per-obj-dir^/SINGLE_COMPILE_PER_OBJ_DIR^ +Disallow simultaneous compilations in the same object directory when +project files are used. + +@item ^--unchecked-shared-lib-imports^/UNCHECKED_SHARED_LIB_IMPORTS^ +By default, shared library projects are not allowed to import static library +projects. When this switch is used on the command line, this restriction is +relaxed. + +@item ^--source-info=^/SRC_INFO=source-info-file^ +Specify a source info file. This switch is active only when project files +are used. If the source info file is specified as a relative path, then it is +relative to the object directory of the main project. If the source info file +does not exist, then after the Project Manager has successfully parsed and +processed the project files and found the sources, it creates the source info +file. If the source info file already exists and can be read successfully, +then the Project Manager will get all the needed information about the sources +from the source info file and will not look for them. This reduces the time +to process the project files, especially when looking for sources that take a +long time. If the source info file exists but cannot be parsed successfully, +the Project Manager will attempt to recreate it. If the Project Manager fails +to create the source info file, a message is issued, but gnatmake does not +fail. + +@ifclear vms +@item --create-map-file +When linking an executable, create a map file. The name of the map file +has the same name as the executable with extension ".map". + +@item --create-map-file=mapfile +When linking an executable, create a map file. The name of the map file is +"mapfile". + +@end ifclear + +@item ^-a^/ALL_FILES^ +@cindex @option{^-a^/ALL_FILES^} (@command{gnatmake}) +Consider all files in the make process, even the GNAT internal system +files (for example, the predefined Ada library files), as well as any +locked files. Locked files are files whose ALI file is write-protected. +By default, +@command{gnatmake} does not check these files, +because the assumption is that the GNAT internal files are properly up +to date, and also that any write protected ALI files have been properly +installed. Note that if there is an installation problem, such that one +of these files is not up to date, it will be properly caught by the +binder. +You may have to specify this switch if you are working on GNAT +itself. The switch @option{^-a^/ALL_FILES^} is also useful +in conjunction with @option{^-f^/FORCE_COMPILE^} +if you need to recompile an entire application, +including run-time files, using special configuration pragmas, +such as a @code{Normalize_Scalars} pragma. + +By default +@code{gnatmake ^-a^/ALL_FILES^} compiles all GNAT +internal files with +@ifclear vms +@code{gcc -c -gnatpg} rather than @code{gcc -c}. +@end ifclear +@ifset vms +the @code{/CHECKS=SUPPRESS_ALL /STYLE_CHECKS=GNAT} switch. +@end ifset + +@item ^-b^/ACTIONS=BIND^ +@cindex @option{^-b^/ACTIONS=BIND^} (@command{gnatmake}) +Bind only. Can be combined with @option{^-c^/ACTIONS=COMPILE^} to do +compilation and binding, but no link. +Can be combined with @option{^-l^/ACTIONS=LINK^} +to do binding and linking. When not combined with +@option{^-c^/ACTIONS=COMPILE^} +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 @var{file_name} +may be given without extension, with the source extension or, if no GNAT +Project File is specified, with the ALI file extension. + +@item ^-c^/ACTIONS=COMPILE^ +@cindex @option{^-c^/ACTIONS=COMPILE^} (@command{gnatmake}) +Compile only. Do not perform binding, except when @option{^-b^/ACTIONS=BIND^} +is also specified. Do not perform linking, except if both +@option{^-b^/ACTIONS=BIND^} and +@option{^-l^/ACTIONS=LINK^} are also specified. +If the root unit specified by @var{file_name} is not a main unit, this is the +default. Otherwise @command{gnatmake} will attempt binding and linking +unless all objects are up to date and the executable is more recent than +the objects. + +@item ^-C^/MAPPING^ +@cindex @option{^-C^/MAPPING^} (@command{gnatmake}) +Use a temporary mapping file. A mapping file is a way to communicate +to the compiler two mappings: from unit names to file names (without +any directory information) and from file names to path names (with +full directory information). A mapping file can make the compiler's +file searches faster, especially if there are many source directories, +or the sources are read over a slow network connection. If +@option{^-P^/PROJECT_FILE^} is used, a mapping file is always used, so +@option{^-C^/MAPPING^} is unnecessary; in this case the mapping file +is initially populated based on the project file. If +@option{^-C^/MAPPING^} is used without +@option{^-P^/PROJECT_FILE^}, +the mapping file is initially empty. Each invocation of the compiler +will add any newly accessed sources to the mapping file. + +@item ^-C=^/USE_MAPPING_FILE=^@var{file} +@cindex @option{^-C=^/USE_MAPPING^} (@command{gnatmake}) +Use a specific mapping file. The file, specified as a path name (absolute or +relative) by this switch, should already exist, otherwise the switch is +ineffective. The specified mapping file will be communicated to the compiler. +This switch is not compatible with a project file +(^-P^/PROJECT_FILE=^@var{file}) or with multiple compiling processes +(^-j^/PROCESSES=^nnn, when nnn is greater than 1). + +@item ^-d^/DISPLAY_PROGRESS^ +@cindex @option{^-d^/DISPLAY_PROGRESS^} (@command{gnatmake}) +Display progress for each source, up to date or not, as a single line + +@smallexample +completed x out of y (zz%) +@end smallexample + +If the file needs to be compiled this is displayed after the invocation of +the compiler. These lines are displayed even in quiet output mode. + +@item ^-D ^/DIRECTORY_OBJECTS=^@var{dir} +@cindex @option{^-D^/DIRECTORY_OBJECTS^} (@command{gnatmake}) +Put all object files and ALI file in directory @var{dir}. +If the @option{^-D^/DIRECTORY_OBJECTS^} 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. + +@ifclear vms +@item -eL +@cindex @option{-eL} (@command{gnatmake}) +@cindex symbolic links +Follow all symbolic links when processing project files. +This should be used if your project uses symbolic links for files or +directories, but is not needed in other cases. + +@cindex naming scheme +This also assumes that no directory matches the naming scheme for files (for +instance that you do not have a directory called "sources.ads" when using the +default GNAT naming scheme). + +When you do not have to use this switch (i.e.@: by default), gnatmake is able to +save a lot of system calls (several per source file and object file), which +can result in a significant speed up to load and manipulate a project file, +especially when using source files from a remote system. + +@end ifclear + +@item ^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^ +@cindex @option{^-eS^/STANDARD_OUTPUT_FOR_COMMANDS^} (@command{gnatmake}) +Output the commands for the compiler, the binder and the linker +on ^standard output^SYS$OUTPUT^, +instead of ^standard error^SYS$ERROR^. + +@item ^-f^/FORCE_COMPILE^ +@cindex @option{^-f^/FORCE_COMPILE^} (@command{gnatmake}) +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 @option{^-a^/ALL_FILES^} switch is also specified. + +@item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^ +@cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@command{gnatmake}) +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^/VERBOSE^), then error lines start with the full path name of the project +file, rather than its simple file name. + +@item ^-g^/DEBUG^ +@cindex @option{^-g^/DEBUG^} (@command{gnatmake}) +Enable debugging. This switch is simply passed to the compiler and to the +linker. + +@item ^-i^/IN_PLACE^ +@cindex @option{^-i^/IN_PLACE^} (@command{gnatmake}) +In normal mode, @command{gnatmake} compiles all object files and ALI files +into the current directory. If the @option{^-i^/IN_PLACE^} 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 @command{gnatmake} will automatically +maintain and update this organization. If no ALI files are found on the +Ada object path (@ref{Search Paths and the Run-Time Library (RTL)}), +the new object and ALI files are created in the +directory containing the source being compiled. If another organization +is desired, where objects and sources are kept in different directories, +a useful technique is to create dummy ALI files in the desired directories. +When detecting such a dummy file, @command{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. + +@item ^-j^/PROCESSES=^@var{n} +@cindex @option{^-j^/PROCESSES^} (@command{gnatmake}) +@cindex Parallel make +Use @var{n} processes to carry out the (re)compilations. On a +multiprocessor machine compilations will occur in parallel. In the +event of compilation errors, messages from various compilations might +get interspersed (but @command{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. + +@item ^-k^/CONTINUE_ON_ERROR^ +@cindex @option{^-k^/CONTINUE_ON_ERROR^} (@command{gnatmake}) +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 @command{gnatmake} +terminates. + +If @command{gnatmake} is invoked with several @file{file_names} and with this +switch, if there are compilation errors when building an executable, +@command{gnatmake} will not attempt to build the following executables. + +@item ^-l^/ACTIONS=LINK^ +@cindex @option{^-l^/ACTIONS=LINK^} (@command{gnatmake}) +Link only. Can be combined with @option{^-b^/ACTIONS=BIND^} to binding +and linking. Linking will not be performed if combined with +@option{^-c^/ACTIONS=COMPILE^} +but not with @option{^-b^/ACTIONS=BIND^}. +When not combined with @option{^-b^/ACTIONS=BIND^} +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 @var{file_name} +may be given without extension, with the source extension or, if no GNAT +Project File is specified, with the ALI file extension. + +@item ^-m^/MINIMAL_RECOMPILATION^ +@cindex @option{^-m^/MINIMAL_RECOMPILATION^} (@command{gnatmake}) +Specify that the minimum necessary amount of recompilations +be performed. In this mode @command{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 @command{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 @option{-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. + +@item ^-M^/DEPENDENCIES_LIST^ +@cindex Dependencies, producing list +@cindex @option{^-M^/DEPENDENCIES_LIST^} (@command{gnatmake}) +Check if all objects are up to date. If they are, output the object +dependences to @file{stdout} in a form that can be directly exploited in +a @file{Makefile}. By default, each source file is prefixed with its +(relative or absolute) directory name. This name is whatever you +specified in the various @option{^-aI^/SOURCE_SEARCH^} +and @option{^-I^/SEARCH^} switches. If you use +@code{gnatmake ^-M^/DEPENDENCIES_LIST^} +@option{^-q^/QUIET^} +(see below), only the source file names, +without relative paths, are output. If you just specify the +@option{^-M^/DEPENDENCIES_LIST^} +switch, dependencies of the GNAT internal system files are omitted. This +is typically what you want. If you also specify +the @option{^-a^/ALL_FILES^} switch, +dependencies of the GNAT internal files are also listed. Note that +dependencies of the objects in external Ada libraries (see switch +@option{^-aL^/SKIP_MISSING=^}@var{dir} in the following list) +are never reported. + +@item ^-n^/DO_OBJECT_CHECK^ +@cindex @option{^-n^/DO_OBJECT_CHECK^} (@command{gnatmake}) +Don't compile, bind, or link. Checks if all objects are up to date. +If they are not, the full name of the first file that needs to be +recompiled is printed. +Repeated use of this option, followed by compiling the indicated source +file, will eventually result in recompiling all required units. + +@item ^-o ^/EXECUTABLE=^@var{exec_name} +@cindex @option{^-o^/EXECUTABLE^} (@command{gnatmake}) +Output executable name. The name of the final executable program will be +@var{exec_name}. If the @option{^-o^/EXECUTABLE^} 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 @command{gnatmake} with several +@file{file_names}. + +@item ^-p or --create-missing-dirs^/CREATE_MISSING_DIRS^ +@cindex @option{^-p^/CREATE_MISSING_DIRS^} (@command{gnatmake}) +When using project files (^-P^/PROJECT_FILE=^@var{project}), create +automatically missing object directories, library directories and exec +directories. + +@item ^-P^/PROJECT_FILE=^@var{project} +@cindex @option{^-P^/PROJECT_FILE^} (@command{gnatmake}) +Use project file @var{project}. Only one such switch can be used. +@xref{gnatmake and Project Files}. + +@item ^-q^/QUIET^ +@cindex @option{^-q^/QUIET^} (@command{gnatmake}) +Quiet. When this flag is not set, the commands carried out by +@command{gnatmake} are displayed. + +@item ^-s^/SWITCH_CHECK/^ +@cindex @option{^-s^/SWITCH_CHECK^} (@command{gnatmake}) +Recompile if compiler switches have changed since last compilation. +All compiler switches but -I and -o are taken into account in the +following way: +orders between different ``first letter'' switches are ignored, but +orders between same switches are taken into account. For example, +@option{-O -O2} is different than @option{-O2 -O}, but @option{-g -O} +is equivalent to @option{-O -g}. + +This switch is recommended when Integrated Preprocessing is used. + +@item ^-u^/UNIQUE^ +@cindex @option{^-u^/UNIQUE^} (@command{gnatmake}) +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^/UNIQUE^ with a project file and no main has a special meaning +(@pxref{Project Files and Main Subprograms}). + +@item ^-U^/ALL_PROJECTS^ +@cindex @option{^-U^/ALL_PROJECTS^} (@command{gnatmake}) +When used without a project file or with one or several mains on the command +line, is equivalent to ^-u^/UNIQUE^. When used with a project file and no main +on the command line, all sources of all project files are checked and compiled +if not up to date, and libraries are rebuilt, if necessary. + +@item ^-v^/REASONS^ +@cindex @option{^-v^/REASONS^} (@command{gnatmake}) +Verbose. Display the reason for all recompilations @command{gnatmake} +decides are necessary, with the highest verbosity level. + +@item ^-vl^/LOW_VERBOSITY^ +@cindex @option{^-vl^/LOW_VERBOSITY^} (@command{gnatmake}) +Verbosity level Low. Display fewer lines than in verbosity Medium. + +@item ^-vm^/MEDIUM_VERBOSITY^ +@cindex @option{^-vm^/MEDIUM_VERBOSITY^} (@command{gnatmake}) +Verbosity level Medium. Potentially display fewer lines than in verbosity High. + +@item ^-vh^/HIGH_VERBOSITY^ +@cindex @option{^-vm^/HIGH_VERBOSITY^} (@command{gnatmake}) +Verbosity level High. Equivalent to ^-v^/REASONS^. + +@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} +Indicate the verbosity of the parsing of GNAT project files. +@xref{Switches Related to Project Files}. + +@item ^-x^/NON_PROJECT_UNIT_COMPILATION^ +@cindex @option{^-x^/NON_PROJECT_UNIT_COMPILATION^} (@command{gnatmake}) +Indicate that sources that are not part of any Project File may be compiled. +Normally, when using Project Files, only sources that are part of a Project +File may be compile. When this switch is used, a source outside of all Project +Files may be compiled. The ALI file and the object file will be put in the +object directory of the main Project. The compilation switches used will only +be those specified on the command line. Even when +@option{^-x^/NON_PROJECT_UNIT_COMPILATION^} is used, mains specified on the +command line need to be sources of a project file. + +@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} +Indicate that external variable @var{name} has the value @var{value}. +The Project Manager will use this value for occurrences of +@code{external(name)} when parsing the project file. +@xref{Switches Related to Project Files}. + +@item ^-z^/NOMAIN^ +@cindex @option{^-z^/NOMAIN^} (@command{gnatmake}) +No main subprogram. Bind and link the program even if the unit name +given on the command line is a package name. The resulting executable +will execute the elaboration routines of the package and its closure, +then the finalization routines. + +@end table + +@table @asis +@item @command{gcc} @asis{switches} +@ifclear vms +Any uppercase or multi-character switch that is not a @command{gnatmake} switch +is passed to @command{gcc} (e.g.@: @option{-O}, @option{-gnato,} etc.) +@end ifclear +@ifset vms +Any qualifier that cannot be recognized as a qualifier for @code{GNAT MAKE} +but is recognizable as a valid qualifier for @code{GNAT COMPILE} is +automatically treated as a compiler switch, and passed on to all +compilations that are carried out. +@end ifset +@end table + +@noindent +Source and library search path switches: + +@table @option +@c !sort! +@item ^-aI^/SOURCE_SEARCH=^@var{dir} +@cindex @option{^-aI^/SOURCE_SEARCH^} (@command{gnatmake}) +When looking for source files also look in directory @var{dir}. +The order in which source files search is undertaken is +described in @ref{Search Paths and the Run-Time Library (RTL)}. + +@item ^-aL^/SKIP_MISSING=^@var{dir} +@cindex @option{^-aL^/SKIP_MISSING^} (@command{gnatmake}) +Consider @var{dir} as being an externally provided Ada library. +Instructs @command{gnatmake} to skip compilation units whose @file{.ALI} +files have been located in directory @var{dir}. This allows you to have +missing bodies for the units in @var{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 +@option{^-aI^/SOURCE_SEARCH=^@var{dir}} +or @option{^-I^/SEARCH=^@var{dir}}. +Note: this switch is provided for compatibility with previous versions +of @command{gnatmake}. The easier method of causing standard libraries +to be excluded from consideration is to write-protect the corresponding +ALI files. + +@item ^-aO^/OBJECT_SEARCH=^@var{dir} +@cindex @option{^-aO^/OBJECT_SEARCH^} (@command{gnatmake}) +When searching for library and object files, look in directory +@var{dir}. The order in which library files are searched is described in +@ref{Search Paths for gnatbind}. + +@item ^-A^/CONDITIONAL_SOURCE_SEARCH=^@var{dir} +@cindex Search paths, for @command{gnatmake} +@cindex @option{^-A^/CONDITIONAL_SOURCE_SEARCH^} (@command{gnatmake}) +Equivalent to @option{^-aL^/SKIP_MISSING=^@var{dir} +^-aI^/SOURCE_SEARCH=^@var{dir}}. + +@item ^-I^/SEARCH=^@var{dir} +@cindex @option{^-I^/SEARCH^} (@command{gnatmake}) +Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir} +^-aI^/SOURCE_SEARCH=^@var{dir}}. + +@item ^-I-^/NOCURRENT_DIRECTORY^ +@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@command{gnatmake}) +@cindex Source files, suppressing search +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 @command{gnatmake} was invoked. + +@item ^-L^/LIBRARY_SEARCH=^@var{dir} +@cindex @option{^-L^/LIBRARY_SEARCH^} (@command{gnatmake}) +@cindex Linker libraries +Add directory @var{dir} to the list of directories in which the linker +will search for libraries. This is equivalent to +@option{-largs ^-L^/LIBRARY_SEARCH=^}@var{dir}. +@ifclear vms +Furthermore, under Windows, the sources pointed to by the libraries path +set in the registry are not searched for. +@end ifclear + +@item -nostdinc +@cindex @option{-nostdinc} (@command{gnatmake}) +Do not look for source files in the system default directory. + +@item -nostdlib +@cindex @option{-nostdlib} (@command{gnatmake}) +Do not look for library files in the system default directory. + +@item --RTS=@var{rts-path} +@cindex @option{--RTS} (@command{gnatmake}) +Specifies the default location of the runtime library. GNAT looks for the +runtime +in the following directories, and stops as soon as a valid runtime is found +(@file{adainclude} or @file{ada_source_path}, and @file{adalib} or +@file{ada_object_path} present): + +@itemize @bullet +@item /$rts_path + +@item /$rts_path + +@item /rts-$rts_path +@end itemize + +@noindent +The selected path is handled like a normal RTS path. + +@end table + +@node Mode Switches for gnatmake +@section Mode Switches for @command{gnatmake} + +@noindent +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 +mode switch, to be interpreted as switches to be passed on to the +designated component of GNAT. + +@table @option +@c !sort! +@item -cargs @var{switches} +@cindex @option{-cargs} (@command{gnatmake}) +Compiler switches. Here @var{switches} is a list of switches +that are valid switches for @command{gcc}. They will be passed on to +all compile steps performed by @command{gnatmake}. + +@item -bargs @var{switches} +@cindex @option{-bargs} (@command{gnatmake}) +Binder switches. Here @var{switches} is a list of switches +that are valid switches for @code{gnatbind}. They will be passed on to +all bind steps performed by @command{gnatmake}. + +@item -largs @var{switches} +@cindex @option{-largs} (@command{gnatmake}) +Linker switches. Here @var{switches} is a list of switches +that are valid switches for @command{gnatlink}. They will be passed on to +all link steps performed by @command{gnatmake}. + +@item -margs @var{switches} +@cindex @option{-margs} (@command{gnatmake}) +Make switches. The switches are directly interpreted by @command{gnatmake}, +regardless of any previous occurrence of @option{-cargs}, @option{-bargs} +or @option{-largs}. +@end table + +@node Notes on the Command Line +@section Notes on the Command Line + +@noindent +This section contains some additional useful notes on the operation +of the @command{gnatmake} command. + +@itemize @bullet +@item +@cindex Recompilation, by @command{gnatmake} +If @command{gnatmake} finds no ALI files, it recompiles the main program +and all other units required by the main program. +This means that @command{gnatmake} +can be used for the initial compile, as well as during subsequent steps of +the development cycle. + +@item +If you enter @code{gnatmake @var{file}.adb}, where @file{@var{file}.adb} +is a subunit or body of a generic unit, @command{gnatmake} recompiles +@file{@var{file}.adb} (because it finds no ALI) and stops, issuing a +warning. + +@item +In @command{gnatmake} the switch @option{^-I^/SEARCH^} +is used to specify both source and +library file paths. Use @option{^-aI^/SOURCE_SEARCH^} +instead if you just want to specify +source paths only and @option{^-aO^/OBJECT_SEARCH^} +if you want to specify library paths +only. + +@item +@command{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 +@option{^-f^/FORCE_COMPILE^} switch will not recompile these files +unless @option{^-a^/ALL_FILES^} is also specified. + +@item +@command{gnatmake} has been designed to make the use of Ada libraries +particularly convenient. Assume you have an Ada library organized +as follows: @i{^obj-dir^[OBJ_DIR]^} contains the objects and ALI files for +of your Ada compilation units, +whereas @i{^include-dir^[INCLUDE_DIR]^} contains the +specs of these units, but no bodies. Then to compile a unit +stored in @code{main.adb}, which uses this Ada library you would just type + +@smallexample +@ifclear vms +$ gnatmake -aI@var{include-dir} -aL@var{obj-dir} main +@end ifclear +@ifset vms +$ gnatmake /SOURCE_SEARCH=@i{[INCLUDE_DIR]} + /SKIP_MISSING=@i{[OBJ_DIR]} main +@end ifset +@end smallexample + +@item +Using @command{gnatmake} along with the +@option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^} +switch provides a mechanism for avoiding unnecessary recompilations. Using +this switch, +you can update the comments/format of your +source files without having to recompile everything. Note, however, that +adding or deleting lines in a source files may render its debugging +info obsolete. If the file in question is a spec, the impact is rather +limited, as that debugging info will only be useful during the +elaboration phase of your program. For bodies the impact can be more +significant. In all events, your debugger will warn you if a source file +is more recent than the corresponding object, and alert you to the fact +that the debugging information may be out of date. +@end itemize + +@node How gnatmake Works +@section How @command{gnatmake} Works + +@noindent +Generally @command{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 @command{gnatmake} +approach and in particular to understand how it uses the results of +previous compilations without incorrectly depending on them. + +First a definition: an object file is considered @dfn{up to date} if the +corresponding ALI file exists and if all the source files listed in the +dependency section of this ALI file have time stamps matching those in +the ALI file. This means that neither the source file itself nor any +files that it depends on have been modified, and hence there is no need +to recompile this file. + +@command{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, +@command{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 @command{gnatmake} recursively applies the above procedure on all these +files. + +This process ensures that @command{gnatmake} only trusts the dependencies +in an existing ALI file if they are known to be correct. Otherwise it +always recompiles to determine a new, guaranteed accurate set of +dependencies. As a result the program is compiled ``upside down'' from what may +be more familiar as the required order of compilation in some other Ada +systems. In particular, clients are compiled before the units on which +they depend. The ability of GNAT to compile in any order is critical in +allowing an order of compilation to be chosen that guarantees that +@command{gnatmake} will recompute a correct set of new dependencies if +necessary. + +When invoking @command{gnatmake} with several @var{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 +(@pxref{Using Other File Names}), changing through a configuration pragmas +file the version of a source and invoking @command{gnatmake} to recompile may +have no effect, if the previous version of the source is still accessible +by @command{gnatmake}. It may be necessary to use the switch +^-f^/FORCE_COMPILE^. + +@node Examples of gnatmake Usage +@section Examples of @command{gnatmake} Usage + +@table @code +@item gnatmake hello.adb +Compile all files necessary to bind and link the main program +@file{hello.adb} (containing unit @code{Hello}) and bind and link the +resulting object files to generate an executable file @file{^hello^HELLO.EXE^}. + +@item gnatmake main1 main2 main3 +Compile all files necessary to bind and link the main programs +@file{main1.adb} (containing unit @code{Main1}), @file{main2.adb} +(containing unit @code{Main2}) and @file{main3.adb} +(containing unit @code{Main3}) and bind and link the resulting object files +to generate three executable files @file{^main1^MAIN1.EXE^}, +@file{^main2^MAIN2.EXE^} +and @file{^main3^MAIN3.EXE^}. + +@ifclear vms +@item gnatmake -q Main_Unit -cargs -O2 -bargs -l +@end ifclear + +@ifset vms +@item gnatmake Main_Unit /QUIET +/COMPILER_QUALIFIERS /OPTIMIZE=ALL +/BINDER_QUALIFIERS /ORDER_OF_ELABORATION +@end ifset +Compile all files necessary to bind and link the main program unit +@code{Main_Unit} (from file @file{main_unit.adb}). All compilations will +be done with optimization level 2 and the order of elaboration will be +listed by the binder. @command{gnatmake} will operate in quiet mode, not +displaying commands it is executing. +@end table + +@c ************************* +@node Improving Performance +@chapter Improving Performance +@cindex Improving performance + +@noindent +This chapter 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 @command{gnatelim} tool and unused subprogram/data +elimination feature, which can reduce the size of program executables. + +Note: to invoke @command{gnatelim} with a project file, use the @code{gnat} +driver (see @ref{The GNAT Driver and Project Files}). + +@ifnottex +@menu +* Performance Considerations:: +* Text_IO Suggestions:: +* Reducing Size of Ada Executables with gnatelim:: +* Reducing Size of Executables with unused subprogram/data elimination:: +@end menu +@end ifnottex + +@c ***************************** +@node Performance Considerations +@section Performance Considerations + +@noindent +The GNAT system provides a number of options that allow a trade-off +between + +@itemize @bullet +@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 + +@noindent +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 @bullet +@item +no optimization + +@item +no inlining of subprogram calls + +@item +all run-time checks enabled except overflow and elaboration checks +@end itemize + +@noindent +These options are suitable for most program development purposes. This +chapter 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:: +* Other Optimization Switches:: +* Optimization and Strict Aliasing:: + +@ifset vms +* Coverage Analysis:: +@end ifset +@end menu + +@node Controlling Run-Time Checks +@subsection Controlling Run-Time Checks + +@noindent +By default, GNAT generates all run-time checks, except integer overflow +checks, stack overflow checks, and checks for access before elaboration on +subprogram calls. The latter are not required in default mode, because all +necessary checking is done at compile time. +@cindex @option{-gnatp} (@command{gcc}) +@cindex @option{-gnato} (@command{gcc}) +Two gnat switches, @option{-gnatp} and @option{-gnato} allow this default to +be modified. @xref{Run-Time Checks}. + +Our experience is that the default is suitable for most development +purposes. + +We treat integer overflow specially because these +are quite expensive and in our experience are not as important as other +run-time checks in the development process. Note that division by zero +is not considered an overflow check, and divide by zero checks are +generated where required by default. + +Elaboration checks are off by default, and also not needed by default, since +GNAT uses a static elaboration analysis approach that avoids the need for +run-time checking. This manual contains a full chapter discussing the issue +of elaboration checks, and if the default is not satisfactory for your use, +you should read this chapter. + +For validity checks, the minimal checks required by the Ada Reference +Manual (for case statements and assignments to array elements) are on +by default. These can be suppressed by use of the @option{-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 @option{-gnatVn}. Validity checks +are also suppressed entirely if @option{-gnatp} is used. + +@cindex Overflow checks +@cindex Checks, overflow +@findex Suppress +@findex Unsuppress +@cindex pragma Suppress +@cindex pragma Unsuppress +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. + +@node Use of Restrictions +@subsection Use of Restrictions + +@noindent +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 @code{abort} statement, nor asynchronous transfer +of control (@code{select @dots{} 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 + +@smallexample @c ada + pragma Restrictions (No_Abort_Statements); + pragma Restrictions (Max_Asynchronous_Select_Nesting => 0); +@end smallexample + +@noindent +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 +@subsection Optimization Levels +@cindex @option{^-O^/OPTIMIZE^} (@command{gcc}) + +@noindent +Without any optimization ^option,^qualifier,^ +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,^/OPTIMIZE qualifiers,^ +the last such option is the one that is effective. + +@noindent +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 +@ifclear vms +@option{-O} switch (the permitted forms are @option{-O0}, @option{-O1} +@option{-O2}, @option{-O3}, and @option{-Os}) +@end ifclear +@ifset vms +@code{OPTIMIZE} qualifier +@end ifset +to @command{gcc} to control the optimization level: + +@table @option +@item ^-O0^/OPTIMIZE=NONE^ +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^/OPTIMIZE=NONE^ for production if +execution time is of any concern, since ^-O0^/OPTIMIZE=NONE^ +really does mean no optimization at all. This difference between +gcc and other compilers should be kept in mind when doing +performance comparisons. + +@item ^-O1^/OPTIMIZE=SOME^ +Moderate optimization; +optimizes reasonably well but does not +degrade compilation time significantly. + +@item ^-O2^/OPTIMIZE=ALL^ +@ifset vms +@itemx /OPTIMIZE=DEVELOPMENT +@end ifset +Full optimization; +generates highly optimized code and has +the slowest compilation time. + +@item ^-O3^/OPTIMIZE=INLINING^ +Full optimization as in @option{-O2}; +also uses more aggressive automatic inlining of subprograms within a unit +(@pxref{Inlining of Subprograms}) and attempts to vectorize loops. + +@item ^-Os^/OPTIMIZE=SPACE^ +Optimize space usage (code and data) of resulting program. +@end table + +@noindent +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. +@xref{Optimize Options,, Options That Control Optimization, gcc, Using +the GNU Compiler Collection (GCC)}, for details about +^the @option{-O} settings and a number of @option{-f} options that^how to^ +individually enable or disable specific optimizations. + +Unlike some other compilation systems, ^@command{gcc}^GNAT^ 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 @option{-O3}: The use of this optimization level +is generally discouraged with GNAT, since it often results in larger +executables which may run more slowly. See further discussion of this point +in @ref{Inlining of Subprograms}. + +@node Debugging Optimized Code +@subsection Debugging Optimized Code +@cindex Debugging optimized code +@cindex Optimization and debugging + +@noindent +Although it is possible to do a reasonable amount of debugging at +@ifclear vms +nonzero optimization levels, +the higher the level the more likely that +@end ifclear +@ifset vms +@option{/OPTIMIZE} settings other than @code{NONE}, +such settings will make it more likely that +@end ifset +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 @option{-O2} or @option{-O3}. +Explicit temporary variables that you code might be eliminated at +^level^setting^ @option{-O1} or higher. + +The use of the @option{^-g^/DEBUG^} switch, +@cindex @option{^-g^/DEBUG^} (@command{gcc}) +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: + +@enumerate +@item +@i{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 @bullet +@item +@i{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 +@i{Invariant code motion:} moving an expression that does not change within a +loop, to the beginning of the loop. + +@item +@i{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 +@i{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^switch^} statement. + +@item +@i{The ``roving variable'':} The symptom is an unexpected value in a variable. +There are various reasons for this effect: + +@itemize @bullet +@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 + +@noindent +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 enumerate + +@noindent +In light of such anomalies, a recommended technique is to use @option{-O0} +early in the software development cycle, when extensive debugging capabilities +are most needed, and then move to @option{-O1} and later @option{-O2} as +the debugger becomes less critical. +Whether to use the @option{^-g^/DEBUG^} switch in the release version is +a release management issue. +@ifclear vms +Note that if you use @option{-g} you can then use the @command{strip} program +on the resulting executable, +which removes both debugging information and global symbols. +@end ifclear + +@node Inlining of Subprograms +@subsection Inlining of Subprograms + +@noindent +A call to a subprogram in the current unit is inlined if all the +following conditions are met: + +@itemize @bullet +@item +The optimization level is at least @option{-O1}. + +@item +The called subprogram is suitable for inlining: It must be small enough +and not contain something that @command{gcc} cannot support in inlined +subprograms. + +@item +@cindex pragma Inline +@findex Inline +Any one of the following applies: @code{pragma Inline} is applied to the +subprogram and the @option{^-gnatn^/INLINE^} switch is specified; the +subprogram is local to the unit and called once from within it; the +subprogram is small and optimization level @option{-O2} is specified; +optimization level @option{-O3}) is specified. +@end itemize + +@noindent +Calls to subprograms in @code{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 @bullet +@item +The optimization level is at least @option{-O1}. + +@item +The called subprogram is suitable for inlining: It must be small enough +and not contain something that @command{gcc} cannot support in inlined +subprograms. + +@item +The call appears in a body (not in a package spec). + +@item +There is a @code{pragma Inline} for the subprogram. + +@item +The @option{^-gnatn^/INLINE^} 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 @option{-gnatn} switch causes additional +compilation dependencies. Consider the following: + +@smallexample @c ada +@cartouche +package R is + procedure Q; + pragma Inline (Q); +end R; +package body R is + @dots{} +end R; + +with R; +procedure Main is +begin + @dots{} + R.Q; +end Main; +@end cartouche +@end smallexample + +@noindent +With the default behavior (no @option{-gnatn} switch specified), the +compilation of the @code{Main} procedure depends only on its own source, +@file{main.adb}, and the spec of the package in file @file{r.ads}. This +means that editing the body of @code{R} does not require recompiling +@code{Main}. + +On the other hand, the call @code{R.Q} is not inlined under these +circumstances. If the @option{-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 +@file{r.adb} as well as on the spec. This means that if this body is edited, +the main program must be recompiled. Note that this extra dependency +occurs whether or not the call is in fact inlined by @command{gcc}. + +The use of front end inlining with @option{-gnatN} generates similar +additional dependencies. + +@cindex @option{^-fno-inline^/INLINE=SUPPRESS^} (@command{gcc}) +Note: The @option{^-fno-inline^/INLINE=SUPPRESS^} switch +can be used to prevent +all inlining. This switch overrides all other conditions and ensures +that no inlining occurs. The extra dependences resulting from +@option{-gnatn} will still be active, even if +this switch is used to suppress the resulting inlining actions. + +@cindex @option{-fno-inline-functions} (@command{gcc}) +Note: The @option{-fno-inline-functions} switch can be used to prevent +automatic inlining of subprograms if @option{-O3} is used. + +@cindex @option{-fno-inline-small-functions} (@command{gcc}) +Note: The @option{-fno-inline-small-functions} switch can be used to prevent +automatic inlining of small subprograms if @option{-O2} is used. + +@cindex @option{-fno-inline-functions-called-once} (@command{gcc}) +Note: The @option{-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 @option{-O1} is used. + +Note regarding the use of @option{-O3}: There is no difference in inlining +behavior between @option{-O2} and @option{-O3} for subprograms with an explicit +pragma @code{Inline} assuming the use of @option{-gnatn} +or @option{-gnatN} (the switches that activate inlining). If you have used +pragma @code{Inline} in appropriate cases, then it is usually much better +to use @option{-O2} and @option{-gnatn} and avoid the use of @option{-O3} which +in this case only has the effect of inlining subprograms you did not +think should be inlined. We often find that the use of @option{-O3} slows +down code by performing excessive inlining, leading to increased instruction +cache pressure from the increased code size. So the bottom line here is +that you should not automatically assume that @option{-O3} is better than +@option{-O2}, and indeed you should use @option{-O3} only if tests show that +it actually improves performance. + +@node Other Optimization Switches +@subsection Other Optimization Switches +@cindex Optimization Switches + +Since @code{GNAT} uses the @command{gcc} back end, all the specialized +@command{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 +@option{-funroll-loops} and +the various target-specific @option{-m} options (in particular, it has been +observed that @option{-march=pentium4} can significantly improve performance +on appropriate machines). For full details of these switches, see +@ref{Submodel Options,, Hardware Models and Configurations, gcc, Using +the GNU Compiler Collection (GCC)}. + +@node Optimization and Strict Aliasing +@subsection Optimization and Strict Aliasing +@cindex Aliasing +@cindex Strict Aliasing +@cindex No_Strict_Aliasing + +@noindent +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: + +@smallexample @c ada +@cartouche +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; + @dots{} + +begin + @dots{} + for J in Data'Range loop + if Data (J) = Int1V.all then + Int2V.all := Int2V.all + 1; + end if; + end loop; + @dots{} +end R; +@end cartouche +@end smallexample + +@noindent +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. + +This kind of optimization, called strict aliasing analysis, is +triggered by specifying an optimization level of @option{-O2} or +higher or @option{-Os} and allows @code{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 @code{Unchecked_Conversion} are used to break +the typing system. Consider the following complete program example: + +@smallexample @c ada +@cartouche +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 cartouche +@end smallexample + +@noindent +This program prints out 0 in @option{-O0} or @option{-O1} +mode, but it prints out 1 in @option{-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. + +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. + +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: + +@smallexample +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 smallexample + +@noindent +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}. + +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 @option{-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 @option{-fno-strict-aliasing}. Actually it is only the +unit containing the dereferencing of the suspicious pointer +that needs to be compiled. So in this case, if we compile +unit @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 @option{-O2} +and @option{-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 @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. + +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: + +@smallexample @c ada + pragma Warnings (Off); + function to_a2u is + new Unchecked_Conversion (a1, a2); + pragma Warnings (On); +@end smallexample + +@noindent +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 +@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. + +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: + +@smallexample @c ada + type a2 is access int2; + pragma No_Strict_Aliasing (a2); +@end smallexample + +@noindent +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. + +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 +@option{-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 @option{-O2} +and @option{-O2 -fno-strict-aliasing} to see how much effect this +has on size and speed of the code. If you really need to use +@option{-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. + +@ifset vms +@node Coverage Analysis +@subsection Coverage Analysis + +@noindent +GNAT supports the HP Performance Coverage Analyzer (PCA), which allows +the user to determine the distribution of execution time across a program, +@pxref{Profiling} for details of usage. +@end ifset + + +@node Text_IO Suggestions +@section @code{Text_IO} Suggestions +@cindex @code{Text_IO} and performance + +@noindent +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. + +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 @command{tail -f} command to watch redirected output. + +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}. + + + +@node Reducing Size of Ada Executables with gnatelim +@section Reducing Size of Ada Executables with @code{gnatelim} +@findex gnatelim + +@noindent +This section describes @command{gnatelim}, a tool which detects unused +subprograms and helps the compiler to create a smaller executable for your +program. + +@menu +* About gnatelim:: +* Running gnatelim:: +* Processing Precompiled Libraries:: +* Correcting the List of Eliminate Pragmas:: +* Making Your Executables Smaller:: +* Summary of the gnatelim Usage Cycle:: +@end menu + +@node About gnatelim +@subsection About @code{gnatelim} + +@noindent +When a program shares a set of Ada +packages with other programs, it may happen that this program uses +only a fraction of the subprograms defined in these packages. The code +created for these unused subprograms increases the size of the executable. + +@code{gnatelim} tracks unused subprograms in an Ada program and +outputs a list of GNAT-specific pragmas @code{Eliminate} marking all the +subprograms that are declared but never called. By placing the list of +@code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and +recompiling your program, you may decrease the size of its executable, +because the compiler will not generate the code for 'eliminated' subprograms. +@xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more +information about this pragma. + +@code{gnatelim} needs as its input data the name of the main subprogram. + +If a set of source files is specified as @code{gnatelim} arguments, it +treats these files as a complete set of sources making up a program to +analyse, and analyses only these sources. + +After a full successful build of the main subprogram @code{gnatelim} can be +called without specifying sources to analyse, in this case it computes +the source closure of the main unit from the @file{ALI} files. + +The following command will create the set of @file{ALI} files needed for +@code{gnatelim}: + +@smallexample +$ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^ +@end smallexample + +Note that @code{gnatelim} does not need object files. + +@node Running gnatelim +@subsection Running @code{gnatelim} + +@noindent +@code{gnatelim} has the following command-line interface: + +@smallexample +$ gnatelim [@var{switches}] ^-main^?MAIN^=@var{main_unit_name} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} +@end smallexample + +@noindent +@var{main_unit_name} should be a name of a source file that contains the main +subprogram of a program (partition). + +Each @var{filename} is the name (including the extension) of a source +file to process. ``Wildcards'' are allowed, and +the file name may contain path information. + +@samp{@var{gcc_switches}} is a list of switches for +@command{gcc}. They will be passed on to all compiler invocations made by +@command{gnatelim} to generate the ASIS trees. Here you can provide +@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, +use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. + +@code{gnatelim} has the following switches: + +@table @option +@c !sort! +@item ^-files^/FILES^=@var{filename} +@cindex @option{^-files^/FILES^} (@code{gnatelim}) +Take the argument source files from the specified file. This file should be an +ordinary text file containing file names separated by spaces or +line breaks. You can use this switch more than once in the same call to +@command{gnatelim}. You also can combine this switch with +an explicit list of files. + +@item ^-log^/LOG^ +@cindex @option{^-log^/LOG^} (@command{gnatelim}) +Duplicate all the output sent to @file{stderr} into a log file. The log file +is named @file{gnatelim.log} and is located in the current directory. + +@item ^-log^/LOGFILE^=@var{filename} +@cindex @option{^-log^/LOGFILE^} (@command{gnatelim}) +Duplicate all the output sent to @file{stderr} into a specified log file. + +@cindex @option{^--no-elim-dispatch^/NO_DISPATCH^} (@command{gnatelim}) +@item ^--no-elim-dispatch^/NO_DISPATCH^ +Do not generate pragmas for dispatching operations. + +@item ^--ignore^/IGNORE^=@var{filename} +@cindex @option{^--ignore^/IGNORE^} (@command{gnatelim}) +Do not generate pragmas for subprograms declared in the sources +listed in a specified file + +@cindex @option{^-o^/OUTPUT^} (@command{gnatelim}) +@item ^-o^/OUTPUT^=@var{report_file} +Put @command{gnatelim} output into a specified file. If this file already exists, +it is overridden. If this switch is not used, @command{gnatelim} outputs its results +into @file{stderr} + +@item ^-q^/QUIET^ +@cindex @option{^-q^/QUIET^} (@command{gnatelim}) +Quiet mode: by default @code{gnatelim} outputs to the standard error +stream the number of program units left to be processed. This option turns +this trace off. + +@cindex @option{^-t^/TIME^} (@command{gnatelim}) +@item ^-t^/TIME^ +Print out execution time. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@command{gnatelim}) +Verbose mode: @code{gnatelim} version information is printed as Ada +comments to the standard output stream. Also, in addition to the number of +program units left @code{gnatelim} will output the name of the current unit +being processed. + +@item ^-wq^/WARNINGS=QUIET^ +@cindex @option{^-wq^/WARNINGS=QUIET^} (@command{gnatelim}) +Quiet warning mode - some warnings are suppressed. In particular warnings that +indicate that the analysed set of sources is incomplete to make up a +partition and that some subprogram bodies are missing are not generated. +@end table + +@node Processing Precompiled Libraries +@subsection Processing Precompiled Libraries + +@noindent +If some program uses a precompiled Ada library, it can be processed by +@code{gnatelim} in a usual way. @code{gnatelim} will newer generate an +Eliminate pragma for a subprogram if the body of this subprogram has not +been analysed, this is a typical case for subprograms from precompiled +libraries. Switch @option{^-wq^/WARNINGS=QUIET^} may be used to suppress +warnings about missing source files and non-analyzed subprogram bodies +that can be generated when processing precompiled Ada libraries. + +@node Correcting the List of Eliminate Pragmas +@subsection Correcting the List of Eliminate Pragmas + +@noindent +In some rare cases @code{gnatelim} may try to eliminate +subprograms that are actually called in the program. In this case, the +compiler will generate an error message of the form: + +@smallexample +main.adb:4:08: cannot reference subprogram "P" eliminated at elim.out:5 +@end smallexample + +@noindent +You will need to manually remove the wrong @code{Eliminate} pragmas from +the configuration file indicated in the error message. You should recompile +your program from scratch after that, because you need a consistent +configuration file(s) during the entire compilation. + +@node Making Your Executables Smaller +@subsection Making Your Executables Smaller + +@noindent +In order to get a smaller executable for your program you now have to +recompile the program completely with the configuration file containing +pragmas Eliminate generated by gnatelim. If these pragmas are placed in +@file{gnat.adc} file located in your current directory, just do: + +@smallexample +$ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^ +@end smallexample + +@noindent +(Use the @option{^-f^/FORCE_COMPILE^} option for @command{gnatmake} to +recompile everything +with the set of pragmas @code{Eliminate} that you have obtained with +@command{gnatelim}). + +Be aware that the set of @code{Eliminate} pragmas is specific to each +program. It is not recommended to merge sets of @code{Eliminate} +pragmas created for different programs in one configuration file. + +@node Summary of the gnatelim Usage Cycle +@subsection Summary of the @code{gnatelim} Usage Cycle + +@noindent +Here is a quick summary of the steps to be taken in order to reduce +the size of your executables with @code{gnatelim}. You may use +other GNAT options to control the optimization level, +to produce the debugging information, to set search path, etc. + +@enumerate +@item +Create a complete set of @file{ALI} files (if the program has not been +built already) + +@smallexample +$ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^ +@end smallexample + +@item +Generate a list of @code{Eliminate} pragmas in default configuration file +@file{gnat.adc} in the current directory +@smallexample +@ifset vms +$ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC +@end ifset +@ifclear vms +$ gnatelim main_prog >@r{[}>@r{]} gnat.adc +@end ifclear +@end smallexample + +@item +Recompile the application + +@smallexample +$ gnatmake ^-f main_prog^/FORCE_COMPILE MAIN_PROG^ +@end smallexample + +@end enumerate + +@node Reducing Size of Executables with unused subprogram/data elimination +@section Reducing Size of Executables with Unused Subprogram/Data Elimination +@findex unused subprogram/data elimination + +@noindent +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 +@subsection About unused subprogram/data elimination + +@noindent +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 +@subsection Compilation options + +@noindent +The operation of eliminating the unused code and data from the final executable +is directly performed by the linker. + +In order to do this, it has to work with objects compiled with the +following options: +@option{-ffunction-sections} @option{-fdata-sections}. +@cindex @option{-ffunction-sections} (@command{gcc}) +@cindex @option{-fdata-sections} (@command{gcc}) +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 @option{-Wl,--gc-sections} option to gcc command or in the +@option{-largs} section of @command{gnatmake}. This will perform a +garbage collection of code and data never referenced. + +If the linker performs a partial link (@option{-r} ld linker option), then you +will need to provide one or several entry point using the +@option{-e} / @option{--entry} ld option. + +Note that objects compiled without the @option{-ffunction-sections} and +@option{-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 +@subsection Example of unused subprogram/data elimination + +@noindent +Here is a simple example: + +@smallexample @c ada +with Aux; + +procedure Test is +begin + Aux.Used (10); +end Test; + +package Aux is + Used_Data : Integer; + Unused_Data : Integer; + + procedure Used (Data : Integer); + procedure Unused (Data : Integer); +end Aux; + +package body Aux is + procedure Used (Data : Integer) is + begin + Used_Data := Data; + end Used; + + procedure Unused (Data : Integer) is + begin + Unused_Data := Data; + end Unused; +end Aux; +@end smallexample + +@noindent +@code{Unused} and @code{Unused_Data} are never referenced in this code +excerpt, and hence they may be safely removed from the final executable. + +@smallexample +$ 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 smallexample + +@noindent +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. + +@c ******************************** +@node Renaming Files Using gnatchop +@chapter Renaming Files Using @code{gnatchop} +@findex gnatchop + +@noindent +This chapter 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 +* Handling Files with Multiple Units:: +* Operating gnatchop in Compilation Mode:: +* Command Line for gnatchop:: +* Switches for gnatchop:: +* Examples of gnatchop Usage:: +@end menu + +@node Handling Files with Multiple Units +@section Handling Files with Multiple Units + +@noindent +The basic compilation model of GNAT requires that a file submitted to the +compiler have only one unit and there be a strict correspondence +between the file name and the unit name. + +The @code{gnatchop} utility allows both of these rules to be relaxed, +allowing GNAT to process files which contain multiple compilation units +and files with arbitrary file names. @code{gnatchop} +reads the specified file and generates one or more output files, +containing one unit per file. The unit and the file name correspond, +as required by GNAT. + +If you want to 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 @command{gnatchop} once, generate the +new set of files and work with them from that point on. + +Alternatively, if you want to keep your files in the ``foreign'' format, +perhaps to maintain compatibility with some other Ada compilation +system, you can set up a procedure where you use @command{gnatchop} each +time you compile, regarding the source files that it writes as temporary +files that you throw away. + +Note that if your file containing multiple units starts with a byte order +mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop +will each start with a copy of this BOM, meaning that they can be compiled +automatically in UTF-8 mode without needing to specify an explicit encoding. + +@node Operating gnatchop in Compilation Mode +@section Operating gnatchop in Compilation Mode + +@noindent +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 +that configuration pragmas always belong to the following unit. Any comments +belong to the following unit. These rules +almost always result in the right choice of +the split point without needing to mark it explicitly and most users will +find this default to be what they want. In this default mode it is incorrect to +submit a file containing only configuration pragmas, or one that ends in +configuration pragmas, to @code{gnatchop}. + +However, using a special option to activate ``compilation mode'', +@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 @code{gnatchop} is given a file that consists of +only configuration pragmas, then this file is appended to the +@file{gnat.adc} file in the current directory. This behavior provides +the required behavior described in the RM for the actions to be taken +on submitting such a file to the compiler, namely that these pragmas +should apply to all subsequent compilations in the same compilation +environment. Using GNAT, the current directory, possibly containing a +@file{gnat.adc} file is the representation +of a compilation environment. For more information on the +@file{gnat.adc} file, see @ref{Handling of Configuration Pragmas}. + +Second, in compilation mode, if @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 +behavior provides the required behavior described in the RM for the +actions to be taken on compiling such a file, namely that the pragmas +apply to all units in the compilation, but not to subsequently compiled +units. + +Finally, if configuration pragmas appear between units, they are appended +to the previous unit. This results in the previous unit being illegal, +since the compiler does not accept configuration pragmas that follow +a unit. This provides the required RM behavior that forbids configuration +pragmas other than those preceding the first compilation unit of a +compilation. + +For most purposes, @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 @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 +@section Command Line for @code{gnatchop} + +@noindent +The @code{gnatchop} command has the form: + +@smallexample +@c $ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]} +@c @ovar{directory} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]} + @r{[}@var{directory}@r{]} +@end smallexample + +@noindent +The only required argument is the file name of the file to be chopped. +There are no restrictions on the form of this file name. The file itself +contains one or more Ada units, in normal GNAT format, concatenated +together. As shown, more than one file may be presented to be chopped. + +When run in default mode, @code{gnatchop} generates one output file in +the current directory for each unit in each of the files. + +@var{directory}, if specified, gives the name of the directory to which +the output files will be written. If it is not specified, all files are +written to the current directory. + +For example, given a +file called @file{hellofiles} containing + +@smallexample @c ada +@group +@cartouche +procedure hello; + +with Text_IO; use Text_IO; +procedure hello is +begin + Put_Line ("Hello"); +end hello; +@end cartouche +@end group +@end smallexample + +@noindent +the command + +@smallexample +$ gnatchop ^hellofiles^HELLOFILES.^ +@end smallexample + +@noindent +generates two files in the current directory, one called +@file{hello.ads} containing the single line that is the procedure spec, +and the other called @file{hello.adb} containing the remaining text. The +original file is not affected. The generated files can be compiled in +the normal manner. + +@noindent +When gnatchop is invoked on a file that is empty or that contains only empty +lines and/or comments, gnatchop will not fail, but will not produce any +new sources. + +For example, given a +file called @file{toto.txt} containing + +@smallexample @c ada +@group +@cartouche +-- Just a comment +@end cartouche +@end group +@end smallexample + +@noindent +the command + +@smallexample +$ gnatchop ^toto.txt^TOT.TXT^ +@end smallexample + +@noindent +will not produce any new file and will result in the following warnings: + +@smallexample +toto.txt:1:01: warning: empty file, contains no compilation units +no compilation units found +no source files written +@end smallexample + +@node Switches for gnatchop +@section Switches for @code{gnatchop} + +@noindent +@command{gnatchop} recognizes the following switches: + +@table @option +@c !sort! + +@item --version +@cindex @option{--version} @command{gnatchop} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatchop} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item ^-c^/COMPILATION^ +@cindex @option{^-c^/COMPILATION^} (@code{gnatchop}) +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. + +@ifclear vms +@item -gnat@var{xxx} +This passes the given @option{-gnat@var{xxx}} switch to @code{gnat} which is +used to parse the given file. Not all @var{xxx} options make sense, +but for example, the use of @option{-gnati2} allows @code{gnatchop} to +process a source file that uses Latin-2 coding for identifiers. +@end ifclear + +@item ^-h^/HELP^ +Causes @code{gnatchop} to generate a brief help summary to the standard +output file showing usage information. + +@item ^-k@var{mm}^/FILE_NAME_MAX_LENGTH=@var{mm}^ +@cindex @option{^-k^/FILE_NAME_MAX_LENGTH^} (@code{gnatchop}) +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. +@ifset vms +If no value is given, or +if no @code{/FILE_NAME_MAX_LENGTH} qualifier is given, +a default of 39, suitable for OpenVMS Alpha +Systems, is assumed +@end ifset +@ifclear vms +No space is allowed between the @option{-k} and the numeric value. The numeric +value may be omitted in which case a default of @option{-k8}, +suitable for use +with DOS-like file systems, is used. If no @option{-k} switch +is present then +there is no limit on the length of file names. +@end ifclear + +@item ^-p^/PRESERVE^ +@cindex @option{^-p^/PRESERVE^} (@code{gnatchop}) +Causes the file ^modification^creation^ 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 +@code{gnatchop} is used as part of a standard build process. + +@item ^-q^/QUIET^ +@cindex @option{^-q^/QUIET^} (@code{gnatchop}) +Causes output of informational messages indicating the set of generated +files to be suppressed. Warnings and error messages are unaffected. + +@item ^-r^/REFERENCE^ +@cindex @option{^-r^/REFERENCE^} (@code{gnatchop}) +@findex Source_Reference +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 +@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 @option{^-g^/DEBUG^} switch of @command{gcc} or @command{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 @code{Source_Reference} +pragma referencing a third file, then gnatchop respects +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 @code{gnatchop} +is used in conjunction with @code{gnatprep} to compile files that +contain preprocessing statements and multiple units. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@code{gnatchop}) +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. + +@item ^-w^/OVERWRITE^ +@cindex @option{^-w^/OVERWRITE^} (@code{gnatchop}) +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 +check, and causes all but the last instance of such duplicated +units to be skipped. + +@ifclear vms +@item --GCC=@var{xxxx} +@cindex @option{--GCC=} (@code{gnatchop}) +Specify the path of the GNAT parser to be used. When this switch is used, +no attempt is made to add the prefix to the GNAT parser executable. +@end ifclear +@end table + +@node Examples of gnatchop Usage +@section Examples of @code{gnatchop} Usage + +@table @code +@ifset vms +@item gnatchop /OVERWRITE HELLO_S.ADA [PRERELEASE.FILES] +@end ifset +@ifclear vms +@item gnatchop -w hello_s.ada prerelease/files +@end ifclear + +Chops the source file @file{hello_s.ada}. The output files will be +placed in the directory @file{^prerelease/files^[PRERELEASE.FILES]^}, +overwriting any +files with matching names in that directory (no files in the current +directory are modified). + +@item gnatchop ^archive^ARCHIVE.^ +Chops the source file @file{^archive^ARCHIVE.^} +into the current directory. One +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 @code{cat}^VMS @code{APPEND/NEW}^ +command), and then +@command{gnatchop} is used at the other end to reconstitute the original +file names. + +@item gnatchop file1 file2 file3 direc +Chops all units in files @file{file1}, @file{file2}, @file{file3}, placing +the resulting files in the directory @file{direc}. Note that if any units +occur more than once anywhere within this set of files, an error message +is generated, and no files are written. To override this check, use the +@option{^-w^/OVERWRITE^} 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. +@end table + +@node Configuration Pragmas +@chapter Configuration Pragmas +@cindex Configuration pragmas +@cindex Pragmas, configuration + +@noindent +Configuration pragmas include those pragmas described as +such in the Ada Reference Manual, as well as +implementation-dependent pragmas that are configuration pragmas. +@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}, +for details on these additional GNAT-specific configuration pragmas. +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: + +@smallexample + Ada_83 + Ada_95 + Ada_05 + Ada_2005 + Ada_12 + Ada_2012 + Assertion_Policy + Assume_No_Invalid_Values + C_Pass_By_Copy + Check_Name + Check_Policy + Compile_Time_Error + Compile_Time_Warning + Compiler_Unit + Component_Alignment + Convention_Identifier + Debug_Policy + Detect_Blocking + Default_Storage_Pool + Discard_Names + Elaboration_Checks + Eliminate + Extend_System + Extensions_Allowed + External_Name_Casing + Fast_Math + Favor_Top_Level + Float_Representation + Implicit_Packing + Initialize_Scalars + Interrupt_State + License + Locking_Policy + Long_Float + No_Run_Time + No_Strict_Aliasing + Normalize_Scalars + Optimize_Alignment + Persistent_BSS + Polling + Priority_Specific_Dispatching + Profile + Profile_Warnings + Propagate_Exceptions + Queuing_Policy + Ravenscar + Restricted_Run_Time + Restrictions + Restrictions_Warnings + Reviewable + Short_Circuit_And_Or + Source_File_Name + Source_File_Name_Project + Style_Checks + Suppress + Suppress_Exception_Locations + Task_Dispatching_Policy + Universal_Data + Unsuppress + Use_VADS_Size + Validity_Checks + Warnings + Wide_Character_Encoding + +@end smallexample + +@menu +* Handling of Configuration Pragmas:: +* The Configuration Pragmas Files:: +@end menu + +@node Handling of Configuration Pragmas +@section Handling of Configuration Pragmas + +Configuration pragmas may either appear at the start of a compilation +unit, in which case they apply only to that unit, or they may apply to +all compilations performed in a given compilation environment. + +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{Operating gnatchop in Compilation Mode} for details. +However, for most purposes, it will be more convenient to edit the +@file{gnat.adc} file that contains configuration pragmas directly, +as described in the following section. + +@node The Configuration Pragmas Files +@section The Configuration Pragmas Files +@cindex @file{gnat.adc} + +@noindent +In GNAT a compilation environment is defined by the current +directory at the time that a compile command is given. This current +directory is searched for a file whose name is @file{gnat.adc}. If +this file is present, it is expected to contain one or more +configuration pragmas that will be applied to the current compilation. +However, if the switch @option{-gnatA} is used, @file{gnat.adc} is not +considered. + +Configuration pragmas may be entered into the @file{gnat.adc} file +either by running @code{gnatchop} on a source file that consists only of +configuration pragmas, or more conveniently by +direct editing of the @file{gnat.adc} file, which is a standard format +source file. + +In addition to @file{gnat.adc}, additional files containing configuration +pragmas may be applied to the current compilation using the switch +@option{-gnatec}@var{path}. @var{path} must designate an existing file that +contains only configuration pragmas. These configuration pragmas are +in addition to those found in @file{gnat.adc} (provided @file{gnat.adc} +is present and switch @option{-gnatA} is not used). + +It is allowed to specify several switches @option{-gnatec}, all of which +will be taken into account. + +If you are using project file, a separate mechanism is provided using +project attributes, see @ref{Specifying Configuration Pragmas} for more +details. + +@ifset vms +Of special interest to GNAT OpenVMS Alpha is the following +configuration pragma: + +@smallexample @c ada +@cartouche +pragma Extend_System (Aux_DEC); +@end cartouche +@end smallexample + +@noindent +In the presence of this pragma, GNAT adds to the definition of the +predefined package SYSTEM all the additional types and subprograms that are +defined in HP Ada. See @ref{Compatibility with HP Ada} for details. +@end ifset + +@node Handling Arbitrary File Naming Conventions Using gnatname +@chapter Handling Arbitrary File Naming Conventions Using @code{gnatname} +@cindex Arbitrary File Naming Conventions + +@menu +* Arbitrary File Naming Conventions:: +* Running gnatname:: +* Switches for gnatname:: +* Examples of gnatname Usage:: +@end menu + +@node Arbitrary File Naming Conventions +@section Arbitrary File Naming Conventions + +@noindent +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 +(@code{.ads} for specs, @code{.adb} for bodies), the GNAT compiler +does not need additional information. + +@noindent +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 (@pxref{Configuration Pragmas}) +or a project file. +When the non-standard file naming conventions are well-defined, +a small number of pragmas @code{Source_File_Name} specifying a naming pattern +(@pxref{Alternative File Naming Schemes}) may be sufficient. However, +if the file naming conventions are irregular or arbitrary, a number +of pragma @code{Source_File_Name} for individual compilation units +must be defined. +To help maintain the correspondence between compilation unit names and +source file names within the compiler, +GNAT provides a tool @code{gnatname} to generate the required pragmas for a +set of files. + +@node Running gnatname +@section Running @code{gnatname} + +@noindent +The usual form of the @code{gnatname} command is + +@smallexample +@c $ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns} +@c @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatname @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]} + @r{[}--and @r{[}@var{switches}@r{]} @var{naming_pattern} @r{[}@var{naming_patterns}@r{]}@r{]} +@end smallexample + +@noindent +All of the arguments are optional. If invoked without any argument, +@code{gnatname} will display its usage. + +@noindent +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, +@code{gnatname} will use the GNAT compiler in syntax-check-only mode on all +regular files. + +@noindent +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. + +@noindent +@code{gnatname} may be called with several sections of directories/patterns. +Sections are separated by 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 @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. + +@noindent +Examples of Naming Patterns are + +@smallexample + "*.[12].ada" + "*.ad[sb]*" + "body_*" "spec_*" +@end smallexample + +@noindent +For a more complete description of the syntax of Naming Patterns, +see the second kind of regular expressions described in @file{g-regexp.ads} +(the ``Glob'' regular expressions). + +@noindent +When invoked with no switch @code{-P}, @code{gnatname} will create a +configuration pragmas file @file{gnat.adc} in the current working directory, +with pragmas @code{Source_File_Name} for each file that contains a valid Ada +unit. + +@node Switches for gnatname +@section Switches for @code{gnatname} + +@noindent +Switches for @code{gnatname} must precede any specified Naming Pattern. + +@noindent +You may specify any of the following switches to @code{gnatname}: + +@table @option +@c !sort! + +@item --version +@cindex @option{--version} @command{gnatname} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatname} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item --and +Start another section of directories/patterns. + +@item ^-c^/CONFIG_FILE=^@file{file} +@cindex @option{^-c^/CONFIG_FILE^} (@code{gnatname}) +Create a configuration pragmas file @file{file} (instead of the default +@file{gnat.adc}). +@ifclear vms +There may be zero, one or more space between @option{-c} and +@file{file}. +@end ifclear +@file{file} may include directory information. @file{file} must be +writable. There may be only one switch @option{^-c^/CONFIG_FILE^}. +When a switch @option{^-c^/CONFIG_FILE^} is +specified, no switch @option{^-P^/PROJECT_FILE^} may be specified (see below). + +@item ^-d^/SOURCE_DIRS=^@file{dir} +@cindex @option{^-d^/SOURCE_DIRS^} (@code{gnatname}) +Look for source files in directory @file{dir}. There may be zero, one or more +spaces between @option{^-d^/SOURCE_DIRS=^} and @file{dir}. +When a switch @option{^-d^/SOURCE_DIRS^} +is specified, the current working directory will not be searched for source +files, unless it is explicitly specified with a @option{^-d^/SOURCE_DIRS^} +or @option{^-D^/DIR_FILES^} switch. +Several switches @option{^-d^/SOURCE_DIRS^} may be specified. +If @file{dir} is a relative path, it is relative to the directory of +the configuration pragmas file specified with switch +@option{^-c^/CONFIG_FILE^}, +or to the directory of the project file specified with switch +@option{^-P^/PROJECT_FILE^} or, +if neither switch @option{^-c^/CONFIG_FILE^} +nor switch @option{^-P^/PROJECT_FILE^} are specified, it is relative to the +current working directory. The directory +specified with switch @option{^-d^/SOURCE_DIRS^} must exist and be readable. + +@item ^-D^/DIRS_FILE=^@file{file} +@cindex @option{^-D^/DIRS_FILE^} (@code{gnatname}) +Look for source files in all directories listed in text file @file{file}. +There may be zero, one or more spaces between @option{^-D^/DIRS_FILE=^} +and @file{file}. +@file{file} must be an existing, readable text file. +Each nonempty line in @file{file} must be a directory. +Specifying switch @option{^-D^/DIRS_FILE^} is equivalent to specifying as many +switches @option{^-d^/SOURCE_DIRS^} as there are nonempty lines in +@file{file}. + +@item ^-f^/FOREIGN_PATTERN=^@file{pattern} +@cindex @option{^-f^/FOREIGN_PATTERN^} (@code{gnatname}) +Foreign patterns. Using this switch, it is possible to add sources of languages +other than Ada to the list of sources of a project file. +It is only useful if a ^-P^/PROJECT_FILE^ switch is used. +For example, +@smallexample +gnatname ^-Pprj -f"*.c"^/PROJECT_FILE=PRJ /FOREIGN_PATTERN=*.C^ "*.ada" +@end smallexample +@noindent +will look for Ada units in all files with the @file{.ada} extension, +and will add to the list of file for project @file{prj.gpr} the C files +with extension @file{.^c^C^}. + +@item ^-h^/HELP^ +@cindex @option{^-h^/HELP^} (@code{gnatname}) +Output usage (help) information. The output is written to @file{stdout}. + +@item ^-P^/PROJECT_FILE=^@file{proj} +@cindex @option{^-P^/PROJECT_FILE^} (@code{gnatname}) +Create or update project file @file{proj}. There may be zero, one or more space +between @option{-P} and @file{proj}. @file{proj} may include directory +information. @file{proj} must be writable. +There may be only one switch @option{^-P^/PROJECT_FILE^}. +When a switch @option{^-P^/PROJECT_FILE^} is specified, +no switch @option{^-c^/CONFIG_FILE^} may be specified. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@code{gnatname}) +Verbose mode. Output detailed explanation of behavior to @file{stdout}. +This includes name of the file written, the name of the directories to search +and, for each file in those directories whose name matches at least one of +the Naming Patterns, an indication of whether the file contains a unit, +and if so the name of the unit. + +@item ^-v -v^/VERBOSE /VERBOSE^ +@cindex @option{^-v -v^/VERBOSE /VERBOSE^} (@code{gnatname}) +Very Verbose mode. In addition to the output produced in verbose mode, +for each file in the searched directories whose name matches none of +the Naming Patterns, an indication is given that there is no match. + +@item ^-x^/EXCLUDED_PATTERN=^@file{pattern} +@cindex @option{^-x^/EXCLUDED_PATTERN^} (@code{gnatname}) +Excluded patterns. Using this switch, it is possible to exclude some files +that would match the name patterns. For example, +@smallexample +gnatname ^-x "*_nt.ada"^/EXCLUDED_PATTERN=*_nt.ada^ "*.ada" +@end smallexample +@noindent +will look for Ada units in all files with the @file{.ada} extension, +except those whose names end with @file{_nt.ada}. + +@end table + +@node Examples of gnatname Usage +@section Examples of @code{gnatname} Usage + +@ifset vms +@smallexample +$ gnatname /CONFIG_FILE=[HOME.ME]NAMES.ADC /SOURCE_DIRS=SOURCES "[a-z]*.ada*" +@end smallexample +@end ifset + +@ifclear vms +@smallexample +$ gnatname -c /home/me/names.adc -d sources "[a-z]*.ada*" +@end smallexample +@end ifclear + +@noindent +In this example, the directory @file{^/home/me^[HOME.ME]^} must already exist +and be writable. In addition, the directory +@file{^/home/me/sources^[HOME.ME.SOURCES]^} (specified by +@option{^-d sources^/SOURCE_DIRS=SOURCES^}) must exist and be readable. + +@ifclear vms +Note the optional spaces after @option{-c} and @option{-d}. +@end ifclear + +@smallexample +@ifclear vms +$ gnatname -P/home/me/proj -x "*_nt_body.ada" + -dsources -dsources/plus -Dcommon_dirs.txt "body_*" "spec_*" +@end ifclear +@ifset vms +$ gnatname /PROJECT_FILE=[HOME.ME]PROJ + /EXCLUDED_PATTERN=*_nt_body.ada + /SOURCE_DIRS=(SOURCES,[SOURCES.PLUS]) + /DIRS_FILE=COMMON_DIRS.TXT "body_*" "spec_*" +@end ifset +@end smallexample + +Note that several switches @option{^-d^/SOURCE_DIRS^} may be used, +even in conjunction with one or several switches +@option{^-D^/DIRS_FILE^}. Several Naming Patterns and one excluded pattern +are used in this example. + +@c ***************************************** +@c * G N A T P r o j e c t M a n a g e r * +@c ***************************************** + +@c ------ macros for projects.texi +@c These macros are needed when building the gprbuild documentation, but +@c should have no effect in the gnat user's guide + +@macro CODESAMPLE{TXT} +@smallexample +@group +\TXT\ +@end group +@end smallexample +@end macro + +@macro PROJECTFILE{TXT} +@CODESAMPLE{\TXT\} +@end macro + +@c simulates a newline when in a @CODESAMPLE +@macro NL{} +@end macro + +@macro TIP{TXT} +@quotation +@noindent +\TXT\ +@end quotation +@end macro + +@macro TIPHTML{TXT} +\TXT\ +@end macro + +@macro IMPORTANT{TXT} +@quotation +@noindent +\TXT\ +@end quotation + +@end macro + +@macro NOTE{TXT} +@quotation +@noindent +\TXT\ +@end quotation +@end macro + +@include projects.texi + +@c ***************************************** +@c * Cross-referencing tools +@c ***************************************** + +@node The Cross-Referencing Tools gnatxref and gnatfind +@chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind} +@findex gnatxref +@findex gnatfind + +@noindent +The compiler generates cross-referencing information (unless +you set the @samp{-gnatx} switch), which are saved in the @file{.ali} files. +This information indicates where in the source each entity is declared and +referenced. Note that entities in package Standard are not included, but +entities in all other predefined units are included in the output. + +Before using any of these two tools, you need to compile successfully your +application, so that GNAT gets a chance to generate the cross-referencing +information. + +The two tools @code{gnatxref} and @code{gnatfind} take advantage of this +information to provide the user with the capability to easily locate the +declaration and references to an entity. These tools are quite similar, +the difference being that @code{gnatfind} is intended for locating +definitions and/or references to a specified entity or entities, whereas +@code{gnatxref} is oriented to generating a full report of all +cross-references. + +To use these tools, you must not compile your application using the +@option{-gnatx} switch on the @command{gnatmake} command line +(@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing +information will not be generated. + +Note: to invoke @code{gnatxref} or @code{gnatfind} with a project file, +use the @code{gnat} driver (see @ref{The GNAT Driver and Project Files}). + +@menu +* Switches for gnatxref:: +* Switches for gnatfind:: +* Project Files for gnatxref and gnatfind:: +* Regular Expressions in gnatfind and gnatxref:: +* Examples of gnatxref Usage:: +* Examples of gnatfind Usage:: +@end menu + +@node Switches for gnatxref +@section @code{gnatxref} Switches + +@noindent +The command invocation for @code{gnatxref} is: +@smallexample +@c $ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatxref @r{[}@var{switches}@r{]} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]} +@end smallexample + +@noindent +where + +@table @var +@item sourcefile1 +@itemx sourcefile2 +identifies the source files for which a report is to be generated. The +``with''ed units will be processed too. You must provide at least one file. + +These file names are considered to be regular expressions, so for instance +specifying @file{source*.adb} is the same as giving every file in the current +directory whose name starts with @file{source} and whose extension is +@file{adb}. + +You shouldn't specify any directory name, just base names. @command{gnatxref} +and @command{gnatfind} will be able to locate these files by themselves using +the source path. If you specify directories, no result is produced. + +@end table + +@noindent +The switches can be: +@table @option +@c !sort! +@item --version +@cindex @option{--version} @command{gnatxref} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatxref} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item ^-a^/ALL_FILES^ +@cindex @option{^-a^/ALL_FILES^} (@command{gnatxref}) +If this switch is present, @code{gnatfind} and @code{gnatxref} will parse +the read-only files found in the library search path. Otherwise, these files +will be ignored. This option can be used to protect Gnat sources or your own +libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} +much faster, and their output much smaller. Read-only here refers to access +or permissions status in the file system for the current user. + +@item -aIDIR +@cindex @option{-aIDIR} (@command{gnatxref}) +When looking for source files also look in directory DIR. The order in which +source file search is undertaken is the same as for @command{gnatmake}. + +@item -aODIR +@cindex @option{-aODIR} (@command{gnatxref}) +When searching for library and object files, look in directory +DIR. The order in which library files are searched is the same as for +@command{gnatmake}. + +@item -nostdinc +@cindex @option{-nostdinc} (@command{gnatxref}) +Do not look for sources in the system default directory. + +@item -nostdlib +@cindex @option{-nostdlib} (@command{gnatxref}) +Do not look for library files in the system default directory. + +@item --ext=@var{extension} +@cindex @option{--ext} (@command{gnatxref}) +Specify an alternate ali file extension. The default is @code{ali} and other +extensions (e.g. @code{sli} for SPARK library files) may be specified via this +switch. Note that if this switch overrides the default, which means that only +the new extension will be considered. + +@item --RTS=@var{rts-path} +@cindex @option{--RTS} (@command{gnatxref}) +Specifies the default location of the runtime library. Same meaning as the +equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). + +@item ^-d^/DERIVED_TYPES^ +@cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref}) +If this switch is set @code{gnatxref} will output the parent type +reference for each matching derived types. + +@item ^-f^/FULL_PATHNAME^ +@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatxref}) +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. + +@item ^-g^/IGNORE_LOCALS^ +@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatxref}) +If this switch is set, information is output only for library-level +entities, ignoring local entities. The use of this switch may accelerate +@code{gnatfind} and @code{gnatxref}. + +@item -IDIR +@cindex @option{-IDIR} (@command{gnatxref}) +Equivalent to @samp{-aODIR -aIDIR}. + +@item -pFILE +@cindex @option{-pFILE} (@command{gnatxref}) +Specify a project file to use @xref{GNAT Project Manager}. +If you need to use the @file{.gpr} +project files, you should use gnatxref through the GNAT driver +(@command{gnat xref -Pproject}). + +By default, @code{gnatxref} and @code{gnatfind} will try to locate a +project file in the current directory. + +If a project file is either specified or found by the tools, then the content +of the source directory and object directory lines are added as if they +had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} +and @samp{^-aO^OBJECT_SEARCH^}. +@item ^-u^/UNUSED^ +Output only unused symbols. This may be really useful if you give your +main compilation unit on the command line, as @code{gnatxref} will then +display every unused entity and 'with'ed package. + +@ifclear vms +@item -v +Instead of producing the default output, @code{gnatxref} will generate a +@file{tags} file that can be used by vi. For examples how to use this +feature, see @ref{Examples of gnatxref Usage}. The tags file is output +to the standard output, thus you will have to redirect it to a file. +@end ifclear + +@end table + +@noindent +All these switches may be in any order on the command line, and may even +appear after the file names. They need not be separated by spaces, thus +you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of +@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. + +@node Switches for gnatfind +@section @code{gnatfind} Switches + +@noindent +The command line for @code{gnatfind} is: + +@smallexample +@c $ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} +@c @r{[}@var{file1} @var{file2} @dots{}] +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatfind @r{[}@var{switches}@r{]} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} + @r{[}@var{file1} @var{file2} @dots{}@r{]} +@end smallexample + +@noindent +where + +@table @var +@item pattern +An entity will be output only if it matches the regular expression found +in @var{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}. + +Omitting the pattern is equivalent to specifying @samp{*}, which +will match any entity. Note that if you do not provide a pattern, you +have to provide both a sourcefile and a line. + +Entity names are given in Latin-1, with uppercase/lowercase equivalence +for matching purposes. At the current time there is no support for +8-bit codes other than Latin-1, or for wide characters in identifiers. + +@item sourcefile +@code{gnatfind} will look for references, bodies or declarations +of symbols referenced in @file{@var{sourcefile}}, at line @var{line} +and column @var{column}. See @ref{Examples of gnatfind Usage} +for syntax examples. + +@item line +is a decimal integer identifying the line number containing +the reference to the entity (or entities) to be located. + +@item column +is 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 file1 file2 @dots{} +The search will be restricted to these source files. If none are given, then +the search will be done for every library file in the search path. +These file must appear only after the pattern or sourcefile. + +These file names are considered to be regular expressions, so for instance +specifying @file{source*.adb} is the same as giving every file in the current +directory whose name starts with @file{source} and whose extension is +@file{adb}. + +The location of the spec of the entity will always be displayed, even if it +isn't in one of @file{@var{file1}}, @file{@var{file2}},@enddots{} The +occurrences of the entity in the separate units of the ones given on the +command line will also be displayed. + +Note that if you specify at least one file in this part, @code{gnatfind} may +sometimes not be able to find the body of the subprograms. + +@end table + +@noindent +At least one of 'sourcefile' or 'pattern' has to be present on +the command line. + +The following switches are available: +@table @option +@c !sort! + +@cindex @option{--version} @command{gnatfind} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatfind} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item ^-a^/ALL_FILES^ +@cindex @option{^-a^/ALL_FILES^} (@command{gnatfind}) +If this switch is present, @code{gnatfind} and @code{gnatxref} will parse +the read-only files found in the library search path. Otherwise, these files +will be ignored. This option can be used to protect Gnat sources or your own +libraries from being parsed, thus making @code{gnatfind} and @code{gnatxref} +much faster, and their output much smaller. Read-only here refers to access +or permission status in the file system for the current user. + +@item -aIDIR +@cindex @option{-aIDIR} (@command{gnatfind}) +When looking for source files also look in directory DIR. The order in which +source file search is undertaken is the same as for @command{gnatmake}. + +@item -aODIR +@cindex @option{-aODIR} (@command{gnatfind}) +When searching for library and object files, look in directory +DIR. The order in which library files are searched is the same as for +@command{gnatmake}. + +@item -nostdinc +@cindex @option{-nostdinc} (@command{gnatfind}) +Do not look for sources in the system default directory. + +@item -nostdlib +@cindex @option{-nostdlib} (@command{gnatfind}) +Do not look for library files in the system default directory. + +@item --ext=@var{extension} +@cindex @option{--ext} (@command{gnatfind}) +Specify an alternate ali file extension. The default is @code{ali} and other +extensions (e.g. @code{sli} for SPARK library files) may be specified via this +switch. Note that if this switch overrides the default, which means that only +the new extension will be considered. + +@item --RTS=@var{rts-path} +@cindex @option{--RTS} (@command{gnatfind}) +Specifies the default location of the runtime library. Same meaning as the +equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). + +@item ^-d^/DERIVED_TYPE_INFORMATION^ +@cindex @option{^-d^/DERIVED_TYPE_INFORMATION^} (@code{gnatfind}) +If this switch is set, then @code{gnatfind} will output the parent type +reference for each matching derived types. + +@item ^-e^/EXPRESSIONS^ +@cindex @option{^-e^/EXPRESSIONS^} (@command{gnatfind}) +By default, @code{gnatfind} accept the simple regular expression set for +@samp{pattern}. If this switch is set, then the pattern will be +considered as full Unix-style regular expression. + +@item ^-f^/FULL_PATHNAME^ +@cindex @option{^-f^/FULL_PATHNAME^} (@command{gnatfind}) +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. + +@item ^-g^/IGNORE_LOCALS^ +@cindex @option{^-g^/IGNORE_LOCALS^} (@command{gnatfind}) +If this switch is set, information is output only for library-level +entities, ignoring local entities. The use of this switch may accelerate +@code{gnatfind} and @code{gnatxref}. + +@item -IDIR +@cindex @option{-IDIR} (@command{gnatfind}) +Equivalent to @samp{-aODIR -aIDIR}. + +@item -pFILE +@cindex @option{-pFILE} (@command{gnatfind}) +Specify a project file (@pxref{GNAT Project Manager}) to use. +By default, @code{gnatxref} and @code{gnatfind} will try to locate a +project file in the current directory. + +If a project file is either specified or found by the tools, then the content +of the source directory and object directory lines are added as if they +had been specified respectively by @samp{^-aI^/SOURCE_SEARCH^} and +@samp{^-aO^/OBJECT_SEARCH^}. + +@item ^-r^/REFERENCES^ +@cindex @option{^-r^/REFERENCES^} (@command{gnatfind}) +By default, @code{gnatfind} will output only the information about the +declaration, body or type completion of the entities. If this switch is +set, the @code{gnatfind} will locate every reference to the entities in +the files specified on the command line (or in every file in the search +path if no file is given on the command line). + +@item ^-s^/PRINT_LINES^ +@cindex @option{^-s^/PRINT_LINES^} (@command{gnatfind}) +If this switch is set, then @code{gnatfind} will output the content +of the Ada source file lines were the entity was found. + +@item ^-t^/TYPE_HIERARCHY^ +@cindex @option{^-t^/TYPE_HIERARCHY^} (@command{gnatfind}) +If this switch is set, then @code{gnatfind} will output the type hierarchy for +the specified type. It act like -d option but recursively from parent +type to parent type. When this switch is set it is not possible to +specify more than one file. + +@end table + +@noindent +All these switches may be in any order on the command line, and may even +appear after the file names. They need not be separated by spaces, thus +you can say @samp{gnatxref ^-ag^/ALL_FILES/IGNORE_LOCALS^} instead of +@samp{gnatxref ^-a -g^/ALL_FILES /IGNORE_LOCALS^}. + +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 @code{*} at the end of the command line. + +@node Project Files for gnatxref and gnatfind +@section Project Files for @command{gnatxref} and @command{gnatfind} + +@noindent +Project files allow a programmer to specify how to compile its +application, where to find sources, etc. These files are used +@ifclear vms +primarily by GPS, but they can also be used +@end ifclear +by the two tools +@code{gnatxref} and @code{gnatfind}. + +A project file name must end with @file{.gpr}. If a single one is +present in the current directory, then @code{gnatxref} and @code{gnatfind} will +extract the information from it. If multiple project files are found, none of +them is read, and you have to use the @samp{-p} switch to specify the one +you want to use. + +The following lines can be included, even though most of them have default +values which can be used in most cases. +The lines can be entered in any order in the file. +Except for @file{src_dir} and @file{obj_dir}, you can only have one instance of +each line. If you have multiple instances, only the last one is taken into +account. + +@table @code +@item src_dir=DIR +[default: @code{"^./^[]^"}] +specifies a directory where to look for source files. Multiple @code{src_dir} +lines can be specified and they will be searched in the order they +are specified. + +@item obj_dir=DIR +[default: @code{"^./^[]^"}] +specifies a directory where to look for object and library files. Multiple +@code{obj_dir} lines can be specified, and they will be searched in the order +they are specified + +@item comp_opt=SWITCHES +[default: @code{""}] +creates a variable which can be referred to subsequently by using +the @code{$@{comp_opt@}} notation. This is intended to store the default +switches given to @command{gnatmake} and @command{gcc}. + +@item bind_opt=SWITCHES +[default: @code{""}] +creates a variable which can be referred to subsequently by using +the @samp{$@{bind_opt@}} notation. This is intended to store the default +switches given to @command{gnatbind}. + +@item link_opt=SWITCHES +[default: @code{""}] +creates a variable which can be referred to subsequently by using +the @samp{$@{link_opt@}} notation. This is intended to store the default +switches given to @command{gnatlink}. + +@item main=EXECUTABLE +[default: @code{""}] +specifies the name of the executable for the application. This variable can +be referred to in the following lines by using the @samp{$@{main@}} notation. + +@ifset vms +@item comp_cmd=COMMAND +[default: @code{"GNAT COMPILE /SEARCH=$@{src_dir@} /DEBUG /TRY_SEMANTICS"}] +@end ifset +@ifclear vms +@item comp_cmd=COMMAND +[default: @code{"gcc -c -I$@{src_dir@} -g -gnatq"}] +@end ifclear +specifies the command used to compile a single file in the application. + +@ifset vms +@item make_cmd=COMMAND +[default: @code{"GNAT MAKE $@{main@} +/SOURCE_SEARCH=$@{src_dir@} /OBJECT_SEARCH=$@{obj_dir@} +/DEBUG /TRY_SEMANTICS /COMPILER_QUALIFIERS $@{comp_opt@} +/BINDER_QUALIFIERS $@{bind_opt@} /LINKER_QUALIFIERS $@{link_opt@}"}] +@end ifset +@ifclear vms +@item make_cmd=COMMAND +[default: @code{"gnatmake $@{main@} -aI$@{src_dir@} +-aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@} +-bargs $@{bind_opt@} -largs $@{link_opt@}"}] +@end ifclear +specifies the command used to recompile the whole application. + +@item run_cmd=COMMAND +[default: @code{"$@{main@}"}] +specifies the command used to run the application. + +@item debug_cmd=COMMAND +[default: @code{"gdb $@{main@}"}] +specifies the command used to debug the application + +@end table + +@noindent +@command{gnatxref} and @command{gnatfind} only take into account the +@code{src_dir} and @code{obj_dir} lines, and ignore the others. + +@node Regular Expressions in gnatfind and gnatxref +@section Regular Expressions in @code{gnatfind} and @code{gnatxref} + +@noindent +As specified in the section about @command{gnatfind}, the pattern can be a +regular expression. Actually, there are to set of regular expressions +which are recognized by the program: + +@table @code +@item globbing patterns +These are the most usual regular expression. They are the same that you +generally used in a Unix shell command line, or in a DOS session. + +Here is a more formal grammar: +@smallexample +@group +@iftex +@leftskip=.5cm +@end iftex +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 group +@end smallexample + +@item full regular expression +The second set of regular expressions is much more powerful. This is the +type of regular expressions recognized by utilities such a @file{grep}. + +The following is the form of a regular expression, expressed in Ada +reference manual style BNF is as follows + +@smallexample +@iftex +@leftskip=.5cm +@end iftex +@group +regexp ::= term @{| term@} -- alternation (term or term @dots{}) + +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 +@end group +@group +elmt ::= nschar -- matches given character +elmt ::= [nschar @{nschar@}] -- matches any character listed +elmt ::= [^^^ nschar @{nschar@}] -- matches any character not listed +elmt ::= [char - char] -- matches chars in given range +elmt ::= \ char -- matches given character +elmt ::= . -- matches any single character +elmt ::= ( regexp ) -- parens used for grouping + +char ::= any character, including special characters +nschar ::= any character except ()[].*+?^^^ +@end group +@end smallexample + +Following are a few examples: + +@table @samp +@item abcde|fghi +will match any of the two strings @samp{abcde} and @samp{fghi}, + +@item abc*d +will match any string like @samp{abd}, @samp{abcd}, @samp{abccd}, +@samp{abcccd}, and so on, + +@item [a-z]+ +will match any string which has only lowercase characters in it (and at +least one character. + +@end table +@end table + +@node Examples of gnatxref Usage +@section Examples of @code{gnatxref} Usage + +@subsection General Usage + +@noindent +For the following examples, we will consider the following units: + +@smallexample @c ada +@group +@cartouche +main.ads: +1: with Bar; +2: package Main is +3: procedure Foo (B : in Integer); +4: C : Integer; +5: private +6: D : Integer; +7: end Main; + +main.adb: +1: package body Main is +2: procedure Foo (B : in Integer) is +3: begin +4: C := B; +5: D := B; +6: Bar.Print (B); +7: Bar.Print (C); +8: end Foo; +9: end Main; + +bar.ads: +1: package Bar is +2: procedure Print (B : Integer); +3: end bar; +@end cartouche +@end group +@end smallexample + +@table @code + +@noindent +The first thing to do is to recompile your application (for instance, in +that case just by doing a @samp{gnatmake main}, so that GNAT generates +the cross-referencing information. +You can then issue any of the following commands: + +@item gnatxref main.adb +@code{gnatxref} generates cross-reference information for main.adb +and every unit 'with'ed by main.adb. + +The output would be: +@smallexample +@iftex +@leftskip=0cm +@end iftex +B Type: Integer + Decl: bar.ads 2:22 +B Type: Integer + Decl: main.ads 3:20 + Body: main.adb 2:20 + Ref: main.adb 4:13 5:13 6:19 +Bar Type: Unit + Decl: bar.ads 1:9 + Ref: main.adb 6:8 7:8 + main.ads 1:6 +C Type: Integer + Decl: main.ads 4:5 + Modi: main.adb 4:8 + Ref: main.adb 7:19 +D Type: Integer + Decl: main.ads 6:5 + Modi: main.adb 5:8 +Foo Type: Unit + Decl: main.ads 3:15 + Body: main.adb 2:15 +Main Type: Unit + Decl: main.ads 2:9 + Body: main.adb 1:14 +Print Type: Unit + Decl: bar.ads 2:15 + Ref: main.adb 6:12 7:12 +@end smallexample + +@noindent +that is the entity @code{Main} is declared in main.ads, line 2, column 9, +its body is in main.adb, line 1, column 14 and is not referenced any where. + +The entity @code{Print} is declared in bar.ads, line 2, column 15 and it +it referenced in main.adb, line 6 column 12 and line 7 column 12. + +@item gnatxref package1.adb package2.ads +@code{gnatxref} will generates cross-reference information for +package1.adb, package2.ads and any other package 'with'ed by any +of these. + +@end table + +@ifclear vms +@subsection Using gnatxref with vi + +@code{gnatxref} can generate a tags file output, which can be used +directly from @command{vi}. Note that the standard version of @command{vi} +will not work properly with overloaded symbols. Consider using another +free implementation of @command{vi}, such as @command{vim}. + +@smallexample +$ gnatxref -v gnatfind.adb > tags +@end smallexample + +@noindent +will generate the tags file for @code{gnatfind} itself (if the sources +are in the search path!). + +From @command{vi}, you can then use the command @samp{:tag @var{entity}} +(replacing @var{entity} by whatever you are looking for), and vi will +display a new file with the corresponding declaration of entity. +@end ifclear + +@node Examples of gnatfind Usage +@section Examples of @code{gnatfind} Usage + +@table @code + +@item gnatfind ^-f^/FULL_PATHNAME^ 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 @samp{^-f^/FULL_PATHNAME^} +switch is set) + +The output will look like: +@smallexample +^directory/^[directory]^main.ads:106:14: xyz <= declaration +^directory/^[directory]^main.adb:24:10: xyz <= body +^directory/^[directory]^foo.ads:45:23: xyz <= declaration +@end smallexample + +@noindent +that is to say, 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 gnatfind ^-fs^/FULL_PATHNAME/SOURCE_LINE^ xyz:main.adb +This is the same command as the previous one, instead @code{gnatfind} will +display the content of the Ada source file lines. + +The output will look like: + +@smallexample +^directory/^[directory]^main.ads:106:14: xyz <= declaration + procedure xyz; +^directory/^[directory]^main.adb:24:10: xyz <= body + procedure xyz is +^directory/^[directory]^foo.ads:45:23: xyz <= declaration + xyz : Integer; +@end smallexample + +@noindent +This can make it easier to find exactly the location your are looking +for. + +@item gnatfind ^-r^/REFERENCES^ "*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 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 gnatfind ^mydir/^[mydir]^main.adb:123:45 +Find the declaration for the entity referenced at column 45 in +line 123 of file main.adb in directory mydir. Note that it +is usual to omit the identifier name when the column is given, +since the column position identifies a unique reference. + +The column has to be the beginning of the identifier, and should not +point to any character in the middle of the identifier. + +@end table + +@c ********************************* +@node The GNAT Pretty-Printer gnatpp +@chapter The GNAT Pretty-Printer @command{gnatpp} +@findex gnatpp +@cindex Pretty-Printer + +@noindent +^The @command{gnatpp} tool^GNAT PRETTY^ is an ASIS-based utility +for source reformatting / pretty-printing. +It takes an Ada source file as input and generates a reformatted +version as output. +You can specify various style directives via switches; e.g., +identifier case conventions, rules of indentation, and comment layout. + +To produce a reformatted file, @command{gnatpp} generates and uses the ASIS +tree for the input source and thus requires the input to be syntactically and +semantically legal. +If this condition is not met, @command{gnatpp} will terminate with an +error message; no output file will be generated. + +If the source files presented to @command{gnatpp} contain +preprocessing directives, then the output file will +correspond to the generated source after all +preprocessing is carried out. There is no way +using @command{gnatpp} to obtain pretty printed files that +include the preprocessing directives. + +If the compilation unit +contained in the input source depends semantically upon units located +outside the current directory, you have to provide the source search path +when invoking @command{gnatpp}, if these units are contained in files with +names that do not follow the GNAT file naming rules, you have to provide +the configuration file describing the corresponding naming scheme; +see the description of the @command{gnatpp} +switches below. Another possibility is to use a project file and to +call @command{gnatpp} through the @command{gnat} driver + +The @command{gnatpp} command has the form + +@smallexample +@c $ gnatpp @ovar{switches} @var{filename} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatpp @r{[}@var{switches}@r{]} @var{filename} @r{[}-cargs @var{gcc_switches}@r{]} +@end smallexample + +@noindent +where +@itemize @bullet +@item +@var{switches} is an optional sequence of switches defining such properties as +the formatting rules, the source search path, and the destination for the +output source file + +@item +@var{filename} is the name (including the extension) of the source file to +reformat; ``wildcards'' or several file names on the same gnatpp command are +allowed. The file name may contain path information; it does not have to +follow the GNAT file naming rules + +@item +@samp{@var{gcc_switches}} is a list of switches for +@command{gcc}. They will be passed on to all compiler invocations made by +@command{gnatelim} to generate the ASIS trees. Here you can provide +@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, +use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. +@end itemize + +@menu +* Switches for gnatpp:: +* Formatting Rules:: +@end menu + +@node Switches for gnatpp +@section Switches for @command{gnatpp} + +@noindent +The following subsections describe the various switches accepted by +@command{gnatpp}, organized by category. + +@ifclear vms +You specify a switch by supplying a name and generally also a value. +In many cases the values for a switch with a given name are incompatible with +each other +(for example the switch that controls the casing of a reserved word may have +exactly one value: upper case, lower case, or +mixed case) and thus exactly one such switch can be in effect for an +invocation of @command{gnatpp}. +If more than one is supplied, the last one is used. +However, some values for the same switch are mutually compatible. +You may supply several such switches to @command{gnatpp}, but then +each must be specified in full, with both the name and the value. +Abbreviated forms (the name appearing once, followed by each value) are +not permitted. +For example, to set +the alignment of the assignment delimiter both in declarations and in +assignment statements, you must write @option{-A2A3} +(or @option{-A2 -A3}), but not @option{-A23}. +@end ifclear + +@ifset vms +In many cases the set of options for a given qualifier are incompatible with +each other (for example the qualifier that controls the casing of a reserved +word may have exactly one option, which specifies either upper case, lower +case, or mixed case), and thus exactly one such option can be in effect for +an invocation of @command{gnatpp}. +If more than one is supplied, the last one is used. +However, some qualifiers have options that are mutually compatible, +and then you may then supply several such options when invoking +@command{gnatpp}. +@end ifset + +In most cases, it is obvious whether or not the +^values for a switch with a given name^options for a given qualifier^ +are compatible with each other. +When the semantics might not be evident, the summaries below explicitly +indicate the effect. + +@menu +* Alignment Control:: +* Casing Control:: +* Construct Layout Control:: +* General Text Layout Control:: +* Other Formatting Options:: +* Setting the Source Search Path:: +* Output File Control:: +* Other gnatpp Switches:: +@end menu + +@node Alignment Control +@subsection Alignment Control +@cindex Alignment control in @command{gnatpp} + +@noindent +Programs can be easier to read if certain constructs are vertically aligned. +By default all alignments are set ON. +Through the @option{^-A0^/ALIGN=OFF^} switch you may reset the default to +OFF, and then use one or more of the other +^@option{-A@var{n}} switches^@option{/ALIGN} options^ +to activate alignment for specific constructs. + +@table @option +@cindex @option{^-A@var{n}^/ALIGN^} (@command{gnatpp}) + +@ifset vms +@item /ALIGN=ON +Set all alignments to ON +@end ifset + +@item ^-A0^/ALIGN=OFF^ +Set all alignments to OFF + +@item ^-A1^/ALIGN=COLONS^ +Align @code{:} in declarations + +@item ^-A2^/ALIGN=DECLARATIONS^ +Align @code{:=} in initializations in declarations + +@item ^-A3^/ALIGN=STATEMENTS^ +Align @code{:=} in assignment statements + +@item ^-A4^/ALIGN=ARROWS^ +Align @code{=>} in associations + +@item ^-A5^/ALIGN=COMPONENT_CLAUSES^ +Align @code{at} keywords in the component clauses in record +representation clauses +@end table + +@noindent +The @option{^-A^/ALIGN^} switches are mutually compatible; any combination +is allowed. + +@node Casing Control +@subsection Casing Control +@cindex Casing control in @command{gnatpp} + +@noindent +@command{gnatpp} allows you to specify the casing for reserved words, +pragma names, attribute designators and identifiers. +For identifiers you may define a +general rule for name casing but also override this rule +via a set of dictionary files. + +Three types of casing are supported: lower case, upper case, and mixed case. +Lower and upper case are self-explanatory (but since some letters in +Latin1 and other GNAT-supported character sets +exist only in lower-case form, an upper case conversion will have no +effect on them.) +``Mixed case'' means that the first letter, and also each letter immediately +following an underscore, are converted to their uppercase forms; +all the other letters are converted to their lowercase forms. + +@table @option +@cindex @option{^-a@var{x}^/ATTRIBUTE^} (@command{gnatpp}) +@item ^-aL^/ATTRIBUTE_CASING=LOWER_CASE^ +Attribute designators are lower case + +@item ^-aU^/ATTRIBUTE_CASING=UPPER_CASE^ +Attribute designators are upper case + +@item ^-aM^/ATTRIBUTE_CASING=MIXED_CASE^ +Attribute designators are mixed case (this is the default) + +@cindex @option{^-k@var{x}^/KEYWORD_CASING^} (@command{gnatpp}) +@item ^-kL^/KEYWORD_CASING=LOWER_CASE^ +Keywords (technically, these are known in Ada as @emph{reserved words}) are +lower case (this is the default) + +@item ^-kU^/KEYWORD_CASING=UPPER_CASE^ +Keywords are upper case + +@cindex @option{^-n@var{x}^/NAME_CASING^} (@command{gnatpp}) +@item ^-nD^/NAME_CASING=AS_DECLARED^ +Name casing for defining occurrences are as they appear in the source file +(this is the default) + +@item ^-nU^/NAME_CASING=UPPER_CASE^ +Names are in upper case + +@item ^-nL^/NAME_CASING=LOWER_CASE^ +Names are in lower case + +@item ^-nM^/NAME_CASING=MIXED_CASE^ +Names are in mixed case + +@cindex @option{^-p@var{x}^/PRAGMA_CASING^} (@command{gnatpp}) +@item ^-pL^/PRAGMA_CASING=LOWER_CASE^ +Pragma names are lower case + +@item ^-pU^/PRAGMA_CASING=UPPER_CASE^ +Pragma names are upper case + +@item ^-pM^/PRAGMA_CASING=MIXED_CASE^ +Pragma names are mixed case (this is the default) + +@item ^-D@var{file}^/DICTIONARY=@var{file}^ +@cindex @option{^-D^/DICTIONARY^} (@command{gnatpp}) +Use @var{file} as a @emph{dictionary file} that defines +the casing for a set of specified names, +thereby overriding the effect on these names by +any explicit or implicit +^-n^/NAME_CASING^ switch. +To supply more than one dictionary file, +use ^several @option{-D} switches^a list of files as options^. + +@noindent +@option{gnatpp} implicitly uses a @emph{default dictionary file} +to define the casing for the Ada predefined names and +the names declared in the GNAT libraries. + +@item ^-D-^/SPECIFIC_CASING^ +@cindex @option{^-D-^/SPECIFIC_CASING^} (@command{gnatpp}) +Do not use the default dictionary file; +instead, use the casing +defined by a @option{^-n^/NAME_CASING^} switch and any explicit +dictionary file(s) +@end table + +@noindent +The structure of a dictionary file, and details on the conventions +used in the default dictionary file, are defined in @ref{Name Casing}. + +The @option{^-D-^/SPECIFIC_CASING^} and +@option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually +compatible. + +@node Construct Layout Control +@subsection Construct Layout Control +@cindex Layout control in @command{gnatpp} + +@noindent +This group of @command{gnatpp} switches controls the layout of comments and +complex syntactic constructs. See @ref{Formatting Comments} for details +on their effect. + +@table @option +@cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp}) +@item ^-c0^/COMMENTS_LAYOUT=UNTOUCHED^ +All the comments remain unchanged + +@item ^-c1^/COMMENTS_LAYOUT=DEFAULT^ +GNAT-style comment line indentation (this is the default). + +@item ^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^ +Reference-manual comment line indentation. + +@item ^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^ +GNAT-style comment beginning + +@item ^-c4^/COMMENTS_LAYOUT=REFORMAT^ +Reformat comment blocks + +@item ^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^ +Keep unchanged special form comments + +Reformat comment blocks + +@cindex @option{^-l@var{n}^/CONSTRUCT_LAYOUT^} (@command{gnatpp}) +@item ^-l1^/CONSTRUCT_LAYOUT=GNAT^ +GNAT-style layout (this is the default) + +@item ^-l2^/CONSTRUCT_LAYOUT=COMPACT^ +Compact layout + +@item ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^ +Uncompact layout + +@cindex @option{^-N^/NOTABS^} (@command{gnatpp}) +@item ^-N^/NOTABS^ +All the VT characters are removed from the comment text. All the HT characters +are expanded with the sequences of space characters to get to the next tab +stops. + +@cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp}) +@item ^--no-separate-is^/NO_SEPARATE_IS^ +Do not place the keyword @code{is} on a separate line in a subprogram body in +case if the spec occupies more then one line. + +@cindex @option{^--separate-label^/SEPARATE_LABEL^} (@command{gnatpp}) +@item ^--separate-label^/SEPARATE_LABEL^ +Place statement label(s) on a separate line, with the following statement +on the next line. + +@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp}) +@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^ +Place the keyword @code{loop} in FOR and WHILE loop statements and the +keyword @code{then} in IF statements on a separate line. + +@cindex @option{^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^} (@command{gnatpp}) +@item ^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^ +Do not place the keyword @code{loop} in FOR and WHILE loop statements and the +keyword @code{then} in IF statements on a separate line. This option is +incompatible with @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} option. + +@cindex @option{^--use-on-new-line^/USE_ON_NEW_LINE^} (@command{gnatpp}) +@item ^--use-on-new-line^/USE_ON_NEW_LINE^ +Start each USE clause in a context clause from a separate line. + +@cindex @option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^} (@command{gnatpp}) +@item ^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^ +Use a separate line for a loop or block statement name, but do not use an extra +indentation level for the statement itself. + +@end table + +@ifclear vms +@noindent +The @option{-c1} and @option{-c2} switches are incompatible. +The @option{-c3} and @option{-c4} switches are compatible with each other and +also with @option{-c1} and @option{-c2}. The @option{-c0} switch disables all +the other comment formatting switches. + +The @option{-l1}, @option{-l2}, and @option{-l3} switches are incompatible. +@end ifclear + +@ifset vms +@noindent +For the @option{/COMMENTS_LAYOUT} qualifier: +@itemize @bullet +@item +The @option{DEFAULT} and @option{STANDARD_INDENT} options are incompatible. +@item +The @option{GNAT_BEGINNING} and @option{REFORMAT} options are compatible with +each other and also with @option{DEFAULT} and @option{STANDARD_INDENT}. +@end itemize + +@noindent +The @option{GNAT}, @option{COMPACT}, and @option{UNCOMPACT} options for the +@option{/CONSTRUCT_LAYOUT} qualifier are incompatible. +@end ifset + +@node General Text Layout Control +@subsection General Text Layout Control + +@noindent +These switches allow control over line length and indentation. + +@table @option +@item ^-M@var{nnn}^/LINE_LENGTH_MAX=@var{nnn}^ +@cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp}) +Maximum line length, @var{nnn} from 32@dots{}256, the default value is 79 + +@item ^-i@var{nnn}^/INDENTATION_LEVEL=@var{nnn}^ +@cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp}) +Indentation level, @var{nnn} from 1@dots{}9, the default value is 3 + +@item ^-cl@var{nnn}^/CONTINUATION_INDENT=@var{nnn}^ +@cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp}) +Indentation level for continuation lines (relative to the line being +continued), @var{nnn} from 1@dots{}9. +The default +value is one less then the (normal) indentation level, unless the +indentation is set to 1 (in which case the default value for continuation +line indentation is also 1) +@end table + +@node Other Formatting Options +@subsection Other Formatting Options + +@noindent +These switches control the inclusion of missing end/exit labels, and +the indentation level in @b{case} statements. + +@table @option +@item ^-e^/NO_MISSED_LABELS^ +@cindex @option{^-e^/NO_MISSED_LABELS^} (@command{gnatpp}) +Do not insert missing end/exit labels. An end label is the name of +a construct that may optionally be repeated at the end of the +construct's declaration; +e.g., the names of packages, subprograms, and tasks. +An exit label is the name of a loop that may appear as target +of an exit statement within the loop. +By default, @command{gnatpp} inserts these end/exit labels when +they are absent from the original source. This option suppresses such +insertion, so that the formatted source reflects the original. + +@item ^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^ +@cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp}) +Insert a Form Feed character after a pragma Page. + +@item ^-T@var{nnn}^/MAX_INDENT=@var{nnn}^ +@cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp}) +Do not use an additional indentation level for @b{case} alternatives +and variants if there are @var{nnn} or more (the default +value is 10). +If @var{nnn} is 0, an additional indentation level is +used for @b{case} alternatives and variants regardless of their number. +@end table + +@node Setting the Source Search Path +@subsection Setting the Source Search Path + +@noindent +To define the search path for the input source file, @command{gnatpp} +uses the same switches as the GNAT compiler, with the same effects. + +@table @option +@item ^-I^/SEARCH=^@var{dir} +@cindex @option{^-I^/SEARCH^} (@code{gnatpp}) +The same as the corresponding gcc switch + +@item ^-I-^/NOCURRENT_DIRECTORY^ +@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatpp}) +The same as the corresponding gcc switch + +@item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE^=@var{path} +@cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@code{gnatpp}) +The same as the corresponding gcc switch + +@item ^--RTS^/RUNTIME_SYSTEM^=@var{path} +@cindex @option{^--RTS^/RUNTIME_SYSTEM^} (@code{gnatpp}) +The same as the corresponding gcc switch + +@end table + +@node Output File Control +@subsection Output File Control + +@noindent +By default the output is sent to the file whose name is obtained by appending +the ^@file{.pp}^@file{$PP}^ suffix to the name of the input file +(if the file with this name already exists, it is unconditionally overwritten). +Thus if the input file is @file{^my_ada_proc.adb^MY_ADA_PROC.ADB^} then +@command{gnatpp} will produce @file{^my_ada_proc.adb.pp^MY_ADA_PROC.ADB$PP^} +as output file. +The output may be redirected by the following switches: + +@table @option +@item ^-pipe^/STANDARD_OUTPUT^ +@cindex @option{^-pipe^/STANDARD_OUTPUT^} (@code{gnatpp}) +Send the output to @code{Standard_Output} + +@item ^-o @var{output_file}^/OUTPUT=@var{output_file}^ +@cindex @option{^-o^/OUTPUT^} (@code{gnatpp}) +Write the output into @var{output_file}. +If @var{output_file} already exists, @command{gnatpp} terminates without +reading or processing the input file. + +@item ^-of ^/FORCED_OUTPUT=^@var{output_file} +@cindex @option{^-of^/FORCED_OUTPUT^} (@code{gnatpp}) +Write the output into @var{output_file}, overwriting the existing file +(if one is present). + +@item ^-r^/REPLACE^ +@cindex @option{^-r^/REPLACE^} (@code{gnatpp}) +Replace the input source file with the reformatted output, and copy the +original input source into the file whose name is obtained by appending the +^@file{.npp}^@file{$NPP}^ suffix to the name of the input file. +If a file with this name already exists, @command{gnatpp} terminates without +reading or processing the input file. + +@item ^-rf^/OVERRIDING_REPLACE^ +@cindex @option{^-rf^/OVERRIDING_REPLACE^} (@code{gnatpp}) +Like @option{^-r^/REPLACE^} except that if the file with the specified name +already exists, it is overwritten. + +@item ^-rnb^/REPLACE_NO_BACKUP^ +@cindex @option{^-rnb^/REPLACE_NO_BACKUP^} (@code{gnatpp}) +Replace the input source file with the reformatted output without +creating any backup copy of the input source. + +@item ^--eol=@var{xxx}^/END_OF_LINE=@var{xxx}^ +@cindex @option{^--eol^/END_OF_LINE^} (@code{gnatpp}) +Specifies the format of the reformatted output file. The @var{xxx} +^string specified with the switch^option^ may be either +@itemize @bullet +@item ``@option{^dos^DOS^}'' MS DOS style, lines end with CR LF characters +@item ``@option{^crlf^CRLF^}'' +the same as @option{^crlf^CRLF^} +@item ``@option{^unix^UNIX^}'' UNIX style, lines end with LF character +@item ``@option{^lf^LF^}'' +the same as @option{^unix^UNIX^} +@end itemize + +@item ^-W^/RESULT_ENCODING=^@var{e} +@cindex @option{^-W^/RESULT_ENCODING=^} (@command{gnatpp}) +Specify the wide character encoding method used to write the code in the +result file +@var{e} is one of the following: + +@itemize @bullet + +@item ^h^HEX^ +Hex encoding + +@item ^u^UPPER^ +Upper half encoding + +@item ^s^SHIFT_JIS^ +Shift/JIS encoding + +@item ^e^EUC^ +EUC encoding + +@item ^8^UTF8^ +UTF-8 encoding + +@item ^b^BRACKETS^ +Brackets encoding (default value) +@end itemize + +@end table + +@noindent +Options @option{^-pipe^/STANDARD_OUTPUT^}, +@option{^-o^/OUTPUT^} and +@option{^-of^/FORCED_OUTPUT^} are allowed only if the call to gnatpp +contains only one file to reformat. +Option +@option{^--eol^/END_OF_LINE^} +and +@option{^-W^/RESULT_ENCODING^} +cannot be used together +with @option{^-pipe^/STANDARD_OUTPUT^} option. + +@node Other gnatpp Switches +@subsection Other @code{gnatpp} Switches + +@noindent +The additional @command{gnatpp} switches are defined in this subsection. + +@table @option +@item ^-files @var{filename}^/FILES=@var{filename}^ +@cindex @option{^-files^/FILES^} (@code{gnatpp}) +Take the argument source files from the specified file. This file should be an +ordinary text file containing file names separated by spaces or +line breaks. You can use this switch more than once in the same call to +@command{gnatpp}. You also can combine this switch with an explicit list of +files. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@code{gnatpp}) +Verbose mode; +@command{gnatpp} generates version information and then +a trace of the actions it takes to produce or obtain the ASIS tree. + +@item ^-w^/WARNINGS^ +@cindex @option{^-w^/WARNINGS^} (@code{gnatpp}) +Warning mode; +@command{gnatpp} generates a warning whenever it cannot provide +a required layout in the result source. +@end table + +@node Formatting Rules +@section Formatting Rules + +@noindent +The following subsections show how @command{gnatpp} treats ``white space'', +comments, program layout, and name casing. +They provide the detailed descriptions of the switches shown above. + +@menu +* White Space and Empty Lines:: +* Formatting Comments:: +* Construct Layout:: +* Name Casing:: +@end menu + +@node White Space and Empty Lines +@subsection White Space and Empty Lines + +@noindent +@command{gnatpp} does not have an option to control space characters. +It will add or remove spaces according to the style illustrated by the +examples in the @cite{Ada Reference Manual}. + +The only format effectors +(see @cite{Ada Reference Manual}, paragraph 2.1(13)) +that will appear in the output file are platform-specific line breaks, +and also format effectors within (but not at the end of) comments. +In particular, each horizontal tab character that is not inside +a comment will be treated as a space and thus will appear in the +output file as zero or more spaces depending on +the reformatting of the line in which it appears. +The only exception is a Form Feed character, which is inserted after a +pragma @code{Page} when @option{-ff} is set. + +The output file will contain no lines with trailing ``white space'' (spaces, +format effectors). + +Empty lines in the original source are preserved +only if they separate declarations or statements. +In such contexts, a +sequence of two or more empty lines is replaced by exactly one empty line. +Note that a blank line will be removed if it separates two ``comment blocks'' +(a comment block is a sequence of whole-line comments). +In order to preserve a visual separation between comment blocks, use an +``empty comment'' (a line comprising only hyphens) rather than an empty line. +Likewise, if for some reason you wish to have a sequence of empty lines, +use a sequence of empty comments instead. + +@node Formatting Comments +@subsection Formatting Comments + +@noindent +Comments in Ada code are of two kinds: +@itemize @bullet +@item +a @emph{whole-line comment}, which appears by itself (possibly preceded by +``white space'') on a line + +@item +an @emph{end-of-line comment}, which follows some other Ada lexical element +on the same line. +@end itemize + +@noindent +The indentation of a whole-line comment is that of either +the preceding or following line in +the formatted source, depending on switch settings as will be described below. + +For an end-of-line comment, @command{gnatpp} leaves the same number of spaces +between the end of the preceding Ada lexical element and the beginning +of the comment as appear in the original source, +unless either the comment has to be split to +satisfy the line length limitation, or else the next line contains a +whole line comment that is considered a continuation of this end-of-line +comment (because it starts at the same position). +In the latter two +cases, the start of the end-of-line comment is moved right to the nearest +multiple of the indentation level. +This may result in a ``line overflow'' (the right-shifted comment extending +beyond the maximum line length), in which case the comment is split as +described below. + +There is a difference between @option{^-c1^/COMMENTS_LAYOUT=DEFAULT^} +(GNAT-style comment line indentation) +and @option{^-c2^/COMMENTS_LAYOUT=STANDARD_INDENT^} +(reference-manual comment line indentation). +With reference-manual style, a whole-line comment is indented as if it +were a declaration or statement at the same place +(i.e., according to the indentation of the preceding line(s)). +With GNAT style, a whole-line comment that is immediately followed by an +@b{if} or @b{case} statement alternative, a record variant, or the reserved +word @b{begin}, is indented based on the construct that follows it. + +For example: +@smallexample @c ada +@cartouche +if A then + null; + -- some comment +else + null; +end if; +@end cartouche +@end smallexample + +@noindent +Reference-manual indentation produces: + +@smallexample @c ada +@cartouche +if A then + null; + -- some comment +else + null; +end if; +@end cartouche +@end smallexample + +@noindent +while GNAT-style indentation produces: + +@smallexample @c ada +@cartouche +if A then + null; +-- some comment +else + null; +end if; +@end cartouche +@end smallexample + +@noindent +The @option{^-c3^/COMMENTS_LAYOUT=GNAT_BEGINNING^} switch +(GNAT style comment beginning) has the following +effect: + +@itemize @bullet +@item +For each whole-line comment that does not end with two hyphens, +@command{gnatpp} inserts spaces if necessary after the starting two hyphens +to ensure that there are at least two spaces between these hyphens and the +first non-blank character of the comment. +@end itemize + +@noindent +For an end-of-line comment, if in the original source the next line is a +whole-line comment that starts at the same position +as the end-of-line comment, +then the whole-line comment (and all whole-line comments +that follow it and that start at the same position) +will start at this position in the output file. + +@noindent +That is, if in the original source we have: + +@smallexample @c ada +@cartouche +begin +A := B + C; -- B must be in the range Low1..High1 + -- C must be in the range Low2..High2 + --B+C will be in the range Low1+Low2..High1+High2 +X := X + 1; +@end cartouche +@end smallexample + +@noindent +Then in the formatted source we get + +@smallexample @c ada +@cartouche +begin + A := B + C; -- B must be in the range Low1..High1 + -- C must be in the range Low2..High2 + -- B+C will be in the range Low1+Low2..High1+High2 + X := X + 1; +@end cartouche +@end smallexample + +@noindent +A comment that exceeds the line length limit will be split. +Unless switch +@option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} (reformat comment blocks) is set and +the line belongs to a reformattable block, splitting the line generates a +@command{gnatpp} warning. +The @option{^-c4^/COMMENTS_LAYOUT=REFORMAT^} switch specifies that whole-line +comments may be reformatted in typical +word processor style (that is, moving words between lines and putting as +many words in a line as possible). + +@noindent +The @option{^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^} switch specifies, that comments +that has a special format (that is, a character that is neither a letter nor digit +not white space nor line break immediately following the leading @code{--} of +the comment) should be without any change moved from the argument source +into reformatted source. This switch allows to preserve comments that are used +as a special marks in the code (e.g.@: SPARK annotation). + +@node Construct Layout +@subsection Construct Layout + +@noindent +In several cases the suggested layout in the Ada Reference Manual includes +an extra level of indentation that many programmers prefer to avoid. The +affected cases include: + +@itemize @bullet + +@item Record type declaration (RM 3.8) + +@item Record representation clause (RM 13.5.1) + +@item Loop statement in case if a loop has a statement identifier (RM 5.6) + +@item Block statement in case if a block has a statement identifier (RM 5.6) +@end itemize + +@noindent +In compact mode (when GNAT style layout or compact layout is set), +the pretty printer uses one level of indentation instead +of two. This is achieved in the record definition and record representation +clause cases by putting the @code{record} keyword on the same line as the +start of the declaration or representation clause, and in the block and loop +case by putting the block or loop header on the same line as the statement +identifier. + +@noindent +The difference between GNAT style @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^} +and compact @option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} +layout on the one hand, and uncompact layout +@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} on the other hand, +can be illustrated by the following examples: + +@iftex +@cartouche +@multitable @columnfractions .5 .5 +@item @i{GNAT style, compact layout} @tab @i{Uncompact layout} + +@item +@smallexample @c ada +type q is record + a : integer; + b : integer; +end record; +@end smallexample +@tab +@smallexample @c ada +type q is + record + a : integer; + b : integer; + end record; +@end smallexample + +@item +@smallexample @c ada +for q use record + a at 0 range 0 .. 31; + b at 4 range 0 .. 31; +end record; +@end smallexample +@tab +@smallexample @c ada +for q use + record + a at 0 range 0 .. 31; + b at 4 range 0 .. 31; + end record; +@end smallexample + +@item +@smallexample @c ada +Block : declare + A : Integer := 3; +begin + Proc (A, A); +end Block; +@end smallexample +@tab +@smallexample @c ada +Block : + declare + A : Integer := 3; + begin + Proc (A, A); + end Block; +@end smallexample + +@item +@smallexample @c ada +Clear : for J in 1 .. 10 loop + A (J) := 0; +end loop Clear; +@end smallexample +@tab +@smallexample @c ada +Clear : + for J in 1 .. 10 loop + A (J) := 0; + end loop Clear; +@end smallexample +@end multitable +@end cartouche +@end iftex + +@ifnottex +@smallexample +@cartouche +GNAT style, compact layout Uncompact layout + +type q is record type q is + a : integer; record + b : integer; a : integer; +end record; b : integer; + end record; + +for q use record for q use + a at 0 range 0 .. 31; record + b at 4 range 0 .. 31; a at 0 range 0 .. 31; +end record; b at 4 range 0 .. 31; + end record; + +Block : declare Block : + A : Integer := 3; declare +begin A : Integer := 3; + Proc (A, A); begin +end Block; Proc (A, A); + end Block; + +Clear : for J in 1 .. 10 loop Clear : + A (J) := 0; for J in 1 .. 10 loop +end loop Clear; A (J) := 0; + end loop Clear; +@end cartouche +@end smallexample +@end ifnottex + +@noindent +A further difference between GNAT style layout and compact layout is that +GNAT style layout inserts empty lines as separation for +compound statements, return statements and bodies. + +Note that the layout specified by +@option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^} +for named block and loop statements overrides the layout defined by these +constructs by @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^}, +@option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} or +@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} option. + +@node Name Casing +@subsection Name Casing + +@noindent +@command{gnatpp} always converts the usage occurrence of a (simple) name to +the same casing as the corresponding defining identifier. + +You control the casing for defining occurrences via the +@option{^-n^/NAME_CASING^} switch. +@ifclear vms +With @option{-nD} (``as declared'', which is the default), +@end ifclear +@ifset vms +With @option{/NAME_CASING=AS_DECLARED}, which is the default, +@end ifset +defining occurrences appear exactly as in the source file +where they are declared. +The other ^values for this switch^options for this qualifier^ --- +@option{^-nU^UPPER_CASE^}, +@option{^-nL^LOWER_CASE^}, +@option{^-nM^MIXED_CASE^} --- +result in +^upper, lower, or mixed case, respectively^the corresponding casing^. +If @command{gnatpp} changes the casing of a defining +occurrence, it analogously changes the casing of all the +usage occurrences of this name. + +If the defining occurrence of a name is not in the source compilation unit +currently being processed by @command{gnatpp}, the casing of each reference to +this name is changed according to the value of the @option{^-n^/NAME_CASING^} +switch (subject to the dictionary file mechanism described below). +Thus @command{gnatpp} acts as though the @option{^-n^/NAME_CASING^} switch +had affected the +casing for the defining occurrence of the name. + +Some names may need to be spelled with casing conventions that are not +covered by the upper-, lower-, and mixed-case transformations. +You can arrange correct casing by placing such names in a +@emph{dictionary file}, +and then supplying a @option{^-D^/DICTIONARY^} switch. +The casing of names from dictionary files overrides +any @option{^-n^/NAME_CASING^} switch. + +To handle the casing of Ada predefined names and the names from GNAT libraries, +@command{gnatpp} assumes a default dictionary file. +The name of each predefined entity is spelled with the same casing as is used +for the entity in the @cite{Ada Reference Manual}. +The name of each entity in the GNAT libraries is spelled with the same casing +as is used in the declaration of that entity. + +The @w{@option{^-D-^/SPECIFIC_CASING^}} switch suppresses the use of the +default dictionary file. +Instead, the casing for predefined and GNAT-defined names will be established +by the @option{^-n^/NAME_CASING^} switch or explicit dictionary files. +For example, by default the names @code{Ada.Text_IO} and @code{GNAT.OS_Lib} +will appear as just shown, +even in the presence of a @option{^-nU^/NAME_CASING=UPPER_CASE^} switch. +To ensure that even such names are rendered in uppercase, +additionally supply the @w{@option{^-D-^/SPECIFIC_CASING^}} switch +(or else, less conveniently, place these names in upper case in a dictionary +file). + +A dictionary file is +a plain text file; each line in this file can be either a blank line +(containing only space characters and ASCII.HT characters), an Ada comment +line, or the specification of exactly one @emph{casing schema}. + +A casing schema is a string that has the following syntax: + +@smallexample +@cartouche + @var{casing_schema} ::= @var{identifier} | *@var{simple_identifier}* + + @var{simple_identifier} ::= @var{letter}@{@var{letter_or_digit}@} +@end cartouche +@end smallexample + +@noindent +(See @cite{Ada Reference Manual}, Section 2.3) for the definition of the +@var{identifier} lexical element and the @var{letter_or_digit} category.) + +The casing schema string can be followed by white space and/or an Ada-style +comment; any amount of white space is allowed before the string. + +If a dictionary file is passed as +@ifclear vms +the value of a @option{-D@var{file}} switch +@end ifclear +@ifset vms +an option to the @option{/DICTIONARY} qualifier +@end ifset +then for every +simple name and every identifier, @command{gnatpp} checks if the dictionary +defines the casing for the name or for some of its parts (the term ``subword'' +is used below to denote the part of a name which is delimited by ``_'' or by +the beginning or end of the word and which does not contain any ``_'' inside): + +@itemize @bullet +@item +if the whole name is in the dictionary, @command{gnatpp} uses for this name +the casing defined by the dictionary; no subwords are checked for this word + +@item +for every subword @command{gnatpp} checks if the dictionary contains the +corresponding string of the form @code{*@var{simple_identifier}*}, +and if it does, the casing of this @var{simple_identifier} is used +for this subword + +@item +if the whole name does not contain any ``_'' inside, and if for this name +the dictionary contains two entries - one of the form @var{identifier}, +and another - of the form *@var{simple_identifier}*, then the first one +is applied to define the casing of this name + +@item +if more than one dictionary file is passed as @command{gnatpp} switches, each +dictionary adds new casing exceptions and overrides all the existing casing +exceptions set by the previous dictionaries + +@item +when @command{gnatpp} checks if the word or subword is in the dictionary, +this check is not case sensitive +@end itemize + +@noindent +For example, suppose we have the following source to reformat: + +@smallexample @c ada +@cartouche +procedure test is + name1 : integer := 1; + name4_name3_name2 : integer := 2; + name2_name3_name4 : Boolean; + name1_var : Float; +begin + name2_name3_name4 := name4_name3_name2 > name1; +end; +@end cartouche +@end smallexample + +@noindent +And suppose we have two dictionaries: + +@smallexample +@cartouche +@i{dict1:} + NAME1 + *NaMe3* + *Name1* +@end cartouche + +@cartouche +@i{dict2:} + *NAME3* +@end cartouche +@end smallexample + +@noindent +If @command{gnatpp} is called with the following switches: + +@smallexample +@ifclear vms +@command{gnatpp -nM -D dict1 -D dict2 test.adb} +@end ifclear +@ifset vms +@command{gnatpp test.adb /NAME_CASING=MIXED_CASE /DICTIONARY=(dict1, dict2)} +@end ifset +@end smallexample + +@noindent +then we will get the following name casing in the @command{gnatpp} output: + +@smallexample @c ada +@cartouche +procedure Test is + NAME1 : Integer := 1; + Name4_NAME3_Name2 : Integer := 2; + Name2_NAME3_Name4 : Boolean; + Name1_Var : Float; +begin + Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1; +end Test; +@end cartouche +@end smallexample + +@c ********************************* +@node The GNAT Metric Tool gnatmetric +@chapter The GNAT Metric Tool @command{gnatmetric} +@findex gnatmetric +@cindex Metric tool + +@noindent +^The @command{gnatmetric} tool^@command{GNAT METRIC}^ is an ASIS-based utility +for computing various program metrics. +It takes an Ada source file as input and generates a file containing the +metrics data as output. Various switches control which +metrics are computed and output. + +@command{gnatmetric} generates and uses the ASIS +tree for the input source and thus requires the input to be syntactically and +semantically legal. +If this condition is not met, @command{gnatmetric} will generate +an error message; no metric information for this file will be +computed and reported. + +If the compilation unit contained in the input source depends semantically +upon units in files located outside the current directory, you have to provide +the source search path when invoking @command{gnatmetric}. +If it depends semantically upon units that are contained +in files with names that do not follow the GNAT file naming rules, you have to +provide the configuration file describing the corresponding naming scheme (see +the description of the @command{gnatmetric} switches below.) +Alternatively, you may use a project file and invoke @command{gnatmetric} +through the @command{gnat} driver. + +The @command{gnatmetric} command has the form + +@smallexample +@c $ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatmetric @r{[}@var{switches}@r{]} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]} +@end smallexample + +@noindent +where +@itemize @bullet +@item +@var{switches} specify the metrics to compute and define the destination for +the output + +@item +Each @var{filename} is the name (including the extension) of a source +file to process. ``Wildcards'' are allowed, and +the file name may contain path information. +If no @var{filename} is supplied, then the @var{switches} list must contain +at least one +@option{-files} switch (@pxref{Other gnatmetric Switches}). +Including both a @option{-files} switch and one or more +@var{filename} arguments is permitted. + +@item +@samp{@var{gcc_switches}} is a list of switches for +@command{gcc}. They will be passed on to all compiler invocations made by +@command{gnatmetric} to generate the ASIS trees. Here you can provide +@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, +and use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. +@end itemize + +@menu +* Switches for gnatmetric:: +@end menu + +@node Switches for gnatmetric +@section Switches for @command{gnatmetric} + +@noindent +The following subsections describe the various switches accepted by +@command{gnatmetric}, organized by category. + +@menu +* Output Files Control:: +* Disable Metrics For Local Units:: +* Specifying a set of metrics to compute:: +* Other gnatmetric Switches:: +* Generate project-wide metrics:: +@end menu + +@node Output Files Control +@subsection Output File Control +@cindex Output file control in @command{gnatmetric} + +@noindent +@command{gnatmetric} has two output formats. It can generate a +textual (human-readable) form, and also XML. By default only textual +output is generated. + +When generating the output in textual form, @command{gnatmetric} creates +for each Ada source file a corresponding text file +containing the computed metrics, except for the case when the set of metrics +specified by gnatmetric parameters consists only of metrics that are computed +for the whole set of analyzed sources, but not for each Ada source. +By default, this file is placed in the same directory as where the source +file is located, and its name is obtained +by appending the ^@file{.metrix}^@file{$METRIX}^ suffix to the name of the +input file. + +All the output information generated in XML format is placed in a single +file. By default this file is placed in the current directory and has the +name ^@file{metrix.xml}^@file{METRIX$XML}^. + +Some of the computed metrics are summed over the units passed to +@command{gnatmetric}; for example, the total number of lines of code. +By default this information is sent to @file{stdout}, but a file +can be specified with the @option{-og} switch. + +The following switches control the @command{gnatmetric} output: + +@table @option +@cindex @option{^-x^/XML^} (@command{gnatmetric}) +@item ^-x^/XML^ +Generate the XML output + +@cindex @option{^-xs^/XSD^} (@command{gnatmetric}) +@item ^-xs^/XSD^ +Generate the XML output and the XML schema file that describes the structure +of the XML metric report, this schema is assigned to the XML file. The schema +file has the same name as the XML output file with @file{.xml} suffix replaced +with @file{.xsd} + +@cindex @option{^-nt^/NO_TEXT^} (@command{gnatmetric}) +@item ^-nt^/NO_TEXT^ +Do not generate the output in text form (implies @option{^-x^/XML^}) + +@cindex @option{^-d^/DIRECTORY^} (@command{gnatmetric}) +@item ^-d @var{output_dir}^/DIRECTORY=@var{output_dir}^ +Put text files with detailed metrics into @var{output_dir} + +@cindex @option{^-o^/SUFFIX_DETAILS^} (@command{gnatmetric}) +@item ^-o @var{file_suffix}^/SUFFIX_DETAILS=@var{file_suffix}^ +Use @var{file_suffix}, instead of ^@file{.metrix}^@file{$METRIX}^ +in the name of the output file. + +@cindex @option{^-og^/GLOBAL_OUTPUT^} (@command{gnatmetric}) +@item ^-og @var{file_name}^/GLOBAL_OUTPUT=@var{file_name}^ +Put global metrics into @var{file_name} + +@cindex @option{^-ox^/XML_OUTPUT^} (@command{gnatmetric}) +@item ^-ox @var{file_name}^/XML_OUTPUT=@var{file_name}^ +Put the XML output into @var{file_name} (also implies @option{^-x^/XML^}) + +@cindex @option{^-sfn^/SHORT_SOURCE_FILE_NAME^} (@command{gnatmetric}) +@item ^-sfn^/SHORT_SOURCE_FILE_NAME^ +Use ``short'' source file names in the output. (The @command{gnatmetric} +output includes the name(s) of the Ada source file(s) from which the metrics +are computed. By default each name includes the absolute path. The +@option{^-sfn^/SHORT_SOURCE_FILE_NAME^} switch causes @command{gnatmetric} +to exclude all directory information from the file names that are output.) + +@end table + +@node Disable Metrics For Local Units +@subsection Disable Metrics For Local Units +@cindex Disable Metrics For Local Units in @command{gnatmetric} + +@noindent +@command{gnatmetric} relies on the GNAT compilation model @minus{} +one compilation +unit per one source file. It computes line metrics for the whole source +file, and it also computes syntax +and complexity metrics for the file's outermost unit. + +By default, @command{gnatmetric} will also compute all metrics for certain +kinds of locally declared program units: + +@itemize @bullet +@item +subprogram (and generic subprogram) bodies; + +@item +package (and generic package) specs and bodies; + +@item +task object and type specifications and bodies; + +@item +protected object and type specifications and bodies. +@end itemize + +@noindent +These kinds of entities will be referred to as +@emph{eligible local program units}, or simply @emph{eligible local units}, +@cindex Eligible local unit (for @command{gnatmetric}) +in the discussion below. + +Note that a subprogram declaration, generic instantiation, +or renaming declaration only receives metrics +computation when it appear as the outermost entity +in a source file. + +Suppression of metrics computation for eligible local units can be +obtained via the following switch: + +@table @option +@cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric}) +@item ^-nolocal^/SUPPRESS=LOCAL_DETAILS^ +Do not compute detailed metrics for eligible local program units + +@end table + +@node Specifying a set of metrics to compute +@subsection Specifying a set of metrics to compute + +@noindent +By default all the metrics are computed and reported. The switches +described in this subsection allow you to control, on an individual +basis, whether metrics are computed and +reported. If at least one positive metric +switch is specified (that is, a switch that defines that a given +metric or set of metrics is to be computed), then only +explicitly specified metrics are reported. + +@menu +* Line Metrics Control:: +* Syntax Metrics Control:: +* Complexity Metrics Control:: +* Object-Oriented Metrics Control:: +@end menu + +@node Line Metrics Control +@subsubsection Line Metrics Control +@cindex Line metrics control in @command{gnatmetric} + +@noindent +For any (legal) source file, and for each of its +eligible local program units, @command{gnatmetric} computes the following +metrics: + +@itemize @bullet +@item +the total number of lines; + +@item +the total number of code lines (i.e., non-blank lines that are not comments) + +@item +the number of comment lines + +@item +the number of code lines containing end-of-line comments; + +@item +the comment percentage: the ratio between the number of lines that contain +comments and the number of all non-blank lines, expressed as a percentage; + +@item +the number of empty lines and lines containing only space characters and/or +format effectors (blank lines) + +@item +the average number of code lines in subprogram bodies, task bodies, entry +bodies and statement sequences in package bodies (this metric is only computed +across the whole set of the analyzed units) + +@end itemize + +@noindent +@command{gnatmetric} sums the values of the line metrics for all the +files being processed and then generates the cumulative results. The tool +also computes for all the files being processed the average number of code +lines in bodies. + +You can use the following switches to select the specific line metrics +to be computed and reported. + +@table @option +@cindex @option{^--lines@var{x}^/LINE_COUNT_METRICS^} (@command{gnatmetric}) + +@ifclear vms +@cindex @option{--no-lines@var{x}} +@end ifclear + +@item ^--lines-all^/LINE_COUNT_METRICS=ALL^ +Report all the line metrics + +@item ^--no-lines-all^/LINE_COUNT_METRICS=NONE^ +Do not report any of line metrics + +@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES^ +Report the number of all lines + +@item ^--no-lines^/LINE_COUNT_METRICS=NOALL_LINES^ +Do not report the number of all lines + +@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES^ +Report the number of code lines + +@item ^--no-lines-code^/LINE_COUNT_METRICS=NOCODE_LINES^ +Do not report the number of code lines + +@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES^ +Report the number of comment lines + +@item ^--no-lines-comment^/LINE_COUNT_METRICS=NOCOMMENT_LINES^ +Do not report the number of comment lines + +@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES^ +Report the number of code lines containing +end-of-line comments + +@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=NOCODE_COMMENT_LINES^ +Do not report the number of code lines containing +end-of-line comments + +@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE^ +Report the comment percentage in the program text + +@item ^--no-lines-ratio^/LINE_COUNT_METRICS=NOCOMMENT_PERCENTAGE^ +Do not report the comment percentage in the program text + +@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES^ +Report the number of blank lines + +@item ^--no-lines-blank^/LINE_COUNT_METRICS=NOBLANK_LINES^ +Do not report the number of blank lines + +@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES^ +Report the average number of code lines in subprogram bodies, task bodies, +entry bodies and statement sequences in package bodies. The metric is computed +and reported for the whole set of processed Ada sources only. + +@item ^--no-lines-average^/LINE_COUNT_METRICS=NOAVERAGE_BODY_LINES^ +Do not report the average number of code lines in subprogram bodies, +task bodies, entry bodies and statement sequences in package bodies. + +@end table + +@node Syntax Metrics Control +@subsubsection Syntax Metrics Control +@cindex Syntax metrics control in @command{gnatmetric} + +@noindent +@command{gnatmetric} computes various syntactic metrics for the +outermost unit and for each eligible local unit: + +@table @emph +@item LSLOC (``Logical Source Lines Of Code'') +The total number of declarations and the total number of statements + +@item Maximal static nesting level of inner program units +According to +@cite{Ada Reference Manual}, 10.1(1), ``A program unit is either a +package, a task unit, a protected unit, a +protected entry, a generic unit, or an explicitly declared subprogram other +than an enumeration literal.'' + +@item Maximal nesting level of composite syntactic constructs +This corresponds to the notion of the +maximum nesting level in the GNAT built-in style checks +(@pxref{Style Checking}) +@end table + +@noindent +For the outermost unit in the file, @command{gnatmetric} additionally computes +the following metrics: + +@table @emph +@item Public subprograms +This metric is computed for package specs. It is the +number of subprograms and generic subprograms declared in the visible +part (including the visible part of nested packages, protected objects, and +protected types). + +@item All subprograms +This metric is computed for bodies and subunits. The +metric is equal to a total number of subprogram bodies in the compilation +unit. +Neither generic instantiations nor renamings-as-a-body nor body stubs +are counted. Any subprogram body is counted, independently of its nesting +level and enclosing constructs. Generic bodies and bodies of protected +subprograms are counted in the same way as ``usual'' subprogram bodies. + +@item Public types +This metric is computed for package specs and +generic package declarations. It is the total number of types +that can be referenced from outside this compilation unit, plus the +number of types from all the visible parts of all the visible generic +packages. Generic formal types are not counted. Only types, not subtypes, +are included. + +@noindent +Along with the total number of public types, the following +types are counted and reported separately: + +@itemize @bullet +@item +Abstract types + +@item +Root tagged types (abstract, non-abstract, private, non-private). Type +extensions are @emph{not} counted + +@item +Private types (including private extensions) + +@item +Task types + +@item +Protected types + +@end itemize + +@item All types +This metric is computed for any compilation unit. It is equal to the total +number of the declarations of different types given in the compilation unit. +The private and the corresponding full type declaration are counted as one +type declaration. Incomplete type declarations and generic formal types +are not counted. +No distinction is made among different kinds of types (abstract, +private etc.); the total number of types is computed and reported. + +@end table + +@noindent +By default, all the syntax metrics are computed and reported. You can use the +following switches to select specific syntax metrics. + +@table @option + +@cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric}) + +@ifclear vms +@cindex @option{--no-syntax@var{x}} (@command{gnatmetric}) +@end ifclear + +@item ^--syntax-all^/SYNTAX_METRICS=ALL^ +Report all the syntax metrics + +@item ^--no-syntax-all^/SYNTAX_METRICS=NONE^ +Do not report any of syntax metrics + +@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS^ +Report the total number of declarations + +@item ^--no-declarations^/SYNTAX_METRICS=NODECLARATIONS^ +Do not report the total number of declarations + +@item ^--statements^/SYNTAX_METRICS=STATEMENTS^ +Report the total number of statements + +@item ^--no-statements^/SYNTAX_METRICS=NOSTATEMENTS^ +Do not report the total number of statements + +@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS^ +Report the number of public subprograms in a compilation unit + +@item ^--no-public-subprograms^/SYNTAX_METRICS=NOPUBLIC_SUBPROGRAMS^ +Do not report the number of public subprograms in a compilation unit + +@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS^ +Report the number of all the subprograms in a compilation unit + +@item ^--no-all-subprograms^/SYNTAX_METRICS=NOALL_SUBPROGRAMS^ +Do not report the number of all the subprograms in a compilation unit + +@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES^ +Report the number of public types in a compilation unit + +@item ^--no-public-types^/SYNTAX_METRICS=NOPUBLIC_TYPES^ +Do not report the number of public types in a compilation unit + +@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES^ +Report the number of all the types in a compilation unit + +@item ^--no-all-types^/SYNTAX_METRICS=NOALL_TYPES^ +Do not report the number of all the types in a compilation unit + +@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING^ +Report the maximal program unit nesting level + +@item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^ +Do not report the maximal program unit nesting level + +@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING^ +Report the maximal construct nesting level + +@item ^--no-construct-nesting^/SYNTAX_METRICS=NOCONSTRUCT_NESTING^ +Do not report the maximal construct nesting level + +@end table + +@node Complexity Metrics Control +@subsubsection Complexity Metrics Control +@cindex Complexity metrics control in @command{gnatmetric} + +@noindent +For a program unit that is an executable body (a subprogram body (including +generic bodies), task body, entry body or a package body containing +its own statement sequence) @command{gnatmetric} computes the following +complexity metrics: + +@itemize @bullet +@item +McCabe cyclomatic complexity; + +@item +McCabe essential complexity; + +@item +maximal loop nesting level + +@end itemize + +@noindent +The McCabe complexity metrics are defined +in @url{http://www.mccabe.com/pdf/nist235r.pdf} + +According to McCabe, both control statements and short-circuit control forms +should be taken into account when computing cyclomatic complexity. For each +body, we compute three metric values: + +@itemize @bullet +@item +the complexity introduced by control +statements only, without taking into account short-circuit forms, + +@item +the complexity introduced by short-circuit control forms only, and + +@item +the total +cyclomatic complexity, which is the sum of these two values. +@end itemize + +@noindent +When computing cyclomatic and essential complexity, @command{gnatmetric} skips +the code in the exception handlers and in all the nested program units. + +By default, all the complexity metrics are computed and reported. +For more fine-grained control you can use +the following switches: + +@table @option +@cindex @option{^-complexity@var{x}^/COMPLEXITY_METRICS^} (@command{gnatmetric}) + +@ifclear vms +@cindex @option{--no-complexity@var{x}} +@end ifclear + +@item ^--complexity-all^/COMPLEXITY_METRICS=ALL^ +Report all the complexity metrics + +@item ^--no-complexity-all^/COMPLEXITY_METRICS=NONE^ +Do not report any of complexity metrics + +@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC^ +Report the McCabe Cyclomatic Complexity + +@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=NOCYCLOMATIC^ +Do not report the McCabe Cyclomatic Complexity + +@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL^ +Report the Essential Complexity + +@item ^--no-complexity-essential^/COMPLEXITY_METRICS=NOESSENTIAL^ +Do not report the Essential Complexity + +@item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^ +Report maximal loop nesting level + +@item ^--no-loop-nesting^/COMPLEXITY_METRICS=NOLOOP_NESTING^ +Do not report maximal loop nesting level + +@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY^ +Report the average McCabe Cyclomatic Complexity for all the subprogram bodies, +task bodies, entry bodies and statement sequences in package bodies. +The metric is computed and reported for whole set of processed Ada sources +only. + +@item ^--no-complexity-average^/COMPLEXITY_METRICS=NOAVERAGE_COMPLEXITY^ +Do not report the average McCabe Cyclomatic Complexity for all the subprogram +bodies, task bodies, entry bodies and statement sequences in package bodies + +@cindex @option{^-ne^/NO_EXITS_AS_GOTOS^} (@command{gnatmetric}) +@item ^-ne^/NO_EXITS_AS_GOTOS^ +Do not consider @code{exit} statements as @code{goto}s when +computing Essential Complexity + +@item ^--extra-exit-points^/EXTRA_EXIT_POINTS^ +Report the extra exit points for subprogram bodies. As an exit point, this +metric counts @code{return} statements and raise statements in case when the +raised exception is not handled in the same body. In case of a function this +metric subtracts 1 from the number of exit points, because a function body +must contain at least one @code{return} statement. + +@item ^--no-extra-exit-points^/NOEXTRA_EXIT_POINTS^ +Do not report the extra exit points for subprogram bodies +@end table + + +@node Object-Oriented Metrics Control +@subsubsection Object-Oriented Metrics Control +@cindex Object-Oriented metrics control in @command{gnatmetric} + +@noindent +@cindex Coupling metrics (in in @command{gnatmetric}) +Coupling metrics are object-oriented metrics that measure the +dependencies between a given class (or a group of classes) and the +``external world'' (that is, the other classes in the program). In this +subsection the term ``class'' is used in its +traditional object-oriented programming sense +(an instantiable module that contains data and/or method members). +A @emph{category} (of classes) +is a group of closely related classes that are reused and/or +modified together. + +A class @code{K}'s @emph{efferent coupling} is the number of classes +that @code{K} depends upon. +A category's efferent coupling is the number of classes outside the +category that the classes inside the category depend upon. + +A class @code{K}'s @emph{afferent coupling} is the number of classes +that depend upon @code{K}. +A category's afferent coupling is the number of classes outside the +category that depend on classes belonging to the category. + +Ada's implementation of the object-oriented paradigm does not use the +traditional class notion, so the definition of the coupling +metrics for Ada maps the class and class category notions +onto Ada constructs. + +For the coupling metrics, several kinds of modules -- a library package, +a library generic package, and a library generic package instantiation -- +that define a tagged type or an interface type are +considered to be a class. A category consists of a library package (or +a library generic package) that defines a tagged or an interface type, +together with all its descendant (generic) packages that define tagged +or interface types. For any package counted as a class, +its body and subunits (if any) are considered +together with its spec when counting the dependencies, and coupling +metrics are reported for spec units only. For dependencies +between classes, the Ada semantic dependencies are considered. +For coupling metrics, only dependencies on units that are considered as +classes, are considered. + +When computing coupling metrics, @command{gnatmetric} counts only +dependencies between units that are arguments of the gnatmetric call. +Coupling metrics are program-wide (or project-wide) metrics, so to +get a valid result, you should call @command{gnatmetric} for +the whole set of sources that make up your program. It can be done +by calling @command{gnatmetric} from the GNAT driver with @option{-U} +option (see See @ref{The GNAT Driver and Project Files} for details. + +By default, all the coupling metrics are disabled. You can use the following +switches to specify the coupling metrics to be computed and reported: + +@table @option + +@ifclear vms +@cindex @option{--package@var{x}} (@command{gnatmetric}) +@cindex @option{--no-package@var{x}} (@command{gnatmetric}) +@cindex @option{--category@var{x}} (@command{gnatmetric}) +@cindex @option{--no-category@var{x}} (@command{gnatmetric}) +@end ifclear + +@ifset vms +@cindex @option{/COUPLING_METRICS} (@command{gnatmetric}) +@end ifset + +@item ^--coupling-all^/COUPLING_METRICS=ALL^ +Report all the coupling metrics + +@item ^--no-coupling-all^/COUPLING_METRICS=NONE^ +Do not report any of metrics + +@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT^ +Report package efferent coupling + +@item ^--no-package-efferent-coupling^/COUPLING_METRICS=NOPACKAGE_EFFERENT^ +Do not report package efferent coupling + +@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT^ +Report package afferent coupling + +@item ^--no-package-afferent-coupling^/COUPLING_METRICS=NOPACKAGE_AFFERENT^ +Do not report package afferent coupling + +@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT^ +Report category efferent coupling + +@item ^--no-category-efferent-coupling^/COUPLING_METRICS=NOCATEGORY_EFFERENT^ +Do not report category efferent coupling + +@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT^ +Report category afferent coupling + +@item ^--no-category-afferent-coupling^/COUPLING_METRICS=NOCATEGORY_AFFERENT^ +Do not report category afferent coupling + +@end table + +@node Other gnatmetric Switches +@subsection Other @code{gnatmetric} Switches + +@noindent +Additional @command{gnatmetric} switches are as follows: + +@table @option +@item ^-files @var{filename}^/FILES=@var{filename}^ +@cindex @option{^-files^/FILES^} (@code{gnatmetric}) +Take the argument source files from the specified file. This file should be an +ordinary text file containing file names separated by spaces or +line breaks. You can use this switch more than once in the same call to +@command{gnatmetric}. You also can combine this switch with +an explicit list of files. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@code{gnatmetric}) +Verbose mode; +@command{gnatmetric} generates version information and then +a trace of sources being processed. + +@item ^-q^/QUIET^ +@cindex @option{^-q^/QUIET^} (@code{gnatmetric}) +Quiet mode. +@end table + +@node Generate project-wide metrics +@subsection Generate project-wide metrics + +In order to compute metrics on all units of a given project, you can use +the @command{gnat} driver along with the @option{-P} option: +@smallexample + gnat metric -Pproj +@end smallexample + +@noindent +If the project @code{proj} depends upon other projects, you can compute +the metrics on the project closure using the @option{-U} option: +@smallexample + gnat metric -Pproj -U +@end smallexample + +@noindent +Finally, if not all the units are relevant to a particular main +program in the project closure, you can generate metrics for the set +of units needed to create a given main program (unit closure) using +the @option{-U} option followed by the name of the main unit: +@smallexample + gnat metric -Pproj -U main +@end smallexample + + +@c *********************************** +@node File Name Krunching Using gnatkr +@chapter File Name Krunching Using @code{gnatkr} +@findex gnatkr + +@noindent +This chapter discusses the method used by the compiler to shorten +the default file names chosen for Ada units so that they do not +exceed the maximum length permitted. It also describes the +@code{gnatkr} utility that can be used to determine the result of +applying this shortening. +@menu +* About gnatkr:: +* Using gnatkr:: +* Krunching Method:: +* Examples of gnatkr Usage:: +@end menu + +@node About gnatkr +@section About @code{gnatkr} + +@noindent +The default file naming rule in GNAT +is that the file name must be derived from +the unit name. The exact default rule is as follows: +@itemize @bullet +@item +Take the unit name and replace all dots by hyphens. +@item +If such a replacement occurs in the +second character position of a name, and the first character is +^@samp{a}, @samp{g}, @samp{s}, or @samp{i}, ^@samp{A}, @samp{G}, @samp{S}, or @samp{I},^ +then replace the dot by the character +^@samp{~} (tilde)^@samp{$} (dollar sign)^ +instead of a minus. +@end itemize +The reason for this exception is to avoid clashes +with the standard names for children of System, Ada, Interfaces, +and GNAT, which use the prefixes +^@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},^@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},^ +respectively. + +The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}} +switch of the compiler activates a ``krunching'' +circuit that limits file names to nn characters (where nn is a decimal +integer). For example, using OpenVMS, +where the maximum file name length is +39, the value of nn is usually set to 39, but if you want to generate +a set of files that would be usable if ported to a system with some +different maximum file length, then a different value can be specified. +The default value of 39 for OpenVMS need not be specified. + +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 +@section Using @code{gnatkr} + +@noindent +The @code{gnatkr} command has the form + +@ifclear vms +@smallexample +@c $ gnatkr @var{name} @ovar{length} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatkr @var{name} @r{[}@var{length}@r{]} +@end smallexample +@end ifclear + +@ifset vms +@smallexample +$ gnatkr @var{name} /COUNT=nn +@end smallexample +@end ifset + +@noindent +@var{name} is the uncrunched file name, derived from the name of the unit +in the standard manner described in the previous section (i.e., in particular +all dots are replaced by hyphens). The file name may or may not have an +extension (defined as a suffix of the form period followed by arbitrary +characters other than period). If an extension is present then it will +be preserved in the output. For example, when krunching @file{hellofile.ads} +to eight characters, the result will be hellofil.ads. + +Note: for compatibility with previous versions of @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 @code{gnatkr} is given an argument +such as @file{Hello.World.adb} it will be treated exactly as if the first +period had been a hyphen, and for example krunching to eight characters +gives the result @file{hellworl.adb}. + +Note that the result is always all lower case (except on OpenVMS where it is +all upper case). Characters of the other case are folded as required. + +@var{length} represents the length of the krunched name. The default +when no argument is given is ^8^39^ 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. + +@noindent +The output is the krunched name. The output has an extension only if the +original argument was a file name with an extension. + +@node Krunching Method +@section Krunching Method + +@noindent +The initial file name is determined by the name of the unit that the file +contains. The name is formed by taking the full expanded name of the +unit and replacing the separating dots with hyphens and +using ^lowercase^uppercase^ +for all letters, except that a hyphen in the second character position is +replaced by a ^tilde^dollar sign^ if the first character is +^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^. +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: + +@itemize @bullet +@item +The name is divided into segments separated by hyphens, tildes or +underscores and all hyphens, tildes, and underscores are +eliminated. If this leaves the name short enough, we are done. + +@item +If the name is too long, the longest segment is located (left-most +if there are two of equal length), and shortened by dropping +its last character. This is repeated until the name is short enough. + +As an example, consider the krunching of @*@file{our-strings-wide_fixed.adb} +to fit the name into 8 characters as required by some operating systems. + +@smallexample +our-strings-wide_fixed 22 +our strings wide fixed 19 +our string wide fixed 18 +our strin wide fixed 17 +our stri wide fixed 16 +our stri wide fixe 15 +our str wide fixe 14 +our str wid fixe 13 +our str wid fix 12 +ou str wid fix 11 +ou st wid fix 10 +ou st wi fix 9 +ou st wi fi 8 +Final file name: oustwifi.adb +@end smallexample + +@item +The file names for all predefined units are always krunched to eight +characters. The krunching of these predefined units uses the following +special prefix replacements: + +@table @file +@item ada- +replaced by @file{^a^A^-} + +@item gnat- +replaced by @file{^g^G^-} + +@item interfaces- +replaced by @file{^i^I^-} + +@item system- +replaced by @file{^s^S^-} +@end table + +These system files have a hyphen in the second character position. That +is why normal user files replace such a character with a +^tilde^dollar sign^, to +avoid confusion with system file names. + +As an example of this special rule, consider +@*@file{ada-strings-wide_fixed.adb}, which gets krunched as follows: + +@smallexample +ada-strings-wide_fixed 22 +a- strings wide fixed 18 +a- string wide fixed 17 +a- strin wide fixed 16 +a- stri wide fixed 15 +a- stri wide fixe 14 +a- str wide fixe 13 +a- str wid fixe 12 +a- str wid fix 11 +a- st wid fix 10 +a- st wi fix 9 +a- st wi fi 8 +Final file name: a-stwifi.adb +@end smallexample +@end itemize + +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 @code{gnatkr} is supplied for conveniently determining the +krunched name of a file. + +@node Examples of gnatkr Usage +@section Examples of @code{gnatkr} Usage + +@smallexample +@iftex +@leftskip=0cm +@end iftex +@ifclear vms +$ gnatkr very_long_unit_name.ads --> velounna.ads +$ gnatkr grandparent-parent-child.ads --> grparchi.ads +$ gnatkr Grandparent.Parent.Child.ads --> grparchi.ads +$ gnatkr grandparent-parent-child --> grparchi +@end ifclear +$ gnatkr very_long_unit_name.ads/count=6 --> vlunna.ads +$ gnatkr very_long_unit_name.ads/count=0 --> very_long_unit_name.ads +@end smallexample + +@node Preprocessing Using gnatprep +@chapter Preprocessing Using @code{gnatprep} +@findex gnatprep + +@noindent +This chapter discusses how to use GNAT's @code{gnatprep} utility for simple +preprocessing. +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{Conditional Compilation}. + +@menu +* Preprocessing Symbols:: +* Using gnatprep:: +* Switches for gnatprep:: +* Form of Definitions File:: +* Form of Input Text for gnatprep:: +@end menu + +@node Preprocessing Symbols +@section Preprocessing Symbols + +@noindent +Preprocessing symbols are defined in definition files and referred to in +sources to be preprocessed. A Preprocessing symbol is an identifier, following +normal Ada (case-insensitive) rules for its syntax, with the restriction that +all characters need to be in the ASCII set (no accented letters). + +@node Using gnatprep +@section Using @code{gnatprep} + +@noindent +To call @code{gnatprep} use + +@smallexample +@c $ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatprep @r{[}@var{switches}@r{]} @var{infile} @var{outfile} @r{[}@var{deffile}@r{]} +@end smallexample + +@noindent +where +@table @var +@item switches +is an optional sequence of switches as described in the next section. + +@item infile +is the full name of the input file, which is an Ada source +file containing preprocessor directives. + +@item outfile +is the full name of the output file, which is an Ada source +in standard Ada form. When used with GNAT, this file name will +normally have an ads or adb suffix. + +@item 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 @option{-D} switch. + +@end table + +@node Switches for gnatprep +@section Switches for @code{gnatprep} + +@table @option +@c !sort! + +@item ^-b^/BLANK_LINES^ +@cindex @option{^-b^/BLANK_LINES^} (@command{gnatprep}) +Causes both preprocessor lines and the lines deleted by +preprocessing to be replaced by blank lines in the output source file, +preserving line numbers in the output file. + +@item ^-c^/COMMENTS^ +@cindex @option{^-c^/COMMENTS^} (@command{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 @code{"--! "}. This option will result in line numbers +being preserved in the output file. + +@item ^-C^/REPLACE_IN_COMMENTS^ +@cindex @option{^-C^/REPLACE_IN_COMMENTS^} (@command{gnatprep}) +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). + +@item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^ +@cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep}) +Defines a new preprocessing symbol, associated with 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. + +@ifset vms +@item /REMOVE +@cindex @option{/REMOVE} (@command{gnatprep}) +This is the default setting which causes lines deleted by preprocessing +to be entirely removed from the output file. +@end ifset + +@item ^-r^/REFERENCE^ +@cindex @option{^-r^/REFERENCE^} (@command{gnatprep}) +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 @option{^-b^/BLANK_LINES^} mode if +@option{^-c^/COMMENTS^} +has not been specified explicitly. + +Note that if the file to be preprocessed contains multiple units, then +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 +@code{gnatchop ^-r^/REFERENCE^} +so that the final chopped files will correctly refer to the original +input source file for @code{gnatprep}. + +@item ^-s^/SYMBOLS^ +@cindex @option{^-s^/SYMBOLS^} (@command{gnatprep}) +Causes a sorted list of symbol names and values to be +listed on the standard output file. + +@item ^-u^/UNDEFINED^ +@cindex @option{^-u^/UNDEFINED^} (@command{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 @code{#if} or @code{#elsif} test will be treated as an error. + +@end table + +@ifclear vms +@noindent +Note: if neither @option{-b} nor @option{-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. +@end ifclear + +@node Form of Definitions File +@section Form of Definitions File + +@noindent +The definitions file contains lines of the form + +@smallexample +symbol := value +@end smallexample + +@noindent +where symbol is a preprocessing symbol, and value is one of the following: + +@itemize @bullet +@item +Empty, corresponding to a null substitution +@item +A string literal using normal Ada syntax +@item +Any sequence of characters from the set +(letters, digits, period, underline). +@end itemize + +@noindent +Comment lines may also appear in the definitions file, starting with +the usual @code{--}, +and comments may be added to the definitions lines. + +@node Form of Input Text for gnatprep +@section Form of Input Text for @code{gnatprep} + +@noindent +The input text may contain preprocessor conditional inclusion lines, +as well as general symbol substitution sequences. + +The preprocessor conditional inclusion commands have the form + +@smallexample +@group +@cartouche +#if @i{expression} @r{[}then@r{]} + lines +#elsif @i{expression} @r{[}then@r{]} + lines +#elsif @i{expression} @r{[}then@r{]} + lines +@dots{} +#else + lines +#end if; +@end cartouche +@end group +@end smallexample + +@noindent +In this example, @i{expression} is defined by the following grammar: +@smallexample +@i{expression} ::= +@i{expression} ::= = "" +@i{expression} ::= = +@i{expression} ::= 'Defined +@i{expression} ::= not @i{expression} +@i{expression} ::= @i{expression} and @i{expression} +@i{expression} ::= @i{expression} or @i{expression} +@i{expression} ::= @i{expression} and then @i{expression} +@i{expression} ::= @i{expression} or else @i{expression} +@i{expression} ::= ( @i{expression} ) +@end smallexample + +The following restriction exists: it is not allowed to have "and" or "or" +following "not" in the same expression without parentheses. For example, this +is not allowed: + +@smallexample + not X or Y +@end smallexample + +This should be one of the following: + +@smallexample + (not X) or Y + not (X or Y) +@end smallexample + +@noindent +For the first test (@i{expression} ::= ) 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 +@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. + +The test (@i{expression} ::= @code{'Defined}) is true only if +the symbol has been defined in the definition file or by a @option{-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 @option{-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 @code{True} +or @code{False}. + +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 @code{then} keyword is optional as shown + +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 @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 @code{elsif} clauses can be present, +including none at all. The @code{else} is optional, as in Ada. + +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. + +Symbol substitution outside of preprocessor lines is obtained by using +the sequence + +@smallexample +$symbol +@end smallexample + +@noindent +anywhere within a source line, except in a comment or within a +string literal. The identifier +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 @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 @code{hello} and writing: + +@smallexample +Header : String := "$XYZ"; +@end smallexample + +@noindent +you should set XYZ to @code{"hello"} and write: + +@smallexample +Header : String := $XYZ; +@end smallexample + +@noindent +and then the substitution will occur as desired. + +@node The GNAT Library Browser gnatls +@chapter The GNAT Library Browser @code{gnatls} +@findex gnatls +@cindex Library browser + +@noindent +@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. + +Note: to invoke @code{gnatls} with a project file, use the @code{gnat} +driver (see @ref{The GNAT Driver and Project Files}). + +@menu +* Running gnatls:: +* Switches for gnatls:: +* Examples of gnatls Usage:: +@end menu + +@node Running gnatls +@section Running @code{gnatls} + +@noindent +The @code{gnatls} command has the form + +@smallexample +$ gnatls switches @var{object_or_ali_file} +@end smallexample + +@noindent +The main argument is the list of object or @file{ali} files +(@pxref{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: + +@smallexample +$ 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 smallexample + +@noindent +The first line can be interpreted as follows: the main unit which is +contained in +object file @file{demo1.o} is demo1, whose main source is in +@file{demo1.adb}. Furthermore, the version of the source used for the +compilation of demo1 has been modified (DIF). Each source file has a status +qualifier which can be: + +@table @code +@item OK (unchanged) +The version of the source file used for the compilation of the +specified unit corresponds exactly to the actual source file. + +@item MOK (slightly modified) +The version of the source file used for the compilation of the +specified unit differs from the actual source file but not enough to +require recompilation. If you use gnatmake with the qualifier +@option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}, a file marked +MOK will not be recompiled. + +@item DIF (modified) +No version of the source found on the path corresponds to the source +used to build this object. + +@item ??? (file not found) +No source file was found for this unit. + +@item HID (hidden, unchanged version not first on PATH) +The version of the source that corresponds exactly to the source used +for compilation has been found on the path but it is hidden by another +version of the same source that has been modified. + +@end table + +@node Switches for gnatls +@section Switches for @code{gnatls} + +@noindent +@code{gnatls} recognizes the following switches: + +@table @option +@c !sort! +@cindex @option{--version} @command{gnatls} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatls} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item ^-a^/ALL_UNITS^ +@cindex @option{^-a^/ALL_UNITS^} (@code{gnatls}) +Consider all units, including those of the predefined Ada library. +Especially useful with @option{^-d^/DEPENDENCIES^}. + +@item ^-d^/DEPENDENCIES^ +@cindex @option{^-d^/DEPENDENCIES^} (@code{gnatls}) +List sources from which specified units depend on. + +@item ^-h^/OUTPUT=OPTIONS^ +@cindex @option{^-h^/OUTPUT=OPTIONS^} (@code{gnatls}) +Output the list of options. + +@item ^-o^/OUTPUT=OBJECTS^ +@cindex @option{^-o^/OUTPUT=OBJECTS^} (@code{gnatls}) +Only output information about object files. + +@item ^-s^/OUTPUT=SOURCES^ +@cindex @option{^-s^/OUTPUT=SOURCES^} (@code{gnatls}) +Only output information about source files. + +@item ^-u^/OUTPUT=UNITS^ +@cindex @option{^-u^/OUTPUT=UNITS^} (@code{gnatls}) +Only output information about compilation units. + +@item ^-files^/FILES^=@var{file} +@cindex @option{^-files^/FILES^} (@code{gnatls}) +Take as arguments the files listed in text file @var{file}. +Text file @var{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. + +@item ^-aO^/OBJECT_SEARCH=^@var{dir} +@itemx ^-aI^/SOURCE_SEARCH=^@var{dir} +@itemx ^-I^/SEARCH=^@var{dir} +@itemx ^-I-^/NOCURRENT_DIRECTORY^ +@itemx -nostdinc +@cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatls}) +@cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatls}) +@cindex @option{^-I^/SEARCH^} (@code{gnatls}) +@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatls}) +Source path manipulation. Same meaning as the equivalent @command{gnatmake} +flags (@pxref{Switches for gnatmake}). + +@item --RTS=@var{rts-path} +@cindex @option{--RTS} (@code{gnatls}) +Specifies the default location of the runtime library. Same meaning as the +equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}). + +@item ^-v^/OUTPUT=VERBOSE^ +@cindex @option{^-v^/OUTPUT=VERBOSE^} (@code{gnatls}) +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: + +@table @code +@item Preelaborable +The unit is preelaborable in the Ada sense. + +@item No_Elab_Code +No elaboration code has been produced by the compiler for this unit. + +@item Pure +The unit is pure in the Ada sense. + +@item Elaborate_Body +The unit contains a pragma Elaborate_Body. + +@item Remote_Types +The unit contains a pragma Remote_Types. + +@item Shared_Passive +The unit contains a pragma Shared_Passive. + +@item Predefined +This unit is part of the predefined environment and cannot be modified +by the user. + +@item Remote_Call_Interface +The unit contains a pragma Remote_Call_Interface. + +@end table + +@end table + +@node Examples of gnatls Usage +@section Example of @code{gnatls} Usage +@ifclear vms + +@noindent +Example of using the verbose switch. Note how the source and +object paths are affected by the -I switch. + +@smallexample +$ gnatls -v -I.. demo1.o + +GNATLS 5.03w (20041123-34) +Copyright 1997-2004 Free Software Foundation, Inc. + +Source Search Path: + + ../ + /home/comar/local/adainclude/ + +Object Search Path: + + ../ + /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ + +Project Search Path: + + /home/comar/local/lib/gnat/ + +./demo1.o + Unit => + Name => demo1 + Kind => subprogram body + Flags => No_Elab_Code + Source => demo1.adb modified +@end smallexample + +@noindent +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. + +@smallexample +$ 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 smallexample +@end ifclear + +@ifset vms +@smallexample +GNAT LIST /DEPENDENCIES /OUTPUT=SOURCES /ALL_UNITS DEMO1.ADB + +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]ada.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-finali.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-filico.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-stream.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]a-tags.ads +demo1.adb +gen_list.ads +gen_list.adb +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]gnat.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]g-io.ads +instr.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]system.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-exctab.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finimp.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-finroo.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-secsta.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stalib.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stoele.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-stratt.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-tasoli.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]s-unstyp.ads +GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB]unchconv.ads +@end smallexample +@end ifset + +@node Cleaning Up Using gnatclean +@chapter Cleaning Up Using @code{gnatclean} +@findex gnatclean +@cindex Cleaning tool + +@noindent +@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. + +@menu +* Running gnatclean:: +* Switches for gnatclean:: +@c * Examples of gnatclean Usage:: +@end menu + +@node Running gnatclean +@section Running @code{gnatclean} + +@noindent +The @code{gnatclean} command has the form: + +@smallexample +$ gnatclean switches @var{names} +@end smallexample + +@noindent +@var{names} is a list of source file names. Suffixes @code{.^ads^ADS^} and +@code{^adb^ADB^} may be omitted. If a project file is specified using switch +@code{^-P^/PROJECT_FILE=^}, then @var{names} may be completely omitted. + +@noindent +In normal mode, @code{gnatclean} delete the files produced by the compiler and, +if switch @code{^-c^/COMPILER_FILES_ONLY^} is not specified, by the binder and +the linker. In informative-only mode, specified by switch +@code{^-n^/NODELETE^}, the list of files that would have been deleted in +normal mode is listed, but no file is actually deleted. + +@node Switches for gnatclean +@section Switches for @code{gnatclean} + +@noindent +@code{gnatclean} recognizes the following switches: + +@table @option +@c !sort! +@cindex @option{--version} @command{gnatclean} +Display Copyright and version, then exit disregarding all other options. + +@item --help +@cindex @option{--help} @command{gnatclean} +If @option{--version} was not used, display usage, then exit disregarding +all other options. + +@item ^--subdirs^/SUBDIRS^=subdir +Actual object directory of each project file is the subdirectory subdir of the +object directory specified or defaulted in the project file. + +@item ^--unchecked-shared-lib-imports^/UNCHECKED_SHARED_LIB_IMPORTS^ +By default, shared library projects are not allowed to import static library +projects. When this switch is used on the command line, this restriction is +relaxed. + +@item ^-c^/COMPILER_FILES_ONLY^ +@cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean}) +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. + +@item ^-D ^/DIRECTORY_OBJECTS=^@var{dir} +@cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatclean}) +Indicate that ALI and object files should normally be found in directory +@var{dir}. + +@item ^-F^/FULL_PATH_IN_BRIEF_MESSAGES^ +@cindex @option{^-F^/FULL_PATH_IN_BRIEF_MESSAGES^} (@code{gnatclean}) +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^/VERBOSE^), then error lines start with the full path name of the project +file, rather than its simple file name. + +@item ^-h^/HELP^ +@cindex @option{^-h^/HELP^} (@code{gnatclean}) +Output a message explaining the usage of @code{^gnatclean^gnatclean^}. + +@item ^-n^/NODELETE^ +@cindex @option{^-n^/NODELETE^} (@code{gnatclean}) +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. + +@item ^-P^/PROJECT_FILE=^@var{project} +@cindex @option{^-P^/PROJECT_FILE^} (@code{gnatclean}) +Use project file @var{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. + +@item ^-q^/QUIET^ +@cindex @option{^-q^/QUIET^} (@code{gnatclean}) +Quiet output. If there are no errors, do not output anything, except in +verbose mode (switch ^-v^/VERBOSE^) or in informative-only mode +(switch ^-n^/NODELETE^). + +@item ^-r^/RECURSIVE^ +@cindex @option{^-r^/RECURSIVE^} (@code{gnatclean}) +When a project file is specified (using switch ^-P^/PROJECT_FILE=^), +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. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@code{gnatclean}) +Verbose mode. + +@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} +@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean}) +Indicates the verbosity of the parsing of GNAT project files. +@xref{Switches Related to Project Files}. + +@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} +@cindex @option{^-X^/EXTERNAL_REFERENCE^} (@code{gnatclean}) +Indicates that external variable @var{name} has the value @var{value}. +The Project Manager will use this value for occurrences of +@code{external(name)} when parsing the project file. +@xref{Switches Related to Project Files}. + +@item ^-aO^/OBJECT_SEARCH=^@var{dir} +@cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean}) +When searching for ALI and object files, look in directory +@var{dir}. + +@item ^-I^/SEARCH=^@var{dir} +@cindex @option{^-I^/SEARCH^} (@code{gnatclean}) +Equivalent to @option{^-aO^/OBJECT_SEARCH=^@var{dir}}. + +@item ^-I-^/NOCURRENT_DIRECTORY^ +@cindex @option{^-I-^/NOCURRENT_DIRECTORY^} (@code{gnatclean}) +@cindex Source files, suppressing search +Do not look for ALI or object files in the directory +where @code{gnatclean} was invoked. + +@end table + +@c @node Examples of gnatclean Usage +@c @section Examples of @code{gnatclean} Usage + +@ifclear vms +@node GNAT and Libraries +@chapter GNAT and Libraries +@cindex Library, building, installing, using + +@noindent +This chapter describes how to build and use libraries with GNAT, and also shows +how to recompile the GNAT run-time library. You should be familiar with the +Project Manager facility (@pxref{GNAT Project Manager}) before reading this +chapter. + +@menu +* Introduction to Libraries in GNAT:: +* General Ada Libraries:: +* Stand-alone Ada Libraries:: +* Rebuilding the GNAT Run-Time Library:: +@end menu + +@node Introduction to Libraries in GNAT +@section Introduction to Libraries in GNAT + +@noindent +A library is, conceptually, a collection of objects which does not have its +own main thread of execution, but rather provides certain services to the +applications that use it. A library can be either statically linked with the +application, in which case its code is directly included in the application, +or, on platforms that support it, be dynamically linked, in which case +its code is shared by all applications making use of this library. + +GNAT supports both types of libraries. +In the static case, the compiled code can be provided in different ways. The +simplest approach is to provide directly the set of objects resulting from +compilation of the library source files. Alternatively, you can group the +objects into an archive using whatever commands are provided by the operating +system. For the latter case, the objects are grouped into a shared library. + +In the GNAT environment, a library has three types of components: +@itemize @bullet +@item +Source files. +@item +@file{ALI} files. +@xref{The Ada Library Information Files}. +@item +Object files, an archive or a shared library. +@end itemize + +@noindent +A GNAT library may expose all its source files, which is useful for +documentation purposes. Alternatively, it may expose only the units needed by +an external user to make use of the library. That is to say, the specs +reflecting the library services along with all the units needed to compile +those specs, which can include generic bodies or any body implementing an +inlined routine. In the case of @emph{stand-alone libraries} those exposed +units are called @emph{interface units} (@pxref{Stand-alone Ada Libraries}). + +All compilation units comprising an application, including those in a library, +need to be elaborated in an order partially defined by Ada's semantics. GNAT +computes the elaboration order from the @file{ALI} files and this is why they +constitute a mandatory part of GNAT libraries. +@emph{Stand-alone libraries} are the exception to this rule because a specific +library elaboration routine is produced independently of the application(s) +using the library. + +@node General Ada Libraries +@section General Ada Libraries + +@menu +* Building a library:: +* Installing a library:: +* Using a library:: +@end menu + +@node Building a library +@subsection Building a library + +@noindent +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} +(@pxref{Library Projects}). + +A project is considered a library project, when two project-level attributes +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 @code +@item Library_Kind +This attribute controls whether the library is to be static or dynamic + +@item Library_Version +This attribute specifies the library version; this value is used +during dynamic linking of shared libraries to determine if the currently +installed versions of the binaries are compatible. + +@item Library_Options +@item Library_GCC +These attributes specify additional low-level options to be used during +library generation, and redefine the actual application used to generate +library. +@end table + +@noindent +The GNAT Project Manager takes full care of the library maintenance task, +including recompilation of the source files for which objects do not exist +or are not up to date, assembly of the library archive, and installation of +the library (i.e., copying associated source, object and @file{ALI} files +to the specified location). + +Here is a simple library project file: +@smallexample @c ada +project My_Lib is + for Source_Dirs use ("src1", "src2"); + for Object_Dir use "obj"; + for Library_Name use "mylib"; + for Library_Dir use "lib"; + for Library_Kind use "dynamic"; +end My_lib; +@end smallexample + +@noindent +and the compilation command to build and install the library: + +@smallexample @c ada + $ gnatmake -Pmy_lib +@end smallexample + +@noindent +It is not entirely trivial to perform manually all the steps required to +produce a library. We recommend that you use the GNAT Project Manager +for this task. In special cases where this is not desired, the necessary +steps are discussed below. + +There are various possibilities for compiling the units that make up the +library: for example with a Makefile (@pxref{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 +@command{gnatmake}, which will ensure that all necessary objects are built. + +After this task is accomplished, you should follow the standard procedure +of the underlying operating system to produce the static or shared library. + +Here is an example of such a dummy program: +@smallexample @c ada +@group +with My_Lib.Service1; +with My_Lib.Service2; +with My_Lib.Service3; +procedure My_Lib_Dummy is +begin + null; +end; +@end group +@end smallexample + +@noindent +Here are the generic commands that will build an archive or a shared library. + +@smallexample +# compiling the library +$ gnatmake -c my_lib_dummy.adb + +# we don't need the dummy object itself +$ rm my_lib_dummy.o my_lib_dummy.ali + +# create an archive with the remaining objects +$ ar rc libmy_lib.a *.o +# some systems may require "ranlib" to be run as well + +# or create a shared library +$ gcc -shared -o libmy_lib.so *.o +# some systems may require the code to have been compiled with -fPIC + +# remove the object files that are now in the library +$ rm *.o + +# Make the ALI files read-only so that gnatmake will not try to +# regenerate the objects that are in the library +$ chmod -w *.ali +@end smallexample + +@noindent +Please note that the library must have a name of the form @file{lib@var{xxx}.a} +or @file{lib@var{xxx}.so} (or @file{lib@var{xxx}.dll} on Windows) in order to +be accessed by the directive @option{-l@var{xxx}} at link time. + +@node Installing a library +@subsection Installing a library +@cindex @code{ADA_PROJECT_PATH} +@cindex @code{GPR_PROJECT_PATH} + +@noindent +If you use project files, library installation is part of the library build +process (@pxref{Installing a library with project files}). + +When project files are not an option, it is also possible, but not recommended, +to install the library so that the sources needed to use the library are on the +Ada source path and the ALI files & libraries be on the Ada Object path (see +@ref{Search Paths and the Run-Time Library (RTL)}. Alternatively, the system +administrator can place general-purpose libraries in the default compiler +paths, by specifying the libraries' location in the configuration files +@file{ada_source_path} and @file{ada_object_path}. These configuration files +must be located in the GNAT installation tree at the same place as the gcc spec +file. The location of the gcc spec file can be determined as follows: +@smallexample +$ gcc -v +@end smallexample + +@noindent +The configuration files mentioned above have a simple format: each line +must contain one unique directory name. +Those names are added to the corresponding path +in their order of appearance in the file. The names can be either absolute +or relative; in the latter case, they are relative to where theses files +are located. + +The files @file{ada_source_path} and @file{ada_object_path} might not be +present in a +GNAT installation, in which case, GNAT will look for its run-time library in +the directories @file{adainclude} (for the sources) and @file{adalib} (for the +objects and @file{ALI} files). When the files exist, the compiler does not +look in @file{adainclude} and @file{adalib}, and thus the +@file{ada_source_path} file +must contain the location for the GNAT run-time sources (which can simply +be @file{adainclude}). In the same way, the @file{ada_object_path} file must +contain the location for the GNAT run-time objects (which can simply +be @file{adalib}). + +You can also specify a new default path to the run-time library at compilation +time with the switch @option{--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 @command{gcc}, @command{gnatmake}, @command{gnatbind}, +@command{gnatls}, @command{gnatfind} and @command{gnatxref}. + +It is possible to install a library before or after the standard GNAT +library, by reordering the lines in the configuration files. In general, a +library must be installed before the GNAT library if it redefines +any part of it. + +@node Using a library +@subsection Using a library + +@noindent Once again, the project facility greatly simplifies the use of +libraries. In this context, using a library is just a matter of adding a +@code{with} clause in the user project. For instance, to make use of the +library @code{My_Lib} shown in examples in earlier sections, you can +write: + +@smallexample @c projectfile +with "my_lib"; +project My_Proj is + @dots{} +end My_Proj; +@end smallexample + +Even if you have a third-party, non-Ada library, you can still use GNAT's +Project Manager facility to provide a wrapper for it. For example, the +following project, when @code{with}ed by your main project, will link with the +third-party library @file{liba.a}: + +@smallexample @c projectfile +@group +project Liba is + for Externally_Built use "true"; + for Source_Files use (); + for Library_Dir use "lib"; + for Library_Name use "a"; + for Library_Kind use "static"; +end Liba; +@end group +@end smallexample +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. + +@noindent +In order to use an Ada library manually, you need to make sure that this +library is on both your source and object path +(see @ref{Search Paths and the Run-Time Library (RTL)} +and @ref{Search Paths for gnatbind}). Furthermore, when the objects are grouped +in an archive or a shared library, you need to specify the desired +library at link time. + +For example, you can use the library @file{mylib} installed in +@file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands: + +@smallexample +$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \ + -largs -lmy_lib +@end smallexample + +@noindent +This can be expressed more simply: +@smallexample +$ gnatmake my_appl +@end smallexample +@noindent +when the following conditions are met: +@itemize @bullet +@item +@file{/dir/my_lib_src} has been added by the user to the environment +variable @env{ADA_INCLUDE_PATH}, or by the administrator to the file +@file{ada_source_path} +@item +@file{/dir/my_lib_obj} has been added by the user to the environment +variable @env{ADA_OBJECTS_PATH}, or by the administrator to the file +@file{ada_object_path} +@item +a pragma @code{Linker_Options} has been added to one of the sources. +For example: + +@smallexample @c ada +pragma Linker_Options ("-lmy_lib"); +@end smallexample +@end itemize + +@node Stand-alone Ada Libraries +@section Stand-alone Ada Libraries +@cindex Stand-alone library, building, using + +@menu +* Introduction to Stand-alone Libraries:: +* Building a Stand-alone Library:: +* Creating a Stand-alone Library to be used in a non-Ada context:: +* Restrictions in Stand-alone Libraries:: +@end menu + +@node Introduction to Stand-alone Libraries +@subsection Introduction to Stand-alone Libraries + +@noindent +A Stand-alone Library (abbreviated ``SAL'') is a library that contains the +necessary code to +elaborate the Ada units that are included in the library. In contrast with +an ordinary library, which consists of all sources, objects and @file{ALI} +files of the +library, a SAL may specify a restricted subset of compilation units +to serve as a library interface. In this case, the fully +self-sufficient set of files will normally consist of an objects +archive, the sources of interface units' specs, and the @file{ALI} +files of interface units. +If an interface spec contains a generic unit or an inlined subprogram, +the body's +source must also be provided; if the units that must be provided in the source +form depend on other units, the source and @file{ALI} files of those must +also be provided. + +The main purpose of a SAL is to minimize the recompilation overhead of client +applications when a new version of the library is installed. Specifically, +if the interface sources have not changed, client applications do not need to +be recompiled. If, furthermore, a SAL is provided in the shared form and its +version, controlled by @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 +text exposed to the clients. Such ``information hiding'' might be useful or +necessary for various reasons. + +Stand-alone libraries are also well suited to be used in an executable whose +main routine is not written in Ada. + +@node Building a Stand-alone Library +@subsection Building a Stand-alone Library + +@noindent +GNAT's Project facility provides a simple way of building and installing +stand-alone libraries; see @ref{Stand-alone Library Projects}. +To be a Stand-alone Library Project, in addition to the two attributes +that make a project a Library Project (@code{Library_Name} and +@code{Library_Dir}; see @ref{Library Projects}), the attribute +@code{Library_Interface} must be defined. For example: + +@smallexample @c projectfile +@group + for Library_Dir use "lib_dir"; + for Library_Name use "dummy"; + for Library_Interface use ("int1", "int1.child"); +@end group +@end smallexample + +@noindent +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. + +When a Stand-alone Library is built, first the binder is invoked to build +a package whose name depends on the library name +(@file{^b~dummy.ads/b^B$DUMMY.ADS/B^} in the example above). +This binder-generated package includes initialization and +finalization procedures whose +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 @code{Library_Auto_Init} set to +@code{"false"}. + +For a Stand-Alone Library, only the @file{ALI} files of the Interface Units +(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. + +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 +the library directory. The sources of the Interface +Units of the library that are needed by an Ada client of the library will be +copied to the designated directory, called the Interface Copy directory. +These sources include the specs of the Interface Units, but they may also +include bodies and subunits, when pragmas @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. + +Building stand-alone libraries by hand is somewhat tedious, but for those +occasions when it is necessary here are the steps that you need to perform: +@itemize @bullet +@item +Compile all library sources. + +@item +Invoke the binder with the switch @option{-n} (No Ada main program), +with all the @file{ALI} files of the interfaces, and +with the switch @option{-L} to give specific names to the @code{init} +and @code{final} procedures. For example: +@smallexample + gnatbind -n int1.ali int2.ali -Lsal1 +@end smallexample + +@item +Compile the binder generated file: +@smallexample + gcc -c b~int2.adb +@end smallexample + +@item +Link the dynamic library with all the necessary object files, +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 @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 @option{SL} on the line in the @file{ALI} file that starts +with letter ``P'') and make the modified copy of the @file{ALI} file +read-only. +@end itemize + +@noindent +Using SALs is not different from using other libraries +(see @ref{Using a library}). + +@node Creating a Stand-alone Library to be used in a non-Ada context +@subsection Creating a Stand-alone Library to be used in a non-Ada context + +@noindent +It is easy to adapt the SAL build procedure discussed above for use of a SAL in +a non-Ada context. + +The only extra step required is to ensure that library interface subprograms +are compatible with the main program, by means of @code{pragma Export} +or @code{pragma Convention}. + +Here is an example of simple library interface for use with C main program: + +@smallexample @c ada +package My_Package is + + procedure Do_Something; + pragma Export (C, Do_Something, "do_something"); + + procedure Do_Something_Else; + pragma Export (C, Do_Something_Else, "do_something_else"); + +end My_Package; +@end smallexample + +@noindent +On the foreign language side, you must provide a ``foreign'' view of the +library interface; remember that it should contain elaboration routines in +addition to interface subprograms. + +The example below shows the content of @code{mylib_interface.h} (note +that there is no rule for the naming of this file, any name can be used) +@smallexample +/* the library elaboration procedure */ +extern void mylibinit (void); + +/* the library finalization procedure */ +extern void mylibfinal (void); + +/* the interface exported by the library */ +extern void do_something (void); +extern void do_something_else (void); +@end smallexample + +@noindent +Libraries built as explained above can be used from any program, provided +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 @code{mylib} library. + +@smallexample +#include "mylib_interface.h" + +int +main (void) +@{ + /* First, elaborate the library before using it */ + mylibinit (); + + /* Main program, using the library exported entities */ + do_something (); + do_something_else (); + + /* Library finalization at the end of the program */ + mylibfinal (); + return 0; +@} +@end smallexample + +@noindent +Note that invoking any library finalization procedure generated by +@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 +after the finalization phase. + +@node Restrictions in Stand-alone Libraries +@subsection Restrictions in Stand-alone Libraries + +@noindent +The pragmas listed below should be used with caution inside libraries, +as they can create incompatibilities with other Ada libraries: +@itemize @bullet +@item pragma @code{Locking_Policy} +@item pragma @code{Queuing_Policy} +@item pragma @code{Task_Dispatching_Policy} +@item pragma @code{Unreserve_All_Interrupts} +@end itemize + +@noindent +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, +@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. + +Similarly, the traceback in the exception occurrence mechanism should be +enabled or disabled in a consistent manner across all libraries. +Otherwise, Program_Error will be raised during the elaboration of the +conflicting libraries. + +If the @code{Version} or @code{Body_Version} +attributes are used inside a library, then you need to +perform a @code{gnatbind} step that specifies all @file{ALI} files in all +libraries, so that version identifiers can be properly computed. +In practice these attributes are rarely used, so this is unlikely +to be a consideration. + +@node Rebuilding the GNAT Run-Time Library +@section Rebuilding the GNAT Run-Time Library +@cindex GNAT Run-Time Library, rebuilding +@cindex Building the GNAT Run-Time Library +@cindex Rebuilding the GNAT Run-Time Library +@cindex Run-Time Library, rebuilding + +@noindent +It may be useful to recompile the GNAT library in various contexts, the +most important one being the use of partition-wide configuration pragmas +such as @code{Normalize_Scalars}. A special Makefile called +@code{Makefile.adalib} is provided to that effect and can be found in +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: + +@smallexample +$ gnatls -v +@end smallexample + +@noindent +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. + +@node Using the GNU make Utility +@chapter Using the GNU @code{make} Utility +@findex make + +@noindent +This chapter offers some examples of makefiles that solve specific +problems. It does not explain how to write a makefile (@pxref{Top,, GNU +make, make, GNU @code{make}}), nor does it try to replace the +@command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}). + +All the examples in this section are specific to the GNU version of +make. Although @command{make} is a standard utility, and the basic language +is the same, these examples use some advanced features found only in +@code{GNU make}. + +@menu +* Using gnatmake in a Makefile:: +* Automatically Creating a List of Directories:: +* Generating the Command Line Switches:: +* Overcoming Command Line Length Limits:: +@end menu + +@node Using gnatmake in a Makefile +@section Using gnatmake in a Makefile +@findex makefile +@cindex GNU make + +@noindent +Complex project organizations can be handled in a very powerful way by +using GNU make combined with gnatmake. For instance, here is a Makefile +which allows you to build each subsystem of a big project into a separate +shared library. Such a makefile allows you to significantly reduce the link +time of very big applications while maintaining full coherence at +each step of the build process. + +The list of dependencies are handled automatically by +@command{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 +(@pxref{Automatically Creating a List of Directories}) +which might help you in case your project has a lot of subdirectories. + +@smallexample +@iftex +@leftskip=0cm +@font@heightrm=cmr8 +@heightrm +@end iftex +## This Makefile is intended to be used with the following directory +## configuration: +## - The sources are split into a series of csc (computer software components) +## Each of these csc is put in its own directory. +## Their name are referenced by the directory names. +## They will be compiled into shared library (although this would also work +## with static libraries +## - The main program (and possibly other packages that do not belong to any +## csc is put in the top level directory (where the Makefile is). +## toplevel_dir __ first_csc (sources) __ lib (will contain the library) +## \_ second_csc (sources) __ lib (will contain the library) +## \_ @dots{} +## Although this Makefile is build for shared library, it is easy to modify +## to build partial link objects instead (modify the lines with -shared and +## gnatlink below) +## +## With this makefile, you can change any file in the system or add any new +## file, and everything will be recompiled correctly (only the relevant shared +## objects will be recompiled, and the main program will be re-linked). + +# The list of computer software component for your project. This might be +# generated automatically. +CSC_LIST=aa bb cc + +# Name of the main program (no extension) +MAIN=main + +# If we need to build objects with -fPIC, uncomment the following line +#NEED_FPIC=-fPIC + +# The following variable should give the directory containing libgnat.so +# You can get this directory through 'gnatls -v'. This is usually the last +# directory in the Object_Path. +GLIB=@dots{} + +# The directories for the libraries +# (This macro expands the list of CSC to the list of shared libraries, you +# could simply use the expanded form: +# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so +LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@} + +$@{MAIN@}: objects $@{LIB_DIR@} + gnatbind $@{MAIN@} $@{CSC_LIST:%=-aO%/lib@} -shared + gnatlink $@{MAIN@} $@{CSC_LIST:%=-l%@} + +objects:: + # recompile the sources + gnatmake -c -i $@{MAIN@}.adb $@{NEED_FPIC@} $@{CSC_LIST:%=-I%@} + +# Note: In a future version of GNAT, the following commands will be simplified +# by a new tool, gnatmlib +$@{LIB_DIR@}: + mkdir -p $@{dir $@@ @} + cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat + cd $@{dir $@@ @} && cp -f ../*.ali . + +# The dependencies for the modules +# Note that we have to force the expansion of *.o, since in some cases +# make won't be able to do it itself. +aa/lib/libaa.so: $@{wildcard aa/*.o@} +bb/lib/libbb.so: $@{wildcard bb/*.o@} +cc/lib/libcc.so: $@{wildcard cc/*.o@} + +# Make sure all of the shared libraries are in the path before starting the +# program +run:: + LD_LIBRARY_PATH=`pwd`/aa/lib:`pwd`/bb/lib:`pwd`/cc/lib ./$@{MAIN@} + +clean:: + $@{RM@} -rf $@{CSC_LIST:%=%/lib@} + $@{RM@} $@{CSC_LIST:%=%/*.ali@} + $@{RM@} $@{CSC_LIST:%=%/*.o@} + $@{RM@} *.o *.ali $@{MAIN@} +@end smallexample + +@node Automatically Creating a List of Directories +@section Automatically Creating a List of Directories + +@noindent +In most makefiles, you will have to specify a list of directories, and +store it in a variable. For small projects, it is often easier to +specify each of them by hand, since you then have full control over what +is the proper order for these directories, which ones should be +included. + +However, in larger projects, which might involve hundreds of +subdirectories, it might be more convenient to generate this list +automatically. + +The example below presents two methods. The first one, although less +general, gives you more control over the list. It involves wildcard +characters, that are automatically expanded by @command{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, @enddots{} + +The second method is the most general one. It requires an external +program, called @command{find}, which is standard on all Unix systems. All +the directories found under a given root directory will be added to the +list. + +@smallexample +@iftex +@leftskip=0cm +@font@heightrm=cmr8 +@heightrm +@end iftex +# The examples below are based on the following directory hierarchy: +# All the directories can contain any number of files +# ROOT_DIRECTORY -> a -> aa -> aaa +# -> ab +# -> ac +# -> b -> ba -> baa +# -> bb +# -> bc +# This Makefile creates a variable called DIRS, that can be reused any time +# you need this list (see the other examples in this section) + +# The root of your project's directory hierarchy +ROOT_DIRECTORY=. + +#### +# First method: specify explicitly the list of directories +# This allows you to specify any subset of all the directories you need. +#### + +DIRS := a/aa/ a/ab/ b/ba/ + +#### +# Second method: use wildcards +# Note that the argument(s) to wildcard below should end with a '/'. +# Since wildcards also return file names, we have to filter them out +# to avoid duplicate directory names. +# We thus use make's @code{dir} and @code{sort} functions. +# It sets DIRs to the following value (note that the directories aaa and baa +# are not given, unless you change the arguments to wildcard). +# DIRS= ./a/a/ ./b/ ./a/aa/ ./a/ab/ ./a/ac/ ./b/ba/ ./b/bb/ ./b/bc/ +#### + +DIRS := $@{sort $@{dir $@{wildcard $@{ROOT_DIRECTORY@}/*/ + $@{ROOT_DIRECTORY@}/*/*/@}@}@} + +#### +# Third method: use an external program +# This command is much faster if run on local disks, avoiding NFS slowdowns. +# This is the most complete command: it sets DIRs to the following value: +# DIRS= ./a ./a/aa ./a/aa/aaa ./a/ab ./a/ac ./b ./b/ba ./b/ba/baa ./b/bb ./b/bc +#### + +DIRS := $@{shell find $@{ROOT_DIRECTORY@} -type d -print@} + +@end smallexample + +@node Generating the Command Line Switches +@section Generating the Command Line Switches + +@noindent +Once you have created the list of directories as explained in the +previous section (@pxref{Automatically Creating a List of Directories}), +you can easily generate the command line arguments to pass to gnatmake. + +For the sake of completeness, this example assumes that the source path +is not the same as the object path, and that you have two separate lists +of directories. + +@smallexample +# see "Automatically creating a list of directories" to create +# these variables +SOURCE_DIRS= +OBJECT_DIRS= + +GNATMAKE_SWITCHES := $@{patsubst %,-aI%,$@{SOURCE_DIRS@}@} +GNATMAKE_SWITCHES += $@{patsubst %,-aO%,$@{OBJECT_DIRS@}@} + +all: + gnatmake $@{GNATMAKE_SWITCHES@} main_unit +@end smallexample + +@node Overcoming Command Line Length Limits +@section Overcoming Command Line Length Limits + +@noindent +One problem that might be encountered on big projects is that many +operating systems limit the length of the command line. It is thus hard to give +gnatmake the list of source and object directories. + +This example shows how you can set up environment variables, which will +make @command{gnatmake} behave exactly as if the directories had been +specified on the command line, but have a much higher length limit (or +even none on most systems). + +It assumes that you have created a list of directories in your Makefile, +using one of the methods presented in +@ref{Automatically Creating a List of Directories}. +For the sake of completeness, we assume that the object +path (where the ALI files are found) is different from the sources patch. + +Note a small trick in the Makefile below: for efficiency reasons, we +create two temporary variables (SOURCE_LIST and OBJECT_LIST), that are +expanded immediately by @code{make}. This way we overcome the standard +make behavior which is to expand the variables only when they are +actually used. + +On Windows, if you are using the standard Windows command shell, you must +replace colons with semicolons in the assignments to these variables. + +@smallexample +@iftex +@leftskip=0cm +@font@heightrm=cmr8 +@heightrm +@end iftex +# In this example, we create both ADA_INCLUDE_PATH and ADA_OBJECT_PATH. +# This is the same thing as putting the -I arguments on the command line. +# (the equivalent of using -aI on the command line would be to define +# only ADA_INCLUDE_PATH, the equivalent of -aO is ADA_OBJECT_PATH). +# You can of course have different values for these variables. +# +# Note also that we need to keep the previous values of these variables, since +# they might have been set before running 'make' to specify where the GNAT +# library is installed. + +# see "Automatically creating a list of directories" to create these +# variables +SOURCE_DIRS= +OBJECT_DIRS= + +empty:= +space:=$@{empty@} $@{empty@} +SOURCE_LIST := $@{subst $@{space@},:,$@{SOURCE_DIRS@}@} +OBJECT_LIST := $@{subst $@{space@},:,$@{OBJECT_DIRS@}@} +ADA_INCLUDE_PATH += $@{SOURCE_LIST@} +ADA_OBJECT_PATH += $@{OBJECT_LIST@} +export ADA_INCLUDE_PATH +export ADA_OBJECT_PATH + +all: + gnatmake main_unit +@end smallexample +@end ifclear + +@node Memory Management Issues +@chapter Memory Management Issues + +@noindent +This chapter 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''). +@ifclear vms +It also describes the @command{gnatmem} tool, which can be used to track down +``memory leaks''. +@end ifclear + +@menu +* Some Useful Memory Pools:: +* The GNAT Debug Pool Facility:: +@ifclear vms +* The gnatmem Tool:: +@end ifclear +@end menu + +@node Some Useful Memory Pools +@section Some Useful Memory Pools +@findex Memory Pool +@cindex storage, pool + +@noindent +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: +@smallexample @c ada + type T1 is access Something; + -- no Storage pool is defined for T2 + type T2 is access Something_Else; + for T2'Storage_Pool use T1'Storage_Pool; + -- the above is equivalent to + for T2'Storage_Pool use System.Pool_Global.Global_Pool_Object; +@end smallexample + +@noindent +The @code{System.Pool_Local} package offers the Unbounded_Reclaim_Pool storage +pool. The allocation strategy is similar to @code{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: + +@smallexample @c ada +with System.Pool_Local; +procedure Pooloc1 is + procedure Internal is + type A is access Integer; + X : System.Pool_Local.Unbounded_Reclaim_Pool; + for A'Storage_Pool use X; + v : A; + begin + for I in 1 .. 50 loop + v := new Integer; + end loop; + end Internal; +begin + for I in 1 .. 100 loop + Internal; + end loop; +end Pooloc1; +@end smallexample + +@noindent +The @code{System.Pool_Size} package implements the 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: + +@smallexample @c ada + type T1 is access Something; + for T1'Storage_Size use 10_000; +@end smallexample + +@node The GNAT Debug Pool Facility +@section The GNAT Debug Pool Facility +@findex Debug Pool +@cindex storage, pool, memory corruption + +@noindent +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}. + +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. +@smallexample @c ada +type Ptr is access Some_Type; +Pool : GNAT.Debug_Pools.Debug_Pool; +for Ptr'Storage_Pool use Pool; +@end smallexample + +@noindent +@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. + +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 @bullet +@item +@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage} +@item +@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage} +@item +@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage} +@item +@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage } +@end itemize + +@noindent +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#}. + +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 +@code{Debug_Pools}, that includes typical instances of memory corruption: +@smallexample @c ada +@iftex +@leftskip=0cm +@end iftex +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 smallexample + +@noindent +The debug pool mechanism provides the following precise diagnostics on the +execution of this erroneous program: +@smallexample +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 smallexample + +@ifclear vms +@node The gnatmem Tool +@section The @command{gnatmem} Tool +@findex gnatmem + +@noindent +The @code{gnatmem} utility monitors dynamic allocation and +deallocation activity in a program, and displays information about +incorrect deallocations and possible sources of memory leaks. +It is designed to work in association with a static runtime library +only and in this context provides three types of information: +@itemize @bullet +@item +General information concerning memory management, such as the total +number of allocations and deallocations, the amount of allocated +memory and the high water mark, i.e.@: the largest amount of allocated +memory in the course of program execution. + +@item +Backtraces for all incorrect deallocations, that is to say deallocations +which do not correspond to a valid allocation. + +@item +Information on each allocation that is potentially the origin of a memory +leak. +@end itemize + +@menu +* Running gnatmem:: +* Switches for gnatmem:: +* Example of gnatmem Usage:: +@end menu + +@node Running gnatmem +@subsection Running @code{gnatmem} + +@noindent +@code{gnatmem} makes use of the output created by the special version of +allocation and deallocation routines that record call information. This +allows to obtain accurate dynamic memory usage history at a minimal cost to +the execution speed. Note however, that @code{gnatmem} is not supported on +all platforms (currently, it is supported on AIX, HP-UX, GNU/Linux, +Solaris and Windows NT/2000/XP (x86). + +@noindent +The @code{gnatmem} command has the form + +@smallexample +@c $ gnatmem @ovar{switches} user_program +@c Expanding @ovar macro inline (explanation in macro def comments) + $ gnatmem @r{[}@var{switches}@r{]} @var{user_program} +@end smallexample + +@noindent +The program must have been linked with the instrumented version of the +allocation and deallocation routines. This is done by linking with the +@file{libgmem.a} library. For correct symbolic backtrace information, +the user program should be compiled with debugging options +(see @ref{Switches for gcc}). For example to build @file{my_program}: + +@smallexample +$ gnatmake -g my_program -largs -lgmem +@end smallexample + +@noindent +As library @file{libgmem.a} contains an alternate body for package +@code{System.Memory}, @file{s-memory.adb} should not be compiled and linked +when an executable is linked with library @file{libgmem.a}. It is then not +recommended to use @command{gnatmake} with switch @option{^-a^/ALL_FILES^}. + +@noindent +When @file{my_program} is executed, the file @file{gmem.out} is produced. +This file contains information about all allocations and deallocations +performed by the program. It is produced by the instrumented allocations and +deallocations routines and will be used by @code{gnatmem}. + +In order to produce symbolic backtrace information for allocations and +deallocations performed by the GNAT run-time library, you need to use a +version of that library that has been compiled with the @option{-g} switch +(see @ref{Rebuilding the GNAT Run-Time Library}). + +Gnatmem must be supplied with the @file{gmem.out} file and the executable to +examine. If the location of @file{gmem.out} file was not explicitly supplied by +@option{-i} switch, gnatmem will assume that this file can be found in the +current directory. For example, after you have executed @file{my_program}, +@file{gmem.out} can be analyzed by @code{gnatmem} using the command: + +@smallexample +$ gnatmem my_program +@end smallexample + +@noindent +This will produce the output with the following format: + +*************** debut cc +@smallexample +$ gnatmem my_program + +Global information +------------------ + Total number of allocations : 45 + Total number of deallocations : 6 + Final Water Mark (non freed mem) : 11.29 Kilobytes + High Water Mark : 11.40 Kilobytes + +. +. +. +Allocation Root # 2 +------------------- + Number of non freed allocations : 11 + Final Water Mark (non freed mem) : 1.16 Kilobytes + High Water Mark : 1.27 Kilobytes + Backtrace : + my_program.adb:23 my_program.alloc +. +. +. +@end smallexample + +The first block of output gives general information. In this case, the +Ada construct ``@code{@b{new}}'' was executed 45 times, and only 6 calls to an +Unchecked_Deallocation routine occurred. + +@noindent +Subsequent paragraphs display information on all allocation roots. +An allocation root is a specific point in the execution of the program +that generates some dynamic allocation, such as a ``@code{@b{new}}'' +construct. This root is represented by an execution backtrace (or subprogram +call stack). By default the backtrace depth for allocations roots is 1, so +that a root corresponds exactly to a source location. The backtrace can +be made deeper, to make the root more specific. + +@node Switches for gnatmem +@subsection Switches for @code{gnatmem} + +@noindent +@code{gnatmem} recognizes the following switches: + +@table @option + +@item -q +@cindex @option{-q} (@code{gnatmem}) +Quiet. Gives the minimum output needed to identify the origin of the +memory leaks. Omits statistical information. + +@item @var{N} +@cindex @var{N} (@code{gnatmem}) +N is an integer literal (usually between 1 and 10) which controls the +depth of the backtraces defining allocation root. The default value for +N is 1. The deeper the backtrace, the more precise the localization of +the root. Note that the total number of roots can depend on this +parameter. This parameter must be specified @emph{before} the name of the +executable to be analyzed, to avoid ambiguity. + +@item -b n +@cindex @option{-b} (@code{gnatmem}) +This switch has the same effect as just depth parameter. + +@item -i @var{file} +@cindex @option{-i} (@code{gnatmem}) +Do the @code{gnatmem} processing starting from @file{file}, rather than +@file{gmem.out} in the current directory. + +@item -m n +@cindex @option{-m} (@code{gnatmem}) +This switch causes @code{gnatmem} to mask the allocation roots that have less +than n leaks. The default value is 1. Specifying the value of 0 will allow to +examine even the roots that didn't result in leaks. + +@item -s order +@cindex @option{-s} (@code{gnatmem}) +This switch causes @code{gnatmem} to sort the allocation roots according to the +specified order of sort criteria, each identified by a single letter. The +currently supported criteria are @code{n, h, w} standing respectively for +number of unfreed allocations, high watermark, and final watermark +corresponding to a specific root. The default order is @code{nwh}. + +@end table + +@node Example of gnatmem Usage +@subsection Example of @code{gnatmem} Usage + +@noindent +The following example shows the use of @code{gnatmem} +on a simple memory-leaking program. +Suppose that we have the following Ada program: + +@smallexample @c ada +@group +@cartouche +with Unchecked_Deallocation; +procedure Test_Gm is + + type T is array (1..1000) of Integer; + type Ptr is access T; + procedure Free is new Unchecked_Deallocation (T, Ptr); + A : Ptr; + + procedure My_Alloc is + begin + A := new T; + end My_Alloc; + + procedure My_DeAlloc is + B : Ptr := A; + begin + Free (B); + end My_DeAlloc; + +begin + My_Alloc; + for I in 1 .. 5 loop + for J in I .. 5 loop + My_Alloc; + end loop; + My_Dealloc; + end loop; +end; +@end cartouche +@end group +@end smallexample + +@noindent +The program needs to be compiled with debugging option and linked with +@code{gmem} library: + +@smallexample +$ gnatmake -g test_gm -largs -lgmem +@end smallexample + +@noindent +Then we execute the program as usual: + +@smallexample +$ test_gm +@end smallexample + +@noindent +Then @code{gnatmem} is invoked simply with +@smallexample +$ gnatmem test_gm +@end smallexample + +@noindent +which produces the following output (result may vary on different platforms): + +@smallexample +Global information +------------------ + Total number of allocations : 18 + Total number of deallocations : 5 + Final Water Mark (non freed mem) : 53.00 Kilobytes + High Water Mark : 56.90 Kilobytes + +Allocation Root # 1 +------------------- + Number of non freed allocations : 11 + Final Water Mark (non freed mem) : 42.97 Kilobytes + High Water Mark : 46.88 Kilobytes + Backtrace : + test_gm.adb:11 test_gm.my_alloc + +Allocation Root # 2 +------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 10.02 Kilobytes + High Water Mark : 10.02 Kilobytes + Backtrace : + s-secsta.adb:81 system.secondary_stack.ss_init + +Allocation Root # 3 +------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 12 Bytes + High Water Mark : 12 Bytes + Backtrace : + s-secsta.adb:181 system.secondary_stack.ss_init +@end smallexample + +@noindent +Note that the GNAT run time contains itself a certain number of +allocations that have no corresponding deallocation, +as shown here for root #2 and root +#3. This is a normal behavior when the number of non-freed allocations +is one, it allocates dynamic data structures that the run time needs for +the complete lifetime of the program. Note also that there is only one +allocation root in the user program with a single line back trace: +test_gm.adb:11 test_gm.my_alloc, whereas a careful analysis of the +program shows that 'My_Alloc' is called at 2 different points in the +source (line 21 and line 24). If those two allocation roots need to be +distinguished, the backtrace depth parameter can be used: + +@smallexample +$ gnatmem 3 test_gm +@end smallexample + +@noindent +which will give the following output: + +@smallexample +Global information +------------------ + Total number of allocations : 18 + Total number of deallocations : 5 + Final Water Mark (non freed mem) : 53.00 Kilobytes + High Water Mark : 56.90 Kilobytes + +Allocation Root # 1 +------------------- + Number of non freed allocations : 10 + Final Water Mark (non freed mem) : 39.06 Kilobytes + High Water Mark : 42.97 Kilobytes + Backtrace : + test_gm.adb:11 test_gm.my_alloc + test_gm.adb:24 test_gm + b_test_gm.c:52 main + +Allocation Root # 2 +------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 10.02 Kilobytes + High Water Mark : 10.02 Kilobytes + Backtrace : + s-secsta.adb:81 system.secondary_stack.ss_init + s-secsta.adb:283 + b_test_gm.c:33 adainit + +Allocation Root # 3 +------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 3.91 Kilobytes + High Water Mark : 3.91 Kilobytes + Backtrace : + test_gm.adb:11 test_gm.my_alloc + test_gm.adb:21 test_gm + b_test_gm.c:52 main + +Allocation Root # 4 +------------------- + Number of non freed allocations : 1 + Final Water Mark (non freed mem) : 12 Bytes + High Water Mark : 12 Bytes + Backtrace : + s-secsta.adb:181 system.secondary_stack.ss_init + s-secsta.adb:283 + b_test_gm.c:33 adainit +@end smallexample + +@noindent +The allocation root #1 of the first example has been split in 2 roots #1 +and #3 thanks to the more precise associated backtrace. + +@end ifclear + +@node Stack Related Facilities +@chapter Stack Related Facilities + +@noindent +This chapter 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 +@section Stack Overflow Checking +@cindex Stack Overflow Checking +@cindex -fstack-check + +@noindent +For most operating systems, @command{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 +@option{-fstack-check}. For example: + +@smallexample +gcc -c -fstack-check package1.adb +@end smallexample + +@noindent +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. + +For declared tasks, the stack size is controlled by the size +given in an applicable @code{Storage_Size} pragma or by the value specified +at bind time with @option{-d} (@pxref{Switches for gnatbind}) or is set to +the default size as defined in the GNAT runtime otherwise. + +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. +@ifclear vms +To ensure that a clean exception is signalled for stack +overflow, set the environment variable +@env{GNAT_STACK_LIMIT} to indicate the maximum +stack area that can be used, as in: +@cindex GNAT_STACK_LIMIT + +@smallexample +SET GNAT_STACK_LIMIT 1600 +@end smallexample + +@noindent +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. +@end ifclear +@ifset vms +To have a fixed size stack in the environment task, the stack must be put +in the P0 address space and its size specified. Use these switches to +create a p0 image: + +@smallexample +gnatmake my_progs -largs "-Wl,--opt=STACK=4000,/p0image" +@end smallexample + +@noindent +The quotes are required to keep case. The number after @samp{STACK=} is the +size of the environmental task stack in pagelets (512 bytes). In this example +the stack size is about 2 megabytes. + +@noindent +A consequence of the @option{/p0image} qualifier is also to makes RMS buffers +be placed in P0 space. Refer to @cite{HP OpenVMS Linker Utility Manual} for +more details about the @option{/p0image} qualifier and the @option{stack} +option. +@end ifset + +@node Static Stack Usage Analysis +@section Static Stack Usage Analysis +@cindex Static Stack Usage Analysis +@cindex -fstack-usage + +@noindent +A unit compiled with @option{-fstack-usage} will generate an extra file +that specifies +the maximum amount of stack used, on a per-function basis. +The file has the same +basename as the target object file with a @file{.su} extension. +Each line of this file is made up of three fields: + +@itemize +@item +The name of the function. +@item +A number of bytes. +@item +One or more qualifiers: @code{static}, @code{dynamic}, @code{bounded}. +@end itemize + +The second field corresponds to the size of the known part of the function +frame. + +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. + +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. + +@node Dynamic Stack Usage Analysis +@section Dynamic Stack Usage Analysis + +@noindent +It is possible to measure the maximum amount of stack used by a task, by +adding a switch to @command{gnatbind}, as: + +@smallexample +$ gnatbind -u0 file +@end smallexample + +@noindent +With this option, at each task termination, its stack usage is output on +@file{stderr}. +It is not always convenient to output the stack usage when the program +is still running. Hence, it is possible to delay this output until program +termination. for a given number of tasks specified as the argument of the +@option{-u} option. For instance: + +@smallexample +$ gnatbind -u100 file +@end smallexample + +@noindent +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: + +@noindent +Index | Task Name | Stack Size | Stack Usage [Value +/- Variation] + +@noindent +where: + +@table @emph +@item Index +is a number associated with each task. + +@item Task Name +is the name of the task analyzed. + +@item Stack Size +is the maximum size for the stack. + +@item Stack Usage +is the measure done by the stack analyzer. In order to prevent overflow, the stack +is not entirely analyzed, and it's not possible to know exactly how +much has actually been used. The report thus contains the theoretical stack usage +(Value) and the possible variation (Variation) around this value. + +@end table + +@noindent +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. + + +@c ********************************* +@c * GNATCHECK * +@c ********************************* +@node Verifying Properties Using gnatcheck +@chapter Verifying Properties Using @command{gnatcheck} +@findex gnatcheck +@cindex @command{gnatcheck} + +@noindent +The @command{gnatcheck} tool is an ASIS-based utility that checks properties +of Ada source files according to a given set of semantic rules. +@cindex ASIS + +In order to check compliance with a given rule, @command{gnatcheck} has to +semantically analyze the Ada sources. +Therefore, checks can only be performed on +legal Ada units. Moreover, when a unit depends semantically upon units located +outside the current directory, the source search path has to be provided when +calling @command{gnatcheck}, either through a specified project file or +through @command{gnatcheck} switches. + +A number of rules are predefined in @command{gnatcheck} and are described +later in this chapter. + +For full details, refer to @cite{GNATcheck Reference Manual} document. + + +@c ********************************* +@node Creating Sample Bodies Using gnatstub +@chapter Creating Sample Bodies Using @command{gnatstub} +@findex gnatstub + +@noindent +@command{gnatstub} creates body stubs, that is, empty but compilable bodies +for library unit declarations. + +Note: to invoke @code{gnatstub} with a project file, use the @code{gnat} +driver (see @ref{The GNAT Driver and Project Files}). + +To create a body stub, @command{gnatstub} has to compile the library +unit declaration. Therefore, bodies can be created only for legal +library units. Moreover, if a library unit depends semantically upon +units located outside the current directory, you have to provide +the source search path when calling @command{gnatstub}, see the description +of @command{gnatstub} switches below. + +By default, all the program unit body stubs generated by @code{gnatstub} +raise the predefined @code{Program_Error} exception, which will catch +accidental calls of generated stubs. This behavior can be changed with +option @option{^--no-exception^/NO_EXCEPTION^} (see below). + +@menu +* Running gnatstub:: +* Switches for gnatstub:: +@end menu + +@node Running gnatstub +@section Running @command{gnatstub} + +@noindent +@command{gnatstub} has the command-line interface of the form + +@smallexample +@c $ gnatstub @ovar{switches} @var{filename} @ovar{directory} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatstub @r{[}@var{switches}@r{]} @var{filename} @r{[}@var{directory}@r{]} @r{[}-cargs @var{gcc_switches}@r{]} +@end smallexample + +@noindent +where +@table @var +@item filename +is the name of the source file that contains a library unit declaration +for which a body must be created. The file name may contain the path +information. +The file name does not have to follow the GNAT file name conventions. If the +name +does not follow GNAT file naming conventions, the name of the body file must +be provided +explicitly as the value of the @option{^-o^/BODY=^@var{body-name}} option. +If the file name follows the GNAT file naming +conventions and the name of the body file is not provided, +@command{gnatstub} +creates the name +of the body file from the argument file name by replacing the @file{.ads} +suffix +with the @file{.adb} suffix. + +@item directory +indicates the directory in which the body stub is to be placed (the default +is the +current directory) + +@item @samp{@var{gcc_switches}} is a list of switches for +@command{gcc}. They will be passed on to all compiler invocations made by +@command{gnatelim} to generate the ASIS trees. Here you can provide +@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path, +use the @option{-gnatec} switch to set the configuration file, +use the @option{-gnat05} switch if sources should be compiled in +Ada 2005 mode etc. + +@item switches +is an optional sequence of switches as described in the next section +@end table + +@node Switches for gnatstub +@section Switches for @command{gnatstub} + +@table @option +@c !sort! + +@item ^-f^/FULL^ +@cindex @option{^-f^/FULL^} (@command{gnatstub}) +If the destination directory already contains a file with the name of the +body file +for the argument spec file, replace it with the generated body stub. + +@item ^-hs^/HEADER=SPEC^ +@cindex @option{^-hs^/HEADER=SPEC^} (@command{gnatstub}) +Put the comment header (i.e., all the comments preceding the +compilation unit) from the source of the library unit declaration +into the body stub. + +@item ^-hg^/HEADER=GENERAL^ +@cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub}) +Put a sample comment header into the body stub. + +@item ^--header-file=@var{filename}^/FROM_HEADER_FILE=@var{filename}^ +@cindex @option{^--header-file^/FROM_HEADER_FILE=^} (@command{gnatstub}) +Use the content of the file as the comment header for a generated body stub. + +@ifclear vms +@item -IDIR +@cindex @option{-IDIR} (@command{gnatstub}) +@itemx -I- +@cindex @option{-I-} (@command{gnatstub}) +@end ifclear +@ifset vms +@item /NOCURRENT_DIRECTORY +@cindex @option{/NOCURRENT_DIRECTORY} (@command{gnatstub}) +@end ifset +^These switches have ^This switch has^ the same meaning as in calls to +@command{gcc}. +^They define ^It defines ^ the source search path in the call to +@command{gcc} issued +by @command{gnatstub} to compile an argument source file. + +@item ^-gnatec^/CONFIGURATION_PRAGMAS_FILE=^@var{PATH} +@cindex @option{^-gnatec^/CONFIGURATION_PRAGMAS_FILE^} (@command{gnatstub}) +This switch has the same meaning as in calls to @command{gcc}. +It defines the additional configuration file to be passed to the call to +@command{gcc} issued +by @command{gnatstub} to compile an argument source file. + +@item ^-gnatyM^/MAX_LINE_LENGTH=^@var{n} +@cindex @option{^-gnatyM^/MAX_LINE_LENGTH^} (@command{gnatstub}) +(@var{n} is a non-negative integer). Set the maximum line length in the +body stub to @var{n}; the default is 79. The maximum value that can be +specified is 32767. Note that in the special case of configuration +pragma files, the maximum is always 32767 regardless of whether or +not this switch appears. + +@item ^-gnaty^/STYLE_CHECKS=^@var{n} +@cindex @option{^-gnaty^/STYLE_CHECKS=^} (@command{gnatstub}) +(@var{n} is a non-negative integer from 1 to 9). Set the indentation level in +the generated body sample to @var{n}. +The default indentation is 3. + +@item ^-gnatyo^/ORDERED_SUBPROGRAMS^ +@cindex @option{^-gnato^/ORDERED_SUBPROGRAMS^} (@command{gnatstub}) +Order local bodies alphabetically. (By default local bodies are ordered +in the same way as the corresponding local specs in the argument spec file.) + +@item ^-i^/INDENTATION=^@var{n} +@cindex @option{^-i^/INDENTATION^} (@command{gnatstub}) +Same as @option{^-gnaty^/STYLE_CHECKS=^@var{n}} + +@item ^-k^/TREE_FILE=SAVE^ +@cindex @option{^-k^/TREE_FILE=SAVE^} (@command{gnatstub}) +Do not remove the tree file (i.e., the snapshot of the compiler internal +structures used by @command{gnatstub}) after creating the body stub. + +@item ^-l^/LINE_LENGTH=^@var{n} +@cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub}) +Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}} + +@item ^--no-exception^/NO_EXCEPTION^ +@cindex @option{^--no-exception^/NO_EXCEPTION^} (@command{gnatstub}) +void raising PROGRAM_ERROR in the generated bodies of program unit stubs. +This is not always possible for function stubs. + +@item ^--no-local-header^/NO_LOCAL_HEADER^ +@cindex @option{^--no-local-header^/NO_LOCAL_HEADER^} (@command{gnatstub}) +Do not place local comment header with unit name before body stub for a +unit. + +@item ^-o ^/BODY=^@var{body-name} +@cindex @option{^-o^/BODY^} (@command{gnatstub}) +Body file name. This should be set if the argument file name does not +follow +the GNAT file naming +conventions. If this switch is omitted the default name for the body will be +obtained +from the argument file name according to the GNAT file naming conventions. + +@item ^-q^/QUIET^ +@cindex @option{^-q^/QUIET^} (@command{gnatstub}) +Quiet mode: do not generate a confirmation when a body is +successfully created, and do not generate a message when a body is not +required for an +argument unit. + +@item ^-r^/TREE_FILE=REUSE^ +@cindex @option{^-r^/TREE_FILE=REUSE^} (@command{gnatstub}) +Reuse the tree file (if it exists) instead of creating it. Instead of +creating the tree file for the library unit declaration, @command{gnatstub} +tries to find it in the current directory and use it for creating +a body. If the tree file is not found, no body is created. This option +also implies @option{^-k^/SAVE^}, whether or not +the latter is set explicitly. + +@item ^-t^/TREE_FILE=OVERWRITE^ +@cindex @option{^-t^/TREE_FILE=OVERWRITE^} (@command{gnatstub}) +Overwrite the existing tree file. If the current directory already +contains the file which, according to the GNAT file naming rules should +be considered as a tree file for the argument source file, +@command{gnatstub} +will refuse to create the tree file needed to create a sample body +unless this option is set. + +@item ^-v^/VERBOSE^ +@cindex @option{^-v^/VERBOSE^} (@command{gnatstub}) +Verbose mode: generate version information. + +@end table + +@c ********************************* +@node Generating Ada Bindings for C and C++ headers +@chapter Generating Ada Bindings for C and C++ headers +@findex binding + +@noindent +GNAT now comes with a binding generator for C and C++ headers which is +intended to do 95% of the tedious work of generating Ada specs from C +or C++ header files. + +Note that this capability is not intended to generate 100% correct Ada specs, +and will is some cases require manual adjustments, although it can often +be used out of the box in practice. + +Some of the known limitations include: + +@itemize @bullet +@item only very simple character constant macros are translated into Ada +constants. Function macros (macros with arguments) are partially translated +as comments, to be completed manually if needed. +@item some extensions (e.g. vector types) are not supported +@item pointers to pointers or complex structures are mapped to System.Address +@item identifiers with identical name (except casing) will generate compilation + 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. + +@menu +* Running the binding generator:: +* Generating bindings for C++ headers:: +* Switches:: +@end menu + +@node Running the binding generator +@section Running the binding generator + +@noindent +The binding generator is part of the @command{gcc} compiler and can be +invoked via the @option{-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: + +@smallexample +$ g++ -c -fdump-ada-spec -C /usr/include/time.h +$ gcc -c -gnat05 *.ads +@end smallexample + +will generate, under GNU/Linux, the following files: @file{time_h.ads}, +@file{bits_time_h.ads}, @file{stddef_h.ads}, @file{bits_types_h.ads} which +correspond to the files @file{/usr/include/time.h}, +@file{/usr/include/bits/time.h}, etc@dots{}, and will then compile in Ada 2005 +mode these Ada specs. + +The @code{-C} switch tells @command{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 @option{-fdump-ada-spec-slim} switch. + +Note that we recommend when possible to use the @command{g++} driver to +generate bindings, even for most C headers, since this will in general +generate better Ada specs. For generating bindings for C++ headers, it is +mandatory to use the @command{g++} command, or @command{gcc -x c++} which +is equivalent in this case. If @command{g++} cannot work on your C headers +because of incompatibilities between C and C++, then you can fallback to +@command{gcc} instead. + +For an example of better bindings generated from the C++ front-end, +the name of the parameters (when available) are actually ignored by the C +front-end. Consider the following C header: + +@smallexample +extern void foo (int variable); +@end smallexample + +with the C front-end, @code{variable} is ignored, and the above is handled as: + +@smallexample +extern void foo (int); +@end smallexample + +generating a generic: + +@smallexample +procedure foo (param1 : int); +@end smallexample + +with the C++ front-end, the name is available, and we generate: + +@smallexample +procedure foo (variable : int); +@end smallexample + +In some cases, the generated bindings will be more complete or more meaningful +when defining some macros, which you can do via the @option{-D} switch. This +is for example the case with @file{Xlib.h} under GNU/Linux: + +@smallexample +g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h +@end smallexample + +The above will generate more complete bindings than a straight call without +the @option{-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 +@code{#include} and possible @code{#define} directives. For example, to +generate Ada bindings for @file{readline/readline.h}, you need to first +include @file{stdio.h}, so you can create a file with the following two +lines in e.g. @file{readline1.h}: + +@smallexample +#include +#include +@end smallexample + +and then generate Ada bindings from this file: + +@smallexample +$ g++ -c -fdump-ada-spec readline1.h +@end smallexample + +@node Generating bindings for C++ headers +@section Generating bindings for C++ headers + +@noindent +Generating bindings for C++ headers is done using the same options, always +with the @command{g++} compiler. + +In this mode, C++ classes will be mapped to Ada tagged types, constructors +will be mapped using the @code{CPP_Constructor} pragma, and when possible, +multiple inheritance of abstract classes will be mapped to Ada interfaces +(@xref{Interfacing to C++,,,gnat_rm, GNAT Reference Manual}, for additional +information on interfacing to C++). + +For example, given the following C++ header file: + +@smallexample +@group +@cartouche +class Carnivore @{ +public: + virtual int Number_Of_Teeth () = 0; +@}; + +class Domestic @{ +public: + virtual void Set_Owner (char* Name) = 0; +@}; + +class Animal @{ +public: + int Age_Count; + virtual void Set_Age (int New_Age); +@}; + +class Dog : Animal, Carnivore, Domestic @{ + public: + int Tooth_Count; + char *Owner; + + virtual int Number_Of_Teeth (); + virtual void Set_Owner (char* Name); + + Dog(); +@}; +@end cartouche +@end group +@end smallexample + +The corresponding Ada code is generated: + +@smallexample @c ada +@group +@cartouche + package Class_Carnivore is + type Carnivore is limited interface; + pragma Import (CPP, Carnivore); + + function Number_Of_Teeth (this : access Carnivore) return int is abstract; + end; + use Class_Carnivore; + + package Class_Domestic is + type Domestic is limited interface; + pragma Import (CPP, Domestic); + + procedure Set_Owner + (this : access Domestic; + Name : Interfaces.C.Strings.chars_ptr) is abstract; + end; + use Class_Domestic; + + package Class_Animal is + type Animal is tagged limited record + Age_Count : aliased int; + end record; + pragma Import (CPP, Animal); + + procedure Set_Age (this : access Animal; New_Age : int); + pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi"); + end; + use Class_Animal; + + package Class_Dog is + type Dog is new Animal and Carnivore and Domestic with record + Tooth_Count : aliased int; + Owner : Interfaces.C.Strings.chars_ptr; + end record; + pragma Import (CPP, Dog); + + function Number_Of_Teeth (this : access Dog) return int; + pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv"); + + procedure Set_Owner + (this : access Dog; Name : Interfaces.C.Strings.chars_ptr); + pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc"); + + function New_Dog return Dog; + pragma CPP_Constructor (New_Dog); + pragma Import (CPP, New_Dog, "_ZN3DogC1Ev"); + end; + use Class_Dog; +@end cartouche +@end group +@end smallexample + +@node Switches +@section Switches + +@table @option +@item -fdump-ada-spec +@cindex @option{-fdump-ada-spec} (@command{gcc}) +Generate Ada spec files for the given header files transitively (including +all header files that these headers depend upon). + +@item -fdump-ada-spec-slim +@cindex @option{-fdump-ada-spec-slim} (@command{gcc}) +Generate Ada spec files for the header files specified on the command line +only. + +@item -C +@cindex @option{-C} (@command{gcc}) +Extract comments from headers and generate Ada comments in the Ada spec files. +@end table + +@node Other Utility Programs +@chapter Other Utility Programs + +@noindent +This chapter discusses some other utility programs available in the Ada +environment. + +@menu +* Using Other Utility Programs with GNAT:: +* The External Symbol Naming Scheme of GNAT:: +* Converting Ada Files to html with gnathtml:: +* Installing gnathtml:: +@ifset vms +* LSE:: +* Profiling:: +@end ifset +@end menu + +@node Using Other Utility Programs with GNAT +@section Using Other Utility Programs with GNAT + +@noindent +The object files generated by GNAT are in standard system format and in +particular the debugging information uses this format. This means +programs generated by GNAT can be used with existing utilities that +depend on these formats. + +@ifclear vms +In general, any utility program that works with C will also often work with +Ada programs generated by GNAT. This includes software utilities such as +gprof (a profiling program), @code{gdb} (the FSF debugger), and utilities such +as Purify. +@end ifclear + +@node The External Symbol Naming Scheme of GNAT +@section The External Symbol Naming Scheme of GNAT + +@noindent +In order to interpret the output from GNAT, when using tools that are +originally intended for use with other languages, it is useful to +understand the conventions used to generate link names from the Ada +entity names. + +All link names are in all lowercase letters. With the exception of library +procedure names, the mechanism used is simply to use the full expanded +Ada name with dots replaced by double underscores. For example, suppose +we have the following package spec: + +@smallexample @c ada +@group +@cartouche +package QRS is + MN : Integer; +end QRS; +@end cartouche +@end group +@end smallexample + +@noindent +The variable @code{MN} has a full expanded Ada name of @code{QRS.MN}, so +the corresponding link name is @code{qrs__mn}. +@findex Export +Of course if a @code{pragma Export} is used this may be overridden: + +@smallexample @c ada +@group +@cartouche +package Exports is + Var1 : Integer; + pragma Export (Var1, C, External_Name => "var1_name"); + Var2 : Integer; + pragma Export (Var2, C, Link_Name => "var2_link_name"); +end Exports; +@end cartouche +@end group +@end smallexample + +@noindent +In this case, the link name for @var{Var1} is whatever link name the +C compiler would assign for the C function @var{var1_name}. This typically +would be either @var{var1_name} or @var{_var1_name}, depending on operating +system conventions, but other possibilities exist. The link name for +@var{Var2} is @var{var2_link_name}, and this is not operating system +dependent. + +@findex _main +One exception occurs for library level procedures. A potential ambiguity +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 @code{Main} (which might well not be the main program). + +To avoid this ambiguity, we attach the prefix @code{_ada_} to such +names. So if we have a library level procedure such as + +@smallexample @c ada +@group +@cartouche +procedure Hello (S : String); +@end cartouche +@end group +@end smallexample + +@noindent +the external name of this procedure will be @var{_ada_hello}. + + +@node Converting Ada Files to html with gnathtml +@section Converting Ada Files to HTML with @code{gnathtml} + +@noindent +This @code{Perl} script allows Ada source files to be browsed using +standard Web browsers. For installation procedure, see the section +@xref{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 @option{-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. + +The command line is as follow: +@smallexample +@c $ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ perl gnathtml.pl @r{[}@var{^switches^options^}@r{]} @var{ada-files} +@end smallexample + +@noindent +You can pass it as many Ada files as you want. @code{gnathtml} will generate +an html file for every ada file, and a global file called @file{index.htm}. +This file is an index of every identifier defined in the files. + +The available ^switches^options^ are the following ones: + +@table @option +@item -83 +@cindex @option{-83} (@code{gnathtml}) +Only the Ada 83 subset of keywords will be highlighted. + +@item -cc @var{color} +@cindex @option{-cc} (@code{gnathtml}) +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. + +@item -d +@cindex @option{-d} (@code{gnathtml}) +If the Ada files depend on some other files (for instance through +@code{with} clauses, the latter files will also be converted to html. +Only the files in the user project will be converted to html, not the files +in the run-time library itself. + +@item -D +@cindex @option{-D} (@code{gnathtml}) +This command is the same as @option{-d} above, but @command{gnathtml} will +also look for files in the run-time library, and generate html files for them. + +@item -ext @var{extension} +@cindex @option{-ext} (@code{gnathtml}) +This option allows you to change the extension of the generated HTML files. +If you do not specify an extension, it will default to @file{htm}. + +@item -f +@cindex @option{-f} (@code{gnathtml}) +By default, gnathtml will generate html links only for global entities +('with'ed units, global variables and types,@dots{}). If you specify +@option{-f} on the command line, then links will be generated for local +entities too. + +@item -l @var{number} +@cindex @option{-l} (@code{gnathtml}) +If this ^switch^option^ is provided and @var{number} is not 0, then +@code{gnathtml} will number the html files every @var{number} line. + +@item -I @var{dir} +@cindex @option{-I} (@code{gnathtml}) +Specify a directory to search for library files (@file{.ALI} files) and +source files. You can provide several -I switches on the command line, +and the directories will be parsed in the order of the command line. + +@item -o @var{dir} +@cindex @option{-o} (@code{gnathtml}) +Specify the output directory for html files. By default, gnathtml will +saved the generated html files in a subdirectory named @file{html/}. + +@item -p @var{file} +@cindex @option{-p} (@code{gnathtml}) +If you are using Emacs and the most recent Emacs Ada mode, which provides +a full Integrated Development Environment for compiling, checking, +running and debugging applications, you may use @file{.gpr} files +to give the directories where Emacs can find sources and object files. + +Using this ^switch^option^, 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. + +@item -sc @var{color} +@cindex @option{-sc} (@code{gnathtml}) +This ^switch^option^ 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. + +@item -t @var{file} +@cindex @option{-t} (@code{gnathtml}) +This ^switch^option^ provides the name of a file. This file contains a list of +file names to be converted, and the effect is exactly as though they had +appeared explicitly on the command line. This +is the recommended way to work around the command line length limit on some +systems. + +@end table + +@node Installing gnathtml +@section Installing @code{gnathtml} + +@noindent +@code{Perl} needs to be installed on your machine to run this script. +@code{Perl} is freely available for almost every architecture and +Operating System via the Internet. + +On Unix systems, you may want to modify the first line of the script +@code{gnathtml}, to explicitly tell the Operating system where Perl +is. The syntax of this line is: +@smallexample +#!full_path_name_to_perl +@end smallexample + +@noindent +Alternatively, you may run the script using the following command line: + +@smallexample +@c $ perl gnathtml.pl @ovar{switches} @var{files} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ perl gnathtml.pl @r{[}@var{switches}@r{]} @var{files} +@end smallexample + +@ifset vms +@node LSE +@section LSE +@findex LSE + +@noindent +The GNAT distribution provides an Ada 95 template for the HP Language +Sensitive Editor (LSE), a component of DECset. In order to +access it, invoke LSE with the qualifier /ENVIRONMENT=GNU:[LIB]ADA95.ENV. + +@node Profiling +@section Profiling +@findex PCA + +@noindent +GNAT supports The HP Performance Coverage Analyzer (PCA), a component +of DECset. To use it proceed as outlined under ``HELP PCA'', except for running +the collection phase with the /DEBUG qualifier. + +@smallexample +$ GNAT MAKE /DEBUG +$ DEFINE LIB$DEBUG PCA$COLLECTOR +$ RUN/DEBUG +@end smallexample +@noindent +@end ifset + +@ifclear vms +@c ****************************** +@node Code Coverage and Profiling +@chapter Code Coverage and Profiling +@cindex Code Coverage +@cindex Profiling + +@noindent +This chapter describes how to use @code{gcov} - coverage testing tool - and +@code{gprof} - profiler tool - on your Ada programs. + +@menu +* Code Coverage of Ada Programs using gcov:: +* Profiling an Ada Program using gprof:: +@end menu + +@node Code Coverage of Ada Programs using gcov +@section Code Coverage of Ada Programs using gcov +@cindex gcov +@cindex -fprofile-arcs +@cindex -ftest-coverage +@cindex -coverage +@cindex Code Coverage + +@noindent +@code{gcov} is a test coverage program: it analyzes the execution of a given +program on selected tests, to help you determine the portions of the program +that are still untested. + +@code{gcov} is part of the GCC suite, and is described in detail in the GCC +User's Guide. You can refer to this documentation for a more complete +description. + +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 +@subsection Quick startup guide + +In order to perform coverage analysis of a program using @code{gcov}, 3 +steps are needed: + +@itemize @bullet +@item +Code instrumentation during the compilation process +@item +Execution of the instrumented program +@item +Execution of the @code{gcov} tool to generate the result. +@end itemize + +The code instrumentation needed by gcov is created at the object level: +The source code is not modified in any way, because the instrumentation code is +inserted by gcc during the compilation process. To compile your code with code +coverage activated, you need to recompile your whole project using the +switches +@code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using +@code{-fprofile-arcs}. + +@smallexample +$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \ + -largs -fprofile-arcs +@end smallexample + +This compilation process will create @file{.gcno} files together with +the usual object files. + +Once the program is compiled with coverage instrumentation, you can +run it as many times as needed - on portions of a test suite for +example. The first execution will produce @file{.gcda} files at the +same location as the @file{.gcno} files. The following executions +will update those files, so that a cumulative result of the covered +portions of the program is generated. + +Finally, you need to call the @code{gcov} tool. The different options of +@code{gcov} are available in the GCC User's Guide, section 'Invoking gcov'. + +This will create annotated source files with a @file{.gcov} extension: +@file{my_main.adb} file will be analysed in @file{my_main.adb.gcov}. + +@node Gnat specifics +@subsection Gnat specifics + +Because Ada semantics, portions of the source code may be shared among +several object files. This is the case for example when generics are +involved, when inlining is active or when declarations generate initialisation +calls. In order to take +into account this shared code, you need to call @code{gcov} on all +source files of the tested program at once. + +The list of source files might exceed the system's maximum command line +length. In order to bypass this limitation, a new mechanism has been +implemented in @code{gcov}: you can now list all your project's files into a +text file, and provide this file to gcov as a parameter, preceded by a @@ +(e.g. @samp{gcov @@mysrclist.txt}). + +Note that on AIX compiling a static library with @code{-fprofile-arcs} is +not supported as there can be unresolved symbols during the final link. + +@node Profiling an Ada Program using gprof +@section Profiling an Ada Program using gprof +@cindex gprof +@cindex -pg +@cindex Profiling + +@noindent +This section is not meant to be an exhaustive documentation of @code{gprof}. +Full documentation for it can be found in the 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. + +@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 +@itemize @bullet +@item +linux x86/x86_64 +@item +solaris sparc/sparc64/x86 +@item +windows x86 +@end itemize + +@noindent +In order to profile a program using @code{gprof}, 3 steps are needed: + +@itemize @bullet +@item +Code instrumentation, requiring a full recompilation of the project with the +proper switches. +@item +Execution of the program under the analysis conditions, i.e. with the desired +input. +@item +Analysis of the results using the @code{gprof} tool. +@end itemize + +@noindent +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 +@subsection Compilation for profiling +@cindex -pg +@cindex 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: + +@smallexample +gnatmake -f -pg -P my_project +@end smallexample + +@noindent +Note that only the objects that were compiled with the @samp{-pg} switch will +be profiled; if you need to profile your whole project, use the @samp{-f} +gnatmake switch to force full recompilation. + +@node Program execution +@subsection Program execution + +@noindent +Once the program has been compiled for profiling, you can run it as usual. + +The only constraint imposed by profiling is that the program must terminate +normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be +properly analyzed. + +Once the program completes execution, a data file called @file{gmon.out} is +generated in the directory where the program was launched from. If this file +already exists, it will be overwritten. + +@node Running gprof +@subsection Running gprof + +@noindent +The @code{gprof} tool is called as follow: + +@smallexample +gprof my_prog gmon.out +@end smallexample + +@noindent +or simpler: + +@smallexample +gprof my_prog +@end smallexample + +@noindent +The complete form of the gprof command line is the following: + +@smallexample +gprof [^switches^options^] [executable [data-file]] +@end smallexample + +@noindent +@code{gprof} supports numerous ^switch^options^. The order of these +^switch^options^ 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: + +@table @option + +@item --demangle[=@var{style}] +@itemx --no-demangle +@cindex @option{--demangle} (@code{gprof}) +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}. + +@item -e @var{function_name} +@cindex @option{-e} (@code{gprof}) +The @samp{-e @var{function}} option tells @code{gprof} not to print +information about the function @var{function_name} (and its +children@dots{}) 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 @samp{[not printed]}. More than one @samp{-e} option may be +given; only one @var{function_name} may be indicated with each @samp{-e} +option. + +@item -E @var{function_name} +@cindex @option{-E} (@code{gprof}) +The @code{-E @var{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 @samp{-E} option may be given; only one +@var{function_name} may be indicated with each @samp{-E} option. + +@item -f @var{function_name} +@cindex @option{-f} (@code{gprof}) +The @samp{-f @var{function}} option causes @code{gprof} to limit the +call graph to the function @var{function_name} and its children (and +their children@dots{}). More than one @samp{-f} option may be given; +only one @var{function_name} may be indicated with each @samp{-f} +option. + +@item -F @var{function_name} +@cindex @option{-F} (@code{gprof}) +The @samp{-F @var{function}} option works like the @code{-f} option, but +only time spent in the function and its children (and their +children@dots{}) will be used to determine total-time and +percentages-of-time for the call graph. More than one @samp{-F} option +may be given; only one @var{function_name} may be indicated with each +@samp{-F} option. The @samp{-F} option overrides the @samp{-E} option. + +@end table + +@node Interpretation of profiling results +@subsection Interpretation of profiling results + +@noindent + +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. +@end ifclear + +@c ****************************** +@node Running and Debugging Ada Programs +@chapter Running and Debugging Ada Programs +@cindex Debugging + +@noindent +This chapter discusses how to debug Ada programs. +@ifset vms +It applies to GNAT on the Alpha OpenVMS platform; +for I64 OpenVMS please refer to the @cite{OpenVMS Debugger Manual}, +since HP has implemented Ada support in the OpenVMS debugger on I64. +@end ifset + +An incorrect Ada program may be handled in three ways by the GNAT compiler: + +@enumerate +@item +The illegality may be a violation of the static semantics of Ada. In +that case GNAT diagnoses the constructs in the program that are illegal. +It is then a straightforward matter for the user to modify those parts of +the program. + +@item +The illegality may be a violation of the dynamic semantics of Ada. In +that case the program compiles and executes, but may generate incorrect +results, or may terminate abnormally with some exception. + +@item +When presented with a program that contains convoluted errors, GNAT +itself may terminate abnormally without providing full diagnostics on +the incorrect user program. +@end enumerate + +@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:: +* Ada Exceptions:: +* Ada Tasks:: +* Debugging Generic Units:: +* Remote Debugging using gdbserver:: +* GNAT Abnormal Termination or Failure to Terminate:: +* Naming Conventions for GNAT Source Files:: +* Getting Internal Debugging Information:: +* Stack Traceback:: +@end menu + +@cindex Debugger +@findex gdb + +@node The GNAT Debugger GDB +@section The GNAT Debugger GDB + +@noindent +@code{GDB} is a general purpose, platform-independent debugger that +can be used to debug mixed-language programs compiled with @command{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. + +@xref{Top,, Debugging with GDB, gdb, Debugging with GDB}, +@ifset vms +located in the GNU:[DOCS] directory, +@end ifset +for full details on the usage of @code{GDB}, including a section on +its usage on programs. This manual should be consulted for full +details. The section that follows is a brief introduction to the +philosophy and use of @code{GDB}. + +When GNAT programs are compiled, the compiler optionally writes debugging +information into the generated object file, including information on +line numbers, and on declared types and variables. This information is +separate from the generated code. It makes the object files considerably +larger, but it does not add to the size of the actual executable that +will be loaded into memory, and has no impact on run-time performance. The +generation of debug information is triggered by the use of the +^-g^/DEBUG^ switch in the @command{gcc} or @command{gnatmake} command +used to carry out the compilations. It is important to emphasize that +the use of these options does not change the generated code. + +The debugging information is written in standard system formats that +are used by many tools, including debuggers and profilers. The format +of the information is typically designed to describe C types and +semantics, but GNAT implements a translation scheme which allows full +details about Ada types and variables to be encoded into these +standard C formats. Details of this encoding scheme may be found in +the file exp_dbug.ads in the GNAT source distribution. However, the +details of this encoding are, in general, of no interest to a user, +since @code{GDB} automatically performs the necessary decoding. + +When a program is bound and linked, the debugging information is +collected from the object files, and stored in the executable image of +the program. Again, this process significantly increases the size of +the generated executable file, but it does not increase the size of +the executable program itself. Furthermore, if this program is run in +the normal manner, it runs exactly as if the debug information were +not present, and takes no more actual memory. + +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. + +@c ************** +@node Running GDB +@section Running GDB + +@noindent +This section describes how to initiate the debugger. +@c The above sentence is really just filler, but it was otherwise +@c clumsy to get the first paragraph nonindented given the conditional +@c nature of the description + +@ifclear vms +The debugger can be launched from a @code{GPS} menu or +directly from the command line. The description below covers the latter use. +All the commands shown can be used in the @code{GPS} debug console window, +but there are usually more GUI-based ways to achieve the same effect. +@end ifclear + +The command to run @code{GDB} is + +@smallexample +$ ^gdb program^GDB PROGRAM^ +@end smallexample + +@noindent +where @code{^program^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}. + +@c ******************************* +@node Introduction to GDB Commands +@section Introduction to GDB Commands + +@noindent +@code{GDB} contains a large repertoire of commands. @xref{Top,, +Debugging with GDB, gdb, Debugging with GDB}, +@ifset vms +located in the GNU:[DOCS] directory, +@end ifset +for extensive documentation on the use +of these commands, together with examples of their use. Furthermore, +the command @command{help} invoked from within GDB activates a simple help +facility which summarizes the available commands and their options. +In this section we summarize a few of the most commonly +used commands to give an idea of what @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. + +@table @code +@item set args @var{arguments} +The @var{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. + +@item run +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. + +@item breakpoint @var{location} +The breakpoint command sets a breakpoint, that is to say a point at which +execution will halt and @code{GDB} will await further +commands. @var{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. + +@item catch exception @var{name} +This command causes the program execution to stop whenever exception +@var{name} is raised. If @var{name} is omitted, then the execution is +suspended when any exception is raised. + +@item print @var{expression} +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. + +@item continue +Continues execution following a breakpoint, until the next breakpoint or the +termination of the program. + +@item step +Executes a single line after a breakpoint. If the next statement +is a subprogram call, execution continues into (the first statement of) +the called subprogram. + +@item next +Executes a single line. If this line is a subprogram call, executes and +returns from the call. + +@item 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. + +@item 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. + +@item 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. + +@item down +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), + +@item frame @var{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 + +@noindent +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 @ref{Top,, Debugging with GDB, gdb, +Debugging with GDB}. Note that most commands can be abbreviated +(for example, c for continue, bt for backtrace). + +@node Using Ada Expressions +@section Using Ada Expressions +@cindex Ada expressions + +@noindent +@code{GDB} supports a fairly large subset of Ada expression syntax, with some +extensions. The philosophy behind the design of this subset is + +@itemize @bullet +@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}). + +@item +That type safety and strict adherence to Ada language restrictions +are not particularly important to the @code{GDB} user. + +@item +That brevity is important to the @code{GDB} user. +@end itemize + +@noindent +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. + +For details on the supported Ada syntax, see @ref{Top,, Debugging with +GDB, gdb, Debugging with GDB}. + +@node Calling User-Defined Subprograms +@section Calling User-Defined Subprograms + +@noindent +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: + +@smallexample +call subprogram-name (parameters) +@end smallexample + +@noindent +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). + +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. + +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. + +@node Using the Next Command in a Function +@section Using the Next Command in a Function + +@noindent +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 ``epilog'' of the function. +This is the code that returns to the caller. There is only one copy of +this epilog 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 epilog is associated with the first statement +of the function. + +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. + +@node Ada Exceptions +@section Stopping when Ada Exceptions are Raised +@cindex Exceptions + +@noindent +You can set catchpoints that stop the program execution when your program +raises selected exceptions. + +@table @code +@item catch exception +Set a catchpoint that stops execution whenever (any task in the) program +raises any exception. + +@item catch exception @var{name} +Set a catchpoint that stops execution whenever (any task in the) program +raises the exception @var{name}. + +@item catch exception unhandled +Set a catchpoint that stops executing whenever (any task in the) program +raises an exception for which there is no handler. + +@item info exceptions +@itemx info exceptions @var{regexp} +The @code{info exceptions} command permits the user to examine all defined +exceptions within Ada programs. With a regular expression, @var{regexp}, as +argument, prints out only those exceptions whose name matches @var{regexp}. +@end table + +@node Ada Tasks +@section Ada Tasks +@cindex Tasks + +@noindent +@code{GDB} allows the following task-related commands: + +@table @code +@item info tasks +This command shows a list of current Ada tasks, as in the following example: + +@smallexample +@iftex +@leftskip=0cm +@end iftex +(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 smallexample + +@noindent +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. + +@item break @var{linespec} task @var{taskid} +@itemx break @var{linespec} task @var{taskid} if @dots{} +@cindex Breakpoints and tasks +These commands are like the @code{break @dots{} thread @dots{}}. +@var{linespec} specifies source lines. + +Use the qualifier @samp{task @var{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. @var{taskid} is one of the +numeric task identifiers assigned by @code{GDB}, shown in the first +column of the @samp{info tasks} display. + +If you do not specify @samp{task @var{taskid}} when you set a +breakpoint, the breakpoint applies to @emph{all} tasks of your +program. + +You can use the @code{task} qualifier on conditional breakpoints as +well; in this case, place @samp{task @var{taskid}} before the +breakpoint condition (before the @code{if}). + +@item task @var{taskno} +@cindex Task switching + +This command allows to switch to the task referred by @var{taskno}. In +particular, This allows to browse the backtrace of the specified +task. It is advised to switch back to the original task before +continuing execution otherwise the scheduling of the program may be +perturbed. +@end table + +@noindent +For more detailed information on the tasking support, +see @ref{Top,, Debugging with GDB, gdb, Debugging with GDB}. + +@node Debugging Generic Units +@section Debugging Generic Units +@cindex Debugging Generic Units +@cindex Generics + +@noindent +GNAT always uses code expansion for generic instantiation. This means that +each time an instantiation occurs, a complete copy of the original code is +made, with appropriate substitutions of formals by actuals. + +It is not possible to refer to the original generic entities in +@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 + +@smallexample @c ada +@group +@cartouche +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; +@end cartouche +@end group +@end smallexample + +@noindent +Then to break on a call to procedure kp in the k2 instance, simply +use the command: + +@smallexample +(gdb) break g.k2.kp +@end smallexample + +@noindent +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 Remote Debugging using gdbserver +@section Remote Debugging using gdbserver +@cindex Remote Debugging using gdbserver + +@noindent +On platforms where gdbserver is supported, it is possible to use this tool +to debug your application remotely. This can be useful in situations +where the program needs to be run on a target host that is different +from the host used for development, particularly when the target has +a limited amount of resources (either CPU and/or memory). + +To do so, start your program using gdbserver on the target machine. +gdbserver then automatically suspends the execution of your program +at its entry point, waiting for a debugger to connect to it. The +following commands starts an application and tells gdbserver to +wait for a connection with the debugger on localhost port 4444. + +@smallexample +$ gdbserver localhost:4444 program +Process program created; pid = 5685 +Listening on port 4444 +@end smallexample + +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. + +@smallexample +$ 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 smallexample + +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, @ref{Top, Server, Using +the gdbserver Program, gdb, Debugging with GDB}. GNAT Pro provides support +for gdbserver on x86-linux, x86-windows and x86_64-linux. + +@node GNAT Abnormal Termination or Failure to Terminate +@section GNAT Abnormal Termination or Failure to Terminate +@cindex GNAT Abnormal Termination or Failure to Terminate + +@noindent +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. + +@enumerate +@item +Run @command{gcc} with the @option{-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 @option{-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 @command{gcc} with the @option{^-v (verbose)^/VERBOSE^} switch. In this +mode, @command{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. + +@item +@cindex @option{-gnatdc} switch +Run @command{gcc} with the @option{-gnatdc} switch. This is a GNAT specific +switch that does for the front-end what @option{^-v^VERBOSE^} 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. +@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 @command{gcc}). You can use @code{gdb} on @code{gnat1} as you +would on a C program (but @pxref{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 @command{gcc} backend, indicates the source line at +which the execution stopped, and @code{input_file name} indicates the name of +the source file. +@end enumerate + +@node Naming Conventions for GNAT Source Files +@section Naming Conventions for GNAT Source Files + +@noindent +In order to examine the workings of the GNAT system, the following +brief description of its organization may be helpful: + +@itemize @bullet +@item +Files with prefix @file{^sc^SC^} contain the lexical scanner. + +@item +All files prefixed with @file{^par^PAR^} are components of the parser. The +numbers correspond to chapters of the Ada Reference Manual. For example, +parsing of select statements can be found in @file{par-ch9.adb}. + +@item +All files prefixed with @file{^sem^SEM^} perform semantic analysis. The +numbers correspond to chapters of the Ada standard. For example, all +issues involving context clauses can be found in @file{sem_ch10.adb}. In +addition, some features of the language require sufficient special processing +to justify their own semantic files: sem_aggr for aggregates, sem_disp for +dynamic dispatching, etc. + +@item +All files prefixed with @file{^exp^EXP^} perform normalization and +expansion of the intermediate representation (abstract syntax tree, or AST). +these files use the same numbering scheme as the parser and semantics files. +For example, the construction of record initialization procedures is done in +@file{exp_ch3.adb}. + +@item +The files prefixed with @file{^bind^BIND^} implement the binder, which +verifies the consistency of the compilation, determines an order of +elaboration, and generates the bind file. + +@item +The files @file{atree.ads} and @file{atree.adb} detail the low-level +data structures used by the front-end. + +@item +The files @file{sinfo.ads} and @file{sinfo.adb} detail the structure of +the abstract syntax tree as produced by the parser. + +@item +The files @file{einfo.ads} and @file{einfo.adb} detail the attributes of +all entities, computed during semantic analysis. + +@item +Library management issues are dealt with in files with prefix +@file{^lib^LIB^}. + +@item +@findex Ada +@cindex Annex A +Ada files with the prefix @file{^a-^A-^} are children of @code{Ada}, as +defined in Annex A. + +@item +@findex Interfaces +@cindex Annex B +Files with prefix @file{^i-^I-^} are children of @code{Interfaces}, as +defined in Annex B. + +@item +@findex System +Files with prefix @file{^s-^S-^} are children of @code{System}. This includes +both language-defined children and GNAT run-time routines. + +@item +@findex GNAT +Files with prefix @file{^g-^G-^} are children of @code{GNAT}. These are useful +general-purpose packages, fully documented in their specs. All +the other @file{.c} files are modifications of common @command{gcc} files. +@end itemize + +@node Getting Internal Debugging Information +@section Getting Internal Debugging Information + +@noindent +Most compilers have internal debugging switches and modes. GNAT +does also, except GNAT internal debugging switches and modes are not +secret. A summary and full description of all the compiler and binder +debug flags are in the file @file{debug.adb}. You must obtain the +sources of the compiler to see the full detailed effects of these flags. + +The switches that print the source of the program (reconstructed from +the internal tree) are of general interest for user programs, as are the +options to print +the full internal tree, and the entity table (the symbol table +information). The reconstructed source provides a readable version of the +program after the front-end has completed analysis and expansion, +and is useful when studying the performance of specific constructs. +For example, constraint checks are indicated, complex aggregates +are replaced with loops and assignments, and tasking primitives +are replaced with run-time calls. + +@node Stack Traceback +@section Stack Traceback +@cindex traceback +@cindex stack traceback +@cindex stack unwinding + +@noindent +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 @i{stack unwinding} because it obtains +its information by scanning the run-time stack and recovering the activation +records of all active subprograms. Stack unwinding is one of the most +important tools for program debugging. + +The first entry stored in traceback corresponds to the deepest calling level, +that is to say the subprogram currently executing the instruction +from which we want to obtain the traceback. + +Note that there is no runtime performance penalty when stack traceback +is enabled, and no exception is raised during program execution. + +@menu +* Non-Symbolic Traceback:: +* Symbolic Traceback:: +@end menu + +@node Non-Symbolic Traceback +@subsection Non-Symbolic Traceback +@cindex traceback, non-symbolic + +@noindent +Note: this feature is not supported on all platforms. See +@file{GNAT.Traceback spec in g-traceb.ads} for a complete list of supported +platforms. + +@menu +* Tracebacks From an Unhandled Exception:: +* Tracebacks From Exception Occurrences (non-symbolic):: +* Tracebacks From Anywhere in a Program (non-symbolic):: +@end menu + +@node Tracebacks From an Unhandled Exception +@subsubsection Tracebacks From an Unhandled Exception + +@noindent +A runtime non-symbolic traceback is a list of addresses of call instructions. +To enable this feature you must use the @option{-E} +@code{gnatbind}'s option. With this option a stack traceback is stored as part +of exception information. You can retrieve this information using the +@code{addr2line} tool. + +Here is a simple example: + +@smallexample @c ada +@cartouche +procedure STB is + + procedure P1 is + begin + raise Constraint_Error; + end P1; + + procedure P2 is + begin + P1; + end P2; + +begin + P2; +end STB; +@end cartouche +@end smallexample + +@smallexample +$ gnatmake stb -bargs -E +$ stb + +Execution terminated by unhandled exception +Exception name: CONSTRAINT_ERROR +Message: stb.adb:5 +Call stack traceback locations: +0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 +@end smallexample + +@noindent +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. + +@smallexample +$ gnatmake -g stb -bargs -E +$ stb + +Execution terminated by unhandled exception +Exception name: CONSTRAINT_ERROR +Message: stb.adb:5 +Call stack traceback locations: +0x401373 0x40138b 0x40139c 0x401335 0x4011c4 0x4011f1 0x77e892a4 + +$ addr2line --exe=stb 0x401373 0x40138b 0x40139c 0x401335 0x4011c4 + 0x4011f1 0x77e892a4 + +00401373 at d:/stb/stb.adb:5 +0040138B at d:/stb/stb.adb:10 +0040139C at d:/stb/stb.adb:14 +00401335 at d:/stb/b~stb.adb:104 +004011C4 at /build/@dots{}/crt1.c:200 +004011F1 at /build/@dots{}/crt1.c:222 +77E892A4 in ?? at ??:0 +@end smallexample + +@noindent +The @code{addr2line} tool has several other useful options: + +@table @code +@item --functions +to get the function name corresponding to any location + +@item --demangle=gnat +to use the gnat decoding mode for the function names. Note that +for binutils version 2.9.x the option is simply @option{--demangle}. +@end table + +@smallexample +$ 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/@dots{}/crt1.c:200 +004011F1 in at /build/@dots{}/crt1.c:222 +@end smallexample + +@noindent +From this traceback we can see that the exception was raised in +@file{stb.adb} at line 5, which was reached from a procedure call in +@file{stb.adb} at line 10, and so on. The @file{b~std.adb} is the binder file, +which contains the call to the main program. +@xref{Running gnatbind}. The remaining entries are assorted runtime routines, +and the output will vary from platform to platform. + +It is also possible to use @code{GDB} with these traceback addresses to debug +the program. For example, we can break at a given code location, as reported +in the stack traceback: + +@smallexample +$ gdb -nw stb +@ifclear vms +@noindent +Furthermore, this feature is not implemented inside Windows DLL. Only +the non-symbolic traceback is reported in this case. +@end ifclear + +(gdb) break *0x401373 +Breakpoint 1 at 0x401373: file stb.adb, line 5. +@end smallexample + +@noindent +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. + +@node Tracebacks From Exception Occurrences (non-symbolic) +@subsubsection Tracebacks From Exception Occurrences + +@noindent +Non-symbolic tracebacks are obtained by using the @option{-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: + +@smallexample @c ada +with Ada.Text_IO; +with Ada.Exceptions; + +procedure STB is + + use Ada; + use Ada.Exceptions; + + procedure P1 is + K : Positive := 1; + begin + K := K - 1; + exception + when E : others => + Text_IO.Put_Line (Exception_Information (E)); + end P1; + + procedure P2 is + begin + P1; + end P2; + +begin + P2; +end STB; +@end smallexample + +@noindent +This program will output: + +@smallexample +$ stb + +Exception name: CONSTRAINT_ERROR +Message: stb.adb:12 +Call stack traceback locations: +0x4015e4 0x401633 0x401644 0x401461 0x4011c4 0x4011f1 0x77e892a4 +@end smallexample + +@node Tracebacks From Anywhere in a Program (non-symbolic) +@subsubsection Tracebacks From Anywhere in a Program + +@noindent +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 +@option{-E gnatbind} option in this case, because the stack traceback mechanism +is invoked explicitly. + +@noindent +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: + +@smallexample @c ada +with Ada.Text_IO; +with GNAT.Traceback; +with GNAT.Debug_Utilities; + +procedure STB is + + use Ada; + use GNAT; + use GNAT.Traceback; + + procedure P1 is + TB : Tracebacks_Array (1 .. 10); + -- We are asking for a maximum of 10 stack frames. + Len : Natural; + -- Len will receive the actual number of stack frames returned. + begin + Call_Chain (TB, Len); + + Text_IO.Put ("In STB.P1 : "); + + for K in 1 .. Len loop + Text_IO.Put (Debug_Utilities.Image (TB (K))); + Text_IO.Put (' '); + end loop; + + Text_IO.New_Line; + end P1; + + procedure P2 is + begin + P1; + end P2; + +begin + P2; +end STB; +@end smallexample + +@smallexample +$ gnatmake -g stb +$ stb + +In STB.P1 : 16#0040_F1E4# 16#0040_14F2# 16#0040_170B# 16#0040_171C# +16#0040_1461# 16#0040_11C4# 16#0040_11F1# 16#77E8_92A4# +@end smallexample + +@noindent +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''). + +@node Symbolic Traceback +@subsection Symbolic Traceback +@cindex traceback, symbolic + +@noindent +A symbolic traceback is a stack traceback in which procedure names are +associated with each code location. + +@noindent +Note that this feature is not supported on all platforms. See +@file{GNAT.Traceback.Symbolic spec in g-trasym.ads} for a complete +list of currently supported platforms. + +@noindent +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. + +@menu +* Tracebacks From Exception Occurrences (symbolic):: +* Tracebacks From Anywhere in a Program (symbolic):: +@end menu + +@node Tracebacks From Exception Occurrences (symbolic) +@subsubsection Tracebacks From Exception Occurrences + +@smallexample @c ada +with Ada.Text_IO; +with GNAT.Traceback.Symbolic; + +procedure STB is + + procedure P1 is + begin + raise Constraint_Error; + end P1; + + procedure P2 is + begin + P1; + end P2; + + procedure P3 is + begin + P2; + end P3; + +begin + P3; +exception + when E : others => + Ada.Text_IO.Put_Line (GNAT.Traceback.Symbolic.Symbolic_Traceback (E)); +end STB; +@end smallexample + +@smallexample +$ gnatmake -g .\stb -bargs -E -largs -lgnat -laddr2line -lintl +$ 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 smallexample + +@noindent +In the above example the ``.\'' syntax in the @command{gnatmake} command +is currently required by @command{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 @option{-largs} section is for Windows platforms. By contrast, +under Unix there is no need for the @option{-largs} section. +Differences across platforms are due to details of linker implementation. + +@node Tracebacks From Anywhere in a Program (symbolic) +@subsubsection Tracebacks From Anywhere in a Program + +@noindent +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: + +@smallexample @c ada +with Ada.Text_IO; +with GNAT.Traceback; +with GNAT.Traceback.Symbolic; + +procedure STB is + + use Ada; + use GNAT.Traceback; + use GNAT.Traceback.Symbolic; + + procedure P1 is + TB : Tracebacks_Array (1 .. 10); + -- We are asking for a maximum of 10 stack frames. + Len : Natural; + -- Len will receive the actual number of stack frames returned. + begin + Call_Chain (TB, Len); + Text_IO.Put_Line (Symbolic_Traceback (TB (1 .. Len))); + end P1; + + procedure P2 is + begin + P1; + end P2; + +begin + P2; +end STB; +@end smallexample + +@c ****************************** +@ifset vms +@node Compatibility with HP Ada +@chapter Compatibility with HP Ada +@cindex Compatibility + +@noindent +@cindex DEC Ada +@cindex HP Ada +@cindex Compatibility between GNAT and HP Ada +This chapter compares HP Ada (formerly known as ``DEC Ada'') +for OpenVMS Alpha and GNAT for OpenVMS for Alpha and for I64. +GNAT is highly compatible +with HP Ada, and it should generally be straightforward to port code +from the HP Ada environment to GNAT. However, there are a few language +and implementation differences of which the user must be aware. These +differences are discussed in this chapter. In +addition, the operating environment and command structure for the +compiler are different, and these differences are also discussed. + +For further details on these and other compatibility issues, +see Appendix E of the HP publication +@cite{HP Ada, Technical Overview and Comparison on HP Platforms}. + +Except where otherwise indicated, the description of GNAT for OpenVMS +applies to both the Alpha and I64 platforms. + +For information on porting Ada code from GNAT on Alpha OpenVMS to GNAT on +I64 OpenVMS, see @ref{Transitioning to 64-Bit GNAT for OpenVMS}. + +The discussion in this chapter addresses specifically the implementation +of Ada 83 for HP OpenVMS Alpha Systems. In cases where the implementation +of HP Ada differs between OpenVMS Alpha Systems and OpenVMS VAX Systems, +GNAT always follows the Alpha implementation. + +For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and +attributes are recognized, although only a subset of them can sensibly +be implemented. The description of pragmas in +@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}, +indicates whether or not they are applicable to non-VMS systems. + +@menu +* Ada Language Compatibility:: +* Differences in the Definition of Package System:: +* Language-Related Features:: +* The Package STANDARD:: +* The Package SYSTEM:: +* Tasking and Task-Related Features:: +* Pragmas and Pragma-Related Features:: +* Library of Predefined Units:: +* Bindings:: +* Main Program Definition:: +* Implementation-Defined Attributes:: +* Compiler and Run-Time Interfacing:: +* Program Compilation and Library Management:: +* Input-Output:: +* Implementation Limits:: +* Tools and Utilities:: +@end menu + +@node Ada Language Compatibility +@section Ada Language Compatibility + +@noindent +GNAT handles Ada 95 and Ada 2005 as well as Ada 83, whereas HP Ada is only +for Ada 83. Ada 95 and Ada 2005 are almost completely upwards compatible +with Ada 83, and therefore Ada 83 programs will compile +and run under GNAT with +no changes or only minor changes. The @cite{Annotated Ada Reference Manual} +provides details on specific incompatibilities. + +GNAT provides the switch @option{/83} on the @command{GNAT COMPILE} command, +as well as the pragma @code{ADA_83}, to force the compiler to +operate in Ada 83 mode. This mode does not guarantee complete +conformance to Ada 83, but in practice is sufficient to +eliminate most sources of incompatibilities. +In particular, it eliminates the recognition of the +additional Ada 95 and Ada 2005 keywords, so that their use as identifiers +in Ada 83 programs is legal, and handles the cases of packages +with optional bodies, and generics that instantiate unconstrained +types without the use of @code{(<>)}. + +@node Differences in the Definition of Package System +@section Differences in the Definition of Package @code{System} + +@noindent +An Ada compiler is allowed to add +implementation-dependent declarations to package @code{System}. +In normal mode, +GNAT does not take advantage of this permission, and the version of +@code{System} provided by GNAT exactly matches that defined in the Ada +Reference Manual. + +However, HP Ada adds an extensive set of declarations to package +@code{System}, +as fully documented in the HP Ada manuals. To minimize changes required +for programs that make use of these extensions, GNAT provides the pragma +@code{Extend_System} for extending the definition of package System. By using: +@cindex pragma @code{Extend_System} +@cindex @code{Extend_System} pragma + +@smallexample @c ada +@group +@cartouche +pragma Extend_System (Aux_DEC); +@end cartouche +@end group +@end smallexample + +@noindent +the set of definitions in @code{System} is extended to include those in +package @code{System.Aux_DEC}. +@cindex @code{System.Aux_DEC} package +@cindex @code{Aux_DEC} package (child of @code{System}) +These definitions are incorporated directly into package @code{System}, +as though they had been declared there. For a +list of the declarations added, see the spec of this package, +which can be found in the file @file{s-auxdec.ads} in the GNAT library. +@cindex @file{s-auxdec.ads} file +The pragma @code{Extend_System} is a configuration pragma, which means that +it can be placed in the file @file{gnat.adc}, so that it will automatically +apply to all subsequent compilations. See @ref{Configuration Pragmas}, +for further details. + +An alternative approach that avoids the use of the non-standard +@code{Extend_System} pragma is to add a context clause to the unit that +references these facilities: + +@smallexample @c ada +@cartouche +with System.Aux_DEC; +use System.Aux_DEC; +@end cartouche +@end smallexample + +@noindent +The effect is not quite semantically identical to incorporating +the declarations directly into package @code{System}, +but most programs will not notice a difference +unless they use prefix notation (e.g.@: @code{System.Integer_8}) +to reference the entities directly in package @code{System}. +For units containing such references, +the prefixes must either be removed, or the pragma @code{Extend_System} +must be used. + +@node Language-Related Features +@section Language-Related Features + +@noindent +The following sections highlight differences in types, +representations of types, operations, alignment, and +related topics. + +@menu +* Integer Types and Representations:: +* Floating-Point Types and Representations:: +* Pragmas Float_Representation and Long_Float:: +* Fixed-Point Types and Representations:: +* Record and Array Component Alignment:: +* Address Clauses:: +* Other Representation Clauses:: +@end menu + +@node Integer Types and Representations +@subsection Integer Types and Representations + +@noindent +The set of predefined integer types is identical in HP Ada and GNAT. +Furthermore the representation of these integer types is also identical, +including the capability of size clauses forcing biased representation. + +In addition, +HP Ada for OpenVMS Alpha systems has defined the +following additional integer types in package @code{System}: + +@itemize @bullet + +@item +@code{INTEGER_8} + +@item +@code{INTEGER_16} + +@item +@code{INTEGER_32} + +@item +@code{INTEGER_64} + +@item +@code{LARGEST_INTEGER} +@end itemize + +@noindent +In GNAT, the first four of these types may be obtained from the +standard Ada package @code{Interfaces}. +Alternatively, by use of the pragma @code{Extend_System}, identical +declarations can be referenced directly in package @code{System}. +On both GNAT and HP Ada, the maximum integer size is 64 bits. + +@node Floating-Point Types and Representations +@subsection Floating-Point Types and Representations +@cindex Floating-Point types + +@noindent +The set of predefined floating-point types is identical in HP Ada and GNAT. +Furthermore the representation of these floating-point +types is also identical. One important difference is that the default +representation for HP Ada is @code{VAX_Float}, but the default representation +for GNAT is IEEE. + +Specific types may be declared to be @code{VAX_Float} or IEEE, using the +pragma @code{Float_Representation} as described in the HP Ada +documentation. +For example, the declarations: + +@smallexample @c ada +@cartouche +type F_Float is digits 6; +pragma Float_Representation (VAX_Float, F_Float); +@end cartouche +@end smallexample + +@noindent +declares a type @code{F_Float} that will be represented in @code{VAX_Float} +format. +This set of declarations actually appears in @code{System.Aux_DEC}, +which contains +the full set of additional floating-point declarations provided in +the HP Ada version of package @code{System}. +This and similar declarations may be accessed in a user program +by using pragma @code{Extend_System}. The use of this +pragma, and the related pragma @code{Long_Float} is described in further +detail in the following section. + +@node Pragmas Float_Representation and Long_Float +@subsection Pragmas @code{Float_Representation} and @code{Long_Float} + +@noindent +HP Ada provides the pragma @code{Float_Representation}, which +acts as a program library switch to allow control over +the internal representation chosen for the predefined +floating-point types declared in the package @code{Standard}. +The format of this pragma is as follows: + +@smallexample @c ada +@cartouche +pragma Float_Representation(VAX_Float | IEEE_Float); +@end cartouche +@end smallexample + +@noindent +This pragma controls the representation of floating-point +types as follows: + +@itemize @bullet +@item +@code{VAX_Float} specifies that floating-point +types are represented by default with the VAX system hardware types +@code{F-floating}, @code{D-floating}, @code{G-floating}. +Note that the @code{H-floating} +type was available only on VAX systems, and is not available +in either HP Ada or GNAT. + +@item +@code{IEEE_Float} specifies that floating-point +types are represented by default with the IEEE single and +double floating-point types. +@end itemize + +@noindent +GNAT provides an identical implementation of the pragma +@code{Float_Representation}, except that it functions as a +configuration pragma. Note that the +notion of configuration pragma corresponds closely to the +HP Ada notion of a program library switch. + +When no pragma is used in GNAT, the default is @code{IEEE_Float}, +which is different +from HP Ada 83, where the default is @code{VAX_Float}. In addition, the +predefined libraries in GNAT are built using @code{IEEE_Float}, so it is not +advisable to change the format of numbers passed to standard library +routines, and if necessary explicit type conversions may be needed. + +The use of @code{IEEE_Float} is recommended in GNAT since it is more +efficient, and (given that it conforms to an international standard) +potentially more portable. +The situation in which @code{VAX_Float} may be useful is in interfacing +to existing code and data that expect the use of @code{VAX_Float}. +In such a situation use the predefined @code{VAX_Float} +types in package @code{System}, as extended by +@code{Extend_System}. For example, use @code{System.F_Float} +to specify the 32-bit @code{F-Float} format. + +@noindent +On OpenVMS systems, HP Ada provides the pragma @code{Long_Float} +to allow control over the internal representation chosen +for the predefined type @code{Long_Float} and for floating-point +type declarations with digits specified in the range 7 .. 15. +The format of this pragma is as follows: + +@smallexample @c ada +@cartouche +pragma Long_Float (D_FLOAT | G_FLOAT); +@end cartouche +@end smallexample + +@node Fixed-Point Types and Representations +@subsection Fixed-Point Types and Representations + +@noindent +On HP Ada for OpenVMS Alpha systems, rounding is +away from zero for both positive and negative numbers. +Therefore, @code{+0.5} rounds to @code{1}, +and @code{-0.5} rounds to @code{-1}. + +On GNAT the results of operations +on fixed-point types are in accordance with the Ada +rules. In particular, results of operations on decimal +fixed-point types are truncated. + +@node Record and Array Component Alignment +@subsection Record and Array Component Alignment + +@noindent +On HP Ada for OpenVMS Alpha, all non-composite components +are aligned on natural boundaries. For example, 1-byte +components are aligned on byte boundaries, 2-byte +components on 2-byte boundaries, 4-byte components on 4-byte +byte boundaries, and so on. The OpenVMS Alpha hardware +runs more efficiently with naturally aligned data. + +On GNAT, alignment rules are compatible +with HP Ada for OpenVMS Alpha. + +@node Address Clauses +@subsection Address Clauses + +@noindent +In HP Ada and GNAT, address clauses are supported for +objects and imported subprograms. +The predefined type @code{System.Address} is a private type +in both compilers on Alpha OpenVMS, with the same representation +(it is simply a machine pointer). Addition, subtraction, and comparison +operations are available in the standard Ada package +@code{System.Storage_Elements}, or in package @code{System} +if it is extended to include @code{System.Aux_DEC} using a +pragma @code{Extend_System} as previously described. + +Note that code that @code{with}'s both this extended package @code{System} +and the package @code{System.Storage_Elements} should not @code{use} +both packages, or ambiguities will result. In general it is better +not to mix these two sets of facilities. The Ada package was +designed specifically to provide the kind of features that HP Ada +adds directly to package @code{System}. + +The type @code{System.Address} is a 64-bit integer type in GNAT for +I64 OpenVMS. For more information, +see @ref{Transitioning to 64-Bit GNAT for OpenVMS}. + +GNAT is compatible with HP Ada in its handling of address +clauses, except for some limitations in +the form of address clauses for composite objects with +initialization. Such address clauses are easily replaced +by the use of an explicitly-defined constant as described +in the Ada Reference Manual (13.1(22)). For example, the sequence +of declarations: + +@smallexample @c ada +@cartouche +X, Y : Integer := Init_Func; +Q : String (X .. Y) := "abc"; +@dots{} +for Q'Address use Compute_Address; +@end cartouche +@end smallexample + +@noindent +will be rejected by GNAT, since the address cannot be computed at the time +that @code{Q} is declared. To achieve the intended effect, write instead: + +@smallexample @c ada +@group +@cartouche +X, Y : Integer := Init_Func; +Q_Address : constant Address := Compute_Address; +Q : String (X .. Y) := "abc"; +@dots{} +for Q'Address use Q_Address; +@end cartouche +@end group +@end smallexample + +@noindent +which will be accepted by GNAT (and other Ada compilers), and is also +compatible with Ada 83. A fuller description of the restrictions +on address specifications is found in @ref{Top, GNAT Reference Manual, +About This Guide, gnat_rm, GNAT Reference Manual}. + +@node Other Representation Clauses +@subsection Other Representation Clauses + +@noindent +GNAT implements in a compatible manner all the representation +clauses supported by HP Ada. In addition, GNAT +implements the representation clause forms that were introduced in Ada 95, +including @code{COMPONENT_SIZE} and @code{SIZE} clauses for objects. + +@node The Package STANDARD +@section The Package @code{STANDARD} + +@noindent +The package @code{STANDARD}, as implemented by HP Ada, is fully +described in the @cite{Ada Reference Manual} and in the +@cite{HP Ada Language Reference Manual}. As implemented by GNAT, the +package @code{STANDARD} is described in the @cite{Ada Reference Manual}. + +In addition, HP Ada supports the Latin-1 character set in +the type @code{CHARACTER}. GNAT supports the Latin-1 character set +in the type @code{CHARACTER} and also Unicode (ISO 10646 BMP) in +the type @code{WIDE_CHARACTER}. + +The floating-point types supported by GNAT are those +supported by HP Ada, but the defaults are different, and are controlled by +pragmas. See @ref{Floating-Point Types and Representations}, for details. + +@node The Package SYSTEM +@section The Package @code{SYSTEM} + +@noindent +HP Ada provides a specific version of the package +@code{SYSTEM} for each platform on which the language is implemented. +For the complete spec of the package @code{SYSTEM}, see +Appendix F of the @cite{HP Ada Language Reference Manual}. + +On HP Ada, the package @code{SYSTEM} includes the following conversion +functions: +@itemize @bullet +@item @code{TO_ADDRESS(INTEGER)} + +@item @code{TO_ADDRESS(UNSIGNED_LONGWORD)} + +@item @code{TO_ADDRESS(}@i{universal_integer}@code{)} + +@item @code{TO_INTEGER(ADDRESS)} + +@item @code{TO_UNSIGNED_LONGWORD(ADDRESS)} + +@item Function @code{IMPORT_VALUE return UNSIGNED_LONGWORD} and the +functions @code{IMPORT_ADDRESS} and @code{IMPORT_LARGEST_VALUE} +@end itemize + +@noindent +By default, GNAT supplies a version of @code{SYSTEM} that matches +the definition given in the @cite{Ada Reference Manual}. +This +is a subset of the HP system definitions, which is as +close as possible to the original definitions. The only difference +is that the definition of @code{SYSTEM_NAME} is different: + +@smallexample @c ada +@cartouche +type Name is (SYSTEM_NAME_GNAT); +System_Name : constant Name := SYSTEM_NAME_GNAT; +@end cartouche +@end smallexample + +@noindent +Also, GNAT adds the Ada declarations for +@code{BIT_ORDER} and @code{DEFAULT_BIT_ORDER}. + +However, the use of the following pragma causes GNAT +to extend the definition of package @code{SYSTEM} so that it +encompasses the full set of HP-specific extensions, +including the functions listed above: + +@smallexample @c ada +@cartouche +pragma Extend_System (Aux_DEC); +@end cartouche +@end smallexample + +@noindent +The pragma @code{Extend_System} is a configuration pragma that +is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma +Extend_System,,, gnat_rm, GNAT Reference Manual}, for further details. + +HP Ada does not allow the recompilation of the package +@code{SYSTEM}. Instead HP Ada provides several pragmas +(@code{SYSTEM_NAME}, @code{STORAGE_UNIT}, and @code{MEMORY_SIZE}) +to modify values in the package @code{SYSTEM}. +On OpenVMS Alpha systems, the pragma +@code{SYSTEM_NAME} takes the enumeration literal @code{OPENVMS_AXP} as +its single argument. + +GNAT does permit the recompilation of package @code{SYSTEM} using +the special switch @option{-gnatg}, and this switch can be used if +it is necessary to modify the definitions in @code{SYSTEM}. GNAT does +not permit the specification of @code{SYSTEM_NAME}, @code{STORAGE_UNIT} +or @code{MEMORY_SIZE} by any other means. + +On GNAT systems, the pragma @code{SYSTEM_NAME} takes the +enumeration literal @code{SYSTEM_NAME_GNAT}. + +The definitions provided by the use of + +@smallexample @c ada +pragma Extend_System (AUX_Dec); +@end smallexample + +@noindent +are virtually identical to those provided by the HP Ada 83 package +@code{SYSTEM}. One important difference is that the name of the +@code{TO_ADDRESS} +function for type @code{UNSIGNED_LONGWORD} is changed to +@code{TO_ADDRESS_LONG}. +@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual}, for a +discussion of why this change was necessary. + +@noindent +The version of @code{TO_ADDRESS} taking a @i{universal_integer} argument +is in fact +an extension to Ada 83 not strictly compatible with the reference manual. +GNAT, in order to be exactly compatible with the standard, +does not provide this capability. In HP Ada 83, the +point of this definition is to deal with a call like: + +@smallexample @c ada +TO_ADDRESS (16#12777#); +@end smallexample + +@noindent +Normally, according to Ada 83 semantics, one would expect this to be +ambiguous, since it matches both the @code{INTEGER} and +@code{UNSIGNED_LONGWORD} forms of @code{TO_ADDRESS}. +However, in HP Ada 83, there is no ambiguity, since the +definition using @i{universal_integer} takes precedence. + +In GNAT, since the version with @i{universal_integer} cannot be supplied, +it is +not possible to be 100% compatible. Since there are many programs using +numeric constants for the argument to @code{TO_ADDRESS}, the decision in +GNAT was +to change the name of the function in the @code{UNSIGNED_LONGWORD} case, +so the declarations provided in the GNAT version of @code{AUX_Dec} are: + +@smallexample @c ada +function To_Address (X : Integer) return Address; +pragma Pure_Function (To_Address); + +function To_Address_Long (X : Unsigned_Longword) return Address; +pragma Pure_Function (To_Address_Long); +@end smallexample + +@noindent +This means that programs using @code{TO_ADDRESS} for +@code{UNSIGNED_LONGWORD} must change the name to @code{TO_ADDRESS_LONG}. + +@node Tasking and Task-Related Features +@section Tasking and Task-Related Features + +@noindent +This section compares the treatment of tasking in GNAT +and in HP Ada for OpenVMS Alpha. +The GNAT description applies to both Alpha and I64 OpenVMS. +For detailed information on tasking in +HP Ada, see the @cite{HP Ada Language Reference Manual} and the +relevant run-time reference manual. + +@menu +* Implementation of Tasks in HP Ada for OpenVMS Alpha Systems:: +* Assigning Task IDs:: +* Task IDs and Delays:: +* Task-Related Pragmas:: +* Scheduling and Task Priority:: +* The Task Stack:: +* External Interrupts:: +@end menu + +@node Implementation of Tasks in HP Ada for OpenVMS Alpha Systems +@subsection Implementation of Tasks in HP Ada for OpenVMS Alpha Systems + +@noindent +On OpenVMS Alpha systems, each Ada task (except a passive +task) is implemented as a single stream of execution +that is created and managed by the kernel. On these +systems, HP Ada tasking support is based on DECthreads, +an implementation of the POSIX standard for threads. + +Also, on OpenVMS Alpha systems, HP Ada tasks and foreign +code that calls DECthreads routines can be used together. +The interaction between Ada tasks and DECthreads routines +can have some benefits. For example when on OpenVMS Alpha, +HP Ada can call C code that is already threaded. + +GNAT uses the facilities of DECthreads, +and Ada tasks are mapped to threads. + +@node Assigning Task IDs +@subsection Assigning Task IDs + +@noindent +The HP Ada Run-Time Library always assigns @code{%TASK 1} to +the environment task that executes the main program. On +OpenVMS Alpha systems, @code{%TASK 0} is often used for tasks +that have been created but are not yet activated. + +On OpenVMS Alpha systems, task IDs are assigned at +activation. On GNAT systems, task IDs are also assigned at +task creation but do not have the same form or values as +task ID values in HP Ada. There is no null task, and the +environment task does not have a specific task ID value. + +@node Task IDs and Delays +@subsection Task IDs and Delays + +@noindent +On OpenVMS Alpha systems, tasking delays are implemented +using Timer System Services. The Task ID is used for the +identification of the timer request (the @code{REQIDT} parameter). +If Timers are used in the application take care not to use +@code{0} for the identification, because cancelling such a timer +will cancel all timers and may lead to unpredictable results. + +@node Task-Related Pragmas +@subsection Task-Related Pragmas + +@noindent +Ada supplies the pragma @code{TASK_STORAGE}, which allows +specification of the size of the guard area for a task +stack. (The guard area forms an area of memory that has no +read or write access and thus helps in the detection of +stack overflow.) On OpenVMS Alpha systems, if the pragma +@code{TASK_STORAGE} specifies a value of zero, a minimal guard +area is created. In the absence of a pragma @code{TASK_STORAGE}, +a default guard area is created. + +GNAT supplies the following task-related pragmas: + +@itemize @bullet +@item @code{TASK_INFO} + +This pragma appears within a task definition and +applies to the task in which it appears. The argument +must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}. + +@item @code{TASK_STORAGE} + +GNAT implements pragma @code{TASK_STORAGE} in the same way as HP Ada. +Both HP Ada and GNAT supply the pragmas @code{PASSIVE}, +@code{SUPPRESS}, and @code{VOLATILE}. +@end itemize +@node Scheduling and Task Priority +@subsection Scheduling and Task Priority + +@noindent +HP Ada implements the Ada language requirement that +when two tasks are eligible for execution and they have +different priorities, the lower priority task does not +execute while the higher priority task is waiting. The HP +Ada Run-Time Library keeps a task running until either the +task is suspended or a higher priority task becomes ready. + +On OpenVMS Alpha systems, the default strategy is round- +robin with preemption. Tasks of equal priority take turns +at the processor. A task is run for a certain period of +time and then placed at the tail of the ready queue for +its priority level. + +HP Ada provides the implementation-defined pragma @code{TIME_SLICE}, +which can be used to enable or disable round-robin +scheduling of tasks with the same priority. +See the relevant HP Ada run-time reference manual for +information on using the pragmas to control HP Ada task +scheduling. + +GNAT follows the scheduling rules of Annex D (Real-Time +Annex) of the @cite{Ada Reference Manual}. In general, this +scheduling strategy is fully compatible with HP Ada +although it provides some additional constraints (as +fully documented in Annex D). +GNAT implements time slicing control in a manner compatible with +HP Ada 83, by means of the pragma @code{Time_Slice}, whose semantics +are identical to the HP Ada 83 pragma of the same name. +Note that it is not possible to mix GNAT tasking and +HP Ada 83 tasking in the same program, since the two run-time +libraries are not compatible. + +@node The Task Stack +@subsection The Task Stack + +@noindent +In HP Ada, a task stack is allocated each time a +non-passive task is activated. As soon as the task is +terminated, the storage for the task stack is deallocated. +If you specify a size of zero (bytes) with @code{T'STORAGE_SIZE}, +a default stack size is used. Also, regardless of the size +specified, some additional space is allocated for task +management purposes. On OpenVMS Alpha systems, at least +one page is allocated. + +GNAT handles task stacks in a similar manner. In accordance with +the Ada rules, it provides the pragma @code{STORAGE_SIZE} as +an alternative method for controlling the task stack size. +The specification of the attribute @code{T'STORAGE_SIZE} is also +supported in a manner compatible with HP Ada. + +@node External Interrupts +@subsection External Interrupts + +@noindent +On HP Ada, external interrupts can be associated with task entries. +GNAT is compatible with HP Ada in its handling of external interrupts. + +@node Pragmas and Pragma-Related Features +@section Pragmas and Pragma-Related Features + +@noindent +Both HP Ada and GNAT supply all language-defined pragmas +as specified by the Ada 83 standard. GNAT also supplies all +language-defined pragmas introduced by Ada 95 and Ada 2005. +In addition, GNAT implements the implementation-defined pragmas +from HP Ada 83. + +@itemize @bullet +@item @code{AST_ENTRY} + +@item @code{COMMON_OBJECT} + +@item @code{COMPONENT_ALIGNMENT} + +@item @code{EXPORT_EXCEPTION} + +@item @code{EXPORT_FUNCTION} + +@item @code{EXPORT_OBJECT} + +@item @code{EXPORT_PROCEDURE} + +@item @code{EXPORT_VALUED_PROCEDURE} + +@item @code{FLOAT_REPRESENTATION} + +@item @code{IDENT} + +@item @code{IMPORT_EXCEPTION} + +@item @code{IMPORT_FUNCTION} + +@item @code{IMPORT_OBJECT} + +@item @code{IMPORT_PROCEDURE} + +@item @code{IMPORT_VALUED_PROCEDURE} + +@item @code{INLINE_GENERIC} + +@item @code{INTERFACE_NAME} + +@item @code{LONG_FLOAT} + +@item @code{MAIN_STORAGE} + +@item @code{PASSIVE} + +@item @code{PSECT_OBJECT} + +@item @code{SHARE_GENERIC} + +@item @code{SUPPRESS_ALL} + +@item @code{TASK_STORAGE} + +@item @code{TIME_SLICE} + +@item @code{TITLE} +@end itemize + +@noindent +These pragmas are all fully implemented, with the exception of @code{TITLE}, +@code{PASSIVE}, and @code{SHARE_GENERIC}, which are +recognized, but which have no +effect in GNAT. The effect of @code{PASSIVE} may be obtained by the +use of Ada protected objects. In GNAT, all generics are inlined. + +Unlike HP Ada, the GNAT ``@code{EXPORT_}@i{subprogram}'' pragmas require +a separate subprogram specification which must appear before the +subprogram body. + +GNAT also supplies a number of implementation-defined pragmas including the +following: + +@itemize @bullet +@item @code{ABORT_DEFER} + +@item @code{ADA_83} + +@item @code{ADA_95} + +@item @code{ADA_05} + +@item @code{Ada_2005} + +@item @code{Ada_12} + +@item @code{Ada_2012} + +@item @code{ANNOTATE} + +@item @code{ASSERT} + +@item @code{C_PASS_BY_COPY} + +@item @code{CPP_CLASS} + +@item @code{CPP_CONSTRUCTOR} + +@item @code{CPP_DESTRUCTOR} + +@item @code{DEBUG} + +@item @code{EXTEND_SYSTEM} + +@item @code{LINKER_ALIAS} + +@item @code{LINKER_SECTION} + +@item @code{MACHINE_ATTRIBUTE} + +@item @code{NO_RETURN} + +@item @code{PURE_FUNCTION} + +@item @code{SOURCE_FILE_NAME} + +@item @code{SOURCE_REFERENCE} + +@item @code{TASK_INFO} + +@item @code{UNCHECKED_UNION} + +@item @code{UNIMPLEMENTED_UNIT} + +@item @code{UNIVERSAL_DATA} + +@item @code{UNSUPPRESS} + +@item @code{WARNINGS} + +@item @code{WEAK_EXTERNAL} +@end itemize + +@noindent +For full details on these and other GNAT implementation-defined pragmas, +see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference +Manual}. + +@menu +* Restrictions on the Pragma INLINE:: +* Restrictions on the Pragma INTERFACE:: +* Restrictions on the Pragma SYSTEM_NAME:: +@end menu + +@node Restrictions on the Pragma INLINE +@subsection Restrictions on Pragma @code{INLINE} + +@noindent +HP Ada enforces the following restrictions on the pragma @code{INLINE}: +@itemize @bullet +@item Parameters cannot have a task type. + +@item Function results cannot be task types, unconstrained +array types, or unconstrained types with discriminants. + +@item Bodies cannot declare the following: +@itemize @bullet +@item Subprogram body or stub (imported subprogram is allowed) + +@item Tasks + +@item Generic declarations + +@item Instantiations + +@item Exceptions + +@item Access types (types derived from access types allowed) + +@item Array or record types + +@item Dependent tasks + +@item Direct recursive calls of subprogram or containing +subprogram, directly or via a renaming + +@end itemize +@end itemize + +@noindent +In GNAT, the only restriction on pragma @code{INLINE} is that the +body must occur before the call if both are in the same +unit, and the size must be appropriately small. There are +no other specific restrictions which cause subprograms to +be incapable of being inlined. + +@node Restrictions on the Pragma INTERFACE +@subsection Restrictions on Pragma @code{INTERFACE} + +@noindent +The following restrictions on pragma @code{INTERFACE} +are enforced by both HP Ada and GNAT: +@itemize @bullet +@item Languages accepted: Ada, Bliss, C, Fortran, Default. +Default is the default on OpenVMS Alpha systems. + +@item Parameter passing: Language specifies default +mechanisms but can be overridden with an @code{EXPORT} pragma. + +@itemize @bullet +@item Ada: Use internal Ada rules. + +@item Bliss, C: Parameters must be mode @code{in}; cannot be +record or task type. Result cannot be a string, an +array, or a record. + +@item Fortran: Parameters cannot have a task type. Result cannot +be a string, an array, or a record. +@end itemize +@end itemize + +@noindent +GNAT is entirely upwards compatible with HP Ada, and in addition allows +record parameters for all languages. + +@node Restrictions on the Pragma SYSTEM_NAME +@subsection Restrictions on Pragma @code{SYSTEM_NAME} + +@noindent +For HP Ada for OpenVMS Alpha, the enumeration literal +for the type @code{NAME} is @code{OPENVMS_AXP}. +In GNAT, the enumeration +literal for the type @code{NAME} is @code{SYSTEM_NAME_GNAT}. + +@node Library of Predefined Units +@section Library of Predefined Units + +@noindent +A library of predefined units is provided as part of the +HP Ada and GNAT implementations. HP Ada does not provide +the package @code{MACHINE_CODE} but instead recommends importing +assembler code. + +The GNAT versions of the HP Ada Run-Time Library (@code{ADA$PREDEFINED:}) +units are taken from the OpenVMS Alpha version, not the OpenVMS VAX +version. +The HP Ada Predefined Library units are modified to remove post-Ada 83 +incompatibilities and to make them interoperable with GNAT +(@pxref{Changes to DECLIB}, for details). +The units are located in the @file{DECLIB} directory. + +The GNAT RTL is contained in +the @file{ADALIB} directory, and +the default search path is set up to find @code{DECLIB} units in preference +to @code{ADALIB} units with the same name (@code{TEXT_IO}, +@code{SEQUENTIAL_IO}, and @code{DIRECT_IO}, for example). + +@menu +* Changes to DECLIB:: +@end menu + +@node Changes to DECLIB +@subsection Changes to @code{DECLIB} + +@noindent +The changes made to the HP Ada predefined library for GNAT and post-Ada 83 +compatibility are minor and include the following: + +@itemize @bullet +@item Adjusting the location of pragmas and record representation +clauses to obey Ada 95 (and thus Ada 2005) rules + +@item Adding the proper notation to generic formal parameters +that take unconstrained types in instantiation + +@item Adding pragma @code{ELABORATE_BODY} to package specs +that have package bodies not otherwise allowed + +@item Replacing occurrences of the identifier ``@code{PROTECTED}'' by +``@code{PROTECTD}''. +Currently these are found only in the @code{STARLET} package spec. + +@item Changing @code{SYSTEM.ADDRESS} to @code{SYSTEM.SHORT_ADDRESS} +where the address size is constrained to 32 bits. +@end itemize + +@noindent +None of the above changes is visible to users. + +@node Bindings +@section Bindings + +@noindent +On OpenVMS Alpha, HP Ada provides the following strongly-typed bindings: +@itemize @bullet + +@item Command Language Interpreter (CLI interface) + +@item DECtalk Run-Time Library (DTK interface) + +@item Librarian utility routines (LBR interface) + +@item General Purpose Run-Time Library (LIB interface) + +@item Math Run-Time Library (MTH interface) + +@item National Character Set Run-Time Library (NCS interface) + +@item Compiled Code Support Run-Time Library (OTS interface) + +@item Parallel Processing Run-Time Library (PPL interface) + +@item Screen Management Run-Time Library (SMG interface) + +@item Sort Run-Time Library (SOR interface) + +@item String Run-Time Library (STR interface) + +@item STARLET System Library +@findex Starlet + +@item X Window System Version 11R4 and 11R5 (X, XLIB interface) + +@item X Windows Toolkit (XT interface) + +@item X/Motif Version 1.1.3 and 1.2 (XM interface) +@end itemize + +@noindent +GNAT provides implementations of these HP bindings in the @code{DECLIB} +directory, on both the Alpha and I64 OpenVMS platforms. + +The X/Motif bindings used to build @code{DECLIB} are whatever versions are +in the +HP Ada @file{ADA$PREDEFINED} directory with extension @file{.ADC}. +A pragma @code{Linker_Options} has been added to packages @code{Xm}, +@code{Xt}, and @code{X_Lib} +causing the default X/Motif sharable image libraries to be linked in. This +is done via options files named @file{xm.opt}, @file{xt.opt}, and +@file{x_lib.opt} (also located in the @file{DECLIB} directory). + +It may be necessary to edit these options files to update or correct the +library names if, for example, the newer X/Motif bindings from +@file{ADA$EXAMPLES} +had been (previous to installing GNAT) copied and renamed to supersede the +default @file{ADA$PREDEFINED} versions. + +@menu +* Shared Libraries and Options Files:: +* Interfaces to C:: +@end menu + +@node Shared Libraries and Options Files +@subsection Shared Libraries and Options Files + +@noindent +When using the HP Ada +predefined X and Motif bindings, the linking with their sharable images is +done automatically by @command{GNAT LINK}. +When using other X and Motif bindings, you need +to add the corresponding sharable images to the command line for +@code{GNAT LINK}. When linking with shared libraries, or with +@file{.OPT} files, you must +also add them to the command line for @command{GNAT LINK}. + +A shared library to be used with GNAT is built in the same way as other +libraries under VMS. The VMS Link command can be used in standard fashion. + +@node Interfaces to C +@subsection Interfaces to C + +@noindent +HP Ada +provides the following Ada types and operations: + +@itemize @bullet +@item C types package (@code{C_TYPES}) + +@item C strings (@code{C_TYPES.NULL_TERMINATED}) + +@item Other_types (@code{SHORT_INT}) +@end itemize + +@noindent +Interfacing to C with GNAT, you can use the above approach +described for HP Ada or the facilities of Annex B of +the @cite{Ada Reference Manual} (packages @code{INTERFACES.C}, +@code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more +information, see @ref{Interfacing to C,,, gnat_rm, GNAT Reference Manual}. + +The @option{-gnatF} qualifier forces default and explicit +@code{External_Name} parameters in pragmas @code{Import} and @code{Export} +to be uppercased for compatibility with the default behavior +of HP C. The qualifier has no effect on @code{Link_Name} parameters. + +@node Main Program Definition +@section Main Program Definition + +@noindent +The following section discusses differences in the +definition of main programs on HP Ada and GNAT. +On HP Ada, main programs are defined to meet the +following conditions: +@itemize @bullet +@item Procedure with no formal parameters (returns @code{0} upon +normal completion) + +@item Procedure with no formal parameters (returns @code{42} when +an unhandled exception is raised) + +@item Function with no formal parameters whose returned value +is of a discrete type + +@item Procedure with one @code{out} formal of a discrete type for +which a specification of pragma @code{EXPORT_VALUED_PROCEDURE} is given. + +@end itemize + +@noindent +When declared with the pragma @code{EXPORT_VALUED_PROCEDURE}, +a main function or main procedure returns a discrete +value whose size is less than 64 bits (32 on VAX systems), +the value is zero- or sign-extended as appropriate. +On GNAT, main programs are defined as follows: +@itemize @bullet +@item Must be a non-generic, parameterless subprogram that +is either a procedure or function returning an Ada +@code{STANDARD.INTEGER} (the predefined type) + +@item Cannot be a generic subprogram or an instantiation of a +generic subprogram +@end itemize + +@node Implementation-Defined Attributes +@section Implementation-Defined Attributes + +@noindent +GNAT provides all HP Ada implementation-defined +attributes. + +@node Compiler and Run-Time Interfacing +@section Compiler and Run-Time Interfacing + +@noindent +HP Ada provides the following qualifiers to pass options to the linker +(ACS LINK): +@itemize @bullet +@item @option{/WAIT} and @option{/SUBMIT} + +@item @option{/COMMAND} + +@item @option{/@r{[}NO@r{]}MAP} + +@item @option{/OUTPUT=@var{file-spec}} + +@item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK} +@end itemize + +@noindent +To pass options to the linker, GNAT provides the following +switches: + +@itemize @bullet +@item @option{/EXECUTABLE=@var{exec-name}} + +@item @option{/VERBOSE} + +@item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK} +@end itemize + +@noindent +For more information on these switches, see +@ref{Switches for gnatlink}. +In HP Ada, the command-line switch @option{/OPTIMIZE} is available +to control optimization. HP Ada also supplies the +following pragmas: +@itemize @bullet +@item @code{OPTIMIZE} + +@item @code{INLINE} + +@item @code{INLINE_GENERIC} + +@item @code{SUPPRESS_ALL} + +@item @code{PASSIVE} +@end itemize + +@noindent +In GNAT, optimization is controlled strictly by command +line parameters, as described in the corresponding section of this guide. +The HP pragmas for control of optimization are +recognized but ignored. + +Note that in GNAT, the default is optimization off, whereas in HP Ada +the default is that optimization is turned on. + +@node Program Compilation and Library Management +@section Program Compilation and Library Management + +@noindent +HP Ada and GNAT provide a comparable set of commands to +build programs. HP Ada also provides a program library, +which is a concept that does not exist on GNAT. Instead, +GNAT provides directories of sources that are compiled as +needed. + +The following table summarizes +the HP Ada commands and provides +equivalent GNAT commands. In this table, some GNAT +equivalents reflect the fact that GNAT does not use the +concept of a program library. Instead, it uses a model +in which collections of source and object files are used +in a manner consistent with other languages like C and +Fortran. Therefore, standard system file commands are used +to manipulate these elements. Those GNAT commands are marked with +an asterisk. +Note that, unlike HP Ada, none of the GNAT commands accepts wild cards. + +@need 1500 +@multitable @columnfractions .35 .65 + +@item @emph{HP Ada Command} +@tab @emph{GNAT Equivalent / Description} + +@item @command{ADA} +@tab @command{GNAT COMPILE}@* +Invokes the compiler to compile one or more Ada source files. + +@item @command{ACS ATTACH}@* +@tab [No equivalent]@* +Switches control of terminal from current process running the program +library manager. + +@item @command{ACS CHECK} +@tab @command{GNAT MAKE /DEPENDENCY_LIST}@* +Forms the execution closure of one +or more compiled units and checks completeness and currency. + +@item @command{ACS COMPILE} +@tab @command{GNAT MAKE /ACTIONS=COMPILE}@* +Forms the execution closure of one or +more specified units, checks completeness and currency, +identifies units that have revised source files, compiles same, +and recompiles units that are or will become obsolete. +Also completes incomplete generic instantiations. + +@item @command{ACS COPY FOREIGN} +@tab Copy (*)@* +Copies a foreign object file into the program library as a +library unit body. + +@item @command{ACS COPY UNIT} +@tab Copy (*)@* +Copies a compiled unit from one program library to another. + +@item @command{ACS CREATE LIBRARY} +@tab Create /directory (*)@* +Creates a program library. + +@item @command{ACS CREATE SUBLIBRARY} +@tab Create /directory (*)@* +Creates a program sublibrary. + +@item @command{ACS DELETE LIBRARY} +@tab @* +Deletes a program library and its contents. + +@item @command{ACS DELETE SUBLIBRARY} +@tab @* +Deletes a program sublibrary and its contents. + +@item @command{ACS DELETE UNIT} +@tab Delete file (*)@* +On OpenVMS systems, deletes one or more compiled units from +the current program library. + +@item @command{ACS DIRECTORY} +@tab Directory (*)@* +On OpenVMS systems, lists units contained in the current +program library. + +@item @command{ACS ENTER FOREIGN} +@tab Copy (*)@* +Allows the import of a foreign body as an Ada library +spec and enters a reference to a pointer. + +@item @command{ACS ENTER UNIT} +@tab Copy (*)@* +Enters a reference (pointer) from the current program library to +a unit compiled into another program library. + +@item @command{ACS EXIT} +@tab [No equivalent]@* +Exits from the program library manager. + +@item @command{ACS EXPORT} +@tab Copy (*)@* +Creates an object file that contains system-specific object code +for one or more units. With GNAT, object files can simply be copied +into the desired directory. + +@item @command{ACS EXTRACT SOURCE} +@tab Copy (*)@* +Allows access to the copied source file for each Ada compilation unit + +@item @command{ACS HELP} +@tab @command{HELP GNAT}@* +Provides online help. + +@item @command{ACS LINK} +@tab @command{GNAT LINK}@* +Links an object file containing Ada units into an executable file. + +@item @command{ACS LOAD} +@tab Copy (*)@* +Loads (partially compiles) Ada units into the program library. +Allows loading a program from a collection of files into a library +without knowing the relationship among units. + +@item @command{ACS MERGE} +@tab Copy (*)@* +Merges into the current program library, one or more units from +another library where they were modified. + +@item @command{ACS RECOMPILE} +@tab @command{GNAT MAKE /ACTIONS=COMPILE}@* +Recompiles from external or copied source files any obsolete +unit in the closure. Also, completes any incomplete generic +instantiations. + +@item @command{ACS REENTER} +@tab @command{GNAT MAKE}@* +Reenters current references to units compiled after last entered +with the @command{ACS ENTER UNIT} command. + +@item @command{ACS SET LIBRARY} +@tab Set default (*)@* +Defines a program library to be the compilation context as well +as the target library for compiler output and commands in general. + +@item @command{ACS SET PRAGMA} +@tab Edit @file{gnat.adc} (*)@* +Redefines specified values of the library characteristics +@code{LONG_ FLOAT}, @code{MEMORY_SIZE}, @code{SYSTEM_NAME}, +and @code{Float_Representation}. + +@item @command{ACS SET SOURCE} +@tab Define @code{ADA_INCLUDE_PATH} path (*)@* +Defines the source file search list for the @command{ACS COMPILE} command. + +@item @command{ACS SHOW LIBRARY} +@tab Directory (*)@* +Lists information about one or more program libraries. + +@item @command{ACS SHOW PROGRAM} +@tab [No equivalent]@* +Lists information about the execution closure of one or +more units in the program library. + +@item @command{ACS SHOW SOURCE} +@tab Show logical @code{ADA_INCLUDE_PATH}@* +Shows the source file search used when compiling units. + +@item @command{ACS SHOW VERSION} +@tab Compile with @option{VERBOSE} option +Displays the version number of the compiler and program library +manager used. + +@item @command{ACS SPAWN} +@tab [No equivalent]@* +Creates a subprocess of the current process (same as @command{DCL SPAWN} +command). + +@item @command{ACS VERIFY} +@tab [No equivalent]@* +Performs a series of consistency checks on a program library to +determine whether the library structure and library files are in +valid form. +@end multitable + +@noindent + +@node Input-Output +@section Input-Output + +@noindent +On OpenVMS Alpha systems, HP Ada uses OpenVMS Record +Management Services (RMS) to perform operations on +external files. + +@noindent +HP Ada and GNAT predefine an identical set of input- +output packages. To make the use of the +generic @code{TEXT_IO} operations more convenient, HP Ada +provides predefined library packages that instantiate the +integer and floating-point operations for the predefined +integer and floating-point types as shown in the following table. + +@multitable @columnfractions .45 .55 +@item @emph{Package Name} @tab Instantiation + +@item @code{INTEGER_TEXT_IO} +@tab @code{INTEGER_IO(INTEGER)} + +@item @code{SHORT_INTEGER_TEXT_IO} +@tab @code{INTEGER_IO(SHORT_INTEGER)} + +@item @code{SHORT_SHORT_INTEGER_TEXT_IO} +@tab @code{INTEGER_IO(SHORT_SHORT_INTEGER)} + +@item @code{FLOAT_TEXT_IO} +@tab @code{FLOAT_IO(FLOAT)} + +@item @code{LONG_FLOAT_TEXT_IO} +@tab @code{FLOAT_IO(LONG_FLOAT)} +@end multitable + +@noindent +The HP Ada predefined packages and their operations +are implemented using OpenVMS Alpha files and input-output +facilities. HP Ada supports asynchronous input-output on OpenVMS Alpha. +Familiarity with the following is recommended: +@itemize @bullet +@item RMS file organizations and access methods + +@item OpenVMS file specifications and directories + +@item OpenVMS File Definition Language (FDL) +@end itemize + +@noindent +GNAT provides I/O facilities that are completely +compatible with HP Ada. The distribution includes the +standard HP Ada versions of all I/O packages, operating +in a manner compatible with HP Ada. In particular, the +following packages are by default the HP Ada (Ada 83) +versions of these packages rather than the renamings +suggested in Annex J of the Ada Reference Manual: +@itemize @bullet +@item @code{TEXT_IO} + +@item @code{SEQUENTIAL_IO} + +@item @code{DIRECT_IO} +@end itemize + +@noindent +The use of the standard child package syntax (for +example, @code{ADA.TEXT_IO}) retrieves the post-Ada 83 versions of these +packages. +GNAT provides HP-compatible predefined instantiations +of the @code{TEXT_IO} packages, and also +provides the standard predefined instantiations required +by the @cite{Ada Reference Manual}. + +For further information on how GNAT interfaces to the file +system or how I/O is implemented in programs written in +mixed languages, see @ref{Implementation of the Standard I/O,,, +gnat_rm, GNAT Reference Manual}. +This chapter covers the following: +@itemize @bullet +@item Standard I/O packages + +@item @code{FORM} strings + +@item @code{ADA.DIRECT_IO} + +@item @code{ADA.SEQUENTIAL_IO} + +@item @code{ADA.TEXT_IO} + +@item Stream pointer positioning + +@item Reading and writing non-regular files + +@item @code{GET_IMMEDIATE} + +@item Treating @code{TEXT_IO} files as streams + +@item Shared files + +@item Open modes +@end itemize + +@node Implementation Limits +@section Implementation Limits + +@noindent +The following table lists implementation limits for HP Ada +and GNAT systems. +@multitable @columnfractions .60 .20 .20 +@sp 1 +@item @emph{Compilation Parameter} +@tab @emph{HP Ada} +@tab @emph{GNAT} +@sp 1 + +@item In a subprogram or entry declaration, maximum number of +formal parameters that are of an unconstrained record type +@tab 32 +@tab No set limit +@sp 1 + +@item Maximum identifier length (number of characters) +@tab 255 +@tab 32766 +@sp 1 + +@item Maximum number of characters in a source line +@tab 255 +@tab 32766 +@sp 1 + +@item Maximum collection size (number of bytes) +@tab 2**31-1 +@tab 2**31-1 +@sp 1 + +@item Maximum number of discriminants for a record type +@tab 245 +@tab No set limit +@sp 1 + +@item Maximum number of formal parameters in an entry or +subprogram declaration +@tab 246 +@tab No set limit +@sp 1 + +@item Maximum number of dimensions in an array type +@tab 255 +@tab No set limit +@sp 1 + +@item Maximum number of library units and subunits in a compilation. +@tab 4095 +@tab No set limit +@sp 1 + +@item Maximum number of library units and subunits in an execution. +@tab 16383 +@tab No set limit +@sp 1 + +@item Maximum number of objects declared with the pragma @code{COMMON_OBJECT} +or @code{PSECT_OBJECT} +@tab 32757 +@tab No set limit +@sp 1 + +@item Maximum number of enumeration literals in an enumeration type +definition +@tab 65535 +@tab No set limit +@sp 1 + +@item Maximum number of lines in a source file +@tab 65534 +@tab No set limit +@sp 1 + +@item Maximum number of bits in any object +@tab 2**31-1 +@tab 2**31-1 +@sp 1 + +@item Maximum size of the static portion of a stack frame (approximate) +@tab 2**31-1 +@tab 2**31-1 +@end multitable + +@node Tools and Utilities +@section Tools and Utilities + +@noindent +The following table lists some of the OpenVMS development tools +available for HP Ada, and the corresponding tools for +use with @value{EDITION} on Alpha and I64 platforms. +Aside from the debugger, all the OpenVMS tools identified are part +of the DECset package. + +@iftex +@c Specify table in TeX since Texinfo does a poor job +@tex +\smallskip +\smallskip +\settabs\+Language-Sensitive Editor\quad + &Product with HP Ada\quad + &\cr +\+\it Tool + &\it Product with HP Ada + & \it Product with GNAT Pro\cr +\smallskip +\+Code Management System + &HP CMS + & HP CMS\cr +\smallskip +\+Language-Sensitive Editor + &HP LSE + & emacs or HP LSE (Alpha)\cr +\+ + & + & HP LSE (I64)\cr +\smallskip +\+Debugger + &OpenVMS Debug + & gdb (Alpha),\cr +\+ + & + & OpenVMS Debug (I64)\cr +\smallskip +\+Source Code Analyzer / + &HP SCA + & GNAT XREF\cr +\+Cross Referencer + & + &\cr +\smallskip +\+Test Manager + &HP Digital Test + & HP DTM\cr +\+ + &Manager (DTM) + &\cr +\smallskip +\+Performance and + & HP PCA + & HP PCA\cr +\+Coverage Analyzer + & + &\cr +\smallskip +\+Module Management + & HP MMS + & Not applicable\cr +\+ System + & + &\cr +\smallskip +\smallskip +@end tex +@end iftex + +@ifnottex +@c This is the Texinfo version of the table. It renders poorly in pdf, hence +@c the TeX version above for the printed version +@flushleft +@c @multitable @columnfractions .3 .4 .4 +@multitable {Source Code Analyzer /}{Tool with HP Ada}{Tool with GNAT Pro} +@item @i{Tool} +@tab @i{Tool with HP Ada} +@tab @i{Tool with @value{EDITION}} +@item Code Management@*System +@tab HP CMS +@tab HP CMS +@item Language-Sensitive@*Editor +@tab HP LSE +@tab emacs or HP LSE (Alpha) +@item +@tab +@tab HP LSE (I64) +@item Debugger +@tab OpenVMS Debug +@tab gdb (Alpha), +@item +@tab +@tab OpenVMS Debug (I64) +@item Source Code Analyzer /@*Cross Referencer +@tab HP SCA +@tab GNAT XREF +@item Test Manager +@tab HP Digital Test@*Manager (DTM) +@tab HP DTM +@item Performance and@*Coverage Analyzer +@tab HP PCA +@tab HP PCA +@item Module Management@*System +@tab HP MMS +@tab Not applicable +@end multitable +@end flushleft +@end ifnottex + +@end ifset + +@c ************************************** +@node Platform-Specific Information for the Run-Time Libraries +@appendix Platform-Specific Information for the Run-Time Libraries +@cindex Tasking and threads libraries +@cindex Threads libraries and tasking +@cindex Run-time libraries (platform-specific information) + +@noindent +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 @bullet +@item @b{native threads library}, a binding to the thread package from +the underlying operating system + +@item @b{pthreads library} (Sparc Solaris only), a binding to the Solaris +POSIX thread package +@end itemize + +@noindent +For exception handling, either or both of two models are supplied: +@itemize @bullet +@item @b{Zero-Cost Exceptions} (``ZCX''),@footnote{ +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.} +@cindex Zero-Cost Exceptions +@cindex ZCX (Zero-Cost Exceptions) +which uses binder-generated tables that +are interrogated at run time to locate a handler + +@item @b{setjmp / longjmp} (``SJLJ''), +@cindex setjmp/longjmp Exception Model +@cindex SJLJ (setjmp/longjmp Exception Model) +which uses dynamically-set data to establish +the set of handlers +@end itemize + +@noindent +This appendix 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:: +* Specifying a Run-Time Library:: +* Choosing the Scheduling Policy:: +* Solaris-Specific Considerations:: +* Linux-Specific Considerations:: +* AIX-Specific Considerations:: +* Irix-Specific Considerations:: +* RTX-Specific Considerations:: +* HP-UX-Specific Considerations:: +@end menu + +@node Summary of Run-Time Configurations +@section Summary of Run-Time Configurations + +@multitable @columnfractions .30 .70 +@item @b{alpha-openvms} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native VMS threads +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{alpha-tru64} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native TRU64 threads +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @code{@ @ }@i{rts-sjlj} +@item @code{@ @ @ @ }Tasking @tab native TRU64 threads +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{ia64-hp_linux} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab pthread library +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{ia64-hpux} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native HP-UX threads +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{ia64-openvms} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native VMS threads +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{ia64-sgi_linux} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab pthread library +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{mips-irix} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native IRIX threads +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{pa-hpux} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native HP-UX threads +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @code{@ @ }@i{rts-sjlj} +@item @code{@ @ @ @ }Tasking @tab native HP-UX threads +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{ppc-aix} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native AIX threads +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{ppc-darwin} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native MacOS threads +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{sparc-solaris} @tab +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native Solaris threads library +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @code{@ @ }@i{rts-pthread} +@item @code{@ @ @ @ }Tasking @tab pthread library +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @code{@ @ }@i{rts-sjlj} +@item @code{@ @ @ @ }Tasking @tab native Solaris threads library +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{sparc64-solaris} @tab +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native Solaris threads library +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{x86-linux} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab pthread library +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @code{@ @ }@i{rts-sjlj} +@item @code{@ @ @ @ }Tasking @tab pthread library +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{x86-lynx} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native LynxOS threads +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{x86-solaris} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native Solaris threads +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{x86-windows} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab native Win32 threads +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @code{@ @ }@i{rts-sjlj (default)} +@item @code{@ @ @ @ }Tasking @tab native Win32 threads +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @b{x86-windows-rtx} +@item @code{@ @ }@i{rts-rtx-rtss (default)} +@item @code{@ @ @ @ }Tasking @tab RTX real-time subsystem RTSS threads (kernel mode) +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@item @code{@ @ }@i{rts-rtx-w32} +@item @code{@ @ @ @ }Tasking @tab RTX Win32 threads (user mode) +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @b{x86_64-linux} +@item @code{@ @ }@i{rts-native (default)} +@item @code{@ @ @ @ }Tasking @tab pthread library +@item @code{@ @ @ @ }Exceptions @tab ZCX +@* +@item @code{@ @ }@i{rts-sjlj} +@item @code{@ @ @ @ }Tasking @tab pthread library +@item @code{@ @ @ @ }Exceptions @tab SJLJ +@* +@end multitable + +@node Specifying a Run-Time Library +@section Specifying a Run-Time Library + +@noindent +The @file{adainclude} subdirectory containing the sources of the GNAT +run-time library, and the @file{adalib} subdirectory containing the +@file{ALI} files and the static and/or shared GNAT library, are located +in the gcc target-dependent area: + +@smallexample +target=$prefix/lib/gcc/gcc-@i{dumpmachine}/gcc-@i{dumpversion}/ +@end smallexample + +@noindent +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: + +@smallexample +@group + $(target-dir) + | + +--- adainclude----------+ + | | + +--- adalib-----------+ | + | | | + +--- rts-native | | + | | | | + | +--- adainclude <---+ + | | | + | +--- adalib <----+ + | + +--- rts-sjlj + | + +--- adainclude + | + +--- adalib +@end group +@end smallexample + +@noindent +If the @i{rts-sjlj} library is to be selected on a permanent basis, +these soft links can be modified with the following commands: + +@smallexample +$ cd $target +$ rm -f adainclude adalib +$ ln -s rts-sjlj/adainclude adainclude +$ ln -s rts-sjlj/adalib adalib +@end smallexample + +@noindent +Alternatively, you can specify @file{rts-sjlj/adainclude} in the file +@file{$target/ada_source_path} and @file{rts-sjlj/adalib} in +@file{$target/ada_object_path}. + +Selecting another run-time library temporarily can be +achieved by using the @option{--RTS} switch, e.g., @option{--RTS=sjlj} +@cindex @option{--RTS} option + +@node Choosing the Scheduling Policy +@section Choosing the Scheduling Policy + +@noindent +When using a POSIX threads implementation, you have a choice of several +scheduling policies: @code{SCHED_FIFO}, +@cindex @code{SCHED_FIFO} scheduling policy +@code{SCHED_RR} +@cindex @code{SCHED_RR} scheduling policy +and @code{SCHED_OTHER}. +@cindex @code{SCHED_OTHER} scheduling policy +Typically, the default is @code{SCHED_OTHER}, while using @code{SCHED_FIFO} +or @code{SCHED_RR} requires special (e.g., root) privileges. + +By default, GNAT uses the @code{SCHED_OTHER} policy. To specify +@code{SCHED_FIFO}, +@cindex @code{SCHED_FIFO} scheduling policy +you can use one of the following: + +@itemize @bullet +@item +@code{pragma Time_Slice (0.0)} +@cindex pragma Time_Slice +@item +the corresponding binder option @option{-T0} +@cindex @option{-T0} option +@item +@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} +@cindex pragma Task_Dispatching_Policy +@end itemize + +@noindent +To specify @code{SCHED_RR}, +@cindex @code{SCHED_RR} scheduling policy +you should use @code{pragma Time_Slice} with a +value greater than @code{0.0}, or else use the corresponding @option{-T} +binder option. + +@node Solaris-Specific Considerations +@section Solaris-Specific Considerations +@cindex Solaris Sparc threads libraries + +@noindent +This section addresses some topics related to the various threads libraries +on Sparc Solaris. + +@menu +* Solaris Threads Issues:: +@end menu + +@node Solaris Threads Issues +@subsection Solaris Threads Issues + +@noindent +GNAT under Solaris/Sparc 32 bits comes with an alternate tasking run-time +library based on POSIX threads --- @emph{rts-pthread}. +@cindex rts-pthread threads library +This run-time library has the advantage of being mostly shared across all +POSIX-compliant thread implementations, and it also provides under +@w{Solaris 8} the @code{PTHREAD_PRIO_INHERIT} +@cindex @code{PTHREAD_PRIO_INHERIT} policy (under rts-pthread) +and @code{PTHREAD_PRIO_PROTECT} +@cindex @code{PTHREAD_PRIO_PROTECT} policy (under rts-pthread) +semantics that can be selected using the predefined pragma +@code{Locking_Policy} +@cindex pragma Locking_Policy (under rts-pthread) +with respectively +@code{Inheritance_Locking} and @code{Ceiling_Locking} as the policy. +@cindex @code{Inheritance_Locking} (under rts-pthread) +@cindex @code{Ceiling_Locking} (under rts-pthread) + +As explained above, the native run-time library is based on the Solaris thread +library (@code{libthread}) and is the default library. + +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 @env{GNAT_PROCESSOR} +@cindex @env{GNAT_PROCESSOR} environment variable (on Sparc Solaris) +to one of the following: + +@table @code +@item -2 +Use the default configuration (run the program on all +available processors) - this is the same as having @code{GNAT_PROCESSOR} +unset + +@item -1 +Let the run-time implementation choose one processor and run the program on +that processor + +@item 0 .. Last_Proc +Run the program on the specified processor. +@code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1} +(where @code{_SC_NPROCESSORS_CONF} is a system variable). +@end table + +@node Linux-Specific Considerations +@section Linux-Specific Considerations +@cindex Linux threads libraries + +@noindent +On GNU/Linux without NPTL support (usually system with GNU C Library +older than 2.3), the signal model is not POSIX compliant, which means +that to send a signal to the process, you need to send the signal to all +threads, e.g.@: by using @code{killpg()}. + +@node AIX-Specific Considerations +@section AIX-Specific Considerations +@cindex AIX resolver library + +@noindent +On AIX, the resolver library initializes some internal structure on +the first call to @code{get*by*} functions, which are used to implement +@code{GNAT.Sockets.Get_Host_By_Name} and +@code{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 @code{GNAT.Sockets.Get_Host_By_Name} or +@code{GNAT.Sockets.Get_Host_By_Addrss} +occurs in the environment task, or use @code{pragma Storage_Size} to +specify a sufficiently large size for the stack of the task that contains +this call. + +@node Irix-Specific Considerations +@section Irix-Specific Considerations +@cindex Irix libraries + +@noindent +The GCC support libraries coming with the Irix compiler have moved to +their canonical place with respect to the general Irix ABI related +conventions. Running applications built with the default shared GNAT +run-time now requires the LD_LIBRARY_PATH environment variable to +include this location. A possible way to achieve this is to issue the +following command line on a bash prompt: + +@smallexample +@group +$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`dirname \`gcc --print-file-name=libgcc_s.so\`` +@end group +@end smallexample + +@node RTX-Specific Considerations +@section RTX-Specific Considerations +@cindex RTX libraries + +@noindent +The Real-time Extension (RTX) to Windows is based on the Windows Win32 +API. Applications can be built to work in two different modes: + +@itemize @bullet +@item +Windows executables that run in Ring 3 to utilize memory protection +(@emph{rts-rtx-w32}). + +@item +Real-time subsystem (RTSS) executables that run in Ring 0, where +performance can be optimized with RTSS applications taking precedent +over all Windows applications (@emph{rts-rtx-rtss}). This mode requires +the Microsoft linker to handle RTSS libraries. + +@end itemize + +@node HP-UX-Specific Considerations +@section HP-UX-Specific Considerations +@cindex HP-UX Scheduling + +@noindent +On HP-UX, appropriate privileges are required to change the scheduling +parameters of a task. The calling process must have appropriate +privileges or be a member of a group having @code{PRIV_RTSCHED} access to +successfully change the scheduling parameters. + +By default, GNAT uses the @code{SCHED_HPUX} policy. To have access to the +priority range 0-31 either the @code{FIFO_Within_Priorities} or the +@code{Round_Robin_Within_Priorities} scheduling policies need to be set. + +To specify the @code{FIFO_Within_Priorities} scheduling policy you can use +one of the following: + +@itemize @bullet +@item +@code{pragma Time_Slice (0.0)} +@cindex pragma Time_Slice +@item +the corresponding binder option @option{-T0} +@cindex @option{-T0} option +@item +@code{pragma Task_Dispatching_Policy (FIFO_Within_Priorities)} +@cindex pragma Task_Dispatching_Policy +@end itemize + +@noindent +To specify the @code{Round_Robin_Within_Priorities}, scheduling policy +you should use @code{pragma Time_Slice} with a +value greater than @code{0.0}, or use the corresponding @option{-T} +binder option, or set the @code{pragma Task_Dispatching_Policy +(Round_Robin_Within_Priorities)}. + +@c ******************************* +@node Example of Binder Output File +@appendix Example of Binder Output File + +@noindent +This Appendix displays the source code for @command{gnatbind}'s output +file generated for a simple ``Hello World'' program. +Comments have been added for clarification purposes. + +@smallexample @c adanocomment +@iftex +@leftskip=0cm +@end iftex +-- 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. + +with System; +package ada_main is + + Elab_Final_Code : Integer; + pragma Import (C, Elab_Final_Code, "__gnat_inside_elab_final_code"); + + -- 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: 6.0.0w (20061115)"; + pragma Export (C, GNAT_Version, "__gnat_version"); + + -- 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 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 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. + + procedure Break_Start; + pragma Import (C, Break_Start, "__gnat_break_start"); + + -- 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. + + type Version_32 is mod 2 ** 32; + u00001 : constant Version_32 := 16#7880BEB3#; + u00002 : constant Version_32 := 16#0D24CBD0#; + u00003 : constant Version_32 := 16#3283DBEB#; + u00004 : constant Version_32 := 16#2359F9ED#; + u00005 : constant Version_32 := 16#664FB847#; + u00006 : constant Version_32 := 16#68E803DF#; + u00007 : constant Version_32 := 16#5572E604#; + u00008 : constant Version_32 := 16#46B173D8#; + u00009 : constant Version_32 := 16#156A40CF#; + u00010 : constant Version_32 := 16#033DABE0#; + u00011 : constant Version_32 := 16#6AB38FEA#; + u00012 : constant Version_32 := 16#22B6217D#; + u00013 : constant Version_32 := 16#68A22947#; + u00014 : constant Version_32 := 16#18CC4A56#; + u00015 : constant Version_32 := 16#08258E1B#; + u00016 : constant Version_32 := 16#367D5222#; + u00017 : constant Version_32 := 16#20C9ECA4#; + u00018 : constant Version_32 := 16#50D32CB6#; + u00019 : constant Version_32 := 16#39A8BB77#; + u00020 : constant Version_32 := 16#5CF8FA2B#; + u00021 : constant Version_32 := 16#2F1EB794#; + u00022 : constant Version_32 := 16#31AB6444#; + u00023 : constant Version_32 := 16#1574B6E9#; + u00024 : constant Version_32 := 16#5109C189#; + u00025 : constant Version_32 := 16#56D770CD#; + u00026 : constant Version_32 := 16#02F9DE3D#; + u00027 : constant Version_32 := 16#08AB6B2C#; + u00028 : constant Version_32 := 16#3FA37670#; + u00029 : constant Version_32 := 16#476457A0#; + u00030 : constant Version_32 := 16#731E1B6E#; + u00031 : constant Version_32 := 16#23C2E789#; + u00032 : constant Version_32 := 16#0F1BD6A1#; + u00033 : constant Version_32 := 16#7C25DE96#; + u00034 : constant Version_32 := 16#39ADFFA2#; + u00035 : constant Version_32 := 16#571DE3E7#; + u00036 : constant Version_32 := 16#5EB646AB#; + u00037 : constant Version_32 := 16#4249379B#; + u00038 : constant Version_32 := 16#0357E00A#; + u00039 : constant Version_32 := 16#3784FB72#; + u00040 : constant Version_32 := 16#2E723019#; + u00041 : constant Version_32 := 16#623358EA#; + u00042 : constant Version_32 := 16#107F9465#; + u00043 : constant Version_32 := 16#6843F68A#; + u00044 : constant Version_32 := 16#63305874#; + u00045 : constant Version_32 := 16#31E56CE1#; + u00046 : constant Version_32 := 16#02917970#; + u00047 : constant Version_32 := 16#6CCBA70E#; + u00048 : constant Version_32 := 16#41CD4204#; + u00049 : constant Version_32 := 16#572E3F58#; + u00050 : constant Version_32 := 16#20729FF5#; + u00051 : constant Version_32 := 16#1D4F93E8#; + u00052 : constant Version_32 := 16#30B2EC3D#; + u00053 : constant Version_32 := 16#34054F96#; + u00054 : constant Version_32 := 16#5A199860#; + u00055 : constant Version_32 := 16#0E7F912B#; + u00056 : constant Version_32 := 16#5760634A#; + u00057 : constant Version_32 := 16#5D851835#; + + -- 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. + + pragma Export (C, u00001, "helloB"); + pragma Export (C, u00002, "system__standard_libraryB"); + pragma Export (C, u00003, "system__standard_libraryS"); + pragma Export (C, u00004, "adaS"); + pragma Export (C, u00005, "ada__text_ioB"); + pragma Export (C, u00006, "ada__text_ioS"); + pragma Export (C, u00007, "ada__exceptionsB"); + pragma Export (C, u00008, "ada__exceptionsS"); + pragma Export (C, u00009, "gnatS"); + pragma Export (C, u00010, "gnat__heap_sort_aB"); + pragma Export (C, u00011, "gnat__heap_sort_aS"); + pragma Export (C, u00012, "systemS"); + pragma Export (C, u00013, "system__exception_tableB"); + pragma Export (C, u00014, "system__exception_tableS"); + pragma Export (C, u00015, "gnat__htableB"); + pragma Export (C, u00016, "gnat__htableS"); + pragma Export (C, u00017, "system__exceptionsS"); + pragma Export (C, u00018, "system__machine_state_operationsB"); + pragma Export (C, u00019, "system__machine_state_operationsS"); + pragma Export (C, u00020, "system__machine_codeS"); + pragma Export (C, u00021, "system__storage_elementsB"); + pragma Export (C, u00022, "system__storage_elementsS"); + pragma Export (C, u00023, "system__secondary_stackB"); + pragma Export (C, u00024, "system__secondary_stackS"); + pragma Export (C, u00025, "system__parametersB"); + pragma Export (C, u00026, "system__parametersS"); + pragma Export (C, u00027, "system__soft_linksB"); + pragma Export (C, u00028, "system__soft_linksS"); + pragma Export (C, u00029, "system__stack_checkingB"); + pragma Export (C, u00030, "system__stack_checkingS"); + pragma Export (C, u00031, "system__tracebackB"); + pragma Export (C, u00032, "system__tracebackS"); + pragma Export (C, u00033, "ada__streamsS"); + pragma Export (C, u00034, "ada__tagsB"); + pragma Export (C, u00035, "ada__tagsS"); + pragma Export (C, u00036, "system__string_opsB"); + pragma Export (C, u00037, "system__string_opsS"); + pragma Export (C, u00038, "interfacesS"); + pragma Export (C, u00039, "interfaces__c_streamsB"); + pragma Export (C, u00040, "interfaces__c_streamsS"); + pragma Export (C, u00041, "system__file_ioB"); + pragma Export (C, u00042, "system__file_ioS"); + pragma Export (C, u00043, "ada__finalizationB"); + pragma Export (C, u00044, "ada__finalizationS"); + pragma Export (C, u00045, "system__finalization_rootB"); + pragma Export (C, u00046, "system__finalization_rootS"); + pragma Export (C, u00047, "system__finalization_implementationB"); + pragma Export (C, u00048, "system__finalization_implementationS"); + pragma Export (C, u00049, "system__string_ops_concat_3B"); + pragma Export (C, u00050, "system__string_ops_concat_3S"); + pragma Export (C, u00051, "system__stream_attributesB"); + pragma Export (C, u00052, "system__stream_attributesS"); + pragma Export (C, u00053, "ada__io_exceptionsS"); + pragma Export (C, u00054, "system__unsigned_typesS"); + pragma Export (C, u00055, "system__file_control_blockS"); + pragma Export (C, u00056, "ada__finalization__list_controllerB"); + pragma Export (C, u00057, "ada__finalization__list_controllerS"); + + -- BEGIN ELABORATION ORDER + -- ada (spec) + -- gnat (spec) + -- gnat.heap_sort_a (spec) + -- gnat.heap_sort_a (body) + -- gnat.htable (spec) + -- gnat.htable (body) + -- interfaces (spec) + -- system (spec) + -- system.machine_code (spec) + -- system.parameters (spec) + -- system.parameters (body) + -- interfaces.c_streams (spec) + -- interfaces.c_streams (body) + -- system.standard_library (spec) + -- ada.exceptions (spec) + -- system.exception_table (spec) + -- system.exception_table (body) + -- ada.io_exceptions (spec) + -- system.exceptions (spec) + -- system.storage_elements (spec) + -- system.storage_elements (body) + -- system.machine_state_operations (spec) + -- system.machine_state_operations (body) + -- system.secondary_stack (spec) + -- system.stack_checking (spec) + -- system.soft_links (spec) + -- system.soft_links (body) + -- system.stack_checking (body) + -- system.secondary_stack (body) + -- system.standard_library (body) + -- system.string_ops (spec) + -- system.string_ops (body) + -- ada.tags (spec) + -- ada.tags (body) + -- ada.streams (spec) + -- system.finalization_root (spec) + -- system.finalization_root (body) + -- system.string_ops_concat_3 (spec) + -- system.string_ops_concat_3 (body) + -- system.traceback (spec) + -- system.traceback (body) + -- ada.exceptions (body) + -- system.unsigned_types (spec) + -- system.stream_attributes (spec) + -- system.stream_attributes (body) + -- system.finalization_implementation (spec) + -- system.finalization_implementation (body) + -- ada.finalization (spec) + -- ada.finalization (body) + -- ada.finalization.list_controller (spec) + -- ada.finalization.list_controller (body) + -- system.file_control_block (spec) + -- system.file_io (spec) + -- system.file_io (body) + -- ada.text_io (spec) + -- ada.text_io (body) + -- hello (body) + -- END ELABORATION ORDER + +end ada_main; + +-- The following source file name pragmas allow the generated file +-- names to be unique for different main programs. They are needed +-- since the package name will always be Ada_Main. + +pragma Source_File_Name (ada_main, Spec_File_Name => "b~hello.ads"); +pragma Source_File_Name (ada_main, Body_File_Name => "b~hello.adb"); + +-- Generated package body for Ada_Main starts here + +package body ada_main is + + -- The actual finalization is performed by calling the + -- library routine in System.Standard_Library.Adafinal + + procedure Do_Finalize; + pragma Import (C, Do_Finalize, "system__standard_library__adafinal"); + + ------------- + -- adainit -- + ------------- + +@findex adainit + procedure adainit is + + -- These booleans are set to True once the associated unit has + -- been elaborated. It is also used to avoid elaborating the + -- same unit twice. + + E040 : Boolean; + pragma Import (Ada, E040, "interfaces__c_streams_E"); + + E008 : Boolean; + pragma Import (Ada, E008, "ada__exceptions_E"); + + E014 : Boolean; + pragma Import (Ada, E014, "system__exception_table_E"); + + E053 : Boolean; + pragma Import (Ada, E053, "ada__io_exceptions_E"); + + E017 : Boolean; + pragma Import (Ada, E017, "system__exceptions_E"); + + E024 : Boolean; + pragma Import (Ada, E024, "system__secondary_stack_E"); + + E030 : Boolean; + pragma Import (Ada, E030, "system__stack_checking_E"); + + E028 : Boolean; + pragma Import (Ada, E028, "system__soft_links_E"); + + E035 : Boolean; + pragma Import (Ada, E035, "ada__tags_E"); + + E033 : Boolean; + pragma Import (Ada, E033, "ada__streams_E"); + + E046 : Boolean; + pragma Import (Ada, E046, "system__finalization_root_E"); + + E048 : Boolean; + pragma Import (Ada, E048, "system__finalization_implementation_E"); + + E044 : Boolean; + pragma Import (Ada, E044, "ada__finalization_E"); + + E057 : Boolean; + pragma Import (Ada, E057, "ada__finalization__list_controller_E"); + + E055 : Boolean; + pragma Import (Ada, E055, "system__file_control_block_E"); + + E042 : Boolean; + pragma Import (Ada, E042, "system__file_io_E"); + + E006 : Boolean; + pragma Import (Ada, E006, "ada__text_io_E"); + + -- Set_Globals is a library routine that stores away the + -- value of the indicated set of global values in global + -- variables within the library. + + procedure Set_Globals + (Main_Priority : Integer; + Time_Slice_Value : Integer; + WC_Encoding : Character; + Locking_Policy : Character; + Queuing_Policy : Character; + Task_Dispatching_Policy : Character; + Adafinal : System.Address; + Unreserve_All_Interrupts : Integer; + Exception_Tracebacks : Integer); +@findex __gnat_set_globals + pragma Import (C, Set_Globals, "__gnat_set_globals"); + + -- SDP_Table_Build is a library routine used to build the + -- exception tables. See unit Ada.Exceptions in files + -- a-except.ads/adb for full details of how zero cost + -- exception handling works. This procedure, the call to + -- it, and the two following tables are all omitted if the + -- build is in longjmp/setjmp exception mode. + +@findex SDP_Table_Build +@findex Zero Cost Exceptions + procedure SDP_Table_Build + (SDP_Addresses : System.Address; + SDP_Count : Natural; + Elab_Addresses : System.Address; + Elab_Addr_Count : Natural); + pragma Import (C, SDP_Table_Build, "__gnat_SDP_Table_Build"); + + -- Table of Unit_Exception_Table addresses. Used for zero + -- cost exception handling to build the top level table. + + ST : aliased constant array (1 .. 23) of System.Address := ( + Hello'UET_Address, + Ada.Text_Io'UET_Address, + Ada.Exceptions'UET_Address, + Gnat.Heap_Sort_A'UET_Address, + System.Exception_Table'UET_Address, + System.Machine_State_Operations'UET_Address, + System.Secondary_Stack'UET_Address, + System.Parameters'UET_Address, + System.Soft_Links'UET_Address, + System.Stack_Checking'UET_Address, + System.Traceback'UET_Address, + Ada.Streams'UET_Address, + Ada.Tags'UET_Address, + System.String_Ops'UET_Address, + Interfaces.C_Streams'UET_Address, + System.File_Io'UET_Address, + Ada.Finalization'UET_Address, + System.Finalization_Root'UET_Address, + System.Finalization_Implementation'UET_Address, + System.String_Ops_Concat_3'UET_Address, + System.Stream_Attributes'UET_Address, + System.File_Control_Block'UET_Address, + Ada.Finalization.List_Controller'UET_Address); + + -- Table of addresses of elaboration routines. Used for + -- zero cost exception handling to make sure these + -- addresses are included in the top level procedure + -- address table. + + EA : aliased constant array (1 .. 23) of System.Address := ( + adainit'Code_Address, + Do_Finalize'Code_Address, + Ada.Exceptions'Elab_Spec'Address, + System.Exceptions'Elab_Spec'Address, + Interfaces.C_Streams'Elab_Spec'Address, + System.Exception_Table'Elab_Body'Address, + Ada.Io_Exceptions'Elab_Spec'Address, + System.Stack_Checking'Elab_Spec'Address, + System.Soft_Links'Elab_Body'Address, + System.Secondary_Stack'Elab_Body'Address, + Ada.Tags'Elab_Spec'Address, + Ada.Tags'Elab_Body'Address, + Ada.Streams'Elab_Spec'Address, + System.Finalization_Root'Elab_Spec'Address, + Ada.Exceptions'Elab_Body'Address, + System.Finalization_Implementation'Elab_Spec'Address, + System.Finalization_Implementation'Elab_Body'Address, + Ada.Finalization'Elab_Spec'Address, + Ada.Finalization.List_Controller'Elab_Spec'Address, + System.File_Control_Block'Elab_Spec'Address, + System.File_Io'Elab_Body'Address, + Ada.Text_Io'Elab_Spec'Address, + Ada.Text_Io'Elab_Body'Address); + + -- Start of processing for adainit + + begin + + -- Call SDP_Table_Build to build the top level procedure + -- table for zero cost exception handling (omitted in + -- longjmp/setjmp mode). + + SDP_Table_Build (ST'Address, 23, EA'Address, 23); + + -- Call Set_Globals to record various information for + -- this partition. The values are derived by the binder + -- from information stored in the ali files by the compiler. + +@findex __gnat_set_globals + Set_Globals + (Main_Priority => -1, + -- Priority of main program, -1 if no pragma Priority used + + Time_Slice_Value => -1, + -- Time slice from Time_Slice pragma, -1 if none used + + WC_Encoding => 'b', + -- Wide_Character encoding used, default is brackets + + Locking_Policy => ' ', + -- Locking_Policy used, default of space means not + -- specified, otherwise it is the first character of + -- the policy name. + + Queuing_Policy => ' ', + -- Queuing_Policy used, default of space means not + -- specified, otherwise it is the first character of + -- the policy name. + + Task_Dispatching_Policy => ' ', + -- Task_Dispatching_Policy used, default of space means + -- not specified, otherwise first character of the + -- policy name. + + Adafinal => System.Null_Address, + -- Address of Adafinal routine, not used anymore + + Unreserve_All_Interrupts => 0, + -- Set true if pragma Unreserve_All_Interrupts was used + + Exception_Tracebacks => 0); + -- Indicates if exception tracebacks are enabled + + Elab_Final_Code := 1; + + -- 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. + + if not E040 then + Interfaces.C_Streams'Elab_Spec; + end if; + E040 := True; + if not E008 then + Ada.Exceptions'Elab_Spec; + end if; + if not E014 then + System.Exception_Table'Elab_Body; + E014 := True; + end if; + if not E053 then + Ada.Io_Exceptions'Elab_Spec; + E053 := True; + end if; + if not E017 then + System.Exceptions'Elab_Spec; + E017 := True; + end if; + if not E030 then + System.Stack_Checking'Elab_Spec; + end if; + if not E028 then + System.Soft_Links'Elab_Body; + E028 := True; + end if; + E030 := True; + if not E024 then + System.Secondary_Stack'Elab_Body; + E024 := True; + end if; + if not E035 then + Ada.Tags'Elab_Spec; + end if; + if not E035 then + Ada.Tags'Elab_Body; + E035 := True; + end if; + if not E033 then + Ada.Streams'Elab_Spec; + E033 := True; + end if; + if not E046 then + System.Finalization_Root'Elab_Spec; + end if; + E046 := True; + if not E008 then + Ada.Exceptions'Elab_Body; + E008 := True; + end if; + if not E048 then + System.Finalization_Implementation'Elab_Spec; + end if; + if not E048 then + System.Finalization_Implementation'Elab_Body; + E048 := True; + end if; + if not E044 then + Ada.Finalization'Elab_Spec; + end if; + E044 := True; + if not E057 then + Ada.Finalization.List_Controller'Elab_Spec; + end if; + E057 := True; + if not E055 then + System.File_Control_Block'Elab_Spec; + E055 := True; + end if; + if not E042 then + System.File_Io'Elab_Body; + E042 := True; + end if; + if not E006 then + Ada.Text_Io'Elab_Spec; + end if; + if not E006 then + Ada.Text_Io'Elab_Body; + E006 := True; + end if; + + Elab_Final_Code := 0; + end adainit; + + -------------- + -- adafinal -- + -------------- + +@findex adafinal + procedure adafinal is + begin + Do_Finalize; + end adafinal; + + ---------- + -- main -- + ---------- + + -- main is actually a function, as in the ANSI C standard, + -- defined to return the exit status. The three parameters + -- are the argument count, argument values and environment + -- pointer. + +@findex Main Program + 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. + +@findex __gnat_initialize + procedure initialize; + pragma Import (C, initialize, "__gnat_initialize"); + + -- The finalize routine performs low level system + -- finalization using a standard library routine. The + -- routine is found in file a-final.c and in the standard + -- distribution is a dummy routine that does nothing, so + -- really this is a hook for special user finalization. + +@findex __gnat_finalize + procedure finalize; + pragma Import (C, finalize, "__gnat_finalize"); + + -- We get to the main program of the partition by using + -- pragma Import because if we try to with the unit and + -- call it Ada style, then not only do we waste time + -- recompiling it, but also, we don't really know the right + -- switches (e.g.@: identifier character set) to be used + -- to compile it. + + procedure Ada_Main_Program; + pragma Import (Ada, Ada_Main_Program, "_ada_hello"); + + -- Start of processing for main + + begin + -- Save global variables + + gnat_argc := argc; + gnat_argv := argv; + gnat_envp := envp; + + -- Call low level system initialization + + Initialize; + + -- Call our generated Ada initialization routine + + adainit; + + -- This is the point at which we want the debugger to get + -- control + + Break_Start; + + -- 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. + +@findex Object file list +-- 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 smallexample + +@noindent +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: + +@smallexample @c ada +Ada.Text_Io'Elab_Body; +@end smallexample + +@noindent +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). + +@node Elaboration Order Handling in GNAT +@appendix Elaboration Order Handling in GNAT +@cindex Order of elaboration +@cindex Elaboration control + +@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 Access-to-Subprogram Values:: +* Summary of Procedures for Elaboration Control:: +* Other Elaboration Order Considerations:: +@end menu + +@noindent +This chapter 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. + +@node Elaboration Code +@section Elaboration Code + +@noindent +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: + +@table @asis +@item Initializers for variables. +Variables declared at the library level, in package specs or bodies, can +require initialization that is performed at elaboration time, as in: +@smallexample @c ada +@cartouche +Sqrt_Half : Float := Sqrt (0.5); +@end cartouche +@end smallexample + +@item Package initialization code +Code in a @code{BEGIN-END} section at the outer level of a package body is +executed as part of the package body elaboration code. + +@item Library level task allocators +Tasks that are declared using task allocators at the library level +start executing immediately and hence can execute at elaboration time. +@end table + +@noindent +Subprogram calls are possible in any of these contexts, which means that +any arbitrary part of the program may be executed as part of the elaboration +code. It is even possible to write a program which does all its work at +elaboration time, with a null main program, although stylistically this +would usually be considered an inappropriate way to structure +a program. + +An important concern arises in the context of elaboration code: +we have to be sure that it is executed in an appropriate order. What we +have is a series of elaboration code sections, potentially one section +for each unit in the program. It is important that these execute +in the correct order. Correctness here means that, taking the above +example of the declaration of @code{Sqrt_Half}, +if some other piece of +elaboration code references @code{Sqrt_Half}, +then it must run after the +section of elaboration code that contains the declaration of +@code{Sqrt_Half}. + +There would never be any order of elaboration problem if we made a rule +that whenever you @code{with} a unit, you must elaborate both the spec and body +of that unit before elaborating the unit doing the @code{with}'ing: + +@smallexample @c ada +@group +@cartouche +with Unit_1; +package Unit_2 is @dots{} +@end cartouche +@end group +@end smallexample + +@noindent +would require that both the body and spec of @code{Unit_1} be elaborated +before the spec of @code{Unit_2}. However, a rule like that would be far too +restrictive. In particular, it would make it impossible to have routines +in separate packages that were mutually recursive. + +You might think that a clever enough compiler could look at the actual +elaboration code and determine an appropriate correct order of elaboration, +but in the general case, this is not possible. Consider the following +example. + +In the body of @code{Unit_1}, we have a procedure @code{Func_1} +that references +the variable @code{Sqrt_1}, which is declared in the elaboration code +of the body of @code{Unit_1}: + +@smallexample @c ada +@cartouche +Sqrt_1 : Float := Sqrt (0.1); +@end cartouche +@end smallexample + +@noindent +The elaboration code of the body of @code{Unit_1} also contains: + +@smallexample @c ada +@group +@cartouche +if expression_1 = 1 then + Q := Unit_2.Func_2; +end if; +@end cartouche +@end group +@end smallexample + +@noindent +@code{Unit_2} is exactly parallel, +it has a procedure @code{Func_2} that references +the variable @code{Sqrt_2}, which is declared in the elaboration code of +the body @code{Unit_2}: + +@smallexample @c ada +@cartouche +Sqrt_2 : Float := Sqrt (0.1); +@end cartouche +@end smallexample + +@noindent +The elaboration code of the body of @code{Unit_2} also contains: + +@smallexample @c ada +@group +@cartouche +if expression_2 = 2 then + Q := Unit_1.Func_1; +end if; +@end cartouche +@end group +@end smallexample + +@noindent +Now the question is, which of the following orders of elaboration is +acceptable: + +@smallexample +@group +Spec of Unit_1 +Spec of Unit_2 +Body of Unit_1 +Body of Unit_2 +@end group +@end smallexample + +@noindent +or + +@smallexample +@group +Spec of Unit_2 +Spec of Unit_1 +Body of Unit_2 +Body of Unit_1 +@end group +@end smallexample + +@noindent +If you carefully analyze the flow here, you will see that you cannot tell +at compile time the answer to this question. +If @code{expression_1} is not equal to 1, +and @code{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 @code{expression_1} /= 1 and @code{expression_2} = 2, +then the call to @code{Func_1} +will occur, but not the call to @code{Func_2.} +This means that it is essential +to elaborate the body of @code{Unit_1} before +the body of @code{Unit_2}, so the first +order of elaboration is correct and the second is wrong. + +By making @code{expression_1} and @code{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 +@section Checking the Elaboration Order + +@noindent +In some languages that involve the same kind of elaboration problems, +e.g.@: Java and C++, the programmer is expected to worry about these +ordering problems himself, 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: + +@table @asis +@item Standard rules +Some standard rules restrict the possible choice of elaboration +order. In particular, if you @code{with} a unit, then its spec is always +elaborated before the unit doing the @code{with}. Similarly, a parent +spec is always elaborated before the child spec, and finally +a spec is always elaborated before its corresponding body. + +@item Dynamic elaboration checks +@cindex Elaboration checks +@cindex Checks, elaboration +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 (@code{Program_Error}) is raised. + +@item Elaboration control +Facilities are provided for the programmer to specify the desired order +of elaboration. +@end table + +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: + +@table @asis +@item Restrictions on calls +A subprogram can only be called at elaboration time if its body +has been elaborated. The rules for elaboration given above guarantee +that the spec of the subprogram has been elaborated before the +call, but not the body. If this rule is violated, then the +exception @code{Program_Error} is raised. + +@item Restrictions on instantiations +A generic unit can only be instantiated if the body of the generic +unit has been elaborated. Again, the rules for elaboration given above +guarantee that the spec of the generic unit has been elaborated +before the instantiation, but not the body. If this rule is +violated, then the exception @code{Program_Error} is raised. +@end table + +@noindent +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 @code{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 @code{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 +@section Controlling the Elaboration Order + +@noindent +In the previous section we discussed the rules in Ada which ensure +that @code{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: + +@table @asis +@item 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: + +@smallexample @c ada +@group +@cartouche +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 cartouche +@end group +@end smallexample + +@noindent +A package that @code{with}'s @code{Definitions} may safely instantiate +@code{Definitions.Subp} because the compiler can determine that there +definitely is no package body to worry about in this case + +@item pragma Pure +@cindex pragma Pure +@findex Pure +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 pragma Preelaborate +@findex Preelaborate +@cindex pragma Preelaborate +This pragma places slightly less stringent restrictions on a unit than +does pragma Pure, +but these restrictions are still sufficient to ensure that there +are no elaboration problems with any calls to the unit. + +@item pragma Elaborate_Body +@findex Elaborate_Body +@cindex pragma Elaborate_Body +This pragma requires that the body of a unit be elaborated immediately +after its spec. Suppose a unit @code{A} has such a pragma, +and unit @code{B} does +a @code{with} of unit @code{A}. Recall that the standard rules require +the spec of unit @code{A} +to be elaborated before the @code{with}'ing unit; given the pragma in +@code{A}, we also know that the body of @code{A} +will be elaborated before @code{B}, so +that calls to @code{A} are safe and do not need a check. +@end table + +@noindent +Note that, +unlike pragma @code{Pure} and pragma @code{Preelaborate}, +the use of +@code{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 @code{Unit_1} and @code{Unit_2}. +If a programmer +marks @code{Unit_1} as @code{Elaborate_Body}, +and not @code{Unit_2,} then the order of +elaboration will be: + +@smallexample +@group +Spec of Unit_2 +Spec of Unit_1 +Body of Unit_1 +Body of Unit_2 +@end group +@end smallexample + +@noindent +Now that means that the call to @code{Func_1} in @code{Unit_2} +need not be checked, +it must be safe. But the call to @code{Func_2} in +@code{Unit_1} may still fail if +@code{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 @code{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 @code{Unit_1}/@code{Unit_2} example, if +we marked both of them as having pragma @code{Elaborate_Body}, then +clearly there would be no possible elaboration order. + +The above pragmas allow a server to guarantee safe use by clients, and +clearly this is the preferable approach. Consequently a good rule +is to mark units as @code{Pure} or @code{Preelaborate} if possible, +and if this is not possible, +mark them as @code{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: + +@table @asis +@item pragma Elaborate (unit) +@findex Elaborate +@cindex pragma Elaborate +This pragma is placed in the context clause, after a @code{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. + +@item pragma Elaborate_All (unit) +@findex Elaborate_All +@cindex pragma Elaborate_All +This is a stronger version of the Elaborate pragma. Consider the +following example: + +@smallexample +Unit A @code{with}'s unit B and calls B.Func in elab code +Unit B @code{with}'s unit C, and B.Func calls C.Func +@end smallexample + +@noindent +Now if we put a pragma @code{Elaborate (B)} +in unit @code{A}, this ensures that the +body of @code{B} is elaborated before the call, but not the +body of @code{C}, so +the call to @code{C.Func} could still cause @code{Program_Error} to +be raised. + +The effect of a pragma @code{Elaborate_All} is stronger, it requires +not only that the body of the named unit be elaborated before the +unit doing the @code{with}, but also the bodies of all units that the +named unit uses, following @code{with} links transitively. For example, +if we put a pragma @code{Elaborate_All (B)} in unit @code{A}, +then it requires +not only that the body of @code{B} be elaborated before @code{A}, +but also the +body of @code{C}, because @code{B} @code{with}'s @code{C}. +@end table + +@noindent +We are now in a position to give a usage rule in Ada for avoiding +elaboration problems, at least if dynamic dispatching and access to +subprogram values are not used. We will handle these cases separately +later. + +The rule is simple. If a unit has elaboration code that can directly or +indirectly make a call to a subprogram in a @code{with}'ed unit, or instantiate +a generic package in a @code{with}'ed unit, +then if the @code{with}'ed unit does not have +pragma @code{Pure} or @code{Preelaborate}, then the client should have +a pragma @code{Elaborate_All} +for the @code{with}'ed unit. By following this rule a client is +assured that calls can be made without risk of an exception. + +For generic subprogram instantiations, the rule can be relaxed to +require only a pragma @code{Elaborate} since elaborating the body +of a subprogram cannot cause any transitive elaboration (we are +not calling the subprogram in this case, just elaborating its +declaration). + +If this rule is not followed, then a program may be in one of four +states: + +@table @asis +@item No order exists +No order of elaboration exists which follows the rules, taking into +account any @code{Elaborate}, @code{Elaborate_All}, +or @code{Elaborate_Body} pragmas. In +this case, an Ada compiler must diagnose the situation at bind +time, and refuse to build an executable program. + +@item One or more orders exist, all incorrect +One or more acceptable elaboration orders exist, and all of them +generate an elaboration order problem. In this case, the binder +can build an executable program, but @code{Program_Error} will be raised +when the program is run. + +@item Several orders exist, some right, some incorrect +One or more acceptable elaboration orders exists, and some of them +work, and some do not. The programmer has not controlled +the order of elaboration, so the binder may or may not pick one of +the correct orders, and the program may or may not raise an +exception when it is run. This is the worst case, because it means +that the program may fail when moved to another compiler, or even +another version of the same compiler. + +@item One or more orders exists, all correct +One ore more acceptable elaboration orders exist, and all of them +work. In this case the program runs successfully. This state of +affairs can be guaranteed by following the rule we gave above, but +may be true even if the rule is not followed. +@end table + +@noindent +Note that one additional advantage of following our rules on the use +of @code{Elaborate} and @code{Elaborate_All} +is that the program continues to stay in the ideal (all orders OK) state +even if maintenance +changes some bodies of some units. Conversely, if a program that does +not follow this rule happens to be safe at some point, this state of affairs +may deteriorate silently as a result of maintenance changes. + +You may have noticed that the above discussion did not mention +the use of @code{Elaborate_Body}. This was a deliberate omission. If you +@code{with} an @code{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 @code{Elaborate_All} on such units. + +@node Controlling Elaboration in GNAT - Internal Calls +@section Controlling Elaboration in GNAT - Internal Calls + +@noindent +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: + +@smallexample @c ada +@group +@cartouche +function One return Float; + +Q : Float := One; + +function One return Float is +begin + return 1.0; +end One; +@end cartouche +@end group +@end smallexample + +@noindent +will obviously raise @code{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 @code{Program_Error}: + +@smallexample +@group +@cartouche + 1. procedure y is + 2. function One return Float; + 3. + 4. Q : Float := One; + | + >>> warning: cannot call "One" before body is elaborated + >>> warning: Program_Error will be raised at run time + + 5. + 6. function One return Float is + 7. begin + 8. return 1.0; + 9. end One; +10. +11. begin +12. null; +13. end; +@end cartouche +@end group +@end smallexample + +@noindent +Note that in this particular case, it is likely that the call is safe, because +the function @code{One} does not access any global variables. +Nevertheless in Ada, we do not want the validity of the check to depend on +the contents of the body (think about the separate compilation case), so this +is still wrong, as we discussed in the previous sections. + +The error is easily corrected by rearranging the declarations so that the +body of @code{One} appears before the declaration containing the call +(note that in Ada 95 and Ada 2005, +declarations can appear in any order, so there is no restriction that +would prevent this reordering, and if we write: + +@smallexample @c ada +@group +@cartouche +function One return Float; + +function One return Float is +begin + return 1.0; +end One; + +Q : Float := One; +@end cartouche +@end group +@end smallexample + +@noindent +then all is well, no warning is generated, and no +@code{Program_Error} exception +will be raised. +Things are more complicated when a chain of subprograms is executed: + +@smallexample @c ada +@group +@cartouche +function A return Integer; +function B return Integer; +function C return Integer; + +function B return Integer is begin return A; end; +function C return Integer is begin return B; end; + +X : Integer := C; + +function A return Integer is begin return 1; end; +@end cartouche +@end group +@end smallexample + +@noindent +Now the call to @code{C} +at elaboration time in the declaration of @code{X} is correct, because +the body of @code{C} is already elaborated, +and the call to @code{B} within the body of +@code{C} is correct, but the call +to @code{A} within the body of @code{B} is incorrect, because the body +of @code{A} has not been elaborated, so @code{Program_Error} +will be raised on the call to @code{A}. +In this case GNAT will generate a +warning that @code{Program_Error} may be +raised at the point of the call. Let's look at the warning: + +@smallexample +@group +@cartouche + 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 cartouche +@end group +@end smallexample + +@noindent +Note that the message here says ``may raise'', instead of the direct case, +where the message says ``will be raised''. That's because whether +@code{A} is +actually called depends in general on run-time flow of control. +For example, if the body of @code{B} said + +@smallexample @c ada +@group +@cartouche +function B return Integer is +begin + if some-condition-depending-on-input-data then + return A; + else + return 1; + end if; +end B; +@end cartouche +@end group +@end smallexample + +@noindent +then we could not know until run time whether the incorrect call to A would +actually occur, so @code{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 @code{Program_Error} +might be raised, but it certainly +couldn't do a perfect job (that would require solving the halting problem +and is provably impossible), and because this is a warning anyway, it does +not seem worth the effort to do the analysis. Cases in which it +would be relevant are rare. + +In practice, warnings of either of the forms given +above will usually correspond to +real errors, and should be examined carefully and eliminated. +In the rare case where a warning is bogus, it can be suppressed by any of +the following methods: + +@itemize @bullet +@item +Compile with the @option{-gnatws} switch set + +@item +Suppress @code{Elaboration_Check} for the called subprogram + +@item +Use pragma @code{Warnings_Off} to turn warnings off for the call +@end itemize + +@noindent +For the internal elaboration check case, +GNAT by default generates the +necessary run-time checks to ensure +that @code{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 +@code{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 @code{Program_Error} exception. + +@node Controlling Elaboration in GNAT - External Calls +@section Controlling Elaboration in GNAT - External Calls + +@noindent +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: + +@smallexample @c ada +@cartouche +@group +package Math is + function Sqrt (Arg : Float) return Float; +end Math; + +package body Math is + function Sqrt (Arg : Float) return Float is + begin + @dots{} + end Sqrt; +end Math; +@end group +@group +with Math; +package Stuff is + X : Float := Math.Sqrt (0.5); +end Stuff; + +with Stuff; +procedure Main is +begin + @dots{} +end Main; +@end group +@end cartouche +@end smallexample + +@noindent +where @code{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 @code{Math}, +the spec of @code{Stuff} and the body of @code{Main}). +In what order should the four separate sections of elaboration code +be executed? + +There are some restrictions in the order of elaboration that the binder +can choose. In particular, if unit U has a @code{with} +for a package @code{X}, then you +are assured that the spec of @code{X} +is elaborated before U , but you are +not assured that the body of @code{X} +is elaborated before U. +This means that in the above case, the binder is allowed to choose the +order: + +@smallexample +spec of Math +spec of Stuff +body of Math +body of Main +@end smallexample + +@noindent +but that's not good, because now the call to @code{Math.Sqrt} +that happens during +the elaboration of the @code{Stuff} +spec happens before the body of @code{Math.Sqrt} is +elaborated, and hence causes @code{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 @code{with} +first, but +that is not a general rule that can be followed in all cases. Consider + +@smallexample @c ada +@group +@cartouche +package X is @dots{} + +package Y is @dots{} + +with X; +package body Y is @dots{} + +with Y; +package body X is @dots{} +@end cartouche +@end group +@end smallexample + +@noindent +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 +@code{with} cannot work in this case: +the body of @code{X} @code{with}'s @code{Y}, +which means you would have to +elaborate the body of @code{Y} first, but that @code{with}'s @code{X}, +which means +you have to elaborate the body of @code{X} first, but @dots{} 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 @code{Program_Error} +exception to be raised, and it tries to do so (in the +above example of @code{Math/Stuff/Spec}, the GNAT binder will +by default +elaborate the body of @code{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 +@section Default Behavior in GNAT - Ensuring Safety + +@noindent +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: + +@itemize +@item +@emph{If a unit has elaboration code that can directly or indirectly make a +call to a subprogram in a @code{with}'ed unit, or instantiate a generic +package in a @code{with}'ed unit, then if the @code{with}'ed unit +does not have pragma @code{Pure} or +@code{Preelaborate}, then the client should have an +@code{Elaborate_All} pragma for the @code{with}'ed unit.} + +@emph{In the case of instantiating a generic subprogram, it is always +sufficient to have only an @code{Elaborate} pragma for the +@code{with}'ed unit.} +@end itemize + +@noindent +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 @code{Elaborate} +and @code{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 @code{Elaborate} and +@code{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 @code{Elaborate} and +@code{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 +@option{-gnatwl} +(warn on elaboration problems) switch. This will cause warning messages +to be generated indicating the missing @code{Elaborate} and +@code{Elaborate_All} pragmas. +Consider the following source program: + +@smallexample @c ada +@group +@cartouche +with k; +package j is + m : integer := k.r; +end; +@end cartouche +@end group +@end smallexample + +@noindent +where it is clear that there +should be a pragma @code{Elaborate_All} +for unit @code{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 +@option{-gnatwl} +switch, then the compiler outputs a warning: + +@smallexample +@group +@cartouche +1. with k; +2. package j is +3. m : integer := k.r; + | + >>> warning: call to "r" may raise Program_Error + >>> warning: missing pragma Elaborate_All for "k" + +4. end; +@end cartouche +@end group +@end smallexample + +@noindent +and these warnings can be used as a guide for supplying manually +the missing pragmas. It is usually a bad idea to use this warning +option during development. That's because it will warn you when +you need to put in a pragma, but cannot warn you when it is time +to take it out. So the use of pragma @code{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 @option{-gnatE} switch on the compiler (@command{gcc} or +@command{gnatmake}) command, or by the use of the configuration pragma: + +@smallexample @c ada +pragma Elaboration_Checks (DYNAMIC); +@end smallexample + +@noindent +Either approach will cause the unit affected to be compiled using the +standard dynamic run-time elaboration checks described in the Ada +Reference Manual. The static model is generally preferable, since it +is clearly safer to rely on compile and link time checks rather than +run-time checks. However, in the case of legacy code, it may be +difficult to meet the requirements of the static model. This +issue is further discussed in +@ref{What to Do If the Default Elaboration Behavior Fails}. + +Note that the static model provides a strict subset of the allowed +behavior and programs of the Ada Reference Manual, so if you do +adhere to the static model and no circularities exist, +then you are assured that your program will +work using the dynamic model, providing that you remove any +pragma Elaborate statements from the source. + +@node Treatment of Pragma Elaborate +@section Treatment of Pragma Elaborate +@cindex Pragma Elaborate + +@noindent +The use of @code{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 +@code{pragma Elaborate} is useful is when the caller knows that there +are no transitive calls, or that the called unit contains all necessary +transitive @code{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 +@code{pragma Elaborate} statements in place. Consequently, we made the +decision that GNAT in its default mode will believe that if it encounters +a @code{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 @code{pragma Elaborate} statements. +Second, when fixing circularities in existing code, you can selectively +use @code{pragma Elaborate} statements to convince the static mode of +GNAT that it need not generate an implicit @code{pragma Elaborate_All} +statement. + +When using the static mode with @option{-gnatwl}, any use of +@code{pragma Elaborate} will generate a warning about possible +problems. + +@node Elaboration Issues for Library Tasks +@section Elaboration Issues for Library Tasks +@cindex Library tasks, elaboration issues +@cindex Elaboration of library tasks + +@noindent +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 + +@smallexample @c ada +package Decls is + task Lib_Task is + entry Start; + end Lib_Task; + + type My_Int is new Integer; + + function Ident (M : My_Int) return My_Int; +end Decls; + +with Utils; +package body Decls is + task body Lib_Task is + begin + accept Start; + Utils.Put_Val (2); + end Lib_Task; + + function Ident (M : My_Int) return My_Int is + begin + return M; + end Ident; +end Decls; + +with Decls; +package Utils is + procedure Put_Val (Arg : Decls.My_Int); +end Utils; + +with Text_IO; +package body Utils is + procedure Put_Val (Arg : Decls.My_Int) is + begin + Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); + end Put_Val; +end Utils; + +with Decls; +procedure Main is +begin + Decls.Lib_Task.Start; +end; +@end smallexample + +@noindent +If the above example is compiled in the default static elaboration +mode, then a circularity occurs. The circularity comes from the call +@code{Utils.Put_Val} in the task body of @code{Decls.Lib_Task}. Since +this call occurs in elaboration code, we need an implicit pragma +@code{Elaborate_All} for @code{Utils}. This means that not only must +the spec and body of @code{Utils} be elaborated before the body +of @code{Decls}, but also the spec and body of any unit that is +@code{with'ed} by the body of @code{Utils} must also be elaborated before +the body of @code{Decls}. This is the transitive implication of +pragma @code{Elaborate_All} and it makes sense, because in general +the body of @code{Put_Val} might have a call to something in a +@code{with'ed} unit. + +In this case, the body of Utils (actually its spec) @code{with's} +@code{Decls}. Unfortunately this means that the body of @code{Decls} +must be elaborated before itself, in case there is a call from the +body of @code{Utils}. + +Here is the exact chain of events we are worrying about: + +@enumerate +@item +In the body of @code{Decls} a call is made from within the body of a library +task to a subprogram in the package @code{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. + +@item +This means that the body and spec of @code{Util} must be elaborated before +the body of @code{Decls} so that this call does not cause an access before +elaboration. + +@item +Within the body of @code{Util}, specifically within the body of +@code{Util.Put_Val} there may be calls to any unit @code{with}'ed +by this package. + +@item +One such @code{with}'ed package is package @code{Decls}, so there +might be a call to a subprogram in @code{Decls} in @code{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 @code{Decls} knowing what +is in the body of @code{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. + +@item +This means that the spec and body of @code{Decls} must also be +elaborated before we elaborate the unit containing the call, but +that unit is @code{Decls}! This means that the body of @code{Decls} +must be elaborated before itself, and that's a circularity. +@end enumerate + +@noindent +Indeed, if you add an explicit pragma @code{Elaborate_All} for @code{Utils} in +the body of @code{Decls} you will get a true Ada Reference Manual +circularity that makes the program illegal. + +In practice, we have found that problems with the static model of +elaboration in existing code often arise from library tasks, so +we must address this particular situation. + +Note that if we compile and run the program above, using the dynamic model of +elaboration (that is to say use the @option{-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 @bullet + +@item +Use the dynamic model of elaboration. + +If we use the @option{-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 +@code{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. + +@smallexample @c ada +package Decls1 is + task Lib_Task is + entry Start; + end Lib_Task; +end Decls1; + +with Utils; +package body Decls1 is + task body Lib_Task is + begin + accept Start; + Utils.Put_Val (2); + end Lib_Task; +end Decls1; + +package Decls2 is + type My_Int is new Integer; + function Ident (M : My_Int) return My_Int; +end Decls2; + +with Utils; +package body Decls2 is + function Ident (M : My_Int) return My_Int is + begin + return M; + end Ident; +end Decls2; + +with Decls2; +package Utils is + procedure Put_Val (Arg : Decls2.My_Int); +end Utils; + +with Text_IO; +package body Utils is + procedure Put_Val (Arg : Decls2.My_Int) is + begin + Text_IO.Put_Line (Decls2.My_Int'Image (Decls2.Ident (Arg))); + end Put_Val; +end Utils; + +with Decls1; +procedure Main is +begin + Decls1.Lib_Task.Start; +end; +@end smallexample + +@noindent +All we have done is to split @code{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. + +@item +Declare separate task types. + +A significant part of the problem arises because of the use of the +single task declaration form. This means that the elaboration of +the task type, and the elaboration of the task itself (i.e.@: the +creation of the task) happen at the same time. A good rule +of style in Ada is to always create explicit task types. By +following the additional step of placing task objects in separate +packages from the task type declaration, many elaboration problems +are avoided. Here is another modified example of the example program: + +@smallexample @c ada +package Decls is + task type Lib_Task_Type is + entry Start; + end Lib_Task_Type; + + type My_Int is new Integer; + + function Ident (M : My_Int) return My_Int; +end Decls; + +with Utils; +package body Decls is + task body Lib_Task_Type is + begin + accept Start; + Utils.Put_Val (2); + end Lib_Task_Type; + + function Ident (M : My_Int) return My_Int is + begin + return M; + end Ident; +end Decls; + +with Decls; +package Utils is + procedure Put_Val (Arg : Decls.My_Int); +end Utils; + +with Text_IO; +package body Utils is + procedure Put_Val (Arg : Decls.My_Int) is + begin + Text_IO.Put_Line (Decls.My_Int'Image (Decls.Ident (Arg))); + end Put_Val; +end Utils; + +with Decls; +package Declst is + Lib_Task : Decls.Lib_Task_Type; +end Declst; + +with Declst; +procedure Main is +begin + Declst.Lib_Task.Start; +end; +@end smallexample + +@noindent +What we have done here is to replace the @code{task} declaration in +package @code{Decls} with a @code{task type} declaration. Then we +introduce a separate package @code{Declst} to contain the actual +task object. This separates the elaboration issues for +the @code{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 @code{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 No_Entry_Calls_In_Elaboration_Code restriction. +@cindex No_Entry_Calls_In_Elaboration_Code + +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 @code{accept} +statement. Now of course there is nothing to prohibit elaboration +code from making entry calls (for example from another library level task), +so we cannot tell in isolation that +the task will not execute the accept statement during elaboration. + +However, in practice it is very unusual to see elaboration code +make any entry calls, and the pattern of tasks starting +at elaboration time and then immediately blocking on @code{accept} or +@code{select} statements is very common. What this means is that +the compiler is being too pessimistic when it analyzes the +whole package body as though it might be executed at elaboration +time. + +If we know that the elaboration code contains no entry calls, (a very safe +assumption most of the time, that could almost be made the default +behavior), then we can compile all units of the program under control +of the following configuration pragma: + +@smallexample +pragma Restrictions (No_Entry_Calls_In_Elaboration_Code); +@end smallexample + +@noindent +This pragma can be placed in the @file{gnat.adc} file in the usual +manner. If we take our original unmodified program and compile it +in the presence of a @file{gnat.adc} containing the above pragma, +then once again, we can compile, bind, link, and execute, obtaining +the expected result. In the presence of this pragma, the compiler does +not trace calls in a task body, that appear after the first @code{accept} +or @code{select} statement, and therefore does not report a potential +circularity in the original program. + +The compiler will check to the extent it can that the above +restriction is not violated, but it is not always possible to do a +complete check at compile time, so it is important to use this +pragma only if the stated restriction is in fact met, that is to say +no task receives an entry call before elaboration of all units is completed. + +@end itemize + +@node Mixing Elaboration Models +@section Mixing Elaboration Models +@noindent +So far, we have assumed that the entire program is either compiled +using the dynamic model or static model, ensuring consistency. It +is possible to mix the two models, but rules have to be followed +if this mixing is done to ensure that elaboration checks are not +omitted. + +The basic rule is that @emph{a unit compiled with the static model cannot +be @code{with'ed} 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 +@code{Elaborate_All} so that no elaboration checks are required +in inner subprograms, and this assumption is violated if the +client is compiled with dynamic checks. + +The precise rule is as follows. A unit that is compiled with dynamic +checks can only @code{with} a unit that meets at least one of the +following criteria: + +@itemize @bullet + +@item +The @code{with'ed} unit is itself compiled with dynamic elaboration +checks (that is with the @option{-gnatE} switch. + +@item +The @code{with'ed} unit is an internal GNAT implementation unit from +the System, Interfaces, Ada, or GNAT hierarchies. + +@item +The @code{with'ed} unit has pragma Preelaborate or pragma Pure. + +@item +The @code{with'ing} unit (that is the client) has an explicit pragma +@code{Elaborate_All} for the @code{with'ed} unit. + +@end itemize + +@noindent +If this rule is violated, that is if a unit with dynamic elaboration +checks @code{with's} a unit that does not meet one of the above four +criteria, then the binder (@code{gnatbind}) will issue a warning +similar to that in the following example: + +@smallexample +warning: "x.ads" has dynamic elaboration checks and with's +warning: "y.ads" which has static elaboration checks +@end smallexample + +@noindent +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 @option{-ws} binder switch +in the usual manner. + +One useful application of this mixing rule is in the case of a subsystem +which does not itself @code{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. + +@node What to Do If the Default Elaboration Behavior Fails +@section What to Do If the Default Elaboration Behavior Fails + +@noindent +If the binder cannot find an acceptable order, it outputs detailed +diagnostics. For example: +@smallexample +@group +@iftex +@leftskip=0cm +@end iftex +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 -gnatwl +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 group + +@end smallexample + +@noindent +In this case we have a cycle that the binder cannot break. On the one +hand, there is an explicit pragma Elaborate in @code{proc} for +@code{pack}. This means that the body of @code{pack} must be elaborated +before the body of @code{proc}. On the other hand, there is elaboration +code in @code{pack} that calls a subprogram in @code{proc}. This means +that for maximum safety, there should really be a pragma +Elaborate_All in @code{pack} for @code{proc} which would require that +the body of @code{proc} be elaborated before the body of +@code{pack}. Clearly both requirements cannot be satisfied. +Faced with a circularity of this kind, you have three different options. + +@table @asis +@item Fix the program +The most desirable option from the point of view of long-term maintenance +is to rearrange the program so that the elaboration problems are avoided. +One useful technique is to place the elaboration code into separate +child packages. Another is to move some of the initialization code to +explicitly called subprograms, where the program controls the order +of initialization explicitly. Although this is the most desirable option, +it may be impractical and involve too much modification, especially in +the case of complex legacy code. + +@item Perform dynamic checks +If the compilations are done using the +@option{-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 @code{Elaborate} or @code{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 @code{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. + +@item Suppress checks +The drawback of dynamic checks is that they generate a +significant overhead at run time, both in space and time. If you +are absolutely sure that your program cannot raise any elaboration +exceptions, and you still want to use the dynamic elaboration model, +then you can use the configuration pragma +@code{Suppress (Elaboration_Check)} to suppress all such checks. For +example this pragma could be placed in the @file{gnat.adc} file. + +@item Suppress checks selectively +When you know that certain calls or instantiations in elaboration code cannot +possibly lead to an elaboration error, and the binder nevertheless complains +about implicit @code{Elaborate} and @code{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 @code{Suppress (Elaboration_Check)} can be +used with different granularity to suppress warnings and break elaboration +circularities: + +@itemize @bullet +@item +Place the pragma that names the called subprogram in the declarative part +that contains the call. + +@item +Place the pragma in the declarative part, without naming an entity. This +disables warnings on all calls in the corresponding declarative region. + +@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. + +@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. + +@item Use Pragma Elaborate +As previously described in section @xref{Treatment of Pragma Elaborate}, +GNAT in static mode assumes that a @code{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 @code{pragma Elaborate} will be sufficient in a +case where @code{pragma Elaborate_All} would cause a circularity. +@end itemize + +@noindent +These five cases are listed in order of decreasing safety, and therefore +require increasing programmer care in their application. Consider the +following program: + +@smallexample @c adanocomment +package Pack1 is + function F1 return Integer; + X1 : Integer; +end Pack1; + +package Pack2 is + function F2 return Integer; + function Pure (x : integer) return integer; + -- pragma Suppress (Elaboration_Check, On => Pure); -- (3) + -- pragma Suppress (Elaboration_Check); -- (4) +end Pack2; + +with Pack2; +package body Pack1 is + function F1 return Integer is + begin + return 100; + end F1; + Val : integer := Pack2.Pure (11); -- Elab. call (1) +begin + declare + -- pragma Suppress(Elaboration_Check, Pack2.F2); -- (1) + -- pragma Suppress(Elaboration_Check); -- (2) + begin + X1 := Pack2.F2 + 1; -- Elab. call (2) + end; +end Pack1; + +with Pack1; +package body Pack2 is + function F2 return Integer is + begin + return Pack1.F1; + end F2; + function Pure (x : integer) return integer is + begin + return x ** 3 - 3 * x; + end; +end Pack2; + +with Pack1, Ada.Text_IO; +procedure Proc3 is +begin + Ada.Text_IO.Put_Line(Pack1.X1'Img); -- 101 +end Proc3; +@end smallexample +In the absence of any pragmas, an attempt to bind this program produces +the following diagnostics: +@smallexample +@group +@iftex +@leftskip=.5cm +@end iftex +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 -gnatwl 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 group +@end smallexample +The sources of the circularity are the two calls to @code{Pack2.Pure} and +@code{Pack2.F2} in the body of @code{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. + +@noindent +The call to @code{Pure} is safe because this function does not depend on the +state of @code{Pack2}. Therefore any call to this function is safe, and it +is correct to place pragma (3) in the corresponding package spec. + +@noindent +Finally, we could place pragma (4) in the spec of @code{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 @code{F2} requires that @code{F1} +be already elaborated. +@end table + +@noindent +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 +@option{-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 warnings generated +with the +@option{-gnatwl} +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 +@option{^-p (pessimistic elaboration order)^/PESSIMISTIC_ELABORATION_ORDER^} +switch for +@code{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 ACVC 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 +@option{-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 ACVC tests.) + +@node Elaboration for Access-to-Subprogram Values +@section Elaboration for Access-to-Subprogram Values +@cindex Access-to-subprogram + +@noindent +Access-to-subprogram types (introduced in Ada 95) complicate +the handling of elaboration. The trouble is that it becomes +impossible to tell at compile time which procedure +is being called. This means that it is not possible for the binder +to analyze the elaboration requirements in this case. + +If at the point at which the access value is created +(i.e., the evaluation of @code{P'Access} for a subprogram @code{P}), +the body of the subprogram is +known to have been elaborated, then the access value is safe, and its use +does not require a check. This may be achieved by appropriate arrangement +of the order of declarations if the subprogram is in the current unit, +or, if the subprogram is in another unit, by using pragma +@code{Pure}, @code{Preelaborate}, or @code{Elaborate_Body} +on the referenced unit. + +If the referenced body is not known to have been elaborated at the point +the access value is created, then any use of the access value must do a +dynamic check, and this dynamic check will fail and raise a +@code{Program_Error} exception if the body has not been elaborated yet. +GNAT will generate the necessary checks, and in addition, if the +@option{-gnatwl} +switch is set, will generate warnings that such checks are required. + +The use of dynamic dispatching for tagged types similarly generates +a requirement for dynamic checks, and premature calls to any primitive +operation of a tagged type before the body of the operation has been +elaborated, will result in the raising of @code{Program_Error}. + +@node Summary of Procedures for Elaboration Control +@section Summary of Procedures for Elaboration Control +@cindex Elaboration control + +@noindent +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, then use the +@option{-gnatwl} +switch to generate warnings about missing @code{Elaborate} or +@code{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 +@option{-gnatE} switch to generate dynamic elaboration checks, +and, if you are sure there really are no elaboration problems, +use a global pragma @code{Suppress (Elaboration_Check)}. + +@node Other Elaboration Order Considerations +@section Other Elaboration Order Considerations +@noindent +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: + +@smallexample @c ada +with Init_Constants; +package Constants is + X : Integer := 0; + Y : Integer := 0; +end Constants; + +package Init_Constants is + procedure P; -- require a body +end Init_Constants; + +with Constants; +package body Init_Constants is + procedure P is begin null; end; +begin + Constants.X := 3; + Constants.Y := 4; +end Init_Constants; + +with Constants; +package Calc is + Z : Integer := Constants.X + Constants.Y; +end Calc; + +with Calc; +with Text_IO; use Text_IO; +procedure Main is +begin + Put_Line (Calc.Z'Img); +end Main; +@end smallexample + +@noindent +In this example, there is more than one valid order of elaboration. For +example both the following are correct orders: + +@smallexample +Init_Constants spec +Constants spec +Calc spec +Init_Constants body +Main body + + and + +Init_Constants spec +Init_Constants body +Constants spec +Calc spec +Main body +@end smallexample + +@noindent +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 @code{Calc} initializes @code{Z} to zero, and then the main program +runs with this value of zero. But in the second order, the elaboration +routine of @code{Calc} runs after the body of Init_Constants has set +@code{X} and @code{Y} and thus @code{Z} is set to 7 before @code{Main} +runs. + +One could perhaps by applying pretty clever non-artificial intelligence +to the situation guess that it is more likely that the second order of +elaboration is the one desired, but there is no formal linguistic reason +to prefer one over the other. In fact in this particular case, GNAT will +prefer the second order, because of the rule that bodies are elaborated +as soon as possible, but it's just luck that this is what was wanted +(if indeed the second order was preferred). + +If the program cares about the order of elaboration routines in a case like +this, it is important to specify the order required. In this particular +case, that could have been achieved by adding to the spec of Calc: + +@smallexample @c ada +pragma Elaborate_All (Constants); +@end smallexample + +@noindent +which requires that the body (if any) and spec of @code{Constants}, +as well as the body and spec of any unit @code{with}'ed by +@code{Constants} be elaborated before @code{Calc} is elaborated. + +Clearly no automatic method can always guess which alternative you require, +and if you are working with legacy code that had constraints of this kind +which were not properly specified by adding @code{Elaborate} or +@code{Elaborate_All} pragmas, then indeed it is possible that two different +compilers can choose different orders. + +However, GNAT does attempt to diagnose the common situation where there +are uninitialized variables in the visible part of a package spec, and the +corresponding package body has an elaboration block that directly or +indirectly initialized one or more of these variables. This is the situation +in which a pragma Elaborate_Body is usually desirable, and GNAT will generate +a warning that suggests this addition if it detects this situation. + +The @code{gnatbind} +@option{^-p^/PESSIMISTIC_ELABORATION^} 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 @code{Elaborate} pragmas. For the example above, we have the +following output: + +@smallexample +gnatmake -f -q main +main + 7 +gnatmake -f -q main -bargs -p +main + 0 +@end smallexample + +@noindent +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 +@code{Elaborate} or @code{Elaborate_All} pragmas to ensure the desired order. + + + +@c ******************************* +@node Conditional Compilation +@appendix Conditional Compilation +@c ******************************* +@cindex Conditional compilation + +@noindent +It is often necessary to arrange for a single source program +to serve multiple purposes, where it is compiled in different +ways to achieve these different goals. Some examples of the +need for this feature are + +@itemize @bullet +@item Adapting a program to a different hardware environment +@item Adapting a program to a different target architecture +@item Turning debugging features on and off +@item Arranging for a program to compile with different compilers +@end itemize + +@noindent +In C, or C++, the typical approach would be to use the preprocessor +that is defined as part of the language. The Ada language does not +contain such a feature. This is not an oversight, but rather a very +deliberate design decision, based on the experience that overuse of +the preprocessing features in C and C++ can result in programs that +are extremely difficult to maintain. For example, if we have ten +switches that can be on or off, this means that there are a thousand +separate programs, any one of which might not even be syntactically +correct, and even if syntactically correct, the resulting program +might not work correctly. Testing all combinations can quickly become +impossible. + +Nevertheless, the need to tailor programs certainly exists, and in +this Appendix we will discuss how this can +be achieved using Ada in general, and GNAT in particular. + +@menu +* Use of Boolean Constants:: +* Debugging - A Special Case:: +* Conditionalizing Declarations:: +* Use of Alternative Implementations:: +* Preprocessing:: +@end menu + +@node Use of Boolean Constants +@section Use of Boolean Constants + +@noindent +In the case where the difference is simply which code +sequence is executed, the cleanest solution is to use Boolean +constants to control which code is executed. + +@smallexample @c ada +@group +FP_Initialize_Required : constant Boolean := True; +@dots{} +if FP_Initialize_Required then +@dots{} +end if; +@end group +@end smallexample + +@noindent +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 @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 +is turned on.) +@cindex Preprocessors (contrasted with conditional compilation) + +Typically the Boolean constants will be in a separate package, +something like: + +@smallexample @c ada +@group +package Config is + FP_Initialize_Required : constant Boolean := True; + Reset_Available : constant Boolean := False; + @dots{} +end Config; +@end group +@end smallexample + +@noindent +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 @code{with} +of @code{Config} to make the constants visible. + + +@node Debugging - A Special Case +@section Debugging - A Special Case + +@noindent +A common use of conditional code is to execute statements (for example +dynamic checks, or output of intermediate results) under control of a +debug switch, so that the debugging behavior can be turned on and off. +This can be done using a Boolean constant to control whether the code +is active: + +@smallexample @c ada +@group +if Debugging then + Put_Line ("got to the first stage!"); +end if; +@end group +@end smallexample + +@noindent +or + +@smallexample @c ada +@group +if Debugging and then Temperature > 999.0 then + raise Temperature_Crazy; +end if; +@end group +@end smallexample + +@noindent +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 @code{Assert} that can be used for such tests. This pragma is modeled +@cindex pragma @code{Assert} +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 @code{Assert} is described in +@ref{Pragma Assert,,, gnat_rm, GNAT Reference Manual}, but as an +example, the last test could be written: + +@smallexample @c ada +pragma Assert (Temperature <= 999.0, "Temperature Crazy"); +@end smallexample + +@noindent +or simply + +@smallexample @c ada +pragma Assert (Temperature <= 999.0); +@end smallexample + +@noindent +In both cases, if assertions are active and the temperature is excessive, +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. + +You can turn assertions on and off by using the @code{Assertion_Policy} +pragma. +@cindex pragma @code{Assertion_Policy} +This is an Ada 2005 pragma which is implemented in all modes by +GNAT, but only in the latest versions of GNAT which include Ada 2005 +capability. Alternatively, you can use the @option{-gnata} switch +@cindex @option{-gnata} switch +to enable assertions from the command line (this is recognized by all versions +of GNAT). + +For the example above with the @code{Put_Line}, the GNAT-specific pragma +@code{Debug} can be used: +@cindex pragma @code{Debug} + +@smallexample @c ada +pragma Debug (Put_Line ("got to the first stage!")); +@end smallexample + +@noindent +If debug pragmas are enabled, the argument, which must be of the form of +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 @code{Debug} argument as needed. + +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. + +Debug pragmas are enabled using either the @option{-gnata} switch that also +controls assertions, or with a separate Debug_Policy pragma. +@cindex pragma @code{Debug_Policy} +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 @code{Assertion_Policy} to control assertions. + +@code{Assertion_Policy} and @code{Debug_Policy} are configuration pragmas, +and thus they can appear in @file{gnat.adc} if you are not using a +project file, or in the file designated to contain configuration pragmas +in a project file. +They then apply to all subsequent compilations. In practice the use of +the @option{-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 @code{null} statement. + +@smallexample @c ada +@group +if @dots{} then + @dots{} -- some statements +else + pragma Assert (Num_Cases < 10); + null; +end if; +@end group +@end smallexample + + +@node Conditionalizing Declarations +@section Conditionalizing Declarations + +@noindent +In some cases, it may be necessary to conditionalize declarations to meet +different requirements. For example we might want a bit string whose length +is set to meet some hardware message requirement. + +In some cases, it may be possible to do this using declare blocks controlled +by conditional constants: + +@smallexample @c ada +@group +if Small_Machine then + declare + X : Bit_String (1 .. 10); + begin + @dots{} + end; +else + declare + X : Large_Bit_String (1 .. 1000); + begin + @dots{} + end; +end if; +@end group +@end smallexample + +@noindent +Note that in this approach, both declarations are analyzed by the +compiler so this can only be used where both declarations are legal, +even though one of them will not be used. + +Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, +or Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations +that are parameterized by these constants. For example + +@smallexample @c ada +@group +for Rec use + Field1 at 0 range Boolean'Pos (Little_Endian) * 10 .. Bits_Per_Word; +end record; +@end group +@end smallexample + +@noindent +If @code{Bits_Per_Word} is set to 32, this generates either + +@smallexample @c ada +@group +for Rec use + Field1 at 0 range 0 .. 32; +end record; +@end group +@end smallexample + +@noindent +for the big endian case, or + +@smallexample @c ada +@group +for Rec use record + Field1 at 0 range 10 .. 32; +end record; +@end group +@end smallexample + +@noindent +for the little endian case. Since a powerful subset of Ada expression +notation is usable for creating static constants, clever use of this +feature can often solve quite difficult problems in conditionalizing +compilation (note incidentally that in Ada 95, the little endian +constant was introduced as @code{System.Default_Bit_Order}, so you do not +need to define this one yourself). + + +@node Use of Alternative Implementations +@section Use of Alternative Implementations + +@noindent +In some cases, none of the approaches described above are adequate. This +can occur for example if the set of declarations required is radically +different for two different configurations. + +In this situation, the official Ada way of dealing with conditionalizing +such code is to write separate units for the different cases. As long as +this does not result in excessive duplication of code, this can be done +without creating maintenance problems. The approach is to share common +code as far as possible, and then isolate the code and declarations +that are different. Subunits are often a convenient method for breaking +out a piece of a unit that is to be conditionalized, with separate files +for different versions of the subunit for different targets, where the +build script selects the right one to give to the compiler. +@cindex Subunits (and conditional compilation) + +As an example, consider a situation where a new feature in Ada 2005 +allows something to be done in a really nice way. But your code must be able +to compile with an Ada 95 compiler. Conceptually you want to say: + +@smallexample @c ada +@group +if Ada_2005 then + @dots{} neat Ada 2005 code +else + @dots{} not quite as neat Ada 95 code +end if; +@end group +@end smallexample + +@noindent +where @code{Ada_2005} is a Boolean constant. + +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.) + +So instead we write + +@smallexample @c ada +procedure Insert is separate; +@end smallexample + +@noindent +Then we have two files for the subunit @code{Insert}, with the two sets of +code. +If the package containing this is called @code{File_Queries}, then we might +have two files + +@itemize @bullet +@item @file{file_queries-insert-2005.adb} +@item @file{file_queries-insert-95.adb} +@end itemize + +@noindent +and the build script renames the appropriate file to + +@smallexample +file_queries-insert.adb +@end smallexample + +@noindent +and then carries out the compilation. + +This can also be done with project files' naming schemes. For example: + +@smallexample @c project +For Body ("File_Queries.Insert") use "file_queries-insert-2005.ada"; +@end smallexample + +@noindent +Note also that with project files it is desirable to use a different extension +than @file{ads} / @file{adb} for alternative versions. Otherwise a naming +conflict may arise through another commonly used feature: to declare as part +of the project a set of directories containing all the sources obeying the +default naming scheme. + +The use of alternative units is certainly feasible in all situations, +and for example the Ada part of the GNAT run-time is conditionalized +based on the target architecture using this approach. As a specific example, +consider the implementation of the AST feature in VMS. There is one +spec: + +@smallexample +s-asthan.ads +@end smallexample + +@noindent +which is the same for all architectures, and three bodies: + +@table @file +@item s-asthan.adb +used for all non-VMS operating systems +@item s-asthan-vms-alpha.adb +used for VMS on the Alpha +@item s-asthan-vms-ia64.adb +used for VMS on the ia64 +@end table + +@noindent +The dummy version @file{s-asthan.adb} simply raises exceptions noting that +this operating system feature is not available, and the two remaining +versions interface with the corresponding versions of VMS to provide +VMS-compatible AST handling. The GNAT build script knows the architecture +and operating system, and automatically selects the right version, +renaming it if necessary to @file{s-asthan.adb} before the run-time build. + +Another style for arranging alternative implementations is through Ada's +access-to-subprogram facility. +In case some functionality is to be conditionally included, +you can declare an access-to-procedure variable @code{Ref} that is initialized +to designate a ``do nothing'' procedure, and then invoke @code{Ref.all} +when appropriate. +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 +@section Preprocessing +@cindex Preprocessing + +@noindent +Although it is quite possible to conditionalize code without the use of +C-style preprocessing, as described earlier in this section, it is +nevertheless convenient in some cases to use the C approach. Moreover, +older Ada compilers have often provided some preprocessing capability, +so legacy code may depend on this approach, even though it is not +standard. + +To accommodate such use, GNAT provides a preprocessor (modeled to a large +extent on the various preprocessors that have been used +with legacy code on other compilers, to enable easier transition). + +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 +@code{gnatprep} utility, whose use is fully described in +@ref{Preprocessing Using gnatprep}. +@cindex @code{gnatprep} + +The preprocessing language allows such constructs as + +@smallexample +@group +#if DEBUG or PRIORITY > 4 then + bunch of declarations +#else + completely different bunch of declarations +#end if; +@end group +@end smallexample + +@noindent +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 @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{Integrated Preprocessing}. + + +@c ******************************* +@node Inline Assembler +@appendix Inline Assembler +@c ******************************* + +@noindent +If you need to write low-level software that interacts directly +with the hardware, Ada provides two ways to incorporate assembly +language code into your program. First, you can import and invoke +external routines written in assembly language, an Ada feature fully +supported by GNAT@. However, for small sections of code it may be simpler +or more efficient to include assembly language statements directly +in your Ada source program, using the facilities of the implementation-defined +package @code{System.Machine_Code}, which incorporates the gcc +Inline Assembler. The Inline Assembler approach offers a number of advantages, +including the following: + +@itemize @bullet +@item No need to use non-Ada tools +@item Consistent interface over different targets +@item Automatic usage of the proper calling conventions +@item Access to Ada constants and variables +@item Definition of intrinsic routines +@item Possibility of inlining a subprogram comprising assembler code +@item Code optimizer can take Inline Assembler code into account +@end itemize + +This chapter presents a series of examples to show you how to use +the Inline Assembler. Although it focuses on the Intel x86, +the general approach applies also to other processors. +It is assumed that you are familiar with Ada +and with assembly language programming. + +@menu +* Basic Assembler Syntax:: +* A Simple Example of Inline Assembler:: +* Output Variables in Inline Assembler:: +* Input Variables in Inline Assembler:: +* Inlining Inline Assembler Code:: +* Other Asm Functionality:: +@end menu + +@c --------------------------------------------------------------------------- +@node Basic Assembler Syntax +@section Basic Assembler Syntax + +@noindent +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 +and points out the differences from the Intel conventions. +See the gcc @emph{as} and @emph{gas} (an @emph{as} macro +pre-processor) documentation for further information. + +@table @asis +@item Register names +gcc / @emph{as}: Prefix with ``%''; for example @code{%eax} +@* +Intel: No extra punctuation; for example @code{eax} + +@item Immediate operand +gcc / @emph{as}: Prefix with ``$''; for example @code{$4} +@* +Intel: No extra punctuation; for example @code{4} + +@item Address +gcc / @emph{as}: Prefix with ``$''; for example @code{$loc} +@* +Intel: No extra punctuation; for example @code{loc} + +@item Memory contents +gcc / @emph{as}: No extra punctuation; for example @code{loc} +@* +Intel: Square brackets; for example @code{[loc]} + +@item Register contents +gcc / @emph{as}: Parentheses; for example @code{(%eax)} +@* +Intel: Square brackets; for example @code{[eax]} + +@item Hexadecimal numbers +gcc / @emph{as}: Leading ``0x'' (C language syntax); for example @code{0xA0} +@* +Intel: Trailing ``h''; for example @code{A0h} + +@item Operand size +gcc / @emph{as}: Explicit in op code; for example @code{movw} to move +a 16-bit word +@* +Intel: Implicit, deduced by assembler; for example @code{mov} + +@item Instruction repetition +gcc / @emph{as}: Split into two lines; for example +@* +@code{rep} +@* +@code{stosl} +@* +Intel: Keep on one line; for example @code{rep stosl} + +@item Order of operands +gcc / @emph{as}: Source first; for example @code{movw $4, %eax} +@* +Intel: Destination first; for example @code{mov eax, 4} +@end table + +@c --------------------------------------------------------------------------- +@node A Simple Example of Inline Assembler +@section A Simple Example of Inline Assembler + +@noindent +The following example will generate a single assembly language statement, +@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. + +@smallexample @c ada +@group +with System.Machine_Code; use System.Machine_Code; +procedure Nothing is +begin + Asm ("nop"); +end Nothing; +@end group +@end smallexample + +@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. +@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 @code{Asm}; a complete specification of the syntax +is found in @ref{Machine Code Insertions,,, gnat_rm, GNAT Reference +Manual}. + +Under the standard GNAT conventions, the @code{Nothing} procedure +should be in a file named @file{nothing.adb}. +You can build the executable in the usual way: +@smallexample +gnatmake nothing +@end smallexample +However, the interesting aspect of this example is not its run-time behavior +but rather the generated assembly code. +To see this output, invoke the compiler as follows: +@smallexample + gcc -c -S -fomit-frame-pointer -gnatp @file{nothing.adb} +@end smallexample +where the options are: + +@table @code +@item -c +compile only (no bind or link) +@item -S +generate assembler listing +@item -fomit-frame-pointer +do not set up separate stack frames +@item -gnatp +do not add runtime checks +@end table + +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 @code{.s} +extension. In our example, the file @file{nothing.s} has the following +contents: + +@smallexample +@group +.file "nothing.adb" +gcc2_compiled.: +___gnu_compiled_ada: +.text + .align 4 +.globl __ada_nothing +__ada_nothing: +#APP + nop +#NO_APP + jmp L1 + .align 2,0x90 +L1: + ret +@end group +@end smallexample + +The assembly code you included is clearly indicated by +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'. + +If you make a mistake in your assembler code (such as using the +wrong size modifier, or using a wrong operand for the instruction) GNAT +will report this error in a temporary file, which will be deleted when +the compilation is finished. Generating an assembler file will help +in such cases, since you can assemble this file separately using the +@emph{as} assembler that comes with gcc. + +Assembling the file using the command + +@smallexample +as @file{nothing.s} +@end smallexample +@noindent +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 +@file{nothing.out}. + +@c --------------------------------------------------------------------------- +@node Output Variables in Inline Assembler +@section Output Variables in Inline Assembler + +@noindent +The examples in this section, showing how to access the processor flags, +illustrate how to specify the destination operands for assembly language +statements. + +@smallexample @c ada +@group +with Interfaces; use Interfaces; +with Ada.Text_IO; use Ada.Text_IO; +with System.Machine_Code; use System.Machine_Code; +procedure Get_Flags is + Flags : Unsigned_32; + use ASCII; +begin + Asm ("pushfl" & LF & HT & -- push flags on stack + "popl %%eax" & LF & HT & -- load eax with flags + "movl %%eax, %0", -- store flags in variable + Outputs => Unsigned_32'Asm_Output ("=g", Flags)); + Put_Line ("Flags register:" & Flags'Img); +end Get_Flags; +@end group +@end smallexample + +In order to have a nicely aligned assembly listing, we have separated +multiple assembler statements in the Asm template string with linefeed +(ASCII.LF) and horizontal tab (ASCII.HT) characters. +The resulting section of the assembly output file is: + +@smallexample +@group +#APP + pushfl + popl %eax + movl %eax, -40(%ebp) +#NO_APP +@end group +@end smallexample + +It would have been legal to write the Asm invocation as: + +@smallexample +Asm ("pushfl popl %%eax movl %%eax, %0") +@end smallexample + +but in the generated assembler file, this would come out as: + +@smallexample +#APP + pushfl popl %eax movl %eax, -40(%ebp) +#NO_APP +@end smallexample + +which is not so convenient for the human reader. + +We use Ada comments +at the end of each line to explain what the assembler instructions +actually do. This is a useful convention. + +When writing Inline Assembler instructions, you need to precede each register +and variable name with a percent sign. Since the assembler already requires +a percent sign at the beginning of a register name, you need two consecutive +percent signs for such names in the Asm template string, thus @code{%%eax}. +In the generated assembly code, one of the percent signs will be stripped off. + +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: +@smallexample +movl %%eax, %0 +@end smallexample +The intent is to store the contents of the eax register in a variable that can +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 @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 @code{%0} output variable. + +Information about the output variable is supplied in the @code{Outputs} +parameter to @code{Asm}: +@smallexample +Outputs => Unsigned_32'Asm_Output ("=g", Flags)); +@end smallexample + +The output is defined by the @code{Asm_Output} attribute of the target type; +the general format is +@smallexample +Type'Asm_Output (constraint_string, variable_name) +@end smallexample + +The constraint string directs the compiler how +to store/access the associated variable. In the example +@smallexample +Unsigned_32'Asm_Output ("=m", Flags); +@end smallexample +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, +@smallexample +Unsigned_32'Asm_Output ("=r", Flags); +@end smallexample +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 (@strong{=}), it tells +the compiler that the variable will be used to store data into it. + +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 +most useful (for the Intel x86 processor) are the following: + +@table @code +@item = +output constraint +@item g +global (i.e.@: can be stored anywhere) +@item m +in memory +@item I +a constant +@item a +use eax +@item b +use ebx +@item c +use ecx +@item d +use edx +@item S +use esi +@item D +use edi +@item r +use one of eax, ebx, ecx or edx +@item q +use one of eax, ebx, ecx, edx, esi or edi +@end table + +The full set of constraints is described in the gcc and @emph{as} +documentation; note that it is possible to combine certain constraints +in one constraint string. + +You specify the association of an output variable with an assembler operand +through the @code{%}@emph{n} notation, where @emph{n} is a non-negative +integer. Thus in +@smallexample @c ada +@group +Asm ("pushfl" & LF & HT & -- push flags on stack + "popl %%eax" & LF & HT & -- load eax with flags + "movl %%eax, %0", -- store flags in variable + Outputs => Unsigned_32'Asm_Output ("=g", Flags)); +@end group +@end smallexample +@noindent +@code{%0} will be replaced in the expanded code by the appropriate operand, +whatever +the compiler decided for the @code{Flags} variable. + +In general, you may have any number of output variables: +@itemize @bullet +@item +Count the operands starting at 0; thus @code{%0}, @code{%1}, etc. +@item +Specify the @code{Outputs} parameter as a parenthesized comma-separated list +of @code{Asm_Output} attributes +@end itemize + +For example: +@smallexample @c ada +@group +Asm ("movl %%eax, %0" & LF & HT & + "movl %%ebx, %1" & LF & HT & + "movl %%ecx, %2", + Outputs => (Unsigned_32'Asm_Output ("=g", Var_A), -- %0 = Var_A + Unsigned_32'Asm_Output ("=g", Var_B), -- %1 = Var_B + Unsigned_32'Asm_Output ("=g", Var_C))); -- %2 = Var_C +@end group +@end smallexample +@noindent +where @code{Var_A}, @code{Var_B}, and @code{Var_C} are variables +in the Ada program. + +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 +@code{Asm} template string: + +@smallexample @c ada +@group +with Interfaces; use Interfaces; +with Ada.Text_IO; use Ada.Text_IO; +with System.Machine_Code; use System.Machine_Code; +procedure Get_Flags_2 is + Flags : Unsigned_32; + use ASCII; +begin + Asm ("pushfl" & LF & HT & -- push flags on stack + "popl %%eax", -- save flags in eax + Outputs => Unsigned_32'Asm_Output ("=a", Flags)); + Put_Line ("Flags register:" & Flags'Img); +end Get_Flags_2; +@end group +@end smallexample + +@noindent +The @code{"a"} constraint tells the compiler that the @code{Flags} +variable will come from the eax register. Here is the resulting code: + +@smallexample +@group +#APP + pushfl + popl %eax +#NO_APP + movl %eax,-40(%ebp) +@end group +@end smallexample + +@noindent +The compiler generated the store of eax into Flags after +expanding the assembler code. + +Actually, there was no need to pop the flags into the eax register; +more simply, we could just pop the flags directly into the program variable: + +@smallexample @c ada +@group +with Interfaces; use Interfaces; +with Ada.Text_IO; use Ada.Text_IO; +with System.Machine_Code; use System.Machine_Code; +procedure Get_Flags_3 is + Flags : Unsigned_32; + use ASCII; +begin + Asm ("pushfl" & LF & HT & -- push flags on stack + "pop %0", -- save flags in Flags + Outputs => Unsigned_32'Asm_Output ("=g", Flags)); + Put_Line ("Flags register:" & Flags'Img); +end Get_Flags_3; +@end group +@end smallexample + +@c --------------------------------------------------------------------------- +@node Input Variables in Inline Assembler +@section Input Variables in Inline Assembler + +@noindent +The example in this section illustrates how to specify the source operands +for assembly language statements. +The program simply increments its input value by 1: + +@smallexample @c ada +@group +with Interfaces; use Interfaces; +with Ada.Text_IO; use Ada.Text_IO; +with System.Machine_Code; use System.Machine_Code; +procedure Increment is + + function Incr (Value : Unsigned_32) return Unsigned_32 is + Result : Unsigned_32; + begin + Asm ("incl %0", + Inputs => Unsigned_32'Asm_Input ("a", Value), + Outputs => Unsigned_32'Asm_Output ("=a", Result)); + return Result; + end Incr; + + Value : Unsigned_32; + +begin + Value := 5; + Put_Line ("Value before is" & Value'Img); + Value := Incr (Value); + Put_Line ("Value after is" & Value'Img); +end Increment; +@end group +@end smallexample + +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 @code{Result} variable. + +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, now starts at the first input +statement, and continues with the output statements. +When both parameters use the same variable, the +compiler will treat them as the same %n operand, which is the case here. + +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 +@code{Inputs} parameter cause its variable to be loaded into the register +before execution of the assembler statements. + +Thus the effect of the @code{Asm} invocation is: +@enumerate +@item load the 32-bit value of @code{Value} into eax +@item execute the @code{incl %eax} instruction +@item store the contents of eax into the @code{Result} variable +@end enumerate + +The resulting assembler file (with @option{-O2} optimization) contains: +@smallexample +@group +_increment__incr.1: + subl $4,%esp + movl 8(%esp),%eax +#APP + incl %eax +#NO_APP + movl %eax,%edx + movl %ecx,(%esp) + addl $4,%esp + ret +@end group +@end smallexample + +@c --------------------------------------------------------------------------- +@node Inlining Inline Assembler Code +@section Inlining Inline Assembler Code + +@noindent +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 @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: + +@smallexample @c ada +@group +with Interfaces; use Interfaces; +with Ada.Text_IO; use Ada.Text_IO; +with System.Machine_Code; use System.Machine_Code; +procedure Increment_2 is + + function Incr (Value : Unsigned_32) return Unsigned_32 is + Result : Unsigned_32; + begin + Asm ("incl %0", + Inputs => Unsigned_32'Asm_Input ("a", Value), + Outputs => Unsigned_32'Asm_Output ("=a", Result)); + return Result; + end Incr; + pragma Inline (Increment); + + Value : Unsigned_32; + +begin + Value := 5; + Put_Line ("Value before is" & Value'Img); + Value := Increment (Value); + Put_Line ("Value after is" & Value'Img); +end Increment_2; +@end group +@end smallexample + +Compile the program with both optimization (@option{-O2}) and inlining +(@option{-gnatn}) enabled. + +The @code{Incr} function is still compiled as usual, but at the +point in @code{Increment} where our function used to be called: + +@smallexample +@group +pushl %edi +call _increment__incr.1 +@end group +@end smallexample + +@noindent +the code for the function body directly appears: + +@smallexample +@group +movl %esi,%eax +#APP + incl %eax +#NO_APP + movl %eax,%edx +@end group +@end smallexample + +@noindent +thus saving the overhead of stack frame setup and an out-of-line call. + +@c --------------------------------------------------------------------------- +@node Other Asm Functionality +@section Other @code{Asm} Functionality + +@noindent +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:: +* The Volatile Parameter:: +@end menu + +@c --------------------------------------------------------------------------- +@node The Clobber Parameter +@subsection The @code{Clobber} Parameter + +@noindent +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., +@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 @code{mull} +storing its result in both eax and edx). +It can also arise from explicit register usage in your +assembly code; for example: +@smallexample +@group +Asm ("movl %0, %%ebx" & LF & HT & + "movl %%ebx, %1", + Inputs => Unsigned_32'Asm_Input ("g", Var_In), + Outputs => Unsigned_32'Asm_Output ("=g", Var_Out)); +@end group +@end smallexample +@noindent +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 @code{Clobber} parameter to @code{Asm}, +to identify the registers that will be used by your assembly code: + +@smallexample +@group +Asm ("movl %0, %%ebx" & LF & HT & + "movl %%ebx, %1", + Inputs => Unsigned_32'Asm_Input ("g", Var_In), + Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), + Clobber => "ebx"); +@end group +@end smallexample + +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., @code{"eax, ebx"} + +The @code{Clobber} parameter has several additional uses: +@enumerate +@item Use ``register'' name @code{cc} to indicate that flags might have changed +@item Use ``register'' name @code{memory} if you changed a memory location +@end enumerate + +@c --------------------------------------------------------------------------- +@node The Volatile Parameter +@subsection The @code{Volatile} Parameter +@cindex Volatile parameter + +@noindent +Compiler optimizations in the presence of Inline Assembler may sometimes have +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 @code{Volatile} parameter to @code{True}; for example: + +@smallexample @c ada +@group +Asm ("movl %0, %%ebx" & LF & HT & + "movl %%ebx, %1", + Inputs => Unsigned_32'Asm_Input ("g", Var_In), + Outputs => Unsigned_32'Asm_Output ("=g", Var_Out), + Clobber => "ebx", + Volatile => True); +@end group +@end smallexample + +By default, @code{Volatile} is set to @code{False} unless there is no +@code{Outputs} parameter. + +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 @code{Volatile} +to @code{True} only if the compiler's optimizations have created +problems. +@c END OF INLINE ASSEMBLER CHAPTER +@c =============================== + +@c *********************************** +@c * Compatibility and Porting Guide * +@c *********************************** +@node Compatibility and Porting Guide +@appendix Compatibility and Porting Guide + +@noindent +This chapter describes the compatibility issues that may arise between +GNAT and other Ada compilation systems (including those for Ada 83), +and shows how GNAT can expedite porting +applications developed in other Ada environments. + +@menu +* Compatibility with Ada 83:: +* Compatibility between Ada 95 and Ada 2005:: +* Implementation-dependent characteristics:: +* Compatibility with Other Ada Systems:: +* Representation Clauses:: +@ifclear vms +@c Brief section is only in non-VMS version +@c Full chapter is in VMS version +* Compatibility with HP Ada 83:: +@end ifclear +@ifset vms +* Transitioning to 64-Bit GNAT for OpenVMS:: +@end ifset +@end menu + +@node Compatibility with Ada 83 +@section Compatibility with Ada 83 +@cindex Compatibility (between Ada 83 and Ada 95 / Ada 2005) + +@noindent +Ada 95 and Ada 2005 are highly upwards compatible with Ada 83. In +particular, the design intention was that the difficulties associated +with moving from Ada 83 to Ada 95 or Ada 2005 should be no greater than those +that occur when moving from one Ada 83 system to another. + +However, there are a number of points at which there are minor +incompatibilities. The @cite{Ada 95 Annotated Reference Manual} contains +full details of these issues, +and should be consulted for a complete treatment. +In practice the +following subsections treat the most likely issues to be encountered. + +@menu +* Legal Ada 83 programs that are illegal in Ada 95:: +* More deterministic semantics:: +* Changed semantics:: +* Other language compatibility issues:: +@end menu + +@node Legal Ada 83 programs that are illegal in Ada 95 +@subsection Legal Ada 83 programs that are illegal in Ada 95 + +Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in +Ada 95 and thus also in Ada 2005: + +@table @emph +@item Character literals +Some uses of character literals are ambiguous. Since Ada 95 has introduced +@code{Wide_Character} as a new predefined character type, some uses of +character literals that were legal in Ada 83 are illegal in Ada 95. +For example: +@smallexample @c ada + for Char in 'A' .. 'Z' loop @dots{} end loop; +@end smallexample + +@noindent +The problem is that @code{'A'} and @code{'Z'} could be from either +@code{Character} or @code{Wide_Character}. The simplest correction +is to make the type explicit; e.g.: +@smallexample @c ada + for Char in Character range 'A' .. 'Z' loop @dots{} end loop; +@end smallexample + +@item New reserved words +The identifiers @code{abstract}, @code{aliased}, @code{protected}, +@code{requeue}, @code{tagged}, and @code{until} are reserved in Ada 95. +Existing Ada 83 code using any of these identifiers must be edited to +use some alternative name. + +@item Freezing rules +The rules in Ada 95 are slightly different with regard to the point at +which entities are frozen, and representation pragmas and clauses are +not permitted past the freeze point. This shows up most typically in +the form of an error message complaining that a representation item +appears too late, and the appropriate corrective action is to move +the item nearer to the declaration of the entity to which it refers. + +A particular case is that representation pragmas +@ifset vms +(including the +extended HP Ada 83 compatibility pragmas such as @code{Export_Procedure}) +@end ifset +cannot be applied to a subprogram body. If necessary, a separate subprogram +declaration must be introduced to which the pragma can be applied. + +@item Optional bodies for library packages +In Ada 83, a package that did not require a package body was nevertheless +allowed to have one. This lead to certain surprises in compiling large +systems (situations in which the body could be unexpectedly ignored by the +binder). In Ada 95, if a package does not require a body then it is not +permitted to have a body. To fix this problem, simply remove a redundant +body if it is empty, or, if it is non-empty, introduce a dummy declaration +into the spec that makes the body required. One approach is to add a private +part to the package declaration (if necessary), and define a parameterless +procedure called @code{Requires_Body}, which must then be given a dummy +procedure body in the package body, which then becomes required. +Another approach (assuming that this does not introduce elaboration +circularities) is to add an @code{Elaborate_Body} pragma to the package spec, +since one effect of this pragma is to require the presence of a package body. + +@item @code{Numeric_Error} is now the same as @code{Constraint_Error} +In Ada 95, the exception @code{Numeric_Error} is a renaming of +@code{Constraint_Error}. +This means that it is illegal to have separate exception handlers for +the two exceptions. The fix is simply to remove the handler for the +@code{Numeric_Error} case (since even in Ada 83, a compiler was free to raise +@code{Constraint_Error} in place of @code{Numeric_Error} in all cases). + +@item Indefinite subtypes in generics +In Ada 83, it was permissible to pass an indefinite type (e.g.@: @code{String}) +as the actual for a generic formal private type, but then the instantiation +would be illegal if there were any instances of declarations of variables +of this type in the generic body. In Ada 95, to avoid this clear violation +of the methodological principle known as the ``contract model'', +the generic declaration explicitly indicates whether +or not such instantiations are permitted. If a generic formal parameter +has explicit unknown discriminants, indicated by using @code{(<>)} after the +type name, then it can be instantiated with indefinite types, but no +stand-alone variables can be declared of this type. Any attempt to declare +such a variable will result in an illegality at the time the generic is +declared. If the @code{(<>)} notation is not used, then it is illegal +to instantiate the generic with an indefinite type. +This is the potential incompatibility issue when porting Ada 83 code to Ada 95. +It will show up as a compile time error, and +the fix is usually simply to add the @code{(<>)} to the generic declaration. +@end table + +@node More deterministic semantics +@subsection More deterministic semantics + +@table @emph +@item Conversions +Conversions from real types to integer types round away from 0. In Ada 83 +the conversion Integer(2.5) could deliver either 2 or 3 as its value. This +implementation freedom was intended to support unbiased rounding in +statistical applications, but in practice it interfered with portability. +In Ada 95 the conversion semantics are unambiguous, and rounding away from 0 +is required. Numeric code may be affected by this change in semantics. +Note, though, that this issue is no worse than already existed in Ada 83 +when porting code from one vendor to another. + +@item Tasking +The Real-Time Annex introduces a set of policies that define the behavior of +features that were implementation dependent in Ada 83, such as the order in +which open select branches are executed. +@end table + +@node Changed semantics +@subsection Changed semantics + +@noindent +The worst kind of incompatibility is one where a program that is legal in +Ada 83 is also legal in Ada 95 but can have an effect in Ada 95 that was not +possible in Ada 83. Fortunately this is extremely rare, but the one +situation that you should be alert to is the change in the predefined type +@code{Character} from 7-bit ASCII to 8-bit Latin-1. + +@table @emph +@item Range of type @code{Character} +The range of @code{Standard.Character} is now the full 256 characters +of Latin-1, whereas in most Ada 83 implementations it was restricted +to 128 characters. Although some of the effects of +this change will be manifest in compile-time rejection of legal +Ada 83 programs it is possible for a working Ada 83 program to have +a different effect in Ada 95, one that was not permitted in Ada 83. +As an example, the expression +@code{Character'Pos(Character'Last)} returned @code{127} in Ada 83 and now +delivers @code{255} as its value. +In general, you should look at the logic of any +character-processing Ada 83 program and see whether it needs to be adapted +to work correctly with Latin-1. Note that the predefined Ada 95 API has a +character handling package that may be relevant if code needs to be adapted +to account for the additional Latin-1 elements. +The desirable fix is to +modify the program to accommodate the full character set, but in some cases +it may be convenient to define a subtype or derived type of Character that +covers only the restricted range. +@cindex Latin-1 +@end table + +@node Other language compatibility issues +@subsection Other language compatibility issues + +@table @emph +@item @option{-gnat83} switch +All implementations of GNAT provide a switch that causes GNAT to operate +in Ada 83 mode. In this mode, some but not all compatibility problems +of the type described above are handled automatically. For example, the +new reserved words introduced in Ada 95 and Ada 2005 are treated simply +as identifiers as in Ada 83. +However, +in practice, it is usually advisable to make the necessary modifications +to the program to remove the need for using this switch. +See @ref{Compiling Different Versions of Ada}. + +@item Support for removed Ada 83 pragmas and attributes +A number of pragmas and attributes from Ada 83 were removed from Ada 95, +generally because they were replaced by other mechanisms. Ada 95 and Ada 2005 +compilers are allowed, but not required, to implement these missing +elements. In contrast with some other compilers, GNAT implements all +such pragmas and attributes, eliminating this compatibility concern. These +include @code{pragma Interface} and the floating point type attributes +(@code{Emax}, @code{Mantissa}, etc.), among other items. +@end table + + +@node Compatibility between Ada 95 and Ada 2005 +@section Compatibility between Ada 95 and Ada 2005 +@cindex Compatibility between Ada 95 and Ada 2005 + +@noindent +Although Ada 2005 was designed to be upwards compatible with Ada 95, there are +a number of incompatibilities. Several are enumerated below; +for a complete description please see the +Annotated Ada 2005 Reference Manual, or section 9.1.1 in +@cite{Rationale for Ada 2005}. + +@table @emph +@item New reserved words. +The words @code{interface}, @code{overriding} and @code{synchronized} are +reserved in Ada 2005. +A pre-Ada 2005 program that uses any of these as an identifier will be +illegal. + +@item New declarations in predefined packages. +A number of packages in the predefined environment contain new declarations: +@code{Ada.Exceptions}, @code{Ada.Real_Time}, @code{Ada.Strings}, +@code{Ada.Strings.Fixed}, @code{Ada.Strings.Bounded}, +@code{Ada.Strings.Unbounded}, @code{Ada.Strings.Wide_Fixed}, +@code{Ada.Strings.Wide_Bounded}, @code{Ada.Strings.Wide_Unbounded}, +@code{Ada.Tags}, @code{Ada.Text_IO}, and @code{Interfaces.C}. +If an Ada 95 program does a @code{with} and @code{use} of any of these +packages, the new declarations may cause name clashes. + +@item Access parameters. +A nondispatching subprogram with an access parameter cannot be renamed +as a dispatching operation. This was permitted in Ada 95. + +@item Access types, discriminants, and constraints. +Rule changes in this area have led to some incompatibilities; for example, +constrained subtypes of some access types are not permitted in Ada 2005. + +@item Aggregates for limited types. +The allowance of aggregates for limited types in Ada 2005 raises the +possibility of ambiguities in legal Ada 95 programs, since additional types +now need to be considered in expression resolution. + +@item Fixed-point multiplication and division. +Certain expressions involving ``*'' or ``/'' for a fixed-point type, which +were legal in Ada 95 and invoked the predefined versions of these operations, +are now ambiguous. +The ambiguity may be resolved either by applying a type conversion to the +expression, or by explicitly invoking the operation from package +@code{Standard}. + +@item Return-by-reference types. +The Ada 95 return-by-reference mechanism has been removed. Instead, the user +can declare a function returning a value from an anonymous access type. +@end table + + +@node Implementation-dependent characteristics +@section Implementation-dependent characteristics +@noindent +Although the Ada language defines the semantics of each construct as +precisely as practical, in some situations (for example for reasons of +efficiency, or where the effect is heavily dependent on the host or target +platform) the implementation is allowed some freedom. In porting Ada 83 +code to GNAT, you need to be aware of whether / how the existing code +exercised such implementation dependencies. Such characteristics fall into +several categories, and GNAT offers specific support in assisting the +transition from certain Ada 83 compilers. + +@menu +* Implementation-defined pragmas:: +* Implementation-defined attributes:: +* Libraries:: +* Elaboration order:: +* Target-specific aspects:: +@end menu + +@node Implementation-defined pragmas +@subsection Implementation-defined pragmas + +@noindent +Ada compilers are allowed to supplement the language-defined pragmas, and +these are a potential source of non-portability. All GNAT-defined pragmas +are described in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT +Reference Manual}, and these include several that are specifically +intended to correspond to other vendors' Ada 83 pragmas. +For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful. +For compatibility with HP Ada 83, GNAT supplies the pragmas +@code{Extend_System}, @code{Ident}, @code{Inline_Generic}, +@code{Interface_Name}, @code{Passive}, @code{Suppress_All}, +and @code{Volatile}. +Other relevant pragmas include @code{External} and @code{Link_With}. +Some vendor-specific +Ada 83 pragmas (@code{Share_Generic}, @code{Subtitle}, and @code{Title}) are +recognized, thus +avoiding compiler rejection of units that contain such pragmas; they are not +relevant in a GNAT context and hence are not otherwise implemented. + +@node Implementation-defined attributes +@subsection Implementation-defined attributes + +Analogous to pragmas, the set of attributes may be extended by an +implementation. All GNAT-defined attributes are described in +@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference +Manual}, and these include several that are specifically intended +to correspond to other vendors' Ada 83 attributes. For migrating from VADS, +the attribute @code{VADS_Size} may be useful. For compatibility with HP +Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and +@code{Type_Class}. + +@node Libraries +@subsection Libraries +@noindent +Vendors may supply libraries to supplement the standard Ada API. If Ada 83 +code uses vendor-specific libraries then there are several ways to manage +this in Ada 95 or Ada 2005: +@enumerate +@item +If the source code for the libraries (specs and bodies) are +available, then the libraries can be migrated in the same way as the +application. +@item +If the source code for the specs but not the bodies are +available, then you can reimplement the bodies. +@item +Some features introduced by Ada 95 obviate the need for library support. For +example most Ada 83 vendors supplied a package for unsigned integers. The +Ada 95 modular type feature is the preferred way to handle this need, so +instead of migrating or reimplementing the unsigned integer package it may +be preferable to retrofit the application using modular types. +@end enumerate + +@node Elaboration order +@subsection Elaboration order +@noindent +The implementation can choose any elaboration order consistent with the unit +dependency relationship. This freedom means that some orders can result in +Program_Error being raised due to an ``Access Before Elaboration'': an attempt +to invoke a subprogram its body has been elaborated, or to instantiate a +generic before the generic body has been elaborated. By default GNAT +attempts to choose a safe order (one that will not encounter access before +elaboration problems) by implicitly inserting @code{Elaborate} or +@code{Elaborate_All} pragmas where +needed. However, this can lead to the creation of elaboration circularities +and a resulting rejection of the program by gnatbind. This issue is +thoroughly described in @ref{Elaboration Order Handling in GNAT}. +In brief, there are several +ways to deal with this situation: + +@itemize @bullet +@item +Modify the program to eliminate the circularities, e.g.@: by moving +elaboration-time code into explicitly-invoked procedures +@item +Constrain the elaboration order by including explicit @code{Elaborate_Body} or +@code{Elaborate} pragmas, and then inhibit the generation of implicit +@code{Elaborate_All} +pragmas either globally (as an effect of the @option{-gnatE} switch) or locally +(by selectively suppressing elaboration checks via pragma +@code{Suppress(Elaboration_Check)} when it is safe to do so). +@end itemize + +@node Target-specific aspects +@subsection Target-specific aspects +@noindent +Low-level applications need to deal with machine addresses, data +representations, interfacing with assembler code, and similar issues. If +such an Ada 83 application is being ported to different target hardware (for +example where the byte endianness has changed) then you will need to +carefully examine the program logic; the porting effort will heavily depend +on the robustness of the original design. Moreover, Ada 95 (and thus +Ada 2005) are sometimes +incompatible with typical Ada 83 compiler practices regarding implicit +packing, the meaning of the Size attribute, and the size of access values. +GNAT's approach to these issues is described in @ref{Representation Clauses}. + +@node Compatibility with Other Ada Systems +@section Compatibility with Other Ada Systems + +@noindent +If programs avoid the use of implementation dependent and +implementation defined features, as documented in the @cite{Ada +Reference Manual}, there should be a high degree of portability between +GNAT and other Ada systems. The following are specific items which +have proved troublesome in moving Ada 95 programs from GNAT to other Ada 95 +compilers, but do not affect porting code to GNAT@. +(As of @value{NOW}, GNAT is the only compiler available for Ada 2005; +the following issues may or may not arise for Ada 2005 programs +when other compilers appear.) + +@table @emph +@item Ada 83 Pragmas and Attributes +Ada 95 compilers are allowed, but not required, to implement the missing +Ada 83 pragmas and attributes that are no longer defined in Ada 95. +GNAT implements all such pragmas and attributes, eliminating this as +a compatibility concern, but some other Ada 95 compilers reject these +pragmas and attributes. + +@item Specialized Needs Annexes +GNAT implements the full set of special needs annexes. At the +current time, it is the only Ada 95 compiler to do so. This means that +programs making use of these features may not be portable to other Ada +95 compilation systems. + +@item Representation Clauses +Some other Ada 95 compilers implement only the minimal set of +representation clauses required by the Ada 95 reference manual. GNAT goes +far beyond this minimal set, as described in the next section. +@end table + +@node Representation Clauses +@section Representation Clauses + +@noindent +The Ada 83 reference manual was quite vague in describing both the minimal +required implementation of representation clauses, and also their precise +effects. Ada 95 (and thus also Ada 2005) are much more explicit, but the +minimal set of capabilities required is still quite limited. + +GNAT implements the full required set of capabilities in +Ada 95 and Ada 2005, but also goes much further, and in particular +an effort has been made to be compatible with existing Ada 83 usage to the +greatest extent possible. + +A few cases exist in which Ada 83 compiler behavior is incompatible with +the requirements in Ada 95 (and thus also Ada 2005). These are instances of +intentional or accidental dependence on specific implementation dependent +characteristics of these Ada 83 compilers. The following is a list of +the cases most likely to arise in existing Ada 83 code. + +@table @emph +@item Implicit Packing +Some Ada 83 compilers allowed a Size specification to cause implicit +packing of an array or record. This could cause expensive implicit +conversions for change of representation in the presence of derived +types, and the Ada design intends to avoid this possibility. +Subsequent AI's were issued to make it clear that such implicit +change of representation in response to a Size clause is inadvisable, +and this recommendation is represented explicitly in the Ada 95 (and Ada 2005) +Reference Manuals as implementation advice that is followed by GNAT@. +The problem will show up as an error +message rejecting the size clause. The fix is simply to provide +the explicit pragma @code{Pack}, or for more fine tuned control, provide +a Component_Size clause. + +@item Meaning of Size Attribute +The Size attribute in Ada 95 (and Ada 2005) for discrete types is defined as +the minimal number of bits required to hold values of the type. For example, +on a 32-bit machine, the size of @code{Natural} will typically be 31 and not +32 (since no sign bit is required). Some Ada 83 compilers gave 31, and +some 32 in this situation. This problem will usually show up as a compile +time error, but not always. It is a good idea to check all uses of the +'Size attribute when porting Ada 83 code. The GNAT specific attribute +Object_Size can provide a useful way of duplicating the behavior of +some Ada 83 compiler systems. + +@item Size of Access Types +A common assumption in Ada 83 code is that an access type is in fact a pointer, +and that therefore it will be the same size as a System.Address value. This +assumption is true for GNAT in most cases with one exception. For the case of +a pointer to an unconstrained array type (where the bounds may vary from one +value of the access type to another), the default is to use a ``fat pointer'', +which is represented as two separate pointers, one to the bounds, and one to +the array. This representation has a number of advantages, including improved +efficiency. However, it may cause some difficulties in porting existing Ada 83 +code which makes the assumption that, for example, pointers fit in 32 bits on +a machine with 32-bit addressing. + +To get around this problem, GNAT also permits the use of ``thin pointers'' for +access types in this case (where the designated type is an unconstrained array +type). These thin pointers are indeed the same size as a System.Address value. +To specify a thin pointer, use a size clause for the type, for example: + +@smallexample @c ada +type X is access all String; +for X'Size use Standard'Address_Size; +@end smallexample + +@noindent +which will cause the type X to be represented using a single pointer. +When using this representation, the bounds are right behind the array. +This representation is slightly less efficient, and does not allow quite +such flexibility in the use of foreign pointers or in using the +Unrestricted_Access attribute to create pointers to non-aliased objects. +But for any standard portable use of the access type it will work in +a functionally correct manner and allow porting of existing code. +Note that another way of forcing a thin pointer representation +is to use a component size clause for the element size in an array, +or a record representation clause for an access field in a record. +@end table + +@ifclear vms +@c This brief section is only in the non-VMS version +@c The complete chapter on HP Ada is in the VMS version +@node Compatibility with HP Ada 83 +@section Compatibility with HP Ada 83 + +@noindent +The VMS version of GNAT fully implements all the pragmas and attributes +provided by HP Ada 83, as well as providing the standard HP Ada 83 +libraries, including Starlet. In addition, data layouts and parameter +passing conventions are highly compatible. This means that porting +existing HP Ada 83 code to GNAT in VMS systems should be easier than +most other porting efforts. The following are some of the most +significant differences between GNAT and HP Ada 83. + +@table @emph +@item Default floating-point representation +In GNAT, the default floating-point format is IEEE, whereas in HP Ada 83, +it is VMS format. GNAT does implement the necessary pragmas +(Long_Float, Float_Representation) for changing this default. + +@item System +The package System in GNAT exactly corresponds to the definition in the +Ada 95 reference manual, which means that it excludes many of the +HP Ada 83 extensions. However, a separate package Aux_DEC is provided +that contains the additional definitions, and a special pragma, +Extend_System allows this package to be treated transparently as an +extension of package System. + +@item To_Address +The definitions provided by Aux_DEC are exactly compatible with those +in the HP Ada 83 version of System, with one exception. +HP Ada provides the following declarations: + +@smallexample @c ada +TO_ADDRESS (INTEGER) +TO_ADDRESS (UNSIGNED_LONGWORD) +TO_ADDRESS (@i{universal_integer}) +@end smallexample + +@noindent +The version of TO_ADDRESS taking a @i{universal integer} argument is in fact +an extension to Ada 83 not strictly compatible with the reference manual. +In GNAT, we are constrained to be exactly compatible with the standard, +and this means we cannot provide this capability. In HP Ada 83, the +point of this definition is to deal with a call like: + +@smallexample @c ada +TO_ADDRESS (16#12777#); +@end smallexample + +@noindent +Normally, according to the Ada 83 standard, one would expect this to be +ambiguous, since it matches both the INTEGER and UNSIGNED_LONGWORD forms +of TO_ADDRESS@. However, in HP Ada 83, there is no ambiguity, since the +definition using @i{universal_integer} takes precedence. + +In GNAT, since the version with @i{universal_integer} cannot be supplied, it +is not possible to be 100% compatible. Since there are many programs using +numeric constants for the argument to TO_ADDRESS, the decision in GNAT was +to change the name of the function in the UNSIGNED_LONGWORD case, so the +declarations provided in the GNAT version of AUX_Dec are: + +@smallexample @c ada +function To_Address (X : Integer) return Address; +pragma Pure_Function (To_Address); + +function To_Address_Long (X : Unsigned_Longword) + return Address; +pragma Pure_Function (To_Address_Long); +@end smallexample + +@noindent +This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must +change the name to TO_ADDRESS_LONG@. + +@item Task_Id values +The Task_Id values assigned will be different in the two systems, and GNAT +does not provide a specified value for the Task_Id of the environment task, +which in GNAT is treated like any other declared task. +@end table + +@noindent +For full details on these and other less significant compatibility issues, +see appendix E of the HP publication entitled @cite{HP Ada, Technical +Overview and Comparison on HP Platforms}. + +For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and +attributes are recognized, although only a subset of them can sensibly +be implemented. The description of pragmas in @ref{Implementation +Defined Pragmas,,, gnat_rm, GNAT Reference Manual} +indicates whether or not they are applicable to non-VMS systems. +@end ifclear + +@ifset vms +@node Transitioning to 64-Bit GNAT for OpenVMS +@section Transitioning to 64-Bit @value{EDITION} for OpenVMS + +@noindent +This section is meant to assist users of pre-2006 @value{EDITION} +for Alpha OpenVMS who are transitioning to 64-bit @value{EDITION}, +the version of the GNAT technology supplied in 2006 and later for +OpenVMS on both Alpha and I64. + +@menu +* Introduction to transitioning:: +* Migration of 32 bit code:: +* Taking advantage of 64 bit addressing:: +* Technical details:: +@end menu + +@node Introduction to transitioning +@subsection Introduction + +@noindent +64-bit @value{EDITION} for Open VMS has been designed to meet +three main goals: + +@enumerate +@item +Providing a full conforming implementation of Ada 95 and Ada 2005 + +@item +Allowing maximum backward compatibility, thus easing migration of existing +Ada source code + +@item +Supplying a path for exploiting the full 64-bit address range +@end enumerate + +@noindent +Ada's strong typing semantics has made it +impractical to have different 32-bit and 64-bit modes. As soon as +one object could possibly be outside the 32-bit address space, this +would make it necessary for the @code{System.Address} type to be 64 bits. +In particular, this would cause inconsistencies if 32-bit code is +called from 64-bit code that raises an exception. + +This issue has been resolved by always using 64-bit addressing +at the system level, but allowing for automatic conversions between +32-bit and 64-bit addresses where required. Thus users who +do not currently require 64-bit addressing capabilities, can +recompile their code with only minimal changes (and indeed +if the code is written in portable Ada, with no assumptions about +the size of the @code{Address} type, then no changes at all are necessary). +At the same time, +this approach provides a simple, gradual upgrade path to future +use of larger memories than available for 32-bit systems. +Also, newly written applications or libraries will by default +be fully compatible with future systems exploiting 64-bit +addressing capabilities. + +@ref{Migration of 32 bit code}, will focus on porting applications +that do not require more than 2 GB of +addressable memory. This code will be referred to as +@emph{32-bit code}. +For applications intending to exploit the full 64-bit address space, +@ref{Taking advantage of 64 bit addressing}, +will consider further changes that may be required. +Such code will be referred to below as @emph{64-bit code}. + +@node Migration of 32 bit code +@subsection Migration of 32-bit code + +@menu +* Address types:: +* Access types and 32/64-bit allocation:: +* Unchecked conversions:: +* Predefined constants:: +* Interfacing with C:: +* 32/64-bit descriptors:: +* Experience with source compatibility:: +@end menu + +@node Address types +@subsubsection Address types + +@noindent +To solve the problem of mixing 64-bit and 32-bit addressing, +while maintaining maximum backward compatibility, the following +approach has been taken: + +@itemize @bullet +@item +@code{System.Address} always has a size of 64 bits +@cindex @code{System.Address} size +@cindex @code{Address} size + +@item +@code{System.Short_Address} is a 32-bit subtype of @code{System.Address} +@cindex @code{System.Short_Address} size +@cindex @code{Short_Address} size +@end itemize + +@noindent +Since @code{System.Short_Address} is a subtype of @code{System.Address}, +a @code{Short_Address} +may be used where an @code{Address} is required, and vice versa, without +needing explicit type conversions. +By virtue of the Open VMS parameter passing conventions, +even imported +and exported subprograms that have 32-bit address parameters are +compatible with those that have 64-bit address parameters. +(See @ref{Making code 64 bit clean} for details.) + +The areas that may need attention are those where record types have +been defined that contain components of the type @code{System.Address}, and +where objects of this type are passed to code expecting a record layout with +32-bit addresses. + +Different compilers on different platforms cannot be +expected to represent the same type in the same way, +since alignment constraints +and other system-dependent properties affect the compiler's decision. +For that reason, Ada code +generally uses representation clauses to specify the expected +layout where required. + +If such a representation clause uses 32 bits for a component having +the type @code{System.Address}, 64-bit @value{EDITION} for OpenVMS +will detect that error and produce a specific diagnostic message. +The developer should then determine whether the representation +should be 64 bits or not and make either of two changes: +change the size to 64 bits and leave the type as @code{System.Address}, or +leave the size as 32 bits and change the type to @code{System.Short_Address}. +Since @code{Short_Address} is a subtype of @code{Address}, no changes are +required in any code setting or accessing the field; the compiler will +automatically perform any needed conversions between address +formats. + +@node Access types and 32/64-bit allocation +@subsubsection Access types and 32/64-bit allocation +@cindex 32-bit allocation +@cindex 64-bit allocation + +@noindent +By default, objects designated by access values are always allocated in +the 64-bit address space, and access values themselves are represented +in 64 bits. If these defaults are not appropriate, and 32-bit allocation +is required (for example if the address of an allocated object is assigned +to a @code{Short_Address} variable), then several alternatives are available: + +@itemize @bullet +@item +A pool-specific access type (ie, an @w{Ada 83} access type, whose +definition is @code{access T} versus @code{access all T} or +@code{access constant T}), may be declared with a @code{'Size} representation +clause that establishes the size as 32 bits. +In such circumstances allocations for that type will +be from the 32-bit heap. Such a clause is not permitted +for a general access type (declared with @code{access all} or +@code{access constant}) as values of such types must be able to refer +to any object of the designated type, including objects residing outside +the 32-bit address range. Existing @w{Ada 83} code will not contain such +type definitions, however, since general access types were introduced +in @w{Ada 95}. + +@item +Switches for @command{GNAT BIND} control whether the internal GNAT +allocation routine @code{__gnat_malloc} uses 64-bit or 32-bit allocations. +@cindex @code{__gnat_malloc} +The switches are respectively @option{-H64} (the default) and +@option{-H32}. +@cindex @option{-H32} (@command{gnatbind}) +@cindex @option{-H64} (@command{gnatbind}) + +@item +The environment variable (logical name) @code{GNAT$NO_MALLOC_64} +@cindex @code{GNAT$NO_MALLOC_64} environment variable +may be used to force @code{__gnat_malloc} to use 32-bit allocation. +If this variable is left +undefined, or defined as @code{"DISABLE"}, @code{"FALSE"}, or @code{"0"}, +then the default (64-bit) allocation is used. +If defined as @code{"ENABLE"}, @code{"TRUE"}, or @code{"1"}, +then 32-bit allocation is used. The gnatbind qualifiers described above +override this logical name. + +@item +A ^gcc switch^gcc switch^ for OpenVMS, @option{-mno-malloc64}, operates +@cindex @option{-mno-malloc64} (^gcc^gcc^) +at a low level to convert explicit calls to @code{malloc} and related +functions from the C run-time library so that they perform allocations +in the 32-bit heap. +Since all internal allocations from GNAT use @code{__gnat_malloc}, +this switch is not required unless the program makes explicit calls on +@code{malloc} (or related functions) from interfaced C code. +@end itemize + + +@node Unchecked conversions +@subsubsection Unchecked conversions + +@noindent +In the case of an @code{Unchecked_Conversion} where the source type is a +64-bit access type or the type @code{System.Address}, and the target +type is a 32-bit type, the compiler will generate a warning. +Even though the generated code will still perform the required +conversions, it is highly recommended in these cases to use +respectively a 32-bit access type or @code{System.Short_Address} +as the source type. + +@node Predefined constants +@subsubsection Predefined constants + +@noindent +The following table shows the correspondence between pre-2006 versions of +@value{EDITION} on Alpha OpenVMS (``Old'') and 64-bit @value{EDITION} +(``New''): + +@multitable {@code{System.Short_Memory_Size}} {2**32} {2**64} +@item @b{Constant} @tab @b{Old} @tab @b{New} +@item @code{System.Word_Size} @tab 32 @tab 64 +@item @code{System.Memory_Size} @tab 2**32 @tab 2**64 +@item @code{System.Short_Memory_Size} @tab 2**32 @tab 2**32 +@item @code{System.Address_Size} @tab 32 @tab 64 +@end multitable + +@noindent +If you need to refer to the specific +memory size of a 32-bit implementation, instead of the +actual memory size, use @code{System.Short_Memory_Size} +rather than @code{System.Memory_Size}. +Similarly, references to @code{System.Address_Size} may need +to be replaced by @code{System.Short_Address'Size}. +The program @command{gnatfind} may be useful for locating +references to the above constants, so that you can verify that they +are still correct. + +@node Interfacing with C +@subsubsection Interfacing with C + +@noindent +In order to minimize the impact of the transition to 64-bit addresses on +legacy programs, some fundamental types in the @code{Interfaces.C} +package hierarchy continue to be represented in 32 bits. +These types are: @code{ptrdiff_t}, @code{size_t}, and @code{chars_ptr}. +This eases integration with the default HP C layout choices, for example +as found in the system routines in @code{DECC$SHR.EXE}. +Because of this implementation choice, the type fully compatible with +@code{chars_ptr} is now @code{Short_Address} and not @code{Address}. +Depending on the context the compiler will issue a +warning or an error when type @code{Address} is used, alerting the user to a +potential problem. Otherwise 32-bit programs that use +@code{Interfaces.C} should normally not require code modifications + +The other issue arising with C interfacing concerns pragma @code{Convention}. +For VMS 64-bit systems, there is an issue of the appropriate default size +of C convention pointers in the absence of an explicit size clause. The HP +C compiler can choose either 32 or 64 bits depending on compiler options. +GNAT chooses 32-bits rather than 64-bits in the default case where no size +clause is given. This proves a better choice for porting 32-bit legacy +applications. In order to have a 64-bit representation, it is necessary to +specify a size representation clause. For example: + +@smallexample @c ada +type int_star is access Interfaces.C.int; +pragma Convention(C, int_star); +for int_star'Size use 64; -- Necessary to get 64 and not 32 bits +@end smallexample + +@node 32/64-bit descriptors +@subsubsection 32/64-bit descriptors + +@noindent +By default, GNAT uses a 64-bit descriptor mechanism. For an imported +subprogram (i.e., a subprogram identified by pragma @code{Import_Function}, +@code{Import_Procedure}, or @code{Import_Valued_Procedure}) that specifies +@code{Short_Descriptor} as its mechanism, a 32-bit descriptor is used. +@cindex @code{Short_Descriptor} mechanism for imported subprograms + +If the configuration pragma @code{Short_Descriptors} is supplied, then +all descriptors will be 32 bits. +@cindex pragma @code{Short_Descriptors} + +@node Experience with source compatibility +@subsubsection Experience with source compatibility + +@noindent +The Security Server and STARLET on I64 provide an interesting ``test case'' +for source compatibility issues, since it is in such system code +where assumptions about @code{Address} size might be expected to occur. +Indeed, there were a small number of occasions in the Security Server +file @file{jibdef.ads} +where a representation clause for a record type specified +32 bits for a component of type @code{Address}. +All of these errors were detected by the compiler. +The repair was obvious and immediate; to simply replace @code{Address} by +@code{Short_Address}. + +In the case of STARLET, there were several record types that should +have had representation clauses but did not. In these record types +there was an implicit assumption that an @code{Address} value occupied +32 bits. +These compiled without error, but their usage resulted in run-time error +returns from STARLET system calls. +Future GNAT technology enhancements may include a tool that detects and flags +these sorts of potential source code porting problems. + +@c **************************************** +@node Taking advantage of 64 bit addressing +@subsection Taking advantage of 64-bit addressing + +@menu +* Making code 64 bit clean:: +* Allocating memory from the 64 bit storage pool:: +* Restrictions on use of 64 bit objects:: +* STARLET and other predefined libraries:: +@end menu + +@node Making code 64 bit clean +@subsubsection Making code 64-bit clean + +@noindent +In order to prevent problems that may occur when (parts of) a +system start using memory outside the 32-bit address range, +we recommend some additional guidelines: + +@itemize @bullet +@item +For imported subprograms that take parameters of the +type @code{System.Address}, ensure that these subprograms can +indeed handle 64-bit addresses. If not, or when in doubt, +change the subprogram declaration to specify +@code{System.Short_Address} instead. + +@item +Resolve all warnings related to size mismatches in +unchecked conversions. Failing to do so causes +erroneous execution if the source object is outside +the 32-bit address space. + +@item +(optional) Explicitly use the 32-bit storage pool +for access types used in a 32-bit context, or use +generic access types where possible +(@pxref{Restrictions on use of 64 bit objects}). +@end itemize + +@noindent +If these rules are followed, the compiler will automatically insert +any necessary checks to ensure that no addresses or access values +passed to 32-bit code ever refer to objects outside the 32-bit +address range. +Any attempt to do this will raise @code{Constraint_Error}. + +@node Allocating memory from the 64 bit storage pool +@subsubsection Allocating memory from the 64-bit storage pool + +@noindent +By default, all allocations -- for both pool-specific and general +access types -- use the 64-bit storage pool. To override +this default, for an individual access type or globally, see +@ref{Access types and 32/64-bit allocation}. + +@node Restrictions on use of 64 bit objects +@subsubsection Restrictions on use of 64-bit objects + +@noindent +Taking the address of an object allocated from a 64-bit storage pool, +and then passing this address to a subprogram expecting +@code{System.Short_Address}, +or assigning it to a variable of type @code{Short_Address}, will cause +@code{Constraint_Error} to be raised. In case the code is not 64-bit clean +(@pxref{Making code 64 bit clean}), or checks are suppressed, +no exception is raised and execution +will become erroneous. + +@node STARLET and other predefined libraries +@subsubsection STARLET and other predefined libraries + +@noindent +All code that comes as part of GNAT is 64-bit clean, but the +restrictions given in @ref{Restrictions on use of 64 bit objects}, +still apply. Look at the package +specs to see in which contexts objects allocated +in 64-bit address space are acceptable. + +@node Technical details +@subsection Technical details + +@noindent +64-bit @value{EDITION} for Open VMS takes advantage of the freedom given in the +Ada standard with respect to the type of @code{System.Address}. Previous +versions of GNAT Pro have defined this type as private and implemented it as a +modular type. + +In order to allow defining @code{System.Short_Address} as a proper subtype, +and to match the implicit sign extension in parameter passing, +in 64-bit @value{EDITION} for Open VMS, @code{System.Address} is defined as a +visible (i.e., non-private) integer type. +Standard operations on the type, such as the binary operators ``+'', ``-'', +etc., that take @code{Address} operands and return an @code{Address} result, +have been hidden by declaring these +@code{abstract}, a feature introduced in Ada 95 that helps avoid the potential +ambiguities that would otherwise result from overloading. +(Note that, although @code{Address} is a visible integer type, +good programming practice dictates against exploiting the type's +integer properties such as literals, since this will compromise +code portability.) + +Defining @code{Address} as a visible integer type helps achieve +maximum compatibility for existing Ada code, +without sacrificing the capabilities of the 64-bit architecture. +@end ifset + +@c ************************************************ +@ifset unw +@node Microsoft Windows Topics +@appendix Microsoft Windows Topics +@cindex Windows NT +@cindex Windows 95 +@cindex Windows 98 + +@noindent +This chapter describes topics that are specific to the Microsoft Windows +platforms (NT, 2000, and XP Professional). + +@menu +* Using GNAT on Windows:: +* Using a network installation of GNAT:: +* CONSOLE and WINDOWS subsystems:: +* Temporary Files:: +* Mixed-Language Programming on Windows:: +* Windows Calling Conventions:: +* Introduction to Dynamic Link Libraries (DLLs):: +* Using DLLs with GNAT:: +* Building DLLs with GNAT Project files:: +* Building DLLs with GNAT:: +* Building DLLs with gnatdll:: +* GNAT and Windows Resources:: +* Debugging a DLL:: +* Setting Stack Size from gnatlink:: +* Setting Heap Size from gnatlink:: +@end menu + +@node Using GNAT on Windows +@section Using GNAT on Windows + +@noindent +One of the strengths of the GNAT technology is that its tool set +(@command{gcc}, @command{gnatbind}, @command{gnatlink}, @command{gnatmake}, the +@code{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 @bullet + +@item +You can build applications using the @code{CONSOLE} or @code{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 + +@noindent +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 @bullet + +@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. + +@item +It is not possible to link against Microsoft libraries except for +import libraries. Interfacing must be done by the mean of DLLs. + +@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 +@section Using a network installation of GNAT + +@noindent +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} + +In order to use such a network installation, simply add the UNC path of the +@file{bin} directory of your GNAT installation in front of your PATH. For +example, if GNAT is installed in @file{\GNAT} directory of a share location +called @file{c-drive} on a machine @file{LOKI}, the following command will +make it available: + +@code{@ @ @ path \\loki\c-drive\gnat\bin;%path%} + +Be aware that every compilation using the network installation results in the +transfer of large amounts of data across the network and will likely cause +serious performance penalty. + +@node CONSOLE and WINDOWS subsystems +@section CONSOLE and WINDOWS subsystems +@cindex CONSOLE Subsystem +@cindex WINDOWS Subsystem +@cindex -mwindows + +@noindent +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 @option{-mwindows} linker option must be specified. + +@smallexample +$ gnatmake winprog -largs -mwindows +@end smallexample + +@node Temporary Files +@section Temporary Files +@cindex Temporary files + +@noindent +It is possible to control where temporary files gets created by setting +the @env{TMP} environment variable. The file will be created: + +@itemize +@item Under the directory pointed to by the @env{TMP} environment variable if +this directory exists. + +@item Under @file{c:\temp}, if the @env{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 + +@noindent +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 +@section Mixed-Language Programming on Windows + +@noindent +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 @command{gcc} 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 non-Ada code, you have two choices: + +@enumerate +@item +Encapsulate your non-Ada 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 +(@pxref{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 +(@pxref{Building DLLs with GNAT Project files}) and use the Microsoft +or whatever environment to build your executable. +@end enumerate + +@node Windows Calling Conventions +@section Windows Calling Conventions +@findex Stdcall +@findex APIENTRY + +This section pertain only to Win32. On Win64 there is a single native +calling convention. All convention specifiers are ignored on this +platform. + +@menu +* C Calling Convention:: +* Stdcall Calling Convention:: +* Win32 Calling Convention:: +* DLL Calling Convention:: +@end menu + +@noindent +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: + +@itemize @bullet +@item +@code{C} (Microsoft defined) + +@item +@code{Stdcall} (Microsoft defined) + +@item +@code{Win32} (GNAT specific) + +@item +@code{DLL} (GNAT specific) +@end itemize + +@node C Calling Convention +@subsection @code{C} Calling Convention + +@noindent +This is the default calling convention used when interfacing to C/C++ +routines compiled with either @command{gcc} or Microsoft Visual C++. + +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. + +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: + +@smallexample +int get_val (long); +@end smallexample + +@noindent +should be imported from Ada as follows: + +@smallexample @c ada +@group +function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; +pragma Import (C, Get_Val, External_Name => "get_val"); +@end group +@end smallexample + +@noindent +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. + +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, @pxref{Stdcall Calling Convention}). + +@node Stdcall Calling Convention +@subsection @code{Stdcall} Calling Convention + +@noindent +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{@@}@code{@var{nn}}, where @var{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 +@code{Stdcall} calling convention is the name of the C routine. The leading +underscore and trailing @code{@@}@code{@var{nn}} are added automatically by +the compiler. For instance the Win32 function: + +@smallexample +@b{APIENTRY} int get_val (long); +@end smallexample + +@noindent +should be imported from Ada as follows: + +@smallexample @c ada +@group +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 group +@end smallexample + +@noindent +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: + +@smallexample @c ada +@group +function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; +pragma Import (Stdcall, Get_Val, External_Name => "retrieve_val"); +@end group +@end smallexample + +@noindent +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: + +@smallexample @c ada +@group +function Get_Val (V : Interfaces.C.long) return Interfaces.C.int; +pragma Import (Stdcall, Get_Val, Link_Name => "retrieve_val"); +@end group +@end smallexample + +@noindent +then the imported routine is @code{retrieve_val}, that is, there is no +decoration at all. No leading underscore and no Stdcall suffix +@code{@@}@code{@var{nn}}. + +@noindent +This is especially important as in some special cases a DLL's entry +point name lacks a trailing @code{@@}@code{@var{nn}} while the exported +name generated for a call has it. + +@noindent +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: + +@smallexample +int my_var; +@end smallexample + +@noindent +then, to access this variable from Ada you should write: + +@smallexample @c ada +@group +My_Var : Interfaces.C.int; +pragma Import (Stdcall, My_Var); +@end group +@end smallexample + +@noindent +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 +@subsection @code{Win32} Calling Convention + +@noindent +This convention, which is GNAT-specific is fully equivalent to the +@code{Stdcall} calling convention described above. + +@node DLL Calling Convention +@subsection @code{DLL} Calling Convention + +@noindent +This convention, which is GNAT-specific is fully equivalent to the +@code{Stdcall} calling convention described above. + +@node Introduction to Dynamic Link Libraries (DLLs) +@section Introduction to Dynamic Link Libraries (DLLs) +@findex DLL + +@noindent +A Dynamically Linked Library (DLL) is a library that can be shared by +several applications running under Windows. A DLL can contain any number of +routines and variables. + +One advantage of DLLs is that you can change and enhance them without +forcing all the applications that depend on them to be relinked or +recompiled. However, you should be aware than all calls to DLL routines are +slower since, as you will understand below, such calls are indirect. + +To illustrate the remainder of this section, suppose that an application +wants to use the services of a DLL @file{API.dll}. To use the services +provided by @file{API.dll} you must statically link against the DLL or +an import library which contains a jump table with an entry for each +routine and variable exported by the DLL. In the Microsoft world this +import library is called @file{API.lib}. When using GNAT this import +library is called either @file{libAPI.dll.a}, @file{libapi.dll.a}, +@file{libAPI.a} or @file{libapi.a} (names are case insensitive). + +After you have linked your application with the DLL or the import library +and you run your application, here is what happens: + +@enumerate +@item +Your application is loaded into memory. + +@item +The DLL @file{API.dll} is mapped into the address space of your +application. This means that: + +@itemize @bullet +@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 @file{libAPI.dll.a} +or @file{API.lib} or automatically created when linking against a DLL) +which is part of your application are initialized with the addresses +of the routines and variables in @file{API.dll}. + +@item +If present in @file{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 enumerate + +@noindent +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 @option{-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 (@pxref{The Definition File}). + +@node Using DLLs with GNAT +@section Using DLLs with GNAT + +@menu +* Creating an Ada Spec for the DLL Services:: +* Creating an Import Library:: +@end menu + +@noindent +To use the services of a DLL, say @file{API.dll}, in your Ada application +you must have: + +@enumerate +@item +The Ada spec for the routines and/or variables you want to access in +@file{API.dll}. If not available this Ada spec must be built from the C/C++ +header files provided with the DLL. + +@item +The import library (@file{libAPI.dll.a} or @file{API.lib}). As previously +mentioned an import library is a statically linked library containing the +import table which will be filled at load time to point to the actual +@file{API.dll} routines. Sometimes you don't have an import library for the +DLL you want to use. The following sections will explain how to build +one. Note that this is optional. + +@item +The actual DLL, @file{API.dll}. +@end enumerate + +@noindent +Once you have all the above, to compile an Ada application that uses the +services of @file{API.dll} and whose main subprogram is @code{My_Ada_App}, +you simply issue the command + +@smallexample +$ gnatmake my_ada_app -largs -lAPI +@end smallexample + +@noindent +The argument @option{-largs -lAPI} at the end of the @command{gnatmake} command +tells the GNAT linker to look for an import library. The linker will +look for a library name in this specific order: + +@enumerate +@item @file{libAPI.dll.a} +@item @file{API.dll.a} +@item @file{libAPI.a} +@item @file{API.lib} +@item @file{libAPI.dll} +@item @file{API.dll} +@end enumerate + +The first three are the GNU style import libraries. The third is the +Microsoft style import libraries. The last two are the actual DLL names. + +Note that if the Ada package spec for @file{API.dll} contains the +following pragma + +@smallexample @c ada +pragma Linker_Options ("-lAPI"); +@end smallexample + +@noindent +you do not have to add @option{-largs -lAPI} at the end of the +@command{gnatmake} command. + +If any one of the items above is missing you will have to create it +yourself. The following sections explain how to do so using as an +example a fictitious DLL called @file{API.dll}. + +@node Creating an Ada Spec for the DLL Services +@subsection Creating an Ada Spec for the DLL Services + +@noindent +A DLL typically comes with a C/C++ header file which provides the +definitions of the routines and variables exported by the DLL. The Ada +equivalent of this header file is a package spec that contains definitions +for the imported entities. If the DLL you intend to use does not come with +an Ada spec you have to generate one such spec yourself. For example if +the header file of @file{API.dll} is a file @file{api.h} containing the +following two definitions: + +@smallexample +@group +@cartouche +int some_var; +int get (char *); +@end cartouche +@end group +@end smallexample + +@noindent +then the equivalent Ada spec could be: + +@smallexample @c ada +@group +@cartouche +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 cartouche +@end group +@end smallexample + +@noindent +Note that a variable is +@strong{always imported with a DLL convention}. A function +can have @code{C} or @code{Stdcall} convention. +(@pxref{Windows Calling Conventions}). + +@node Creating an Import Library +@subsection Creating an Import Library +@cindex Import library + +@menu +* The Definition File:: +* GNAT-Style Import Library:: +* Microsoft-Style Import Library:: +@end menu + +@noindent +If a Microsoft-style import library @file{API.lib} or a GNAT-style +import library @file{libAPI.dll.a} or @file{libAPI.a} is available +with @file{API.dll} you can skip this section. You can also skip this +section if @file{API.dll} or @file{libAPI.dll} is built with GNU tools +as in this case it is possible to link directly against the +DLL. Otherwise read on. + +@node The Definition File +@subsubsection The Definition File +@cindex Definition file +@findex .def + +@noindent +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: + +@smallexample +@group +@cartouche +@r{[}LIBRARY @var{name}@r{]} +@r{[}DESCRIPTION @var{string}@r{]} +EXPORTS + @var{symbol1} + @var{symbol2} + @dots{} +@end cartouche +@end group +@end smallexample + +@table @code +@item LIBRARY @var{name} +This section, which is optional, gives the name of the DLL. + +@item DESCRIPTION @var{string} +This section, which is optional, gives a description string that will be +embedded in the import library. + +@item EXPORTS +This section gives the list of exported symbols (procedures, functions or +variables). For instance in the case of @file{API.dll} the @code{EXPORTS} +section of @file{API.def} looks like: + +@smallexample +@group +@cartouche +EXPORTS + some_var + get +@end cartouche +@end group +@end smallexample +@end table + +@noindent +Note that you must specify the correct suffix (@code{@@}@code{@var{nn}}) +(@pxref{Windows Calling Conventions}) for a Stdcall +calling convention function in the exported symbols list. + +@noindent +There can actually be other sections in a definition file, but these +sections are not relevant to the discussion at hand. + +@node GNAT-Style Import Library +@subsubsection GNAT-Style Import Library + +@noindent +To create a static import library from @file{API.dll} with the GNAT tools +you should proceed as follows: + +@enumerate +@item +Create the definition file @file{API.def} (@pxref{The Definition File}). +For that use the @code{dll2def} tool as follows: + +@smallexample +$ dll2def API.dll > API.def +@end smallexample + +@noindent +@code{dll2def} is a very simple tool: it takes as input a DLL and prints +to standard output the list of entry points in the DLL. Note that if +some routines in the DLL have the @code{Stdcall} convention +(@pxref{Windows Calling Conventions}) with stripped @code{@@}@var{nn} +suffix then you'll have to edit @file{api.def} to add it, and specify +@option{-k} to @command{gnatdll} when creating the import library. + +@noindent +Here are some hints to find the right @code{@@}@var{nn} suffix. + +@enumerate +@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). + +@smallexample +$ dumpbin /exports api.lib +@end smallexample + +@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 enumerate + +@item +Build the import library @code{libAPI.dll.a}, using @code{gnatdll} +(@pxref{Using gnatdll}) as follows: + +@smallexample +$ gnatdll -e API.def -d API.dll +@end smallexample + +@noindent +@code{gnatdll} takes as input a definition file @file{API.def} and the +name of the DLL containing the services listed in the definition file +@file{API.dll}. The name of the static import library generated is +computed from the name of the definition file as follows: if the +definition file name is @var{xyz}@code{.def}, the import library name will +be @code{lib}@var{xyz}@code{.a}. Note that in the previous example option +@option{-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 (@pxref{Using gnatdll} for more information about @code{gnatdll}). +@end enumerate + +@node Microsoft-Style Import Library +@subsubsection Microsoft-Style Import Library + +@noindent +With GNAT you can either use a GNAT-style or Microsoft-style import +library. A Microsoft import library is needed only if you plan to make an +Ada DLL available to applications developed with Microsoft +tools (@pxref{Mixed-Language Programming on Windows}). + +To create a Microsoft-style import library for @file{API.dll} you +should proceed as follows: + +@enumerate +@item +Create the definition file @file{API.def} from the DLL. For this use either +the @code{dll2def} tool as described above or the Microsoft @code{dumpbin} +tool (see the corresponding Microsoft documentation for further details). + +@item +Build the actual import library using Microsoft's @code{lib} utility: + +@smallexample +$ lib -machine:IX86 -def:API.def -out:API.lib +@end smallexample + +@noindent +If you use the above command the definition file @file{API.def} must +contain a line giving the name of the DLL: + +@smallexample +LIBRARY "API" +@end smallexample + +@noindent +See the Microsoft documentation for further details about the usage of +@code{lib}. +@end enumerate + +@node Building DLLs with GNAT Project files +@section Building DLLs with GNAT Project files +@cindex DLLs, building + +@noindent +There is nothing specific to Windows in the build process. +@pxref{Library Projects}. + +@noindent +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. + +@node Building DLLs with GNAT +@section Building DLLs with GNAT +@cindex DLLs, building + +@noindent +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. + +@enumerate + +@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 @command{gnatmake} tool. + +@item building the DLL + +To build the DLL you must use @command{gcc}'s @option{-shared} and +@option{-shared-libgcc} options. It is quite simple to use this method: + +@smallexample +$ gcc -shared -shared-libgcc -o api.dll obj1.o obj2.o @dots{} +@end smallexample + +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 @command{gcc} a definition +file, @pxref{The Definition File}. For example: + +@smallexample +$ gcc -shared -shared-libgcc -o api.dll api.def obj1.o obj2.o @dots{} +@end smallexample + +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: + +@smallexample +$ mkdir apilib +$ copy *.ads *.ali api.dll apilib +$ attrib +R apilib\*.ali +@end smallexample + +@end enumerate + +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 @option{-shared} binder's +option. + +@smallexample +$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI +@end smallexample + +@node Building DLLs with gnatdll +@section Building DLLs with gnatdll +@cindex DLLs, building + +@menu +* Limitations When Using Ada DLLs from Ada:: +* Exporting Ada Entities:: +* Ada DLLs and Elaboration:: +* Ada DLLs and Finalization:: +* Creating a Spec for Ada DLLs:: +* Creating the Definition File:: +* Using gnatdll:: +@end menu + +@noindent +Note that it is preferred to use GNAT Project files +(@pxref{Building DLLs with GNAT Project files}) or the built-in GNAT +DLL support (@pxref{Building DLLs with GNAT}) or to build DLLs. + +This section explains how to build DLLs containing Ada code using +@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the +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: + +@enumerate +@item +You need to mark each Ada @i{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 (@pxref{Exporting Ada Entities}). You can +skip this step if you plan to use the Ada DLL only from Ada applications. + +@item +Your Ada code must export an initialization routine which calls the routine +@code{adainit} generated by @command{gnatbind} to perform the elaboration of +the Ada code in the DLL (@pxref{Ada DLLs and Elaboration}). The initialization +routine exported by the Ada DLL must be invoked by the clients of the DLL +to initialize the DLL. + +@item +When useful, the DLL should also export a finalization routine which calls +routine @code{adafinal} generated by @command{gnatbind} to perform the +finalization of the Ada code in the DLL (@pxref{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 +(@pxref{The Definition File}). + +@item +Finally you must use @code{gnatdll} to produce the DLL and the import +library (@pxref{Using gnatdll}). +@end enumerate + +@noindent +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. +@pxref{Library Projects}. + +@node Limitations When Using Ada DLLs from Ada +@subsection Limitations When Using Ada DLLs from Ada + +@noindent +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.@: @code{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 +@subsection Exporting Ada Entities +@cindex Export table + +@noindent +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: + +@smallexample @c ada +@group +@cartouche +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 cartouche +@end group +@end smallexample + +@smallexample @c ada +@group +@cartouche +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 cartouche +@end group +@end smallexample + +@noindent +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: + +@smallexample @c ada +@group +@cartouche +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 cartouche +@end group +@end smallexample + +@smallexample @c ada +@group +@cartouche +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; + + @dots{} + -- The remainder of this package body is unchanged. +end API; +@end cartouche +@end group +@end smallexample + +@noindent +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 +(@pxref{Creating the Definition File}). + +@node Ada DLLs and Elaboration +@subsection Ada DLLs and Elaboration +@cindex DLLs and elaboration + +@noindent +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 +(@pxref{Elaboration Order Handling in GNAT}). + +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 +(@pxref{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 (@pxref{Using gnatdll}). + +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. + +@node Ada DLLs and Finalization +@subsection Ada DLLs and Finalization +@cindex DLLs and finalization + +@noindent +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 +(@pxref{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 +(@pxref{Using gnatdll}). + +@node Creating a Spec for Ada DLLs +@subsection Creating a Spec for Ada DLLs + +@noindent +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: + +@smallexample +@group +@cartouche +extern int *_imp__count; +#define count (*_imp__count) +int factorial (int); +@end cartouche +@end group +@end smallexample + +@noindent +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}: + +@smallexample @c ada +@group +@cartouche +package API is + Count : Integer := 0; + @dots{} + -- Remainder of the package omitted. +end API; +@end cartouche +@end group +@end smallexample + +@noindent +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: + +@smallexample @c ada +@group +@cartouche +package API is + Count : Integer; + pragma Import (DLL, Count); +end API; +@end cartouche +@end group +@end smallexample + +@node Creating the Definition File +@subsection Creating the Definition File + +@noindent +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: + +@smallexample +@group +@cartouche +EXPORTS + count + factorial + finalize_api + initialize_api +@end cartouche +@end group +@end smallexample + +@noindent +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: + +@smallexample +@group +@cartouche +EXPORTS + api__count + api__factorial + api__finalize_api + api__initialize_api +@end cartouche +@end group +@end smallexample + +@node Using gnatdll +@subsection Using @code{gnatdll} +@findex gnatdll + +@menu +* gnatdll Example:: +* gnatdll behind the Scenes:: +* Using dlltool:: +@end menu + +@noindent +@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 + +@smallexample +@cartouche +@c $ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ gnatdll @r{[}@var{switches}@r{]} @var{list-of-files} @r{[}-largs @var{opts}@r{]} +@end cartouche +@end smallexample + +@noindent +where @var{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 @var{list-of-files} is +missing, only the static import library is generated. + +@noindent +You may specify any of the following switches to @code{gnatdll}: + +@table @code +@c @item -a@ovar{address} +@c Expanding @ovar macro inline (explanation in macro def comments) +@item -a@r{[}@var{address}@r{]} +@cindex @option{-a} (@code{gnatdll}) +Build a non-relocatable DLL at @var{address}. If @var{address} is not +specified the default address @var{0x11000000} will be used. By default, +when this switch is missing, @code{gnatdll} builds relocatable DLL. We +advise the reader to build relocatable DLL. + +@item -b @var{address} +@cindex @option{-b} (@code{gnatdll}) +Set the relocatable DLL base address. By default the address is +@code{0x11000000}. + +@item -bargs @var{opts} +@cindex @option{-bargs} (@code{gnatdll}) +Binder options. Pass @var{opts} to the binder. + +@item -d @var{dllfile} +@cindex @option{-d} (@code{gnatdll}) +@var{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 @var{dllfile} as shown in the following +example: if @var{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 @option{-e}) is obtained algorithmically from @var{dllfile} +as shown in the following example: +if @var{dllfile} is @code{xyz.dll}, the definition +file used is @code{xyz.def}. + +@item -e @var{deffile} +@cindex @option{-e} (@code{gnatdll}) +@var{deffile} is the name of the definition file. + +@item -g +@cindex @option{-g} (@code{gnatdll}) +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 +@option{-g} switch if you plan on using the debugger or the symbolic +stack traceback. + +@item -h +@cindex @option{-h} (@code{gnatdll}) +Help mode. Displays @code{gnatdll} switch usage information. + +@item -Idir +@cindex @option{-I} (@code{gnatdll}) +Direct @code{gnatdll} to search the @var{dir} directory for source and +object files needed to build the DLL. +(@pxref{Search Paths and the Run-Time Library (RTL)}). + +@item -k +@cindex @option{-k} (@code{gnatdll}) +Removes the @code{@@}@var{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{@@}@var{nn} suffix has been removed. This is the case for most +of the Windows NT DLL for example. This option has no effect when +@option{-n} option is specified. + +@item -l @var{file} +@cindex @option{-l} (@code{gnatdll}) +The list of ALI and object files used to build the DLL are listed in +@var{file}, instead of being given in the command line. Each line in +@var{file} contains the name of an ALI or object file. + +@item -n +@cindex @option{-n} (@code{gnatdll}) +No Import. Do not create the import library. + +@item -q +@cindex @option{-q} (@code{gnatdll}) +Quiet mode. Do not display unnecessary messages. + +@item -v +@cindex @option{-v} (@code{gnatdll}) +Verbose mode. Display extra information. + +@item -largs @var{opts} +@cindex @option{-largs} (@code{gnatdll}) +Linker options. Pass @var{opts} to the linker. +@end table + +@node gnatdll Example +@subsubsection @code{gnatdll} Example + +@noindent +As an example the command to build a relocatable DLL from @file{api.adb} +once @file{api.adb} has been compiled and @file{api.def} created is + +@smallexample +$ gnatdll -d api.dll api.ali +@end smallexample + +@noindent +The above command creates two files: @file{libapi.dll.a} (the import +library) and @file{api.dll} (the actual DLL). If you want to create +only the DLL, just type: + +@smallexample +$ gnatdll -d api.dll -n api.ali +@end smallexample + +@noindent +Alternatively if you want to create just the import library, type: + +@smallexample +$ gnatdll -d api.dll +@end smallexample + +@node gnatdll behind the Scenes +@subsubsection @code{gnatdll} behind the Scenes + +@noindent +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. + +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 @file{api.o} and +@file{api.ali} are available. To build a relocatable DLL, @code{gnatdll} does +the following: + +@enumerate +@item +@code{gnatdll} builds the base file (@file{api.base}). A base file gives +the information necessary to generate relocation information for the +DLL. + +@smallexample +@group +$ gnatbind -n api +$ gnatlink api -o api.jnk -mdll -Wl,--base-file,api.base +@end group +@end smallexample + +@noindent +In addition to the base file, the @command{gnatlink} command generates an +output file @file{api.jnk} which can be discarded. The @option{-mdll} switch +asks @command{gnatlink} to generate the routines @code{DllMain} and +@code{DllMainCRTStartup} that are called by the Windows loader when the DLL +is loaded into memory. + +@item +@code{gnatdll} uses @code{dlltool} (@pxref{Using dlltool}) to build the +export table (@file{api.exp}). The export table contains the relocation +information in a form which can be used during the final link to ensure +that the Windows loader is able to place the DLL anywhere in memory. + +@smallexample +@group +$ dlltool --dllname api.dll --def api.def --base-file api.base \ + --output-exp api.exp +@end group +@end smallexample + +@item +@code{gnatdll} builds the base file using the new export table. Note that +@command{gnatbind} must be called once again since the binder generated file +has been deleted during the previous call to @command{gnatlink}. + +@smallexample +@group +$ gnatbind -n api +$ gnatlink api -o api.jnk api.exp -mdll + -Wl,--base-file,api.base +@end group +@end smallexample + +@item +@code{gnatdll} builds the new export table using the new base file and +generates the DLL import library @file{libAPI.dll.a}. + +@smallexample +@group +$ dlltool --dllname api.dll --def api.def --base-file api.base \ + --output-exp api.exp --output-lib libAPI.a +@end group +@end smallexample + +@item +Finally @code{gnatdll} builds the relocatable DLL using the final export +table. + +@smallexample +@group +$ gnatbind -n api +$ gnatlink api api.exp -o api.dll -mdll +@end group +@end smallexample +@end enumerate + +@node Using dlltool +@subsubsection Using @code{dlltool} + +@noindent +@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 + +@smallexample +@c $ dlltool @ovar{switches} +@c Expanding @ovar macro inline (explanation in macro def comments) +$ dlltool @r{[}@var{switches}@r{]} +@end smallexample + +@noindent +@code{dlltool} switches include: + +@table @option +@item --base-file @var{basefile} +@cindex @option{--base-file} (@command{dlltool}) +Read the base file @var{basefile} generated by the linker. This switch +is used to create a relocatable DLL. + +@item --def @var{deffile} +@cindex @option{--def} (@command{dlltool}) +Read the definition file. + +@item --dllname @var{name} +@cindex @option{--dllname} (@command{dlltool}) +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 +@option{--output-lib}. + +@item -k +@cindex @option{-k} (@command{dlltool}) +Kill @code{@@}@var{nn} from exported names +(@pxref{Windows Calling Conventions} +for a discussion about @code{Stdcall}-style symbols. + +@item --help +@cindex @option{--help} (@command{dlltool}) +Prints the @code{dlltool} switches with a concise description. + +@item --output-exp @var{exportfile} +@cindex @option{--output-exp} (@command{dlltool}) +Generate an export file @var{exportfile}. The export file contains the +export table (list of symbols in the DLL) and is used to create the DLL. + +@item --output-lib @var{libfile} +@cindex @option{--output-lib} (@command{dlltool}) +Generate a static import library @var{libfile}. + +@item -v +@cindex @option{-v} (@command{dlltool}) +Verbose mode. + +@item --as @var{assembler-name} +@cindex @option{--as} (@command{dlltool}) +Use @var{assembler-name} as the assembler. The default is @code{as}. +@end table + +@node GNAT and Windows Resources +@section GNAT and Windows Resources +@cindex Resources, windows + +@menu +* Building Resources:: +* Compiling Resources:: +* Using Resources:: +@end menu + +@noindent +Resources are an easy way to add Windows specific objects to your +application. The objects that can be added as resources include: + +@itemize @bullet +@item +menus + +@item +accelerators + +@item +dialog boxes + +@item +string tables + +@item +bitmaps + +@item +cursors + +@item +icons + +@item +fonts +@end itemize + +@noindent +This section explains how to build, compile and use resources. + +@node Building Resources +@subsection Building Resources +@cindex Resources, building + +@noindent +A resource file is an ASCII file. By convention resource files have an +@file{.rc} extension. +The easiest way to build a resource file is to use Microsoft tools +such as @code{imagedit.exe} to build bitmaps, icons and cursors and +@code{dlgedit.exe} to build dialogs. +It is always possible to build an @file{.rc} file yourself by writing a +resource script. + +It is not our objective to explain how to write a resource file. A +complete description of the resource script language can be found in the +Microsoft documentation. + +@node Compiling Resources +@subsection Compiling Resources +@findex rc +@findex windres +@cindex Resources, compiling + +@noindent +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: + +@smallexample +$ windres -i myres.rc -o myres.o +@end smallexample + +@noindent +By default @code{windres} will run @command{gcc} to preprocess the @file{.rc} +file. You can specify an alternate preprocessor (usually named +@file{cpp.exe}) using the @code{windres} @option{--preprocessor} +parameter. A list of all possible options may be obtained by entering +the command @code{windres} @option{--help}. + +It is also possible to use the Microsoft resource compiler @code{rc.exe} +to produce a @file{.res} file (binary resource file). See the +corresponding Microsoft documentation for further details. In this case +you need to use @code{windres} to translate the @file{.res} file to a +GNAT-compatible object file as follows: + +@smallexample +$ windres -i myres.res -o myres.o +@end smallexample + +@node Using Resources +@subsection Using Resources +@cindex Resources, using + +@noindent +To include the resource file in your program just add the +GNAT-compatible object file for the resource(s) to the linker +arguments. With @command{gnatmake} this is done by using the @option{-largs} +option: + +@smallexample +$ gnatmake myprog -largs myres.o +@end smallexample + +@node Debugging a DLL +@section Debugging a DLL +@cindex DLL debugging + +@menu +* Program and DLL Both Built with GCC/GNAT:: +* Program Built with Foreign Tools and DLL Built with GCC/GNAT:: +@end menu + +@noindent +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: + +@enumerate 1 +@item +The program and the DLL are built with @code{GCC/GNAT}. +@item +The program is built with foreign tools and the DLL is built with +@code{GCC/GNAT}. +@item +The program is built with @code{GCC/GNAT} and the DLL is built with +foreign tools. +@end enumerate + +@noindent +In this section we address only cases one and two above. +There is no point in trying to debug +a DLL with @code{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. + +@node Program and DLL Both Built with GCC/GNAT +@subsection Program and DLL Both Built with GCC/GNAT + +@noindent +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}. + +@noindent +The DLL (@pxref{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: + +@enumerate 1 +@item Launch @code{GDB} on the main program. + +@smallexample +$ gdb -nw ada_main +@end smallexample + +@item Start the program and stop at the beginning of the main procedure + +@smallexample +(gdb) start +@end smallexample + +@noindent +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 + +@smallexample +(gdb) break ada_dll +(gdb) cont +@end smallexample + +@end enumerate + +@noindent +At this stage a breakpoint is set inside the DLL. From there on +you can use the standard approach to debug the whole program +(@pxref{Running and Debugging Ada Programs}). + +@ignore +@c This used to work, probably because the DLLs were non-relocatable +@c keep this section around until the problem is sorted out. + +To break on the @code{DllMain} routine it is not possible to follow +the procedure above. At the time the program stop on @code{ada_main} +the @code{DllMain} routine as already been called. Either you can use +the procedure below @pxref{Debugging the DLL Directly} or this procedure: + +@enumerate 1 +@item Launch @code{GDB} on the main program. + +@smallexample +$ gdb ada_main +@end smallexample + +@item Load DLL symbols + +@smallexample +(gdb) add-sym api.dll +@end smallexample + +@item Set a breakpoint inside the DLL + +@smallexample +(gdb) break ada_dll.adb:45 +@end smallexample + +Note that at this point it is not possible to break using the routine symbol +directly as the program is not yet running. The solution is to break +on the proper line (break in @file{ada_dll.adb} line 45). + +@item Start the program + +@smallexample +(gdb) run +@end smallexample + +@end enumerate +@end ignore + +@node Program Built with Foreign Tools and DLL Built with GCC/GNAT +@subsection Program Built with Foreign Tools and DLL Built with GCC/GNAT + +@menu +* Debugging the DLL Directly:: +* Attaching to a Running Process:: +@end menu + +@noindent +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. + +@noindent +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}. + +@noindent +The DLL (@pxref{Introduction to Dynamic Link Libraries (DLLs)}) must have +been built with debugging information (see GNAT -g option). + +@node Debugging the DLL Directly +@subsubsection Debugging the DLL Directly + +@enumerate 1 +@item +Find out the executable starting address + +@smallexample +$ objdump --file-header main.exe +@end smallexample + +The starting address is reported on the last line. For example: + +@smallexample +main.exe: file format pei-i386 +architecture: i386, flags 0x0000010a: +EXEC_P, HAS_DEBUG, D_PAGED +start address 0x00401010 +@end smallexample + +@item +Launch the debugger on the executable. + +@smallexample +$ gdb main.exe +@end smallexample + +@item +Set a breakpoint at the starting address, and launch the program. + +@smallexample +$ (gdb) break *0x00401010 +$ (gdb) run +@end smallexample + +The program will stop at the given address. + +@item +Set a breakpoint on a DLL subroutine. + +@smallexample +(gdb) break ada_dll.adb:45 +@end smallexample + +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). + +@smallexample +(gdb) set language ada +(gdb) break ada_dll +@end smallexample + +@item +Continue the program. + +@smallexample +(gdb) cont +@end smallexample + +@noindent +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 (@pxref{Running and Debugging Ada Programs}). + +@end enumerate + +@noindent +It is also possible to debug the DLL by attaching to a running process. + +@node Attaching to a Running Process +@subsubsection Attaching to a Running Process +@cindex DLL debugging, attach to process + +@noindent +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. + +@enumerate 1 + +@item Launch the main program @file{main.exe}. + +@smallexample +$ main +@end smallexample + +@item Use the Windows @i{Task Manager} to find the process ID. Let's say +that the process PID for @file{main.exe} is 208. + +@item Launch gdb. + +@smallexample +$ gdb +@end smallexample + +@item Attach to the running process to be debugged. + +@smallexample +(gdb) attach 208 +@end smallexample + +@item Load the process debugging information. + +@smallexample +(gdb) symbol-file main.exe +@end smallexample + +@item Break somewhere in the DLL. + +@smallexample +(gdb) break ada_dll +@end smallexample + +@item Continue process execution. + +@smallexample +(gdb) cont +@end smallexample + +@end enumerate + +@noindent +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 +(@pxref{Running and Debugging Ada Programs}). + +@node Setting Stack Size from gnatlink +@section Setting Stack Size from @command{gnatlink} + +@noindent +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 @command{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 +@command{gnatlink} using either: + +@itemize @bullet + +@item using @option{-Xlinker} linker option + +@smallexample +$ gnatlink hello -Xlinker --stack=0x10000,0x1000 +@end smallexample + +This sets the stack reserve size to 0x10000 bytes and the stack commit +size to 0x1000 bytes. + +@item using @option{-Wl} linker option + +@smallexample +$ gnatlink hello -Wl,--stack=0x1000000 +@end smallexample + +This sets the stack reserve size to 0x1000000 bytes. Note that with +@option{-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 +@section Setting Heap Size from @command{gnatlink} + +@noindent +Under Windows systems, it is possible to specify the program heap size from +@command{gnatlink} using either: + +@itemize @bullet + +@item using @option{-Xlinker} linker option + +@smallexample +$ gnatlink hello -Xlinker --heap=0x10000,0x1000 +@end smallexample + +This sets the heap reserve size to 0x10000 bytes and the heap commit +size to 0x1000 bytes. + +@item using @option{-Wl} linker option + +@smallexample +$ gnatlink hello -Wl,--heap=0x1000000 +@end smallexample + +This sets the heap reserve size to 0x1000000 bytes. Note that with +@option{-Wl} option it is not possible to set the heap commit size +because the coma is a separator for this option. + +@end itemize + +@end ifset + +@c ********************************** +@c * GNU Free Documentation License * +@c ********************************** +@include fdl.texi +@c GNU Free Documentation License + +@node Index,,GNU Free Documentation License, Top +@unnumbered Index + +@printindex cp + +@contents +@c Put table of contents at end, otherwise it precedes the "title page" in +@c the .txt version +@c Edit the pdf file to move the contents to the beginning, after the title +@c page + +@bye -- cgit v1.2.3