@c o
@c G N A T _ U G N o
@c o
-@c Copyright (C) 1992-2004 Ada Core Technologies, Inc. o
+@c Copyright (C) 1992-2006, AdaCore o
@c o
@c GNAT is free software; you can redistribute it and/or modify it under o
@c terms of the GNU General Public License as published by the Free Soft- o
@c or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License o
@c for more details. You should have received a copy of the GNU General o
@c Public License distributed with GNAT; see file COPYING. If not, write o
-@c to the Free Software Foundation, 59 Temple Place - Suite 330, Boston, o
-@c MA 02111-1307, USA. o
+@c to the Free Software Foundation, 51 Franklin Street, Fifth Floor, o
+@c Boston, MA 02110-1301, USA. o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@setfilename gnat_ugn_unw.info
@end ifset
+@set FSFEDITION
+@set EDITION GNAT
+
+@ifset unw
+@set PLATFORM
+@set FILE gnat_ugn_unw
+@end ifset
+
@ifset vms
-@settitle GNAT User's Guide for Native Platforms / OpenVMS Alpha
-@dircategory GNU Ada tools
-@direntry
-* GNAT User's Guide (gnat_ugn_vms) for Native Platforms / OpenVMS Alpha
-@end direntry
+@set PLATFORM OpenVMS
+@set FILE gnat_ugn_vms
@end ifset
-@ifset unw
-@settitle GNAT User's Guide for Native Platforms / Unix and Windows
+@settitle @value{EDITION} User's Guide @value{PLATFORM}
+@dircategory GNU Ada tools
@direntry
-* GNAT User's Guide (gnat_ugn_unw) for Native Platforms / Unix and Windows
+* @value{EDITION} User's Guide (@value{FILE}) @value{PLATFORM}
@end direntry
-@end ifset
@include gcc-common.texi
@c %**end of header
@copying
-Copyright @copyright{} 1995-2004, Free Software Foundation
+Copyright @copyright{} 1995-2005, Free Software Foundation
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 the Invariant Sections being ``GNU Free Documentation License'', with the
Front-Cover Texts being
-@ifset vms
-``GNAT User's Guide for Native Platforms / OpenVMS Alpha'',
-@end ifset
-@ifset unw
-``GNAT User's Guide for Native Platforms / Unix and Windows'',
-@end ifset
+``@value{EDITION} User's Guide'',
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@titlepage
-@title GNAT User's Guide
-@center @titlefont{for Native Platforms}
-@sp 1
+@title @value{EDITION} User's Guide
-@flushright
-@ifset unw
-@titlefont{@i{Unix and Windows}}
-@end ifset
@ifset vms
-@titlefont{@i{OpenVMS Alpha}}
-@end ifset
+@sp 1
+@flushright
+@titlefont{@i{@value{PLATFORM}}}
@end flushright
+@end ifset
+
@sp 2
@subtitle GNAT, The GNU Ada 95 Compiler
@subtitle GCC version @value{version-GCC}
-@author Ada Core Technologies, Inc.
+@author AdaCore
@page
@vskip 0pt plus 1filll
@end titlepage
-
@ifnottex
@node Top, About This Guide, (dir), (dir)
-@top GNAT User's Guide
+@top @value{EDITION} User's Guide
-@ifset vms
-@noindent
-GNAT User's Guide for Native Platforms / OpenVMS Alpha
-@end ifset
-
-@ifset unw
@noindent
-GNAT User's Guide for Native Platforms / Unix and Windows
-@end ifset
+@value{EDITION} User's Guide @value{PLATFORM}
@noindent
GNAT, The GNU Ada 95 Compiler@*
GCC version @value{version-GCC}@*
@noindent
-Ada Core Technologies, Inc.@*
+AdaCore@*
@menu
* About This Guide::
* 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
* GNAT and Libraries::
* Using the GNU make Utility::
@end ifclear
-* Finding Memory Problems::
+* Memory Management Issues::
+* Stack Related Facilities::
+* Verifying properties using gnatcheck::
* Creating Sample Bodies Using gnatstub::
* Other Utility Programs::
* Running and Debugging Ada Programs::
@ifset vms
-* Compatibility with DEC Ada::
+* Compatibility with HP Ada::
@end ifset
* Platform-Specific Information for the Run-Time Libraries::
* Example of Binder Output File::
* 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::
* Output and Error Message Control::
* Warning Message Control::
* Debugging and Assertion Control::
-* Run-Time Checks::
-* Stack Overflow Checking::
* Validity Checking::
* Style Checking::
+* Run-Time Checks::
* Using gcc for Syntax Checking::
* Using gcc for Semantic Checking::
-* Compiling Ada 83 Programs::
+* Compiling Different Versions of Ada::
* Character Set Control::
* File Naming Control::
* Subprogram Inlining Control::
* Running gnatlink::
* Switches for gnatlink::
-* Setting Stack Size from gnatlink::
-* Setting Heap Size from gnatlink::
The GNAT Make Program gnatmake
* How gnatmake Works::
* Examples of gnatmake Usage::
-
Improving Performance
* Performance Considerations::
* Reducing the Size of Ada Executables with gnatelim::
+* Reducing the Size of Executables with unused subprogram/data elimination::
Performance Considerations
* Controlling Run-Time Checks::
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
+* Other Optimization Switches::
* Optimization and Strict Aliasing::
@ifset vms
* Coverage Analysis::
* Making Your Executables Smaller::
* Summary of the gnatelim Usage Cycle::
+Reducing the Size of Executables with unused subprogram/data elimination
+* About unused subprogram/data elimination::
+* Compilation options::
+
Renaming Files Using gnatchop
* Handling Files with Multiple Units::
* 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::
-* Using Third-Party Libraries through 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::
* 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
* Running gnatclean::
* Switches for gnatclean::
-* Examples of gnatclean Usage::
+@c * Examples of gnatclean Usage::
@ifclear vms
GNAT and Libraries
-* Creating an Ada Library::
-* Installing an Ada Library::
-* Using an Ada Library::
-* Creating an Ada Library to be Used in a Non-Ada Context::
+* Introduction to Libraries in GNAT::
+* General Ada Libraries::
+* Stand-alone Ada Libraries::
* Rebuilding the GNAT Run-Time Library::
Using the GNU make Utility
* Overcoming Command Line Length Limits::
@end ifclear
-Finding Memory Problems
+Memory Management Issues
+* Some Useful Memory Pools::
+* The GNAT Debug Pool Facility::
@ifclear vms
* The gnatmem Tool::
@end ifclear
-* The GNAT Debug Pool Facility::
+
+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
* Example of gnatmem Usage::
@end ifclear
-The GNAT Debug Pool Facility
+Verifying properties using gnatcheck
+
+* Format of the Report File::
+* General gnatcheck Switches::
+* gnatcheck Rule Options::
+* Add the Results of Compiler Checks to gnatcheck Output::
-Creating Sample Bodies Using gnatstub
+ Sample Bodies Using gnatstub
* Running gnatstub::
* Switches for gnatstub::
@end ifset
@ifset vms
-Compatibility with DEC Ada
+Compatibility with HP Ada
* Ada 95 Compatibility::
* Differences in the Definition of Package System::
* The Package STANDARD::
* The Package SYSTEM::
* Tasking and Task-Related Features::
-* Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems::
* Pragmas and Pragma-Related Features::
* Library of Predefined Units::
* Bindings::
* Program Compilation and Library Management::
* Input-Output::
* Implementation Limits::
-* Tools::
+* Tools and Utilities::
Language-Related Features
* Address Clauses::
* Other Representation Clauses::
-Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems
+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::
* Summary of Run-Time Configurations::
* Specifying a Run-Time Library::
-* Choosing between Native and FSU Threads Libraries::
* Choosing the Scheduling Policy::
* Solaris-Specific Considerations::
-* IRIX-Specific Considerations::
* Linux-Specific Considerations::
+* AIX-Specific Considerations::
Example of Binder Output File
* Input Variables in Inline Assembler::
* Inlining Inline Assembler Code::
* Other Asm Functionality::
-* A Complete Example::
Compatibility and Porting Guide
* Compatibility with Ada 83::
* Implementation-dependent characteristics::
-* Compatibility with DEC Ada 83::
+@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 95 Systems::
* Representation Clauses::
+@ifset vms
+* Transitioning from Alpha to I64 OpenVMS::
+@end ifset
@ifset unw
Microsoft Windows Topics
* Building DLLs with GNAT::
* GNAT and Windows Resources::
* Debugging a DLL::
-* GNAT and COM/DCOM Objects::
+* Setting Stack Size from gnatlink::
+* Setting Heap Size from gnatlink::
@end ifset
-
* Index::
@end menu
@end ifnottex
@noindent
@ifset vms
-This guide describes the use of of GNAT, a full language compiler for the Ada
-95 programming language, implemented on HP OpenVMS Alpha platforms.
+This guide describes the use of @value{EDITION},
+a full language compiler for the Ada
+95 programming language, implemented on OpenVMS for HP's Alpha and
+Integrity server (I64) platforms.
@end ifset
@ifclear vms
-This guide describes the use of GNAT, a compiler and software development
+This guide describes the use of @value{EDITION},
+a compiler and software development
toolset for the full Ada 95 programming language.
@end ifclear
It describes the features of the compiler and tools, and details
how to use them to build Ada 95 applications.
+@ifset PROEDITION
+For ease of exposition, ``GNAT Pro'' will be referred to simply as
+``GNAT'' in the remainder of this document.
+@end ifset
+
@menu
* What This Guide Contains::
* What You Should Know before Reading This Guide::
@item
@ref{Compiling Using gcc}, describes how to compile
-Ada programs with @code{gcc}, the Ada compiler.
+Ada programs with @command{gcc}, the Ada compiler.
@item
@ref{Binding Using gnatbind}, describes how to
@item
@ref{Linking Using gnatlink},
-describes @code{gnatlink}, a
+describes @command{gnatlink}, a
program that provides for linking using the GNAT run-time library to
-construct a program. @code{gnatlink} can also incorporate foreign language
+construct a program. @command{gnatlink} can also incorporate foreign language
object units into the executable.
@item
-@ref{The GNAT Make Program gnatmake}, describes @code{gnatmake}, a
+@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.
@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.
+also describes the @command{gnatelim} tool and unused subprogram/data
+elimination.
@item
@ref{Renaming Files Using gnatchop}, describes
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}
@end ifclear
@item
-@ref{Finding Memory Problems}, describes
+@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
-@command{gnatmem}, a utility that monitors dynamic allocation and deallocation
-and helps detect ``memory leaks'', and
+It also describes @command{gnatmem}, a utility that monitors dynamic
+allocation and deallocation and helps detect ``memory leaks''.
@end ifclear
-the GNAT Debug Pool facility, which helps detect incorrect memory references.
+
+@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},
@ifset vms
@item
-@ref{Compatibility with DEC Ada}, details the compatibility of GNAT with
-DEC Ada 83 @footnote{``DEC Ada'' refers to the legacy product originally
+@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.
+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
@end ifset
@end itemize
-
@c *************************************************
@node What You Should Know before Reading This Guide
@c *************************************************
the ``@code{\}'' character should be used instead.
@end ifset
-
-
@c ****************************
@node Getting Started with GNAT
@chapter Getting Started with GNAT
@end enumerate
@noindent
-All three steps are most commonly handled by using the @code{gnatmake}
+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
@end smallexample
@noindent
-@code{gcc} is the command used to run the compiler. This compiler is
+@command{gcc} is the command used to run the compiler. This compiler is
capable of compiling programs in several languages, including Ada 95 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
that an Ada program is consistent.
To build an executable file,
use @code{gnatbind} to bind the program
-and @code{gnatlink} to link it. The
-argument to both @code{gnatbind} and @code{gnatlink} is the name of the
+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:
The result is an executable program called @file{hello}, which can be
run by entering:
-@c The following should be removed (BMB 2001-01-23)
-@c @smallexample
-@c $ ^./hello^$ RUN HELLO^
-@c @end smallexample
-
@smallexample
-$ hello
+$ ^hello^RUN HELLO^
@end smallexample
@noindent
@noindent
appear in response to this command.
-
@c ****************************************
@node Running a Program with Multiple Units
@section Running a Program with Multiple Units
@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 @code{gnatmake} tool. All you need to know in this case
+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:
@end smallexample
@noindent
-In the next section we discuss the advantages of using @code{gnatmake} in
+In the next section we discuss the advantages of using @command{gnatmake} in
more detail.
@c *****************************
@noindent
If you work on a program by compiling single components at a time using
-@code{gcc}, you typically keep track of the units you modify. In order to
+@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,
sure that the makefile is kept up-to-date manually, which is also an
error-prone process.
-The @code{gnatmake} utility takes care of these details automatically.
+The @command{gnatmake} utility takes care of these details automatically.
Invoke it using either one of the following forms:
@smallexample
@noindent
The argument is the name of the file containing the main program;
-you may omit the extension. @code{gnatmake}
+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 @code{gnatmake}, because working out by hand
+can be extremely helpful to use @command{gnatmake}, because working out by hand
what needs to be recompiled can be difficult.
-Note that @code{gnatmake}
+Note that @command{gnatmake}
takes into account all the Ada 95 rules that
establish dependencies among units. These include dependencies that result
from inlining subprogram bodies, and from
generic instantiation. Unlike some other
-Ada make tools, @code{gnatmake} does not rely on the dependencies that were
+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. @code{gnatmake} determines the exact set of
+be wrong when sources change. @command{gnatmake} determines the exact set of
dependencies from scratch each time it is run.
@ifset vms
* Simple Debugging with GPS::
@end menu
-
@node Building a New Program with GPS
@subsection Building a New Program with GPS
@noindent
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.)
+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.
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.
terminate this GPS session.
@end enumerate
-
-
@node Simple Debugging with GPS
@subsection Simple Debugging with GPS
@noindent
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
@end enumerate
@end enumerate
-
@node Introduction to Glide and GVD
@section Introduction to Glide and GVD
@cindex Glide
* 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::
@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
+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.
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
-@pxref{Handling of Configuration Pragmas}
+see @ref{Handling of Configuration Pragmas}.
@cindex @file{gnat.adc}
@ifclear vms
@end ifclear
@noindent
-@code{gnatmake} handles non-standard file names in the usual manner (the
+@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 gnatmake command, it may not be omitted.
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 @code{gnatmake}.
+recompilations is done automatically when one uses @command{gnatmake}.
@end itemize
@node The Ada Library Information Files
as well as the wide character encoding used during compilation).
@item
-List of arguments used in the @code{gcc} command for the compilation
+List of arguments used in the @command{gcc} command for the compilation
@item
Attributes of the unit, including configuration pragmas used, an indication
To build this example, first compile the foreign language files to
generate object files:
@smallexample
-gcc -c file1.c
-gcc -c file2.c
+^gcc -c file1.c^gcc -c FILE1.C^
+^gcc -c file2.c^gcc -c FILE2.C^
@end smallexample
@item
example's. First, compile the foreign language files to generate object
files:
@smallexample
-gcc -c main.c
+^gcc -c main.c^gcc -c main.c^
@end smallexample
@item
are unlikely to be able to be passed.
Note that in the case of GNAT running
-on a platform that supports DEC Ada 83, a higher degree of compatibility
+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
Ada compiler for further details on elaboration.
However, it is not possible to mix the tasking run time of GNAT and
-DEC Ada 83, All the tasking operations must either be entirely within
-GNAT compiled sections of the program, or entirely within DEC Ada 83
+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
Data will be passed according to the conventions described
in section B.3 of the Ada 95 Reference Manual.
+A note on interfacing to a C ``varargs'' function:
@findex C varargs function
-@cindex Intefacing to C varargs function
-@cindex varargs function intefacs
-@item 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
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 printfi.
+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 a particular call. However, this does not work on
+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 External
Equivalent to C.
+@ifclear vms
@findex C++
@cindex Interfacing to C++
@cindex Convention C++
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
@item Intrinsic
This applies to an intrinsic operation, as defined in the Ada 95
-Reference Manual. If a a pragma Import (Intrinsic) applies to a subprogram,
+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 can
@itemize @bullet
@item
-Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_-
-Arithmetic. The corresponding subprogram declaration must have
+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.
@findex Stdcall
@cindex Convention Stdcall
@item Stdcall
-This is relevant only to NT/Win95 implementations of GNAT,
-and specifies that the Stdcall calling sequence will be used, as defined
-by the NT API.
+This is relevant only to Windows XP/2000/NT/95 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 Stdcall.
+This is equivalent to @code{Stdcall}.
@findex Win32
@cindex Convention Win32
@item Win32
-This is equivalent to Stdcall.
+This is equivalent to @code{Stdcall}.
@end ifset
@findex Stubbed
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 & C++ Programs
+@section Building Mixed Ada and C++ Programs
@noindent
A programmer inexperienced with mixed-language development may find that
@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
-the path to libgcc explicitly, since some libraries needed by GNAT are
-located in this directory:
+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-libgcc-file-name`
+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
class A : public Origin @{
public:
void method1 (void);
- virtual void method2 (int v);
+ void method2 (int v);
A();
int a_value;
@};
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 to be useful to Ada programmers who have
-previously used an Ada compiler implementing the traditional Ada library
-model, as described in the Ada 95 Language Reference Manual. If you
-have not used such a system, please go on to the next section.
+This section is intended for Ada programmers who have
+used an Ada compiler implementing the traditional Ada library
+model, as described in the Ada 95 Language Reference Manual.
@cindex GNAT library
-In GNAT, there is no @dfn{library} in the normal sense. Instead, the set of
+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.
GNAT uses the current directory for temporary files.
@end ifset
-
@c *************************
@node Compiling Using gcc
-@chapter Compiling Using @code{gcc}
+@chapter Compiling Using @command{gcc}
@noindent
-This chapter discusses how to compile Ada programs using the @code{gcc}
+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
@noindent
The first step in creating an executable program is to compile the units
-of the program using the @code{gcc} command. You must compile the
+of the program using the @command{gcc} command. You must compile the
following files:
@itemize @bullet
@file{.ads} for a spec or @file{.adb} for a body).
@ifclear vms
You specify the
-@option{-c} switch to tell @code{gcc} to compile, but not link, the file.
+@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
containing the directory information.
@findex gnat1
-@code{gcc} is actually a driver program that looks at the extensions of
+@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 @code{gcc} driver also calls the assembler and any other
+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 @code{gcc}
-command. This causes @code{gcc} to call the appropriate compiler for
+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:
@end ifclear
@node Switches for gcc
-@section Switches for @code{gcc}
+@section Switches for @command{gcc}
@noindent
-The @code{gcc} command accepts switches that control the
+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::
-* Run-Time Checks::
-* Stack Overflow Checking::
* Validity Checking::
* Style Checking::
+* Run-Time Checks::
* Using gcc for Syntax Checking::
* Using gcc for Semantic Checking::
-* Compiling Ada 83 Programs::
+* Compiling Different Versions of Ada::
* Character Set Control::
* File Naming Control::
* Subprogram Inlining Control::
* Exception Handling Control::
* Units to Sources Mapping Files::
* Integrated Preprocessing::
+* Code Generation Control::
@ifset vms
* Return Codes::
@end ifset
@table @option
@c !sort!
@ifclear vms
-@cindex @option{-b} (@code{gcc})
+@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} (@code{gcc})
+@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. See the
-@code{gcc} manual page for further details. You would normally use the
+@command{gcc} manual page for further details. You would normally use the
@option{-b} or @option{-V} switch instead.
@item -c
-@cindex @option{-c} (@code{gcc})
+@cindex @option{-c} (@command{gcc})
Compile. Always use this switch when compiling Ada programs.
-Note: for some other languages when using @code{gcc}, notably in
+Note: for some other languages when using @command{gcc}, notably in
the case of C and C++, it is possible to use
-use @code{gcc} without a @option{-c} switch to
+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 @code{gcc} cannot be used to run the GNAT binder.
+and @command{gcc} cannot be used to run the GNAT binder.
@end ifclear
@item -fno-inline
-@cindex @option{-fno-inline} (@code{gcc})
+@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
See also @option{-gnatn} and @option{-gnatN}.
@item -fno-strict-aliasing
-@cindex @option{-fno-strict-aliasing} (@code{gcc})
+@cindex @option{-fno-strict-aliasing} (@command{gcc})
Causes the compiler to avoid assumptions regarding non-aliasing
-of objects of different types. See section
-@pxref{Optimization and Strict Aliasing} for details.
+of objects of different types. See
+@ref{Optimization and Strict Aliasing} for details.
@item -fstack-check
-@cindex @option{-fstack-check} (@code{gcc})
+@cindex @option{-fstack-check} (@command{gcc})
Activates stack checking.
-See @ref{Stack Overflow Checking} for details of the use of this option.
+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[=su]
+@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^} (@code{gcc})
+@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} (@code{gcc})
+@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} (@code{gcc})
+@cindex @option{-gnata} (@command{gcc})
Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
-activated.
+activated. Note that these pragmas can also be controlled using the
+configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
@item -gnatA
-@cindex @option{-gnatA} (@code{gcc})
+@cindex @option{-gnatA} (@command{gcc})
Avoid processing @file{gnat.adc}. If a gnat.adc file is present,
it will be ignored.
@item -gnatb
-@cindex @option{-gnatb} (@code{gcc})
+@cindex @option{-gnatb} (@command{gcc})
Generate brief messages to @file{stderr} even if verbose mode set.
@item -gnatc
-@cindex @option{-gnatc} (@code{gcc})
+@cindex @option{-gnatc} (@command{gcc})
Check syntax and semantics only (no code generation attempted).
@item -gnatd
-@cindex @option{-gnatd} (@code{gcc})
+@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
users guide.
@item -gnatD
-@cindex @option{-gnatD} (@code{gcc})
+@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} (@code{gcc})
+@cindex @option{-gnatec} (@command{gcc})
Specify a configuration pragma file
@ifclear vms
(the equal sign is optional)
@end ifclear
-(see @ref{The Configuration Pragmas Files}).
+(@pxref{The Configuration Pragmas Files}).
@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
-@cindex @option{-gnateD} (@code{gcc})
+@cindex @option{-gnateD} (@command{gcc})
Defines a symbol, associated with value, for preprocessing.
-(see @ref{Integrated Preprocessing})
+(@pxref{Integrated Preprocessing}).
@item -gnatef
-@cindex @option{-gnatef} (@code{gcc})
+@cindex @option{-gnatef} (@command{gcc})
Display full source path name in brief error messages.
@item -gnatem=@var{path}
-@cindex @option{-gnatem} (@code{gcc})
+@cindex @option{-gnatem} (@command{gcc})
Specify a mapping file
@ifclear vms
(the equal sign is optional)
@end ifclear
-(see @ref{Units to Sources Mapping Files}).
+(@pxref{Units to Sources Mapping Files}).
@item -gnatep=@var{file}
-@cindex @option{-gnatep} (@code{gcc})
+@cindex @option{-gnatep} (@command{gcc})
Specify a preprocessing data file
@ifclear vms
(the equal sign is optional)
@end ifclear
-(see @ref{Integrated Preprocessing}).
+(@pxref{Integrated Preprocessing}).
@item -gnatE
-@cindex @option{-gnatE} (@code{gcc})
+@cindex @option{-gnatE} (@command{gcc})
Full dynamic elaboration checks.
@item -gnatf
-@cindex @option{-gnatf} (@code{gcc})
+@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} (@code{gcc})
+@cindex @option{-gnatF} (@command{gcc})
Externals names are folded to all uppercase.
@item -gnatg
-@cindex @option{-gnatg} (@code{gcc})
+@cindex @option{-gnatg} (@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.
as errors.
@item -gnatG
-@cindex @option{-gnatG} (@code{gcc})
+@cindex @option{-gnatG} (@command{gcc})
List generated expanded code in source form.
@item ^-gnath^/HELP^
-@cindex @option{^-gnath^/HELP^} (@code{gcc})
+@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^} (@code{gcc})
+@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
@ifset vms
For details of the possible selections for @var{c},
-see @xref{Character Set Control}.
+see @ref{Character Set Control}.
@end ifset
@item -gnatk=@var{n}
-@cindex @option{-gnatk} (@code{gcc})
+@cindex @option{-gnatk} (@command{gcc})
Limit file names to @var{n} (1-999) characters ^(@code{k} = krunch)^^.
@item -gnatl
-@cindex @option{-gnatl} (@code{gcc})
+@cindex @option{-gnatl} (@command{gcc})
Output full source listing with embedded error messages.
-@item -gnatL
-@cindex @option{-gnatL} (@code{gcc})
-Use the longjmp/setjmp method for exception handling
-
@item -gnatm=@var{n}
-@cindex @option{-gnatm} (@code{gcc})
+@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.
+limit is exceeded. The equal sign here is optional.
@item -gnatn
-@cindex @option{-gnatn} (@code{gcc})
+@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} (@code{gcc})
+@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
catches that cannot be dealt with in the front-end.
@item -gnato
-@cindex @option{-gnato} (@code{gcc})
+@cindex @option{-gnato} (@command{gcc})
Enable numeric overflow checking (which is not normally enabled by
default). Not 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} (@code{gcc})
+@cindex @option{-gnatp} (@command{gcc})
Suppress all checks.
@item -gnatP
-@cindex @option{-gnatP} (@code{gcc})
+@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.
See the description of pragma Polling in the GNAT Reference Manual for
full details.
@item -gnatq
-@cindex @option{-gnatq} (@code{gcc})
+@cindex @option{-gnatq} (@command{gcc})
Don't quit; try semantics, even if parse errors.
@item -gnatQ
-@cindex @option{-gnatQ} (@code{gcc})
+@cindex @option{-gnatQ} (@command{gcc})
Don't quit; generate @file{ALI} and tree files even if illegalities.
@item ^-gnatR[0/1/2/3[s]]^/REPRESENTATION_INFO^
-@cindex @option{-gnatR} (@code{gcc})
+@cindex @option{-gnatR} (@command{gcc})
Output representation information for declared types and objects.
@item -gnats
-@cindex @option{-gnats} (@code{gcc})
+@cindex @option{-gnats} (@command{gcc})
Syntax check only.
@item -gnatS
-@cindex @option{-gnatS} (@code{gcc})
+@cindex @option{-gnatS} (@command{gcc})
Print package Standard.
@item -gnatt
-@cindex @option{-gnatt} (@code{gcc})
+@cindex @option{-gnatt} (@command{gcc})
Generate tree output file.
@item ^-gnatT^/TABLE_MULTIPLIER=^@var{nnn}
-@cindex @option{^-gnatT^/TABLE_MULTIPLIER^} (@code{gcc})
+@cindex @option{^-gnatT^/TABLE_MULTIPLIER^} (@command{gcc})
All compiler tables start at @var{nnn} times usual starting size.
@item -gnatu
-@cindex @option{-gnatu} (@code{gcc})
+@cindex @option{-gnatu} (@command{gcc})
List units for this compilation.
@item -gnatU
-@cindex @option{-gnatU} (@code{gcc})
+@cindex @option{-gnatU} (@command{gcc})
Tag all error messages with the unique string ``error:''
@item -gnatv
-@cindex @option{-gnatv} (@code{gcc})
+@cindex @option{-gnatv} (@command{gcc})
Verbose mode. Full error output with source lines to @file{stdout}.
@item -gnatV
-@cindex @option{-gnatV} (@code{gcc})
+@cindex @option{-gnatV} (@command{gcc})
Control level of validity checking. See separate section describing
this feature.
@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}[,...])^
-@cindex @option{^-gnatw^/WARNINGS^} (@code{gcc})
+@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. (see @ref{Warning Message Control})
+are enabled or disabled (@pxref{Warning Message Control}).
@item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e}
-@cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@code{gcc})
+@cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc})
Wide character encoding method
@ifclear vms
(@var{e}=n/h/u/s/e/8).
@end ifset
@item -gnatx
-@cindex @option{-gnatx} (@code{gcc})
+@cindex @option{-gnatx} (@command{gcc})
Suppress generation of cross-reference information.
@item ^-gnaty^/STYLE_CHECKS=(option,option..)^
-@cindex @option{^-gnaty^/STYLE_CHECKS^} (@code{gcc})
-Enable built-in style checks. (see @ref{Style Checking})
+@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^} (@code{gcc})
+@cindex @option{^-gnatz^/DISTRIBUTION_STUBS^} (@command{gcc})
Distribution stub generation and compilation
@ifclear vms
(@var{m}=r/c for receiver/caller stubs).
to be generated and compiled).
@end ifset
-@item -gnatZ
-Use the zero cost method for exception handling
-
@item ^-I^/SEARCH=^@var{dir}
-@cindex @option{^-I^/SEARCH^} (@code{gcc})
+@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^} (@code{gcc})
+@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
in order to compile large and/or nested @code{case} statements.
@item -o @var{file}
-@cindex @option{-o} (@code{gcc})
-This switch is used in @code{gcc} to redirect the generated object 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.
@ifclear vms
@item -O[@var{n}]
-@cindex @option{-O} (@code{gcc})
+@cindex @option{-O} (@command{gcc})
@var{n} controls the optimization level.
@table @asis
@item n = 1
Normal optimization, the default if you specify @option{-O} without
-an operand.
+an operand. A good compromise between code quality and compilation
+time.
@item n = 2
-Extensive optimization
+Extensive optimization, may improve execution time, possibly at the cost of
+substantially increased compilation time.
-@item n = 3
-Extensive optimization with automatic inlining of subprograms not
-specified by pragma @code{Inline}. This applies only to
-inlining within a unit. For details on control of inlining
-see @xref{Subprogram Inlining Control}.
@end table
@end ifclear
@item DEVELOPMENT
Same as @code{SOME}.
-@item INLINING
-Full optimization, and also attempt automatic inlining of small
-subprograms within a unit even when pragma @code{Inline}
-is not specified (@pxref{Inlining of Subprograms}).
-
@item UNROLL_LOOPS
Try to unroll loops. This keyword may be specified together with
any keyword above other than @code{NONE}. Loop unrolling
@ifclear vms
@item -pass-exit-codes
-@cindex @option{-pass-exit-codes} (@code{gcc})
+@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} (@code{gcc})
+@cindex @option{--RTS} (@command{gcc})
Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}).
+equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
@item ^-S^/ASM^
-@cindex @option{^-S^/ASM^} (@code{gcc})
+@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^} (@code{gcc})
-Show commands generated by the @code{gcc} driver. Normally used only for
+@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} (@code{gcc})
-Execute @var{ver} version of the compiler. This is the @code{gcc}
+@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
@end smallexample
@end ifclear
-
-@c NEED TO CHECK THIS FOR VMS
-
@noindent
The following restrictions apply to the combination of switches
in this manner:
@end ifclear
@end itemize
-
@node Output and Error Message Control
@subsection Output and Error Message Control
@findex stderr
@table @option
@c !sort!
@item -gnatv
-@cindex @option{-gnatv} (@code{gcc})
+@cindex @option{-gnatv} (@command{gcc})
@findex stdout
@ifclear vms
The v stands for verbose.
used the only source lines output are those with errors.
@item -gnatl
-@cindex @option{-gnatl} (@code{gcc})
+@cindex @option{-gnatl} (@command{gcc})
@ifclear vms
The @code{l} stands for list.
@end ifclear
warning messages generated.
@item -gnatU
-@cindex @option{-gnatU} (@code{gcc})
+@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} (@code{gcc})
+@cindex @option{-gnatb} (@command{gcc})
@ifclear vms
The @code{b} stands for brief.
@end ifclear
format message or full listing (which as usual is written to
@file{stdout} (the standard output file).
-@item -gnatm^^=^@var{n}
-@cindex @option{-gnatm} (@code{gcc})
+@item -gnatm=@var{n}
+@cindex @option{-gnatm} (@command{gcc})
@ifclear vms
The @code{m} stands for maximum.
@end ifclear
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} (@code{gcc})
+@cindex @option{-gnatf} (@command{gcc})
@cindex Error messages, suppressing
@ifclear vms
The @code{f} stands for full.
Additional details on incorrect parameters
@end itemize
-
@item -gnatq
-@cindex @option{-gnatq} (@code{gcc})
+@cindex @option{-gnatq} (@command{gcc})
@ifclear vms
The @code{q} stands for quit (really ``don't quit'').
@end ifclear
internal fatal error when given a syntactically invalid tree.
@item -gnatQ
-@cindex @option{-gnatQ} (@code{gcc})
+@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
analysis.
When @option{-gnatQ} is used and the generated @file{ALI} file is marked as
-being in error, @code{gnatmake} will attempt to recompile the source when it
+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,
@end table
-
@node Warning Message Control
@subsection Warning Message Control
@cindex Warning messages
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
@item
Attempt to return local value by reference
-
@item
Premature instantiation of a generic body
@item
Accidental hiding of name by child unit
-
@item
Access before elaboration detected at compile time
@c !sort!
@item -gnatwa
@emph{Activate all optional errors.}
-@cindex @option{-gnatwa} (@code{gcc})
+@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
@item -gnatwA
@emph{Suppress all optional errors.}
-@cindex @option{-gnatwA} (@code{gcc})
+@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 -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 -gnatwc
@emph{Activate warnings on conditionals.}
-@cindex @option{-gnatwc} (@code{gcc})
+@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
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 can also be turned on using @option{-gnatwa}.
@item -gnatwC
@emph{Suppress warnings on conditionals.}
-@cindex @option{-gnatwC} (@code{gcc})
+@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 -gnatwd
@emph{Activate warnings on implicit dereferencing.}
-@cindex @option{-gnatwd} (@code{gcc})
+@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
@item -gnatwD
@emph{Suppress warnings on implicit dereferencing.}
-@cindex @option{-gnatwD} (@code{gcc})
+@cindex @option{-gnatwD} (@command{gcc})
@cindex Implicit dereferencing
@cindex Dereferencing, implicit
This switch suppresses warnings for implicit dereferences in
@item -gnatwe
@emph{Treat warnings as errors.}
-@cindex @option{-gnatwe} (@code{gcc})
+@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
@item -gnatwf
@emph{Activate warnings on unreferenced formals.}
-@cindex @option{-gnatwf} (@code{gcc})
+@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
@item -gnatwF
@emph{Suppress warnings on unreferenced formals.}
-@cindex @option{-gnatwF} (@code{gcc})
+@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
@item -gnatwg
@emph{Activate warnings on unrecognized pragmas.}
-@cindex @option{-gnatwg} (@code{gcc})
+@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
@item -gnatwG
@emph{Suppress warnings on unrecognized pragmas.}
-@cindex @option{-gnatwG} (@code{gcc})
+@cindex @option{-gnatwG} (@command{gcc})
This switch suppresses warnings for unrecognized pragmas.
@item -gnatwh
@emph{Activate warnings on hiding.}
-@cindex @option{-gnatwh} (@code{gcc})
+@cindex @option{-gnatwh} (@command{gcc})
@cindex Hiding of Declarations
This switch activates warnings on hiding declarations.
A declaration is considered hiding
@item -gnatwH
@emph{Suppress warnings on hiding.}
-@cindex @option{-gnatwH} (@code{gcc})
+@cindex @option{-gnatwH} (@command{gcc})
This switch suppresses warnings on hiding declarations.
@item -gnatwi
@emph{Activate warnings on implementation units.}
-@cindex @option{-gnatwi} (@code{gcc})
+@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},
@item -gnatwI
@emph{Disable warnings on implementation units.}
-@cindex @option{-gnatwI} (@code{gcc})
+@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} (@code{gcc})
+@cindex @option{-gnatwj} (@command{gcc})
@cindex Features, obsolescent
@cindex Obsolescent features
If this warning option is activated, then warnings are generated for
would generate many annoying positive warnings. The default is that
such warnings are not generated.
+In addition to the above cases, warnings are also generated for
+GNAT features that have been provided in past versions but which
+have been superseded (typically by features in the new Ada standard).
+For example, @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} (@code{gcc})
+@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} (@code{gcc})
+@cindex @option{-gnatwk} (@command{gcc})
This switch activates warnings for variables that are initialized but
never modified, and then could be declared constants.
@item -gnatwK
@emph{Suppress warnings on variables that could be constants.}
-@cindex @option{-gnatwK} (@code{gcc})
+@cindex @option{-gnatwK} (@command{gcc})
This switch disables warnings on variables that could be declared constants.
@item -gnatwl
@emph{Activate warnings for missing elaboration pragmas.}
-@cindex @option{-gnatwl} (@code{gcc})
+@cindex @option{-gnatwl} (@command{gcc})
@cindex Elaboration, warnings
This switch activates warnings on missing
-@code{pragma Elaborate_All} statements.
+@code{Elaborate_All} and @code{Elaborate} pragmas.
See the section in this guide on elaboration checking for details on
-when such pragma should be used. Warnings are also generated if you
+when such pragmas should be used. 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.
@item -gnatwL
@emph{Suppress warnings for missing elaboration pragmas.}
-@cindex @option{-gnatwL} (@code{gcc})
-This switch suppresses warnings on missing pragma Elaborate_All statements.
+@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 pragma should be used.
+when such pragmas should be used.
@item -gnatwm
@emph{Activate warnings on modified but unreferenced variables.}
-@cindex @option{-gnatwm} (@code{gcc})
+@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
@item -gnatwM
@emph{Disable warnings on modified but unreferenced variables.}
-@cindex @option{-gnatwM} (@code{gcc})
+@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} (@code{gcc})
+@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
@item -gnatwo
@emph{Activate warnings on address clause overlays.}
-@cindex @option{-gnatwo} (@code{gcc})
+@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
@item -gnatwO
@emph{Suppress warnings on address clause overlays.}
-@cindex @option{-gnatwO} (@code{gcc})
+@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 -gnatwp
@emph{Activate warnings on ineffective pragma Inlines.}
-@cindex @option{-gnatwp} (@code{gcc})
+@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
@item -gnatwP
@emph{Suppress warnings on ineffective pragma Inlines.}
-@cindex @option{-gnatwP} (@code{gcc})
+@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 -gnatwr
@emph{Activate warnings on redundant constructs.}
-@cindex @option{-gnatwr} (@code{gcc})
+@cindex @option{-gnatwr} (@command{gcc})
This switch activates warnings for redundant constructs. The following
is the current list of constructs regarded as redundant:
This warning can also be turned on using @option{-gnatwa}.
Use of the operator abs on an operand that is known at compile time
to be non-negative
@item
-Use of an unnecessary extra level of parentheses (C-style) around conditions
-in @code{if} statements, @code{while} statements and @code{exit} statements.
-@item
Comparison of boolean expressions to an explicit True value.
@end itemize
@item -gnatwR
@emph{Suppress warnings on redundant constructs.}
-@cindex @option{-gnatwR} (@code{gcc})
+@cindex @option{-gnatwR} (@command{gcc})
This switch suppresses warnings for redundant constructs.
@item -gnatws
@emph{Suppress all warnings.}
-@cindex @option{-gnatws} (@code{gcc})
+@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 @code{gcc} back 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 -gnatwu
@emph{Activate warnings on unused entities.}
-@cindex @option{-gnatwu} (@code{gcc})
+@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
@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 is includes the effect of @option{-gnatwf}).
+(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} (@code{gcc})
+@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} (@code{gcc})
+@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
@item -gnatwV
@emph{Suppress warnings on unassigned variables.}
-@cindex @option{-gnatwV} (@code{gcc})
+@cindex @option{-gnatwV} (@command{gcc})
This switch suppresses warnings for access to variables which
may not be properly initialized.
+@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.
+
+@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 -gnatwx
@emph{Activate warnings on Export/Import pragmas.}
-@cindex @option{-gnatwx} (@code{gcc})
+@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
@item -gnatwX
@emph{Suppress warnings on Export/Import pragmas.}
-@cindex @option{-gnatwX} (@code{gcc})
+@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
@item -gnatwz
@emph{Activate warnings on unchecked conversions.}
-@cindex @option{-gnatwz} (@code{gcc})
+@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
@item -gnatwZ
@emph{Suppress warnings on unchecked conversions.}
-@cindex @option{-gnatwZ} (@code{gcc})
+@cindex @option{-gnatwZ} (@command{gcc})
This switch suppresses warnings for unchecked conversions
where the types are known at compile time to have different
sizes.
front end of the compiler. In some cases, the @option{^gcc^GCC^} back end
can provide additional warnings. One such useful warning is provided by
@option{^-Wuninitialized^WARNINGS=UNINITIALIZED^}. This must be used in
-conjunction with tunrning on optimization mode. This causes the flow
+conjunction with turning on optimization mode. This causes the flow
analysis circuits of the back end optimizer to output additional
warnings about uninitialized variables.
@item ^-w^/NO_BACK_END_WARNINGS^
@cindex @option{-w}
-This switch suppresses warnings from the @option{^gcc^GCC^} back end. It may
-be used in conjunction with @option{-gnatws} to ensure that all warnings
-are suppressed during the entire compilation process.
+This switch suppresses warnings from the @option{^gcc^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 suppress them.
+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
@end table
-
@node Debugging and Assertion Control
@subsection Debugging and Assertion Control
@table @option
@item -gnata
-@cindex @option{-gnata} (@code{gcc})
+@cindex @option{-gnata} (@command{gcc})
@findex Assert
@findex Debug
@cindex Assertions
to the default checks described above.
@end ifset
-
@table @option
@c !sort!
@item -gnatVa
@emph{All validity checks.}
-@cindex @option{-gnatVa} (@code{gcc})
+@cindex @option{-gnatVa} (@command{gcc})
All validity checks are turned on.
@ifclear vms
That is, @option{-gnatVa} is
@item -gnatVc
@emph{Validity checks for copies.}
-@cindex @option{-gnatVc} (@code{gcc})
+@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} (@code{gcc})
+@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
@item -gnatVf
@emph{Validity checks for floating-point values.}
-@cindex @option{-gnatVf} (@code{gcc})
+@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 NaN's and infinities are considered invalid,
@item -gnatVi
@emph{Validity checks for @code{in} mode parameters}
-@cindex @option{-gnatVi} (@code{gcc})
+@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} (@code{gcc})
+@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.
@item -gnatVn
@emph{No validity checks.}
-@cindex @option{-gnatVn} (@code{gcc})
+@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
@item -gnatVo
@emph{Validity checks for operator and attribute operands.}
-@cindex @option{-gnatVo} (@code{gcc})
+@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.
+on individual component values for composite comparisons, and on the
+expressions in type conversions and qualified expressions.
@item -gnatVp
@emph{Validity checks for parameters.}
-@cindex @option{-gnatVp} (@code{gcc})
+@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
@item -gnatVr
@emph{Validity checks for function returns.}
-@cindex @option{-gnatVr} (@code{gcc})
+@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} (@code{gcc})
+@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} (@code{gcc})
+@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.
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,...)^} switch
-@cindex @option{-gnaty} (@code{gcc})
+@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
signs are used to form the top and bottom of the box.
@item
-If a comment starts and ends with ``@code{--}'' is permitted as long as at
+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:
@end smallexample
@end itemize
+@item ^d^DOS_LINE_ENDINGS^
+@emph{Check no DOS line terminators present.}
+If the ^letter d^word DOS_LINE_ENDINGS^ appears in the string after
+@option{-gnaty} then 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.}
If the ^letter e^word END^ appears in the string after @option{-gnaty} then
@item ^f^VTABS^
@emph{No form feeds or vertical tabs.}
If the ^letter f^word VTABS^ appears in the string after @option{-gnaty} then
-neither form feeds nor vertical tab characters are not permitted
+neither form feeds nor vertical tab characters are permitted
in the source text.
@item ^h^HTABS^
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}
+If the ^letter I (upper case)^word IN_MODE^ appears in the string
+after @option{-gnaty} then 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.}
If the ^letter k^word KEYWORD^ appears in the string after @option{-gnaty} then
@end cartouche
@end smallexample
+@item ^Lnnn^MAX_NESTING=nnn^
+@emph{Set maximum nesting level}
+If the sequence ^Lnnn^MAX_NESTING=nnn^, where nnn is a decimal number in
+the range 0-999, appears in the string after @option{-gnaty} then the
+maximum level of nesting of constructs (including subprograms, loops,
+blocks, packages, and conditionals) may not exceed the given value. A
+value of zero disconnects this style check.
+
@item ^m^LINE_LENGTH^
@emph{Check maximum line length.}
If the ^letter m^word LINE_LENGTH^ appears in the string after @option{-gnaty}
then 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 raw
+treatment of 80 character lines. Note that this count is of
characters in the source text. This means that a tab character counts
-as one character in this count and a wide character sequence counts as
-several characters (however many are needed in the encoding).
+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.}
If the sequence ^M^MAX_LENGTH=^nnn, where nnn is a decimal number, appears in
the string after @option{-gnaty} then the length of lines must not exceed the
-given value.
+given value. The maximum value that can be specified is 32767.
@item ^n^STANDARD_CASING^
@emph{Check casing of entities in Standard.}
A vertical bar must be surrounded by spaces.
@end itemize
+@item ^u^UNNECESSARY_BLANK_LINES^
+@emph{Check unnecessary blank lines.}
+Check for unnecessary blank lines. 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.}
+Check for the use of an unnecessary extra level of parentheses (C-style)
+around conditions in @code{if} statements, @code{while} statements and
+@code{exit} statements.
+
+@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,
as meeting either a requirement for a following space, or as meeting
a requirement for no following space.
-@end table
-
@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
@ifclear vms
@option{-gnaty} on its own (that is not
followed by any letters or digits),
-is equivalent to @code{gnaty3abcefhiklmprst}, that is all checking
-options enabled with the exception of -gnatyo,
+is equivalent to @code{gnaty3abcefhiklmnprst}, that is all checking
+options enabled with the exception of @option{-gnatyo},
+@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
@end ifclear
@ifset vms
/STYLE_CHECKS=ALL_BUILTIN enables all checking options with
-the exception of ORDERED_SUBPROGRAMS,
+the exception of ORDERED_SUBPROGRAMS, UNNECESSARY_BLANK_LINES,
+XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
@end ifset
-with an indentation level of 3. This is the standard
+an indentation level of 3 is set. This is similar to the standard
checking option that is used for the GNAT sources.
The switch
@cindex Access before elaboration
@cindex Checks, division by zero
@cindex Checks, access before elaboration
+@cindex Checks, stack overflow checking
@noindent
If you compile with the default options, GNAT will insert many run-time
checks into the compiled code, including code that performs range
checking against constraints, but not arithmetic overflow checking for
-integer operations (including division by zero) or checks for access
-before elaboration on subprogram calls. All other run-time checks, as
-required by the Ada 95 Reference Manual, are generated by default.
-The following @code{gcc} switches refine this default behavior:
+integer operations (including division by zero), checks for access
+before elaboration on subprogram calls, or stack overflow checking. All
+other run-time checks, as required by the Ada 95 Reference Manual, are
+generated by default. The following @command{gcc} switches refine this
+default behavior:
@table @option
@c !sort!
@item -gnatp
-@cindex @option{-gnatp} (@code{gcc})
+@cindex @option{-gnatp} (@command{gcc})
@cindex Suppressing checks
@cindex Checks, suppressing
@findex Suppress
program bugs.
@item -gnato
-@cindex @option{-gnato} (@code{gcc})
+@cindex @option{-gnato} (@command{gcc})
@cindex Overflow checks
@cindex Check, overflow
Enables overflow checking for integer operations.
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 @code{gnatmake} or
-@code{gcc} command.
+explicitly use the -gnato switch either on the @command{gnatmake} or
+@command{gcc} command.
@item -gnatE
-@cindex @option{-gnatE} (@code{gcc})
+@cindex @option{-gnatE} (@command{gcc})
@cindex Elaboration checks
@cindex Check, elaboration
Enables dynamic checks for access-before-elaboration
on subprogram calls and generic instantiations.
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
checks) or @code{Unsuppress} (to add back suppressed checks) pragmas in
the program source.
-@node Stack Overflow Checking
-@subsection Stack Overflow Checking
-@cindex Stack Overflow Checking
-@cindex -fstack-check
-
-@noindent
-For most operating systems, @code{gcc} does not perform stack overflow
-checking by default. This means that if the main environment task or
-some other task exceeds the available stack space, then unpredictable
-behavior will occur.
-
-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) do 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 always controlled by the size
-given in an applicable @code{Storage_Size} pragma (or is set to
-the default size if no pragma is used.
-
-For the environment task, the stack size depends on
-system defaults and is unknown to the compiler. The stack
-may even dynamically grow on some systems, precluding the
-normal Ada semantics for stack overflow. In the worst case,
-unbounded stack usage, causes unbounded stack expansion
-resulting in the system running out of virtual memory.
-
-The stack checking may still work correctly if a fixed
-size stack is allocated, but this cannot be guaranteed.
-To ensure that a clean exception is signalled for stack
-overflow, set the environment variable
-@code{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.
-
-
@node Using gcc for Syntax Checking
-@subsection Using @code{gcc} for Syntax Checking
+@subsection Using @command{gcc} for Syntax Checking
@table @option
@item -gnats
-@cindex @option{-gnats} (@code{gcc})
+@cindex @option{-gnats} (@command{gcc})
@ifclear vms
@noindent
(@pxref{Renaming Files Using gnatchop}).
@end table
-
@node Using gcc for Semantic Checking
-@subsection Using @code{gcc} for Semantic Checking
+@subsection Using @command{gcc} for Semantic Checking
@table @option
@item -gnatc
-@cindex @option{-gnatc} (@code{gcc})
+@cindex @option{-gnatc} (@command{gcc})
@ifclear vms
@noindent
and specifications where a separate body is present).
@end table
-@node Compiling Ada 83 Programs
-@subsection Compiling Ada 83 Programs
+@node Compiling Different Versions of Ada
+@subsection Compiling Different Versions of Ada
@table @option
-@cindex Ada 83 compatibility
-@item -gnat83
-@cindex @option{-gnat83} (@code{gcc})
+@cindex Compatibility with Ada 83
+@cindex Ada 83 mode
+@cindex Ada 95 mode
+@cindex Ada 2005 mode
+
+GNAT is primarily an Ada 95 compiler, but the switches described in
+this section allow operation in Ada 83 compatibility mode, and also
+allow the use of a preliminary implementation of many of the expected
+new features in Ada 2005, the forthcoming new version of the standard.
+
+@item -gnat83 (Ada 83 Compatibility Mode)
+@cindex @option{-gnat83} (@command{gcc})
@cindex ACVC, Ada 83 tests
@noindent
program.
For further information, please refer to @ref{Compatibility and Porting Guide}.
+@item -gnat95 (Ada 95 mode)
+@cindex @option{-gnat95} (@command{gcc})
+
+@noindent
+GNAT is primarily an Ada 95 compiler, and all current releases of GNAT Pro
+compile in Ada 95 mode by default. Typically, Ada 95 is sufficiently upwards
+compatible with Ada 83, that legacy Ada 83 programs may be compiled using
+this default Ada95 mode without problems (see section above describing the
+use of @option{-gnat83} to run in Ada 83 mode).
+
+In Ada 95 mode, the use of Ada 2005 features will in general cause error
+messages or warnings. Some specialized releases of GNAT (notably the GAP
+academic version) operate in Ada 2005 mode by default (see section below
+describing the use of @option{-gnat05} to run in Ada 2005 mode). For such
+versions the @option{-gnat95} switch may be used to enforce Ada 95 mode.
+This option 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})
+
+@noindent
+Although GNAT is primarily an Ada 95 compiler, it can be set to operate
+in Ada 2005 mode using this option. Although the new standard has not
+yet been issued (as of early 2005), many features have been discussed and
+approved in ``Ada Issues'' (AI's). For the text of these AI's, see
+@url{www.ada-auth.org/cgi-bin/cvsweb.cgi/AIs}. Included with GNAT
+releases is a file @file{features-ada0y} that describes the current set
+of implemented Ada 2005 features.
+
+If these features are used in Ada 95 mode (which is the normal default),
+then error messages or warnings may be
+generated, reflecting the fact that these new features are otherwise
+unauthorized extensions to Ada 95. The use of the @option{-gnat05}
+switch (or an equivalent pragma) causes these messages to be suppressed.
+
+Note that some specialized releases of GNAT (notably the GAP academic
+version) have Ada 2005 mode on by default, and in such environments,
+the Ada 2005 features can be used freely without the use of switches.
+
@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^} (@code{gcc})
+@cindex @option{^-gnati^/IDENTIFIER_CHARACTER_SET^} (@command{gcc})
@noindent
Normally GNAT recognizes the Latin-1 character set in source program
implementation of these character sets.
@item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e}
-@cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@code{gcc})
+@cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@command{gcc})
Specify the method of encoding for wide characters.
@var{e} is one of the following:
@item ^b^BRACKETS^
Brackets encoding only (default value)
@end table
-For full details on the these encoding
-methods see @xref{Wide Character Encodings}.
+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 @code{UTF-8} encodings will be recognized. The units that are
@table @option
@item ^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{n}
-@cindex @option{-gnatk} (@code{gcc})
+@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
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} (@code{gcc})
+@cindex @option{-gnatn} (@command{gcc})
@ifclear vms
The @code{n} here is intended to suggest the first syllable of the
word ``inline''.
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 @xref{Inlining of Subprograms}.
+see @ref{Inlining of Subprograms}.
@item -gnatN
-@cindex @option{-gnatN} (@code{gcc})
+@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.
@table @option
@item -gnatt
-@cindex @option{-gnatt} (@code{gcc})
+@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
not have to specify this switch in normal operation.
@item -gnatu
-@cindex @option{-gnatu} (@code{gcc})
+@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} (@code{gcc})
-If this switch is not used, the exit code returned by @code{gcc} when
+@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, @code{gcc} exits with an extended
+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:
@cindex Debugging options
@ifclear vms
@item -gnatd@var{x}
-@cindex @option{-gnatd} (@code{gcc})
+@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
@end ifclear
@item -gnatG
-@cindex @option{-gnatG} (@code{gcc})
+@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
@item free @var{expr} [storage_pool = @var{xxx}]
Shows the storage pool associated with a @code{free} statement.
-@item freeze @var{typename} [@var{actions}]
-Shows the point at which @var{typename} is frozen, with possible
+@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} [@var{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}
@item @var{function-name}! (@var{arg}, @var{arg}, @var{arg})
Intrinsic function call.
-@item @var{labelname} : label
+@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} ... && @var{expr}
A multiple concatenation (same effect as @var{expr} & @var{expr} &
@var{expr}, but handled more efficiently).
@end table
@item -gnatD
-@cindex @option{-gnatD} (@code{gcc})
+@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 ooutput file. For
+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 @code{gcc} @option{^-g^/DEBUG^} switch
+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
@ifclear vms
@item -gnatR[0|1|2|3[s]]
-@cindex @option{-gnatR} (@code{gcc})
+@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
@end ifclear
@ifset vms
@item /REPRESENTATION_INFO
-@cindex @option{/REPRESENTATION_INFO} (@code{gcc})
+@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
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}.
@item -gnatS
-@cindex @option{-gnatS} (@code{gcc})
+@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 and remain entirely Standard (since new
+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
types in package Standard.
@item -gnatx
-@cindex @option{-gnatx} (@code{gcc})
+@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
@noindent
GNAT uses two methods for handling exceptions at run-time. The
-@code{longjmp/setjmp} method saves the context when entering
+@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
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.
+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 can be used to control which of the
two exception handling methods is used.
@table @option
@c !sort!
-@item -gnatL
-@cindex @option{-gnatL} (@code{gcc})
-This switch causes the longjmp/setjmp approach to be used
+@item --RTS=sjlj
+@cindex @option{--RTS=sjlj} (@command{gnatmake})
+This switch causes the setjmp/longjmp run-time to be used
for exception handling. If this is the default mechanism for the
target (see below), then this has no effect. If the default
mechanism for the target is zero cost exceptions, then
-this switch can be used to modify this default, but it must be
-used for all units in the partition, including all run-time
-library units. One way to achieve this is to use the
-@option{-a} and @option{-f} switches for @code{gnatmake}.
+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 -gnatZ
-@cindex @option{-gnatZ} (@code{gcc})
+@item --RTS=zcx
+@cindex @option{--RTS=zcx} (@command{gnatmake})
@cindex Zero Cost Exceptions
-This switch causes the zero cost approach to be sed
+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 has no effect. If the default
-mechanism for the target is longjmp/setjmp exceptions, then
-this switch can be used to modify this default, but it must be
-used for all units in the partition, including all run-time
-library units. One way to achieve this is to use the
-@option{-a} and @option{-f} switches for @code{gnatmake}.
+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 (see below).
@end table
@noindent
-The @code{longjmp/setjmp} approach is available on all targets, but
-the @code{zero cost} approach is only available on selected targets.
+The @code{setjmp/longjmp} approach is available on all targets, while
+the @code{zero cost} approach is available on selected targets.
To determine whether zero cost exceptions can be used for a
particular target, look at the private part of the file system.ads.
Either @code{GCC_ZCX_Support} or @code{Front_End_ZCX_Support} must
@table @option
@item -gnatem^^=^@var{path}
-@cindex @option{-gnatem} (@code{gcc})
+@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
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
-@code{gnatmake} running under the project file facility. The
+@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.
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, @code{gnatmake} create a temporary mapping file
+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
@option{-gnateD} specifies or modifies the values of preprocessing symbol.
@noindent
-It is recommended that @code{gnatmake} switch ^-s^/SWITCH_CHECK^ should be
+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 @code{gnatmake} switch ^-m^/MINIMAL_RECOMPILATION^ will almost
+Note that @command{gnatmake} switch ^-m^/MINIMAL_RECOMPILATION^ will almost
always trigger recompilation for sources that are preprocessed,
-because @code{gnatmake} cannot compute the checksum of the source after
+because @command{gnatmake} cannot compute the checksum of the source after
preprocessing.
@noindent
@table @code
@item -gnatep=@var{file}
-@cindex @option{-gnatep} (@code{gcc})
+@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
After the file name or the character '*', another optional literal string
-indicating the file name of the definition file to be used for preprocessing.
-(see @ref{Form of Definitions File}. The definition files are found by the
+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
@end smallexample
@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
-@cindex @option{-gnateD} (@code{gcc})
+@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)
@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
On VMS, GNAT compiled programs return POSIX-style codes by default,
e.g. @option{/RETURN_CODES=POSIX}.
-To enable VMS style return codes, GNAT LINK with the option
+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
@end ifset
-
@node Search Paths and the Run-Time Library (RTL)
@section Search Paths and the Run-Time Library (RTL)
@item
Each directory named by an @option{^-I^/SOURCE_SEARCH^} switch given on the
-@code{gcc} command line, in the order given.
+@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 @code{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
+
+@noindent
+@code{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
list of directory names.
This variable can also be defined by means of an environment string
-(an argument to the DEC C exec* set of functions).
+(an argument to the HP C exec* set of functions).
Logical Name:
@smallexample
By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB]
first, followed by the standard Ada 95
libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADAINCLUDE].
-If this is not redefined, the user will obtain the DEC Ada 83 IO packages
+If this is not redefined, the user will obtain the HP Ada 83 IO packages
(Text_IO, Sequential_IO, etc)
instead of the Ada95 packages. Thus, in order to get the Ada 95
packages by default, ADA_INCLUDE_PATH must be redefined.
@end ifset
@item
-@findex ADA_PRJ_INCLUDE_FILE
-Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
-
-@noindent
-@code{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
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 an Ada Library}
+@ref{Installing a library}
@end ifclear
@end enumerate
working directory.
@ifclear vms
Caution: The object file can be redirected with the @option{-o} switch;
-however, @code{gcc} and @code{gnat1} have not been coordinated on this
+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
in compiling sources from multiple directories. This can make
development environments much more flexible.
-
@node Order of Compilation Issues
@section Order of Compilation Issues
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 @code{gnatlink}. The two most important
+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 @code{gnatlink} utility used to link the Ada application.
+to be read by the @command{gnatlink} utility used to link the Ada application.
@end enumerate
-
@node Running gnatbind
@section Running @code{gnatbind}
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
-@code{gcc} command). If it can locate this source file, it checks that
+@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
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 @code{gnatlink} will cause the program to
+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}
@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind})
Generate binder program in C
+@item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}[k|m]
+@cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}[k|m]} (@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 [k|m] 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}[k|m]
+@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 defined 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.
@code{GNAT.Traceback.Symbolic} for more information.
@ifclear vms
Note that on x86 ports, you must not use @option{-fomit-frame-pointer}
-@code{gcc} option.
-@end ifclear vms
+@command{gcc} option.
+@end ifclear
@item ^-F^/FORCE_ELABS_FLAGS^
@cindex @option{^-F^/FORCE_ELABS_FLAGS^} (@command{gnatbind})
@item ^-Lxxx^/BUILD_LIBRARY=xxx^
@cindex @option{^-L^/BUILD_LIBRARY^} (@command{gnatbind})
-Binds the units for library building. In this case the adainit and
-adafinal procedures (See @pxref{Binding with Non-Ada Main Programs})
+Bind the units for library building. In this case the adainit and
+adafinal procedures (@pxref{Binding with Non-Ada Main Programs})
are renamed to ^xxxinit^XXXINIT^ and
^xxxfinal^XXXFINAL^.
Implies ^-n^/NOCOMPILE^.
@ifclear vms
-(@pxref{GNAT and Libraries}, for more details.)
+(@xref{GNAT and Libraries}, for more details.)
@end ifclear
@ifset vms
On OpenVMS, these init and final procedures are exported in uppercase
@item ^-Mxyz^/RENAME_MAIN=xyz^
@cindex @option{^-M^/RENAME_MAIN^} (@command{gnatbind})
-Rename generated main program from main to xyz
+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})
@item --RTS=@var{rts-path}
@cindex @option{--RTS} (@code{gnatbind})
Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}).
+equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
@item ^-o ^/OUTPUT=^@var{file}
@cindex @option{^-o ^/OUTPUT^} (@command{gnatbind})
@itemize @bullet
@item ``@option{^in^INVALID^}'' requesting an invalid value where possible
@item ``@option{^lo^LOW^}'' for the lowest possible value
-possible, and the low
@item ``@option{^hi^HIGH^}'' for the highest possible value
@item ``@option{xx}'' for a value consisting of repeated bytes with the
value 16#xx# (i.e. xx is a string of two hexadecimal digits).
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
-non-zero value will activate round-robin scheduling.
+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
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 n result stored and displayed at program
+termination. Results that can't be stored are displayed on the fly, at task
+termination. This option is currently not supported on OpenVMS I64 platforms.
+
@item ^-v^/REPORT_ERRORS=VERBOSE^
@cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind})
Verbose mode. Write error messages, header, summary output to
no arguments.
@end ifclear
-
@node Consistency-Checking Modes
@subsection Consistency-Checking Modes
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 @code{gnatmake} because in this
+mode that is automatically used by @command{gnatmake} because in this
case the checking against sources has already been performed by
-@code{gnatmake} in the course of compilation (i.e. before binding).
+@command{gnatmake} in the course of compilation (i.e. before binding).
@ifset vms
@item /READ_SOURCES=AVAILABLE
@noindent
The following switches provide additional control over the elaboration
-order. For full details see @xref{Elaboration Order Handling in GNAT}.
+order. For full details see @ref{Elaboration Order Handling in GNAT}.
@table @option
@item ^-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_All} pragmas are implicitly inserted.
+@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.
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 @code{gnatlink}
+This compilation occurs automatically as part of the @command{gnatlink}
processing.
Currently the GNAT run time requires a FPU using 80 bits mode
consists of elaboration of these units in an appropriate order.
@end table
-
@node Command-Line Access
@section Command-Line Access
@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}
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 @code{gcc}
+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:
command line, in the order given.
@item
-@findex ADA_OBJECTS_PATH
+@findex ADA_PRJ_OBJECTS_FILE
+Each of the directories listed in the text file whose name is given
+by the @code{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
+
+@noindent
+@code{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
@code{ADA_OBJECTS_PATH} ^environment variable^logical name^.
@ifset unw
list of directory names.
This variable can also be defined by means of an environment string
-(an argument to the DEC C exec* set of functions).
+(an argument to the HP C exec* set of functions).
Logical Name:
@smallexample
By default, the path includes GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB]
first, followed by the standard Ada 95
libraries in GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB].
-If this is not redefined, the user will obtain the DEC Ada 83 IO packages
+If this is not redefined, the user will obtain the HP Ada 83 IO packages
(Text_IO, Sequential_IO, etc)
instead of the Ada95 packages. Thus, in order to get the Ada 95
packages by default, ADA_OBJECTS_PATH must be redefined.
@end ifset
@item
-@findex ADA_PRJ_OBJECTS_FILE
-Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
-
-@noindent
-@code{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
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 an Ada Library}
+@ref{Installing a library}
@end ifclear
@end enumerate
after accessing the Ada units.
@end table
-
@c ------------------------------------
@node Linking Using gnatlink
-@chapter Linking Using @code{gnatlink}
+@chapter Linking Using @command{gnatlink}
@c ------------------------------------
@findex gnatlink
@noindent
-This chapter discusses @code{gnatlink}, a tool that links
+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 @code{gcc} command)^^
+invokes the system linker ^(via the @command{gcc} command)^^
with a correct list of object files and library references.
-@code{gnatlink} automatically determines the list of files and
+@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.
@menu
* Running gnatlink::
* Switches for gnatlink::
-* Setting Stack Size from gnatlink::
-* Setting Heap Size from gnatlink::
@end menu
@node Running gnatlink
-@section Running @code{gnatlink}
+@section Running @command{gnatlink}
@noindent
-The form of the @code{gnatlink} command is
+The form of the @command{gnatlink} command is
@smallexample
$ gnatlink [@var{switches}] @var{mainprog}[.ali]
@end smallexample
@noindent
-The arguments of @code{gnatlink} (switches, main @file{ALI} file,
+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.
@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, @code{gnatlink} locates the corresponding binder file
+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 @code{gnatlink} switches and the main @file{ALI}
-file are passed to the linker uninterpreted.
+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
Refer to the GCC documentation for
details. Here is an example showing how to generate a linker map:
-@ifclear vms
@smallexample
-$ gnatlink my_prog -Wl,-Map,MAPFILE
+$ ^gnatlink my_prog -Wl,-Map,MAPFILE^GNAT LINK my_prog.ali /MAP^
@end smallexample
-@end ifclear
-
-@ifset vms
-<<Need example for VMS>>
-@end ifset
Using @var{linker options} it is possible to set the program stack and
-heap size. See @ref{Setting Stack Size from gnatlink}, and
+heap size.
+@ifclear vms
+See @ref{Setting Stack Size from gnatlink} and
@ref{Setting Heap Size from gnatlink}.
+@end ifclear
-@code{gnatlink} determines the list of objects required by the Ada
+@command{gnatlink} determines the list of objects required by the Ada
program and prepends them to the list of objects passed to the linker.
-@code{gnatlink} also gathers any arguments set by the use of
+@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
-@code{gnatlink} accepts the following types of extra files on the command
+@command{gnatlink} accepts the following types of extra files on the command
line: objects (.OBJ), libraries (.OLB), sharable images (.EXE), and
options files (.OPT). These are recognized and handled according to their
extension.
@end ifset
@node Switches for gnatlink
-@section Switches for @code{gnatlink}
+@section Switches for @command{gnatlink}
@noindent
-The following switches are available with the @code{gnatlink} utility:
+The following switches are available with the @command{gnatlink} utility:
@table @option
@c !sort!
@item ^-A^/BIND_FILE=ADA^
-@cindex @option{^-A^/BIND_FILE=ADA^} (@code{gnatlink})
+@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^} (@code{gnatlink})
+@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 @code{gnatlink} that the binder has generated C code rather than
+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^} (@code{gnatlink})
-On some targets, the command line length is limited, and @code{gnatlink}
+@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
@item ^-g^/DEBUG^
@cindex Debugging information, including
-@cindex @option{^-g^/DEBUG^} (@code{gnatlink})
+@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^}.
are @file{b_@var{mainprog}.c} and @file{b_@var{mainprog}.o}.
@item ^-n^/NOCOMPILE^
-@cindex @option{^-n^/NOCOMPILE^} (@code{gnatlink})
+@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^} (@code{gnatlink})
+@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^} (@code{gnatlink})
+@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^} (@code{gnatlink})
+@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
@ifclear vms
@item -b @var{target}
-@cindex @option{-b} (@code{gnatlink})
+@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} (@code{gnatlink})
+@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. See the
-@code{gcc} manual page for further details. You would normally use the
+@command{gcc} manual page 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} (@code{gnatlink})
+@cindex @option{--GCC=compiler_name} (@command{gnatlink})
Program used for compiling the binder file. The default is
-`@code{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 @code{gnatlink} to use
-@code{foo -x -y} as your compiler. Note that switch @option{-c} is always
+@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 @code{gnatlink} 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,
+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 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=} (@code{gnatlink})
+@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 (@file{gcc}). When this switch is used, the
-specified linker is called instead of (@file{gcc}) with exactly the same
-parameters that would have been passed to (@file{gcc}) so if the desired
+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
@ifset vms
@item /DEBUG=TRACEBACK
-@cindex @code{/DEBUG=TRACEBACK} (@code{gnatlink})
+@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 /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 a
-Digital compiler.
+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
@end table
-@node Setting Stack Size from gnatlink
-@section Setting Stack Size from @code{gnatlink}
-
-@noindent
-Under Windows systems, it is possible to specify the program stack size from
-@code{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 @code{gnatlink}
-
-@noindent
-Under Windows systems, it is possible to specify the program heap size from
-@code{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
@node The GNAT Make Program gnatmake
-@chapter The GNAT Make Program @code{gnatmake}
+@chapter The GNAT Make Program @command{gnatmake}
@findex gnatmake
@menu
in the presence of overloading, @code{use} clauses, generics and inlined
subprograms.
-@code{gnatmake} automatically takes care of the third and fourth steps
+@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.
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
-@code{gnatmake}.
+@command{gnatmake}.
@node Running gnatmake
-@section Running @code{gnatmake}
+@section Running @command{gnatmake}
@noindent
-The usual form of the @code{gnatmake} command is
+The usual form of the @command{gnatmake} command is
@smallexample
$ gnatmake [@var{switches}] @var{file_name}
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
-@code{gnatmake} was invoked and if it is not found, it will be search on
+@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 @code{gnatmake} output (except when you specify
+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 @code{gnatmake}
+@section Switches for @command{gnatmake}
@noindent
-You may specify any of the following switches to @code{gnatmake}:
+You may specify any of the following switches to @command{gnatmake}:
@table @option
@c !sort!
@ifclear vms
@item --GCC=@var{compiler_name}
-@cindex @option{--GCC=compiler_name} (@code{gnatmake})
-Program used for compiling. The default is `@code{gcc}'. You need to use
+@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 @code{gnatmake} 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 @code{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,
+-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} (@code{gnatmake})
+@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 @code{gnatmake} to use @code{bar -x -y} as your
-binder. Binder switches that are normally appended by @code{gnatmake} to
-`@code{gnatbind}' are now appended to the end of @code{bar -x -y}.
+-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} (@code{gnatmake})
-Program used for linking. The default is `@code{gnatlink}'. You need to
+@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 @code{gnatmake} to use @code{lan -x -y} as your
-linker. Linker switches that are normally appended by @code{gnatmake} to
-`@code{gnatlink}' are now appended to the end of @code{lan -x -y}.
+-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^} (@code{gnatmake})
+@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,
-@code{gnatmake} does not check these files,
+@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
@end ifset
@item ^-b^/ACTIONS=BIND^
-@cindex @option{^-b^/ACTIONS=BIND^} (@code{gnatmake})
+@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^}
Project File is specified, with the ALI file extension.
@item ^-c^/ACTIONS=COMPILE^
-@cindex @option{^-c^/ACTIONS=COMPILE^} (@code{gnatmake})
+@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 @code{gnatmake} will attempt binding and linking
+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^} (@code{gnatmake})
+@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 @code{gnatmake} is invoked with this switch, it will create
+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
of the compiler.
@item ^-C=^/USE_MAPPING_FILE=^@var{file}
-@cindex @option{^-C=^/USE_MAPPING^} (@code{gnatmake})
+@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.
(^-j^/PROCESSES=^nnn, when nnn is greater than 1).
@item ^-D ^/DIRECTORY_OBJECTS=^@var{dir}
-@cindex @option{^-D^/DIRECTORY_OBJECTS^} (@code{gnatmake})
+@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.
@ifclear vms
@item -eL
-@cindex @option{-eL} (@code{gnatmake})
+@cindex @option{-eL} (@command{gnatmake})
Follow all symbolic links when processing project files.
@end ifclear
@item ^-f^/FORCE_COMPILE^
-@cindex @option{^-f^/FORCE_COMPILE^} (@code{gnatmake})
+@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^} (@code{gnatmake})
+@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 ^-i^/IN_PLACE^
-@cindex @option{^-i^/IN_PLACE^} (@code{gnatmake})
-In normal mode, @code{gnatmake} compiles all object files and ALI files
+@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 @code{gnatmake} will automatically
+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, @code{gnatmake} will be forced to recompile
-the corresponding source file, and it will be put the resulting object
-and ALI files in the directory where it found the dummy file.
+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^} (@code{gnatmake})
+@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 @code{gnatmake} will give you the full ordered
+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^} (@code{gnatmake})
+@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 @code{gnatmake}
+sources for which the compile fails is given when @command{gnatmake}
terminates.
-If @code{gnatmake} is invoked with several @file{file_names} and with this
+If @command{gnatmake} is invoked with several @file{file_names} and with this
switch, if there are compilation errors when building an executable,
-@code{gnatmake} will not attempt to build the following executables.
+@command{gnatmake} will not attempt to build the following executables.
@item ^-l^/ACTIONS=LINK^
-@cindex @option{^-l^/ACTIONS=LINK^} (@code{gnatmake})
+@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 need to have been bound.
+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^} (@code{gnatmake})
-Specifies that the minimum necessary amount of recompilations
-be performed. In this mode @code{gnatmake} ignores time
+@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
@item ^-M^/DEPENDENCIES_LIST^
@cindex Dependencies, producing list
-@cindex @option{^-M^/DEPENDENCIES_LIST^} (@code{gnatmake})
+@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
are never reported.
@item ^-n^/DO_OBJECT_CHECK^
-@cindex @option{^-n^/DO_OBJECT_CHECK^} (@code{gnatmake})
+@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.
file, will eventually result in recompiling all required units.
@item ^-o ^/EXECUTABLE=^@var{exec_name}
-@cindex @option{^-o^/EXECUTABLE^} (@code{gnatmake})
+@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 @code{gnatmake} with several
+This switch cannot be used when invoking @command{gnatmake} with several
@file{file_names}.
@item ^-P^/PROJECT_FILE=^@var{project}
-@cindex @option{^-P^/PROJECT_FILE^} (@code{gnatmake})
+@cindex @option{^-P^/PROJECT_FILE^} (@command{gnatmake})
Use project file @var{project}. Only one such switch can be used.
-See @ref{gnatmake and Project Files}.
+@xref{gnatmake and Project Files}.
@item ^-q^/QUIET^
-@cindex @option{^-q^/QUIET^} (@code{gnatmake})
+@cindex @option{^-q^/QUIET^} (@command{gnatmake})
Quiet. When this flag is not set, the commands carried out by
-@code{gnatmake} are displayed.
+@command{gnatmake} are displayed.
@item ^-s^/SWITCH_CHECK/^
-@cindex @option{^-s^/SWITCH_CHECK^} (@code{gnatmake})
+@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:
This switch is recommended when Integrated Preprocessing is used.
@item ^-u^/UNIQUE^
-@cindex @option{^-u^/UNIQUE^} (@code{gnatmake})
+@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
-(see @ref{Project Files and Main Subprograms}).
+(@pxref{Project Files and Main Subprograms}).
@item ^-U^/ALL_PROJECTS^
-@cindex @option{^-U^/ALL_PROJECTS^} (@code{gnatmake})
+@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^} (@code{gnatmake})
-Verbose. Displays the reason for all recompilations @code{gnatmake}
-decides are necessary.
+@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}
-Indicates the verbosity of the parsing of GNAT project files.
-See @ref{Switches Related to Project Files}.
+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.
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
-Indicates that external variable @var{name} has the value @var{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.
-See @ref{Switches Related to Project Files}.
+@xref{Switches Related to Project Files}.
@item ^-z^/NOMAIN^
-@cindex @option{^-z^/NOMAIN^} (@code{gnatmake})
+@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.
@item ^-g^/DEBUG^
-@cindex @option{^-g^/DEBUG^} (@code{gnatmake})
+@cindex @option{^-g^/DEBUG^} (@command{gnatmake})
Enable debugging. This switch is simply passed to the compiler and to the
linker.
@end table
@table @asis
-@item @code{gcc} @asis{switches}
+@item @command{gcc} @asis{switches}
@ifclear vms
-Any uppercase or multi-character switch that is not a @code{gnatmake} switch
-is passed to @code{gcc} (e.g. @option{-O}, @option{-gnato,} etc.)
+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}
@table @option
@c !sort!
@item ^-aI^/SOURCE_SEARCH=^@var{dir}
-@cindex @option{^-aI^/SOURCE_SEARCH^} (@code{gnatmake})
+@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^} (@code{gnatmake})
+@cindex @option{^-aL^/SKIP_MISSING^} (@command{gnatmake})
Consider @var{dir} as being an externally provided Ada library.
-Instructs @code{gnatmake} to skip compilation units whose @file{.ALI}
+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
@option{^-aI^/SOURCE_SEARCH=^@var{dir}}
or @option{^-I^/SEARCH=^@var{dir}}.
Note: this switch is provided for compatibility with previous versions
-of @code{gnatmake}. The easier method of causing standard libraries
+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^} (@code{gnatmake})
+@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 @code{gnatmake}
-@cindex @option{^-A^/CONDITIONAL_SOURCE_SEARCH^} (@code{gnatmake})
+@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^} (@code{gnatmake})
+@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^} (@code{gnatmake})
+@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 @code{gnatmake} was invoked.
+where @command{gnatmake} was invoked.
@item ^-L^/LIBRARY_SEARCH=^@var{dir}
-@cindex @option{^-L^/LIBRARY_SEARCH^} (@code{gnatmake})
+@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
@end ifclear
@item -nostdinc
-@cindex @option{-nostdinc} (@code{gnatmake})
+@cindex @option{-nostdinc} (@command{gnatmake})
Do not look for source files in the system default directory.
@item -nostdlib
-@cindex @option{-nostdlib} (@code{gnatmake})
+@cindex @option{-nostdlib} (@command{gnatmake})
Do not look for library files in the system default directory.
@item --RTS=@var{rts-path}
-@cindex @option{--RTS} (@code{gnatmake})
+@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
@end table
@node Mode Switches for gnatmake
-@section Mode Switches for @code{gnatmake}
+@section Mode Switches for @command{gnatmake}
@noindent
The mode switches (referred to as @code{mode_switches}) allow the
@table @option
@c !sort!
@item -cargs @var{switches}
-@cindex @option{-cargs} (@code{gnatmake})
+@cindex @option{-cargs} (@command{gnatmake})
Compiler switches. Here @var{switches} is a list of switches
-that are valid switches for @code{gcc}. They will be passed on to
-all compile steps performed by @code{gnatmake}.
+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} (@code{gnatmake})
+@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 @code{gnatmake}.
+all bind steps performed by @command{gnatmake}.
@item -largs @var{switches}
-@cindex @option{-largs} (@code{gnatmake})
+@cindex @option{-largs} (@command{gnatmake})
Linker switches. Here @var{switches} is a list of switches
-that are valid switches for @code{gnatlink}. They will be passed on to
-all link steps performed by @code{gnatmake}.
+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} (@code{gnatmake})
-Make switches. The switches are directly interpreted by @code{gnatmake},
+@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
@noindent
This section contains some additional useful notes on the operation
-of the @code{gnatmake} command.
+of the @command{gnatmake} command.
@itemize @bullet
@item
-@cindex Recompilation, by @code{gnatmake}
-If @code{gnatmake} finds no ALI files, it recompiles the main program
+@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 @code{gnatmake}
+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, @code{gnatmake} recompiles
+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 @code{gnatmake} the switch @option{^-I^/SEARCH^}
+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
only.
@item
-@code{gnatmake} examines both an ALI file and its corresponding object file
-for consistency. If an ALI is more recent than its corresponding object,
-or if the object file is missing, the corresponding source will be recompiled.
-Note that @code{gnatmake} expects an ALI and the corresponding object file
-to be in the same directory.
-
-@item
-@code{gnatmake} will ignore any files whose ALI file is write-protected.
+@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
-@code{gnatmake} has been designed to make the use of Ada libraries
+@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,
@end smallexample
@item
-Using @code{gnatmake} along with the
+Using @command{gnatmake} along with the
@option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}
switch provides a mechanism for avoiding unnecessary rcompilations. Using
this switch,
@end itemize
@node How gnatmake Works
-@section How @code{gnatmake} Works
+@section How @command{gnatmake} Works
@noindent
-Generally @code{gnatmake} automatically performs all necessary
+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 @code{gnatmake}
+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 its time stamp predates that of the
-object file and if all the source files listed in 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.
-@code{gnatmake} works by first checking if the specified main unit is up
+@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,
-@code{gnatmake} compiles the main program to build a new ALI file that
+@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 @code{gnatmake} recursively applies the above procedure on all these files.
+and @command{gnatmake} recursively applies the above procedure on all these
+files.
-This process ensures that @code{gnatmake} only trusts the dependencies
+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
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
-@code{gnatmake} will recompute a correct set of new dependencies if
+@command{gnatmake} will recompute a correct set of new dependencies if
necessary.
-When invoking @code{gnatmake} with several @var{file_names}, if a unit is
+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
-(See @ref{Using Other File Names}), changing through a configuration pragmas
-file the version of a source and invoking @code{gnatmake} to recompile may
+(@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 @code{gnatmake}. It may be necessary to use the switch ^-f^/FORCE_COMPILE^.
+by @command{gnatmake}. It may be necessary to use the switch
+^-f^/FORCE_COMPILE^.
@node Examples of gnatmake Usage
-@section Examples of @code{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 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. @code{gnatmake} will operate in quiet mode, not
+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
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, which can reduce
-the size of program executables.
+It then documents the @command{gnatelim} tool and unused subprogram/data
+elimination feature, which can reduce the size of program executables.
@ifnottex
@menu
* Performance Considerations::
* Reducing the Size of Ada Executables with gnatelim::
+* Reducing the Size of Executables with unused subprogram/data elimination::
@end menu
@end ifnottex
-
@c *****************************
@node Performance Considerations
@section Performance Considerations
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
+* Other Optimization Switches::
* Optimization and Strict Aliasing::
+
@ifset vms
* Coverage Analysis::
@end ifset
checking for integer operations 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} (@code{gcc})
-@cindex @option{-gnato} (@code{gcc})
+@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}.
constructs and controlled types will show much improved performance.
The relevant restrictions pragmas are
-@smallexample
+@smallexample @c ada
pragma Restrictions (No_Abort_Statements);
pragma Restrictions (Max_Asynchronous_Select_Nesting => 0);
@end smallexample
@node Optimization Levels
@subsection Optimization Levels
-@cindex @option{^-O^/OPTIMIZE^} (@code{gcc})
+@cindex @option{^-O^/OPTIMIZE^} (@command{gcc})
@noindent
The default is optimization off. This results in the fastest compile
@ifset vms
@code{OPTIMIZE} qualifier
@end ifset
-to @code{gcc} to control the optimization level:
+to @command{gcc} to control the optimization level:
@table @option
@item ^-O0^/OPTIMIZE=NONE^
generates unoptimized code but has
the fastest compilation time.
+Note that many other compilers do fairly extensive optimization
+even if "no optimization" is specified. When using 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^
-Medium level optimization;
+Moderate optimization;
optimizes reasonably well but does not
degrade compilation time significantly.
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 @pxref{Inlining of Subprograms}.
-
+in @ref{Inlining of Subprograms}.
@node Debugging Optimized Code
@subsection Debugging Optimized Code
@noindent
Although it is possible to do a reasonable amount of debugging at
@ifclear vms
-non-zero optimization levels,
+nonzero optimization levels,
the higher the level the more likely that
@end ifclear
@ifset vms
^level^setting^ @option{-O1} or higher.
The use of the @option{^-g^/DEBUG^} switch,
-@cindex @option{^-g^/DEBUG^} (@code{gcc})
+@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.
which removes both debugging information and global symbols.
@end ifclear
-
@node Inlining of Subprograms
@subsection Inlining of Subprograms
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain nested subprograms or anything else that @code{gcc}
+and not contain nested subprograms or anything else that @command{gcc}
cannot support in inlined subprograms.
@item
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain nested subprograms or anything else @code{gcc} cannot
+and not contain nested subprograms or anything else @command{gcc} cannot
support in inlined subprograms.
@item
There is a @code{pragma Inline} for the subprogram.
@item
-@cindex @option{-gnatn} (@code{gcc})
+@cindex @option{-gnatn} (@command{gcc})
The @option{^-gnatn^/INLINE^} switch
-is used in the @code{gcc} command line
+is used in the @command{gcc} command line
@end itemize
Note that specifying the @option{-gnatn} switch causes additional
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 @code{gcc}.
+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^} (@code{gcc})
+@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
@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 @code{gcc} back end, all the specialized
+@code{gcc} optimization switches are potentially usable. These switches
+have not been extensively tested with GNAT but can generally be expected
+to work. Examples of switches in this category are
+@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 the
+@code{gcc} manual.
+
@node Optimization and Strict Aliasing
@subsection Optimization and Strict Aliasing
@cindex Aliasing
for all iterations of the loop and avoid the extra memory reference
required to dereference it each time through the loop.
-This kind of optimziation, called strict aliasing analysis, is
+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.
@subsection Coverage Analysis
@noindent
-GNAT supports the Digital Performance Coverage Analyzer (PCA), which allows
+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
@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 @code{gnatmake}.
+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})
@item ^--GCC^/COMPILER^=@var{compiler_name}
@cindex @option{^-GCC^/COMPILER^} (@command{gnatelim})
-Instructs @code{gnatelim} to use specific @code{gcc} compiler instead of one
+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 @code{gnatmake} instead of one
+Instructs @code{gnatelim} to use specific @command{gnatmake} instead of one
available on the path.
-
-@item -d@var{x}
-@cindex @option{-d@var{x}} (@command{gnatelim})
-Activate internal debugging switches. @var{x} is a letter or digit, or
-string of letters or digits, which specifies the type of debugging
-mode desired. Normally these are used only for internal development
-or system debugging purposes. You can find full documentation for these
-switches in the spec of the @code{Gnatelim} unit in the compiler
-source file @file{gnatelim.ads}.
@end table
@noindent
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
@end enumerate
+@node Reducing the Size of Executables with unused subprogram/data elimination
+@section Reducing the 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::
+@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 only available on native x86 GNU/Linux platform for the
+moment.
+
+@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 gnatmake. This will create the final executable,
+without including the code and data determined as never accessed.
+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. This allows you to eliminate the unused code of the GNAT
+library from your executable.
@c ********************************
@node Renaming Files Using gnatchop
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
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 the section on handling of configuration
-pragmas @pxref{Handling of Configuration Pragmas}.
+@file{gnat.adc} file, see @ref{Handling of Configuration Pragmas}.
Second, in compilation mode, if @code{gnatchop}
is given a file that starts with
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 @code{gcc} or @code{gnatmake} is specified)
+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.
@smallexample
Ada_83
Ada_95
+ Ada_05
C_Pass_By_Copy
Component_Alignment
+ Detect_Blocking
Discard_Names
Elaboration_Checks
Eliminate
Extend_System
- Extensions_Allowed
External_Name_Casing
Float_Representation
Initialize_Scalars
+ Interrupt_State
License
Locking_Policy
Long_Float
Normalize_Scalars
+ Persistent_BSS
Polling
+ Profile
+ Profile_Warnings
Propagate_Exceptions
Queuing_Policy
Ravenscar
Restricted_Run_Time
Restrictions
+ Restrictions_Warnings
Reviewable
Source_File_Name
Style_Checks
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 section @pxref{Operating gnatchop in Compilation Mode} for details.
+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.
@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 DEC Ada. See @pxref{Compatibility with DEC Ada} for details.
+defined in HP Ada. See @ref{Compatibility with HP Ada} for details.
@end ifset
@node Handling Arbitrary File Naming Conventions Using gnatname
@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 (see @ref{Configuration Pragmas})
+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
-(see @ref{Alternative File Naming Schemes}) may be sufficient. However,
+(@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.
@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 *****************************************
* 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::
-* Using Third-Party Libraries through Projects::
* Stand-alone Library Projects::
* Switches Related to Project Files::
* Tools Supporting Project Files::
@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^/EXTERNAT_REFERENCE=^@emph{vbl}=@emph{value}} switch.
+@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.
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} (see @ref{gnatmake and Project Files}).
+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
-deducted from the main source file name. Through the attributes
+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 the executable files, when no attribute @code{Executable} applies:
+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
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-g^-g^");
for Executable ("proc") use "proc1";
+ when others =>
+ null;
end case;
end Builder;
@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
@end smallexample
Attribute @code{Locally_Removed_Files} may also be used to check if a source
-is still needed: if it is possible to build using @code{gnatmake} when such
+is still needed: if it is possible to build using @command{gnatmake} when such
a source is put in attribute @code{Locally_Removed_Files} of a project P, then
it is possible to remove the source completely from a system that includes
project P.
@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
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 (see @ref{Variables})
-@item A string-valued attribute reference (see @ref{Attributes})
-@item An external reference (see @ref{External References in Project Files})
+@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
variables are called @emph{untyped variables}. Typed variables are
particularly useful in @code{case} constructions, to support conditional
attribute declarations.
-(see @ref{case Constructions}).
+(@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.
others have values that are string lists.
There are two categories of attributes: @emph{simple attributes}
-and @emph{associative arrays} (see @ref{Associative Array 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.
@tab string
@item @code{Locally_Removed_Files}
@tab string list
-@item @code{Main}
-@tab string list
@item @code{Languages}
@tab string list
-@item @code{Main_Language}
-@tab string
+@item @code{Main}
+@tab string list
@item @code{Library_Dir}
@tab string
@item @code{Library_Name}
@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}
-(see @ref{Naming Schemes}):
+(@pxref{Naming Schemes}):
@multitable @columnfractions .4 .2 .2 .2
@item Attribute Name @tab Category @tab Index @tab Value
The following attributes are defined for packages @code{Builder},
@code{Compiler}, @code{Binder},
@code{Linker}, @code{Cross_Reference}, and @code{Finder}
-(see @ref{^Switches^Switches^ and Project Files}).
+(@pxref{^Switches^Switches^ and Project Files}).
@multitable @columnfractions .4 .2 .2 .2
@item Attribute Name @tab Category @tab Index @tab Value
@end smallexample
@noindent
-In this example, @code{Default} must be either an project imported by the
+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.
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 a typed string variable.
+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.
package declarations are not allowed.
The value of the case variable is often given by an external reference
-(see @ref{External References in Project Files}).
+(@pxref{External References in Project Files}).
@c ****************************************
@c * Objects and Sources in Project Files *
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
-(see @ref{Source File Names}).
+(@pxref{Source File Names}).
@node Object Directory
@subsection Object Directory
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
-(see @ref{Naming Schemes}) is an immediate source of the project.
+(@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
Otherwise, a project must contain at least one immediate source.
Projects with no source files are useful as template packages
-(see @ref{Packages in Project Files}) for other projects; in particular to
-define a package @code{Naming} (see @ref{Naming Schemes}).
+(@pxref{Packages in Project Files}) for other projects; in particular to
+define a package @code{Naming} (@pxref{Naming Schemes}).
@c ****************************
@c * Importing Projects *
@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
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 is simply a file name, with no path, then its
-location is determined by the @emph{project path}:
+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
-If the ^environment variable^logical name^ @env{ADA_PROJECT_PATH} exists,
-then the project path includes all the directories in this
-^environment variable^logical name^, plus the directory of the project file.
+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
-If the ^environment variable^logical name^ @env{ADA_PROJECT_PATH} does not
-exist, then the project path contains only one directory, namely the one where
-the project file is located.
+In between, all the directories referenced in the
+^environment variable^logical name^ @env{ADA_PROJECT_PATH} if it exists.
@end itemize
@noindent
@end smallexample
@noindent
-then the path is relative to the directory where the importing project file is
-located. Any symbolic link will be fully resolved in the directory
-of the importing project file before the imported project file is examined.
+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,
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 straigh @code{with} may also be imported,
+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}.
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 "(...)/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 "(...)/A1";
+project C1 extends all "(...)/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 ****************************************
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 (see @ref{Packages}).
+packages are preset (@pxref{Packages}).
A package may contain variable declarations, attribute declarations, and case
constructions.
In addition to the tool-oriented packages, you can also declare a package
named @code{Naming} to establish specialized source file naming conventions
-(see @ref{Naming Schemes}).
+(@pxref{Naming Schemes}).
@c ************************************
@c * Variables from Imported Projects *
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 (see @ref{Specifying Configuration Pragmas}).
+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
@end ifclear
@ifset vms
-For example, the following package models the DEC Ada file naming rules:
+For example, the following package models the HP Ada file naming rules:
@smallexample @c projectfile
@group
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 the library-related attributes
+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 responsability of the developer to
-choose a name that will be accepted by the platform. It is recommanded to
+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
-different from the project's object directory. It also needs to be writable.
+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
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"}. 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 an static executable. Otherwise, the library may be 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.
-Depending on the operating system, there may or may not be a distinction
-between dynamic and relocatable libraries. For Unix and VMS Unix there is no
-such distinction.
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
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 ti 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
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 rebuild if some of its sources are recompiled
+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
@file{l2.ads}, @file{l2.adb}.
If @file{l1.adb} has been modified, then the library associated with @code{L}
-will be rebuild when compiling all the immediate sources of @code{A} only
+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 parject @code{A} are also up to date,
+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
library directory. To build executables, @command{gnatmake} will use the
library rather than the individual object files.
-
-@c **********************************************
-@c * Using Third-Party Libraries through Projects
-@c **********************************************
-@node Using Third-Party Libraries through Projects
-@section Using Third-Party Libraries through Projects
-
-Whether you are exporting your own library to make it available to
-clients, or you are using a library provided by a third party, it is
-convenient to have project files that automatically set the correct
-command line switches for the compiler and linker.
-
-Such project files are very similar to the library project files;
-@xref{Library Projects}. The only difference is that you set the
-@code{Source_Dirs} and @code{Object_Dir} attribute so that they point to the
-directories where, respectively, the sources and the read-only ALI files have
-been installed.
-
-If you need to interface with a set of libraries, as opposed to a
-single one, you need to create one library project for each of the
-libraries. In addition, a top-level project that imports all these
-library projects should be provided, so that the user of your library
-has a single @code{with} clause to add to his own projects.
-
-For instance, let's assume you are providing two static libraries
-@file{liba.a} and @file{libb.a}. The user needs to link with
-both of these libraries. Each of these is associated with its
-own set of header files. Let's assume furthermore that all the
-header files for the two libraries have been installed in the same
-directory @file{headers}. The @file{ALI} files are found in the same
-@file{headers} directory.
-
-In this case, you should provide the following three projects:
-
-@smallexample @c projectfile
-@group
-with "liba", "libb";
-project My_Library is
- for Source_Dirs use ("headers");
- for Object_Dir use "headers";
-end My_Library;
-@end group
-
-@group
-project Liba is
- for Source_Dirs use ();
- for Library_Dir use "lib";
- for Library_Name use "a";
- for Library_Kind use "static";
-end Liba;
-@end group
-
-@group
-project Libb is
- for Source_Dirs use ();
- for Library_Dir use "lib";
- for Library_Name use "b";
- for Library_Kind use "static";
-end Libb;
-@end group
-@end smallexample
+@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 *
^-l^/ACTION=LINK^ have special meanings.
@itemize @bullet
-@item ^-b^/ACTION=BIND^ is only allwed for stand-alone libraries. It indicates
+@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.
@command{^gnatls^gnatls^},
@command{^gnatelim^gnatelim^},
@command{^gnatpp^gnatpp^},
+@command{^gnatmetric^gnatmetric^},
+@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.
@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^}.
+(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
@end smallexample
@noindent
-In addition, for command BIND, COMP or COMPILE, FIND, ELIM, LS or LIST, LINK,
-PP or PRETTY and XREF, the project file related switches
+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 immediate sources of the specified project file.
@noindent
-For each of these commands, there is optionally a corresponding package
-in the main project.
+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{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^})
@item
+package @code{Gnatstub} for command STUB
+(invoking @code{^gnatstub^gnatstub^})
+
+@item
package @code{Cross_Reference} for command XREF (invoking
@code{^gnatxref^gnatxref^})
@end smallexample
-
@node The Cross-Referencing Tools gnatxref and gnatfind
@chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
@findex gnatxref
cross-references.
To use these tools, you must not compile your application using the
-@option{-gnatx} switch on the @file{gnatmake} command line
-(see @ref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing
+@option{-gnatx} switch on the @command{gnatmake} command line
+(@pxref{The GNAT Make Program gnatmake}). Otherwise, cross-referencing
information will not be generated.
@menu
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
@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 @file{gnatmake}.
+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
-@file{gnatmake}.
+@command{gnatmake}.
@item -nostdinc
@cindex @option{-nostdinc} (@command{gnatxref})
@item --RTS=@var{rts-path}
@cindex @option{--RTS} (@command{gnatxref})
Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}).
+equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
@item ^-d^/DERIVED_TYPES^
@cindex @option{^-d^/DERIVED_TYPES^} (@command{gnatxref})
@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 @xref{Examples of gnatxref Usage}. The tags file is output
+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
@table @code
@item pattern
An entity will be output only if it matches the regular expression found
-in @samp{pattern}, see @xref{Regular Expressions in gnatfind and gnatxref}.
+in @samp{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
@item sourcefile
@code{gnatfind} will look for references, bodies or declarations
of symbols referenced in @file{sourcefile}, at line @samp{line}
-and column @samp{column}. See @pxref{Examples of gnatfind Usage}
+and column @samp{column}. See @ref{Examples of gnatfind Usage}
for syntax examples.
@item line
@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 @file{gnatmake}.
+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
-@file{gnatmake}.
+@command{gnatmake}.
@item -nostdinc
@cindex @option{-nostdinc} (@command{gnatfind})
@item --RTS=@var{rts-path}
@cindex @option{--RTS} (@command{gnatfind})
Specifies the default location of the runtime library. Same meaning as the
-equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}).
+equivalent @command{gnatmake} flag (@pxref{Switches for gnatmake}).
@item ^-d^/DERIVED_TYPE_INFORMATION^
@cindex @option{^-d^/DERIVED_TYPE_INFORMATION^} (@code{gnatfind})
@end table
-
@c *********************************
@node The GNAT Pretty-Printer gnatpp
@chapter The GNAT Pretty-Printer @command{gnatpp}
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}; see the description of the @command{gnatpp}
-switches below.
+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
@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
+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::
* Other gnatpp Switches::
@end menu
-
@node Alignment Control
@subsection Alignment Control
@cindex Alignment control in @command{gnatpp}
@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}
@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
+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 ^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^
Uncompact layout
-@item ^-notab^/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{^-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 specification occupies more then one line.
@end table
@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}.
+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
line indentation is also 1)
@end table
-
@node Other Formatting Options
@subsection Other Formatting Options
@end table
-
@node Output File Control
@subsection Output File Control
@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^/NO_BACKUP^
+@cindex @option{^-rnb^/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
+
@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
+contains only one file to reformat.
+Option
+@option{^--eol^/END_OF_LINE^}
+cannot be used together
+with @option{^-pipe^/STANDARD_OUTPUT^} option.
@node Other gnatpp Switches
@subsection Other @code{gnatpp} Switches
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;
@item ^-w^/WARNINGS^
@cindex @option{^-w^/WARNINGS^} (@code{gnatpp})
Warning mode;
-@command{gnatpp} generates a warning whenever it can not provide
+@command{gnatpp} generates a warning whenever it cannot provide
a required layout in the result source.
@end table
-
@node Formatting Rules
@section Formatting Rules
* Name Casing::
@end menu
-
@node White Space and Empty Lines
@subsection White Space and Empty Lines
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
word processor style (that is, moving words between lines and putting as
many words in a line as possible).
-
@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
@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
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
GNAT style layout inserts empty lines as separation for
compound statements, return statements and bodies.
-
@node Name Casing
@subsection Name Casing
@smallexample
@cartouche
- @var{casing_schema} ::= @var{identifier} | [*]@var{simple_identifier}[*]
+ @var{casing_schema} ::= @var{identifier} | *@var{simple_identifier}*
@var{simple_identifier} ::= @var{letter}@{@var{letter_or_digit}@}
@end cartouche
@end smallexample
@noindent
-(The @code{[]} metanotation stands for an optional part;
-see @cite{Ada Reference Manual}, Section 2.3) for the definition of the
-@var{identifier} lexical element and the @var{letter_or_digit} category).
+(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.
the casing defined by the dictionary; no subwords are checked for this word
@item
-for the first subword (that is, for the subword preceding the leftmost
-``_''), @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
+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
-for the last subword (following the rightmost ``_'') @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
-for every intermediate subword (surrounded by two'_') @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
-simple_identifier is used for this subword
+if the whole name does not contain any ``_'' inside, and if for this name
+the dictionary contains two entries - one of the form @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
@i{dict1:}
NAME1
*NaMe3*
- *NAME2
+ *Name1*
@end cartouche
@cartouche
@cartouche
procedure Test is
NAME1 : Integer := 1;
- Name4_NAME3_NAME2 : integer := 2;
+ Name4_NAME3_Name2 : Integer := 2;
Name2_NAME3_Name4 : Boolean;
Name1_Var : Float;
begin
- Name2_NAME3_Name4 := Name4_NAME3_NAME2 > NAME1;
+ 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 [@i{switches}] @{@i{filename}@} [@i{-cargs gcc_switches}]
+@end smallexample
+
+@noindent
+where
+@itemize @bullet
+@item
+@i{switches} specify the metrics to compute and define the destination for
+the output
+
+@item
+Each @i{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 @i{filename} is supplied, then the @i{switches} list must contain
+at least one
+@option{-files} switch (@pxref{Other gnatmetric Switches}).
+Including both a @option{-files} switch and one or more
+@i{filename} arguments is permitted.
+
+@item
+@i{-cargs 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::
+* Line Metrics Control::
+* Syntax Metrics Control::
+* Complexity Metrics Control::
+* Other gnatmetric Switches::
+@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. 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) specifications 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 Line Metrics Control
+@subsection 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 number of empty lines and lines containing only space characters and/or
+format effectors (blank lines)
+
+@end itemize
+
+If @command{gnatmetric} is invoked on more than one source file, it sums the
+values of the line metrics for all the files being processed and then
+generates the cumulative results.
+
+By default, all the line metrics are computed and reported. You can use the
+following switches to select the specific line metrics to be computed and
+reported (if any of these parameters is set, only explicitly specified line
+metrics are computed).
+
+@table @option
+@cindex @option{^-la^/LINES_ALL^} (@command{gnatmetric})
+@item ^-la^/LINES_ALL^
+The number of all lines
+
+@cindex @option{^-lcode^/CODE_LINES^} (@command{gnatmetric})
+@item ^-lcode^/CODE_LINES^
+The number of code lines
+
+@cindex @option{^-lcomm^/COMMENT_LINES^} (@command{gnatmetric})
+@item ^-lcomm^/COMENT_LINES^
+The number of comment lines
+
+@cindex @option{^-leol^/MIXED_CODE_COMMENTS^} (@command{gnatmetric})
+@item ^-leol^/MIXED_CODE_COMMENTS^
+The number of code lines containing
+end-of-line comments
+
+@cindex @option{^-lb^/BLANK_LINES^} (@command{gnatmetric})
+@item ^-lb^/BLANK_LINES^
+The number of blank lines
+
+@end table
+
+
+@node Syntax Metrics Control
+@subsection 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 95 Language 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 specifications. It is the
+number of subprograms and generic subprograms declared in the visible
+part (including in 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 specifications 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;
+if any of these is set, only the explicitly specified metrics are computed.
+
+@table @option
+@cindex @option{^-ed^/DECLARATION_TOTAL^} (@command{gnatmetric})
+@item ^-ed^/DECLARATION_TOTAL^
+The total number of declarations
+
+@cindex @option{^-es^/STATEMENT_TOTAL^} (@command{gnatmetric})
+@item ^-es^/STATEMENT_TOTAL^
+The total number of statements
+
+@cindex @option{^-eps^/^} (@command{gnatmetric})
+@item ^-eps^/INT_SUBPROGRAMS^
+The number of public subprograms in a compilation unit
+
+@cindex @option{^-eas^/SUBPROGRAMS_ALL^} (@command{gnatmetric})
+@item ^-eas^/SUBPROGRAMS_ALL^
+The number of all the subprograms in a compilation unit
+
+@cindex @option{^-ept^/INT_TYPES^} (@command{gnatmetric})
+@item ^-ept^/INT_TYPES^
+The number of public types in a compilation unit
+
+@cindex @option{^-eat^/TYPES_ALL^} (@command{gnatmetric})
+@item ^-eat^/TYPES_ALL^
+The number of all the types in a compilation unit
+
+@cindex @option{^-enu^/PROGRAM_NESTING_MAX^} (@command{gnatmetric})
+@item ^-enu^/PROGRAM_NESTING_MAX^
+The maximal program unit nesting level
+
+@cindex @option{^-ec^/CONSTRUCT_NESTING_MAX^} (@command{gnatmetric})
+@item ^-ec^/CONSTRUCT_NESTING_MAX^
+The maximal construct nesting level
+
+@end table
+
+@node Complexity Metrics Control
+@subsection 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{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 finely-grained control you can use
+the following switches:
+
+@table @option
+@cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric})
+
+@item ^-nocc^/SUPPRESS=CYCLOMATIC_COMPLEXITY^
+Do not compute the McCabe Cyclomatic Complexity
+
+@item ^-noec^/SUPPRESS=ESSENTIAL_COMPLEXITY^
+Do not compute the Essential Complexity
+
+@item ^-nonl^/SUPPRESS=MAXIMAL_LOOP_NESTING^
+Do not compute maximal loop nesting level
+
+@item ^-ne^/SUPPRESS=EXITS_AS_GOTOS^
+Do not consider @code{exit} statements as @code{goto}s when
+computing Essential Complexity
+
+@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 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{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
@c ***********************************
@node File Name Krunching Using gnatkr
@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
-impled crunching length is always eight characters.
+implied crunching length is always eight characters.
@noindent
The output is the krunched name. The output has an extension only if the
To call @code{gnatprep} use
@smallexample
-$ gnatprep [-bcrsu] [-Dsymbol=value] infile outfile [deffile]
+$ gnatprep [switches] infile outfile [deffile]
@end smallexample
@noindent
where
@table @code
+@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.
symbols to be referenced by the preprocessor. This argument is
optional, and can be replaced by the use of the @option{-D} switch.
-@item switches
-is an optional sequence of switches as described in the next section.
@end table
@node Switches for gnatprep
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 symbol, associated with value. If no value is given on the
@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 non empty 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}
@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 @code{gnatmake} flags
-(see @ref{Switches for gnatmake}).
+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 @code{gnatmake} flag (see @ref{Switches for gnatmake}).
+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 and object paths. Do not use
+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:
@smallexample
$ gnatls -v -I.. demo1.o
-GNATLS 3.10w (970212) Copyright 1999 Free Software Foundation, Inc.
+GNATLS 5.03w (20041123-34)
+Copyright 1997-2004 Free Software Foundation, Inc.
Source Search Path:
<Current_Directory>
Object Search Path:
<Current_Directory>
../
- /home/comar/local/lib/gcc-lib/mips-sni-sysv4/2.7.2/adalib/
+ /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 =>
@menu
* Running gnatclean::
* Switches for gnatclean::
-* Examples of gnatclean Usage::
+@c * Examples of gnatclean Usage::
@end menu
@node Running gnatclean
@item ^-q^/QUIET^
@cindex @option{^-q^/QUIET^} (@code{gnatclean})
-Quiet output. If there are no error, do not ouuput anything, except in
+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 ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (@code{gnatclean})
Indicates the verbosity of the parsing of GNAT project files.
-See @ref{Switches Related to 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.
-See @ref{Switches Related to Project Files}.
+@xref{Switches Related to Project Files}.
@item ^-aO^/OBJECT_SEARCH=^@var{dir}
@cindex @option{^-aO^/OBJECT_SEARCH^} (@code{gnatclean})
@end table
-@node Examples of gnatclean Usage
-@section Examples of @code{gnatclean} Usage
+@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
+@cindex Library, building, installing, using
@noindent
-This chapter addresses some of the issues related to building and using
-a library with GNAT. It also shows how the GNAT run-time library can be
-recompiled.
+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
-* Creating an Ada Library::
-* Installing an Ada Library::
-* Using an Ada Library::
-* Creating an Ada Library to be Used in a Non-Ada Context::
+* Introduction to Libraries in GNAT::
+* General Ada Libraries::
+* Stand-alone Ada Libraries::
* Rebuilding the GNAT Run-Time Library::
@end menu
-@node Creating an Ada Library
-@section Creating an Ada Library
+@node Introduction to Libraries in GNAT
+@section Introduction to Libraries in GNAT
@noindent
-In the GNAT environment, a library has two components:
+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
-Compiled code and Ali files. See @ref{The Ada Library Information Files}.
+@file{ALI} files.
+@xref{The Ada Library Information Files}.
+@item
+Object files, an archive or a shared library.
@end itemize
@noindent
-In order to use other packages @ref{The GNAT Compilation Model}
-requires a certain number of sources to be available to the compiler.
-The minimal set of
-sources required includes the specs of all the packages that make up the
-visible part of the library as well as all the sources upon which they
-depend. The bodies of all visible generic units must also be provided.
+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
-Although it is not strictly mandatory, it is recommended that all sources
-needed to recompile the library be provided, so that the user can make
-full use of inter-unit inlining and source-level debugging. This can also
-make the situation easier for users that need to upgrade their compilation
-toolchain and thus need to recompile the library from sources.
+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
-The compiled code can be provided in different ways. The simplest way is
-to provide directly the set of objects produced by the compiler during
-the compilation of the library. It is also possible to group the objects
-into an archive using whatever commands are provided by the operating
-system. Finally, it is also possible to create a shared library (see
-option -shared in the GCC manual).
+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 @ref{Using the GNU make Utility},
-or with a conventional script.
-For simple libraries, it is also possible to create a
-dummy main program which depends upon all the packages that comprise the
+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
-gnatmake, in order to build all the necessary objects. Here is an example
-of such a dummy program and the generic commands used to build an
-archive or a shared library.
+@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
-@iftex
-@leftskip=.7cm
-@end iftex
+@group
with My_Lib.Service1;
with My_Lib.Service2;
with My_Lib.Service3;
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
# 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
-When the objects are grouped in an archive or a shared library, the user
-needs to specify the desired library at link time, unless a pragma
-linker_options has been used in one of the sources:
-@smallexample @c ada
-pragma Linker_Options ("-lmy_lib");
@end smallexample
@noindent
-Please note that the library must have a name of the form libxxx.a or
-libxxx.so in order to be accessed by the directive -lxxx at link
-time.
+Please note that the library must have a name of the form @file{libxxx.a} or
+@file{libxxx.so} (or @file{libxxx.dll} on Windows) in order to be accessed by
+the directive @option{-lxxx} at link time.
-@node Installing an Ada Library
-@section Installing an Ada Library
+@node Installing a library
+@subsection Installing a library
+@cindex @code{ADA_PROJECT_PATH}
@noindent
-In the GNAT model, installing a library consists in copying into a specific
-location the files that make up this library. It is possible to install
-the sources in a different directory from the other files (ALI, objects,
-archives) since the source path and the object path can easily be
-specified separately.
+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.
-@noindent
-For general purpose libraries, it is possible for the system
-administrator to put those libraries in the default compiler paths. To
-achieve this, he must specify their location in the configuration files
-@file{ada_source_path} and @file{ada_object_path} that 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:
+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 @code{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 simple format: each line in them
-must contain one unique
-directory name. Those names are added to the corresponding path
+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
+or relative; in the latter case, they are relative to where theses files
are located.
-@noindent
-@file{ada_source_path} and @file{ada_object_path} might actually not be
+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
-he 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} at all, and thus the
+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}).
-@noindent
-You can also specify a new default path to the runtime library at compilation
-time with the switch @option{--RTS=rts-path}. You can easily choose and change
-the runtime you want your program to be compiled with. This switch is
-recognized by gcc, gnatmake, gnatbind, gnatls, gnatfind and gnatxref.
+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}.
-@noindent
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 an Ada Library
-@section Using an Ada Library
+@node Using a library
+@subsection Using a library
-@noindent
-In order to use a Ada library, you need to make sure that this
-library is on both your source and object path
-@ref{Search Paths and the Run-Time Library (RTL)}
-and @ref{Search Paths for gnatbind}. For
-instance, you can use the library @file{mylib} installed in
-@file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands:
+@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
-$ gnatmake -aI/dir/my_lib_src -aO/dir/my_lib_obj my_appl \
+@smallexample @c projectfile
+with "my_lib";
+project My_Proj is
+ ...
+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 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 simplified down to the following:
+This can be expressed more simply:
@smallexample
$ gnatmake my_appl
@end smallexample
+@noindent
when the following conditions are met:
@itemize @bullet
@item
variable @code{ADA_OBJECTS_PATH}, or by the administrator to the file
@file{ada_object_path}
@item
-a pragma @code{Linker_Options}, as mentioned in @ref{Creating an Ada Library},
-has been added to the sources.
-@end itemize
-@noindent
-
-@node Creating an Ada Library to be Used in a Non-Ada Context
-@section Creating an Ada Library to be Used in a Non-Ada Context
-
-@noindent
-The previous sections detailed how to create and install a library that
-was usable from an Ada main program. Using this library in a non-Ada
-context is not possible, because the elaboration of the library is
-automatically done as part of the main program elaboration.
+a pragma @code{Linker_Options} has been added to one of the sources.
+For example:
-GNAT also provides the ability to build libraries that can be used both
-in an Ada and non-Ada context. This section describes how to build such
-a library, and then how to use it from a C program. The method for
-interfacing with the library from other languages such as Fortran for
-instance remains the same.
+@smallexample @c ada
+pragma Linker_Options ("-lmy_lib");
+@end smallexample
+@end itemize
-@subsection Creating the Library
+@node Stand-alone Ada Libraries
+@section Stand-alone Ada Libraries
+@cindex Stand-alone library, building, using
-@itemize @bullet
-@item Identify the units representing the interface of the library.
+@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
-Here is an example of simple library interface:
+@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 ada
-package Interface is
+@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
- procedure Do_Something;
+@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.
- procedure Do_Something_Else;
+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.
-end Interface;
-@end smallexample
+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"}.
-@item Use @code{pragma Export} or @code{pragma Convention} for the
-exported entities.
+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.
-Our package @code{Interface} is then updated as follow:
-@smallexample @c ada
-package Interface is
+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.
- procedure Do_Something;
- pragma Export (C, Do_Something, "do_something");
+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.
- procedure Do_Something_Else;
- pragma Export (C, Do_Something_Else, "do_something_else");
+@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
-end Interface;
+@item
+Compile the binder generated file:
+@smallexample
+ gcc -c b~int2.adb
@end smallexample
-@item Compile all the units composing the library.
+@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 Bind the library objects.
+@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
-This step is performed by invoking gnatbind with the @option{-L<prefix>}
-switch. @code{gnatbind} will then generate the library elaboration
-procedure (named @code{<prefix>init}) and the run-time finalization
-procedure (named @code{<prefix>final}).
+@noindent
+Using SALs is not different from using other libraries
+(see @ref{Using a library}).
-@smallexample
-# generate the binder file in Ada
-$ gnatbind -Lmylib interface
+@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
-# generate the binder file in C
-$ gnatbind -C -Lmylib interface
-@end smallexample
+@noindent
+It is easy to adapt the SAL build procedure discussed above for use of a SAL in
+a non-Ada context.
-@item Compile the files generated by the binder
+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}.
-@smallexample
-$ gcc -c b~interface.adb
-@end smallexample
+Here is an example of simple library interface for use with C main program:
-@item Create the library;
+@smallexample @c ada
+package Interface is
-The procedure is identical to the procedure explained in
-@ref{Creating an Ada Library},
-except that @file{b~interface.o} needs to be added to
-the list of objects.
+ procedure Do_Something;
+ pragma Export (C, Do_Something, "do_something");
-@smallexample
-# create an archive file
-$ ar cr libmylib.a b~interface.o <other object files>
+ procedure Do_Something_Else;
+ pragma Export (C, Do_Something_Else, "do_something_else");
-# create a shared library
-$ gcc -shared -o libmylib.so b~interface.o <other object files>
+end Interface;
@end smallexample
-@item Provide a ``foreign'' view of the library interface;
+@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)
extern void do_something (void);
extern void do_something_else (void);
@end smallexample
-@end itemize
-
-@subsection Using the Library
@noindent
Libraries built as explained above can be used from any program, provided
libraries can be used simultaneously, as long as the elaboration
procedure of each library is called.
-Below is an example of C program that uses our @code{mylib} library.
+Below is an example of a C program that uses the @code{mylib} library.
@smallexample
#include "mylib_interface.h"
@end smallexample
@noindent
-Note that this same library can be used from an equivalent Ada main
-program. In addition, if the libraries are installed as detailed in
-@ref{Installing an Ada Library}, it is not necessary to invoke the
-library elaboration and finalization routines. The binder will ensure
-that this is done as part of the main program elaboration and
-finalization phases.
+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.
-@subsection The Finalization Phase
-
-@noindent
-Invoking any library finalization procedure generated by @code{gnatbind}
-shuts down the Ada run time permanently. Consequently, the finalization
-of all Ada libraries must be performed at the end of the program. No
-call to these libraries nor the Ada run time should be made past the
-finalization phase.
-
-@subsection Restrictions in Libraries
+@node Restrictions in Stand-alone Libraries
+@subsection Restrictions in Stand-alone Libraries
@noindent
The pragmas listed below should be used with caution inside libraries,
@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,
-a @code{Program_Error} will
+@code{Program_Error} will
be raised during the elaboration of the conflicting
libraries. The usage of these pragmas and its consequences for the user
should therefore be well documented.
-Similarly, the traceback in exception occurrences mechanism should be
+Similarly, the traceback in the exception occurrence mechanism should be
enabled or disabled in a consistent manner across all libraries.
-Otherwise, a Program_Error will be raised during the elaboration of the
+Otherwise, Program_Error will be raised during the elaboration of the
conflicting libraries.
-If the @code{'Version} and @code{'Body_Version}
-attributes are used inside a library, then it is necessary to
-perform a @code{gnatbind} step that mentions all @file{ALI} files in all
+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 Normalize_Scalar. A special Makefile called
+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
@noindent
This chapter offers some examples of makefiles that solve specific
problems. It does not explain how to write a makefile (see the GNU make
-documentation), nor does it try to replace the @code{gnatmake} utility
+documentation), 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
each step of the build process.
The list of dependencies are handled automatically by
-@code{gnatmake}. The Makefile is simply used to call gnatmake in each of
+@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
gnatmake the list of source and object directories.
This example shows how you can set up environment variables, which will
-make @code{gnatmake} behave exactly as if the directories had been
+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).
@end smallexample
@end ifclear
-
-@node Finding Memory Problems
-@chapter Finding Memory Problems
+@node Memory Management Issues
+@chapter Memory Management Issues
@noindent
-This chapter describes
+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
-the @command{gnatmem} tool, which can be used to track down
-``memory leaks'', and
+It also describes the @command{gnatmem} tool, which can be used to track down
+``memory leaks''.
@end ifclear
-the GNAT Debug Pool facility, which can be used to detect incorrect uses of
-access values (including ``dangling references'').
@menu
+* Some Useful Memory Pools::
+* The GNAT Debug Pool Facility::
@ifclear vms
* The gnatmem Tool::
@end ifclear
-* The GNAT Debug Pool Facility::
@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
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 x86,
-Solaris (sparc and x86) and Windows NT/2000/XP (x86).
+32-bit Solaris (sparc and x86) and Windows NT/2000/XP (x86).
@noindent
The @code{gnatmem} command has the form
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
-@ref{Switches for gcc}. For example to build @file{my_program}:
+(see @ref{Switches for gcc}). For example to build @file{my_program}:
@smallexample
$ gnatmake -g my_program -largs -lgmem
@end smallexample
@noindent
-When running @file{my_program} the file @file{gmem.out} is produced. This file
-contains information about all allocations and deallocations done by the
-program. It is produced by the instrumented allocations and
+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}.
-@noindent
+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
@code{-i} switch, gnatmem will assume that this file can be found in the
@end ifclear
+@node Stack Related Facilities
+@chapter Stack Related Facilities
-@node The GNAT Debug Pool Facility
-@section The GNAT Debug Pool Facility
-@findex Debug Pool
-@cindex storage, pool, memory corruption
+@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
-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}.
+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.
+To ensure that a clean exception is signalled for stack
+overflow, set the environment variable
+@code{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.
+
+@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
+@code{-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
+
+@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. In order to prevent overflow,
+the real stack limit is slightly larger than the Stack Size in order to allow
+proper recovery.
+
+@item Actual Use
+is the measure done by the stack analyzer.
+
+@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 *********************************
+@node Verifying properties using gnatcheck
+@chapter Verifying properties using @command{gnatcheck}
+@findex 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.
+
+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.
+
+The project support for @command{gnatcheck} is provided by the @command{gnat}
+driver.
+
+Several rules are already implemented in @command{gnatcheck}. The list of such
+rules can be obtained with option @option{^-h^/HELP^} as described in the next
+section. A user can add new rules by modifying the @command{gnatcheck} code and
+rebuilding the tool. For adding a simple rule making some local checks, a small
+amount of straightforward ASIS-based programming is usually needed.
-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;
+@noindent
+@command{gnatcheck} has the command-line interface of the form
+
+@smallexample
+$ gnatcheck [@i{switches}] @{@i{filename}@} [@i{^-files^/FILES^=@{arg_list_filename@}}]
+ [@i{-cargs gcc_switches}] [@i{-rules rule_options}]
@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:
+@noindent
+where
@itemize @bullet
@item
-@code{GNAT.Debug_Pools.Accessing_Not_Allocated_Storage}
+@i{switches} specify the general tool options
+
@item
-@code{GNAT.Debug_Pools.Accessing_Deallocated_Storage}
+Each @i{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
-@code{GNAT.Debug_Pools.Freeing_Not_Allocated_Storage}
+Each @i{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
-@code{GNAT.Debug_Pools.Freeing_Deallocated_Storage }
+@i{-cargs 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
+@i{-rules 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
-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#}.
+Either a @i{filename} or an @i{arg_list_filename} needs to be supplied.
-See the documentation in the file g-debpoo.ads for more information on the
-various strategies.
+@menu
+* Format of the Report File::
+* General gnatcheck Switches::
+* gnatcheck Rule Options::
+* Add the Results of Compiler Checks to gnatcheck Output::
+@end menu
-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
+@node Format of the Report File
+@section Format of the Report File
- type T is access Integer;
- type U is access all T;
+@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
- 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;
+@node General gnatcheck Switches
+@section General @command{gnatcheck} Switches
- procedure Info is new GNAT.Debug_Pools.Print_Info(Put_Line);
+@noindent
+The following switches control the general @command{gnatcheck} behavior
-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
+@table @option
+@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.
+
+@cindex @option{^-h^/HELP^} (@command{gnatcheck})
+@item ^-h^/HELP^
+Print out the list of the currently implemented rules. For more details see
+the README file in the @command{gnatcheck} sources.
+
+@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{^-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
-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
+Note, that if either 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 contain only sections
+explicitly stated by these options.
-Debug Pool info:
- Total allocated bytes : 8
- Total deallocated bytes : 0
- Current Water Mark: 8
- High Water Mark: 8
+@node gnatcheck Rule Options
+@section @command{gnatcheck} Rule Options
-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
+@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@i{rule_id[:param]}
+Turn on the check for a specified rule with the specified parameter, if any.
+@i{rule_id} should 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 @i{:param} item should
+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@i{rule_id}
+Turn off the check for a specified rule
+
+@end table
+@node Add the Results of Compiler Checks to gnatcheck Output
+@section Add 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
+@i{Restrictions} with the same parameters as pragma
+@code{Restrictions} or @code{Restriction_Warnings}
+
+@item Style_Checks
+To record compiler style checks, use the rule named
+@i{Style_Checks}. A parameter of this rule can be either @i{All_Checks}, that
+turns ON all the style checks, or a string that has exactly the same structure
+and semantics as @code{string_LITERAL} parameter of GNAT pragma
+@code{Style_Checks}.
+
+@item Warnings
+To record compiler warnings (@pxref{Warning Message Control}), use the rule
+named @i{Warnings} with a parameter that is a valid
+@code{static_string_expression} argument of GNAT pragma @code{Warnings}.
+
+@end table
+
+@c *********************************
@node Creating Sample Bodies Using gnatstub
@chapter Creating Sample Bodies Using @command{gnatstub}
@findex gnatstub
@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.
+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})
@end table
-
@node Other Utility Programs
@chapter Other Utility Programs
available in the @code{Glide} @result{} @code{Help} menu.
@end ifclear
-
@node Converting Ada Files to html with gnathtml
@section Converting Ada Files to HTML with @code{gnathtml}
The command line is as follow:
@smallexample
-$ perl gnathtml.pl [switches] ada-files
+$ perl gnathtml.pl [^switches^options^] ada-files
@end smallexample
@noindent
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 are the following ones :
+The available ^switches^options^ are the following ones :
@table @option
@item -83
@item -d
@cindex @option{-d} (@code{gnathtml})
-If the ada files depend on some other files (using for instance the
-@code{with} command, the latter will also be converted to html.
+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 -f
@cindex @option{-f} (@code{gnathtml})
By default, gnathtml will generate html links only for global entities
-('with'ed units, global variables and types,...). If you specify the
+('with'ed units, global variables and types,...). 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 is provided and @var{number} is not 0, then @code{gnathtml}
-will number the html files every @var{number} line.
+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})
running and debugging applications, you may use @file{.gpr} files
to give the directories where Emacs can find sources and object files.
-Using this switch, you can tell gnathtml to use these files. This allows
-you to get an html version of your application, even if it is spread
-over multiple directories.
+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 option allows you to change the color used for symbol definitions.
+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 provides the name of a file. This file contains a list of
+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
@findex LSE
@noindent
-The GNAT distribution provides an Ada 95 template for the Digital Language
+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.
@findex PCA
@noindent
-GNAT supports The Digital Performance Coverage Analyzer (PCA), a component
+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.
@cindex Debugging
@noindent
-This chapter discusses how to debug Ada programs. An incorrect Ada program
-may be handled in three ways by the GNAT compiler:
+This chapter discusses how to debug Ada programs.
+@ifset vms
+It applies to the Alpha OpenVMS platform;
+the debugger for I64 OpenVMS is scheduled for a subsequent release.
+@end ifset
+
+An incorrect Ada program may be handled in three ways by the GNAT compiler:
@enumerate
@item
@noindent
@code{GDB} is a general purpose, platform-independent debugger that
-can be used to debug mixed-language programs compiled with @code{GCC},
+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.
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
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
-perturbated.
+perturbed.
@end table
@noindent
@enumerate
@item
-Run @code{gcc} with the @option{-gnatf}. This first
+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.
message displayed may help to pinpoint the culprit.
@item
-Run @code{gcc} with the @option{^-v (verbose)^/VERBOSE^} switch. In this mode,
-@code{gcc} produces ongoing information about the progress of the
+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 @code{gcc} with the @option{-gnatdc} switch. This is a GNAT specific
+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.
Finally, you can start
@code{gdb} directly on the @code{gnat1} executable. @code{gnat1} is the
front-end of GNAT, and can be run independently (normally it is just
-called from @code{gcc}). You can use @code{gdb} on @code{gnat1} as you
+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 @code{gcc} backend, indicates the source line at
+@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
@findex GNAT
Files with prefix @file{^g-^G-^} are children of @code{GNAT}. These are useful
general-purpose packages, fully documented in their specifications. All
-the other @file{.c} files are modifications of common @code{gcc} files.
+the other @file{.c} files are modifications of common @command{gcc} files.
@end itemize
@node Getting Internal Debugging Information
@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.
-@pxref{Running gnatbind}. The remaining entries are assorted runtime routines,
+@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
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
end STB;
@end smallexample
+
+@c ******************************
@ifset vms
-@node Compatibility with DEC Ada
-@chapter Compatibility with DEC Ada
+@node Compatibility with HP Ada
+@chapter Compatibility with HP Ada
@cindex Compatibility
@noindent
-This section of the manual compares DEC Ada for OpenVMS Alpha and GNAT
-OpenVMS Alpha. GNAT achieves a high level of compatibility
-with DEC Ada, and it should generally be straightforward to port code
-from the DEC Ada environment to GNAT. However, there are a few language
+@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 section. In
+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.
-Note that this discussion addresses specifically the implementation
-of Ada 83 for DIGITAL OpenVMS Alpha Systems. In cases where the implementation
-of DEC Ada differs between OpenVMS Alpha Systems and OpenVMS VAX Systems,
+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 from Alpha to I64 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 the
+@cite{GNAT Reference Manual} indicates whether or not they are applicable
+to non-VMS systems.
+
+
@menu
* Ada 95 Compatibility::
* Differences in the Definition of Package System::
* The Package STANDARD::
* The Package SYSTEM::
* Tasking and Task-Related Features::
-* Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems::
* Pragmas and Pragma-Related Features::
* Library of Predefined Units::
* Bindings::
* Program Compilation and Library Management::
* Input-Output::
* Implementation Limits::
-* Tools::
+* Tools and Utilities::
@end menu
@node Ada 95 Compatibility
@section Ada 95 Compatibility
@noindent
-GNAT is an Ada 95 compiler, and DEC Ada is an Ada 83
+GNAT is an Ada 95 compiler, and HP Ada is an Ada 83
compiler. Ada 95 is 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 Ada 95 Reference
-Manual (ANSI/ISO/IEC-8652:1995) provides details on specific
-incompatibilities.
+Manual provides details on specific incompatibilities.
-GNAT provides the switch /83 on the GNAT COMPILE command,
-as well as the pragma ADA_83, to force the compiler to
+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 keywords, so that their use as identifiers
-in Ada83 program is legal, and handles the cases of packages
+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 System
+@section Differences in the Definition of Package @code{System}
@noindent
-Both the Ada 95 and Ada 83 reference manuals permit a compiler to add
-implementation-dependent declarations to package System. In normal mode,
-GNAT does not take advantage of this permission, and the version of System
-provided by GNAT exactly matches that in the Ada 95 Reference Manual.
+Both Ada 95 and Ada 83 permit a compiler 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 in Ada 95.
-However, DEC Ada adds an extensive set of declarations to package System,
-as fully documented in the DEC Ada manuals. To minimize changes required
+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
-Extend_System for extending the definition of package System. By using:
+@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
@end smallexample
@noindent
-The set of definitions in System is extended to include those in package
-@code{System.Aux_DEC}.
-These definitions are incorporated directly into package
-System, as though they had been declared there in the first place. For a
+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 specification of this package,
-which can be found in the file @code{s-auxdec.ads} in the GNAT library.
-The pragma Extend_System is a configuration pragma, which means that
+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 the section on Configuration
-Pragmas for further details.
+apply to all subsequent compilations. See @ref{Configuration Pragmas},
+for further details.
An alternative approach that avoids the use of the non-standard
-Extend_System pragma is to add a context clause to the unit that
+@code{Extend_System} pragma is to add a context clause to the unit that
references these facilities:
@smallexample @c ada
-@group
@cartouche
with System.Aux_DEC;
use System.Aux_DEC;
@end cartouche
-@end group
@end smallexample
@noindent
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}.
+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.
@subsection Integer Types and Representations
@noindent
-The set of predefined integer types is identical in DEC Ada and GNAT.
+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,
-DEC Ada for OpenVMS Alpha systems has defined the
-following additional integer types in package System:
+HP Ada for OpenVMS Alpha systems has defined the
+following additional integer types in package @code{System}:
@itemize @bullet
@item
-INTEGER_8
+@code{INTEGER_8}
@item
-INTEGER_16
+@code{INTEGER_16}
@item
-INTEGER_32
+@code{INTEGER_32}
@item
-INTEGER_64
+@code{INTEGER_64}
@item
-LARGEST_INTEGER
+@code{LARGEST_INTEGER}
@end itemize
@noindent
-When using GNAT, the first four of these types may be obtained from the
+In GNAT, the first four of these types may be obtained from the
standard Ada 95 package @code{Interfaces}.
-Alternatively, by use of the pragma
-@code{Extend_System}, identical
+Alternatively, by use of the pragma @code{Extend_System}, identical
declarations can be referenced directly in package @code{System}.
-On both GNAT and DEC Ada, the maximum integer size is 64 bits.
+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 DEC Ada and GNAT.
+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 DEC Ada is VAX_Float, but the default representation
+representation for HP Ada is @code{VAX_Float}, but the default representation
for GNAT is IEEE.
-Specific types may be declared to be VAX_Float or IEEE, using the pragma
-@code{Float_Representation} as described in the DEC Ada documentation.
+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
-@group
@cartouche
type F_Float is digits 6;
pragma Float_Representation (VAX_Float, F_Float);
@end cartouche
-@end group
@end smallexample
@noindent
-declare a type F_Float that will be represented in VAX_Float format.
-This set of declarations actually appears in System.Aux_DEC, which provides
+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 DEC Ada version of package
-System. This and similar declarations may be accessed in a user program
+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 Float_Representation and Long_Float
+@subsection Pragmas @code{Float_Representation} and @code{Long_Float}
@noindent
-DEC Ada provides the pragma @code{Float_Representation}, which
+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
-@group
+@smallexample @c ada
@cartouche
-@b{pragma} @code{Float_Representation}(VAX_Float | IEEE_Float);
+pragma Float_Representation(VAX_Float | IEEE_Float);
@end cartouche
-@end group
@end smallexample
@noindent
@itemize @bullet
@item
@code{VAX_Float} specifies that floating-point
-types are represented by default with the VAX hardware types
-F-floating, D-floating, G-floating. Note that the H-floating
-type is available only on DIGITAL Vax systems, and is not available
-in either DEC Ada or GNAT for Alpha systems.
+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
@noindent
GNAT provides an identical implementation of the pragma
@code{Float_Representation}, except that it functions as a
-configuration pragma, as defined by Ada 95. Note that the
+configuration pragma. Note that the
notion of configuration pragma corresponds closely to the
-DEC Ada notion of a program library switch.
+HP Ada notion of a program library switch.
-When no pragma is used in GNAT, the default is IEEE_Float, which is different
-from DEC Ada 83, where the default is VAX_Float. In addition, the
-predefined libraries in GNAT are built using IEEE_Float, so it is not
+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 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 VAX_Float may be useful is in interfacing
-to existing code and data that expects the use of VAX_Float. There are
-two possibilities here. If the requirement for the use of VAX_Float is
-localized, then the best approach is to use the predefined VAX_Float
+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.
-Alternatively, if an entire program depends heavily on the use of
-the @code{VAX_Float} and in particular assumes that the types in
-package @code{Standard} are in @code{Vax_Float} format, then it
-may be desirable to reconfigure GNAT to assume Vax_Float by default.
-This is done by using the GNAT LIBRARY command to rebuild the library, and
-then using the general form of the @code{Float_Representation}
-pragma to ensure that this default format is used throughout.
-The form of the GNAT LIBRARY command is:
-
-@smallexample
-GNAT LIBRARY /CONFIG=@i{file} /CREATE=@i{directory}
-@end smallexample
-
-@noindent
-where @i{file} contains the new configuration pragmas
-and @i{directory} is the directory to be created to contain
-the new library.
-
@noindent
-On OpenVMS systems, DEC Ada provides the pragma @code{Long_Float}
+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.
@subsection Fixed-Point Types and Representations
@noindent
-On DEC Ada for OpenVMS Alpha systems, rounding is
+On HP Ada for OpenVMS Alpha systems, rounding is
away from zero for both positive and negative numbers.
-Therefore, +0.5 rounds to 1 and -0.5 rounds to -1.
+Therefore, @code{+0.5} rounds to @code{1},
+and @code{-0.5} rounds to @code{-1}.
-On GNAT for OpenVMS Alpha, the results of operations
+On GNAT the results of operations
on fixed-point types are in accordance with the Ada 95
rules. In particular, results of operations on decimal
fixed-point types are truncated.
@subsection Record and Array Component Alignment
@noindent
-On DEC Ada for OpenVMS Alpha, all non composite components
+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 for OpenVMS Alpha, alignment rules are compatible
-with DEC Ada for OpenVMS Alpha.
+On GNAT, alignment rules are compatible
+with HP Ada for OpenVMS Alpha.
@node Address Clauses
@subsection Address Clauses
@noindent
-In DEC Ada and GNAT, address clauses are supported for
+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, with the same representation (it is simply
-a machine pointer). Addition, subtraction, and comparison
+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 95 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 with's both this extended package @code{System}
+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 95 package was
-designed specifically to provide the kind of features that DEC Ada
+designed specifically to provide the kind of features that HP Ada
adds directly to package @code{System}.
-GNAT is compatible with DEC Ada in its handling of address
+The type @code{System.Address} is a 64-bit integer type in GNAT for
+I64 OpenVMS. For more information,
+see @ref{Transitioning from Alpha to I64 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
@noindent
will be rejected by GNAT, since the address cannot be computed at the time
-that Q is declared. To achieve the intended effect, write instead:
+that @code{Q} is declared. To achieve the intended effect, write instead:
@smallexample @c ada
@group
@noindent
which will be accepted by GNAT (and other Ada 95 compilers), and is also
-backwards compatible with Ada 83. A fuller description of the restrictions
-on address specifications is found in the GNAT Reference Manual.
+compatible with Ada 83. A fuller description of the restrictions
+on address specifications is found in the @cite{GNAT Reference Manual}.
@node Other Representation Clauses
@subsection Other Representation Clauses
@noindent
-GNAT supports in a compatible manner all the representation
-clauses supported by DEC Ada. In addition, it
-supports representation clause forms that are new in Ada 95
-including COMPONENT_SIZE and SIZE clauses for objects.
+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 STANDARD
+@section The Package @code{STANDARD}
@noindent
-The package STANDARD, as implemented by DEC Ada, is fully
-described in the Reference Manual for the Ada Programming
-Language (ANSI/MIL-STD-1815A-1983) and in the DEC Ada
+The package @code{STANDARD}, as implemented by HP Ada, is fully
+described in the Ada 95 Reference Manual and in the HP Ada
Language Reference Manual. As implemented by GNAT, the
-package STANDARD is described in the Ada 95 Reference
+package @code{STANDARD} is described in the Ada 95 Reference
Manual.
-In addition, DEC Ada supports the Latin-1 character set in
-the type CHARACTER. GNAT supports the Latin-1 character set
-in the type CHARACTER and also Unicode (ISO 10646 BMP) in
-the type WIDE_CHARACTER.
+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 DEC Ada, but defaults are different, and are controlled by
-pragmas. See @pxref{Floating-Point Types and Representations} for details.
+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 SYSTEM
+@section The Package @code{SYSTEM}
@noindent
-DEC Ada provides a system-specific version of the package
-SYSTEM for each platform on which the language ships.
-For the complete specification of the package SYSTEM, see
-Appendix F of the DEC Ada Language Reference Manual.
+HP Ada provides a specific version of the package
+@code{SYSTEM} for each platform on which the language is implemented.
+For the complete specification of the package @code{SYSTEM}, see
+Appendix F of the @cite{HP Ada Language Reference Manual}.
-On DEC Ada, the package SYSTEM includes the following conversion functions:
+On HP Ada, the package @code{SYSTEM} includes the following conversion
+functions:
@itemize @bullet
-@item TO_ADDRESS(INTEGER)
+@item @code{TO_ADDRESS(INTEGER)}
-@item TO_ADDRESS(UNSIGNED_LONGWORD)
+@item @code{TO_ADDRESS(UNSIGNED_LONGWORD)}
-@item TO_ADDRESS(universal_integer)
+@item @code{TO_ADDRESS(}@i{universal_integer}@code{)}
-@item TO_INTEGER(ADDRESS)
+@item @code{TO_INTEGER(ADDRESS)}
-@item TO_UNSIGNED_LONGWORD(ADDRESS)
+@item @code{TO_UNSIGNED_LONGWORD(ADDRESS)}
-@item Function IMPORT_VALUE return UNSIGNED_LONGWORD and the
- functions IMPORT_ADDRESS and IMPORT_LARGEST_VALUE
+@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 SYSTEM that matches
+By default, GNAT supplies a version of @code{SYSTEM} that matches
the definition given in the Ada 95 Reference Manual.
This
-is a subset of the DIGITAL system definitions, which is as
+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 SYSTEM_NAME is different:
+is that the definition of @code{SYSTEM_NAME} is different:
@smallexample @c ada
-@group
@cartouche
type Name is (SYSTEM_NAME_GNAT);
System_Name : constant Name := SYSTEM_NAME_GNAT;
@end cartouche
-@end group
@end smallexample
@noindent
Also, GNAT adds the new Ada 95 declarations for
-BIT_ORDER and DEFAULT_BIT_ORDER.
+@code{BIT_ORDER} and @code{DEFAULT_BIT_ORDER}.
However, the use of the following pragma causes GNAT
-to extend the definition of package SYSTEM so that it
-encompasses the full set of DIGITAL-specific extensions,
+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
@end smallexample
@noindent
-The pragma Extend_System is a configuration pragma that
+The pragma @code{Extend_System} is a configuration pragma that
is most conveniently placed in the @file{gnat.adc} file. See the
-GNAT Reference Manual for further details.
-
-DEC Ada does not allow the recompilation of the package
-SYSTEM. Instead DEC Ada provides several pragmas (SYSTEM_
-NAME, STORAGE_UNIT, and MEMORY_SIZE) to modify values in
-the package SYSTEM. On OpenVMS Alpha systems, the pragma
-SYSTEM_NAME takes the enumeration literal OPENVMS_AXP as
+@cite{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 SYSTEM using
-a special switch (@option{-gnatg}) and this switch can be used if
-it is necessary to modify the definitions in SYSTEM. GNAT does
-not permit the specification of SYSTEM_NAME, STORAGE_UNIT
-or MEMORY_SIZE by any other means.
+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 SYSTEM_NAME takes the
-enumeration literal SYSTEM_NAME_GNAT.
+On GNAT systems, the pragma @code{SYSTEM_NAME} takes the
+enumeration literal @code{SYSTEM_NAME_GNAT}.
The definitions provided by the use of
@end smallexample
@noindent
-are virtually identical to those provided by the DEC Ada 83 package
-System. One important difference is that the name of the TO_ADDRESS
-function for type UNSIGNED_LONGWORD is changed to TO_ADDRESS_LONG.
-See the GNAT Reference manual for a discussion of why this change was
+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}.
+See the @cite{GNAT Reference Manual} for a discussion of why this change was
necessary.
@noindent
-The version of TO_ADDRESS taking a universal integer argument is in fact
+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.
-In GNAT, we are constrained to be exactly compatible with the standard,
-and this means we cannot provide this capability. In DEC Ada 83, the
+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
@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 DEC Ada 83, there is no ambiguity, since the
-definition using universal_integer takes precedence.
+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 universal_integer cannot be supplied, it is
+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:
+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;
@end smallexample
@noindent
-This means that programs using TO_ADDRESS for UNSIGNED_LONGWORD must
-change the name to TO_ADDRESS_LONG.
+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
-The concepts relevant to a comparison of tasking on GNAT
-and on DEC Ada for OpenVMS Alpha systems are discussed in
-the following sections.
-
-For detailed information on concepts related to tasking in
-DEC Ada, see the DEC Ada Language Reference Manual and the
+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.
-@node Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems
-@section Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems
+@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, DEC Ada tasking support is based on DECthreads,
+systems, HP Ada tasking support is based on DECthreads,
an implementation of the POSIX standard for threads.
-Although tasks are implemented as threads, all tasks in
-an Ada program are part of the same process. As a result,
-resources such as open files and virtual memory can be
-shared easily among tasks. Having all tasks in one process
-allows better integration with the programming environment
-(the shell and the debugger, for example).
-
-Also, on OpenVMS Alpha systems, DEC Ada tasks and foreign
+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,
-DEC Ada can call C code that is already threaded.
-GNAT on OpenVMS Alpha uses the facilities of DECthreads,
+HP Ada can call C code that is already threaded.
+
+GNAT uses the facilities of DECthreads,
and Ada tasks are mapped to threads.
-@menu
-* Assigning Task IDs::
-* Task IDs and Delays::
-* Task-Related Pragmas::
-* Scheduling and Task Priority::
-* The Task Stack::
-* External Interrupts::
-@end menu
@node Assigning Task IDs
@subsection Assigning Task IDs
@noindent
-The DEC Ada Run-Time Library always assigns %TASK 1 to
+The HP Ada Run-Time Library always assigns @code{%TASK 1} to
the environment task that executes the main program. On
-OpenVMS Alpha systems, %TASK 0 is often used for tasks
+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 DEC Ada. There is no null task, and the
+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
@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 REQIDT parameter).
+identification of the timer request (the @code{REQIDT} parameter).
If Timers are used in the application take care not to use
-0 for the identification, because cancelling such a timer
+@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 TASK_STORAGE, which allows
+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
-TASK_STORAGE specifies a value of zero, a minimal guard
-area is created. In the absence of a pragma TASK_STORAGE, a default guard
-area is created.
+@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 TASK_INFO
+@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 SYSTEM.TASK_INFO.TASK_INFO_TYPE.
+ must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}.
-@item TASK_STORAGE
+@item @code{TASK_STORAGE}
- GNAT implements pragma TASK_STORAGE in the same way as
- DEC Ada.
- Both DEC Ada and GNAT supply the pragmas PASSIVE,
- SUPPRESS, and VOLATILE.
+ 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
-DEC Ada implements the Ada language requirement that
+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 DEC
+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 rear of the ready queue for
+time and then placed at the tail of the ready queue for
its priority level.
-DEC Ada provides the implementation-defined pragma TIME_SLICE,
+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 DEC Ada run-time reference manual for
-information on using the pragmas to control DEC Ada task
+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
+GNAT follows the scheduling rules of Annex D (Real-Time
Annex) of the Ada 95 Reference Manual. In general, this
-scheduling strategy is fully compatible with DEC Ada
+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
-DEC Ada 83, by means of the pragma Time_Slice, whose semantics are identical
-to the DEC Ada 83 pragma of the same name.
+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
-DEC Ada 83 tasking in the same program, since the two run times are
-not compatible.
+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 DEC Ada, a task stack is allocated each time a
-non passive task is activated. As soon as the task is
+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 T'STORAGE_SIZE,
+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. According to
-the Ada 95 rules, it provides the pragma STORAGE_SIZE as
+GNAT handles task stacks in a similar manner. In accordance with
+the Ada 95 rules, it provides the pragma @code{STORAGE_SIZE} as
an alternative method for controlling the task stack size.
-The specification of the attribute T'STORAGE_SIZE is also
-supported in a manner compatible with DEC Ada.
+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 DEC Ada, external interrupts can be associated with task entries.
-GNAT is compatible with DEC Ada in its handling of external interrupts.
+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 DEC Ada and GNAT supply all language-defined pragmas
+Both HP Ada and GNAT supply all language-defined pragmas
as specified by the Ada 83 standard. GNAT also supplies all
language-defined pragmas specified in the Ada 95 Reference Manual.
In addition, GNAT implements the implementation-defined pragmas
-from DEC Ada 83.
+from HP Ada 83.
@itemize @bullet
-@item AST_ENTRY
+@item @code{AST_ENTRY}
-@item COMMON_OBJECT
+@item @code{COMMON_OBJECT}
-@item COMPONENT_ALIGNMENT
+@item @code{COMPONENT_ALIGNMENT}
-@item EXPORT_EXCEPTION
+@item @code{EXPORT_EXCEPTION}
-@item EXPORT_FUNCTION
+@item @code{EXPORT_FUNCTION}
-@item EXPORT_OBJECT
+@item @code{EXPORT_OBJECT}
-@item EXPORT_PROCEDURE
+@item @code{EXPORT_PROCEDURE}
-@item EXPORT_VALUED_PROCEDURE
+@item @code{EXPORT_VALUED_PROCEDURE}
-@item FLOAT_REPRESENTATION
+@item @code{FLOAT_REPRESENTATION}
-@item IDENT
+@item @code{IDENT}
-@item IMPORT_EXCEPTION
+@item @code{IMPORT_EXCEPTION}
-@item IMPORT_FUNCTION
+@item @code{IMPORT_FUNCTION}
-@item IMPORT_OBJECT
+@item @code{IMPORT_OBJECT}
-@item IMPORT_PROCEDURE
+@item @code{IMPORT_PROCEDURE}
-@item IMPORT_VALUED_PROCEDURE
+@item @code{IMPORT_VALUED_PROCEDURE}
-@item INLINE_GENERIC
+@item @code{INLINE_GENERIC}
-@item INTERFACE_NAME
+@item @code{INTERFACE_NAME}
-@item LONG_FLOAT
+@item @code{LONG_FLOAT}
-@item MAIN_STORAGE
+@item @code{MAIN_STORAGE}
-@item PASSIVE
+@item @code{PASSIVE}
-@item PSET_OBJECT
+@item @code{PSET_OBJECT}
-@item SHARE_GENERIC
+@item @code{SHARE_GENERIC}
-@item SUPPRESS_ALL
+@item @code{SUPPRESS_ALL}
-@item TASK_STORAGE
+@item @code{TASK_STORAGE}
-@item TIME_SLICE
+@item @code{TIME_SLICE}
-@item TITLE
+@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
+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
+effect in GNAT. The effect of @code{PASSIVE} may be obtained by the
use of protected objects in Ada 95. In GNAT, all generics are inlined.
-Unlike DEC Ada, the GNAT 'EXPORT_@i{subprogram}' pragmas require
+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 C_PASS_BY_COPY
+@item @code{ABORT_DEFER}
-@item EXTEND_SYSTEM
+@item @code{ADA_83}
-@item SOURCE_FILE_NAME
+@item @code{ADA_95}
-@item UNSUPPRESS
+@item @code{ADA_05}
-@item WARNINGS
+@item @code{ANNOTATE}
-@item ABORT_DEFER
+@item @code{ASSERT}
-@item ADA_83
+@item @code{C_PASS_BY_COPY}
-@item ADA_95
+@item @code{CPP_CLASS}
-@item ANNOTATE
+@item @code{CPP_CONSTRUCTOR}
-@item ASSERT
+@item @code{CPP_DESTRUCTOR}
-@item CPP_CLASS
+@item @code{CPP_VIRTUAL}
-@item CPP_CONSTRUCTOR
+@item @code{CPP_VTABLE}
-@item CPP_DESTRUCTOR
+@item @code{DEBUG}
-@item CPP_VIRTUAL
+@item @code{EXTEND_SYSTEM}
-@item CP_VTABLE
+@item @code{LINKER_ALIAS}
-@item DEBUG
+@item @code{LINKER_SECTION}
-@item LINKER_ALIAS
+@item @code{MACHINE_ATTRIBUTE}
-@item LINKER_SECTION
+@item @code{NO_RETURN}
-@item MACHINE_ATTRIBUTE
+@item @code{PURE_FUNCTION}
-@item NO_RETURN
+@item @code{SOURCE_FILE_NAME}
-@item PURE_FUNCTION
+@item @code{SOURCE_REFERENCE}
-@item SOURCE_REFERENCE
+@item @code{TASK_INFO}
-@item TASK_INFO
+@item @code{UNCHECKED_UNION}
-@item UNCHECKED_UNION
+@item @code{UNIMPLEMENTED_UNIT}
-@item UNIMPLEMENTED_UNIT
+@item @code{UNIVERSAL_DATA}
-@item UNIVERSAL_DATA
+@item @code{UNSUPPRESS}
-@item WEAK_EXTERNAL
+@item @code{WARNINGS}
+
+@item @code{WEAK_EXTERNAL}
@end itemize
@noindent
@end menu
@node Restrictions on the Pragma INLINE
-@subsection Restrictions on the Pragma INLINE
+@subsection Restrictions on Pragma @code{INLINE}
@noindent
-DEC Ada applies the following restrictions to the pragma INLINE:
+HP Ada enforces the following restrictions on the pragma @code{INLINE}:
@itemize @bullet
-@item Parameters cannot be a task type.
+@item Parameters cannot have a task type.
@item Function results cannot be task types, unconstrained
array types, or unconstrained types with discriminants.
@end itemize
@noindent
-In GNAT, the only restriction on pragma INLINE is that the
+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 the Pragma INTERFACE
+@subsection Restrictions on Pragma @code{INTERFACE}
@noindent
-The following lists and describes the restrictions on the
-pragma INTERFACE on DEC Ada and GNAT:
+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 EXPORT pragma.
+mechanisms but can be overridden with an @code{EXPORT} pragma.
@itemize @bullet
@item Ada: Use internal Ada rules.
record or task type. Result cannot be a string, an
array, or a record.
-@item Fortran: Parameters cannot be a task. Result cannot
+@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 DEC Ada, and in addition allows
+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 the Pragma SYSTEM_NAME
+@subsection Restrictions on Pragma @code{SYSTEM_NAME}
@noindent
-For DEC Ada for OpenVMS Alpha, the enumeration literal
-for the type NAME is OPENVMS_AXP. In GNAT, the enumeration
-literal for the type NAME is SYSTEM_NAME_GNAT.
+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
-DEC Ada and GNAT implementations. DEC Ada does not provide
-the package MACHINE_CODE but instead recommends importing
+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 DEC Ada Run-Time Library (ADA$PREDEFINED:)
+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. During GNAT installation, the DEC Ada Predefined
-Library units are copied into the GNU:[LIB.OPENVMS7_x.2_8_x.DECLIB]
-(aka DECLIB) directory and patched to remove Ada 95 incompatibilities
-and to make them interoperable with GNAT, @pxref{Changes to DECLIB}
-for details.
+version.
+The HP Ada Predefined Library units are modified to remove Ada 95
+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 GNU:[LIB.OPENVMS7_x.2_8_x.ADALIB] (aka ADALIB) directory and
-the default search path is set up to find DECLIB units in preference
-to ADALIB units with the same name (TEXT_IO, SEQUENTIAL_IO, and DIRECT_IO,
-for example).
-However, it is possible to change the default so that the
-reverse is true, or even to mix them using child package
-notation. The DEC Ada 83 units are available as DEC.xxx where xxx
-is the package name, and the Ada units are available in the
-standard manner defined for Ada 95, that is to say as Ada.xxx. To
-change the default, set ADA_INCLUDE_PATH and ADA_OBJECTS_PATH
-appropriately. For example, to change the default to use the Ada95
-versions do:
+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).
-@smallexample
-$ DEFINE ADA_INCLUDE_PATH GNU:[LIB.OPENVMS7_1.2_8_1.ADAINCLUDE],-
- GNU:[LIB.OPENVMS7_1.2_8_1.DECLIB]
-$ DEFINE ADA_OBJECTS_PATH GNU:[LIB.OPENVMS7_1.2_8_1.ADALIB],-
- GNU:[LIB.OPENVMS7_1.2_8_1.DECLIB]
-@end smallexample
@menu
* Changes to DECLIB::
@end menu
@node Changes to DECLIB
-@subsection Changes to DECLIB
+@subsection Changes to @code{DECLIB}
@noindent
-The changes made to the DEC Ada predefined library for GNAT and Ada 95
+The changes made to the HP Ada predefined library for GNAT and Ada 95
compatibility are minor and include the following:
@itemize @bullet
@item Adding the proper notation to generic formal parameters
that take unconstrained types in instantiation
-@item Adding pragma ELABORATE_BODY to package specifications
+@item Adding pragma @code{ELABORATE_BODY} to package specifications
that have package bodies not otherwise allowed
-@item Occurrences of the identifier @code{"PROTECTED"} are renamed to
-@code{"PROTECTD"}.
-Currently these are found only in the STARLET package spec.
+@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
@section Bindings
@noindent
-On OpenVMS Alpha, DEC Ada provides the following strongly-typed bindings:
+On OpenVMS Alpha, HP Ada provides the following strongly-typed bindings:
@itemize @bullet
@item Command Language Interpreter (CLI interface)
@end itemize
@noindent
-GNAT provides implementations of these DEC bindings in the DECLIB directory.
+GNAT provides implementations of these HP bindings in the @code{DECLIB}
+directory.
-The X/Motif bindings used to build DECLIB are whatever versions are in the
-DEC Ada @file{ADA$PREDEFINED} directory with extension @file{.ADC}.
-The build script will
-automatically add a pragma Linker_Options to packages @code{Xm}, @code{Xt},
-and @code{X_Lib}
+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).
@subsection Shared Libraries and Options Files
@noindent
-When using the DEC Ada
+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
@subsection Interfaces to C
@noindent
-DEC Ada
+HP Ada
provides the following Ada types and operations:
@itemize @bullet
-@item C types package (C_TYPES)
+@item C types package (@code{C_TYPES})
-@item C strings (C_TYPES.NULL_TERMINATED)
+@item C strings (@code{C_TYPES.NULL_TERMINATED})
-@item Other_types (SHORT_INT)
+@item Other_types (@code{SHORT_INT})
@end itemize
@noindent
-Interfacing to C with GNAT, one can use the above approach
-described for DEC Ada or the facilities of Annex B of
-the Ada 95 Reference Manual (packages INTERFACES.C,
-INTERFACES.C.STRINGS and INTERFACES.C.POINTERS). For more
+Interfacing to C with GNAT, you can use the above approach
+described for HP Ada or the facilities of Annex B of
+the Ada 95 Reference Manual (packages @code{INTERFACES.C},
+@code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more
information, see the section ``Interfacing to C'' in the
@cite{GNAT Reference Manual}.
The @option{-gnatF} qualifier forces default and explicit
-@code{External_Name} parameters in pragmas Import and Export
+@code{External_Name} parameters in pragmas @code{Import} and @code{Export}
to be uppercased for compatibility with the default behavior
-of Compaq C. The qualifier has no effect on @code{Link_Name} parameters.
+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 DEC Ada and GNAT.
-On DEC Ada, main programs are defined to meet 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 0 upon
+@item Procedure with no formal parameters (returns @code{0} upon
normal completion)
-@item Procedure with no formal parameters (returns 42 when
- unhandled exceptions are raised)
+@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 OUT formal of a discrete type for
- which a specification of pragma EXPORT_VALUED_PROCEDURE is given.
+@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 EXPORT_VALUED_PROCEDURE,
+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, parameter-less subprogram that
+@item Must be a non-generic, parameterless subprogram that
is either a procedure or function returning an Ada
-STANDARD.INTEGER (the predefined type)
+@code{STANDARD.INTEGER} (the predefined type)
@item Cannot be a generic subprogram or an instantiation of a
generic subprogram
@section Implementation-Defined Attributes
@noindent
-GNAT provides all DEC Ada implementation-defined
+GNAT provides all HP Ada implementation-defined
attributes.
@node Compiler and Run-Time Interfacing
@section Compiler and Run-Time Interfacing
@noindent
-DEC Ada provides the following ways to pass options to the linker
+HP Ada provides the following qualifiers to pass options to the linker
(ACS LINK):
@itemize @bullet
-@item /WAIT and /SUBMIT qualifiers
+@item @option{/WAIT} and @option{/SUBMIT}
-@item /COMMAND qualifier
+@item @option{/COMMAND}
-@item /[NO]MAP qualifier
+@item @option{/[NO]MAP}
-@item /OUTPUT=file-spec
+@item @option{/OUTPUT=@i{file-spec}}
-@item /[NO]DEBUG and /[NO]TRACEBACK qualifiers
+@item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK}
@end itemize
@noindent
switches:
@itemize @bullet
-@item @option{/EXECUTABLE=exec-name}
+@item @option{/EXECUTABLE=@i{exec-name}}
-@item @option{/VERBOSE qualifier}
+@item @option{/VERBOSE}
-@item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK} qualifiers
+@item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK}
@end itemize
@noindent
For more information on these switches, see
@ref{Switches for gnatlink}.
-In DEC Ada, the command-line switch @option{/OPTIMIZE} is available
-to control optimization. DEC Ada also supplies the
+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}
@noindent
In GNAT, optimization is controlled strictly by command
line parameters, as described in the corresponding section of this guide.
-The DIGITAL pragmas for control of optimization are
+The HP pragmas for control of optimization are
recognized but ignored.
-Note that in GNAT, the default is optimization off, whereas in DEC Ada 83,
+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
-DEC Ada and GNAT provide a comparable set of commands to
-build programs. DEC Ada also provides a program library,
+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 DEC Ada commands and provides
+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
Fortran. Therefore, standard system file commands are used
to manipulate these elements. Those GNAT commands are marked with
an asterisk.
-Note that, unlike DEC Ada, none of the GNAT commands accepts wild cards.
+Note that, unlike HP Ada, none of the GNAT commands accepts wild cards.
@need 1500
@multitable @columnfractions .35 .65
-@item @emph{DEC Ada Command}
+@item @emph{HP Ada Command}
@tab @emph{GNAT Equivalent / Description}
@item @command{ADA}
@section Input-Output
@noindent
-On OpenVMS Alpha systems, DEC Ada uses OpenVMS Record
+On OpenVMS Alpha systems, HP Ada uses OpenVMS Record
Management Services (RMS) to perform operations on
external files.
@noindent
-DEC Ada and GNAT predefine an identical set of input-
+HP Ada and GNAT predefine an identical set of input-
output packages. To make the use of the
-generic TEXT_IO operations more convenient, DEC Ada
+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.
@end multitable
@noindent
-The DEC Ada predefined packages and their operations
-are implemented using OpenVMS Alpha files and input-
-output facilities. DEC Ada supports asynchronous input-
-output on OpenVMS Alpha. Familiarity with the following is
-recommended:
+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
@noindent
GNAT provides I/O facilities that are completely
-compatible with DEC Ada. The distribution includes the
-standard DEC Ada versions of all I/O packages, operating
-in a manner compatible with DEC Ada. In particular, the
-following packages are by default the DEC Ada (Ada 83)
+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 95 Reference Manual:
+suggested in Annex J of the Ada 95 Reference Manual:
@itemize @bullet
@item @code{TEXT_IO}
The use of the standard Ada 95 syntax for child packages (for
example, @code{ADA.TEXT_IO}) retrieves the Ada 95 versions of these
packages, as defined in the Ada 95 Reference Manual.
-GNAT provides DIGITAL-compatible predefined instantiations
+GNAT provides HP-compatible predefined instantiations
of the @code{TEXT_IO} packages, and also
provides the standard predefined instantiations required
by the Ada 95 Reference Manual.
@section Implementation Limits
@noindent
-The following table lists implementation limits for DEC Ada
+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{DEC Ada}
+@tab @emph{HP Ada}
@tab @emph{GNAT}
@sp 1
@tab 2**31-1
@end multitable
-@node Tools
-@section Tools
+@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 /}{Product with HP Ada}{Product with GNAT Pro}
+@item @i{Tool}
+ @tab @i{Product with HP Ada}
+ @tab @i{Product 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
@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.
+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{FSU threads library}, a binding to the Florida State University
-threads implementation, which complies fully with the requirements of Annex D
-
@item @b{pthreads library} (Sparc Solaris only), a binding to the Solaris
POSIX thread package
@end itemize
@menu
* Summary of Run-Time Configurations::
* Specifying a Run-Time Library::
-* Choosing between Native and FSU Threads Libraries::
* Choosing the Scheduling Policy::
* Solaris-Specific Considerations::
-* IRIX-Specific Considerations::
* Linux-Specific Considerations::
+* AIX-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 threads library
+@item @code{@ @ @ @ }Tasking @tab native HP-UX threads
@item @code{@ @ @ @ }Exceptions @tab ZCX
@*
@item @code{@ @ }@i{rts-sjlj}
-@item @code{@ @ @ @ }Tasking @tab native HP threads library
+@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-fsu} @tab
-@item @code{@ @ @ @ }Tasking @tab FSU threads library
-@item @code{@ @ @ @ }Exceptions @tab SJLJ
-@*
@item @code{@ @ }@i{rts-m64}
@item @code{@ @ @ @ }Tasking @tab native Solaris threads library
@item @code{@ @ @ @ }Exceptions @tab ZCX
@item @tab @xref{Building and Debugging 64-bit Applications}, for details.
@*
@item @code{@ @ }@i{rts-pthread}
-@item @code{@ @ @ @ }Tasking @tab pthreads library
+@item @code{@ @ @ @ }Tasking @tab pthread library
@item @code{@ @ @ @ }Exceptions @tab ZCX
@*
@item @code{@ @ }@i{rts-sjlj}
@*
@item @b{x86-linux}
@item @code{@ @ }@i{rts-native (default)}
-@item @code{@ @ @ @ }Tasking @tab LinuxThread library
+@item @code{@ @ @ @ }Tasking @tab pthread library
@item @code{@ @ @ @ }Exceptions @tab ZCX
@*
-@item @code{@ @ }@i{rts-fsu}
-@item @code{@ @ @ @ }Tasking @tab FSU threads library
+@item @code{@ @ }@i{rts-sjlj}
+@item @code{@ @ @ @ }Tasking @tab pthread library
@item @code{@ @ @ @ }Exceptions @tab SJLJ
@*
-@item @code{@ @ }@i{rts-sjlj}
-@item @code{@ @ @ @ }Tasking @tab LinuxThread library
+@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-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_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
| | |
| +--- adalib <----+
|
- +--- rts-fsu
- | |
- | +--- adainclude
- | |
- | +--- adalib
- |
+--- rts-sjlj
|
+--- adainclude
@end smallexample
@noindent
-If the @i{rts-fsu} library is to be selected on a permanent basis,
+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-fsu/adainclude adainclude
-$ ln -s rts-fsu/adalib adalib
+$ ln -s rts-sjlj/adainclude adainclude
+$ ln -s rts-sjlj/adalib adalib
@end smallexample
@noindent
-Alternatively, you can specify @file{rts-fsu/adainclude} in the file
-@file{$target/ada_source_path} and @file{rts-fsu/adalib} in
+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
Set the environment variables:
@smallexample
-$ ADA_INCLUDE_PATH=$target/rts-fsu/adainclude:$ADA_INCLUDE_PATH
-$ ADA_OBJECTS_PATH=$target/rts-fsu/adalib:$ADA_OBJECTS_PATH
+$ ADA_INCLUDE_PATH=$target/rts-sjlj/adainclude:$ADA_INCLUDE_PATH
+$ ADA_OBJECTS_PATH=$target/rts-sjlj/adalib:$ADA_OBJECTS_PATH
$ export ADA_INCLUDE_PATH ADA_OBJECTS_PATH
@end smallexample
@item
-Use @option{-aI$target/rts-fsu/adainclude}
-and @option{-aO$target/rts-fsu/adalib}
+Use @option{-aI$target/rts-sjlj/adainclude}
+and @option{-aO$target/rts-sjlj/adalib}
on the @command{gnatmake} command line
@item
-Use the switch @option{--RTS}; e.g., @option{--RTS=fsu}
+Use the switch @option{--RTS}; e.g., @option{--RTS=sjlj}
@cindex @option{--RTS} option
@end itemize
-@noindent
-You can similarly switch to @emph{rts-sjlj}.
-
-@node Choosing between Native and FSU Threads Libraries
-@section Choosing between Native and FSU Threads Libraries
-@cindex Native threads library
-@cindex FSU threads library
-
-@noindent
-Some GNAT implementations offer a choice between
-native threads and FSU threads.
-
-@itemize @bullet
-@item
-The @emph{native threads} library correspond to the standard system threads
-implementation (e.g. LinuxThreads on GNU/Linux,
-@cindex LinuxThreads library
-POSIX threads on AIX, or
-Solaris threads on Solaris). When this option is chosen, GNAT provides
-a full and accurate implementation of the core language tasking model
-as described in Chapter 9 of the Ada Reference Manual,
-but might not (and probably does not) implement
-the exact semantics as specified in @w{Annex D} (the Real-Time Systems Annex).
-@cindex Annex D (Real-Time Systems Annex) compliance
-@cindex Real-Time Systems Annex compliance
-Indeed, the reason that a choice of libraries is offered
-on a given target is because some of the
-ACATS tests for @w{Annex D} fail using the native threads library.
-As far as possible, this library is implemented
-in accordance with Ada semantics (e.g., modifying priorities as required
-to simulate ceiling locking),
-but there are often slight inaccuracies, most often in the area of
-absolutely respecting the priority rules on a single
-processor.
-Moreover, it is not possible in general to define the exact behavior,
-because the native threads implementations
-are not well enough documented.
-
-On systems where the @code{SCHED_FIFO} POSIX scheduling policy is supported,
-@cindex POSIX scheduling policies
-@cindex @code{SCHED_FIFO} scheduling policy
-native threads will provide a behavior very close to the @w{Annex D}
-requirements (i.e., a run-till-blocked scheduler with fixed priorities), but
-on some systems (in particular GNU/Linux and Solaris), you need to have root
-privileges to use the @code{SCHED_FIFO} policy.
-
-@item
-The @emph{FSU threads} library provides a completely accurate implementation
-of @w{Annex D}.
-Thus, operating with this library, GNAT is 100% compliant with both the core
-and all @w{Annex D}
-requirements.
-The formal validations for implementations offering
-a choice of threads packages are always carried out using the FSU
-threads option.
-@end itemize
-
-@noindent
-From these considerations, it might seem that FSU threads are the
-better choice,
-but that is by no means always the case. The FSU threads package
-operates with all Ada tasks appearing to the system to be a single
-thread. This is often considerably more efficient than operating
-with separate threads, since for example, switching between tasks
-can be accomplished without the (in some cases considerable)
-overhead of a context switch between two system threads. However,
-it means that you may well lose concurrency at the system
-level. Notably, some system operations (such as I/O) may block all
-tasks in a program and not just the calling task. More
-significantly, the FSU threads approach likely means you cannot
-take advantage of multiple processors, since for this you need
-separate threads (or even separate processes) to operate on
-different processors.
-
-For most programs, the native threads library is
-usually the better choice. Use the FSU threads if absolute
-conformance to @w{Annex D} is important for your application, or if
-you find that the improved efficiency of FSU threads is significant to you.
-
-Note also that to take full advantage of Florist and Glade, it is highly
-recommended that you use native threads.
-
-
@node Choosing the Scheduling Policy
@section Choosing the Scheduling Policy
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
* Building and Debugging 64-bit Applications::
@end menu
-
@node Solaris Threads Issues
@subsection Solaris Threads Issues
@noindent
-Starting with version 3.14, GNAT under Solaris comes with a new tasking
-run-time library based on POSIX threads --- @emph{rts-pthread}.
+GNAT under Solaris 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
As explained above, the native run-time library is based on the Solaris thread
library (@code{libthread}) and is the default library.
-The FSU run-time library is based on the FSU threads.
-@cindex FSU threads library
-Starting with Solaris 2.5.1, when the Solaris threads library is used
-(this is the default), programs
+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
(where @code{_SC_NPROCESSORS_CONF} is a system variable).
@end table
-
@node Building and Debugging 64-bit Applications
@subsection Building and Debugging 64-bit Applications
The easiest way to build a 64bit application is to add
@option{-m64 --RTS=m64} to the @command{gnatmake} flags.
-To debug these applications, dwarf-2 debug information is required, so you
-have to add @option{-gdwarf-2} to your gnatmake arguments.
-In addition, a special
-version of gdb, called @command{gdb64}, needs to be used.
+To debug these applications, a special version of gdb called @command{gdb64}
+needs to be used.
To summarize, building and debugging a ``Hello World'' program in 64-bit mode
amounts to:
@smallexample
- $ gnatmake -m64 -gdwarf-2 --RTS=m64 hello.adb
+ $ gnatmake -m64 -g --RTS=m64 hello.adb
$ gdb64 hello
@end smallexample
-
-
-@node IRIX-Specific Considerations
-@section IRIX-Specific Considerations
-@cindex IRIX thread library
-
-@noindent
-On SGI IRIX, the thread library depends on which compiler is used.
-The @emph{o32 ABI} compiler comes with a run-time library based on the
-user-level @code{athread}
-library. Thus kernel-level capabilities such as nonblocking system
-calls or time slicing can only be achieved reliably by specifying different
-@code{sprocs} via the pragma @code{Task_Info}
-@cindex pragma Task_Info (and IRIX threads)
-and the
-@code{System.Task_Info} package.
-@cindex @code{System.Task_Info} package (and IRIX threads)
-See the @cite{GNAT Reference Manual} for further information.
-
-The @emph{n32 ABI} compiler comes with a run-time library based on the
-kernel POSIX threads and thus does not have the limitations mentioned above.
-
-
@node Linux-Specific Considerations
@section Linux-Specific Considerations
@cindex Linux threads libraries
@noindent
-The default thread library under GNU/Linux has the following disadvantages
-compared to other native thread libraries:
+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()}.
-@itemize @bullet
-@item The size of the task's stack is limited to 2 megabytes.
-@item 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()}.
-@end itemize
+@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_Addrss}.
+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.
@c *******************************
@node Example of Binder Output File
file generated for a simple ``Hello World'' program.
Comments have been added for clarification purposes.
-
@smallexample @c adanocomment
@iftex
@leftskip=0cm
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
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 unit in a @code{with}'ed unit,
+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:
@end table
@noindent
-Note that one additional advantage of following our Elaborate_All rule
+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 subprograms. Conversely, if a program that does
+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.
@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 unit
-in a @code{with}'ed unit, then if the @code{with}'ed unit
+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} for the @code{with}'ed unit.}
+@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
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_All}
-pragmas.
+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_All} pragmas. The
+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_All} pragmas so portability to other compilers than
-GNAT is not guaranteed.
+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_All} pragmas.
+to be generated indicating the missing @code{Elaborate} and
+@code{Elaborate_All} pragmas.
Consider the following source program:
@smallexample @c ada
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 Elaborate_All may lead to
+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
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 (@code{gcc} or @code{gnatmake})
-command, or by the use of the configuration pragma:
+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 enumerate
@noindent
-Indeed, if you add an explicit pragma Elaborate_All for @code{Utils} in
+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.
@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_All} pragmas.
-The behavior then is exactly as specified in the Ada 95 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.
+(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 Ada 95 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
example this pragma could be placed in the @file{gnat.adc} file.
@item Suppress checks selectively
-When you know that certain calls in elaboration code cannot possibly
-lead to an elaboration error, and the binder nevertheless generates warnings
-on those calls and inserts 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:
+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
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_All}
-pragmas, and supply the missing pragmas.
+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
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_All} pragmas to ensure the desired order.
-
+@code{Elaborate} or @code{Elaborate_All} pragmas to ensure the desired order.
@node Inline Assembler
@appendix Inline Assembler
* Input Variables in Inline Assembler::
* Inlining Inline Assembler Code::
* Other Asm Functionality::
-* A Complete Example::
@end menu
@c ---------------------------------------------------------------------------
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 ---------------------------------------------------------------------------
-@node A Complete Example
-@section A Complete Example
-
-@noindent
-This section contains a complete program illustrating a realistic usage
-of GNAT's Inline Assembler capabilities. It comprises a main procedure
-@code{Check_CPU} and a package @code{Intel_CPU}.
-The package declares a collection of functions that detect the properties
-of the 32-bit x86 processor that is running the program.
-The main procedure invokes these functions and displays the information.
-
-The Intel_CPU package could be enhanced by adding functions to
-detect the type of x386 co-processor, the processor caching options and
-special operations such as the SIMD extensions.
-
-Although the Intel_CPU package has been written for 32-bit Intel
-compatible CPUs, it is OS neutral. It has been tested on DOS,
-Windows/NT and GNU/Linux.
-
-@menu
-* Check_CPU Procedure::
-* Intel_CPU Package Specification::
-* Intel_CPU Package Body::
-@end menu
-
-@c ---------------------------------------------------------------------------
-@node Check_CPU Procedure
-@subsection @code{Check_CPU} Procedure
-@cindex Check_CPU procedure
-
-@smallexample @c adanocomment
----------------------------------------------------------------------
--- --
--- Uses the Intel_CPU package to identify the CPU the program is --
--- running on, and some of the features it supports. --
--- --
----------------------------------------------------------------------
-
-with Intel_CPU; -- Intel CPU detection functions
-with Ada.Text_IO; -- Standard text I/O
-with Ada.Command_Line; -- To set the exit status
-
-procedure Check_CPU is
-
- Type_Found : Boolean := False;
- -- Flag to indicate that processor was identified
-
- Features : Intel_CPU.Processor_Features;
- -- The processor features
-
- Signature : Intel_CPU.Processor_Signature;
- -- The processor type signature
-
-begin
-
- -----------------------------------
- -- Display the program banner. --
- -----------------------------------
-
- Ada.Text_IO.Put_Line (Ada.Command_Line.Command_Name &
- ": check Intel CPU version and features, v1.0");
- Ada.Text_IO.Put_Line ("distribute freely, but no warranty whatsoever");
- Ada.Text_IO.New_Line;
-
- -----------------------------------------------------------------------
- -- We can safely start with the assumption that we are on at least --
- -- a x386 processor. If the CPUID instruction is present, then we --
- -- have a later processor type. --
- -----------------------------------------------------------------------
-
- if Intel_CPU.Has_CPUID = False then
-
- -- No CPUID instruction, so we assume this is indeed a x386
- -- processor. We can still check if it has a FP co-processor.
- if Intel_CPU.Has_FPU then
- Ada.Text_IO.Put_Line
- ("x386-type processor with a FP co-processor");
- else
- Ada.Text_IO.Put_Line
- ("x386-type processor without a FP co-processor");
- end if; -- check for FPU
-
- -- Program done
- Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success);
- return;
-
- end if; -- check for CPUID
-
- -----------------------------------------------------------------------
- -- If CPUID is supported, check if this is a true Intel processor, --
- -- if it is not, display a warning. --
- -----------------------------------------------------------------------
-
- if Intel_CPU.Vendor_ID /= Intel_CPU.Intel_Processor then
- Ada.Text_IO.Put_Line ("*** This is a Intel compatible processor");
- Ada.Text_IO.Put_Line ("*** Some information may be incorrect");
- end if; -- check if Intel
-
- ----------------------------------------------------------------------
- -- With the CPUID instruction present, we can assume at least a --
- -- x486 processor. If the CPUID support level is < 1 then we have --
- -- to leave it at that. --
- ----------------------------------------------------------------------
-
- if Intel_CPU.CPUID_Level < 1 then
-
- -- Ok, this is a x486 processor. we still can get the Vendor ID
- Ada.Text_IO.Put_Line ("x486-type processor");
- Ada.Text_IO.Put_Line ("Vendor ID is " & Intel_CPU.Vendor_ID);
-
- -- We can also check if there is a FPU present
- if Intel_CPU.Has_FPU then
- Ada.Text_IO.Put_Line ("Floating-Point support");
- else
- Ada.Text_IO.Put_Line ("No Floating-Point support");
- end if; -- check for FPU
-
- -- Program done
- Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success);
- return;
-
- end if; -- check CPUID level
-
- ---------------------------------------------------------------------
- -- With a CPUID level of 1 we can use the processor signature to --
- -- determine it's exact type. --
- ---------------------------------------------------------------------
-
- Signature := Intel_CPU.Signature;
-
- ----------------------------------------------------------------------
- -- Ok, now we go into a lot of messy comparisons to get the --
- -- processor type. For clarity, no attememt to try to optimize the --
- -- comparisons has been made. Note that since Intel_CPU does not --
- -- support getting cache info, we cannot distinguish between P5 --
- -- and Celeron types yet. --
- ----------------------------------------------------------------------
-
- -- x486SL
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0100# and
- Signature.Model = 2#0100# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("x486SL processor");
- end if;
-
- -- x486DX2 Write-Back
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0100# and
- Signature.Model = 2#0111# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("Write-Back Enhanced x486DX2 processor");
- end if;
-
- -- x486DX4
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0100# and
- Signature.Model = 2#1000# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("x486DX4 processor");
- end if;
-
- -- x486DX4 Overdrive
- if Signature.Processor_Type = 2#01# and
- Signature.Family = 2#0100# and
- Signature.Model = 2#1000# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("x486DX4 OverDrive processor");
- end if;
-
- -- Pentium (60, 66)
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0101# and
- Signature.Model = 2#0001# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("Pentium processor (60, 66)");
- end if;
-
- -- Pentium (75, 90, 100, 120, 133, 150, 166, 200)
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0101# and
- Signature.Model = 2#0010# then
- Type_Found := True;
- Ada.Text_IO.Put_Line
- ("Pentium processor (75, 90, 100, 120, 133, 150, 166, 200)");
- end if;
-
- -- Pentium OverDrive (60, 66)
- if Signature.Processor_Type = 2#01# and
- Signature.Family = 2#0101# and
- Signature.Model = 2#0001# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("Pentium OverDrive processor (60, 66)");
- end if;
-
- -- Pentium OverDrive (75, 90, 100, 120, 133, 150, 166, 200)
- if Signature.Processor_Type = 2#01# and
- Signature.Family = 2#0101# and
- Signature.Model = 2#0010# then
- Type_Found := True;
- Ada.Text_IO.Put_Line
- ("Pentium OverDrive cpu (75, 90, 100, 120, 133, 150, 166, 200)");
- end if;
-
- -- Pentium OverDrive processor for x486 processor-based systems
- if Signature.Processor_Type = 2#01# and
- Signature.Family = 2#0101# and
- Signature.Model = 2#0011# then
- Type_Found := True;
- Ada.Text_IO.Put_Line
- ("Pentium OverDrive processor for x486 processor-based systems");
- end if;
-
- -- Pentium processor with MMX technology (166, 200)
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0101# and
- Signature.Model = 2#0100# then
- Type_Found := True;
- Ada.Text_IO.Put_Line
- ("Pentium processor with MMX technology (166, 200)");
- end if;
-
- -- Pentium OverDrive with MMX for Pentium (75, 90, 100, 120, 133)
- if Signature.Processor_Type = 2#01# and
- Signature.Family = 2#0101# and
- Signature.Model = 2#0100# then
- Type_Found := True;
- Ada.Text_IO.Put_Line
- ("Pentium OverDrive processor with MMX " &
- "technology for Pentium processor (75, 90, 100, 120, 133)");
- end if;
-
- -- Pentium Pro processor
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0110# and
- Signature.Model = 2#0001# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("Pentium Pro processor");
- end if;
-
- -- Pentium II processor, model 3
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0110# and
- Signature.Model = 2#0011# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("Pentium II processor, model 3");
- end if;
-
- -- Pentium II processor, model 5 or Celeron processor
- if Signature.Processor_Type = 2#00# and
- Signature.Family = 2#0110# and
- Signature.Model = 2#0101# then
- Type_Found := True;
- Ada.Text_IO.Put_Line
- ("Pentium II processor, model 5 or Celeron processor");
- end if;
-
- -- Pentium Pro OverDrive processor
- if Signature.Processor_Type = 2#01# and
- Signature.Family = 2#0110# and
- Signature.Model = 2#0011# then
- Type_Found := True;
- Ada.Text_IO.Put_Line ("Pentium Pro OverDrive processor");
- end if;
-
- -- If no type recognized, we have an unknown. Display what
- -- we _do_ know
- if Type_Found = False then
- Ada.Text_IO.Put_Line ("Unknown processor");
- end if;
-
- -----------------------------------------
- -- Display processor stepping level. --
- -----------------------------------------
-
- Ada.Text_IO.Put_Line ("Stepping level:" & Signature.Stepping'Img);
-
- ---------------------------------
- -- Display vendor ID string. --
- ---------------------------------
-
- Ada.Text_IO.Put_Line ("Vendor ID: " & Intel_CPU.Vendor_ID);
-
- ------------------------------------
- -- Get the processors features. --
- ------------------------------------
-
- Features := Intel_CPU.Features;
-
- -----------------------------
- -- Check for a FPU unit. --
- -----------------------------
-
- if Features.FPU = True then
- Ada.Text_IO.Put_Line ("Floating-Point unit available");
- else
- Ada.Text_IO.Put_Line ("no Floating-Point unit");
- end if; -- check for FPU
-
- --------------------------------
- -- List processor features. --
- --------------------------------
-
- Ada.Text_IO.Put_Line ("Supported features: ");
-
- -- Virtual Mode Extension
- if Features.VME = True then
- Ada.Text_IO.Put_Line (" VME - Virtual Mode Extension");
- end if;
-
- -- Debugging Extension
- if Features.DE = True then
- Ada.Text_IO.Put_Line (" DE - Debugging Extension");
- end if;
-
- -- Page Size Extension
- if Features.PSE = True then
- Ada.Text_IO.Put_Line (" PSE - Page Size Extension");
- end if;
-
- -- Time Stamp Counter
- if Features.TSC = True then
- Ada.Text_IO.Put_Line (" TSC - Time Stamp Counter");
- end if;
-
- -- Model Specific Registers
- if Features.MSR = True then
- Ada.Text_IO.Put_Line (" MSR - Model Specific Registers");
- end if;
-
- -- Physical Address Extension
- if Features.PAE = True then
- Ada.Text_IO.Put_Line (" PAE - Physical Address Extension");
- end if;
-
- -- Machine Check Extension
- if Features.MCE = True then
- Ada.Text_IO.Put_Line (" MCE - Machine Check Extension");
- end if;
-
- -- CMPXCHG8 instruction supported
- if Features.CX8 = True then
- Ada.Text_IO.Put_Line (" CX8 - CMPXCHG8 instruction");
- end if;
-
- -- on-chip APIC hardware support
- if Features.APIC = True then
- Ada.Text_IO.Put_Line (" APIC - on-chip APIC hardware support");
- end if;
-
- -- Fast System Call
- if Features.SEP = True then
- Ada.Text_IO.Put_Line (" SEP - Fast System Call");
- end if;
-
- -- Memory Type Range Registers
- if Features.MTRR = True then
- Ada.Text_IO.Put_Line (" MTTR - Memory Type Range Registers");
- end if;
-
- -- Page Global Enable
- if Features.PGE = True then
- Ada.Text_IO.Put_Line (" PGE - Page Global Enable");
- end if;
-
- -- Machine Check Architecture
- if Features.MCA = True then
- Ada.Text_IO.Put_Line (" MCA - Machine Check Architecture");
- end if;
-
- -- Conditional Move Instruction Supported
- if Features.CMOV = True then
- Ada.Text_IO.Put_Line
- (" CMOV - Conditional Move Instruction Supported");
- end if;
-
- -- Page Attribute Table
- if Features.PAT = True then
- Ada.Text_IO.Put_Line (" PAT - Page Attribute Table");
- end if;
-
- -- 36-bit Page Size Extension
- if Features.PSE_36 = True then
- Ada.Text_IO.Put_Line (" PSE_36 - 36-bit Page Size Extension");
- end if;
-
- -- MMX technology supported
- if Features.MMX = True then
- Ada.Text_IO.Put_Line (" MMX - MMX technology supported");
- end if;
-
- -- Fast FP Save and Restore
- if Features.FXSR = True then
- Ada.Text_IO.Put_Line (" FXSR - Fast FP Save and Restore");
- end if;
-
- ---------------------
- -- Program done. --
- ---------------------
-
- Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Success);
-
-exception
-
- when others =>
- Ada.Command_Line.Set_Exit_Status (Ada.Command_Line.Failure);
- raise;
-
-end Check_CPU;
-@end smallexample
-
-@c ---------------------------------------------------------------------------
-@node Intel_CPU Package Specification
-@subsection @code{Intel_CPU} Package Specification
-@cindex Intel_CPU package specification
-
-@smallexample @c adanocomment
--------------------------------------------------------------------------
--- --
--- file: intel_cpu.ads --
--- --
--- ********************************************* --
--- * WARNING: for 32-bit Intel processors only * --
--- ********************************************* --
--- --
--- This package contains a number of subprograms that are useful in --
--- determining the Intel x86 CPU (and the features it supports) on --
--- which the program is running. --
--- --
--- The package is based upon the information given in the Intel --
--- Application Note AP-485: "Intel Processor Identification and the --
--- CPUID Instruction" as of April 1998. This application note can be --
--- found on www.intel.com. --
--- --
--- It currently deals with 32-bit processors only, will not detect --
--- features added after april 1998, and does not guarantee proper --
--- results on Intel-compatible processors. --
--- --
--- Cache info and x386 fpu type detection are not supported. --
--- --
--- This package does not use any privileged instructions, so should --
--- work on any OS running on a 32-bit Intel processor. --
--- --
--------------------------------------------------------------------------
-
-with Interfaces; use Interfaces;
--- for using unsigned types
-
-with System.Machine_Code; use System.Machine_Code;
--- for using inline assembler code
-
-with Ada.Characters.Latin_1; use Ada.Characters.Latin_1;
--- for inserting control characters
-
-package Intel_CPU is
-
- ----------------------
- -- Processor bits --
- ----------------------
-
- subtype Num_Bits is Natural range 0 .. 31;
- -- the number of processor bits (32)
-
- --------------------------
- -- Processor register --
- --------------------------
-
- -- define a processor register type for easy access to
- -- the individual bits
-
- type Processor_Register is array (Num_Bits) of Boolean;
- pragma Pack (Processor_Register);
- for Processor_Register'Size use 32;
-
- -------------------------
- -- Unsigned register --
- -------------------------
-
- -- define a processor register type for easy access to
- -- the individual bytes
-
- type Unsigned_Register is
- record
- L1 : Unsigned_8;
- H1 : Unsigned_8;
- L2 : Unsigned_8;
- H2 : Unsigned_8;
- end record;
-
- for Unsigned_Register use
- record
- L1 at 0 range 0 .. 7;
- H1 at 0 range 8 .. 15;
- L2 at 0 range 16 .. 23;
- H2 at 0 range 24 .. 31;
- end record;
-
- for Unsigned_Register'Size use 32;
-
- ---------------------------------
- -- Intel processor vendor ID --
- ---------------------------------
-
- Intel_Processor : constant String (1 .. 12) := "GenuineIntel";
- -- indicates an Intel manufactured processor
-
- ------------------------------------
- -- Processor signature register --
- ------------------------------------
-
- -- a register type to hold the processor signature
-
- type Processor_Signature is
- record
- Stepping : Natural range 0 .. 15;
- Model : Natural range 0 .. 15;
- Family : Natural range 0 .. 15;
- Processor_Type : Natural range 0 .. 3;
- Reserved : Natural range 0 .. 262143;
- end record;
-
- for Processor_Signature use
- record
- Stepping at 0 range 0 .. 3;
- Model at 0 range 4 .. 7;
- Family at 0 range 8 .. 11;
- Processor_Type at 0 range 12 .. 13;
- Reserved at 0 range 14 .. 31;
- end record;
-
- for Processor_Signature'Size use 32;
-
- -----------------------------------
- -- Processor features register --
- -----------------------------------
-
- -- a processor register to hold the processor feature flags
-
- type Processor_Features is
- record
- FPU : Boolean; -- floating point unit on chip
- VME : Boolean; -- virtual mode extension
- DE : Boolean; -- debugging extension
- PSE : Boolean; -- page size extension
- TSC : Boolean; -- time stamp counter
- MSR : Boolean; -- model specific registers
- PAE : Boolean; -- physical address extension
- MCE : Boolean; -- machine check extension
- CX8 : Boolean; -- cmpxchg8 instruction
- APIC : Boolean; -- on-chip apic hardware
- Res_1 : Boolean; -- reserved for extensions
- SEP : Boolean; -- fast system call
- MTRR : Boolean; -- memory type range registers
- PGE : Boolean; -- page global enable
- MCA : Boolean; -- machine check architecture
- CMOV : Boolean; -- conditional move supported
- PAT : Boolean; -- page attribute table
- PSE_36 : Boolean; -- 36-bit page size extension
- Res_2 : Natural range 0 .. 31; -- reserved for extensions
- MMX : Boolean; -- MMX technology supported
- FXSR : Boolean; -- fast FP save and restore
- Res_3 : Natural range 0 .. 127; -- reserved for extensions
- end record;
-
- for Processor_Features use
- record
- FPU at 0 range 0 .. 0;
- VME at 0 range 1 .. 1;
- DE at 0 range 2 .. 2;
- PSE at 0 range 3 .. 3;
- TSC at 0 range 4 .. 4;
- MSR at 0 range 5 .. 5;
- PAE at 0 range 6 .. 6;
- MCE at 0 range 7 .. 7;
- CX8 at 0 range 8 .. 8;
- APIC at 0 range 9 .. 9;
- Res_1 at 0 range 10 .. 10;
- SEP at 0 range 11 .. 11;
- MTRR at 0 range 12 .. 12;
- PGE at 0 range 13 .. 13;
- MCA at 0 range 14 .. 14;
- CMOV at 0 range 15 .. 15;
- PAT at 0 range 16 .. 16;
- PSE_36 at 0 range 17 .. 17;
- Res_2 at 0 range 18 .. 22;
- MMX at 0 range 23 .. 23;
- FXSR at 0 range 24 .. 24;
- Res_3 at 0 range 25 .. 31;
- end record;
-
- for Processor_Features'Size use 32;
-
- -------------------
- -- Subprograms --
- -------------------
-
- function Has_FPU return Boolean;
- -- return True if a FPU is found
- -- use only if CPUID is not supported
-
- function Has_CPUID return Boolean;
- -- return True if the processor supports the CPUID instruction
-
- function CPUID_Level return Natural;
- -- return the CPUID support level (0, 1 or 2)
- -- can only be called if the CPUID instruction is supported
-
- function Vendor_ID return String;
- -- return the processor vendor identification string
- -- can only be called if the CPUID instruction is supported
-
- function Signature return Processor_Signature;
- -- return the processor signature
- -- can only be called if the CPUID instruction is supported
-
- function Features return Processor_Features;
- -- return the processors features
- -- can only be called if the CPUID instruction is supported
-
-private
-
- ------------------------
- -- EFLAGS bit names --
- ------------------------
-
- ID_Flag : constant Num_Bits := 21;
- -- ID flag bit
-
-end Intel_CPU;
-@end smallexample
-
-@c ---------------------------------------------------------------------------
-@node Intel_CPU Package Body
-@subsection @code{Intel_CPU} Package Body
-@cindex Intel_CPU package body
-
-@smallexample @c adanocomment
-package body Intel_CPU is
-
- ---------------------------
- -- Detect FPU presence --
- ---------------------------
-
- -- There is a FPU present if we can set values to the FPU Status
- -- and Control Words.
-
- function Has_FPU return Boolean is
-
- Register : Unsigned_16;
- -- processor register to store a word
-
- begin
-
- -- check if we can change the status word
- Asm (
-
- -- the assembler code
- "finit" & LF & HT & -- reset status word
- "movw $0x5A5A, %%ax" & LF & HT & -- set value status word
- "fnstsw %0" & LF & HT & -- save status word
- "movw %%ax, %0", -- store status word
-
- -- output stored in Register
- -- register must be a memory location
- Outputs => Unsigned_16'Asm_output ("=m", Register),
-
- -- tell compiler that we used eax
- Clobber => "eax");
-
- -- if the status word is zero, there is no FPU
- if Register = 0 then
- return False; -- no status word
- end if; -- check status word value
-
- -- check if we can get the control word
- Asm (
-
- -- the assembler code
- "fnstcw %0", -- save the control word
-
- -- output into Register
- -- register must be a memory location
- Outputs => Unsigned_16'Asm_output ("=m", Register));
-
- -- check the relevant bits
- if (Register and 16#103F#) /= 16#003F# then
- return False; -- no control word
- end if; -- check control word value
-
- -- FPU found
- return True;
-
- end Has_FPU;
-
- --------------------------------
- -- Detect CPUID instruction --
- --------------------------------
-
- -- The processor supports the CPUID instruction if it is possible
- -- to change the value of ID flag bit in the EFLAGS register.
-
- function Has_CPUID return Boolean is
-
- Original_Flags, Modified_Flags : Processor_Register;
- -- EFLAG contents before and after changing the ID flag
-
- begin
-
- -- try flipping the ID flag in the EFLAGS register
- Asm (
-
- -- the assembler code
- "pushfl" & LF & HT & -- push EFLAGS on stack
- "pop %%eax" & LF & HT & -- pop EFLAGS into eax
- "movl %%eax, %0" & LF & HT & -- save EFLAGS content
- "xor $0x200000, %%eax" & LF & HT & -- flip ID flag
- "push %%eax" & LF & HT & -- push EFLAGS on stack
- "popfl" & LF & HT & -- load EFLAGS register
- "pushfl" & LF & HT & -- push EFLAGS on stack
- "pop %1", -- save EFLAGS content
-
- -- output values, may be anything
- -- Original_Flags is %0
- -- Modified_Flags is %1
- Outputs =>
- (Processor_Register'Asm_output ("=g", Original_Flags),
- Processor_Register'Asm_output ("=g", Modified_Flags)),
-
- -- tell compiler eax is destroyed
- Clobber => "eax");
-
- -- check if CPUID is supported
- if Original_Flags(ID_Flag) /= Modified_Flags(ID_Flag) then
- return True; -- ID flag was modified
- else
- return False; -- ID flag unchanged
- end if; -- check for CPUID
-
- end Has_CPUID;
-
- -------------------------------
- -- Get CPUID support level --
- -------------------------------
-
- function CPUID_Level return Natural is
-
- Level : Unsigned_32;
- -- returned support level
-
- begin
-
- -- execute CPUID, storing the results in the Level register
- Asm (
-
- -- the assembler code
- "cpuid", -- execute CPUID
-
- -- zero is stored in eax
- -- returning the support level in eax
- Inputs => Unsigned_32'Asm_input ("a", 0),
-
- -- eax is stored in Level
- Outputs => Unsigned_32'Asm_output ("=a", Level),
-
- -- tell compiler ebx, ecx and edx registers are destroyed
- Clobber => "ebx, ecx, edx");
-
- -- return the support level
- return Natural (Level);
-
- end CPUID_Level;
-
- --------------------------------
- -- Get CPU Vendor ID String --
- --------------------------------
-
- -- The vendor ID string is returned in the ebx, ecx and edx register
- -- after executing the CPUID instruction with eax set to zero.
- -- In case of a true Intel processor the string returned is
- -- "GenuineIntel"
-
- function Vendor_ID return String is
-
- Ebx, Ecx, Edx : Unsigned_Register;
- -- registers containing the vendor ID string
-
- Vendor_ID : String (1 .. 12);
- -- the vendor ID string
-
- begin
-
- -- execute CPUID, storing the results in the processor registers
- Asm (
-
- -- the assembler code
- "cpuid", -- execute CPUID
-
- -- zero stored in eax
- -- vendor ID string returned in ebx, ecx and edx
- Inputs => Unsigned_32'Asm_input ("a", 0),
-
- -- ebx is stored in Ebx
- -- ecx is stored in Ecx
- -- edx is stored in Edx
- Outputs => (Unsigned_Register'Asm_output ("=b", Ebx),
- Unsigned_Register'Asm_output ("=c", Ecx),
- Unsigned_Register'Asm_output ("=d", Edx)));
-
- -- now build the vendor ID string
- Vendor_ID( 1) := Character'Val (Ebx.L1);
- Vendor_ID( 2) := Character'Val (Ebx.H1);
- Vendor_ID( 3) := Character'Val (Ebx.L2);
- Vendor_ID( 4) := Character'Val (Ebx.H2);
- Vendor_ID( 5) := Character'Val (Edx.L1);
- Vendor_ID( 6) := Character'Val (Edx.H1);
- Vendor_ID( 7) := Character'Val (Edx.L2);
- Vendor_ID( 8) := Character'Val (Edx.H2);
- Vendor_ID( 9) := Character'Val (Ecx.L1);
- Vendor_ID(10) := Character'Val (Ecx.H1);
- Vendor_ID(11) := Character'Val (Ecx.L2);
- Vendor_ID(12) := Character'Val (Ecx.H2);
-
- -- return string
- return Vendor_ID;
-
- end Vendor_ID;
-
- -------------------------------
- -- Get processor signature --
- -------------------------------
-
- function Signature return Processor_Signature is
-
- Result : Processor_Signature;
- -- processor signature returned
-
- begin
-
- -- execute CPUID, storing the results in the Result variable
- Asm (
-
- -- the assembler code
- "cpuid", -- execute CPUID
-
- -- one is stored in eax
- -- processor signature returned in eax
- Inputs => Unsigned_32'Asm_input ("a", 1),
-
- -- eax is stored in Result
- Outputs => Processor_Signature'Asm_output ("=a", Result),
-
- -- tell compiler that ebx, ecx and edx are also destroyed
- Clobber => "ebx, ecx, edx");
-
- -- return processor signature
- return Result;
-
- end Signature;
-
- ------------------------------
- -- Get processor features --
- ------------------------------
-
- function Features return Processor_Features is
-
- Result : Processor_Features;
- -- processor features returned
-
- begin
-
- -- execute CPUID, storing the results in the Result variable
- Asm (
-
- -- the assembler code
- "cpuid", -- execute CPUID
-
- -- one stored in eax
- -- processor features returned in edx
- Inputs => Unsigned_32'Asm_input ("a", 1),
-
- -- edx is stored in Result
- Outputs => Processor_Features'Asm_output ("=d", Result),
-
- -- tell compiler that ebx and ecx are also destroyed
- Clobber => "ebx, ecx");
-
- -- return processor signature
- return Result;
-
- end Features;
-
-end Intel_CPU;
-@end smallexample
+problems.
@c END OF INLINE ASSEMBLER CHAPTER
@c ===============================
-
-
@c ***********************************
@c * Compatibility and Porting Guide *
@c ***********************************
@menu
* Compatibility with Ada 83::
* Implementation-dependent characteristics::
-* Compatibility with DEC Ada 83::
* Compatibility with Other Ada 95 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 from Alpha to I64 OpenVMS::
+@end ifset
@end menu
@node Compatibility with Ada 83
A particular case is that representation pragmas
@ifset vms
(including the
-extended DEC Ada 83 compatibility pragmas such as @code{Export_Procedure})
+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.
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 Ada 83 Programs}.
+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 have been removed from Ada 95,
(@code{Emax}, @code{Mantissa}, etc.), among other items.
@end table
-
@node Implementation-dependent characteristics
@section Implementation-dependent characteristics
@noindent
* Target-specific aspects::
@end menu
-
@node Implementation-defined pragmas
@subsection Implementation-defined pragmas
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 DEC Ada 83, GNAT supplies the pragmas
+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}.
@cite{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 DEC
+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}.
to invoke a subprogram its body has been elaborated, or to instantiate a
generic before the generic body has been elaborated. By default GNAT
attempts to choose a safe order (one that will not encounter access before
-elaboration problems) by implicitly inserting Elaborate_All pragmas where
+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}.
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 95 Systems
@section Compatibility with Other Ada 95 Systems
or a record representation clause for an access field in a record.
@end table
-@node Compatibility with DEC Ada 83
-@section Compatibility with DEC Ada 83
+@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 DEC Ada 83, as well as providing the standard DEC Ada 83
+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 DEC Ada 83 code to GNAT in VMS systems should be easier than
+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 DEC Ada 83.
+significant differences between GNAT and HP Ada 83.
@table @asis
@item Default floating-point representation
-In GNAT, the default floating-point format is IEEE, whereas in DEC Ada 83,
+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
-DEC Ada 83 extensions. However, a separate package Aux_DEC is provided
+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 DEC Ada 83 version of System, with one exception.
-DEC Ada provides the following declarations:
+in the HP Ada 83 version of System, with one exception.
+HP Ada provides the following declarations:
@smallexample @c ada
TO_ADDRESS (INTEGER)
The version of TO_ADDRESS taking a 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 DEC Ada 83, the
+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
@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 DEC Ada 83, there is no ambiguity, since the
+of TO_ADDRESS@. However, in HP Ada 83, there is no ambiguity, since the
definition using universal_integer takes precedence.
In GNAT, since the version with universal_integer cannot be supplied, it is
@end table
For full details on these and other less significant compatibility issues,
-see appendix E of the Digital publication entitled @cite{DEC Ada, Technical
-Overview and Comparison on DIGITAL Platforms}.
+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 DEC Ada 83 pragmas and
+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 this reference manual
+be implemented. The description of pragmas in the
+@cite{GNAT Reference Manual}
indicates whether or not they are applicable to non-VMS systems.
+@end ifclear
+
+@ifset vms
+@node Transitioning from Alpha to I64 OpenVMS
+@section Transitioning from Alpha to I64 OpenVMS
+
+@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 to transitioning
+
+@noindent
+This section is meant to assist users of @value{EDITION}
+for Alpha OpenVMS who are planning to transition to the I64 architecture.
+@value{EDITION} for Open VMS I64 has been designed to meet
+three main goals:
+
+@enumerate
+@item
+Providing a full conforming implementation of the Ada 95 language
+
+@item
+Allowing maximum backward compatibility, thus easing migration of existing
+Ada source code
+
+@item
+Supplying a path for exploiting the full I64 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 present in I64.
+
+@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 I64 address space,
+@ref{Taking advantage of 64 bit addressing},
+will consider further changes that may be required.
+Such code is called @emph{64-bit code} in the
+remainder of this guide.
+
+
+@node Migration of 32 bit code
+@subsection Migration of 32-bit code
+
+@menu
+* Address types::
+* Access types::
+* Unchecked conversions::
+* Predefined constants::
+* Single source compatibility::
+* 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 I64 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}, GNAT Pro for OpenVMS I64 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 predefined constants have changed:
+
+@multitable {@code{System.Address_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.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 Single source compatibility
+@subsubsection Single source compatibility
+
+@noindent
+In order to allow the same source code to be compiled on
+both Alpha and I64 platforms, GNAT Pro for Alpha OpenVMS
+defines @code{System.Short_Address} and System.Short_Memory_Size
+as aliases of respectively @code{System.Address} and
+@code{System.Memory_Size}.
+(These aliases also leave the door open for a possible
+future ``upgrade'' of OpenVMS Alpha to a 64-bit address space.)
+
+@node Experience with source compatibility
+@subsubsection Experience with source compatibility
+
+@noindent
+The Security Server and STARLET 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.
+To assist in the compile-time detection of such situations, we
+plan to include a switch to generate a warning message when a
+record component is of type @code{Address}.
+
+
+@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
+specifications to see in which contexts objects allocated
+in 64-bit address space are acceptable.
+
+@node Technical details
+@subsection Technical details
+
+@noindent
+GNAT Pro for Open VMS I64 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 GNAT Pro for Open VMS I64, @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}, an Ada 95 feature 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 I64 architecture.
+@end ifset
+@c ************************************************
@ifset unw
@node Microsoft Windows Topics
@appendix Microsoft Windows Topics
* 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::
-* GNAT and COM/DCOM Objects::
+* Setting Stack Size from gnatlink::
+* Setting Heap Size from gnatlink::
@end menu
@node Using GNAT on Windows
@noindent
One of the strengths of the GNAT technology is that its tool set
-(@code{gcc}, @code{gnatbind}, @code{gnatlink}, @code{gnatmake}, the
+(@command{gcc}, @command{gnatbind}, @command{gnatlink}, @command{gnatmake}, the
@code{gdb} debugger, etc.) is used in the same way regardless of the
platform.
Windows C/C++ development environment conditions your overall
interoperability strategy.
-If you use @code{gcc} to compile the non-Ada part of your application,
+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
@menu
* C Calling Convention::
* Stdcall Calling Convention::
+* Win32 Calling Convention::
* DLL Calling Convention::
@end menu
@code{Stdcall} (Microsoft defined)
@item
+@code{Win32} (GNAT specific)
+
+@item
@code{DLL} (GNAT specific)
@end itemize
@noindent
This is the default calling convention used when interfacing to C/C++
-routines compiled with either @code{gcc} or Microsoft Visual 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
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{DLL} calling convention,
-@pxref{DLL Calling Convention}).
+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
Note, that in some special cases a DLL's entry point name lacks a trailing
@code{@@}@code{@i{nn}} while the exported name generated for a call has it.
The @code{gnatdll} tool, which creates the import library for the DLL, is able
-to handle those cases (see the description of the switches in
-@pxref{Using gnatdll} section).
-
-@node DLL Calling Convention
-@subsection @code{DLL} Calling Convention
+to handle those cases (@pxref{Using gnatdll} for the description of
+the switches).
@noindent
-This convention, which is GNAT-specific, must be used when you want to
-import in Ada a variables defined in a DLL. For functions and procedures
-this convention is equivalent to the @code{Stdcall} convention. As an
-example, if a DLL contains a variable defined as:
+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;
@smallexample @c ada
@group
My_Var : Interfaces.C.int;
-pragma Import (DLL, My_Var);
+pragma Import (Stdcall, My_Var);
@end group
@end smallexample
-The remarks concerning the @code{External_Name} and @code{Link_Name}
-parameters given in the previous sections equally apply to the @code{DLL}
-calling convention.
+@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)
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 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.a} or @file{libapi.a} (names are case insensitive).
-
-After you have statically linked your application with the import library
+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.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
@end itemize
@item
-The entries in the @file{libAPI.a} or @file{API.lib} jump table which is
-part of your application are initialized with the addresses of the routines
-and variables in @file{API.dll}.
+The entries in the jump table (from the import library @file{libAPI.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
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 the exported routines must be listed explicitly in a definition
-file (@pxref{The Definition File}).
+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
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.
+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 smallexample
@noindent
-The argument @option{-largs -lAPI} at the end of the @code{gnatmake} command
+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 library named @file{libAPI.a}
(GNAT-style name). Note that if the Ada package spec for @file{API.dll}
@end smallexample
@noindent
-you do not have to add @option{-largs -lAPI} at the end of the @code{gnatmake}
-command.
+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
@end smallexample
@noindent
-Note that a variable is @strong{always imported with a DLL convention}. A
-function can have @code{C}, @code{Stdcall} or @code{DLL} convention. For
-subprograms, the @code{DLL} convention is a synonym of @code{Stdcall}
+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
@noindent
If a Microsoft-style import library @file{API.lib} or a GNAT-style
import library @file{libAPI.a} is available with @file{API.dll} you
-can skip this section. Otherwise read on.
+can skip this section. You can also skip this section if
+@file{API.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
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{@@}@i{nn}
-suffix then you'll have to edit @file{api.def} to add it.
+suffix then you'll have to edit @file{api.def} to add it, and specify
+@code{-k} to @code{gnatdll} when creating the import library.
@noindent
Here are some hints to find the right @code{@@}@i{nn} suffix.
@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 @code{-shared}
+option. It is quite simple to use this method:
+
+@smallexample
+$ gcc -shared -o api.dll obj1.o obj2.o ...
+@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 ...
+@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 @code{-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 this area. @pxref{Library Projects}.
+
+@node Building DLLs with gnatdll
+@section Building DLLs with gnatdll
+@cindex DLLs, building
+
@menu
* Limitations When Using Ada DLLs from Ada::
* Exporting Ada Entities::
@end menu
@noindent
-This section explains how to build DLLs containing Ada code. These DLLs
-will be referred to as Ada DLLs in the remainder of this section.
+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:
@item
Your Ada code must export an initialization routine which calls the routine
-@code{adainit} generated by @code{gnatbind} to perform the elaboration of
+@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 @code{gnatbind} to perform the
+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.
@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}.
+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
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. Please note that the @code{Stdcall} convention
-should only be used for subprograms, not for variables. As an example here
-is an Ada package @code{API}, spec and body, exporting two procedures, a
-function, and a variable:
+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
@item -k
@cindex @option{-k} (@code{gnatdll})
Removes the @code{@@}@i{nn} suffix from the import library's exported
-names. You must specified this option if you want to use a
-@code{Stdcall} function in a DLL for which the @code{@@}@i{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.
+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{@@}@i{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})
@end smallexample
@noindent
-In addition to the base file, the @code{gnatlink} command generates an
+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 @code{gnatlink} to generate the routines @code{DllMain} and
+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} builds the base file using the new export table. Note that
-@code{gnatbind} must be called once again since the binder generated file
-has been deleted during the previous call to @code{gnatlink}.
+@command{gnatbind} must be called once again since the binder generated file
+has been deleted during the previous call to @command{gnatlink}.
@smallexample
@group
@end smallexample
@noindent
-By default @code{windres} will run @code{gcc} to preprocess the @file{.rc}
+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
@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 @code{gnatmake} this is done by using the @option{-largs}
+arguments. With @command{gnatmake} this is done by using the @option{-largs}
option:
@smallexample
$ gdb -nw ada_main
@end smallexample
-@item Break on the main procedure and run the program.
+@item Start the program and stop at the beginning of the main procedure
@smallexample
-(gdb) break ada_main
-(gdb) run
+(gdb) start
@end smallexample
@noindent
@smallexample
(gdb) break ada_dll
-(gdb) run
+(gdb) cont
@end smallexample
@end enumerate
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
@enumerate 1
@item
-Launch the debugger on the DLL.
+Find out the executable starting address
@smallexample
-$ gdb -nw test.dll
+$ objdump --file-header main.exe
@end smallexample
-@item Set a breakpoint on a DLL subroutine.
+The starting address is reported on the last line. For example:
@smallexample
-(gdb) break ada_dll
+main.exe: file format pei-i386
+architecture: i386, flags 0x0000010a:
+EXEC_P, HAS_DEBUG, D_PAGED
+start address 0x00401010
@end smallexample
@item
-Specify the executable file to @code{GDB}.
+Launch the debugger on the executable.
@smallexample
-(gdb) exec-file main.exe
+$ gdb main.exe
@end smallexample
@item
-Run the program.
+Set a breakpoint at the starting address, and launch the program.
@smallexample
-(gdb) run
+$ (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
@item Launch gdb.
@smallexample
-$ gdb -nw
+$ gdb
@end smallexample
@item Attach to the running process to be debugged.
@item Continue process execution.
@smallexample
-(gdb) continue
+(gdb) cont
@end smallexample
@end enumerate
approach to debug a program as described in
(@pxref{Running and Debugging Ada Programs}).
-@node GNAT and COM/DCOM Objects
-@section GNAT and COM/DCOM Objects
-@findex COM
-@findex DCOM
+@node Setting Stack Size from gnatlink
+@section Setting Stack Size from @command{gnatlink}
@noindent
-This section is temporarily left blank.
+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
+Linker_Options or with gnatbind -d. On older versions of Windows (2000, NT4,
+etc.), it is not possible to set the reserve size of individual tasks and thus
+the link-time stack size applies to all tasks.
-@end ifset
+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 *
OSDN Git Service
