\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-2007, AdaCore o
-@c o
-@c GNAT is free software; you can redistribute it and/or modify it under o
-@c terms of the GNU General Public License as published by the Free Soft- o
-@c 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, 51 Franklin Street, Fifth Floor, o
-@c Boston, MA 02110-1301, USA. o
+@c GNAT is maintained by Ada Core Technologies Inc (http://www.gnat.com). o
@c o
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
+@setfilename gnat_ugn.info
+
+@copying
+Copyright @copyright{} 1995-2005, 2006, 2007, 2008 Free Software Foundation,
+Inc.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts and with no Back-Cover
+Texts. A copy of the license is included in the section entitled
+``GNU Free Documentation License''.
+@end copying
+
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
@c
@c GNAT_UGN Style Guide
@c
@c oooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooooo
-@setfilename gnat_ugn.info
-
@set NOW January 2007
@c This flag is used where the text refers to conditions that exist when the
@c text was entered into the document but which may change over time.
@set NONDEFAULTLANGUAGEVERSION Ada 95
@ifset unw
-@setfilename gnat_ugn_unw.info
-@end ifset
-
-@ifset unw
@set PLATFORM
-@set FILE gnat_ugn_unw
@end ifset
@ifset vms
@set PLATFORM OpenVMS
-@set FILE gnat_ugn_vms
@end ifset
+@c @ovar(ARG)
+@c ----------
+@c The ARG is an optional argument. To be used for macro arguments in
+@c their documentation (@defmac).
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}@c
+@end macro
+
@settitle @value{EDITION} User's Guide @value{PLATFORM}
@dircategory GNU Ada tools
@direntry
-* @value{EDITION} User's Guide (@value{FILE}) @value{PLATFORM}
+* @value{EDITION} User's Guide: (gnat_ugn). @value{PLATFORM}
@end direntry
@include gcc-common.texi
@syncodeindex fn cp
@c %**end of header
-@copying
-Copyright @copyright{} 1995-2005, Free Software Foundation
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.2
-or any later version published by the Free Software Foundation;
-with the Invariant Sections being ``GNU Free Documentation License'', with the
-Front-Cover Texts being
-``@value{EDITION} User's Guide'',
-and with no Back-Cover Texts.
-A copy of the license is included in the section entitled
-``GNU Free Documentation License''.
-@end copying
-
@titlepage
@title @value{EDITION} User's Guide
@ifset vms
* Stack Related Facilities::
* Verifying Properties Using gnatcheck::
* Creating Sample Bodies Using gnatstub::
+* Generating Ada Bindings for C and C++ headers::
* Other Utility Programs::
* Running and Debugging Ada Programs::
+@ifclear vms
+* Code Coverage and Profiling::
+@end ifclear
@ifset vms
* Compatibility with HP Ada::
@end ifset
Improving Performance
* Performance Considerations::
+* Text_IO Suggestions::
* Reducing Size of Ada Executables with gnatelim::
* Reducing Size of Executables with unused subprogram/data elimination::
* Examples of gnatkr Usage::
Preprocessing Using gnatprep
+* Preprocessing Symbols::
* Using gnatprep::
* Switches for gnatprep::
* Form of Definitions File::
* The External Symbol Naming Scheme of GNAT::
* Converting Ada Files to html with gnathtml::
+@ifclear vms
+Code Coverage and Profiling
+
+* Code Coverage of Ada Programs using gcov::
+* Profiling an Ada Program using gprof::
+@end ifclear
+
Running and Debugging Ada Programs
* The GNAT Debugger GDB::
* Solaris-Specific Considerations::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
+* Irix-Specific Considerations::
Example of Binder Output File
a utility that generates empty but compilable bodies for library units.
@item
+@ref{Generating Ada Bindings for C and C++ headers}, describes how to
+generate automatically Ada bindings from C and C++ headers.
+
+@item
@ref{Other Utility Programs}, discusses several other GNAT utilities,
including @code{gnathtml}.
+@ifclear vms
+@item
+@ref{Code Coverage and Profiling}, describes how to perform a structural
+coverage and profile the execution of Ada programs.
+@end ifclear
+
@item
@ref{Running and Debugging Ada Programs}, describes how to run and debug
Ada programs.
@itemize @bullet
@item
-@cite{GNAT Reference Manual}, which contains all reference
-material for the GNAT implementation of Ada.
+@xref{Top, GNAT Reference Manual, About This Guide, gnat_rm, GNAT
+Reference Manual}, which contains all reference material for the GNAT
+implementation of Ada.
@ifset unw
@item
material for the Ada 2005 programming language.
@item
-@cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
@ifset vms
-, located in the GNU:[DOCS] directory,
+in the GNU:[DOCS] directory,
@end ifset
-contains all details on the use of the GNU source-level debugger.
+for all details on the use of the GNU source-level debugger.
@item
-@cite{GNU Emacs Manual}
+@xref{Top,, The extensible self-documenting text editor, emacs,
+GNU Emacs Manual},
@ifset vms
-, located in the GNU:[DOCS] directory if the EMACS kit is installed,
+located in the GNU:[DOCS] directory if the EMACS kit is installed,
@end ifset
-contains full information on the extensible editor and programming
+for full information on the extensible editor and programming
environment Emacs.
@end itemize
@itemize @bullet
@item
-@code{Functions}, @code{utility program names}, @code{standard names},
+@code{Functions}, @command{utility program names}, @code{standard names},
and @code{classes}.
@item
-@samp{Option flags}
+@option{Option flags}
@item
-@file{File Names}, @file{button names}, and @file{field names}.
+@file{File names}, @samp{button names}, and @samp{field names}.
@item
-@var{Variables}.
+@code{Variables}, @env{environment variables}, and @var{metasyntactic
+variables}.
@item
@emph{Emphasis}.
@item
-[optional information or parameters]
+@r{[}optional information or parameters@r{]}
@item
Examples are described by text
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).
+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
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.
+e.g.@: @code{abcde}, at the prompt.
The program will pause execution when it gets to the
breakpoint, and the corresponding line is highlighted.
@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
+@dots{} @code{16#7F#)} is identical to standard ASCII coding, but the upper half
is used to represent additional characters. These include extended letters
used by European languages, such as French accents, the vowels with umlauts
used in German, and the extra letter A-ring used in Swedish.
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.
+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
@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#
+16#0000#-16#007f#: 2#0@var{xxxxxxx}#
+16#0080#-16#07ff#: 2#110@var{xxxxx}# 2#10@var{xxxxxx}#
+16#0800#-16#ffff#: 2#1110@var{xxxx}# 2#10@var{xxxxxx}# 2#10@var{xxxxxx}#
@end smallexample
@noindent
-where the xxx bits correspond to the left-padded bits of the
+where the @var{xxx} bits correspond to the left-padded bits of the
16-bit character value. Note that all lower half ASCII characters
are represented as ASCII bytes and all upper half characters and
other wide characters are represented as sequences of upper-half
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,
+@samp{A}, @samp{G}, @samp{I}, or @samp{S},
@end ifset
@ifclear vms
-a,g,i, or s,
+@samp{a}, @samp{g}, @samp{i}, or @samp{s},
@end ifclear
and the second character is a
minus. In this case, the character ^tilde^dollar sign^ is used in place
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-
+@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},
@end ifset
@ifclear vms
-s- a- i- and g-
+@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},
@end ifclear
respectively.
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
+preceded by the special sequence @option{-x} followed by a space and the name
of the language, here @code{ada}, as in:
@smallexample
@command{gnatmake} handles non-standard file names in the usual manner (the
non-standard file name for the main program is simply used as the
argument to gnatmake). Note that if the extension is also non-standard,
-then it must be included in the gnatmake command, it may not be omitted.
+then it must be included in the @command{gnatmake} command, it may not
+be omitted.
@node Alternative File Naming Schemes
@section Alternative File Naming Schemes
@smallexample @c ada
pragma Source_File_Name (
Spec_File_Name => FILE_NAME_PATTERN
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ @r{[},Casing => CASING_SPEC@r{]}
+ @r{[},Dot_Replacement => STRING_LITERAL@r{]});
pragma Source_File_Name (
Body_File_Name => FILE_NAME_PATTERN
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ @r{[},Casing => CASING_SPEC@r{]}
+ @r{[},Dot_Replacement => STRING_LITERAL@r{]});
pragma Source_File_Name (
Subunit_File_Name => FILE_NAME_PATTERN
- [,Casing => CASING_SPEC]
- [,Dot_Replacement => STRING_LITERAL]);
+ @r{[},Casing => CASING_SPEC@r{]}
+ @r{[},Dot_Replacement => STRING_LITERAL@r{]});
FILE_NAME_PATTERN ::= STRING_LITERAL
CASING_SPEC ::= Lowercase | Uppercase | Mixedcase
@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
+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
it is necessary to compile in optimizing mode.
@cindex @option{-gnatN} switch
-The use of @option{-gnatN} activates a more extensive inlining optimization
+The use of @option{-gnatN} activates inlining optimization
that is performed by the front end of the compiler. This inlining does
not require that the code generation be optimized. Like @option{-gnatn},
the use of this switch generates additional dependencies.
-Note that
-@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
-to specify both options.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@item
If an object file @file{O} depends on the proper body of a subunit through
checking.
@item
-Categorization information (e.g. use of pragma @code{Pure}).
+Categorization information (e.g.@: use of pragma @code{Pure}).
@item
Information on all @code{with}'ed units, including presence of
Reference Manual. If a pragma Import (Intrinsic) applies to a subprogram,
this means that the body of the subprogram is provided by the compiler itself,
usually by means of an efficient code sequence, and that the user does not
-supply an explicit body for it. In an application program, the pragma can
-only be applied to the following two sets of names, which the GNAT compiler
-recognizes.
+supply an explicit body for it. In an application program, the pragma may
+be applied to the following sets of names:
@itemize @bullet
@item
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: ``+'', ``-'', ``*'', ``/''
+
+@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
explicit body. The pragma makes it simpler to introduce such declarations.
It incurs no overhead in compilation time or code size, because it is
implemented as a single machine instruction.
+
+@item
+General subprogram entities, to bind an Ada subprogram declaration to
+a compiler builtin by name with back-ends where such interfaces are
+available. A typical example is the set of ``__builtin'' functions
+exposed by the GCC back-end, as in the following example:
+
+@smallexample @c ada
+ function builtin_sqrt (F : Float) return Float;
+ pragma Import (Intrinsic, builtin_sqrt, "__builtin_sqrtf");
+@end smallexample
+
+Most of the GCC builtins are accessible this way, and as for other
+import conventions (e.g. C), it is the user's responsibility to ensure
+that the Ada subprogram profile matches the underlying builtin
+expectations.
@end itemize
+
@noindent
@ifset unw
and specifies that the @code{Stdcall} calling sequence will be used,
as defined by the NT API. Nevertheless, to ease building
cross-platform bindings this convention will be handled as a @code{C} calling
-convention on non Windows platforms.
+convention on non-Windows platforms.
@findex DLL
@cindex Convention DLL
@noindent
Interfacing can be done at 3 levels: simple data, subprograms, and
-classes. In the first two cases, GNAT offers a specific @var{Convention
-C_Plus_Plus} (or @var{CPP}) that behaves exactly like @var{Convention C}.
+classes. In the first two cases, GNAT offers a specific @code{Convention
+C_Plus_Plus} (or @code{CPP}) that behaves exactly like @code{Convention C}.
Usually, C++ mangles the names of subprograms, and currently, GNAT does
not provide any help to solve the demangling problem. This problem can be
addressed in two ways:
@noindent
Interfacing at the class level can be achieved by using the GNAT specific
-pragmas such as @code{CPP_Constructor}. See the GNAT Reference Manual for
-additional information.
+pragmas such as @code{CPP_Constructor}. @xref{Interfacing to C++,,,
+gnat_rm, GNAT Reference Manual}, for additional information.
@node Linking a Mixed C++ & Ada Program
@subsection Linking a Mixed C++ & Ada Program
@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
+compilers are on the @env{PATH}, the previous method may be used. It is
+important to note that environment variables such as
+@env{C_INCLUDE_PATH}, @env{GCC_EXEC_PREFIX}, @env{BINUTILS_ROOT}, and
+@env{GCC_ROOT} will affect both compilers
at the same time and may make one of the two compilers operate
improperly if set during invocation of the wrong compiler. It is also
very important that the linker uses the proper @file{libgcc.a} GCC
library -- that is, the one from the C++ compiler installation. The
-implicit link command as suggested in the 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:
+implicit link command as suggested in the @command{gnatmake} command
+from the former example can be replaced by an explicit link command with
+the full-verbosity option in order to verify which library is used:
@smallexample
$ gnatbind ada_unit
$ gnatlink -v -v ada_unit file1.o file2.o --LINK=c++
Where CC is the name of the non-GNU C++ compiler.
If the @code{zero cost} exception mechanism is used, and the platform
-supports automatic registration of exception tables (e.g. Solaris or IRIX),
+supports automatic registration of exception tables (e.g.@: Solaris or IRIX),
paths to more objects are required:
@smallexample
@end smallexample
If the @code{zero cost} exception mechanism is used, and the platform
-doesn't support automatic registration of exception tables (e.g. HP-UX,
+doesn't support automatic registration of exception tables (e.g.@: HP-UX,
Tru64 or AIX), the simple approach described above will not work and
a pre-linking phase using GNAT will be necessary.
@b{#include} <iostream>
@b{using namespace} std;
-void Check_Carnivore (Carnivore *obj) @{ ... @}
-void Check_Domestic (Domestic *obj) @{ ... @}
-void Check_Animal (Animal *obj) @{ ... @}
-void Check_Dog (Dog *obj) @{ ... @}
+void Check_Carnivore (Carnivore *obj) @{@dots{}@}
+void Check_Domestic (Domestic *obj) @{@dots{}@}
+void Check_Animal (Animal *obj) @{@dots{}@}
+void Check_Dog (Dog *obj) @{@dots{}@}
@b{extern} "C" @{
void adainit (void);
@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):
+following error messages (where @var{fff} is the name of the file you compiled):
@smallexample
cannot generate code for file @var{fff} (package spec)
The basic command for compiling a file containing an Ada unit is
@smallexample
-$ gcc -c [@var{switches}] @file{file name}
+$ gcc -c @ovar{switches} @file{file name}
@end smallexample
@noindent
@cindex @option{-B} (@command{gcc})
Load compiler executables (for example, @code{gnat1}, the Ada compiler)
from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,, Options for Directory Search, gcc, Using the
+GNU Compiler Collection (GCC)}, for further details. You would normally
+use the @option{-b} or @option{-V} switch instead.
@item -c
@cindex @option{-c} (@command{gcc})
are ignored, and @option{-gnatn} and @option{-gnatN} have no
effect if this switch is present.
+@item -fno-inline-functions
+@cindex @option{-fno-inline-functions} (@command{gcc})
+Suppresses automatic inlining of simple subprograms, which is enabled
+if @option{-O3} is used.
+
+@item -fno-inline-small-functions
+@cindex @option{-fno-inline-small-functions} (@command{gcc})
+Suppresses automatic inlining of small subprograms, which is enabled
+if @option{-O2} is used.
+
+@item -fno-inline-functions-called-once
+@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
+Suppresses inlining of subprograms local to the unit and called once
+from within it, which is enabled if @option{-O1} is used.
+
@item -fno-strict-aliasing
@cindex @option{-fno-strict-aliasing} (@command{gcc})
Causes the compiler to avoid assumptions regarding non-aliasing
Makes the compiler output stack usage information for the program, on a
per-function basis. See @ref{Static Stack Usage Analysis} for details.
-@item -fcallgraph-info[=su]
+@item -fcallgraph-info@r{[}=su@r{]}
@cindex @option{-fcallgraph-info} (@command{gcc})
Makes the compiler output callgraph information for the program, on a
per-file basis. The information is generated in the VCG format. It can
Assertions enabled. @code{Pragma Assert} and @code{pragma Debug} to be
activated. Note that these pragmas can also be controlled using the
configuration pragmas @code{Assertion_Policy} and @code{Debug_Policy}.
+It also activates pragmas @code{Check}, @code{Precondition}, and
+@code{Postcondition}. Note that these pragmas can also be controlled
+using the configuration pragma @code{Check_Policy}.
@item -gnatA
@cindex @option{-gnatA} (@command{gcc})
-Avoid processing @file{gnat.adc}. If a gnat.adc file is present,
+Avoid processing @file{gnat.adc}. If a @file{gnat.adc} file is present,
it will be ignored.
@item -gnatb
@cindex @option{-gnatb} (@command{gcc})
Generate brief messages to @file{stderr} even if verbose mode set.
+@item -gnatB
+@cindex @option{-gnatB} (@command{gcc})
+Assume no invalid (bad) values except for 'Valid attribute use.
+
@item -gnatc
@cindex @option{-gnatc} (@command{gcc})
Check syntax and semantics only (no code generation attempted).
programmers, and these are documented at appropriate points in this
users guide.
+@ifclear vms
@item -gnatD
-@cindex @option{-gnatD} (@command{gcc})
+@cindex @option{-gnatD[nn]} (@command{gcc})
+@end ifclear
+@ifset vms
+@item /XDEBUG /LXDEBUG=nnn
+@end ifset
Create expanded source files for source level debugging. This switch
also suppress generation of cross-reference information
(see @option{-gnatx}).
@end ifclear
(@pxref{The Configuration Pragmas Files}).
-@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
+@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=@var{value}@r{]}
@cindex @option{-gnateD} (@command{gcc})
-Defines a symbol, associated with value, for preprocessing.
+Defines a symbol, associated with @var{value}, for preprocessing.
(@pxref{Integrated Preprocessing}).
@item -gnatef
@cindex @option{-gnatef} (@command{gcc})
Display full source path name in brief error messages.
+@item -gnateG
+@cindex @option{-gnateG} (@command{gcc})
+Save result of preprocessing in a text file.
+
@item -gnatem=@var{path}
@cindex @option{-gnatem} (@command{gcc})
Specify a mapping file
so that all standard warnings and all standard style options are turned on.
All warnings and style error messages are treated as errors.
-@item -gnatG
-@cindex @option{-gnatG} (@command{gcc})
+@ifclear vms
+@item -gnatG=nn
+@cindex @option{-gnatG[nn]} (@command{gcc})
+@end ifclear
+@ifset vms
+@item /EXPAND_SOURCE, /LEXPAND_SOURCE=nnn
+@end ifset
List generated expanded code in source form.
@item ^-gnath^/HELP^
@item -gnatm=@var{n}
@cindex @option{-gnatm} (@command{gcc})
Limit number of detected error or warning messages to @var{n}
-where @var{n} is in the range 1..999_999. The default setting if
-no switch is given is 9999. Compilation is terminated if this
-limit is exceeded. The equal sign here is optional.
+where @var{n} is in the range 1..999999. The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. The equal sign here is optional. A value of zero
+means that no limit applies.
@item -gnatn
@cindex @option{-gnatn} (@command{gcc})
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.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@item -gnato
@cindex @option{-gnato} (@command{gcc})
Enable numeric overflow checking (which is not normally enabled by
-default). Not that division by zero is a separate check that is not
+default). Note that division by zero is a separate check that is not
controlled by this switch (division by zero checking is on by default).
@item -gnatp
@cindex @option{-gnatp} (@command{gcc})
-Suppress all checks.
+Suppress all checks. See @ref{Run-Time Checks} for details.
@item -gnatP
@cindex @option{-gnatP} (@command{gcc})
Enable polling. This is required on some systems (notably Windows NT) to
obtain asynchronous abort and asynchronous transfer of control capability.
-See the description of pragma Polling in the GNAT Reference Manual for
-full details.
+@xref{Pragma Polling,,, gnat_rm, GNAT Reference Manual}, for full
+details.
@item -gnatq
@cindex @option{-gnatq} (@command{gcc})
-Don't quit; try semantics, even if parse errors.
+Don't quit. Try semantics, even if parse errors.
@item -gnatQ
@cindex @option{-gnatQ} (@command{gcc})
-Don't quit; generate @file{ALI} and tree files even if illegalities.
+Don't quit. Generate @file{ALI} and tree files even if illegalities.
-@item ^-gnatR[0/1/2/3[s]]^/REPRESENTATION_INFO^
+@item -gnatr
+@cindex @option{-gnatr} (@command{gcc})
+Treat pragma Restrictions as Restriction_Warnings.
+
+@item ^-gnatR@r{[}0@r{/}1@r{/}2@r{/}3@r{[}s@r{]]}^/REPRESENTATION_INFO^
@cindex @option{-gnatR} (@command{gcc})
Output representation information for declared types and objects.
Control level of validity checking. See separate section describing
this feature.
-@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}[,...])^
+@item ^-gnatw@var{xxx}^/WARNINGS=(@var{option}@r{[},@dots{}@r{]})^
@cindex @option{^-gnatw^/WARNINGS^} (@command{gcc})
Warning mode where
^@var{xxx} is a string of option letters that^the list of options^ denotes
@cindex @option{-gnatx} (@command{gcc})
Suppress generation of cross-reference information.
-@item ^-gnaty^/STYLE_CHECKS=(option,option..)^
+@item ^-gnaty^/STYLE_CHECKS=(option,option@dots{})^
@cindex @option{^-gnaty^/STYLE_CHECKS^} (@command{gcc})
Enable built-in style checks (@pxref{Style Checking}).
Library (RTL) ALI files.
@ifclear vms
-@item -O[@var{n}]
+@item -O@ovar{n}
@cindex @option{-O} (@command{gcc})
@var{n} controls the optimization level.
This is the default behavior in the absence of an @option{/OPTIMIZE}
qualifier.
-@item /OPTIMIZE[=(keyword[,...])]
+@item /OPTIMIZE@r{[}=(keyword@r{[},@dots{}@r{]})@r{]}
@cindex @option{/OPTIMIZE} (@code{GNAT COMPILE})
Selects the level of optimization for your program. The supported
keywords are as follows:
Turn off warnings generated by the back end of the compiler. Use of
this switch also causes the default for front end warnings to be set
to suppress (as though @option{-gnatws} had appeared at the start of
-the options.
+the options).
@end table
@item -^gnatl^OUTPUT_FILE^=file
@cindex @option{^-gnatl^OUTPUT_FILE^=fname} (@command{gcc})
-This has the same effect as @code{-gnatl} except that the output is
+This has the same effect as @option{-gnatl} except that the output is
written to a file instead of to standard output. If the given name
@file{fname} does not start with a period, then it is the full name
of the file to be written. If @file{fname} is an extension, it is
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
+range of 1 to 999999 and limits the number of error or warning
+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
+fatal error: maximum number of errors detected
compilation abandoned
@end smallexample
@noindent
+The default setting if
+no switch is given is 9999. If the number of warnings reaches this
+limit, then a message is output and further warnings are suppressed,
+but the compilation is continued. If the number of error messages
+reaches this limit, then a message is output and the compilation
+is abandoned. A value of zero means that no limit applies.
+
+@noindent
Note that the equal sign is optional, so the switches
@option{-gnatm2} and @option{-gnatm=2} are equivalent.
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
+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.
The following section lists compiler switches that are available
to control the handling of warning messages. It is also possible
to exercise much finer control over what warnings are issued and
-suppressed using the GNAT pragma Warnings, which is documented
-in the GNAT Reference manual.
+suppressed using the GNAT pragma Warnings, @xref{Pragma Warnings,,,
+gnat_rm, GNAT Reference manual}.
@table @option
@c !sort!
This switch suppresses warnings for static fixed-point expressions whose
value is not an exact multiple of Small.
+@item -gnatw.b
+@emph{Activate warnings on biased representation.}
+@cindex @option{-gnatw.b} (@command{gcc})
+@cindex Biased representation
+This switch activates warnings when a size clause, value size clause, component
+clause, or component size clause forces the use of biased representation for an
+integer type (e.g. representing a range of 10..11 in a single bit by using 0/1
+to represent 10/11). The default is that such warnings are generated.
+
+@item -gnatw.B
+@emph{Suppress warnings on biased representation.}
+@cindex @option{-gnatwB} (@command{gcc})
+This switch suppresses warnings for representation clauses that force the use
+of biased representation.
+
@item -gnatwc
@emph{Activate warnings on conditionals.}
@cindex @option{-gnatwc} (@command{gcc})
The warning string still appears, but the warning messages are counted
as errors, and prevent the generation of an object file.
+@item -gnatw.e
+@emph{Activate every optional warning}
+@cindex @option{-gnatw.e} (@command{gcc})
+@cindex Warnings, activate every optional warning
+This switch activates all optional warnings, including those which
+are not activated by @code{-gnatwa}.
+
@item -gnatwf
@emph{Activate warnings on unreferenced formals.}
@cindex @option{-gnatwf} (@command{gcc})
This switch disables warnings on variables that could be declared constants.
@item -gnatwl
-@emph{Activate warnings for missing elaboration pragmas.}
+@emph{Activate warnings for elaboration pragmas.}
@cindex @option{-gnatwl} (@command{gcc})
@cindex Elaboration, warnings
This switch activates warnings on missing
@code{Elaborate_All} and @code{Elaborate} pragmas.
See the section in this guide on elaboration checking for details on
-when such pragmas should be used. Warnings are also generated if you
+when such pragmas should be used. In dynamic elaboration mode, this switch
+generations warnings about the need to add elaboration pragmas. Note however,
+that if you blindly follow these warnings, and add @code{Elaborate_All}
+warnings wherever they are recommended, you basically end up with the
+equivalent of the static elaboration model, which may not be what you want for
+legacy code for which the static model does not work.
+
+For the static model, the messages generated are labeled "info:" (for
+information messages). They are not warnings to add elaboration pragmas,
+merely informational messages showing what implicit elaboration pragmas
+have been added, for use in analyzing elaboration circularity problems.
+
+Warnings are also generated if you
are using the static mode of elaboration, and a @code{pragma Elaborate}
is encountered. The default is that such warnings
are not generated.
This warning is not automatically turned on by the use of @option{-gnatwa}.
@item -gnatwL
-@emph{Suppress warnings for missing elaboration pragmas.}
+@emph{Suppress warnings for elaboration pragmas.}
@cindex @option{-gnatwL} (@command{gcc})
This switch suppresses warnings on missing Elaborate and Elaborate_All pragmas.
See the section in this guide on elaboration checking for details on
@cindex @option{-gnatw.o} (@command{gcc})
This switch activates warnings for variables that are modified by using
them as actuals for a call to a procedure with an out mode formal, where
-the resulting assigned value is never read.
+the resulting assigned value is never read. It is applicable in the case
+where there is more than one out mode formal. If there is only one out
+mode formal, the warning is issued by default (controlled by -gnatwu).
The warning is suppressed for volatile
variables and also for variables that are renamings of other variables
or for which an address clause is given.
inlining mechanism cannot inline a call, it will simply ignore the
request silently.
+@item -gnatw.p
+@emph{Activate warnings on parameter ordering.}
+@cindex @option{-gnatw.p} (@command{gcc})
+@cindex Parameter order, warnings
+This switch activates warnings for cases of suspicious parameter
+ordering when the list of arguments are all simple identifiers that
+match the names of the formals, but are in a different order. The
+warning is suppressed if any use of named parameter notation is used,
+so this is the appropriate way to suppress a false positive (and
+serves to emphasize that the "misordering" is deliberate). The
+default is
+that such warnings are not given.
+This warning can also be turned on using @option{-gnatwa}.
+
+@item -gnatw.P
+@emph{Suppress warnings on parameter ordering.}
+@cindex @option{-gnatw.P} (@command{gcc})
+This switch suppresses warnings on cases of suspicious parameter
+ordering.
+
@item -gnatwq
@emph{Activate warnings on questionable missing parentheses.}
@cindex @option{-gnatwq} (@command{gcc})
@item -gnatwW
@emph{Suppress warnings on wrong low bound assumption.}
@cindex @option{-gnatwW} (@command{gcc})
-This switch activates warnings for indexing an unconstrained string parameter
-with a literal or S'Length. This warning can also be suppressed by providing
-an Assert pragma that checks the low bound, for example:
+This switch suppresses warnings for indexing an unconstrained string parameter
+with a literal or S'Length. Note that this warning can also be suppressed
+in a particular case by adding an
+assertion that the lower bound is 1,
+as shown in the following example.
@smallexample @c ada
procedure K (S : String) is
pragma Assert (S'First = 1);
- ...
+ @dots{}
@end smallexample
+@item -gnatw.w
+@emph{Activate warnings on unnecessary Warnings Off pragmas}
+@cindex @option{-gnatw.w} (@command{gcc})
+@cindex Warnings Off control
+This switch activates warnings for use of @code{pragma Warnings (Off, entity}
+where either the pragma is entirely useless (because it suppresses no
+warnings), or it could be replaced by @code{pragma Unreferenced} or
+@code{pragma Unmodified}.The default is that these warnings are not given.
+Note that this warning is not included in -gnatwa, it must be
+activated explicitly.
+
+@item -gnatw.W
+@emph{Suppress warnings on unnecessary Warnings Off pragmas}
+@cindex @option{-gnatw.W} (@command{gcc})
+This switch suppresses warnings for use of @code{pragma Warnings (Off, entity}.
+
@item -gnatwx
@emph{Activate warnings on Export/Import pragmas.}
@cindex @option{-gnatwx} (@command{gcc})
This switch activates warnings for unchecked conversions
where the types are known at compile time to have different
sizes. The default
-is that such warnings are generated.
+is that such warnings are generated. Warnings are also
+generated for subprogram pointers with different conventions,
+and, on VMS only, for data pointers with different conventions.
This warning can also be turned on using @option{-gnatwa}.
@item -gnatwZ
@cindex @option{-gnatwZ} (@command{gcc})
This switch suppresses warnings for unchecked conversions
where the types are known at compile time to have different
-sizes.
+sizes or conventions.
+
+@item ^-Wunused^WARNINGS=UNUSED^
+@cindex @option{-Wunused}
+The warnings controlled by the @option{-gnatw} switch are generated by
+the front end of the compiler. The @option{GCC} back end can provide
+additional warnings and they are controlled by the @option{-W} switch.
+For example, @option{^-Wunused^WARNINGS=UNUSED^} activates back end
+warnings for entities that are declared but not referenced.
@item ^-Wuninitialized^WARNINGS=UNINITIALIZED^
@cindex @option{-Wuninitialized}
-The warnings controlled by the @option{-gnatw} switch are generated by the
-front end of the compiler. In some cases, the @option{^gcc^GCC^} back end
-can provide additional warnings. One such useful warning is provided by
-@option{^-Wuninitialized^WARNINGS=UNINITIALIZED^}. This must be used in
-conjunction with turning on optimization mode. This causes the flow
-analysis circuits of the back end optimizer to output additional
-warnings about uninitialized variables.
+Similarly, @option{^-Wuninitialized^WARNINGS=UNINITIALIZED^} activates
+the back end warning for uninitialized variables. This switch must be
+used in conjunction with an optimization level greater than zero.
+
+@item ^-Wall^/ALL_BACK_END_WARNINGS^
+@cindex @option{-Wall}
+This switch enables all the above warnings from the @option{GCC} back end.
+The code generator detects a number of warning situations that are missed
+by the @option{GNAT} front end, and this switch can be used to activate them.
+The use of this switch also sets the default front end warning mode to
+@option{-gnatwa}, that is, most front end warnings activated as well.
@item ^-w^/NO_BACK_END_WARNINGS^
@cindex @option{-w}
-This switch suppresses warnings from the @option{^gcc^GCC^} back end. The
-code generator detects a number of warning situations that are missed
-by the @option{GNAT} front end, and this switch can be used to suppress them.
+Conversely, this switch suppresses warnings from the @option{GCC} back end.
The use of this switch also sets the default front end warning mode to
@option{-gnatws}, that is, front end warnings suppressed as well.
@smallexample
@cartouche
- @b{pragma} Assert (@var{Boolean-expression} [,
- @var{static-string-expression}])
+ @b{pragma} Assert (@var{Boolean-expression} @r{[},
+ @var{static-string-expression}@r{]})
@b{pragma} Debug (@var{procedure call})
@end cartouche
@end smallexample
debugging procedures to be called between declarations.
@ifset vms
-@item /DEBUG[=debug-level]
+@item /DEBUG@r{[}=debug-level@r{]}
@itemx /NODEBUG
Specifies how much debugging information is to be included in
the resulting object file where 'debug-level' is one of the following:
and subscripts on the left hand side (where memory corruption could
occur as a result of an invalid value).
+The @option{-gnatB} switch tells the compiler to assume that all
+values are valid (that is, within their declared subtype range)
+except in the context of a use of the Valid attribute. This means
+the compiler can generate more efficient code, since the range
+of values is better known at compile time.
+
The @option{-gnatV^@var{x}^^} switch allows more control over the validity
checking mode.
@ifclear vms
@cindex @option{-gnatVf} (@command{gcc})
In the absence of this switch, validity checking occurs only for discrete
values. If @option{-gnatVf} is specified, then validity checking also applies
-for floating-point values, and NaN's and infinities are considered invalid,
+for floating-point values, and NaNs and infinities are considered invalid,
as well as out of range values for constrained types. Note that this means
-that standard @code{IEEE} infinity mode is not allowed. The exact contexts
+that standard IEEE infinity mode is not allowed. The exact contexts
in which floating-point values are checked depends on the setting of other
options. For example,
@option{^-gnatVif^VALIDITY_CHECKING=(IN_PARAMS,FLOATS)^} or
and operands for attributes such as @code{Pos}. Checks are also made
on individual component values for composite comparisons, and on the
expressions in type conversions and qualified expressions. Checks are
-also made on explicit ranges using .. (e.g. slices, loops etc).
+also made on explicit ranges using @samp{..} (e.g.@: slices, loops etc).
@item -gnatVp
@emph{Validity checks for parameters.}
checking of @code{@b{in out}} procedure arguments.
The specification of additional validity checking generates extra code (and
-in the case of @option{-gnatVa} the code expansion can be substantial.
+in the case of @option{-gnatVa} the code expansion can be substantial).
However, these additional checks can be very useful in detecting
uninitialized variables, incorrect use of unchecked conversion, and other
errors leading to invalid values. The use of pragma @code{Initialize_Scalars}
@findex Style checking
@noindent
-The @option{-gnaty^x^(option,option,...)^} switch
+The @option{-gnaty^x^(option,option,@dots{})^} switch
@cindex @option{-gnaty} (@command{gcc})
causes the compiler to
enforce specified style rules. A limited set of style rules has been used
specified style check, an appropriate warning message is given, preceded by
the character sequence ``(style)''.
@ifset vms
-@code{(option,option,...)} is a sequence of keywords
+@code{(option,option,@dots{})} is a sequence of keywords
@end ifset
@ifclear vms
The string @var{x} is a sequence of letters or digits
@table @option
@c !sort!
-@item 1-9
+@item 0-9
@emph{Specify indentation level.}
If a digit from 1-9 appears
^in the string after @option{-gnaty}^as an option for /STYLE_CHECKS^
then proper indentation is checked, with the digit indicating the
-indentation level required.
+indentation level required. A value of zero turns off this style check.
The general style of required indentation is as specified by
the examples in the Ada Reference Manual. Full line comments must be
aligned with the @code{--} starting on a column that is a multiple of
@item ^a^ATTRIBUTE^
@emph{Check attribute casing.}
-If the ^letter a^word ATTRIBUTE^ appears in the string after @option{-gnaty}
-then attribute names, including the case of keywords such as @code{digits}
+Attribute names, including the case of keywords such as @code{digits}
used as attributes names, must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
@item ^A^ARRAY_INDEXES^
@emph{Use of array index numbers in array attributes.}
-If the ^letter A^word ARRAY_INDEXES^ appears in the string after
-@option{-gnaty} then when using the array attributes First, Last, Range,
+When using the array attributes First, Last, Range,
or Length, the index number must be omitted for one-dimensional arrays
and is required for multi-dimensional arrays.
@item ^b^BLANKS^
@emph{Blanks not allowed at statement end.}
-If the ^letter b^word BLANKS^ appears in the string after @option{-gnaty} then
-trailing blanks are not allowed at the end of statements. The purpose of this
+Trailing blanks are not allowed at the end of statements. The purpose of this
rule, together with h (no horizontal tabs), is to enforce a canonical format
for the use of blanks to separate source tokens.
@item ^c^COMMENTS^
@emph{Check comments.}
-If the ^letter c^word COMMENTS^ appears in the string after @option{-gnaty}
-then comments must meet the following set of rules:
+Comments must meet the following set of rules:
@itemize @bullet
annotation
language (where ``@code{--#}'' is used). For the purposes of this rule, a
special character is defined as being in one of the ASCII ranges
-@code{16#21#..16#2F#} or @code{16#3A#..16#3F#}.
+@code{16#21#@dots{}16#2F#} or @code{16#3A#@dots{}16#3F#}.
Note that this usage is not permitted
-in GNAT implementation units (i.e. when @option{-gnatg} is used).
+in GNAT implementation units (i.e., when @option{-gnatg} is used).
@item
A line consisting entirely of minus signs, possibly preceded by blanks, is
@item ^d^DOS_LINE_ENDINGS^
@emph{Check no DOS line terminators present.}
-If the ^letter d^word DOS_LINE_ENDINGS^ appears in the string after
-@option{-gnaty} then all lines must be terminated by a single ASCII.LF
+All lines must be terminated by a single ASCII.LF
character (in particular the DOS line terminator sequence CR/LF is not
allowed).
@item ^e^END^
@emph{Check end/exit labels.}
-If the ^letter e^word END^ appears in the string after @option{-gnaty} then
-optional labels on @code{end} statements ending subprograms and on
+Optional labels on @code{end} statements ending subprograms and on
@code{exit} statements exiting named loops, are required to be present.
@item ^f^VTABS^
@emph{No form feeds or vertical tabs.}
-If the ^letter f^word VTABS^ appears in the string after @option{-gnaty} then
-neither form feeds nor vertical tab characters are permitted
+Neither form feeds nor vertical tab characters are permitted
in the source text.
@item ^g^GNAT^
@emph{GNAT style mode}
-If the ^letter g^word GNAT^ appears in the string after @option{-gnaty} then
-the set of style check switches is set to match that used by the GNAT sources.
+The set of style check switches is set to match that used by the GNAT sources.
This may be useful when developing code that is eventually intended to be
incorporated into GNAT. For further details, see GNAT sources.
@item ^h^HTABS^
@emph{No horizontal tabs.}
-If the ^letter h^word HTABS^ appears in the string after @option{-gnaty} then
-horizontal tab characters are not permitted in the source text.
+Horizontal tab characters are not permitted in the source text.
Together with the b (no blanks at end of line) check, this
enforces a canonical form for the use of blanks to separate
source tokens.
@item ^i^IF_THEN^
@emph{Check if-then layout.}
-If the ^letter i^word IF_THEN^ appears in the string after @option{-gnaty},
-then the keyword @code{then} must appear either on the same
+The keyword @code{then} must appear either on the same
line as corresponding @code{if}, or on a line on its own, lined
up under the @code{if} with at least one non-blank line in between
containing all or part of the condition to be tested.
@item ^I^IN_MODE^
@emph{check mode IN keywords}
-If the ^letter I (upper case)^word IN_MODE^ appears in the string
-after @option{-gnaty} then mode @code{in} (the default mode) is not
+Mode @code{in} (the default mode) is not
allowed to be given explicitly. @code{in out} is fine,
but not @code{in} on its own.
@item ^k^KEYWORD^
@emph{Check keyword casing.}
-If the ^letter k^word KEYWORD^ appears in the string after @option{-gnaty} then
-all keywords must be in lower case (with the exception of keywords
+All keywords must be in lower case (with the exception of keywords
such as @code{digits} used as attribute names to which this check
does not apply).
@item ^l^LAYOUT^
@emph{Check layout.}
-If the ^letter l^word LAYOUT^ appears in the string after @option{-gnaty} then
-layout of statement and declaration constructs must follow the
+Layout of statement and declaration constructs must follow the
recommendations in the Ada Reference Manual, as indicated by the
form of the syntax rules. For example an @code{else} keyword must
be lined up with the corresponding @code{if} keyword.
@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.
+The maximum level of nesting of constructs (including subprograms, loops,
+blocks, packages, and conditionals) may not exceed the given value
+@option{nnn}. A value of zero disconnects this style check.
@item ^m^LINE_LENGTH^
@emph{Check maximum line length.}
-If the ^letter m^word LINE_LENGTH^ appears in the string after @option{-gnaty}
-then the length of source lines must not exceed 79 characters, including
+The length of source lines must not exceed 79 characters, including
any trailing blanks. The value of 79 allows convenient display on an
80 character wide device or window, allowing for possible special
treatment of 80 character lines. Note that this count is of
@item ^Mnnn^MAX_LENGTH=nnn^
@emph{Set maximum line length.}
-If the sequence ^M^MAX_LENGTH=^nnn, where nnn is a decimal number, appears in
-the string after @option{-gnaty} then the length of lines must not exceed the
-given value. The maximum value that can be specified is 32767.
+The length of lines must not exceed the
+given value @option{nnn}. The maximum value that can be specified is 32767.
@item ^n^STANDARD_CASING^
@emph{Check casing of entities in Standard.}
-If the ^letter n^word STANDARD_CASING^ appears in the string
-after @option{-gnaty} then any identifier from Standard must be cased
+Any identifier from Standard must be cased
to match the presentation in the Ada Reference Manual (for example,
@code{Integer} and @code{ASCII.NUL}).
+@item ^N^NONE^
+@emph{Turn off all style checks}
+All style check options are turned off.
+
@item ^o^ORDERED_SUBPROGRAMS^
@emph{Check order of subprogram bodies.}
-If the ^letter o^word ORDERED_SUBPROGRAMS^ appears in the string
-after @option{-gnaty} then all subprogram bodies in a given scope
-(e.g. a package body) must be in alphabetical order. The ordering
+All subprogram bodies in a given scope
+(e.g.@: a package body) must be in alphabetical order. The ordering
rule uses normal Ada rules for comparing strings, ignoring casing
of letters, except that if there is a trailing numeric suffix, then
-the value of this suffix is used in the ordering (e.g. Junk2 comes
+the value of this suffix is used in the ordering (e.g.@: Junk2 comes
before Junk10).
+@item ^O^OVERRIDING_INDICATORS^
+@emph{Check that overriding subprograms are explicitly marked as such.}
+The declaration of a primitive operation of a type extension that overrides
+an inherited operation must carry an overriding indicator.
+
@item ^p^PRAGMA^
@emph{Check pragma casing.}
-If the ^letter p^word PRAGMA^ appears in the string after @option{-gnaty} then
-pragma names must be written in mixed case, that is, the
+Pragma names must be written in mixed case, that is, the
initial letter and any letter following an underscore must be uppercase.
All other letters must be lowercase.
@item ^r^REFERENCES^
@emph{Check references.}
-If the ^letter r^word REFERENCES^ appears in the string after @option{-gnaty}
-then all identifier references must be cased in the same way as the
+All identifier references must be cased in the same way as the
corresponding declaration. No specific casing style is imposed on
identifiers. The only requirement is for consistency of references
with declarations.
@item ^S^STATEMENTS_AFTER_THEN_ELSE^
@emph{Check no statements after THEN/ELSE.}
-If the ^letter S^word STATEMENTS_AFTER_THEN_ELSE^ appears in the
-string after @option{-gnaty} then it is not permitted to write any
-statements on the same line as a THEN OR ELSE keyword following the
+No statements are allowed
+on the same line as a THEN or ELSE keyword following the
keyword in an IF statement. OR ELSE and AND THEN are not affected,
and a special exception allows a pragma to appear after ELSE.
@item ^s^SPECS^
@emph{Check separate specs.}
-If the ^letter s^word SPECS^ appears in the string after @option{-gnaty} then
-separate declarations (``specs'') are required for subprograms (a
+Separate declarations (``specs'') are required for subprograms (a
body is not allowed to serve as its own declaration). The only
exception is that parameterless library level procedures are
not required to have a separate declaration. This exception covers
@item ^t^TOKEN^
@emph{Check token spacing.}
-If the ^letter t^word TOKEN^ appears in the string after @option{-gnaty} then
-the following token spacing rules are enforced:
+The following token spacing rules are enforced:
@itemize @bullet
@item ^u^UNNECESSARY_BLANK_LINES^
@emph{Check unnecessary blank lines.}
-Check for unnecessary blank lines. A blank line is considered
+Unnecessary blank lines are not allowed. A blank line is considered
unnecessary if it appears at the end of the file, or if more than
one blank line occurs in sequence.
@item ^x^XTRA_PARENS^
@emph{Check extra parentheses.}
-Check for the use of an unnecessary extra level of parentheses (C-style)
+Unnecessary extra level of parentheses (C-style) are not allowed
around conditions in @code{if} statements, @code{while} statements and
@code{exit} statements.
+@item ^y^ALL_BUILTIN^
+@emph{Set all standard style check options}
+This is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
+options enabled with the exception of @option{-gnatyo}, @option{-gnatyI},
+@option{-gnatyS}, @option{-gnatyLnnn},
+@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
+
+@ifclear vms
+@item -
+@emph{Remove style check options}
+This causes any subsequent options in the string to act as canceling the
+corresponding style check option. To cancel maximum nesting level control,
+use @option{L} parameter witout any integer value after that, because any
+digit following @option{-} in the parameter string of the @option{-gnaty}
+option will be threated as canceling indentation check. The same is true
+for @option{M} parameter. @option{y} and @option{N} parameters are not
+allowed after @option{-}.
+
+@item +
+This causes any subsequent options in the string to enable the corresponding
+style check option. That is, it cancels the effect of a previous ^-^REMOVE^,
+if any.
+@end ifclear
+
+@ifset vms
+@item NOxxx
+@emph{Removing style check options}
+If the name of a style check is preceded by @option{NO} then the corresponding
+style check is turned off. For example @option{NOCOMMENTS} turns off style
+checking for comments.
+@end ifset
@end table
@noindent
The switch
@ifclear vms
@option{-gnaty} on its own (that is not
-followed by any letters or digits),
-is equivalent to @code{gnaty3aAbcefhiklmnprst}, that is all checking
-options enabled with the exception of @option{-gnatyo},
-@option{-gnatyd}, @option{-gnatyu}, and @option{-gnatyx}.
+followed by any letters or digits), then the effect is equivalent
+to the use of @option{-gnatyy}, as described above, that is all
+built-in standard style check options are enabled.
+
@end ifclear
@ifset vms
/STYLE_CHECKS=ALL_BUILTIN enables all checking options with
the exception of ORDERED_SUBPROGRAMS, UNNECESSARY_BLANK_LINES,
XTRA_PARENS, and DOS_LINE_ENDINGS. In addition
@end ifset
-an indentation level of 3 is set. This is similar to the standard
-checking option that is used for the GNAT sources.
+
+
The switch
@ifclear vms
@cindex Checks, stack overflow checking
@noindent
-If you compile with the default options, GNAT will insert many run-time
-checks into the compiled code, including code that performs range
-checking against constraints, but not arithmetic overflow checking for
-integer operations (including division by zero), checks for access
-before elaboration on subprogram calls, or stack overflow checking. All
-other run-time checks, as required by the Ada Reference Manual, are
-generated by default. The following @command{gcc} switches refine this
-default behavior:
+By default, the following checks are suppressed: integer overflow
+checks, stack overflow checks, and checks for access before
+elaboration on subprogram calls. All other checks, including range
+checks and array bounds checks, are turned on by default. The
+following @command{gcc} switches refine this default behavior.
@table @option
@c !sort!
@cindex Suppressing checks
@cindex Checks, suppressing
@findex Suppress
-Suppress all run-time checks as though @code{pragma Suppress (all_checks})
+Suppress all run-time checks as though @code{pragma Suppress (All_checks)}
had been present in the source. Validity checks are also suppressed (in
other words @option{-gnatp} also implies @option{-gnatVn}.
Use this switch to improve the performance
of the code at the expense of safety in the presence of invalid data or
program bugs.
+Note that when checks are suppressed, the compiler is allowed, but not
+required, to omit the checking code. If the run-time cost of the
+checking code is zero or near-zero, the compiler will generate it even
+if checks are suppressed. In particular, if the compiler can prove
+that a certain check will necessarily fail, it will generate code to
+do an unconditional ``raise'', even if checks are suppressed. The
+compiler warns in this case.
+
+Of course, run-time checks are omitted whenever the compiler can prove
+that they will not fail, whether or not checks are suppressed.
+
+Note that if you suppress a check that would have failed, program
+execution is erroneous, which means the behavior is totally
+unpredictable. The program might crash, or print wrong answers, or
+do anything else. It might even do exactly what you wanted it to do
+(and then it might start failing mysteriously next week or next
+year). The compiler will generate code based on the assumption that
+the condition being checked is true, which can result in disaster if
+that assumption is wrong.
+
@item -gnato
@cindex @option{-gnato} (@command{gcc})
@cindex Overflow checks
range of the result type. The following example shows the distinction:
@smallexample @c ada
-X1 : Integer := Integer'Last;
-X2 : Integer range 1 .. 5 := 5;
-X3 : Integer := Integer'Last;
-X4 : Integer range 1 .. 5 := 5;
-F : Float := 2.0E+20;
-...
+X1 : Integer := "Integer'Last";
+X2 : Integer range 1 .. 5 := "5";
+X3 : Integer := "Integer'Last";
+X4 : Integer range 1 .. 5 := "5";
+F : Float := "2.0E+20";
+@dots{}
X1 := X1 + 1;
X2 := X2 + 1;
X3 := Integer (F);
@end smallexample
@noindent
+Note that if explicit values are assigned at compile time, the
+compiler may be able to detect overflow at compile time, in which case
+no actual run-time checking code is required, and Constraint_Error
+will be raised unconditionally, with or without
+@option{-gnato}. That's why the assigned values in the above fragment
+are in quotes, the meaning is "assign a value not known to the
+compiler that happens to be equal to ...". The remaining discussion
+assumes that the compiler cannot detect the values at compile time.
+
Here the first addition results in a value that is outside the base range
of Integer, and hence requires an overflow check for detection of the
constraint error. Thus the first assignment to @code{X1} raises a
@code{Constraint_Error} exception only if @option{-gnato} is set.
-The second increment operation results in a violation
-of the explicit range constraint, and such range checks are always
-performed (unless specifically suppressed with a pragma @code{suppress}
-or the use of @option{-gnatp}).
+The second increment operation results in a violation of the explicit
+range constraint; such range checks are performed by default, and are
+unaffected by @option{-gnato}.
The two conversions of @code{F} both result in values that are outside
the base range of type @code{Integer} and thus will raise
(such as dividing 0.0 by 0.0).
The reason that we distinguish overflow checking from other kinds of
-range constraint checking is that a failure of an overflow check can
-generate an incorrect value, but cannot cause erroneous behavior. This
-is unlike the situation with a constraint check on an array subscript,
-where failure to perform the check can result in random memory description,
-or the range check on a case statement, where failure to perform the check
-can cause a wild jump.
+range constraint checking is that a failure of an overflow check, unlike
+for example the failure of a range check, can result in an incorrect
+value, but cannot cause random memory destruction (like an out of range
+subscript), or a wild jump (from an out of range case value). Overflow
+checking is also quite expensive in time and space, since in general it
+requires the use of double length arithmetic.
Note again that @option{-gnato} is off by default, so overflow checking is
not performed in default mode. This means that out of the box, with the
@cindex Check, elaboration
Enables dynamic checks for access-before-elaboration
on subprogram calls and generic instantiations.
+Note that @option{-gnatE} is not necessary for safety, because in the
+default mode, GNAT ensures statically that the checks would not fail.
For full details of the effect and use of this switch,
@xref{Compiling Using gcc}.
methods see @ref{Wide Character Encodings}.
Note that brackets coding is always accepted, even if one of the other
options is specified, so for example @option{-gnatW8} specifies that both
-brackets and @code{UTF-8} encodings will be recognized. The units that are
+brackets and UTF-8 encodings will be recognized. The units that are
with'ed directly or indirectly will be scanned using the specified
representation scheme, and so if one of the non-brackets scheme is
used, it must be used consistently throughout the program. However,
@item -gnatN
@cindex @option{-gnatN} (@command{gcc})
-The front end inlining activated by this switch is generally more extensive,
-and quite often more effective than the standard @option{-gnatn} inlining mode.
-It will also generate additional dependencies.
-Note that
-@option{-gnatN} automatically implies @option{-gnatn} so it is not necessary
-to specify both options.
+This switch activates front-end inlining which also
+generates additional dependencies.
+
+When using a gcc-based back end (in practice this means using any version
+of GNAT other than the JGNAT, .NET or GNAAMP versions), then the use of
+@option{-gnatN} is deprecated, and the use of @option{-gnatn} is preferred.
+Historically front end inlining was more extensive than the gcc back end
+inlining, but that is no longer the case.
@end table
@node Auxiliary Output Control
file @file{debug.adb}.
@end ifclear
-@item -gnatG
+@item -gnatG[=nn]
@cindex @option{-gnatG} (@command{gcc})
This switch causes the compiler to generate auxiliary output containing
a pseudo-source listing of the generated expanded code. Like most Ada
is to list this expanded code in a form very close to normal Ada source.
This is very useful in understanding the implications of various Ada
usage on the efficiency of the generated code. There are many cases in
-Ada (e.g. the use of controlled types), where simple Ada statements can
+Ada (e.g.@: the use of controlled types), where simple Ada statements can
generate a lot of run-time code. By using @option{-gnatG} you can identify
these cases, and consider whether it may be desirable to modify the coding
approach to improve efficiency.
+The optional parameter @code{nn} if present after -gnatG specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+
The format of the output is very similar to standard Ada source, and is
easily understood by an Ada programmer. The following special syntactic
additions correspond to low level features used in the generated code that
do not have any exact analogies in pure Ada source form. The following
-is a partial list of these special constructions. See the specification
+is a partial list of these special constructions. See the spec
of package @code{Sprint} in file @file{sprint.ads} for a full list.
If the switch @option{-gnatL} is used in conjunction with
in the expanded source (as comment lines with the original line number).
@table @code
-@item new @var{xxx} [storage_pool = @var{yyy}]
+@item new @var{xxx} @r{[}storage_pool = @var{yyy}@r{]}
Shows the storage pool being used for an allocator.
@item at end @var{procedure-name};
A division or multiplication of fixed-point values which are treated as
integers without any kind of scaling.
-@item free @var{expr} [storage_pool = @var{xxx}]
+@item free @var{expr} @r{[}storage_pool = @var{xxx}@r{]}
Shows the storage pool associated with a @code{free} statement.
@item [subtype or type declaration]
Used to list an equivalent declaration for an internally generated
type that is referenced elsewhere in the listing.
-@item freeze @var{type-name} [@var{actions}]
+@item freeze @var{type-name} @ovar{actions}
Shows the point at which @var{type-name} is frozen, with possible
associated actions to be performed at the freeze point.
(to meet the requirement of H.3.1(9) in a
convenient manner).
-@item @var{expr} && @var{expr} && @var{expr} ... && @var{expr}
+@item @var{expr} && @var{expr} && @var{expr} @dots{} && @var{expr}
A multiple concatenation (same effect as @var{expr} & @var{expr} &
@var{expr}, but handled more efficiently).
evaluation of the expression 1.0/27.0).
@end table
-@item -gnatD
+@item -gnatD[=nn]
@cindex @option{-gnatD} (@command{gcc})
When used in conjunction with @option{-gnatG}, this switch causes
the expanded source, as described above for
@option{-gnatDG}, then the original source lines are interspersed
in the expanded source (as comment lines with the original line number).
+The optional parameter @code{nn} if present after -gnatD specifies an
+alternative maximum line length that overrides the normal default of 72.
+This value is in the range 40-999999, values less than 40 being silently
+reset to 40. The equal sign is optional.
+
+@item -gnatr
+@cindex @option{-gnatr} (@command{gcc})
+@cindex pragma Restrictions
+This switch causes pragma Restrictions to be treated as Restriction_Warnings
+so that violation of restrictions causes warnings rather than illegalities.
+This is useful during the development process when new restrictions are added
+or investigated. The switch also causes pragma Profile to be treated as
+Profile_Warnings, and pragma Restricted_Run_Time and pragma Ravenscar set
+restriction warnings rather than restrictions.
+
@ifclear vms
-@item -gnatR[0|1|2|3[s]]
+@item -gnatR@r{[}0@r{|}1@r{|}2@r{|}3@r{[}s@r{]]}
@cindex @option{-gnatR} (@command{gcc})
This switch controls output from the compiler of a listing showing
representation information for declared types and objects. For
so @option{-gnatR} with no parameter has the same effect), size and alignment
information is listed for declared array and record types. For
@option{-gnatR2}, size and alignment information is listed for all
-declared types and objects. Finally @code{-gnatR3} includes symbolic
+declared types and objects. Finally @option{-gnatR3} includes symbolic
expressions for values that are computed at run time for
variant records. These symbolic expressions have a mostly obvious
format with #n being used to represent the value of the n'th
discriminant. See source files @file{repinfo.ads/adb} in the
@code{GNAT} sources for full details on the format of @option{-gnatR3}
-output. If the switch is followed by an s (e.g. @option{-gnatR2s}), then
+output. If the switch is followed by an s (e.g.@: @option{-gnatR2s}), then
the output is to a file with the name @file{^file.rep^file_REP^} where
file is the name of the corresponding source file.
@end ifclear
@code{GNAT} sources for full details on the format of
@option{/REPRESENTATION_INFO=SYMBOLIC} output.
If _FILE is added at the end of an option
-(e.g. @option{/REPRESENTATION_INFO=ARRAYS_FILE}),
+(e.g.@: @option{/REPRESENTATION_INFO=ARRAYS_FILE}),
then the output is to a file with the name @file{file_REP} where
file is the name of the corresponding source file.
@end ifset
A mapping file is a sequence of sets of three lines. In each set,
the first line is the unit name, in lower case, with ``@code{%s}''
appended for
-specifications and ``@code{%b}'' appended for bodies; the second line is the
+specs and ``@code{%b}'' appended for bodies; the second line is the
file name; and the third line is the path name.
Example:
When the switch @option{-gnatem} is specified, the compiler will create
in memory the two mappings from the specified file. If there is any problem
-(non existent file, truncated file or duplicate entries), no mapping
-will be created.
+(nonexistent file, truncated file or duplicate entries), no mapping will
+be created.
Several @option{-gnatem} switches may be specified; however, only the last
one on the command line will be taken into account.
@noindent
A preprocessing data file is a text file with significant lines indicating
how should be preprocessed either a specific source or all sources not
-mentioned in other lines. A significant line is a non empty, non comment line.
+mentioned in other lines. A significant line is a nonempty, non-comment line.
Comments are similar to Ada comments.
@noindent
-- list all symbols with their values.
@end smallexample
-@item ^-gnateD^/DATA_PREPROCESSING=^symbol[=value]
+@item ^-gnateD^/DATA_PREPROCESSING=^symbol@r{[}=value@r{]}
@cindex @option{-gnateD} (@command{gcc})
Define or redefine a preprocessing symbol, associated with value. If no value
is given on the command line, then the value of the symbol is @code{True}.
@noindent
This switch is similar to switch @option{^-D^/ASSOCIATE^} of @code{gnatprep}.
+@item -gnateG
+When integrated preprocessing is performed and the preprocessor modifies
+the source text, write the result of this preprocessing into a file
+<source>^.prep^_prep^.
+
@end table
@node Code Generation Control
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.
+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
+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.
@noindent
On VMS, GNAT compiled programs return POSIX-style codes by default,
-e.g. @option{/RETURN_CODES=POSIX}.
+e.g.@: @option{/RETURN_CODES=POSIX}.
To enable VMS style return codes, use GNAT BIND and LINK with the option
@option{/RETURN_CODES=VMS}. For example:
@item
@findex ADA_PRJ_INCLUDE_FILE
Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
+by the @env{ADA_PRJ_INCLUDE_FILE} ^environment variable^logical name^.
@noindent
-@code{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
+@env{ADA_PRJ_INCLUDE_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
driver when project files are used. It should not normally be set
by other means.
@item
@findex ADA_INCLUDE_PATH
Each of the directories listed in the value of the
-@code{ADA_INCLUDE_PATH} ^environment variable^logical name^.
+@env{ADA_INCLUDE_PATH} ^environment variable^logical name^.
@ifclear vms
Construct this value
-exactly as the @code{PATH} environment variable: a list of directory
+exactly as the @env{PATH} environment variable: a list of directory
names separated by colons (semicolons when working with the NT version).
@end ifclear
@ifset vms
In addition to the language-defined hierarchies (@code{System}, @code{Ada} and
@code{Interfaces}), the GNAT distribution provides a fourth hierarchy,
consisting of child units of @code{GNAT}. This is a collection of generally
-useful types, subprograms, etc. See the @cite{GNAT Reference Manual} for
-further details.
+useful types, subprograms, etc. @xref{Top, GNAT Reference Manual, About
+This Guid, gnat_rm, GNAT Reference Manual}, for further details.
Besides simplifying access to the RTL, a major use of search paths is
in compiling sources from multiple directories. This can make
The form of the @code{gnatbind} command is
@smallexample
-$ gnatbind [@i{switches}] @i{mainprog}[.ali] [@i{switches}]
+$ gnatbind @ovar{switches} @var{mainprog}@r{[}.ali@r{]} @ovar{switches}
@end smallexample
@noindent
-where @file{@i{mainprog}.adb} is the Ada file containing the main program
+where @file{@var{mainprog}.adb} is the Ada file containing the main program
unit body. If no switches are specified, @code{gnatbind} constructs an Ada
package in two files whose names are
-@file{b~@i{mainprog}.ads}, and @file{b~@i{mainprog}.adb}.
+@file{b~@var{mainprog}.ads}, and @file{b~@var{mainprog}.adb}.
For example, if given the
parameter @file{hello.ali}, for a main program contained in file
@file{hello.adb}, the binder output files would be @file{b~hello.ads}
@cindex @option{^-C^/BIND_FILE=C^} (@command{gnatbind})
Generate binder program in C
-@item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}[k|m]
-@cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}[k|m]} (@command{gnatbind})
+@item ^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}
+@cindex @option{^-d^/DEFAULT_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}} (@command{gnatbind})
This switch can be used to change the default task stack size value
to a specified size @var{nn}, which is expressed in bytes by default, or
in kilobytes when suffixed with @var{k} or in megabytes when suffixed
with @var{m}.
-In the absence of a [k|m] suffix, this switch is equivalent, in effect,
-to completing all task specs with
+In the absence of a @samp{@r{[}k@r{|}m@r{]}} suffix, this switch is equivalent,
+in effect, to completing all task specs with
@smallexample @c ada
pragma Storage_Size (nn);
@end smallexample
When they do not already have such a pragma.
-@item ^-D^/DEFAULT_SECONDARY_STACK_SIZE=^@var{nn}[k|m]
+@item ^-D^/DEFAULT_SECONDARY_STACK_SIZE=^@var{nn}@r{[}k@r{|}m@r{]}
@cindex @option{^-D^/DEFAULT_SECONDARY_STACK_SIZE=nnnnn^} (@command{gnatbind})
This switch can be used to change the default secondary stack size value
to a specified size @var{nn}, which is expressed in bytes by default, or
@cindex @option{^-l^/ORDER_OF_ELABORATION^} (@command{gnatbind})
Output chosen elaboration order.
-@item ^-Lxxx^/BUILD_LIBRARY=xxx^
+@item ^-L@var{xxx}^/BUILD_LIBRARY=@var{xxx}^
@cindex @option{^-L^/BUILD_LIBRARY^} (@command{gnatbind})
Bind the units for library building. In this case the adainit and
adafinal procedures (@pxref{Binding with Non-Ada Main Programs})
-are renamed to ^xxxinit^XXXINIT^ and
-^xxxfinal^XXXFINAL^.
+are renamed to ^@var{xxx}init^@var{XXX}INIT^ and
+^@var{xxx}final^@var{XXX}FINAL^.
Implies ^-n^/NOCOMPILE^.
@ifclear vms
(@xref{GNAT and Libraries}, for more details.)
@item ^-m^/ERROR_LIMIT=^@var{n}
@cindex @option{^-m^/ERROR_LIMIT^} (@command{gnatbind})
-Limit number of detected errors to @var{n}, where @var{n} is
-in the range 1..999_999. The default value if no switch is
-given is 9999. Binding is terminated if the limit is exceeded.
+Limit number of detected errors or warnings to @var{n}, where @var{n} is
+in the range 1..999999. The default value if no switch is
+given is 9999. If the number of warnings reaches this limit, then a
+message is output and further warnings are suppressed, the bind
+continues in this case. If the number of errors reaches this
+limit, then a message is output and the bind is abandoned.
+A value of zero means that no limit is enforced. The equal
+sign is optional.
+
@ifset unw
Furthermore, under Windows, the sources pointed to by the libraries path
set in the registry are not searched for.
@item ``@option{^in^INVALID^}'' requesting an invalid value where possible
@item ``@option{^lo^LOW^}'' for the lowest possible value
@item ``@option{^hi^HIGH^}'' for the highest possible value
-@item ``@option{xx}'' for a value consisting of repeated bytes with the
-value 16#xx# (i.e. xx is a string of two hexadecimal digits).
+@item ``@option{@var{xx}}'' for a value consisting of repeated bytes with the
+value @code{16#@var{xx}#} (i.e., @var{xx} is a string of two hexadecimal digits).
@end itemize
In addition, you can specify @option{-Sev} to indicate that the value is
to be set at run time. In this case, the program will look for an environment
@cindex GNAT_INIT_SCALARS
-variable of the form @code{GNAT_INIT_SCALARS=xx}, where xx is one
-of @option{in/lo/hi/xx} with the same meanings as above.
+variable of the form @env{GNAT_INIT_SCALARS=@var{xx}}, where @var{xx} is one
+of @option{in/lo/hi/@var{xx}} with the same meanings as above.
If no environment variable is found, or if it does not have a valid value,
then the default is @option{in} (invalid values).
file is out of date with respect to the source file. Note that this is the
mode that is automatically used by @command{gnatmake} because in this
case the checking against sources has already been performed by
-@command{gnatmake} in the course of compilation (i.e. before binding).
+@command{gnatmake} in the course of compilation (i.e.@: before binding).
@ifset vms
@item /READ_SOURCES=AVAILABLE
@item
@findex ADA_PRJ_OBJECTS_FILE
Each of the directories listed in the text file whose name is given
-by the @code{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
+by the @env{ADA_PRJ_OBJECTS_FILE} ^environment variable^logical name^.
@noindent
-@code{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
+@env{ADA_PRJ_OBJECTS_FILE} is normally set by gnatmake or by the ^gnat^GNAT^
driver when project files are used. It should not normally be set
by other means.
@item
@findex ADA_OBJECTS_PATH
Each of the directories listed in the value of the
-@code{ADA_OBJECTS_PATH} ^environment variable^logical name^.
+@env{ADA_OBJECTS_PATH} ^environment variable^logical name^.
@ifset unw
Construct this value
-exactly as the @code{PATH} environment variable: a list of directory
+exactly as the @env{PATH} environment variable: a list of directory
names separated by colons (semicolons when working with the NT version
of GNAT).
@end ifset
The form of the @command{gnatlink} command is
@smallexample
-$ gnatlink [@var{switches}] @var{mainprog}[.ali]
- [@var{non-Ada objects}] [@var{linker options}]
+$ gnatlink @ovar{switches} @var{mainprog}@r{[}.ali@r{]}
+ @ovar{non-Ada objects} @ovar{linker options}
@end smallexample
@noindent
@var{linker options} is an optional list of linker specific
switches.
-The default linker called by gnatlink is @var{gcc} which in
+The default linker called by gnatlink is @command{gcc} which in
turn calls the appropriate system linker.
Standard options for the linker such as @option{-lmy_lib} or
@option{-Ldir} can be added as is.
For options that are not recognized by
-@var{gcc} as linker options, use the @var{gcc} switches @option{-Xlinker} or
-@option{-Wl,}.
+@command{gcc} as linker options, use the @command{gcc} switches
+@option{-Xlinker} or @option{-Wl,}.
Refer to the GCC documentation for
details. Here is an example showing how to generate a linker map:
Using @var{linker options} it is possible to set the program stack and
heap size.
-@ifclear vms
+@ifset unw
See @ref{Setting Stack Size from gnatlink} and
@ref{Setting Heap Size from gnatlink}.
-@end ifclear
+@end ifset
@command{gnatlink} determines the list of objects required by the Ada
program and prepends them to the list of objects passed to the linker.
@ifset vms
@command{gnatlink} accepts the following types of extra files on the command
-line: objects (.OBJ), libraries (.OLB), sharable images (.EXE), and
-options files (.OPT). These are recognized and handled according to their
-extension.
+line: objects (@file{.OBJ}), libraries (@file{.OLB}), sharable images
+(@file{.EXE}), and options files (@file{.OPT}). These are recognized and
+handled according to their extension.
@end ifset
@node Switches for gnatlink
@cindex @option{-B} (@command{gnatlink})
Load compiler executables (for example, @code{gnat1}, the Ada compiler)
from @var{dir} instead of the default location. Only use this switch
-when multiple versions of the GNAT compiler are available. See the
-@command{gcc} manual page for further details. You would normally use the
-@option{-b} or @option{-V} switch instead.
+when multiple versions of the GNAT compiler are available.
+@xref{Directory Options,,, gcc, The GNU Compiler Collection},
+for further details. You would normally use the @option{-b} or
+@option{-V} switch instead.
@item --GCC=@var{compiler_name}
@cindex @option{--GCC=compiler_name} (@command{gnatlink})
inserted after your command name. Thus in the above example the compiler
command that will be used by @command{gnatlink} will be @code{foo -c -x -y}.
A limitation of this syntax is that the name and path name of the executable
-itself must not include any embedded spaces. If several
+itself must not include any embedded spaces. If the compiler executable is
+different from the default one (gcc or <prefix>-gcc), then the back-end
+switches in the ALI file are not used to compile the binder generated source.
+For example, this is the case with @option{--GCC="foo -x -y"}. But the back end
+switches will be used for @option{--GCC="gcc -gnatv"}. If several
@option{--GCC=compiler_name} are used, only the last @var{compiler_name}
is taken into account. However, all the additional switches are also taken
into account. Thus,
The usual form of the @command{gnatmake} command is
@smallexample
-$ gnatmake [@var{switches}] @var{file_name}
- [@var{file_names}] [@var{mode_switches}]
+$ gnatmake @ovar{switches} @var{file_name}
+ @ovar{file_names} @ovar{mode_switches}
@end smallexample
@noindent
If @var{mode_switches} are present, they must always be placed after
the last @var{file_name} and all @code{switches}.
-If you are using standard file extensions (.adb and .ads), then the
+If you are using standard file extensions (@file{.adb} and @file{.ads}), then the
extension may be omitted from the @var{file_name} arguments. However, if
you are using non-standard extensions, then it is required that the
extension be given. A relative or absolute directory path can be
Compile only. Do not perform binding, except when @option{^-b^/ACTIONS=BIND^}
is also specified. Do not perform linking, except if both
@option{^-b^/ACTIONS=BIND^} and
- @option{^-l^/ACTIONS=LINK^} are also specified.
+@option{^-l^/ACTIONS=LINK^} are also specified.
If the root unit specified by @var{file_name} is not a main unit, this is the
default. Otherwise @command{gnatmake} will attempt binding and linking
unless all objects are up to date and the executable is more recent than
(^-P^/PROJECT_FILE=^@var{file}) or with multiple compiling processes
(^-j^/PROCESSES=^nnn, when nnn is greater than 1).
+@item ^-d^/DISPLAY_PROGRESS^
+@cindex @option{^-d^/DISPLAY_PROGRESS^} (@command{gnatmake})
+Display progress for each source, up to date or not, as a single line
+
+@smallexample
+completed x out of y (zz%)
+@end smallexample
+
+If the file needs to be compiled this is displayed after the invocation of
+the compiler. These lines are displayed even in quiet output mode.
+
@item ^-D ^/DIRECTORY_OBJECTS=^@var{dir}
@cindex @option{^-D^/DIRECTORY_OBJECTS^} (@command{gnatmake})
Put all object files and ALI file in directory @var{dir}.
modifications to a source file consist in adding/removing comments,
empty lines, spaces or tabs. This means that if you have changed the
comments in a source file or have simply reformatted it, using this
-switch will tell gnatmake not to recompile files that depend on it
+switch will tell @command{gnatmake} not to recompile files that depend on it
(provided other sources on which these files depend have undergone no
semantic modifications). Note that the debugging information may be
out of date with respect to the sources if the @option{-m} switch causes
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.
+be those specified on the command line. Even when
+@option{^-x^/NON_PROJECT_UNIT_COMPILATION^} is used, mains specified on the
+command line need to be sources of a project file.
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
Indicate that external variable @var{name} has the value @var{value}.
@item @command{gcc} @asis{switches}
@ifclear vms
Any uppercase or multi-character switch that is not a @command{gnatmake} switch
-is passed to @command{gcc} (e.g. @option{-O}, @option{-gnato,} etc.)
+is passed to @command{gcc} (e.g.@: @option{-O}, @option{-gnato,} etc.)
@end ifclear
@ifset vms
Any qualifier that cannot be recognized as a qualifier for @code{GNAT MAKE}
@item
Using @command{gnatmake} along with the
@option{^-m (minimal recompilation)^/MINIMAL_RECOMPILATION^}
-switch provides a mechanism for avoiding unnecessary rcompilations. Using
+switch provides a mechanism for avoiding unnecessary recompilations. Using
this switch,
you can update the comments/format of your
source files without having to recompile everything. Note, however, that
@ifset vms
@item gnatmake Main_Unit /QUIET
- /COMPILER_QUALIFIERS /OPTIMIZE=ALL
- /BINDER_QUALIFIERS /ORDER_OF_ELABORATION
+/COMPILER_QUALIFIERS /OPTIMIZE=ALL
+/BINDER_QUALIFIERS /ORDER_OF_ELABORATION
@end ifset
Compile all files necessary to bind and link the main program unit
@code{Main_Unit} (from file @file{main_unit.adb}). All compilations will
@ifnottex
@menu
* Performance Considerations::
+* Text_IO Suggestions::
* Reducing Size of Ada Executables with gnatelim::
* Reducing Size of Executables with unused subprogram/data elimination::
@end menu
@subsection Controlling Run-Time Checks
@noindent
-By default, GNAT generates all run-time checks, except arithmetic overflow
-checking for integer operations and checks for access before elaboration on
+By default, GNAT generates all run-time checks, except integer overflow
+checks, stack overflow checks, and checks for access before elaboration on
subprogram calls. The latter are not required in default mode, because all
necessary checking is done at compile time.
@cindex @option{-gnatp} (@command{gcc})
have to be marked as non-abortable.
If you use neither the @code{abort} statement, nor asynchronous transfer
-of control (@code{select .. then abort}), then this distributed overhead
+of control (@code{select @dots{} then abort}), then this distributed overhead
is removed, which may have a general positive effect in improving
overall performance. Especially code involving frequent use of tasking
constructs and controlled types will show much improved performance.
@cindex @option{^-O^/OPTIMIZE^} (@command{gcc})
@noindent
+Without any optimization ^option,^qualifier,^
+the compiler's goal is to reduce the cost of
+compilation and to make debugging produce the expected results.
+Statements are independent: if you stop the program with a breakpoint between
+statements, you can then assign a new value to any variable or change
+the program counter to any other statement in the subprogram and get exactly
+the results you would expect from the source code.
+
+Turning on optimization makes the compiler attempt to improve the
+performance and/or code size at the expense of compilation time and
+possibly the ability to debug the program.
+
+If you use multiple
+^-O options, with or without level numbers,^/OPTIMIZE qualifiers,^
+the last such option is the one that is effective.
+
+@noindent
The default is optimization off. This results in the fastest compile
times, but GNAT makes absolutely no attempt to optimize, and the
generated programs are considerably larger and slower than when
the fastest compilation time.
Note that many other compilers do fairly extensive optimization
-even if "no optimization" is specified. When using gcc, it is
+even if ``no optimization'' is specified. With gcc, it is
very unusual to use ^-O0^/OPTIMIZE=NONE^ for production if
execution time is of any concern, since ^-O0^/OPTIMIZE=NONE^
really does mean no optimization at all. This difference between
both depend on the particular application and the hardware environment.
You should experiment to find the best level for your application.
-The @option{^-Os^/OPTIMIZE=SPACE^} switch is independent of the time
-optimizations, so you can specify both @option{^-Os^/OPTIMIZE=SPACE^}
-and a time optimization on the same compile command.
-
Since the precise set of optimizations done at each level will vary from
release to release (and sometime from target to target), it is best to think
of the optimization settings in general terms.
-The @cite{Using GNU GCC} manual contains details about
+@xref{Optimize Options,, Options That Control Optimization, gcc, Using
+the GNU Compiler Collection (GCC)}, for details about
^the @option{-O} settings and a number of @option{-f} options that^how to^
individually enable or disable specific optimizations.
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain nested subprograms or anything else that @command{gcc}
-cannot support in inlined subprograms.
-
-@item
-The call occurs after the definition of the body of the subprogram.
+and not contain something that @command{gcc} cannot support in inlined
+subprograms.
@item
@cindex pragma Inline
@findex Inline
-Either @code{pragma Inline} applies to the subprogram or it is
-small and automatic inlining (optimization level @option{-O3}) is
-specified.
+Either @code{pragma Inline} applies to the subprogram, or it is local
+to the unit and called once from within it, or it is small and automatic
+inlining (optimization level @option{-O3}) is specified.
@end itemize
@noindent
@item
The called subprogram is suitable for inlining: It must be small enough
-and not contain nested subprograms or anything else @command{gcc} cannot
-support in inlined subprograms.
+and not contain something that @command{gcc} cannot support in inlined
+subprograms.
@item
The call appears in a body (not in a package spec).
pragma Inline (Q);
end R;
package body R is
- ...
+ @dots{}
end R;
with R;
procedure Main is
begin
- ...
+ @dots{}
R.Q;
end Main;
@end cartouche
@option{-gnatn} will still be active, even if
this switch is used to suppress the resulting inlining actions.
+@cindex @option{-fno-inline-functions} (@command{gcc})
+Note: The @option{-fno-inline-functions} switch can be used to prevent
+automatic inlining of small subprograms if @option{-O3} is used.
+
+@cindex @option{-fno-inline-functions-called-once} (@command{gcc})
+Note: The @option{-fno-inline-functions-called-once} switch
+can be used to prevent inlining of subprograms local to the unit
+and called once from within it if @option{-O1} is used.
+
Note regarding the use of @option{-O3}: There is no difference in inlining
behavior between @option{-O2} and @option{-O3} for subprograms with an explicit
pragma @code{Inline} assuming the use of @option{-gnatn}
@subsection Other Optimization Switches
@cindex Optimization Switches
-Since @code{GNAT} uses the @code{gcc} back end, all the specialized
-@code{gcc} optimization switches are potentially usable. These switches
+Since @code{GNAT} uses the @command{gcc} back end, all the specialized
+@command{gcc} optimization switches are potentially usable. These switches
have not been extensively tested with GNAT but can generally be expected
to work. Examples of switches in this category are
@option{-funroll-loops} and
the various target-specific @option{-m} options (in particular, it has been
observed that @option{-march=pentium4} can significantly improve performance
-on appropriate machines). For full details of these switches, see the
-@code{gcc} manual.
+on appropriate machines). For full details of these switches, see
+@ref{Submodel Options,, Hardware Models and Configurations, gcc, Using
+the GNU Compiler Collection (GCC)}.
@node Optimization and Strict Aliasing
@subsection Optimization and Strict Aliasing
type Int2A is access Int2;
Int1V : Int1A;
Int2V : Int2A;
- ...
+ @dots{}
begin
- ...
+ @dots{}
for J in Data'Range loop
if Data (J) = Int1V.all then
Int2V.all := Int2V.all + 1;
end if;
end loop;
- ...
+ @dots{}
end R;
@end cartouche
@end smallexample
@end smallexample
@noindent
-This program prints out 0 in @code{-O0} or @code{-O1}
-mode, but it prints out 1 in @code{-O2} mode. That's
+This program prints out 0 in @option{-O0} or @option{-O1}
+mode, but it prints out 1 in @option{-O2} mode. That's
because in strict aliasing mode, the compiler can and
does assume that the assignment to @code{v2.all} could not
affect the value of @code{v1.all}, since different types
As implied by the warning message, there are approaches you can use to
avoid the unwanted strict aliasing optimization in a case like this.
-One possibility is to simply avoid the use of @code{-O2}, but
+One possibility is to simply avoid the use of @option{-O2}, but
that is a bit drastic, since it throws away a number of useful
optimizations that do not involve strict aliasing assumptions.
A less drastic approach is to compile the program using the
-option @code{-fno-strict-aliasing}. Actually it is only the
+option @option{-fno-strict-aliasing}. Actually it is only the
unit containing the dereferencing of the suspicious pointer
that needs to be compiled. So in this case, if we compile
unit @code{m} with this switch, then we get the expected
value of zero printed. Analyzing which units might need
the switch can be painful, so a more reasonable approach
-is to compile the entire program with options @code{-O2}
-and @code{-fno-strict-aliasing}. If the performance is
+is to compile the entire program with options @option{-O2}
+and @option{-fno-strict-aliasing}. If the performance is
satisfactory with this combination of options, then the
advantage is that the entire issue of possible "wrong"
optimization due to strict aliasing is avoided.
@pxref{Profiling} for details of usage.
@end ifset
+
+@node Text_IO Suggestions
+@section @code{Text_IO} Suggestions
+@cindex @code{Text_IO} and performance
+
+@noindent
+The @code{Ada.Text_IO} package has fairly high overheads due in part to
+the requirement of maintaining page and line counts. If performance
+is critical, a recommendation is to use @code{Stream_IO} instead of
+@code{Text_IO} for volume output, since this package has less overhead.
+
+If @code{Text_IO} must be used, note that by default output to the standard
+output and standard error files is unbuffered (this provides better
+behavior when output statements are used for debugging, or if the
+progress of a program is observed by tracking the output, e.g. by
+using the Unix @command{tail -f} command to watch redirected output.
+
+If you are generating large volumes of output with @code{Text_IO} and
+performance is an important factor, use a designated file instead
+of the standard output file, or change the standard output file to
+be buffered using @code{Interfaces.C_Streams.setvbuf}.
+
+
+
@node Reducing Size of Ada Executables with gnatelim
@section Reducing Size of Ada Executables with @code{gnatelim}
@findex gnatelim
@code{Eliminate} pragmas in the GNAT configuration file @file{gnat.adc} and
recompiling your program, you may decrease the size of its executable,
because the compiler will not generate the code for 'eliminated' subprograms.
-See GNAT Reference Manual for more information about this pragma.
+@xref{Pragma Eliminate,,, gnat_rm, GNAT Reference Manual}, for more
+information about this pragma.
@code{gnatelim} needs as its input data the name of the main subprogram
and a bind file for a main subprogram.
@code{gnatelim} has the following command-line interface:
@smallexample
-$ gnatelim [options] name
+$ gnatelim @ovar{options} name
@end smallexample
@noindent
$ PIPE GNAT ELIM MAIN_PROG > GNAT.ADC
@end ifset
@ifclear vms
-$ gnatelim main_prog >[>] gnat.adc
+$ gnatelim main_prog >@r{[}>@r{]} gnat.adc
@end ifclear
@end smallexample
Once the objects and static libraries are created with these options, the
linker can perform the dead code elimination. You can do this by setting
the @option{-Wl,--gc-sections} option to gcc command or in the
-@option{-largs} section of gnatmake. This will perform a garbage collection of
-code and data never referenced.
+@option{-largs} section of @command{gnatmake}. This will perform a
+garbage collection of code and data never referenced.
If the linker performs a partial link (@option{-r} ld linker option), then you
will need to provide one or several entry point using the
time you compile, regarding the source files that it writes as temporary
files that you throw away.
+Note that if your file containing multiple units starts with a byte order
+mark (BOM) specifying UTF-8 encoding, then the files generated by gnatchop
+will each start with a copy of this BOM, meaning that they can be compiled
+automatically in UTF-8 mode without needing to specify an explicit encoding.
+
@node Operating gnatchop in Compilation Mode
@section Operating gnatchop in Compilation Mode
The @code{gnatchop} command has the form:
@smallexample
-$ gnatchop switches @var{file name} [@var{file name} @var{file name} ...]
- [@var{directory}]
+$ gnatchop switches @var{file name} @r{[}@var{file name} @dots{}@r{]}
+ @ovar{directory}
@end smallexample
@noindent
previous section for a full description of this mode.
@ifclear vms
-@item -gnatxxx
-This passes the given @option{-gnatxxx} switch to @code{gnat} which is
-used to parse the given file. Not all @code{xxx} options make sense,
+@item -gnat@var{xxx}
+This passes the given @option{-gnat@var{xxx}} switch to @code{gnat} which is
+used to parse the given file. Not all @var{xxx} options make sense,
but for example, the use of @option{-gnati2} allows @code{gnatchop} to
process a source file that uses Latin-2 coding for identifiers.
@end ifclear
units to be skipped.
@ifclear vms
-@item --GCC=xxxx
+@item --GCC=@var{xxxx}
@cindex @option{--GCC=} (@code{gnatchop})
Specify the path of the GNAT parser to be used. When this switch is used,
no attempt is made to add the prefix to the GNAT parser executable.
@noindent
Configuration pragmas include those pragmas described as
such in the Ada Reference Manual, as well as
-implementation-dependent pragmas that are configuration pragmas. See the
-individual descriptions of pragmas in the @cite{GNAT Reference Manual} for
-details on these additional GNAT-specific configuration pragmas. Most
-notably, the pragma @code{Source_File_Name}, which allows
+implementation-dependent pragmas that are configuration pragmas.
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+for details on these additional GNAT-specific configuration pragmas.
+Most notably, the pragma @code{Source_File_Name}, which allows
specifying non-default names for source files, is a configuration
pragma. The following is a complete list of configuration pragmas
recognized by GNAT:
Ada_83
Ada_95
Ada_05
+ Ada_2005
+ Assertion_Policy
C_Pass_By_Copy
+ Check_Name
+ Check_Policy
+ Compile_Time_Error
+ Compile_Time_Warning
+ Compiler_Unit
Component_Alignment
+ Debug_Policy
Detect_Blocking
Discard_Names
Elaboration_Checks
Eliminate
Extend_System
External_Name_Casing
+ Fast_Math
+ Favor_Top_Level
Float_Representation
+ Implicit_Packing
Initialize_Scalars
Interrupt_State
License
Locking_Policy
Long_Float
+ No_Run_Time
+ No_Strict_Aliasing
Normalize_Scalars
+ Optimize_Alignment
Persistent_BSS
Polling
+ Priority_Specific_Dispatching
Profile
Profile_Warnings
Propagate_Exceptions
Restrictions_Warnings
Reviewable
Source_File_Name
+ Source_File_Name_Project
Style_Checks
Suppress
+ Suppress_Exception_Locations
Task_Dispatching_Policy
Universal_Data
Unsuppress
Use_VADS_Size
- Warnings
Validity_Checks
+ Warnings
+ Wide_Character_Encoding
+
@end smallexample
@menu
conventions, the GNAT compiler must be given additional information through
a configuration pragmas file (@pxref{Configuration Pragmas})
or a project file.
-When the non standard file naming conventions are well-defined,
+When the non-standard file naming conventions are well-defined,
a small number of pragmas @code{Source_File_Name} specifying a naming pattern
(@pxref{Alternative File Naming Schemes}) may be sufficient. However,
if the file naming conventions are irregular or arbitrary, a number
The usual form of the @code{gnatname} command is
@smallexample
-$ gnatname [@var{switches}] @var{naming_pattern} [@var{naming_patterns}]
+$ gnatname @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}
+ @r{[}--and @ovar{switches} @var{naming_pattern} @ovar{naming_patterns}@r{]}
@end smallexample
@noindent
used in file names by the Unix shells or the DOS prompt.
@noindent
+@code{gnatname} may be called with several sections of directories/patterns.
+Sections are separated by switch @code{--and}. In each section, there must be
+at least one pattern. If no directory is specified in a section, the current
+directory (or the project directory is @code{-P} is used) is implied.
+The options other that the directory switches and the patterns apply globally
+even if they are in different sections.
+
+@noindent
Examples of Naming Patterns are
@smallexample
(the ``Glob'' regular expressions).
@noindent
-When invoked with no switches, @code{gnatname} will create a configuration
-pragmas file @file{gnat.adc} in the current working directory, with pragmas
-@code{Source_File_Name} for each file that contains a valid Ada unit.
+When invoked with no switch @code{-P}, @code{gnatname} will create a
+configuration pragmas file @file{gnat.adc} in the current working directory,
+with pragmas @code{Source_File_Name} for each file that contains a valid Ada
+unit.
@node Switches for gnatname
@section Switches for @code{gnatname}
If @option{--version} was not used, display usage, then exit disregarding
all other options.
+@item --and
+Start another section of directories/patterns.
+
@item ^-c^/CONFIG_FILE=^@file{file}
@cindex @option{^-c^/CONFIG_FILE^} (@code{gnatname})
Create a configuration pragmas file @file{file} (instead of the default
There may be zero, one or more spaces between @option{^-D^/DIRS_FILE=^}
and @file{file}.
@file{file} must be an existing, readable text file.
-Each non empty line in @file{file} must be a directory.
+Each nonempty line in @file{file} must be a directory.
Specifying switch @option{^-D^/DIRS_FILE^} is equivalent to specifying as many
-switches @option{^-d^/SOURCE_DIRS^} as there are non empty lines in
+switches @option{^-d^/SOURCE_DIRS^} as there are nonempty lines in
@file{file}.
@item ^-f^/FOREIGN_PATTERN=^@file{pattern}
@noindent
will look for Ada units in all files with the @file{.ada} extension,
and will add to the list of file for project @file{prj.gpr} the C files
-with extension ".^c^C^".
+with extension @file{.^c^C^}.
@item ^-h^/HELP^
@cindex @option{^-h^/HELP^} (@code{gnatname})
The next section introduces the main features of GNAT's project facility
through a sequence of examples; subsequent sections will present the syntax
and semantics in more detail. A more formal description of the project
-facility appears in the GNAT Reference Manual.
+facility appears in @ref{Project File Reference,,, gnat_rm, GNAT
+Reference Manual}.
@c *****************************
@c * Examples of Project Files *
of the executable files, when no attribute @code{Executable} applies:
its value replace the platform-specific executable suffix.
Attributes @code{Executable} and @code{Executable_Suffix} are the only ways to
-specify a non default executable file name when several mains are built at once
+specify a non-default executable file name when several mains are built at once
in a single @command{gnatmake} command.
@node Source File Naming Conventions
@noindent
We want to develop an application in directory @file{^/app^[APP]^} that
@code{with} the packages @code{GUI} and @code{Comm}, using the properties of
-the corresponding project files (e.g. the ^switch^switch^ settings
+the corresponding project files (e.g.@: the ^switch^switch^ settings
and object directory).
Skeletal code for a main procedure might be something like the following:
@group
with GUI, Comm;
procedure App_Main is
- ...
+ @dots{}
begin
- ...
+ @dots{}
end App_Main;
@end group
@end smallexample
@noindent
In large software systems it is common to have multiple
implementations of a common interface; in Ada terms, multiple versions of a
-package body for the same specification. For example, one implementation
+package body for the same spec. For example, one implementation
might be safe for use in tasking programs, while another might only be used
in sequential applications. This can be modeled in GNAT using the concept
of @emph{project extension}. If one project (the ``child'') @emph{extends}
will be a compilation error when compiling the spec.
For that purpose, the attribute @code{Excluded_Source_Files} is used.
-Its value is a string list: a list of file names.
+Its value is a string list: a list of file names. It is also possible to use
+attribute @code{Excluded_Source_List_File}. Its value is a single string:
+the file name of a text file containing a list of file names, one per line.
@smallexample @c @projectfile
project B extends "a" is
@menu
* Basic Syntax::
+* Qualified Projects::
* Packages::
* Expressions::
* String Types::
Any name in a project file, such as the project name or a variable name,
has the same syntax as an Ada identifier.
-The reserved words of project files are the Ada reserved words plus
+The reserved words of project files are the Ada 95 reserved words plus
@code{extends}, @code{external}, and @code{project}. Note that the only Ada
reserved words currently used in project file syntax are:
@itemize @bullet
@item
+@code{all}
+@item
+@code{at}
+@item
@code{case}
@item
@code{end}
@item
@code{is}
@item
+@code{limited}
+@item
+@code{null}
+@item
@code{others}
@item
@code{package}
@end itemize
@noindent
-Comments in project files have the same syntax as in Ada, two consecutives
+Comments in project files have the same syntax as in Ada, two consecutive
hyphens through the end of the line.
+@node Qualified Projects
+@subsection Qualified Projects
+
+@noindent
+Before the reserved @code{project}, there may be one or two "qualifiers", that
+is identifiers or other reserved words, to qualify the project.
+
+The current list of qualifiers is:
+
+@itemize @bullet
+@item
+@code{abstract}: qualify a project with no sources. An abstract project must
+have a declaration specifying that there are no sources in the project, and,
+if it extends another project, the project it extends must also be a qualified
+abstract project.
+
+@item
+@code{standard}: a standard project is a non library project with sources.
+
+@item
+@code{aggregate}: for future extension
+
+@item
+@code{aggregate library}: for future extension
+
+@item
+@code{library}: a library project must declare both attributes
+@code{Library_Name} and @code{Library_Dir}.
+
+@item
+@code{configuration}: a configuration project cannot be in a project tree.
+@end itemize
+
@node Packages
@subsection Packages
A @emph{simple string expression} is one of the following:
@itemize @bullet
-@item A literal string; e.g.@code{"comm/my_proj.gpr"}
+@item A literal string; e.g.@: @code{"comm/my_proj.gpr"}
@item A string-valued variable reference (@pxref{Variables})
@item A string-valued attribute reference (@pxref{Attributes})
@item An external reference (@pxref{External References in Project Files})
@tab string list
@item @code{Excluded_Source_Files}
@tab string list
+@item @code{Excluded_Source_List_File}
+@tab string
@item @code{Languages}
@tab string list
@item @code{Main}
@item The name of an imported project
@item The name of a parent project that is extended by the current project
@item An expanded name whose prefix is imported/parent project name,
- and whose selector is a package name
+and whose selector is a package name
@end itemize
@noindent
@end smallexample
@noindent
-The attribute @var{Object_Dir} has a string value, the path name of the object
+The attribute @code{Object_Dir} has a string value, the path name of the object
directory. The path name may be absolute or relative to the directory of the
project file. This directory must already exist, and be readable and writable.
@end smallexample
@noindent
-The attribute @var{Exec_Dir} has a string value, the path name of the exec
+The attribute @code{Exec_Dir} has a string value, the path name of the exec
directory. The path name may be absolute or relative to the directory of the
project file. This directory must already exist, and be writable.
with "project1", "utilities.gpr";
with "/namings/apex.gpr";
project Main is
- ...
+ @dots{}
@end group
@end smallexample
sources. This can be achieved through the @emph{project extension} facility.
@smallexample @c projectfile
- project Modified_Utilities extends "/baseline/utilities.gpr" is ...
+ project Modified_Utilities extends "/baseline/utilities.gpr" is @dots{}
@end smallexample
@noindent
An inherited source file retains any switches specified in the parent project.
-For example if the project @code{Utilities} contains the specification and the
+For example if the project @code{Utilities} contains the spec and the
body of an Ada package @code{Util_IO}, then the project
@code{Modified_Utilities} can contain a new body for package @code{Util_IO}.
The original body of @code{Util_IO} will not be considered in program builds.
-However, the package specification will still be found in the project
+However, the package spec will still be found in the project
@code{Utilities}.
-A child project can have only one parent but it may import any number of other
-projects.
+A child project can have only one parent, except when it is qualified as
+abstract. But it may import any number of other projects.
A project is not allowed to import directly or indirectly at the same time a
child project and any of its ancestors.
Create project A1 that extends A, placing modified P1 there:
@smallexample @c 0projectfile
-project A1 extends "(...)/A" is
+project A1 extends "(@dots{})/A" is
end A1;
@end smallexample
P3 there:
@smallexample @c 0projectfile
-with "(...)/A1";
-project C1 extends all "(...)/C" is
+with "(@dots{})/A1";
+project C1 extends all "(@dots{})/C" is
end C1;
@end smallexample
@end enumerate
Mode : Mode_Type := external ("MODE");
case Mode is
when "Debug" =>
- ...
+ @dots{}
@end group
@end smallexample
with "/global/apex.gpr";
project Example is
package Naming renames Apex.Naming;
- ...
+ @dots{}
end Example;
@end group
@end smallexample
@table @code
-@item @var{Casing}
+@item @code{Casing}
This must be a string with one of the three values @code{"lowercase"},
@code{"uppercase"} or @code{"mixedcase"}; these strings are case insensitive.
@noindent
-If @var{Casing} is not specified, then the default is @code{"lowercase"}.
+If @code{Casing} is not specified, then the default is @code{"lowercase"}.
-@item @var{Dot_Replacement}
+@item @code{Dot_Replacement}
This must be a string whose value satisfies the following conditions:
@itemize @bullet
@noindent
If @code{Dot_Replacement} is not specified, then the default is @code{"-"}.
-@item @var{Spec_Suffix}
+@item @code{Spec_Suffix}
This is an associative array (indexed by the programming language name, case
insensitive) whose value is a string that must satisfy the following
conditions:
If @code{Spec_Suffix ("Ada")} is not specified, then the default is
@code{"^.ads^.ADS^"}.
-@item @var{Body_Suffix}
+@item @code{Body_Suffix}
This is an associative array (indexed by the programming language name, case
insensitive) whose value is a string that must satisfy the following
conditions:
If @code{Body_Suffix ("Ada")} is not specified, then the default is
@code{"^.adb^.ADB^"}.
-@item @var{Separate_Suffix}
+@item @code{Separate_Suffix}
This must be a string whose value satisfies the same conditions as
@code{Body_Suffix}. The same "longest suffix" rules apply.
If @code{Separate_Suffix ("Ada")} is not specified, then it defaults to same
value as @code{Body_Suffix ("Ada")}.
-@item @var{Spec}
+@item @code{Spec}
@noindent
You can use the associative array attribute @code{Spec} to define
the source file name for an individual Ada compilation unit's spec. The array
for Spec ("MyPack.MyChild") use "mypack.mychild.spec";
@end smallexample
-@item @var{Body}
+@item @code{Body}
You can use the associative array attribute @code{Body} to
define the source file name for an individual Ada compilation unit's body
@end group
@end smallexample
-Attribute @code{Library_Interface} has a non empty string list value,
+Attribute @code{Library_Interface} has a nonempty string list value,
each string in the list designating a unit contained in an immediate source
of the project file.
"false" for attribute @code{Library_Auto_Init} will prevent automatic
initialization of dynamic or relocatable libraries.
-When a non automatically initialized Stand-alone Library is used
+When a non-automatically initialized Stand-alone Library is used
in an executable, its initialization procedure must be called before
any service of the library is used.
When the main subprogram is in Ada, it may mean that the initialization
@table @option
@item ^-P^/PROJECT_FILE=^@var{project}
-@cindex @option{^-P^/PROJECT_FILE^} (any tool supporting project files)
+@cindex @option{^-P^/PROJECT_FILE^} (any project-aware tool)
Indicates the name of a project file. This project file will be parsed with
the verbosity indicated by @option{^-vP^MESSAGE_PROJECT_FILES=^@emph{x}},
if any, and using the external references indicated
or @option{^-X^/EXTERNAL_REFERENCE^} is not significant.
@item ^-X^/EXTERNAL_REFERENCE=^@var{name=value}
-@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any tool supporting project files)
+@cindex @option{^-X^/EXTERNAL_REFERENCE^} (any project-aware tool)
Indicates that external variable @var{name} has the value @var{value}.
The Project Manager will use this value for occurrences of
@code{external(name)} when parsing the project file.
takes precedence over the value of the same name in the environment.
@item ^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}
-@cindex @code{^-vP^/MESSAGES_PROJECT_FILE^} (any tool supporting project files)
-@c Previous line uses code vs option command, to stay less than 80 chars
+@cindex @option{^-vP^/MESSAGES_PROJECT_FILE^} (any project-aware tool)
Indicates the verbosity of the parsing of GNAT project files.
@ifclear vms
If several @option{^-vP^/MESSAGES_PROJECT_FILE=^@emph{x}} switches are present,
only the last one is used.
+@item ^-aP^/ADD_PROJECT_SEARCH_DIR=^<dir>
+@cindex @option{^-aP^/ADD_PROJECT_SEARCH_DIR=^} (any project-aware tool)
+Add directory <dir> at the beginning of the project search path, in order,
+after the current working directory.
+
+@ifclear vms
+@item -eL
+@cindex @option{-eL} (any project-aware tool)
+Follow all symbolic links when processing project files.
+@end ifclear
+
+@item ^--subdirs^/SUBDIRS^=<subdir>
+@cindex @option{^--subdirs^/SUBDIRS^=} (gnatmake and gnatclean)
+This switch is recognized by gnatmake and gnatclean. It indicate that the real
+directories (except the source directories) are the subdirectories <subdir>
+of the directories specified in the project files. This applies in particular
+to object directories, library directories and exec directories. If the
+subdirectories do not exist, they are created automatically.
+
@end table
@c **********************************
-- Ada source file:
with Pack;
procedure Foo_Main is
- ...
+ @dots{}
end Foo_Main;
@end group
@end smallexample
@command{^gnatmake -f -u -c^gnatmake -f -u -c^}).
@noindent
-On non VMS platforms, between @command{gnat} and the command, two
+On non-VMS platforms, between @command{gnat} and the command, two
special switches may be used:
@itemize @bullet
@code{^gnatmetric^gnatmetric^}),
and @code{^gnatpp^gnatpp^})
on a set of project units thanks to the combination of the switches
-@code{-P}, @code{-U} and possibly the main unit when one is interested
+@option{-P}, @option{-U} and possibly the main unit when one is interested
in its closure. For instance,
@smallexample
gnat metric -Pproj
other_declarative_item
package_declaration ::=
- package_specification | package_renaming
+ package_spec | package_renaming
-package_specification ::=
+package_spec ::=
@b{package} package_identifier @b{is}
@{simple_declarative_item@}
@b{end} package_identifier ;
@noindent
The command invocation for @code{gnatxref} is:
@smallexample
-$ gnatxref [switches] sourcefile1 [sourcefile2 ...]
+$ gnatxref @ovar{switches} @var{sourcefile1} @r{[}@var{sourcefile2} @dots{}@r{]}
@end smallexample
@noindent
where
-@table @code
-@item sourcefile1, sourcefile2
+@table @var
+@item sourcefile1
+@itemx sourcefile2
identifies the source files for which a report is to be generated. The
``with''ed units will be processed too. You must provide at least one file.
@end table
@noindent
-The switches can be :
+The switches can be:
@table @option
@c !sort!
@item --version
The command line for @code{gnatfind} is:
@smallexample
-$ gnatfind [switches] pattern[:sourcefile[:line[:column]]]
- [file1 file2 ...]
+$ gnatfind @ovar{switches} @var{pattern}@r{[}:@var{sourcefile}@r{[}:@var{line}@r{[}:@var{column}@r{]]]}
+ @r{[}@var{file1} @var{file2} @dots{}]
@end smallexample
@noindent
where
-@table @code
+@table @var
@item pattern
An entity will be output only if it matches the regular expression found
-in @samp{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}.
+in @var{pattern}, see @ref{Regular Expressions in gnatfind and gnatxref}.
Omitting the pattern is equivalent to specifying @samp{*}, which
will match any entity. Note that if you do not provide a pattern, you
@item sourcefile
@code{gnatfind} will look for references, bodies or declarations
-of symbols referenced in @file{sourcefile}, at line @samp{line}
-and column @samp{column}. See @ref{Examples of gnatfind Usage}
+of symbols referenced in @file{@var{sourcefile}}, at line @var{line}
+and column @var{column}. See @ref{Examples of gnatfind Usage}
for syntax examples.
@item line
line of the first character of the identifier for the
entity reference. Columns are numbered from 1.
-@item file1 file2 ...
+@item file1 file2 @dots{}
The search will be restricted to these source files. If none are given, then
the search will be done for every library file in the search path.
These file must appear only after the pattern or sourcefile.
These file names are considered to be regular expressions, so for instance
-specifying 'source*.adb' is the same as giving every file in the current
-directory whose name starts with 'source' and whose extension is 'adb'.
+specifying @file{source*.adb} is the same as giving every file in the current
+directory whose name starts with @file{source} and whose extension is
+@file{adb}.
The location of the spec of the entity will always be displayed, even if it
-isn't in one of file1, file2,... The occurrences of the entity in the
-separate units of the ones given on the command line will also be displayed.
+isn't in one of @file{@var{file1}}, @file{@var{file2}},@enddots{} The
+occurrences of the entity in the separate units of the ones given on the
+command line will also be displayed.
Note that if you specify at least one file in this part, @code{gnatfind} may
-sometimes not be able to find the body of the subprograms...
+sometimes not be able to find the body of the subprograms.
@end table
@ifclear vms
@item make_cmd=COMMAND
[default: @code{"gnatmake $@{main@} -aI$@{src_dir@}
- -aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@}
- -bargs $@{bind_opt@} -largs $@{link_opt@}"}]
+-aO$@{obj_dir@} -g -gnatq -cargs $@{comp_opt@}
+-bargs $@{bind_opt@} -largs $@{link_opt@}"}]
@end ifclear
specifies the command used to recompile the whole application.
@noindent
As specified in the section about @command{gnatfind}, the pattern can be a
regular expression. Actually, there are to set of regular expressions
-which are recognized by the program :
+which are recognized by the program:
@table @code
@item globbing patterns
These are the most usual regular expression. They are the same that you
generally used in a Unix shell command line, or in a DOS session.
-Here is a more formal grammar :
+Here is a more formal grammar:
@smallexample
@group
@iftex
term ::= elmt elmt -- concatenation (elmt then elmt)
term ::= * -- any string of 0 or more characters
term ::= ? -- matches any character
-term ::= [char @{char@}] -- matches any character listed
+term ::= [char @{char@}] -- matches any character listed
term ::= [char - char] -- matches any character in range
@end group
@end smallexample
@leftskip=.5cm
@end iftex
@group
-regexp ::= term @{| term@} -- alternation (term or term ...)
+regexp ::= term @{| term@} -- alternation (term or term @dots{})
-term ::= item @{item@} -- concatenation (item then item)
+term ::= item @{item@} -- concatenation (item then item)
item ::= elmt -- match elmt
item ::= elmt * -- zero or more elmt's
@end group
@end smallexample
-Following are a few examples :
+Following are a few examples:
@table @samp
@item abcde|fghi
-will match any of the two strings 'abcde' and 'fghi'.
+will match any of the two strings @samp{abcde} and @samp{fghi},
@item abc*d
-will match any string like 'abd', 'abcd', 'abccd', 'abcccd', and so on
+will match any string like @samp{abd}, @samp{abcd}, @samp{abccd},
+@samp{abcccd}, and so on,
@item [a-z]+
will match any string which has only lowercase characters in it (and at
-least one character
+least one character.
@end table
@end table
@subsection General Usage
@noindent
-For the following examples, we will consider the following units :
+For the following examples, we will consider the following units:
@smallexample @c ada
@group
@subsection Using gnatxref with vi
@code{gnatxref} can generate a tags file output, which can be used
-directly from @file{vi}. Note that the standard version of @file{vi}
+directly from @command{vi}. Note that the standard version of @command{vi}
will not work properly with overloaded symbols. Consider using another
-free implementation of @file{vi}, such as @file{vim}.
+free implementation of @command{vi}, such as @command{vim}.
@smallexample
$ gnatxref -v gnatfind.adb > tags
will generate the tags file for @code{gnatfind} itself (if the sources
are in the search path!).
-From @file{vi}, you can then use the command @samp{:tag @i{entity}}
-(replacing @i{entity} by whatever you are looking for), and vi will
+From @command{vi}, you can then use the command @samp{:tag @var{entity}}
+(replacing @var{entity} by whatever you are looking for), and vi will
display a new file with the corresponding declaration of entity.
@end ifclear
The @command{gnatpp} command has the form
@smallexample
-$ gnatpp [@var{switches}] @var{filename}
+$ gnatpp @ovar{switches} @var{filename}
@end smallexample
@noindent
@cindex @option{^--no-separate-is^/NO_SEPARATE_IS^} (@command{gnatpp})
@item ^--no-separate-is^/NO_SEPARATE_IS^
Do not place the keyword @code{is} on a separate line in a subprogram body in
-case if the specification occupies more then one line.
+case if the spec occupies more then one line.
@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
@cindex @option{^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^} (@command{gnatpp})
@item ^--no-separate-loop-then^/NO_SEPARATE_LOOP_THEN^
Do not place the keyword @code{loop} in FOR and WHILE loop statements and the
-keyw0rd @code{then} in IF statements on a separate line. This option is
+keyword @code{then} in IF statements on a separate line. This option is
incompatible with @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} option.
@cindex @option{^--use-on-new-line^/USE_ON_NEW_LINE^} (@command{gnatpp})
These switches allow control over line length and indentation.
@table @option
-@item ^-M@i{nnn}^/LINE_LENGTH_MAX=@i{nnn}^
+@item ^-M@var{nnn}^/LINE_LENGTH_MAX=@var{nnn}^
@cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp})
-Maximum line length, @i{nnn} from 32 ..256, the default value is 79
+Maximum line length, @var{nnn} from 32@dots{}256, the default value is 79
-@item ^-i@i{nnn}^/INDENTATION_LEVEL=@i{nnn}^
+@item ^-i@var{nnn}^/INDENTATION_LEVEL=@var{nnn}^
@cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp})
-Indentation level, @i{nnn} from 1 .. 9, the default value is 3
+Indentation level, @var{nnn} from 1@dots{}9, the default value is 3
-@item ^-cl@i{nnn}^/CONTINUATION_INDENT=@i{nnn}^
+@item ^-cl@var{nnn}^/CONTINUATION_INDENT=@var{nnn}^
@cindex @option{^-cl^/CONTINUATION_INDENT^} (@command{gnatpp})
Indentation level for continuation lines (relative to the line being
-continued), @i{nnn} from 1 .. 9.
+continued), @var{nnn} from 1@dots{}9.
The default
value is one less then the (normal) indentation level, unless the
indentation is set to 1 (in which case the default value for continuation
@cindex @option{^-ff^/FORM_FEED_AFTER_PRAGMA_PAGE^} (@command{gnatpp})
Insert a Form Feed character after a pragma Page.
-@item ^-T@i{nnn}^/MAX_INDENT=@i{nnn}^
+@item ^-T@var{nnn}^/MAX_INDENT=@var{nnn}^
@cindex @option{^-T^/MAX_INDENT^} (@command{gnatpp})
Do not use an additional indentation level for @b{case} alternatives
-and variants if there are @i{nnn} or more (the default
+and variants if there are @var{nnn} or more (the default
value is 10).
-If @i{nnn} is 0, an additional indentation level is
+If @var{nnn} is 0, an additional indentation level is
used for @b{case} alternatives and variants regardless of their number.
@end table
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})
+@item ^-rnb^/REPLACE_NO_BACKUP^
+@cindex @option{^-rnb^/REPLACE_NO_BACKUP^} (@code{gnatpp})
Replace the input source file with the reformatted output without
creating any backup copy of the input source.
@noindent
The @option{^-c5^/COMMENTS_LAYOUT=KEEP_SPECIAL^} switch specifies, that comments
that has a special format (that is, a character that is neither a letter nor digit
-not white space nor line break immediatelly following the leading @code{--} of
+not white space nor line break immediately following the leading @code{--} of
the comment) should be without any change moved from the argument source
into reformatted source. This switch allows to preserve comments that are used
-as a special marks in the code (e.g. SPARK annotation).
+as a special marks in the code (e.g.@: SPARK annotation).
@node Construct Layout
@subsection Construct Layout
The @command{gnatmetric} command has the form
@smallexample
-$ gnatmetric [@i{switches}] @{@i{filename}@} [@i{-cargs gcc_switches}]
+$ gnatmetric @ovar{switches} @{@var{filename}@} @r{[}-cargs @var{gcc_switches}@r{]}
@end smallexample
@noindent
where
@itemize @bullet
@item
-@i{switches} specify the metrics to compute and define the destination for
+@var{switches} specify the metrics to compute and define the destination for
the output
@item
-Each @i{filename} is the name (including the extension) of a source
+Each @var{filename} is the name (including the extension) of a source
file to process. ``Wildcards'' are allowed, and
the file name may contain path information.
-If no @i{filename} is supplied, then the @i{switches} list must contain
+If no @var{filename} is supplied, then the @var{switches} list must contain
at least one
@option{-files} switch (@pxref{Other gnatmetric Switches}).
Including both a @option{-files} switch and one or more
-@i{filename} arguments is permitted.
+@var{filename} arguments is permitted.
@item
-@i{-cargs gcc_switches} is a list of switches for
+@samp{-cargs @var{gcc_switches}} is a list of switches for
@command{gcc}. They will be passed on to all compiler invocations made by
@command{gnatmetric} to generate the ASIS trees. Here you can provide
@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
subprogram (and generic subprogram) bodies;
@item
-package (and generic package) specifications and bodies;
+package (and generic package) specs and bodies;
@item
task object and type specifications and bodies;
* Line Metrics Control::
* Syntax Metrics Control::
* Complexity Metrics Control::
+* Object-Oriented Metrics Control::
@end menu
@node Line Metrics Control
@table @emph
@item Public subprograms
-This metric is computed for package specifications. It is the
+This metric is computed for package specs. It is the
number of subprograms and generic subprograms declared in the visible
part (including the visible part of nested packages, protected objects, and
protected types).
subprograms are counted in the same way as ``usual'' subprogram bodies.
@item Public types
-This metric is computed for package specifications and
+This metric is computed for package specs and
generic package declarations. It is the total number of types
that can be referenced from outside this compilation unit, plus the
number of types from all the visible parts of all the visible generic
@cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric})
@ifclear vms
-@cindex @option{--no-syntax@var{x}}
+@cindex @option{--no-syntax@var{x}} (@command{gnatmetric})
@end ifclear
@item ^--syntax-all^/SYNTAX_METRICS=ALL_ON^
@end table
+
+@node Object-Oriented Metrics Control
+@subsubsection Object-Oriented Metrics Control
+@cindex Object-Oriented metrics control in @command{gnatmetric}
+
+@noindent
+@cindex Coupling metrics (in in @command{gnatmetric})
+Coupling metrics are object-oriented metrics that measure the
+dependencies between a given class (or a group of classes) and the
+``external world'' (that is, the other classes in the program). In this
+subsection the term ``class'' is used in its
+traditional object-oriented programming sense
+(an instantiable module that contains data and/or method members).
+A @emph{category} (of classes)
+is a group of closely related classes that are reused and/or
+modified together.
+
+A class @code{K}'s @emph{efferent coupling} is the number of classes
+that @code{K} depends upon.
+A category's efferent coupling is the number of classes outside the
+category that the classes inside the category depend upon.
+
+A class @code{K}'s @emph{afferent coupling} is the number of classes
+that depend upon @code{K}.
+A category's afferent coupling is the number of classes outside the
+category that depend on classes belonging to the category.
+
+Ada's implementation of the object-oriented paradigm does not use the
+traditional class notion, so the definition of the coupling
+metrics for Ada maps the class and class category notions
+onto Ada constructs.
+
+For the coupling metrics, several kinds of modules -- a library package,
+a library generic package, and a library generic package instantiation --
+that define a tagged type or an interface type are
+considered to be a class. A category consists of a library package (or
+a library generic package) that defines a tagged or an interface type,
+together with all its descendant (generic) packages that define tagged
+or interface types. For any package counted as a class,
+its body (if any) is considered
+together with its spec when counting the dependencies. For dependencies
+between classes, the Ada semantic dependencies are considered.
+For coupling metrics, only dependencies on units that are considered as
+classes, are considered.
+
+When computing coupling metrics, @command{gnatmetric} counts only
+dependencies between units that are arguments of the gnatmetric call.
+Coupling metrics are program-wide (or project-wide) metrics, so to
+get a valid result, you should call @command{gnatmetric} for
+the whole set of sources that make up your program. It can be done
+by calling @command{gnatmetric} from the GNAT driver with @option{-U}
+option (see See @ref{The GNAT Driver and Project Files} for details.
+
+By default, all the coupling metrics are disabled. You can use the following
+switches to specify the coupling metrics to be computed and reported:
+
+@table @option
+
+@ifclear vms
+@cindex @option{--package@var{x}} (@command{gnatmetric})
+@cindex @option{--no-package@var{x}} (@command{gnatmetric})
+@cindex @option{--category@var{x}} (@command{gnatmetric})
+@cindex @option{--no-category@var{x}} (@command{gnatmetric})
+@end ifclear
+
+@ifset vms
+@cindex @option{/COUPLING_METRICS} (@command{gnatmetric})
+@end ifset
+
+@item ^--coupling-all^/COUPLING_METRICS=ALL_ON^
+Report all the coupling metrics
+
+@item ^--no-coupling-all^/COUPLING_METRICS=ALL_OFF^
+Do not report any of metrics
+
+@item ^--package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_ON^
+Report package efferent coupling
+
+@item ^--no-package-efferent-coupling^/COUPLING_METRICS=PACKAGE_EFFERENT_OFF^
+Do not report package efferent coupling
+
+@item ^--package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_ON^
+Report package afferent coupling
+
+@item ^--no-package-afferent-coupling^/COUPLING_METRICS=PACKAGE_AFFERENT_OFF^
+Do not report package afferent coupling
+
+@item ^--category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_ON^
+Report category efferent coupling
+
+@item ^--no-category-efferent-coupling^/COUPLING_METRICS=CATEGORY_EFFERENT_OFF^
+Do not report category efferent coupling
+
+@item ^--category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_ON^
+Report category afferent coupling
+
+@item ^--no-category-afferent-coupling^/COUPLING_METRICS=CATEGORY_AFFERENT_OFF^
+Do not report category afferent coupling
+
+@end table
+
@node Other gnatmetric Switches
@subsection Other @code{gnatmetric} Switches
@item
If such a replacement occurs in the
second character position of a name, and the first character is
-^a, g, s, or i^A, G, S, or I^ then replace the dot by the character
-^~ (tilde)^$ (dollar sign)^
+^@samp{a}, @samp{g}, @samp{s}, or @samp{i}, ^@samp{A}, @samp{G}, @samp{S}, or @samp{I},^
+then replace the dot by the character
+^@samp{~} (tilde)^@samp{$} (dollar sign)^
instead of a minus.
@end itemize
The reason for this exception is to avoid clashes
with the standard names for children of System, Ada, Interfaces,
-and GNAT, which use the prefixes ^s- a- i- and g-^S- A- I- and G-^
+and GNAT, which use the prefixes
+^@samp{s-}, @samp{a-}, @samp{i-}, and @samp{g-},^@samp{S-}, @samp{A-}, @samp{I-}, and @samp{G-},^
respectively.
The @option{^-gnatk^/FILE_NAME_MAX_LENGTH=^@var{nn}}
@ifclear vms
@smallexample
-$ gnatkr @var{name} [@var{length}]
+$ gnatkr @var{name} @ovar{length}
@end smallexample
@end ifclear
@noindent
@var{name} is the uncrunched file name, derived from the name of the unit
-in the standard manner described in the previous section (i.e. in particular
+in the standard manner described in the previous section (i.e., in particular
all dots are replaced by hyphens). The file name may or may not have an
extension (defined as a suffix of the form period followed by arbitrary
characters other than period). If an extension is present then it will
using ^lowercase^uppercase^
for all letters, except that a hyphen in the second character position is
replaced by a ^tilde^dollar sign^ if the first character is
-^a, i, g, or s^A, I, G, or S^.
+^@samp{a}, @samp{i}, @samp{g}, or @samp{s}^@samp{A}, @samp{I}, @samp{G}, or @samp{S}^.
The extension is @code{.ads} for a
-specification and @code{.adb} for a body.
+spec and @code{.adb} for a body.
Krunching does not affect the extension, but the file name is shortened to
the specified length by following these rules:
@ref{Conditional Compilation}.
@menu
+* Preprocessing Symbols::
* Using gnatprep::
* Switches for gnatprep::
* Form of Definitions File::
* Form of Input Text for gnatprep::
@end menu
+@node Preprocessing Symbols
+@section Preprocessing Symbols
+
+@noindent
+Preprocessing symbols are defined in definition files and referred to in
+sources to be preprocessed. A Preprocessing symbol is an identifier, following
+normal Ada (case-insensitive) rules for its syntax, with the restriction that
+all characters need to be in the ASCII set (no accented letters).
@node Using gnatprep
@section Using @code{gnatprep}
To call @code{gnatprep} use
@smallexample
-$ gnatprep [switches] infile outfile [deffile]
+$ gnatprep @ovar{switches} @var{infile} @var{outfile} @ovar{deffile}
@end smallexample
@noindent
where
-@table @code
+@table @var
@item switches
is an optional sequence of switches as described in the next section.
@item deffile
is the full name of a text file containing definitions of
-symbols to be referenced by the preprocessor. This argument is
+preprocessing symbols to be referenced by the preprocessor. This argument is
optional, and can be replaced by the use of the @option{-D} switch.
@end table
Causes comments to be scanned. Normally comments are ignored by gnatprep.
If this option is specified, then comments are scanned and any $symbol
substitutions performed as in program text. This is particularly useful
-when structured comments are used (e.g. when writing programs in the
+when structured comments are used (e.g., when writing programs in the
SPARK dialect of Ada). Note that this switch is not available when
doing integrated preprocessing (it would be useless in this context
since comments are ignored by the compiler in any case).
@item ^-Dsymbol=value^/ASSOCIATE="symbol=value"^
@cindex @option{^-D^/ASSOCIATE^} (@command{gnatprep})
-Defines a new symbol, associated with value. If no value is given on the
-command line, then symbol is considered to be @code{True}. This switch
+Defines a new preprocessing symbol, associated with value. If no value is given
+on the command line, then symbol is considered to be @code{True}. This switch
can be used in place of a definition file.
@ifset vms
@end smallexample
@noindent
-where symbol is an identifier, following normal Ada (case-insensitive)
-rules for its syntax, and value is one of the following:
+where symbol is a preprocessing symbol, and value is one of the following:
@itemize @bullet
@item
@smallexample
@group
@cartouche
-#if @i{expression} [then]
+#if @i{expression} @r{[}then@r{]}
lines
-#elsif @i{expression} [then]
+#elsif @i{expression} @r{[}then@r{]}
lines
-#elsif @i{expression} [then]
+#elsif @i{expression} @r{[}then@r{]}
lines
-...
+@dots{}
#else
lines
#end if;
@i{expression} ::= ( @i{expression} )
@end smallexample
+The following restriction exists: it is not allowed to have "and" or "or"
+following "not" in the same expression without parentheses. For example, this
+is not allowed:
+
+@smallexample
+ not X or Y
+@end smallexample
+
+This should be one of the following:
+
+@smallexample
+ (not X) or Y
+ not (X or Y)
+@end smallexample
+
@noindent
For the first test (@i{expression} ::= <symbol>) the symbol must have
either the value true or false, that is to say the right-hand of the
including none at all. The @code{else} is optional, as in Ada.
The @code{#} marking the start of a preprocessor line must be the first
-non-blank character on the line, i.e. it must be preceded only by
+non-blank character on the line, i.e., it must be preceded only by
spaces or horizontal tabs.
Symbol substitution outside of preprocessor lines is obtained by using
The @code{gnatlbr} command has the form
@smallexample
-$ GNAT LIBRARY /[CREATE | SET | DELETE]=directory [/CONFIG=file]
+$ GNAT LIBRARY /@r{[}CREATE@r{|}SET@r{|}DELETE@r{]}=directory @r{[}/CONFIG=file@r{]}
@end smallexample
@node Switches for gnatlbr
@c !sort!
@item /CREATE=directory
@cindex @code{/CREATE} (@code{gnatlbr})
- Create the new run-time library in the specified directory.
+Create the new run-time library in the specified directory.
@item /SET=directory
@cindex @code{/SET} (@code{gnatlbr})
- Make the library in the specified directory the current run-time
- library.
+Make the library in the specified directory the current run-time library.
@item /DELETE=directory
@cindex @code{/DELETE} (@code{gnatlbr})
- Delete the run-time library in the specified directory.
+Delete the run-time library in the specified directory.
@item /CONFIG=file
@cindex @code{/CONFIG} (@code{gnatlbr})
- With /CREATE:
- Use the configuration pragmas in the specified file when building
- the library.
+With /CREATE: Use the configuration pragmas in the specified file when
+building the library.
- With /SET:
- Use the configuration pragmas in the specified file when compiling.
+With /SET: Use the configuration pragmas in the specified file when
+compiling.
@end table
@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.
+Each nonempty line should contain the name of an existing file.
Several such switches may be specified simultaneously.
@item ^-aO^/OBJECT_SEARCH=^@var{dir}
@end smallexample
@noindent
-Please note that the library must have a name of the form @file{libxxx.a} or
-@file{libxxx.so} (or @file{libxxx.dll} on Windows) in order to be accessed by
-the directive @option{-lxxx} at link time.
+Please note that the library must have a name of the form @file{lib@var{xxx}.a}
+or @file{lib@var{xxx}.so} (or @file{lib@var{xxx}.dll} on Windows) in order to
+be accessed by the directive @option{-l@var{xxx}} at link time.
@node Installing a library
@subsection Installing a library
files and libraries in the directories mentioned in the project file. For
convenience, the user's library project file should be installed in a location
that will be searched automatically by the GNAT
-builder. These are the directories referenced in the @code{ADA_PROJECT_PATH}
+builder. These are the directories referenced in the @env{ADA_PROJECT_PATH}
environment variable (@pxref{Importing Projects}), and also the default GNAT
library location that can be queried with @command{gnatls -v} and is usually of
the form $gnat_install_root/lib/gnat.
@smallexample @c projectfile
with "my_lib";
project My_Proj is
- ...
+ @dots{}
end My_Proj;
@end smallexample
@itemize @bullet
@item
@file{/dir/my_lib_src} has been added by the user to the environment
-variable @code{ADA_INCLUDE_PATH}, or by the administrator to the file
+variable @env{ADA_INCLUDE_PATH}, or by the administrator to the file
@file{ada_source_path}
@item
@file{/dir/my_lib_obj} has been added by the user to the environment
-variable @code{ADA_OBJECTS_PATH}, or by the administrator to the file
+variable @env{ADA_OBJECTS_PATH}, or by the administrator to the file
@file{ada_object_path}
@item
a pragma @code{Linker_Options} has been added to one of the sources.
@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
+(i.e., add a word @option{SL} on the line in the @file{ALI} file that starts
with letter ``P'') and make the modified copy of the @file{ALI} file
read-only.
@end itemize
@noindent
This chapter offers some examples of makefiles that solve specific
-problems. It does not explain how to write a makefile (see the GNU make
-documentation), nor does it try to replace the @command{gnatmake} utility
-(@pxref{The GNAT Make Program gnatmake}).
+problems. It does not explain how to write a makefile (@pxref{Top,, GNU
+make, make, GNU @code{make}}), nor does it try to replace the
+@command{gnatmake} utility (@pxref{The GNAT Make Program gnatmake}).
All the examples in this section are specific to the GNU version of
-make. Although @code{make} is a standard utility, and the basic language
+make. Although @command{make} is a standard utility, and the basic language
is the same, these examples use some advanced features found only in
@code{GNU make}.
## csc is put in the top level directory (where the Makefile is).
## toplevel_dir __ first_csc (sources) __ lib (will contain the library)
## \_ second_csc (sources) __ lib (will contain the library)
-## \_ ...
+## \_ @dots{}
## Although this Makefile is build for shared library, it is easy to modify
## to build partial link objects instead (modify the lines with -shared and
## gnatlink below)
# The following variable should give the directory containing libgnat.so
# You can get this directory through 'gnatls -v'. This is usually the last
# directory in the Object_Path.
-GLIB=...
+GLIB=@dots{}
# The directories for the libraries
# (This macro expands the list of CSC to the list of shared libraries, you
-# could simply use the expanded form :
+# could simply use the expanded form:
# LIB_DIR=aa/lib/libaa.so bb/lib/libbb.so cc/lib/libcc.so
LIB_DIR=$@{foreach dir,$@{CSC_LIST@},$@{dir@}/lib/lib$@{dir@}.so@}
# by a new tool, gnatmlib
$@{LIB_DIR@}:
mkdir -p $@{dir $@@ @}
- cd $@{dir $@@ @}; gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
- cd $@{dir $@@ @}; cp -f ../*.ali .
+ cd $@{dir $@@ @} && gcc -shared -o $@{notdir $@@ @} ../*.o -L$@{GLIB@} -lgnat
+ cd $@{dir $@@ @} && cp -f ../*.ali .
# The dependencies for the modules
# Note that we have to force the expansion of *.o, since in some cases
store it in a variable. For small projects, it is often easier to
specify each of them by hand, since you then have full control over what
is the proper order for these directories, which ones should be
-included...
+included.
However, in larger projects, which might involve hundreds of
subdirectories, it might be more convenient to generate this list
The example below presents two methods. The first one, although less
general, gives you more control over the list. It involves wildcard
-characters, that are automatically expanded by @code{make}. Its
+characters, that are automatically expanded by @command{make}. Its
shortcoming is that you need to explicitly specify some of the
organization of your project, such as for instance the directory tree
-depth, whether some directories are found in a separate tree,...
+depth, whether some directories are found in a separate tree, @enddots{}
The second method is the most general one. It requires an external
-program, called @code{find}, which is standard on all Unix systems. All
+program, called @command{find}, which is standard on all Unix systems. All
the directories found under a given root directory will be added to the
list.
The @code{gnatmem} utility monitors dynamic allocation and
deallocation activity in a program, and displays information about
incorrect deallocations and possible sources of memory leaks.
-It provides three type of information:
+It is designed to work in association with a static runtime library
+only and in this context provides three types of information:
@itemize @bullet
@item
General information concerning memory management, such as the total
number of allocations and deallocations, the amount of allocated
-memory and the high water mark, i.e. the largest amount of allocated
+memory and the high water mark, i.e.@: the largest amount of allocated
memory in the course of program execution.
@item
The @code{gnatmem} command has the form
@smallexample
- $ gnatmem [switches] user_program
+ $ gnatmem @ovar{switches} user_program
@end smallexample
@noindent
Gnatmem must be supplied with the @file{gmem.out} file and the executable to
examine. If the location of @file{gmem.out} file was not explicitly supplied by
-@code{-i} switch, gnatmem will assume that this file can be found in the
+@option{-i} switch, gnatmem will assume that this file can be found in the
current directory. For example, after you have executed @file{my_program},
@file{gmem.out} can be analyzed by @code{gnatmem} using the command:
Note that the GNAT run time contains itself a certain number of
allocations that have no corresponding deallocation,
as shown here for root #2 and root
-#3. This is a normal behavior when the number of non freed allocations
+#3. This is a normal behavior when the number of non-freed allocations
is one, it allocates dynamic data structures that the run time needs for
the complete lifetime of the program. Note also that there is only one
allocation root in the user program with a single line back trace:
@ifclear vms
To ensure that a clean exception is signalled for stack
overflow, set the environment variable
-@code{GNAT_STACK_LIMIT} to indicate the maximum
+@env{GNAT_STACK_LIMIT} to indicate the maximum
stack area that can be used, as in:
@cindex GNAT_STACK_LIMIT
It is not always convenient to output the stack usage when the program
is still running. Hence, it is possible to delay this output until program
termination. for a given number of tasks specified as the argument of the
-@code{-u} option. For instance:
+@option{-u} option. For instance:
@smallexample
$ gnatbind -u100 file
@end table
@noindent
-The environment task stack, e.g. the stack that contains the main unit, is
+The environment task stack, e.g., the stack that contains the main unit, is
only processed when the environment variable GNAT_STACK_LIMIT is set.
Invoking @command{gnatcheck} on the command line has the form:
@smallexample
-$ gnatcheck [@i{switches}] @{@i{filename}@}
- [^-files^/FILES^=@{@i{arg_list_filename}@}]
- [-cargs @i{gcc_switches}] [-rules @i{rule_options}]
+$ gnatcheck @ovar{switches} @{@var{filename}@}
+ @r{[}^-files^/FILES^=@{@var{arg_list_filename}@}@r{]}
+ @r{[}-cargs @var{gcc_switches}@r{]} @r{[}-rules @var{rule_options}@r{]}
@end smallexample
@noindent
where
@itemize @bullet
@item
-@i{switches} specify the general tool options
+@var{switches} specify the general tool options
@item
-Each @i{filename} is the name (including the extension) of a source
+Each @var{filename} is the name (including the extension) of a source
file to process. ``Wildcards'' are allowed, and
the file name may contain path information.
@item
-Each @i{arg_list_filename} is the name (including the extension) of a text
+Each @var{arg_list_filename} is the name (including the extension) of a text
file containing the names of the source files to process, separated by spaces
or line breaks.
@item
-@i{gcc_switches} is a list of switches for
+@var{gcc_switches} is a list of switches for
@command{gcc}. They will be passed on to all compiler invocations made by
@command{gnatcheck} to generate the ASIS trees. Here you can provide
@option{^-I^/INCLUDE_DIRS=^} switches to form the source search path,
and use the @option{-gnatec} switch to set the configuration file.
@item
-@i{rule_options} is a list of options for controlling a set of
+@var{rule_options} is a list of options for controlling a set of
rules to be checked by @command{gnatcheck} (@pxref{gnatcheck Rule Options}).
@end itemize
@noindent
-Either a @i{filename} or an @i{arg_list_filename} must be supplied.
+Either a @file{@var{filename}} or an @file{@var{arg_list_filename}} must be supplied.
@menu
* Format of the Report File::
of this construct in the generic unit to the place where this unit is
instantiated.
+@cindex @option{^-m^/DIAGNOSTIC_LIMIT^} (@command{gnatcheck})
+@item ^-m@i{nnn}^/DIAGNOSTIC_LIMIT=@i{nnn}^
+Maximum number of diagnoses to be sent to Stdout, @i{nnn} from o@dots{}1000,
+the default value is 500. Zero means that there is no limitation on
+the number of diagnostic messages to be printed into Stdout.
+
@cindex @option{^-q^/QUIET^} (@command{gnatcheck})
@item ^-q^/QUIET^
Quiet mode. All the diagnoses about rule violations are placed in the
Turn all the rule checks OFF.
@cindex @option{+R} (@command{gnatcheck})
-@item +R@i{rule_id[:param]}
+@item +R@var{rule_id}@r{[}:@var{param}@r{]}
Turn on the check for a specified rule with the specified parameter, if any.
-@i{rule_id} must be the identifier of one of the currently implemented rules
+@var{rule_id} must be the identifier of one of the currently implemented rules
(use @option{^-h^/HELP^} for the list of implemented rules). Rule identifiers
-are not case-sensitive. The @i{param} item must
+are not case-sensitive. The @var{param} item must
be a string representing a valid parameter(s) for the specified rule.
If it contains any space characters then this string must be enclosed in
quotation marks.
@cindex @option{-R} (@command{gnatcheck})
-@item -R@i{rule_id[:param]}
+@item -R@var{rule_id}@r{[}:@var{param}@r{]}
Turn off the check for a specified rule with the specified parameter, if any.
@cindex @option{-from} (@command{gnatcheck})
-@item -from=@i{rule_option_filename}
-Read the rule options from the text file @i{rule_option_filename}, referred as
+@item -from=@var{rule_option_filename}
+Read the rule options from the text file @var{rule_option_filename}, referred as
``rule file'' below.
@end table
@noindent
-The default behavior is that all the rule checks are enabled, except for
-the checks performed by the compiler.
-@ignore
-and the checks associated with the
-global rules.
-@end ignore
+The default behavior is that all the rule checks are disabled.
A rule file is a text file containing a set of rule options.
@cindex Rule file (for @code{gnatcheck})
lines and end-of-line comments). The rule file has free format; that is,
you do not have to start a new rule option on a new line.
-A rule file may contain other @option{-from=@i{rule_option_filename}}
+A rule file may contain other @option{-from=@var{rule_option_filename}}
options, each such option being replaced with the content of the
corresponding rule file during the rule files processing. In case a
-cycle is detected (that is, @i{rule_file_1} reads rule options from
-@i{rule_file_2}, and @i{rule_file_2} reads (directly or indirectly)
-rule options from @i{rule_file_1}), the processing
-of rule files is interrupted and a part of their content is ignored.
+cycle is detected (that is, @file{@var{rule_file_1}} reads rule options
+from @file{@var{rule_file_2}}, and @file{@var{rule_file_2}} reads
+(directly or indirectly) rule options from @file{@var{rule_file_1}}),
+the processing of rule files is interrupted and a part of their content
+is ignored.
@node Adding the Results of Compiler Checks to gnatcheck Output
@code{Restrictions} or @code{Restriction_Warnings}.
@item Style_Checks
-To record compiler style checks, use the rule named
+To record compiler style checks(@pxref{Style Checking}), use the rule named
@code{Style_Checks}. A parameter of this rule can be either @code{All_Checks},
-which enables all the style checks, or a string that has exactly the same
+which enables all the standard style checks that corresponds to @option{-gnatyy}
+GNAT style check option, or a string that has exactly the same
structure and semantics as the @code{string_LITERAL} parameter of GNAT pragma
-@code{Style_Checks} (for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+@code{Style_Checks} (for further information about this pragma,
+@pxref{Pragma Style_Checks,,, gnat_rm, GNAT Reference Manual}).
@item Warnings
To record compiler warnings (@pxref{Warning Message Control}), use the rule
named @code{Warnings} with a parameter that is a valid
@i{static_string_expression} argument of GNAT pragma @code{Warnings}
-(for further information about this pragma, please
-refer to the @cite{@value{EDITION} Reference Manual}).
+(for further information about this pragma, @pxref{Pragma Warnings,,,
+gnat_rm, GNAT Reference Manual}). Note, that in case of gnatcheck
+'s' parameter, that corresponds to the GNAT @option{-gnatws} option, disables
+all the specific warnings, but not suppresses the warning mode,
+and 'e' parameter, corresponding to @option{-gnatwe} that means
+"treat warnings as errors", does not have any effect.
@end table
+To disable a specific restriction check, use @code{-RStyle_Checks} gnatcheck
+option with the corresponding restriction name as a parameter. @code{-R} is
+not available for @code{Style_Checks} and @code{Warnings} options, to disable
+warnings and style checks, use the corresponding warning and style options.
+
@node Project-Wide Checks
@section Project-Wide Checks
@cindex Project-wide checks (for @command{gnatcheck})
@ignore
* Improperly_Called_Protected_Entries::
@end ignore
+* Metrics::
* Misnamed_Identifiers::
* Multiple_Entries_In_Protected_Definitions::
* Name_Clashes::
* Predefined_Numeric_Types::
* Raising_External_Exceptions::
* Raising_Predefined_Exceptions::
+* Separate_Numeric_Error_Handlers::
@ignore
* Recursion::
* Side_Effect_Functions::
@smallexample @c ada
for I in 1 .. N loop
- ...
+ @dots{}
end loop;
@end smallexample
@smallexample @c ada
subtype S is Integer range 1..N;
-...
+@dots{}
for I in S loop
- ...
+ @dots{}
end loop;
@end smallexample
such as @code{A .. B}, subtype marks and @code{'Range} attributes) are flagged.
An enumeration range is
flagged even if contains exactly one enumeration value or no values at all. A
-type derived fom an enumeration type is considered as an enumeration type.
+type derived from an enumeration type is considered as an enumeration type.
This rule helps prevent maintenance problems arising from adding an
enumeration value to a type and having it implicitly handled by an existing
@cindex @code{Exceptions_As_Control_Flow} (for @command{gnatcheck})
@noindent
-Flag each place where an exception is explictly raised and handled in the
+Flag each place where an exception is explicitly raised and handled in the
same subprogram body. A @code{raise} statement in an exception handler,
package body, task body or entry body is not flagged.
ON. @emph{Pragma_Name} is treated as a name of a pragma. If it
does not correspond to any pragma name defined in the Ada
standard or to the name of a GNAT-specific pragma defined
-in the GNAT Reference Manual, it is treated as the name of
-unknown pragma.
+in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}, it is treated as the name of unknown pragma.
@item @code{GNAT}
All the GNAT-specific pragmas are detected; this sets
checked without affecting checks for
other pragmas. @emph{Pragma_Name} is treated as a name
of a pragma. If it does not correspond to any pragma
-defined in the Ada standard or to any name defined in the
-GNAT Reference Manual,
-this option is treated as turning OFF detection of all
-unknown pragmas.
+defined in the Ada standard or to any name defined in
+@ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual},
+this option is treated as turning OFF detection of all unknown pragmas.
@item GNAT
Turn OFF detection of all GNAT-specific pragmas
Flag each procedure that can be rewritten as a function. A procedure can be
converted into a function if it has exactly one parameter of mode @code{out}
and no parameters of mode @code{in out}. Procedure declarations,
-formal procedure declarations. and generic procedure declarations are always
+formal procedure declarations, and generic procedure declarations are always
checked. Procedure
bodies and body stubs are flagged only if they do not have corresponding
separate declarations. Procedure renamings and procedure instantiations are
not flagged.
-If a procedure can be rewritten as a fucntion, but its @code{out} parameter is
+If a procedure can be rewritten as a function, but its @code{out} parameter is
of a limited type, it is not flagged.
Protected procedures are not flagged. Null procedures also are not flagged.
@cindex @code{Generics_In_Subprograms} rule (for @command{gnatcheck})
@noindent
-Flag each declaration of a generic unit in a supbrogram. Generic
+Flag each declaration of a generic unit in a subprogram. Generic
declarations in the bodies of generic subprograms are also flagged.
A generic unit nested in another generic unit is not flagged.
If a generic unit is
@cindex @code{Improperly_Located_Instantiations} rule (for @command{gnatcheck})
@noindent
-Flag all generic instantiations in library-level package specifications
+Flag all generic instantiations in library-level package specs
(including library generic packages) and in all subprogram bodies.
Instantiations in task and entry bodies are not flagged. Instantiations in the
@noindent
Flag all local packages declared in package and generic package
-specifications.
+specs.
Local packages in bodies are not flagged.
This rule has no parameters.
This rule has no parameters.
@end ignore
+@node Metrics
+@subsection @code{Metrics}
+@cindex @code{Metrics} rule (for @command{gnatcheck})
+
+@noindent
+There is a set of checks based on computing a metric value and comparing the
+result with the specified upper (or lower, depending on a specific metric)
+value specified for a given metric. A construct is flagged if a given metric
+is applicable (can be computed) for it and the computed value is greater
+then (lover then) the specified upper (lower) bound.
+
+The name of any metric-based rule consists of the prefix @code{Metrics_}
+followed by the name of the corresponding metric (see the table below).
+For @option{+R} option, each metric-based rule has a numeric parameter
+specifying the bound (integer or real, depending on a metric), @option{-R}
+option for metric rules does not have a parameter.
+
+The following table shows the metric names for that the corresponding
+metrics-based checks are supported by gnatcheck, including the
+constraint that must be satisfied by the bound that is specified for the check
+and what bound - upper (U) or lower (L) - should be specified.
+
+@multitable {@code{Cyclomatic_Complexity}}{Cyclomatic complexity}{Positive integer}
+@ifnothtml
+@headitem Check Name @tab Description @tab Bounds Value
+@end ifnothtml
+@ifhtml
+@item @b{Check Name} @tab @b{Description} @tab @b{Bounds Value}
+@end ifhtml
+@c Above conditional code is workaround to bug in texi2html (Feb 2008)
+@item @code{Essential_Complexity} @tab Essential complexity @tab Positive integer (U)
+@item @code{Cyclomatic_Complexity} @tab Cyclomatic complexity @tab Positive integer (U)
+@item @code{LSLOC} @tab Logical Source Lines of Code @tab Positive integer (U)
+@end multitable
+
+@noindent
+The meaning and the computed values for all these metrics are exactly
+the same as for the corresponding metrics in @command{gnatmetric}.
+
+@emph{Example:} the rule
+@smallexample
++RMetrics_Cyclomatic_Complexity : 7
+@end smallexample
+@noindent
+means that all bodies with cyclomatic complexity exceeding 7 will be flagged.
+
+To turn OFF the check for cyclomatic complexity metric, use the following option:
+@smallexample
+-RMetrics_Cyclomatic_Complexity
+@end smallexample
@node Misnamed_Identifiers
@subsection @code{Misnamed_Identifiers}
@itemize @bullet
@item
- type declarations
+type declarations
@item
- constant declarations (but not number declarations)
+constant declarations (but not number declarations)
@item
- package renaming declarations (but not generic package renaming
- declarations)
+package renaming declarations (but not generic package renaming
+declarations)
@end itemize
@noindent
@itemize @bullet
@item
- type-defining names end with @code{_T}, unless the type is an access type,
- in which case the suffix must be @code{_A}
+type-defining names end with @code{_T}, unless the type is an access type,
+in which case the suffix must be @code{_A}
@item
- constant names end with @code{_C}
+constant names end with @code{_C}
@item
- names defining package renamings end with @code{_R}
+names defining package renamings end with @code{_R}
@end itemize
@noindent
@itemize @bullet
@item
- For an incomplete type declaration: if the corresponding full type
- declaration is available, the defining identifier from the full type
- declaration is checked, but the defining identifier from the incomplete type
- declaration is not; otherwise the defining identifier from the incomplete
- type declaration is checked against the suffix specified for type
- declarations.
+For an incomplete type declaration: if the corresponding full type
+declaration is available, the defining identifier from the full type
+declaration is checked, but the defining identifier from the incomplete type
+declaration is not; otherwise the defining identifier from the incomplete
+type declaration is checked against the suffix specified for type
+declarations.
@item
- For a private type declaration (including private extensions), the defining
- identifier from the private type declaration is checked against the type
- suffix (even if the corresponding full declaration is an access type
- declaration), and the defining identifier from the corresponding full type
- declaration is not checked.
+For a private type declaration (including private extensions), the defining
+identifier from the private type declaration is checked against the type
+suffix (even if the corresponding full declaration is an access type
+declaration), and the defining identifier from the corresponding full type
+declaration is not checked.
@end itemize
@noindent
@end itemize
@noindent
-The rule may have the following parameter for the @option{+R} option:
+The rule has the following parameter for the @option{+R} option:
@table @emph
@item N
@end table
@noindent
-If the parameter for the @option{+R} option is not a positive integer,
-the parameter is ignored and the rule is turned ON with the most recently
-specified maximal non-flagged nesting level.
+If the parameter for the @option{+R} option is not specified or
+if it is not a positive integer, @option{+R} option is ignored.
If more then one option is specified for the gnatcheck call, the later option and
new parameter override the previous one(s).
-A @option{+R} option with no parameter turns the rule ON using the maximal
-non-flagged nesting level specified by the most recent @option{+R} option with
-a parameter, or the value 4 if there is no such previous @option{+R} option.
-
-
@node Parameters_Out_Of_Order
@subsection @code{Parameters_Out_Of_Order}
This rule has no parameters.
+@node Separate_Numeric_Error_Handlers
+@subsection @code{Separate_Numeric_Error_Handlers}
+@cindex @code{Separate_Numeric_Error_Handlers} rule (for @command{gnatcheck})
+
+@noindent
+Flags each exception handler that contains a choice for
+the predefined @code{Constraint_Error} exception, but does not contain
+the choice for the predefined @code{Numeric_Error} exception, or
+that contains the choice for @code{Numeric_Error}, but does not contain the
+choice for @code{Constraint_Error}.
+
+This rule has no parameters.
@ignore
@node Recursion
the source search path when calling @command{gnatstub}, see the description
of @command{gnatstub} switches below.
+By default, all the program unit body stubs generated by @code{gnatstub}
+raise the predefined @code{Program_Error} exception, which will catch
+accidental calls of generated stubs. This behavior can be changed with
+option @option{^--no-exception^/NO_EXCEPTION^} (see below).
+
@menu
* Running gnatstub::
* Switches for gnatstub::
@command{gnatstub} has the command-line interface of the form
@smallexample
-$ gnatstub [switches] filename [directory]
+$ gnatstub @ovar{switches} @var{filename} @ovar{directory}
@end smallexample
@noindent
where
-@table @emph
+@table @var
@item filename
is the name of the source file that contains a library unit declaration
for which a body must be created. The file name may contain the path
@cindex @option{^-hg^/HEADER=GENERAL^} (@command{gnatstub})
Put a sample comment header into the body stub.
+@item ^--header-file=@var{filename}^/FROM_HEADER_FILE=@var{filename}^
+@cindex @option{^--header-file^/FROM_HEADER_FILE=^} (@command{gnatstub})
+Use the content of the file as the comment header for a generated body stub.
+
@ifclear vms
@item -IDIR
@cindex @option{-IDIR} (@command{gnatstub})
@cindex @option{^-l^/LINE_LENGTH^} (@command{gnatstub})
Same as @option{^-gnatyM^/MAX_LINE_LENGTH=^@var{n}}
-@item ^-o^/BODY=^@var{body-name}
+@item ^--no-exception^/NO_EXCEPTION^
+@cindex @option{^--no-exception^/NO_EXCEPTION^} (@command{gnatstub})
+Avoind raising PROGRAM_ERROR in the generated bodies of program unit stubs.
+This is not always possible for function stubs.
+
+@item ^-o ^/BODY=^@var{body-name}
@cindex @option{^-o^/BODY^} (@command{gnatstub})
Body file name. This should be set if the argument file name does not
follow
@end table
+@c *********************************
+@node Generating Ada Bindings for C and C++ headers
+@chapter Generating Ada Bindings for C and C++ headers
+@findex binding
+
+@noindent
+GNAT now comes with a new experimental binding generator for C and C++
+headers which is intended to do 95% of the tedious work of generating
+Ada specs from C or C++ header files. Note that this still is a work in
+progress, not designed to generate 100% correct Ada specs.
+
+The code generated is using the Ada 2005 syntax, which makes it
+easier to interface with other languages than previous versions of Ada.
+
+@menu
+* Running the binding generator::
+* Generating bindings for C++ headers::
+* Switches::
+@end menu
+
+@node Running the binding generator
+@section Running the binding generator
+
+@noindent
+The binding generator is part of the @command{gcc} compiler and can be
+invoked via the @option{-fdump-ada-spec} switch, which will generate Ada
+spec files for the header files specified on the command line, and all
+header files needed by these files transitivitely. For example:
+
+@smallexample
+$ g++ -c -fdump-ada-spec -C /usr/include/time.h
+$ gcc -c -gnat05 *.ads
+@end smallexample
+
+will generate, under GNU/Linux, the following files: @file{time_h.ads},
+@file{bits_time_h.ads}, @file{stddef_h.ads}, @file{bits_types_h.ads} which
+correspond to the files @file{/usr/include/time.h},
+@file{/usr/include/bits/time.h}, etc@dots{}, and will then compile in Ada 2005
+mode these Ada specs.
+
+The @code{-C} switch tells @command{gcc} to extract comments from headers,
+and will attempt to generate corresponding Ada comments.
+
+If you want to generate a single Ada file and not the transitive closure, you
+can use instead the @option{-fdump-ada-spec-slim} switch.
+
+Note that we recommend when possible to use the @command{g++} driver to
+generate bindings, even for most C headers, since this will in general
+generate better Ada specs. For generating bindings for C++ headers, it is
+mandatory to use the @command{g++} command, or @command{gcc -x c++} which
+is equivalent in this case. If @command{g++} cannot work on your C headers
+because of incompatibilities between C and C++, then you can fallback to
+@command{gcc} instead.
+
+For an example of better bindings generated from the C++ front-end,
+the name of the parameters (when available) are actually ignored by the C
+front-end. Consider the following C header:
+
+@smallexample
+extern void foo (int variable);
+@end smallexample
+
+with the C front-end, @code{variable} is ignored, and the above is handled as:
+
+@smallexample
+extern void foo (int);
+@end smallexample
+
+generating a generic:
+
+@smallexample
+procedure foo (param1 : int);
+@end smallexample
+
+with the C++ front-end, the name is available, and we generate:
+
+@smallexample
+procedure foo (variable : int);
+@end smallexample
+
+In some cases, the generated bindings will be more complete or more meaningful
+when defining some macros, which you can do via the @option{-D} switch. This
+is for example the case with @file{Xlib.h} under GNU/Linux:
+
+@smallexample
+g++ -c -fdump-ada-spec -DXLIB_ILLEGAL_ACCESS -C /usr/include/X11/Xlib.h
+@end smallexample
+
+The above will generate more complete bindings than a straight call without
+the @option{-DXLIB_ILLEGAL_ACCESS} switch.
+
+In other cases, it is not possible to parse a header file in a stand alone
+manner, because other include files need to be included first. In this
+case, the solution is to create a small header file including the needed
+@code{#include} and possible @code{#define} directives. For example, to
+generate Ada bindings for @file{readline/readline.h}, you need to first
+include @file{stdio.h}, so you can create a file with the following two
+lines in e.g. @file{readline1.h}:
+
+@smallexample
+#include <stdio.h>
+#include <readline/readline.h>
+@end smallexample
+
+and then generate Ada bindings from this file:
+
+@smallexample
+$ g++ -c -fdump-ada-spec readline1.h
+@end smallexample
+
+@node Generating bindings for C++ headers
+@section Generating bindings for C++ headers
+
+@noindent
+Generating bindings for C++ headers is done using the same options, always
+with the @command{g++} compiler.
+
+In this mode, C++ classes will be mapped to Ada tagged types, constructors
+will be mapped using the @code{CPP_Constructor} pragma, and when possible,
+multiple inheritance of abstract classes will be mapped to Ada interfaces
+(@xref{Interfacing to C++,,,gnat_rm, GNAT Reference Manual}, for additional
+information on interfacing to C++).
+
+For example, given the following C++ header file:
+
+@smallexample
+@group
+@cartouche
+class Carnivore @{
+public:
+ virtual int Number_Of_Teeth () = 0;
+@};
+
+class Domestic @{
+public:
+ virtual void Set_Owner (char* Name) = 0;
+@};
+
+class Animal @{
+public:
+ int Age_Count;
+ virtual void Set_Age (int New_Age);
+@};
+
+class Dog : Animal, Carnivore, Domestic @{
+ public:
+ int Tooth_Count;
+ char *Owner;
+
+ virtual int Number_Of_Teeth ();
+ virtual void Set_Owner (char* Name);
+
+ Dog();
+@};
+@end cartouche
+@end group
+@end smallexample
+
+The corresponding Ada code is generated:
+
+@smallexample @c ada
+@group
+@cartouche
+ package Class_Carnivore is
+ type Carnivore is limited interface;
+ pragma Import (CPP, Carnivore);
+
+ function Number_Of_Teeth (this : access Carnivore) return int is abstract;
+ end;
+ use Class_Carnivore;
+
+ package Class_Domestic is
+ type Domestic is limited interface;
+ pragma Import (CPP, Domestic);
+
+ procedure Set_Owner
+ (this : access Domestic;
+ Name : Interfaces.C.Strings.chars_ptr) is abstract;
+ end;
+ use Class_Domestic;
+
+ package Class_Animal is
+ type Animal is tagged limited record
+ Age_Count : aliased int;
+ end record;
+ pragma Import (CPP, Animal);
+
+ procedure Set_Age (this : access Animal; New_Age : int);
+ pragma Import (CPP, Set_Age, "_ZN6Animal7Set_AgeEi");
+ end;
+ use Class_Animal;
+
+ package Class_Dog is
+ type Dog is new Animal and Carnivore and Domestic with record
+ Tooth_Count : aliased int;
+ Owner : Interfaces.C.Strings.chars_ptr;
+ end record;
+ pragma Import (CPP, Dog);
+
+ function Number_Of_Teeth (this : access Dog) return int;
+ pragma Import (CPP, Number_Of_Teeth, "_ZN3Dog15Number_Of_TeethEv");
+
+ procedure Set_Owner
+ (this : access Dog; Name : Interfaces.C.Strings.chars_ptr);
+ pragma Import (CPP, Set_Owner, "_ZN3Dog9Set_OwnerEPc");
+
+ function New_Dog return Dog'Class;
+ pragma CPP_Constructor (New_Dog);
+ pragma Import (CPP, New_Dog, "_ZN3DogC1Ev");
+ end;
+ use Class_Dog;
+@end cartouche
+@end group
+@end smallexample
+
+@node Switches
+@section Switches
+
+@table @option
+@item -fdump-ada-spec
+@cindex @option{-fdump-ada-spec} (@command{gcc})
+Generate Ada spec files for the given header files transitively (including
+all header files that these headers depend upon).
+
+@item -fdump-ada-spec-slim
+@cindex @option{-fdump-ada-spec-slim} (@command{gcc})
+Generate Ada spec files for the header files specified on the command line
+only.
+
+@item -C
+@cindex @option{-C} (@command{gcc})
+Extract comments from headers and generate Ada comments in the Ada spec files.
+@end table
+
@node Other Utility Programs
@chapter Other Utility Programs
The command line is as follow:
@smallexample
-$ perl gnathtml.pl [^switches^options^] ada-files
+$ perl gnathtml.pl @ovar{^switches^options^} @var{ada-files}
@end smallexample
@noindent
an html file for every ada file, and a global file called @file{index.htm}.
This file is an index of every identifier defined in the files.
-The available ^switches^options^ are the following ones :
+The available ^switches^options^ are the following ones:
@table @option
@item -83
@item -f
@cindex @option{-f} (@code{gnathtml})
By default, gnathtml will generate html links only for global entities
-('with'ed units, global variables and types,...). If you specify
+('with'ed units, global variables and types,@dots{}). If you specify
@option{-f} on the command line, then links will be generated for local
entities too.
On Unix systems, you may want to modify the first line of the script
@code{gnathtml}, to explicitly tell the Operating system where Perl
-is. The syntax of this line is :
+is. The syntax of this line is:
@smallexample
#!full_path_name_to_perl
@end smallexample
Alternatively, you may run the script using the following command line:
@smallexample
-$ perl gnathtml.pl [switches] files
+$ perl gnathtml.pl @ovar{switches} @var{files}
@end smallexample
@ifset vms
@noindent
@end ifset
+@ifclear vms
+@c ******************************
+@node Code Coverage and Profiling
+@chapter Code Coverage and Profiling
+@cindex Code Coverage
+@cindex Profiling
+
+@noindent
+This chapter describes how to use @code{gcov} - coverage testing tool - and
+@code{gprof} - profiler tool - on your Ada programs.
+
+@menu
+* Code Coverage of Ada Programs using gcov::
+* Profiling an Ada Program using gprof::
+@end menu
+
+@node Code Coverage of Ada Programs using gcov
+@section Code Coverage of Ada Programs using gcov
+@cindex gcov
+@cindex -fprofile-arcs
+@cindex -ftest-coverage
+@cindex -coverage
+@cindex Code Coverage
+
+@noindent
+@code{gcov} is a test coverage program: it analyzes the execution of a given
+program on selected tests, to help you determine the portions of the program
+that are still untested.
+
+@code{gcov} is part of the GCC suite, and is described in detail in the GCC
+User's Guide. You can refer to this documentation for a more complete
+description.
+
+This chapter provides a quick startup guide, and
+details some Gnat-specific features.
+
+@menu
+* Quick startup guide::
+* Gnat specifics::
+@end menu
+
+@node Quick startup guide
+@subsection Quick startup guide
+
+In order to perform coverage analysis of a program using @code{gcov}, 3
+steps are needed:
+
+@itemize @bullet
+@item
+Code instrumentation during the compilation process
+@item
+Execution of the instrumented program
+@item
+Execution of the @code{gcov} tool to generate the result.
+@end itemize
+
+The code instrumentation needed by gcov is created at the object level:
+The source code is not modified in any way, because the instrumentation code is
+inserted by gcc during the compilation process. To compile your code with code
+coverage activated, you need to recompile your whole project using the
+switches
+@code{-fprofile-arcs} and @code{-ftest-coverage}, and link it using
+@code{-fprofile-arcs}.
+
+@smallexample
+$ gnatmake -P my_project.gpr -f -cargs -fprofile-arcs -ftest-coverage \
+ -largs -fprofile-arcs
+@end smallexample
+
+This compilation process will create @file{.gcno} files together with
+the usual object files.
+
+Once the program is compiled with coverage instrumentation, you can
+run it as many times as needed - on portions of a test suite for
+example. The first execution will produce @file{.gcda} files at the
+same location as the @file{.gcno} files. The following executions
+will update those files, so that a cumulative result of the covered
+portions of the program is generated.
+
+Finally, you need to call the @code{gcov} tool. The different options of
+@code{gcov} are available in the GCC User's Guide, section 'Invoking gcov'.
+
+This will create annotated source files with a @file{.gcov} extension:
+@file{my_main.adb} file will be analysed in @file{my_main.adb.gcov}.
+
+@node Gnat specifics
+@subsection Gnat specifics
+
+Because Ada semantics, portions of the source code may be shared among
+several object files. This is the case for example when generics are
+involved, when inlining is active or when declarations generate initialisation
+calls. In order to take
+into account this shared code, you need to call @code{gcov} on all
+source files of the tested program at once.
+
+The list of source files might exceed the system's maximum command line
+length. In order to bypass this limitation, a new mechanism has been
+implemented in @code{gcov}: you can now list all your project's files into a
+text file, and provide this file to gcov as a parameter, preceded by a @@
+(e.g. @samp{gcov @@mysrclist.txt}).
+
+Note that on AIX compiling a static library with @code{-fprofile-arcs} is
+not supported as there can be unresolved symbols during the final link.
+
+@node Profiling an Ada Program using gprof
+@section Profiling an Ada Program using gprof
+@cindex gprof
+@cindex -pg
+@cindex Profiling
+
+@noindent
+This section is not meant to be an exhaustive documentation of @code{gprof}.
+Full documentation for it can be found in the GNU Profiler User's Guide
+documentation that is part of this GNAT distribution.
+
+Profiling a program helps determine the parts of a program that are executed
+most often, and are therefore the most time-consuming.
+
+@code{gprof} is the standard GNU profiling tool; it has been enhanced to
+better handle Ada programs and multitasking.
+It is currently supported on the following platforms
+@itemize @bullet
+@item
+linux x86/x86_64
+@item
+solaris sparc/sparc64/x86
+@item
+windows x86
+@end itemize
+
+@noindent
+In order to profile a program using @code{gprof}, 3 steps are needed:
+
+@itemize @bullet
+@item
+Code instrumentation, requiring a full recompilation of the project with the
+proper switches.
+@item
+Execution of the program under the analysis conditions, i.e. with the desired
+input.
+@item
+Analysis of the results using the @code{gprof} tool.
+@end itemize
+
+@noindent
+The following sections detail the different steps, and indicate how
+to interpret the results:
+@menu
+* Compilation for profiling::
+* Program execution::
+* Running gprof::
+* Interpretation of profiling results::
+@end menu
+
+@node Compilation for profiling
+@subsection Compilation for profiling
+@cindex -pg
+@cindex Profiling
+
+In order to profile a program the first step is to tell the compiler
+to generate the necessary profiling information. The compiler switch to be used
+is @code{-pg}, which must be added to other compilation switches. This
+switch needs to be specified both during compilation and link stages, and can
+be specified once when using gnatmake:
+
+@smallexample
+gnatmake -f -pg -P my_project
+@end smallexample
+
+@noindent
+Note that only the objects that were compiled with the @samp{-pg} switch will be
+profiled; if you need to profile your whole project, use the
+@samp{-f} gnatmake switch to force full recompilation.
+
+@node Program execution
+@subsection Program execution
+
+@noindent
+Once the program has been compiled for profiling, you can run it as usual.
+
+The only constraint imposed by profiling is that the program must terminate
+normally. An interrupted program (via a Ctrl-C, kill, etc.) will not be
+properly analyzed.
+
+Once the program completes execution, a data file called @file{gmon.out} is
+generated in the directory where the program was launched from. If this file
+already exists, it will be overwritten.
+
+@node Running gprof
+@subsection Running gprof
+
+@noindent
+The @code{gprof} tool is called as follow:
+
+@smallexample
+gprof my_prog gmon.out
+@end smallexample
+
+@noindent
+or simpler:
+
+@smallexample
+gprof my_prog
+@end smallexample
+
+@noindent
+The complete form of the gprof command line is the following:
+
+@smallexample
+gprof [^switches^options^] [executable [data-file]]
+@end smallexample
+
+@noindent
+@code{gprof} supports numerous ^switch^options^. The order of these
+^switch^options^ does not matter. The full list of options can be found in
+the GNU Profiler User's Guide documentation that comes with this documentation.
+
+The following is the subset of those switches that is most relevant:
+
+@table @option
+
+@item --demangle[=@var{style}]
+@itemx --no-demangle
+@cindex @option{--demangle} (@code{gprof})
+These options control whether symbol names should be demangled when
+printing output. The default is to demangle C++ symbols. The
+@code{--no-demangle} option may be used to turn off demangling. Different
+compilers have different mangling styles. The optional demangling style
+argument can be used to choose an appropriate demangling style for your
+compiler, in particular Ada symbols generated by GNAT can be demangled using
+@code{--demangle=gnat}.
+
+@item -e @var{function_name}
+@cindex @option{-e} (@code{gprof})
+The @samp{-e @var{function}} option tells @code{gprof} not to print
+information about the function @var{function_name} (and its
+children@dots{}) in the call graph. The function will still be listed
+as a child of any functions that call it, but its index number will be
+shown as @samp{[not printed]}. More than one @samp{-e} option may be
+given; only one @var{function_name} may be indicated with each @samp{-e}
+option.
+
+@item -E @var{function_name}
+@cindex @option{-E} (@code{gprof})
+The @code{-E @var{function}} option works like the @code{-e} option, but
+execution time spent in the function (and children who were not called from
+anywhere else), will not be used to compute the percentages-of-time for
+the call graph. More than one @samp{-E} option may be given; only one
+@var{function_name} may be indicated with each @samp{-E} option.
+
+@item -f @var{function_name}
+@cindex @option{-f} (@code{gprof})
+The @samp{-f @var{function}} option causes @code{gprof} to limit the
+call graph to the function @var{function_name} and its children (and
+their children@dots{}). More than one @samp{-f} option may be given;
+only one @var{function_name} may be indicated with each @samp{-f}
+option.
+
+@item -F @var{function_name}
+@cindex @option{-F} (@code{gprof})
+The @samp{-F @var{function}} option works like the @code{-f} option, but
+only time spent in the function and its children (and their
+children@dots{}) will be used to determine total-time and
+percentages-of-time for the call graph. More than one @samp{-F} option
+may be given; only one @var{function_name} may be indicated with each
+@samp{-F} option. The @samp{-F} option overrides the @samp{-E} option.
+
+@end table
+
+@node Interpretation of profiling results
+@subsection Interpretation of profiling results
+
+@noindent
+
+The results of the profiling analysis are represented by two arrays: the
+'flat profile' and the 'call graph'. Full documentation of those outputs
+can be found in the GNU Profiler User's Guide.
+
+The flat profile shows the time spent in each function of the program, and how
+many time it has been called. This allows you to locate easily the most
+time-consuming functions.
+
+The call graph shows, for each subprogram, the subprograms that call it,
+and the subprograms that it calls. It also provides an estimate of the time
+spent in each of those callers/called subprograms.
+@end ifclear
+
+@c ******************************
@node Running and Debugging Ada Programs
@chapter Running and Debugging Ada Programs
@cindex Debugging
GNAT. The latest versions of @code{GDB} are Ada-aware and can handle
complex Ada data structures.
-The manual @cite{Debugging with GDB}
+@xref{Top,, Debugging with GDB, gdb, Debugging with GDB},
@ifset vms
-, located in the GNU:[DOCS] directory,
+located in the GNU:[DOCS] directory,
@end ifset
-contains full details on the usage of @code{GDB}, including a section on
+for full details on the usage of @code{GDB}, including a section on
its usage on programs. This manual should be consulted for full
details. The section that follows is a brief introduction to the
philosophy and use of @code{GDB}.
larger, but it does not add to the size of the actual executable that
will be loaded into memory, and has no impact on run-time performance. The
generation of debug information is triggered by the use of the
-^-g^/DEBUG^ switch in the gcc or gnatmake command used to carry out
-the compilations. It is important to emphasize that the use of these
-options does not change the generated code.
+^-g^/DEBUG^ switch in the @command{gcc} or @command{gnatmake} command
+used to carry out the compilations. It is important to emphasize that
+the use of these options does not change the generated code.
The debugging information is written in standard system formats that
are used by many tools, including debuggers and profilers. The format
@section Introduction to GDB Commands
@noindent
-@code{GDB} contains a large repertoire of commands. The manual
-@cite{Debugging with GDB}
+@code{GDB} contains a large repertoire of commands. @xref{Top,,
+Debugging with GDB, gdb, Debugging with GDB},
@ifset vms
-(located in the GNU:[DOCS] directory)
+located in the GNU:[DOCS] directory,
@end ifset
-includes extensive documentation on the use
+for extensive documentation on the use
of these commands, together with examples of their use. Furthermore,
-the command @var{help} invoked from within @code{GDB} activates a simple help
+the command @command{help} invoked from within GDB activates a simple help
facility which summarizes the available commands and their options.
In this section we summarize a few of the most commonly
used commands to give an idea of what @code{GDB} is about. You should create
@code{GDB} provides. Important additional capabilities, including conditional
breakpoints, the ability to execute command sequences on a breakpoint,
the ability to debug at the machine instruction level and many other
-features are described in detail in @cite{Debugging with GDB}.
-Note that most commands can be abbreviated
+features are described in detail in @ref{Top,, Debugging with GDB, gdb,
+Debugging with GDB}. Note that most commands can be abbreviated
(for example, c for continue, bt for backtrace).
@node Using Ada Expressions
their packages, regardless of context. Where this causes ambiguity,
@code{GDB} asks the user's intent.
-For details on the supported Ada syntax, see @cite{Debugging with GDB}.
+For details on the supported Ada syntax, see @ref{Top,, Debugging with
+GDB, gdb, Debugging with GDB}.
@node Calling User-Defined Subprograms
@section Calling User-Defined Subprograms
@noindent
For more detailed information on the tasking support,
-see @cite{Debugging with GDB}.
+see @ref{Top,, Debugging with GDB, gdb, Debugging with GDB}.
@node Debugging Generic Units
@section Debugging Generic Units
@item
@findex GNAT
Files with prefix @file{^g-^G-^} are children of @code{GNAT}. These are useful
-general-purpose packages, fully documented in their specifications. All
+general-purpose packages, fully documented in their specs. All
the other @file{.c} files are modifications of common @command{gcc} files.
@end itemize
0040138B at d:/stb/stb.adb:10
0040139C at d:/stb/stb.adb:14
00401335 at d:/stb/b~stb.adb:104
-004011C4 at /build/.../crt1.c:200
-004011F1 at /build/.../crt1.c:222
+004011C4 at /build/@dots{}/crt1.c:200
+004011F1 at /build/@dots{}/crt1.c:222
77E892A4 in ?? at ??:0
@end smallexample
0040138B in stb.p2 at d:/stb/stb.adb:10
0040139C in stb at d:/stb/stb.adb:14
00401335 in main at d:/stb/b~stb.adb:104
-004011C4 in <__mingw_CRTStartup> at /build/.../crt1.c:200
-004011F1 in <mainCRTStartup> at /build/.../crt1.c:222
+004011C4 in <__mingw_CRTStartup> at /build/@dots{}/crt1.c:200
+004011F1 in <mainCRTStartup> at /build/@dots{}/crt1.c:222
@end smallexample
@noindent
For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
attributes are recognized, although only a subset of them can sensibly
-be implemented. The description of pragmas in the
-@cite{GNAT Reference Manual} indicates whether or not they are applicable
-to non-VMS systems.
+be implemented. The description of pragmas in
+@xref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
+indicates whether or not they are applicable to non-VMS systems.
@menu
* Ada Language Compatibility::
@cindex @code{Aux_DEC} package (child of @code{System})
These definitions are incorporated directly into package @code{System},
as though they had been declared there. For a
-list of the declarations added, see the specification of this package,
+list of the declarations added, see the spec of this package,
which can be found in the file @file{s-auxdec.ads} in the GNAT library.
@cindex @file{s-auxdec.ads} file
The pragma @code{Extend_System} is a configuration pragma, which means that
The effect is not quite semantically identical to incorporating
the declarations directly into package @code{System},
but most programs will not notice a difference
-unless they use prefix notation (e.g. @code{System.Integer_8})
+unless they use prefix notation (e.g.@: @code{System.Integer_8})
to reference the entities directly in package @code{System}.
For units containing such references,
the prefixes must either be removed, or the pragma @code{Extend_System}
@subsection Record and Array Component Alignment
@noindent
-On HP Ada for OpenVMS Alpha, all non composite components
+On HP Ada for OpenVMS Alpha, all non-composite components
are aligned on natural boundaries. For example, 1-byte
components are aligned on byte boundaries, 2-byte
components on 2-byte boundaries, 4-byte components on 4-byte
@cartouche
X, Y : Integer := Init_Func;
Q : String (X .. Y) := "abc";
-...
+@dots{}
for Q'Address use Compute_Address;
@end cartouche
@end smallexample
X, Y : Integer := Init_Func;
Q_Address : constant Address := Compute_Address;
Q : String (X .. Y) := "abc";
-...
+@dots{}
for Q'Address use Q_Address;
@end cartouche
@end group
@noindent
which will be accepted by GNAT (and other Ada compilers), and is also
compatible with Ada 83. A fuller description of the restrictions
-on address specifications is found in the @cite{GNAT Reference Manual}.
+on address specifications is found in @ref{Top, GNAT Reference Manual,
+About This Guide, gnat_rm, GNAT Reference Manual}.
@node Other Representation Clauses
@subsection Other Representation Clauses
@noindent
HP Ada provides a specific version of the package
@code{SYSTEM} for each platform on which the language is implemented.
-For the complete specification of the package @code{SYSTEM}, see
+For the complete spec of the package @code{SYSTEM}, see
Appendix F of the @cite{HP Ada Language Reference Manual}.
On HP Ada, the package @code{SYSTEM} includes the following conversion
@item @code{TO_UNSIGNED_LONGWORD(ADDRESS)}
@item Function @code{IMPORT_VALUE return UNSIGNED_LONGWORD} and the
- functions @code{IMPORT_ADDRESS} and @code{IMPORT_LARGEST_VALUE}
+functions @code{IMPORT_ADDRESS} and @code{IMPORT_LARGEST_VALUE}
@end itemize
@noindent
@noindent
The pragma @code{Extend_System} is a configuration pragma that
-is most conveniently placed in the @file{gnat.adc} file. See the
-@cite{GNAT Reference Manual} for further details.
+is most conveniently placed in the @file{gnat.adc} file. @xref{Pragma
+Extend_System,,, gnat_rm, GNAT Reference Manual} for further details.
HP Ada does not allow the recompilation of the package
@code{SYSTEM}. Instead HP Ada provides several pragmas
@code{TO_ADDRESS}
function for type @code{UNSIGNED_LONGWORD} is changed to
@code{TO_ADDRESS_LONG}.
-See the @cite{GNAT Reference Manual} for a discussion of why this change was
-necessary.
+@xref{Address Clauses,,, gnat_rm, GNAT Reference Manual} for a
+discussion of why this change was necessary.
@noindent
The version of @code{TO_ADDRESS} taking a @i{universal_integer} argument
@itemize @bullet
@item @code{TASK_INFO}
- This pragma appears within a task definition and
- applies to the task in which it appears. The argument
- must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}.
+This pragma appears within a task definition and
+applies to the task in which it appears. The argument
+must be of type @code{SYSTEM.TASK_INFO.TASK_INFO_TYPE}.
@item @code{TASK_STORAGE}
- GNAT implements pragma @code{TASK_STORAGE} in the same way as
- HP Ada.
- Both HP Ada and GNAT supply the pragmas @code{PASSIVE},
- @code{SUPPRESS}, and @code{VOLATILE}.
+GNAT implements pragma @code{TASK_STORAGE} in the same way as HP Ada.
+Both HP Ada and GNAT supply the pragmas @code{PASSIVE},
+@code{SUPPRESS}, and @code{VOLATILE}.
@end itemize
@node Scheduling and Task Priority
@subsection Scheduling and Task Priority
@end itemize
@noindent
-For full details on these GNAT implementation-defined pragmas, see
-the GNAT Reference Manual.
+For full details on these GNAT implementation-defined pragmas,
+see @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT Reference
+Manual}.
@menu
* Restrictions on the Pragma INLINE::
@item Adding the proper notation to generic formal parameters
that take unconstrained types in instantiation
-@item Adding pragma @code{ELABORATE_BODY} to package specifications
+@item Adding pragma @code{ELABORATE_BODY} to package specs
that have package bodies not otherwise allowed
@item Replacing occurrences of the identifier ``@code{PROTECTED}'' by
described for HP Ada or the facilities of Annex B of
the @cite{Ada Reference Manual} (packages @code{INTERFACES.C},
@code{INTERFACES.C.STRINGS} and @code{INTERFACES.C.POINTERS}). For more
-information, see the section ``Interfacing to C'' in the
-@cite{GNAT Reference Manual}.
+information, see @ref{Interfacing to C,,, gnat_rm, GNAT Reference Manual}.
The @option{-gnatF} qualifier forces default and explicit
@code{External_Name} parameters in pragmas @code{Import} and @code{Export}
following conditions:
@itemize @bullet
@item Procedure with no formal parameters (returns @code{0} upon
- normal completion)
+normal completion)
@item Procedure with no formal parameters (returns @code{42} when
- an unhandled exception is raised)
+an unhandled exception is raised)
@item Function with no formal parameters whose returned value
- is of a discrete type
+is of a discrete type
@item Procedure with one @code{out} formal of a discrete type for
- which a specification of pragma @code{EXPORT_VALUED_PROCEDURE}
- is given.
+which a specification of pragma @code{EXPORT_VALUED_PROCEDURE} is given.
@end itemize
@item @option{/COMMAND}
-@item @option{/[NO]MAP}
+@item @option{/@r{[}NO@r{]}MAP}
-@item @option{/OUTPUT=@i{file-spec}}
+@item @option{/OUTPUT=@var{file-spec}}
-@item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK}
+@item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK}
@end itemize
@noindent
switches:
@itemize @bullet
-@item @option{/EXECUTABLE=@i{exec-name}}
+@item @option{/EXECUTABLE=@var{exec-name}}
@item @option{/VERBOSE}
-@item @option{/[NO]DEBUG} and @option{/[NO]TRACEBACK}
+@item @option{/@r{[}NO@r{]}DEBUG} and @option{/@r{[}NO@r{]}TRACEBACK}
@end itemize
@noindent
@item @command{ACS ENTER FOREIGN}
@tab Copy (*)@*
Allows the import of a foreign body as an Ada library
-specification and enters a reference to a pointer.
+spec and enters a reference to a pointer.
@item @command{ACS ENTER UNIT}
@tab Copy (*)@*
For further information on how GNAT interfaces to the file
system or how I/O is implemented in programs written in
-mixed languages, see the chapter ``Implementation of the
-Standard I/O'' in the @cite{GNAT Reference Manual}.
+mixed languages, see @ref{Implementation of the Standard I/O,,,
+gnat_rm, GNAT Reference Manual}.
This chapter covers the following:
@itemize @bullet
@item Standard I/O packages
@sp 1
@item In a subprogram or entry declaration, maximum number of
- formal parameters that are of an unconstrained record type
+formal parameters that are of an unconstrained record type
@tab 32
@tab No set limit
@sp 1
@sp 1
@item Maximum number of formal parameters in an entry or
- subprogram declaration
+subprogram declaration
@tab 246
@tab No set limit
@sp 1
@sp 1
@item Maximum number of objects declared with the pragma @code{COMMON_OBJECT}
- or @code{PSECT_OBJECT}
+or @code{PSECT_OBJECT}
@tab 32757
@tab No set limit
@sp 1
@item Maximum number of enumeration literals in an enumeration type
- definition
+definition
@tab 65535
@tab No set limit
@sp 1
@c @multitable @columnfractions .3 .4 .4
@multitable {Source Code Analyzer /}{Tool with HP Ada}{Tool with GNAT Pro}
@item @i{Tool}
- @tab @i{Tool with HP Ada}
- @tab @i{Tool with @value{EDITION}}
+@tab @i{Tool with HP Ada}
+@tab @i{Tool with @value{EDITION}}
@item Code Management@*System
- @tab HP CMS
- @tab HP CMS
+@tab HP CMS
+@tab HP CMS
@item Language-Sensitive@*Editor
- @tab HP LSE
- @tab emacs or HP LSE (Alpha)
+@tab HP LSE
+@tab emacs or HP LSE (Alpha)
@item
- @tab
- @tab HP LSE (I64)
+@tab
+@tab HP LSE (I64)
@item Debugger
- @tab OpenVMS Debug
- @tab gdb (Alpha),
+@tab OpenVMS Debug
+@tab gdb (Alpha),
@item
- @tab
- @tab OpenVMS Debug (I64)
+@tab
+@tab OpenVMS Debug (I64)
@item Source Code Analyzer /@*Cross Referencer
- @tab HP SCA
- @tab GNAT XREF
+@tab HP SCA
+@tab GNAT XREF
@item Test Manager
- @tab HP Digital Test@*Manager (DTM)
- @tab HP DTM
+@tab HP Digital Test@*Manager (DTM)
+@tab HP DTM
@item Performance and@*Coverage Analyzer
- @tab HP PCA
- @tab HP PCA
+@tab HP PCA
+@tab HP PCA
@item Module Management@*System
- @tab HP MMS
- @tab Not applicable
+@tab HP MMS
+@tab Not applicable
@end multitable
@end flushleft
@end ifnottex
* Solaris-Specific Considerations::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
+* Irix-Specific Considerations::
+* RTX-Specific Considerations::
@end menu
@node Summary of Run-Time Configurations
@item @code{@ @ @ @ }Tasking @tab native Win32 threads
@item @code{@ @ @ @ }Exceptions @tab SJLJ
@*
+@item @b{x86-windows-rtx}
+@item @code{@ @ }@i{rts-rtx-rtss (default)}
+@item @code{@ @ @ @ }Tasking @tab RTX real-time subsystem RTSS threads (kernel mode)
+@item @code{@ @ @ @ }Exceptions @tab SJLJ
+@*
+@item @code{@ @ }@i{rts-rtx-w32}
+@item @code{@ @ @ @ }Tasking @tab RTX Win32 threads (user mode)
+@item @code{@ @ @ @ }Exceptions @tab ZCX
+@*
@item @b{x86_64-linux}
@item @code{@ @ }@i{rts-native (default)}
@item @code{@ @ @ @ }Tasking @tab pthread library
The user can alternatively specify a processor on which the program should run
to emulate a single-processor system. The multiprocessor / uniprocessor choice
is made by
-setting the environment variable @code{GNAT_PROCESSOR}
-@cindex @code{GNAT_PROCESSOR} environment variable (on Sparc Solaris)
+setting the environment variable @env{GNAT_PROCESSOR}
+@cindex @env{GNAT_PROCESSOR} environment variable (on Sparc Solaris)
to one of the following:
@table @code
@item -2
Use the default configuration (run the program on all
- available processors) - this is the same as having
- @code{GNAT_PROCESSOR} unset
+available processors) - this is the same as having @code{GNAT_PROCESSOR}
+unset
@item -1
Let the run-time implementation choose one processor and run the program on
- that processor
+that processor
@item 0 .. Last_Proc
Run the program on the specified processor.
- @code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1}
+@code{Last_Proc} is equal to @code{_SC_NPROCESSORS_CONF - 1}
(where @code{_SC_NPROCESSORS_CONF} is a system variable).
@end table
On GNU/Linux without NPTL support (usually system with GNU C Library
older than 2.3), the signal model is not POSIX compliant, which means
that to send a signal to the process, you need to send the signal to all
-threads, e.g. by using @code{killpg()}.
+threads, e.g.@: by using @code{killpg()}.
@node AIX-Specific Considerations
@section AIX-Specific Considerations
specify a sufficiently large size for the stack of the task that contains
this call.
+@node Irix-Specific Considerations
+@section Irix-Specific Considerations
+@cindex Irix libraries
+
+@noindent
+The GCC support libraries coming with the Irix compiler have moved to
+their canonical place with respect to the general Irix ABI related
+conventions. Running applications built with the default shared GNAT
+run-time now requires the LD_LIBRARY_PATH environment variable to
+include this location. A possible way to achieve this is to issue the
+following command line on a bash prompt:
+
+@smallexample
+@group
+$ LD_LIBRARY_PATH=$LD_LIBRARY_PATH:`dirname \`gcc --print-file-name=libgcc_s.so\``
+@end group
+@end smallexample
+
+@node RTX-Specific Considerations
+@section RTX-Specific Considerations
+@cindex RTX libraries
+
+@noindent
+The Real-time Extension (RTX) to Windows is based on the Windows Win32
+API. Applications can be built to work in two different modes:
+
+@itemize @bullet
+@item
+Windows executables that run in Ring 3 to utilize memory protection
+(@emph{rts-rtx-w32}).
+
+@item
+Real-time subsystem (RTSS) executables that run in Ring 0, where
+performance can be optimized with RTSS applications taking precedent
+over all Windows applications (@emph{rts-rtx-rtss}).
+
+@end itemize
+
@c *******************************
@node Example of Binder Output File
@appendix Example of Binder Output File
-- a-except.ads/adb for full details of how zero cost
-- exception handling works. This procedure, the call to
-- it, and the two following tables are all omitted if the
- -- build is in longjmp/setjump exception mode.
+ -- build is in longjmp/setjmp exception mode.
@findex SDP_Table_Build
@findex Zero Cost Exceptions
-- Call SDP_Table_Build to build the top level procedure
-- table for zero cost exception handling (omitted in
- -- longjmp/setjump mode).
+ -- longjmp/setjmp mode).
SDP_Table_Build (ST'Address, 23, EA'Address, 23);
-- pragma Import because if we try to with the unit and
-- call it Ada style, then not only do we waste time
-- recompiling it, but also, we don't really know the right
- -- switches (e.g. identifier character set) to be used
+ -- switches (e.g.@: identifier character set) to be used
-- to compile it.
procedure Ada_Main_Program;
@group
@cartouche
with Unit_1;
-package Unit_2 is ...
+package Unit_2 is @dots{}
@end cartouche
@end group
@end smallexample
@noindent
In some languages that involve the same kind of elaboration problems,
-e.g. Java and C++, the programmer is expected to worry about these
+e.g.@: Java and C++, the programmer is expected to worry about these
ordering problems himself, and it is common to
write a program in which an incorrect elaboration order gives
surprising results, because it references variables before they
@section Controlling Elaboration in GNAT - Internal Calls
@noindent
-In the case of internal calls, i.e. calls within a single package, the
+In the case of internal calls, i.e., calls within a single package, the
programmer has full control over the order of elaboration, and it is up
to the programmer to elaborate declarations in an appropriate order. For
example writing:
package body Math is
function Sqrt (Arg : Float) return Float is
begin
- ...
+ @dots{}
end Sqrt;
end Math;
@end group
with Stuff;
procedure Main is
begin
- ...
+ @dots{}
end Main;
@end group
@end cartouche
@smallexample @c ada
@group
@cartouche
-package X is ...
+package X is @dots{}
-package Y is ...
+package Y is @dots{}
with X;
-package body Y is ...
+package body Y is @dots{}
with Y;
-package body X is ...
+package body X is @dots{}
@end cartouche
@end group
@end smallexample
which means you would have to
elaborate the body of @code{Y} first, but that @code{with}'s @code{X},
which means
-you have to elaborate the body of @code{X} first, but ... and we have a
+you have to elaborate the body of @code{X} first, but @dots{} and we have a
loop that cannot be broken.
It is true that the binder can in many cases guess an order of elaboration
In the body of @code{Decls} a call is made from within the body of a library
task to a subprogram in the package @code{Utils}. Since this call may
occur at elaboration time (given that the task is activated at elaboration
-time), we have to assume the worst, i.e. that the
+time), we have to assume the worst, i.e., that the
call does happen at elaboration time.
@item
A significant part of the problem arises because of the use of the
single task declaration form. This means that the elaboration of
-the task type, and the elaboration of the task itself (i.e. the
+the task type, and the elaboration of the task itself (i.e.@: the
creation of the task) happen at the same time. A good rule
of style in Ada is to always create explicit task types. By
following the additional step of placing task objects in separate
@smallexample @c ada
@group
FP_Initialize_Required : constant Boolean := True;
-...
+@dots{}
if FP_Initialize_Required then
-...
+@dots{}
end if;
@end group
@end smallexample
package Config is
FP_Initialize_Required : constant Boolean := True;
Reset_Available : constant Boolean := False;
- ...
+ @dots{}
end Config;
@end group
@end smallexample
@cindex pragma @code{Assert}
on the @code{Assert} pragma that has always been available in GNAT, so this
feature may be used with GNAT even if you are not using Ada 2005 features.
-The use of pragma @code{Assert} is described in the
-@cite{GNAT Reference Manual}, but as an example, the last test could be written:
+The use of pragma @code{Assert} is described in
+@ref{Pragma Assert,,, gnat_rm, GNAT Reference Manual}, but as an
+example, the last test could be written:
@smallexample @c ada
pragma Assert (Temperature <= 999.0, "Temperature Crazy");
@smallexample @c ada
@group
-if ... then
- ... -- some statements
+if @dots{} then
+ @dots{} -- some statements
else
pragma Assert (Num_Cases < 10);
null;
declare
X : Bit_String (1 .. 10);
begin
- ...
+ @dots{}
end;
else
declare
X : Large_Bit_String (1 .. 1000);
begin
- ...
+ @dots{}
end;
end if;
@end group
compiler so this can only be used where both declarations are legal,
even though one of them will not be used.
-Another approach is to define integer constants, e.g. @code{Bits_Per_Word}, or
-Boolean constants, e.g. @code{Little_Endian}, and then write declarations
+Another approach is to define integer constants, e.g.@: @code{Bits_Per_Word}, or
+Boolean constants, e.g.@: @code{Little_Endian}, and then write declarations
that are parameterized by these constants. For example
@smallexample @c ada
@smallexample @c ada
@group
if Ada_2005 then
- ... neat Ada 2005 code
+ @dots{} neat Ada 2005 code
else
- ... not quite as neat Ada 95 code
+ @dots{} not quite as neat Ada 95 code
end if;
@end group
@end smallexample
@noindent
Note also that with project files it is desirable to use a different extension
-than @file{ads} / @file{adb} for alternativee versions. Otherwise a naming
+than @file{ads} / @file{adb} for alternative versions. Otherwise a naming
conflict may arise through another commonly used feature: to declare as part
of the project a set of directories containing all the sources obeying the
default naming scheme.
The examples in this chapter will illustrate several of the forms
for invoking @code{Asm}; a complete specification of the syntax
-is found in the @cite{GNAT Reference Manual}.
+is found in @ref{Machine Code Insertions,,, gnat_rm, GNAT Reference
+Manual}.
Under the standard GNAT conventions, the @code{Nothing} procedure
should be in a file named @file{nothing.adb}.
@item =
output constraint
@item g
-global (i.e. can be stored anywhere)
+global (i.e.@: can be stored anywhere)
@item m
in memory
@item I
@end smallexample
Compile the program with both optimization (@option{-O2}) and inlining
-enabled (@option{-gnatpn} instead of @option{-gnatp}).
+(@option{-gnatn}) enabled.
The @code{Incr} function is still compiled as usual, but at the
point in @code{Increment} where our function used to be called:
@node Legal Ada 83 programs that are illegal in Ada 95
@subsection Legal Ada 83 programs that are illegal in Ada 95
-Some legal Ada 83 programs are illegal (i.e. they will fail to compile) in
+Some legal Ada 83 programs are illegal (i.e., they will fail to compile) in
Ada 95 and thus also in Ada 2005:
@table @emph
character literals that were legal in Ada 83 are illegal in Ada 95.
For example:
@smallexample @c ada
- for Char in 'A' .. 'Z' loop ... end loop;
+ for Char in 'A' .. 'Z' loop @dots{} end loop;
@end smallexample
@noindent
@code{Character} or @code{Wide_Character}. The simplest correction
is to make the type explicit; e.g.:
@smallexample @c ada
- for Char in Character range 'A' .. 'Z' loop ... end loop;
+ for Char in Character range 'A' .. 'Z' loop @dots{} end loop;
@end smallexample
@item New reserved words
@noindent
Ada compilers are allowed to supplement the language-defined pragmas, and
these are a potential source of non-portability. All GNAT-defined pragmas
-are described in the GNAT Reference Manual, and these include several that
-are specifically intended to correspond to other vendors' Ada 83 pragmas.
+are described in @ref{Implementation Defined Pragmas,,, gnat_rm, GNAT
+Reference Manual}, and these include several that are specifically
+intended to correspond to other vendors' Ada 83 pragmas.
For migrating from VADS, the pragma @code{Use_VADS_Size} may be useful.
-For
-compatibility with HP Ada 83, GNAT supplies the pragmas
+For compatibility with HP Ada 83, GNAT supplies the pragmas
@code{Extend_System}, @code{Ident}, @code{Inline_Generic},
@code{Interface_Name}, @code{Passive}, @code{Suppress_All},
and @code{Volatile}.
@subsection Implementation-defined attributes
Analogous to pragmas, the set of attributes may be extended by an
-implementation. All GNAT-defined attributes are described in the
-@cite{GNAT Reference Manual}, and these include several that are specifically
-intended
+implementation. All GNAT-defined attributes are described in
+@ref{Implementation Defined Attributes,,, gnat_rm, GNAT Reference
+Manual}, and these include several that are specifically intended
to correspond to other vendors' Ada 83 attributes. For migrating from VADS,
the attribute @code{VADS_Size} may be useful. For compatibility with HP
Ada 83, GNAT supplies the attributes @code{Bit}, @code{Machine_Size} and
this in Ada 95 or Ada 2005:
@enumerate
@item
-If the source code for the libraries (specifications and bodies) are
+If the source code for the libraries (specs and bodies) are
available, then the libraries can be migrated in the same way as the
application.
@item
-If the source code for the specifications but not the bodies are
+If the source code for the specs but not the bodies are
available, then you can reimplement the bodies.
@item
Some features introduced by Ada 95 obviate the need for library support. For
@itemize @bullet
@item
-Modify the program to eliminate the circularities, e.g. by moving
+Modify the program to eliminate the circularities, e.g.@: by moving
elaboration-time code into explicitly-invoked procedures
@item
Constrain the elaboration order by including explicit @code{Elaborate_Body} or
For GNAT running on other than VMS systems, all the HP Ada 83 pragmas and
attributes are recognized, although only a subset of them can sensibly
-be implemented. The description of pragmas in the
-@cite{GNAT Reference Manual}
+be implemented. The description of pragmas in @ref{Implementation
+Defined Pragmas,,, gnat_rm, GNAT Reference Manual}
indicates whether or not they are applicable to non-VMS systems.
@end ifclear
All code that comes as part of GNAT is 64-bit clean, but the
restrictions given in @ref{Restrictions on use of 64 bit objects},
still apply. Look at the package
-specifications to see in which contexts objects allocated
+specs to see in which contexts objects allocated
in 64-bit address space are acceptable.
@node Technical details
@noindent
Make sure the system on which GNAT is installed is accessible from the
-current machine, i.e. the install location is shared over the network.
+current machine, i.e., the install location is shared over the network.
Shared resources are accessed on Windows by means of UNC paths, which
have the format @code{\\server\sharename\path}
@noindent
It is possible to control where temporary files gets created by setting
-the TMP environment variable. The file will be created:
+the @env{TMP} environment variable. The file will be created:
@itemize
-@item Under the directory pointed to by the TMP environment variable if
+@item Under the directory pointed to by the @env{TMP} environment variable if
this directory exists.
-@item Under c:\temp, if the TMP environment variable is not set (or not
-pointing to a directory) and if this directory exists.
+@item Under @file{c:\temp}, if the @env{TMP} environment variable is not
+set (or not pointing to a directory) and if this directory exists.
@item Under the current working directory otherwise.
@end itemize
If you use @command{gcc} to compile the non-Ada part of your application,
there are no Windows-specific restrictions that affect the overall
interoperability with your Ada code. If you plan to use
-Microsoft tools (e.g. Microsoft Visual C/C++), you should be aware of
+Microsoft tools (e.g.@: Microsoft Visual C/C++), you should be aware of
the following limitations:
@itemize @bullet
@enumerate
@item
-Encapsulate your non Ada code in a DLL to be linked with your Ada
+Encapsulate your non-Ada code in a DLL to be linked with your Ada
application. In this case, use the Microsoft or whatever environment to
build the DLL and use GNAT to build your executable
(@pxref{Using DLLs with GNAT}).
caller) is in charge of cleaning the stack on routine exit. In addition,
the name of a routine with @code{Stdcall} calling convention is mangled by
adding a leading underscore (as for the @code{C} calling convention) and a
-trailing @code{@@}@code{@i{nn}}, where @i{nn} is the overall size (in
+trailing @code{@@}@code{@var{nn}}, where @var{nn} is the overall size (in
bytes) of the parameters passed to the routine.
The name to use on the Ada side when importing a C routine with a
@code{Stdcall} calling convention is the name of the C routine. The leading
-underscore and trailing @code{@@}@code{@i{nn}} are added automatically by
+underscore and trailing @code{@@}@code{@var{nn}} are added automatically by
the compiler. For instance the Win32 function:
@smallexample
@noindent
then the imported routine is @code{retrieve_val}, that is, there is no
decoration at all. No leading underscore and no Stdcall suffix
-@code{@@}@code{@i{nn}}.
+@code{@@}@code{@var{nn}}.
@noindent
This is especially important as in some special cases a DLL's entry
-point name lacks a trailing @code{@@}@code{@i{nn}} while the exported
+point name lacks a trailing @code{@@}@code{@var{nn}} while the exported
name generated for a call has it.
@noindent
@noindent
Note that to ease building cross-platform bindings this convention
-will be handled as a @code{C} calling convention on non Windows platforms.
+will be handled as a @code{C} calling convention on non-Windows platforms.
@node Win32 Calling Convention
@subsection @code{Win32} Calling Convention
@smallexample
@group
@cartouche
-[LIBRARY @i{name}]
-[DESCRIPTION @i{string}]
+@r{[}LIBRARY @var{name}@r{]}
+@r{[}DESCRIPTION @var{string}@r{]}
EXPORTS
- @i{symbol1}
- @i{symbol2}
- ...
+ @var{symbol1}
+ @var{symbol2}
+ @dots{}
@end cartouche
@end group
@end smallexample
@table @code
-@item LIBRARY @i{name}
+@item LIBRARY @var{name}
This section, which is optional, gives the name of the DLL.
-@item DESCRIPTION @i{string}
+@item DESCRIPTION @var{string}
This section, which is optional, gives a description string that will be
embedded in the import library.
@end table
@noindent
-Note that you must specify the correct suffix (@code{@@}@code{@i{nn}})
+Note that you must specify the correct suffix (@code{@@}@code{@var{nn}})
(@pxref{Windows Calling Conventions}) for a Stdcall
calling convention function in the exported symbols list.
@code{dll2def} is a very simple tool: it takes as input a DLL and prints
to standard output the list of entry points in the DLL. Note that if
some routines in the DLL have the @code{Stdcall} convention
-(@pxref{Windows Calling Conventions}) with stripped @code{@@}@i{nn}
+(@pxref{Windows Calling Conventions}) with stripped @code{@@}@var{nn}
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.
+@option{-k} to @command{gnatdll} when creating the import library.
@noindent
-Here are some hints to find the right @code{@@}@i{nn} suffix.
+Here are some hints to find the right @code{@@}@var{nn} suffix.
@enumerate
@item
name of the DLL containing the services listed in the definition file
@file{API.dll}. The name of the static import library generated is
computed from the name of the definition file as follows: if the
-definition file name is @i{xyz}@code{.def}, the import library name will
-be @code{lib}@i{xyz}@code{.a}. Note that in the previous example option
+definition file name is @var{xyz}@code{.def}, the import library name will
+be @code{lib}@var{xyz}@code{.a}. Note that in the previous example option
@option{-e} could have been removed because the name of the definition
file (before the ``@code{.def}'' suffix) is the same as the name of the
DLL (@pxref{Using gnatdll} for more information about @code{gnatdll}).
@item building the DLL
-To build the DLL you must use @command{gcc}'s @code{-shared}
+To build the DLL you must use @command{gcc}'s @option{-shared}
option. It is quite simple to use this method:
@smallexample
-$ gcc -shared -o api.dll obj1.o obj2.o ...
+$ gcc -shared -o api.dll obj1.o obj2.o @dots{}
@end smallexample
It is important to note that in this case all symbols found in the
file, @pxref{The Definition File}. For example:
@smallexample
-$ gcc -shared -o api.dll api.def obj1.o obj2.o ...
+$ gcc -shared -o api.dll api.def obj1.o obj2.o @dots{}
@end smallexample
If you use a definition file you must export the elaboration procedures
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
+GNAT shared libraries. This is achieved by using @option{-shared} binder's
option.
@smallexample
It is therefore not possible to exchange GNAT run-time objects between the
Ada DLL and the main Ada program. Example of GNAT run-time objects are file
-handles (e.g. @code{Text_IO.File_Type}), tasks types, protected objects
+handles (e.g.@: @code{Text_IO.File_Type}), tasks types, protected objects
types, etc.
It is completely safe to exchange plain elementary, array or record types,
return Fact;
end Factorial;
- ...
+ @dots{}
-- The remainder of this package body is unchanged.
end API;
@end cartouche
@noindent
To use the services exported by the Ada DLL from another programming
-language (e.g. C), you have to translate the specs of the exported Ada
+language (e.g.@: C), you have to translate the specs of the exported Ada
entities in that language. For instance in the case of @code{API.dll},
the corresponding C header file could look like:
@cartouche
package API is
Count : Integer := 0;
- ...
+ @dots{}
-- Remainder of the package omitted.
end API;
@end cartouche
@smallexample
@cartouche
-$ gnatdll [@var{switches}] @var{list-of-files} [-largs @var{opts}]
+$ gnatdll @ovar{switches} @var{list-of-files} @r{[}-largs @var{opts}@r{]}
@end cartouche
@end smallexample
@noindent
-where @i{list-of-files} is a list of ALI and object files. The object
+where @var{list-of-files} is a list of ALI and object files. The object
file list must be the exact list of objects corresponding to the non-Ada
sources whose services are to be included in the DLL. The ALI file list
must be the exact list of ALI files for the corresponding Ada sources
-whose services are to be included in the DLL. If @i{list-of-files} is
+whose services are to be included in the DLL. If @var{list-of-files} is
missing, only the static import library is generated.
@noindent
You may specify any of the following switches to @code{gnatdll}:
@table @code
-@item -a[@var{address}]
+@item -a@ovar{address}
@cindex @option{-a} (@code{gnatdll})
Build a non-relocatable DLL at @var{address}. If @var{address} is not
specified the default address @var{0x11000000} will be used. By default,
@item -b @var{address}
@cindex @option{-b} (@code{gnatdll})
Set the relocatable DLL base address. By default the address is
-@var{0x11000000}.
+@code{0x11000000}.
@item -bargs @var{opts}
@cindex @option{-bargs} (@code{gnatdll})
@item -k
@cindex @option{-k} (@code{gnatdll})
-Removes the @code{@@}@i{nn} suffix from the import library's exported
+Removes the @code{@@}@var{nn} suffix from the import library's exported
names, but keeps them for the link names. You must specify this
option if you want to use a @code{Stdcall} function in a DLL for which
-the @code{@@}@i{nn} suffix has been removed. This is the case for most
+the @code{@@}@var{nn} suffix has been removed. This is the case for most
of the Windows NT DLL for example. This option has no effect when
@option{-n} option is specified.
is
@smallexample
-$ dlltool [@var{switches}]
+$ dlltool @ovar{switches}
@end smallexample
@noindent
@item -k
@cindex @option{-k} (@command{dlltool})
-Kill @code{@@}@i{nn} from exported names
+Kill @code{@@}@var{nn} from exported names
(@pxref{Windows Calling Conventions}
for a discussion about @code{Stdcall}-style symbols.
Generate an export file @var{exportfile}. The export file contains the
export table (list of symbols in the DLL) and is used to create the DLL.
-@item --output-lib @i{libfile}
+@item --output-lib @var{libfile}
@cindex @option{--output-lib} (@command{dlltool})
Generate a static import library @var{libfile}.
@cindex @option{-v} (@command{dlltool})
Verbose mode.
-@item --as @i{assembler-name}
+@item --as @var{assembler-name}
@cindex @option{--as} (@command{dlltool})
-Use @i{assembler-name} as the assembler. The default is @code{as}.
+Use @var{assembler-name} as the assembler. The default is @code{as}.
@end table
@node GNAT and Windows Resources
OSDN Git Service
