Google Git
Sign in
gnu / gcc / 19220ca6aa79921cc431e41f25986e16410c7a6a / . / gcc / ada / gnat_ugn.texi
blob: 60dce6e1865e32b84971b20eda46e0a1065ddcee [file] [log] [blame]
\input texinfo @c -*-texinfo-*-
@c %**start of header
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c o
@c GNAT DOCUMENTATION o
@c o
@c G N A T _ U G N o
@c o
@c Copyright (C) 1992-2004 Ada Core Technologies, Inc. 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 ware Foundation; either version 2, or (at your option) any later ver- o
@c sion. GNAT is distributed in the hope that it will be useful, but WITH- o
@c OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY 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 o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c
@c GNAT_UGN Style Guide
@c
@c 1. Always put a @noindent on the line before the first paragraph
@c after any of these commands:
@c
@c @chapter
@c @section
@c @subsection
@c @subsubsection
@c @subsubsubsection
@c
@c @end smallexample
@c @end itemize
@c @end enumerate
@c
@c 2. DO NOT use @example. Use @smallexample instead.
@c a) DO NOT use highlighting commands (@b{}, @i{}) inside an @smallexample
@c context. These can interfere with the readability of the texi
@c source file. Instead, use one of the following annotated
@c @smallexample commands, and preprocess the texi file with the
@c ada2texi tool (which generates appropriate highlighting):
@c @smallexample @c ada
@c @smallexample @c adanocomment
@c @smallexample @c projectfile
@c b) The "@c ada" markup will result in boldface for reserved words
@c and italics for comments
@c c) The "@c adanocomment" markup will result only in boldface for
@c reserved words (comments are left alone)
@c d) The "@c projectfile" markup is like "@c ada" except that the set
@c of reserved words include the new reserved words for project files
@c
@c 3. Each @chapter, @section, @subsection, @subsubsection, etc.
@c command must be preceded by two empty lines
@c
@c 4. The @item command should be on a line of its own if it is in an
@c @itemize or @enumerate command.
@c
@c 5. When talking about ALI files use "ALI" (all uppercase), not "Ali"
@c or "ali".
@c
@c 6. DO NOT put trailing spaces at the end of a line. Such spaces will
@c cause the document build to fail.
@c
@c 7. DO NOT use @cartouche for examples that are longer than around 10 lines.
@c This command inhibits page breaks, so long examples in a @cartouche can
@c lead to large, ugly patches of empty space on a page.
@c
@c NOTE: This file should be submitted to xgnatugn with either the vms flag
@c or the unw flag set. The unw flag covers topics for both Unix and
@c Windows.
@c
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@ifset vms
@setfilename gnat_ugn_vms.info
@end ifset
@ifset unw
@setfilename gnat_ugn_unw.info
@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
@end ifset
@ifset unw
@settitle GNAT User's Guide for Native Platforms / Unix and Windows
@direntry
* GNAT User's Guide (gnat_ugn_unw) for Native Platforms / Unix and Windows
@end direntry
@end ifset
@include gcc-common.texi
@setchapternewpage odd
@syncodeindex fn cp
@c %**end of header
@copying
Copyright @copyright{} 1995-2004, 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
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end copying
@titlepage
@title GNAT User's Guide
@center @titlefont{for Native Platforms}
@sp 1
@flushright
@ifset unw
@titlefont{@i{Unix and Windows}}
@end ifset
@ifset vms
@titlefont{@i{OpenVMS Alpha}}
@end ifset
@end flushright
@sp 2
@subtitle GNAT, The GNU Ada 95 Compiler
@subtitle GCC version @value{version-GCC}
@author Ada Core Technologies, Inc.
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage
@ifnottex
@node Top, About This Guide, (dir), (dir)
@top GNAT 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
@noindent
GNAT, The GNU Ada 95 Compiler@*
GCC version @value{version-GCC}@*
@noindent
Ada Core Technologies, Inc.@*
@menu
* About This Guide::
* Getting Started with GNAT::
* The GNAT Compilation Model::
* Compiling Using gcc::
* Binding Using gnatbind::
* Linking Using gnatlink::
* The GNAT Make Program gnatmake::
* Improving Performance::
* Renaming Files Using gnatchop::
* Configuration Pragmas::
* Handling Arbitrary File Naming Conventions Using gnatname::
* GNAT Project Manager::
* The Cross-Referencing Tools gnatxref and gnatfind::
* The GNAT Pretty-Printer gnatpp::
* File Name Krunching Using gnatkr::
* Preprocessing Using gnatprep::
@ifset vms
* The GNAT Run-Time Library Builder gnatlbr::
@end ifset
* The GNAT Library Browser gnatls::
* Cleaning Up Using gnatclean::
@ifclear vms
* GNAT and Libraries::
* Using the GNU make Utility::
@end ifclear
* Finding Memory Problems::
* Creating Sample Bodies Using gnatstub::
* Other Utility Programs::
* Running and Debugging Ada Programs::
@ifset vms
* Compatibility with DEC Ada::
@end ifset
* Platform-Specific Information for the Run-Time Libraries::
* Example of Binder Output File::
* Elaboration Order Handling in GNAT::
* Inline Assembler::
* Compatibility and Porting Guide::
@ifset unw
* Microsoft Windows Topics::
@end ifset
* GNU Free Documentation License::
* Index::
--- The Detailed Node Listing ---
About This Guide
* What This Guide Contains::
* What You Should Know before Reading This Guide::
* Related Information::
* Conventions::
Getting Started with GNAT
* Running GNAT::
* Running a Simple Ada Program::
* Running a Program with Multiple Units::
* Using the gnatmake Utility::
@ifset vms
* Editing with Emacs::
@end ifset
@ifclear vms
* Introduction to GPS::
* Introduction to Glide and GVD::
@end ifclear
The GNAT Compilation Model
* Source Representation::
* Foreign Language Representation::
* File Naming Rules::
* Using Other File Names::
* Alternative File Naming Schemes::
* Generating Object Files::
* Source Dependencies::
* The Ada Library Information Files::
* Binding an Ada Program::
* Mixed Language Programming::
* Building Mixed Ada & C++ Programs::
* Comparison between GNAT and C/C++ Compilation Models::
* Comparison between GNAT and Conventional Ada Library Models::
@ifset vms
* Placement of temporary files::
@end ifset
Foreign Language Representation
* Latin-1::
* Other 8-Bit Codes::
* Wide Character Encodings::
Compiling Ada Programs With gcc
* Compiling Programs::
* Switches for gcc::
* Search Paths and the Run-Time Library (RTL)::
* Order of Compilation Issues::
* Examples::
Switches for gcc
* Output and Error Message Control::
* Warning Message Control::
* Debugging and Assertion Control::
* Run-Time Checks::
* Stack Overflow Checking::
* Validity Checking::
* Style Checking::
* Using gcc for Syntax Checking::
* Using gcc for Semantic Checking::
* Compiling Ada 83 Programs::
* Character Set Control::
* File Naming Control::
* Subprogram Inlining Control::
* Auxiliary Output Control::
* Debugging Control::
* Exception Handling Control::
* Units to Sources Mapping Files::
* Integrated Preprocessing::
@ifset vms
* Return Codes::
@end ifset
Binding Ada Programs With gnatbind
* Running gnatbind::
* Switches for gnatbind::
* Command-Line Access::
* Search Paths for gnatbind::
* Examples of gnatbind Usage::
Switches for gnatbind
* Consistency-Checking Modes::
* Binder Error Message Control::
* Elaboration Control::
* Output Control::
* Binding with Non-Ada Main Programs::
* Binding Programs with No Main Subprogram::
Linking Using gnatlink
* Running gnatlink::
* Switches for gnatlink::
* Setting Stack Size from gnatlink::
* Setting Heap Size from gnatlink::
The GNAT Make Program gnatmake
* Running gnatmake::
* Switches for gnatmake::
* Mode Switches for gnatmake::
* Notes on the Command Line::
* How gnatmake Works::
* Examples of gnatmake Usage::
Improving Performance
* Performance Considerations::
* Reducing the Size of Ada Executables with gnatelim::
Performance Considerations
* Controlling Run-Time Checks::
* Use of Restrictions::
* Optimization Levels::
* Debugging Optimized Code::
* Inlining of Subprograms::
@ifset vms
* Coverage Analysis::
@end ifset
Reducing the Size of Ada Executables with gnatelim
* About gnatelim::
* Running gnatelim::
* Correcting the List of Eliminate Pragmas::
* Making Your Executables Smaller::
* Summary of the gnatelim Usage Cycle::
Renaming Files Using gnatchop
* Handling Files with Multiple Units::
* Operating gnatchop in Compilation Mode::
* Command Line for gnatchop::
* Switches for gnatchop::
* Examples of gnatchop Usage::
Configuration Pragmas
* Handling of Configuration Pragmas::
* The Configuration Pragmas Files::
Handling Arbitrary File Naming Conventions Using gnatname
* Arbitrary File Naming Conventions::
* Running gnatname::
* Switches for gnatname::
* Examples of gnatname Usage::
GNAT Project Manager
* Introduction::
* Examples of Project Files::
* Project File Syntax::
* Objects and Sources in Project Files::
* Importing Projects::
* Project Extension::
* 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::
* gnatfind Switches::
* Project Files for gnatxref and gnatfind::
* Regular Expressions in gnatfind and gnatxref::
* Examples of gnatxref Usage::
* Examples of gnatfind Usage::
The GNAT Pretty-Printer gnatpp
* Switches for gnatpp::
* Formatting Rules::
File Name Krunching Using gnatkr
* About gnatkr::
* Using gnatkr::
* Krunching Method::
* Examples of gnatkr Usage::
Preprocessing Using gnatprep
* Using gnatprep::
* Switches for gnatprep::
* Form of Definitions File::
* Form of Input Text for gnatprep::
@ifset vms
The GNAT Run-Time Library Builder gnatlbr
* Running gnatlbr::
* Switches for gnatlbr::
* Examples of gnatlbr Usage::
@end ifset
The GNAT Library Browser gnatls
* Running gnatls::
* Switches for gnatls::
* Examples of gnatls Usage::
Cleaning Up Using gnatclean
* Running gnatclean::
* Switches for gnatclean::
* 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::
* Rebuilding the GNAT Run-Time Library::
Using the GNU make Utility
* Using gnatmake in a Makefile::
* Automatically Creating a List of Directories::
* Generating the Command Line Switches::
* Overcoming Command Line Length Limits::
@end ifclear
Finding Memory Problems
@ifclear vms
* The gnatmem Tool::
@end ifclear
* The GNAT Debug Pool Facility::
@ifclear vms
The gnatmem Tool
* Running gnatmem::
* Switches for gnatmem::
* Example of gnatmem Usage::
@end ifclear
The GNAT Debug Pool Facility
Creating Sample Bodies Using gnatstub
* Running gnatstub::
* Switches for gnatstub::
Other Utility Programs
* Using Other Utility Programs with GNAT::
* The External Symbol Naming Scheme of GNAT::
@ifclear vms
* Ada Mode for Glide::
@end ifclear
* Converting Ada Files to html with gnathtml::
Running and Debugging Ada Programs
* The GNAT Debugger GDB::
* Running GDB::
* Introduction to GDB Commands::
* Using Ada Expressions::
* Calling User-Defined Subprograms::
* Using the Next Command in a Function::
* Ada Exceptions::
* Ada Tasks::
* Debugging Generic Units::
* GNAT Abnormal Termination or Failure to Terminate::
* Naming Conventions for GNAT Source Files::
* Getting Internal Debugging Information::
* Stack Traceback::
@ifset vms
* LSE::
@end ifset
@ifset vms
Compatibility with DEC Ada
* Ada 95 Compatibility::
* Differences in the Definition of Package System::
* Language-Related Features::
* 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::
* Main Program Definition::
* Implementation-Defined Attributes::
* Compiler and Run-Time Interfacing::
* Program Compilation and Library Management::
* Input-Output::
* Implementation Limits::
* Tools::
Language-Related Features
* Integer Types and Representations::
* Floating-Point Types and Representations::
* Pragmas Float_Representation and Long_Float::
* Fixed-Point Types and Representations::
* Record and Array Component Alignment::
* Address Clauses::
* Other Representation Clauses::
Implementation of Tasks in DEC Ada for OpenVMS Alpha Systems
* Assigning Task IDs::
* Task IDs and Delays::
* Task-Related Pragmas::
* Scheduling and Task Priority::
* The Task Stack::
* External Interrupts::
Pragmas and Pragma-Related Features
* Restrictions on the Pragma INLINE::
* Restrictions on the Pragma INTERFACE::
* Restrictions on the Pragma SYSTEM_NAME::
Library of Predefined Units
* Changes to DECLIB::
Bindings
* Shared Libraries and Options Files::
* Interfaces to C::
@end ifset
Platform-Specific Information for the Run-Time Libraries
* Summary of Run-Time Configurations::
* Specifying a Run-Time Library::
* Choosing between Native and FSU Threads Libraries::
* Choosing the Scheduling Policy::
* Solaris-Specific Considerations::
* IRIX-Specific Considerations::
* Linux-Specific Considerations::
Example of Binder Output File
Elaboration Order Handling in GNAT
* Elaboration Code in Ada 95::
* Checking the Elaboration Order in Ada 95::
* Controlling the Elaboration Order in Ada 95::
* Controlling Elaboration in GNAT - Internal Calls::
* Controlling Elaboration in GNAT - External Calls::
* Default Behavior in GNAT - Ensuring Safety::
* Treatment of Pragma Elaborate::
* Elaboration Issues for Library Tasks::
* Mixing Elaboration Models::
* What to Do If the Default Elaboration Behavior Fails::
* Elaboration for Access-to-Subprogram Values::
* Summary of Procedures for Elaboration Control::
* Other Elaboration Order Considerations::
Inline Assembler
* Basic Assembler Syntax::
* A Simple Example of Inline Assembler::
* Output Variables in Inline Assembler::
* Input Variables in Inline Assembler::
* Inlining Inline Assembler Code::
* Other Asm Functionality::
* A Complete Example::
Compatibility and Porting Guide
* Compatibility with Ada 83::
* Implementation-dependent characteristics::
* Compatibility with DEC Ada 83::
* Compatibility with Other Ada 95 Systems::
* Representation Clauses::
@ifset unw
Microsoft Windows Topics
* Using GNAT on Windows::
* CONSOLE and WINDOWS subsystems::
* Temporary Files::
* Mixed-Language Programming on Windows::
* Windows Calling Conventions::
* Introduction to Dynamic Link Libraries (DLLs)::
* Using DLLs with GNAT::
* Building DLLs with GNAT::
* GNAT and Windows Resources::
* Debugging a DLL::
* GNAT and COM/DCOM Objects::
@end ifset
* Index::
@end menu
@end ifnottex
@node About This Guide
@unnumbered About This Guide
@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.
@end ifset
@ifclear vms
This guide describes the use of GNAT, 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.
@menu
* What This Guide Contains::
* What You Should Know before Reading This Guide::
* Related Information::
* Conventions::
@end menu
@node What This Guide Contains
@unnumberedsec What This Guide Contains
@noindent
This guide contains the following chapters:
@itemize @bullet
@item
@ref{Getting Started with GNAT}, describes how to get started compiling
and running Ada programs with the GNAT Ada programming environment.
@item
@ref{The GNAT Compilation Model}, describes the compilation model used
by GNAT.
@item
@ref{Compiling Using gcc}, describes how to compile
Ada programs with @code{gcc}, the Ada compiler.
@item
@ref{Binding Using gnatbind}, describes how to
perform binding of Ada programs with @code{gnatbind}, the GNAT binding
utility.
@item
@ref{Linking Using gnatlink},
describes @code{gnatlink}, a
program that provides for linking using the GNAT run-time library to
construct a program. @code{gnatlink} can also incorporate foreign language
object units into the executable.
@item
@ref{The GNAT Make Program gnatmake}, describes @code{gnatmake}, a
utility that automatically determines the set of sources
needed by an Ada compilation unit, and executes the necessary compilations
binding and link.
@item
@ref{Improving Performance}, shows various techniques for making your
Ada program run faster or take less space.
It discusses the effect of the compiler's optimization switch and
also describes the @command{gnatelim} tool.
@item
@ref{Renaming Files Using gnatchop}, describes
@code{gnatchop}, a utility that allows you to preprocess a file that
contains Ada source code, and split it into one or more new files, one
for each compilation unit.
@item
@ref{Configuration Pragmas}, describes the configuration pragmas
handled by GNAT.
@item
@ref{Handling Arbitrary File Naming Conventions Using gnatname},
shows how to override the default GNAT file naming conventions,
either for an individual unit or globally.
@item
@ref{GNAT Project Manager}, describes how to use project files
to organize large projects.
@item
@ref{The Cross-Referencing Tools gnatxref and gnatfind}, discusses
@code{gnatxref} and @code{gnatfind}, two tools that provide an easy
way to navigate through sources.
@item
@ref{The GNAT Pretty-Printer gnatpp}, shows how to produce a reformatted
version of an Ada source file with control over casing, indentation,
comment placement, and other elements of program presentation style.
@item
@ref{File Name Krunching Using gnatkr}, describes the @code{gnatkr}
file name krunching utility, used to handle shortened
file names on operating systems with a limit on the length of names.
@item
@ref{Preprocessing Using gnatprep}, describes @code{gnatprep}, a
preprocessor utility that allows a single source file to be used to
generate multiple or parameterized source files, by means of macro
substitution.
@ifset vms
@item
@ref{The GNAT Run-Time Library Builder gnatlbr}, describes @command{gnatlbr},
a tool for rebuilding the GNAT run time with user-supplied
configuration pragmas.
@end ifset
@item
@ref{The GNAT Library Browser gnatls}, describes @code{gnatls}, a
utility that displays information about compiled units, including dependences
on the corresponding sources files, and consistency of compilations.
@item
@ref{Cleaning Up Using gnatclean}, describes @code{gnatclean}, a utility
to delete files that are produced by the compiler, binder and linker.
@ifclear vms
@item
@ref{GNAT and Libraries}, describes the process of creating and using
Libraries with GNAT. It also describes how to recompile the GNAT run-time
library.
@item
@ref{Using the GNU make Utility}, describes some techniques for using
the GNAT toolset in Makefiles.
@end ifclear
@item
@ref{Finding Memory Problems}, describes
@ifclear vms
@command{gnatmem}, a utility that monitors dynamic allocation and deallocation
and helps detect ``memory leaks'', and
@end ifclear
the GNAT Debug Pool facility, which helps detect incorrect memory references.
@item
@ref{Creating Sample Bodies Using gnatstub}, discusses @code{gnatstub},
a utility that generates empty but compilable bodies for library units.
@item
@ref{Other Utility Programs}, discusses several other GNAT utilities,
including @code{gnathtml}.
@item
@ref{Running and Debugging Ada Programs}, describes how to run and debug
Ada programs.
@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
developed by Digital Equipment Corporation and currently supported by HP.}
for OpenVMS Alpha.
@end ifset
@item
@ref{Platform-Specific Information for the Run-Time Libraries},
describes the various run-time
libraries supported by GNAT on various platforms and explains how to
choose a particular library.
@item
@ref{Example of Binder Output File}, shows the source code for the binder
output file for a sample program.
@item
@ref{Elaboration Order Handling in GNAT}, describes how GNAT helps
you deal with elaboration order issues.
@item
@ref{Inline Assembler}, shows how to use the inline assembly facility
in an Ada program.
@item
@ref{Compatibility and Porting Guide}, includes sections on compatibility
of GNAT with other Ada 83 and Ada 95 compilation systems, to assist
in porting code from other environments.
@ifset unw
@item
@ref{Microsoft Windows Topics}, presents information relevant to the
Microsoft Windows platform.
@end ifset
@end itemize
@c *************************************************
@node What You Should Know before Reading This Guide
@c *************************************************
@unnumberedsec What You Should Know before Reading This Guide
@cindex Ada 95 Language Reference Manual
@noindent
This user's guide assumes that you are familiar with Ada 95 language, as
described in the International Standard ANSI/ISO/IEC-8652:1995, January
1995.
@node Related Information
@unnumberedsec Related Information
@noindent
For further information about related tools, refer to the following
documents:
@itemize @bullet
@item
@cite{GNAT Reference Manual}, which contains all reference
material for the GNAT implementation of Ada 95.
@ifset unw
@item
@cite{Using the GNAT Programming System}, which describes the GPS
integrated development environment.
@item
@cite{GNAT Programming System Tutorial}, which introduces the
main GPS features through examples.
@end ifset
@item
@cite{Ada 95 Language Reference Manual}, which contains all reference
material for the Ada 95 programming language.
@item
@cite{Debugging with GDB}
@ifset vms
, located in the GNU:[DOCS] directory,
@end ifset
contains all details on the use of the GNU source-level debugger.
@item
@cite{GNU Emacs Manual}
@ifset vms
, located in the GNU:[DOCS] directory if the EMACS kit is installed,
@end ifset
contains full information on the extensible editor and programming
environment Emacs.
@end itemize
@c **************
@node Conventions
@unnumberedsec Conventions
@cindex Conventions
@cindex Typographical conventions
@noindent
Following are examples of the typographical and graphic conventions used
in this guide:
@itemize @bullet
@item
@code{Functions}, @code{utility program names}, @code{standard names},
and @code{classes}.
@item
@samp{Option flags}
@item
@file{File Names}, @file{button names}, and @file{field names}.
@item
@var{Variables}.
@item
@emph{Emphasis}.
@item
[optional information or parameters]
@item
Examples are described by text
@smallexample
and then shown this way.
@end smallexample
@end itemize
@noindent
Commands that are entered by the user are preceded in this manual by the
characters @w{``@code{$ }''} (dollar sign followed by space). If your system
uses this sequence as a prompt, then the commands will appear exactly as
you see them in the manual. If your system uses some other prompt, then
the command will appear with the @code{$} replaced by whatever prompt
character you are using.
@ifset unw
Full file names are shown with the ``@code{/}'' character
as the directory separator; e.g., @file{parent-dir/subdir/myfile.adb}.
If you are using GNAT on a Windows platform, please note that
the ``@code{\}'' character should be used instead.
@end ifset
@c ****************************
@node Getting Started with GNAT
@chapter Getting Started with GNAT
@noindent
This chapter describes some simple ways of using GNAT to build
executable Ada programs.
@ifset unw
@ref{Running GNAT}, through @ref{Using the gnatmake Utility},
show how to use the command line environment.
@ref{Introduction to Glide and GVD}, provides a brief
introduction to the visually-oriented IDE for GNAT.
Supplementing Glide on some platforms is GPS, the
GNAT Programming System, which offers a richer graphical
``look and feel'', enhanced configurability, support for
development in other programming language, comprehensive
browsing features, and many other capabilities.
For information on GPS please refer to
@cite{Using the GNAT Programming System}.
@end ifset
@menu
* Running GNAT::
* Running a Simple Ada Program::
* Running a Program with Multiple Units::
* Using the gnatmake Utility::
@ifset vms
* Editing with Emacs::
@end ifset
@ifclear vms
* Introduction to GPS::
* Introduction to Glide and GVD::
@end ifclear
@end menu
@node Running GNAT
@section Running GNAT
@noindent
Three steps are needed to create an executable file from an Ada source
file:
@enumerate
@item
The source file(s) must be compiled.
@item
The file(s) must be bound using the GNAT binder.
@item
All appropriate object files must be linked to produce an executable.
@end enumerate
@noindent
All three steps are most commonly handled by using the @code{gnatmake}
utility program that, given the name of the main program, automatically
performs the necessary compilation, binding and linking steps.
@node Running a Simple Ada Program
@section Running a Simple Ada Program
@noindent
Any text editor may be used to prepare an Ada program.
@ifclear vms
If @code{Glide} is
used, the optional Ada mode may be helpful in laying out the program.
@end ifclear
The
program text is a normal text file. We will suppose in our initial
example that you have used your editor to prepare the following
standard format text file:
@smallexample @c ada
@cartouche
with Ada.Text_IO; use Ada.Text_IO;
procedure Hello is
begin
Put_Line ("Hello WORLD!");
end Hello;
@end cartouche
@end smallexample
@noindent
This file should be named @file{hello.adb}.
With the normal default file naming conventions, GNAT requires
that each file
contain a single compilation unit whose file name is the
unit name,
with periods replaced by hyphens; the
extension is @file{ads} for a
spec and @file{adb} for a body.
You can override this default file naming convention by use of the
special pragma @code{Source_File_Name} (@pxref{Using Other File Names}).
Alternatively, if you want to rename your files according to this default
convention, which is probably more convenient if you will be using GNAT
for all your compilations, then the @code{gnatchop} utility
can be used to generate correctly-named source files
(@pxref{Renaming Files Using gnatchop}).
You can compile the program using the following command (@code{$} is used
as the command prompt in the examples in this document):
@smallexample
$ gcc -c hello.adb
@end smallexample
@noindent
@code{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
the GNAT compiler to compile the specified file.
@ifclear vms
The @option{-c} switch is required. It tells @command{gcc} to only do a
compilation. (For C programs, @command{gcc} can also do linking, but this
capability is not used directly for Ada programs, so the @option{-c}
switch must always be present.)
@end ifclear
This compile command generates a file
@file{hello.o}, which is the object
file corresponding to your Ada program. It also generates
an ``Ada Library Information'' file @file{hello.ali},
which contains additional information used to check
that an Ada program is consistent.
To build an executable file,
use @code{gnatbind} to bind the program
and @code{gnatlink} to link it. The
argument to both @code{gnatbind} and @code{gnatlink} is the name of the
@file{ALI} file, but the default extension of @file{.ali} can
be omitted. This means that in the most common case, the argument
is simply the name of the main program:
@smallexample
$ gnatbind hello
$ gnatlink hello
@end smallexample
@noindent
A simpler method of carrying out these steps is to use
@command{gnatmake},
a master program that invokes all the required
compilation, binding and linking tools in the correct order. In particular,
@command{gnatmake} automatically recompiles any sources that have been
modified since they were last compiled, or sources that depend
on such modified sources, so that ``version skew'' is avoided.
@cindex Version skew (avoided by @command{gnatmake})
@smallexample
$ gnatmake hello.adb
@end smallexample
@noindent
The result is an executable program called @file{hello}, which can be
run by entering:
@c The following should be removed (BMB 2001-01-23)
@c @smallexample
@c $ ^./hello^$ RUN HELLO^
@c @end smallexample
@smallexample
$ hello
@end smallexample
@noindent
assuming that the current directory is on the search path
for executable programs.
@noindent
and, if all has gone well, you will see
@smallexample
Hello WORLD!
@end smallexample
@noindent
appear in response to this command.
@c ****************************************
@node Running a Program with Multiple Units
@section Running a Program with Multiple Units
@noindent
Consider a slightly more complicated example that has three files: a
main program, and the spec and body of a package:
@smallexample @c ada
@cartouche
@group
package Greetings is
procedure Hello;
procedure Goodbye;
end Greetings;
with Ada.Text_IO; use Ada.Text_IO;
package body Greetings is
procedure Hello is
begin
Put_Line ("Hello WORLD!");
end Hello;
procedure Goodbye is
begin
Put_Line ("Goodbye WORLD!");
end Goodbye;
end Greetings;
@end group
@group
with Greetings;
procedure Gmain is
begin
Greetings.Hello;
Greetings.Goodbye;
end Gmain;
@end group
@end cartouche
@end smallexample
@noindent
Following the one-unit-per-file rule, place this program in the
following three separate files:
@table @file
@item greetings.ads
spec of package @code{Greetings}
@item greetings.adb
body of package @code{Greetings}
@item gmain.adb
body of main program
@end table
@noindent
To build an executable version of
this program, we could use four separate steps to compile, bind, and link
the program, as follows:
@smallexample
$ gcc -c gmain.adb
$ gcc -c greetings.adb
$ gnatbind gmain
$ gnatlink gmain
@end smallexample
@noindent
Note that there is no required order of compilation when using GNAT.
In particular it is perfectly fine to compile the main program first.
Also, it is not necessary to compile package specs in the case where
there is an accompanying body; you only need to compile the body. If you want
to submit these files to the compiler for semantic checking and not code
generation, then use the
@option{-gnatc} switch:
@smallexample
$ gcc -c greetings.ads -gnatc
@end smallexample
@noindent
Although the compilation can be done in separate steps as in the
above example, in practice it is almost always more convenient
to use the @code{gnatmake} tool. All you need to know in this case
is the name of the main program's source file. The effect of the above four
commands can be achieved with a single one:
@smallexample
$ gnatmake gmain.adb
@end smallexample
@noindent
In the next section we discuss the advantages of using @code{gnatmake} in
more detail.
@c *****************************
@node Using the gnatmake Utility
@section Using the @command{gnatmake} Utility
@noindent
If you work on a program by compiling single components at a time using
@code{gcc}, you typically keep track of the units you modify. In order to
build a consistent system, you compile not only these units, but also any
units that depend on the units you have modified.
For example, in the preceding case,
if you edit @file{gmain.adb}, you only need to recompile that file. But if
you edit @file{greetings.ads}, you must recompile both
@file{greetings.adb} and @file{gmain.adb}, because both files contain
units that depend on @file{greetings.ads}.
@code{gnatbind} will warn you if you forget one of these compilation
steps, so that it is impossible to generate an inconsistent program as a
result of forgetting to do a compilation. Nevertheless it is tedious and
error-prone to keep track of dependencies among units.
One approach to handle the dependency-bookkeeping is to use a
makefile. However, makefiles present maintenance problems of their own:
if the dependencies change as you change the program, you must make
sure that the makefile is kept up-to-date manually, which is also an
error-prone process.
The @code{gnatmake} utility takes care of these details automatically.
Invoke it using either one of the following forms:
@smallexample
$ gnatmake gmain.adb
$ gnatmake ^gmain^GMAIN^
@end smallexample
@noindent
The argument is the name of the file containing the main program;
you may omit the extension. @code{gnatmake}
examines the environment, automatically recompiles any files that need
recompiling, and binds and links the resulting set of object files,
generating the executable file, @file{^gmain^GMAIN.EXE^}.
In a large program, it
can be extremely helpful to use @code{gnatmake}, because working out by hand
what needs to be recompiled can be difficult.
Note that @code{gnatmake}
takes into account all the Ada 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
found by the compiler on a previous compilation, which may possibly
be wrong when sources change. @code{gnatmake} determines the exact set of
dependencies from scratch each time it is run.
@ifset vms
@node Editing with Emacs
@section Editing with Emacs
@cindex Emacs
@noindent
Emacs is an extensible self-documenting text editor that is available in a
separate VMSINSTAL kit.
Invoke Emacs by typing @kbd{Emacs} at the command prompt. To get started,
click on the Emacs Help menu and run the Emacs Tutorial.
In a character cell terminal, Emacs help is invoked with @kbd{Ctrl-h} (also
written as @kbd{C-h}), and the tutorial by @kbd{C-h t}.
Documentation on Emacs and other tools is available in Emacs under the
pull-down menu button: @code{Help - Info}. After selecting @code{Info},
use the middle mouse button to select a topic (e.g. Emacs).
In a character cell terminal, do @kbd{C-h i} to invoke info, and then @kbd{m}
(stands for menu) followed by the menu item desired, as in @kbd{m Emacs}, to
get to the Emacs manual.
Help on Emacs is also available by typing @kbd{HELP EMACS} at the DCL command
prompt.
The tutorial is highly recommended in order to learn the intricacies of Emacs,
which is sufficiently extensible to provide for a complete programming
environment and shell for the sophisticated user.
@end ifset
@ifclear vms
@node Introduction to GPS
@section Introduction to GPS
@cindex GPS (GNAT Programming System)
@cindex GNAT Programming System (GPS)
@noindent
Although the command line interface (@command{gnatmake}, etc.) alone
is sufficient, a graphical Interactive Development
Environment can make it easier for you to compose, navigate, and debug
programs. This section describes the main features of GPS
(``GNAT Programming System''), the GNAT graphical IDE.
You will see how to use GPS to build and debug an executable, and
you will also learn some of the basics of the GNAT ``project'' facility.
GPS enables you to do much more than is presented here;
e.g., you can produce a call graph, interface to a third-party
Version Control System, and inspect the generated assembly language
for a program.
Indeed, GPS also supports languages other than Ada.
Such additional information, and an explanation of all of the GPS menu
items. may be found in the on-line help, which includes
a user's guide and a tutorial (these are also accessible from the GNAT
startup menu).
@menu
* Building a New Program with GPS::
* Simple Debugging with GPS::
@end menu
@node Building a New Program with GPS
@subsection Building a New Program with GPS
@noindent
GPS invokes the GNAT compilation tools using information
contained in a @emph{project} (also known as a @emph{project file}):
a collection of properties such
as source directories, identities of main subprograms, tool switches, etc.,
and their associated values.
(See @ref{GNAT Project Manager}, for details.)
In order to run GPS, you will need to either create a new project
or else open an existing one.
This section will explain how you can use GPS to create a project,
to associate Ada source files with a project, and to build and run
programs.
@enumerate
@item @emph{Creating a project}
Invoke GPS, either from the command line or the platform's IDE.
After it starts, GPS will display a ``Welcome'' screen with three
radio buttons:
@itemize @bullet
@item
@code{Start with default project in directory}
@item
@code{Create new project with wizard}
@item
@code{Open existing project}
@end itemize
@noindent
Select @code{Create new project with wizard} and press @code{OK}.
A new window will appear. In the text box labeled with
@code{Enter the name of the project to create}, type @file{sample}
as the project name.
In the next box, browse to choose the directory in which you
would like to create the project file.
After selecting an appropriate directory, press @code{Forward}.
A window will appear with the title
@code{Version Control System Configuration}.
Simply press @code{Forward}.
A window will appear with the title
@code{Please select the source directories for this project}.
The directory that you specified for the project file will be selected
by default as the one to use for sources; simply press @code{Forward}.
A window will appear with the title
@code{Please select the build directory for this project}.
The directory that you specified for the project file will be selected
by default for object files and executables;
simply press @code{Forward}.
A window will appear with the title
@code{Please select the main units for this project}.
You will supply this information later, after creating the source file.
Simply press @code{Forward} for now.
A window will appear with the title
@code{Please select the switches to build the project}.
Press @code{Apply}. This will create a project file named
@file{sample.prj} in the directory that you had specified.
@item @emph{Creating and saving the source file}
After you create the new project, a GPS window will appear, which is
partitioned into two main sections:
@itemize @bullet
@item
A @emph{Workspace area}, initially greyed out, which you will use for
creating and editing source files
@item
Directly below, a @emph{Messages area}, which initially displays a
``Welcome'' message.
(If the Messages area is not visible, drag its border upward to expand it.)
@end itemize
@noindent
Select @code{File} on the menu bar, and then the @code{New} command.
The Workspace area will become white, and you can now
enter the source program explicitly.
Type the following text
@smallexample @c ada
@group
with Ada.Text_IO; use Ada.Text_IO;
procedure Hello is
begin
Put_Line("Hello from GPS!");
end Hello;
@end group
@end smallexample
@noindent
Select @code{File}, then @code{Save As}, and enter the source file name
@file{hello.adb}.
The file will be saved in the same directory you specified as the
location of the default project file.
@item @emph{Updating the project file}
You need to add the new source file to the project.
To do this, select
the @code{Project} menu and then @code{Edit project properties}.
Click the @code{Main files} tab on the left, and then the
@code{Add} button.
Choose @file{hello.adb} from the list, and press @code{Open}.
The project settings window will reflect this action.
Click @code{OK}.
@item @emph{Building and running the program}
In the main GPS window, now choose the @code{Build} menu, then @code{Make},
and select @file{hello.adb}.
The Messages window will display the resulting invocations of @command{gcc},
@command{gnatbind}, and @command{gnatlink}
(reflecting the default switch settings from the
project file that you created) and then a ``successful compilation/build''
message.
To run the program, choose the @code{Build} menu, then @code{Run}, and
select @command{hello}.
An @emph{Arguments Selection} window will appear.
There are no command line arguments, so just click @code{OK}.
The Messages window will now display the program's output (the string
@code{Hello from GPS}), and at the bottom of the GPS window a status
update is displayed (@code{Run: hello}).
Close the GPS window (or select @code{File}, then @code{Exit}) to
terminate this GPS session.
@end enumerate
@node Simple Debugging with GPS
@subsection Simple Debugging with GPS
@noindent
This section illustrates basic debugging techniques (setting breakpoints,
examining/modifying variables, single stepping).
@enumerate
@item @emph{Opening a project}
Start GPS and select @code{Open existing project}; browse to
specify the project file @file{sample.prj} that you had created in the
earlier example.
@item @emph{Creating a source file}
Select @code{File}, then @code{New}, and type in the following program:
@smallexample @c ada
@group
with Ada.Text_IO; use Ada.Text_IO;
procedure Example is
Line : String (1..80);
N : Natural;
begin
Put_Line("Type a line of text at each prompt; an empty line to exit");
loop
Put(": ");
Get_Line (Line, N);
Put_Line (Line (1..N) );
exit when N=0;
end loop;
end Example;
@end group
@end smallexample
@noindent
Select @code{File}, then @code{Save as}, and enter the file name
@file{example.adb}.
@item @emph{Updating the project file}
Add @code{Example} as a new main unit for the project:
@enumerate a
@item
Select @code{Project}, then @code{Edit Project Properties}.
@item
Select the @code{Main files} tab, click @code{Add}, then
select the file @file{example.adb} from the list, and
click @code{Open}.
You will see the file name appear in the list of main units
@item
Click @code{OK}
@end enumerate
@item @emph{Building/running the executable}
To build the executable
select @code{Build}, then @code{Make}, and then choose @file{example.adb}.
Run the program to see its effect (in the Messages area).
Each line that you enter is displayed; an empty line will
cause the loop to exit and the program to terminate.
@item @emph{Debugging the program}
Note that the @option{-g} switches to @command{gcc} and @command{gnatlink},
which are required for debugging, are on by default when you create
a new project.
Thus unless you intentionally remove these settings, you will be able
to debug any program that you develop using GPS.
@enumerate a
@item @emph{Initializing}
Select @code{Debug}, then @code{Initialize}, then @file{example}
@item @emph{Setting a breakpoint}
After performing the initialization step, you will observe a small
icon to the right of each line number.
This serves as a toggle for breakpoints; clicking the icon will
set a breakpoint at the corresponding line (the icon will change to
a red circle with an ``x''), and clicking it again
will remove the breakpoint / reset the icon.
For purposes of this example, set a breakpoint at line 10 (the
statement @code{Put_Line@ (Line@ (1..N));}
@item @emph{Starting program execution}
Select @code{Debug}, then @code{Run}. When the
@code{Program Arguments} window appears, click @code{OK}.
A console window will appear; enter some line of text,
e.g. @code{abcde}, at the prompt.
The program will pause execution when it gets to the
breakpoint, and the corresponding line is highlighted.
@item @emph{Examining a variable}
Move the mouse over one of the occurrences of the variable @code{N}.
You will see the value (5) displayed, in ``tool tip'' fashion.
Right click on @code{N}, select @code{Debug}, then select @code{Display N}.
You will see information about @code{N} appear in the @code{Debugger Data}
pane, showing the value as 5.
@item @emph{Assigning a new value to a variable}
Right click on the @code{N} in the @code{Debugger Data} pane, and
select @code{Set value of N}.
When the input window appears, enter the value @code{4} and click
@code{OK}.
This value does not automatically appear in the @code{Debugger Data}
pane; to see it, right click again on the @code{N} in the
@code{Debugger Data} pane and select @code{Update value}.
The new value, 4, will appear in red.
@item @emph{Single stepping}
Select @code{Debug}, then @code{Next}.
This will cause the next statement to be executed, in this case the
call of @code{Put_Line} with the string slice.
Notice in the console window that the displayed string is simply
@code{abcd} and not @code{abcde} which you had entered.
This is because the upper bound of the slice is now 4 rather than 5.
@item @emph{Removing a breakpoint}
Toggle the breakpoint icon at line 10.
@item @emph{Resuming execution from a breakpoint}
Select @code{Debug}, then @code{Continue}.
The program will reach the next iteration of the loop, and
wait for input after displaying the prompt.
This time, just hit the @kbd{Enter} key.
The value of @code{N} will be 0, and the program will terminate.
The console window will disappear.
@end enumerate
@end enumerate
@node Introduction to Glide and GVD
@section Introduction to Glide and GVD
@cindex Glide
@cindex GVD
@noindent
This section describes the main features of Glide,
a GNAT graphical IDE, and also shows how to use the basic commands in GVD,
the GNU Visual Debugger.
These tools may be present in addition to, or in place of, GPS on some
platforms.
Additional information on Glide and GVD may be found
in the on-line help for these tools.
@menu
* Building a New Program with Glide::
* Simple Debugging with GVD::
* Other Glide Features::
@end menu
@node Building a New Program with Glide
@subsection Building a New Program with Glide
@noindent
The simplest way to invoke Glide is to enter @command{glide}
at the command prompt. It will generally be useful to issue this
as a background command, thus allowing you to continue using
your command window for other purposes while Glide is running:
@smallexample
$ glide&
@end smallexample
@noindent
Glide will start up with an initial screen displaying the top-level menu items
as well as some other information. The menu selections are as follows
@itemize @bullet
@item @code{Buffers}
@item @code{Files}
@item @code{Tools}
@item @code{Edit}
@item @code{Search}
@item @code{Mule}
@item @code{Glide}
@item @code{Help}
@end itemize
@noindent
For this introductory example, you will need to create a new Ada source file.
First, select the @code{Files} menu. This will pop open a menu with around
a dozen or so items. To create a file, select the @code{Open file...} choice.
Depending on the platform, you may see a pop-up window where you can browse
to an appropriate directory and then enter the file name, or else simply
see a line at the bottom of the Glide window where you can likewise enter
the file name. Note that in Glide, when you attempt to open a non-existent
file, the effect is to create a file with that name. For this example enter
@file{hello.adb} as the name of the file.
A new buffer will now appear, occupying the entire Glide window,
with the file name at the top. The menu selections are slightly different
from the ones you saw on the opening screen; there is an @code{Entities} item,
and in place of @code{Glide} there is now an @code{Ada} item. Glide uses
the file extension to identify the source language, so @file{adb} indicates
an Ada source file.
You will enter some of the source program lines explicitly,
and use the syntax-oriented template mechanism to enter other lines.
First, type the following text:
@smallexample
with Ada.Text_IO; use Ada.Text_IO;
procedure Hello is
begin
@end smallexample
@noindent
Observe that Glide uses different colors to distinguish reserved words from
identifiers. Also, after the @code{procedure Hello is} line, the cursor is
automatically indented in anticipation of declarations. When you enter
@code{begin}, Glide recognizes that there are no declarations and thus places
@code{begin} flush left. But after the @code{begin} line the cursor is again
indented, where the statement(s) will be placed.
The main part of the program will be a @code{for} loop. Instead of entering
the text explicitly, however, use a statement template. Select the @code{Ada}
item on the top menu bar, move the mouse to the @code{Statements} item,
and you will see a large selection of alternatives. Choose @code{for loop}.
You will be prompted (at the bottom of the buffer) for a loop name;
simply press the @key{Enter} key since a loop name is not needed.
You should see the beginning of a @code{for} loop appear in the source
program window. You will now be prompted for the name of the loop variable;
enter a line with the identifier @code{ind} (lower case). Note that,
by default, Glide capitalizes the name (you can override such behavior
if you wish, although this is outside the scope of this introduction).
Next, Glide prompts you for the loop range; enter a line containing
@code{1..5} and you will see this also appear in the source program,
together with the remaining elements of the @code{for} loop syntax.
Next enter the statement (with an intentional error, a missing semicolon)
that will form the body of the loop:
@smallexample
Put_Line("Hello, World" & Integer'Image(I))
@end smallexample
@noindent
Finally, type @code{end Hello;} as the last line in the program.
Now save the file: choose the @code{File} menu item, and then the
@code{Save buffer} selection. You will see a message at the bottom
of the buffer confirming that the file has been saved.
You are now ready to attempt to build the program. Select the @code{Ada}
item from the top menu bar. Although we could choose simply to compile
the file, we will instead attempt to do a build (which invokes
@command{gnatmake}) since, if the compile is successful, we want to build
an executable. Thus select @code{Ada build}. This will fail because of the
compilation error, and you will notice that the Glide window has been split:
the top window contains the source file, and the bottom window contains the
output from the GNAT tools. Glide allows you to navigate from a compilation
error to the source file position corresponding to the error: click the
middle mouse button (or simultaneously press the left and right buttons,
on a two-button mouse) on the diagnostic line in the tool window. The
focus will shift to the source window, and the cursor will be positioned
on the character at which the error was detected.
Correct the error: type in a semicolon to terminate the statement.
Although you can again save the file explicitly, you can also simply invoke
@code{Ada} @result{} @code{Build} and you will be prompted to save the file.
This time the build will succeed; the tool output window shows you the
options that are supplied by default. The GNAT tools' output (e.g.
object and ALI files, executable) will go in the directory from which
Glide was launched.
To execute the program, choose @code{Ada} and then @code{Run}.
You should see the program's output displayed in the bottom window:
@smallexample
Hello, world 1
Hello, world 2
Hello, world 3
Hello, world 4
Hello, world 5
@end smallexample
@node Simple Debugging with GVD
@subsection Simple Debugging with GVD
@noindent
This section describes how to set breakpoints, examine/modify variables,
and step through execution.
In order to enable debugging, you need to pass the @option{-g} switch
to both the compiler and to @command{gnatlink}. If you are using
the command line, passing @option{-g} to @command{gnatmake} will have
this effect. You can then launch GVD, e.g. on the @code{hello} program,
by issuing the command:
@smallexample
$ gvd hello
@end smallexample
@noindent
If you are using Glide, then @option{-g} is passed to the relevant tools
by default when you do a build. Start the debugger by selecting the
@code{Ada} menu item, and then @code{Debug}.
GVD comes up in a multi-part window. One pane shows the names of files
comprising your executable; another pane shows the source code of the current
unit (initially your main subprogram), another pane shows the debugger output
and user interactions, and the fourth pane (the data canvas at the top
of the window) displays data objects that you have selected.
To the left of the source file pane, you will notice green dots adjacent
to some lines. These are lines for which object code exists and where
breakpoints can thus be set. You set/reset a breakpoint by clicking
the green dot. When a breakpoint is set, the dot is replaced by an @code{X}
in a red circle. Clicking the circle toggles the breakpoint off,
and the red circle is replaced by the green dot.
For this example, set a breakpoint at the statement where @code{Put_Line}
is invoked.
Start program execution by selecting the @code{Run} button on the top menu bar.
(The @code{Start} button will also start your program, but it will
cause program execution to break at the entry to your main subprogram.)
Evidence of reaching the breakpoint will appear: the source file line will be
highlighted, and the debugger interactions pane will display
a relevant message.
You can examine the values of variables in several ways. Move the mouse
over an occurrence of @code{Ind} in the @code{for} loop, and you will see
the value (now @code{1}) displayed. Alternatively, right-click on @code{Ind}
and select @code{Display Ind}; a box showing the variable's name and value
will appear in the data canvas.
Although a loop index is a constant with respect to Ada semantics,
you can change its value in the debugger. Right-click in the box
for @code{Ind}, and select the @code{Set Value of Ind} item.
Enter @code{2} as the new value, and press @command{OK}.
The box for @code{Ind} shows the update.
Press the @code{Step} button on the top menu bar; this will step through
one line of program text (the invocation of @code{Put_Line}), and you can
observe the effect of having modified @code{Ind} since the value displayed
is @code{2}.
Remove the breakpoint, and resume execution by selecting the @code{Cont}
button. You will see the remaining output lines displayed in the debugger
interaction window, along with a message confirming normal program
termination.
@node Other Glide Features
@subsection Other Glide Features
@noindent
You may have observed that some of the menu selections contain abbreviations;
e.g., @code{(C-x C-f)} for @code{Open file...} in the @code{Files} menu.
These are @emph{shortcut keys} that you can use instead of selecting
menu items. The @key{C} stands for @key{Ctrl}; thus @code{(C-x C-f)} means
@key{Ctrl-x} followed by @key{Ctrl-f}, and this sequence can be used instead
of selecting @code{Files} and then @code{Open file...}.
To abort a Glide command, type @key{Ctrl-g}.
If you want Glide to start with an existing source file, you can either
launch Glide as above and then open the file via @code{Files} @result{}
@code{Open file...}, or else simply pass the name of the source file
on the command line:
@smallexample
$ glide hello.adb&
@end smallexample
@noindent
While you are using Glide, a number of @emph{buffers} exist.
You create some explicitly; e.g., when you open/create a file.
Others arise as an effect of the commands that you issue; e.g., the buffer
containing the output of the tools invoked during a build. If a buffer
is hidden, you can bring it into a visible window by first opening
the @code{Buffers} menu and then selecting the desired entry.
If a buffer occupies only part of the Glide screen and you want to expand it
to fill the entire screen, then click in the buffer and then select
@code{Files} @result{} @code{One Window}.
If a window is occupied by one buffer and you want to split the window
to bring up a second buffer, perform the following steps:
@itemize @bullet
@item Select @code{Files} @result{} @code{Split Window};
this will produce two windows each of which holds the original buffer
(these are not copies, but rather different views of the same buffer contents)
@item With the focus in one of the windows,
select the desired buffer from the @code{Buffers} menu
@end itemize
@noindent
To exit from Glide, choose @code{Files} @result{} @code{Exit}.
@end ifclear
@node The GNAT Compilation Model
@chapter The GNAT Compilation Model
@cindex GNAT compilation model
@cindex Compilation model
@menu
* Source Representation::
* Foreign Language Representation::
* File Naming Rules::
* Using Other File Names::
* Alternative File Naming Schemes::
* Generating Object Files::
* Source Dependencies::
* The Ada Library Information Files::
* Binding an Ada Program::
* Mixed Language Programming::
* Building Mixed Ada & C++ Programs::
* Comparison between GNAT and C/C++ Compilation Models::
* Comparison between GNAT and Conventional Ada Library Models::
@ifset vms
* Placement of temporary files::
@end ifset
@end menu
@noindent
This chapter describes the compilation model used by GNAT. Although
similar to that used by other languages, such as C and C++, this model
is substantially different from the traditional Ada compilation models,
which are based on a library. The model is initially described without
reference to the library-based model. If you have not previously used an
Ada compiler, you need only read the first part of this chapter. The
last section describes and discusses the differences between the GNAT
model and the traditional Ada compiler models. If you have used other
Ada compilers, this section will help you to understand those
differences, and the advantages of the GNAT model.
@node Source Representation
@section Source Representation
@cindex Latin-1
@noindent
Ada source programs are represented in standard text files, using
Latin-1 coding. Latin-1 is an 8-bit code that includes the familiar
7-bit ASCII set, plus additional characters used for
representing foreign languages (@pxref{Foreign Language Representation}
for support of non-USA character sets). The format effector characters
are represented using their standard ASCII encodings, as follows:
@table @code
@item VT
@findex VT
Vertical tab, @code{16#0B#}
@item HT
@findex HT
Horizontal tab, @code{16#09#}
@item CR
@findex CR
Carriage return, @code{16#0D#}
@item LF
@findex LF
Line feed, @code{16#0A#}
@item FF
@findex FF
Form feed, @code{16#0C#}
@end table
@noindent
Source files are in standard text file format. In addition, GNAT will
recognize a wide variety of stream formats, in which the end of physical
physical lines is marked by any of the following sequences:
@code{LF}, @code{CR}, @code{CR-LF}, or @code{LF-CR}. This is useful
in accommodating files that are imported from other operating systems.
@cindex End of source file
@cindex Source file, end
@findex SUB
The end of a source file is normally represented by the physical end of
file. However, the control character @code{16#1A#} (@code{SUB}) is also
recognized as signalling the end of the source file. Again, this is
provided for compatibility with other operating systems where this
code is used to represent the end of file.
Each file contains a single Ada compilation unit, including any pragmas
associated with the unit. For example, this means you must place a
package declaration (a package @dfn{spec}) and the corresponding body in
separate files. An Ada @dfn{compilation} (which is a sequence of
compilation units) is represented using a sequence of files. Similarly,
you will place each subunit or child unit in a separate file.
@node Foreign Language Representation
@section Foreign Language Representation
@noindent
GNAT supports the standard character sets defined in Ada 95 as well as
several other non-standard character sets for use in localized versions
of the compiler (@pxref{Character Set Control}).
@menu
* Latin-1::
* Other 8-Bit Codes::
* Wide Character Encodings::
@end menu
@node Latin-1
@subsection Latin-1
@cindex Latin-1
@noindent
The basic character set is Latin-1. This character set is defined by ISO
standard 8859, part 1. The lower half (character codes @code{16#00#}
... @code{16#7F#)} is identical to standard ASCII coding, but the upper half
is used to represent additional characters. These include extended letters
used by European languages, such as French accents, the vowels with umlauts
used in German, and the extra letter A-ring used in Swedish.
@findex Ada.Characters.Latin_1
For a complete list of Latin-1 codes and their encodings, see the source
file of library unit @code{Ada.Characters.Latin_1} in file
@file{a-chlat1.ads}.
You may use any of these extended characters freely in character or
string literals. In addition, the extended characters that represent
letters can be used in identifiers.
@node Other 8-Bit Codes
@subsection Other 8-Bit Codes
@noindent
GNAT also supports several other 8-bit coding schemes:
@table @asis
@item ISO 8859-2 (Latin-2)
@cindex Latin-2
@cindex ISO 8859-2
Latin-2 letters allowed in identifiers, with uppercase and lowercase
equivalence.
@item ISO 8859-3 (Latin-3)
@cindex Latin-3
@cindex ISO 8859-3
Latin-3 letters allowed in identifiers, with uppercase and lowercase
equivalence.
@item ISO 8859-4 (Latin-4)
@cindex Latin-4
@cindex ISO 8859-4
Latin-4 letters allowed in identifiers, with uppercase and lowercase
equivalence.
@item ISO 8859-5 (Cyrillic)
@cindex ISO 8859-5
@cindex Cyrillic
ISO 8859-5 letters (Cyrillic) allowed in identifiers, with uppercase and
lowercase equivalence.
@item ISO 8859-15 (Latin-9)
@cindex ISO 8859-15
@cindex Latin-9
ISO 8859-15 (Latin-9) letters allowed in identifiers, with uppercase and
lowercase equivalence
@item IBM PC (code page 437)
@cindex code page 437
This code page is the normal default for PCs in the U.S. It corresponds
to the original IBM PC character set. This set has some, but not all, of
the extended Latin-1 letters, but these letters do not have the same
encoding as Latin-1. In this mode, these letters are allowed in
identifiers with uppercase and lowercase equivalence.
@item IBM PC (code page 850)
@cindex code page 850
This code page is a modification of 437 extended to include all the
Latin-1 letters, but still not with the usual Latin-1 encoding. In this
mode, all these letters are allowed in identifiers with uppercase and
lowercase equivalence.
@item Full Upper 8-bit
Any character in the range 80-FF allowed in identifiers, and all are
considered distinct. In other words, there are no uppercase and lowercase
equivalences in this range. This is useful in conjunction with
certain encoding schemes used for some foreign character sets (e.g.
the typical method of representing Chinese characters on the PC).
@item No Upper-Half
No upper-half characters in the range 80-FF are allowed in identifiers.
This gives Ada 83 compatibility for identifier names.
@end table
@noindent
For precise data on the encodings permitted, and the uppercase and lowercase
equivalences that are recognized, see the file @file{csets.adb} in
the GNAT compiler sources. You will need to obtain a full source release
of GNAT to obtain this file.
@node Wide Character Encodings
@subsection Wide Character Encodings
@noindent
GNAT allows wide character codes to appear in character and string
literals, and also optionally in identifiers, by means of the following
possible encoding schemes:
@table @asis
@item Hex Coding
In this encoding, a wide character is represented by the following five
character sequence:
@smallexample
ESC a b c d
@end smallexample
@noindent
Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, ESC A345 is used to represent the wide character with code
@code{16#A345#}.
This scheme is compatible with use of the full Wide_Character set.
@item Upper-Half Coding
@cindex Upper-Half Coding
The wide character with encoding @code{16#abcd#} where the upper bit is on
(in other words, ``a'' is in the range 8-F) is represented as two bytes,
@code{16#ab#} and @code{16#cd#}. The second byte cannot be a format control
character, but is not required to be in the upper half. This method can
be also used for shift-JIS or EUC, where the internal coding matches the
external coding.
@item Shift JIS Coding
@cindex Shift JIS Coding
A wide character is represented by a two-character sequence,
@code{16#ab#} and
@code{16#cd#}, with the restrictions described for upper-half encoding as
described above. The internal character code is the corresponding JIS
character according to the standard algorithm for Shift-JIS
conversion. Only characters defined in the JIS code set table can be
used with this encoding method.
@item EUC Coding
@cindex EUC Coding
A wide character is represented by a two-character sequence
@code{16#ab#} and
@code{16#cd#}, with both characters being in the upper half. The internal
character code is the corresponding JIS character according to the EUC
encoding algorithm. Only characters defined in the JIS code set table
can be used with this encoding method.
@item UTF-8 Coding
A wide character is represented using
UCS Transformation Format 8 (UTF-8) as defined in Annex R of ISO
10646-1/Am.2. Depending on the character value, the representation
is a one, two, or three byte sequence:
@smallexample
@iftex
@leftskip=.7cm
@end iftex
16#0000#-16#007f#: 2#0xxxxxxx#
16#0080#-16#07ff#: 2#110xxxxx# 2#10xxxxxx#
16#0800#-16#ffff#: 2#1110xxxx# 2#10xxxxxx# 2#10xxxxxx#
@end smallexample
@noindent
where the xxx bits correspond to the left-padded bits of the
16-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
(The full UTF-8 scheme allows for encoding 31-bit characters as
6-byte sequences, but in this implementation, all UTF-8 sequences
of four or more bytes length will be treated as illegal).
@item Brackets Coding
In this encoding, a wide character is represented by the following eight
character sequence:
@smallexample
[ " a b c d " ]
@end smallexample
@noindent
Where @code{a}, @code{b}, @code{c}, @code{d} are the four hexadecimal
characters (using uppercase letters) of the wide character code. For
example, [``A345''] is used to represent the wide character with code
@code{16#A345#}. It is also possible (though not required) to use the
Brackets coding for upper half characters. For example, the code
@code{16#A3#} can be represented as @code{[``A3'']}.
This scheme is compatible with use of the full Wide_Character set,
and is also the method used for wide character encoding in the standard
ACVC (Ada Compiler Validation Capability) test suite distributions.
@end table
@noindent
Note: Some of these coding schemes do not permit the full use of the
Ada 95 character set. For example, neither Shift JIS, nor EUC allow the
use of the upper half of the Latin-1 set.
@node File Naming Rules
@section File Naming Rules
@noindent
The default file name is determined by the name of the unit that the
file contains. The name is formed by taking the full expanded name of
the unit and replacing the separating dots with hyphens and using
^lowercase^uppercase^ for all letters.
An exception arises if the file name generated by the above rules starts
with one of the characters
@ifset vms
A,G,I, or S,
@end ifset
@ifclear vms
a,g,i, or s,
@end ifclear
and the second character is a
minus. In this case, the character ^tilde^dollar sign^ is used in place
of the minus. The reason for this special rule is to avoid clashes with
the standard names for child units of the packages System, Ada,
Interfaces, and GNAT, which use the prefixes
@ifset vms
S- A- I- and G-
@end ifset
@ifclear vms
s- a- i- and g-
@end ifclear
respectively.
The file extension is @file{.ads} for a spec and
@file{.adb} for a body. The following list shows some
examples of these rules.
@table @file
@item main.ads
Main (spec)
@item main.adb
Main (body)
@item arith_functions.ads
Arith_Functions (package spec)
@item arith_functions.adb
Arith_Functions (package body)
@item func-spec.ads
Func.Spec (child package spec)
@item func-spec.adb
Func.Spec (child package body)
@item main-sub.adb
Sub (subunit of Main)
@item ^a~bad.adb^A$BAD.ADB^
A.Bad (child package body)
@end table
@noindent
Following these rules can result in excessively long
file names if corresponding
unit names are long (for example, if child units or subunits are
heavily nested). An option is available to shorten such long file names
(called file name ``krunching''). This may be particularly useful when
programs being developed with GNAT are to be used on operating systems
with limited file name lengths. @xref{Using gnatkr}.
Of course, no file shortening algorithm can guarantee uniqueness over
all possible unit names; if file name krunching is used, it is your
responsibility to ensure no name clashes occur. Alternatively you
can specify the exact file names that you want used, as described
in the next section. Finally, if your Ada programs are migrating from a
compiler with a different naming convention, you can use the gnatchop
utility to produce source files that follow the GNAT naming conventions.
(For details @pxref{Renaming Files Using gnatchop}.)
Note: in the case of @code{Windows NT/XP} or @code{OpenVMS} operating
systems, case is not significant. So for example on @code{Windows XP}
if the canonical name is @code{main-sub.adb}, you can use the file name
@code{Main-Sub.adb} instead. However, case is significant for other
operating systems, so for example, if you want to use other than
canonically cased file names on a Unix system, you need to follow
the procedures described in the next section.
@node Using Other File Names
@section Using Other File Names
@cindex File names
@noindent
In the previous section, we have described the default rules used by
GNAT to determine the file name in which a given unit resides. It is
often convenient to follow these default rules, and if you follow them,
the compiler knows without being explicitly told where to find all
the files it needs.
However, in some cases, particularly when a program is imported from
another Ada compiler environment, it may be more convenient for the
programmer to specify which file names contain which units. GNAT allows
arbitrary file names to be used by means of the Source_File_Name pragma.
The form of this pragma is as shown in the following examples:
@cindex Source_File_Name pragma
@smallexample @c ada
@cartouche
pragma Source_File_Name (My_Utilities.Stacks,
Spec_File_Name => "myutilst_a.ada");
pragma Source_File_name (My_Utilities.Stacks,
Body_File_Name => "myutilst.ada");
@end cartouche
@end smallexample
@noindent
As shown in this example, the first argument for the pragma is the unit
name (in this example a child unit). The second argument has the form
of a named association. The identifier
indicates whether the file name is for a spec or a body;
the file name itself is given by a string literal.
The source file name pragma is a configuration pragma, which means that
normally it will be placed in the @file{gnat.adc}
file used to hold configuration
pragmas that apply to a complete compilation environment.
For more details on how the @file{gnat.adc} file is created and used
@pxref{Handling of Configuration Pragmas}
@cindex @file{gnat.adc}
@ifclear vms
GNAT allows completely arbitrary file names to be specified using the
source file name pragma. However, if the file name specified has an
extension other than @file{.ads} or @file{.adb} it is necessary to use
a special syntax when compiling the file. The name in this case must be
preceded by the special sequence @code{-x} followed by a space and the name
of the language, here @code{ada}, as in:
@smallexample
$ gcc -c -x ada peculiar_file_name.sim
@end smallexample
@end ifclear
@noindent
@code{gnatmake} handles non-standard file names in the usual manner (the
non-standard file name for the main program is simply used as the
argument to gnatmake). Note that if the extension is also non-standard,
then it must be included in the gnatmake command, it may not be omitted.
@node Alternative File Naming Schemes
@section Alternative File Naming Schemes
@cindex File naming schemes, alternative
@cindex File names
In the previous section, we described the use of the @code{Source_File_Name}
pragma to allow arbitrary names to be assigned to individual source files.
However, this approach requires one pragma for each file, and especially in
large systems can result in very long @file{gnat.adc} files, and also create
a maintenance problem.
GNAT also provides a facility for specifying systematic file naming schemes
other than the standard default naming scheme previously described. An
alternative scheme for naming is specified by the use of
@code{Source_File_Name} pragmas having the following format:
@cindex Source_File_Name pragma
@smallexample @c ada
pragma Source_File_Name (
Spec_File_Name => FILE_NAME_PATTERN
[,Casing => CASING_SPEC]
[,Dot_Replacement => STRING_LITERAL]);
pragma Source_File_Name (
Body_File_Name => FILE_NAME_PATTERN
[,Casing => CASING_SPEC]
[,Dot_Replacement => STRING_LITERAL]);
pragma Source_File_Name (
Subunit_File_Name => FILE_NAME_PATTERN
[,Casing => CASING_SPEC]
[,Dot_Replacement => STRING_LITERAL]);
FILE_NAME_PATTERN ::= STRING_LITERAL
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
@end smallexample
@noindent
The @code{FILE_NAME_PATTERN} string shows how the file name is constructed.
It contains a single asterisk character, and the unit name is substituted
systematically for this asterisk. The optional parameter
@code{Casing} indicates
whether the unit name is to be all upper-case letters, all lower-case letters,
or mixed-case. If no
@code{Casing} parameter is used, then the default is all
^lower-case^upper-case^.
The optional @code{Dot_Replacement} string is used to replace any periods
that occur in subunit or child unit names. If no @code{Dot_Replacement}
argument is used then separating dots appear unchanged in the resulting
file name.
Although the above syntax indicates that the
@code{Casing} argument must appear
before the @code{Dot_Replacement} argument, but it
is also permissible to write these arguments in the opposite order.
As indicated, it is possible to specify different naming schemes for
bodies, specs, and subunits. Quite often the rule for subunits is the
same as the rule for bodies, in which case, there is no need to give
a separate @code{Subunit_File_Name} rule, and in this case the
@code{Body_File_name} rule is used for subunits as well.
The separate rule for subunits can also be used to implement the rather
unusual case of a compilation environment (e.g. a single directory) which
contains a subunit and a child unit with the same unit name. Although
both units cannot appear in the same partition, the Ada Reference Manual
allows (but does not require) the possibility of the two units coexisting
in the same environment.
The file name translation works in the following steps:
@itemize @bullet
@item
If there is a specific @code{Source_File_Name} pragma for the given unit,
then this is always used, and any general pattern rules are ignored.
@item
If there is a pattern type @code{Source_File_Name} pragma that applies to
the unit, then the resulting file name will be used if the file exists. If
more than one pattern matches, the latest one will be tried first, and the
first attempt resulting in a reference to a file that exists will be used.
@item
If no pattern type @code{Source_File_Name} pragma that applies to the unit
for which the corresponding file exists, then the standard GNAT default
naming rules are used.
@end itemize
@noindent
As an example of the use of this mechanism, consider a commonly used scheme
in which file names are all lower case, with separating periods copied
unchanged to the resulting file name, and specs end with @file{.1.ada}, and
bodies end with @file{.2.ada}. GNAT will follow this scheme if the following
two pragmas appear:
@smallexample @c ada
pragma Source_File_Name
(Spec_File_Name => "*.1.ada");
pragma Source_File_Name
(Body_File_Name => "*.2.ada");
@end smallexample
@noindent
The default GNAT scheme is actually implemented by providing the following
default pragmas internally:
@smallexample @c ada
pragma Source_File_Name
(Spec_File_Name => "*.ads", Dot_Replacement => "-");
pragma Source_File_Name
(Body_File_Name => "*.adb", Dot_Replacement => "-");
@end smallexample
@noindent
Our final example implements a scheme typically used with one of the
Ada 83 compilers, where the separator character for subunits was ``__''
(two underscores), specs were identified by adding @file{_.ADA}, bodies
by adding @file{.ADA}, and subunits by
adding @file{.SEP}. All file names were
upper case. Child units were not present of course since this was an
Ada 83 compiler, but it seems reasonable to extend this scheme to use
the same double underscore separator for child units.
@smallexample @c ada
pragma Source_File_Name
(Spec_File_Name => "*_.ADA",
Dot_Replacement => "__",
Casing = Uppercase);
pragma Source_File_Name
(Body_File_Name => "*.ADA",
Dot_Replacement => "__",
Casing = Uppercase);
pragma Source_File_Name
(Subunit_File_Name => "*.SEP",
Dot_Replacement => "__",
Casing = Uppercase);
@end smallexample
@node Generating Object Files
@section Generating Object Files
@noindent
An Ada program consists of a set of source files, and the first step in
compiling the program is to generate the corresponding object files.
These are generated by compiling a subset of these source files.
The files you need to compile are the following:
@itemize @bullet
@item
If a package spec has no body, compile the package spec to produce the
object file for the package.
@item
If a package has both a spec and a body, compile the body to produce the
object file for the package. The source file for the package spec need
not be compiled in this case because there is only one object file, which
contains the code for both the spec and body of the package.
@item
For a subprogram, compile the subprogram body to produce the object file
for the subprogram. The spec, if one is present, is as usual in a
separate file, and need not be compiled.
@item
@cindex Subunits
In the case of subunits, only compile the parent unit. A single object
file is generated for the entire subunit tree, which includes all the
subunits.
@item
Compile child units independently of their parent units
(though, of course, the spec of all the ancestor unit must be present in order
to compile a child unit).
@item
@cindex Generics
Compile generic units in the same manner as any other units. The object
files in this case are small dummy files that contain at most the
flag used for elaboration checking. This is because GNAT always handles generic
instantiation by means of macro expansion. However, it is still necessary to
compile generic units, for dependency checking and elaboration purposes.
@end itemize
@noindent
The preceding rules describe the set of files that must be compiled to
generate the object files for a program. Each object file has the same
name as the corresponding source file, except that the extension is
@file{.o} as usual.
You may wish to compile other files for the purpose of checking their
syntactic and semantic correctness. For example, in the case where a
package has a separate spec and body, you would not normally compile the
spec. However, it is convenient in practice to compile the spec to make
sure it is error-free before compiling clients of this spec, because such
compilations will fail if there is an error in the spec.
GNAT provides an option for compiling such files purely for the
purposes of checking correctness; such compilations are not required as
part of the process of building a program. To compile a file in this
checking mode, use the @option{-gnatc} switch.
@node Source Dependencies
@section Source Dependencies
@noindent
A given object file clearly depends on the source file which is compiled
to produce it. Here we are using @dfn{depends} in the sense of a typical
@code{make} utility; in other words, an object file depends on a source
file if changes to the source file require the object file to be
recompiled.
In addition to this basic dependency, a given object may depend on
additional source files as follows:
@itemize @bullet
@item
If a file being compiled @code{with}'s a unit @var{X}, the object file
depends on the file containing the spec of unit @var{X}. This includes
files that are @code{with}'ed implicitly either because they are parents
of @code{with}'ed child units or they are run-time units required by the
language constructs used in a particular unit.
@item
If a file being compiled instantiates a library level generic unit, the
object file depends on both the spec and body files for this generic
unit.
@item
If a file being compiled instantiates a generic unit defined within a
package, the object file depends on the body file for the package as
well as the spec file.
@item
@findex Inline
@cindex @option{-gnatn} switch
If a file being compiled contains a call to a subprogram for which
pragma @code{Inline} applies and inlining is activated with the
@option{-gnatn} switch, the object file depends on the file containing the
body of this subprogram as well as on the file containing the spec. Note
that for inlining to actually occur as a result of the use of this switch,
it is necessary to compile in optimizing mode.
@cindex @option{-gnatN} switch
The use of @option{-gnatN} activates a more extensive inlining optimization
that is performed by the front end of the compiler. This inlining does
not require that the code generation be optimized. Like @option{-gnatn},
the use of this switch generates additional dependencies.
Note that
@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
to specify both options.
@item
If an object file O depends on the proper body of a subunit through inlining
or instantiation, it depends on the parent unit of the subunit. This means that
any modification of the parent unit or one of its subunits affects the
compilation of O.
@item
The object file for a parent unit depends on all its subunit body files.
@item
The previous two rules meant that for purposes of computing dependencies and
recompilation, a body and all its subunits are treated as an indivisible whole.
@noindent
These rules are applied transitively: if unit @code{A} @code{with}'s
unit @code{B}, whose elaboration calls an inlined procedure in package
@code{C}, the object file for unit @code{A} will depend on the body of
@code{C}, in file @file{c.adb}.
The set of dependent files described by these rules includes all the
files on which the unit is semantically dependent, as described in the
Ada 95 Language Reference Manual. However, it is a superset of what the
ARM describes, because it includes generic, inline, and subunit dependencies.
An object file must be recreated by recompiling the corresponding source
file if any of the source files on which it depends are modified. For
example, if the @code{make} utility is used to control compilation,
the rule for an Ada object file must mention all the source files on
which the object file depends, according to the above definition.
The determination of the necessary
recompilations is done automatically when one uses @code{gnatmake}.
@end itemize
@node The Ada Library Information Files
@section The Ada Library Information Files
@cindex Ada Library Information files
@cindex @file{ALI} files
@noindent
Each compilation actually generates two output files. The first of these
is the normal object file that has a @file{.o} extension. The second is a
text file containing full dependency information. It has the same
name as the source file, but an @file{.ali} extension.
This file is known as the Ada Library Information (@file{ALI}) file.
The following information is contained in the @file{ALI} file.
@itemize @bullet
@item
Version information (indicates which version of GNAT was used to compile
the unit(s) in question)
@item
Main program information (including priority and time slice settings,
as well as the wide character encoding used during compilation).
@item
List of arguments used in the @code{gcc} command for the compilation
@item
Attributes of the unit, including configuration pragmas used, an indication
of whether the compilation was successful, exception model used etc.
@item
A list of relevant restrictions applying to the unit (used for consistency)
checking.
@item
Categorization information (e.g. use of pragma @code{Pure}).
@item
Information on all @code{with}'ed units, including presence of
@code{Elaborate} or @code{Elaborate_All} pragmas.
@item
Information from any @code{Linker_Options} pragmas used in the unit
@item
Information on the use of @code{Body_Version} or @code{Version}
attributes in the unit.
@item
Dependency information. This is a list of files, together with
time stamp and checksum information. These are files on which
the unit depends in the sense that recompilation is required
if any of these units are modified.
@item
Cross-reference data. Contains information on all entities referenced
in the unit. Used by tools like @code{gnatxref} and @code{gnatfind} to
provide cross-reference information.
@end itemize
@noindent
For a full detailed description of the format of the @file{ALI} file,
see the source of the body of unit @code{Lib.Writ}, contained in file
@file{lib-writ.adb} in the GNAT compiler sources.
@node Binding an Ada Program
@section Binding an Ada Program
@noindent
When using languages such as C and C++, once the source files have been
compiled the only remaining step in building an executable program
is linking the object modules together. This means that it is possible to
link an inconsistent version of a program, in which two units have
included different versions of the same header.
The rules of Ada do not permit such an inconsistent program to be built.
For example, if two clients have different versions of the same package,
it is illegal to build a program containing these two clients.
These rules are enforced by the GNAT binder, which also determines an
elaboration order consistent with the Ada rules.
The GNAT binder is run after all the object files for a program have
been created. It is given the name of the main program unit, and from
this it determines the set of units required by the program, by reading the
corresponding ALI files. It generates error messages if the program is
inconsistent or if no valid order of elaboration exists.
If no errors are detected, the binder produces a main program, in Ada by
default, that contains calls to the elaboration procedures of those
compilation unit that require them, followed by
a call to the main program. This Ada program is compiled to generate the
object file for the main program. The name of
the Ada file is @file{b~@var{xxx}.adb} (with the corresponding spec
@file{b~@var{xxx}.ads}) where @var{xxx} is the name of the
main program unit.
Finally, the linker is used to build the resulting executable program,
using the object from the main program from the bind step as well as the
object files for the Ada units of the program.
@node Mixed Language Programming
@section Mixed Language Programming
@cindex Mixed Language Programming
@noindent
This section describes how to develop a mixed-language program,
specifically one that comprises units in both Ada and C.
@menu
* Interfacing to C::
* Calling Conventions::
@end menu
@node Interfacing to C
@subsection Interfacing to C
@noindent
Interfacing Ada with a foreign language such as C involves using
compiler directives to import and/or export entity definitions in each
language---using @code{extern} statements in C, for instance, and the
@code{Import}, @code{Export}, and @code{Convention} pragmas in Ada. For
a full treatment of these topics, read Appendix B, section 1 of the Ada
95 Language Reference Manual.
There are two ways to build a program using GNAT that contains some Ada
sources and some foreign language sources, depending on whether or not
the main subprogram is written in Ada. Here is a source example with
the main subprogram in Ada:
@smallexample
/* file1.c */
#include <stdio.h>
void print_num (int num)
@{
printf ("num is %d.\n", num);
return;
@}
/* file2.c */
/* num_from_Ada is declared in my_main.adb */
extern int num_from_Ada;
int get_num (void)
@{
return num_from_Ada;
@}
@end smallexample
@smallexample @c ada
-- my_main.adb
procedure My_Main is
-- Declare then export an Integer entity called num_from_Ada
My_Num : Integer := 10;
pragma Export (C, My_Num, "num_from_Ada");
-- Declare an Ada function spec for Get_Num, then use
-- C function get_num for the implementation.
function Get_Num return Integer;
pragma Import (C, Get_Num, "get_num");
-- Declare an Ada procedure spec for Print_Num, then use
-- C function print_num for the implementation.
procedure Print_Num (Num : Integer);
pragma Import (C, Print_Num, "print_num");
begin
Print_Num (Get_Num);
end My_Main;
@end smallexample
@enumerate
@item
To build this example, first compile the foreign language files to
generate object files:
@smallexample
gcc -c file1.c
gcc -c file2.c
@end smallexample
@item
Then, compile the Ada units to produce a set of object files and ALI
files:
@smallexample
gnatmake ^-c^/ACTIONS=COMPILE^ my_main.adb
@end smallexample
@item
Run the Ada binder on the Ada main program:
@smallexample
gnatbind my_main.ali
@end smallexample
@item
Link the Ada main program, the Ada objects and the other language
objects:
@smallexample
gnatlink my_main.ali file1.o file2.o
@end smallexample
@end enumerate
The last three steps can be grouped in a single command:
@smallexample
gnatmake my_main.adb -largs file1.o file2.o
@end smallexample
@cindex Binder output file
@noindent
If the main program is in a language other than Ada, then you may have
more than one entry point into the Ada subsystem. You must use a special
binder option to generate callable routines that initialize and
finalize the Ada units (@pxref{Binding with Non-Ada Main Programs}).
Calls to the initialization and finalization routines must be inserted
in the main program, or some other appropriate point in the code. The
call to initialize the Ada units must occur before the first Ada
subprogram is called, and the call to finalize the Ada units must occur
after the last Ada subprogram returns. The binder will place the
initialization and finalization subprograms into the
@file{b~@var{xxx}.adb} file where they can be accessed by your C
sources. To illustrate, we have the following example:
@smallexample
/* main.c */
extern void adainit (void);
extern void adafinal (void);
extern int add (int, int);
extern int sub (int, int);
int main (int argc, char *argv[])
@{
int a = 21, b = 7;
adainit();
/* Should print "21 + 7 = 28" */
printf ("%d + %d = %d\n", a, b, add (a, b));
/* Should print "21 - 7 = 14" */
printf ("%d - %d = %d\n", a, b, sub (a, b));
adafinal();
@}
@end smallexample
@smallexample @c ada
-- unit1.ads
package Unit1 is
function Add (A, B : Integer) return Integer;
pragma Export (C, Add, "add");
end Unit1;
-- unit1.adb
package body Unit1 is
function Add (A, B : Integer) return Integer is
begin
return A + B;
end Add;
end Unit1;
-- unit2.ads
package Unit2 is
function Sub (A, B : Integer) return Integer;
pragma Export (C, Sub, "sub");
end Unit2;
-- unit2.adb
package body Unit2 is
function Sub (A, B : Integer) return Integer is
begin
return A - B;
end Sub;
end Unit2;
@end smallexample
@enumerate
@item
The build procedure for this application is similar to the last
example's. First, compile the foreign language files to generate object
files:
@smallexample
gcc -c main.c
@end smallexample
@item
Next, compile the Ada units to produce a set of object files and ALI
files:
@smallexample
gnatmake ^-c^/ACTIONS=COMPILE^ unit1.adb
gnatmake ^-c^/ACTIONS=COMPILE^ unit2.adb
@end smallexample
@item
Run the Ada binder on every generated ALI file. Make sure to use the
@option{-n} option to specify a foreign main program:
@smallexample
gnatbind ^-n^/NOMAIN^ unit1.ali unit2.ali
@end smallexample
@item
Link the Ada main program, the Ada objects and the foreign language
objects. You need only list the last ALI file here:
@smallexample
gnatlink unit2.ali main.o -o exec_file
@end smallexample
This procedure yields a binary executable called @file{exec_file}.
@end enumerate
@node Calling Conventions
@subsection Calling Conventions
@cindex Foreign Languages
@cindex Calling Conventions
GNAT follows standard calling sequence conventions and will thus interface
to any other language that also follows these conventions. The following
Convention identifiers are recognized by GNAT:
@table @code
@cindex Interfacing to Ada
@cindex Other Ada compilers
@cindex Convention Ada
@item Ada
This indicates that the standard Ada calling sequence will be
used and all Ada data items may be passed without any limitations in the
case where GNAT is used to generate both the caller and callee. It is also
possible to mix GNAT generated code and code generated by another Ada
compiler. In this case, the data types should be restricted to simple
cases, including primitive types. Whether complex data types can be passed
depends on the situation. Probably it is safe to pass simple arrays, such
as arrays of integers or floats. Records may or may not work, depending
on whether both compilers lay them out identically. Complex structures
involving variant records, access parameters, tasks, or protected types,
are unlikely to be able to be passed.
Note that in the case of GNAT running
on a platform that supports DEC Ada 83, a higher degree of compatibility
can be guaranteed, and in particular records are layed out in an identical
manner in the two compilers. Note also that if output from two different
compilers is mixed, the program is responsible for dealing with elaboration
issues. Probably the safest approach is to write the main program in the
version of Ada other than GNAT, so that it takes care of its own elaboration
requirements, and then call the GNAT-generated adainit procedure to ensure
elaboration of the GNAT components. Consult the documentation of the other
Ada compiler for further details on elaboration.
However, it is not possible to mix the tasking run time of GNAT and
DEC Ada 83, All the tasking operations must either be entirely within
GNAT compiled sections of the program, or entirely within DEC Ada 83
compiled sections of the program.
@cindex Interfacing to Assembly
@cindex Convention Assembler
@item Assembler
Specifies assembler as the convention. In practice this has the
same effect as convention Ada (but is not equivalent in the sense of being
considered the same convention).
@cindex Convention Asm
@findex Asm
@item Asm
Equivalent to Assembler.
@cindex Interfacing to COBOL
@cindex Convention COBOL
@findex COBOL
@item COBOL
Data will be passed according to the conventions described
in section B.4 of the Ada 95 Reference Manual.
@findex C
@cindex Interfacing to C
@cindex Convention C
@item C
Data will be passed according to the conventions described
in section B.3 of the Ada 95 Reference Manual.
@cindex Convention Default
@findex Default
@item Default
Equivalent to C.
@cindex Convention External
@findex External
@item External
Equivalent to C.
@findex C++
@cindex Interfacing to C++
@cindex Convention C++
@item CPP
This stands for C++. For most purposes this is identical to C.
See the separate description of the specialized GNAT pragmas relating to
C++ interfacing for further details.
@findex Fortran
@cindex Interfacing to Fortran
@cindex Convention Fortran
@item Fortran
Data will be passed according to the conventions described
in section B.5 of the Ada 95 Reference Manual.
@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,
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
only be applied to the following two sets of names, which the GNAT compiler
recognizes.
@itemize @bullet
@item
Rotate_Left, Rotate_Right, Shift_Left, Shift_Right, Shift_Right_-
Arithmetic. The corresponding subprogram declaration must have
two formal parameters. The
first one must be a signed integer type or a modular type with a binary
modulus, and the second parameter must be of type Natural.
The return type must be the same as the type of the first argument. The size
of this type can only be 8, 16, 32, or 64.
@item binary arithmetic operators: ``+'', ``-'', ``*'', ``/''
The corresponding operator declaration must have parameters and result type
that have the same root numeric type (for example, all three are long_float
types). This simplifies the definition of operations that use type checking
to perform dimensional checks:
@smallexample @c ada
type Distance is new Long_Float;
type Time is new Long_Float;
type Velocity is new Long_Float;
function "/" (D : Distance; T : Time)
return Velocity;
pragma Import (Intrinsic, "/");
@end smallexample
@noindent
This common idiom is often programmed with a generic definition and an
explicit body. The pragma makes it simpler to introduce such declarations.
It incurs no overhead in compilation time or code size, because it is
implemented as a single machine instruction.
@end itemize
@noindent
@ifset unw
@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.
@findex DLL
@cindex Convention DLL
@item DLL
This is equivalent to Stdcall.
@findex Win32
@cindex Convention Win32
@item Win32
This is equivalent to Stdcall.
@end ifset
@findex Stubbed
@cindex Convention Stubbed
@item Stubbed
This is a special convention that indicates that the compiler
should provide a stub body that raises @code{Program_Error}.
@end table
@noindent
GNAT additionally provides a useful pragma @code{Convention_Identifier}
that can be used to parametrize conventions and allow additional synonyms
to be specified. For example if you have legacy code in which the convention
identifier Fortran77 was used for Fortran, you can use the configuration
pragma:
@smallexample @c ada
pragma Convention_Identifier (Fortran77, Fortran);
@end smallexample
@noindent
And from now on the identifier Fortran77 may be used as a convention
identifier (for example in an @code{Import} pragma) with the same
meaning as Fortran.
@node Building Mixed Ada & C++ Programs
@section Building Mixed Ada & C++ Programs
@noindent
A programmer inexperienced with mixed-language development may find that
building an application containing both Ada and C++ code can be a
challenge. As a matter of fact, interfacing with C++ has not been
standardized in the Ada 95 Reference Manual due to the immaturity of --
and lack of standards for -- C++ at the time. This section gives a few
hints that should make this task easier. The first section addresses
the differences regarding interfacing with C. The second section
looks into the delicate problem of linking the complete application from
its Ada and C++ parts. The last section gives some hints on how the GNAT
run time can be adapted in order to allow inter-language dispatching
with a new C++ compiler.
@menu
* Interfacing to C++::
* Linking a Mixed C++ & Ada Program::
* A Simple Example::
* Adapting the Run Time to a New C++ Compiler::
@end menu
@node Interfacing to C++
@subsection Interfacing to C++
@noindent
GNAT supports interfacing with C++ compilers generating code that is
compatible with the standard Application Binary Interface of the given
platform.
@noindent
Interfacing can be done at 3 levels: simple data, subprograms, and
classes. In the first two cases, GNAT offers a specific @var{Convention
CPP} that behaves exactly like @var{Convention C}. Usually, C++ mangles
the names of subprograms, and currently, GNAT does not provide any help
to solve the demangling problem. This problem can be addressed in two
ways:
@itemize @bullet
@item
by modifying the C++ code in order to force a C convention using
the @code{extern "C"} syntax.
@item
by figuring out the mangled name and use it as the Link_Name argument of
the pragma import.
@end itemize
@noindent
Interfacing at the class level can be achieved by using the GNAT specific
pragmas such as @code{CPP_Class} and @code{CPP_Virtual}. See the GNAT
Reference Manual for additional information.
@node Linking a Mixed C++ & Ada Program
@subsection Linking a Mixed C++ & Ada Program
@noindent
Usually the linker of the C++ development system must be used to link
mixed applications because most C++ systems will resolve elaboration
issues (such as calling constructors on global class instances)
transparently during the link phase. GNAT has been adapted to ease the
use of a foreign linker for the last phase. Three cases can be
considered:
@enumerate
@item
Using GNAT and G++ (GNU C++ compiler) from the same GCC installation:
The C++ linker can simply be called by using the C++ specific driver
called @code{c++}. Note that this setup is not very common because it
may involve recompiling the whole GCC tree from sources, which makes it
harder to upgrade the compilation system for one language without
destabilizing the other.
@smallexample
$ c++ -c file1.C
$ c++ -c file2.C
$ gnatmake ada_unit -largs file1.o file2.o --LINK=c++
@end smallexample
@item
Using GNAT and G++ from two different GCC installations: If both
compilers are on the PATH, the previous method may be used. It is
important to note that environment variables such as C_INCLUDE_PATH,
GCC_EXEC_PREFIX, BINUTILS_ROOT, and GCC_ROOT will affect both compilers
at the same time and may make one of the two compilers operate
improperly if set during invocation of the wrong compiler. It is also
very important that the linker uses the proper @file{libgcc.a} GCC
library -- that is, the one from the C++ compiler installation. The
implicit link command as suggested in the gnatmake command from the
former example can be replaced by an explicit link command with the
full-verbosity option in order to verify which library is used:
@smallexample
$ gnatbind ada_unit
$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
@end smallexample
If there is a problem due to interfering environment variables, it can
be worked around by using an intermediate script. The following example
shows the proper script to use when GNAT has not been installed at its
default location and g++ has been installed at its default location:
@smallexample
$ cat ./my_script
#!/bin/sh
unset BINUTILS_ROOT
unset GCC_ROOT
c++ $*
$ gnatlink -v -v ada_unit file1.o file2.o --LINK=./my_script
@end smallexample
@item
Using a non-GNU C++ compiler: The commands previously described can be
used to insure that the C++ linker is used. Nonetheless, you need to add
the path to libgcc explicitly, since some libraries needed by GNAT are
located in this directory:
@smallexample
$ cat ./my_script
#!/bin/sh
CC $* `gcc -print-libgcc-file-name`
$ gnatlink ada_unit file1.o file2.o --LINK=./my_script
@end smallexample
Where CC is the name of the non-GNU C++ compiler.
@end enumerate
@node A Simple Example
@subsection A Simple Example
@noindent
The following example, provided as part of the GNAT examples, shows how
to achieve procedural interfacing between Ada and C++ in both
directions. The C++ class A has two methods. The first method is exported
to Ada by the means of an extern C wrapper function. The second method
calls an Ada subprogram. On the Ada side, The C++ calls are modelled by
a limited record with a layout comparable to the C++ class. The Ada
subprogram, in turn, calls the C++ method. So, starting from the C++
main program, the process passes back and forth between the two
languages.
@noindent
Here are the compilation commands:
@smallexample
$ gnatmake -c simple_cpp_interface
$ c++ -c cpp_main.C
$ c++ -c ex7.C
$ gnatbind -n simple_cpp_interface
$ gnatlink simple_cpp_interface -o cpp_main --LINK=$(CPLUSPLUS)
-lstdc++ ex7.o cpp_main.o
@end smallexample
@noindent
Here are the corresponding sources:
@smallexample
//cpp_main.C
#include "ex7.h"
extern "C" @{
void adainit (void);
void adafinal (void);
void method1 (A *t);
@}
void method1 (A *t)
@{
t->method1 ();
@}
int main ()
@{
A obj;
adainit ();
obj.method2 (3030);
adafinal ();
@}
//ex7.h
class Origin @{
public:
int o_value;
@};
class A : public Origin @{
public:
void method1 (void);
virtual void method2 (int v);
A();
int a_value;
@};
//ex7.C
#include "ex7.h"
#include <stdio.h>
extern "C" @{ void ada_method2 (A *t, int v);@}
void A::method1 (void)
@{
a_value = 2020;
printf ("in A::method1, a_value = %d \n",a_value);
@}
void A::method2 (int v)
@{
ada_method2 (this, v);
printf ("in A::method2, a_value = %d \n",a_value);
@}
A::A(void)
@{
a_value = 1010;
printf ("in A::A, a_value = %d \n",a_value);
@}
-- Ada sources
@b{package} @b{body} Simple_Cpp_Interface @b{is}
@b{procedure} Ada_Method2 (This : @b{in} @b{out} A; V : Integer) @b{is}
@b{begin}
Method1 (This);
This.A_Value := V;
@b{end} Ada_Method2;
@b{end} Simple_Cpp_Interface;
@b{package} Simple_Cpp_Interface @b{is}
@b{type} A @b{is} @b{limited}
@b{record}
O_Value : Integer;
A_Value : Integer;
@b{end} @b{record};
@b{pragma} Convention (C, A);
@b{procedure} Method1 (This : @b{in} @b{out} A);
@b{pragma} Import (C, Method1);
@b{procedure} Ada_Method2 (This : @b{in} @b{out} A; V : Integer);
@b{pragma} Export (C, Ada_Method2);
@b{end} Simple_Cpp_Interface;
@end smallexample
@node Adapting the Run Time to a New C++ Compiler
@subsection Adapting the Run Time to a New C++ Compiler
@noindent
GNAT offers the capability to derive Ada 95 tagged types directly from
preexisting C++ classes and . See ``Interfacing with C++'' in the
@cite{GNAT Reference Manual}. The mechanism used by GNAT for achieving
such a goal
has been made user configurable through a GNAT library unit
@code{Interfaces.CPP}. The default version of this file is adapted to
the GNU C++ compiler. Internal knowledge of the virtual
table layout used by the new C++ compiler is needed to configure
properly this unit. The Interface of this unit is known by the compiler
and cannot be changed except for the value of the constants defining the
characteristics of the virtual table: CPP_DT_Prologue_Size, CPP_DT_Entry_Size,
CPP_TSD_Prologue_Size, CPP_TSD_Entry_Size. Read comments in the source
of this unit for more details.
@node Comparison between GNAT and C/C++ Compilation Models
@section Comparison between GNAT and C/C++ Compilation Models
@noindent
The GNAT model of compilation is close to the C and C++ models. You can
think of Ada specs as corresponding to header files in C. As in C, you
don't need to compile specs; they are compiled when they are used. The
Ada @code{with} is similar in effect to the @code{#include} of a C
header.
One notable difference is that, in Ada, you may compile specs separately
to check them for semantic and syntactic accuracy. This is not always
possible with C headers because they are fragments of programs that have
less specific syntactic or semantic rules.
The other major difference is the requirement for running the binder,
which performs two important functions. First, it checks for
consistency. In C or C++, the only defense against assembling
inconsistent programs lies outside the compiler, in a makefile, for
example. The binder satisfies the Ada requirement that it be impossible
to construct an inconsistent program when the compiler is used in normal
mode.
@cindex Elaboration order control
The other important function of the binder is to deal with elaboration
issues. There are also elaboration issues in C++ that are handled
automatically. This automatic handling has the advantage of being
simpler to use, but the C++ programmer has no control over elaboration.
Where @code{gnatbind} might complain there was no valid order of
elaboration, a C++ compiler would simply construct a program that
malfunctioned at run time.
@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.
@cindex GNAT library
In GNAT, there is no @dfn{library} in the normal sense. Instead, the set of
source files themselves acts as the library. Compiling Ada programs does
not generate any centralized information, but rather an object file and
a ALI file, which are of interest only to the binder and linker.
In a traditional system, the compiler reads information not only from
the source file being compiled, but also from the centralized library.
This means that the effect of a compilation depends on what has been
previously compiled. In particular:
@itemize @bullet
@item
When a unit is @code{with}'ed, the unit seen by the compiler corresponds
to the version of the unit most recently compiled into the library.
@item
Inlining is effective only if the necessary body has already been
compiled into the library.
@item
Compiling a unit may obsolete other units in the library.
@end itemize
@noindent
In GNAT, compiling one unit never affects the compilation of any other
units because the compiler reads only source files. Only changes to source
files can affect the results of a compilation. In particular:
@itemize @bullet
@item
When a unit is @code{with}'ed, the unit seen by the compiler corresponds
to the source version of the unit that is currently accessible to the
compiler.
@item
@cindex Inlining
Inlining requires the appropriate source files for the package or
subprogram bodies to be available to the compiler. Inlining is always
effective, independent of the order in which units are complied.
@item
Compiling a unit never affects any other compilations. The editing of
sources may cause previous compilations to be out of date if they
depended on the source file being modified.
@end itemize
@noindent
The most important result of these differences is that order of compilation
is never significant in GNAT. There is no situation in which one is
required to do one compilation before another. What shows up as order of
compilation requirements in the traditional Ada library becomes, in
GNAT, simple source dependencies; in other words, there is only a set
of rules saying what source files must be present when a file is
compiled.
@ifset vms
@node Placement of temporary files
@section Placement of temporary files
@cindex Temporary files (user control over placement)
@noindent
GNAT creates temporary files in the directory designated by the environment
variable @env{TMPDIR}.
(See the HP @emph{C RTL Reference Manual} on the function @code{getenv()}
for detailed information on how environment variables are resolved.
For most users the easiest way to make use of this feature is to simply
define @env{TMPDIR} as a job level logical name).
For example, if you wish to use a Ramdisk (assuming DECRAM is installed)
for compiler temporary files, then you can include something like the
following command in your @file{LOGIN.COM} file:
@smallexample
$ define/job TMPDIR "/disk$scratchram/000000/temp/"
@end smallexample
@noindent
If @env{TMPDIR} is not defined, then GNAT uses the directory designated by
@env{TMP}; if @env{TMP} is not defined, then GNAT uses the directory
designated by @env{TEMP}.
If none of these environment variables are defined then GNAT uses the
directory designated by the logical name @code{SYS$SCRATCH:}
(by default the user's home directory). If all else fails
GNAT uses the current directory for temporary files.
@end ifset
@c *************************
@node Compiling Using gcc
@chapter Compiling Using @code{gcc}
@noindent
This chapter discusses how to compile Ada programs using the @code{gcc}
command. It also describes the set of switches
that can be used to control the behavior of the compiler.
@menu
* Compiling Programs::
* Switches for gcc::
* Search Paths and the Run-Time Library (RTL)::
* Order of Compilation Issues::
* Examples::
@end menu
@node Compiling Programs
@section Compiling Programs
@noindent
The first step in creating an executable program is to compile the units
of the program using the @code{gcc} command. You must compile the
following files:
@itemize @bullet
@item
the body file (@file{.adb}) for a library level subprogram or generic
subprogram
@item
the spec file (@file{.ads}) for a library level package or generic
package that has no body
@item
the body file (@file{.adb}) for a library level package
or generic package that has a body
@end itemize
@noindent
You need @emph{not} compile the following files
@itemize @bullet
@item
the spec of a library unit which has a body
@item
subunits
@end itemize
@noindent
because they are compiled as part of compiling related units. GNAT
package specs
when the corresponding body is compiled, and subunits when the parent is
compiled.
@cindex cannot generate code
If you attempt to compile any of these files, you will get one of the
following error messages (where fff is the name of the file you compiled):
@smallexample
cannot generate code for file @var{fff} (package spec)
to check package spec, use -gnatc
cannot generate code for file @var{fff} (missing subunits)
to check parent unit, use -gnatc
cannot generate code for file @var{fff} (subprogram spec)
to check subprogram spec, use -gnatc
cannot generate code for file @var{fff} (subunit)
to check subunit, use -gnatc
@end smallexample
@noindent
As indicated by the above error messages, if you want to submit
one of these files to the compiler to check for correct semantics
without generating code, then use the @option{-gnatc} switch.
The basic command for compiling a file containing an Ada unit is
@smallexample
$ gcc -c [@var{switches}] @file{file name}
@end smallexample
@noindent
where @var{file name} is the name of the Ada file (usually
having an extension
@file{.ads} for a spec or @file{.adb} for a body).
@ifclear vms
You specify the
@option{-c} switch to tell @code{gcc} to compile, but not link, the file.
@end ifclear
The result of a successful compilation is an object file, which has the
same name as the source file but an extension of @file{.o} and an Ada
Library Information (ALI) file, which also has the same name as the
source file, but with @file{.ali} as the extension. GNAT creates these
two output files in the current directory, but you may specify a source
file in any directory using an absolute or relative path specification
containing the directory information.
@findex gnat1
@code{gcc} is actually a driver program that looks at the extensions of
the file arguments and loads the appropriate compiler. For example, the
GNU C compiler is @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
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
each file. For example, the following command lists three separate
files to be compiled:
@smallexample
$ gcc -c x.adb y.adb z.c
@end smallexample
@noindent
calls @code{gnat1} (the Ada compiler) twice to compile @file{x.adb} and
@file{y.adb}, and @code{cc1} (the C compiler) once to compile @file{z.c}.
The compiler generates three object files @file{x.o}, @file{y.o} and
@file{z.o} and the two ALI files @file{x.ali} and @file{y.ali} from the
Ada compilations. Any switches apply to all the files ^listed,^listed.^
@ifclear vms
except for
@option{-gnat@var{x}} switches, which apply only to Ada compilations.
@end ifclear
@node Switches for gcc
@section Switches for @code{gcc}
@noindent
The @code{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.
@menu
* Output and Error Message Control::
* Warning Message Control::
* Debugging and Assertion Control::
* Run-Time Checks::
* Stack Overflow Checking::
* Validity Checking::
* Style Checking::
* Using gcc for Syntax Checking::
* Using gcc for Semantic Checking::
* Compiling Ada 83 Programs::
* Character Set Control::
* File Naming Control::
* Subprogram Inlining Control::
* Auxiliary Output Control::
* Debugging Control::
* Exception Handling Control::
* Units to Sources Mapping Files::
* Integrated Preprocessing::
@ifset vms
* Return Codes::
@end ifset
@end menu
@table @option
@c !sort!
@ifclear vms
@cindex @option{-b} (@code{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})
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
@option{-b} or @option{-V} switch instead.
@item -c
@cindex @option{-c} (@code{gcc})
Compile. Always use this switch when compiling Ada programs.
Note: for some other languages when using @code{gcc}, notably in
the case of C and C++, it is possible to use
use @code{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.
@end ifclear
@item -fno-inline
@cindex @option{-fno-inline} (@code{gcc})
Suppresses all back-end inlining, even if other optimization or inlining
switches are set.
This includes suppression of inlining that results
from the use of the pragma @code{Inline_Always}.
See also @option{-gnatn} and @option{-gnatN}.
@item -fstack-check
@cindex @option{-fstack-check} (@code{gcc})
Activates stack checking.
See @ref{Stack Overflow Checking}, for details of the use of this option.
@item ^-g^/DEBUG^
@cindex @option{^-g^/DEBUG^} (@code{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})
Enforce Ada 83 restrictions.
@item -gnata
@cindex @option{-gnata} (@code{gcc})
Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
activated.
@item -gnatA
@cindex @option{-gnatA} (@code{gcc})
Avoid processing @file{gnat.adc}. If a gnat.adc file is present,
it will be ignored.
@item -gnatb
@cindex @option{-gnatb} (@code{gcc})
Generate brief messages to @file{stderr} even if verbose mode set.
@item -gnatc
@cindex @option{-gnatc} (@code{gcc})
Check syntax and semantics only (no code generation attempted).
@item -gnatd
@cindex @option{-gnatd} (@code{gcc})
Specify debug options for the compiler. The string of characters after
the @option{-gnatd} specify the specific debug options. The possible
characters are 0-9, a-z, A-Z, optionally preceded by a dot. See
compiler source file @file{debug.adb} for details of the implemented
debug options. Certain debug options are relevant to applications
programmers, and these are documented at appropriate points in this
users guide.
@item -gnatD
@cindex @option{-gnatD} (@code{gcc})
Output 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})
Specify a configuration pragma file
@ifclear vms
(the equal sign is optional)
@end ifclear
(see @ref{The Configuration Pragmas Files}).
@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
@cindex @option{-gnateD} (@code{gcc})
Defines a symbol, associated with value, for preprocessing.
(see @ref{Integrated Preprocessing})
@item -gnatef
@cindex @option{-gnatef} (@code{gcc})
Display full source path name in brief error messages.
@item -gnatem=@var{path}
@cindex @option{-gnatem} (@code{gcc})
Specify a mapping file
@ifclear vms
(the equal sign is optional)
@end ifclear
(see @ref{Units to Sources Mapping Files}).
@item -gnatep=@var{file}
@cindex @option{-gnatep} (@code{gcc})
Specify a preprocessing data file
@ifclear vms
(the equal sign is optional)
@end ifclear
(see @ref{Integrated Preprocessing}).
@item -gnatE
@cindex @option{-gnatE} (@code{gcc})
Full dynamic elaboration checks.
@item -gnatf
@cindex @option{-gnatf} (@code{gcc})
Full errors. Multiple errors per line, all undefined references, do not
attempt to suppress cascaded errors.
@item -gnatF
@cindex @option{-gnatF} (@code{gcc})
Externals names are folded to all uppercase.
@item -gnatg
@cindex @option{-gnatg} (@code{gcc})
Internal GNAT implementation mode. This should not be used for
applications programs, it is intended only for use by the compiler
and its run-time library. For documentation, see the GNAT sources.
Note that @option{-gnatg} implies @option{-gnatwu} so that warnings
are generated on unreferenced entities, and all warnings are treated
as errors.
@item -gnatG
@cindex @option{-gnatG} (@code{gcc})
List generated expanded code in source form.
@item ^-gnath^/HELP^
@cindex @option{^-gnath^/HELP^} (@code{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})
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}.
@end ifset
@item -gnatk=@var{n}
@cindex @option{-gnatk} (@code{gcc})
Limit file names to @var{n} (1-999) characters ^(@code{k} = krunch)^^.
@item -gnatl
@cindex @option{-gnatl} (@code{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})
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.
@item -gnatn
@cindex @option{-gnatn} (@code{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})
Activate front end inlining for subprograms for which
pragma @code{Inline} is specified. This inlining is performed
by the front end and will be visible in the
@option{-gnatG} output.
In some cases, this has proved more effective than the back end
inlining resulting from the use of
@option{-gnatn}.
Note that
@option{-gnatN} automatically implies
@option{-gnatn} so it is not necessary
to specify both options. There are a few cases that the back-end inlining
catches that cannot be dealt with in the front-end.
@item -gnato
@cindex @option{-gnato} (@code{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})
Suppress all checks.
@item -gnatP
@cindex @option{-gnatP} (@code{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})
Don't quit; try semantics, even if parse errors.
@item -gnatQ
@cindex @option{-gnatQ} (@code{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})
Output representation information for declared types and objects.
@item -gnats
@cindex @option{-gnats} (@code{gcc})
Syntax check only.
@item -gnatS
@cindex @option{-gnatS} (@code{gcc})
Print package Standard.
@item -gnatt
@cindex @option{-gnatt} (@code{gcc})
Generate tree output file.
@item ^-gnatT^/TABLE_MULTIPLIER=^@var{nnn}
@cindex @option{^-gnatT^/TABLE_MULTIPLIER^} (@code{gcc})
All compiler tables start at @var{nnn} times usual starting size.
@item -gnatu
@cindex @option{-gnatu} (@code{gcc})
List units for this compilation.
@item -gnatU
@cindex @option{-gnatU} (@code{gcc})
Tag all error messages with the unique string ``error:''
@item -gnatv
@cindex @option{-gnatv} (@code{gcc})
Verbose mode. Full error output with source lines to @file{stdout}.
@item -gnatV
@cindex @option{-gnatV} (@code{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})
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})
@item ^-gnatW^/WIDE_CHARACTER_ENCODING=^@var{e}
@cindex @option{^-gnatW^/WIDE_CHARACTER_ENCODING^} (@code{gcc})
Wide character encoding method
@ifclear vms
(@var{e}=n/h/u/s/e/8).
@end ifclear
@ifset vms
(@var{e}=@code{BRACKETS, NONE, HEX, UPPER, SHIFT_JIS, EUC, UTF8})
@end ifset
@item -gnatx
@cindex @option{-gnatx} (@code{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})
@item ^-gnatz^/DISTRIBUTION_STUBS=^@var{m}
@cindex @option{^-gnatz^/DISTRIBUTION_STUBS^} (@code{gcc})
Distribution stub generation and compilation
@ifclear vms
(@var{m}=r/c for receiver/caller stubs).
@end ifclear
@ifset vms
(@var{m}=@code{RECEIVER} or @code{CALLER} to specify the type of stubs
to be generated and compiled).
@end ifset
@item -gnatZ
Use the zero cost method for exception handling
@item ^-I^/SEARCH=^@var{dir}
@cindex @option{^-I^/SEARCH^} (@code{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 RTL
Except for the source file named in the command line, do not look for source
files in the directory containing the source file named in the command line
(@pxref{Search Paths and the Run-Time Library (RTL)}).
@ifclear vms
@item -mbig-switch
@cindex @option{-mbig-switch} (@command{gcc})
@cindex @code{case} statement (effect of @option{-mbig-switch} option)
This standard gcc switch causes the compiler to use larger offsets in its
jump table representation for @code{case} statements.
This may result in less efficient code, but is sometimes necessary
(for example on HP-UX targets)
@cindex HP-UX and @option{-mbig-switch} option
in order to compile large and/or nested @code{case} statements.
@item -o @var{file}
@cindex @option{-o} (@code{gcc})
This switch is used in @code{gcc} to redirect the generated object file
and its associated ALI file. Beware of this switch with GNAT, because it may
cause the object file and ALI file to have different names which in turn
may confuse the binder and the linker.
@end ifclear
@item -nostdinc
@cindex @option{-nostdinc} (@command{gcc})
Inhibit the search of the default location for the GNAT Run Time
Library (RTL) source files.
@item -nostdlib
@cindex @option{-nostdlib} (@command{gcc})
Inhibit the search of the default location for the GNAT Run Time
Library (RTL) ALI files.
@ifclear vms
@item -O[@var{n}]
@cindex @option{-O} (@code{gcc})
@var{n} controls the optimization level.
@table @asis
@item n = 0
No optimization, the default setting if no @option{-O} appears
@item n = 1
Normal optimization, the default if you specify @option{-O} without
an operand.
@item n = 2
Extensive optimization
@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
@ifset vms
@item /NOOPTIMIZE
@cindex @option{/NOOPTIMIZE} (@code{GNAT COMPILE})
Equivalent to @option{/OPTIMIZE=NONE}.
This is the default behavior in the absence of an @option{/OPTMIZE}
qualifier.
@item /OPTIMIZE[=(keyword[,...])]
@cindex @option{/OPTIMIZE} (@code{GNAT COMPILE})
Selects the level of optimization for your program. The supported
keywords are as follows:
@table @code
@item ALL
Perform most optimizations, including those that
are expensive.
This is the default if the @option{/OPTMIZE} qualifier is supplied
without keyword options.
@item NONE
Do not do any optimizations. Same as @code{/NOOPTIMIZE}.
@item SOME
Perform some optimizations, but omit ones that are costly.
@item DEVELOPMENT
Same as @code{SOME}.
@item INLINING
Full optimization, 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
usually, but not always, improves the performance of programs.
@end table
@end ifset
@ifclear vms
@item -pass-exit-codes
@cindex @option{-pass-exit-codes} (@code{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})
Specifies the default location of the runtime library. Same meaning as the
equivalent @code{gnatmake} flag (see @ref{Switches for gnatmake}).
@item ^-S^/ASM^
@cindex @option{^-S^/ASM^} (@code{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 ^-v^/VERBOSE^
@cindex @option{^-v^/VERBOSE^} (@code{gcc})
Show commands generated by the @code{gcc} driver. Normally used only for
debugging purposes or if you need to be sure what version of the
compiler you are executing.
@ifclear vms
@item -V @var{ver}
@cindex @option{-V} (@code{gcc})
Execute @var{ver} version of the compiler. This is the @code{gcc}
version, not the GNAT version.
@end ifclear
@end table
@ifclear vms
You may combine a sequence of GNAT switches into a single switch. For
example, the combined switch
@cindex Combining GNAT switches
@smallexample
-gnatofi3
@end smallexample
@noindent
is equivalent to specifying the following sequence of switches:
@smallexample
-gnato -gnatf -gnati3
@end smallexample
@end ifclear
@c NEED TO CHECK THIS FOR VMS
@noindent
The following restrictions apply to the combination of switches
in this manner:
@itemize @bullet
@item
The switch @option{-gnatc} if combined with other switches must come
first in the string.
@item
The switch @option{-gnats} if combined with other switches must come
first in the string.
@item
The switches
@option{^-gnatz^/DISTRIBUTION_STUBS^}, @option{-gnatzc}, and @option{-gnatzr}
may not be combined with any other switches.
@ifclear vms
@item
Once a ``y'' appears in the string (that is a use of the @option{-gnaty}
switch), then all further characters in the switch are interpreted
as style modifiers (see description of @option{-gnaty}).
@item
Once a ``d'' appears in the string (that is a use of the @option{-gnatd}
switch), then all further characters in the switch are interpreted
as debug flags (see description of @option{-gnatd}).
@item
Once a ``w'' appears in the string (that is a use of the @option{-gnatw}
switch), then all further characters in the switch are interpreted
as warning mode modifiers (see description of @option{-gnatw}).
@item
Once a ``V'' appears in the string (that is a use of the @option{-gnatV}
switch), then all further characters in the switch are interpreted
as validity checking options (see description of @option{-gnatV}).
@end ifclear
@end itemize
@node Output and Error Message Control
@subsection Output and Error Message Control
@findex stderr
@noindent
The standard default format for error messages is called ``brief format''.
Brief format messages are written to @file{stderr} (the standard error
file) and have the following form:
@smallexample
e.adb:3:04: Incorrect spelling of keyword "function"
e.adb:4:20: ";" should be "is"
@end smallexample
@noindent
The first integer after the file name is the line number in the file,
and the second integer is the column number within the line.
@code{glide} can parse the error messages
and point to the referenced character.
The following switches provide control over the error message
format:
@table @option
@c !sort!
@item -gnatv
@cindex @option{-gnatv} (@code{gcc})
@findex stdout
@ifclear vms
The v stands for verbose.
@end ifclear
The effect of this setting is to write long-format error
messages to @file{stdout} (the standard output file.
The same program compiled with the
@option{-gnatv} switch would generate:
@smallexample
@cartouche
3. funcion X (Q : Integer)
|
>>> Incorrect spelling of keyword "function"
4. return Integer;
|
>>> ";" should be "is"
@end cartouche
@end smallexample
@noindent
The vertical bar indicates the location of the error, and the @samp{>>>}
prefix can be used to search for error messages. When this switch is
used the only source lines output are those with errors.
@item -gnatl
@cindex @option{-gnatl} (@code{gcc})
@ifclear vms
The @code{l} stands for list.
@end ifclear
This switch causes a full listing of
the file to be generated. The output might look as follows:
@smallexample
@cartouche
1. procedure E is
2. V : Integer;
3. funcion X (Q : Integer)
|
>>> Incorrect spelling of keyword "function"
4. return Integer;
|
>>> ";" should be "is"
5. begin
6. return Q + Q;
7. end;
8. begin
9. V := X + X;
10.end E;
@end cartouche
@end smallexample
@noindent
@findex stderr
When you specify the @option{-gnatv} or @option{-gnatl} switches and
standard output is redirected, a brief summary is written to
@file{stderr} (standard error) giving the number of error messages and
warning messages generated.
@item -gnatU
@cindex @option{-gnatU} (@code{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})
@ifclear vms
The @code{b} stands for brief.
@end ifclear
This switch causes GNAT to generate the
brief format error messages to @file{stderr} (the standard error
file) as well as the verbose
format message or full listing (which as usual is written to
@file{stdout} (the standard output file).
@item -gnatm^^=^@var{n}
@cindex @option{-gnatm} (@code{gcc})
@ifclear vms
The @code{m} stands for maximum.
@end ifclear
@var{n} is a decimal integer in the
range of 1 to 999 and limits the number of error messages to be
generated. For example, using @option{-gnatm2} might yield
@smallexample
e.adb:3:04: Incorrect spelling of keyword "function"
e.adb:5:35: missing ".."
fatal error: maximum errors reached
compilation abandoned
@end smallexample
@item -gnatf
@cindex @option{-gnatf} (@code{gcc})
@cindex Error messages, suppressing
@ifclear vms
The @code{f} stands for full.
@end ifclear
Normally, the compiler suppresses error messages that are likely to be
redundant. This switch causes all error
messages to be generated. In particular, in the case of
references to undefined variables. If a given variable is referenced
several times, the normal format of messages is
@smallexample
e.adb:7:07: "V" is undefined (more references follow)
@end smallexample
@noindent
where the parenthetical comment warns that there are additional
references to the variable @code{V}. Compiling the same program with the
@option{-gnatf} switch yields
@smallexample
e.adb:7:07: "V" is undefined
e.adb:8:07: "V" is undefined
e.adb:8:12: "V" is undefined
e.adb:8:16: "V" is undefined
e.adb:9:07: "V" is undefined
e.adb:9:12: "V" is undefined
@end smallexample
@noindent
The @option{-gnatf} switch also generates additional information for
some error messages. Some examples are:
@itemize @bullet
@item
Full details on entities not available in high integrity mode
@item
Details on possibly non-portable unchecked conversion
@item
List possible interpretations for ambiguous calls
@item
Additional details on incorrect parameters
@end itemize
@item -gnatq
@cindex @option{-gnatq} (@code{gcc})
@ifclear vms
The @code{q} stands for quit (really ``don't quit'').
@end ifclear
In normal operation mode, the compiler first parses the program and
determines if there are any syntax errors. If there are, appropriate
error messages are generated and compilation is immediately terminated.
This switch tells
GNAT to continue with semantic analysis even if syntax errors have been
found. This may enable the detection of more errors in a single run. On
the other hand, the semantic analyzer is more likely to encounter some
internal fatal error when given a syntactically invalid tree.
@item -gnatQ
@cindex @option{-gnatQ} (@code{gcc})
In normal operation mode, the @file{ALI} file is not generated if any
illegalities are detected in the program. The use of @option{-gnatQ} forces
generation of the @file{ALI} file. This file is marked as being in
error, so it cannot be used for binding purposes, but it does contain
reasonably complete cross-reference information, and thus may be useful
for use by tools (e.g. semantic browsing tools or integrated development
environments) that are driven from the @file{ALI} file. This switch
implies @option{-gnatq}, since the semantic phase must be run to get a
meaningful ALI file.
In addition, if @option{-gnatt} is also specified, then the tree file is
generated even if there are illegalities. It may be useful in this case
to also specify @option{-gnatq} to ensure that full semantic processing
occurs. The resulting tree file can be processed by ASIS, for the purpose
of providing partial information about illegal units, but if the error
causes the tree to be badly malformed, then ASIS may crash during the
analysis.
When @option{-gnatQ} is used and the generated @file{ALI} file is marked as
being in error, @code{gnatmake} will attempt to recompile the source when it
finds such an @file{ALI} file, including with switch @option{-gnatc}.
Note