@c o
@c G N A T _ U G N o
@c o
-@c Copyright (C) 1992-2007, AdaCore o
+@c Copyright (C) 1992-2008, 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
@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
@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
@c %**end of header
@copying
-Copyright @copyright{} 1995-2005, Free Software Foundation
+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
* Creating Sample Bodies Using gnatstub::
* Other Utility Programs::
* Running and Debugging Ada Programs::
+@ifclear vms
+* Code Coverage and Profiling::
+@end ifclear
@ifset vms
* Compatibility with HP Ada::
@end ifset
* 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
@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}.
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
@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
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
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)
@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})
switches are set.
This includes suppression of inlining that results
from the use of the pragma @code{Inline_Always}.
-See also @option{-gnatn} and @option{-gnatN}.
+Any occurrences of pragma @code{Inline} or @code{Inline_Always}
+are ignored, and @option{-gnatn} and @option{-gnatN} have no
+effect if this switch is present.
@item -fno-strict-aliasing
@cindex @option{-fno-strict-aliasing} (@command{gcc})
@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
For details of the possible selections for @var{c},
see @ref{Character Set Control}.
-@item ^-gnatI^IGNORE_REP_CLAUSES^
+@item ^-gnatI^/IGNORE_REP_CLAUSES^
@cindex @option{^-gnatI^IGNORE_REP_CLAUSES^} (@command{gcc})
Ignore representation clauses. When this switch is used, all
representation clauses are treated as comments. This is useful
@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})
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}[,@dots{}])^
@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}).
This is the default behavior in the absence of an @option{/OPTIMIZE}
qualifier.
-@item /OPTIMIZE[=(keyword[,...])]
+@item /OPTIMIZE[=(keyword[,@dots{}])]
@cindex @option{/OPTIMIZE} (@code{GNAT COMPILE})
Selects the level of optimization for your program. The supported
keywords are as follows:
version, not the GNAT version.
@end ifclear
-@item ^-w^NO_BACK_END_WARNINGS^
+@item ^-w^/NO_BACK_END_WARNINGS^
@cindex @option{-w} (@command{gcc})
Turn off warnings generated by the back end of the compiler. Use of
this switch also causes the default for front end warnings to be set
@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
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.
Possible order of elaboration problems
@item
+Assertions (pragma Assert) that are sure to fail
+
+@item
Unreachable code
@item
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!
@option{-gnatwd} (implicit dereferencing),
@option{-gnatwh} (hiding),
@option{-gnatwl} (elaboration warnings),
+@option{-gnatw.o} (warn on values set by out parameters ignored)
and @option{-gnatwt} (tracking of deleted conditional code).
All other optional warnings are turned on.
in this section for details on optional warning messages that can be
individually controlled.
+@item -gnatw.a
+@emph{Activate warnings on failing assertions.}
+@cindex @option{-gnatw.a} (@command{gcc})
+@cindex Assert failures
+This switch activates warnings for assertions where the compiler can tell at
+compile time that the assertion will fail. Note that this warning is given
+even if assertions are disabled. The default is that such warnings are
+generated.
+
+@item -gnatw.A
+@emph{Suppress warnings on failing assertions.}
+@cindex @option{-gnatw.A} (@command{gcc})
+@cindex Assert failures
+This switch suppresses warnings for assertions where the compiler can tell at
+compile time that the assertion will fail.
+
@item -gnatwb
@emph{Activate warnings on bad fixed values.}
@cindex @option{-gnatwb} (@command{gcc})
effects of defining address clauses that cause one variable to overlap
another.
+@item -gnatw.o
+@emph{Activate warnings on modified but unreferenced out parameters.}
+@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. 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.
+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.O
+@emph{Disable warnings on modified but unreferenced out parameters.}
+@cindex @option{-gnatw.O} (@command{gcc})
+This switch suppresses 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.
+
@item -gnatwp
@emph{Activate warnings on ineffective pragma Inlines.}
@cindex @option{-gnatwp} (@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 ^-Wuninitialized^WARNINGS=UNINITIALIZED^
@cindex @option{-Wuninitialized}
@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.}
@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
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
-the alignment level.
+the alignment level, or they may be aligned the same way as the following
+non-blank line (this is useful when full line comments appear in the middle
+of a statement.
@item ^a^ATTRIBUTE^
@emph{Check attribute casing.}
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
@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
+(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 ^p^PRAGMA^
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);
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,
since brackets encoding is always recognized, it may be conveniently
used in standard libraries, allowing these libraries to be used with
any of the available coding schemes.
-scheme. If no @option{-gnatW?} parameter is present, then the default
-representation is Brackets encoding only.
+scheme.
+
+If no @option{-gnatW?} parameter is present, then the default
+representation is normally Brackets encoding only. However, if the
+first three characters of the file are 16#EF# 16#BB# 16#BF# (the standard
+byte order mark or BOM for UTF-8), then these three characters are
+skipped and the default representation for the file is set to UTF-8.
Note that the wide character representation that is specified (explicitly
or by default) for the main program also acts as the default encoding used
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.
(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).
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
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.
@subsection Integrated Preprocessing
@noindent
-GNAT sources may be preprocessed immediately before compilation; the actual
+GNAT sources may be preprocessed immediately before compilation.
+In this case, the actual
text of the source is not the text of the source file, but is derived from it
through a process called preprocessing. Integrated preprocessing is specified
through switches @option{-gnatep} and/or @option{-gnateD}. @option{-gnatep}
@option{-gnateD} specifies or modifies the values of preprocessing symbol.
@noindent
+Note that when integrated preprocessing is used, the output from the
+preprocessor is not written to any external file. Instead it is passed
+internally to the compiler. If you need to preserve the result of
+preprocessing in a file, then you should use @command{gnatprep}
+to perform the desired preprocessing in stand-alone mode.
+
+@noindent
It is recommended that @command{gnatmake} switch ^-s^/SWITCH_CHECK^ should be
used when Integrated Preprocessing is used. The reason is that preprocessing
with another Preprocessing Data file without changing the sources will
@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
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
@table @option
@c !sort!
+@item --version
+@cindex @option{--version} @command{gnatbind}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatbind}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@item -a
@cindex @option{-a} @command{gnatbind}
Indicates that, if supported by the platform, the adainit procedure should
@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 ``@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).
@item ^-u@var{n}^/DYNAMIC_STACK_USAGE=@var{n}^
@cindex @option{^-u^/DYNAMIC_STACK_USAGE^} (@code{gnatbind})
-Enable dynamic stack usage, with n result stored and displayed at program
-termination. Results that can't be stored are displayed on the fly, at task
-termination. This option is currently not supported on OpenVMS I64 platforms.
+Enable dynamic stack usage, with @var{n} results stored and displayed
+at program termination. A result is generated when a task
+terminates. Results that can't be stored are displayed on the fly, at
+task termination. This option is currently not supported on Itanium
+platforms. (See @ref{Dynamic Stack Usage Analysis} for details.)
@item ^-v^/REPORT_ERRORS=VERBOSE^
@cindex @option{^-v^/REPORT_ERRORS=VERBOSE^} (@code{gnatbind})
Warning messages are treated as fatal errors
@end ifset
+@item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e}
+@cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind})
+Override default wide character encoding for standard Text_IO files.
+
@item ^-x^/READ_SOURCES=NONE^
@cindex @option{^-x^/READ_SOURCES^} (@code{gnatbind})
Exclude source files (check object consistency only).
they are available.
@end ifset
+@item ^-y^/ENABLE_LEAP_SECONDS^
+@cindex @option{^-y^/ENABLE_LEAP_SECONDS^} (@code{gnatbind})
+Enable leap seconds support in @code{Ada.Calendar} and its children.
+
@item ^-z^/ZERO_MAIN^
@cindex @option{^-z^/ZERO_MAIN^} (@code{gnatbind})
No main subprogram.
is simply ignored. If you specify this switch, a missing source
file is an error.
+@item ^-Wx^/WIDE_CHARACTER_ENCODING=^@var{e}
+@cindex @option{^-Wx^/WIDE_CHARACTER_ENCODING^} (@code{gnatbind})
+Override default wide character encoding for standard Text_IO files.
+Normally the default wide character encoding method used for standard
+[Wide_[Wide_]]Text_IO files is taken from the encoding specified for
+the main source input (see description of switch
+@option{^-gnatWx^/WIDE_CHARACTER_ENCODING^} for the compiler). The
+use of this switch for the binder (which has the same set of
+possible arguments) overrides this default as specified.
+
@item ^-x^/READ_SOURCES=NONE^
@cindex @option{^-x^/READ_SOURCES=NONE^} (@code{gnatbind})
Exclude source files. In this mode, the binder only checks that ALI
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
Normally the binder checks that the unit name given on the command line
corresponds to a suitable main subprogram. When this switch is used,
a list of ALI files can be given, and the execution of the program
-consists of elaboration of these units in an appropriate order.
+consists of elaboration of these units in an appropriate order. Note
+that the default wide character encoding method for standard Text_IO
+files is always set to Brackets if this switch is set (you can use
+the binder switch
+@option{^-Wx^WIDE_CHARACTER_ENCODING^} to override this default).
@end table
@node Command-Line Access
@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
@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:
@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
@table @option
@c !sort!
+@item --version
+@cindex @option{--version} @command{gnatlink}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatlink}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@item ^-A^/BIND_FILE=ADA^
@cindex @option{^-A^/BIND_FILE=ADA^} (@command{gnatlink})
The binder has generated code in Ada. This is the default.
@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})
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
@table @option
@c !sort!
+
+@item --version
+@cindex @option{--version} @command{gnatmake}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatmake}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@ifclear vms
@item --GCC=@var{compiler_name}
@cindex @option{--GCC=compiler_name} (@command{gnatmake})
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
@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
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.
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.
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
@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.
@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.
This feature will allow you to eliminate such unused code from your
executable, making it smaller (in disk and in memory).
-This functionality is available on all platforms using elf binary format and
-having GNU binutils version 2.16.1.
+This functionality is available on all Linux platforms except for the IA-64
+architecture and on all cross platforms using the ELF binary file format.
+In both cases GNU binutils version 2.16 or later are required to enable it.
@node Compilation options
@subsection Compilation options
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
The @code{gnatchop} command has the form:
@smallexample
-$ gnatchop switches @var{file name} [@var{file name} @var{file name} ...]
+$ gnatchop switches @var{file name} [@var{file name} @var{file name} @dots{}]
[@var{directory}]
@end smallexample
@table @option
@c !sort!
+@item --version
+@cindex @option{--version} @command{gnatchop}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatchop}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@item ^-c^/COMPILATION^
@cindex @option{^-c^/COMPILATION^} (@code{gnatchop})
Causes @code{gnatchop} to operate in compilation mode, in which
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:
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
@table @option
@c !sort!
+@item --version
+@cindex @option{--version} @command{gnatname}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatname}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@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
the inherited body is not part of the sources of the project, otherwise there
will be a compilation error when compiling the spec.
-For that purpose, the attribute @code{Locally_Removed_Files} is used.
+For that purpose, the attribute @code{Excluded_Source_Files} is used.
Its value is a string list: a list of file names.
@smallexample @c @projectfile
project B extends "a" is
for Source_Files use ("pkg.ads");
-- New spec of Pkg does not need a completion
- for Locally_Removed_Files use ("pkg.adb");
+ for Excluded_Source_Files use ("pkg.adb");
end B;
@end smallexample
-Attribute @code{Locally_Removed_Files} may also be used to check if a source
+Attribute @code{Excluded_Source_Files} may also be used to check if a source
is still needed: if it is possible to build using @command{gnatmake} when such
-a source is put in attribute @code{Locally_Removed_Files} of a project P, then
+a source is put in attribute @code{Excluded_Source_Files} of a project P, then
it is possible to remove the source completely from a system that includes
project P.
@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 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
@item @code{Exec_Dir}
@tab string
-@item @code{Locally_Removed_Files}
+@item @code{Excluded_Source_Dirs}
+@tab string list
+@item @code{Excluded_Source_Files}
@tab string list
@item @code{Languages}
@tab string list
@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
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:
@itemize @bullet
@item It must not be empty
@item It must include at least one dot
-@item It cannot end with the same string as @code{Spec_Suffix ("Ada")}
+@item It cannot be the same as @code{Spec_Suffix ("Ada")}
@end itemize
@noindent
+If @code{Body_Suffix ("Ada")} and @code{Spec_Suffix ("Ada")} end with the
+same string, then a file name that ends with the longest of these two suffixes
+will be a body if the longest suffix is @code{Body_Suffix ("Ada")} or a spec
+if the longest suffix is @code{Spec_Suffix ("Ada")}.
+
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}.
+@code{Body_Suffix}. The same "longest suffix" rules apply.
@noindent
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
-- 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
@noindent
The command invocation for @code{gnatxref} is:
@smallexample
-$ gnatxref [switches] sourcefile1 [sourcefile2 ...]
+$ gnatxref [switches] sourcefile1 [sourcefile2 @dots{}]
@end smallexample
@noindent
@end table
@noindent
-The switches can be :
+The switches can be:
@table @option
@c !sort!
+@item --version
+@cindex @option{--version} @command{gnatxref}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatxref}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@item ^-a^/ALL_FILES^
@cindex @option{^-a^/ALL_FILES^} (@command{gnatxref})
If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
@smallexample
$ gnatfind [switches] pattern[:sourcefile[:line[:column]]]
- [file1 file2 ...]
+ [file1 file2 @dots{}]
@end smallexample
@noindent
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{file1}, @file{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
@table @option
@c !sort!
+@cindex @option{--version} @command{gnatfind}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatfind}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@item ^-a^/ALL_FILES^
@cindex @option{^-a^/ALL_FILES^} (@command{gnatfind})
If this switch is present, @code{gnatfind} and @code{gnatxref} will parse
@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}}
+From @command{vi}, you can then use the command @samp{:tag @i{entity}}
(replacing @i{entity} by whatever you are looking for), and vi will
display a new file with the corresponding declaration of entity.
@end ifclear
@cindex @option{^--separate-loop-then^/SEPARATE_LOOP_THEN^} (@command{gnatpp})
@item ^--separate-loop-then^/SEPARATE_LOOP_THEN^
Place the keyword @code{loop} in FOR and WHILE loop statements and the
-keywird @code{then} in IF statements on a separate line.
+keyword @code{then} in IF statements on a separate line.
+
+@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
+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})
+@item ^--use-on-new-line^/USE_ON_NEW_LINE^
+Start each USE clause in a context clause from a separate line.
+
+@cindex @option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^} (@command{gnatpp})
+@item ^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^
+Use a separate line for a loop or block statement name, but do not use an extra
+indentation level for the statement itself.
@end table
@table @option
@item ^-M@i{nnn}^/LINE_LENGTH_MAX=@i{nnn}^
@cindex @option{^-M^/LINE_LENGTH^} (@command{gnatpp})
-Maximum line length, @i{nnn} from 32 ..256, the default value is 79
+Maximum line length, @i{nnn} from 32@dots{}256, the default value is 79
@item ^-i@i{nnn}^/INDENTATION_LEVEL=@i{nnn}^
@cindex @option{^-i^/INDENTATION_LEVEL^} (@command{gnatpp})
-Indentation level, @i{nnn} from 1 .. 9, the default value is 3
+Indentation level, @i{nnn} from 1@dots{}9, the default value is 3
@item ^-cl@i{nnn}^/CONTINUATION_INDENT=@i{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), @i{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
@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
GNAT style layout inserts empty lines as separation for
compound statements, return statements and bodies.
+Note that the layout specified by
+@option{^--separate-stmt-name^/STMT_NAME_ON_NEW_LINE^}
+for named block and loop statements overrides the layout defined by these
+constructs by @option{^-l1^/CONSTRUCT_LAYOUT=GNAT^},
+@option{^-l2^/CONSTRUCT_LAYOUT=COMPACT^} or
+@option{^-l3^/CONSTRUCT_LAYOUT=UNCOMPACT^} option.
+
@node Name Casing
@subsection Name Casing
@menu
* Output Files Control::
* Disable Metrics For Local Units::
-* Line Metrics Control::
-* Syntax Metrics Control::
-* Complexity Metrics Control::
+* Specifying a set of metrics to compute::
* Other gnatmetric Switches::
* Generate project-wide metrics::
@end menu
When generating the output in textual form, @command{gnatmetric} creates
for each Ada source file a corresponding text file
-containing the computed metrics. By default, this file
-is placed in the same directory as where the source file is located, and
-its name is obtained
+containing the computed metrics, except for the case when the set of metrics
+specified by gnatmetric parameters consists only of metrics that are computed
+for the whole set of analyzed sources, but not for each Ada source.
+By default, this file is placed in the same directory as where the source
+file is located, and its name is obtained
by appending the ^@file{.metrix}^@file{$METRIX}^ suffix to the name of the
input file.
@end table
+@node Specifying a set of metrics to compute
+@subsection Specifying a set of metrics to compute
+
+@noindent
+By default all the metrics are computed and reported. The switches
+described in this subsection allow you to control, on an individual
+basis, whether metrics are computed and
+reported. If at least one positive metric
+switch is specified (that is, a switch that defines that a given
+metric or set of metrics is to be computed), then only
+explicitly specified metrics are reported.
+
+@menu
+* Line Metrics Control::
+* Syntax Metrics Control::
+* Complexity Metrics Control::
+@end menu
+
@node Line Metrics Control
-@subsection Line Metrics Control
+@subsubsection Line Metrics Control
@cindex Line metrics control in @command{gnatmetric}
@noindent
the number of code lines containing end-of-line comments;
@item
+the comment percentage: the ratio between the number of lines that contain
+comments and the number of all non-blank lines, expressed as a percentage;
+
+@item
the number of empty lines and lines containing only space characters and/or
format effectors (blank lines)
+@item
+the average number of code lines in subprogram bodies, task bodies, entry
+bodies and statement sequences in package bodies (this metric is only computed
+across the whole set of the analyzed units)
+
@end itemize
-If @command{gnatmetric} is invoked on more than one source file, it sums the
-values of the line metrics for all the files being processed and then
-generates the cumulative results.
+@noindent
+@command{gnatmetric} sums the values of the line metrics for all the
+files being processed and then generates the cumulative results. The tool
+also computes for all the files being processed the average number of code
+lines in bodies.
-By default, all the line metrics are computed and reported. You can use the
-following switches to select the specific line metrics to be computed and
-reported (if any of these parameters is set, only explicitly specified line
-metrics are computed).
+You can use the following switches to select the specific line metrics
+to be computed and reported.
@table @option
-@cindex @option{^-la^/LINES_ALL^} (@command{gnatmetric})
-@item ^-la^/LINES_ALL^
-The number of all lines
+@cindex @option{^--lines@var{x}^/LINE_COUNT_METRICS^} (@command{gnatmetric})
+
+@ifclear vms
+@cindex @option{--no-lines@var{x}}
+@end ifclear
+
+@item ^--lines-all^/LINE_COUNT_METRICS=ALL_ON^
+Report all the line metrics
+
+@item ^--no-lines-all^/LINE_COUNT_METRICS=ALL_OFF^
+Do not report any of line metrics
+
+@item ^--lines^/LINE_COUNT_METRICS=ALL_LINES_ON^
+Report the number of all lines
-@cindex @option{^-lcode^/CODE_LINES^} (@command{gnatmetric})
-@item ^-lcode^/CODE_LINES^
-The number of code lines
+@item ^--no-lines^/LINE_COUNT_METRICS=ALL_LINES_OFF^
+Do not report the number of all lines
-@cindex @option{^-lcomm^/COMMENT_LINES^} (@command{gnatmetric})
-@item ^-lcomm^/COMENT_LINES^
-The number of comment lines
+@item ^--lines-code^/LINE_COUNT_METRICS=CODE_LINES_ON^
+Report the number of code lines
-@cindex @option{^-leol^/MIXED_CODE_COMMENTS^} (@command{gnatmetric})
-@item ^-leol^/MIXED_CODE_COMMENTS^
-The number of code lines containing
+@item ^--no-lines-code^/LINE_COUNT_METRICS=CODE_LINES_OFF^
+Do not report the number of code lines
+
+@item ^--lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_ON^
+Report the number of comment lines
+
+@item ^--no-lines-comment^/LINE_COUNT_METRICS=COMMENT_LINES_OFF^
+Do not report the number of comment lines
+
+@item ^--lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_ON^
+Report the number of code lines containing
+end-of-line comments
+
+@item ^--no-lines-eol-comment^/LINE_COUNT_METRICS=CODE_COMMENT_LINES_OFF^
+Do not report the number of code lines containing
end-of-line comments
-@cindex @option{^-lb^/BLANK_LINES^} (@command{gnatmetric})
-@item ^-lb^/BLANK_LINES^
-The number of blank lines
+@item ^--lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_ON^
+Report the comment percentage in the program text
+
+@item ^--no-lines-ratio^/LINE_COUNT_METRICS=COMMENT_PERCENTAGE_OFF^
+Do not report the comment percentage in the program text
+
+@item ^--lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_ON^
+Report the number of blank lines
+
+@item ^--no-lines-blank^/LINE_COUNT_METRICS=BLANK_LINES_OFF^
+Do not report the number of blank lines
+
+@item ^--lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_ON^
+Report the average number of code lines in subprogram bodies, task bodies,
+entry bodies and statement sequences in package bodies. The metric is computed
+and reported for the whole set of processed Ada sources only.
+
+@item ^--no-lines-average^/LINE_COUNT_METRICS=AVERAGE_BODY_LINES_OFF^
+Do not report the average number of code lines in subprogram bodies,
+task bodies, entry bodies and statement sequences in package bodies.
@end table
@node Syntax Metrics Control
-@subsection Syntax Metrics Control
+@subsubsection Syntax Metrics Control
@cindex Syntax metrics control in @command{gnatmetric}
@noindent
@item Public subprograms
This metric is computed for package specifications. It is the
number of subprograms and generic subprograms declared in the visible
-part (including in nested packages, protected objects, and
+part (including the visible part of nested packages, protected objects, and
protected types).
@item All subprograms
This metric is computed for package specifications and
generic package declarations. It is the total number of types
that can be referenced from outside this compilation unit, plus the
-number of types from all the visible parts of all the visible generic packages.
-Generic formal types are not counted. Only types, not subtypes,
+number of types from all the visible parts of all the visible generic
+packages. Generic formal types are not counted. Only types, not subtypes,
are included.
@noindent
@noindent
By default, all the syntax metrics are computed and reported. You can use the
-following switches to select specific syntax metrics;
-if any of these is set, only the explicitly specified metrics are computed.
+following switches to select specific syntax metrics.
@table @option
-@cindex @option{^-ed^/DECLARATION_TOTAL^} (@command{gnatmetric})
-@item ^-ed^/DECLARATION_TOTAL^
-The total number of declarations
-@cindex @option{^-es^/STATEMENT_TOTAL^} (@command{gnatmetric})
-@item ^-es^/STATEMENT_TOTAL^
-The total number of statements
+@cindex @option{^--syntax@var{x}^/SYNTAX_METRICS^} (@command{gnatmetric})
+
+@ifclear vms
+@cindex @option{--no-syntax@var{x}}
+@end ifclear
+
+@item ^--syntax-all^/SYNTAX_METRICS=ALL_ON^
+Report all the syntax metrics
+
+@item ^--no-syntax-all^/ALL_OFF^
+Do not report any of syntax metrics
+
+@item ^--declarations^/SYNTAX_METRICS=DECLARATIONS_ON^
+Report the total number of declarations
+
+@item ^--no-declarations^/SYNTAX_METRICS=DECLARATIONS_OFF^
+Do not report the total number of declarations
+
+@item ^--statements^/SYNTAX_METRICS=STATEMENTS_ON^
+Report the total number of statements
+
+@item ^--no-statements^/SYNTAX_METRICS=STATEMENTS_OFF^
+Do not report the total number of statements
+
+@item ^--public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_ON^
+Report the number of public subprograms in a compilation unit
+
+@item ^--no-public-subprograms^/SYNTAX_METRICS=PUBLIC_SUBPROGRAMS_OFF^
+Do not report the number of public subprograms in a compilation unit
+
+@item ^--all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_ON^
+Report the number of all the subprograms in a compilation unit
+
+@item ^--no-all-subprograms^/SYNTAX_METRICS=ALL_SUBPROGRAMS_OFF^
+Do not report the number of all the subprograms in a compilation unit
+
+@item ^--public-types^/SYNTAX_METRICS=PUBLIC_TYPES_ON^
+Report the number of public types in a compilation unit
+
+@item ^--no-public-types^/SYNTAX_METRICS=PUBLIC_TYPES_OFF^
+Do not report the number of public types in a compilation unit
-@cindex @option{^-eps^/^} (@command{gnatmetric})
-@item ^-eps^/INT_SUBPROGRAMS^
-The number of public subprograms in a compilation unit
+@item ^--all-types^/SYNTAX_METRICS=ALL_TYPES_ON^
+Report the number of all the types in a compilation unit
-@cindex @option{^-eas^/SUBPROGRAMS_ALL^} (@command{gnatmetric})
-@item ^-eas^/SUBPROGRAMS_ALL^
-The number of all the subprograms in a compilation unit
+@item ^--no-all-types^/SYNTAX_METRICS=ALL_TYPES_OFF^
+Do not report the number of all the types in a compilation unit
-@cindex @option{^-ept^/INT_TYPES^} (@command{gnatmetric})
-@item ^-ept^/INT_TYPES^
-The number of public types in a compilation unit
+@item ^--unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_ON^
+Report the maximal program unit nesting level
-@cindex @option{^-eat^/TYPES_ALL^} (@command{gnatmetric})
-@item ^-eat^/TYPES_ALL^
-The number of all the types in a compilation unit
+@item ^--no-unit-nesting^/SYNTAX_METRICS=UNIT_NESTING_OFF^
+Do not report the maximal program unit nesting level
-@cindex @option{^-enu^/PROGRAM_NESTING_MAX^} (@command{gnatmetric})
-@item ^-enu^/PROGRAM_NESTING_MAX^
-The maximal program unit nesting level
+@item ^--construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_ON^
+Report the maximal construct nesting level
-@cindex @option{^-ec^/CONSTRUCT_NESTING_MAX^} (@command{gnatmetric})
-@item ^-ec^/CONSTRUCT_NESTING_MAX^
-The maximal construct nesting level
+@item ^--no-construct-nesting^/SYNTAX_METRICS=CONSTRUCT_NESTING_OFF^
+Do not report the maximal construct nesting level
@end table
@node Complexity Metrics Control
-@subsection Complexity Metrics Control
+@subsubsection Complexity Metrics Control
@cindex Complexity metrics control in @command{gnatmetric}
@noindent
For a program unit that is an executable body (a subprogram body (including
generic bodies), task body, entry body or a package body containing
-its own statement sequence ) @command{gnatmetric} computes the following
+its own statement sequence) @command{gnatmetric} computes the following
complexity metrics:
@itemize @bullet
the code in the exception handlers and in all the nested program units.
By default, all the complexity metrics are computed and reported.
-For more finely-grained control you can use
+For more fine-grained control you can use
the following switches:
@table @option
-@cindex @option{^-n@var{x}^/SUPPRESS^} (@command{gnatmetric})
+@cindex @option{^-complexity@var{x}^/COMPLEXITY_METRICS^} (@command{gnatmetric})
+
+@ifclear vms
+@cindex @option{--no-complexity@var{x}}
+@end ifclear
+
+@item ^--complexity-all^/COMPLEXITY_METRICS=ALL_ON^
+Report all the complexity metrics
+
+@item ^--no-complexity-all^/COMPLEXITY_METRICS=ALL_OFF^
+Do not report any of complexity metrics
+
+@item ^--complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_ON^
+Report the McCabe Cyclomatic Complexity
+
+@item ^--no-complexity-cyclomatic^/COMPLEXITY_METRICS=CYCLOMATIC_OFF^
+Do not report the McCabe Cyclomatic Complexity
-@item ^-nocc^/SUPPRESS=CYCLOMATIC_COMPLEXITY^
-Do not compute the McCabe Cyclomatic Complexity
+@item ^--complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_ON^
+Report the Essential Complexity
-@item ^-noec^/SUPPRESS=ESSENTIAL_COMPLEXITY^
-Do not compute the Essential Complexity
+@item ^--no-complexity-essential^/COMPLEXITY_METRICS=ESSENTIAL_OFF^
+Do not report the Essential Complexity
-@item ^-nonl^/SUPPRESS=MAXIMAL_LOOP_NESTING^
-Do not compute maximal loop nesting level
+@item ^--loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_ON^
+Report maximal loop nesting level
-@item ^-ne^/SUPPRESS=EXITS_AS_GOTOS^
+@item ^--no-loop-nesting^/COMPLEXITY_METRICS=LOOP_NESTING_OFF^
+Do not report maximal loop nesting level
+
+@item ^--complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_ON^
+Report the average McCabe Cyclomatic Complexity for all the subprogram bodies,
+task bodies, entry bodies and statement sequences in package bodies.
+The metric is computed and reported for whole set of processed Ada sources
+only.
+
+@item ^--no-complexity-average^/COMPLEXITY_METRICS=AVERAGE_COMPLEXITY_OFF^
+Do not report the average McCabe Cyclomatic Complexity for all the subprogram
+bodies, task bodies, entry bodies and statement sequences in package bodies
+
+@cindex @option{^-ne^/NO_EXITS_AS_GOTOS^} (@command{gnatmetric})
+@item ^-ne^/NO_EXITS_AS_GOTOS^
Do not consider @code{exit} statements as @code{goto}s when
computing Essential Complexity
@item ^-files @var{filename}^/FILES=@var{filename}^
@cindex @option{^-files^/FILES^} (@code{gnatmetric})
Take the argument source files from the specified file. This file should be an
-ordinary textual file containing file names separated by spaces or
+ordinary text file containing file names separated by spaces or
line breaks. You can use this switch more then once in the same call to
@command{gnatmetric}. You also can combine this switch with
an explicit list of files.
@node Generate project-wide metrics
@subsection Generate project-wide metrics
-In order to compute metrics on all units of a given project, one can use
+In order to compute metrics on all units of a given project, you can use
the @command{gnat} driver along with the @option{-P} option:
@smallexample
gnat metric -Pproj
@end smallexample
-If the project @code{proj} depends upon other projects, one can compute
+
+@noindent
+If the project @code{proj} depends upon other projects, you can compute
the metrics on the project closure using the @option{-U} option:
@smallexample
gnat metric -Pproj -U
@end smallexample
+
+@noindent
Finally, if not all the units are relevant to a particular main
-program in the project closure, one can generate metrics for the set
+program in the project closure, you can generate metrics for the set
of units needed to create a given main program (unit closure) using
the @option{-U} option followed by the name of the main unit:
@smallexample
@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}}
@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.
Krunching does not affect the extension, but the file name is shortened to
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).
lines
#elsif @i{expression} [then]
lines
-...
+@dots{}
#else
lines
#end if;
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
@table @option
@c !sort!
+@cindex @option{--version} @command{gnatls}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatls}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@item ^-a^/ALL_UNITS^
@cindex @option{^-a^/ALL_UNITS^} (@code{gnatls})
Consider all units, including those of the predefined Ada library.
@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}
@table @option
@c !sort!
+@cindex @option{--version} @command{gnatclean}
+Display Copyright and version, then exit disregarding all other options.
+
+@item --help
+@cindex @option{--help} @command{gnatclean}
+If @option{--version} was not used, display usage, then exit disregarding
+all other options.
+
@item ^-c^/COMPILER_FILES_ONLY^
@cindex @option{^-c^/COMPILER_FILES_ONLY^} (@code{gnatclean})
Only attempt to delete the files produced by the compiler, not those produced
@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.
@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
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:
system defaults and is unknown to the compiler. Stack checking
may still work correctly if a fixed
size stack is allocated, but this cannot be guaranteed.
+@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
increase the amount of stack for the environment task, then this
is an operating systems issue, and must be addressed with the
appropriate operating systems commands.
+@end ifclear
+@ifset vms
+To have a fixed size stack in the environment task, the stack must be put
+in the P0 address space and its size specified. Use these switches to
+create a p0 image:
+
+@smallexample
+gnatmake my_progs -largs "-Wl,--opt=STACK=4000,/p0image"
+@end smallexample
+
+@noindent
+The quotes are required to keep case. The number after @samp{STACK=} is the
+size of the environmental task stack in pagelets (512 bytes). In this example
+the stack size is about 2 megabytes.
+
+@noindent
+A consequence of the @option{/p0image} qualifier is also to makes RMS buffers
+be placed in P0 space. Refer to @cite{HP OpenVMS Linker Utility Manual} for
+more details about the @option{/p0image} qualifier and the @option{stack}
+option.
+@end ifset
@node Static Stack Usage Analysis
@section Static Stack Usage Analysis
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.
@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
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}).
@end table
@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 @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})
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
@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.
+
+Finaly, 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 anotated 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}).
+
+@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 platoforms
+@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
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::
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
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
@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::
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}
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
* Solaris-Specific Considerations::
* Linux-Specific Considerations::
* AIX-Specific Considerations::
+* Irix-Specific Considerations::
@end menu
@node Summary of Run-Time Configurations
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
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
+
@c *******************************
@node Example of Binder Output File
@appendix Example of Binder Output File
-- 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
@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
@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
@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}).
@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
EXPORTS
@i{symbol1}
@i{symbol2}
- ...
+ @dots{}
@end cartouche
@end group
@end smallexample
some routines in the DLL have the @code{Stdcall} convention
(@pxref{Windows Calling Conventions}) with stripped @code{@@}@i{nn}
suffix then you'll have to edit @file{api.def} to add it, 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.
@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
@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})
OSDN Git Service
