diff options
Diffstat (limited to 'gcc-4.4.3/gcc/ada/gnat_ugn.texi')
| -rw-r--r-- | gcc-4.4.3/gcc/ada/gnat_ugn.texi | 32629 |
1 files changed, 0 insertions, 32629 deletions
diff --git a/gcc-4.4.3/gcc/ada/gnat_ugn.texi b/gcc-4.4.3/gcc/ada/gnat_ugn.texi deleted file mode 100644 index 76e57585f..000000000 --- a/gcc-4.4.3/gcc/ada/gnat_ugn.texi +++ /dev/null @@ -1,32629 +0,0 @@ -\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 GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o -@c o -@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo - -@setfilename gnat_ugn.info - -@copying -Copyright @copyright{} 1995-2005, 2006, 2007, 2008 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.2 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 - -@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:: -* 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:: -@ifset vms -* The GNAT Run-Time Library Builder gnatlbr:: -@end ifset -* 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:: -* 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:: -* 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:: - -GNAT Project Manager - -* Introduction:: -* Examples of Project Files:: -* Project File Syntax:: -* Objects and Sources in Project Files:: -* Importing Projects:: -* Project Extension:: -* Project Hierarchy Extension:: -* External References in Project Files:: -* Packages in Project Files:: -* Variables from Imported Projects:: -* Naming Schemes:: -* Library Projects:: -* Stand-alone Library Projects:: -* Switches Related to Project Files:: -* Tools Supporting Project Files:: -* An Extended Example:: -* Project File Complete Syntax:: - -The Cross-Referencing Tools gnatxref and gnatfind - -* gnatxref Switches:: -* gnatfind Switches:: -* Project Files for gnatxref and gnatfind:: -* Regular Expressions in gnatfind and gnatxref:: -* Examples of gnatxref Usage:: -* Examples of gnatfind Usage:: - -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:: - -@ifset vms -The GNAT Run-Time Library Builder gnatlbr - -* Running gnatlbr:: -* Switches for gnatlbr:: -* Examples of gnatlbr Usage:: -@end ifset - -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 - -* Format of the Report File:: -* General gnatcheck Switches:: -* gnatcheck Rule Options:: -* Adding the Results of Compiler Checks to gnatcheck Output:: -* Project-Wide Checks:: -* Predefined Rules:: - -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:: -* 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:: - -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. - -@ifset vms -@item -@ref{The GNAT Run-Time Library Builder gnatlbr}, describes @command{gnatlbr}, -a tool for rebuilding the GNAT run time with user-supplied -configuration pragmas. -@end ifset - -@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{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. -Note that -@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary -to specify both options. - -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 <stdio.h> - -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 parametrize 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++ 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, and currently, GNAT does -not provide any help to solve the demangling problem. This problem can be -addressed 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 and use 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{c++}. Note that this setup is not very common because it -may involve recompiling the whole GCC tree from sources, which makes it -harder to upgrade the compilation system for one language without -destabilizing the other. - -@smallexample -$ c++ -c file1.C -$ c++ -c file2.C -$ gnatmake ada_unit -largs file1.o file2.o --LINK=c++ -@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 - -@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 -$ c++ -c cpp_main.C -$ c++ -c ex7.C -$ gnatbind -n simple_cpp_interface -$ gnatlink simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS) - -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 <stdio.h> - -extern "C" @{ void ada_method2 (A *t, int v);@} - -void A::method1 (void) -@{ - a_value = 2020; - printf ("in A::method1, a_value = %d \n",a_value); - -@} - -void A::method2 (int v) -@{ - ada_method2 (this, v); - printf ("in A::method2, a_value = %d \n",a_value); - -@} - -A::A(void) -@{ - a_value = 1010; - printf ("in A::A, a_value = %d \n",a_value); -@} -@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++ 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'Class; - 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} <iostream> -@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 -$ gcc -c @ovar{switches} @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 small subprograms, which is enabled -if @option{-O3} 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-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 -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 -gnatc -@cindex @option{-gnatc} (@command{gcc}) -Check syntax and semantics only (no code generation attempted). - -@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. - -@item -gnatD -@cindex @option{-gnatD} (@command{gcc}) -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 -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 -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 error messages are treated as errors. - -@item -gnatG -@cindex @option{-gnatG} (@command{gcc}) -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, all -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). - -@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..999_999. The default setting if -no switch is given is 9999. Compilation is terminated if this -limit is exceeded. The equal sign here is optional. - -@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. -In some cases, this has proved more effective than the back end -inlining resulting from the use of -@option{-gnatn}. -Note that -@option{-gnatN} automatically implies -@option{-gnatn} so it is not necessary -to specify both options. There are a few cases that the back-end inlining -catches that cannot be dealt with in the front-end. - -@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. - -@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. See separate section describing -this feature. - -@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 ^-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 -@item -O@ovar{n} -@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{^-gnatz^/DISTRIBUTION_STUBS^}, @option{-gnatzc}, and @option{-gnatzr} -may not be combined with any other switches. - -@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 (see description of @option{-gnatV}). -@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 999 and limits the number of error 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 errors reached -compilation abandoned -@end smallexample - -@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 -Full details on entities not available in high integrity mode -@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 all optional errors.} -@cindex @option{-gnatwa} (@command{gcc}) -This switch activates most optional warning messages, see 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{-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 as errors.} -@cindex @option{-gnatwe} (@command{gcc}) -@cindex Warnings, treat as error -This switch causes warning 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. - -@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 -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 -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 -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 -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}. - -@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 -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 has specific requirements for checking -for invalid values. In particular, RM 13.9.1 requires that the -evaluation of invalid values (for example from unchecked conversions), -not result in erroneous execution. In GNAT, the result of such an -evaluation in normal default mode is to either use the value -unmodified, or to raise Constraint_Error in those cases where use -of the unmodified value would cause erroneous execution. The cases -where unmodified values might lead to erroneous execution are case -statements (where a wild jump might result from an invalid value), -and subscripts on the left hand side (where memory corruption could -occur as a result of an invalid value). - -The @option{-gnatV^@var{x}^^} switch allows more control over the validity -checking mode. -@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 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 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 warning message is given, preceded by -the character sequence ``(style)''. -@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 ^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 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 ^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 -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 -Suppress all run-time checks as though @code{pragma Suppress (All_checks)} -had been present in the source. Validity checks are also suppressed (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. - -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. - -@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} or @option{-gnat05} switch earlier in the command line. - -@item -gnat05 (Ada 2005 mode) -@cindex @option{-gnat05} (@command{gcc}) -@cindex Ada 2005 mode - -@noindent -This switch directs the compiler to implement the Ada 2005 version of the -language. -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). - -For information about the approved ``Ada Issues'' that have been incorporated -into Ada 2005, see @url{http://www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}. -Included with GNAT releases is a file @file{features-ada0y} that describes -the set of implemented Ada 2005 features. -@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}) -The front end inlining activated by this switch is generally more extensive, -and quite often more effective than the standard @option{-gnatn} inlining mode. -It will also generate additional dependencies. -Note that -@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary -to specify both options. -@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. - -@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 -@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 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. - -@item freeze @var{type-name} @ovar{actions} -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 -@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). - -@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 only 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} create 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 -<source>^.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 -$ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches} -@end smallexample - -@noindent -where @file{@var{mainprog}.adb} is the Ada file containing the main program -unit body. If no switches are specified, @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}. - -However for some purposes it may be convenient to generate the main -program in C rather than Ada. This may for example be helpful when you -are generating a mixed language program with the main program in C. The -GNAT compiler itself is an example. -The use of the @option{^-C^/BIND_FILE=C^} switch -for both @code{gnatbind} and @command{gnatlink} will cause the program to -be generated in C (and compiled using the gnu C compiler). - -@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:: -* 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^/BIND_FILE=ADA^ -@cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatbind}) -Generate binder program in Ada (default) - -@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 ^-C^/BIND_FILE=C^ -@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind}) -Generate binder program in C - -@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. -This is the default with the zero cost exception mechanism. -@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 ^-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 to @var{n}, where @var{n} is -in the range 1..999_999. The default value if no switch is -given is 9999. Binding is terminated if the limit is exceeded. -@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^ -@cindex @option{^-O^/OBJECT_LIST^} (@command{gnatbind}) -Output object list. - -@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 ^-A^/BIND_FILE=ADA^ -@cindex @option{^-A^/BIND_FILE=ADA^} (@code{gnatbind}) -Generate binder program in Ada (default). The binder program is named -@file{b~@var{mainprog}.adb} by default. This can be changed with -@option{^-o^/OUTPUT^} @code{gnatbind} option. - -@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 ^-C^/BIND_FILE=C^ -@cindex @option{^-C^/BIND_FILE=C^} (@code{gnatbind}) -Generate binder program in C. The binder program is named -@file{b_@var{mainprog}.c}. -This can be changed with @option{^-o^/OUTPUT^} @code{gnatbind} -option. - -@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. In C mode you would normally give -@var{file} an extension of @file{.c} because it will be a C source program. -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 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 unless the -C switch is used in which case the -output is a C source file, which must be compiled using the C compiler. -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, in the case where the output is in Ada. Note that if this option -is used, then linking must be done manually, since gnatlink will not -be able to find the generated file. - -@ifclear vms -@item gnatbind main -C -o mainprog.c -x -@end ifclear -@ifset vms -@item gnatbind MAIN.ALI /BIND_FILE=C /OUTPUT=Mainprog.C /READ_SOURCES=NONE -@end ifset -The main program @code{Main} (source program in -@file{main.adb}) is bound, excluding source files from the -consistency checking, generating -the file @file{mainprog.c}. - -@ifclear vms -@item gnatbind -x main_program -C -o mainprog.c -This command is exactly the same as the previous example. Switches may -appear anywhere in the command line, and single letter switches may be -combined into a single switch. -@end ifclear - -@ifclear vms -@item gnatbind -n math dbase -C -o ada-control.c -@end ifclear -@ifset vms -@item gnatbind /NOMAIN math dbase /BIND_FILE=C /OUTPUT=ada-control.c -@end ifset -The main program is in a language other than Ada, but calls to -subprograms in packages @code{Math} and @code{Dbase} appear. This call -to @code{gnatbind} generates the file @file{ada-control.c} containing -the @code{adainit} and @code{adafinal} routines to be called before and -after accessing the Ada units. -@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 -$ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]} - @ovar{non-Ada objects} @ovar{linker options} -@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. -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 ^-A^/BIND_FILE=ADA^ -@cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatlink}) -The binder has generated code in Ada. This is the default. - -@item ^-C^/BIND_FILE=C^ -@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatlink}) -If instead of generating a file in Ada, the binder has generated one in -C, then the linker needs to know about it. Use this switch to signal -to @command{gnatlink} that the binder has generated C code rather than -Ada code. - -@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 <prefix>-gcc), then the back-end -switches in the ALI file are not used to compile the binder generated source. -For example, this is the case with @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="<string>" -@code{"<string>"} 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 -$ gnatmake @ovar{switches} @var{file_name} - @ovar{file_names} @ovar{mode_switches} -@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 ^-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). These mappings are used by the compiler to short-circuit the path -search. When @command{gnatmake} is invoked with this switch, it will create -a temporary mapping file, initially populated by the project manager, -if @option{^-P^/PROJECT_FILE^} is used, otherwise initially empty. -Each invocation of the compiler will add the newly accessed sources to the -mapping file. This will improve the source search during the next invocation -of the compiler. - -@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}) -Follow all symbolic links when processing project files. -@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 <current directory>/$rts_path - -@item <default-search-dir>/$rts_path - -@item <default-search-dir>/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}, -and also attempts automatic inlining of small -subprograms within a unit (@pxref{Inlining of Subprograms}). - -@item ^-Os^/OPTIMIZE=SPACE^ -Optimize space usage 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 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 -Either @code{pragma Inline} applies to the subprogram, or it is local -to the unit and called once from within it, or it is small and automatic -inlining (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 -@cindex @option{-gnatn} (@command{gcc}) -The @option{^-gnatn^/INLINE^} switch -is used in the @command{gcc} 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 small subprograms if @option{-O3} 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 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. - -@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:: -* 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 -and a bind file for a main subprogram. - -To create a bind file for @code{gnatelim}, run @code{gnatbind} for -the main subprogram. @code{gnatelim} can work with both Ada and C -bind files; when both are present, it uses the Ada bind file. -The following commands will build the program and create the bind file: - -@smallexample -$ gnatmake ^-c Main_Prog^/ACTIONS=COMPILE MAIN_PROG^ -$ gnatbind main_prog -@end smallexample - -Note that @code{gnatelim} needs neither object nor ALI files. - -@node Running gnatelim -@subsection Running @code{gnatelim} - -@noindent -@code{gnatelim} has the following command-line interface: - -@smallexample -$ gnatelim @ovar{options} name -@end smallexample - -@noindent -@code{name} should be a name of a source file that contains the main subprogram -of a program (partition). - -@code{gnatelim} has the following switches: - -@table @option -@c !sort! -@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. - -@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 ^-a^/ALL^ -@cindex @option{^-a^/ALL^} (@command{gnatelim}) -Also look for subprograms from the GNAT run time that can be eliminated. Note -that when @file{gnat.adc} is produced using this switch, the entire program -must be recompiled with switch @option{^-a^/ALL_FILES^} to @command{gnatmake}. - -@item ^-I^/INCLUDE_DIRS=^@var{dir} -@cindex @option{^-I^/INCLUDE_DIRS^} (@command{gnatelim}) -When looking for source files also look in directory @var{dir}. Specifying -@option{^-I-^/INCLUDE_DIRS=-^} instructs @code{gnatelim} not to look for -sources in the current directory. - -@item ^-b^/BIND_FILE=^@var{bind_file} -@cindex @option{^-b^/BIND_FILE^} (@command{gnatelim}) -Specifies @var{bind_file} as the bind file to process. If not set, the name -of the bind file is computed from the full expanded Ada name -of a main subprogram. - -@item ^-C^/CONFIG_FILE=^@var{config_file} -@cindex @option{^-C^/CONFIG_FILE^} (@command{gnatelim}) -Specifies a file @var{config_file} that contains configuration pragmas. The -file must be specified with full path. - -@item ^--GCC^/COMPILER^=@var{compiler_name} -@cindex @option{^-GCC^/COMPILER^} (@command{gnatelim}) -Instructs @code{gnatelim} to use specific @command{gcc} compiler instead of one -available on the path. - -@item ^--GNATMAKE^/GNATMAKE^=@var{gnatmake_name} -@cindex @option{^--GNATMAKE^/GNATMAKE^} (@command{gnatelim}) -Instructs @code{gnatelim} to use specific @command{gnatmake} instead of one -available on the path. -@end table - -@noindent -@code{gnatelim} sends its output to the standard output stream, and all the -tracing and debug information is sent to the standard error stream. -In order to produce a proper GNAT configuration file -@file{gnat.adc}, redirection must be used: - -@smallexample -@ifset vms -$ PIPE GNAT ELIM MAIN_PROG.ADB > GNAT.ADC -@end ifset -@ifclear vms -$ gnatelim main_prog.adb > gnat.adc -@end ifclear -@end smallexample - -@ifclear vms -@noindent -or - -@smallexample -$ gnatelim main_prog.adb >> gnat.adc -@end smallexample - -@noindent -in order to append the @code{gnatelim} output to the existing contents of -@file{gnat.adc}. -@end ifclear - -@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 -file.adb:106:07: cannot call eliminated subprogram "My_Prog" -@end smallexample - -@noindent -You will need to manually remove the wrong @code{Eliminate} pragmas from -the @file{gnat.adc} file. You should recompile your program -from scratch after that, because you need a consistent @file{gnat.adc} file -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 new @file{gnat.adc} file -created by @code{gnatelim} in your current directory: - -@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 @file{gnat.adc} file. - -@node Summary of the gnatelim Usage Cycle -@subsection Summary of the 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 -Produce a bind file - -@smallexample -$ gnatmake ^-c main_prog^/ACTIONS=COMPILE MAIN_PROG^ -$ gnatbind main_prog -@end smallexample - -@item -Generate a list of @code{Eliminate} pragmas -@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. - -@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 -$ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]} - @ovar{directory} -@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 - Assertion_Policy - C_Pass_By_Copy - Check_Name - Check_Policy - Compile_Time_Error - Compile_Time_Warning - Compiler_Unit - Component_Alignment - Debug_Policy - Detect_Blocking - Discard_Names - Elaboration_Checks - Eliminate - Extend_System - 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 - 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 -$ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns} - @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@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. -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 ***************************************** -@node GNAT Project Manager -@chapter GNAT Project Manager - -@menu -* Introduction:: -* Examples of Project Files:: -* Project File Syntax:: -* Objects and Sources in Project Files:: -* Importing Projects:: -* Project Extension:: -* Project Hierarchy Extension:: -* External References in Project Files:: -* Packages in Project Files:: -* Variables from Imported Projects:: -* Naming Schemes:: -* Library Projects:: -* Stand-alone Library Projects:: -* Switches Related to Project Files:: -* Tools Supporting Project Files:: -* An Extended Example:: -* Project File Complete Syntax:: -@end menu - -@c **************** -@c * Introduction * -@c **************** - -@node Introduction -@section Introduction - -@noindent -This chapter describes GNAT's @emph{Project Manager}, a facility that allows -you to manage complex builds involving a number of source files, directories, -and compilation options for different system configurations. In particular, -project files allow you to specify: -@itemize @bullet -@item -The directory or set of directories containing the source files, and/or the -names of the specific source files themselves -@item -The directory in which the compiler's output -(@file{ALI} files, object files, tree files) is to be placed -@item -The directory in which the executable programs is to be placed -@item -^Switch^Switch^ settings for any of the project-enabled tools -(@command{gnatmake}, compiler, binder, linker, @code{gnatls}, @code{gnatxref}, -@code{gnatfind}); you can apply these settings either globally or to individual -compilation units. -@item -The source files containing the main subprogram(s) to be built -@item -The source programming language(s) (currently Ada and/or C) -@item -Source file naming conventions; you can specify these either globally or for -individual compilation units -@end itemize - -@menu -* Project Files:: -@end menu - -@node Project Files -@subsection Project Files - -@noindent -Project files are written in a syntax close to that of Ada, using familiar -notions such as packages, context clauses, declarations, default values, -assignments, and inheritance. Finally, project files can be built -hierarchically from other project files, simplifying complex system -integration and project reuse. - -A @dfn{project} is a specific set of values for various compilation properties. -The settings for a given project are described by means of -a @dfn{project file}, which is a text file written in an Ada-like syntax. -Property values in project files are either strings or lists of strings. -Properties that are not explicitly set receive default values. A project -file may interrogate the values of @dfn{external variables} (user-defined -command-line switches or environment variables), and it may specify property -settings conditionally, based on the value of such variables. - -In simple cases, a project's source files depend only on other source files -in the same project, or on the predefined libraries. (@emph{Dependence} is -used in -the Ada technical sense; as in one Ada unit @code{with}ing another.) However, -the Project Manager also allows more sophisticated arrangements, -where the source files in one project depend on source files in other -projects: -@itemize @bullet -@item -One project can @emph{import} other projects containing needed source files. -@item -You can organize GNAT projects in a hierarchy: a @emph{child} project -can extend a @emph{parent} project, inheriting the parent's source files and -optionally overriding any of them with alternative versions -@end itemize - -@noindent -More generally, the Project Manager lets you structure large development -efforts into hierarchical subsystems, where build decisions are delegated -to the subsystem level, and thus different compilation environments -(^switch^switch^ settings) used for different subsystems. - -The Project Manager is invoked through the -@option{^-P^/PROJECT_FILE=^@emph{projectfile}} -switch to @command{gnatmake} or to the @command{^gnat^GNAT^} front driver. -@ifclear vms -There may be zero, one or more spaces between @option{-P} and -@option{@emph{projectfile}}. -@end ifclear -If you want to define (on the command line) an external variable that is -queried by the project file, you must use the -@option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. -The Project Manager parses and interprets the project file, and drives the -invoked tool based on the project settings. - -The Project Manager supports a wide range of development strategies, -for systems of all sizes. Here are some typical practices that are -easily handled: -@itemize @bullet -@item -Using a common set of source files, but generating object files in different -directories via different ^switch^switch^ settings -@item -Using a mostly-shared set of source files, but with different versions of -some unit or units -@end itemize - -@noindent -The destination of an executable can be controlled inside a project file -using the @option{^-o^-o^} -^switch^switch^. -In the absence of such a ^switch^switch^ either inside -the project file or on the command line, any executable files generated by -@command{gnatmake} are placed in the directory @code{Exec_Dir} specified -in the project file. If no @code{Exec_Dir} is specified, they will be placed -in the object directory of the project. - -You can use project files to achieve some of the effects of a source -versioning system (for example, defining separate projects for -the different sets of sources that comprise different releases) but the -Project Manager is independent of any source configuration management tools -that might be used by the developers. - -The next section introduces the main features of GNAT's project facility -through a sequence of examples; subsequent sections will present the syntax -and semantics in more detail. A more formal description of the project -facility appears in @ref{Project File Reference,,, gnat_rm, GNAT -Reference Manual}. - -@c ***************************** -@c * Examples of Project Files * -@c ***************************** - -@node Examples of Project Files -@section Examples of Project Files -@noindent -This section illustrates some of the typical uses of project files and -explains their basic structure and behavior. - -@menu -* Common Sources with Different ^Switches^Switches^ and Directories:: -* Using External Variables:: -* Importing Other Projects:: -* Extending a Project:: -@end menu - -@node Common Sources with Different ^Switches^Switches^ and Directories -@subsection Common Sources with Different ^Switches^Switches^ and Directories - -@menu -* Source Files:: -* Specifying the Object Directory:: -* Specifying the Exec Directory:: -* Project File Packages:: -* Specifying ^Switch^Switch^ Settings:: -* Main Subprograms:: -* Executable File Names:: -* Source File Naming Conventions:: -* Source Language(s):: -@end menu - -@noindent -Suppose that the Ada source files @file{pack.ads}, @file{pack.adb}, and -@file{proc.adb} are in the @file{/common} directory. The file -@file{proc.adb} contains an Ada main subprogram @code{Proc} that @code{with}s -package @code{Pack}. We want to compile these source files under two sets -of ^switches^switches^: -@itemize @bullet -@item -When debugging, we want to pass the @option{-g} switch to @command{gnatmake}, -and the @option{^-gnata^-gnata^}, -@option{^-gnato^-gnato^}, -and @option{^-gnatE^-gnatE^} switches to the -compiler; the compiler's output is to appear in @file{/common/debug} -@item -When preparing a release version, we want to pass the @option{^-O2^O2^} switch -to the compiler; the compiler's output is to appear in @file{/common/release} -@end itemize - -@noindent -The GNAT project files shown below, respectively @file{debug.gpr} and -@file{release.gpr} in the @file{/common} directory, achieve these effects. - -Schematically: -@smallexample -@group -^/common^[COMMON]^ - debug.gpr - release.gpr - pack.ads - pack.adb - proc.adb -@end group -@group -^/common/debug^[COMMON.DEBUG]^ - proc.ali, proc.o - pack.ali, pack.o -@end group -@group -^/common/release^[COMMON.RELEASE]^ - proc.ali, proc.o - pack.ali, pack.o -@end group -@end smallexample -Here are the corresponding project files: - -@smallexample @c projectfile -@group -project Debug is - for Object_Dir use "debug"; - for Main use ("proc"); - - package Builder is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for Executable ("proc.adb") use "proc1"; - end Builder; -@end group - -@group - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("-fstack-check", - "^-gnata^-gnata^", - "^-gnato^-gnato^", - "^-gnatE^-gnatE^"); - end Compiler; -end Debug; -@end group -@end smallexample - -@smallexample @c projectfile -@group -project Release is - for Object_Dir use "release"; - for Exec_Dir use "."; - for Main use ("proc"); - - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-O2^-O2^"); - end Compiler; -end Release; -@end group -@end smallexample - -@noindent -The name of the project defined by @file{debug.gpr} is @code{"Debug"} (case -insensitive), and analogously the project defined by @file{release.gpr} is -@code{"Release"}. For consistency the file should have the same name as the -project, and the project file's extension should be @code{"gpr"}. These -conventions are not required, but a warning is issued if they are not followed. - -If the current directory is @file{^/temp^[TEMP]^}, then the command -@smallexample -gnatmake ^-P/common/debug.gpr^/PROJECT_FILE=[COMMON]DEBUG^ -@end smallexample - -@noindent -generates object and ALI files in @file{^/common/debug^[COMMON.DEBUG]^}, -as well as the @code{^proc1^PROC1.EXE^} executable, -using the ^switch^switch^ settings defined in the project file. - -Likewise, the command -@smallexample -gnatmake ^-P/common/release.gpr^/PROJECT_FILE=[COMMON]RELEASE^ -@end smallexample - -@noindent -generates object and ALI files in @file{^/common/release^[COMMON.RELEASE]^}, -and the @code{^proc^PROC.EXE^} -executable in @file{^/common^[COMMON]^}, -using the ^switch^switch^ settings from the project file. - -@node Source Files -@unnumberedsubsubsec Source Files - -@noindent -If a project file does not explicitly specify a set of source directories or -a set of source files, then by default the project's source files are the -Ada source files in the project file directory. Thus @file{pack.ads}, -@file{pack.adb}, and @file{proc.adb} are the source files for both projects. - -@node Specifying the Object Directory -@unnumberedsubsubsec Specifying the Object Directory - -@noindent -Several project properties are modeled by Ada-style @emph{attributes}; -a property is defined by supplying the equivalent of an Ada attribute -definition clause in the project file. -A project's object directory is another such a property; the corresponding -attribute is @code{Object_Dir}, and its value is also a string expression, -specified either as absolute or relative. In the later case, -it is relative to the project file directory. Thus the compiler's -output is directed to @file{^/common/debug^[COMMON.DEBUG]^} -(for the @code{Debug} project) -and to @file{^/common/release^[COMMON.RELEASE]^} -(for the @code{Release} project). -If @code{Object_Dir} is not specified, then the default is the project file -directory itself. - -@node Specifying the Exec Directory -@unnumberedsubsubsec Specifying the Exec Directory - -@noindent -A project's exec directory is another property; the corresponding -attribute is @code{Exec_Dir}, and its value is also a string expression, -either specified as relative or absolute. If @code{Exec_Dir} is not specified, -then the default is the object directory (which may also be the project file -directory if attribute @code{Object_Dir} is not specified). Thus the executable -is placed in @file{^/common/debug^[COMMON.DEBUG]^} -for the @code{Debug} project (attribute @code{Exec_Dir} not specified) -and in @file{^/common^[COMMON]^} for the @code{Release} project. - -@node Project File Packages -@unnumberedsubsubsec Project File Packages - -@noindent -A GNAT tool that is integrated with the Project Manager is modeled by a -corresponding package in the project file. In the example above, -The @code{Debug} project defines the packages @code{Builder} -(for @command{gnatmake}) and @code{Compiler}; -the @code{Release} project defines only the @code{Compiler} package. - -The Ada-like package syntax is not to be taken literally. Although packages in -project files bear a surface resemblance to packages in Ada source code, the -notation is simply a way to convey a grouping of properties for a named -entity. Indeed, the package names permitted in project files are restricted -to a predefined set, corresponding to the project-aware tools, and the contents -of packages are limited to a small set of constructs. -The packages in the example above contain attribute definitions. - -@node Specifying ^Switch^Switch^ Settings -@unnumberedsubsubsec Specifying ^Switch^Switch^ Settings - -@noindent -^Switch^Switch^ settings for a project-aware tool can be specified through -attributes in the package that corresponds to the tool. -The example above illustrates one of the relevant attributes, -@code{^Default_Switches^Default_Switches^}, which is defined in packages -in both project files. -Unlike simple attributes like @code{Source_Dirs}, -@code{^Default_Switches^Default_Switches^} is -known as an @emph{associative array}. When you define this attribute, you must -supply an ``index'' (a literal string), and the effect of the attribute -definition is to set the value of the array at the specified index. -For the @code{^Default_Switches^Default_Switches^} attribute, -the index is a programming language (in our case, Ada), -and the value specified (after @code{use}) must be a list -of string expressions. - -The attributes permitted in project files are restricted to a predefined set. -Some may appear at project level, others in packages. -For any attribute that is an associative array, the index must always be a -literal string, but the restrictions on this string (e.g., a file name or a -language name) depend on the individual attribute. -Also depending on the attribute, its specified value will need to be either a -string or a string list. - -In the @code{Debug} project, we set the switches for two tools, -@command{gnatmake} and the compiler, and thus we include the two corresponding -packages; each package defines the @code{^Default_Switches^Default_Switches^} -attribute with index @code{"Ada"}. -Note that the package corresponding to -@command{gnatmake} is named @code{Builder}. The @code{Release} project is -similar, but only includes the @code{Compiler} package. - -In project @code{Debug} above, the ^switches^switches^ starting with -@option{-gnat} that are specified in package @code{Compiler} -could have been placed in package @code{Builder}, since @command{gnatmake} -transmits all such ^switches^switches^ to the compiler. - -@node Main Subprograms -@unnumberedsubsubsec Main Subprograms - -@noindent -One of the specifiable properties of a project is a list of files that contain -main subprograms. This property is captured in the @code{Main} attribute, -whose value is a list of strings. If a project defines the @code{Main} -attribute, it is not necessary to identify the main subprogram(s) when -invoking @command{gnatmake} (@pxref{gnatmake and Project Files}). - -@node Executable File Names -@unnumberedsubsubsec Executable File Names - -@noindent -By default, the executable file name corresponding to a main source is -deduced from the main source file name. Through the attributes -@code{Executable} and @code{Executable_Suffix} of package @code{Builder}, -it is possible to change this default. -In project @code{Debug} above, the executable file name -for main source @file{^proc.adb^PROC.ADB^} is -@file{^proc1^PROC1.EXE^}. -Attribute @code{Executable_Suffix}, when specified, may change the suffix -of the executable files, when no attribute @code{Executable} applies: -its value replace the platform-specific executable suffix. -Attributes @code{Executable} and @code{Executable_Suffix} are the only ways to -specify a non-default executable file name when several mains are built at once -in a single @command{gnatmake} command. - -@node Source File Naming Conventions -@unnumberedsubsubsec Source File Naming Conventions - -@noindent -Since the project files above do not specify any source file naming -conventions, the GNAT defaults are used. The mechanism for defining source -file naming conventions -- a package named @code{Naming} -- -is described below (@pxref{Naming Schemes}). - -@node Source Language(s) -@unnumberedsubsubsec Source Language(s) - -@noindent -Since the project files do not specify a @code{Languages} attribute, by -default the GNAT tools assume that the language of the project file is Ada. -More generally, a project can comprise source files -in Ada, C, and/or other languages. - -@node Using External Variables -@subsection Using External Variables - -@noindent -Instead of supplying different project files for debug and release, we can -define a single project file that queries an external variable (set either -on the command line or via an ^environment variable^logical name^) in order to -conditionally define the appropriate settings. Again, assume that the -source files @file{pack.ads}, @file{pack.adb}, and @file{proc.adb} are -located in directory @file{^/common^[COMMON]^}. The following project file, -@file{build.gpr}, queries the external variable named @code{STYLE} and -defines an object directory and ^switch^switch^ settings based on whether -the value is @code{"deb"} (debug) or @code{"rel"} (release), and where -the default is @code{"deb"}. - -@smallexample @c projectfile -@group -project Build is - for Main use ("proc"); - - type Style_Type is ("deb", "rel"); - Style : Style_Type := external ("STYLE", "deb"); - - case Style is - when "deb" => - for Object_Dir use "debug"; - - when "rel" => - for Object_Dir use "release"; - for Exec_Dir use "."; - end case; -@end group - -@group - package Builder is - - case Style is - when "deb" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for Executable ("proc") use "proc1"; - when others => - null; - end case; - - end Builder; -@end group - -@group - package Compiler is - - case Style is - when "deb" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnata^-gnata^", - "^-gnato^-gnato^", - "^-gnatE^-gnatE^"); - - when "rel" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-O2^-O2^"); - end case; - - end Compiler; - -end Build; -@end group -@end smallexample - -@noindent -@code{Style_Type} is an example of a @emph{string type}, which is the project -file analog of an Ada enumeration type but whose components are string literals -rather than identifiers. @code{Style} is declared as a variable of this type. - -The form @code{external("STYLE", "deb")} is known as an -@emph{external reference}; its first argument is the name of an -@emph{external variable}, and the second argument is a default value to be -used if the external variable doesn't exist. You can define an external -variable on the command line via the @option{^-X^/EXTERNAL_REFERENCE^} switch, -or you can use ^an environment variable^a logical name^ -as an external variable. - -Each @code{case} construct is expanded by the Project Manager based on the -value of @code{Style}. Thus the command -@ifclear vms -@smallexample -gnatmake -P/common/build.gpr -XSTYLE=deb -@end smallexample -@end ifclear - -@ifset vms -@smallexample -gnatmake /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=deb -@end smallexample -@end ifset - -@noindent -is equivalent to the @command{gnatmake} invocation using the project file -@file{debug.gpr} in the earlier example. So is the command -@smallexample -gnatmake ^-P/common/build.gpr^/PROJECT_FILE=[COMMON]BUILD.GPR^ -@end smallexample - -@noindent -since @code{"deb"} is the default for @code{STYLE}. - -Analogously, - -@ifclear vms -@smallexample -gnatmake -P/common/build.gpr -XSTYLE=rel -@end smallexample -@end ifclear - -@ifset vms -@smallexample -GNAT MAKE /PROJECT_FILE=[COMMON]BUILD.GPR /EXTERNAL_REFERENCE=STYLE=rel -@end smallexample -@end ifset - -@noindent -is equivalent to the @command{gnatmake} invocation using the project file -@file{release.gpr} in the earlier example. - -@node Importing Other Projects -@subsection Importing Other Projects -@cindex @code{ADA_PROJECT_PATH} - -@noindent -A compilation unit in a source file in one project may depend on compilation -units in source files in other projects. To compile this unit under -control of a project file, the -dependent project must @emph{import} the projects containing the needed source -files. -This effect is obtained using syntax similar to an Ada @code{with} clause, -but where @code{with}ed entities are strings that denote project files. - -As an example, suppose that the two projects @code{GUI_Proj} and -@code{Comm_Proj} are defined in the project files @file{gui_proj.gpr} and -@file{comm_proj.gpr} in directories @file{^/gui^[GUI]^} -and @file{^/comm^[COMM]^}, respectively. -Suppose that the source files for @code{GUI_Proj} are -@file{gui.ads} and @file{gui.adb}, and that the source files for -@code{Comm_Proj} are @file{comm.ads} and @file{comm.adb}, where each set of -files is located in its respective project file directory. Schematically: - -@smallexample -@group -^/gui^[GUI]^ - gui_proj.gpr - gui.ads - gui.adb -@end group - -@group -^/comm^[COMM]^ - comm_proj.gpr - comm.ads - comm.adb -@end group -@end smallexample - -@noindent -We want to develop an application in directory @file{^/app^[APP]^} that -@code{with} the packages @code{GUI} and @code{Comm}, using the properties of -the corresponding project files (e.g.@: the ^switch^switch^ settings -and object directory). -Skeletal code for a main procedure might be something like the following: - -@smallexample @c ada -@group -with GUI, Comm; -procedure App_Main is - @dots{} -begin - @dots{} -end App_Main; -@end group -@end smallexample - -@noindent -Here is a project file, @file{app_proj.gpr}, that achieves the desired -effect: - -@smallexample @c projectfile -@group -with "/gui/gui_proj", "/comm/comm_proj"; -project App_Proj is - for Main use ("app_main"); -end App_Proj; -@end group -@end smallexample - -@noindent -Building an executable is achieved through the command: -@smallexample -gnatmake ^-P/app/app_proj^/PROJECT_FILE=[APP]APP_PROJ^ -@end smallexample -@noindent -which will generate the @code{^app_main^APP_MAIN.EXE^} executable -in the directory where @file{app_proj.gpr} resides. - -If an imported project file uses the standard extension (@code{^gpr^GPR^}) then -(as illustrated above) the @code{with} clause can omit the extension. - -Our example specified an absolute path for each imported project file. -Alternatively, the directory name of an imported object can be omitted -if either -@itemize @bullet -@item -The imported project file is in the same directory as the importing project -file, or -@item -You have defined ^an environment variable^a logical name^ -that includes the directory containing -the needed project file. The syntax of @code{ADA_PROJECT_PATH} is the same as -the syntax of @code{ADA_INCLUDE_PATH} and @code{ADA_OBJECTS_PATH}: a list of -directory names separated by colons (semicolons on Windows). -@end itemize - -@noindent -Thus, if we define @code{ADA_PROJECT_PATH} to include @file{^/gui^[GUI]^} and -@file{^/comm^[COMM]^}, then our project file @file{app_proj.gpr} can be written -as follows: - -@smallexample @c projectfile -@group -with "gui_proj", "comm_proj"; -project App_Proj is - for Main use ("app_main"); -end App_Proj; -@end group -@end smallexample - -@noindent -Importing other projects can create ambiguities. -For example, the same unit might be present in different imported projects, or -it might be present in both the importing project and in an imported project. -Both of these conditions are errors. Note that in the current version of -the Project Manager, it is illegal to have an ambiguous unit even if the -unit is never referenced by the importing project. This restriction may be -relaxed in a future release. - -@node Extending a Project -@subsection Extending a Project - -@noindent -In large software systems it is common to have multiple -implementations of a common interface; in Ada terms, multiple versions of a -package body for the same spec. For example, one implementation -might be safe for use in tasking programs, while another might only be used -in sequential applications. This can be modeled in GNAT using the concept -of @emph{project extension}. If one project (the ``child'') @emph{extends} -another project (the ``parent'') then by default all source files of the -parent project are inherited by the child, but the child project can -override any of the parent's source files with new versions, and can also -add new files. This facility is the project analog of a type extension in -Object-Oriented Programming. Project hierarchies are permitted (a child -project may be the parent of yet another project), and a project that -inherits one project can also import other projects. - -As an example, suppose that directory @file{^/seq^[SEQ]^} contains the project -file @file{seq_proj.gpr} as well as the source files @file{pack.ads}, -@file{pack.adb}, and @file{proc.adb}: - -@smallexample -@group -^/seq^[SEQ]^ - pack.ads - pack.adb - proc.adb - seq_proj.gpr -@end group -@end smallexample - -@noindent -Note that the project file can simply be empty (that is, no attribute or -package is defined): - -@smallexample @c projectfile -@group -project Seq_Proj is -end Seq_Proj; -@end group -@end smallexample - -@noindent -implying that its source files are all the Ada source files in the project -directory. - -Suppose we want to supply an alternate version of @file{pack.adb}, in -directory @file{^/tasking^[TASKING]^}, but use the existing versions of -@file{pack.ads} and @file{proc.adb}. We can define a project -@code{Tasking_Proj} that inherits @code{Seq_Proj}: - -@smallexample -@group -^/tasking^[TASKING]^ - pack.adb - tasking_proj.gpr -@end group - -@group -project Tasking_Proj extends "/seq/seq_proj" is -end Tasking_Proj; -@end group -@end smallexample - -@noindent -The version of @file{pack.adb} used in a build depends on which project file -is specified. - -Note that we could have obtained the desired behavior using project import -rather than project inheritance; a @code{base} project would contain the -sources for @file{pack.ads} and @file{proc.adb}, a sequential project would -import @code{base} and add @file{pack.adb}, and likewise a tasking project -would import @code{base} and add a different version of @file{pack.adb}. The -choice depends on whether other sources in the original project need to be -overridden. If they do, then project extension is necessary, otherwise, -importing is sufficient. - -@noindent -In a project file that extends another project file, it is possible to -indicate that an inherited source is not part of the sources of the extending -project. This is necessary sometimes when a package spec has been overloaded -and no longer requires a body: in this case, it is necessary to indicate that -the inherited body is not part of the sources of the project, otherwise there -will be a compilation error when compiling the spec. - -For that purpose, the attribute @code{Excluded_Source_Files} is used. -Its value is a string list: a list of file names. It is also possible to use -attribute @code{Excluded_Source_List_File}. Its value is a single string: -the file name of a text file containing a list of file names, one per line. - -@smallexample @c @projectfile -project B extends "a" is - for Source_Files use ("pkg.ads"); - -- New spec of Pkg does not need a completion - for Excluded_Source_Files use ("pkg.adb"); -end B; -@end smallexample - -Attribute @code{Excluded_Source_Files} may also be used to check if a source -is still needed: if it is possible to build using @command{gnatmake} when such -a source is put in attribute @code{Excluded_Source_Files} of a project P, then -it is possible to remove the source completely from a system that includes -project P. - -@c *********************** -@c * Project File Syntax * -@c *********************** - -@node Project File Syntax -@section Project File Syntax - -@menu -* Basic Syntax:: -* Qualified Projects:: -* Packages:: -* Expressions:: -* String Types:: -* Variables:: -* Attributes:: -* Associative Array Attributes:: -* case Constructions:: -@end menu - -@noindent -This section describes the structure of project files. - -A project may be an @emph{independent project}, entirely defined by a single -project file. Any Ada source file in an independent project depends only -on the predefined library and other Ada source files in the same project. - -@noindent -A project may also @dfn{depend on} other projects, in either or both of -the following ways: -@itemize @bullet -@item It may import any number of projects -@item It may extend at most one other project -@end itemize - -@noindent -The dependence relation is a directed acyclic graph (the subgraph reflecting -the ``extends'' relation is a tree). - -A project's @dfn{immediate sources} are the source files directly defined by -that project, either implicitly by residing in the project file's directory, -or explicitly through any of the source-related attributes described below. -More generally, a project @var{proj}'s @dfn{sources} are the immediate sources -of @var{proj} together with the immediate sources (unless overridden) of any -project on which @var{proj} depends (either directly or indirectly). - -@node Basic Syntax -@subsection Basic Syntax - -@noindent -As seen in the earlier examples, project files have an Ada-like syntax. -The minimal project file is: -@smallexample @c projectfile -@group -project Empty is - -end Empty; -@end group -@end smallexample - -@noindent -The identifier @code{Empty} is the name of the project. -This project name must be present after the reserved -word @code{end} at the end of the project file, followed by a semi-colon. - -Any name in a project file, such as the project name or a variable name, -has the same syntax as an Ada identifier. - -The reserved words of project files are the Ada 95 reserved words plus -@code{extends}, @code{external}, and @code{project}. Note that the only Ada -reserved words currently used in project file syntax are: - -@itemize @bullet -@item -@code{all} -@item -@code{at} -@item -@code{case} -@item -@code{end} -@item -@code{for} -@item -@code{is} -@item -@code{limited} -@item -@code{null} -@item -@code{others} -@item -@code{package} -@item -@code{renames} -@item -@code{type} -@item -@code{use} -@item -@code{when} -@item -@code{with} -@end itemize - -@noindent -Comments in project files have the same syntax as in Ada, two consecutive -hyphens through the end of the line. - -@node Qualified Projects -@subsection Qualified Projects - -@noindent -Before the reserved @code{project}, there may be one or two "qualifiers", that -is identifiers or other reserved words, to qualify the project. - -The current list of qualifiers is: - -@itemize @bullet -@item -@code{abstract}: qualify a project with no sources. An abstract project must -have a declaration specifying that there are no sources in the project, and, -if it extends another project, the project it extends must also be a qualified -abstract project. - -@item -@code{standard}: a standard project is a non library project with sources. - -@item -@code{aggregate}: for future extension - -@item -@code{aggregate library}: for future extension - -@item -@code{library}: a library project must declare both attributes -@code{Library_Name} and @code{Library_Dir}. - -@item -@code{configuration}: a configuration project cannot be in a project tree. -@end itemize - -@node Packages -@subsection Packages - -@noindent -A project file may contain @emph{packages}. The name of a package must be one -of the identifiers from the following list. A package -with a given name may only appear once in a project file. Package names are -case insensitive. The following package names are legal: - -@itemize @bullet -@item -@code{Naming} -@item -@code{Builder} -@item -@code{Compiler} -@item -@code{Binder} -@item -@code{Linker} -@item -@code{Finder} -@item -@code{Cross_Reference} -@item -@code{Eliminate} -@item -@code{Pretty_Printer} -@item -@code{Metrics} -@item -@code{gnatls} -@item -@code{gnatstub} -@item -@code{IDE} -@item -@code{Language_Processing} -@end itemize - -@noindent -In its simplest form, a package may be empty: - -@smallexample @c projectfile -@group -project Simple is - package Builder is - end Builder; -end Simple; -@end group -@end smallexample - -@noindent -A package may contain @emph{attribute declarations}, -@emph{variable declarations} and @emph{case constructions}, as will be -described below. - -When there is ambiguity between a project name and a package name, -the name always designates the project. To avoid possible confusion, it is -always a good idea to avoid naming a project with one of the -names allowed for packages or any name that starts with @code{gnat}. - -@node Expressions -@subsection Expressions - -@noindent -An @emph{expression} is either a @emph{string expression} or a -@emph{string list expression}. - -A @emph{string expression} is either a @emph{simple string expression} or a -@emph{compound string expression}. - -A @emph{simple string expression} is one of the following: -@itemize @bullet -@item A literal string; e.g.@: @code{"comm/my_proj.gpr"} -@item A string-valued variable reference (@pxref{Variables}) -@item A string-valued attribute reference (@pxref{Attributes}) -@item An external reference (@pxref{External References in Project Files}) -@end itemize - -@noindent -A @emph{compound string expression} is a concatenation of string expressions, -using the operator @code{"&"} -@smallexample - Path & "/" & File_Name & ".ads" -@end smallexample - -@noindent -A @emph{string list expression} is either a -@emph{simple string list expression} or a -@emph{compound string list expression}. - -A @emph{simple string list expression} is one of the following: -@itemize @bullet -@item A parenthesized list of zero or more string expressions, -separated by commas -@smallexample - File_Names := (File_Name, "gnat.adc", File_Name & ".orig"); - Empty_List := (); -@end smallexample -@item A string list-valued variable reference -@item A string list-valued attribute reference -@end itemize - -@noindent -A @emph{compound string list expression} is the concatenation (using -@code{"&"}) of a simple string list expression and an expression. Note that -each term in a compound string list expression, except the first, may be -either a string expression or a string list expression. - -@smallexample @c projectfile -@group - File_Name_List := () & File_Name; -- One string in this list - Extended_File_Name_List := File_Name_List & (File_Name & ".orig"); - -- Two strings - Big_List := File_Name_List & Extended_File_Name_List; - -- Concatenation of two string lists: three strings - Illegal_List := "gnat.adc" & Extended_File_Name_List; - -- Illegal: must start with a string list -@end group -@end smallexample - -@node String Types -@subsection String Types - -@noindent -A @emph{string type declaration} introduces a discrete set of string literals. -If a string variable is declared to have this type, its value -is restricted to the given set of literals. - -Here is an example of a string type declaration: - -@smallexample @c projectfile - type OS is ("NT", "nt", "Unix", "GNU/Linux", "other OS"); -@end smallexample - -@noindent -Variables of a string type are called @emph{typed variables}; all other -variables are called @emph{untyped variables}. Typed variables are -particularly useful in @code{case} constructions, to support conditional -attribute declarations. -(@pxref{case Constructions}). - -The string literals in the list are case sensitive and must all be different. -They may include any graphic characters allowed in Ada, including spaces. - -A string type may only be declared at the project level, not inside a package. - -A string type may be referenced by its name if it has been declared in the same -project file, or by an expanded name whose prefix is the name of the project -in which it is declared. - -@node Variables -@subsection Variables - -@noindent -A variable may be declared at the project file level, or within a package. -Here are some examples of variable declarations: - -@smallexample @c projectfile -@group - This_OS : OS := external ("OS"); -- a typed variable declaration - That_OS := "GNU/Linux"; -- an untyped variable declaration -@end group -@end smallexample - -@noindent -The syntax of a @emph{typed variable declaration} is identical to the Ada -syntax for an object declaration. By contrast, the syntax of an untyped -variable declaration is identical to an Ada assignment statement. In fact, -variable declarations in project files have some of the characteristics of -an assignment, in that successive declarations for the same variable are -allowed. Untyped variable declarations do establish the expected kind of the -variable (string or string list), and successive declarations for it must -respect the initial kind. - -@noindent -A string variable declaration (typed or untyped) declares a variable -whose value is a string. This variable may be used as a string expression. -@smallexample @c projectfile - File_Name := "readme.txt"; - Saved_File_Name := File_Name & ".saved"; -@end smallexample - -@noindent -A string list variable declaration declares a variable whose value is a list -of strings. The list may contain any number (zero or more) of strings. - -@smallexample @c projectfile - Empty_List := (); - List_With_One_Element := ("^-gnaty^-gnaty^"); - List_With_Two_Elements := List_With_One_Element & "^-gnatg^-gnatg^"; - Long_List := ("main.ada", "pack1_.ada", "pack1.ada", "pack2_.ada" - "pack2.ada", "util_.ada", "util.ada"); -@end smallexample - -@noindent -The same typed variable may not be declared more than once at project level, -and it may not be declared more than once in any package; it is in effect -a constant. - -The same untyped variable may be declared several times. Declarations are -elaborated in the order in which they appear, so the new value replaces -the old one, and any subsequent reference to the variable uses the new value. -However, as noted above, if a variable has been declared as a string, all -subsequent -declarations must give it a string value. Similarly, if a variable has -been declared as a string list, all subsequent declarations -must give it a string list value. - -A @emph{variable reference} may take several forms: - -@itemize @bullet -@item The simple variable name, for a variable in the current package (if any) -or in the current project -@item An expanded name, whose prefix is a context name. -@end itemize - -@noindent -A @emph{context} may be one of the following: - -@itemize @bullet -@item The name of an existing package in the current project -@item The name of an imported project of the current project -@item The name of an ancestor project (i.e., a project extended by the current -project, either directly or indirectly) -@item An expanded name whose prefix is an imported/parent project name, and -whose selector is a package name in that project. -@end itemize - -@noindent -A variable reference may be used in an expression. - -@node Attributes -@subsection Attributes - -@noindent -A project (and its packages) may have @emph{attributes} that define -the project's properties. Some attributes have values that are strings; -others have values that are string lists. - -There are two categories of attributes: @emph{simple attributes} -and @emph{associative arrays} (@pxref{Associative Array Attributes}). - -Legal project attribute names, and attribute names for each legal package are -listed below. Attributes names are case-insensitive. - -The following attributes are defined on projects (all are simple attributes): - -@multitable @columnfractions .4 .3 -@item @emph{Attribute Name} -@tab @emph{Value} -@item @code{Source_Files} -@tab string list -@item @code{Source_Dirs} -@tab string list -@item @code{Source_List_File} -@tab string -@item @code{Object_Dir} -@tab string -@item @code{Exec_Dir} -@tab string -@item @code{Excluded_Source_Dirs} -@tab string list -@item @code{Excluded_Source_Files} -@tab string list -@item @code{Excluded_Source_List_File} -@tab string -@item @code{Languages} -@tab string list -@item @code{Main} -@tab string list -@item @code{Library_Dir} -@tab string -@item @code{Library_Name} -@tab string -@item @code{Library_Kind} -@tab string -@item @code{Library_Version} -@tab string -@item @code{Library_Interface} -@tab string -@item @code{Library_Auto_Init} -@tab string -@item @code{Library_Options} -@tab string list -@item @code{Library_Src_Dir} -@tab string -@item @code{Library_ALI_Dir} -@tab string -@item @code{Library_GCC} -@tab string -@item @code{Library_Symbol_File} -@tab string -@item @code{Library_Symbol_Policy} -@tab string -@item @code{Library_Reference_Symbol_File} -@tab string -@item @code{Externally_Built} -@tab string -@end multitable - -@noindent -The following attributes are defined for package @code{Naming} -(@pxref{Naming Schemes}): - -@multitable @columnfractions .4 .2 .2 .2 -@item Attribute Name @tab Category @tab Index @tab Value -@item @code{Spec_Suffix} -@tab associative array -@tab language name -@tab string -@item @code{Body_Suffix} -@tab associative array -@tab language name -@tab string -@item @code{Separate_Suffix} -@tab simple attribute -@tab n/a -@tab string -@item @code{Casing} -@tab simple attribute -@tab n/a -@tab string -@item @code{Dot_Replacement} -@tab simple attribute -@tab n/a -@tab string -@item @code{Spec} -@tab associative array -@tab Ada unit name -@tab string -@item @code{Body} -@tab associative array -@tab Ada unit name -@tab string -@item @code{Specification_Exceptions} -@tab associative array -@tab language name -@tab string list -@item @code{Implementation_Exceptions} -@tab associative array -@tab language name -@tab string list -@end multitable - -@noindent -The following attributes are defined for packages @code{Builder}, -@code{Compiler}, @code{Binder}, -@code{Linker}, @code{Cross_Reference}, and @code{Finder} -(@pxref{^Switches^Switches^ and Project Files}). - -@multitable @columnfractions .4 .2 .2 .2 -@item Attribute Name @tab Category @tab Index @tab Value -@item @code{^Default_Switches^Default_Switches^} -@tab associative array -@tab language name -@tab string list -@item @code{^Switches^Switches^} -@tab associative array -@tab file name -@tab string list -@end multitable - -@noindent -In addition, package @code{Compiler} has a single string attribute -@code{Local_Configuration_Pragmas} and package @code{Builder} has a single -string attribute @code{Global_Configuration_Pragmas}. - -@noindent -Each simple attribute has a default value: the empty string (for string-valued -attributes) and the empty list (for string list-valued attributes). - -An attribute declaration defines a new value for an attribute. - -Examples of simple attribute declarations: - -@smallexample @c projectfile - for Object_Dir use "objects"; - for Source_Dirs use ("units", "test/drivers"); -@end smallexample - -@noindent -The syntax of a @dfn{simple attribute declaration} is similar to that of an -attribute definition clause in Ada. - -Attributes references may be appear in expressions. -The general form for such a reference is @code{<entity>'<attribute>}: -Associative array attributes are functions. Associative -array attribute references must have an argument that is a string literal. - -Examples are: - -@smallexample @c projectfile - project'Object_Dir - Naming'Dot_Replacement - Imported_Project'Source_Dirs - Imported_Project.Naming'Casing - Builder'^Default_Switches^Default_Switches^("Ada") -@end smallexample - -@noindent -The prefix of an attribute may be: -@itemize @bullet -@item @code{project} for an attribute of the current project -@item The name of an existing package of the current project -@item The name of an imported project -@item The name of a parent project that is extended by the current project -@item An expanded name whose prefix is imported/parent project name, -and whose selector is a package name -@end itemize - -@noindent -Example: -@smallexample @c projectfile -@group - project Prj is - for Source_Dirs use project'Source_Dirs & "units"; - for Source_Dirs use project'Source_Dirs & "test/drivers" - end Prj; -@end group -@end smallexample - -@noindent -In the first attribute declaration, initially the attribute @code{Source_Dirs} -has the default value: an empty string list. After this declaration, -@code{Source_Dirs} is a string list of one element: @code{"units"}. -After the second attribute declaration @code{Source_Dirs} is a string list of -two elements: @code{"units"} and @code{"test/drivers"}. - -Note: this example is for illustration only. In practice, -the project file would contain only one attribute declaration: - -@smallexample @c projectfile - for Source_Dirs use ("units", "test/drivers"); -@end smallexample - -@node Associative Array Attributes -@subsection Associative Array Attributes - -@noindent -Some attributes are defined as @emph{associative arrays}. An associative -array may be regarded as a function that takes a string as a parameter -and delivers a string or string list value as its result. - -Here are some examples of single associative array attribute associations: - -@smallexample @c projectfile - for Body ("main") use "Main.ada"; - for ^Switches^Switches^ ("main.ada") - use ("^-v^-v^", - "^-gnatv^-gnatv^"); - for ^Switches^Switches^ ("main.ada") - use Builder'^Switches^Switches^ ("main.ada") - & "^-g^-g^"; -@end smallexample - -@noindent -Like untyped variables and simple attributes, associative array attributes -may be declared several times. Each declaration supplies a new value for the -attribute, and replaces the previous setting. - -@noindent -An associative array attribute may be declared as a full associative array -declaration, with the value of the same attribute in an imported or extended -project. - -@smallexample @c projectfile - package Builder is - for Default_Switches use Default.Builder'Default_Switches; - end Builder; -@end smallexample - -@noindent -In this example, @code{Default} must be either a project imported by the -current project, or the project that the current project extends. If the -attribute is in a package (in this case, in package @code{Builder}), the same -package needs to be specified. - -@noindent -A full associative array declaration replaces any other declaration for the -attribute, including other full associative array declaration. Single -associative array associations may be declare after a full associative -declaration, modifying the value for a single association of the attribute. - -@node case Constructions -@subsection @code{case} Constructions - -@noindent -A @code{case} construction is used in a project file to effect conditional -behavior. -Here is a typical example: - -@smallexample @c projectfile -@group -project MyProj is - type OS_Type is ("GNU/Linux", "Unix", "NT", "VMS"); - - OS : OS_Type := external ("OS", "GNU/Linux"); -@end group - -@group - package Compiler is - case OS is - when "GNU/Linux" | "Unix" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnath^-gnath^"); - when "NT" => - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnatP^-gnatP^"); - when others => - end case; - end Compiler; -end MyProj; -@end group -@end smallexample - -@noindent -The syntax of a @code{case} construction is based on the Ada case statement -(although there is no @code{null} construction for empty alternatives). - -The case expression must be a typed string variable. -Each alternative comprises the reserved word @code{when}, either a list of -literal strings separated by the @code{"|"} character or the reserved word -@code{others}, and the @code{"=>"} token. -Each literal string must belong to the string type that is the type of the -case variable. -An @code{others} alternative, if present, must occur last. - -After each @code{=>}, there are zero or more constructions. The only -constructions allowed in a case construction are other case constructions, -attribute declarations and variable declarations. String type declarations and -package declarations are not allowed. Variable declarations are restricted to -variables that have already been declared before the case construction. - -The value of the case variable is often given by an external reference -(@pxref{External References in Project Files}). - -@c **************************************** -@c * Objects and Sources in Project Files * -@c **************************************** - -@node Objects and Sources in Project Files -@section Objects and Sources in Project Files - -@menu -* Object Directory:: -* Exec Directory:: -* Source Directories:: -* Source File Names:: -@end menu - -@noindent -Each project has exactly one object directory and one or more source -directories. The source directories must contain at least one source file, -unless the project file explicitly specifies that no source files are present -(@pxref{Source File Names}). - -@node Object Directory -@subsection Object Directory - -@noindent -The object directory for a project is the directory containing the compiler's -output (such as @file{ALI} files and object files) for the project's immediate -sources. - -The object directory is given by the value of the attribute @code{Object_Dir} -in the project file. - -@smallexample @c projectfile - for Object_Dir use "objects"; -@end smallexample - -@noindent -The attribute @code{Object_Dir} has a string value, the path name of the object -directory. The path name may be absolute or relative to the directory of the -project file. This directory must already exist, and be readable and writable. - -By default, when the attribute @code{Object_Dir} is not given an explicit value -or when its value is the empty string, the object directory is the same as the -directory containing the project file. - -@node Exec Directory -@subsection Exec Directory - -@noindent -The exec directory for a project is the directory containing the executables -for the project's main subprograms. - -The exec directory is given by the value of the attribute @code{Exec_Dir} -in the project file. - -@smallexample @c projectfile - for Exec_Dir use "executables"; -@end smallexample - -@noindent -The attribute @code{Exec_Dir} has a string value, the path name of the exec -directory. The path name may be absolute or relative to the directory of the -project file. This directory must already exist, and be writable. - -By default, when the attribute @code{Exec_Dir} is not given an explicit value -or when its value is the empty string, the exec directory is the same as the -object directory of the project file. - -@node Source Directories -@subsection Source Directories - -@noindent -The source directories of a project are specified by the project file -attribute @code{Source_Dirs}. - -This attribute's value is a string list. If the attribute is not given an -explicit value, then there is only one source directory, the one where the -project file resides. - -A @code{Source_Dirs} attribute that is explicitly defined to be the empty list, -as in - -@smallexample @c projectfile - for Source_Dirs use (); -@end smallexample - -@noindent -indicates that the project contains no source files. - -Otherwise, each string in the string list designates one or more -source directories. - -@smallexample @c projectfile - for Source_Dirs use ("sources", "test/drivers"); -@end smallexample - -@noindent -If a string in the list ends with @code{"/**"}, then the directory whose path -name precedes the two asterisks, as well as all its subdirectories -(recursively), are source directories. - -@smallexample @c projectfile - for Source_Dirs use ("/system/sources/**"); -@end smallexample - -@noindent -Here the directory @code{/system/sources} and all of its subdirectories -(recursively) are source directories. - -To specify that the source directories are the directory of the project file -and all of its subdirectories, you can declare @code{Source_Dirs} as follows: -@smallexample @c projectfile - for Source_Dirs use ("./**"); -@end smallexample - -@noindent -Each of the source directories must exist and be readable. - -@node Source File Names -@subsection Source File Names - -@noindent -In a project that contains source files, their names may be specified by the -attributes @code{Source_Files} (a string list) or @code{Source_List_File} -(a string). Source file names never include any directory information. - -If the attribute @code{Source_Files} is given an explicit value, then each -element of the list is a source file name. - -@smallexample @c projectfile - for Source_Files use ("main.adb"); - for Source_Files use ("main.adb", "pack1.ads", "pack2.adb"); -@end smallexample - -@noindent -If the attribute @code{Source_Files} is not given an explicit value, -but the attribute @code{Source_List_File} is given a string value, -then the source file names are contained in the text file whose path name -(absolute or relative to the directory of the project file) is the -value of the attribute @code{Source_List_File}. - -Each line in the file that is not empty or is not a comment -contains a source file name. - -@smallexample @c projectfile - for Source_List_File use "source_list.txt"; -@end smallexample - -@noindent -By default, if neither the attribute @code{Source_Files} nor the attribute -@code{Source_List_File} is given an explicit value, then each file in the -source directories that conforms to the project's naming scheme -(@pxref{Naming Schemes}) is an immediate source of the project. - -A warning is issued if both attributes @code{Source_Files} and -@code{Source_List_File} are given explicit values. In this case, the attribute -@code{Source_Files} prevails. - -Each source file name must be the name of one existing source file -in one of the source directories. - -A @code{Source_Files} attribute whose value is an empty list -indicates that there are no source files in the project. - -If the order of the source directories is known statically, that is if -@code{"/**"} is not used in the string list @code{Source_Dirs}, then there may -be several files with the same source file name. In this case, only the file -in the first directory is considered as an immediate source of the project -file. If the order of the source directories is not known statically, it is -an error to have several files with the same source file name. - -Projects can be specified to have no Ada source -files: the value of (@code{Source_Dirs} or @code{Source_Files} may be an empty -list, or the @code{"Ada"} may be absent from @code{Languages}: - -@smallexample @c projectfile - for Source_Dirs use (); - for Source_Files use (); - for Languages use ("C", "C++"); -@end smallexample - -@noindent -Otherwise, a project must contain at least one immediate source. - -Projects with no source files are useful as template packages -(@pxref{Packages in Project Files}) for other projects; in particular to -define a package @code{Naming} (@pxref{Naming Schemes}). - -@c **************************** -@c * Importing Projects * -@c **************************** - -@node Importing Projects -@section Importing Projects -@cindex @code{ADA_PROJECT_PATH} - -@noindent -An immediate source of a project P may depend on source files that -are neither immediate sources of P nor in the predefined library. -To get this effect, P must @emph{import} the projects that contain the needed -source files. - -@smallexample @c projectfile -@group - with "project1", "utilities.gpr"; - with "/namings/apex.gpr"; - project Main is - @dots{} -@end group -@end smallexample - -@noindent -As can be seen in this example, the syntax for importing projects is similar -to the syntax for importing compilation units in Ada. However, project files -use literal strings instead of names, and the @code{with} clause identifies -project files rather than packages. - -Each literal string is the file name or path name (absolute or relative) of a -project file. If a string corresponds to a file name, with no path or a -relative path, then its location is determined by the @emph{project path}. The -latter can be queried using @code{gnatls -v}. It contains: - -@itemize @bullet -@item -In first position, the directory containing the current project file. -@item -In last position, the default project directory. This default project directory -is part of the GNAT installation and is the standard place to install project -files giving access to standard support libraries. -@ifclear vms -@ref{Installing a library} -@end ifclear - -@item -In between, all the directories referenced in the -^environment variable^logical name^ @env{ADA_PROJECT_PATH} if it exists. -@end itemize - -@noindent -If a relative pathname is used, as in - -@smallexample @c projectfile - with "tests/proj"; -@end smallexample - -@noindent -then the full path for the project is constructed by concatenating this -relative path to those in the project path, in order, until a matching file is -found. Any symbolic link will be fully resolved in the directory of the -importing project file before the imported project file is examined. - -If the @code{with}'ed project file name does not have an extension, -the default is @file{^.gpr^.GPR^}. If a file with this extension is not found, -then the file name as specified in the @code{with} clause (no extension) will -be used. In the above example, if a file @code{project1.gpr} is found, then it -will be used; otherwise, if a file @code{^project1^PROJECT1^} exists -then it will be used; if neither file exists, this is an error. - -A warning is issued if the name of the project file does not match the -name of the project; this check is case insensitive. - -Any source file that is an immediate source of the imported project can be -used by the immediate sources of the importing project, transitively. Thus -if @code{A} imports @code{B}, and @code{B} imports @code{C}, the immediate -sources of @code{A} may depend on the immediate sources of @code{C}, even if -@code{A} does not import @code{C} explicitly. However, this is not recommended, -because if and when @code{B} ceases to import @code{C}, some sources in -@code{A} will no longer compile. - -A side effect of this capability is that normally cyclic dependencies are not -permitted: if @code{A} imports @code{B} (directly or indirectly) then @code{B} -is not allowed to import @code{A}. However, there are cases when cyclic -dependencies would be beneficial. For these cases, another form of import -between projects exists, the @code{limited with}: a project @code{A} that -imports a project @code{B} with a straight @code{with} may also be imported, -directly or indirectly, by @code{B} on the condition that imports from @code{B} -to @code{A} include at least one @code{limited with}. - -@smallexample @c 0projectfile -with "../b/b.gpr"; -with "../c/c.gpr"; -project A is -end A; - -limited with "../a/a.gpr"; -project B is -end B; - -with "../d/d.gpr"; -project C is -end C; - -limited with "../a/a.gpr"; -project D is -end D; -@end smallexample - -@noindent -In the above legal example, there are two project cycles: -@itemize @bullet -@item A-> B-> A -@item A -> C -> D -> A -@end itemize - -@noindent -In each of these cycle there is one @code{limited with}: import of @code{A} -from @code{B} and import of @code{A} from @code{D}. - -The difference between straight @code{with} and @code{limited with} is that -the name of a project imported with a @code{limited with} cannot be used in the -project that imports it. In particular, its packages cannot be renamed and -its variables cannot be referred to. - -An exception to the above rules for @code{limited with} is that for the main -project specified to @command{gnatmake} or to the @command{GNAT} driver a -@code{limited with} is equivalent to a straight @code{with}. For example, -in the example above, projects @code{B} and @code{D} could not be main -projects for @command{gnatmake} or to the @command{GNAT} driver, because they -each have a @code{limited with} that is the only one in a cycle of importing -projects. - -@c ********************* -@c * Project Extension * -@c ********************* - -@node Project Extension -@section Project Extension - -@noindent -During development of a large system, it is sometimes necessary to use -modified versions of some of the source files, without changing the original -sources. This can be achieved through the @emph{project extension} facility. - -@smallexample @c projectfile - project Modified_Utilities extends "/baseline/utilities.gpr" is @dots{} -@end smallexample - -@noindent -A project extension declaration introduces an extending project -(the @emph{child}) and a project being extended (the @emph{parent}). - -By default, a child project inherits all the sources of its parent. -However, inherited sources can be overridden: a unit in a parent is hidden -by a unit of the same name in the child. - -Inherited sources are considered to be sources (but not immediate sources) -of the child project; see @ref{Project File Syntax}. - -An inherited source file retains any switches specified in the parent project. - -For example if the project @code{Utilities} contains the spec and the -body of an Ada package @code{Util_IO}, then the project -@code{Modified_Utilities} can contain a new body for package @code{Util_IO}. -The original body of @code{Util_IO} will not be considered in program builds. -However, the package spec will still be found in the project -@code{Utilities}. - -A child project can have only one parent, except when it is qualified as -abstract. But it may import any number of other projects. - -A project is not allowed to import directly or indirectly at the same time a -child project and any of its ancestors. - -@c ******************************* -@c * Project Hierarchy Extension * -@c ******************************* - -@node Project Hierarchy Extension -@section Project Hierarchy Extension - -@noindent -When extending a large system spanning multiple projects, it is often -inconvenient to extend every project in the hierarchy that is impacted by a -small change introduced. In such cases, it is possible to create a virtual -extension of entire hierarchy using @code{extends all} relationship. - -When the project is extended using @code{extends all} inheritance, all projects -that are imported by it, both directly and indirectly, are considered virtually -extended. That is, the Project Manager creates "virtual projects" -that extend every project in the hierarchy; all these virtual projects have -no sources of their own and have as object directory the object directory of -the root of "extending all" project. - -It is possible to explicitly extend one or more projects in the hierarchy -in order to modify the sources. These extending projects must be imported by -the "extending all" project, which will replace the corresponding virtual -projects with the explicit ones. - -When building such a project hierarchy extension, the Project Manager will -ensure that both modified sources and sources in virtual extending projects -that depend on them, are recompiled. - -By means of example, consider the following hierarchy of projects. - -@enumerate -@item -project A, containing package P1 -@item -project B importing A and containing package P2 which depends on P1 -@item -project C importing B and containing package P3 which depends on P2 -@end enumerate - -@noindent -We want to modify packages P1 and P3. - -This project hierarchy will need to be extended as follows: - -@enumerate -@item -Create project A1 that extends A, placing modified P1 there: - -@smallexample @c 0projectfile -project A1 extends "(@dots{})/A" is -end A1; -@end smallexample - -@item -Create project C1 that "extends all" C and imports A1, placing modified -P3 there: - -@smallexample @c 0projectfile -with "(@dots{})/A1"; -project C1 extends all "(@dots{})/C" is -end C1; -@end smallexample -@end enumerate - -When you build project C1, your entire modified project space will be -recompiled, including the virtual project B1 that has been impacted by the -"extending all" inheritance of project C. - -Note that if a Library Project in the hierarchy is virtually extended, -the virtual project that extends the Library Project is not a Library Project. - -@c **************************************** -@c * External References in Project Files * -@c **************************************** - -@node External References in Project Files -@section External References in Project Files - -@noindent -A project file may contain references to external variables; such references -are called @emph{external references}. - -An external variable is either defined as part of the environment (an -environment variable in Unix, for example) or else specified on the command -line via the @option{^-X^/EXTERNAL_REFERENCE=^@emph{vbl}=@emph{value}} switch. -If both, then the command line value is used. - -The value of an external reference is obtained by means of the built-in -function @code{external}, which returns a string value. -This function has two forms: -@itemize @bullet -@item @code{external (external_variable_name)} -@item @code{external (external_variable_name, default_value)} -@end itemize - -@noindent -Each parameter must be a string literal. For example: - -@smallexample @c projectfile - external ("USER") - external ("OS", "GNU/Linux") -@end smallexample - -@noindent -In the form with one parameter, the function returns the value of -the external variable given as parameter. If this name is not present in the -environment, the function returns an empty string. - -In the form with two string parameters, the second argument is -the value returned when the variable given as the first argument is not -present in the environment. In the example above, if @code{"OS"} is not -the name of ^an environment variable^a logical name^ and is not passed on -the command line, then the returned value is @code{"GNU/Linux"}. - -An external reference may be part of a string expression or of a string -list expression, and can therefore appear in a variable declaration or -an attribute declaration. - -@smallexample @c projectfile -@group - type Mode_Type is ("Debug", "Release"); - Mode : Mode_Type := external ("MODE"); - case Mode is - when "Debug" => - @dots{} -@end group -@end smallexample - -@c ***************************** -@c * Packages in Project Files * -@c ***************************** - -@node Packages in Project Files -@section Packages in Project Files - -@noindent -A @emph{package} defines the settings for project-aware tools within a -project. -For each such tool one can declare a package; the names for these -packages are preset (@pxref{Packages}). -A package may contain variable declarations, attribute declarations, and case -constructions. - -@smallexample @c projectfile -@group - project Proj is - package Builder is -- used by gnatmake - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-v^-v^", - "^-g^-g^"); - end Builder; - end Proj; -@end group -@end smallexample - -@noindent -The syntax of package declarations mimics that of package in Ada. - -Most of the packages have an attribute -@code{^Default_Switches^Default_Switches^}. -This attribute is an associative array, and its value is a string list. -The index of the associative array is the name of a programming language (case -insensitive). This attribute indicates the ^switch^switch^ -or ^switches^switches^ to be used -with the corresponding tool. - -Some packages also have another attribute, @code{^Switches^Switches^}, -an associative array whose value is a string list. -The index is the name of a source file. -This attribute indicates the ^switch^switch^ -or ^switches^switches^ to be used by the corresponding -tool when dealing with this specific file. - -Further information on these ^switch^switch^-related attributes is found in -@ref{^Switches^Switches^ and Project Files}. - -A package may be declared as a @emph{renaming} of another package; e.g., from -the project file for an imported project. - -@smallexample @c projectfile -@group - with "/global/apex.gpr"; - project Example is - package Naming renames Apex.Naming; - @dots{} - end Example; -@end group -@end smallexample - -@noindent -Packages that are renamed in other project files often come from project files -that have no sources: they are just used as templates. Any modification in the -template will be reflected automatically in all the project files that rename -a package from the template. - -In addition to the tool-oriented packages, you can also declare a package -named @code{Naming} to establish specialized source file naming conventions -(@pxref{Naming Schemes}). - -@c ************************************ -@c * Variables from Imported Projects * -@c ************************************ - -@node Variables from Imported Projects -@section Variables from Imported Projects - -@noindent -An attribute or variable defined in an imported or parent project can -be used in expressions in the importing / extending project. -Such an attribute or variable is denoted by an expanded name whose prefix -is either the name of the project or the expanded name of a package within -a project. - -@smallexample @c projectfile -@group - with "imported"; - project Main extends "base" is - Var1 := Imported.Var; - Var2 := Base.Var & ".new"; -@end group - -@group - package Builder is - for ^Default_Switches^Default_Switches^ ("Ada") - use Imported.Builder'Ada_^Switches^Switches^ & - "^-gnatg^-gnatg^" & - "^-v^-v^"; - end Builder; -@end group - -@group - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use Base.Compiler'Ada_^Switches^Switches^; - end Compiler; - end Main; -@end group -@end smallexample - -@noindent -In this example: - -@itemize @bullet -@item -The value of @code{Var1} is a copy of the variable @code{Var} defined -in the project file @file{"imported.gpr"} -@item -the value of @code{Var2} is a copy of the value of variable @code{Var} -defined in the project file @file{base.gpr}, concatenated with @code{".new"} -@item -attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package -@code{Builder} is a string list that includes in its value a copy of the value -of @code{Ada_^Switches^Switches^} defined in the @code{Builder} package -in project file @file{imported.gpr} plus two new elements: -@option{"^-gnatg^-gnatg^"} -and @option{"^-v^-v^"}; -@item -attribute @code{^Default_Switches^Default_Switches^ ("Ada")} in package -@code{Compiler} is a copy of the variable @code{Ada_^Switches^Switches^} -defined in the @code{Compiler} package in project file @file{base.gpr}, -the project being extended. -@end itemize - -@c ****************** -@c * Naming Schemes * -@c ****************** - -@node Naming Schemes -@section Naming Schemes - -@noindent -Sometimes an Ada software system is ported from a foreign compilation -environment to GNAT, and the file names do not use the default GNAT -conventions. Instead of changing all the file names (which for a variety -of reasons might not be possible), you can define the relevant file -naming scheme in the @code{Naming} package in your project file. - -@noindent -Note that the use of pragmas described in -@ref{Alternative File Naming Schemes} by mean of a configuration -pragmas file is not supported when using project files. You must use -the features described in this paragraph. You can however use specify -other configuration pragmas (@pxref{Specifying Configuration Pragmas}). - -@ifclear vms -For example, the following -package models the Apex file naming rules: - -@smallexample @c projectfile -@group - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "."; - for Spec_Suffix ("Ada") use ".1.ada"; - for Body_Suffix ("Ada") use ".2.ada"; - end Naming; -@end group -@end smallexample -@end ifclear - -@ifset vms -For example, the following package models the HP Ada file naming rules: - -@smallexample @c projectfile -@group - package Naming is - for Casing use "lowercase"; - for Dot_Replacement use "__"; - for Spec_Suffix ("Ada") use "_.^ada^ada^"; - for Body_Suffix ("Ada") use ".^ada^ada^"; - end Naming; -@end group -@end smallexample - -@noindent -(Note that @code{Casing} is @code{"lowercase"} because GNAT gets the file -names in lower case) -@end ifset - -@noindent -You can define the following attributes in package @code{Naming}: - -@table @code - -@item @code{Casing} -This must be a string with one of the three values @code{"lowercase"}, -@code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive. - -@noindent -If @code{Casing} is not specified, then the default is @code{"lowercase"}. - -@item @code{Dot_Replacement} -This must be a string whose value satisfies the following conditions: - -@itemize @bullet -@item It must not be empty -@item It cannot start or end with an alphanumeric character -@item It cannot be a single underscore -@item It cannot start with an underscore followed by an alphanumeric -@item It cannot contain a dot @code{'.'} except if the entire string -is @code{"."} -@end itemize - -@noindent -If @code{Dot_Replacement} is not specified, then the default is @code{"-"}. - -@item @code{Spec_Suffix} -This is an associative array (indexed by the programming language name, case -insensitive) whose value is a string that must satisfy the following -conditions: - -@itemize @bullet -@item It must not be empty -@item It must include at least one dot -@end itemize -@noindent -If @code{Spec_Suffix ("Ada")} is not specified, then the default is -@code{"^.ads^.ADS^"}. - -@item @code{Body_Suffix} -This is an associative array (indexed by the programming language name, case -insensitive) whose value is a string that must satisfy the following -conditions: - -@itemize @bullet -@item It must not be empty -@item It must include at least one dot -@item It cannot be the same as @code{Spec_Suffix ("Ada")} -@end itemize -@noindent -If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the -same string, then a file name that ends with the longest of these two suffixes -will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec -if the longest suffix is @code{Spec_Suffix ("Ada")}. - -If @code{Body_Suffix ("Ada")} is not specified, then the default is -@code{"^.adb^.ADB^"}. - -@item @code{Separate_Suffix} -This must be a string whose value satisfies the same conditions as -@code{Body_Suffix}. The same "longest suffix" rules apply. - -@noindent -If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same -value as @code{Body_Suffix ("Ada")}. - -@item @code{Spec} -@noindent -You can use the associative array attribute @code{Spec} to define -the source file name for an individual Ada compilation unit's spec. The array -index must be a string literal that identifies the Ada unit (case insensitive). -The value of this attribute must be a string that identifies the file that -contains this unit's spec (case sensitive or insensitive depending on the -operating system). - -@smallexample @c projectfile - for Spec ("MyPack.MyChild") use "mypack.mychild.spec"; -@end smallexample - -@item @code{Body} - -You can use the associative array attribute @code{Body} to -define the source file name for an individual Ada compilation unit's body -(possibly a subunit). The array index must be a string literal that identifies -the Ada unit (case insensitive). The value of this attribute must be a string -that identifies the file that contains this unit's body or subunit (case -sensitive or insensitive depending on the operating system). - -@smallexample @c projectfile - for Body ("MyPack.MyChild") use "mypack.mychild.body"; -@end smallexample -@end table - -@c ******************** -@c * Library Projects * -@c ******************** - -@node Library Projects -@section Library Projects - -@noindent -@emph{Library projects} are projects whose object code is placed in a library. -(Note that this facility is not yet supported on all platforms) - -To create a library project, you need to define in its project file -two project-level attributes: @code{Library_Name} and @code{Library_Dir}. -Additionally, you may define other library-related attributes such as -@code{Library_Kind}, @code{Library_Version}, @code{Library_Interface}, -@code{Library_Auto_Init}, @code{Library_Options} and @code{Library_GCC}. - -The @code{Library_Name} attribute has a string value. There is no restriction -on the name of a library. It is the responsibility of the developer to -choose a name that will be accepted by the platform. It is recommended to -choose names that could be Ada identifiers; such names are almost guaranteed -to be acceptable on all platforms. - -The @code{Library_Dir} attribute has a string value that designates the path -(absolute or relative) of the directory where the library will reside. -It must designate an existing directory, and this directory must be writable, -different from the project's object directory and from any source directory -in the project tree. - -If both @code{Library_Name} and @code{Library_Dir} are specified and -are legal, then the project file defines a library project. The optional -library-related attributes are checked only for such project files. - -The @code{Library_Kind} attribute has a string value that must be one of the -following (case insensitive): @code{"static"}, @code{"dynamic"} or -@code{"relocatable"} (which is a synonym for @code{"dynamic"}). If this -attribute is not specified, the library is a static library, that is -an archive of object files that can be potentially linked into a -static executable. Otherwise, the library may be dynamic or -relocatable, that is a library that is loaded only at the start of execution. - -If you need to build both a static and a dynamic library, you should use two -different object directories, since in some cases some extra code needs to -be generated for the latter. For such cases, it is recommended to either use -two different project files, or a single one which uses external variables -to indicate what kind of library should be build. - -The @code{Library_ALI_Dir} attribute may be specified to indicate the -directory where the ALI files of the library will be copied. When it is -not specified, the ALI files are copied to the directory specified in -attribute @code{Library_Dir}. The directory specified by @code{Library_ALI_Dir} -must be writable and different from the project's object directory and from -any source directory in the project tree. - -The @code{Library_Version} attribute has a string value whose interpretation -is platform dependent. It has no effect on VMS and Windows. On Unix, it is -used only for dynamic/relocatable libraries as the internal name of the -library (the @code{"soname"}). If the library file name (built from the -@code{Library_Name}) is different from the @code{Library_Version}, then the -library file will be a symbolic link to the actual file whose name will be -@code{Library_Version}. - -Example (on Unix): - -@smallexample @c projectfile -@group -project Plib is - - Version := "1"; - - for Library_Dir use "lib_dir"; - for Library_Name use "dummy"; - for Library_Kind use "relocatable"; - for Library_Version use "libdummy.so." & Version; - -end Plib; -@end group -@end smallexample - -@noindent -Directory @file{lib_dir} will contain the internal library file whose name -will be @file{libdummy.so.1}, and @file{libdummy.so} will be a symbolic link to -@file{libdummy.so.1}. - -When @command{gnatmake} detects that a project file -is a library project file, it will check all immediate sources of the project -and rebuild the library if any of the sources have been recompiled. - -Standard project files can import library project files. In such cases, -the libraries will only be rebuilt if some of its sources are recompiled -because they are in the closure of some other source in an importing project. -Sources of the library project files that are not in such a closure will -not be checked, unless the full library is checked, because one of its sources -needs to be recompiled. - -For instance, assume the project file @code{A} imports the library project file -@code{L}. The immediate sources of A are @file{a1.adb}, @file{a2.ads} and -@file{a2.adb}. The immediate sources of L are @file{l1.ads}, @file{l1.adb}, -@file{l2.ads}, @file{l2.adb}. - -If @file{l1.adb} has been modified, then the library associated with @code{L} -will be rebuilt when compiling all the immediate sources of @code{A} only -if @file{a1.ads}, @file{a2.ads} or @file{a2.adb} includes a statement -@code{"with L1;"}. - -To be sure that all the sources in the library associated with @code{L} are -up to date, and that all the sources of project @code{A} are also up to date, -the following two commands needs to be used: - -@smallexample -gnatmake -Pl.gpr -gnatmake -Pa.gpr -@end smallexample - -When a library is built or rebuilt, an attempt is made first to delete all -files in the library directory. -All @file{ALI} files will also be copied from the object directory to the -library directory. To build executables, @command{gnatmake} will use the -library rather than the individual object files. - -@ifclear vms -It is also possible to create library project files for third-party libraries -that are precompiled and cannot be compiled locally thanks to the -@code{externally_built} attribute. (See @ref{Installing a library}). -@end ifclear - -@c ******************************* -@c * Stand-alone Library Projects * -@c ******************************* - -@node Stand-alone Library Projects -@section Stand-alone Library Projects - -@noindent -A Stand-alone Library is a library that contains the necessary code to -elaborate the Ada units that are included in the library. A Stand-alone -Library is suitable to be used in an executable when the main is not -in Ada. However, Stand-alone Libraries may also be used with an Ada main -subprogram. - -A Stand-alone Library Project is a Library Project where the library is -a Stand-alone Library. - -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. - -@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 - -Attribute @code{Library_Interface} has a nonempty 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 -(^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 (dummyinit and dummyfinal in the example -above). The object corresponding to this package is included in the library. - -A dynamic or relocatable Stand-alone Library is automatically initialized -if automatic initialization of Stand-alone Libraries is supported on the -platform and if attribute @code{Library_Auto_Init} is not specified or -is specified with the value "true". A static Stand-alone Library is never -automatically initialized. - -Single string attribute @code{Library_Auto_Init} may be specified with only -two possible values: "false" or "true" (case-insensitive). Specifying -"false" for attribute @code{Library_Auto_Init} will prevent automatic -initialization of dynamic or relocatable libraries. - -When a non-automatically initialized Stand-alone Library is used -in an executable, its initialization procedure must be called before -any service of the library is used. -When the main subprogram is in Ada, it may mean that the initialization -procedure has to be called during elaboration of another package. - -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. - -When a Stand-Alone Library is bound, the switches that are specified in -the attribute @code{Default_Switches ("Ada")} in package @code{Binder} are -used in the call to @command{gnatbind}. - -The string list attribute @code{Library_Options} may be used to specified -additional switches to the call to @command{gcc} to link the library. - -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, necessary to an Ada client of the library, will be -copied to the designated directory, called Interface Copy directory. -These sources includes 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 units 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. - -@c ************************************* -@c * Switches Related to Project Files * -@c ************************************* -@node Switches Related to Project Files -@section Switches Related to Project Files - -@noindent -The following switches are used by GNAT tools that support project files: - -@table @option - -@item ^-P^/PROJECT_FILE=^@var{project} -@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool) -Indicates the name of a project file. This project file will be parsed with -the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}}, -if any, and using the external references indicated -by @option{^-X^/EXTERNAL_REFERENCE^} switches, if any. -@ifclear vms -There may zero, one or more spaces between @option{-P} and @var{project}. -@end ifclear - -@noindent -There must be only one @option{^-P^/PROJECT_FILE^} switch on the command line. - -@noindent -Since the Project Manager parses the project file only after all the switches -on the command line are checked, the order of the switches -@option{^-P^/PROJECT_FILE^}, -@option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} -or @option{^-X^/EXTERNAL_REFERENCE^} is not significant. - -@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value} -@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool) -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. - -@ifclear vms -@noindent -If @var{name} or @var{value} includes a space, then @var{name=value} should be -put between quotes. -@smallexample - -XOS=NT - -X"user=John Doe" -@end smallexample -@end ifclear - -@noindent -Several @option{^-X^/EXTERNAL_REFERENCE^} switches can be used simultaneously. -If several @option{^-X^/EXTERNAL_REFERENCE^} switches specify the same -@var{name}, only the last one is used. - -@noindent -An external variable specified with a @option{^-X^/EXTERNAL_REFERENCE^} switch -takes precedence over the value of the same name in the environment. - -@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x} -@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool) -Indicates the verbosity of the parsing of GNAT project files. - -@ifclear vms -@option{-vP0} means Default; -@option{-vP1} means Medium; -@option{-vP2} means High. -@end ifclear - -@ifset vms -There are three possible options for this qualifier: DEFAULT, MEDIUM and -HIGH. -@end ifset - -@noindent -The default is ^Default^DEFAULT^: no output for syntactically correct -project files. -@noindent -If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present, -only the last one is used. - -@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir> -@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool) -Add directory <dir> at the beginning of the project search path, in order, -after the current working directory. - -@ifclear vms -@item -eL -@cindex @option{-eL} (any project-aware tool) -Follow all symbolic links when processing project files. -@end ifclear - -@item ^--subdirs^/SUBDIRS^=<subdir> -@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean) -This switch is recognized by gnatmake and gnatclean. It indicate that the real -directories (except the source directories) are the subdirectories <subdir> -of the directories specified in the project files. This applies in particular -to object directories, library directories and exec directories. If the -subdirectories do not exist, they are created automatically. - -@end table - -@c ********************************** -@c * Tools Supporting Project Files * -@c ********************************** - -@node Tools Supporting Project Files -@section Tools Supporting Project Files - -@menu -* gnatmake and Project Files:: -* The GNAT Driver and Project Files:: -@end menu - -@node gnatmake and Project Files -@subsection gnatmake and Project Files - -@noindent -This section covers several topics related to @command{gnatmake} and -project files: defining ^switches^switches^ for @command{gnatmake} -and for the tools that it invokes; specifying configuration pragmas; -the use of the @code{Main} attribute; building and rebuilding library project -files. - -@menu -* ^Switches^Switches^ and Project Files:: -* Specifying Configuration Pragmas:: -* Project Files and Main Subprograms:: -* Library Project Files:: -@end menu - -@node ^Switches^Switches^ and Project Files -@subsubsection ^Switches^Switches^ and Project Files - -@ifset vms -It is not currently possible to specify VMS style qualifiers in the project -files; only Unix style ^switches^switches^ may be specified. -@end ifset - -@noindent -For each of the packages @code{Builder}, @code{Compiler}, @code{Binder}, and -@code{Linker}, you can specify a @code{^Default_Switches^Default_Switches^} -attribute, a @code{^Switches^Switches^} attribute, or both; -as their names imply, these ^switch^switch^-related -attributes affect the ^switches^switches^ that are used for each of these GNAT -components when -@command{gnatmake} is invoked. As will be explained below, these -component-specific ^switches^switches^ precede -the ^switches^switches^ provided on the @command{gnatmake} command line. - -The @code{^Default_Switches^Default_Switches^} attribute is an associative -array indexed by language name (case insensitive) whose value is a string list. -For example: - -@smallexample @c projectfile -@group -package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnaty^-gnaty^", - "^-v^-v^"); -end Compiler; -@end group -@end smallexample - -@noindent -The @code{^Switches^Switches^} attribute is also an associative array, -indexed by a file name (which may or may not be case sensitive, depending -on the operating system) whose value is a string list. For example: - -@smallexample @c projectfile -@group -package Builder is - for ^Switches^Switches^ ("main1.adb") - use ("^-O2^-O2^"); - for ^Switches^Switches^ ("main2.adb") - use ("^-g^-g^"); -end Builder; -@end group -@end smallexample - -@noindent -For the @code{Builder} package, the file names must designate source files -for main subprograms. For the @code{Binder} and @code{Linker} packages, the -file names must designate @file{ALI} or source files for main subprograms. -In each case just the file name without an explicit extension is acceptable. - -For each tool used in a program build (@command{gnatmake}, the compiler, the -binder, and the linker), the corresponding package @dfn{contributes} a set of -^switches^switches^ for each file on which the tool is invoked, based on the -^switch^switch^-related attributes defined in the package. -In particular, the ^switches^switches^ -that each of these packages contributes for a given file @var{f} comprise: - -@itemize @bullet -@item -the value of attribute @code{^Switches^Switches^ (@var{f})}, -if it is specified in the package for the given file, -@item -otherwise, the value of @code{^Default_Switches^Default_Switches^ ("Ada")}, -if it is specified in the package. -@end itemize - -@noindent -If neither of these attributes is defined in the package, then the package does -not contribute any ^switches^switches^ for the given file. - -When @command{gnatmake} is invoked on a file, the ^switches^switches^ comprise -two sets, in the following order: those contributed for the file -by the @code{Builder} package; -and the switches passed on the command line. - -When @command{gnatmake} invokes a tool (compiler, binder, linker) on a file, -the ^switches^switches^ passed to the tool comprise three sets, -in the following order: - -@enumerate -@item -the applicable ^switches^switches^ contributed for the file -by the @code{Builder} package in the project file supplied on the command line; - -@item -those contributed for the file by the package (in the relevant project file -- -see below) corresponding to the tool; and - -@item -the applicable switches passed on the command line. -@end enumerate - -@noindent -The term @emph{applicable ^switches^switches^} reflects the fact that -@command{gnatmake} ^switches^switches^ may or may not be passed to individual -tools, depending on the individual ^switch^switch^. - -@command{gnatmake} may invoke the compiler on source files from different -projects. The Project Manager will use the appropriate project file to -determine the @code{Compiler} package for each source file being compiled. -Likewise for the @code{Binder} and @code{Linker} packages. - -As an example, consider the following package in a project file: - -@smallexample @c projectfile -@group -project Proj1 is - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-g^-g^"); - for ^Switches^Switches^ ("a.adb") - use ("^-O1^-O1^"); - for ^Switches^Switches^ ("b.adb") - use ("^-O2^-O2^", - "^-gnaty^-gnaty^"); - end Compiler; -end Proj1; -@end group -@end smallexample - -@noindent -If @command{gnatmake} is invoked with this project file, and it needs to -compile, say, the files @file{a.adb}, @file{b.adb}, and @file{c.adb}, then -@file{a.adb} will be compiled with the ^switch^switch^ -@option{^-O1^-O1^}, -@file{b.adb} with ^switches^switches^ -@option{^-O2^-O2^} -and @option{^-gnaty^-gnaty^}, -and @file{c.adb} with @option{^-g^-g^}. - -The following example illustrates the ordering of the ^switches^switches^ -contributed by different packages: - -@smallexample @c projectfile -@group -project Proj2 is - package Builder is - for ^Switches^Switches^ ("main.adb") - use ("^-g^-g^", - "^-O1^-)1^", - "^-f^-f^"); - end Builder; -@end group - -@group - package Compiler is - for ^Switches^Switches^ ("main.adb") - use ("^-O2^-O2^"); - end Compiler; -end Proj2; -@end group -@end smallexample - -@noindent -If you issue the command: - -@smallexample - gnatmake ^-Pproj2^/PROJECT_FILE=PROJ2^ -O0 main -@end smallexample - -@noindent -then the compiler will be invoked on @file{main.adb} with the following -sequence of ^switches^switches^ - -@smallexample - ^-g -O1 -O2 -O0^-g -O1 -O2 -O0^ -@end smallexample - -with the last @option{^-O^-O^} -^switch^switch^ having precedence over the earlier ones; -several other ^switches^switches^ -(such as @option{^-c^-c^}) are added implicitly. - -The ^switches^switches^ -@option{^-g^-g^} -and @option{^-O1^-O1^} are contributed by package -@code{Builder}, @option{^-O2^-O2^} is contributed -by the package @code{Compiler} -and @option{^-O0^-O0^} comes from the command line. - -The @option{^-g^-g^} -^switch^switch^ will also be passed in the invocation of -@command{Gnatlink.} - -A final example illustrates switch contributions from packages in different -project files: - -@smallexample @c projectfile -@group -project Proj3 is - for Source_Files use ("pack.ads", "pack.adb"); - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnata^-gnata^"); - end Compiler; -end Proj3; -@end group - -@group -with "Proj3"; -project Proj4 is - for Source_Files use ("foo_main.adb", "bar_main.adb"); - package Builder is - for ^Switches^Switches^ ("foo_main.adb") - use ("^-s^-s^", - "^-g^-g^"); - end Builder; -end Proj4; -@end group - -@group --- Ada source file: -with Pack; -procedure Foo_Main is - @dots{} -end Foo_Main; -@end group -@end smallexample - -If the command is -@smallexample -gnatmake ^-PProj4^/PROJECT_FILE=PROJ4^ foo_main.adb -cargs -gnato -@end smallexample - -@noindent -then the ^switches^switches^ passed to the compiler for @file{foo_main.adb} are -@option{^-g^-g^} (contributed by the package @code{Proj4.Builder}) and -@option{^-gnato^-gnato^} (passed on the command line). -When the imported package @code{Pack} is compiled, the ^switches^switches^ used -are @option{^-g^-g^} from @code{Proj4.Builder}, -@option{^-gnata^-gnata^} (contributed from package @code{Proj3.Compiler}, -and @option{^-gnato^-gnato^} from the command line. - -@noindent -When using @command{gnatmake} with project files, some ^switches^switches^ or -arguments may be expressed as relative paths. As the working directory where -compilation occurs may change, these relative paths are converted to absolute -paths. For the ^switches^switches^ found in a project file, the relative paths -are relative to the project file directory, for the switches on the command -line, they are relative to the directory where @command{gnatmake} is invoked. -The ^switches^switches^ for which this occurs are: -^-I^-I^, -^-A^-A^, -^-L^-L^, -^-aO^-aO^, -^-aL^-aL^, -^-aI^-aI^, as well as all arguments that are not switches (arguments to -^switch^switch^ -^-o^-o^, object files specified in package @code{Linker} or after --largs on the command line). The exception to this rule is the ^switch^switch^ -^--RTS=^--RTS=^ for which a relative path argument is never converted. - -@node Specifying Configuration Pragmas -@subsubsection Specifying Configuration Pragmas - -When using @command{gnatmake} with project files, if there exists a file -@file{gnat.adc} that contains configuration pragmas, this file will be -ignored. - -Configuration pragmas can be defined by means of the following attributes in -project files: @code{Global_Configuration_Pragmas} in package @code{Builder} -and @code{Local_Configuration_Pragmas} in package @code{Compiler}. - -Both these attributes are single string attributes. Their values is the path -name of a file containing configuration pragmas. If a path name is relative, -then it is relative to the project directory of the project file where the -attribute is defined. - -When compiling a source, the configuration pragmas used are, in order, -those listed in the file designated by attribute -@code{Global_Configuration_Pragmas} in package @code{Builder} of the main -project file, if it is specified, and those listed in the file designated by -attribute @code{Local_Configuration_Pragmas} in package @code{Compiler} of -the project file of the source, if it exists. - -@node Project Files and Main Subprograms -@subsubsection Project Files and Main Subprograms - -@noindent -When using a project file, you can invoke @command{gnatmake} -with one or several main subprograms, by specifying their source files on the -command line. - -@smallexample - gnatmake ^-P^/PROJECT_FILE=^prj main1 main2 main3 -@end smallexample - -@noindent -Each of these needs to be a source file of the same project, except -when the switch ^-u^/UNIQUE^ is used. - -@noindent -When ^-u^/UNIQUE^ is not used, all the mains need to be sources of the -same project, one of the project in the tree rooted at the project specified -on the command line. The package @code{Builder} of this common project, the -"main project" is the one that is considered by @command{gnatmake}. - -@noindent -When ^-u^/UNIQUE^ is used, the specified source files may be in projects -imported directly or indirectly by the project specified on the command line. -Note that if such a source file is not part of the project specified on the -command line, the ^switches^switches^ found in package @code{Builder} of the -project specified on the command line, if any, that are transmitted -to the compiler will still be used, not those found in the project file of -the source file. - -@noindent -When using a project file, you can also invoke @command{gnatmake} without -explicitly specifying any main, and the effect depends on whether you have -defined the @code{Main} attribute. This attribute has a string list value, -where each element in the list is the name of a source file (the file -extension is optional) that contains a unit that can be a main subprogram. - -If the @code{Main} attribute is defined in a project file as a non-empty -string list and the switch @option{^-u^/UNIQUE^} is not used on the command -line, then invoking @command{gnatmake} with this project file but without any -main on the command line is equivalent to invoking @command{gnatmake} with all -the file names in the @code{Main} attribute on the command line. - -Example: -@smallexample @c projectfile -@group - project Prj is - for Main use ("main1", "main2", "main3"); - end Prj; -@end group -@end smallexample - -@noindent -With this project file, @code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^"} -is equivalent to -@code{"gnatmake ^-Pprj^/PROJECT_FILE=PRJ^ main1 main2 main3"}. - -When the project attribute @code{Main} is not specified, or is specified -as an empty string list, or when the switch @option{-u} is used on the command -line, then invoking @command{gnatmake} with no main on the command line will -result in all immediate sources of the project file being checked, and -potentially recompiled. Depending on the presence of the switch @option{-u}, -sources from other project files on which the immediate sources of the main -project file depend are also checked and potentially recompiled. In other -words, the @option{-u} switch is applied to all of the immediate sources of the -main project file. - -When no main is specified on the command line and attribute @code{Main} exists -and includes several mains, or when several mains are specified on the -command line, the default ^switches^switches^ in package @code{Builder} will -be used for all mains, even if there are specific ^switches^switches^ -specified for one or several mains. - -But the ^switches^switches^ from package @code{Binder} or @code{Linker} will be -the specific ^switches^switches^ for each main, if they are specified. - -@node Library Project Files -@subsubsection Library Project Files - -@noindent -When @command{gnatmake} is invoked with a main project file that is a library -project file, it is not allowed to specify one or more mains on the command -line. - -@noindent -When a library project file is specified, switches ^-b^/ACTION=BIND^ and -^-l^/ACTION=LINK^ have special meanings. - -@itemize @bullet -@item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates -to @command{gnatmake} that @command{gnatbind} should be invoked for the -library. - -@item ^-l^/ACTION=LINK^ may be used for all library projects. It indicates -to @command{gnatmake} that the binder generated file should be compiled -(in the case of a stand-alone library) and that the library should be built. - -@end itemize - -@node The GNAT Driver and Project Files -@subsection The GNAT Driver and Project Files - -@noindent -A number of GNAT tools, other than @command{^gnatmake^gnatmake^} -can benefit from project files: -@command{^gnatbind^gnatbind^}, -@command{^gnatcheck^gnatcheck^}), -@command{^gnatclean^gnatclean^}), -@command{^gnatelim^gnatelim^}, -@command{^gnatfind^gnatfind^}, -@command{^gnatlink^gnatlink^}, -@command{^gnatls^gnatls^}, -@command{^gnatmetric^gnatmetric^}, -@command{^gnatpp^gnatpp^}, -@command{^gnatstub^gnatstub^}, -and @command{^gnatxref^gnatxref^}. However, none of these tools can be invoked -directly with a project file switch (@option{^-P^/PROJECT_FILE=^}). -They must be invoked through the @command{gnat} driver. - -The @command{gnat} driver is a wrapper that accepts a number of commands and -calls the corresponding tool. It was designed initially for VMS platforms (to -convert VMS qualifiers to Unix-style switches), but it is now available on all -GNAT platforms. - -On non-VMS platforms, the @command{gnat} driver accepts the following commands -(case insensitive): - -@itemize @bullet -@item -BIND to invoke @command{^gnatbind^gnatbind^} -@item -CHOP to invoke @command{^gnatchop^gnatchop^} -@item -CLEAN to invoke @command{^gnatclean^gnatclean^} -@item -COMP or COMPILE to invoke the compiler -@item -ELIM to invoke @command{^gnatelim^gnatelim^} -@item -FIND to invoke @command{^gnatfind^gnatfind^} -@item -KR or KRUNCH to invoke @command{^gnatkr^gnatkr^} -@item -LINK to invoke @command{^gnatlink^gnatlink^} -@item -LS or LIST to invoke @command{^gnatls^gnatls^} -@item -MAKE to invoke @command{^gnatmake^gnatmake^} -@item -NAME to invoke @command{^gnatname^gnatname^} -@item -PREP or PREPROCESS to invoke @command{^gnatprep^gnatprep^} -@item -PP or PRETTY to invoke @command{^gnatpp^gnatpp^} -@item -METRIC to invoke @command{^gnatmetric^gnatmetric^} -@item -STUB to invoke @command{^gnatstub^gnatstub^} -@item -XREF to invoke @command{^gnatxref^gnatxref^} -@end itemize - -@noindent -(note that the compiler is invoked using the command -@command{^gnatmake -f -u -c^gnatmake -f -u -c^}). - -@noindent -On non-VMS platforms, between @command{gnat} and the command, two -special switches may be used: - -@itemize @bullet -@item -@command{-v} to display the invocation of the tool. -@item -@command{-dn} to prevent the @command{gnat} driver from removing -the temporary files it has created. These temporary files are -configuration files and temporary file list files. -@end itemize - -@noindent -The command may be followed by switches and arguments for the invoked -tool. - -@smallexample - gnat bind -C main.ali - gnat ls -a main - gnat chop foo.txt -@end smallexample - -@noindent -Switches may also be put in text files, one switch per line, and the text -files may be specified with their path name preceded by '@@'. - -@smallexample - gnat bind @@args.txt main.ali -@end smallexample - -@noindent -In addition, for commands BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK, -METRIC, PP or PRETTY, STUB and XREF, the project file related switches -(@option{^-P^/PROJECT_FILE^}, -@option{^-X^/EXTERNAL_REFERENCE^} and -@option{^-vP^/MESSAGES_PROJECT_FILE=^x}) may be used in addition to -the switches of the invoking tool. - -@noindent -When GNAT PP or GNAT PRETTY is used with a project file, but with no source -specified on the command line, it invokes @command{^gnatpp^gnatpp^} with all -the immediate sources of the specified project file. - -@noindent -When GNAT METRIC is used with a project file, but with no source -specified on the command line, it invokes @command{^gnatmetric^gnatmetric^} -with all the immediate sources of the specified project file and with -@option{^-d^/DIRECTORY^} with the parameter pointing to the object directory -of the project. - -@noindent -In addition, when GNAT PP, GNAT PRETTY or GNAT METRIC is used with -a project file, no source is specified on the command line and -switch ^-U^/ALL_PROJECTS^ is specified on the command line, then -the underlying tool (^gnatpp^gnatpp^ or -^gnatmetric^gnatmetric^) is invoked for all sources of all projects, -not only for the immediate sources of the main project. -@ifclear vms -(-U stands for Universal or Union of the project files of the project tree) -@end ifclear - -@noindent -For each of the following commands, there is optionally a corresponding -package in the main project. - -@itemize @bullet -@item -package @code{Binder} for command BIND (invoking @code{^gnatbind^gnatbind^}) - -@item -package @code{Check} for command CHECK (invoking -@code{^gnatcheck^gnatcheck^}) - -@item -package @code{Compiler} for command COMP or COMPILE (invoking the compiler) - -@item -package @code{Cross_Reference} for command XREF (invoking -@code{^gnatxref^gnatxref^}) - -@item -package @code{Eliminate} for command ELIM (invoking -@code{^gnatelim^gnatelim^}) - -@item -package @code{Finder} for command FIND (invoking @code{^gnatfind^gnatfind^}) - -@item -package @code{Gnatls} for command LS or LIST (invoking @code{^gnatls^gnatls^}) - -@item -package @code{Gnatstub} for command STUB -(invoking @code{^gnatstub^gnatstub^}) - -@item -package @code{Linker} for command LINK (invoking @code{^gnatlink^gnatlink^}) - -@item -package @code{Metrics} for command METRIC -(invoking @code{^gnatmetric^gnatmetric^}) - -@item -package @code{Pretty_Printer} for command PP or PRETTY -(invoking @code{^gnatpp^gnatpp^}) - -@end itemize - -@noindent -Package @code{Gnatls} has a unique attribute @code{^Switches^Switches^}, -a simple variable with a string list value. It contains ^switches^switches^ -for the invocation of @code{^gnatls^gnatls^}. - -@smallexample @c projectfile -@group -project Proj1 is - package gnatls is - for ^Switches^Switches^ - use ("^-a^-a^", - "^-v^-v^"); - end gnatls; -end Proj1; -@end group -@end smallexample - -@noindent -All other packages have two attribute @code{^Switches^Switches^} and -@code{^Default_Switches^Default_Switches^}. - -@noindent -@code{^Switches^Switches^} is an associative array attribute, indexed by the -source file name, that has a string list value: the ^switches^switches^ to be -used when the tool corresponding to the package is invoked for the specific -source file. - -@noindent -@code{^Default_Switches^Default_Switches^} is an associative array attribute, -indexed by the programming language that has a string list value. -@code{^Default_Switches^Default_Switches^ ("Ada")} contains the -^switches^switches^ for the invocation of the tool corresponding -to the package, except if a specific @code{^Switches^Switches^} attribute -is specified for the source file. - -@smallexample @c projectfile -@group -project Proj is - - for Source_Dirs use ("./**"); - - package gnatls is - for ^Switches^Switches^ use - ("^-a^-a^", - "^-v^-v^"); - end gnatls; -@end group -@group - - package Compiler is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-gnatv^-gnatv^", - "^-gnatwa^-gnatwa^"); - end Binder; -@end group -@group - - package Binder is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-C^-C^", - "^-e^-e^"); - end Binder; -@end group -@group - - package Linker is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-C^-C^"); - for ^Switches^Switches^ ("main.adb") - use ("^-C^-C^", - "^-v^-v^", - "^-v^-v^"); - end Linker; -@end group -@group - - package Finder is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-a^-a^", - "^-f^-f^"); - end Finder; -@end group -@group - - package Cross_Reference is - for ^Default_Switches^Default_Switches^ ("Ada") - use ("^-a^-a^", - "^-f^-f^", - "^-d^-d^", - "^-u^-u^"); - end Cross_Reference; -end Proj; -@end group -@end smallexample - -@noindent -With the above project file, commands such as - -@smallexample - ^gnat comp -Pproj main^GNAT COMP /PROJECT_FILE=PROJ MAIN^ - ^gnat ls -Pproj main^GNAT LIST /PROJECT_FILE=PROJ MAIN^ - ^gnat xref -Pproj main^GNAT XREF /PROJECT_FILE=PROJ MAIN^ - ^gnat bind -Pproj main.ali^GNAT BIND /PROJECT_FILE=PROJ MAIN.ALI^ - ^gnat link -Pproj main.ali^GNAT LINK /PROJECT_FILE=PROJ MAIN.ALI^ -@end smallexample - -@noindent -will set up the environment properly and invoke the tool with the switches -found in the package corresponding to the tool: -@code{^Default_Switches^Default_Switches^ ("Ada")} for all tools, -except @code{^Switches^Switches^ ("main.adb")} -for @code{^gnatlink^gnatlink^}. -It is also possible to invoke some of the tools, -@code{^gnatcheck^gnatcheck^}), -@code{^gnatmetric^gnatmetric^}), -and @code{^gnatpp^gnatpp^}) -on a set of project units thanks to the combination of the switches -@option{-P}, @option{-U} and possibly the main unit when one is interested -in its closure. For instance, -@smallexample -gnat metric -Pproj -@end smallexample -will compute the metrics for all the immediate units of project -@code{proj}. -@smallexample -gnat metric -Pproj -U -@end smallexample -will compute the metrics for all the units of the closure of projects -rooted at @code{proj}. -@smallexample -gnat metric -Pproj -U main_unit -@end smallexample -will compute the metrics for the closure of units rooted at -@code{main_unit}. This last possibility relies implicitly -on @command{gnatbind}'s option @option{-R}. - -@c ********************** -@node An Extended Example -@section An Extended Example - -@noindent -Suppose that we have two programs, @var{prog1} and @var{prog2}, -whose sources are in corresponding directories. We would like -to build them with a single @command{gnatmake} command, and we want to place -their object files into @file{build} subdirectories of the source directories. -Furthermore, we want to have to have two separate subdirectories -in @file{build} -- @file{release} and @file{debug} -- which will contain -the object files compiled with different set of compilation flags. - -In other words, we have the following structure: - -@smallexample -@group - main - |- prog1 - | |- build - | | debug - | | release - |- prog2 - |- build - | debug - | release -@end group -@end smallexample - -@noindent -Here are the project files that we must place in a directory @file{main} -to maintain this structure: - -@enumerate - -@item We create a @code{Common} project with a package @code{Compiler} that -specifies the compilation ^switches^switches^: - -@smallexample -File "common.gpr": -@group -@b{project} Common @b{is} - - @b{for} Source_Dirs @b{use} (); -- No source files -@end group - -@group - @b{type} Build_Type @b{is} ("release", "debug"); - Build : Build_Type := External ("BUILD", "debug"); -@end group -@group - @b{package} Compiler @b{is} - @b{case} Build @b{is} - @b{when} "release" => - @b{for} ^Default_Switches^Default_Switches^ ("Ada") - @b{use} ("^-O2^-O2^"); - @b{when} "debug" => - @b{for} ^Default_Switches^Default_Switches^ ("Ada") - @b{use} ("^-g^-g^"); - @b{end case}; - @b{end} Compiler; - -@b{end} Common; -@end group -@end smallexample - -@item We create separate projects for the two programs: - -@smallexample -@group -File "prog1.gpr": - -@b{with} "common"; -@b{project} Prog1 @b{is} - - @b{for} Source_Dirs @b{use} ("prog1"); - @b{for} Object_Dir @b{use} "prog1/build/" & Common.Build; - - @b{package} Compiler @b{renames} Common.Compiler; - -@b{end} Prog1; -@end group -@end smallexample - -@smallexample -@group -File "prog2.gpr": - -@b{with} "common"; -@b{project} Prog2 @b{is} - - @b{for} Source_Dirs @b{use} ("prog2"); - @b{for} Object_Dir @b{use} "prog2/build/" & Common.Build; - - @b{package} Compiler @b{renames} Common.Compiler; - -@end group -@b{end} Prog2; -@end smallexample - -@item We create a wrapping project @code{Main}: - -@smallexample -@group -File "main.gpr": - -@b{with} "common"; -@b{with} "prog1"; -@b{with} "prog2"; -@b{project} Main @b{is} - - @b{package} Compiler @b{renames} Common.Compiler; - -@b{end} Main; -@end group -@end smallexample - -@item Finally we need to create a dummy procedure that @code{with}s (either -explicitly or implicitly) all the sources of our two programs. - -@end enumerate - -@noindent -Now we can build the programs using the command - -@smallexample - gnatmake ^-P^/PROJECT_FILE=^main dummy -@end smallexample - -@noindent -for the Debug mode, or - -@ifclear vms -@smallexample - gnatmake -Pmain -XBUILD=release -@end smallexample -@end ifclear - -@ifset vms -@smallexample - GNAT MAKE /PROJECT_FILE=main /EXTERNAL_REFERENCE=BUILD=release -@end smallexample -@end ifset - -@noindent -for the Release mode. - -@c ******************************** -@c * Project File Complete Syntax * -@c ******************************** - -@node Project File Complete Syntax -@section Project File Complete Syntax - -@smallexample -project ::= - context_clause project_declaration - -context_clause ::= - @{with_clause@} - -with_clause ::= - @b{with} path_name @{ , path_name @} ; - -path_name ::= - string_literal - -project_declaration ::= - simple_project_declaration | project_extension - -simple_project_declaration ::= - @b{project} <project_>simple_name @b{is} - @{declarative_item@} - @b{end} <project_>simple_name; - -project_extension ::= - @b{project} <project_>simple_name @b{extends} path_name @b{is} - @{declarative_item@} - @b{end} <project_>simple_name; - -declarative_item ::= - package_declaration | - typed_string_declaration | - other_declarative_item - -package_declaration ::= - package_spec | package_renaming - -package_spec ::= - @b{package} package_identifier @b{is} - @{simple_declarative_item@} - @b{end} package_identifier ; - -package_identifier ::= - @code{Naming} | @code{Builder} | @code{Compiler} | @code{Binder} | - @code{Linker} | @code{Finder} | @code{Cross_Reference} | - @code{^gnatls^gnatls^} | @code{IDE} | @code{Pretty_Printer} - -package_renaming ::== - @b{package} package_identifier @b{renames} - <project_>simple_name.package_identifier ; - -typed_string_declaration ::= - @b{type} <typed_string_>_simple_name @b{is} - ( string_literal @{, string_literal@} ); - -other_declarative_item ::= - attribute_declaration | - typed_variable_declaration | - variable_declaration | - case_construction - -attribute_declaration ::= - full_associative_array_declaration | - @b{for} attribute_designator @b{use} expression ; - -full_associative_array_declaration ::= - @b{for} <associative_array_attribute_>simple_name @b{use} - <project_>simple_name [ . <package_>simple_Name ] ' <attribute_>simple_name ; - -attribute_designator ::= - <simple_attribute_>simple_name | - <associative_array_attribute_>simple_name ( string_literal ) - -typed_variable_declaration ::= - <typed_variable_>simple_name : <typed_string_>name := string_expression ; - -variable_declaration ::= - <variable_>simple_name := expression; - -expression ::= - term @{& term@} - -term ::= - literal_string | - string_list | - <variable_>name | - external_value | - attribute_reference - -string_literal ::= - (same as Ada) - -string_list ::= - ( <string_>expression @{ , <string_>expression @} ) - -external_value ::= - @b{external} ( string_literal [, string_literal] ) - -attribute_reference ::= - attribute_prefix ' <simple_attribute_>simple_name [ ( literal_string ) ] - -attribute_prefix ::= - @b{project} | - <project_>simple_name | package_identifier | - <project_>simple_name . package_identifier - -case_construction ::= - @b{case} <typed_variable_>name @b{is} - @{case_item@} - @b{end case} ; - -case_item ::= - @b{when} discrete_choice_list => - @{case_construction | attribute_declaration@} - -discrete_choice_list ::= - string_literal @{| string_literal@} | - @b{others} - -name ::= - simple_name @{. simple_name@} - -simple_name ::= - identifier (same as Ada) - -@end smallexample - -@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 -* gnatxref Switches:: -* gnatfind Switches:: -* Project Files for gnatxref and gnatfind:: -* Regular Expressions in gnatfind and gnatxref:: -* Examples of gnatxref Usage:: -* Examples of gnatfind Usage:: -@end menu - -@node gnatxref Switches -@section @code{gnatxref} Switches - -@noindent -The command invocation for @code{gnatxref} is: -@smallexample -$ gnatxref @ovar{switches} @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 --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{Project Files}. -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 gnatfind Switches -@section @code{gnatfind} Switches - -@noindent -The command line for @code{gnatfind} is: - -@smallexample -$ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]} - @r{[}@var{file1} @var{file2} @dots{}] -@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 --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{Project Files}) 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 -$ gnatpp @ovar{switches} @var{filename} -@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 -@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-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{output_file}^ -@cindex @option{^-files^/FILES^} (@code{gnatpp}) -Take the argument source files from the specified file. This file should be an -ordinary textual file containing file names separated by spaces or -line breaks. You can use this switch more then once in the same call to -@command{gnatpp}. You also can combine this switch with 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 -$ gnatmetric @ovar{switches} @{@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{-cargs @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. -@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{^-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 textual 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_ON^ -Report all the line metrics - -@item ^--no-lines-all^/LINE_COUNT_METRICS=ALL_OFF^ -Do not report any of line metrics - -@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES_ON^ -Report the number of all lines - -@item ^--no-lines^/LINE_COUNT_METRICS=ALL_LINES_OFF^ -Do not report the number of all lines - -@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES_ON^ -Report the number of code lines - -@item ^--no-lines-code^/LINE_COUNT_METRICS=CODE_LINES_OFF^ -Do not report the number of code lines - -@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_ON^ -Report the number of comment lines - -@item ^--no-lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_OFF^ -Do not report the number of comment lines - -@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_ON^ -Report the number of code lines containing -end-of-line comments - -@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_OFF^ -Do not report the number of code lines containing -end-of-line comments - -@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_ON^ -Report the comment percentage in the program text - -@item ^--no-lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_OFF^ -Do not report the comment percentage in the program text - -@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_ON^ -Report the number of blank lines - -@item ^--no-lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_OFF^ -Do not report the number of blank lines - -@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_ON^ -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=AVERAGE_BODY_LINES_OFF^ -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_ON^ -Report all the syntax metrics - -@item ^--no-syntax-all^/ALL_OFF^ -Do not report any of syntax metrics - -@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS_ON^ -Report the total number of declarations - -@item ^--no-declarations^/SYNTAX_METRICS=DECLARATIONS_OFF^ -Do not report the total number of declarations - -@item ^--statements^/SYNTAX_METRICS=STATEMENTS_ON^ -Report the total number of statements - -@item ^--no-statements^/SYNTAX_METRICS=STATEMENTS_OFF^ -Do not report the total number of statements - -@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_ON^ -Report the number of public subprograms in a compilation unit - -@item ^--no-public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_OFF^ -Do not report the number of public subprograms in a compilation unit - -@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_ON^ -Report the number of all the subprograms in a compilation unit - -@item ^--no-all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_OFF^ -Do not report the number of all the subprograms in a compilation unit - -@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES_ON^ -Report the number of public types in a compilation unit - -@item ^--no-public-types^/SYNTAX_METRICS=PUBLIC_TYPES_OFF^ -Do not report the number of public types in a compilation unit - -@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES_ON^ -Report the number of all the types in a compilation unit - -@item ^--no-all-types^/SYNTAX_METRICS=ALL_TYPES_OFF^ -Do not report the number of all the types in a compilation unit - -@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_ON^ -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_ON^ -Report the maximal construct nesting level - -@item ^--no-construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_OFF^ -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_ON^ -Report all the complexity metrics - -@item ^--no-complexity-all^/COMPLEXITY_METRICS=ALL_OFF^ -Do not report any of complexity metrics - -@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_ON^ -Report the McCabe Cyclomatic Complexity - -@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_OFF^ -Do not report the McCabe Cyclomatic Complexity - -@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_ON^ -Report the Essential Complexity - -@item ^--no-complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_OFF^ -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=LOOP_NESTING_OFF^ -Do not report maximal loop nesting level - -@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_ON^ -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=AVERAGE_COMPLEXITY_OFF^ -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 - -@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 (if any) is considered -together with its spec when counting the dependencies. 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_ON^ -Report all the coupling metrics - -@item ^--no-coupling-all^/COUPLING_METRICS=ALL_OFF^ -Do not report any of metrics - -@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_ON^ -Report package efferent coupling - -@item ^--no-package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_OFF^ -Do not report package efferent coupling - -@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_ON^ -Report package afferent coupling - -@item ^--no-package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_OFF^ -Do not report package afferent coupling - -@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_ON^ -Report category efferent coupling - -@item ^--no-category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_OFF^ -Do not report category efferent coupling - -@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_ON^ -Report category afferent coupling - -@item ^--no-category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_OFF^ -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 then 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 ^-dv^/DEBUG_OUTPUT^ -@cindex @option{^-dv^/DEBUG_OUTPUT^} (@code{gnatmetric}) -Debug mode; -@command{gnatmetric} generates various messages useful to understand what -happens during the metrics computation - -@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 -$ gnatkr @var{name} @ovar{length} -@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 -$ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile} -@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} ::= <symbol> -@i{expression} ::= <symbol> = "<value>" -@i{expression} ::= <symbol> = <symbol> -@i{expression} ::= <symbol> '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} ::= <symbol>) the symbol must have -either the value true or false, that is to say the right-hand of the -symbol definition must be one of the (case-insensitive) literals -@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} ::= <symbol> @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. - -@ifset vms -@node The GNAT Run-Time Library Builder gnatlbr -@chapter The GNAT Run-Time Library Builder @code{gnatlbr} -@findex gnatlbr -@cindex Library builder - -@noindent -@code{gnatlbr} is a tool for rebuilding the GNAT run time with user -supplied configuration pragmas. - -@menu -* Running gnatlbr:: -* Switches for gnatlbr:: -* Examples of gnatlbr Usage:: -@end menu - -@node Running gnatlbr -@section Running @code{gnatlbr} - -@noindent -The @code{gnatlbr} command has the form - -@smallexample -$ GNAT LIBRARY /@r{[}CREATE@r{|}SET@r{|}DELETE@r{]}=directory @r{[}/CONFIG=file@r{]} -@end smallexample - -@node Switches for gnatlbr -@section Switches for @code{gnatlbr} - -@noindent -@code{gnatlbr} recognizes the following switches: - -@table @option -@c !sort! -@item /CREATE=directory -@cindex @code{/CREATE} (@code{gnatlbr}) -Create the new run-time library in the specified directory. - -@item /SET=directory -@cindex @code{/SET} (@code{gnatlbr}) -Make the library in the specified directory the current run-time library. - -@item /DELETE=directory -@cindex @code{/DELETE} (@code{gnatlbr}) -Delete the run-time library in the specified directory. - -@item /CONFIG=file -@cindex @code{/CONFIG} (@code{gnatlbr}) -With /CREATE: Use the configuration pragmas in the specified file when -building the library. - -With /SET: Use the configuration pragmas in the specified file when -compiling. - -@end table - -@node Examples of gnatlbr Usage -@section Example of @code{gnatlbr} Usage - -@smallexample -Contents of VAXFLOAT.ADC: -pragma Float_Representation (VAX_Float); - -$ GNAT LIBRARY /CREATE=[.VAXFLOAT] /CONFIG=VAXFLOAT.ADC - -GNAT LIBRARY rebuilds the run-time library in directory [.VAXFLOAT] - -@end smallexample -@end ifset - -@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: - <Current_Directory> - ../ - /home/comar/local/adainclude/ - -Object Search Path: - <Current_Directory> - ../ - /home/comar/local/lib/gcc-lib/x86-linux/3.4.3/adalib/ - -Project Search Path: - <Current_Directory> - /home/comar/local/lib/gnat/ - -./demo1.o - Unit => - Name => demo1 - Kind => subprogram body - Flags => No_Elab_Code - Source => demo1.adb modified -@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 ^-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. Except in the case of -@emph{stand-alone libraries}, where 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} - -@noindent -If you use project files, library installation is part of the library build -process. Thus no further action is needed in order to make use of the -libraries that are built as part of the general application build. A usable -version of the library is installed in the directory specified by the -@code{Library_Dir} attribute of the library project file. - -You may want to install a library in a context different from where the library -is built. This situation arises with third party suppliers, who may want -to distribute a library in binary form where the user is not expected to be -able to recompile the library. The simplest option in this case is to provide -a project file slightly different from the one used to build the library, by -using the @code{externally_built} attribute. For instance, the project -file used to build the library in the previous section can be changed into the -following one when the library is installed: - -@smallexample @c projectfile -project My_Lib is - for Source_Dirs use ("src1", "src2"); - for Library_Name use "mylib"; - for Library_Dir use "lib"; - for Library_Kind use "dynamic"; - for Externally_Built use "true"; -end My_lib; -@end smallexample - -@noindent -This project file assumes that the directories @file{src1}, -@file{src2}, and @file{lib} exist in -the directory containing the project file. The @code{externally_built} -attribute makes it clear to the GNAT builder that it should not attempt to -recompile any of the units from this library. It allows the library provider to -restrict the source set to the minimum necessary for clients to make use of the -library as described in the first section of this chapter. It is the -responsibility of the library provider to install the necessary sources, ALI -files and libraries in the directories mentioned in the project file. For -convenience, the user's library project file should be installed in a location -that will be searched automatically by the GNAT -builder. These are the directories referenced in the @env{ADA_PROJECT_PATH} -environment variable (@pxref{Importing Projects}), and also the default GNAT -library location that can be queried with @command{gnatls -v} and is usually of -the form $gnat_install_root/lib/gnat. - -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 Interface 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 Interface; -@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 provides three type 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 - $ gnatmem @ovar{switches} 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 <system__secondary_stack___elabb> - b_test_gm.c:33 adainit - -Allocation Root # 3 -------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 3.91 Kilobytes - High Water Mark : 3.91 Kilobytes - Backtrace : - test_gm.adb:11 test_gm.my_alloc - test_gm.adb:21 test_gm - b_test_gm.c:52 main - -Allocation Root # 4 -------------------- - Number of non freed allocations : 1 - Final Water Mark (non freed mem) : 12 Bytes - High Water Mark : 12 Bytes - Backtrace : - s-secsta.adb:181 system.secondary_stack.ss_init - s-secsta.adb:283 <system__secondary_stack___elabb> - b_test_gm.c:33 adainit -@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 | Actual Use [min - max] - -@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 Actual Use -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 real amount of stack used is between the min -and max values. - -@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 as described below. - -A number of rules are predefined in @command{gnatcheck} and are described -later in this chapter. -You can also add new rules, by modifying the @command{gnatcheck} code and -rebuilding the tool. In order to add a simple rule making some local checks, -a small amount of straightforward ASIS-based programming is usually needed. - -Project support for @command{gnatcheck} is provided by the GNAT -driver (see @ref{The GNAT Driver and Project Files}). - -Invoking @command{gnatcheck} on the command line has the form: - -@smallexample -$ gnatcheck @ovar{switches} @{@var{filename}@} - @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]} - @r{[}-cargs @var{gcc_switches}@r{]} @r{[}-rules @var{rule_options}@r{]} -@end smallexample - -@noindent -where -@itemize @bullet -@item -@var{switches} specify the general tool options - -@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. - -@item -Each @var{arg_list_filename} is the name (including the extension) of a text -file containing the names of the source files to process, separated by spaces -or line breaks. - -@item -@var{gcc_switches} is a list of switches for -@command{gcc}. They will be passed on to all compiler invocations made by -@command{gnatcheck} 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. - -@item -@var{rule_options} is a list of options for controlling a set of -rules to be checked by @command{gnatcheck} (@pxref{gnatcheck Rule Options}). -@end itemize - -@noindent -Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be supplied. - -@menu -* Format of the Report File:: -* General gnatcheck Switches:: -* gnatcheck Rule Options:: -* Adding the Results of Compiler Checks to gnatcheck Output:: -* Project-Wide Checks:: -* Predefined Rules:: -@end menu - -@node Format of the Report File -@section Format of the Report File -@cindex Report file (for @code{gnatcheck}) - -@noindent -The @command{gnatcheck} tool outputs on @file{stdout} all messages concerning -rule violations. -It also creates, in the current -directory, a text file named @file{^gnatcheck.out^GNATCHECK.OUT^} that -contains the complete report of the last gnatcheck run. This report contains: -@itemize @bullet -@item a list of the Ada source files being checked, -@item a list of enabled and disabled rules, -@item a list of the diagnostic messages, ordered in three different ways -and collected in three separate -sections. Section 1 contains the raw list of diagnostic messages. It -corresponds to the output going to @file{stdout}. Section 2 contains -messages ordered by rules. -Section 3 contains messages ordered by source files. -@end itemize - -@node General gnatcheck Switches -@section General @command{gnatcheck} Switches - -@noindent -The following switches control the general @command{gnatcheck} behavior - -@table @option -@c !sort! -@cindex @option{^-a^/ALL^} (@command{gnatcheck}) -@item ^-a^/ALL^ -Process all units including those with read-only ALI files such as -those from GNAT Run-Time library. - -@ifclear vms -@ignore -@cindex @option{-d} (@command{gnatcheck}) -@item -d -Debug mode -@end ignore - -@cindex @option{-dd} (@command{gnatcheck}) -@item -dd -Progress indicator mode (for use in GPS) -@end ifclear - -@cindex @option{^-h^/HELP^} (@command{gnatcheck}) -@item ^-h^/HELP^ -List the predefined and user-defined rules. For more details see -@ref{Predefined Rules}. - -@cindex @option{^-l^/LOCS^} (@command{gnatcheck}) -@item ^-l^/LOCS^ -Use full source locations references in the report file. For a construct from -a generic instantiation a full source location is a chain from the location -of this construct in the generic unit to the place where this unit is -instantiated. - -@cindex @option{^-m^/DIAGNOSIS_LIMIT^} (@command{gnatcheck}) -@item ^-m@i{nnn}^/DIAGNOSIS_LIMIT=@i{nnn}^ -Maximum number of diagnoses to be sent to Stdout, @i{nnn} from o@dots{}1000, -the default value is 500. Zero means that there is no limitation on -the number of diagnostic messages to be printed into Stdout. - -@cindex @option{^-q^/QUIET^} (@command{gnatcheck}) -@item ^-q^/QUIET^ -Quiet mode. All the diagnoses about rule violations are placed in the -@command{gnatcheck} report file only, without duplicating in @file{stdout}. - -@cindex @option{^-s^/SHORT^} (@command{gnatcheck}) -@item ^-s^/SHORT^ -Short format of the report file (no version information, no list of applied -rules, no list of checked sources is included) - -@cindex @option{^-s1^/COMPILER_STYLE^} (@command{gnatcheck}) -@item ^-s1^/COMPILER_STYLE^ -Include the compiler-style section in the report file - -@cindex @option{^-s2^/BY_RULES^} (@command{gnatcheck}) -@item ^-s2^/BY_RULES^ -Include the section containing diagnoses ordered by rules in the report file - -@cindex @option{^-s3^/BY_FILES_BY_RULES^} (@command{gnatcheck}) -@item ^-s3^/BY_FILES_BY_RULES^ -Include the section containing diagnoses ordered by files and then by rules -in the report file - -@cindex @option{^-v^/VERBOSE^} (@command{gnatcheck}) -@item ^-v^/VERBOSE^ -Verbose mode; @command{gnatcheck} generates version information and then -a trace of sources being processed. - -@end table - -@noindent -Note that if any of the options @option{^-s1^/COMPILER_STYLE^}, -@option{^-s2^/BY_RULES^} or -@option{^-s3^/BY_FILES_BY_RULES^} is specified, -then the @command{gnatcheck} report file will only contain sections -explicitly denoted by these options. - -@node gnatcheck Rule Options -@section @command{gnatcheck} Rule Options - -@noindent -The following options control the processing performed by -@command{gnatcheck}. - -@table @option -@cindex @option{+ALL} (@command{gnatcheck}) -@item +ALL -Turn all the rule checks ON. - -@cindex @option{-ALL} (@command{gnatcheck}) -@item -ALL -Turn all the rule checks OFF. - -@cindex @option{+R} (@command{gnatcheck}) -@item +R@var{rule_id}@r{[}:@var{param}@r{]} -Turn on the check for a specified rule with the specified parameter, if any. -@var{rule_id} must be the identifier of one of the currently implemented rules -(use @option{^-h^/HELP^} for the list of implemented rules). Rule identifiers -are not case-sensitive. The @var{param} item must -be a string representing a valid parameter(s) for the specified rule. -If it contains any space characters then this string must be enclosed in -quotation marks. - -@cindex @option{-R} (@command{gnatcheck}) -@item -R@var{rule_id}@r{[}:@var{param}@r{]} -Turn off the check for a specified rule with the specified parameter, if any. - -@cindex @option{-from} (@command{gnatcheck}) -@item -from=@var{rule_option_filename} -Read the rule options from the text file @var{rule_option_filename}, referred as -``rule file'' below. - -@end table - -@noindent -The default behavior is that all the rule checks are disabled. - -A rule file is a text file containing a set of rule options. -@cindex Rule file (for @code{gnatcheck}) -The file may contain empty lines and Ada-style comments (comment -lines and end-of-line comments). The rule file has free format; that is, -you do not have to start a new rule option on a new line. - -A rule file may contain other @option{-from=@var{rule_option_filename}} -options, each such option being replaced with the content of the -corresponding rule file during the rule files processing. In case a -cycle is detected (that is, @file{@var{rule_file_1}} reads rule options -from @file{@var{rule_file_2}}, and @file{@var{rule_file_2}} reads -(directly or indirectly) rule options from @file{@var{rule_file_1}}), -the processing of rule files is interrupted and a part of their content -is ignored. - - -@node Adding the Results of Compiler Checks to gnatcheck Output -@section Adding the Results of Compiler Checks to @command{gnatcheck} Output - -@noindent -The @command{gnatcheck} tool can include in the generated diagnostic messages -and in -the report file the results of the checks performed by the compiler. Though -disabled by default, this effect may be obtained by using @option{+R} with -the following rule identifiers and parameters: - -@table @option -@item Restrictions -To record restrictions violations (that are performed by the compiler if the -pragma @code{Restrictions} or @code{Restriction_Warnings} are given), -use the rule named -@code{Restrictions} with the same parameters as pragma -@code{Restrictions} or @code{Restriction_Warnings}. - -@item Style_Checks -To record compiler style checks(@pxref{Style Checking}), use the rule named -@code{Style_Checks}. A parameter of this rule can be either @code{All_Checks}, -which enables all the standard style checks that corresponds to @option{-gnatyy} -GNAT style check option, or a string that has exactly the same -structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma -@code{Style_Checks} (for further information about this pragma, -@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}). - -@item Warnings -To record compiler warnings (@pxref{Warning Message Control}), use the rule -named @code{Warnings} with a parameter that is a valid -@i{static_string_expression} argument of GNAT pragma @code{Warnings} -(for further information about this pragma, @pxref{Pragma Warnings,,, -gnat_rm, GNAT Reference Manual}). Note, that in case of gnatcheck -'s' parameter, that corresponds to the GNAT @option{-gnatws} option, disables -all the specific warnings, but not suppresses the warning mode, -and 'e' parameter, corresponding to @option{-gnatwe} that means -"treat warnings as errors", does not have any effect. - -@end table - -To disable a specific restriction check, use @code{-RStyle_Checks} gnatcheck -option with the corresponding restriction name as a parameter. @code{-R} is -not available for @code{Style_Checks} and @code{Warnings} options, to disable -warnings and style checks, use the corresponding warning and style options. - -@node Project-Wide Checks -@section Project-Wide Checks -@cindex Project-wide checks (for @command{gnatcheck}) - -@noindent -In order to perform checks on all units of a given project, you can use -the GNAT driver along with the @option{-P} option: -@smallexample - gnat check -Pproj -rules -from=my_rules -@end smallexample - -@noindent -If the project @code{proj} depends upon other projects, you can perform -checks on the project closure using the @option{-U} option: -@smallexample - gnat check -Pproj -U -rules -from=my_rules -@end smallexample - -@noindent -Finally, if not all the units are relevant to a particular main -program in the project closure, you can perform checks 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 check -Pproj -U main -rules -from=my_rules -@end smallexample - - -@node Predefined Rules -@section Predefined Rules -@cindex Predefined rules (for @command{gnatcheck}) - -@ignore -@c (Jan 2007) Since the global rules are still under development and are not -@c documented, there is no point in explaining the difference between -@c global and local rules -@noindent -A rule in @command{gnatcheck} is either local or global. -A @emph{local rule} is a rule that applies to a well-defined section -of a program and that can be checked by analyzing only this section. -A @emph{global rule} requires analysis of some global properties of the -whole program (mostly related to the program call graph). -As of @value{NOW}, the implementation of global rules should be -considered to be at a preliminary stage. You can use the -@option{+GLOBAL} option to enable all the global rules, and the -@option{-GLOBAL} rule option to disable all the global rules. - -All the global rules in the list below are -so indicated by marking them ``GLOBAL''. -This +GLOBAL and -GLOBAL options are not -included in the list of gnatcheck options above, because at the moment they -are considered as a temporary debug options. - -@command{gnatcheck} performs rule checks for generic -instances only for global rules. This limitation may be relaxed in a later -release. -@end ignore - -@noindent -The following subsections document the rules implemented in -@command{gnatcheck}. -The subsection title is the same as the rule identifier, which may be -used as a parameter of the @option{+R} or @option{-R} options. - - -@menu -* Abstract_Type_Declarations:: -* Anonymous_Arrays:: -* Anonymous_Subtypes:: -* Blocks:: -* Boolean_Relational_Operators:: -@ignore -* Ceiling_Violations:: -@end ignore -* Controlled_Type_Declarations:: -* Declarations_In_Blocks:: -* Default_Parameters:: -* Discriminated_Records:: -* Enumeration_Ranges_In_CASE_Statements:: -* Exceptions_As_Control_Flow:: -* EXIT_Statements_With_No_Loop_Name:: -* Expanded_Loop_Exit_Names:: -* Explicit_Full_Discrete_Ranges:: -* Float_Equality_Checks:: -* Forbidden_Pragmas:: -* Function_Style_Procedures:: -* Generics_In_Subprograms:: -* GOTO_Statements:: -* Implicit_IN_Mode_Parameters:: -* Implicit_SMALL_For_Fixed_Point_Types:: -* Improperly_Located_Instantiations:: -* Improper_Returns:: -* Library_Level_Subprograms:: -* Local_Packages:: -@ignore -* Improperly_Called_Protected_Entries:: -@end ignore -* Metrics:: -* Misnamed_Identifiers:: -* Multiple_Entries_In_Protected_Definitions:: -* Name_Clashes:: -* Non_Qualified_Aggregates:: -* Non_Short_Circuit_Operators:: -* Non_SPARK_Attributes:: -* Non_Tagged_Derived_Types:: -* Non_Visible_Exceptions:: -* Numeric_Literals:: -* OTHERS_In_Aggregates:: -* OTHERS_In_CASE_Statements:: -* OTHERS_In_Exception_Handlers:: -* Outer_Loop_Exits:: -* Overloaded_Operators:: -* Overly_Nested_Control_Structures:: -* Parameters_Out_Of_Order:: -* Positional_Actuals_For_Defaulted_Generic_Parameters:: -* Positional_Actuals_For_Defaulted_Parameters:: -* Positional_Components:: -* Positional_Generic_Parameters:: -* Positional_Parameters:: -* Predefined_Numeric_Types:: -* Raising_External_Exceptions:: -* Raising_Predefined_Exceptions:: -* Separate_Numeric_Error_Handlers:: -@ignore -* Recursion:: -* Side_Effect_Functions:: -@end ignore -* Slices:: -* Unassigned_OUT_Parameters:: -* Uncommented_BEGIN_In_Package_Bodies:: -* Unconstrained_Array_Returns:: -* Universal_Ranges:: -* Unnamed_Blocks_And_Loops:: -@ignore -* Unused_Subprograms:: -@end ignore -* USE_PACKAGE_Clauses:: -* Volatile_Objects_Without_Address_Clauses:: -@end menu - - -@node Abstract_Type_Declarations -@subsection @code{Abstract_Type_Declarations} -@cindex @code{Abstract_Type_Declarations} rule (for @command{gnatcheck}) - -@noindent -Flag all declarations of abstract types. For an abstract private -type, both the private and full type declarations are flagged. - -This rule has no parameters. - - -@node Anonymous_Arrays -@subsection @code{Anonymous_Arrays} -@cindex @code{Anonymous_Arrays} rule (for @command{gnatcheck}) - -@noindent -Flag all anonymous array type definitions (by Ada semantics these can only -occur in object declarations). - -This rule has no parameters. - -@node Anonymous_Subtypes -@subsection @code{Anonymous_Subtypes} -@cindex @code{Anonymous_Subtypes} rule (for @command{gnatcheck}) - -@noindent -Flag all uses of anonymous subtypes. A use of an anonymous subtype is -any instance of a subtype indication with a constraint, other than one -that occurs immediately within a subtype declaration. Any use of a range -other than as a constraint used immediately within a subtype declaration -is considered as an anonymous subtype. - -An effect of this rule is that @code{for} loops such as the following are -flagged (since @code{1..N} is formally a ``range''): - -@smallexample @c ada -for I in 1 .. N loop - @dots{} -end loop; -@end smallexample - -@noindent -Declaring an explicit subtype solves the problem: - -@smallexample @c ada -subtype S is Integer range 1..N; -@dots{} -for I in S loop - @dots{} -end loop; -@end smallexample - -@noindent -This rule has no parameters. - -@node Blocks -@subsection @code{Blocks} -@cindex @code{Blocks} rule (for @command{gnatcheck}) - -@noindent -Flag each block statement. - -This rule has no parameters. - -@node Boolean_Relational_Operators -@subsection @code{Boolean_Relational_Operators} -@cindex @code{Boolean_Relational_Operators} rule (for @command{gnatcheck}) - -@noindent -Flag each call to a predefined relational operator (``<'', ``>'', ``<='', -``>='', ``='' and ``/='') for the predefined Boolean type. -(This rule is useful in enforcing the SPARK language restrictions.) - -Calls to predefined relational operators of any type derived from -@code{Standard.Boolean} are not detected. Calls to user-defined functions -with these designators, and uses of operators that are renamings -of the predefined relational operators for @code{Standard.Boolean}, -are likewise not detected. - -This rule has no parameters. - -@ignore -@node Ceiling_Violations -@subsection @code{Ceiling_Violations} (under construction, GLOBAL) -@cindex @code{Ceiling_Violations} rule (for @command{gnatcheck}) - -@noindent -Flag invocations of a protected operation by a task whose priority exceeds -the protected object's ceiling. - -As of @value{NOW}, this rule has the following limitations: - -@itemize @bullet - -@item - We consider only pragmas Priority and Interrupt_Priority as means to define - a task/protected operation priority. We do not consider the effect of using - Ada.Dynamic_Priorities.Set_Priority procedure; - -@item - We consider only base task priorities, and no priority inheritance. That is, - we do not make a difference between calls issued during task activation and - execution of the sequence of statements from task body; - -@item - Any situation when the priority of protected operation caller is set by a - dynamic expression (that is, the corresponding Priority or - Interrupt_Priority pragma has a non-static expression as an argument) we - treat as a priority inconsistency (and, therefore, detect this situation). -@end itemize - -@noindent -At the moment the notion of the main subprogram is not implemented in -gnatcheck, so any pragma Priority in a library level subprogram body (in case -if this subprogram can be a main subprogram of a partition) changes the -priority of an environment task. So if we have more then one such pragma in -the set of processed sources, the pragma that is processed last, defines the -priority of an environment task. - -This rule has no parameters. -@end ignore - -@node Controlled_Type_Declarations -@subsection @code{Controlled_Type_Declarations} -@cindex @code{Controlled_Type_Declarations} rule (for @command{gnatcheck}) - -@noindent -Flag all declarations of controlled types. A declaration of a private type -is flagged if its full declaration declares a controlled type. A declaration -of a derived type is flagged if its ancestor type is controlled. Subtype -declarations are not checked. A declaration of a type that itself is not a -descendant of a type declared in @code{Ada.Finalization} but has a controlled -component is not checked. - -This rule has no parameters. - - - -@node Declarations_In_Blocks -@subsection @code{Declarations_In_Blocks} -@cindex @code{Declarations_In_Blocks} rule (for @command{gnatcheck}) - -@noindent -Flag all block statements containing local declarations. A @code{declare} -block with an empty @i{declarative_part} or with a @i{declarative part} -containing only pragmas and/or @code{use} clauses is not flagged. - -This rule has no parameters. - - -@node Default_Parameters -@subsection @code{Default_Parameters} -@cindex @code{Default_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag all default expressions for subprogram parameters. Parameter -declarations of formal and generic subprograms are also checked. - -This rule has no parameters. - - -@node Discriminated_Records -@subsection @code{Discriminated_Records} -@cindex @code{Discriminated_Records} rule (for @command{gnatcheck}) - -@noindent -Flag all declarations of record types with discriminants. Only the -declarations of record and record extension types are checked. Incomplete, -formal, private, derived and private extension type declarations are not -checked. Task and protected type declarations also are not checked. - -This rule has no parameters. - - -@node Enumeration_Ranges_In_CASE_Statements -@subsection @code{Enumeration_Ranges_In_CASE_Statements} -@cindex @code{Enumeration_Ranges_In_CASE_Statements} (for @command{gnatcheck}) - -@noindent -Flag each use of a range of enumeration literals as a choice in a -@code{case} statement. -All forms for specifying a range (explicit ranges -such as @code{A .. B}, subtype marks and @code{'Range} attributes) are flagged. -An enumeration range is -flagged even if contains exactly one enumeration value or no values at all. A -type derived from an enumeration type is considered as an enumeration type. - -This rule helps prevent maintenance problems arising from adding an -enumeration value to a type and having it implicitly handled by an existing -@code{case} statement with an enumeration range that includes the new literal. - -This rule has no parameters. - - -@node Exceptions_As_Control_Flow -@subsection @code{Exceptions_As_Control_Flow} -@cindex @code{Exceptions_As_Control_Flow} (for @command{gnatcheck}) - -@noindent -Flag each place where an exception is explicitly raised and handled in the -same subprogram body. A @code{raise} statement in an exception handler, -package body, task body or entry body is not flagged. - -The rule has no parameters. - -@node EXIT_Statements_With_No_Loop_Name -@subsection @code{EXIT_Statements_With_No_Loop_Name} -@cindex @code{EXIT_Statements_With_No_Loop_Name} (for @command{gnatcheck}) - -@noindent -Flag each @code{exit} statement that does not specify the name of the loop -being exited. - -The rule has no parameters. - - -@node Expanded_Loop_Exit_Names -@subsection @code{Expanded_Loop_Exit_Names} -@cindex @code{Expanded_Loop_Exit_Names} rule (for @command{gnatcheck}) - -@noindent -Flag all expanded loop names in @code{exit} statements. - -This rule has no parameters. - -@node Explicit_Full_Discrete_Ranges -@subsection @code{Explicit_Full_Discrete_Ranges} -@cindex @code{Explicit_Full_Discrete_Ranges} rule (for @command{gnatcheck}) - -@noindent -Flag each discrete range that has the form @code{A'First .. A'Last}. - -This rule has no parameters. - -@node Float_Equality_Checks -@subsection @code{Float_Equality_Checks} -@cindex @code{Float_Equality_Checks} rule (for @command{gnatcheck}) - -@noindent -Flag all calls to the predefined equality operations for floating-point types. -Both ``@code{=}'' and ``@code{/=}'' operations are checked. -User-defined equality operations are not flagged, nor are ``@code{=}'' -and ``@code{/=}'' operations for fixed-point types. - -This rule has no parameters. - - -@node Forbidden_Pragmas -@subsection @code{Forbidden_Pragmas} -@cindex @code{Forbidden_Pragmas} rule (for @command{gnatcheck}) - -@noindent -Flag each use of the specified pragmas. The pragmas to be detected -are named in the rule's parameters. - -This rule has the following parameters: - -@itemize @bullet -@item For the @option{+R} option - -@table @asis -@item @emph{Pragma_Name} -Adds the specified pragma to the set of pragmas to be -checked and sets the checks for all the specified pragmas -ON. @emph{Pragma_Name} is treated as a name of a pragma. If it -does not correspond to any pragma name defined in the Ada -standard or to the name of a GNAT-specific pragma defined -in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference -Manual}, it is treated as the name of unknown pragma. - -@item @code{GNAT} -All the GNAT-specific pragmas are detected; this sets -the checks for all the specified pragmas ON. - -@item @code{ALL} -All pragmas are detected; this sets the rule ON. -@end table - -@item For the @option{-R} option -@table @asis -@item @emph{Pragma_Name} -Removes the specified pragma from the set of pragmas to be -checked without affecting checks for -other pragmas. @emph{Pragma_Name} is treated as a name -of a pragma. If it does not correspond to any pragma -defined in the Ada standard or to any name defined in -@ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}, -this option is treated as turning OFF detection of all unknown pragmas. - -@item GNAT -Turn OFF detection of all GNAT-specific pragmas - -@item ALL -Clear the list of the pragmas to be detected and -turn the rule OFF. -@end table -@end itemize - -@noindent -Parameters are not case sensitive. If @emph{Pragma_Name} does not have -the syntax of an Ada identifier and therefore can not be considered -as a pragma name, a diagnostic message is generated and the corresponding -parameter is ignored. - -When more then one parameter is given in the same rule option, the parameters -must be separated by a comma. - -If more then one option for this rule is specified for the @command{gnatcheck} -call, a new option overrides the previous one(s). - -The @option{+R} option with no parameters turns the rule ON with the set of -pragmas to be detected defined by the previous rule options. -(By default this set is empty, so if the only option specified for the rule is -@option{+RForbidden_Pragmas} (with -no parameter), then the rule is enabled, but it does not detect anything). -The @option{-R} option with no parameter turns the rule OFF, but it does not -affect the set of pragmas to be detected. - - - - -@node Function_Style_Procedures -@subsection @code{Function_Style_Procedures} -@cindex @code{Function_Style_Procedures} rule (for @command{gnatcheck}) - -@noindent -Flag each procedure that can be rewritten as a function. A procedure can be -converted into a function if it has exactly one parameter of mode @code{out} -and no parameters of mode @code{in out}. Procedure declarations, -formal procedure declarations, and generic procedure declarations are always -checked. Procedure -bodies and body stubs are flagged only if they do not have corresponding -separate declarations. Procedure renamings and procedure instantiations are -not flagged. - -If a procedure can be rewritten as a function, but its @code{out} parameter is -of a limited type, it is not flagged. - -Protected procedures are not flagged. Null procedures also are not flagged. - -This rule has no parameters. - - -@node Generics_In_Subprograms -@subsection @code{Generics_In_Subprograms} -@cindex @code{Generics_In_Subprograms} rule (for @command{gnatcheck}) - -@noindent -Flag each declaration of a generic unit in a subprogram. Generic -declarations in the bodies of generic subprograms are also flagged. -A generic unit nested in another generic unit is not flagged. -If a generic unit is -declared in a local package that is declared in a subprogram body, the -generic unit is flagged. - -This rule has no parameters. - - -@node GOTO_Statements -@subsection @code{GOTO_Statements} -@cindex @code{GOTO_Statements} rule (for @command{gnatcheck}) - -@noindent -Flag each occurrence of a @code{goto} statement. - -This rule has no parameters. - - -@node Implicit_IN_Mode_Parameters -@subsection @code{Implicit_IN_Mode_Parameters} -@cindex @code{Implicit_IN_Mode_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each occurrence of a formal parameter with an implicit @code{in} mode. -Note that @code{access} parameters, although they technically behave -like @code{in} parameters, are not flagged. - -This rule has no parameters. - - -@node Implicit_SMALL_For_Fixed_Point_Types -@subsection @code{Implicit_SMALL_For_Fixed_Point_Types} -@cindex @code{Implicit_SMALL_For_Fixed_Point_Types} rule (for @command{gnatcheck}) - -@noindent -Flag each fixed point type declaration that lacks an explicit -representation clause to define its @code{'Small} value. -Since @code{'Small} can be defined only for ordinary fixed point types, -decimal fixed point type declarations are not checked. - -This rule has no parameters. - - -@node Improperly_Located_Instantiations -@subsection @code{Improperly_Located_Instantiations} -@cindex @code{Improperly_Located_Instantiations} rule (for @command{gnatcheck}) - -@noindent -Flag all generic instantiations in library-level package specs -(including library generic packages) and in all subprogram bodies. - -Instantiations in task and entry bodies are not flagged. Instantiations in the -bodies of protected subprograms are flagged. - -This rule has no parameters. - - - -@node Improper_Returns -@subsection @code{Improper_Returns} -@cindex @code{Improper_Returns} rule (for @command{gnatcheck}) - -@noindent -Flag each explicit @code{return} statement in procedures, and -multiple @code{return} statements in functions. -Diagnostic messages are generated for all @code{return} statements -in a procedure (thus each procedure must be written so that it -returns implicitly at the end of its statement part), -and for all @code{return} statements in a function after the first one. -This rule supports the stylistic convention that each subprogram -should have no more than one point of normal return. - -This rule has no parameters. - - -@node Library_Level_Subprograms -@subsection @code{Library_Level_Subprograms} -@cindex @code{Library_Level_Subprograms} rule (for @command{gnatcheck}) - -@noindent -Flag all library-level subprograms (including generic subprogram instantiations). - -This rule has no parameters. - - -@node Local_Packages -@subsection @code{Local_Packages} -@cindex @code{Local_Packages} rule (for @command{gnatcheck}) - -@noindent -Flag all local packages declared in package and generic package -specs. -Local packages in bodies are not flagged. - -This rule has no parameters. - -@ignore -@node Improperly_Called_Protected_Entries -@subsection @code{Improperly_Called_Protected_Entries} (under construction, GLOBAL) -@cindex @code{Improperly_Called_Protected_Entries} rule (for @command{gnatcheck}) - -@noindent -Flag each protected entry that can be called from more than one task. - -This rule has no parameters. -@end ignore - -@node Metrics -@subsection @code{Metrics} -@cindex @code{Metrics} rule (for @command{gnatcheck}) - -@noindent -There is a set of checks based on computing a metric value and comparing the -result with the specified upper (or lower, depending on a specific metric) -value specified for a given metric. A construct is flagged if a given metric -is applicable (can be computed) for it and the computed value is greater -then (lover then) the specified upper (lower) bound. - -The name of any metric-based rule consists of the prefix @code{Metrics_} -followed by the name of the corresponding metric (see the table below). -For @option{+R} option, each metric-based rule has a numeric parameter -specifying the bound (integer or real, depending on a metric), @option{-R} -option for metric rules does not have a parameter. - -The following table shows the metric names for that the corresponding -metrics-based checks are supported by gnatcheck, including the -constraint that must be satisfied by the bound that is specified for the check -and what bound - upper (U) or lower (L) - should be specified. - -@multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer} -@ifnothtml -@headitem Check Name @tab Description @tab Bounds Value -@end ifnothtml -@ifhtml -@item @b{Check Name} @tab @b{Description} @tab @b{Bounds Value} -@end ifhtml -@c Above conditional code is workaround to bug in texi2html (Feb 2008) -@item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer (U) -@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer (U) -@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer (U) -@end multitable - -@noindent -The meaning and the computed values for all these metrics are exactly -the same as for the corresponding metrics in @command{gnatmetric}. - -@emph{Example:} the rule -@smallexample -+RMetrics_Cyclomatic_Complexity : 7 -@end smallexample -@noindent -means that all bodies with cyclomatic complexity exceeding 7 will be flagged. - -To turn OFF the check for cyclomatic complexity metric, use the following option: -@smallexample --RMetrics_Cyclomatic_Complexity -@end smallexample - -@node Misnamed_Identifiers -@subsection @code{Misnamed_Identifiers} -@cindex @code{Misnamed_Identifiers} rule (for @command{gnatcheck}) - -@noindent -Flag the declaration of each identifier that does not have a suffix -corresponding to the kind of entity being declared. -The following declarations are checked: - -@itemize @bullet -@item -type declarations - -@item -constant declarations (but not number declarations) - -@item -package renaming declarations (but not generic package renaming -declarations) -@end itemize - -@noindent -This rule may have parameters. When used without parameters, the rule enforces -the following checks: - -@itemize @bullet -@item -type-defining names end with @code{_T}, unless the type is an access type, -in which case the suffix must be @code{_A} -@item -constant names end with @code{_C} -@item -names defining package renamings end with @code{_R} -@end itemize - -@noindent -For a private or incomplete type declaration the following checks are -made for the defining name suffix: - -@itemize @bullet -@item -For an incomplete type declaration: if the corresponding full type -declaration is available, the defining identifier from the full type -declaration is checked, but the defining identifier from the incomplete type -declaration is not; otherwise the defining identifier from the incomplete -type declaration is checked against the suffix specified for type -declarations. - -@item -For a private type declaration (including private extensions), the defining -identifier from the private type declaration is checked against the type -suffix (even if the corresponding full declaration is an access type -declaration), and the defining identifier from the corresponding full type -declaration is not checked. -@end itemize - -@noindent -For a deferred constant, the defining name in the corresponding full constant -declaration is not checked. - -Defining names of formal types are not checked. - -The rule may have the following parameters: - -@itemize @bullet -@item -For the @option{+R} option: -@table @code -@item Default -Sets the default listed above for all the names to be checked. - -@item Type_Suffix=@emph{string} -Specifies the suffix for a type name. - -@item Access_Suffix=@emph{string} -Specifies the suffix for an access type name. If -this parameter is set, it overrides for access -types the suffix set by the @code{Type_Suffix} parameter. - -@item Constant_Suffix=@emph{string} -Specifies the suffix for a constant name. - -@item Renaming_Suffix=@emph{string} -Specifies the suffix for a package renaming name. -@end table - -@item -For the @option{-R} option: -@table @code -@item All_Suffixes -Remove all the suffixes specified for the -identifier suffix checks, whether by default or -as specified by other rule parameters. All the -checks for this rule are disabled as a result. - -@item Type_Suffix -Removes the suffix specified for types. This -disables checks for types but does not disable -any other checks for this rule (including the -check for access type names if @code{Access_Suffix} is -set). - -@item Access_Suffix -Removes the suffix specified for access types. -This disables checks for access type names but -does not disable any other checks for this rule. -If @code{Type_Suffix} is set, access type names are -checked as ordinary type names. - -@item Constant_Suffix -Removes the suffix specified for constants. This -disables checks for constant names but does not -disable any other checks for this rule. - -@item Renaming_Suffix -Removes the suffix specified for package -renamings. This disables checks for package -renamings but does not disable any other checks -for this rule. -@end table -@end itemize - -@noindent -If more than one parameter is used, parameters must be separated by commas. - -If more than one option is specified for the @command{gnatcheck} invocation, -a new option overrides the previous one(s). - -The @option{+RMisnamed_Identifiers} option (with no parameter) enables -checks for all the -name suffixes specified by previous options used for this rule. - -The @option{-RMisnamed_Identifiers} option (with no parameter) disables -all the checks but keeps -all the suffixes specified by previous options used for this rule. - -The @emph{string} value must be a valid suffix for an Ada identifier (after -trimming all the leading and trailing space characters, if any). -Parameters are not case sensitive, except the @emph{string} part. - -If any error is detected in a rule parameter, the parameter is ignored. -In such a case the options that are set for the rule are not -specified. - - - -@node Multiple_Entries_In_Protected_Definitions -@subsection @code{Multiple_Entries_In_Protected_Definitions} -@cindex @code{Multiple_Entries_In_Protected_Definitions} rule (for @command{gnatcheck}) - -@noindent -Flag each protected definition (i.e., each protected object/type declaration) -that defines more than one entry. -Diagnostic messages are generated for all the entry declarations -except the first one. An entry family is counted as one entry. Entries from -the private part of the protected definition are also checked. - -This rule has no parameters. - -@node Name_Clashes -@subsection @code{Name_Clashes} -@cindex @code{Name_Clashes} rule (for @command{gnatcheck}) - -@noindent -Check that certain names are not used as defining identifiers. To activate -this rule, you need to supply a reference to the dictionary file(s) as a rule -parameter(s) (more then one dictionary file can be specified). If no -dictionary file is set, this rule will not cause anything to be flagged. -Only defining occurrences, not references, are checked. -The check is not case-sensitive. - -This rule is enabled by default, but without setting any corresponding -dictionary file(s); thus the default effect is to do no checks. - -A dictionary file is a plain text file. The maximum line length for this file -is 1024 characters. If the line is longer then this limit, extra characters -are ignored. - -Each line can be either an empty line, a comment line, or a line containing -a list of identifiers separated by space or HT characters. -A comment is an Ada-style comment (from @code{--} to end-of-line). -Identifiers must follow the Ada syntax for identifiers. -A line containing one or more identifiers may end with a comment. - -@node Non_Qualified_Aggregates -@subsection @code{Non_Qualified_Aggregates} -@cindex @code{Non_Qualified_Aggregates} rule (for @command{gnatcheck}) - -@noindent -Flag each non-qualified aggregate. -A non-qualified aggregate is an -aggregate that is not the expression of a qualified expression. A -string literal is not considered an aggregate, but an array -aggregate of a string type is considered as a normal aggregate. -Aggregates of anonymous array types are not flagged. - -This rule has no parameters. - - -@node Non_Short_Circuit_Operators -@subsection @code{Non_Short_Circuit_Operators} -@cindex @code{Non_Short_Circuit_Operators} rule (for @command{gnatcheck}) - -@noindent -Flag all calls to predefined @code{and} and @code{or} operators for -any boolean type. Calls to -user-defined @code{and} and @code{or} and to operators defined by renaming -declarations are not flagged. Calls to predefined @code{and} and @code{or} -operators for modular types or boolean array types are not flagged. - -This rule has no parameters. - - - -@node Non_SPARK_Attributes -@subsection @code{Non_SPARK_Attributes} -@cindex @code{Non_SPARK_Attributes} rule (for @command{gnatcheck}) - -@noindent -The SPARK language defines the following subset of Ada 95 attribute -designators as those that can be used in SPARK programs. The use of -any other attribute is flagged. - -@itemize @bullet -@item @code{'Adjacent} -@item @code{'Aft} -@item @code{'Base} -@item @code{'Ceiling} -@item @code{'Component_Size} -@item @code{'Compose} -@item @code{'Copy_Sign} -@item @code{'Delta} -@item @code{'Denorm} -@item @code{'Digits} -@item @code{'Exponent} -@item @code{'First} -@item @code{'Floor} -@item @code{'Fore} -@item @code{'Fraction} -@item @code{'Last} -@item @code{'Leading_Part} -@item @code{'Length} -@item @code{'Machine} -@item @code{'Machine_Emax} -@item @code{'Machine_Emin} -@item @code{'Machine_Mantissa} -@item @code{'Machine_Overflows} -@item @code{'Machine_Radix} -@item @code{'Machine_Rounds} -@item @code{'Max} -@item @code{'Min} -@item @code{'Model} -@item @code{'Model_Emin} -@item @code{'Model_Epsilon} -@item @code{'Model_Mantissa} -@item @code{'Model_Small} -@item @code{'Modulus} -@item @code{'Pos} -@item @code{'Pred} -@item @code{'Range} -@item @code{'Remainder} -@item @code{'Rounding} -@item @code{'Safe_First} -@item @code{'Safe_Last} -@item @code{'Scaling} -@item @code{'Signed_Zeros} -@item @code{'Size} -@item @code{'Small} -@item @code{'Succ} -@item @code{'Truncation} -@item @code{'Unbiased_Rounding} -@item @code{'Val} -@item @code{'Valid} -@end itemize - -@noindent -This rule has no parameters. - - -@node Non_Tagged_Derived_Types -@subsection @code{Non_Tagged_Derived_Types} -@cindex @code{Non_Tagged_Derived_Types} rule (for @command{gnatcheck}) - -@noindent -Flag all derived type declarations that do not have a record extension part. - -This rule has no parameters. - - - -@node Non_Visible_Exceptions -@subsection @code{Non_Visible_Exceptions} -@cindex @code{Non_Visible_Exceptions} rule (for @command{gnatcheck}) - -@noindent -Flag constructs leading to the possibility of propagating an exception -out of the scope in which the exception is declared. -Two cases are detected: - -@itemize @bullet -@item -An exception declaration in a subprogram body, task body or block -statement is flagged if the body or statement does not contain a handler for -that exception or a handler with an @code{others} choice. - -@item -A @code{raise} statement in an exception handler of a subprogram body, -task body or block statement is flagged if it (re)raises a locally -declared exception. This may occur under the following circumstances: -@itemize @minus -@item -it explicitly raises a locally declared exception, or -@item -it does not specify an exception name (i.e., it is simply @code{raise;}) -and the enclosing handler contains a locally declared exception in its -exception choices. -@end itemize -@end itemize - -@noindent -Renamings of local exceptions are not flagged. - -This rule has no parameters. - - -@node Numeric_Literals -@subsection @code{Numeric_Literals} -@cindex @code{Numeric_Literals} rule (for @command{gnatcheck}) - -@noindent -Flag each use of a numeric literal in an index expression, and in any -circumstance except for the following: - -@itemize @bullet -@item -a literal occurring in the initialization expression for a constant -declaration or a named number declaration, or - -@item -an integer literal that is less than or equal to a value -specified by the @option{N} rule parameter. -@end itemize - -@noindent -This rule may have the following parameters for the @option{+R} option: - -@table @asis -@item @emph{N} -@emph{N} is an integer literal used as the maximal value that is not flagged -(i.e., integer literals not exceeding this value are allowed) - -@item @code{ALL} -All integer literals are flagged -@end table - -@noindent -If no parameters are set, the maximum unflagged value is 1. - -The last specified check limit (or the fact that there is no limit at -all) is used when multiple @option{+R} options appear. - -The @option{-R} option for this rule has no parameters. -It disables the rule but retains the last specified maximum unflagged value. -If the @option{+R} option subsequently appears, this value is used as the -threshold for the check. - - -@node OTHERS_In_Aggregates -@subsection @code{OTHERS_In_Aggregates} -@cindex @code{OTHERS_In_Aggregates} rule (for @command{gnatcheck}) - -@noindent -Flag each use of an @code{others} choice in extension aggregates. -In record and array aggregates, an @code{others} choice is flagged unless -it is used to refer to all components, or to all but one component. - -If, in case of a named array aggregate, there are two associations, one -with an @code{others} choice and another with a discrete range, the -@code{others} choice is flagged even if the discrete range specifies -exactly one component; for example, @code{(1..1 => 0, others => 1)}. - -This rule has no parameters. - -@node OTHERS_In_CASE_Statements -@subsection @code{OTHERS_In_CASE_Statements} -@cindex @code{OTHERS_In_CASE_Statements} rule (for @command{gnatcheck}) - -@noindent -Flag any use of an @code{others} choice in a @code{case} statement. - -This rule has no parameters. - -@node OTHERS_In_Exception_Handlers -@subsection @code{OTHERS_In_Exception_Handlers} -@cindex @code{OTHERS_In_Exception_Handlers} rule (for @command{gnatcheck}) - -@noindent -Flag any use of an @code{others} choice in an exception handler. - -This rule has no parameters. - - -@node Outer_Loop_Exits -@subsection @code{Outer_Loop_Exits} -@cindex @code{Outer_Loop_Exits} rule (for @command{gnatcheck}) - -@noindent -Flag each @code{exit} statement containing a loop name that is not the name -of the immediately enclosing @code{loop} statement. - -This rule has no parameters. - - -@node Overloaded_Operators -@subsection @code{Overloaded_Operators} -@cindex @code{Overloaded_Operators} rule (for @command{gnatcheck}) - -@noindent -Flag each function declaration that overloads an operator symbol. -A function body is checked only if the body does not have a -separate spec. Formal functions are also checked. For a -renaming declaration, only renaming-as-declaration is checked - -This rule has no parameters. - - -@node Overly_Nested_Control_Structures -@subsection @code{Overly_Nested_Control_Structures} -@cindex @code{Overly_Nested_Control_Structures} rule (for @command{gnatcheck}) - -@noindent -Flag each control structure whose nesting level exceeds the value provided -in the rule parameter. - -The control structures checked are the following: - -@itemize @bullet -@item @code{if} statement -@item @code{case} statement -@item @code{loop} statement -@item Selective accept statement -@item Timed entry call statement -@item Conditional entry call -@item Asynchronous select statement -@end itemize - -@noindent -The rule has the following parameter for the @option{+R} option: - -@table @emph -@item N -Positive integer specifying the maximal control structure nesting -level that is not flagged -@end table - -@noindent -If the parameter for the @option{+R} option is not specified or -if it is not a positive integer, @option{+R} option is ignored. - -If more then one option is specified for the gnatcheck call, the later option and -new parameter override the previous one(s). - - -@node Parameters_Out_Of_Order -@subsection @code{Parameters_Out_Of_Order} -@cindex @code{Parameters_Out_Of_Order} rule (for @command{gnatcheck}) - -@noindent -Flag each subprogram and entry declaration whose formal parameters are not -ordered according to the following scheme: - -@itemize @bullet - -@item @code{in} and @code{access} parameters first, -then @code{in out} parameters, -and then @code{out} parameters; - -@item for @code{in} mode, parameters with default initialization expressions -occur last -@end itemize - -@noindent -Only the first violation of the described order is flagged. - -The following constructs are checked: - -@itemize @bullet -@item subprogram declarations (including null procedures); -@item generic subprogram declarations; -@item formal subprogram declarations; -@item entry declarations; -@item subprogram bodies and subprogram body stubs that do not -have separate specifications -@end itemize - -@noindent -Subprogram renamings are not checked. - -This rule has no parameters. - - -@node Positional_Actuals_For_Defaulted_Generic_Parameters -@subsection @code{Positional_Actuals_For_Defaulted_Generic_Parameters} -@cindex @code{Positional_Actuals_For_Defaulted_Generic_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each generic actual parameter corresponding to a generic formal -parameter with a default initialization, if positional notation is used. - -This rule has no parameters. - -@node Positional_Actuals_For_Defaulted_Parameters -@subsection @code{Positional_Actuals_For_Defaulted_Parameters} -@cindex @code{Positional_Actuals_For_Defaulted_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each actual parameter to a subprogram or entry call where the -corresponding formal parameter has a default expression, if positional -notation is used. - -This rule has no parameters. - -@node Positional_Components -@subsection @code{Positional_Components} -@cindex @code{Positional_Components} rule (for @command{gnatcheck}) - -@noindent -Flag each array, record and extension aggregate that includes positional -notation. - -This rule has no parameters. - - -@node Positional_Generic_Parameters -@subsection @code{Positional_Generic_Parameters} -@cindex @code{Positional_Generic_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each instantiation using positional parameter notation. - -This rule has no parameters. - - -@node Positional_Parameters -@subsection @code{Positional_Parameters} -@cindex @code{Positional_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flag each subprogram or entry call using positional parameter notation, -except for the following: - -@itemize @bullet -@item -Invocations of prefix or infix operators are not flagged -@item -If the called subprogram or entry has only one formal parameter, -the call is not flagged; -@item -If a subprogram call uses the @emph{Object.Operation} notation, then -@itemize @minus -@item -the first parameter (that is, @emph{Object}) is not flagged; -@item -if the called subprogram has only two parameters, the second parameter -of the call is not flagged; -@end itemize -@end itemize - -@noindent -This rule has no parameters. - - - - -@node Predefined_Numeric_Types -@subsection @code{Predefined_Numeric_Types} -@cindex @code{Predefined_Numeric_Types} rule (for @command{gnatcheck}) - -@noindent -Flag each explicit use of the name of any numeric type or subtype defined -in package @code{Standard}. - -The rationale for this rule is to detect when the -program may depend on platform-specific characteristics of the implementation -of the predefined numeric types. Note that this rule is over-pessimistic; -for example, a program that uses @code{String} indexing -likely needs a variable of type @code{Integer}. -Another example is the flagging of predefined numeric types with explicit -constraints: - -@smallexample @c ada - subtype My_Integer is Integer range Left .. Right; - Vy_Var : My_Integer; -@end smallexample - -@noindent -This rule detects only numeric types and subtypes defined in -@code{Standard}. The use of numeric types and subtypes defined in other -predefined packages (such as @code{System.Any_Priority} or -@code{Ada.Text_IO.Count}) is not flagged - -This rule has no parameters. - - - -@node Raising_External_Exceptions -@subsection @code{Raising_External_Exceptions} -@cindex @code{Raising_External_Exceptions} rule (for @command{gnatcheck}) - -@noindent -Flag any @code{raise} statement, in a program unit declared in a library -package or in a generic library package, for an exception that is -neither a predefined exception nor an exception that is also declared (or -renamed) in the visible part of the package. - -This rule has no parameters. - - - -@node Raising_Predefined_Exceptions -@subsection @code{Raising_Predefined_Exceptions} -@cindex @code{Raising_Predefined_Exceptions} rule (for @command{gnatcheck}) - -@noindent -Flag each @code{raise} statement that raises a predefined exception -(i.e., one of the exceptions @code{Constraint_Error}, @code{Numeric_Error}, -@code{Program_Error}, @code{Storage_Error}, or @code{Tasking_Error}). - -This rule has no parameters. - -@node Separate_Numeric_Error_Handlers -@subsection @code{Separate_Numeric_Error_Handlers} -@cindex @code{Separate_Numeric_Error_Handlers} rule (for @command{gnatcheck}) - -@noindent -Flags each exception handler that contains a choice for -the predefined @code{Constraint_Error} exception, but does not contain -the choice for the predefined @code{Numeric_Error} exception, or -that contains the choice for @code{Numeric_Error}, but does not contain the -choice for @code{Constraint_Error}. - -This rule has no parameters. - -@ignore -@node Recursion -@subsection @code{Recursion} (under construction, GLOBAL) -@cindex @code{Recursion} rule (for @command{gnatcheck}) - -@noindent -Flag recursive subprograms (cycles in the call graph). Declarations, and not -calls, of recursive subprograms are detected. - -This rule has no parameters. -@end ignore - -@ignore -@node Side_Effect_Functions -@subsection @code{Side_Effect_Functions} (under construction, GLOBAL) -@cindex @code{Side_Effect_Functions} rule (for @command{gnatcheck}) - -@noindent -Flag functions with side effects. - -We define a side effect as changing any data object that is not local for the -body of this function. - -At the moment, we do NOT consider a side effect any input-output operations -(changing a state or a content of any file). - -We do not consider protected functions for this rule (???) - -There are the following sources of side effect: - -@enumerate -@item Explicit (or direct) side-effect: - -@itemize @bullet -@item -direct assignment to a non-local variable; - -@item -direct call to an entity that is known to change some data object that is - not local for the body of this function (Note, that if F1 calls F2 and F2 - does have a side effect, this does not automatically mean that F1 also - have a side effect, because it may be the case that F2 is declared in - F1's body and it changes some data object that is global for F2, but - local for F1); -@end itemize - -@item Indirect side-effect: -@itemize @bullet -@item -Subprogram calls implicitly issued by: -@itemize @bullet -@item -computing initialization expressions from type declarations as a part - of object elaboration or allocator evaluation; -@item -computing implicit parameters of subprogram or entry calls or generic - instantiations; -@end itemize - -@item -activation of a task that change some non-local data object (directly or - indirectly); - -@item -elaboration code of a package that is a result of a package instantiation; - -@item -controlled objects; -@end itemize - -@item Situations when we can suspect a side-effect, but the full static check -is either impossible or too hard: -@itemize @bullet -@item -assignment to access variables or to the objects pointed by access - variables; - -@item -call to a subprogram pointed by access-to-subprogram value - -@item -dispatching calls; -@end itemize -@end enumerate - -@noindent -This rule has no parameters. -@end ignore - -@node Slices -@subsection @code{Slices} -@cindex @code{Slices} rule (for @command{gnatcheck}) - -@noindent -Flag all uses of array slicing - -This rule has no parameters. - - -@node Unassigned_OUT_Parameters -@subsection @code{Unassigned_OUT_Parameters} -@cindex @code{Unassigned_OUT_Parameters} rule (for @command{gnatcheck}) - -@noindent -Flags procedures' @code{out} parameters that are not assigned, and -identifies the contexts in which the assignments are missing. - -An @code{out} parameter is flagged in the statements in the procedure -body's handled sequence of statements (before the procedure body's -@code{exception} part, if any) if this sequence of statements contains -no assignments to the parameter. - -An @code{out} parameter is flagged in an exception handler in the exception -part of the procedure body's handled sequence of statements if the handler -contains no assignment to the parameter. - -Bodies of generic procedures are also considered. - -The following are treated as assignments to an @code{out} parameter: - -@itemize @bullet -@item -an assignment statement, with the parameter or some component as the target; - -@item -passing the parameter (or one of its components) as an @code{out} or -@code{in out} parameter. -@end itemize - -@noindent -This rule does not have any parameters. - - - -@node Uncommented_BEGIN_In_Package_Bodies -@subsection @code{Uncommented_BEGIN_In_Package_Bodies} -@cindex @code{Uncommented_BEGIN_In_Package_Bodies} rule (for @command{gnatcheck}) - -@noindent -Flags each package body with declarations and a statement part that does not -include a trailing comment on the line containing the @code{begin} keyword; -this trailing comment needs to specify the package name and nothing else. -The @code{begin} is not flagged if the package body does not -contain any declarations. - -If the @code{begin} keyword is placed on the -same line as the last declaration or the first statement, it is flagged -independently of whether the line contains a trailing comment. The -diagnostic message is attached to the line containing the first statement. - -This rule has no parameters. - - -@node Unconstrained_Array_Returns -@subsection @code{Unconstrained_Array_Returns} -@cindex @code{Unconstrained_Array_Returns} rule (for @command{gnatcheck}) - -@noindent -Flag each function returning an unconstrained array. Function declarations, -function bodies (and body stubs) having no separate specifications, -and generic function instantiations are checked. -Generic function declarations, function calls and function renamings are -not checked. - -This rule has no parameters. - -@node Universal_Ranges -@subsection @code{Universal_Ranges} -@cindex @code{Universal_Ranges} rule (for @command{gnatcheck}) - -@noindent -Flag discrete ranges that are a part of an index constraint, constrained -array definition, or @code{for}-loop parameter specification, and whose bounds -are both of type @i{universal_integer}. Ranges that have at least one -bound of a specific type (such as @code{1 .. N}, where @code{N} is a variable -or an expression of non-universal type) are not flagged. - -This rule has no parameters. - - -@node Unnamed_Blocks_And_Loops -@subsection @code{Unnamed_Blocks_And_Loops} -@cindex @code{Unnamed_Blocks_And_Loops} rule (for @command{gnatcheck}) - -@noindent -Flag each unnamed block statement and loop statement. - -The rule has no parameters. - - - -@ignore -@node Unused_Subprograms -@subsection @code{Unused_Subprograms} (under construction, GLOBAL) -@cindex @code{Unused_Subprograms} rule (for @command{gnatcheck}) - -@noindent -Flag all unused subprograms. - -This rule has no parameters. -@end ignore - - - - -@node USE_PACKAGE_Clauses -@subsection @code{USE_PACKAGE_Clauses} -@cindex @code{USE_PACKAGE_Clauses} rule (for @command{gnatcheck}) - -@noindent -Flag all @code{use} clauses for packages; @code{use type} clauses are -not flagged. - -This rule has no parameters. - - - -@node Volatile_Objects_Without_Address_Clauses -@subsection @code{Volatile_Objects_Without_Address_Clauses} -@cindex @code{Volatile_Objects_Without_Address_Clauses} rule (for @command{gnatcheck}) - -@noindent -Flag each volatile object that does not have an address clause. - -The following check is made: if the pragma @code{Volatile} is applied to a -data object or to its type, then an address clause must -be supplied for this object. - -This rule does not check the components of data objects, -array components that are volatile as a result of the pragma -@code{Volatile_Components}, or objects that are volatile because -they are atomic as a result of pragmas @code{Atomic} or -@code{Atomic_Components}. - -Only variable declarations, and not constant declarations, are checked. - -This rule has no parameters. - - -@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. - -@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 -$ gnatstub @ovar{switches} @var{filename} @ovar{directory} -@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 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 ^-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 - -@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 -$ perl gnathtml.pl @ovar{^switches^options^} @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 -$ perl gnathtml.pl @ovar{switches} @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 <PROGRAM_NAME> -$ DEFINE LIB$DEBUG PCA$COLLECTOR -$ RUN/DEBUG <PROGRAM_NAME> -@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:: -* 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 breakpoint exception @var{name} -A special form of the breakpoint command which breakpoints whenever -exception @var{name} is raised. -If @var{name} is omitted, -then a breakpoint will occur 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 Breaking on Ada Exceptions -@cindex Exceptions - -@noindent -You can set breakpoints that trip when your program raises -selected exceptions. - -@table @code -@item break exception -Set a breakpoint that trips whenever (any task in the) program raises -any exception. - -@item break exception @var{name} -Set a breakpoint that trips whenever (any task in the) program raises -the exception @var{name}. - -@item break exception unhandled -Set a breakpoint that trips 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 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 <mainCRTStartup> 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 as follows: -@itemize @bullet -@item @code{ABORT_DEFER} - -@item @code{ADA_83} - -@item @code{ADA_95} - -@item @code{ADA_05} - -@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 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:: -@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}). - -@end itemize - -@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 (RM); -@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:: -* Unchecked conversions:: -* Predefined constants:: -* Interfacing with C:: -* 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 - -@item -@code{System.Short_Address} is a 32-bit subtype of @code{System.Address} -@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 -@subsubsection Access types - -@noindent -By default, objects designated by access values are always -allocated in the 32-bit -address space. Thus legacy code will never contain -any objects that are not addressable with 32-bit addresses, and -the compiler will never raise exceptions as result of mixing -32-bit and 64-bit addresses. - -However, the access values themselves are represented in 64 bits, for optimum -performance and future compatibility with 64-bit code. As was -the case with @code{System.Address}, the compiler will give an error message -if an object or record component has a representation clause that -requires the access value to fit in 32 bits. In such a situation, -an explicit size clause for the access type, specifying 32 bits, -will have the desired effect. - -General access types (declared with @code{access all}) can never be -32 bits, 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 Ada 83 code will not contain such type definitions, -however, since general access types were introduced in Ada 95. - -@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 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:: -* Using 64 bit storage pools by default:: -* General access types:: -* 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 -For any access type @code{T} that potentially requires memory allocations -beyond the 32-bit address space, -use the following representation clause: - -@smallexample @c ada - for T'Storage_Pool use System.Pool_64; -@end smallexample - -@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 Using 64 bit storage pools by default -@subsubsection Using 64-bit storage pools by default - -@noindent -In some cases it may be desirable to have the compiler allocate -from 64-bit storage pools by default. This may be the case for -libraries that are 64-bit clean, but may be used in both 32-bit -and 64-bit contexts. For these cases the following configuration -pragma may be specified: - -@smallexample @c ada - pragma Pool_64_Default; -@end smallexample - -@noindent -Any code compiled in the context of this pragma will by default -use the @code{System.Pool_64} storage pool. This default may be overridden -for a specific access type @code{T} by the representation clause: - -@smallexample @c ada - for T'Storage_Pool use System.Pool_32; -@end smallexample - -@noindent -Any object whose address may be passed to a subprogram with a -@code{Short_Address} argument, or assigned to a variable of type -@code{Short_Address}, needs to be allocated from this pool. - -@node General access types -@subsubsection General access types - -@noindent -Objects designated by access values from a -general access type (declared with @code{access all}) are never allocated -from a 64-bit storage pool. Code that uses general access types will -accept objects allocated in either 32-bit or 64-bit address spaces, -but never allocate objects outside the 32-bit address space. -Using general access types ensures maximum compatibility with both -32-bit and 64-bit code. - -@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:: -* Building DLLs with GNAT Project files:: -* 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. The library must be built to be compatible with -@file{MSVCRT.LIB} (/MD Microsoft compiler option), @file{LIBC.LIB} and -@file{LIBCMT.LIB} (/ML or /MT Microsoft compiler options) are known to -not be compatible with the GNAT runtime. Even if the library is -compatible with @file{MSVCRT.LIB} it is not guaranteed to work. - -@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 plan to use -Microsoft tools (e.g.@: Microsoft Visual C/C++), you should be aware of -the following limitations: - -@itemize @bullet -@item -You cannot link your Ada code with an object or library generated with -Microsoft tools if these use the @code{.tls} section (Thread Local -Storage section) since the GNAT linker does not yet support this section. - -@item -You cannot link your Ada code with an object or library generated with -Microsoft tools if these use I/O routines other than those provided in -the Microsoft DLL: @code{msvcrt.dll}. This is because the GNAT run time -uses the services of @code{msvcrt.dll} for its I/Os. Use of other I/O -libraries can cause a conflict with @code{msvcrt.dll} services. For -instance Visual C++ I/O stream routines conflict with those in -@code{msvcrt.dll}. -@end itemize - -@noindent -If you do want to use the Microsoft tools for your non-Ada code and hit one -of the above limitations, 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}) 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 - -@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 first for a library named @file{API.lib} -(Microsoft-style name) and if not found for a libraries named -@file{libAPI.dll.a}, @file{API.dll.a} or @file{libAPI.a}. -(GNAT-style name). 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 Stdcall 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 -@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} -option. It is quite simple to use this method: - -@smallexample -$ gcc -shared -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 -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 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 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 the built-in GNAT DLL support -(@pxref{Building DLLs with GNAT}) or GNAT Project files -(@pxref{Building DLLs with GNAT Project files}) 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 -$ gnatdll @ovar{switches} @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 -@item -a@ovar{address} -@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 -$ dlltool @ovar{switches} -@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. -@item -@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 |