@setfilename gnat_ugn_unw.info
@end ifset
+@set FSFEDITION
+@set EDITION GNAT
+
+@ifset unw
+@set PLATFORM Unix and Windows
+@set FILE gnat_ugn_unw
+@end ifset
+
@ifset vms
-@settitle GNAT User's Guide for Native Platforms / OpenVMS Alpha
-@dircategory GNU Ada tools
-@direntry
-* GNAT User's Guide (gnat_ugn_vms) for Native Platforms / OpenVMS Alpha
-@end direntry
+@set PLATFORM OpenVMS Alpha
+@set FILE gnat_ugn_vms
@end ifset
-@ifset unw
-@settitle GNAT User's Guide for Native Platforms / Unix and Windows
+@settitle @value{EDITION} User's Guide for Native Platforms / @value{PLATFORM}
+@dircategory GNU Ada tools
@direntry
-* GNAT User's Guide (gnat_ugn_unw) for Native Platforms / Unix and Windows
+* @value{EDITION} User's Guide (@value{FILE}) for Native Platforms / @value{PLATFORM}
@end direntry
-@end ifset
@include gcc-common.texi
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
+``GNAT User's Guide for Native Platforms / @value{PLATFORM}'',
and with no Back-Cover Texts.
A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@titlepage
-@title GNAT User's Guide
+@title @value{EDITION} 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
+@titlefont{@i{@value{PLATFORM}}}
@end flushright
@sp 2
@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
+@top @value{EDITION} User's Guide
-@ifset unw
@noindent
-GNAT User's Guide for Native Platforms / Unix and Windows
-@end ifset
+@value{EDITION} User's Guide for Native Platforms / @value{PLATFORM}
@noindent
GNAT, The GNU Ada 95 Compiler@*
* How gnatmake Works::
* Examples of gnatmake Usage::
-
Improving Performance
* Performance Considerations::
* Reducing the Size of Ada Executables with gnatelim::
* An Extended Example::
* Project File Complete Syntax::
-
The Cross-Referencing Tools gnatxref and gnatfind
* gnatxref Switches::
* Examples of gnatxref Usage::
* Examples of gnatfind Usage::
-
The GNAT Pretty-Printer gnatpp
* Switches for gnatpp::
* Formatting Rules::
-
File Name Krunching Using gnatkr
* About gnatkr::
* GNAT and COM/DCOM Objects::
@end ifset
-
* Index::
@end menu
@end ifnottex
@noindent
@ifset vms
-This guide describes the use of of GNAT, a full language compiler for the Ada
+This guide describes the use of of @value{EDITION},
+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
+This guide describes the use of @value{EDITION},
+a compiler and software development
toolset for the full Ada 95 programming language.
@end ifclear
It describes the features of the compiler and tools, and details
how to use them to build Ada 95 applications.
+@ifset PROEDITION
+For ease of exposition, ``GNAT Pro'' will be referred to simply as
+``GNAT'' in the remainder of this document.
+@end ifset
+
@menu
* What This Guide Contains::
* What You Should Know before Reading This Guide::
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
@end ifset
@end itemize
-
@c *************************************************
@node What You Should Know before Reading This Guide
@c *************************************************
the ``@code{\}'' character should be used instead.
@end ifset
-
-
@c ****************************
@node Getting Started with GNAT
@chapter Getting Started with GNAT
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
appear in response to this command.
-
@c ****************************************
@node Running a Program with Multiple Units
@section Running a Program with Multiple Units
* Simple Debugging with GPS::
@end menu
-
@node Building a New Program with GPS
@subsection Building a New Program with GPS
@noindent
The file will be saved in the same directory you specified as the
location of the default project file.
-
@item @emph{Updating the project file}
You need to add the new source file to the project.
terminate this GPS session.
@end enumerate
-
-
@node Simple Debugging with GPS
@subsection Simple Debugging with GPS
@noindent
You will see information about @code{N} appear in the @code{Debugger Data}
pane, showing the value as 5.
-
@item @emph{Assigning a new value to a variable}
Right click on the @code{N} in the @code{Debugger Data} pane, and
@end enumerate
@end enumerate
-
@node Introduction to Glide and GVD
@section Introduction to Glide and GVD
@cindex Glide
GNAT uses the current directory for temporary files.
@end ifset
-
@c *************************
@node Compiling Using gcc
@chapter Compiling Using @code{gcc}
instead of the object file.
This may be useful if you need to examine the generated assembly code.
+@item ^-fverbose-asm^/VERBOSE_ASM^
+@cindex @option{^-fverbose-asm^/VERBOSE_ASM^} (@code{gcc})
+^Used in conjunction with @option{-S}^Used in place of @option{/ASM}^
+to cause the generated assembly code file to be annotated with variable
+names, making it significantly easier to follow.
+
@item ^-v^/VERBOSE^
@cindex @option{^-v^/VERBOSE^} (@code{gcc})
Show commands generated by the @code{gcc} driver. Normally used only for
@end smallexample
@end ifclear
-
@c NEED TO CHECK THIS FOR VMS
@noindent
@end ifclear
@end itemize
-
@node Output and Error Message Control
@subsection Output and Error Message Control
@findex stderr
Additional details on incorrect parameters
@end itemize
-
@item -gnatq
@cindex @option{-gnatq} (@code{gcc})
@ifclear vms
@end table
-
@node Warning Message Control
@subsection Warning Message Control
@cindex Warning messages
Fixed-point type declarations with a null range
@item
+Direct_IO or Sequential_IO instantiated with a type that has access values
+
+@item
Variables that are never assigned a value
@item
@item
Attempt to return local value by reference
-
@item
Premature instantiation of a generic body
@item
Accidental hiding of name by child unit
-
@item
Access before elaboration detected at compile time
@end table
-
@node Debugging and Assertion Control
@subsection Debugging and Assertion Control
to the default checks described above.
@end ifset
-
@table @option
@c !sort!
@item -gnatVa
the validity checking mode at the program source level, and also allows for
temporary disabling of validity checks.
-
@node Style Checking
@subsection Style Checking
@findex Style checking
is an operating systems issue, and must be addressed with the
appropriate operating systems commands.
-
@node Using gcc for Syntax Checking
@subsection Using @code{gcc} for Syntax Checking
@table @option
(@pxref{Renaming Files Using gnatchop}).
@end table
-
@node Using gcc for Semantic Checking
@subsection Using @code{gcc} for Semantic Checking
@table @option
For the source file naming rules, @xref{File Naming Rules}.
@end table
-
@node Subprogram Inlining Control
@subsection Subprogram Inlining Control
@end table
-
@node Integrated Preprocessing
@subsection Integrated Preprocessing
@end ifset
-
@node Search Paths and the Run-Time Library (RTL)
@section Search Paths and the Run-Time Library (RTL)
in compiling sources from multiple directories. This can make
development environments much more flexible.
-
@node Order of Compilation Issues
@section Order of Compilation Issues
to be read by the @code{gnatlink} utility used to link the Ada application.
@end enumerate
-
@node Running gnatbind
@section Running @code{gnatbind}
for both @code{gnatbind} and @code{gnatlink} will cause the program to
be generated in C (and compiled using the gnu C compiler).
-
@node Switches for gnatbind
@section Switches for @command{gnatbind}
no arguments.
@end ifclear
-
@node Consistency-Checking Modes
@subsection Consistency-Checking Modes
consists of elaboration of these units in an appropriate order.
@end table
-
@node Command-Line Access
@section Command-Line Access
@code{gnat_argv} from the @code{argc} and @code{argv} values passed to
it.
-
@node Search Paths for gnatbind
@section Search Paths for @code{gnatbind}
after accessing the Ada units.
@end table
-
@c ------------------------------------
@node Linking Using gnatlink
@chapter Linking Using @code{gnatlink}
only.
@item
-@code{gnatmake} examines both an ALI file and its corresponding object file
-for consistency. If an ALI is more recent than its corresponding object,
-or if the object file is missing, the corresponding source will be recompiled.
-Note that @code{gnatmake} expects an ALI and the corresponding object file
-to be in the same directory.
-
-@item
@code{gnatmake} will ignore any files whose ALI file is write-protected.
This may conveniently be used to exclude standard libraries from
consideration and in particular it means that the use of the
previous compilations without incorrectly depending on them.
First a definition: an object file is considered @dfn{up to date} if the
-corresponding ALI file exists and its time stamp predates that of the
-object file and if all the source files listed in the
+corresponding ALI file exists and if all the source files listed in the
dependency section of this ALI file have time stamps matching those in
the ALI file. This means that neither the source file itself nor any
files that it depends on have been modified, and hence there is no need
displaying commands it is executing.
@end table
-
@c *************************
@node Improving Performance
@chapter Improving Performance
@end menu
@end ifnottex
-
@c *****************************
@node Performance Considerations
@section Performance Considerations
executables which run more slowly. See further discussion of this point
in @pxref{Inlining of Subprograms}.
-
@node Debugging Optimized Code
@subsection Debugging Optimized Code
@cindex Debugging optimized code
which removes both debugging information and global symbols.
@end ifclear
-
@node Inlining of Subprograms
@subsection Inlining of Subprograms
from scratch after that, because you need a consistent @file{gnat.adc} file
during the entire compilation.
-
@node Making Your Executables Smaller
@subsection Making Your Executables Smaller
@end enumerate
-
-
-
@c ********************************
@node Renaming Files Using gnatchop
@chapter Renaming Files Using @code{gnatchop}
time you compile, regarding the source files that it writes as temporary
files that you throw away.
-
@node Operating gnatchop in Compilation Mode
@section Operating gnatchop in Compilation Mode
Ada_95
C_Pass_By_Copy
Component_Alignment
+ Detect_Blocking
Discard_Names
Elaboration_Checks
Eliminate
@option{^-D^/DIRS_FILE^}. Several Naming Patterns and one excluded pattern
are used in this example.
-
@c *****************************************
@c * G N A T P r o j e c t M a n a g e r *
@c *****************************************
@noindent
By default, the executable file name corresponding to a main source is
-deducted from the main source file name. Through the attributes
+deduced from the main source file name. Through the attributes
@code{Executable} and @code{Executable_Suffix} of package @code{Builder},
it is possible to change this default.
In project @code{Debug} above, the executable file name
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-g^-g^");
for Executable ("proc") use "proc1";
+ when others =>
+ null;
end case;
end Builder;
library directory. To build executables, @command{gnatmake} will use the
library rather than the individual object files.
-
@c **********************************************
@c * Using Third-Party Libraries through Projects
@c **********************************************
@end itemize
@noindent
-Note that the compiler is invoked using the command
-@command{^gnatmake -f -u -c^gnatmake -f -u -c^}.
+(note that the compiler is invoked using the command
+@command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
+
+@noindent
+On non VMS platforms, between @command{gnat} and the command, two
+special switches may be used:
+
+@itemize @bullet
+@item
+@command{-v} to display the invocation of the tool.
+@item
+@command{-dn} to prevent the @command{gnat} driver from removing
+the temporary files it has created. These temporary files are
+configuration files and temporary file list files.
+@end itemize
@noindent
The command may be followed by switches and arguments for the invoked
@end smallexample
-
@node The Cross-Referencing Tools gnatxref and gnatfind
@chapter The Cross-Referencing Tools @code{gnatxref} and @code{gnatfind}
@findex gnatxref
@end table
-
@c *********************************
@node The GNAT Pretty-Printer gnatpp
@chapter The GNAT Pretty-Printer @command{gnatpp}
follow the GNAT file naming rules
@end itemize
-
@menu
* Switches for gnatpp::
* Formatting Rules::
* Other gnatpp Switches::
@end menu
-
@node Alignment Control
@subsection Alignment Control
@cindex Alignment control in @command{gnatpp}
The @option{^-A^/ALIGN^} switches are mutually compatible; any combination
is allowed.
-
@node Casing Control
@subsection Casing Control
@cindex Casing control in @command{gnatpp}
@option{^-D@var{file}^/DICTIONARY=@var{file}^} switches are mutually
compatible.
-
@node Construct Layout Control
@subsection Construct Layout Control
@cindex Layout control in @command{gnatpp}
line indentation is also 1)
@end table
-
@node Other Formatting Options
@subsection Other Formatting Options
@end table
-
@node Output File Control
@subsection Output File Control
a required layout in the result source.
@end table
-
@node Formatting Rules
@section Formatting Rules
* Name Casing::
@end menu
-
@node White Space and Empty Lines
@subsection White Space and Empty Lines
Likewise, if for some reason you wish to have a sequence of empty lines,
use a sequence of empty comments instead.
-
@node Formatting Comments
@subsection Formatting Comments
word processor style (that is, moving words between lines and putting as
many words in a line as possible).
-
@node Construct Layout
@subsection Construct Layout
end record; b : integer;
end record;
-
Block : declare Block :
A : Integer := 3; declare
begin A : Integer := 3;
GNAT style layout inserts empty lines as separation for
compound statements, return statements and bodies.
-
@node Name Casing
@subsection Name Casing
@end cartouche
@end smallexample
-
-
@c ***********************************
@node File Name Krunching Using gnatkr
@chapter File Name Krunching Using @code{gnatkr}
library must be installed before the GNAT library if it redefines
any part of it.
-
@node Using the library
@subsection Using the library
@end smallexample
@end itemize
-
@node Stand-alone Ada Libraries
@section Stand-alone Ada Libraries
@cindex Stand-alone library, building, using
particular the set of instructions needed to rebuild a new library and
to use it.
-
@node Using the GNU make Utility
@chapter Using the GNU @code{make} Utility
@findex make
@end smallexample
@end ifclear
-
@node Finding Memory Problems
@chapter Finding Memory Problems
* The GNAT Debug Pool Facility::
@end menu
-
@ifclear vms
@node The gnatmem Tool
@section The @command{gnatmem} Tool
@end ifclear
-
@node The GNAT Debug Pool Facility
@section The GNAT Debug Pool Facility
@findex Debug Pool
High Water Mark: 8
@end smallexample
-
@node Creating Sample Bodies Using gnatstub
@chapter Creating Sample Bodies Using @command{gnatstub}
@findex gnatstub
@end table
-
@node Other Utility Programs
@chapter Other Utility Programs
available in the @code{Glide} @result{} @code{Help} menu.
@end ifclear
-
@node Converting Ada Files to html with gnathtml
@section Converting Ada Files to HTML with @code{gnathtml}
exactly as if the debugger were not present. The following section
describes some of the additional commands that can be given to @code{GDB}.
-
@c *******************************
@node Introduction to GDB Commands
@section Introduction to GDB Commands
tool as described earlier (note that the hexadecimal addresses
need to be specified in C format, with a leading ``0x'').
-
@node Symbolic Traceback
@subsection Symbolic Traceback
@cindex traceback, symbolic
@end ifset
-
@c **************************************
@node Platform-Specific Information for the Run-Time Libraries
@appendix Platform-Specific Information for the Run-Time Libraries
* AIX-Specific Considerations::
@end menu
-
@node Summary of Run-Time Configurations
@section Summary of Run-Time Configurations
-
@multitable @columnfractions .30 .70
@item @b{alpha-openvms}
@item @code{@ @ }@i{rts-native (default)}
@*
@end multitable
-
-
@node Specifying a Run-Time Library
@section Specifying a Run-Time Library
Note also that to take full advantage of Florist and Glade, it is highly
recommended that you use native threads.
-
@node Choosing the Scheduling Policy
@section Choosing the Scheduling Policy
value greater than @code{0.0}, or else use the corresponding @option{-T}
binder option.
-
-
@node Solaris-Specific Considerations
@section Solaris-Specific Considerations
@cindex Solaris Sparc threads libraries
* Building and Debugging 64-bit Applications::
@end menu
-
@node Solaris Threads Issues
@subsection Solaris Threads Issues
(where @code{_SC_NPROCESSORS_CONF} is a system variable).
@end table
-
@node Building and Debugging 64-bit Applications
@subsection Building and Debugging 64-bit Applications
$ gdb64 hello
@end smallexample
-
-
@node IRIX-Specific Considerations
@section IRIX-Specific Considerations
@cindex IRIX thread library
The @emph{n32 ABI} compiler comes with a run-time library based on the
kernel POSIX threads and thus does not have the limitations mentioned above.
-
@node Linux-Specific Considerations
@section Linux-Specific Considerations
@cindex Linux threads libraries
file generated for a simple ``Hello World'' program.
Comments have been added for clarification purposes.
-
@smallexample @c adanocomment
@iftex
@leftskip=0cm
the problem might be (more usually of course you would be debugging
elaboration code in your own application).
-
@node Elaboration Order Handling in GNAT
@appendix Elaboration Order Handling in GNAT
@cindex Order of elaboration
and figuring out which is correct, and then adding the necessary
@code{Elaborate_All} pragmas to ensure the desired order.
-
@node Inline Assembler
@appendix Inline Assembler
@c END OF INLINE ASSEMBLER CHAPTER
@c ===============================
-
-
@c ***********************************
@c * Compatibility and Porting Guide *
@c ***********************************
(@code{Emax}, @code{Mantissa}, etc.), among other items.
@end table
-
@node Implementation-dependent characteristics
@section Implementation-dependent characteristics
@noindent
* Target-specific aspects::
@end menu
-
@node Implementation-defined pragmas
@subsection Implementation-defined pragmas
packing, the meaning of the Size attribute, and the size of access values.
GNAT's approach to these issues is described in @ref{Representation Clauses}.
-
@node Compatibility with Other Ada 95 Systems
@section Compatibility with Other Ada 95 Systems
be implemented. The description of pragmas in this reference manual
indicates whether or not they are applicable to non-VMS systems.
-
-
@ifset unw
@node Microsoft Windows Topics
@appendix Microsoft Windows Topics
* Introduction to Dynamic Link Libraries (DLLs)::
* Using DLLs with GNAT::
* Building DLLs with GNAT::
+* Building DLLs with GNAT Project files::
+* Building DLLs with gnatdll::
* GNAT and Windows Resources::
* Debugging a DLL::
* GNAT and COM/DCOM Objects::
To illustrate the remainder of this section, suppose that an application
wants to use the services of a DLL @file{API.dll}. To use the services
-provided by @file{API.dll} you must statically link against an import
-library which contains a jump table with an entry for each routine and
-variable exported by the DLL. In the Microsoft world this import library is
-called @file{API.lib}. When using GNAT this import library is called either
-@file{libAPI.a} or @file{libapi.a} (names are case insensitive).
-
-After you have statically linked your application with the import library
+provided by @file{API.dll} you must statically link against the DLL or
+an import library which contains a jump table with an entry for each
+routine and variable exported by the DLL. In the Microsoft world this
+import library is called @file{API.lib}. When using GNAT this import
+library is called either @file{libAPI.a} or @file{libapi.a} (names are
+case insensitive).
+
+After you have linked your application with the DLL or the import library
and you run your application, here is what happens:
@enumerate
@end itemize
@item
-The entries in the @file{libAPI.a} or @file{API.lib} jump table which is
-part of your application are initialized with the addresses of the routines
-and variables in @file{API.dll}.
+The entries in the jump table (from the import library @file{libAPI.a}
+or @file{API.lib} or automatically created when linking against a DLL)
+which is part of your application are initialized with the addresses
+of the routines and variables in @file{API.dll}.
@item
If present in @file{API.dll}, routines @code{DllMain} or
As a side note, an interesting difference between Microsoft DLLs and
Unix shared libraries, is the fact that on most Unix systems all public
routines are exported by default in a Unix shared library, while under
-Windows the exported routines must be listed explicitly in a definition
-file (@pxref{The Definition File}).
+Windows it is possible (but not required) to list exported routines in
+a definition file (@pxref{The Definition File}).
@node Using DLLs with GNAT
@section Using DLLs with GNAT
mentioned an import library is a statically linked library containing the
import table which will be filled at load time to point to the actual
@file{API.dll} routines. Sometimes you don't have an import library for the
-DLL you want to use. The following sections will explain how to build one.
+DLL you want to use. The following sections will explain how to build
+one. Note that this is optional.
@item
The actual DLL, @file{API.dll}.
@noindent
If a Microsoft-style import library @file{API.lib} or a GNAT-style
import library @file{libAPI.a} is available with @file{API.dll} you
-can skip this section. Otherwise read on.
+can skip this section. You can also skip this section if
+@file{API.dll} is built with GNU tools as in this case it is possible
+to link directly against the DLL. Otherwise read on.
@node The Definition File
@subsubsection The Definition File
@section Building DLLs with GNAT
@cindex DLLs, building
+@noindent
+This section explain how to build DLLs using the GNAT built-in DLL
+support. With the following procedure it is straight forward to build
+and use DLLs with GNAT.
+
+@enumerate
+
+@item building object files
+
+The first step is to build all objects files that are to be included
+into the DLL. This is done by using the standard @code{gnatmake} tool.
+
+@item building the DLL
+
+To build the DLL you must use @code{gcc}'s @code{-shared}
+option. It is quite simple to use this method:
+
+@smallexample
+$ gcc -shared -o api.dll obj1.o obj2.o ...
+@end smallexample
+
+It is important to note that in this case all symbols found in the
+object files are automatically exported. It is possible to restrict
+the set of symbols to export by passing to @code{gcc} a definition
+file, @pxref{The Definition File}. For example:
+
+@smallexample
+$ gcc -shared -o api.dll api.def obj1.o obj2.o ...
+@end smallexample
+
+If you use a definition file you must export the elaboration procedures
+for every package that required one. Elaboration procedures are named
+using the package name followed by "_E".
+
+@item preparing DLL to be used
+
+For the DLL to be used by client programs the bodies must be hidden
+from it and the .ali set with read-only attribute. This is very important
+otherwise GNAT will recompile all packages and will not actually use
+the code in the DLL. For example:
+
+@smallexample
+$ mkdir apilib
+$ copy *.ads *.ali api.dll apilib
+$ attrib +R apilib\*.ali
+@end smallexample
+
+@end enumerate
+
+At this point it is possible to use the DLL by directly linking
+against it. Note that you must use the GNAT shared runtime when using
+GNAT shared libraries. This is achieved by using @code{-shared} binder's
+option.
+
+@smallexample
+$ gnatmake main -Iapilib -bargs -shared -largs -Lapilib -lAPI
+@end smallexample
+
+@node Building DLLs with GNAT Project files
+@section Building DLLs with GNAT Project files
+@cindex DLLs, building
+
+@noindent
+There is nothing specific to Windows in this area. @pxref{Library Projects}.
+
+@node Building DLLs with gnatdll
+@section Building DLLs with gnatdll
+@cindex DLLs, building
+
@menu
* Limitations When Using Ada DLLs from Ada::
* Exporting Ada Entities::
@end menu
@noindent
-This section explains how to build DLLs containing Ada code. These DLLs
-will be referred to as Ada DLLs in the remainder of this section.
+Note that it is prefered to use the built-in GNAT DLL support
+(@pxref{Building DLLs with GNAT}) or GNAT Project files
+(@pxref{Building DLLs with GNAT Project files}) to build DLLs.
+
+This section explains how to build DLLs containing Ada code using
+@code{gnatdll}. These DLLs will be referred to as Ada DLLs in the
+remainder of this section.
The steps required to build an Ada DLL that is to be used by Ada as well as
non-Ada applications are as follows:
@end ifset
-
@c **********************************
@c * GNU Free Documentation License *
@c **********************************
OSDN Git Service
