@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
@ifnottex
@node Top, About This Guide, (dir), (dir)
-@top GNAT User's Guide
+@top @value{EDITION} User's Guide
-@ifset vms
@noindent
-GNAT User's Guide for Native Platforms / OpenVMS Alpha
-@end ifset
-
-@ifset unw
-@noindent
-GNAT User's Guide for Native Platforms / Unix and Windows
-@end ifset
+@value{EDITION} User's Guide for Native Platforms / @value{PLATFORM}
@noindent
GNAT, The GNU Ada 95 Compiler@*
* Output and Error Message Control::
* Warning Message Control::
* Debugging and Assertion Control::
-* Run-Time Checks::
-* Stack Overflow Checking::
* Validity Checking::
* Style Checking::
+* Run-Time Checks::
+* Stack Overflow Checking::
* Using gcc for Syntax Checking::
* Using gcc for Semantic Checking::
* Compiling Ada 83 Programs::
GNAT and Libraries
-* Creating an Ada Library::
-* Installing an Ada Library::
-* Using an Ada Library::
-* Creating an Ada Library to be Used in a Non-Ada Context::
+* Introduction to Libraries in GNAT::
+* General Ada Libraries::
+* Stand-alone Ada Libraries::
* Rebuilding the GNAT Run-Time Library::
Using the GNU make Utility
* Solaris-Specific Considerations::
* IRIX-Specific Considerations::
* Linux-Specific Considerations::
+* AIX-Specific Considerations::
Example of Binder Output File
@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::
* Output and Error Message Control::
* Warning Message Control::
* Debugging and Assertion Control::
-* Run-Time Checks::
-* Stack Overflow Checking::
* Validity Checking::
* Style Checking::
+* Run-Time Checks::
+* Stack Overflow Checking::
* Using gcc for Syntax Checking::
* Using gcc for Semantic Checking::
* Compiling Ada 83 Programs::
* Exception Handling Control::
* Units to Sources Mapping Files::
* Integrated Preprocessing::
+* Code Generation Control::
@ifset vms
* Return Codes::
@end ifset
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
@end cartouche
@end smallexample
+@item ^Lnnn^MAX_NESTING=nnn^
+@emph{Set maximum nesting level}
+If the sequence ^Lnnn^MAX_NESTING=nnn^, where nnn is a decimal number in
+the range 0-999, appears in the string after @option{-gnaty} then the
+maximum level of nesting of constructs (including subprograms, loops,
+blocks, packages, and conditionals) may not exceed the given value. A
+value of zero disconnects this style check.
+
@item ^m^LINE_LENGTH^
@emph{Check maximum line length.}
If the ^letter m^word LINE_LENGTH^ appears in the string after @option{-gnaty}
Ada compilation will cause the compiler to output a
representation of package Standard in a form very
close to standard Ada. It is not quite possible to
-do this and remain entirely Standard (since new
+do this entirely in standard Ada (since new
numeric base types cannot be created in standard
Ada), but the output is easily
readable to any Ada programmer, and is useful to
@end table
+@node Code Generation Control
+@subsection Code Generation Control
+
+@noindent
+
+The GCC technology provides a wide range of target dependent
+@option{-m} switches for controlling
+details of code generation with respect to different versions of
+architectures. This includes variations in instruction sets (e.g.
+different members of the power pc family), and different requirements
+for optimal arrangement of instructions (e.g. different members of
+the x86 family). The list of available @option{-m} switches may be
+found in the GCC documentation.
+
+Use of the these @option{-m} switches may in some cases result in improved
+code performance.
+
+The GNAT Pro technology is tested and qualified without any
+@option{-m} switches,
+so generally the most reliable approach is to avoid the use of these
+switches. However, we generally expect most of these switches to work
+successfully with GNAT Pro, and many customers have reported successful
+use of these options.
+
+Our general advice is to avoid the use of @option{-m} switches unless
+special needs lead to requirements in this area. In particular,
+there is no point in using @option{-m} switches to improve performance
+unless you actually see a performance improvement.
+
@ifset vms
@node Return Codes
@subsection Return Codes
installation tree and is used to store standard libraries such as the
GNAT Run Time Library (RTL) source files.
@ifclear vms
-@ref{Installing an Ada Library}
+@ref{Installing the library}
@end ifclear
@end enumerate
@ifclear vms
Note that on x86 ports, you must not use @option{-fomit-frame-pointer}
@code{gcc} option.
-@end ifclear vms
+@end ifclear
@item ^-F^/FORCE_ELABS_FLAGS^
@cindex @option{^-F^/FORCE_ELABS_FLAGS^} (@command{gnatbind})
GNAT Run Time Library (RTL) unless the switch @option{-nostdlib} is
specified.
@ifclear vms
-@ref{Installing an Ada Library}
+@ref{Installing the library}
@end ifclear
@end enumerate
Indicates the verbosity of the parsing of GNAT project files.
See @ref{Switches Related to Project Files}.
+@item ^-x^/NON_PROJECT_UNIT_COMPILATION^
+@cindex @option{^-x^/NON_PROJECT_UNIT_COMPILATION^} (@code{gnatmake})
+Indicates that sources that are not part of any Project File may be compiled.
+Normally, when using Project Files, only sources that are part of a Project
+File may be compile. When this switch is used, a source outside of all Project
+Files may be compiled. The ALI file and the object file will be put in the
+object directory of the main Project. The compilation switches used will only
+be those specified on the command line.
+
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
Indicates that external variable @var{name} has the value @var{value}.
The Project Manager will use this value for occurrences of
Long_Float
Normalize_Scalars
Polling
+ Profile
+ Profile_Warnings
Propagate_Exceptions
Queuing_Policy
Ravenscar
Restricted_Run_Time
Restrictions
+ Restrictions_Warnings
Reviewable
Source_File_Name
Style_Checks
for ^Default_Switches^Default_Switches^ ("Ada")
use ("^-g^-g^");
for Executable ("proc") use "proc1";
+ when others =>
+ null;
end case;
end Builder;
(absolute or relative) of the directory where the library will reside.
It must designate an existing directory, and this directory must be
different from the project's object directory. It also needs to be writable.
+The directory should only be used for one library; the reason is that all
+files contained in this directory may be deleted by the Project Manager.
If both @code{Library_Name} and @code{Library_Dir} are specified and
are legal, then the project file defines a library project. The optional
The @code{Library_Kind} attribute has a string value that must be one of the
following (case insensitive): @code{"static"}, @code{"dynamic"} or
-@code{"relocatable"}. If this attribute is not specified, the library is a
-static library, that is an archive of object files that can be potentially
-linked into an static executable. Otherwise, the library may be dynamic or
+@code{"relocatable"} (which is a synonym for @code{"dynamic"}). If this
+attribute is not specified, the library is a static library, that is
+an archive of object files that can be potentially linked into an
+static executable. Otherwise, the library may be dynamic or
relocatable, that is a library that is loaded only at the start of execution.
-Depending on the operating system, there may or may not be a distinction
-between dynamic and relocatable libraries. For Unix and VMS Unix there is no
-such distinction.
If you need to build both a static and a dynamic library, you should use two
different object directories, since in some cases some extra code needs to
^-l^/ACTION=LINK^ have special meanings.
@itemize @bullet
-@item ^-b^/ACTION=BIND^ is only allwed for stand-alone libraries. It indicates
+@item ^-b^/ACTION=BIND^ is only allowed for stand-alone libraries. It indicates
to @command{gnatmake} that @command{gnatbind} should be invoked for the
library.
@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
directory whose name starts with @file{source} and whose extension is
@file{adb}.
+You shouldn't specify any directory name, just base names. @command{gnatxref}
+and @command{gnatfind} will be able to locate these files by themselves using
+the source path. If you specify directories, no result is produced.
+
@end table
@noindent
If the compilation unit
contained in the input source depends semantically upon units located
outside the current directory, you have to provide the source search path
-when invoking @command{gnatpp}; see the description of the @command{gnatpp}
-switches below.
+when invoking @command{gnatpp}, if these units are contained in files with
+names that do not follow the GNAT file naming rules, you have to provide
+the configuration file describing the corresponding naming scheme;
+see the description of the @command{gnatpp}
+switches below. Another possibility is to use a project file and to
+call @command{gnatpp} through the @command{gnat} driver
The @command{gnatpp} command has the form
@item
@var{filename} is the name (including the extension) of the source file to
reformat; ``wildcards'' or several file names on the same gnatpp command are
-allowed. The file name may contain path information; it does not have to follow
-the GNAT file naming rules
+allowed. The file name may contain path information; it does not have to
+follow the GNAT file naming rules
@end itemize
@table @option
@cindex @option{^-c@var{n}^/COMMENTS_LAYOUT^} (@command{gnatpp})
+@item ^-c0^/COMMENTS_LAYOUT=UNTOUCHED^
+All the comments remain unchanged
+
@item ^-c1^/COMMENTS_LAYOUT=DEFAULT^
GNAT-style comment line indentation (this is the default).
Uncompact layout
@item ^-notab^/NOTABS^
-All the VT characters are removed from the comment text. All the HT characters are
-expanded with the sequences of space characters to get to the next tab stops.
+All the VT characters are removed from the comment text. All the HT characters
+are expanded with the sequences of space characters to get to the next tab
+stops.
@end table
@noindent
The @option{-c1} and @option{-c2} switches are incompatible.
The @option{-c3} and @option{-c4} switches are compatible with each other and
-also with @option{-c1} and @option{-c2}.
+also with @option{-c1} and @option{-c2}. The @option{-c0} switch disables all
+the other comment formatting switches.
The @option{-l1}, @option{-l2}, and @option{-l3} switches are incompatible.
@end ifclear
@cindex @option{^-rf^/OVERRIDING_REPLACE^} (@code{gnatpp})
Like @option{^-r^/REPLACE^} except that if the file with the specified name
already exists, it is overwritten.
+
+@item ^-rnb^/NO_BACKUP^
+@cindex @option{^-rnb^/NO_BACKUP^} (@code{gnatpp})
+Replace the input source file with the reformatted output without
+creating any backup copy of the input source.
@end table
@noindent
The additional @command{gnatpp} switches are defined in this subsection.
@table @option
+@item ^-files @var{filename}^/FILES=@var{output_file}^
+@cindex @option{^-files^/FILES^} (@code{gnatpp})
+Take the argument source files from the specified file. This file should be an
+ordinary textual file containing file names separated by spaces or
+line breaks. You can use this switch more then once in the same call to
+@command{gnatpp}. You also can combine this switch with explicit list of
+files.
+
@item ^-v^/VERBOSE^
@cindex @option{^-v^/VERBOSE^} (@code{gnatpp})
Verbose mode;
@cindex @option{^-u^/OUTPUT=UNITS^} (@code{gnatls})
Only output information about compilation units.
+@item ^-files^/FILES^=@var{file}
+@cindex @option{^-files^/FILES^} (@code{gnatls})
+Take as arguments the files listed in text file @var{file}.
+Text file @var{file} may contain empty lines that are ignored.
+Each non empty line should contain the name of an existing file.
+Several such switches may be specified simultaneously.
+
@item ^-aO^/OBJECT_SEARCH=^@var{dir}
@itemx ^-aI^/SOURCE_SEARCH=^@var{dir}
@itemx ^-I^/SEARCH=^@var{dir}
@ifclear vms
@node GNAT and Libraries
@chapter GNAT and Libraries
-@cindex Library, building, installing
+@cindex Library, building, installing, using
@noindent
-This chapter addresses some of the issues related to building and using
-a library with GNAT. It also shows how the GNAT run-time library can be
-recompiled.
+This chapter describes how to build and use
+libraries with GNAT, and also shows how to recompile the GNAT run-time library.
+You should be familiar with the
+Project Manager facility (see @ref{GNAT Project Manager}) before reading this
+chapter.
@menu
-* Creating an Ada Library::
-* Installing an Ada Library::
-* Using an Ada Library::
-* Creating an Ada Library to be Used in a Non-Ada Context::
+* Introduction to Libraries in GNAT::
+* General Ada Libraries::
+* Stand-alone Ada Libraries::
* Rebuilding the GNAT Run-Time Library::
@end menu
-@node Creating an Ada Library
-@section Creating an Ada Library
+@node Introduction to Libraries in GNAT
+@section Introduction to Libraries in GNAT
@noindent
-In the GNAT environment, a library has two components:
+A library is, conceptually, a collection of objects which does not have its
+own main thread of execution, but rather provides certain services to the
+applications that use it. A library can be either statically linked with the
+application, in which case its code is directly included in the application,
+or, on platforms that support it, be dynamically linked, in which case
+its code is shared by all applications making use of this library.
+
+GNAT supports both types of libraries.
+In the static case, the compiled code can be provided in different ways.
+The simplest approach is to provide directly the
+set of objects resulting from compilation of the library source files.
+Alternatively, you can group the objects into an archive using whatever
+commands are provided by the operating system. For the latter case,
+the objects are grouped into a shared library.
+
+In the GNAT environment, a library has two types of components:
@itemize @bullet
@item
Source files.
@item
-Compiled code and Ali files. See @ref{The Ada Library Information Files}.
+Compiled code and @file{ALI} files.
+See @ref{The Ada Library Information Files}.
@end itemize
@noindent
-In order to use other packages @ref{The GNAT Compilation Model}
-requires a certain number of sources to be available to the compiler.
-The minimal set of
-sources required includes the specs of all the packages that make up the
-visible part of the library as well as all the sources upon which they
-depend. The bodies of all visible generic units must also be provided.
-@noindent
-Although it is not strictly mandatory, it is recommended that all sources
-needed to recompile the library be provided, so that the user can make
-full use of inter-unit inlining and source-level debugging. This can also
-make the situation easier for users that need to upgrade their compilation
-toolchain and thus need to recompile the library from sources.
+A GNAT library may either completely expose its source files to the
+compilation context of the user's application.
+Alternatively, it may expose
+a limited subset of its source files, called @emph{interface units},
+in which case the library is referred to as a @emph{stand-alone library}
+(see @ref{Stand-alone Ada Libraries}). In addition, GNAT fully supports
+foreign libraries, which are only available in the object format.
+
+All compilation units comprising
+an application are elaborated, in an order partially defined by Ada language
+semantics.
+Where possible, GNAT provides facilities
+to ensure that compilation units of a library are automatically elaborated;
+however, there are cases where this must be responsibility of a user. This will
+be addressed in greater detail below.
+
+@node General Ada Libraries
+@section General Ada Libraries
+
+@menu
+* Building the library::
+* Installing the library::
+* Using the library::
+@end menu
+
+@node Building the library
+@subsection Building the library
@noindent
-The compiled code can be provided in different ways. The simplest way is
-to provide directly the set of objects produced by the compiler during
-the compilation of the library. It is also possible to group the objects
-into an archive using whatever commands are provided by the operating
-system. Finally, it is also possible to create a shared library (see
-option -shared in the GCC manual).
+The easiest way to build a library is to use the Project Manager,
+which supports a special type of projects called Library Projects
+(see @ref{Library Projects}).
+
+A project is considered a library project, when two project-level attributes
+are defined in it: @code{Library_Name} and @code{Library_Dir}. In order to
+control different aspects of library configuration, additional optional
+project-level attributes can be specified:
+@table @code
+@item Library_Kind
+This attribute controls whether the library is to be static or shared
+
+@item Library_Version
+This attribute specifies what is the library version; this value is used
+during dynamic linking of shared libraries to determine if the currently
+installed versions of the binaries are compatible.
+
+@item Library_Options
+@item Library_GCC
+These attributes specify additional low-level options to be used during
+library generation, and redefine the actual application used to generate
+library.
+@end table
@noindent
+The GNAT Project Manager takes full care of the library maintenance task,
+including recompilation of the source files for which objects do not exist
+or are not up to date, assembly of the library archive, and installation of
+the library, i.e. copying associated source, object and @file{ALI} files
+to the specified location.
+
+It is not entirely trivial to correctly perform all the steps required to
+produce a library. We recommend that you use the GNAT Project Manager
+for this task. In special cases where this is not desired, the necessary
+steps are discussed below.
+
There are various possibilities for compiling the units that make up the
-library: for example with a Makefile @ref{Using the GNU make Utility},
+library: for example with a Makefile (see @ref{Using the GNU make Utility})
or with a conventional script.
For simple libraries, it is also possible to create a
dummy main program which depends upon all the packages that comprise the
interface of the library. This dummy main program can then be given to
-gnatmake, in order to build all the necessary objects. Here is an example
-of such a dummy program and the generic commands used to build an
-archive or a shared library.
+@command{gnatmake}, which will ensure that all necessary objects are built.
+After this task is accomplished, you should follow the standard procedure
+of the underlying operating system to produce the static or shared library.
+
+Here is an example of such a dummy program:
@smallexample @c ada
-@iftex
-@leftskip=.7cm
-@end iftex
+@group
with My_Lib.Service1;
with My_Lib.Service2;
with My_Lib.Service3;
begin
null;
end;
+@end group
@end smallexample
+@noindent
+Here are the generic commands that will build an archive or a shared library.
+
@smallexample
# compiling the library
$ gnatmake -c my_lib_dummy.adb
# Make the ALI files read-only so that gnatmake will not try to
# regenerate the objects that are in the library
$ chmod -w *.ali
-
@end smallexample
@noindent
-When the objects are grouped in an archive or a shared library, the user
-needs to specify the desired library at link time, unless a pragma
-linker_options has been used in one of the sources:
-@smallexample @c ada
-pragma Linker_Options ("-lmy_lib");
-@end smallexample
+Please note that the library must have a name of the form @file{libxxx.a} or
+@file{libxxx.so} in order to be accessed by the directive @option{-lxxx}
+at link time.
-@noindent
-Please note that the library must have a name of the form libxxx.a or
-libxxx.so in order to be accessed by the directive -lxxx at link
-time.
-
-@node Installing an Ada Library
-@section Installing an Ada Library
+@node Installing the library
+@subsection Installing the library
@noindent
In the GNAT model, installing a library consists in copying into a specific
-location the files that make up this library. It is possible to install
-the sources in a different directory from the other files (ALI, objects,
-archives) since the source path and the object path can easily be
-specified separately.
-
-@noindent
-For general purpose libraries, it is possible for the system
-administrator to put those libraries in the default compiler paths. To
-achieve this, he must specify their location in the configuration files
-@file{ada_source_path} and @file{ada_object_path} that must be located in
-the GNAT
+location the files that make up this library. When the library is built using
+projects, it is automatically installed in the location specified in the
+project by means of the attribute @code{Library_Dir},
+otherwise the user must specify the destination.
+GNAT also supports installing the sources in a
+different directory from the other files (@file{ALI}, objects, archives)
+since the source path and the object path can be specified separately.
+
+The system administrator can place general purpose libraries in the default
+compiler paths, by specifying the libraries' location in the configuration
+files @file{ada_source_path} and @file{ada_object_path}.
+These configuration files must be located in the GNAT
installation tree at the same place as the gcc spec file. The location of
the gcc spec file can be determined as follows:
@smallexample
@end smallexample
@noindent
-The configuration files mentioned above have simple format: each line in them
-must contain one unique
-directory name. Those names are added to the corresponding path
+The configuration files mentioned above have a simple format: each line
+must contain one unique directory name.
+Those names are added to the corresponding path
in their order of appearance in the file. The names can be either absolute
-or relative, in the latter case, they are relative to where theses files
+or relative; in the latter case, they are relative to where theses files
are located.
-@noindent
-@file{ada_source_path} and @file{ada_object_path} might actually not be
+The files @file{ada_source_path} and @file{ada_object_path} might not be
present in a
GNAT installation, in which case, GNAT will look for its run-time library in
-he directories @file{adainclude} for the sources and @file{adalib} for the
-objects and @file{ALI} files. When the files exist, the compiler does not
-look in @file{adainclude} and @file{adalib} at all, and thus the
+the directories @file{adainclude} (for the sources) and @file{adalib} (for the
+objects and @file{ALI} files). When the files exist, the compiler does not
+look in @file{adainclude} and @file{adalib}, and thus the
@file{ada_source_path} file
must contain the location for the GNAT run-time sources (which can simply
be @file{adainclude}). In the same way, the @file{ada_object_path} file must
contain the location for the GNAT run-time objects (which can simply
be @file{adalib}).
-@noindent
-You can also specify a new default path to the runtime library at compilation
-time with the switch @option{--RTS=rts-path}. You can easily choose and change
-the runtime you want your program to be compiled with. This switch is
-recognized by gcc, gnatmake, gnatbind, gnatls, gnatfind and gnatxref.
+You can also specify a new default path to the run-time library at compilation
+time with the switch @option{--RTS=rts-path}. You can thus choose / change
+the run-time library you want your program to be compiled with. This switch is
+recognized by @command{gcc}, @command{gnatmake}, @command{gnatbind},
+@command{gnatls}, @command{gnatfind} and @command{gnatxref}.
-@noindent
It is possible to install a library before or after the standard GNAT
library, by reordering the lines in the configuration files. In general, a
library must be installed before the GNAT library if it redefines
any part of it.
-@node Using an Ada Library
-@section Using an Ada Library
+
+@node Using the library
+@subsection Using the library
+
+@noindent
+Once again, the project facility greatly simplifies the addition of libraries
+to the compilation. If the project file for an application lists a library
+project in its @code{with} clause, the Project Manager will ensure that the
+library files are consistent, and that they are considered during the
+compilation and linking of the application.
+
+Even if you have a third-party, non-Ada library, you can still use GNAT's
+Project Manager facility to provide a wrapper for it. The following project for
+example, when @code{with}ed in your main project, will link with the
+third-party library @file{liba.a}:
+
+@smallexample @c projectfile
+@group
+project Liba is
+ for Source_Dirs use ();
+ for Library_Dir use "lib";
+ for Library_Name use "a";
+ for Library_Kind use "static";
+end Liba;
+@end group
+@end smallexample
@noindent
-In order to use a Ada library, you need to make sure that this
+In order to use an Ada library manually, you need to make sure that this
library is on both your source and object path
-@ref{Search Paths and the Run-Time Library (RTL)}
-and @ref{Search Paths for gnatbind}. For
-instance, you can use the library @file{mylib} installed in
+(see @ref{Search Paths and the Run-Time Library (RTL)},
+and @ref{Search Paths for gnatbind}). Furthermore, when the objects are grouped
+in an archive or a shared library, you need to specify the desired
+library at link time.
+
+For example, you can use the library @file{mylib} installed in
@file{/dir/my_lib_src} and @file{/dir/my_lib_obj} with the following commands:
@smallexample
@end smallexample
@noindent
-This can be simplified down to the following:
+This can be expressed more simply:
@smallexample
$ gnatmake my_appl
@end smallexample
+@noindent
when the following conditions are met:
@itemize @bullet
@item
variable @code{ADA_OBJECTS_PATH}, or by the administrator to the file
@file{ada_object_path}
@item
-a pragma @code{Linker_Options}, as mentioned in @ref{Creating an Ada Library},
-has been added to the sources.
-@end itemize
-@noindent
-
-@node Creating an Ada Library to be Used in a Non-Ada Context
-@section Creating an Ada Library to be Used in a Non-Ada Context
+a pragma @code{Linker_Options} has been added to one of the sources.
+For example:
-@noindent
-The previous sections detailed how to create and install a library that
-was usable from an Ada main program. Using this library in a non-Ada
-context is not possible, because the elaboration of the library is
-automatically done as part of the main program elaboration.
+@smallexample @c ada
+pragma Linker_Options ("-lmy_lib");
+@end smallexample
+@end itemize
-GNAT also provides the ability to build libraries that can be used both
-in an Ada and non-Ada context. This section describes how to build such
-a library, and then how to use it from a C program. The method for
-interfacing with the library from other languages such as Fortran for
-instance remains the same.
-@subsection Creating the Library
+@node Stand-alone Ada Libraries
+@section Stand-alone Ada Libraries
+@cindex Stand-alone library, building, using
-@itemize @bullet
-@item Identify the units representing the interface of the library.
+@menu
+* Introduction to Stand-alone Libraries::
+* Building a Stand-alone Library::
+* Creating a Stand-alone Library to be used in a non-Ada context::
+* Restrictions in Stand-alone Libraries::
+@end menu
-Here is an example of simple library interface:
+@node Introduction to Stand-alone Libraries
+@subsection Introduction to Stand-alone Libraries
+
+@noindent
+A Stand-alone Library (SAL) is a library that contains the necessary code to
+elaborate the Ada units that are included in the library. In contrast with
+an ordinary library, which consists of all sources, objects and @file{ALI}
+files of the
+library, a SAL may specify a restricted subset of compilation units
+to serve as a library interface. In this case, the fully
+self-sufficient set of files will normally consist of an objects
+archive, the sources of interface units' specs, and the @file{ALI}
+files of interface units.
+If an interface spec contains a generic unit or an inlined subprogram,
+the body's
+source must also be provided; if the units that must be provided in the source
+form depend on other units, the source and @file{ALI} files of those must
+also be provided.
+
+The main purpose of a SAL is to minimize the recompilation overhead of client
+applications when a new version of the library is installed. Specifically,
+if the interface sources have not changed, client applications do not need to
+be recompiled. If, furthermore, a SAL is provided in the shared form and its
+version, controlled by @code{Library_Version} attribute, is not changed,
+then the clients do not need to be relinked.
+
+SALs also allow the library providers to minimize the amount of library source
+text exposed to the clients. Such ``information hiding'' might be useful or
+necessary for various reasons.
+
+Stand-alone libraries are also well suited to be used in an executable whose
+main routine is not written in Ada.
+
+@node Building a Stand-alone Library
+@subsection Building a Stand-alone Library
+
+@noindent
+GNAT's Project facility provides a simple way of building and installing
+stand-alone libraries; see @ref{Stand-alone Library Projects}.
+To be a Stand-alone Library Project, in addition to the two attributes
+that make a project a Library Project (@code{Library_Name} and
+@code{Library_Dir}; see @ref{Library Projects}), the attribute
+@code{Library_Interface} must be defined. For example:
-@smallexample @c ada
-package Interface is
+@smallexample @c projectfile
+@group
+ for Library_Dir use "lib_dir";
+ for Library_Name use "dummy";
+ for Library_Interface use ("int1", "int1.child");
+@end group
+@end smallexample
- procedure Do_Something;
+@noindent
+Attribute @code{Library_Interface} has a non empty string list value,
+each string in the list designating a unit contained in an immediate source
+of the project file.
- procedure Do_Something_Else;
+When a Stand-alone Library is built, first the binder is invoked to build
+a package whose name depends on the library name
+(@file{^b~dummy.ads/b^B$DUMMY.ADS/B^} in the example above).
+This binder-generated package includes initialization and
+finalization procedures whose
+names depend on the library name (@code{dummyinit} and @code{dummyfinal}
+in the example
+above). The object corresponding to this package is included in the library.
-end Interface;
-@end smallexample
+You must ensure timely (e.g., prior to any use of interfaces in the SAL)
+calling of these procedures if a static SAL is built, or if a shared SAL
+is built
+with the project-level attribute @code{Library_Auto_Init} set to
+@code{"false"}.
-@item Use @code{pragma Export} or @code{pragma Convention} for the
-exported entities.
+For a Stand-Alone Library, only the @file{ALI} files of the Interface Units
+(those that are listed in attribute @code{Library_Interface}) are copied to
+the Library Directory. As a consequence, only the Interface Units may be
+imported from Ada units outside of the library. If other units are imported,
+the binding phase will fail.
-Our package @code{Interface} is then updated as follow:
-@smallexample @c ada
-package Interface is
+The attribute @code{Library_Src_Dir} may be specified for a
+Stand-Alone Library. @code{Library_Src_Dir} is a simple attribute that has a
+single string value. Its value must be the path (absolute or relative to the
+project directory) of an existing directory. This directory cannot be the
+object directory or one of the source directories, but it can be the same as
+the library directory. The sources of the Interface
+Units of the library that are needed by an Ada client of the library will be
+copied to the designated directory, called the Interface Copy directory.
+These sources includes the specs of the Interface Units, but they may also
+include bodies and subunits, when pragmas @code{Inline} or @code{Inline_Always}
+are used, or when there is a generic unit in the spec. Before the sources
+are copied to the Interface Copy directory, an attempt is made to delete all
+files in the Interface Copy directory.
- procedure Do_Something;
- pragma Export (C, Do_Something, "do_something");
+Building stand-alone libraries by hand is somewhat tedious, but for those
+occasions when it is necessary here are the steps that you need to perform:
+@itemize @bullet
+@item
+Compile all library sources.
- procedure Do_Something_Else;
- pragma Export (C, Do_Something_Else, "do_something_else");
+@item
+Invoke the binder with the switch @option{-n} (No Ada main program),
+with all the @file{ALI} files of the interfaces, and
+with the switch @option{-L} to give specific names to the @code{init}
+and @code{final} procedures. For example:
+@smallexample
+ gnatbind -n int1.ali int2.ali -Lsal1
+@end smallexample
-end Interface;
+@item
+Compile the binder generated file:
+@smallexample
+ gcc -c b~int2.adb
@end smallexample
-@item Compile all the units composing the library.
+@item
+Link the dynamic library with all the necessary object files,
+indicating to the linker the names of the @code{init} (and possibly
+@code{final}) procedures for automatic initialization (and finalization).
+The built library should be placed in a directory different from
+the object directory.
-@item Bind the library objects.
+@item
+Copy the @code{ALI} files of the interface to the library directory,
+add in this copy an indication that it is an interface to a SAL
+(i.e. add a word @option{SL} on the line in the @file{ALI} file that starts
+with letter ``P'') and make the modified copy of the @file{ALI} file
+read-only.
+@end itemize
-This step is performed by invoking gnatbind with the @option{-L<prefix>}
-switch. @code{gnatbind} will then generate the library elaboration
-procedure (named @code{<prefix>init}) and the run-time finalization
-procedure (named @code{<prefix>final}).
+@noindent
+Using SALs is not different from using other libraries
+(see @ref{Using the library}).
-@smallexample
-# generate the binder file in Ada
-$ gnatbind -Lmylib interface
+@node Creating a Stand-alone Library to be used in a non-Ada context
+@subsection Creating a Stand-alone Library to be used in a non-Ada context
-# generate the binder file in C
-$ gnatbind -C -Lmylib interface
-@end smallexample
+@noindent
+It is easy to adapt the SAL build procedure discussed above for use of a SAL in
+a non-Ada context.
-@item Compile the files generated by the binder
+The only extra step required is to ensure that library interface subprograms
+are compatible with the main program, by means of @code{pragma Export}
+or @code{pragma Convention}.
-@smallexample
-$ gcc -c b~interface.adb
-@end smallexample
+Here is an example of simple library interface for use with C main program:
-@item Create the library;
+@smallexample @c ada
+package Interface is
-The procedure is identical to the procedure explained in
-@ref{Creating an Ada Library},
-except that @file{b~interface.o} needs to be added to
-the list of objects.
+ procedure Do_Something;
+ pragma Export (C, Do_Something, "do_something");
-@smallexample
-# create an archive file
-$ ar cr libmylib.a b~interface.o <other object files>
+ procedure Do_Something_Else;
+ pragma Export (C, Do_Something_Else, "do_something_else");
-# create a shared library
-$ gcc -shared -o libmylib.so b~interface.o <other object files>
+end Interface;
@end smallexample
-@item Provide a ``foreign'' view of the library interface;
+@noindent
+On the foreign language side, you must provide a ``foreign'' view of the
+library interface; remember that it should contain elaboration routines in
+addition to interface subprograms.
The example below shows the content of @code{mylib_interface.h} (note
that there is no rule for the naming of this file, any name can be used)
extern void do_something (void);
extern void do_something_else (void);
@end smallexample
-@end itemize
-
-@subsection Using the Library
@noindent
Libraries built as explained above can be used from any program, provided
libraries can be used simultaneously, as long as the elaboration
procedure of each library is called.
-Below is an example of C program that uses our @code{mylib} library.
+Below is an example of C program that uses the @code{mylib} library.
@smallexample
#include "mylib_interface.h"
@end smallexample
@noindent
-Note that this same library can be used from an equivalent Ada main
-program. In addition, if the libraries are installed as detailed in
-@ref{Installing an Ada Library}, it is not necessary to invoke the
-library elaboration and finalization routines. The binder will ensure
-that this is done as part of the main program elaboration and
-finalization phases.
-
-@subsection The Finalization Phase
-
-@noindent
-Invoking any library finalization procedure generated by @code{gnatbind}
-shuts down the Ada run time permanently. Consequently, the finalization
-of all Ada libraries must be performed at the end of the program. No
-call to these libraries nor the Ada run time should be made past the
-finalization phase.
+Note that invoking any library finalization procedure generated by
+@code{gnatbind} shuts down the Ada run-time environment.
+Consequently, the
+finalization of all Ada libraries must be performed at the end of the program.
+No call to these libraries nor to the Ada run-time library should be made
+after the finalization phase.
-@subsection Restrictions in Libraries
+@node Restrictions in Stand-alone Libraries
+@subsection Restrictions in Stand-alone Libraries
@noindent
The pragmas listed below should be used with caution inside libraries,
@item pragma @code{Task_Dispatching_Policy}
@item pragma @code{Unreserve_All_Interrupts}
@end itemize
+
+@noindent
When using a library that contains such pragmas, the user must make sure
that all libraries use the same pragmas with the same values. Otherwise,
-a @code{Program_Error} will
+@code{Program_Error} will
be raised during the elaboration of the conflicting
libraries. The usage of these pragmas and its consequences for the user
should therefore be well documented.
-Similarly, the traceback in exception occurrences mechanism should be
+Similarly, the traceback in the exception occurrence mechanism should be
enabled or disabled in a consistent manner across all libraries.
-Otherwise, a Program_Error will be raised during the elaboration of the
+Otherwise, Program_Error will be raised during the elaboration of the
conflicting libraries.
-If the @code{'Version} and @code{'Body_Version}
-attributes are used inside a library, then it is necessary to
-perform a @code{gnatbind} step that mentions all @file{ALI} files in all
+If the @code{Version} or @code{Body_Version}
+attributes are used inside a library, then you need to
+perform a @code{gnatbind} step that specifies all @file{ALI} files in all
libraries, so that version identifiers can be properly computed.
In practice these attributes are rarely used, so this is unlikely
to be a consideration.
@node Rebuilding the GNAT Run-Time Library
@section Rebuilding the GNAT Run-Time Library
+@cindex GNAT Run-Time Library, rebuilding
@noindent
It may be useful to recompile the GNAT library in various contexts, the
most important one being the use of partition-wide configuration pragmas
-such as Normalize_Scalar. A special Makefile called
+such as @code{Normalize_Scalars}. A special Makefile called
@code{Makefile.adalib} is provided to that effect and can be found in
the directory containing the GNAT library. The location of this
directory depends on the way the GNAT environment has been installed and can
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
@cindex @option{^-gnatyM^/MAX_LINE_LENGTH^} (@command{gnatstub})
(@var{n} is a non-negative integer). Set the maximum line length in the
body stub to @var{n}; the default is 79. The maximum value that can be
-specified is 32767.
+specified is 32767. Note that in the special case of configuration
+pragma files, the maximum is always 32767 regardless of whether or
+not this switch appears.
@item ^-gnaty^/STYLE_CHECKS=^@var{n}
@cindex @option{^-gnaty^/STYLE_CHECKS=^} (@command{gnatstub})
* Solaris-Specific Considerations::
* IRIX-Specific Considerations::
* Linux-Specific Considerations::
+* AIX-Specific Considerations::
@end menu
e.g. by using @code{killpg()}.
@end itemize
+@node AIX-Specific Considerations
+@section AIX-Specific Considerations
+@cindex AIX resolver library
+@noindent
+On AIX, the resolver library initializes some internal structure on
+the first call to @code{get*by*} functions, which are used to implement
+@code{GNAT.Sockets.Get_Host_By_Name} and
+@code{GNAT.Sockets.Get_Host_By_Addrss}.
+If such initialization occurs within an Ada task, and the stack size for
+the task is the default size, a stack overflow may occur.
+
+To avoid this overflow, the user should either ensure that the first call
+to @code{GNAT.Sockets.Get_Host_By_Name} or
+@code{GNAT.Sockets.Get_Host_By_Addrss}
+occurs in the environment task, or use @code{pragma Storage_Size} to
+specify a sufficiently large size for the stack of the task that contains
+this call.
@c *******************************
@node Example of Binder Output File
* 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
to standard output the list of entry points in the DLL. Note that if
some routines in the DLL have the @code{Stdcall} convention
(@pxref{Windows Calling Conventions}) with stripped @code{@@}@i{nn}
-suffix then you'll have to edit @file{api.def} to add it.
+suffix then you'll have to edit @file{api.def} to add it, and specify
+@code{-k} to @code{gnatdll} when creating the import library.
@noindent
Here are some hints to find the right @code{@@}@i{nn} suffix.
@section Building DLLs with GNAT
@cindex DLLs, building
+@noindent
+This section explain how to build DLLs using the GNAT built-in DLL
+support. With the following procedure it is straight forward to build
+and use DLLs with GNAT.
+
+@enumerate
+
+@item building object files
+
+The first step is to build all objects files that are to be included
+into the DLL. This is done by using the standard @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:
@item -k
@cindex @option{-k} (@code{gnatdll})
Removes the @code{@@}@i{nn} suffix from the import library's exported
-names. You must specified this option if you want to use a
-@code{Stdcall} function in a DLL for which the @code{@@}@i{nn} suffix
-has been removed. This is the case for most of the Windows NT DLL for
-example. This option has no effect when @option{-n} option is specified.
+names, but keeps them for the link names. You must specify this
+option if you want to use a @code{Stdcall} function in a DLL for which
+the @code{@@}@i{nn} suffix has been removed. This is the case for most
+of the Windows NT DLL for example. This option has no effect when
+@option{-n} option is specified.
@item -l @var{file}
@cindex @option{-l} (@code{gnatdll})
OSDN Git Service
